ruflo/Claude Flow 多智能体群（Swarm）中的战略规划 Agent：planner 任务分解、依赖映射与协作编排完全指南

多智能体系统要真正落地，关键的并不在于每个 Agent 单点的能力，而在于是否有一个角色能把复杂需求拆成原子任务、理清依赖、分配资源并跟踪进度。本文以当前仓库 .claude/agents/core/planner.md 定义的战略规划 Agent（planner）为主线，系统讲解它在 ruflo / Claude Flow 多智能体编排体系中的定位、五项核心职责、五步规划流程、标准 YAML 输出契约，以及通过 MCP 工具与记忆系统完成的任务编排与跨 Agent 协作方式。读完本文，你将掌握一套可复制的"规划 → 编排 → 记忆回写"方法论，并能结合仓库源码把 planner 真正接入你自己的多 Agent 工作流。

planner 是什么：群体智能里的"战略中枢"

在 .claude/agents/core 目录中，ruflo 同时预置了 planner.md、coder.md、researcher.md、reviewer.md、tester.md 五个核心角色，分别对应规划、实现、研究、评审与测试。其中 planner 被明确定义为：

"A strategic planning specialist responsible for breaking down complex tasks into manageable components and creating actionable execution plans."（负责将复杂任务拆解为可管理组件、并产出可执行计划的一名战略规划专家。）

它的元信息同样体现在文档开头的 frontmatter 中——name: planner、description: Strategic planning and task orchestration agent，这也意味着它并非一段普通提示词，而是可被上层编排器（如 /spawn、/orchestrate 等命令，参见 .claude/commands/coordination/task-orchestrate.md）识别并加载为独立 Agent 的系统级定义。

在多 Agent 协作中，planner 扮演的是"上游大脑"：它不直接写代码，而是为 coder、researcher、tester 等执行型 Agent 提供任务契约。这种"规划者与执行者分离"的设计，避免了每个执行者各自为政、重复造轮子，也让整条流水线具备可预期性。

五项核心职责

planner 的能力模型收敛为五项职责，是后续所有流程与输出格式设计的基础：

职责	关键产出	说明
任务分析 Task Analysis	原子任务清单	把复杂请求拆成"可执行的最小粒度"任务，避免粒度不均导致的失控
依赖映射 Dependency Mapping	依赖图与前置条件	显式记录任务之间的先后关系与前置条件
资源规划 Resource Planning	Agent 分配方案	决定每个任务由哪类 Agent 承接，以及工具与算力配比
时间线创建 Timeline Creation	工期估计	基于依赖与资源给出切合实际的完成时限
风险评估 Risk Assessment	风险与缓解清单	提前识别阻塞点并给出后备方案

值得注意，这份职责清单与协作伙伴的文档形成闭环：在 researcher.md 中，researcher 的协作指南明确写着"Share findings with planner for task decomposition via memory"（通过记忆把发现共享给 planner 以支持任务分解）；coder.md 也要求"Follow planner's task breakdown"（遵循 planner 的任务拆解）。由此可以推断，planner 处于信息汇聚与派发的枢纽位置：上游接收 researcher 的研究结论，下游向 coder、tester 派发分解后的任务，评审结果再回流修正计划。

五步规划流程：从评估到风险兜底

原文档给出了贯穿规划全生命周期的五步流程，每一步都对应明确的动作目标：

1. Initial Assessment（初始评估）
   • 分析请求的完整范围（scope）；
   • 识别核心目标与成功标准（objectives / success criteria）；
   • 判断复杂程度与所需专业领域。
2. Task Decomposition（任务分解）
   • 拆成具体、可度量的子任务；
   • 确保每个任务有清晰的输入与输出；
   • 做逻辑分组与阶段划分。
3. Dependency Analysis（依赖分析）
   • 绘制任务间依赖关系；
   • 识别关键路径项（critical path items）；
   • 标记潜在瓶颈。
4. Resource Allocation（资源分配）
   • 为每个任务确定所需 Agent；
   • 分配时间与计算资源；
   • 在可行时规划并行执行。
5. Risk Mitigation（风险缓解）
   • 识别可能的失败点；
   • 制定应急预案；
   • 在计划中内置验证检查点。

这套流程的实质是"先广度后深度"：先用评估圈定边界，再用分解与依赖分析把黑盒变白盒，最后以资源与风险兜底。其中第 2、3 步产出的"任务 + 依赖"结构，恰好对应下层任务系统的可持久化字段，为后续用 MCP 工具落地提供了语义基础（见下文第五节）。

输出格式：一份可机器消费的 YAML 计划契约

原文档为 planner 定义了标准输出骨架，这是全文最具工程价值的部分——它保证每次规划产物的结构一致，既能被人类阅读，也能被后续的编排逻辑稳定解析。完整结构如下：

plan:
  objective: "Clear description of the goal"
  phases:
    - name: "Phase Name"
      tasks:
        - id: "task-1"
          description: "What needs to be done"
          agent: "Which agent should handle this"
          dependencies: ["task-ids"]
          estimated_time: "15m"
          priority: "high|medium|low"

  critical_path: ["task-1", "task-3", "task-7"]

  risks:
    - description: "Potential issue"
      mitigation: "How to handle it"

  success_criteria:
    - "Measurable outcome 1"
    - "Measurable outcome 2"

对其中各字段做进一步解读，便于实际编写时拿捏取值尺度：

• plan.objective：一句话描述目标，越具体越好，应能被 success_criteria 直接检验。
• plan.phases[].name：阶段名，用于把子任务做逻辑分组，形成可交付的里程碑。
• plan.phases[].tasks[]：任务数组，最小单元应具备"单一职责"。
  • id：任务唯一标识，被 dependencies、critical_path 引用，是整个契约的"外键"；
  • agent：承接 Agent 类型，实践中通常对应 researcher、architect、coder、tester 等角色（.claude/agents/core 目录即为可选角色池）；
  • dependencies：前置任务 id 列表，空数组表示可立即开始；
  • estimated_time：建议使用 15m/2h/1d 这类可解析单位，方便后续汇总工期；
  • priority：枚举 high|medium|low，用于指导执行顺序与资源倾斜。
• critical_path：关键路径上的任务 id 数组。关键路径上的延误会直接拖慢整体工期，因此也是进度监控的优先对象。
• risks[]：每条风险含 description 与 mitigation 两个字段，强制"提出问题必须附带对策"。
• success_criteria[]：可度量的完成标准，通常为"行为可验证"的断言式描述。

结合任务系统源码可以确认，这套 YAML 契约与底层任务数据模型高度同构。在 v3/@claude-flow/cli/src/mcp-tools/task-tools.ts 中，task_create 工具的入参 schema 支持 type（枚举 feature | bugfix | research | refactor）、description、priority（枚举 low | normal | high | critical）、assignTo（Agent id 数组）与 tags，且 task_create 的描述明确指出：当需要"跨会话任务持久化、Agent 分配、依赖追踪与完成度分析"时应使用任务工具而不是会话内清单。这与 planner 输出中的 agent、priority、id 一一对应，说明 planner 产出的计划可以直接落到持久化任务存储中被跟踪执行。

MCP 工具集成：规划结果如何变成真实任务

原文档最后一部分给出了 planner 与 Claude Flow MCP 工具的具体交互示例，这是连接"规划"与"执行"的关键枢纽。仓库中的 MCP 桥接配置位于 .claude/mcp.json，任务工具与记忆工具的实现分别在 task-tools.ts 与对应的 memory 工具模块中。

任务编排（Task Orchestration）

// Orchestrate complex tasks
mcp__claude-flow__task_orchestrate {
  task: "Implement authentication system",
  strategy: "parallel",
  priority: "high",
  maxAgents: 5
}

// Share task breakdown
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm/planner/task-breakdown",
  namespace: "coordination",
  value: JSON.stringify({
    main_task: "authentication",
    subtasks: [
      {id: "1", task: "Research auth libraries", assignee: "researcher"},
      {id: "2", task: "Design auth flow", assignee: "architect"},
      {id: "3", task: "Implement auth service", assignee: "coder"},
      {id: "4", task: "Write auth tests", assignee: "tester"}
    ],
    dependencies: {"3": ["1", "2"], "4": ["3"]}
  })
}

// Monitor task progress
mcp__claude-flow__task_status {
  taskId: "auth-implementation"
}

对该示例做逐字段说明：

• task：待编排的顶层任务描述，如 "Implement authentication system"；
• strategy：编排策略，示例用 parallel（并行）；当任务存在严格先后依赖时应选用顺序/混合策略。CLI 层面 npx claude-flow task orchestrate 的 --strategy 选项（见 .claude/commands/coordination/task-orchestrate.md）也支持同样的概念；
• priority：high 指示该任务是当前优先投入资源的方向；
• maxAgents：最多并发参与的 Agent 数，用于限制并行度、防止资源争抢。

memory_usage 子调用把任务分解写入协调命名空间（namespace: "coordination"），键名 swarm/planner/task-breakdown 遵循 swarm/<role>/<topic> 的命名约定。注意示例中 assignee 被指派为 researcher、architect、coder、tester，dependencies 用对象描述"子任务 3 依赖 1、2；子任务 4 依赖 3"——这正是 YAML 输出中 dependencies 数组的等价表达，映射成图就是一条"研究 → 设计 → 实现 → 测试"的流水线。

记忆协同（Memory Coordination）

// Report planning status
mcp__claude-flow__memory_usage {
  action: "store",
  key: "swarm/planner/status",
  namespace: "coordination",
  value: JSON.stringify({
    agent: "planner",
    status: "planning",
    tasks_planned: 12,
    estimated_hours: 24,
    timestamp: Date.now()
  })
}

这段调用的作用是把 planner 自身的运行状态（当前处于 planning、已规划任务数、预计耗时）写入共享记忆，供监控类命令（如 .claude/commands/monitoring/status.md 或 swarm-status）与其它 Agent 读取。结合 .claude/commands/memory/memory-usage.md 可知，memory_usage 的 CLI 等价形式为：

npx claude-flow memory usage --action store --key "swarm/planner/status" \
  --value '{"agent":"planner","status":"planning","tasks_planned":12,"estimated_hours":24}'

action 支持 store（写入）、retrieve（读取）、list（列出）与 clear。在多 Agent 场景下，planner 的决策不应只存在对话上下文里，而应通过 memory_usage store 沉淀到命名空间中，形成"所有 Agent 可见、跨会话可恢复"的协调底座。

协作准则与最佳实践

原文档的收尾部分给出了两条软性约束，它们与硬性的 YAML 契约同等重要。

协作准则（Collaboration Guidelines）

• 与其它 Agent 协同以验证可行性（比如向 coder 确认某个拆分在技术上是可实现的）；
• 依据执行反馈持续修订计划（计划不是一次性产物，而是随执行滚动更新的活文档）；
• 维持清晰的沟通渠道；
• 记录所有规划决策（记录路径同样是协调记忆）。

最佳实践（Best Practices）

1. 计划必须满足四条标准：
   • Specific and actionable（具体可执行）——每个任务都能被无歧义地执行；
   • Measurable and time-bound（可度量、有时限）——能靠 estimated_time 与 success_criteria 判定进展与完成；
   • Realistic and achievable（现实可达）——资源与工期估计不脱离实际；
   • Flexible and adaptable（灵活可调）——保留面对变更的缓冲。
2. 规划时需通盘考虑：可用资源与约束、团队能力与负载、外部依赖与阻塞、质量标准与需求。
3. 优化目标：尽可能并行执行、Agent 之间有清晰的交接（handoffs）、资源利用高效、进度全程可见。

文档最后一句 "A good plan executed now is better than a perfect plan executed never"（一个现在就能执行的好计划，胜过永远执行不了的完美计划）点明了 planner 的实践哲学：规划服务于执行，而不是为了形式上的完美无限推迟开工。

结合仓库源码看 planner 的落地生态

虽然 .claude/agents/core/planner.md 本身是 Agent 定义文档，但仓库中存在多个与之配套、可印证其运作方式的实现：

• 任务生命周期工具链：v3/@claude-flow/cli/src/mcp-tools/task-tools.ts 提供了 task_create、task_list、task_status、task_update、task_assign、task_complete、task_cancel、task_retry 等完整工具。planner 拆解出的任务经 task_create 创建后，即可被 task_assign 分配给指定 Agent、用 task_status 轮询进展、以 task_complete 收口，并以 task_retry 重建失败任务——这套闭环与文档中"编排 → 状态监控"的调用序列是互相呼应的。
• CLI 命令入口：.claude/commands/coordination/task-orchestrate.md 定义了 npx claude-flow task orchestrate，其参数 --task、--strategy、--priority（low|medium|high|critical）与 MCP 调用示例高度一致，提供了不依赖 MCP 客户端的命令行编排路径。
• 多 Agent 角色协同：规划阶段可参考 .claude/agents/core/researcher.md 的角色能力决定是否需要前置调研任务；执行交接对象则可从 coder.md、tester.md、reviewer.md 等核心角色中选择。coredir 还提供了一批可直接复用的计划模板，如 .claude/agents/templates/orchestrator-task.md 与 migration-plan.md，可作为规划输出的起步骨架。
• 插件生态中的映射：plugin/agents/core 目录同样提供了 planner 的插件化变体，说明该角色已被抽象为可在不同部署形态间复用的标准件。

结语：把 planner 用好的三个要点

综合原文档与仓库实现，要让 planner 真正提升多 Agent 协作质量，可以抓住三个要点：

1. 先契约后执行：规划结果严格套用 YAML 契约（objective / phases / tasks / critical_path / risks / success_criteria），为每个子任务补齐 id、agent、dependencies、estimated_time、priority，确保可被下层任务系统直接消费；
2. 一切协调走记忆：任务分解、规划状态、进度更新都通过 memory_usage 写入 coordination 命名空间，使 planner 的决策对所有 Agent 透明、可回溯、跨会话可用；
3. 把计划当作活文档：依据 coder/tester 的执行反馈与 task_status 的进展回写不断修订计划，让规划与执行形成正反馈循环。

ruflo 的 planner 角色定义本身并不复杂，但正是这种"分工明确、契约统一、记忆共享"的设计，构成了可扩展、可监控、可持续改进的多智能体协作基础。