docs: 沉淀 Trace 单一路径架构

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

@@ -2,6 +2,20 @@
 
 本文定义 HWLAB v0.2 Code Agent trace、result 和 Cloud Web trace 展示的数据权威、读写路径和回归判定。Trace 是 Workbench 最复杂的用户可见状态面；实现必须先收敛 source of truth，再生成派生 UI/cache，不得通过叠加 fallback、多路径或兼容快照掩盖状态污染。
 
+## 当前态总览
+
+当前 Trace 架构只有一条 completed/final 权威路径：用户入口提交 turn 后，Cloud API 用 `traceId` 绑定 AgentRun command；terminal 读取时重新通过 AgentRun command registry 找到当前 `commandId`，再从 command result 重建 final response；Web 和 CLI 只消费同一个 API payload，并通过同一个 row renderer 展示 trace。其他状态只能是 seed、cache 或 render-only evidence。
+
+| 阶段 | 唯一路径 | 不允许 |
+| --- | --- | --- |
+| 提交 | Cloud Web 或 `hwlab-cli client` -> Cloud Web 同源 `/v1/agent/chat` -> Cloud API -> AgentRun run/command。 | 绕到内部 manager、临时 job、旧 agent worker、浏览器历史拼 prompt 或 runner 直连入口。 |
+| Result | `/v1/agent/chat/result/{traceId}` -> session/run seed -> AgentRun command registry -> command result -> `terminalEvidence`。 | `latest`、top-level session snapshot、旧 `traceResults`、内存旧 cache 或共享 `runId` 直接当 final response。 |
+| Trace | `/v1/agent/chat/trace/{traceId}` -> 同一 `traceId -> commandId` 映射 -> AgentRun events 按 command 过滤 -> `terminalEvidence`。 | 未按 commandId 分割事件，或把其他 command 的 assistant/tool/terminal row 挤进当前 trace。 |
+| 渲染 | API payload -> `tools/src/hwlab-cli/trace-renderer.ts` 的 `traceDisplayRows` -> CLI `--render web` 和 Web `MessageTracePanel`。 | Web、CLI 各自实现一套 row 过滤/去噪/final 展示逻辑。 |
+| CI | 后端合同测试 + CLI/Web renderer 测试 + G14 component plan 共同覆盖同一 API path 和同一 renderer 文件。 | CI 只测内部 helper、fixture、裸 API 或旧 fallback contract，却不覆盖 Web 用户路径会用到的 API/renderer。 |
+
+这条路径的核心约束是“final response 只有 AgentRun command result 一个 authority”。`agent_sessions`、`codeAgentChatResults`、`runnerTrace`、Web local state 和 CLI summary 都不得产生第二个 final response；它们只能保存可被上述 authority 重建或解释的派生证据。
+
 ## 身份模型
 
 | 身份 | 归属 | 语义 |
@@ -60,6 +74,19 @@ Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 term
 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 自身事件展示，不通过串线实现。
 
+## Web/CLI/CI 同路径保证
+
+Web、CLI 和 CI 的一致性按“入口同源、API 同 path、renderer 同代码、CI 同组件模型”保证：
+
+- **Web 入口**：浏览器只从 Cloud Web origin 调用相对 `/v1/agent/chat*` 路径，经 Cloud Web/edge 进入 Cloud API；浏览器代码不得直连 AgentRun、内部 manager、pod service 或临时 debug endpoint。
+- **CLI 入口**：`hwlab-cli client agent send/result/trace/inspect/steer` 的标准 base-url 是目标 lane 的 Cloud Web origin，v0.2 public Web 等价入口为 `http://74.48.78.17:19666`；CLI 再请求同一 `/v1/agent/chat*` path，并且只从 `HWLAB_API_KEY` 生成 `Authorization: Bearer`。Cloud API 直连 `19667` 只允许作为 API 合同、admin/setup/gateway 或明确诊断证据，不能替代 Web trace/result issue 的 Web 等价验收。
+- **Trace renderer**：CLI 的 `agent trace --render web` 和 Web 的 `MessageTracePanel` 必须共同 import `tools/src/hwlab-cli/trace-renderer.ts`；任何 row 分类、noise count、completion row、assistant markdown、tool row 或 compacted trace 展示改动都先改这个共享 renderer，再由 Web/CLI 测试覆盖。
+- **Result/Trace state**：Web 的 result polling、trace replay、`mergeTraceResults` 和 CLI 的 poll/wait/trace 命令都必须以 `/v1/agent/chat/result/{traceId}` 和 `/v1/agent/chat/trace/{traceId}` 为唯一用户 API；不得给 Web 增加一条 session-level final response 查询，或给 CLI 增加一条内部 result manager 查询。
+- **CI component model**：`tools/src/hwlab-cli/trace-renderer.ts` 是 Cloud Web code input；改动、移动或重命名共享 renderer 时，必须同步 G14 CI component planner 和 planner 测试，保证 renderer 变化触发 Cloud Web 相关验证/rollout。服务端 trace/result 代码、Web trace state 和 CLI trace client 的 affected component 也必须保持在同一发布计划里。
+- **CI 语义边界**：CI 同路径不是要求单元测试访问公网；它要求 mock/contract 测试表达同一 HTTP path、同一 identity mapping、同一 renderer import 和同一失败语义。真实关闭 Web trace/result issue 时，再用目标 public Cloud Web origin 或 Web 等价 CLI 做 P4 验收。
+
+如果 Web、CLI 或 CI 只覆盖了上述链路的一段，不能称为同路径修复。例如只修 Web DOM、只修 CLI formatter、只修 session cache、只修 AgentRun events filter、或只让 CI mock helper 变绿，都可能继续保留另一条 final/trace 路径，导致“修过很多次但现象还在”。Trace 相关变更必须同时对齐 authority、API、renderer 和 component plan 四层中的相关部分。
+
 ## 派生缓存边界
 
 允许存在的派生状态只有两个用途：降低轮询开销和提升 UI 可见性。派生状态必须可被权威路径重建，且不得成为 terminal result 的替代 authority。
@@ -74,6 +101,18 @@ Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 term
 
 当派生状态和 AgentRun command registry 冲突时，以 command registry 和 command result 为准；冲突的派生状态应被下一次权威读取覆盖或忽略，不新增兼容分支。
 
+## 后续变更纪律
+
+后续任何 trace/result/final response 变更，必须先按本节收敛路径，再改实现或测试：
+
+1. **先定 authority**：新增字段或状态必须归类为 authority、seed、cache、render-only evidence 或 diagnostic；除了 AgentRun command result，其他类别都不能生成 terminal `reply.content` 或 `finalResponse`。
+2. **先删旧路再接新路**：如果新需求确实改变 authority 或 API path，必须在同一变更中删除旧 reader/writer、旧测试和旧门禁；不得保留 legacy mode、feature flag、双读、双写、兼容 fallback 或“查不到再试旧路径”。
+3. **失败要 fail closed**：找不到 `traceId -> commandId`、owner 不匹配、events 过期、command result 缺失或 cache 冲突时，返回结构化错误/retention/terminalEvidence，不用 latest、cached、top-level session 或其他 command result 补洞。
+4. **共享代码优先**：Web/CLI row 语义只能落在共享 renderer；Web state 只负责请求、合并和展示状态，CLI 只负责调用同一 API 和输出同一 renderer 结果，不能在两端分头补过滤规则。
+5. **组件模型跟着代码走**：移动 trace server、Web trace state、CLI trace client 或共享 renderer 时，必须同步 CI component planner；不能让文件路径变化把 Web/CLI trace 代码移出 Cloud Web 验证面。
+6. **旧断言一律拆除**：任何测试、预检、guard、gate 或 fixture 还在要求 `fallback` 字段、latest result、session top-level final、legacy trace snapshot 或双路径兼容时，删除并改写为本 SPEC 的当前目标行为；不得为了让旧断言通过而补兼容分支。
+7. **证据按路径给出**：trace/result closeout 必须同时列出 `traceId`、`runId`、`commandId`、API path、renderer 入口和 Web/CLI base-url；只给 job id、PipelineRun、单测或源码 diff 不足以证明用户路径已收敛。
+
 ## 禁止路径
 
 - 不得为 trace/result 增加 parallel final response path、legacy mode、feature flag、旧 top-level fallback 或“查不到 command 就用 latest/cached result”的分支。
@@ -92,8 +131,12 @@ Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 term
 - 已 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 自动回放条件。
+- Result/trace 响应序列化测试必须断言没有 `fallback` 字段，且 `traceId`、`agentRun.commandId`、`terminalEvidence.agentRun.commandId` 和 `finalResponse.traceId` 一致。
+- CLI 测试必须覆盖 `agent result`、`agent trace --render web`、`harness result` 和 `harness trace` 都请求 Cloud Web base-url 下的 `/v1/agent/chat/result/{traceId}` 或 `/v1/agent/chat/trace/{traceId}`，并暴露共享 renderer 标识。
+- Web 测试必须覆盖 `mergeTraceResults`、compacted trace 自动请求完整 `/trace/{traceId}`、`MessageTracePanel` 共享 renderer import，以及 final response 不从 trace row 或 session latest 反填。
+- CI planner 测试必须覆盖共享 renderer、服务端 trace/result、Web trace state 和 CLI trace client 的 affected component 归属；路径重命名时先更新 planner 测试，不用旧路径断言保护旧架构。
 
-真实入口验收必须走目标 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。
+真实入口验收必须走目标 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`。v0.2 默认用 `http://74.48.78.17:19666` 作为 Web 等价 base-url；`19667` API 直连只能补充证明 Cloud API contract，不能单独关闭 Web trace/result 类 issue。仅有单测、PR merge、PipelineRun 或源码证据不能关闭 trace/result 类 issue。
 
 ## 相关文档