# Agent 协作闭环 — 项目示例

> 📌 这是内部/存档文档，面向维护者与研究者。新读者请从仓库根 [README](../README.md) 开始。

> 一种双模型协作开发流程：**实施者写代码，审查者挑毛病，测试抓漏网之鱼，复检验收**。
> 本示例基于 kimi-tide 项目的真实实践记录（DeepSeek/DSH 实施 × Kimi 审查）。

---

## 1. 什么是协作闭环

```
┌─────────────┐  实施   ┌─────────────┐  审查报告   ┌─────────────┐
│ Phase 1      │───────▶│ Phase 2      │───────────▶│ Phase 3      │
│ 实施         │        │ 独立审查      │            │ 修复 + 测试  │
│ (DSH 主 agent)│        │ (Kimi 只读)  │            │ (DSH 主 agent)│
└─────────────┘        └─────────────┘            └──────┬──────┘
       ▲                                                  │
       │              ┌─────────────┐                     │
       └──────────────│ Phase 4      │◀────────────────────┘
          (有新问题   │ 复检验收     │
           则回到 3)   │ (Kimi)      │
                      └─────────────┘
```

| 阶段 | 执行者 | 产出 | 工具约束 |
|------|--------|------|---------|
| **1. 实施** | DSH 主 agent | 代码/配置变更 | 完整工具 |
| **2. 独立审查** | Kimi（独立上下文） | 分级问题清单（严重/中等/轻微）| **只读**（reviewOnly 天然适配） |
| **3. 修复 + 测试** | DSH 主 agent | 修复 + 单元测试锁定 | 完整工具 |
| **4. 复检验收** | Kimi | 逐项复核表 + 新问题 + 成熟度评价 | 只读 |

**核心原则**：

1. **写代码的人不审查自己的代码**——审查者拥有全新上下文，没有实施时的思维惯性。
2. **测试是第三双眼睛**——审查者也会漏（见下文实录），能跑的测试永远比读代码可靠。
3. **修复必须复检**——修复本身可能引入新问题，闭环不验收不关闭。

**成熟度评级（复检验收时统一口径）**：

| 等级 | 定义 |
|------|------|
| 实验级 | 核心路径在作者环境可跑；不可移植、无测试或测试不全 |
| 可用级 | 关键路径有测试锁定、路径可移植、安全问题已关闭；可小范围日常使用 |
| 生产级 | 测试覆盖充分、文档与代码同步、有明确的升级与回滚路径；可团队投产 |

---

## 2. 为什么有效（本项目的实测数据）

kimi-tide 项目的一轮完整闭环：

| 环节 | 数据 |
|------|------|
| Kimi 初审 | **23 个问题**：3 严重 / 8 中等 / 12 轻微，全部命中真实痛点 |
| DSH 实施修复 | 23 项全部修复 + 新增 5 个单元测试 |
| **测试抓到的隐藏 bug** | 审查者漏掉的 `syncAuthFile` EEXIST 处理错误（**修复前**的代码中：文件副本需要刷新时 `symlinkSync` 抛 EEXIST 直接返回，导致 copy 刷新永远不会执行——已修复并由测试锁定，当前代码无此问题） |
| Kimi 复检 | 23 项确认修复 ✅ + 新发现 5 个问题（2 代码 + 3 文档版本同步，明细见[复检档案](audit/review-round-2.md)） |
| 二次修复 | 5 项全部修复，测试 5/5 绿 |
| 最终评价 | "修复可接受，达到可用成熟度" |

> 完整原始报告存档：[第一轮审查档案](audit/review-round-1.md) · [第二轮复检档案](audit/review-round-2.md)

**价值拆解**：

- 审查报告把"凭据陈旧"列为严重 #1，但真正的根因（EEXIST 短路）是**测试**抓到的——审查判断了症状，测试挖出了病灶。
- 复检发现 5 个新问题里 3 个是**文档与代码不同步**（tarball 版本号、过期的路径警告）——这类"实施后遗症"只有独立复核才能系统性发现。

**闭环的第二次应用（设计文档审查，0.3.0 计划）**：同样的"独立审查 → 修订 → 复检 → 终审"流程也被用于**设计/计划文档**而非代码——0.3.0 能力评分路由计划经三轮闭环（R1 13 条 → 修订 v2 → R2 7 条 → 修订 v2.1 → R3 遗留 7 条处理 → 定稿 v2.2），总评「同意闭环进入 writing-plans」。与代码审查的不同点：审查对象是 spec/plan 文本，审查者无法跑测试，因此"落地性"由审查者对照现行源码逐条核实，动态验证项留给实施阶段。档案见 [`superpowers/reviews/2026-08-17-capability-routing-kimi-review-round1.md`](superpowers/reviews/2026-08-17-capability-routing-kimi-review-round1.md)（round2/round3 同目录）。

**闭环的第三次应用（0.3.0 实施阶段，2026-08-18）**：11 任务 TDD 实施同样按任务级"实施 → 检验 → 范围复核"闭环执行——28 次子代理派发（11 实施者 / 10 任务检验者 / 5 范围复核者 / 1 最终全分支评审 / 1 最终修复波），3 处计划缺陷经裁定修正，全链路无遗留 open finding；ff 合并后 154/154 测试绿（commit 86da918）。本轮验证：闭环对**实施阶段的任务粒度**质量把关同样有效，而不仅限于设计/代码审查。

---

## 3. 操作手册（在 DSH 中复现闭环）

### 3.1 前提条件

- DSH 已运行（web profile）
- ~~`dsh-kimi-bridge` 插件已安装且重启生效 → 工具面板出现 `call_kimi` / `kimi_status` / `kimi_abort` / `kimi_steer`~~（**历史**：dsh-kimi-bridge 已于 2026-08-23 归档退役，其审查角色由 @kimi 子代理经 kimi-tide 路由承接）
- kimi CLI 已登录（`kimi login`）
- 可选：kimi-tide 的 provider 接入（让 DSH 对话本身也能跑在 Kimi 模型上）

### 3.2 Phase 1 — 实施

正常在 DSH 中完成开发（改代码、写配置）。完成时**明确边界**：列出改动文件清单，供审查者定位。

### 3.3 Phase 2 — 独立审查（发任务给 Kimi）

用 `call_kimi` 工具（`mode: async` 后台跑，`kimi_status` 轮询；或 `mode: block` 等结果）：

```
prompt 要素（见 docs/templates/review-task.md 完整模板）：
1. 项目背景（3-5 句，让审查者无需外部信息）
2. 审查范围：文件清单（明确重点文件）
3. 关注维度：正确性 / 安全 / 健壮性 / 平台兼容 / 代码质量
4. 输出格式：分级清单（严重/中等/轻微），每条含位置+描述+建议
5. 约束：只读，不修改任何文件；最后给成熟度评价
```

要点：
- **默认 reviewOnly 模式正好是只读审查**——kimi 拿不到写工具，天然不会乱动代码。审查者无法执行代码，所以任务书要提示它：把"需动态验证的怀疑"单独列为一节，由主 agent 代跑后回传（见[复检模板](templates/recheck-task.md)的执行环境话术）。
- 项目路径必须写绝对路径（kimi 的 cwd 是 DSH 会话工作目录）。
- 大项目分多轮：一轮一个模块。每轮结束把结论归档（`docs/audit/`），下一轮任务书引用上一轮编号，避免重复审查与遗漏。
- 任务书固定记录实施者/审查者身份（模型与工具可用性），多模型协作下结论才有可比性。

### 3.4 Phase 3 — 修复 + 测试

1. 主 agent 逐项评估审查报告：**核实每一条**（审查者也会误报——本示例中 2 条测试期望错误就是审查与实现之间的语义分歧）。
2. 按优先级修复。
3. **为修复的关键路径补测试**——特别是审查者标"严重"的项，用测试锁定，而不是改完就完。
4. 跑测试、跑冒烟验证（脚本实跑、schema 校验、端到端调用）。

### 3.5 Phase 4 — 复检验收（再发任务给 Kimi）

```
prompt 要素（见 docs/templates/recheck-task.md 完整模板）：
1. 逐项修复清单（编号 + 一句话说明改法）
2. 要求逐项确认：已修复 / 未修复 / 部分修复
3. 要求检查新引入的问题（修复的副作用）
4. 要求跑测试（若有 Shell 权限）；否则主 agent 代跑并附结果
5. 最终成熟度评价
```

复检发现新问题 → 回到 Phase 3 继续修 → 再复检，直到无新问题或仅剩可接受项。

---

## 4. 踩过的坑（供后来者参考）

1. **审查 prompt 信息不足 = 审查质量塌方**。第一次给 kimi 的任务书里写了项目背景、文件清单、已知事实、输出格式，审查质量很高；如果只丢一句"审查一下项目"，得到的会是泛泛之谈。
2. **测试期望要与实现语义对齐**。修复后我们写的两个测试用例期望本身有误（其一错误地期望：即便输入是非法 TOML，工具也应把它修复为合法输出——与实现"fail-loud"语义不符；其二是 mtime 精度假设），被测试运行抓出来——测试本身也要被"调试"。
3. **文档同步是复检的固定检查项**。版本号、README 里的路径警告、tarball 文件名——实施阶段几乎必然忘记同步，复检专门扫这一层。
4. **审查者可能没有执行环境**。Kimi 复检时因 reviewOnly 没有 Shell 工具，无法自己跑测试——由主 agent 代跑并把输出附进复检任务，审查者核对代码逻辑即可。
5. **闭环的价值上限取决于测试的真实性**。junction/copy fallback 的测试之所以能抓到 EEXIST bug，是因为它在**真实的 Windows 无 symlink 权限环境**下跑，而不是 mock 出来的。
6. **测试通过 ≠ 装得进宿主**。kimi-tide 插件冒烟测试全绿（OAuth/模型/流式/工具调用），但第一次装入 DSH 仍然崩溃——插件缺官方要求的 `dsh.bundle.patch` 声明，只能作为普通依赖存在，手动进 bundles 后启动失败。**审查清单要包含"发布规范"维度**：插件的 bundle 声明、exports 映射、打包清单（files）、宿主版本兼容性，这些是静态测试覆盖不到、只有真实安装才能暴露的问题。事后由用户手动修复，代价是两个备份目录和一次崩溃排查。
7. **作者的隐含假设 = 文档最容易断的链接**。Kimi 优化 README 时默认读者已装有 kimi CLI，把 `kimi login` 写成前置条件却漏掉了"安装 CLI"这一步，用户一眼抓出。AI 作者容易把**自己环境里已存在的东西**当作读者也有——审查文档时专门做一次"依赖链校验"：每条命令所需的可执行文件/服务/登录态，是否都出现在它之前的步骤或前置条件里。

---

## 5. 与其他协作模式的关系

| 模式 | 适用场景 |
|------|---------|
| **本闭环（审查型）** | 代码质量把关、安全审计、上线前验收 |
| 并行编码（`call_kimi` 派独立任务） | 多方案探索、互不依赖的模块开发 |
| 接力（`kimi_steer` 续会话） | 长任务分段、方向调整 |
| 自审查（同模型回看） | 快速检查，但存在"思维惯性"，不如独立上下文可靠 |

---

## 6. 模板

- [审查任务书模板](templates/review-task.md)
- [复检任务书模板](templates/recheck-task.md)

> 版本锁定说明（历史）：本示例中的命令绑定 DSH 0.1.0-rc.6 / dsh-kimi-bridge 0.1.1（kimi-tide 插件侧已在 DSH rc.7 实机验证）；dsh-kimi-bridge 已于 2026-08-23 归档退役。
> DSH 升级后请先验证插件兼容性（`dsh plugin` 的 peer 依赖检查），再更新本文档与
> 模板中的版本号——文档过期本身就是复检的固定检查项（本项目的 R2-2/R2-3/R2-4
> 就是这类问题）。

> 本闭环在 kimi-tide 项目上以代码审查完整跑过两轮（审查 → 修复 → 复检 → 二次修复），
> 最终 28 个问题（23 初审 + 5 复检）全部关闭，测试 5/5 绿，验收通过；
> 此后又应用于 0.3.0 设计文档三轮审查与 11 任务实施阶段（见 §2）。
> 原始报告存档：[第一轮](audit/review-round-1.md) · [第二轮](audit/review-round-2.md)