Smith API：Issues Agent、Issue 状态与修复验证

Issues Agent 针对一个 tracing project/session 扫描 traces，提炼 issue，并可衔接 GitHub 修复与 preview deployment 验证。所有 create/get/list/update/delete 与 issue 查询页面都标注 Beta，接口和数据模型可能无通知变更；它适合受控试点，不应未经兼容层直接成为不可替代的生产控制面。

每个 Session 一个 Issues Agent

POST /api/v1/platform/sessions/{session_id}/issues-agent 创建配置并入队首次扫描。一个 session 已有 agent 时返回 409。初始配置可包含：

GitHub repo URL、base branch、repo subdirectory；
Context Hub repo handle；
priorities；
run_filter traces-filter DSL。

run_filter 是 Engine 的 prompt guidance，并不是服务端强制执行的查询边界。不能用它实现租户隔离、合规排除或安全访问控制；不应被分析的 trace 必须在采集、项目划分和服务端授权层隔离。

Agent 读模型还包含 cron enable/schedule、engine version、issue count、latest deployment run/thread、preview verification 开关、Agent Overview repo、每月 LCU 上限以及 workspace/session 标签。tenant_name 由服务端 join，便于 org admin 跨 workspace 列表展示；这不意味着普通 workspace 成员获得跨租户权限。

Delete 返回 204，并删除 agent config、其 issues 和 agent-overview Hub repo，是明确级联删除。执行前应导出仍需保留的 issue/overview，停止 cron 与在途修复；不要把它当“暂时关闭”。暂时停用应修改 cron 或相关 feature flag，而不是 delete。

PATCH 的三态字段

Update 是 partial patch，省略字段保持不变。特别要区分：

run_filter：字段缺失不改，空字符串清除；
user_instructions：空字符串清除，前端不能用 null；这是用户拥有的权威偏好，Engine 会在下一次扫描把它协调进 Overview，但不会自行编辑该字段；
session_lcu_spend_limit_monthly：字符串序列化以保留 NUMERIC(28,6) 精度；缺失不改，0 或正数为月上限，0 会立即视为已达上限，负数清除并存为 NULL；
agent_overview_accepted、cron、preview verify 等布尔值要显式区分“false”与“未发送”。

Session 限额与 Organization 限额独立、同时执行。配置 GitHub repo 发生变化时，服务端会清除相关 fix 字段；这与设置 overview repo ID 在同一 CRUD transaction 完成。客户端超时后先 GET 回读，不应再次用旧快照覆盖已发生的副作用。

Agent Overview 与 Prompt Hub

PATCH .../issues-agent/overview 保存 overview content；若没有 backing repo 会创建私有 Prompt Hub repo，否则创建新 commit，并返回 repo ID 与 commit hash。Overview 是版本化知识，不是临时 UI 文本：更新前保留 commit，避免多个编辑者以最后写入覆盖。

user_instructions 与 Overview 不是同一事实源。前者属于用户、Engine 只读取；后者是协调后的 agent context，可由保存 endpoint 形成 commit。审核流程应展示差异并明确“accepted”状态，不能由后台扫描静默替用户接受。

Issue 模型与状态

Issue 包含 name、description、tags、首次/末次出现、关联 traces、proposed fix/context/prompt/example 修复、GitHub branch/PR、verification、watching_since 与 recurrence count。

状态枚举：open、fixing、watching、completed、ignored。严重级是整数并映射为 0=urgent、1=high、2=medium、3=low。不要按常见“数字越大越严重”的假设排序。

List 可按 session ID/name、status、severity、tag、updated_at 筛选；sort_by 为 created_at、updated_at 或 severity。limit 默认 50、上限 500，使用 offset。大规模增量同步应以 updated_at checkpoint 加 ID 去重，单靠 offset 在并发更新下可能跳项或重复。

Viewed 状态是用户维度

POST /issues/{id}/views 幂等记录“当前用户打开过该 issue”，成功 204；GET /sessions/{session_id}/issues/views 返回 issue ID 与 viewed_at。它只驱动 UI 的 unread row 与 Engine tab badge，不改变 issue 的业务 status，也不表示团队已确认或完成处置。

多设备可重复 mark viewed；404/403 后不要把本地 badge 强制清零。客户端将服务端 view set 与当前 issue list 合并展示即可，不需要创造新的共享“已读”状态。

Webhook Secret 轮换

POST .../issues-agent/webhooks/{id}/roll-secret 立即替换 signing secret，之后的投递马上使用新 secret。响应 webhook 对象包含 signing_secret、event_types、status/severity filter、URL 或 Slack channel/team 目标和 headers。

由于切换立即生效，消费者应支持短暂双 secret 验证窗口，或先协调停投/部署新 secret 再 rotate。完整 secret 只在 secret manager 传递，不进入普通 API 日志、trace 或笔记。Slack 目标与 URL 是互斥交付方向，组织安装由服务端解析；仍要防止将跨组织 channel 配置到错误 session。

Preview 修复验证闭环

POST /issues/{id}/start-preview 接收 commit_sha、run_id、thread_id：打开或复用 fix PR，添加 preview label，并调度轮询；preview ready 后恢复 fix run。返回 PR number 与 preview URL。

随后 POST /issues/{id}/fix-verdict 写入 status 与 detail，返回完整 verification：attempt、commit SHA、branch/PR、preview URL、deadline、ready check、run/thread/session IDs 与时间戳。

issue fixing
  → commit/branch
  → open or reuse PR
  → preview deployment pending
  → replay verification
  → verdict
  → watching / completed / retry

Start-preview 可能在客户端超时前已经创建 PR/label，因此重试前先 GET issue/verification。Preview URL 属于外部执行面，测试数据要脱敏，凭据与网络权限最小化。Verdict detail 是诊断证据，不要存完整敏感 trace payload。

Beta 上线边界

通过内部 adapter 封装 Beta schema，保存未知字段并容忍新增 enum；不要让业务表直接镜像所有 API 字段。
每次升级做 contract test：create/get/patch、三态清除、list filter、view 幂等、overview commit、preview/verdict。
Cron 与扫描要有 LCU 上限、并发限制、失败退避和手动 kill switch。
Engine 提议的代码、prompt、context 和 examples 都必须人工或策略审批；Issue 的“proposed”字段不是已验证修复。
对 delete cascade、secret rotation、GitHub repo 切换和 preview label 记录审计，并准备独立回滚路径。