From b9c1a124b07a3fc04c2c96427a37a7cb2153fc16 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Sat, 6 Jun 2026 17:35:33 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B2=89=E6=B7=80=20Code=20Agent=20tra?= =?UTF-8?q?ce=20=E5=BD=93=E5=89=8D=E6=80=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/spec-v02-code-agent-trace.md | 25 ++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/reference/spec-v02-code-agent-trace.md b/docs/reference/spec-v02-code-agent-trace.md index f8a96823..693ef311 100644 --- a/docs/reference/spec-v02-code-agent-trace.md +++ b/docs/reference/spec-v02-code-agent-trace.md @@ -4,13 +4,13 @@ ## 当前态总览 -当前 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。 +当前 Trace 架构只有一条 completed/final 权威路径：用户入口提交 turn 后，Cloud API 用 `traceId` 绑定 AgentRun command；terminal 读取时重新通过 AgentRun command registry 找到当前 `commandId`，再从 command result 重建 final response；running trace 刷新只轻量同步 AgentRun events，不等待 command result；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。 | +| Trace | `/v1/agent/chat/trace/{traceId}` -> 同一 `traceId -> commandId` 映射 -> AgentRun events 按 command 过滤 -> running 直接返回 live events；terminal 才同步 command result 形成 `terminalEvidence`。 | running trace 每轮先等待 command result、重复拉 events，未按 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。 | @@ -64,6 +64,18 @@ Completed result 响应必须把 AgentRun command result 的终态证据公开 Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 terminal”的轮询语义，不是 final fallback。Completed / failed / canceled / blocked 等 terminal 状态必须经过同一 command registry/result 路径确认。 +## Running Trace 刷新流程 + +`GET /v1/agent/chat/trace/{traceId}` 的 running 刷新是 Trace 用户可见性的关键路径，必须保持轻量、单向和可预测： + +1. Cloud API 先从当前 result/session seed 取得 AgentRun `runId` 和可用 `commandId` 线索，再调用 `refreshAgentRunTrace` 刷新 AgentRun events。刷新 events 是 running `/trace` 的第一动作；不得在刷新前等待 `syncAgentRunChatResult` 或 command result。 +2. AgentRun events 仍按当前 `traceId -> commandId` 过滤并写入 trace buffer。running 响应返回 live events、eventCount、traceStatus 和必要 error/blocker 信息；它不生成 assistant final response。 +3. `/trace` 只有在明确 terminal 状态、terminal result event 或 command result 已 terminal 时，才调用 `syncAgentRunChatResult` 读取 command result。此时 `/trace` 已经刷新过 events，result 同步不得再次重复拉同一批 events；实现应显式走 no-refresh-events 语义，避免同一轮请求 events fetch/append 两次。 +4. AgentRun/provider 执行失败、限流或 high-demand 错误必须作为 trace/result 状态和 terminal error 暴露；不得把执行层失败隐藏成 trace 缺失，也不得为了给 UI 拼完整回复而从 trace rows 反填 final response。 +5. running trace 的用户可见刷新目标是小于 5 秒。这里的目标衡量 Web/CLI 对同源 `/v1/agent/chat/trace/{traceId}` 的可见更新延迟，而不是要求模型执行成功或 final result 小于 5 秒。即使 `/result` 仍 running 或最终 failed，`/trace` 也应能在该窗口内暴露新增 events 或明确错误状态。 + +这条流程禁止把 running `/trace` 做成“先同步最终 result、再刷新 trace”的重路径。Result 慢、provider 慢或 command result 暂不可用时，trace 面板仍必须能独立显示当前 AgentRun events；terminal final response 则继续只由 command result 权威路径生成。 + ## Trace 读取与渲染流程 `GET /v1/agent/chat/trace/{traceId}` 服务完整 trace 回放，Cloud Web 与 `hwlab-cli client agent trace --render web` 必须共享同一 row 转换语义： @@ -81,7 +93,7 @@ Web、CLI 和 CI 的一致性按“入口同源、API 同 path、renderer 同代 - **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 查询。 +- **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 每个刷新 tick 必须并行启动 result 和 trace 请求，不得先等待 result 再请求 trace；不得给 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 验收。 @@ -112,12 +124,14 @@ Web、CLI 和 CI 的一致性按“入口同源、API 同 path、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 不足以证明用户路径已收敛。 +8. **刷新延迟按同源 trace 测**：trace 刷新性能问题必须用 public Cloud Web origin 或 Web 等价 CLI 采样 `/v1/agent/chat/trace/{traceId}`，记录 eventCount 变化和 trace endpoint latency；不得用内部 AgentRun events、pod log 或 `/result` 完成时间替代用户可见 trace 延迟。 ## 禁止路径 - 不得为 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 字段。 +- 不得让 running `/trace` 每轮先等待 command result、重复同步 events 或串行依赖 `/result`；trace 刷新慢不能靠加 Web 专用轮询、CLI 专用快速接口或 latest/cache fallback 解决。 - 不得在 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。 @@ -130,13 +144,14 @@ Web、CLI 和 CI 的一致性按“入口同源、API 同 path、renderer 同代 - 第二条 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。 +- running `GET /trace/{traceId}` 必须先刷新 AgentRun events 并返回 live trace；未 terminal 时不得调用 command result 同步，terminal 时 result 同步不得重复刷新同一批 events。 - 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 反填。 +- Web 测试必须覆盖 `mergeTraceResults`、compacted trace 自动请求完整 `/trace/{traceId}`、`subscribeToTrace` 在同一 refresh tick 并行启动 `/result` 与 `/trace`、`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`。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。 +真实入口验收必须走目标 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。Trace 刷新延迟类 issue 还必须给出至少一轮 running `/trace` eventCount 在小于 5 秒窗口内增长的证据；模型 high-demand、backend failed 或工具执行失败可以作为 out-of-scope 执行层状态记录，但不能替代 trace 可见性判定。仅有单测、PR merge、PipelineRun 或源码证据不能关闭 trace/result 类 issue。 ## 相关文档