pikasTech-HWLAB/docs/reference/code-agent-chat-readiness.md

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

本地合同检查：

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

该命令验证 Workbench 默认页、同源只读边界和 /v1/agent/chat 前端主流程接线。它只产出 SOURCE 级证据。

授权凭证注入后的真实 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 证据分级。