From d39d184eae0aa6215b8dbcf6856fc1d8ed5791d5 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 3 Jun 2026 09:29:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20Code=20Agent=20ses?= =?UTF-8?q?sion=20=E6=89=8B=E5=8A=A8=E5=8C=96=E8=A7=84=E6=A0=BC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/cloud-workbench.md | 6 ++-- docs/reference/code-agent-chat-readiness.md | 19 ++++++----- docs/reference/spec-v02-hwlab-cli.md | 36 ++++++++++++++------- docs/reference/spec-v02-hwlab-cloud-api.md | 15 +++++---- docs/reference/spec-v02-hwlab-cloud-web.md | 14 ++++---- 5 files changed, 56 insertions(+), 34 deletions(-) diff --git a/docs/reference/cloud-workbench.md b/docs/reference/cloud-workbench.md index e4c7143b..ee134c22 100644 --- a/docs/reference/cloud-workbench.md +++ b/docs/reference/cloud-workbench.md @@ -27,8 +27,10 @@ Cloud Workbench is the default user-facing frontend at - Cloud Web 的 Code Agent 非视觉业务路径必须能被 `hwlab-cli client agent` 复现。Web 发现 AgentRun、session continuation、trace/result 或 provider 问题时，先用 CLI 通过同一 Cloud Web base URL、同一 `/v1/agent/chat`、同一 - `conversationId/sessionId/threadId/retryOf` 复现，再进入前端状态机或样式修复； - 不能用只覆盖首轮新会话的 CLI 验收替代 Web continuation 验收。 + 显式 `conversationId/sessionId/threadId/retryOf` 复现，再进入前端状态机或样式修复。 + Code Agent session 管理必须手动化：无 session 时先显式创建 session，session failed/stale + 时保留失败证据并要求显式新建或选择 session；不能用只覆盖首轮自动新会话的 CLI 验收 + 替代 Web continuation 验收。 ## Required Layout diff --git a/docs/reference/code-agent-chat-readiness.md b/docs/reference/code-agent-chat-readiness.md index b488b89b..7ba7d975 100644 --- a/docs/reference/code-agent-chat-readiness.md +++ b/docs/reference/code-agent-chat-readiness.md @@ -184,13 +184,16 @@ blocker，不能降级到 M3 Skill CLI、受控硬件 shortcut、外网专用检 进入 gateway 前保留固定 `DO1/DI1` 或固定 gateway 身份白名单预拦截；真实下游执行失败可以 返回执行失败，但不能由 cloud-api 用旧白名单提前拒绝。 -持久 session 是默认合同：同一个 `conversationId/sessionId` 必须映射到 repo-owned Codex -thread 和固定 workspace，刷新前端、重新打开页面或短连接 result 轮询不得创建新的短期 runner。 -除非 Pod 重建或 Codex supervisor 明确重启，workspace、thread/session 绑定和可见 trace 应持续 -存在。Workbench 前端必须把这些会话标识和最近消息持久化到浏览器本地状态；用户显式清空 -对话或登出时才清除该本地状态。刷新后下一轮自然语言请求必须携带已保存的 -`conversationId/sessionId/threadId`，不能只因为 JS 内存重建就显示“首轮请求”或重新分配 -Codex workspace。 +显式持久 session 是默认合同：用户、Workbench 或 CLI 必须先显式创建或选择 Code Agent +session，之后同一个 `conversationId/sessionId` 才能映射到 repo-owned Codex thread 和固定 +workspace。刷新前端、重新打开页面或短连接 result 轮询只能恢复已显式选中的 session， +不得创建新的短期 runner，也不得在无 session 时自动生成 `conversationId/sessionId/threadId`。 +没有已选 session 时，`/v1/agent/chat` 必须返回 `session_required`；session failed/stale/canceled +时必须返回 `session_not_usable` 或等价 blocker。失败 session 保留 trace、thread、partial output +和错误证据，不自动滚动、不隐式清理后继续；继续工作前必须显式创建或选择另一个 session。 +除非 Pod 重建或 Codex supervisor 明确重启，usable session 的 workspace、thread/session 绑定和 +可见 trace 应持续存在。Workbench 前端可以持久化这些会话标识和最近消息，但只作为显式 session +selection 的缓存；用户显式清空对话或登出时才清除该本地状态。 ## PC Gateway Windows Skill 调用 @@ -231,7 +234,7 @@ Workbench 与 Code Agent 的用户请求必须是短连接 submit + 短连接 re Code Agent backend 的 completed 语义只能来自真实 Codex app-server `turn/completed` 成功事件。`item/agentMessage/delta`、`item/completed`、已有 assistant 文本、transport close 或 activity idle timeout 都不能单独升级成 `status: "completed"`。如果已经收到部分 assistant 文本但没有收到 `turn/completed`，终态必须是 timeout/partial blocker，并保留 trace、session、thread、partial output 摘要和可重试提示；Workbench 只能显示“部分回复/超时”，不能标 DEV-LIVE reply pass。 -`Codex app-server transport closed after partial assistant output but before turn/completed` 不能单独判定为 CI/CD 滚动中断。排查必须同时看三类证据：失败 trace 的 `providerTrace`/`runnerTrace`、对应 `hwlab-cloud-api` Pod 的 restart/age、以及同一时间窗口内的 Kubernetes rollout/kill 事件。若 Pod 在 trace 开始前已经稳定且 `RESTARTS=0`，应归类为 Codex app-server transport/session 失败，提示用户用新 session 重试；只有 trace 时间窗口内存在当前会话所在 Pod 的删除、重建或 restart 证据时，才归类为滚动导致的中断。失败响应也必须尽量保留 `providerTrace`，即使 `terminalStatus=failed`，避免前端把“providerTrace 缺失”误报成未知降级。 +`Codex app-server transport closed after partial assistant output but before turn/completed` 不能单独判定为 CI/CD 滚动中断。排查必须同时看三类证据：失败 trace 的 `providerTrace`/`runnerTrace`、对应 `hwlab-cloud-api` Pod 的 restart/age、以及同一时间窗口内的 Kubernetes rollout/kill 事件。若 Pod 在 trace 开始前已经稳定且 `RESTARTS=0`，应归类为 Codex app-server transport/session 失败，提示用户显式创建新 session 后重试；只有 trace 时间窗口内存在当前会话所在 Pod 的删除、重建或 restart 证据时，才归类为滚动导致的中断。失败响应也必须尽量保留 `providerTrace`，即使 `terminalStatus=failed`，避免前端把“providerTrace 缺失”误报成未知降级。 cloud-web 同源代理必须把短连接语义原样转发给 cloud-api，至少包括 `Prefer: respond-async`、`X-HWLAB-Short-Connection` 和 `X-Trace-Id`。如果这些 header 在 cloud-web 层被过滤，cloud-api 会把同一个请求当成长同步请求处理，用户入口会表现为 `17666` 卡住或代理超时，而 `17667` 直连 cloud-api 正常。此类问题应先比对同一 trace 在 `17666` 与 `17667` 的 submit 行为，再修代理 header 透传，而不是调大前端等待时间。 diff --git a/docs/reference/spec-v02-hwlab-cli.md b/docs/reference/spec-v02-hwlab-cli.md index da9bee20..d52bf5dc 100644 --- a/docs/reference/spec-v02-hwlab-cli.md +++ b/docs/reference/spec-v02-hwlab-cli.md @@ -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 已失败或 stale，CLI/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 ` 读取 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 ` 读取 Cloud Web 的 `/v1/agent/chat/inspect`，输出 trace 所属 `conversationId/sessionId/threadId`、session 状态和 `retryOf` 建议；`client agent send --from-trace ` 只能作为显式复现该 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:` 是 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//.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 `，让 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 ` 是运行中引导入口，必须调用 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 --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 session；session 创建或选择是 `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 --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 --message "重试上一条" --provider-profile deepseek --no-wait`，确认 CLI 先访问 `/v1/agent/chat/inspect?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 `，确认 CLI 访问 `/v1/agent/chat/inspect?traceId=` 并输出 trace 所属 `conversationId/sessionId/threadId/retryOf`、session 状态和 redacted continuation。若该 session 为 failed/stale，再运行 `client agent send --from-trace --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 --message "请把最终回复包含 STEER_ACCEPTED 标记"`，最后用 `client agent result ` 和 `client agent trace --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 --message "执行一个会持续运行的任务，等待后续 steer" --provider-profile minimax-m3` 获得运行中 trace；随后运行 `client agent steer --message "请把最终回复包含 STEER_ACCEPTED 标记"`，最后用 `client agent result ` 和 `client agent trace --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。 | diff --git a/docs/reference/spec-v02-hwlab-cloud-api.md b/docs/reference/spec-v02-hwlab-cloud-api.md index 666eacbb..02f8c93d 100644 --- a/docs/reference/spec-v02-hwlab-cloud-api.md +++ b/docs/reference/spec-v02-hwlab-cloud-api.md @@ -14,12 +14,13 @@ - `internal/cloud/server.ts` 负责 HTTP route、REST/RPC bridge、health、live-builds、device-pod authority、gateway poll/result 和 Code Agent chat。 - `internal/cloud/access-control.ts` 负责 `/auth/*`、admin/user、device pod profile/grant、device job lifecycle 和 Code Agent owner binding。 - `internal/cloud/access-control.ts` 也是账号 workspace authority：`account_workspaces` 记录同一账号的 Workbench 当前 workspace、selected conversation/session、active trace、provider profile 和 revision。 +- Code Agent session 生命周期必须显式化。Cloud API 目标入口为 `POST /v1/agent/sessions` 创建 session、`GET/PATCH /v1/agent/sessions*` 查询/选择/标记状态；`POST /v1/agent/chat` 只接受显式传入或账号 workspace 中已显式选中的 usable session。没有 session 时返回 `session_required`，session failed/stale/canceled 时返回 `session_not_usable`，不得自动创建、滚动或替换 session。 - `internal/db/runtime-store.ts` 和 `internal/cloud/db-contract.ts` 负责 Postgres runtime store 与 readiness 分层。 - `internal/cloud/code-agent-*.ts` 负责 Codex stdio session、trace store、result cache、provider profile 和取消/轮询。 - AgentRun v0.1 接入只使用标准 `threadId` 路径：`POST /v1/agent/chat` 收到的 `conversationId/sessionId/threadId` 必须写入 AgentRun command `payload.threadId` 和 `SessionRef.threadId`；协议字段、trace、result 和 conversation facts 都以该字段为唯一 thread identity。 - AgentRun run 级 events 写回 HWLAB trace 时必须按当前 `commandId` 归属过滤；同一 run 的旧 command 尾部事件不能混入后续 command trace。取消、失败或 blocked 轮次如果已有 assistant/tool 可读进展，必须以脱敏、限长的 conversation facts 写入 UI/trace/inspect 证据，供后续 `inspect`/`--from-trace` 可见性使用；这些 facts 不得作为下一轮模型上下文或 prompt 拼接来源。 -- AgentRun completed 轮次续接必须依赖 Codex stdio 原生 session continuation。Cloud API 只把本轮原始 `message/prompt` 和标准 `conversationId/sessionId/threadId` 写入 AgentRun command payload 与 `SessionRef`；不得从请求、account workspace 或 account conversation 生成 `conversationContext`，不得把历史消息拼入 prompt，也不得把请求体里的 `conversationContext/messages` 当作模型上下文。历史 conversation facts 只用于 UI、inspect、trace 和 `--from-trace` 的可见性证据；收到 synthetic context 字段时只能记录 ignored trace 并剥离。`thread/resume` 失败时按 AgentRun `thread-resume-failed` 终止本轮。 -- Code Agent 不允许存在 turn/session/conversation 总时长 timeout；只允许无新 app-server 响应、无 notification、无 assistant/tool/event activity 的 idle timeout。AgentRun command 失败、provider 失败或 idle timeout 只终结当前 command，不能把同一 conversation/session/thread 的后续 turn 截断；除显式取消、中断、过期或 thread-resume-failed stale 指针清理外，后续消息必须继续使用原 session/thread。 +- AgentRun completed 轮次续接必须依赖 Codex stdio 原生 session continuation。Cloud API 只把本轮原始 `message/prompt` 和显式 session 的标准 `conversationId/sessionId/threadId` 写入 AgentRun command payload 与 `SessionRef`；不得从请求、account workspace 或 account conversation 生成 `conversationContext`，不得把历史消息拼入 prompt，也不得把请求体里的 `conversationContext/messages` 当作模型上下文。历史 conversation facts 只用于 UI、inspect、trace 和 `--from-trace` 的可见性证据；收到 synthetic context 字段时只能记录 ignored trace 并剥离。`thread/resume` 失败时按 AgentRun `thread-resume-failed` 终止本轮并标记当前 session failed/stale，不自动创建新 session。 +- Code Agent 不允许存在 turn/session/conversation 总时长 timeout；只允许无新 app-server 响应、无 notification、无 assistant/tool/event activity 的 idle timeout。AgentRun command 失败、provider 失败或 idle timeout 只终结当前 command，并按 session policy 标记当前 session 状态；系统不得自动滚动到新 session。后续消息要么继续同一个 usable session/thread，要么由用户显式创建或选择另一个 session。 - Cloud API 通过 AgentRun v0.1 `runner-jobs.transientEnv` 传递本次 Code Agent turn 的短期上下文，例如 `HWLAB_RUNTIME_*`、`HWLAB_CODE_AGENT_ASSEMBLED_RUNTIME` 和 `HWLAB_DEVICE_POD_API_KEY`。`transientEnv` 不设固定 8 项上限，新增短期上下文时必须按 name 去重、只传本次 Job 需要的 value；`HWLAB_RUNTIME_API_URL` 必须指向当前 namespace 内的 `hwlab-cloud-api` Service，`HWLAB_RUNTIME_WEB_URL` 才指向 `hwlab-cloud-web`；`HWLAB_DEVICE_POD_API_KEY` 只能作为 assembled runner 内 `hwpod` 访问正式 device-pod 的统一授权，必须标记 sensitive，并继续禁止承载 GitHub token、provider key、长期 SSH key 或其他可复用 credential；文档、日志和 trace 只允许保留脱敏后的 name、来源或摘要，不打印 Secret 值。 - 同 Pod sidecar `hwlab-codex-api-forwarder` 监听 `127.0.0.1:49280/responses`，用于 `codex-api` profile 直连 hyueapi，并保持 hyueapi 在 `NO_PROXY` 中。 - `hwlab-code-agent-workspace` PVC 挂载到 `/workspace/hwlab`，用于长会话 workspace；它是 cloud-api 运行资源，不是独立用户入口。 @@ -38,11 +39,12 @@ | `GET /v1/auth/session`、`GET /v1/users/me`、`GET /v1/access/status`、`GET /v1/setup/status` | v0.2 用户/session/setup 的 REST 状态和兼容入口；响应不得暴露 password hash、session token 原文或 Secret 值。 | | `POST /v1/admin/users`、`POST/PUT /v1/admin/device-pods`、`POST/DELETE /v1/admin/device-pod-grants...` | `admin` 管理用户、device pod profile 和 grant 的入口。 | | `GET/PATCH /v1/workbench/workspace`、`POST /v1/workbench/workspace/{id}/reset`、`GET /events` | 账号级共享 workspace authority；所有读写按 ownerUserId 隔离，写入使用 revision 观测冲突，active trace 只表示最近活动/当前选中 trace，不作为同账号 Code Agent 并发互斥锁。 | +| `POST /v1/agent/sessions`、`GET/PATCH /v1/agent/sessions...` | 显式 Code Agent session 生命周期入口；创建/选择/状态标记 session，并与账号 workspace selection 同步。 | | `GET /v1/m3/status`、`POST /v1/m3/io` | M3 只读/受控 IO 入口；写操作必须有明确 approval。 | | `GET /v1/diagnostics/gate`、`GET /v1/live-builds` | 诊断和 live build inventory。 | | `GET /v1/gateway/sessions`、`POST /v1/gateway/poll`、`POST /v1/gateway/result` | gateway 主动出站注册、取任务和回传结果。 | | `POST /v1/internal/device-pod/gateway-dispatch` | 仅接受 `hwlab-device-pod` 内部服务凭据，用于把 executor job dispatch 到 gateway poll/result；普通用户和 Code Agent 不可调用。 | -| `POST /v1/agent/chat`、`POST /v1/agent/chat/steer`、`GET /v1/agent/chat/result/{traceId}`、`GET /v1/agent/chat/trace/{traceId}`、`POST /v1/agent/chat/cancel` | Code Agent 短连接提交、运行中 steer、轮询、trace 和取消。 | +| `POST /v1/agent/chat`、`POST /v1/agent/chat/steer`、`GET /v1/agent/chat/result/{traceId}`、`GET /v1/agent/chat/trace/{traceId}`、`POST /v1/agent/chat/cancel` | Code Agent 短连接提交、运行中 steer、轮询、trace 和取消；普通 chat 必须绑定显式 usable session。 | 用户、权限、device-pod 管理 API 的最终规格见 [spec-user-access.md](spec-user-access.md) 和 [spec-device-pod.md](spec-device-pod.md)。 @@ -54,15 +56,15 @@ ## T2 -阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：使用短连接 `POST /v1/agent/chat` 提交一次对话，再轮询 `/v1/agent/chat/result/{traceId}`，只有 `status=completed` 且 assistant reply 非空才算 Code Agent 通过；对运行中请求使用 `POST /v1/agent/chat/steer` 时，响应必须包含 target trace、steerTraceId、AgentRun runId/targetCommandId/steerCommandId 和继续观察原 trace 的 result/trace URL。 +阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：先显式创建 Code Agent session，再使用短连接 `POST /v1/agent/chat` 绑定该 session 提交一次对话，并轮询 `/v1/agent/chat/result/{traceId}`；只有 `status=completed` 且 assistant reply 非空才算 Code Agent 通过。未绑定 session 的普通 chat 必须返回 `session_required`。对运行中请求使用 `POST /v1/agent/chat/steer` 时，响应必须包含 target trace、steerTraceId、AgentRun runId/targetCommandId/steerCommandId 和继续观察原 trace 的 result/trace URL。 ## T2.1 -阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：在同一 `conversationId/sessionId/threadId` 中先发起一轮会产生可见 assistant/tool 进展的 Code Agent 请求并取消，再发送“回答一下刚才调查结果”这类后续消息；第二轮必须继续使用同一个标准 `threadId`，且 trace/result 不能混入上一 command 的尾部事件。 +阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：在同一个显式 `conversationId/sessionId/threadId` 中先发起一轮会产生可见 assistant/tool 进展的 Code Agent 请求并取消，再发送“回答一下刚才调查结果”这类后续消息；如果 session 仍 usable，第二轮必须继续使用同一个标准 `threadId`，且 trace/result 不能混入上一 command 的尾部事件。如果取消导致 session failed/stale，API 必须拒绝继续并要求显式创建新 session，不能自动滚动。 ## T2.2 -阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：在同一 `conversationId/sessionId/threadId` 中先完成一轮“看看 device-pod 可用性？”这类 Code Agent 请求，再发送“总结我们刚才的对话内容”；第二轮 AgentRun command 必须只包含本轮原始 message/prompt、同一个标准 threadId 和必要运行元数据，不得包含 `conversationContext/messages` 或历史 prompt 拼接。assistant reply 必须通过 Codex stdio 原生 `thread/resume` 记住第一轮，不能回答“这是本会话第一条消息”或等价的新会话结论；若 `thread/resume` 失败，应以 `thread-resume-failed` 终止。 +阅读 docs/reference/spec-v02-hwlab-cloud-api.md，然后用 cli 手动测试以下内容：在同一个显式 `conversationId/sessionId/threadId` 中先完成一轮“看看 device-pod 可用性？”这类 Code Agent 请求，再发送“总结我们刚才的对话内容”；第二轮 AgentRun command 必须只包含本轮原始 message/prompt、同一个标准 threadId 和必要运行元数据，不得包含 `conversationContext/messages` 或历史 prompt 拼接。assistant reply 必须通过 Codex stdio 原生 `thread/resume` 记住第一轮，不能回答“这是本会话第一条消息”或等价的新会话结论；若 `thread/resume` 失败，应以 `thread-resume-failed` 终止并标记 session failed/stale，继续前必须显式创建新 session。 ## T3 @@ -74,6 +76,7 @@ | --- | --- | --- | | health/readiness | 已实现 | `/health/live` 汇总 DB、runtime、Code Agent 和 blocker。 | | Code Agent 短连接 submit/steer/result/trace/cancel | 已实现 | repo-owned Codex stdio、运行中 steer 和 provider profile 已接入。 | +| 显式 Code Agent session 生命周期 | 目标状态 | `/v1/agent/sessions*` 管理 session create/select/status；`/v1/agent/chat` 无 session 时返回 `session_required`，失败 session 不自动滚动。 | | Postgres durable runtime | 已实现 | 通过 v02 独立 DB SecretRef 和 migration ledger 判定。 | | gateway outbound poll/result | 已实现 | 支持 gateway 主动轮询和 `hardware.invoke.shell` 分发。 | | device-pod 正式权限/profile/job | 部分实现 | profile/grant/list/status/job 持久化在 cloud-api；用户态 probe GET 已收敛为只读 job；已提供内部 gateway dispatch route 供 `hwlab-device-pod` executor 下发到 device-host-cli，无在线 gateway/device-host-cli 时返回 blocker。 | diff --git a/docs/reference/spec-v02-hwlab-cloud-web.md b/docs/reference/spec-v02-hwlab-cloud-web.md index 02edc3e4..84ec51d7 100644 --- a/docs/reference/spec-v02-hwlab-cloud-web.md +++ b/docs/reference/spec-v02-hwlab-cloud-web.md @@ -10,13 +10,14 @@ - Cloud Web 与 `hwlab-cli client` 必须共享同一组非视觉业务 API。浏览器遇到的 Code Agent continuation、trace/result、device-pod list/status 和 device-pod job 问题，必须能通过 `hwlab-cli client` 走同一 `19666` Cloud Web path 复现；不能让 CLI 长期绕到 `19667` Cloud API 后把 Web 路径缺口误判为业务已通过。 - Cloud Web 只承担浏览器 UI 和 `hwlab-cli client` 的同源代理。AgentRun runner 内的 `hwpod` 不走 Cloud Web；Cloud Web 不转发 AgentRun Device Pod API key，也不保留 device-pod lease 路由。 - 浏览器启动后必须从 `GET /v1/workbench/workspace` hydrate 账号 workspace；同一个账号在多个浏览器标签页、多个浏览器或 CLI profile 中应看到同一个 `workspaceId`、selected conversation/session/thread、provider profile 和 active trace。浏览器 localStorage 只能作为短期缓存，并必须绑定 actor，不能作为 workspace authority。 +- Code Agent session 管理必须全部手动化。Workbench 可以从账号 workspace 恢复“已显式选中”的 session，但不能在普通发送、页面刷新、trace replay、失败恢复或 provider resume 失败时自动创建、滚动或替换 session。没有已选 session 时，composer 必须展示“新建 session/选择 session”的显式动作；session failed/stale/canceled 后必须保留失败证据，继续前由用户显式新建或选择另一个 session。 - Cloud Web trace 展示与 `hwlab-cli client agent trace --render web` 必须共享同一套 trace row 纯转换路径。Web 发生 row 顺序错乱、final response 缺失、assistant 消息被吞、tool call 只显示泛化占位或噪声事件淹没时，先用 CLI 输出同一渲染 row 摘要和 noise event count 复现；CLI 可复现说明是 trace row 转换问题，CLI 不可复现再进入 DOM/CSS/滚动状态调查。默认展示应压制 AgentRun backend echo、token/rate-limit/status/terminal echo 等低价值事件，但原始 trace JSON 仍必须保留用于 `--full`/下载排障。 -- Cloud Web Code Agent composer 必须无锁：运行中 turn 不得把输入框或发送按钮 disabled。浏览器提交时必须按共享 composer policy 自动分流，空闲/终态走 `POST /v1/agent/chat` 开新 turn，存在 active running trace 时走 `POST /v1/agent/chat/steer` 引导当前 turn。`hwlab-cli client agent composer status` 必须能用同一 policy 输出 `locked=false`、`disabled=false`、`submitMode=turn|steer`、`route` 和 `targetTraceId`，用于复现 Web 输入框是否被旧逻辑锁住。 +- Cloud Web Code Agent composer 必须无锁：运行中 turn 不得把输入框或发送按钮 disabled。浏览器提交时必须基于已显式选中的 session 工作；没有 session 时返回 `session_required` 并引导用户新建 session，不能自动开 session。存在 active running trace 时，用户显式 steer 动作走 `POST /v1/agent/chat/steer`；空闲且 session usable 时，用户显式发送 turn 走 `POST /v1/agent/chat`。`hwlab-cli client agent composer status` 必须能用同一 policy 输出 `sessionRequired`、`sessionUsable`、`submitMode=turn|steer`、`route` 和 `targetTraceId`。 - Code Agent result `completed` 只有在同时包含真实 provider/model/trace/conversation 元数据、`providerTrace` 和可展示的 final assistant response 时，才能被 Web 标记为真实完成；`provider=agentrun-v01` 只是执行基础设施标识，不得替代上游 provider/model，也不得把 SOURCE、fixture、echo、mock 或 stub 当成 DEV-LIVE 完成。 -- 同一 conversation/session 的后续用户消息必须在 AgentRun runner reuse window 有效时复用已存在的 AgentRun run/runner 继续新 command/turn；只有 runner 不可用、已过期或协议明确要求新 runner 时才重新 bundle 和启动 runner。每条消息都重新 bundle/runner 属于 v0.2 AgentRun 接入缺口，不能只靠 trace 显示原因当成已完成。 +- 同一显式 conversation/session 的后续用户消息必须在 AgentRun runner reuse window 有效时复用已存在的 AgentRun run/runner 继续新 command/turn；只有 runner 不可用、已过期或用户显式创建新 session 时才重新 bundle 和启动 runner。每条消息都重新 bundle/runner 属于 v0.2 AgentRun 接入缺口，不能只靠 trace 显示原因当成已完成。 - AgentRun 会话连续性只有一个标准路径：Cloud Web/CLI 提交的 `threadId` 必须经 Cloud API adapter 写入 AgentRun command `payload.threadId` 和 `SessionRef.threadId`。前端、CLI、API 和 AgentRun 的协议字段、trace、result 和 conversation facts 都以该字段为唯一 thread identity。 - Cloud Web 提交 Code Agent turn 时只发送当前用户消息、共享 workspace 的 `conversationId/sessionId/threadId`、workspace revision 和必要运行元数据；不得发送 `conversationContext/messages`，也不得把浏览器历史拼入 prompt。历史消息只用于本地 UI 展示和 trace/inspect 可见性，不能替代 AgentRun/Codex stdio 原生 `thread/resume`。 -- Workbench 不允许把 Code Agent 长任务总耗时当成失败条件；只能在无新 trace/event/activity 的 idle timeout 后显示超时。AgentRun command/provider/backend 失败后，当前消息可显示 failed/blocker，但 conversation/session/thread 仍是后续 turn 的默认 continuation，不能要求用户重新建 session；显式取消、中断、过期和 thread-resume-failed stale 指针清理除外。 +- Workbench 不允许把 Code Agent 长任务总耗时当成失败条件；只能在无新 trace/event/activity 的 idle timeout 后显示超时。AgentRun command/provider/backend 失败后，当前消息可显示 failed/blocker；session 是否仍 usable 必须由 session 状态显式表达。`thread-resume-failed`、provider continuation 失效、运行面中断或用户取消导致 session failed/stale/canceled 时，不得自动清理并滚动到新 session；继续前必须由用户显式创建或选择 session。 - 同一 AgentRun run 复用多条 command 时，Web trace 展示只显示当前 command 归属事件和必要 run 级状态；旧 command 的 assistant/tool/terminal 尾部不能堆到新 command 末尾。取消轮次的可读进展必须作为脱敏 conversation facts 进入 UI/trace/inspect 证据，而不是靠旧 trace 尾部串线让后续轮次“碰巧看到”；这些 facts 不得作为下一轮模型上下文或 prompt 拼接来源。 ## 内部架构 @@ -35,6 +36,7 @@ | `GET /help` | 返回可用 route 摘要。 | | `GET /v1`、`GET /v1/...` | 同源代理到 `hwlab-cloud-api`；公开的 Code Agent result/trace 轮询按 route policy 处理。 | | `GET/PATCH /v1/workbench/workspace...` | 同源代理到 cloud-api 的账号 workspace authority，用于 Web/CLI 共享工作区和 revision 冲突保护。 | +| `POST/GET/PATCH /v1/agent/sessions...` | 同源代理到 cloud-api 的显式 Code Agent session 生命周期入口；Web 不在普通 send 中隐式创建 session。 | | `POST /v1/agent/chat`、`POST /v1/agent/chat/steer`、`POST /v1/agent/chat/cancel` | 同源代理到 cloud-api 的 Code Agent 入口；steer 必须走同一个 `19666` Web path，由 cloud-api/AgentRun 判断目标 turn 是否可接收。 | | `POST /v1/device-pods/...` | 受控同源代理到 cloud-api 的 Device Pod job/操作入口；只要 Cloud API 已提供对应能力，Cloud Web 不能只代理 list/status 而让 job POST 在 `19666` 返回 404。 | | `POST /v1/m3/io`、`POST /json-rpc` | 同源代理到受控 API；不能绕过 cloud-api 直连硬件服务。 | @@ -55,11 +57,11 @@ Cloud Web check 通过后仍需执行 bundle build 和 dist freshness 校验， ## T2 -阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：从同源 `19666` 提交 Code Agent 短连接请求并轮询 result，确认请求经 cloud-web proxy 到 `hwlab-cloud-api`，且 trace 可回放。 +阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：先通过同源 `19666` 显式创建或选择 Code Agent session，再提交 Code Agent 短连接请求并轮询 result，确认请求经 cloud-web proxy 到 `hwlab-cloud-api`，且 trace 可回放；未创建或选择 session 的普通 send 必须返回 `session_required`，不能自动创建 session。 阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：对运行中 Code Agent trace 调用 `hwlab-cli client agent steer --message ...`，确认请求走 Cloud Web 同源 `POST /v1/agent/chat/steer`；Web 层不能返回 `serviceId=hwlab-cloud-web` 的 404，目标不存在、非运行中或 runner 拒绝时必须透传 cloud-api/AgentRun 的结构化业务状态。 -阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：先启动一个真实运行中的 Code Agent turn，再运行 `hwlab-cli client agent composer status`，确认输出 `composer.locked=false`、`composer.disabled=false`、`composer.submitMode=steer`、`composer.route=/v1/agent/chat/steer` 和当前 `targetTraceId`；随后运行 `hwlab-cli client agent composer submit --message ...`，确认 CLI 按 Web composer policy 自动走 steer，而不是手动指定 steer URL 或新开 turn。 +阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：未选择 session 时运行 `hwlab-cli client agent composer status` 必须显示 `sessionRequired=true`；显式创建 session 并启动一个真实运行中的 Code Agent turn 后，再运行 `hwlab-cli client agent composer status`，确认输出当前 `sessionId`、`composer.submitMode=steer`、`composer.route=/v1/agent/chat/steer` 和当前 `targetTraceId`；随后运行 `hwlab-cli client agent composer submit --message ...`，确认 CLI 按 Web composer policy 走 steer，但不自动创建或滚动 session。 ## T2.1 @@ -67,7 +69,7 @@ Cloud Web check 通过后仍需执行 bundle build 和 dist freshness 校验， ## T2.2 -阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：在同一 conversation/session 连续发送两条 Code Agent 消息，确认第二条复用第一条的 AgentRun `runId` 和 runner `jobName`、生成新的 `commandId`，且不重新 materialize bundle/启动新 runner；result completed 必须包含真实 provider/model/`providerTrace`/trace/conversation 和 final assistant response。复用失败原因只能作为诊断，不作为本测试通过条件。 +阅读 docs/reference/spec-v02-hwlab-cloud-web.md，然后用 cli 手动测试以下内容：先显式创建 session，再在同一 conversation/session 连续发送两条 Code Agent 消息，确认第二条复用第一条的 AgentRun `runId` 和 runner `jobName`、生成新的 `commandId`，且不重新 materialize bundle/启动新 runner；result completed 必须包含真实 provider/model/`providerTrace`/trace/conversation 和 final assistant response。复用失败原因只能作为诊断，不作为本测试通过条件；如果 session failed/stale，必须显式创建新 session 再继续。 ## T2.3