4.6 KiB
4.6 KiB
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 调用模板
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 应包含：
- 角色声明：你是 XX 的执行者，不自己写代码，通过 Cursor 执行
- 环境信息：仓库路径、Cursor 命令格式、超时设置
- 任务描述：要做什么、为什么、约束条件
- 验证标准：怎样算完成（测试通过、无悬空引用等）
- Git 操作：commit message 格式
TDD 验收模式
用 TDD 方式验证实现是否正确：
- 让 Cursor 写验收测试（覆盖所有设计点）
- 运行测试
- 全绿 = 实现正确
- 红色 = 让 Cursor 修复实现 → 再跑
这种方式特别适合 AI 编码——强制每一步都有验证，防止"写了一堆代码但没验证"的问题。
反模式
| 反模式 | 为什么不好 | 正确做法 |
|---|---|---|
| 协调者自己写代码 | 上下文被细节淹没 | 派 subagent |
| 执行者手写代码不用 Cursor | 质量不稳定，浪费 token | 让 Cursor 做 |
| 一个 subagent 任务太大 | 超时风险，错误难定位 | 拆分成多个小任务 |
| 协调者轮询 subagent 状态 | 浪费 token 和时间 | 用 sessions_yield 等完成通知 |
| Coding Agent 做架构决策 | 它不理解业务上下文 | 协调者做决策，Cursor 只执行 |
总结
主人说"做什么" → 协调者决定"怎么做" → 执行者安排"谁来做" → Coding Agent 做
保持每一层的纯粹性，是高效协作的关键。