docs: 固化 Code Agent session 手动化规格

This commit is contained in:
Codex
2026-06-03 09:29:30 +08:00
parent 66dd78d20c
commit d39d184eae
5 changed files with 56 additions and 34 deletions
+24 -12
View File
@@ -10,12 +10,22 @@
当前阶段的 Web 等价 CLI 验收默认使用 `admin` 的默认账号 workspace:不要为了避免污染而临时创建测试账号、切换 profile、指定临时 `projectId` 或隔离 workspace。需要清理上下文时直接通过 `client workbench restore/status/reset --confirm` 作用于 admin 默认 workspace,并在 issue 评论记录 reset、traceId、workspace revision 和恢复结果。只有用户明确要求多账号/多 profile 隔离验证,或目标功能本身就是账号隔离/profile 行为时,才使用 `--profile`、新增账号或非默认 `projectId`
## Code Agent session 手动化
Code Agent session 是显式资源,不再由普通 `client agent send`、Workbench composer、`--from-trace` 或账号 workspace 自动创建、滚动或替换。账号 workspace 只能记录当前显式选中的 session、最近 trace 和展示状态;它不是隐式 session factory。
- 无 Code Agent session 时,必须先显式创建 session,再发送 turn。CLI 目标入口为 `client agent session create`;Web 目标入口为“新建 session”显式动作;Cloud API 目标入口为 `POST /v1/agent/sessions`。session 创建返回 `conversationId/sessionId``threadId` 可以在首轮 turn 被 provider/AgentRun 建立后回写。
- `client agent send` 必须携带显式 `--session-id`,或使用此前通过 `client agent session create|select` 明确选中的 workspace session;没有显式或已选 session 时返回结构化 `session_required`,不能自动生成 `conversationId/sessionId/threadId`
- session 失败、`thread-resume-failed`、provider continuation 失效、用户取消或运行面中断时,当前 session 必须保留为 failed/stale/canceled 证据;系统不得自动滚动到新 session、不得隐式清理后继续,也不得把下一条普通消息路由到新 session。继续工作前必须显式创建或选择另一个 session。
- `--from-trace` 只用于 inspect 和显式复现 trace 所属 session;如果 trace 所属 session 已失败或 staleCLI/Web/API 必须返回该失败 session 的证据和“请显式创建新 session”建议,不能自动替换 continuation。
- 最终 CLI 交互验收必须使用 HWLAB CLI 原入口,并按“登录 -> 显式创建或选择 session -> `client agent send --session-id ... --provider-profile minimax-m3 --message "在吗?"` -> result/trace”的顺序执行;不得用 UniDesk CLI 包装测试,也不得用 fresh auto session 掩盖失败 session 问题。
## 在系统中的职责划分
- 提供 WEB 等价的非视觉业务入口:登录鉴权、session 恢复、Device Pod 看板、Code Agent 对话、trace/result 轮询、logout 和工作台 live summary。
- 提供 WEB 等价的非视觉业务入口:登录鉴权、显式 Code Agent session 管理、Device Pod 看板、Code Agent 对话、trace/result 轮询、logout 和工作台 live summary。
- 只走 Cloud Web 同源 API surface;正式运行时由 `HWLAB_RUNTIME_*` 装配出当前 lane 的 Web/API endpoint,失败时必须 fail closed,不能静默退回 legacy DEV 入口。
- Web/CLI 路径一致性优先于继续 Web 修复。Cloud Web 暴露 Code Agent、AgentRun、continuation、steer、trace/result 或 provider 问题后,必须先能用 runtime namespace/lane 装配出的 `bun tools/hwlab-cli/bin/hwlab-cli.ts client agent send/result/trace/inspect/steer ...` 对同一 Cloud Web origin、同一 `/v1/agent/chat*`、同一 `conversationId/sessionId/threadId/retryOf` 复现或解释,再继续修 Web 状态机。Cloud API 只用于显式 admin/setup/gateway 诊断,不得替代 WEB 同源路径验收。
- 从 Web trace 回放 Code Agent 问题时,优先用 `client agent send --from-trace <traceId>` 读取 Cloud Web 的 `/v1/agent/chat/inspect`自动带回原 `conversationId/sessionId/threadId` 并把 `retryOf` 指向来源 trace;只有 inspect 缺失时才手动传 `--conversation-id``--session-id``--thread-id``--retry-of`。CLI 输出必须包含 replay 来源、inspect 状态和 redacted continuation 摘要
- 从 Web trace 回放 Code Agent 问题时,优先用 `client agent inspect --trace-id <traceId>` 读取 Cloud Web 的 `/v1/agent/chat/inspect`输出 trace 所属 `conversationId/sessionId/threadId`、session 状态和 `retryOf` 建议;`client agent send --from-trace <traceId>` 只能作为显式复现该 trace 所属 session 的入口,不能自动创建、滚动或替换 session。inspect 缺失或 session 已 failed/stale 时,CLI 必须返回结构化 blocker 和显式新建 session 建议
- 默认业务子命令不直连 Postgres、Kubernetes Service、Secret、device-pod 内部 Service、gateway RPC 或本地 fixture;需要鉴权的请求使用 `/auth/*` 返回的 cookie 或显式 `--cookie`。唯一例外是 `client gateway` 诊断族:它使用同一 runtime endpoint resolver 定位 Cloud API,用于短连接观测 gateway session、单次 shell invoke 和 transport 压测;该入口只验证底层传输稳定性,不替代 Web 用户流程授权,也不发布镜像或常驻服务。显式 API URL 只作为 unlocked local debug 入口。
- Pod 内透传执行不放进 `hwlab-cli`;需要进入正在工作的 Code Agent/Cloud API pod 时,`hwlab-cli` 只查询并输出 UniDesk 标准 route,实际透传由 UniDesk `bun scripts/cli.ts ssh 'G14:k3s:hwlab-v02:pod:<pod>:<container>' ...` 完成。`pod:` 是 route 语法,`/` 只用于 pod 内文件系统路径。
- `client runtime routes` 必须按当前运行 profile/lane 的数据生成 UniDesk `pod:` route;实现不得硬编码 `dev``v0.2``v0.3`、namespace 或 catalog path。新增版本只允许通过 `deploy.json.lanes[profile]` 声明 namespace、artifact catalog 和 service overrides,不为每个版本新增代码分支。
@@ -27,11 +37,11 @@
- Code Agent 交互必须默认暴露 `traceId``resultUrl`、终态和 assistant 回复文本摘要;不能要求用户先拉全量 trace 再手工查找回复。
- CLI 本地登录态必须支持 `--profile NAME` 隔离,同一 base URL 下不同 profile 写入 `.state/hwlab-cli/profiles/<base-url-hash>/<profile>.json`。切换到其他账号再切回原账号时,`client workbench restore/status` 必须从服务端账号 workspace 恢复之前的 `workspaceId``conversationId``sessionId``threadId``activeTraceId` 和 revision,而不是只依赖本地文件。
- `client workbench restore/status/watch/reset` 是账号 workspace 的非视觉入口:`restore/status` 对应 `GET /v1/workbench/workspace``watch` 对应 `/events?afterRevision=``reset --confirm` 对应服务端 reset。输出必须显示 workspace revision、selected conversation/session、active trace 和本地 state file,且不得保存 password、session token 原文以外的 Secret 值。
- `client agent send` 是 Cloud Web Code Agent composer 的非视觉等价入口。它必须支持 `--from-trace``--conversation-id``--session-id``--thread-id``--retry-of`,并在输出中返回 redacted continuation 摘要,证明本次 CLI 请求是否覆盖 Web 的继续会话路径。浏览器 issue 中已经给出 traceId 时,复现命令优先使用 `--from-trace <traceId>`,让 CLI 先走 `/v1/agent/chat/inspect` 读取标准 continuation IDs,再提交同源 `/v1/agent/chat`
- `client agent send` 是 Cloud Web Code Agent composer 的非视觉等价入口。它必须支持 `--session-id``--thread-id``--conversation-id``--from-trace``--retry-of`,并在输出中返回 redacted continuation 摘要`send` 只能向显式传入或已显式选中的 session 提交 turn;没有 session 时返回 `session_required`session failed/stale 时返回 `session_not_usable`,不能隐式创建或滚动 session。浏览器 issue 中已经给出 traceId 时,复现命令先 `inspect`,再由用户显式确认要复现原 session 或创建新 session
- `client agent send --from-trace` 只能用 inspect 恢复 `conversationId/sessionId/threadId/retryOf` 和提交本轮原始消息;不得把 inspect 的 messages/facts 作为 `conversationContext``messages` 或 prompt 前缀提交。CLI 的 continuation 摘要只用于可见性,不是模型上下文。
- `client agent composer status|submit` 是 Cloud Web composer 的状态机等价入口。`status` 必须先恢复账号 workspace,再用与 Web 相同的 composer policy 输出 `locked``disabled``submitMode``route``targetTraceId`、conversation/session/thread 和 workspace revision运行中 turn 必须显示 `locked=false``disabled=false``submitMode=steer``submit` 必须按该 policy 自动选择 `/v1/agent/chat``/v1/agent/chat/steer`,不得要求用户手动判断 URL 或绕过 Cloud Web 同源 path
- `client agent composer status|submit` 是 Cloud Web composer 的状态机等价入口。`status` 必须先恢复账号 workspace,再输出 `sessionRequired``sessionUsable``submitMode``route``targetTraceId`、conversation/session/thread 和 workspace revision没有已选 session 必须显示 `sessionRequired=true``submit` 只能在已显式选中可用 session 时提交 turn;运行中 trace 的 steer 仍走同源 `/v1/agent/chat/steer`,但不能借 steer/turn policy 自动创建或滚动 session
- Code Agent continuation 的 thread 字段只有 `threadId` 一个标准名称。CLI 读取 inspect、`--from-trace` 回放、手动 `--thread-id` 提交和输出摘要都必须以该字段为唯一 thread identity;服务端响应也应保持同一字段口径。
- `client agent send` 默认先恢复账号 workspace,从 selected conversation/session workspace JSON 中读取标准 `conversationId/sessionId/threadId`,再向 `/v1/agent/chat` 发送这些 IDs`workspaceId``expectedWorkspaceRevision`服务端接受后 CLI 保存新的 workspace revision终态轮询后 PATCH workspace 清理终态 `activeTraceId`。默认 workspace 恢复只恢复 ID 和 revision不恢复 messages/facts,不生成 `conversationContext`,也不得把历史文本拼入 prompt。显式传入新的 `--conversation-id` 且没有显式 `--session-id/--thread-id` 时,CLI 必须把它视为新独立 conversation,不得从默认 workspace 继承旧 session/thread,避免 stale continuation 误续接。只有显式 `--no-workspace` 才跳过这一默认恢复路径
- `client agent send` 可以恢复账号 workspace 来读取“已显式选中”的 session,但 workspace 只代表 selection,不代表自动创建或自动恢复。`send` 只发送该 session 的 `conversationId/sessionId/threadId``workspaceId``expectedWorkspaceRevision`;终态轮询后 PATCH workspace 只能更新 session 状态、active trace 和 evidence。默认 workspace 恢复不恢复 messages/facts,不生成 `conversationContext`,也不得把历史文本拼入 prompt。显式传入新的 `--conversation-id` 不能隐式继承旧 session/thread;需要新 session 时必须先 `client agent session create`
- `client agent steer <traceId>` 是运行中引导入口,必须调用 Cloud Web 同源 `POST /v1/agent/chat/steer`,把 steer 文本装配成 AgentRun `type=steer` command 作用到目标 trace 的 active turn。CLI 不手动穿内部 URL;验收使用当前 runtime namespace/lane 自动解析的 `19666` Web 入口,并通过原 trace 的 result/trace 观察 steer 是否被 runner 接收和应用。
- `client agent trace <traceId> --render web` 必须调用 Cloud Web trace row 的同一纯转换路径,输出 `render="web"`、renderer 标识、source event count、rendered row count、默认压制的 noise event count 和 row 摘要。浏览器 trace 展示错乱时,必须先用该 CLI 入口确认 Web 渲染转换是否已经乱序、重复、缺 final response、吞掉关键 row 或只显示泛化 tool call,再继续修浏览器 DOM/CSS。
- AgentRun v0.1 短连接 runner 已要求支持同 run/runner 多轮 command。CLI 仍应把 Web 提交的 `conversationId/sessionId/threadId` 原样送到 Cloud Web API,用于验证 adapter 是否在 runner reuse window 有效时复用同一个 AgentRun `runId` / `jobName` 并创建新 `commandId`;每轮都新建 runner 或重新 bundle 不是通过状态,trace 中的原因说明只能用于定位。
@@ -63,7 +73,8 @@
| `hwlab-cli client gateway sessions` | `GET Cloud API /v1/gateway/sessions` | 显式 Cloud API 诊断入口,观察 gateway online/stale、inflight 和 capability;默认不带 Web cookie。 |
| `hwlab-cli client gateway invoke` | `POST Cloud API /v1/rpc/hardware.invoke.shell` | 显式 Cloud API 诊断入口,执行一次 bounded shell dispatch 并返回结构化 dispatch 摘要。 |
| `hwlab-cli client gateway pressure` | `POST Cloud API /v1/rpc/hardware.invoke.shell` | 显式 Cloud API 压测入口,真实验证大输出、长单行、stderr、timeout 和并发超容量不会造成黑洞。 |
| `hwlab-cli client agent send` | `GET /v1/agent/chat/inspect` + `POST /v1/agent/chat` + `GET /result/{trace}` | 以 short connection 提交 Code Agent 消息并轮询结果,默认输出 assistant 回复文本摘要;支持 `--from-trace` 自动复现 Web continuation,也支持手动 `--conversation-id``--session-id``--thread-id``--retry-of`。 |
| `hwlab-cli client agent session create|select|status|list` | `POST/GET/PATCH /v1/agent/sessions*` + `GET/PATCH /v1/workbench/workspace*` | 显式创建、选择和观察 Code Agent sessionsession 创建或选择是 `send` 前置条件。 |
| `hwlab-cli client agent send` | `GET /v1/agent/chat/inspect` + `POST /v1/agent/chat` + `GET /result/{trace}` | 以 short connection 向显式 session 提交 Code Agent turn 并轮询结果,默认输出 assistant 回复文本摘要;支持 `--from-trace` 显式复现 Web continuation,但不自动创建或滚动 session。 |
| `hwlab-cli client agent composer status|submit` | `GET /v1/workbench/workspace` + `POST /v1/agent/chat``POST /v1/agent/chat/steer` | 使用 Web 共享 composer policy 探测输入框锁定状态和 turn/steer 分流;运行中应显示无锁 steer,并自动提交 steer。 |
| `hwlab-cli client agent trace TRACE [--render web]` | `GET /v1/agent/chat/trace/{trace}` | 回放 trace,默认输出状态、事件摘要和 assistant stream 文本;`--render web` 复用 Cloud Web trace row 转换,便于 CLI 复现 Web trace 渲染问题。 |
| `hwlab-cli client agent steer TRACE` | `POST /v1/agent/chat/steer` | 对目标 trace 的运行中 Code Agent turn 发送 steer 文本;默认短连接返回 accepted 和 steer command 摘要,后续观察原 trace 的 result/trace。 |
@@ -90,15 +101,15 @@
## T3
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:运行 `client agent send --message "你好" --provider-profile deepseek --timeout-ms 120000`,确认响应包含 accepted/result/trace 信息和 assistant 回复文本;若 DeepSeek trace 明确失败为 AgentRun `provider-auth-failed` 且上游错误为 `INSUFFICIENT_BALANCE` / account balance 不足,则改用 `client agent send --message "你好" --provider-profile minimax-m3 --timeout-ms 120000` 继续同一验收。该替换只改变 provider profile,不允许改变 AgentRun ResourceBundle、Codex stdio `thread/start` / `thread/resume`、promptRefs/skillRefs/toolAliases 装配或手动拼接历史上下文;其他后端失败仍必须输出 traceId、resultUrl 或 runnerTrace 摘要,不能无输出或只给旧 gate blocker
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:运行 `client agent session create --provider-profile minimax-m3` 显式创建 session,再运行 `client agent send --session-id <sessionId> --message "在吗?" --provider-profile minimax-m3 --wait --timeout-ms 120000`,确认响应包含 accepted/result/trace 信息和 assistant 回复文本。未先创建或选择 session 时,`client agent send --message "在吗?"` 必须返回结构化 `session_required`,不能自动创建 session。该验收默认使用 MiniMax-M3;如果是 DeepSeek 专项才切换 provider profile
## T3.1
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:对一个来自 Cloud Web 的失败 trace 运行 `client agent send --from-trace <traceId> --message "重试上一条" --provider-profile deepseek --no-wait`,确认 CLI 访问 `/v1/agent/chat/inspect?traceId=<traceId>`,再提交 `/v1/agent/chat`,输出包含 `replay.source``continuation.replayedFromTrace``conversationId/sessionId/threadId/retryOf`,且不输出 cookie、token 或 secret 原文。
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:对一个来自 Cloud Web 的失败 trace 运行 `client agent inspect --trace-id <traceId>`,确认 CLI 访问 `/v1/agent/chat/inspect?traceId=<traceId>` 并输出 trace 所属 `conversationId/sessionId/threadId/retryOf`、session 状态和 redacted continuation。若该 session 为 failed/stale,再运行 `client agent send --from-trace <traceId> --message "重试上一条" --provider-profile minimax-m3` 必须返回 `session_not_usable` 或等价 blocker,并提示显式创建新 session;不得自动滚动到新 session,也不得输出 cookie、token 或 secret 原文。
## T5.1
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:复测取消后追问场景时,`client agent send/result/trace --render web` 输出只允许出现标准 `threadId`,不允许出现历史 thread 别名字段;第二轮必须是新 `commandId` 且 trace row 不包含上一 command 的尾部 assistant/tool/terminal 文本。
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:复测取消后追问场景时,必须继续使用同一个显式 session;`client agent send/result/trace --render web` 输出只允许出现标准 `threadId`,不允许出现历史 thread 别名字段;第二轮必须是新 `commandId` 且 trace row 不包含上一 command 的尾部 assistant/tool/terminal 文本。取消后的 session 若被标记 failed/stale,则不能自动滚动,必须先显式创建新 session。
## T3A
@@ -110,11 +121,11 @@
## T3.3
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:在 runtime endpoint locked 环境下先运行 `client agent send --message "执行一个会持续运行的任务,等待后续 steer" --provider-profile deepseek` 获得运行中 trace,再运行 `client agent steer <traceId> --message "请把最终回复包含 STEER_ACCEPTED 标记"`,最后用 `client agent result <traceId>``client agent trace <traceId> --render web` 确认同一 target trace 出现 AgentRun steer command 事件且最终回复或 trace 可见 steer 处理结果。该验收必须使用 runtime namespace/lane 自动解析出的同源 Web 入口,不能 mock,也不能用自动交互脚本,不能手动传 URL。
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:在 runtime endpoint locked 环境下先显式创建 Code Agent session,再运行 `client agent send --session-id <sessionId> --message "执行一个会持续运行的任务,等待后续 steer" --provider-profile minimax-m3` 获得运行中 trace;随后运行 `client agent steer <traceId> --message "请把最终回复包含 STEER_ACCEPTED 标记"`,最后用 `client agent result <traceId>``client agent trace <traceId> --render web` 确认同一 target trace 出现 AgentRun steer command 事件且最终回复或 trace 可见 steer 处理结果。该验收必须使用 runtime namespace/lane 自动解析出的同源 Web 入口,不能 mock,也不能用自动交互脚本,不能手动传 URL。
## T3.4
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:启动真实运行中的 Code Agent turn,再运行 `client agent composer status`,确认 `composer.locked=false``composer.disabled=false``composer.submitMode=steer``composer.route=/v1/agent/chat/steer``composer.targetTraceId=<运行中 trace>`;随后运行 `client agent composer submit --message "请在最终回复或 trace 中体现 COMPOSER_STEER_OK"`,确认请求自动走 Cloud Web 同源 `/v1/agent/chat/steer`,最后用原 trace 的 `client agent result``client agent trace --render web` 验证 steer 可见。该验收必须使用 runtime namespace/lane 自动解析入口,不能手动传 URL、不能 mock、不能用自动交互脚本。
阅读 docs/reference/spec-v02-hwlab-cli.md,然后在 `G14:/root/hwlab-v02` 用 cli 手动测试以下内容:未选择 session 时运行 `client agent composer status` 必须显示 `sessionRequired=true`;显式创建 session 并启动真实运行中的 Code Agent turn,再运行 `client agent composer status`,确认输出当前 `sessionId``submitMode=steer``composer.route=/v1/agent/chat/steer``composer.targetTraceId=<运行中 trace>`;随后运行 `client agent composer submit --message "请在最终回复或 trace 中体现 COMPOSER_STEER_OK"`,确认请求走 Cloud Web 同源 `/v1/agent/chat/steer`,最后用原 trace 的 `client agent result``client agent trace --render web` 验证 steer 可见。该验收必须使用 runtime namespace/lane 自动解析入口,不能手动传 URL、不能 mock、不能用自动交互脚本。
## T4
@@ -138,7 +149,8 @@
| --- | --- | --- |
| 固定 repo 短连接 client | 目标状态 | `hwlab-cli``G14:/root/hwlab-v02` 或当前 v0.2 worktree 直接用 Bun 运行,不作为 runtime service。 |
| WEB 等价 API client | 目标状态 | `client` 子命令覆盖 Cloud Web 非视觉业务面。 |
| WEB composer 状态机等价 | 已实现 | `client agent composer status|submit` 复用 Web composer policy,可探测输入框无锁和自动 steer/turn 分流。 |
| 显式 Code Agent session 管理 | 目标状态 | `client agent session create|select|status|list``send` 前置;普通 `send` 不自动创建或滚动 session。 |
| WEB composer 状态机等价 | 目标状态 | `client agent composer status|submit` 复用 Web composer policy,但必须显示 sessionRequired/sessionUsable,不能自动创建或滚动 session。 |
| JSON-RPC 同源 API | 目标状态 | `client rpc` 自动补齐 Web JSON-RPC envelope 的 `meta` 字段。 |
| 通用同源 API request | 目标状态 | `client request` 用于追平低频和新增 WEB API,禁止绝对 URL。 |
| G14 harness-ops 短连接能力 | 目标状态 | `client harness` / `client harness-ops` / `client harness-opt` 覆盖 submit/result/trace/wait/audit,只作为业务 API client。 |