151 lines
4.6 KiB
Markdown
151 lines
4.6 KiB
Markdown
# 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 做
|
|
```
|
|
|
|
保持每一层的纯粹性，是高效协作的关键。
|