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 时才可作为普通文本备用通道返回。

当前 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

本地合同检查：

node scripts/code-agent-chat-smoke.mjs

该命令验证 schema、provider_unavailable provider gap、OPENAI_API_KEY missing-env 分类，以及本地 stub completion 不能升级为 DEV-LIVE pass。

Workbench 静态接线检查：

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 复测：

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 默认页和同源边界。
docs/reference/dev-runtime-boundary.md：DEV 端口、k3s 与运行态边界。
docs/reference/architecture.md：SOURCE、LOCAL、DRY-RUN、 DEV-LIVE、BLOCKED 证据分级。

7.5 KiB Raw Blame History Unescape Escape