# 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 凭证缺失，不能标真实回复通过。 |
| `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
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` 证据分级。