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 填补。

写入流程

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

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

Completed result 响应必须把 AgentRun command result 的终态证据公开为 terminalEvidence，并与 agentRun.commandId、finalResponse.traceId 保持一致。/result 和 /trace 响应不得导出 fallback 字段；降级、缺失或过期只能用 status、traceStatus、retention、error 和 terminalEvidence 表达，避免旧 fallback contract 重新成为并行 final response 路径。

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 转换语义：

Cloud API 先用 result 同一路径解析当前 traceId -> commandId；对于 AgentRun trace，events 必须按该 commandId 过滤。
可读 rows 至少覆盖 request/setup、tool call、assistant message、terminal/result 和 blocker。低价值 AgentRun backend echo、状态 echo、terminal boilerplate 和重复噪声可被 row renderer 去噪，但原始 trace JSON 仍应通过 --full 或下载保留。
Web 默认显示完整可读事件列表。Result polling 返回的 compacted head-tail runnerTrace 不能冒充完整 trace；发现 eventsCompacted=true 时必须继续请求 /trace/{traceId}。
如果完整 trace 已过期或缺失，UI 必须显式展示 missing/expired，并提供 result/inspect 可用证据；不得用最新 trace 或 session final response 填补历史 trace。
同一 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。

11 KiB Raw Blame History Unescape Escape