ruflo 的 agent-planner 技能解析：从任务分解到蜂群任务编排的策略规划 Agent

在 ruflo（一个多智能体 meta-harness 框架）中，planner 是承担"战略拆解 + 任务编排"职责的核心协调者。本文基于 agent-planner 技能定义 展开，完整讲解其角色设定、五步规划流程、标准 YAML 计划输出格式，以及它如何通过 task_orchestrate、memory_usage、task_status 等 MCP 工具与蜂群（swarm）中的其他 Agent 协同执行。读完后你将能够：理解 planner 技能的 frontmatter 结构与 hooks 机制，掌握其计划产出格式，并能对照仓库中 MCP 工具的真实实现验证调用参数。

技能文件结构：双重 frontmatter 与调用方式

agent-planner/SKILL.md 位于 .agents/skills/ 目录下。根据 .agents/README.md 的说明，ruflo 的 Codex CLI 集成采用如下目录约定：config.toml 控制模型选择、审批策略、沙箱模式、MCP 连接与技能配置，而 skills/<skill-name>/SKILL.md 是技能指令文件，技能通过 $skill-name 语法调用——因此本技能可通过 $agent-planner 触发。

该文件由两段 YAML frontmatter 组成，分别承担"技能元数据"和"Agent 定义"两种角色：

第一段是技能包装元数据：

---
name: agent-planner
description: Agent skill for planner - invoke with $agent-planner
---

第二段是 planner Agent 本身的定义，声明了类型、能力集、优先级与生命周期 hooks：

---
name: planner
type: coordinator
color: "#4ECDC4"
description: Strategic planning and task orchestration agent
capabilities:
  - task_decomposition
  - dependency_analysis
  - resource_allocation
  - timeline_estimation
  - risk_assessment
priority: high
hooks:
  pre: |
    echo "🎯 Planning agent activated for: $TASK"
    memory_store "planner_start_$(date +%s)" "Started planning: $TASK"
  post: |
    echo "✅ Planning complete"
    memory_store "planner_end_$(date +%s)" "Completed planning: $TASK"
---

几个值得注意的设计点：

• type: coordinator：planner 不是直接产出代码的 worker，而是协调者（coordinator），职责是规划与分派，这与其"战略规划和任务编排"的定位一致；
• 五项 capabilities：任务分解、依赖分析、资源分配、时间线估算、风险评估，构成 planner 的能力边界；
• priority: high：表明在蜂群优先级调度中 planner 任务优先处理；
• hooks.pre / hooks.post：在规划开始前和结束后分别写入 planner_start_* / planner_end_* 记忆条目，使规划过程本身可被记忆系统追踪。这与后文 MCP 部分"Always coordinate through memory（始终通过记忆进行协调）"的原则一脉相承。

核心职责：planner 的五项任务

技能正文以"You are a strategic planning specialist（你是战略规划专家）"为系统角色设定，随后列出五项核心职责（完整继承自原文档）：

1. Task Analysis（任务分析）：将复杂请求分解为原子化、可执行的任务；
2. Dependency Mapping（依赖映射）：识别并记录任务间依赖与前置条件；
3. Resource Planning（资源规划）：确定所需的资源、工具与 Agent 分配；
4. Timeline Creation（时间线制定）：估算任务完成的现实时间范围；
5. Risk Assessment（风险评估）：识别潜在阻塞点与缓解策略。

这五项职责与 frontmatter 中 capabilities 声明一一对应，可以推断 ruflo 的技能规范鼓励"能力声明"与"职责描述"保持一致，便于蜂群调度时做能力匹配。

规划流程：从初步评估到风险缓解的五步法

原文档定义了标准化的五步规划流程，这是 planner 处理任何任务的固定工作流：

1. Initial Assessment（初步评估）

• 分析请求的完整范围；
• 识别关键目标与成功标准；
• 判断复杂度等级与所需专业能力。

2. Task Decomposition（任务分解）

• 拆解为具体、可度量的子任务；
• 确保每个任务有清晰的输入和输出；
• 建立逻辑分组与阶段划分（phases）。

3. Dependency Analysis（依赖分析）

• 绘制任务间依赖图；
• 识别关键路径（critical path）任务；
• 标记潜在瓶颈。

4. Resource Allocation（资源分配）

• 确定每个任务需要哪些 Agent 承接；
• 分配时间与计算资源；
• 尽可能规划并行执行。

5. Risk Mitigation（风险缓解）

• 识别潜在失败点；
• 制定应急预案（contingency plans）；
• 构建验证检查点（validation checkpoints）。

从流程设计看，这套五步法实际上把一个项目管理的完整闭环——范围界定、WBS 分解、关键路径、资源装载、风险登记——压缩进了 Agent 的规划上下文，为后文的结构化输出打下了骨架。

标准输出格式：计划必须长什么样

planner 的产出不是自由文本，而是严格的结构化 YAML 计划。原文档给出的标准模板如下（完整保留）：

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"

各字段的语义要点：

字段	含义	说明
objective	总体目标	一句话清晰描述要达成什么
phases[].tasks[].id	任务唯一标识	用于依赖引用与 MCP 工具中的 taskId 追踪
phases[].tasks[].agent	承接 Agent	指定哪个 Agent 处理该任务，实现"规划即分派"
dependencies	前置任务 ID 列表	驱动关键路径计算与执行顺序
estimated_time	时间估算	如 "15m"，支撑整体时间线汇总
priority	优先级	取值为 high / medium / low 三档
critical_path	关键路径	决定整体工期的任务链
risks	风险与缓解	每个风险必须附带 mitigation 应对方案
success_criteria	成功标准	必须可度量（measurable outcome）

这套格式的价值在于：它是机器可消费的——dependencies、agent、priority 都能直接映射到 MCP 任务工具与记忆系统的字段上，使计划能被蜂群调度器直接执行，而非仅给人阅读。

MCP 工具集成：把计划变成蜂群动作

技能文档定义了 planner 与蜂群交互的三类 MCP 调用。下面逐一还原原文档示例，并对照仓库中 MCP 工具的真实实现说明参数约束。

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"
}

这三个工具名并非虚构——它们在 v2-compat-tools.ts 中有完整的 V2 兼容实现（V2 下划线命名映射到 V3 斜杠命名，属于兼容性层）：

• task_orchestrate → tasks/create：入参 schema 要求 task（必填，任务描述或指令），strategy 取 parallel / sequential / adaptive（默认 adaptive），priority 取 low / medium / high / critical（默认 medium），maxAgents 范围 1～10。handler 会将请求包装为 type: 'orchestration' 的任务并透传 strategy 与 maxAgents 到 config（见 v2-compat-tools.ts L254-L281）。原文档示例中 strategy: "parallel"、priority: "high"、maxAgents: 5 均在合法取值范围内。
• task_status → tasks/status：入参 taskId（可选）与 detailed（布尔，默认 false）。当提供 taskId 时走单任务状态查询（detailed 控制是否附带子任务与指标），否则列出全部任务（见 v2-compat-tools.ts L286-L313）。
• memory_usage → memory/store / memory/search / memory/list：入参包括 action（必填，取 store / retrieve / delete / list）、key、value、namespace（默认 coordination）。store 动作会把 key 存储为 namespace/key 的组合键（见 v2-compat-tools.ts L351-L400）。原文档中 namespace: "coordination" 与实现默认值一致，key 采用 swarm$planner$... 的分段命名约定，用于在协调命名空间内标识"planner 的任务分解"。

值得强调的是，这些 V2 兼容工具在源码中均标注为 deprecated: true，官方推荐迁移到 V3 斜杠命名（tasks/create、tasks/status、memory/store 等）。V3 侧的 task-tools.ts 用 zod 定义了更完整的任务 schema：type、description、priority（整数 1～10，1 为最高优先，默认 5）、dependencies（任务 ID 数组）、assignToAgent / assignToAgentType（指定或按类型自动挑选承接 Agent）、timeout（毫秒）与 metadata。任务生命周期状态为 pending → queued → assigned → running → completed / failed / cancelled（见 task-tools.ts L126）。

对照 planner 的 YAML 计划格式可以发现清晰的映射关系：计划中的 tasks[].id / dependencies 对应 tasks/create 的 dependencies 参数，tasks[].agent 对应 assignToAgentType，tasks[].priority（high/medium/low）对应 V3 的 1～10 数值优先级。也就是说，planner 的产出格式与蜂群任务系统的数据模型是同一套概念。

Memory Coordination（记忆协调）

原文档还定义了 planner 上报自身规划状态的标准动作：

// 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 把"当前正在规划、已规划 12 个任务、预计 24 小时"写入 coordination 命名空间，供其他 Agent 查询整体进度。结合 hooks 中的 memory_store "planner_start_..." / "planner_end_..." 调用，planner 的状态可见性来自三个层次：pre/post hook 的起止事件、swarm$planner$status 的周期性状态快照、swarm$planner$task-breakdown 的任务分解数据。文档结尾的原则"A good plan executed now is better than a perfect plan executed never（一份立即执行的合格计划，好过一份永不执行的完美计划）……Always coordinate through memory（始终通过记忆进行协调）"正是这套机制的设计哲学。

协作准则与最佳实践

原文档为 planner 定义了三组行为约束（完整继承）：

协作准则（Collaboration Guidelines）

• 与其他 Agent 协调以验证方案可行性；
• 根据执行反馈更新计划；
• 保持清晰的沟通渠道；
• 记录所有规划决策。

最佳实践（Best Practices）

计划必须满足四个性质：具体可行动（specific and actionable）、可度量有时限（measurable and time-bound）、现实可达（realistic and achievable）、灵活可调整（flexible and adaptable）；

规划时需要考虑：可用资源与约束、团队能力与负载、外部依赖与阻塞、质量标准与要求；

优化方向：尽可能并行执行、Agent 之间清晰的交接（handoffs）、高效的资源利用、持续可见的进度。

这些准则与五步流程中的"验证检查点"和"并行执行规划"呼应，共同约束 planner 输出"能驱动进度"的计划，而非纸面方案。

运行上下文：planner 技能所在的 Codex 配置环境

.agents 目录下的技能需要宿主配置才能生效。.agents/README.md 说明 config.toml 控制模型选择、审批策略、沙箱模式、MCP 服务器连接与技能配置。仓库中现有的 config.toml 是一个由 @claude-flow/codex 生成的 Claude Flow V3 Codex 配置示例，其中与 planner 技能运行相关的关键项包括：

• approval_policy：取值 untrusted（总是需要审批）/ on-failure（失败后审批）/ on-request（重大变更时审批）/ never（自动批准）。示例中为 "on-request"，意味着 planner 触发的高影响编排动作会请求人工确认；
• sandbox_mode：取值 read-only / workspace-write / danger-full-access，示例中为 "workspace-write"，即 Agent 只能在工作区内写文件；
• model、web_search：模型选择（如 gpt-5.3-codex、claude-sonnet 等）与联网检索策略（disabled / cached / live）；
• project_doc_max_bytes 与 project_doc_fallback_filenames：控制从 AGENTS.md 等文档读取的字节上限与回退文件名。

从源码结构看，这套配置与技能体系是分工的：config.toml 决定"Agent 能在什么权限边界内行动"，skills/*/SKILL.md 决定"Agent 如何思考与产出"，而 MCP 工具层（v3/mcp/tools/）提供两者之间实际执行动作的通道。planner 作为 type: coordinator 的高优先级技能，其计划经由 tasks/create 落地为任务、经由 memory/* 落地为共享状态，就在这个权限边界内运行。

小结

agent-planner 是 ruflo 中一个"声明式规划角色 + 结构化计划格式 + 记忆化协调"三位一体的技能：frontmatter 声明其协调者身份与能力集，五步流程约束其思考路径，YAML 计划模板固定其产出格式，而 task_orchestrate / memory_usage / task_status 三个 MCP 调用把计划接入真实的蜂群任务系统（V2 兼容层在 v2-compat-tools.ts，V3 任务模型在 task-tools.ts）。如果你想深入，可以从 SKILL.md 本身出发，沿 tasks/*、memory/* 工具实现与 .agents 目录约定 继续阅读仓库中的编排细节。