RuView goal-planner Agent：基于 GOAP 算法的 AI 动态目标规划引擎

在 RuView 这个把 WiFi 信号转化为空间智能与生命体征监测能力的项目中，开发过程本身也高度依赖 AI 智能体协同：大量 ADR（架构决策记录）之间存在密集依赖，需要规划"下一步先做什么"。.claude/agents/goal/goal-planner.md 定义了 claude-flow 智能体集群中的 Goal Planner——一个专门使用目标导向行动规划（GOAP, Goal-Oriented Action Planning）算法动态生成最优行动序列的专家 Agent。读完本文，你将理解该 Agent 的完整能力模型、五步 GOAP 规划方法论（含 A* 搜索与 OODA 闭环）、与 MCP 编排工具的集成方式，以及它在本仓库中与 ADR-038 所设计的 sublinear GOAP 路线图规划系统的对应关系。

一、Agent 的定义与定位

goal-planner 是 Claude Code Agent 定义文件，采用"YAML frontmatter + Markdown 提示词正文"的标准结构，位于 .claude/agents/goal/goal-planner.md。其 frontmatter 声明了三个字段：

---
name: goal-planner
description: "Goal-Oriented Action Planning (GOAP) specialist that dynamically creates
  intelligent plans to achieve complex objectives. Uses gaming AI techniques to discover
  novel solutions by combining actions in creative ways. Excels at adaptive replanning,
  multi-step reasoning, and finding optimal paths through complex state spaces."
color: purple
---

• name：Agent 的唯一标识，供编排器（如 swarm 协调器）在 agent_spawn / task_orchestrate 时引用；
• description：能力描述，既是给开发者看的说明，也用于 Agent 路由时判断"什么任务该派给它"；
• color：在监控/可视化界面中显示该 Agent 的颜色。

从目录结构看，它处于 goal/ 分类下，与同目录的 sublinear-goal-planner（一个使用 sublinear 矩阵求解器做 PageRank 优先级和时域优势预测的进阶版本）构成"基础版 + 进阶版"的规划能力组合；而 core/planner.md 则属于通用核心 Agent 层。这种分层组织体现了 claude-flow 框架"通用 Agent 打底、领域专家 Agent 增强"的设计思路。

GOAP 本身源自游戏 AI 领域（Jeff Orkin，2003 年，最初用于《F.E.A.R.》的敌人行为系统）：把世界建模为一组布尔/数值状态属性，把每个行为（Action）定义为"前置条件 + 效果 + 代价"，然后由规划器从当前状态搜索到目标状态的最优行动路径。goal-planner 把这套游戏 AI 技术与软件工程实践结合，用于"通过创造性组合已知动作来发现新颖解法"。

二、十一项核心能力

文档正文开篇列出了 goal-planner 的完整能力清单，这十一项能力可以归纳为四个层面：

搜索与推理层

• Dynamic Planning（动态规划）：使用 A* 搜索算法在状态空间中发现最优路径；
• Precondition Analysis（前置条件分析）：评估每个动作的要求与依赖关系；
• Effect Prediction（效果预测）：建模动作执行后世界状态如何改变；
• Goal Decomposition（目标分解）：把复杂目标拆解为可实现的子目标；
• Cost Optimization（代价优化）：综合考虑动作代价，寻找最高效路径。

自适应层

• Adaptive Replanning（自适应重规划）：根据执行结果和变化中的条件调整计划；
• Continuous Learning（持续学习）：基于执行反馈更新规划策略。

执行融合层

• Mixed Execution（混合执行）：把基于 LLM 的推理与确定性代码动作混合使用——这是该 Agent 区别于纯经典规划器的关键特征：既有可验证的确定性动作，又有 LLM 处理长尾情况的能力；
• Novel Solution Discovery（新颖解发现）：以创造性的方式组合已知动作。

系统对接层

• Tool Group Management（工具组管理）：把动作匹配到当前可用的工具和系统能力；
• Domain Modeling（领域建模）：使用强类型的状态表示进行工作，保证状态语义不歧义。

三、GOAP 五步规划方法论

goal-planner 的工作流程严格遵循 GOAP 算法的五阶段闭环，这是文档的核心骨架：

3.1 状态评估（State Assessment）

规划的第一步是弄清"现在有什么"和"要到达哪里"：

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

3.2 动作分析（Action Analysis）

• 盘点所有可用动作及其前置条件与效果；
• 判定哪些动作在当前状态下是可应用的（preconditions 全部满足）；
• 计算各动作的代价与优先级。

3.3 计划生成（Plan Generation）

• 使用 A* 路径搜索算法遍历可能的动作序列；
• 基于"已付出代价 + 启发式目标距离"（即 A* 的经典 f = g + h 评估）对候选路径打分；
• 生成一条能把当前状态变换到目标状态的最优计划。

3.4 执行监控：OODA 循环（Execution Monitoring）

goal-planner 不是"生成计划后撒手不管"，而是以 OODA 循环持续监控执行过程：

阶段	含义
Observe（观察）	监控当前状态与执行进度
Orient（定向）	分析状态变化与预期状态的偏差
Decide（决策）	判断是否需要重新规划
Act（行动）	执行下一个动作，或触发重规划

3.5 动态重规划（Dynamic Replanning）

• 检测到动作失败或产生非预期结果时自动介入；
• 从新的当前状态重新计算最优路径；
• 适应条件变化与新信息。

这套"评估→分析→生成→监控→重规划"的方法论保证了规划是在线的、闭环的，而非一次性静态输出。

四、MCP 集成示例：编排、协作与记忆复用

文档给出了三段 MCP（Model Context Protocol）工具调用示例，展示了 goal-planner 如何与 claude-flow 生态对接：

// 1. 编排复杂目标的达成
mcp__claude-flow__task_orchestrate {
  task: "achieve_production_deployment",
  strategy: "adaptive",      // 自适应策略：允许执行中重规划
  priority: "high"
}

// 2. 初始化分层集群进行并行规划
mcp__claude-flow__swarm_init {
  topology: "hierarchical",  // 分层拓扑：协调者 + 专职 Agent
  maxAgents: 5
}

// 3. 把成功规划存入记忆，供后续复用
mcp__claude-flow__memory_usage {
  action: "store",
  namespace: "goap-plans",
  key: "deployment_plan_v1",
  value: JSON.stringify(successful_plan)
}

三个调用分别对应三个关键环节：

1. task_orchestrate——以 adaptive 策略启动一个任务编排，priority: "high" 使其在资源竞争中获得优先调度。adaptive 策略与上文 OODA 重规划能力相呼应：编排器允许在执行过程中根据反馈调整行动序列；
2. swarm_init——用 hierarchical（分层）拓扑初始化最多 5 个 Agent 的集群，实现"并行规划"：协调者统筹，专职 Agent 分头处理子目标；
3. memory_usage——把成功的规划以 goap-plans 命名空间 + deployment_plan_v1 键持久化。这实现了能力清单中"Continuous Learning"的落地机制：同类目标再次出现时，先检索历史成功计划作为候选，再做增量修正。

五、在本仓库中的落点：从 Agent 定义到 ADR 路线图规划

goal-planner 不是孤立存在的提示词文件——在 RuView 仓库中，GOAP 规划思想有明确的工程化落点：docs/adr/ADR-038-sublinear-goal-oriented-action-planning.md（ADR-038：Sublinear Goal-Oriented Action Planning for Project Roadmap Optimization，状态 Proposed）把这套方法论完整应用到了项目自身的研发路线图规划上。对照阅读可以看清 Agent 能力如何映射为系统实现：

问题场景：RuView（WiFi-DensePose）当时有 37 份 ADR，14 份已接受/完成、19 份处于 Proposed、1 份被取代，且 ADR 之间依赖密集（例如 ADR-037 多人姿态依赖 ADR-014 信号处理、ADR-024 对比嵌入与 ADR-029 多站组网）。单开发者（或 AI Agent 小组）需要回答"下一步构建什么"，这正是 goal-planner 的目标分解 + 前置条件分析能力的真实用例。

世界状态建模：ADR-038 定义了一个扁平的类型化状态地图，分三类属性——布尔功能标志（如 sota_signal_processing、esp32_firmware_base、aether_embeddings，每类都给出"事实来源"，例如某 crate 的 cargo test 是否通过）、硬件可用性标志（esp32_connected、gpu_available 等，通过 USB 序列口探测、nvidia-smi 检测）、数值质量指标（pose_accuracy_pck02、breathing_snr_db 等）。这就是 goal-planner 能力清单中"Domain Modeling：强类型状态表示"的具体形态。

动作目录：每个 ADR 实现阶段被建模为一个动作，结构包含前置条件、效果、以"开发者-天"计的代价、所需硬件与所需 Agent 类型，例如：

动作 ID	ADR	代价（天）	前置条件	效果	硬件
adr037_p1_person_count	037	3	sota_signal_processing	person_count_estimation = true	无
adr037_p4_neural_multi	037	10	signal_decomposition、aether_embeddings、gpu_available	multi_person_neural = true	GPU
adr021_vital_esp32	021	5	vital_signs_extraction、esp32_connected	vital_signs_esp32_validated = true	ESP32
adr029_p3_multistatic	029	5	multi_band_fusion、esp32_multistatic_ready	multistatic_mesh = true	2+ ESP32

其中硬件前置条件直接体现了 goal-planner"把动作匹配到可用工具/能力"（Tool Group Management）的思想：ESP32 或 GPU 不可用时，相关动作自动被排除，避免生成"死胡同"计划。

从朴素 A* 到 sublinear 优化：goal-planner 文档描述的是经典 A* 搜索，而 ADR-038 给出了针对本项目状态空间规模的三条子线性优化，二者是"通用方法论 → 特定工程实现"的递进关系：

组件	朴素 GOAP	子线性 GOAP（ADR-038 方案）
状态空间	2^N（N=25 布尔量）≈ 3300 万	剪枝到相关动作子集
每次扩展评估的动作数	全部约 80 个	5–15 个（向后相关性剪枝）
搜索深度	最长 15	最长 4（按 ADR 依赖分 Tier 0–3 层次分解）
重规划代价	全量重搜	仅增量修补（invalidation → patch → merge）
典型规划耗时	约 100ms	< 5ms

具体技术包括：① 向后相关性剪枝（backward relevance pruning，从目标条件反向推导，通常把约 80 个动作缩减到 5–15 个）；② 按 ADR 依赖关系将动作分为 Tier 0（基础）到 Tier 3（集成）四层，层内动作可并行规划，把有效搜索深度从约 15 压到约 4；③ 增量重规划——状态变化（测试开始通过、硬件插入）时只对失效部分打补丁。

执行监控的对应：ADR-038 的执行协议与 goal-planner 的 OODA 循环逐环节对应：PRE-CHECK（观察前置条件，不满足即重规划）→ DISPATCH（派发给对应类型 Agent）→ EXECUTE → VERIFY（tester Agent 观察状态）→ UPDATE（效果达成则更新状态）→ REPLAN（效果未达成则标记失败并重规划）。规划器以 goap-coordinator 身份运行在分层集群中，下辖 researcher / coder / tester / reviewer 等专职 Agent，与 goal-planner 示例中 swarm_init { topology: "hierarchical" } 的拓扑完全一致。

PageRank"下一步做什么"：当用户没有指定具体目标而问"接下来该做什么"时，规划器在动作依赖图上跑 PageRank（damping 0.85），得分最高的动作是"承重"动作——解锁的下游工作最多；最终按 PageRank_score × (1/cost_days)（单位投入的价值）排序返回 Top-K。仓库中 sublinear/pagerank-analyzer.md 正是负责这类图分析计算的专职 Agent（通过 mcp__sublinear-time-solver__pageRank 等工具），与 goal-planner 形成能力互补。

进阶变体 sublinear-goal-planner：同目录下的 goal/agent.md（name 为 sublinear-goal-planner）是 goal-planner 的数学化增强版，展示了 GOAP 的完整实现链路：世界状态与动作目录的 JavaScript 建模（WorldState 当前/目标状态 Map + 带 cost/preconditions/effects 的 Actions 数组）、动作图邻接矩阵构建（边权取动作代价的倒数并调用 analyzeMatrix 检查矩阵性质）、PageRank 目标优先级、A* 搜索中用子线性求解器优化启发式函数、OODA 循环的 DynamicPlanner 类实现（1 秒周期 observe→orient→decide→act，偏差显著时触发 replan 并把成功模式写入 goap-patterns 记忆命名空间）、以及行为树（GOAPBehaviorTree）与效用函数动作选择（时间/代价/风险/目标对齐四维加权）。这可以视为 goal-planner 文档中"Dynamic Planning + Adaptive Replanning"两项能力的一份可运行参考实现。

CLI 与记忆持久化：ADR-038 还规划了面向开发者的命令行入口，把 Agent 能力暴露为可复用的终端操作：

# 为目标生成动作序列
npx @claude-flow/cli@latest goap plan --goal "multi-person tracking"
# 快照当前世界状态
npx @claude-flow/cli@latest goap observe
# PageRank 式的"下一步"推荐
npx @claude-flow/cli@latest goap prioritize --top-k 5
# 通过集群执行计划
npx @claude-flow/cli@latest goap execute --goal "vital sign monitoring"
# 导出 DOT 依赖图
npx @claude-flow/cli@latest goap graph --format dot > goap.dot

世界状态与计划进度持久化在 claude-flow memory 系统的 goap 命名空间下（world-state / current-plan 键），从而获得跨会话连续性——规划器下次启动时可从上次的进度恢复。这与 goal-planner 文档中 memory_usage { namespace: "goap-plans" } 的示例是同一机制在两种场景下的体现。

六、工程集成与运行前提

从仓库结构看，该 Agent 体系是 claude-flow 工作流框架的一部分，而非独立的运行时：

• .claude/settings.json 配置了 PreToolUse（Bash 命令前置检查）、PostToolUse（Write/Edit 后置处理）、UserPromptSubmit（路由）、SessionStart/SessionEnd（会话恢复与记忆同步）等钩子，均指向 helpers/hook-handler.cjs 等脚本——这些钩子为 Agent 集群提供状态观察与学习反馈通道，与 ADR-038 集成点表中"claude-flow hooks：pre-task/post-task 触发状态观察"一一对应；
• 状态观察依赖仓库内可验证的事实来源：cargo test 输出、USB 设备枚举、关键源文件存在性检查等，并按 TTL 缓存（例如 cargo test 结果缓存 10 分钟、硬件探测缓存 30 秒），以平衡观察开销与状态新鲜度；
• 同目录下 swarm/hierarchical-coordinator.md 等集群协调器 Agent 定义了 goal-planner 所初始化集群的拓扑行为，templates/ 则提供集群初始化、编排等模板 Agent。

适用前提与限制需要说明：goal-planner.md 是一份 Claude Code Agent 定义文件，其价值在于为 claude-flow 编排器提供 GOAP 专家角色的系统提示词与工具约定；文中引用的 mcp__claude-flow__* MCP 工具属于 claude-flow 生态，需在该框架环境下才可用。ADR-038 描述的 sublinear 规划器（.claude-flow/goap/ TypeScript 模块、goap CLI 子命令）状态为 Proposed，其中给出的性能预算（规划 < 5ms、PageRank < 2ms、增量重规划 < 1ms 等）属于设计目标而非实测数据。同时，ADR-038 也诚实列出了该方案的代价：动作目录需要随新 ADR 手工维护、cargo test 类状态观察开销大（靠 TTL 缓存缓解）、以"开发者-天"计的代价模型只是估算、布尔化状态会损失"精度逐渐提升"这类连续变化的细节。

七、小结

.claude/agents/goal/goal-planner.md 定义的是 RuView 智能体集群中的 GOAP 专家角色：它以游戏 AI 的目标导向规划为理论根基，具备 A* 最优搜索、前置条件/效果分析、OODA 闭环监控与动态重规划、LLM 与确定性动作混合执行等完整能力，并通过 claude-flow 的编排（task_orchestrate）、集群（swarm_init）与记忆（memory_usage）三类 MCP 工具实现规划、协作与经验复用。结合 ADR-038 与本仓库中 sublinear-goal-planner、pagerank-analyzer 等配套 Agent 可以看到一条清晰的技术脉络：从通用 GOAP 方法论，到面向 ADR 依赖图的子线性优化（相关性剪枝、Tier 分层、增量重规划、PageRank 优先级），再到面向开发者的 CLI 与集群派发协议——这套体系让"下一步做什么"从依赖人脑的工作变成可查询、可重规划、可审计的自动化决策过程。