docs: Agent 三层分工模型（协调者/执行者/Coding Agent）

docs/shared/agent-division-of-labor.md

@@ -0,0 +1,150 @@
+# Agent 三层分工模型：协调者 / 执行者 / Coding Agent
+
+## 概述
+
+在多 Agent 协作的工作流中，我们采用三层分工模型来最大化效率、最小化心智负担。每一层有明确的职责边界，互不越界。
+
+```
+主人（决策者）
+  ↕ 实时沟通
+协调者（小墨）
+  ↓ 派发任务
+执行者（Subagent）
+  ↓ 调度工具
+Coding Agent（Cursor / Codex / Claude Code）
+  ↓ 写代码
+代码仓库
+```
+
+## 三层角色
+
+### 🎯 协调者（Coordinator）
+
+**代表：** 小墨（主 Agent）
+
+**职责：**
+- 和主人实时沟通，理解需求
+- 把控方向，做架构决策
+- 拆分任务，派发给执行者
+- 验证结果，汇报进展
+- 管理上下文空间，不被细节消耗
+
+**不做：**
+- ❌ 写代码、改文件
+- ❌ Debug 具体问题
+- ❌ 直接操作 Coding Agent
+
+**核心原则：** 协调者的上下文空间是最宝贵的资源。一旦开始写代码，上下文就会被实现细节淹没，无法继续做沟通和决策。
+
+### ⚙️ 执行者（Executor）
+
+**代表：** Subagent
+
+**职责：**
+- 理解协调者派发的任务
+- 拆分为具体的 Coding Agent 调用
+- 调度 Coding Agent 执行代码修改
+- 验证修改结果（跑测试、grep 检查）
+- 如果出错，把报错扔给 Coding Agent 修复
+- 向协调者汇报结果
+
+**不做：**
+- ❌ 和主人直接沟通
+- ❌ 做架构决策
+- ❌ 自己手写代码
+
+**工作流：**
+```
+理解任务 → 拆分步骤 → 写 Cursor prompt → 执行 → 验证
+                                                ↓ 失败
+                                          把报错扔给 Cursor → 再验证
+```
+
+### 🔨 Coding Agent
+
+**代表：** Cursor Agent CLI / Codex / Claude Code
+
+**职责：**
+- 接收自然语言 prompt
+- 在代码仓库中执行修改
+- 读文件、写文件、运行命令
+
+**特点：**
+- 有完整的代码上下文（整个仓库）
+- 擅长大范围重构和模式匹配
+- 但不理解业务方向，需要精确的 prompt
+
+## 为什么要三层？
+
+### 上下文隔离
+
+| 层级 | 上下文内容 | 大小 |
+|------|-----------|------|
+| 协调者 | 用户意图、架构方向、进展状态 | 小（保持精简） |
+| 执行者 | 具体任务、文件结构、错误信息 | 中（任务级别） |
+| Coding Agent | 完整代码库、AST、类型系统 | 大（仓库级别） |
+
+如果协调者直接写代码，它的上下文会被代码细节占满，就无法再和主人有效沟通。
+
+### 错误恢复
+
+- **Coding Agent 出错** → 执行者把报错扔回去，让它修
+- **执行者方向偏了** → 协调者 steer 或 kill，重新派发
+- **协调者理解错了** → 主人纠正，协调者调整方向
+
+每一层只处理自己能处理的错误，不越级。
+
+## 实践配置
+
+### Cursor Agent CLI 调用模板
+
+```bash
+export CURSOR_API_KEY=$(grep CURSOR_API_KEY ~/.bashrc | cut -d= -f2)
+cd <repo>
+agent -p --trust --force --output-format text "<prompt>"
+```
+
+参数说明：
+- `-p` (print mode)：非交互，适合脚本调用
+- `--trust`：信任工作目录
+- `--force`：允许修改文件（不加则只建议不执行）
+- `--output-format text`：纯文本输出
+
+### Subagent 派发模板
+
+协调者派发任务时，prompt 应包含：
+
+1. **角色声明**：你是 XX 的执行者，不自己写代码，通过 Cursor 执行
+2. **环境信息**：仓库路径、Cursor 命令格式、超时设置
+3. **任务描述**：要做什么、为什么、约束条件
+4. **验证标准**：怎样算完成（测试通过、无悬空引用等）
+5. **Git 操作**：commit message 格式
+
+### TDD 验收模式
+
+用 TDD 方式验证实现是否正确：
+
+1. 让 Cursor 写验收测试（覆盖所有设计点）
+2. 运行测试
+3. 全绿 = 实现正确
+4. 红色 = 让 Cursor 修复实现 → 再跑
+
+这种方式特别适合 AI 编码——强制每一步都有验证，防止"写了一堆代码但没验证"的问题。
+
+## 反模式
+
+| 反模式 | 为什么不好 | 正确做法 |
+|--------|-----------|---------|
+| 协调者自己写代码 | 上下文被细节淹没 | 派 subagent |
+| 执行者手写代码不用 Cursor | 质量不稳定，浪费 token | 让 Cursor 做 |
+| 一个 subagent 任务太大 | 超时风险，错误难定位 | 拆分成多个小任务 |
+| 协调者轮询 subagent 状态 | 浪费 token 和时间 | 用 sessions_yield 等完成通知 |
+| Coding Agent 做架构决策 | 它不理解业务上下文 | 协调者做决策，Cursor 只执行 |
+
+## 总结
+
+```
+主人说"做什么" → 协调者决定"怎么做" → 执行者安排"谁来做" → Coding Agent 做
+```
+
+保持每一层的纯粹性，是高效协作的关键。

mkdocs.yml

@@ -93,6 +93,7 @@ nav:
       - SiliconFlow 图片生成: shared/siliconflow-image-gen.md
       - Memex 知识管理: shared/memex-knowledge-base.md
       - TTS 语音功能: shared/tts-guide.md
+      - Agent 三层分工模型: shared/agent-division-of-labor.md
 
 extra:
   social: