mirrors/pikasTech-HWLAB

Fork 0

Files

T

Codex Agent 3dd7b2d1da docs: cross-ref hwlab-code-agent skill from long-term reference docs

2026-06-07 13:08:49 +08:00

25 KiB

Raw Blame History

v0.2 Code Agent Trace 规格

Code Agent 操作见 hwlab-code-agent skill。以下仅保留 trace renderer 架构和组合复用原则。

本文定义 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；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 过滤 -> 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。

这条路径的核心约束是“final response 只有 AgentRun command result 一个 authority”。agent_sessions、codeAgentChatResults、runnerTrace、Web local state 和 CLI summary 都不得产生第二个 final response；它们只能保存可被上述 authority 重建或解释的派生证据。

身份模型

身份	归属	语义
`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 路径确认。

Running Trace 刷新流程

GET /v1/agent/chat/trace/{traceId} 的 running 刷新是 Trace 用户可见性的关键路径，必须保持轻量、单向和可预测：

Cloud API 先从当前 result/session seed 取得 AgentRun runId 和可用 commandId 线索，再调用 refreshAgentRunTrace 刷新 AgentRun events。刷新 events 是 running /trace 的第一动作；不得在刷新前等待 syncAgentRunChatResult 或 command result。
AgentRun events 仍按当前 traceId -> commandId 过滤并写入 trace buffer。running 响应返回 live events、eventCount、traceStatus 和必要 error/blocker 信息；它不生成 assistant final response。
/trace 只有在明确 terminal 状态、terminal result event 或 command result 已 terminal 时，才调用 syncAgentRunChatResult 读取 command result。此时 /trace 已经刷新过 events，result 同步不得再次重复拉同一批 events；实现应显式走 no-refresh-events 语义，避免同一轮请求 events fetch/append 两次。
AgentRun/provider 执行失败、限流或 high-demand 错误必须作为 trace/result 状态和 terminal error 暴露；不得把执行层失败隐藏成 trace 缺失，也不得为了给 UI 拼完整回复而从 trace rows 反填 final response。
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 转换语义：

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 自身事件展示，不通过串线实现。
Steer 事件归属原 target trace。POST /v1/agent/chat/steer 被接受后，原 trace 的完整 trace/read/render 路径必须能看到 agentrun:steer:accepted 和 agentrun:steer:command-created，并保留目标 runId、targetCommandId 和 steerCommandId。后续 provider/backend terminal failure 仍是目标 turn 的终态；它不得删除 steer accepted/command-created rows，也不得被报告成 steer POST 短请求失败。

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 每个刷新 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 验收。

如果 Web、CLI 或 CI 只覆盖了上述链路的一段，不能称为同路径修复。例如只修 Web DOM、只修 CLI formatter、只修 session cache、只修 AgentRun events filter、或只让 CI mock helper 变绿，都可能继续保留另一条 final/trace 路径，导致“修过很多次但现象还在”。Trace 相关变更必须同时对齐 authority、API、renderer 和 component plan 四层中的相关部分。

组合优先原则

CaseRun、harness、runner、诊断脚本和其他上层编排工具需要查看 Code Agent trace 时，必须采用“ID + 既有工具组合”的方式，而不是在上层工具里重新实现 trace/result/session 查询和渲染逻辑。上层工具的职责是稳定返回 traceId、sessionId、conversationId、threadId、AgentRun runId/commandId 线索和可复制的下一条 HWLAB CLI 命令；完整 trace、result、inspect 和 Web renderer 语义继续由 hwlab-cli client agent trace/result/inspect 提供。

推荐输出合同：

traceLookup.source=hwlab-cli.client.agent，说明后续查询复用既有 HWLAB Agent CLI。
traceLookup.strategy=id_plus_existing_cli，说明当前工具只提供 identity 和组合 hint。
traceLookup.commands.result=hwlab-cli client agent result <traceId> --base-url <web-origin>。
traceLookup.commands.trace=hwlab-cli client agent trace <traceId> --base-url <web-origin> --render web。
traceLookup.commands.inspect=hwlab-cli client agent inspect --trace-id <traceId> --base-url <web-origin>。
有 sessionId 时可以补 traceLookup.commands.sessionStatus=hwlab-cli client agent session status <sessionId> --base-url <web-origin>。

这条规则的目的是通过组合复用保持单一 trace authority：CaseRun 或 harness 可以归档 traceLookup 和由 result payload 直接可得的终态摘要，但不得为了方便再发明一套 /trace/{traceId} fetch、row renderer、session 反查、final response 归因或 AgentRun events 过滤器。需要更多可见性时，先改进 hwlab-cli client agent trace/result/inspect 这些已有入口，再让上层工具返回新的 hint 或消费这些入口的稳定字段。

派生缓存边界

允许存在的派生状态只有两个用途：降低轮询开销和提升 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/final response 变更，必须先按本节收敛路径，再改实现或测试：

先定 authority：新增字段或状态必须归类为 authority、seed、cache、render-only evidence 或 diagnostic；除了 AgentRun command result，其他类别都不能生成 terminal reply.content 或 finalResponse。
先删旧路再接新路：如果新需求确实改变 authority 或 API path，必须在同一变更中删除旧 reader/writer、旧测试和旧门禁；不得保留 legacy mode、feature flag、双读、双写、兼容 fallback 或“查不到再试旧路径”。
失败要 fail closed：找不到 traceId -> commandId、owner 不匹配、events 过期、command result 缺失或 cache 冲突时，返回结构化错误/retention/terminalEvidence，不用 latest、cached、top-level session 或其他 command result 补洞。
共享代码优先：Web/CLI row 语义只能落在共享 renderer；Web state 只负责请求、合并和展示状态，CLI 只负责调用同一 API 和输出同一 renderer 结果，不能在两端分头补过滤规则。
组件模型跟着代码走：移动 trace server、Web trace state、CLI trace client 或共享 renderer 时，必须同步 CI component planner；不能让文件路径变化把 Web/CLI trace 代码移出 Cloud Web 验证面。
旧断言一律拆除：任何测试、预检、guard、gate 或 fixture 还在要求 fallback 字段、latest result、session top-level final、legacy trace snapshot 或双路径兼容时，删除并改写为本 SPEC 的当前目标行为；不得为了让旧断言通过而补兼容分支。
证据按路径给出：trace/result closeout 必须同时列出 traceId、runId、commandId、API path、renderer 入口和 Web/CLI base-url；只给 job id、PipelineRun、单测或源码 diff 不足以证明用户路径已收敛。
刷新延迟按同源 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。

回归测试要求

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

同一 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。
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 标识。
Steer 回归测试必须覆盖 /v1/agent/chat/steer 在 AgentRun steer command 创建后短连接 202 返回，不等待 owner/session/workspace 持久化；同一 target trace 的 render rows 必须包含 agentrun:steer:accepted 和 agentrun:steer:command-created。
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。Trace 刷新延迟类 issue 还必须给出至少一轮 running /trace eventCount 在小于 5 秒窗口内增长的证据；模型 high-demand、backend failed 或工具执行失败可以作为 out-of-scope 执行层状态记录，但不能替代 trace 可见性判定。仅有单测、PR merge、PipelineRun 或源码证据不能关闭 trace/result 类 issue。

25 KiB Raw Blame History Unescape Escape