From 6f76162126ad443340ed738a3e0fce4c191488b4 Mon Sep 17 00:00:00 2001 From: chenchen Date: Tue, 2 Jun 2026 22:21:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(integration):=20correctness=20is=20judged?= =?UTF-8?q?=20by=20client+user,=20not=20HM=20(fix=20=C2=A76)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HM has no AI and must not compile/test/judge code correctness — that was an overreach. Reframed §6: HM only relays AM execution status + the FACT of whether an artifact exists (anti-empty-shell), never a quality/correctness verdict. The desktop client (Claude-Code-like) pulls the code/git, runs and tests it, and the user reviews — that is where "is it correct/valid/what I wanted" is decided. AM test results are a test_report artifact for the client to read, NOT a signal fed to HM for judging. Co-Authored-By: Claude Opus 4.8 --- .../integration/heicode-sub-mode-flow-spec.md | 43 ++++++++++--------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/integration/heicode-sub-mode-flow-spec.md b/docs/integration/heicode-sub-mode-flow-spec.md index 71b24e96..7823be6a 100644 --- a/docs/integration/heicode-sub-mode-flow-spec.md +++ b/docs/integration/heicode-sub-mode-flow-spec.md @@ -288,8 +288,12 @@ 🟢 已实现。**这是全文最关键的概念之一,三方必须一致理解。** -### 6.1 为什么要"裁决" -**AM（agent_management）只会上报"执行事实"**(它说 `completed` 只代表"我跑完了"),但"跑完了"**不等于"交付成功"**——可能跑完了却没产出真实代码(只产了一段总结/兜底)。**如果直接把 AM 的 `completed` 给用户,会出现"显示成功、实际没东西"的假成功。** 所以由 **HM 做唯一裁判**:综合 AM 的状态 + 实际产物,算出一个**给用户看的最终状态 `display_status`**。**客户端只看 `display_status`,不看 AM 的原始状态。** +### 6.1 HM 只做"事实透传 + 防空壳",**不判断代码对错** +- **AM 只上报执行事实**(`completed` 只代表"我跑完了")。 +- **HM 没 AI、不读代码、不跑代码、不编译、不测试。** 所以 **HM 不判断"代码对不对、有没有效"**——那不是 HM 能做、也不该做的事。 +- HM 的 `display_status` 只做两件事:**① 忠实透传 AM 的执行状态**;**② 防"空壳/兜底假成功"**——AM 说 `completed` 时,HM 顺手核对一下"**到底有没有产物**"(这是**事实层面**的核对:有/无、是不是兜底占位,**不是质量判断**)。 +- **真正"对不对、有没有效"由客户端 + 用户判断**(见 §6.6):客户端是 Claude-Code 式程序,**能把产物/git 拉下来自己跑、自己测、看 diff**,用户 review 拍板。 +- 客户端只看 `display_status` 决定**"这轮跑完了没、是不是空交付"**;**"代码好不好"客户端自己看产物。** ### 6.2 三层状态（`GET .../tasks/{id}/workflow` 同时返回） | 字段 | 含义 | 谁产生 | @@ -333,25 +337,22 @@ ### 6.5 成功判据（客户端用） > **`display_status == "completed"` 且 artifacts 非空 = 真成功**;其余都不是成功(各有不同处理)。 -### 6.6 ⚠️ HM 判断的边界：它"知道"什么、"不知道"什么（三方必读，别误解） +### 6.6 ⚠️ "对不对/有没有效"归谁判 —— **客户端 + 用户,不是 HM**（三方必读） -**HM 没有 AI、不读代码、不跑代码**,所以它对"内容真不真、对不对"的判断**是有边界的**: +| 谁 | 判什么 | 怎么判 | +|---|---|---| +| **HM** | 只判**事实**:这轮跑完没?有没有产物?是不是空壳/兜底? | 看 AM 状态 + artifact 有无（**不读代码、不编译、不测试、不判对错**） | +| **客户端**（Claude-Code 式） | 判**代码对不对、能不能跑、是不是要的** | **把产物/git 拉到本地,自己跑、自己测、看 diff**;有问题就本地改或回云端改 | +| **用户** | **终裁**:满不满意、收不收货 | 在客户端 review 产物,满意才算真完;不满意 → 改/重做（§3.7） | -| HM **能**判断 | HM **判断不了** | -|---|---| -| 有没有 artifact（空/有） | 代码**能不能编译、能不能跑** | -| 是不是 AM 的兜底占位（`metadata.synthesized`） | 代码**逻辑对不对、有没有 bug** | -| 是不是纯总结 / 交付类型 | 是否**满足用户的真实需求** | -| 有没有"改了 N 个文件"的结构信号 | 文件里是不是**有效代码还是垃圾** | +> **直接回答你的问题**: +> - **HM 不需要、也不该编译/测试/判断代码真伪**——那不合理。HM 是网关,没 AI。 +> - **完成后是对是错,客户端当然知道**:它是智能体程序,把代码拉下来一跑一测就清楚,用户也会 review。**这才是判"有效"的地方。** +> - HM 的 `display_status` 顶多帮客户端**省一步**:告诉它"这轮跑完了 / 是不是空交付",**避免把一个空壳当成功**;但**"代码好不好"绝不由 HM 判**。 -> **诚实结论**:当前 `display_status=completed` 只保证 **"AM 真的产出了一个非兜底、非纯总结的交付物"**——**它防的是"假成功/空交付",不是"代码正确性"的担保**。而且当前判断**依赖 AM 老实打标**(`synthesized` / `artifact_type`),理论上**可被糊弄**(标成 code_patch + 给几个文件就算 completed,哪怕代码是错的)。 - -**怎么把"有东西"升级成"真实有效"——分三层,越往下越硬（目标态）:** -1. **🔴 验证信号（最该补）**：AM 在回调里带 **`verification` 块**——`build_passed` / `tests_total` / `tests_passed` / `tests_failed` / `lint_passed`。**HM 把"编译通过 + 测试全过"作为 `completed` 的强条件**;编译失败/测试挂 → 降级为 `needs_codegen`(带原因)。这是"真实有效"最实在的证据。 -2. **🔴 验收对照**：AM 对照需求包 `acceptance_criteria` 逐条自检并回传结果,HM 记录 + 纳入裁决参考。 -3. **🟢 用户终裁**：HM 永远无法替用户判断"是不是我要的"。`completed` 之后,**用户在客户端 review 产物**(看代码 / 跑起来 / git diff),满意才算真完;不满意 → 改/重做(§3.7)。这是设计上的最后一道、也是最权威的一道闸。 - -> 一句话回答"HM 怎么知道 AM 完成的是真实有效的":**严格说,HM 现在只能确认"有真东西、不是空/兜底",确认不了"对不对"。要确认"有效",必须 AM 把编译/测试结果回传给 HM 裁决;而"是不是用户要的",最终只能用户 review 拍板。** +**关于测试/编译**(纠正我之前的错误说法): +- 跑测试/编译是 **AM 在自己沙箱里做**(任务执行的一部分),或**客户端在本地做**。 +- 若 AM 跑了测试,**测试结果就是一个产物(`test_report` artifact)给客户端看**——**不是回传给 HM 去"裁决"**。HM 不参与对错判断。 --- @@ -418,7 +419,7 @@ - **超时**：AM 长时间无回调 → HM 标 `stale`/超时,客户端可见。 ### 9.4 产物与验收 -- **验收标准如何验证**：需求包里的 `acceptance_criteria` 谁来验? 建议:AM 跑测试(若有)并把**测试结果**作为 artifact 回传;HM 把「测试通过」纳入 `completed` 裁决参考。 +- **验收标准如何验证**：需求包里的 `acceptance_criteria` 谁来验? 建议:AM 跑测试(若有)并把**测试结果作为 `test_report` 产物给客户端**;**客户端 + 用户**据此判对错(**不经 HM 裁决**,§6.6)。 - **产物版本/标签**：每次交付打 tag(`delivery--rev`)或记 commit_sha,便于回溯 + 部署指定版本。 - **修改 vs 重做的边界**：`/messages`(在现有产物上改)与 `/redo`(重新生成)语义要清晰;redo 是否丢弃旧分支? 建议:redo 开新分支,旧的保留可对比。 @@ -459,8 +460,8 @@ **agent_management（runtime）** - 🔴 真正 git 入库 + 多 agent 分支 + 合并成交付分支 -- 🔴 **回传 `verification` 块**（`build_passed` / `tests_total` / `tests_passed` / `tests_failed` / `lint_passed`）——**这是 HM 把"完成"判成"真实有效"的关键证据**（§6.6） -- 🔴 对照 `acceptance_criteria` 自检并回传结果 +- 🔴 跑测试/编译并把结果作为 **`test_report` 产物给客户端看**（**不是给 HM 裁决**；对错由客户端+用户判，§6.6） +- 🔴 对照 `acceptance_criteria` 自检，结果同样作为产物给客户端 - 🔴 per-agent 指标上报（tokens/tools/elapsed/当前动作） - 🔴 artifact 带 `source_agent_role` + `git_ref` - 🔴 phases[] 阶段细分上报