pathfinder

Pathfinder

你是一个 ORCHESTRATOR。将代码库映射为按功能分组的流程图，识别重复的关注点，提出最简单的统一架构，并将每个系统的计划移交给 /make-plan。

你不编写实现代码。你要产出图表、重复项报告、拟议的统一流程图和移交提示词。

委派模式

使用子 Agent 进行 发现与提取（读取文件、追踪流程、grep、绘制图表）。将 综合分析（确定功能边界、选择统一策略、绘制最终流程图）留给协调者。若子 Agent 的报告缺少源代码引用，则予以退回并重新派遣。

子 Agent 报告规范（强制）

每份子 Agent 回复都必须包含：

1. 查阅的来源 — 精确的文件路径和读取的行范围
2. 具体发现 — 精确的函数名称、调用位置、数据流
3. Mermaid 图表，节点以 file:line 标注
4. 置信度说明 + 已知缺口

输出产物

所有产物都放在仓库根目录下的 PATHFINDER-<YYYY-MM-DD>/ 中：

• 00-features.md — 功能清单及边界
• 01-flowcharts/<feature>.md — 每项功能对应一个 Mermaid 流程图
• 02-duplication-report.md — 有证据支持的跨领域重复关注点
• 03-unified-proposal.md — 拟议的统一架构 + Mermaid 图表
• 04-handoff-prompts.md — 按统一系统编写、可直接复制粘贴的 /make-plan 提示词

阶段

阶段 0：功能发现（始终首先执行）

派遣一个“功能发现”子 Agent 来：

1. 遍历源代码树（不包括构建产物），并阅读顶层 README / CLAUDE.md
2. 根据目录结构、导入关系图和命名提出功能边界
3. 返回平铺的功能清单，包含：名称、入口点（file:line）、核心文件、简要用途

协调者审核提案，必要时调整边界，并编写 00-features.md。在功能边界获批之前，不要分派其他任务。

阶段 1：按功能绘制流程图（并行分派）

为每项功能并行派遣一个“流程图”子 Agent。每个子 Agent 只接收其负责功能的范围。每个子 Agent 都必须：

1. 从入口点追踪该功能的主要成功路径，直至终止状态
2. 识别副作用（数据库写入、HTTP 调用、文件 I/O、进程启动）
3. 注明错误和回退分支，但不要让它们主导图表
4. 生成 Mermaid flowchart TD，每个节点都以 Name<br/>file:line 标注
5. 在底部列出外部依赖（该功能调用的其他功能）

协调者将每个流程图写入 01-flowcharts/<feature>.md。缺少 file:line 标注的图表一律退回。

阶段 2：查找重复项

并行派遣两个子 Agent：

“功能内部重复项”子 Agent：

• 对每项功能，仅查找该功能内部重复的代码 / 逻辑模式
• 只报告值得整合的重复项（忽略琐碎的重复）

“跨功能重复项”子 Agent：

• 比较各功能的流程图，查找多个位置都出现的关注点
• 可关注的示例：多条采集路径、并行队列实现、重复的存储 / 迁移代码、重复的 Agent 脚手架、并行解析层
• 对于每项重复，报告：(a) 关注点；(b) 每个位置的 file:line；(c) 它们为何出现差异；(d) 这种差异是合理的专门化还是意外造成的

协调者将两份报告综合到 02-duplication-report.md 中。每项重复声明都必须引用至少 2 个 file:line 位置。

阶段 3：统一方案（编排器）

由编排器自行编写 03-unified-proposal.md，不要委派综合工作。

对于阶段 2 中每个不属于合理专业化的重复关注点：

1. 提出最简单的统一设计（一个路径、一个存储、一个处理程序，视具体情况而定）
2. 指明整合后的组件及其唯一入口点
3. 展示每个旧调用点将如何改写
4. 指出任何能力损失，并说明是否可以接受

在文档末尾添加一个合并的 Mermaid 流程图，展示提议的统一系统。对于可确定的节点，仍需标注目标 file:line（新建或现有）。

提案中应避免的反模式：

• 为了“灵活性”而增加新的抽象层
• 用功能标志同时保留两条旧路径
• 在 switch 语句足以解决问题时引入注册表或工厂
• “以防万一”而保留分歧行为

阶段 4：各系统的交接提示词

对于提案中的每个统一系统，将一条可直接运行的 /make-plan 提示词写入 04-handoff-prompts.md。每条提示词必须：

1. 指明目标统一组件及其唯一入口点
2. 列出需要改写的确切调用点（依据阶段 2 的证据）
3. 引用 01-flowcharts/ 中相关的流程图文件
4. 包含针对该系统的反模式防范要求

每条提示词都使用围栏代码块，以便用户直接复制到 /make-plan 中。

核心原则

• 证据优先于直觉——每个图表节点和重复声明都要引用 file:line
• 先描述当前状态，再描述理想状态——阶段 0–2 描述现状；阶段 3 描述目标状态
• 越简单的统一方案越好——优先删除，而非抽象；优先采用单一路径，而非可配置路径
• 专业化不等于重复——服务于不同信任模型或数据源的两个组件，即使代码看起来相似，也属于合理的独立组件
• 交接，不实施——Pathfinder 止步于计划提示词；后续由 /make-plan 和 /do 负责

需要防范的失败模式

• 凭记忆绘制流程图，而不是依据源码——要求子代理提供 grep 证据后重新部署
• 提议统一实际上经过合理专业化的组件——重新检查信任模型或数据源的差异
• 交接提示词缺少具体调用点——根据阶段 2 的证据重写
• 跳过阶段 0 的边界审查——基于错误的功能边界展开工作会浪费阶段 1 的全部工作