Code Queue Review
137 lines
8.7 KiB
Markdown
137 lines
8.7 KiB
Markdown
# Code Agent Chat Readiness Runbook
|
||
|
||
本文定义 Cloud Workbench `POST /v1/agent/chat` 的 readiness 判定。它只处理
|
||
Code Agent 回复链路是否具备复测条件，不修复、不读取、不打印、不创建也不修改任何
|
||
Secret 或 token。
|
||
|
||
## 运行边界
|
||
|
||
- DEV Cloud Web 入口是 `http://74.48.78.17:16666/`，同源代理到
|
||
`/v1/agent/chat`。
|
||
- DEV API/edge 入口是 `http://74.48.78.17:16667/`；它不能替代 Workbench
|
||
同源聊天入口的真实回复证据。
|
||
- `internal/cloud/code-agent-chat.mjs` 是 `/v1/agent/chat` 的后端处理入口。
|
||
- `scripts/code-agent-chat-smoke.mjs` 是 Code Agent chat schema 与 readiness
|
||
gate。
|
||
- `scripts/dev-cloud-workbench-smoke.mjs --static` 只验证 Workbench 源码合同和
|
||
`/v1/agent/chat` 前端接线；它不是 DEV-LIVE 回复证明。
|
||
|
||
## Provider 前置条件
|
||
|
||
当前 DEV 部署合同中 `hwlab-cloud-api` 的 Code Agent provider 是
|
||
`HWLAB_CODE_AGENT_PROVIDER=codex-stdio`。运行时必须具备 repo-owned Codex MCP
|
||
stdio session supervisor，并证明 `/workspace/hwlab` 可读写、`CODEX_HOME=/codex-home`
|
||
可写、`/app/node_modules/.bin/codex --version` 可执行、`codex mcp-server`
|
||
可通过 MCP initialize/tools/list 观测到 `codex` 与 `codex-reply`。
|
||
|
||
Codex token boundary 仍由授权路径把 `OPENAI_API_KEY` 注入到 DEV runtime。DEV Pod
|
||
必须使用 `HWLAB_CODE_AGENT_OPENAI_BASE_URL` 指向受控 DEV egress/proxy 路径
|
||
`http://172.26.26.227:17680/v1/responses`，不能直接指向 public `api.openai.com`。
|
||
|
||
Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime 缺少该授权凭证注入，
|
||
`provider_unavailable` 且 `error.missingEnv` 包含 `OPENAI_API_KEY` 必须判为
|
||
`BLOCKED/credential`。
|
||
|
||
部署前和部署后的自动化只允许证明 env 名称、`secretKeyRef` 的 Secret 名和 key 名、以及
|
||
DEV egress/base-url 合同是否声明和保留；不得读取 Secret data，也不得把 Secret 值写入
|
||
report、issue、PR 或截图。
|
||
|
||
## 判定标准
|
||
|
||
| 观测结果 | readiness |
|
||
| --- | --- |
|
||
| `status: "failed"`，`error.code: "provider_unavailable"`，且 `error.missingEnv` 包含 `OPENAI_API_KEY` | `BLOCKED/credential`；provider 凭证缺失，不能标真实回复通过。 |
|
||
| `provider: "codex-readonly-runner"` 且 `sessionMode: "controlled-readonly-session-registry"`、`capabilityLevel: "read-only-session-tools"`、`session.status` 为 `idle/ready/busy`、`session.idleTimeoutMs` 和 `session.lastTraceId` 存在、`session.longLivedSession: true`、`longLivedSessionGate.status: "blocked"`、`runnerLimitations` 包含 `not-codex-stdio` / `not-write-capable` / `process-local-session-registry` | 可标为 #317 read-only long-lived session registry pass；不能关闭 full Codex stdio/session capability blocker。 |
|
||
| `codexStdioFeasibility.status: "blocked"`，或 blocker 包含 `codex_cli_binary_missing`、`codex_cli_not_executable`、`codex_cli_native_dependency_missing`、`runner_lifecycle_missing`、`stdio_protocol_not_wired`、`workspace_mount_missing`、`workspace_write_boundary_blocked`、`codex_home_missing`、`codex_home_write_blocked`、`provider_token_boundary` | 真实 Codex stdio / 等价 long-lived runner 未具备；必须按 blocker 处理，不能表述为完整 Codex session。 |
|
||
| `status: "completed"`，但来自 mock、fixture、本地 stub、source-only smoke、浏览器本地回显或人工拼接 | 不是 DEV-LIVE reply pass。 |
|
||
| 真实 DEV `POST /v1/agent/chat` 返回 `status: "completed"`，且 `reply.content` 是非空 assistant 回复 | 可标 DEV-LIVE reply pass。 |
|
||
| 传输失败、schema 不完整、HTTP 非预期、`reply.content` 为空或缺失 | `BLOCKED`，按 runtime/schema/transport 分析。 |
|
||
|
||
只有“真实 DEV 路由 + `completed` + 非空 assistant reply”能作为 DEV-LIVE 回复通过依据。
|
||
不得把 mock、fixture、本地 echo、source report、静态检查或前端状态当作通过。
|
||
|
||
## Runner 能力边界
|
||
|
||
`/v1/agent/chat` 可以先落地受控只读能力，但必须诚实区分：
|
||
|
||
- `controlled-readonly-session-registry`：由 cloud-api 进程内 registry 保存
|
||
`conversationId/sessionId` 映射、`status`、workspace、sandbox、`createdAt`、`updatedAt`、
|
||
`idleTimeoutMs`、`lastTraceId`、`turn` 计数与只读工具 trace。它可以覆盖 `pwd`、
|
||
`skills.discover`、`ls`、`rg --files` 和 bounded `cat`，输出必须限长和脱敏。该模式是
|
||
read-only long-lived session，但 `longLivedSessionGate` 必须保持 `blocked`，直到 Codex
|
||
stdio 或等价 full Code Agent 协议通道真实接通。
|
||
- 该模式必须同时标记 `not-codex-stdio`、`not-write-capable`、`process-local-session-registry`。它不是
|
||
Codex stdio / workspace-write session，不提供写文件、任意 shell、硬件写、Secret/kubeconfig/DB URL
|
||
读取，也不证明 M3/M4/M5 trusted green。
|
||
- OpenAI Responses fallback 只能标记为 `openai-responses-fallback` /
|
||
`text-chat-only`，不得满足 Codex runner capability gate。默认路径不得用 fallback
|
||
冒充完整 Code Agent；仅明确允许 fallback 时才可作为普通文本备用通道返回。
|
||
- 已登记 PC gateway `shell.exec` capability 是受控硬件能力例外：当请求能从显式
|
||
`projectId/gatewaySessionId/resourceId/capabilityId` 或唯一 DEV MVP topology 解析时，
|
||
`/v1/agent/chat` 可以选择 `hwlab-hardware-capability` runner，经 cloud-api 进程内
|
||
JSON-RPC helper 调用 `hardware.invoke.shell`。该 helper 必须使用冻结的
|
||
`hwlab-cloud-api` service id 常量，返回 payload 需包含 `toolCalls[]`、`operationId`、
|
||
`dispatchStatus`、`exitCode`、stdout/stderr 摘要、`runnerTrace.eventLabels` 与
|
||
`capabilityLevel`。拓扑缺失、不唯一、gateway offline、session/capability missing、
|
||
dispatch failed 或 JSON-RPC meta/serviceId 无效时必须返回结构化 blocker，不能转入
|
||
Codex stdio 或 OpenAI 文本 fallback 冒充成功。
|
||
- `security.hardware-boundary` 仍然阻断直接 gateway/box-simu/patch-panel URL、`/invoke`、
|
||
`/sync/tick` 和泛化硬件写绕过；受控 `hardware.invoke.shell` capability route 只允许
|
||
已登记、可解析的 cloud-api 调用，不开放任意 shell。JSON-RPC/REST bridge 拒绝未知
|
||
`serviceId` 时，错误原因应可见为 `unknown serviceId ...` 或等价结构化 reason，且不得泄露
|
||
Secret/token。
|
||
|
||
当前 DEV/runtime 若要升级为完整 #275 runner，至少需要 repo-owned 的 Codex CLI/stdio 或等价
|
||
runner 二进制/协议适配、session supervisor 生命周期、workspace mount 与 sandbox 合同、token/Secret
|
||
注入边界、trace/cancel/reap 机制，以及与 cloud-api/workbench 的持久 session 映射。缺任一项时，必须
|
||
在 `codexStdioFeasibility` 中报告 blocker。
|
||
|
||
## Smoke Gate
|
||
|
||
本地合同检查：
|
||
|
||
```sh
|
||
node scripts/code-agent-chat-smoke.mjs
|
||
```
|
||
|
||
该命令验证 schema、`provider_unavailable` provider gap、`OPENAI_API_KEY`
|
||
missing-env 分类，以及本地 stub completion 不能升级为 DEV-LIVE pass。
|
||
|
||
Workbench 静态接线检查：
|
||
|
||
```sh
|
||
node scripts/dev-cloud-workbench-smoke.mjs --static
|
||
node scripts/dev-cloud-workbench-smoke.mjs --dom-only --url http://74.48.78.17:16666/
|
||
```
|
||
|
||
该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出
|
||
`SOURCE` 级证据。`--dom-only` 会保留部署 runtime/web-asset identity preflight，
|
||
但只做真实 DEV DOM/help 只读观察；它不会发送 `/v1/agent/chat`，Code Agent journey
|
||
必须记录为 `not_applicable`，不能冒充真实 DEV-LIVE reply。
|
||
|
||
授权凭证注入后的真实 DEV 复测：
|
||
|
||
```sh
|
||
node scripts/code-agent-chat-smoke.mjs --live --url http://74.48.78.17:16666/
|
||
```
|
||
|
||
`--live` 会向真实 DEV `/v1/agent/chat` 发送一条最小聊天请求。输出只包含
|
||
readiness、provider/model/backend、assistant 回复是否非空和长度、错误分类等摘要；不打印
|
||
assistant 回复正文，不读取或打印任何 Secret 值。
|
||
|
||
## 复测结果解释
|
||
|
||
- 若输出 `readiness.level: "BLOCKED/credential"`，后续动作是由授权路径注入
|
||
`hwlab-code-agent-provider/openai-api-key`，不是由 runner 临时补 Secret。
|
||
- 若输出 `readiness.level: "#143 DEV-LIVE reply pass"`，只说明真实回复链路通过；
|
||
它不自动证明 M3、M4、M5 或硬件闭环通过。
|
||
- 若 `scripts/dev-cloud-workbench-smoke.mjs --static` 通过，而 `--live` 未通过，结论是
|
||
Workbench 接线和源合同通过，但真实 provider readiness 仍 blocked。
|
||
|
||
## 稳定来源
|
||
|
||
- [docs/reference/cloud-workbench.md](cloud-workbench.md)：Cloud Workbench 默认页和同源边界。
|
||
- [docs/reference/dev-runtime-boundary.md](dev-runtime-boundary.md)：DEV 端口、k3s 与运行态边界。
|
||
- [docs/reference/architecture.md](architecture.md)：`SOURCE`、`LOCAL`、`DRY-RUN`、
|
||
`DEV-LIVE`、`BLOCKED` 证据分级。
|