Code Queue Review
116 lines
6.5 KiB
Markdown
116 lines
6.5 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 使用 OpenAI
|
||
provider，运行时通过 `OPENAI_API_KEY` 读取 provider 凭证。该环境变量应由授权路径把
|
||
`hwlab-code-agent-provider/openai-api-key` 注入到 DEV runtime。DEV Pod 的 OpenAI
|
||
Responses 请求必须使用 `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-tools"`、`runnerLimitations` 包含 `not-codex-stdio` / `not-write-capable` / `not-durable-session` | 只能标为 read-only session registry partial pass；不能关闭 #275 的 long-lived Codex stdio/session blocker。 |
|
||
| `codexStdioFeasibility.status: "blocked"`，或 blocker 包含 `codex_cli_binary_missing`、`runner_lifecycle_missing`、`stdio_protocol_not_wired`、`workspace_mount_missing`、`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` 映射、`turn` 计数、workspace 与只读工具 trace。它可以覆盖
|
||
`pwd`、`skills.discover`、`ls`、`rg --files` 和 bounded `cat`，输出必须限长和脱敏。
|
||
- 该模式必须同时标记 `not-codex-stdio`、`not-write-capable`、`not-durable-session`。它不是
|
||
long-lived Codex stdio session，不提供写文件、任意 shell、硬件写、Secret/kubeconfig/DB URL
|
||
读取，也不证明 M3/M4/M5 trusted green。
|
||
- OpenAI Responses fallback 只能标记为 `openai-responses-fallback` /
|
||
`text-chat-only`，不得满足 Codex runner capability gate。
|
||
|
||
当前 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` 证据分级。
|