# 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 相对独立
```

---

*本清单依据全链路只读评审得出，证据可在各仓库 `文件:行` 复核。*