fix: expose caserun trace lookup hints
This commit is contained in:
Codex Agent
@@ -233,7 +233,9 @@ bun tools/hwlab-cli/bin/hwlab-cli.ts case run result <runId>
|
||||
bun tools/hwlab-cli/bin/hwlab-cli.ts case run logs <runId> --tail 8000
|
||||
```
|
||||
|
||||
`case run` 在当前版本只负责编排流程和记录原始证据，不做 evidence 自动评价、自动打分或门禁判断。流程是：prepare 先在 subject repo 本地 checkout 下创建 `.worktree/caserun-<runId>` 隔离 worktree并写入 run-local spec，然后生成 Code Agent prompt/context，创建或调用 HWLAB Code Agent session，把 isolated worktree、run-local HWPOD spec、任务目标和约束交给 Code Agent；agent 阶段结束或超时后，CaseRun 采集 agent trace/terminal state/commandExecution 摘要、subject worktree 的 `git status` / `git diff --stat` / `git diff --binary`，再按 case 定义执行 runner 后置 `hwpod-cli build` 和 `cmd.run` Keil 异步 job-status 查询，最后把原始证据和可读归档写入 case registry repo 的 `runs/<caseId>/<runId>/`。固定归档包括 `evidence.json`、`summary.md`、`run.json`、`result.json`、`agent-prompt.md`、`agent-diff.patch`、run-local `.hwlab/hwpod-spec.yaml`、worker stdout/stderr、`artifact-manifest.json`，以及共享 Web/CLI trace renderer 生成的 `agent-messages.json`、`agent-trace.md`、`agent-transcript.md` 和 `final-response.md`。`agent-trace.md` / `agent-transcript.md` 必须包含 rendered trace rows、renderer 标识和 subject diff 区块；`final-response.md` 在存在权威 finalResponse 时保存正文，不存在时显式记录 `finalResponse=null`、terminal/error rows 和缺失原因。下载不作为 compile-only CaseRun 的隐式步骤；后续需要下载时，应作为独立 action 显式加入 case 定义和流程记录。
|
||||
`case run` 在当前版本只负责编排流程和记录原始证据，不做 evidence 自动评价、自动打分或门禁判断。流程是：prepare 先在 subject repo 本地 checkout 下创建 `.worktree/caserun-<runId>` 隔离 worktree并写入 run-local spec，然后生成 Code Agent prompt/context，创建或调用 HWLAB Code Agent session，把 isolated worktree、run-local HWPOD spec、任务目标和约束交给 Code Agent；agent 阶段结束或超时后，CaseRun 记录 agent identity、terminal result 里已有的终态字段、trace lookup hint、subject worktree 的 `git status` / `git diff --stat` / `git diff --binary`，再按 case 定义执行 runner 后置 `hwpod-cli build` 和 `cmd.run` Keil 异步 job-status 查询，最后把原始证据和可读归档写入 case registry repo 的 `runs/<caseId>/<runId>/`。固定归档包括 `evidence.json`、`summary.md`、`run.json`、`result.json`、`agent-prompt.md`、`agent-diff.patch`、run-local `.hwlab/hwpod-spec.yaml`、worker stdout/stderr、`artifact-manifest.json`，以及 `agent-messages.json`、`agent-trace.md`、`agent-transcript.md` 和 `final-response.md`。`agent-trace.md` / `agent-transcript.md` 必须包含 trace lookup hint、renderer 标识和 subject diff 区块；如果归档了完整 rendered rows，其语义必须来自共享 Web/CLI trace renderer，不能由 CaseRun 自行发明。`final-response.md` 在 terminal result 存在权威 finalResponse 时保存正文，不存在时显式记录 `finalResponse=null`、terminal/error rows 和缺失原因。下载不作为 compile-only CaseRun 的隐式步骤；后续需要下载时，应作为独立 action 显式加入 case 定义和流程记录。
|
||||
|
||||
CaseRun 的 trace 处理必须遵循 [spec-v02-code-agent-trace.md](spec-v02-code-agent-trace.md) 的组合优先原则：CaseRun 只负责稳定返回和归档 `traceId`、`sessionId`、`conversationId`、`threadId`、AgentRun 执行线索以及 `traceLookup.commands.*`，完整 trace/result/session 读取继续使用已有 `hwlab-cli client agent trace/result/inspect`。CaseRun 不应在自身内部再实现一套 `/v1/agent/chat/trace/{traceId}` 查询器、row renderer、session 反查或 final response 归因逻辑；如果已有 agent CLI 的 trace 可见性不足，先改进 `client agent trace/result/inspect`，再让 CaseRun 输出新的 ID 或 hint。归档中的 `agent-trace.json` 可以是 `lookupOnly=true` 的 identity manifest，表示“用这些 ID 调既有 CLI 查完整 trace”，不能伪装成完整 trace dump。
|
||||
|
||||
长时间 CaseRun 必须优先使用 `case run start/status/result/logs` 短连接形态，而不是用 shell/nohup 包装同步 `case run`。`start` 只负责创建 `.state/hwlab-cli/caserun/<runId>/`、启动后台 worker 并立即返回 `runId`、PID、stdout/stderr 路径和下一条查询命令；`status`、`result`、`logs` 都是短查询。`run.json` 是阶段状态权威，阶段开始时就要刷新 `status`、`stage`、`traceId/sessionId/conversationId/threadId`、AgentRun/trace 轮询信息、stdout/stderr byte count 和下一条轮询命令；长等待期间不得出现无输出、无 trace、无状态文件更新的黑洞窗口。
|
||||
|
||||
|
||||
@@ -100,6 +100,21 @@ Web、CLI 和 CI 的一致性按“入口同源、API 同 path、renderer 同代
|
||||
|
||||
如果 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。
|
||||
|
||||
Reference in New Issue
Block a user