ruflo GOAP 目标规划器：agent-goal-planner 技能的 A* 状态空间搜索、自适应重规划与 MCP 编排实践

本文以 agent-goal-planner 技能定义文件 为核心，系统讲解 ruflo（claude-flow）中基于目标导向行动规划（GOAP）的 Agent 技能设计：它如何用 A* 算法在强类型状态空间中发现最优行动序列，如何通过 OODA 循环实现执行监控与动态重规划，以及它如何借助 task_orchestrate、swarm_init、memory_usage 三个 MCP 工具把规划结果落地为真实的多智能体编排。读完本文，你将掌握该技能的完整方法论、仓库中 GOAPPlanner 的源码级实现，以及技能在 Codex CLI 环境下的启用方式。

一、技能定位：一个 GOAP 专家的 Agent 技能

agent-goal-planner 是 ruflo 仓库 .agents/skills/ 目录下的一个 Agent 技能。按照 .agents/README.md 的说明，.agents/ 目录存放 OpenAI Codex CLI 的 Agent 配置与技能，技能通过 $skill-name 语法调用，每个技能目录包含一个带 YAML frontmatter 的 SKILL.md。该技能的 frontmatter 结构如下：

name: agent-goal-planner
description: Agent skill for goal-planner - invoke with $agent-goal-planner
---
name: goal-planner
description: "Goal-Oriented Action Planning (GOAP) specialist that dynamically
  creates intelligent plans to achieve complex objectives..."
color: purple

从源码结构看，技能采用双层命名：外层 agent-goal-planner 是 Codex 侧的调用入口（$agent-goal-planner），内层 goal-planner 定义了角色本体——一个把游戏 AI 中的 GOAP 技术与实际软件工程结合的规划器，目标是"通过创造性的行动组合发现新解"，擅长自适应重规划、多步推理和在复杂状态空间中寻找最优路径。

1.1 十一项核心能力

技能原文完整定义了 11 项核心能力，这是理解该技能职责边界的关键：

能力	说明
Dynamic Planning（动态规划）	使用 A* 搜索算法在状态空间中寻找最优路径
Precondition Analysis（前置条件分析）	评估每个行动的需求与依赖
Effect Prediction（效果预测）	建模行动如何改变世界状态
Adaptive Replanning（自适应重规划）	根据执行结果与条件变化调整计划
Goal Decomposition（目标分解）	把复杂目标拆解为可达成子目标
Cost Optimization（成本优化）	考虑行动代价，寻找最高效路径
Novel Solution Discovery（新解发现）	以创造性方式组合已有行动
Mixed Execution（混合执行）	融合 LLM 推理与确定性代码行动
Tool Group Management（工具组管理）	将行动匹配到可用工具与能力
Domain Modeling（领域建模）	基于强类型的状态表示
Continuous Learning（持续学习）	根据执行反馈更新规划策略

值得注意的是 "Mixed Execution" 与 "Tool Group Management" 两条：从技能文本可以推断，该规划器并非纯 LLM 推理，而是把 LLM 生成的推理步骤与确定性代码行动（仓库中的工具调用）混合编排，并把抽象行动绑定到实际可用工具组——这正是它与仓库内 MCP 工具集对接的接口。

二、五步规划方法论：从状态评估到动态重规划

技能定义了一套完整的 GOAP 规划流程，共五个阶段。

2.1 State Assessment（状态评估）

• 分析当前世界状态（现在什么是真的）；
• 定义目标状态（什么应当为真）；
• 识别当前状态与目标状态之间的差距。

2.2 Action Analysis（行动分析）

• 清点所有可用行动及其前置条件与效果；
• 判断哪些行动在当前状态下可应用；
• 计算行动的成本与优先级。

2.3 Plan Generation（计划生成）

• 使用 A* 寻路搜索所有可能的行动序列；
• 按成本与到目标的启发式距离评估路径；
• 生成能把当前状态变换为目标状态的最优计划。

2.4 Execution Monitoring（执行监控，OODA 循环）

技能明确用 OODA（Observe–Orient–Decide–Act）循环监控执行：

1. Observe：监控当前状态与执行进度；
2. Orient：分析变化与相对预期状态的偏差；
3. Decide：判断是否需要重规划；
4. Act：执行下一个行动，或触发重规划。

2.5 Dynamic Replanning（动态重规划）

• 检测行动失败或产生意外结果；
• 从新的当前状态重新计算最优路径；
• 适应变化的条件与新信息。

这套方法论在仓库中有真实的代码对应物。v3/goal_ui/src/lib/goapPlanner.ts 中的 GOAPPlanner 类正是技能所述"A* + 前置条件 + 效果建模"的可执行实现，下文逐条对照。

三、源码级原理：GOAPPlanner 如何执行 A* 搜索

goapPlanner.ts 定义了一个完整的 GOAP 规划器，其结构与技能方法论一一对应。

3.1 强类型世界状态与行动模型

文件定义了 WorldState 接口（第 26–35 行），每个维度是一个布尔标志，例如：

interface WorldState {
  goalDefined: boolean;
  goalParsed: boolean;
  stateAssessed: boolean;
  informationGathered: boolean;
  documentsAnalyzed: boolean;
  knowledgeSynthesized: boolean;
  insightsGenerated: boolean;
  verified: boolean;
}

Action 接口（第 37–43 行）则把技能中的"前置条件/效果/成本"三要素落实为字段：

interface Action {
  name: string;
  cost: number;
  preconditions: Partial<WorldState>;
  effects: Partial<WorldState>;
  stepGenerator: (goal: string) => Step;
}

每个行动除了成本、前置条件和效果外，还携带一个 stepGenerator，把抽象行动展开为带标题、描述、状态（pending | active | completed | error）的展示步骤——这就是技能所说"行动与工具/能力匹配"的呈现层。

3.2 启发式函数：未满足条件计数

heuristic 方法（第 59–67 行）计算"到目标的距离"：遍历目标状态的每个键，目标为真而当前状态为假的维度计数 +1。这是一个典型的 GOAP 启发式——可证明它从不超过真实剩余成本（每个行动至多把若干未满足维度翻真），满足 A* 可采纳性要求。

3.3 前置条件检查与效果应用

preconditionsMet（第 72–79 行）要求前置条件中所有为 true 的键在当前状态里也为真才允许行动；applyEffects（第 84–86 行）用对象展开把行动效果合并进状态。这两者共同保证了状态转移的合法性。

3.4 A* 主循环

plan 方法（第 91–146 行）是核心。其执行逻辑：

1. 以当前状态构建开放列表（openList）起始节点，成本为 0；
2. 每轮按 cost + heuristic（即 f 值）对开放列表排序，取最小节点扩展；
3. 若节点状态的启发式距离为 0（目标达成），把路径上的行动映射为 Step[] 返回；
4. 用 JSON.stringify(state) 作为状态键维护闭合列表（closedList），避免重复扩展；
5. 对每个前置条件满足的行动，生成新状态节点，成本累加行动代价后入开放列表；
6. 若开放列表耗尽仍未达成目标，返回空数组——由调用方决定回退策略。

public plan(currentState: WorldState, goalState: WorldState, userGoal: string): Step[] {
  // openList 按 cost + heuristic 排序，closedList 去重
  while (openList.length > 0) {
    openList.sort((a, b) => (a.cost + a.heuristic) - (b.cost + b.heuristic));
    const current = openList.shift()!;
    if (this.heuristic(current.state, goalState) === 0) {
      return current.actions.map(action => action.stepGenerator(userGoal));
    }
    // 扩展所有 preconditionsMet 的行动...
  }
  return []; // 无可行计划
}

同文件还导出了 parseGoal（第 152–180 行）：从自然语言目标中抽取领域（technology/business/software engineering/energy）、动作类型（research/analyze/investigate/compare/evaluate）与关键词，作为技能中 "Goal Decomposition" 能力的轻量实现。

3.5 规划配置：重规划触发器与并行执行

goal_ui 的 Index 页面 给出了规划器的默认研究配置，恰好把技能方法论中的重规划与成本优化落实为可配置参数：

goapConfig: {
  executionMode: "closed",
  enableReplanning: true,
  replanningTriggers: ["Action failure", "Low confidence results", "Missing preconditions"],
  costOptimization: true,
  parallelExecution: true,
},
actionConfig: {
  maxActionCost: 5,
  enableFallbacks: true,
  validatePreconditions: true,
  trackEffects: true,
},
parameters: {
  maxSources: 15,
  minConfidence: 85,
  maxSteps: 7,
  parallelAgents: 3,
  timeout: 120,
}

其中 replanningTriggers 的三项——行动失败、低置信度结果、前置条件缺失——与技能第 5 步 "Dynamic Replanning" 的三条检测条件逐条对应；actionConfig.maxActionCost: 5 与 validatePreconditions: true 则对应第 2 步 "Action Analysis" 中的成本计算与前置条件判定。配合 GOAPConfigDisplay 与 StateAssessmentCard 等组件，状态评估和 GOAP 配置在 UI 层也是显式可见的。

四、MCP 集成：把规划结果变成真实编排

技能文档末尾给出了三个 MCP 集成示例，它们对应仓库 v3/mcp/tools/v2-compat-tools.ts 中真实注册的工具。下面逐一说明其参数与底层映射关系。

4.1 task_orchestrate：编排复杂目标达成

// Orchestrate complex goal achievement
mcp__claude-flow__task_orchestrate {
  task: "achieve_production_deployment",
  strategy: "adaptive",
  priority: "high"
}

在 v2-compat-tools.ts 中，task_orchestrate 是 V2 兼容工具，注释明确标注其映射到 V3 的 tasks/create。规划器产出的最优行动序列就是通过这类任务编排工具下发执行的，strategy 参数支持 adaptive，与技能"根据执行结果调整计划"的定位一致。

4.2 swarm_init：并行规划所需的蜂群拓扑

// Coordinate with swarm for parallel planning
mcp__claude-flow__swarm_init {
  topology: "hierarchical",
  maxAgents: 5
}

swarm_init 工具的 inputSchema（v2-compat-tools.ts）为示例中的两个参数提供了完整约束：

• topology（必填）：枚举 mesh | hierarchical | ring | star | adaptive | collective | hierarchical-mesh；
• maxAgents：取值 1–100，schema 默认值 5；
• strategy：balanced | specialized | adaptive，schema 默认 balanced，其 handler 会把它翻译成 V3 的 loadBalancing（balanced 时为 true）与 autoScaling（adaptive 时为 true）配置。

该工具标记为 deprecated: true，官方建议改用 swarm/init。这一点与 .agents/config.toml 中 [swarm] 段的默认值相互印证：default_topology = "hierarchical"、default_strategy = "specialized"、consensus = "raft"、anti_drift = true、checkpoint_interval = 10（每 10 个任务做检查点）——后者正是支撑 OODA 监控与重规划的基础设施。

4.3 memory_usage：沉淀可复用计划

// Store successful plans for reuse
mcp__claude-flow__memory_usage {
  action: "store",
  namespace: "goap-plans",
  key: "deployment_plan_v1",
  value: JSON.stringify(successful_plan)
}

memory_usage 是 V2 兼容工具，映射到 V3 的 memory/store（action: "search" 时映射 memory/search，见 v2-compat-tools.ts 的映射表）。技能在 "Continuous Learning" 能力中要求"根据执行反馈更新规划策略"，这里给出了具体落点：把成功计划以 goap-plans 命名空间存入记忆库，后续同类目标可直接复用或作为搜索起点，形成"规划 → 执行 → 存储 → 复用"的闭环。

需要说明的是，这三个 mcp__claude-flow__* 前缀工具均属于 V2 兼容层（工具 version: "2.0.0"、deprecated: true），在当前仓库的 V3 工具集中应优先使用 tasks/create、swarm/init、memory/store 等新名称；技能文档保留旧名是出于向后兼容演示。

五、启用方式：在 Codex CLI 中挂载该技能

按 .agents/README.md 的结构约定，.agents/skills/<skill-name>/SKILL.md 即技能本体，[[skills.config]] 条目控制启用。.agents/config.toml 展示了 Codex 与 claude-flow 的接入配置：

[mcp_servers.claude-flow]
command = "npx"
args = ["-y", "@claude-flow/cli@latest"]
enabled = true
tool_timeout_sec = 120

该配置通过 npx @claude-flow/cli 启动 claude-flow 的 MCP 服务器，工具超时 120 秒。文件中现有的四个 [[skills.config]] 条目启用了 swarm-orchestration、memory-management、sparc-methodology、security-audit 四个技能目录；按同样格式为 .agents/skills/agent-goal-planner 增加一条 enabled = true 的条目，即可在 Codex 会话中通过 $agent-goal-planner 触发该 GOAP 规划技能（本仓库为只读环境，此处仅说明配置方式）。同一文件的 [performance] 段还限制了 max_agents = 8、task_timeout = 300 秒，这些全局上限会作用于技能中 swarm_init 请求的并行规模，使用时应留意 maxAgents 不超过这些边界。

六、小结

agent-goal-planner 技能把游戏 AI 领域的 GOAP 范式完整地移植到了多智能体工程场景：以强类型布尔状态为世界的表示，以"前置条件 + 效果 + 成本"三元组描述行动，用 A* 搜索生成最优计划，用 OODA 循环监控执行并在失败、低置信度、前置条件缺失三类信号出现时动态重规划，最终通过 task_orchestrate / swarm_init / memory_usage 三组 MCP 工具把抽象计划转化为任务编排、蜂群协作与经验沉淀。仓库中的 GOAPPlanner 实现、goal_ui 规划配置 与 V2 兼容 MCP 工具 分别对应方法论的算法层、配置层与集成层，三者共同构成了一条从"目标描述"到"可执行、可复用、可复现"的完整链路。