From 262fbd90ff7ef8b68d9dc8a89f23f944860c06ab Mon Sep 17 00:00:00 2001
From: xiaohei <xiaohei@heicode.local>
Date: Mon, 1 Jun 2026 13:59:31 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20add=20=E9=9C=80=E8=A6=81=E7=BB=9F?=
 =?UTF-8?q?=E4=B8=80=E5=AE=9A=E4=B9=89=E7=9A=84=E6=A0=87=E5=87=86=E6=B8=85?=
 =?UTF-8?q?=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

梳理 8 个需统一权威定义的标准（完成判定/状态机/交付物/结构化契约/事件契约/安全治理/模型清单/编排术语），
含现状散落点、要钉死内容、唯一裁判方、优先级与依赖关系。
---
 需要统一定义的标准清单.md | 119 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 119 insertions(+)
 create mode 100644 需要统一定义的标准清单.md

diff --git a/需要统一定义的标准清单.md b/需要统一定义的标准清单.md
new file mode 100644
index 0000000..2789791
--- /dev/null
+++ b/需要统一定义的标准清单.md
@@ -0,0 +1,119 @@
+# Heicode 需要统一定义的标准清单
+
+> 日期：2026-06-01
+> 关联：见本仓库《Heicode 全链路代码评审报告》（README.md）
+> 背景：评审发现的统一根因——关键业务概念没有单一权威定义，而是在 Runtime / Manager / 客户端 / 文档 里各写一份，再靠下游正则和文档补丁去对齐。本清单列出需要"定一份、各方引用"的标准。
+
+---
+
+## 总原则
+
+> **每个关键概念定唯一权威定义 + 唯一裁判方；由 Runtime 输出"结构化真相"，Manager 据结构化字段裁决，客户端只消费结论。删掉客户端 / Manager 各自的本地正则与各写一份的枚举。**
+
+共 8 个标准，按优先级分三档。
+
+---
+
+## 🔴 地基级（必须先定）
+
+### 1. 任务完成判定标准（Completion Contract）
+
+| 项 | 内容 |
+|---|---|
+| 现状散落 | `HeiCode-Swarm/agent/task_executor.py:141`（模型自报 status 即成功）、`orchestrator/main.py:519`（无条件发 completed）、`heicode-mananger/heicode/controller/agnet_callback.go:304`（Manager 镜像 completed） |
+| 要钉死 | `completed` 的**充要条件**：代码类任务必须有结构化产出（`files_modified` 非空 / 有 diff / 有 commit）；否则进入非成功终态 |
+| 唯一裁判 | Manager（据 Runtime 上报的结构化字段判定，不靠文本） |
+
+### 2. 状态枚举与状态机（Status Enum / State Machine）
+
+| 项 | 内容 |
+|---|---|
+| 现状散落 | 文档枚举 `heicode-desktop-sub-agile-api.md:1399`（**没有 `completed`**）vs 代码实际写 `completed`（`agnet_callback.go:307`） |
+| 要钉死 | `deployment.status` / `runtime_state` / `task.status` 三套枚举完整合法值（含 `completed` 与新增 `completed_without_deliverable` / `needs_codegen`）+ 状态转移图；文档 / Go / 客户端三处对齐 |
+| 唯一裁判 | 一份枚举定义被三方 import / 引用 |
+
+### 3. 交付物分类与有效性标准（Artifact Taxonomy）
+
+| 项 | 内容 |
+|---|---|
+| 现状散落 | Runtime 硬编码类型 `orchestrator/main.py:480,494`；Manager 自由字符串无校验 + uri 正则 `agnet_runtime_client.go:670`；客户端另一套中文正则 `heicode-desktop-sub-agile-api.md:300` |
+| 要钉死 | `artifact_type` 规范枚举；"是否算代码交付物"**只依据结构化字段**判定，不再 re-parse 文本 |
+| 唯一裁判 | Manager；删客户端 `classifyArtifact` 与 Manager `runtimeArtifactsAreSummaryOnly` 两套正则 |
+
+---
+
+## 🟠 与地基配套
+
+### 4. 结构化产出契约（Runtime → Manager 结构化真相 Schema）
+
+| 项 | 内容 |
+|---|---|
+| 说明 | 支撑标准 1、3 的载体 |
+| 现状 | `files_modified` / `git_skipped` / `artifact_type` 只塞在 artifact metadata 里，**无人据此否决 completed** |
+| 要钉死 | Runtime 每次完成必须上报的结构化字段集：`files_modified[]`、`has_diff`、`commit_sha`、`deliverable: code\|document\|summary_only`、`tokens_used` 等；Manager 据此裁决 |
+
+### 5. 回调事件契约（Callback Event Schema）
+
+| 项 | 内容 |
+|---|---|
+| 现状 | 事件类型/必填字段已部分定义 `agnet_callback.go:463`，但与 ASCE §12.1 必采事件、§12.2 必采字段未完全对齐 |
+| 要钉死 | 事件类型全集（task.* / handoff.* / approval.* / resource.accessed / secret.lease.created / usage.recorded / artifact.created）+ 每类必填字段 + trace 完整性要求（保证可回放） |
+
+### 6. 安全治理标准（Security & Governance）— 一组小标准
+
+| 子标准 | 现状 | 要钉死 |
+|---|---|---|
+| `secret_ref` 格式 | Agnet 入口已强制 `azkv://`，但 Resource CRUD 未校验（`resource.go:449`） | 所有写入口统一强制 |
+| 明文密钥定义与扫描 | 仅按字段名拦截（`resource.go:33`） | 补值级模式（JWT/`sk-`/`ghp_` 等）+ 统一扫描覆盖面（含 metadata / 数组 / secret_ref 列） |
+| 高危操作清单 + 审批 gate | Manager 不阻断（`agnet_control_plane.go:1071`） | 钉死高危操作清单 + "未批准必须阻断执行"在 Manager 还是 Runtime 强制 |
+| 凭证 lease 与撤销 | lease 为 `lease://` 占位（`agnet_approval.go:213`），revoke 不通知 Runtime（`agnet_approval.go:339`） | lease 是真凭证还是引用；撤销是否同步 Runtime 立即失效 |
+| permission manifest 语义 | 仅生成下发，无运行时校验（`agnet_control_plane.go:870`） | "给模型看" vs "系统强制"，运行时校验点在哪 |
+| 审计字段 | best-effort 非 fail-closed（`agnet_audit.go:59`） | 统一 who/agent/resource/action/time/approval/result，是否 fail-closed |
+
+---
+
+## 🟡 独立可并行
+
+### 7. 模型清单标准（Model Registry）
+
+| 项 | 内容 |
+|---|---|
+| 现状散落（四套口径） | 代码 `claude-sonnet-4-6`（`agnet_role_template.go:49`）；文档示例 `agnet-model-backend`（占位名）；文档明令禁用占位名（`:48`）；生产实际仅 `gpt-5.4`（`:15`） |
+| 要钉死 | 默认 / 允许模型的**单一可信来源**，对齐生产 NewAPI，清占位名 |
+
+### 8. 编排权威与术语标准（Orchestration Authority & Naming）— 产品决策，单独立项
+
+| 项 | 内容 |
+|---|---|
+| 现状散落 | 客户端本地 swarm、云端蜂群、Swarm 自带 `/tasks` 旁路三套，同名不同义 |
+| 要钉死 | 每种模式唯一编排权威（交互式=本地 / 无人值守·计费·审计=云端经 Manager）；术语单义（云端保留 swarm，本地改名 local-team）；废弃旁路入口 |
+
+---
+
+## 优先级与落地顺序
+
+| 顺序 | 标准 | 说明 |
+|---|---|---|
+| 1 | 标准 1 + 2 + 4 | 完成判定 + 状态机 + 结构化契约，是其余一切的地基 |
+| 2 | 标准 3 + 6 | 交付物裁判 + 安全治理，责任上移到 Manager |
+| 3 | 标准 5 | 跟随 1/4 把事件 schema 补齐、对齐 ASCE |
+| 4 | 标准 7 | 随手清理，低风险 |
+| 5 | 标准 8 | 独立产品决策推进，不与上面混做 |
+
+---
+
+## 标准间依赖关系
+
+```text
+标准4（结构化产出契约）
+   ├── 支撑 → 标准1（完成判定）
+   └── 支撑 → 标准3（交付物分类）
+标准2（状态机）── 定义终态 ── 标准1 引用
+标准5（事件契约）── 承载 ── 标准1/3/6 的过程事件与 trace
+标准6（安全治理）── 依赖 ── 标准5 的 approval / secret.lease / resource.accessed 事件
+标准7、标准8 相对独立
+```
+
+---
+
+*本清单依据全链路只读评审得出，证据可在各仓库 `文件:行` 复核。*