pikasTech-HWLAB/docs/reference/spec-v02-code-agent-trace.md

# v0.2 Code Agent Trace 规格

本文定义 HWLAB v0.2 Code Agent trace、result 和 Cloud Web trace 展示的数据权威、读写路径和回归判定。Trace 是 Workbench 最复杂的用户可见状态面；实现必须先收敛 source of truth，再生成派生 UI/cache，不得通过叠加 fallback、多路径或兼容快照掩盖状态污染。

## 身份模型

| 身份 | 归属 | 语义 |
| --- | --- | --- |
| `traceId` | HWLAB Cloud API | 用户一次 Code Agent turn 的可见追踪 ID，也是 result/trace API 的主键。 |
| `conversationId` | HWLAB Workbench | 用户可见对话容器；只用于业务上下文和 UI 分组。 |
| `sessionId` | HWLAB Code Agent session | 用户显式创建或选择的业务 session，绑定 owner、provider profile 和权限。 |
| `threadId` | HWLAB/AgentRun/Codex | 会话连续性的唯一标准字段；不得新增历史 thread 别名或拼 prompt 替代。 |
| `runId` | AgentRun | 可复用执行壳；同一个 run 可承载同一 session 的多条 command。 |
| `commandId` | AgentRun | 单个 turn 的执行 identity；同一 `runId` 下每个 `traceId` 必须映射到唯一 command。 |
| `runnerId` / `jobName` | AgentRun / k8s | runner 尝试身份，只能作为执行诊断，不代表业务 session。 |

`traceId -> AgentRun commandId` 是 AgentRun 接入后的核心映射。`runId` 只能说明执行壳复用，不能单独说明某个用户 turn 的 final response。Cloud Web、CLI 和 issue closeout 必须同时展示业务身份和执行身份，避免把共享 run 的上一个 command 误认为当前 trace。

## 权威数据源

- **AgentRun command registry 是 completed AgentRun trace 的执行权威**：Cloud API 必须通过 `GET /api/v1/runs/{runId}/commands?afterSeq=0&limit=100` 用 `idempotencyKey === traceId` 或 `payload.traceId === traceId` 找到当前 trace 的 command。
- **AgentRun command result 是 final response 权威**：找到 command 后，Cloud API 必须通过 `GET /api/v1/runs/{runId}/commands/{commandId}/result` 生成 `reply.content`、`finalResponse`、`providerTrace` 和 completed result payload。
- **AgentRun events 是 trace row 权威**：Cloud API 从 `GET /api/v1/runs/{runId}/events` 读取事件，并按当前 `commandId` 过滤 assistant/tool/terminal rows。旧 command 的 assistant/tool/terminal 事件不得进入当前 trace 的可读事件列表。
- **`agent_sessions` 是业务 session 和 seed store，不是 final response authority**：它保存 owner、project、conversation/session/thread、lastTraceId、AgentRun run seed 和必要派生证据；读取 terminal result 时不得把 `session.finalResponse`、`session.traceSummary` 或旧 `traceResults` 当成 completed 文本权威。
- **内存 `codeAgentChatResults` 是短连接缓存，不是 terminal authority**：running 状态可用它承接轮询状态；terminal AgentRun result 再次读取时必须重新走 command registry/result 或使用由该路径刚生成的新 payload。
- **`traceStore` 是 live event buffer，不是历史 final authority**：它服务增量轮询和短期 trace 展示；事件过期时可以报告 missing/expired，但不能用别的 trace 的 final response 填补。

## 写入流程

1. Cloud Web 或 `hwlab-cli client` 通过同源 `POST /v1/agent/chat` 提交 turn；请求必须携带显式选中的 `conversationId/sessionId/threadId` 和 provider profile 语义。
2. Cloud API 认证 actor，按 session owner 和 tool capability 装配 AgentRun 请求；HWPOD/runner 使用的用户 API key 只允许来自 owner 的 `HWLAB_API_KEY`，浏览器 session、cookie 或其他 env 别名不得成为 CLI/runner key 来源。
3. Cloud API 创建或复用 AgentRun `runId`，再创建新 command；command `idempotencyKey` 和 `payload.traceId` 必须等于本次 `traceId`，`payload.conversationId`、`payload.hwlabSessionId`、`payload.threadId` 和 `payload.providerProfile` 必须保留。
4. Cloud API 写入 session seed：业务 session、lastTraceId、AgentRun `runId`、可选当前 `commandId`、provider profile 和 owner 归属。该 seed 只用于后续找到 run，不承诺 final response 正确。
5. 初始 result 返回 `running/accepted`，Web 和 CLI 进入短连接 result/trace 轮询。

写入路径不得把浏览器历史 messages、旧 trace final response、旧 command tail 或 session top-level snapshot 拼入新 command payload。历史只用于 UI 展示和排障，不是模型上下文，也不是新 result 的数据来源。

## Result 读取流程

`GET /v1/agent/chat/result/{traceId}` 是 terminal result 的唯一用户入口。AgentRun adapter 启用时，Cloud API 必须执行以下顺序：

1. 校验 `traceId` 和 session owner；普通用户只能读自己的 trace，admin 按授权读。
2. 从内存缓存或 `agent_sessions` 读取最小 AgentRun seed，至少需要 `runId`；如果没有 seed，返回 not found，不猜测其他 session。
3. 对 terminal 或可能 terminal 的 AgentRun result，必须用 AgentRun command registry 按 `traceId` 解析当前 `commandId`。不得相信缓存里的 `agentRun.commandId`、`providerTrace.commandId`、`traceSummary.agentRun.commandId` 或 top-level `lastTraceId` 作为最终映射。
4. 找到 command 后，读取 command result，并从 command result 重建 `reply`、`finalResponse`、`providerTrace`、`traceSummary` 和 `agentRun` 字段。
5. 写回内存缓存和 session 派生证据时，只能写刚由 command result 生成的 payload；旧 `finalResponse`、旧 `traceSummary` 和旧 `traceResults` 不得参与 merge 覆盖。
6. 如果 command registry 找不到该 `traceId` 对应 command，返回结构化错误，例如 `agentrun_trace_command_not_found`；不得回退到旧缓存、top-level snapshot、latest trace 或其他 command result。

Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 terminal”的轮询语义，不是 final fallback。Completed / failed / canceled / blocked 等 terminal 状态必须经过同一 command registry/result 路径确认。

## Trace 读取与渲染流程

`GET /v1/agent/chat/trace/{traceId}` 服务完整 trace 回放，Cloud Web 与 `hwlab-cli client agent trace --render web` 必须共享同一 row 转换语义：

1. Cloud API 先用 result 同一路径解析当前 `traceId -> commandId`；对于 AgentRun trace，events 必须按该 `commandId` 过滤。
2. 可读 rows 至少覆盖 request/setup、tool call、assistant message、terminal/result 和 blocker。低价值 AgentRun backend echo、状态 echo、terminal boilerplate 和重复噪声可被 row renderer 去噪，但原始 trace JSON 仍应通过 `--full` 或下载保留。
3. Web 默认显示完整可读事件列表。Result polling 返回的 compacted head-tail runnerTrace 不能冒充完整 trace；发现 `eventsCompacted=true` 时必须继续请求 `/trace/{traceId}`。
4. 如果完整 trace 已过期或缺失，UI 必须显式展示 missing/expired，并提供 result/inspect 可用证据；不得用最新 trace 或 session final response 填补历史 trace。
5. 同一 run 多 command 时，旧 command 的 assistant/tool/terminal rows 不能挤到新 command 的 final response 或 trace 尾部。取消/失败前的有价值上下文应作为脱敏 conversation facts 或当前 command 自身事件展示，不通过串线实现。

## 派生缓存边界

允许存在的派生状态只有两个用途：降低轮询开销和提升 UI 可见性。派生状态必须可被权威路径重建，且不得成为 terminal result 的替代 authority。

| 派生状态 | 允许用途 | 禁止用途 |
| --- | --- | --- |
| `codeAgentChatResults` | 保存刚提交的 running result、刚由 command result 生成的 terminal payload。 | 在 terminal 读取时跳过 command registry；返回旧 final response。 |
| `session.traceResults` | 保存按 traceId 写回的审计证据，加快 inspect/list 展示。 | 覆盖 command result；把旧 command 文本当成当前 trace final。 |
| `session.agentRun` | 保存最近或可复用 run seed。 | 证明当前 trace 的 commandId 或 final response。 |
| `session.finalResponse` / `session.traceSummary` | 只作为最近消息的派生展示，必须标明 traceId。 | 历史 result/trace 的 authority；修复其他 trace 时覆盖 latest。 |
| `runnerTrace` compact window | result 轮询里的轻量进度。 | Web 完整 trace 列表；历史 trace closeout 证据。 |

当派生状态和 AgentRun command registry 冲突时，以 command registry 和 command result 为准；冲突的派生状态应被下一次权威读取覆盖或忽略，不新增兼容分支。

## 禁止路径

- 不得为 trace/result 增加 parallel final response path、legacy mode、feature flag、旧 top-level fallback 或“查不到 command 就用 latest/cached result”的分支。
- 不得把 `runId` 当成 trace authority；共享 run 下必须使用 `commandId` 分割事件和 final response。
- 不得把 `provider=agentrun-v01` 当成真实模型/provider；`agentrun-v01` 只属于 adapter/runner infrastructure 字段。
- 不得在 Web、CLI 或 closeout 中把 `AgentRun result is ready`、terminal status echo、boilerplate completion row 或 placeholder status 当成 assistant final response。
- 不得通过拼接浏览器历史消息、旧 trace rows 或旧 summary 来制造 continuity；continuity 只由标准 `threadId` 和 AgentRun/Codex 原生 resume 证明。
- 不得新增 `HWLAB_API_KEY` 以外的 CLI/runner API key 来源，也不得让 Web session/cookie 成为 runner key fallback。

## 回归测试要求

源码层测试必须覆盖以下最小场景：

- 同一 `runId` 下两个 `traceId` / `commandId`，读取第一条历史 trace 时不显示第二条 command 的 assistant/tool/terminal rows。
- 第二条 trace 的 session top-level、`traceResults` 或内存 cache 被污染成第一条 command/final 时，`GET /result/{secondTraceId}` 必须通过 command registry/result 返回第二条 command 的 final response。
- 已 completed 的 AgentRun 内存缓存也必须走 command registry/result；不能只同步 running。
- command registry 找不到目标 `traceId` 时返回结构化错误，不返回旧 cache/latest/top-level。
- Web renderer 的纯逻辑测试覆盖 request/setup、tool call、assistant markdown、completion row、noise count 和 compacted trace 自动回放条件。

真实入口验收必须走目标 lane 的 public Cloud Web origin 或 Web 等价 CLI：`POST /v1/agent/chat`、`GET /v1/agent/chat/result/{traceId}`、`GET /v1/agent/chat/trace/{traceId}` 和 `inspect/session list`。仅有单测、PR merge、PipelineRun 或源码证据不能关闭 trace/result 类 issue。

## 相关文档

- [spec-v02-hwlab-cloud-web.md](spec-v02-hwlab-cloud-web.md)：Cloud Web 工作台、trace renderer 和 Web/CLI 同路径要求。
- [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md)：AgentRun run/command/resource bundle/credential 装配边界。
- [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent 真实 completed 判定和 provider readiness。
- [spec-user-access.md](spec-user-access.md)：Code Agent session owner、trace/result/cancel 权限边界。