多代理开发框架

多代理开发是一个通过子代理编排执行实现计划的开发框架。针对传统子代理开发"协调开销大、上下文污染、串行瓶颈、评审成本高"四大痛点，构建了智能任务分解图、选择性并行执行、分层评审机制和上下文隔离四大核心能力。每个任务派发新鲜子代理执行，并在每步后进行两阶段评审（先规格合规，后代码质量），实现高质量快速迭代。适...

天轰穿@thcjp

Install

openclaw skills install @thcjp/multi-agent-dev

核心功能: 本技能提供自动化配置和灵活的参数设置、化配置和灵活的参数设置等能力。

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

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

输入参数

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

付费版扩展能力

能力	免费版	付费版
基础功能	支持	支持
多代理开发框架通过子代理编排	不支持	支持
代码静态分析与质量评分	不支持	支持
依赖漏洞检测与升级建议	不支持	支持
批量代码审查与报告生成	不支持	支持
CI/CD流水线集成	不支持	支持

功能能力

智能任务分解与依赖图构建
- 读取实现计划文件，一次性提取所有任务的完整文本与上下文
- 构建任务依赖图，识别完全独立任务、共享文件任务、有逻辑依赖任务
- 创建TodoWrite跟踪所有任务状态，确保进度可见
- 控制器精确策展每个子代理所需的上下文，避免子代理读取计划文件
- 输出：任务依赖图、TodoWrite任务列表、每个任务的完整上下文包
选择性并行执行策略
- 完全独立任务（无共享文件）：可并行派发实现子代理，加速开发
- 共享文件但无逻辑依赖：串行实现，可并行评审，避免文件冲突
- 有逻辑依赖：严格串行，等依赖任务完成后再开始
- 不确定时默认串行，安全优先
- 并行安全规则：永远不并行派发操作同一文件的实现子代理；并行实现完成后评审必须串行；出现冲突立即回退串行
分层评审机制（L0-L3）
- L0自评审：每次实现后，实现子代理自检，成本最低
- L1规格合规：L0通过后，对照规格检查完整性与多余内容
- L2代码质量：L1通过后，检查代码质量、优选实践、魔术数字等问题
- L3全局评审：所有任务完成后，检查整体一致性与集成问题
- 严格评审顺序：L0→L1→L2→（所有任务完成）→L3，绝不在L1通过前开始L2
- 评审循环：评审发现问题→实现者修复→评审者重新评审，重复直到通过
上下文隔离与新鲜子代理
- 每个任务派发全新子代理，避免上下文污染
- 控制器提供完整任务文本+场景设定+相关文件内容
- 子代理预先获得完整信息，问题在工作开始前浮现而非之后
- 子代理可提问，控制器清晰完整地回答并提供额外上下文
- 子代理遵循TDD流程：实现、测试、提交、自评审
应急处理与红旗防护
- 子代理提问时：清晰完整回答，必要时提供额外上下文，不催促进入实现
- 评审发现问题：同一实现子代理修复，评审者重新评审，不跳过重新评审
- 子代理任务失败：派发修复子代理并附具体指令，不手动修复（避免上下文污染）
- 子代理上下文不足：控制器补充缺失上下文，重新派发
- 并行任务冲突：立即停止冲突任务，回退串行执行
- 红旗清单：未经同意不在main/master分支开始、不跳过评审、不带未修复问题继续、不让子代理读取计划文件
集成与工作流协同
- 必需集成：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

迅速上手

确认运行环境满足依赖说明中的要求
在AI Agent对话中调用本技能,提供必要的输入参数
检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

使用说明

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

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

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

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

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

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

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

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

对每个任务：

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

第四步：执行全局评审

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

第五步：完成开发分支

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

异常修复

错误类型	原因	处理方式
子代理产出与规格不符	上下文不足或规格模糊	补充完整任务文本+场景设定+相关文件内容，重新派发子代理
评审循环超过3次	实现质量低或规格不清晰	检查规格明确性，考虑重新分解任务为更小单元
子代理上下文污染	复用了非新鲜子代理	确保每任务派发全新子代理，不复用历史子代理实例
并行任务文件冲突	并行子代理操作了相同文件	立即停止冲突任务，回退到串行执行模式，记录冲突文件
TodoWrite状态不同步	未及时更新任务完成状态	每完成一个任务立即更新TodoWrite，定期检查状态一致性
最终评审发现集成问题	任务间接口未对齐	在计划阶段明确接口契约，补充接口文档后重新评审
子代理反复提问影响效率	计划不够详细或上下文不完整	完善计划细节，控制器在派发时提供更完整的上下文
子代理任务执行失败	实现复杂度超出子代理能力	派发修复子代理并附具体指令，或将任务拆分为更小子任务

示例展示

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

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

text

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

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

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

text

[构建依赖图]
任务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配置方式:

bash

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

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

使用约束

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

响应格式

json

{
  "success": true,
  "data": {
    "result": "多代理开发框架处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "multi-agent-dev"
    }
  },
  "execution_log": [
    "解析输入参数",
    "执行核心处理",
    "格式化输出结果"
  ],
  "error": null
}

差异化分析

效率提升量化分析

操作步骤	手动耗时	自动化耗时	时间节约	准确率提升
任务分解	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%

安全守则

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

核心属性

自动化执行: 通过子代理编排执行实现
文件处理: 支持多种文件格式的读取、解析和写入操作
API集成: 通过标准化接口调用外部服务并处理响应
命令执行: 在安全沙箱中执行系统命令并收集结果

异常处置

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

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