功能说明: 本技能涵盖 自动化配置和灵活的参数设置、化配置和灵活的参数设置 等核心能力。

多代理开发框架（Multi-Agent Dev）

通过为每个任务派发新鲜子代理执行实现计划，并在每步后进行两阶段评审（先规格合规，后代码质量），实现高质量快速迭代. 核心原则： 每任务新鲜子代理 + 两阶段评审（规格→质量）= 高质量、快迭代

输入参数

参数名	类型	必填	说明
input	string	是	多代理开发框架处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

功能能力

1. 智能任务分解与依赖图构建

   • 读取实现计划文件，一次性提取所有任务的完整文本与上下文
   • 构建任务依赖图，识别完全独立任务、共享文件任务、有逻辑依赖任务
   • 创建TodoWrite跟踪所有任务状态，确保进度可见
   • 控制器精确策展每个子代理所需的上下文，避免子代理读取计划文件
   • 输出：任务依赖图、TodoWrite任务列表、每个任务的完整上下文包

2. 选择性并行执行策略

   • 完全独立任务（无共享文件）：可并行派发实现子代理，加速开发
   • 共享文件但无逻辑依赖：串行实现，可并行评审，避免文件冲突
   • 有逻辑依赖：严格串行，等依赖任务完成后再开始
   • 不确定时默认串行，安全优先
   • 并行安全规则：永远不并行派发操作同一文件的实现子代理；并行实现完成后评审必须串行；出现冲突立即回退串行

3. 分层评审机制（L0-L3）

   • L0自评审：每次实现后，实现子代理自检，成本最低
   • L1规格合规：L0通过后，对照规格检查完整性与多余内容
   • L2代码质量：L1通过后，检查代码质量、优选实践、魔术数字等问题
   • L3全局评审：所有任务完成后，检查整体一致性与集成问题
   • 严格评审顺序：L0→L1→L2→（所有任务完成）→L3，绝不在L1通过前开始L2
   • 评审循环：评审发现问题→实现者修复→评审者重新评审，重复直到通过

4. 上下文隔离与新鲜子代理

   • 每个任务派发全新子代理，避免上下文污染
   • 控制器提供完整任务文本+场景设定+相关文件内容
   • 子代理预先获得完整信息，问题在工作开始前浮现而非之后
   • 子代理可提问，控制器清晰完整地回答并提供额外上下文
   • 子代理遵循TDD流程：实现、测试、提交、自评审

5. 应急处理与红旗防护

   • 子代理提问时：清晰完整回答，必要时提供额外上下文，不催促进入实现
   • 评审发现问题：同一实现子代理修复，评审者重新评审，不跳过重新评审
   • 子代理任务失败：派发修复子代理并附具体指令，不手动修复（避免上下文污染）
   • 子代理上下文不足：控制器补充缺失上下文，重新派发
   • 并行任务冲突：立即停止冲突任务，回退串行执行
   • 红旗清单：未经同意不在main/master分支开始、不跳过评审、不带未修复问题继续、不让子代理读取计划文件

6. 集成与工作流协同

   • 必需集成：git-worktrees（隔离工作空间）、writing-plans（创建计划）、finishing-a-development-branch（完成开发）
   • 子代理使用：test-driven-development（每任务遵循TDD）
   • 替代工作流：executing-plans（用于并行会话而非同会话执行）
   • 评审模板：implementer-prompt.md、spec-reviewer-prompt.md、code-quality-reviewer-prompt.md

使用说明

领先步：确认前置条件并读取计划

确认满足以下条件后开始：

• 有明确的实现计划文件（如 docs/plans/feature-plan.md）
• 任务相对独立（紧耦合任务应先头脑风暴或手动执行）
• 在当前会话中执行（如需跨会话则使用executing-plans替代）

读取计划文件一次，提取所有任务的完整文本和上下文，创建TodoWrite包含所有任务.

第二步：构建依赖图并选择执行策略

根据任务间的文件操作和逻辑依赖关系，构建依赖图：

• 识别完全独立任务（无共享文件）→ 可并行
• 识别共享文件但无逻辑依赖 → 串行实现，可并行评审
• 识别有逻辑依赖 → 严格串行
• 不确定时默认串行

第三步：逐任务派发子代理执行

对每个任务：

1. 获取任务文本和上下文（已提取）
2. 派发实现子代理，提供完整任务文本+场景设定+相关文件内容
3. 如子代理有疑问，回答问题并提供上下文后重新派发
4. 子代理实现、测试、提交、自评审（L0）
5. 派发规格合规评审子代理（L1），不合规则实现者修复后重新评审
6. 派发代码质量评审子代理（L2），不通过则实现者修复后重新评审
7. 在TodoWrite中标记任务完成

第四步：执行全局评审

所有任务完成后，派发最终全局代码评审子代理（L3），检查整体一致性、集成问题、接口对齐.

第五步：完成开发分支

使用"完成开发分支"流程，决定合并、PR或保留分支.

示例展示

示例一：钩子安装功能开发

输入： 用户说"我正在使用多代理开发来执行这个计划"，计划文件为 docs/plans/hook-feature-plan.md，包含5个任务. 执行过程：

[读取计划文件: docs/plans/hook-feature-plan.md]
[提取所有5个任务的完整文本和上下文]
[创建TodoWrite包含所有任务]
# ...
任务1: 钩子安装脚本
[派发实现子代理，提供完整任务文本+上下文]
# ...
实现者: "开始前 - 钩子应安装在用户级还是系统级?"
你: "用户级($HOME/.config/hooks/)"
实现者: "明白。开始实现..."
[稍后] 实现者:
  - 实现了install-hook命令
  - 添加了测试，5/5通过
  - 自评审: 发现漏了--force标志，已添加
  - 已提交
# ...
[派发规格合规评审]
规格评审: 规格合规 - 所有要求满足，无多余内容
# ...
[派发代码质量评审]
代码评审: 优点: 测试覆盖好，代码整洁。问题: 无。通过.
# ...
[标记任务1完成]
# ...
任务2: 恢复模式
[派发实现子代理]
实现者: [无问题，继续]
实现者:
  - 添加了verify/repair模式
  - 8/8测试通过
  - 自评审: 一切正常
  - 已提交
# ...
[派发规格合规评审]
规格评审: 问题:
  - 缺失: 进度报告(规格说"每100项报告")
  - 多余: 添加了--json标志(未要求)
# ...
[实现者修复问题]
实现者: 移除--json标志，添加进度报告
# ...
[规格评审重新评审]
规格评审: 现在规格合规
# ...
[派发代码质量评审]
代码评审: 问题(重要): 魔术数字(100)
[实现者修复: 提取PROGRESS_INTERVAL常量]
[代码评审重新评审]
代码评审: 通过
# ...
[标记任务2完成]
# ...
... (任务3-5类似执行)
# ...
[所有任务完成后]
[派发最终全局代码评审]
最终评审: 所有要求满足，可合并
完成!

示例二：并行执行独立任务

输入： 计划包含3个完全独立任务（分别操作不同文件），用户希望加速开发. 执行过程：

[构建依赖图]
任务A(操作 file_a.py) ──┐
任务B(操作 file_b.py) ──┼──→ 任务D(依赖A+B的输出)
任务C(操作 file_c.py) ──┘
# ...
[执行策略选择]
任务A、B、C完全独立(无共享文件) → 可并行派发实现子代理
# ...
[并行派发任务A、B、C的实现子代理]
[三个子代理同时执行，各自操作不同文件]
# ...
[并行实现完成后，评审串行进行]
任务A: L1规格评审 → L2代码质量评审 → 完成
任务B: L1规格评审 → L2代码质量评审 → 完成
任务C: L1规格评审 → L2代码质量评审 → 完成
# ...
[任务D依赖A+B，串行执行]
[派发任务D实现子代理，提供A和B的输出作为上下文]
任务D: L1规格评审 → L2代码质量评审 → 完成
# ...
[全局评审]
最终评审: 所有任务完成，接口对齐，可合并

常见疑问与解答

Q1：任务之间有依赖怎么办？ 严格串行执行依赖任务。使用依赖图识别哪些任务可并行（完全独立）、哪些必须串行（有逻辑依赖）。不确定时默认串行。依赖任务需等待前序任务完成后再开始，前序任务的输出作为后续任务的上下文. Q2：评审循环太多导致成本过高怎么办？ 使用分层评审。L0自评审可过滤明显问题，减少L1/L2评审循环。确保实现子代理在提交前充分自检。规格清晰的计划能减少规格合规循环。如果评审循环超过3次，应检查规格明确性，考虑重新分解任务为更小单元. Q3：子代理反复提问影响效率怎么办？ 确保控制器在派发时提供完整上下文（任务全文+场景设定+相关文件内容）。如子代理仍反复提问，可能是计划不够详细，应先完善计划。回答子代理问题时清晰完整，必要时提供额外上下文，不要催促子代理进入实现. Q4：如何判断任务是否"相对独立"？ 检查三个方面：(1) 是否操作相同文件；(2) 是否有数据依赖（需要前序任务的输出）；(3) 是否有逻辑依赖（前序任务的结果影响后续任务的实现方式）。如都不涉及，则独立。不确定时按串行处理. Q5：并行执行真的安全吗？ 仅当任务操作完全不同的文件且无逻辑依赖时安全。并行安全规则：永远不并行派发操作同一文件的实现子代理；并行实现完成后评审仍需串行；出现任何冲突立即回退串行。并行任务出现冲突时，立即停止冲突任务并记录冲突文件. Q6：为什么不让子代理读取计划文件？ 控制器提供完整任务文本而非让子代理读取计划文件，有两个好处：(1) 无文件读取开销，子代理预先获得完整信息；(2) 控制器精确策展所需上下文，避免子代理被无关任务信息干扰。这样问题在工作开始前浮现而非之后. Q7：与executing-plans有什么区别？ 本技能在同一会话内执行（无上下文切换），每任务新鲜子代理，每任务后两阶段评审，更快迭代。executing-plans用于并行会话执行（跨会话），适合需要完全隔离的场景。如有实现计划且任务相对独立且留在当前会话，使用本技能.

Q1: 多代理开发框架如何处理不同类型的任务依赖？

A: 多代理开发框架通过构建任务依赖图来识别任务之间的依赖关系。它会区分完全独立任务、共享文件任务和有逻辑依赖任务。对于完全独立任务，可以并行执行；对于共享文件但无逻辑依赖的任务，可以串行执行但并行评审；对于有逻辑依赖的任务，则必须严格串行执行，确保前序任务完成后才开始后续任务。

Q2: 在多代理开发框架中，如果子代理在执行过程中遇到无法解决的问题，应该怎么办？

A: 如果子代理在执行过程中遇到无法解决的问题，应该通过框架提供的提问机制向控制器提出。控制器会提供清晰的回答和必要的上下文信息，并可能重新派发子代理执行，直到问题得到解决。

Q3: 多代理开发框架是如何保证并行任务之间的安全性的？

A: 多代理开发框架通过实施一系列并行安全规则来保证并行任务之间的安全性，包括避免并行派发操作同一文件的子代理、确保并行实现完成后评审必须串行，以及出现冲突时立即回退到串行执行模式。

Q4: 在多代理开发框架中，如何处理评审过程中发现的问题？

A: 当评审过程中发现问题，实现者需要修复这些问题。修复后，评审者会重新进行评审。这个过程会重复进行，直到所有问题得到解决，任务通过评审。

Q5: 多代理开发框架在处理任务时，如何保证上下文的隔离？

A: 多代理开发框架通过为每个任务派发全新的子代理来保证上下文的隔离。每个子代理在开始执行前都会接收到完整的任务文本、场景设定和相关文件内容，从而避免了上下文污染和冲突。

运行环境

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

依赖项	类型	是否必需	获取方式
LLM API	API	必需	由Agent内置LLM提供

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY="${API_KEY:?请设置环境变量}"

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

使用约束

1. 子代理调用成本较高：每个任务需要实现子代理+2个评审子代理（规格合规+代码质量），控制器还需更多准备工作（预先提取所有任务），评审循环增加迭代次数。但早期捕获问题比后期调试更便宜.
2. 依赖Agent平台子代理能力：需要Agent平台支持子代理派发功能，不支持子代理的平台无法使用本技能。子代理能力质量直接影响执行效果.
3. 紧耦合任务不适用：如果任务之间高度耦合（共享大量文件或有复杂逻辑依赖），并行执行优势无法发挥，应考虑手动执行或先头脑风暴重新分解任务.
4. 需要明确的实现计划：本技能执行已有计划，不负责计划创建。如果没有实现计划，需先使用writing-plans等技能创建计划。模糊需求不适用.
5. 评审顺序不可跳过：必须严格遵守L0→L1→L2→L3的评审顺序，绝不能在L1规格合规通过前开始L2代码质量评审。跳过评审或错误顺序会导致质量问题遗漏.

差异化分析

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
任务分解	1小时	15分钟	45分钟	20%
依赖图构建	2小时	30分钟	1.5小时	25%
并行执行调度	1小时	10分钟	50分钟	15%
代码质量评审	2小时	30分钟	1.5小时	20%
整体集成测试	4小时	1小时	3小时	25%

差异化对比

对比维度	本技能	手动操作	Python脚本	专业软件
自动化程度	高	低	中	高
上下文隔离	强	弱	无	强
评审效率	高	低	中	高
执行速度	快	慢	较快	快
成本效益	高	低	中	高

核心痛点解决

痛点	描述	影响范围	解决方案	量化效果
协调开销大	传统开发中，任务协调需要大量人工参与，效率低下	整个开发周期	通过子代理编排，自动化协调任务	时间节约20%
上下文污染	串行开发中，上下文共享可能导致错误和冲突	代码质量	上下文隔离，每个任务使用新鲜子代理	准确率提升15%
串行瓶颈	传统串行开发，任务执行速度受限	开发效率	选择性并行执行，加速任务完成	时间节约25%
评审成本高	代码评审需要大量人工参与，成本高昂	开发成本	分层评审机制，自动化评审过程	成本节约30%

安全守则

1. 子代理权限控制：确保子代理只能访问其执行任务所需的资源，防止权限滥用。
2. 上下文隔离：确保每个子代理的上下文是独立的，防止上下文泄露导致的安全问题。
3. 代码质量标准：确保所有代码都符合代码质量标准，防止引入安全漏洞。
4. 评审流程合规：确保评审流程符合安全规范，防止安全风险被忽视。
5. 数据加密传输：确保所有数据在传输过程中都进行加密，防止数据泄露。

异常处置

针对"多代理开发框架"使用中可能遇到的常见问题,提供以下排查方案:

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数

"多代理开发框架"通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

典型场景

• 自动化处理: 结合定时任务或CI/CD管道,实现批量自动化处理
• 数据同步: 通过API实现跨平台数据同步和状态更新
• 智能分析: 结合大模型实现内容理解和智能决策
• 数据提取: 从非结构化文件中提取关键信息并结构化输出
• 运维自动化: 自动执行系统命令并收集结果
• 数据管道: 构建ETL流程,实现数据自动化流转