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 |
独立产品决策推进，不与上面混做 |
标准间依赖关系
本清单依据全链路只读评审得出，证据可在各仓库 文件:行 复核。
