Lyon
a45e1bac91
Host commander merge after read-only review. PR #161 is CLEAN/MERGEABLE and doc-only: AGENTS.md index, docs/reference/README.md index, and docs/reference/code-agent-chat-readiness.md. Runner validation reported npm run validate, npm run docs:validate:m3-rollout, and git diff --check. This preserves the credential/provider blocker boundary and does not claim DEV-LIVE completion.
86 lines
3.9 KiB
Markdown
86 lines
3.9 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。
|
||
|
||
Runner 不得尝试修补、读取、回显或替换该 Secret。若 DEV runtime 缺少该授权凭证注入，
|
||
`provider_unavailable` 且 `error.missingEnv` 包含 `OPENAI_API_KEY` 必须判为
|
||
`BLOCKED/credential`。
|
||
|
||
## 判定标准
|
||
|
||
| 观测结果 | readiness |
|
||
| --- | --- |
|
||
| `status: "failed"`，`error.code: "provider_unavailable"`，且 `error.missingEnv` 包含 `OPENAI_API_KEY` | `BLOCKED/credential`；provider 凭证缺失，不能标真实回复通过。 |
|
||
| `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、静态检查或前端状态当作通过。
|
||
|
||
## 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
|
||
```
|
||
|
||
该命令验证 Workbench 默认页、同源只读边界和 `/v1/agent/chat` 前端主流程接线。它只产出
|
||
`SOURCE` 级证据。
|
||
|
||
授权凭证注入后的真实 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` 证据分级。
|