Merge pull request #162 from pikasTech/docs/workbench-evidence-reference-authority

docs: reconcile workbench evidence reference authority
2026-05-23 00:55:04 +08:00
parent a45e1bac91 0eb711d5d9
commit f64182b54f
4 changed files with 21 additions and 1 deletions
@@ -13,7 +13,7 @@
 | DEV 运行态、端口、k3s、DB DNS 和环境边界 | [dev-runtime-boundary.md](dev-runtime-boundary.md) |
 | 部署正规化、artifact 发布、回滚和 Cloud Web rollout | [deployment-publish.md](deployment-publish.md) |
 | Cloud Workbench 默认界面和 UX 边界 | [cloud-workbench.md](cloud-workbench.md) |
-| Code Agent chat readiness 与真实回复判定 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
+| Code Agent chat 同源通道 readiness 与真实回复判定 | [code-agent-chat-readiness.md](code-agent-chat-readiness.md) |
 | 指挥官/runner 协作、PR 和 prompt handoff | [commander-collaboration.md](commander-collaboration.md) |
 | M3 闭环 rollout runbook | [m3-loop-rollout-runbook.md](m3-loop-rollout-runbook.md) |
 | runner GitHub 可见性与 prompt handoff | [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md) |
@@ -25,6 +25,7 @@
 - [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：issue 和长期文档中文化要求。
 - [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户和参谋反馈默认按高优先级用户反馈处理，并挂到 `#7`。
 - [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 规则必须固化进 HWLAB 长期参考文档。
+- [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131)：指挥作风纠偏、一手事实优先和真实推进规则。
 - [pikasTech/HWLAB#99](https://github.com/pikasTech/HWLAB/issues/99)：Cloud Workbench 默认前端方向。
 - [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108)：禁止外层页面纵向滚动、中文 UI 和内部 Markdown 帮助页。
 - [pikasTech/HWLAB#61](https://github.com/pikasTech/HWLAB/issues/61)：DEV 手动 rollout 复盘，以及走向 CLI 加 `deploy/deploy.json` 自动化的路径。
@@ -68,6 +68,11 @@ support M3 PASS. Edge health, Cloud Workbench polish, artifact reports, and
 desired-state plans are support signals until joined with the required loop
 evidence.

+Code Agent chat 证据单独分级：只有真实同源 `/v1/agent/chat`
+`completed` 响应可以证明 chat reply readiness；provider credential gap
+必须保持 `BLOCKED`。它不能升级为 M3、M4、M5 或硬件闭环验收，判定细则见
+[code-agent-chat-readiness.md](code-agent-chat-readiness.md)。
+
 ## Stable Sources

 - [pikasTech/HWLAB#7](https://github.com/pikasTech/HWLAB/issues/7): current
@@ -17,6 +17,10 @@ Cloud Workbench is the default user-facing frontend at
 - `http://74.48.78.17:16667/` remains the API/edge boundary.
 - Browser data sources are same-origin `/v1`, read-only `/json-rpc`, source
  reports, gate reports, and blocked reports.
+- Code Agent conversation 使用受控同源 `POST /v1/agent/chat` 通道。直接
+  API/edge 访问、source reports、本地 echo、mock replies 或 provider
+  credential gaps 不能被写成真实 assistant reply；readiness 权威文档是
+  [code-agent-chat-readiness.md](code-agent-chat-readiness.md).

 ## Required Layout

@@ -57,6 +61,11 @@ The frontend may show read-only DEV observations when they are tied to the
 exact route or component. It must not upgrade source fixtures, dry-run output,
 front-end state, or edge-only health into M3 DEV-LIVE.

+如果 `/v1/agent/chat` 返回 `provider_unavailable` 或报告缺少
+`OPENAI_API_KEY`，可见状态必须保持 `BLOCKED/credential`。在同源 DEV 请求按
+[Code Agent readiness](code-agent-chat-readiness.md) 合同返回 completed
+且非空的 assistant response 前，Workbench 不得暗示已有真实 assistant reply。
+
 ## Lightweight Checks

 Use the existing lightweight checks unless a task explicitly authorizes a
@@ -83,6 +92,8 @@ available.
  Cloud Workbench direction.
 - [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108): no
  outer scroll, Chinese UI, internal Markdown help.
+- [code-agent-chat-readiness.md](code-agent-chat-readiness.md): Code Agent
+  chat 同源 readiness 和 provider credential blocker 边界。
 - [docs/cloud-web-workbench.md](../cloud-web-workbench.md): detailed frontend
  contract.
 - [docs/dev-deploy-apply.md](../dev-deploy-apply.md): Cloud Web manual rollout
@@ -63,6 +63,8 @@ node scripts/runner-issue-visibility-preflight.mjs
 - 把 Gate 或 diagnostics 放回 Cloud Web 默认首页；
 - 继续使用历史公网 `:6666` 或 `:6667` 作为当前 DEV 入口；
 - 把 runner kubeconfig 缺失、runner 观测 gap 或瞬时网络问题直接写成 D601/k3s 不可用；
+- 把 `/v1/agent/chat` 的 `provider_unavailable`、`OPENAI_API_KEY` 缺失或
+  本地/mock 回显写成真实 assistant reply；
 - 用报告完成、Gate 通过、预检通过替代用户可见上线、真实 DEV 运行态变化或 M3 blocker 解除。

 ## 稳定来源
@@ -75,4 +77,5 @@ node scripts/runner-issue-visibility-preflight.mjs
 - [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)：中文化要求。
 - [pikasTech/HWLAB#122](https://github.com/pikasTech/HWLAB/issues/122)：用户反馈优先级要求。
 - [pikasTech/HWLAB#123](https://github.com/pikasTech/HWLAB/issues/123)：docs-spec 入库要求。
+- [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent chat 真实回复和 provider blocker 判定。
 - [runner-issue-visibility-handoff.md](runner-issue-visibility-handoff.md)：runner 可见性和 prompt handoff 详细规则。