docs: 固化 Code Agent steer 短连接语义
This commit is contained in:
Codex Agent
@@ -13,6 +13,7 @@
|
||||
## 会话和执行边界
|
||||
|
||||
- HWLAB `conversationId` / `sessionId` / `threadId` 是用户可见业务会话 authority；AgentRun `runId` / `commandId` / `runnerJobId` 是执行尝试 identity；AgentRun `SessionRef` 和 per-session PVC 承载 backend/profile 的续接状态。不要把新建 AgentRun run/job 等同于新建 HWLAB session，也不要把复用 workspace selection 当作 session state。
|
||||
- AgentRun `type=steer` command 是作用在既有 target trace/target command 上的控制命令，不创建新的 HWLAB session，也不改变业务 `conversationId/sessionId/threadId`。HWLAB closeout 和 UI 展示必须同时保留 target command identity 与 `steerCommandId`，并从原 target trace 观察 `agentrun:steer:accepted` / `agentrun:steer:command-created`。steer command 创建成功只证明短连接控制动作已被 AgentRun 接收；目标 turn 后续 terminal 状态按原 command/result 判定。
|
||||
- HWLAB adapter 调 AgentRun 时必须固定使用 AgentRun policy 边界字段：`tenantId=hwlab`、`projectId=pikasTech/HWLAB`、`providerId=G14`。HWLAB Workbench 的 project/workspace 标识只能作为 `metadata.hwlabProjectId`、`metadata.hwlabWorkspaceId` 或 `workspaceRef` 子字段保存，不能写入 AgentRun `projectId`。如果运行面出现 `tenant-policy-denied`、project mismatch 或 workspace project 污染，临时处理是修 adapter 的字段归一化并重放最小真实请求，不放宽 AgentRun tenant policy。
|
||||
- `providerProfile` 由显式 HWLAB session 负责。`client agent session create --provider-profile <profile>` 建立 session 的 provider profile，并映射为 AgentRun `backendProfile`；后续 `client agent send --session-id <sessionId>` 在未显式传 `--provider-profile` 时必须继承该 session 的 `providerProfile`。账号 workspace 的 provider profile 只在 workspace 当前 selected session 与本次目标 session 完全一致时作为 fallback；旧 workspace 状态不得覆盖显式 session。
|
||||
- 同一 HWLAB session 的 resume 判定看同一个 `sessionId`、`threadId`、`providerProfile/backendProfile`、AgentRun `SessionRef` 和 PVC，而不是只看是否复用了同一个 AgentRun `runId` 或 runner Job。runner pod 被删、Job 被重建或 lease 失效后的临时恢复可以创建 replacement run/job，但只有在复用同一 `SessionRef`/PVC/thread、没有拼接历史 prompt 且 assistant 能看到前序上下文时，才算 session 持久化恢复证据；它不替代 runner reuse window 内复用同一 run/runner 的长期目标。
|
||||
|
||||
@@ -85,6 +85,7 @@ Running 轮询可以返回 `202` 和当前 runnerTrace；这只是“尚未 term
|
||||
3. Web 默认显示完整可读事件列表。Result polling 返回的 compacted head-tail runnerTrace 不能冒充完整 trace；发现 `eventsCompacted=true` 时必须继续请求 `/trace/{traceId}`。
|
||||
4. 如果完整 trace 已过期或缺失，UI 必须显式展示 missing/expired，并提供 result/inspect 可用证据；不得用最新 trace 或 session final response 填补历史 trace。
|
||||
5. 同一 run 多 command 时，旧 command 的 assistant/tool/terminal rows 不能挤到新 command 的 final response 或 trace 尾部。取消/失败前的有价值上下文应作为脱敏 conversation facts 或当前 command 自身事件展示，不通过串线实现。
|
||||
6. 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 同路径保证
|
||||
|
||||
@@ -148,6 +149,7 @@ Web、CLI 和 CI 的一致性按“入口同源、API 同 path、renderer 同代
|
||||
- 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 测试，不用旧路径断言保护旧架构。
|
||||
|
||||
|
||||
@@ -50,6 +50,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb
|
||||
- `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，CLI 层应在发出 `/v1/agent/chat` 前返回 `session_required`；需要新 session 时必须先 `client agent session create --conversation-id <ID>`。
|
||||
- 架构混乱排查时，CLI 输出必须把 `sessionId`、`conversationId`、`threadId`、`providerProfile`、`runtimeEndpoint`、`traceId`、`runId`、`commandId` 和 `jobName` 分开显示。临时处理以显式 session status、AgentRun run/job env、`SessionRef` 和 PVC phase 为证据；长期收敛见 [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md) 的会话和执行边界。
|
||||
- `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 steer` 的成功输出必须适合 issue closeout 直接审计：顶层或 compact body 中必须暴露 HTTP 202、`request.elapsedMs`、route、`traceId`、`steerTraceId`、`accepted=true`、`shortConnection=true`、`agentRun.runId`、`agentRun.targetCommandId` 和 `agentRun.steerCommandId`。该命令默认不等待原 trace terminal；后续用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 验证目标 trace 中的 steer events。目标 turn 后续 provider/backend terminal failure 是另一类终态，不能倒推为 steer POST 短请求失败。
|
||||
- `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 中的原因说明只能用于定位。
|
||||
- `client harness`、`client harness-ops` 和 `client harness-opt` 吸收 G14 harness-ops 的短连接业务能力：health、submit、result、trace、wait 和 audit。
|
||||
@@ -92,7 +93,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb
|
||||
| `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。 |
|
||||
| `hwlab-cli client agent steer TRACE` | `POST /v1/agent/chat/steer` | 对目标 trace 的运行中 Code Agent turn 发送 steer 文本；默认短连接返回 HTTP 202、request elapsed、accepted、steerTraceId 和 steer command 摘要，后续观察原 trace 的 result/trace。 |
|
||||
| `hwlab-cli client agent cancel TRACE` | `POST /v1/agent/chat/cancel` | 取消当前 Code Agent 请求。 |
|
||||
| `hwlab-cli client harness submit` | `POST /v1/agent/chat` | G14 harness-ops 的短连接提交入口，默认 provider profile 为 `deepseek`，返回 trace/result URL；`harness-ops` 和 `harness-opt` 是同义别名。 |
|
||||
| `hwlab-cli client harness wait/result/trace` | `GET /v1/agent/chat/result/{trace}`、`GET /trace/{trace}` | 轮询或读取一次 Code Agent 结果和 trace；单次 wait 最长 60 秒。 |
|
||||
@@ -137,7 +138,7 @@ Code Agent session 是显式资源，不再由普通 `client agent send`、Workb
|
||||
|
||||
## T3.3
|
||||
|
||||
阅读 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。
|
||||
阅读 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 标记"`，确认 steer 命令本身短连接返回 HTTP 202、`request.elapsedMs`、`accepted=true`、`shortConnection=true` 和 `agentRun.steerCommandId`；最后用 `client agent result <traceId>` 和 `client agent trace <traceId> --render web` 确认同一 target trace 出现 `agentrun:steer:accepted` 和 `agentrun:steer:command-created`。该验收必须使用 runtime namespace/lane 自动解析出的同源 Web 入口，不能 mock，也不能用自动交互脚本，不能手动传 URL；若目标 turn 后续 provider/backend 失败，必须单独记录为目标 turn 终态，不得记为 steer 短请求失败。
|
||||
|
||||
## T3.4
|
||||
|
||||
|
||||
@@ -20,6 +20,8 @@ Provider API Key 配置入口也归属 Cloud Web：左侧顶级导航必须提
|
||||
- 显式 session 的 `providerProfile` 优先于账号 workspace provider profile。Workbench 可以展示 workspace 默认 provider，但对已选 session 发送 turn 时必须使用该 session 的 provider profile；用户想切换 provider 时，应显式创建或选择对应 provider 的 session，不能把旧 workspace provider 静默套到当前 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。浏览器提交时必须基于已显式选中的 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`。
|
||||
- Steer 是短连接控制动作，不是等待目标 turn terminal 的长请求。`POST /v1/agent/chat/steer` 在 cloud-api 成功创建 AgentRun `type=steer` command 后必须立即以 HTTP 202 返回，并在响应中暴露 `accepted=true`、`shortConnection=true`、`route=/v1/agent/chat/steer`、`traceId`、`steerTraceId`、`agentRun.runId`、`agentRun.targetCommandId` 和 `agentRun.steerCommandId`。接口不得为了 owner/session/workspace/conversation 持久化写回而延迟 202；这些写回失败只能作为后台可观测问题处理，不能把已 accepted 的 steer 重新标成请求失败。
|
||||
- Workbench 对 steer submit 的失败分类必须以目标 trace 的真实状态为准：如果 steer POST 发生 timeout/ECONNRESET/transport failure，但目标 trace/result 仍是 running 或其他非 terminal 状态，前端必须释放本次 submit lock、保留原 agent message 的 running/steerable 状态并继续 trace 轮询，不得把原 turn 改成 failed 或展示“Code Agent 请求失败”。只有目标 trace/result、cloud-api 或 AgentRun 返回 terminal failed/blocker/canceled 时，才把目标消息标为相应终态。
|
||||
- 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 不可用、已过期或用户显式创建新 session 时才重新 bundle 和启动 runner。每条消息都重新 bundle/runner 属于 v0.2 AgentRun 接入缺口，不能只靠 trace 显示原因当成已完成。
|
||||
- runner pod 被删、runner Job 重建或旧 lease 失效后的临时恢复，可以显示新的 AgentRun run/job/command identity，但 Web 必须继续以同一个 HWLAB `sessionId` / `threadId` / provider profile 呈现业务会话，并明确区分“同 session 恢复执行壳”和“新业务 session”。只要复用同一 AgentRun `SessionRef`/PVC/thread 且没有拼接历史 prompt，replacement run/job 可以作为 session 持久化恢复证据；它不替代 T2.2 的同 run/runner reuse 目标。
|
||||
@@ -118,7 +120,7 @@ Provider API Key 配置入口也归属 Cloud Web：左侧顶级导航必须提
|
||||
| `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/agent/chat`、`POST /v1/agent/chat/steer`、`POST /v1/agent/chat/cancel` | 同源代理到 cloud-api 的 Code Agent 入口；steer 必须走同一个 `19666` Web path，由 cloud-api/AgentRun 判断目标 turn 是否可接收，并在 AgentRun steer command 创建后短连接 202 返回。 |
|
||||
| `POST /v1/hwpod-node-ops` | 受控同源代理到 cloud-api 的 HWPOD node-ops 入口；用于 Web/CLI 同路径只读 smoke，Code Agent 正式业务入口仍是 runner 内 `hwpod` 直达 Cloud API。 |
|
||||
| `POST /v1/web-performance` | 浏览器 RUM 上报入口；只允许低基数性能事件和数值，Cloud API 聚合后进入 Prometheus，详见 [spec-v02-observability-monitoring.md](spec-v02-observability-monitoring.md)。 |
|
||||
| `GET /v1/web-performance/summary` | 性能监控顶级页读取的同源摘要接口；返回低基数 WebUI 体感性能 JSON，包含样本数、route p95、Web Vitals、long task 和错误/超时问题队列，不返回 Prometheus 原始文本或高基数 trace/session/conversation/thread/user 标识。 |
|
||||
@@ -160,7 +162,7 @@ Cloud Web check 通过后仍需执行 bundle build 和 dist freshness 校验，
|
||||
|
||||
阅读 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 <traceId> --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 trace 调用 `hwlab-cli client agent steer <traceId> --message ...`，确认请求走 Cloud Web 同源 `POST /v1/agent/chat/steer`；成功路径必须在短请求内返回 HTTP 202、`accepted=true`、`shortConnection=true` 和 `agentRun.steerCommandId`，再通过原 trace 的 `result/trace --render web` 看到 `agentrun:steer:accepted` 与 `agentrun:steer:command-created`。Web 层不能返回 `serviceId=hwlab-cloud-web` 的 404；目标不存在、非运行中或 runner 拒绝时必须透传 cloud-api/AgentRun 的结构化业务状态，不得把仍 running 的原 turn 误标 failed。
|
||||
|
||||
阅读 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。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user