# 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 做
```

保持每一层的纯粹性，是高效协作的关键。