ruflo-goals dossier-collect 技能实战：基于种子实体的递归并行多源调查与图谱式档案构建-平芜编程栈

ruflo-goals dossier-collect 技能实战：基于种子实体的递归并行多源调查与图谱式档案构建

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

导读

本文讲解 ruflo 仓库中ruflo-goals插件提供的dossier-collect技能（对应 ADR-099），它是一种"以实体为种子、向外递归扩张"的多源并行调查模式：给定用户名、文件路径、代码符号、ADR 编号、URL 或概念，技能会在同一轮内并行查询 Web、记忆、知识图谱、代码库、ADR 索引与 Git 情报，从命中结果中抽取新实体并递归扩展，最终产出带逐条溯源（provenance）的图谱式档案（dossier）。读完本文，你将掌握dossier-collect的完整调用方式、种子类型判定、源矩阵选择、去重与预算纪律，以及 JSON 输出结构与持久化约定，并能区分它与deep-research（问题驱动）之间的适用边界。

一、背景：为什么需要"档案调查"这种独立模式

ruflo-goals插件（安装于 plugins/ruflo-goals/README.md）最初只提供三个 Agent：

Agent	模式	输出
`goal-planner`	GOAP / A* 状态空间规划	行动计划
`deep-researcher`	线性多源综合 + 证据分级	分级发现文档
`horizon-tracker`	长周期目标跟踪 + 漂移检测	里程碑状态

ADR-099 档案调查员：递归并行多源研究指出，这三个 Agent 都没有实现一种在结构上完全不同的研究模式——受 maigret（并行用户名枚举 + 递归扩张 + 结构化档案报告）启发而来的：

大规模并行广度扇出——对同一种子实体并发查询 N 个源，而非串行；
递归扩张——第 k 轮发现的实体成为第 k+1 轮的种子，受深度/预算上限约束；
结构化档案输出——图 + Markdown + JSON，每条声明都带来源溯源，便于导出。

deep-researcher做的是证据分级综合，但它期望人工精选源列表且基本线性执行，没有递归再播种循环、也没有并行扇出原语。与此同时，ADR-099 的调研显示 ruflo 已自带组装该调查器所需的全部原语，无需新增任何外部依赖：混合稀疏+稠密语义搜索（memory_search_unified）、HNSW/RaBitQ 向量检索（embeddings_search）、模式召回（agentdb_pattern-search、agentdb_hierarchical-recall）、知识图谱遍历与抽取（kg-traverse、kg-extract）、Web 搜索抓取（WebSearch/WebFetch）、代码库查询（Grep/Glob/Read）、ADR 索引（ruflo-adr:adr-index）、Git 情报（ruflo-jujutsu:diff-analyze）、并行 Agent 扇出（ruflo-swarm:swarm-init）以及轨迹录制（hooks_intelligence_trajectory-*）。

因此决策是新增一个 Agentdossier-investigator与配套技能dossier-collect，两者共同构成 dossier-collect 技能定义与 dossier-investigator Agent 提示词。ADR-099 同时记录了被否决的备选方案：扩展deep-researcher（会耦合两种结构不同的循环）、把 Python 版 maigret 打包成 MCP 包装器（引入 Python 运行时依赖与 3000+ 站点的网络出口与隐私/滥用姿态问题——我们要的是 maigret 的"模式"而非其"目标清单"）、以及把该能力建进ruflo-knowledge-graph（KG 插件关注已抽取数据的图操作，而调查器关注的是"采集"）。

二、安装与入口

在已安装 Claude Code 风格插件体系的 ruflo 环境中，通过 marketplace 安装：

/plugin marketplace add ruvnet/ruflo /plugin install ruflo-goals@ruflo

插件的唯一新增 CLI 入口就是斜杠技能/ruflo-goals:dossier-collect，无其他 CLI 面变更。插件清单 plugins/ruflo-goals/.claude-plugin/plugin.json 当前版本为 0.2.1，keywords 中包含dossier、investigation、osint、mcp、evidence-grading等，可用于检索与市场分类。

使用前可用仓库自带契约脚本做一次健康检查：

bash plugins/ruflo-goals/scripts/smoke.sh # Expected: "10 passed, 0 failed"

smoke.sh 的 10 项断言覆盖了插件清单版本与关键词、5 个技能 + 4 个 Agent + 1 个命令齐备、README 选择指南中的 4 种任务模式、ADR-099 交叉链接、CLI 版本钉住、命名空间约定、ADR-0001 状态以及"技能中不得出现通配符工具授权"等不变量。

三、参数与调用方式

技能 frontmatter 给出了参数提示：

argument-hint: "<seed> [--max-depth N] [--max-breadth N] [--sources s1,s2] [--budget-usd N] [--exact]"

各参数语义（结合 Agent 输入定义 dossier-investigator.md）：

参数	默认值	含义
`seed`	必填	起始实体，会被类型探测
`--max-depth`/`maxDepth`	2	从种子出发的递归深度
`--max-breadth`/`maxBreadth`	8	每轮每个源最多继续追踪的新实体数
`--sources`	全部适用源	可用源的子集，如`codebase,git,memory`
`--budget-usd`/`budget`	可选	`{ tokens?, usd? }`，触达后干净中止
`--exact`	false	关闭嵌入相似度去重，用于实体身份敏感的运行

// 输入形态（Agent 视角） { "seed": "ruvnet", "sources": ["web","memory","git"], "maxDepth": 2, "maxBreadth": 8, "budget": { "usd": 1 }, "exact": false }

frontmatter 中allowed-tools严格列出了该技能可用的工具面：记忆三件套（memory_store/memory_search/memory_search_unified）、AgentDB 模式检索与层次召回（agentdb_pattern-search/agentdb_pattern-store/agentdb_hierarchical-recall）、向量检索（embeddings_search）、智能体钩子（hooks_intelligence_pattern-search/pattern-store/trajectory-start/trajectory-step/trajectory-end）、任务创建（task_create）以及基础工具Bash/WebSearch/WebFetch/Read/Write/Grep/Glob。ADR-099 的验收标准之一是 Agent 提示词不超过 80 行（遵循 ADR-098 关于 token 成本的指引），当前 dossier-investigator.md 为 68 行，满足该约束。

四、核心执行流程（11 步）

技能正文定义了从种子到档案的完整流水线：

检测种子类型——分类为username（用户句柄）、file（路径）、symbol（代码标识符）、adr（ADR-NNN）、url或concept（自由文本概念）。
挑选源——按源矩阵匹配种子类型；默认取全部适用源。
开启轨迹——调用mcp__plugin_ruflo-core_ruflo__hooks_intelligence_trajectory-start，任务名为dossier:<slug>。
第 0 轮扇出——在同一条消息中发出全部源查询。示例：
- username：WebSearch、对github.com/<user>执行WebFetch、mcp__plugin_ruflo-core_ruflo__memory_search_unified；
- adr：ReadADR 文件、Grep引用、mcp__plugin_ruflo-core_ruflo__memory_search（命名空间adr）；
- symbol：Grep、Glob、mcp__plugin_ruflo-core_ruflo__embeddings_search。
抽取实体——从每条命中中浮出实体（人、仓库、文件、ADR、URL、术语）。用轻量正则 + 启发式即可，仅在歧义时才动用 LLM 抽取（ADR-099 中对应选项是ruflo-knowledge-graph:kg-extract）。
去重——丢弃已在档案中的实体；若未设--exact，还丢弃与既有节点嵌入余弦相似度 ≥ 0.92 的实体。
第 k 轮递归——对每个新实体（每个源以--max-breadth为上限）回到第 4 步递归，直到深度 ≥--max-depth或预算耗尽。
聚合——构建{ nodes, edges }图。每个节点携带{ id, type, attrs, sources: [...] }；每条边携带{ from, to, kind, source, confidence }。
渲染产物——<slug>.md（执行摘要、实体表、mermaid 图、来源溯源脚注）与<slug>.json（机器可读图），默认位置为v3/docs/examples/dossiers/<slug>/。
持久化——mcp__plugin_ruflo-core_ruflo__memory_store，命名空间dossier、键<slug>。
结束轨迹——mcp__plugin_ruflo-core_ruflo__hooks_intelligence_trajectory-end，状态为成功。

Agent 视角的循环可以浓缩为：

seed → [round 0: 跨源并行扇出] → [从每条命中抽取实体] → [对照档案去重；嵌入相似度阈值 0.92，除非 --exact] → [round 1: 用新实体重新播种，再次扇出] → ... 直到 depth ≥ maxDepth 或预算耗尽 → [聚合为图 + 渲染 markdown + 输出 JSON]

技能与 Agent 都强调一个关键纪律：每一轮内把所有源查询批量放进同一条消息，绝不串行化本可并行的事情。

五、源矩阵：按种子类型挑选数据源

Agent 提示词中的源矩阵是本技能的核心配置表，决定了对不同种子类型应该驱动哪些工具：

源	工具	最适合
混合记忆	`mcp__plugin_ruflo-core_ruflo__memory_search_unified`	任意概念
模式库	`mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search`	重复出现的模式
层次召回	`mcp__plugin_ruflo-core_ruflo__agentdb_hierarchical-recall`	分层上下文
向量（HNSW）	`mcp__plugin_ruflo-core_ruflo__embeddings_search`	语义近邻
知识图谱	`mcp__plugin_ruflo-core_ruflo__hooks_intelligence_pattern-search`+`kg-traverse`	实体边
Web 搜索	`WebSearch`	用户名、URL、当前状态
Web 抓取	`WebFetch`	主页、README
代码库	`Grep`、`Glob`、`Read`	符号、文件路径
ADR 索引	`mcp__plugin_ruflo-core_ruflo__memory_search`（命名空间`adr`）	ADR 编号、设计决策
Git 情报	`Bash`（`git log`、`git blame`）	作者、文件历史

与源矩阵配套的是 README 选择指南，它明确了四种任务模式的归属，避免与兄弟 Agent 混用：

你手上有	使用
一个问题	`deep-researcher`/`deep-research`
一个待向外扩张的种子实体	`dossier-investigator`/`dossier-collect`
一个多步骤目标	`goal-planner`/`goal-plan`
一个长周期目标	`horizon-tracker`/`horizon-track`

ADR-099 还明确记录了"与deep-researcher约有 40% 重叠"的取舍：两者共享"查询记忆 + KG + Web"的表层，但因为循环结构不同（线性证据分级 vs 并行递归扩张）、输出格式不同（综合文档 vs 实体图 + 档案），且选择规则无歧义（有问题是deep-researcher，有种子要扩张是dossier-investigator），因此接受这种冗余；若后续重叠过大，可抽出共享的multi-source-query技能级助手而不破坏任一 Agent 的接口。

六、输出结构与 JSON Schema

技能定义了机器可读档案的 JSON 骨架，字段全部可选可空但结构固定：

{ "seed": "ruvnet", "seedType": "username", "depth": 2, "truncated": false, "generatedAt": "ISO-8601", "nodes": [ { "id": "ruvnet", "type": "username", "attrs": { "...": "..." }, "sources": ["WebSearch", "github.com"] } ], "edges": [ { "from": "ruvnet", "to": "ruflo", "kind": "owns", "source": "github.com", "confidence": "high" } ], "stats": { "nodesByType": {}, "sourcesUsed": [], "tokensSpent": 0 } }

仓库里保存着三份真实运行示例（ADR-099 实施记录中注明由docs/examples/提交加入）：ruvnet、ADR-088、ruflo-goals。以 v3/docs/examples/dossiers/ruflo-goals/ruflo-goals.json 为例，一次对concept种子（解析为插件路径plugins/ruflo-goals）的深度 2 调查产出了 16 个节点（plugin 1 / agent 4 / skill 5 / command 1 / adr 1 / memory-namespace 4）、14 条边（ships-agent×4、ships-skill×2、drives×4、persists-to×2、introduces×2），sourcesUsed为["Read", "Glob"]，tokensSpent为 2400——每条边都带着source与confidence字段，正是"逐条溯源"的落地形态。

对应的 v3/docs/examples/dossiers/ruflo-goals/ruflo-goals.md 展示了人类可读产物结构：执行摘要 → 实体表 → mermaid 图 → 选择规则 → 文件清单。其中 mermaid 图清晰刻画了实体关系，例如：

七、预算纪律与去重策略

技能与 Agent 对"展开的失控"做了三层硬约束，这些约束构成 ADR-099 的核心不变量之一（Budget caps）：

预算追踪：若设置了--budget-usd，通过轨迹近似跟踪成本；触达上限时输出部分档案，标记truncated: true并列出仍排队的实体。budget.tokens同理——绝不允许静默超支。
BFS 优先：只做广度优先扩张——先完成第 k 轮，再调度第 k+1 轮，避免深度优先失控带来的成本爆炸。
绝不静默截断：永远显式标记并记录跳过了什么。

去重纪律同样明确：去重，但不合并（de-dup, don't merge）——当两个源指向同一实体时，在一个节点上把两者都链为独立来源，而不是编造一条综合声明。默认采用嵌入相似度阈值 0.92 去重；ADR-099 承认该阈值存在误报风险，--exact模式（关闭相似度去重）被记录为低优先级跟进项，首轮发布时默认阈值已够用。

八、轨迹录制与持久化

从第 3 步到第 11 步，整个调查被包裹在智能体轨迹（trajectory）里：

trajectory-start（任务dossier:<slug>）→ 每轮trajectory-step→ 完成时trajectory-end（success）。

这不仅是可观测性手段：ADR-099 的正向后果之一指出，轨迹录制会喂给 SONA 模式库，使后续调查获得更快的路由。持久化方面，档案写入 AgentDB 记忆的dossier命名空间（键为<slug>），与goap-plans、research、horizons等兄弟命名空间平级；README 命名空间协调表说明dossier是文档化的基础名例外（类似federation），不涉及 legacy-vs-canonical 迁移，而research、horizons等已有规范映射（goals-research、goals-horizons），新写入应从本插件侧采用规范的 kebab-case 形式。同时，保留命名空间pattern、claude-memories、default不得被遮蔽。

九、实战示例

技能文档给出了四类可复制的调用：

/ruflo-goals:dossier-collect ruvnet /ruflo-goals:dossier-collect ADR-097 --max-depth 1 /ruflo-goals:dossier-collect "src/memory/hnsw.ts" --sources codebase,git,memory /ruflo-goals:dossier-collect "ruflo-goals" --max-breadth 5 --budget-usd 1

逐一拆解：

ruvnet——默认username类型，走 Web + 记忆 + Git 全套源，深度 2、广度 8；
ADR-097 --max-depth 1——adr类型，只做一轮扇出，适合快速摸清一个设计决策的引用面；ADR-099 的端到端验收测试正是以ADR-097为种子，期望命中实体包含federation、circuit-breaker、budget；
"src/memory/hnsw.ts" --sources codebase,git,memory——file/symbol类型，显式收窄源集合，专注代码库引用、Git 历史和记忆中的相关讨论；
"ruflo-goals" --max-breadth 5 --budget-usd 1——concept类型，用广度上限 5 与 1 美元的预算约束控制成本。

十、与兄弟技能的边界

一句话总结选型边界：dossier-collect用于枚举与扩张（从种子出发，问"它还连着谁"），而 deep-research 技能用于回答具体问题（线性多阶段、逐条证据分级、产出综合报告），goal-plan 技能用于多步骤行动规划（GOAP/A*、前置条件分析、自适应重规划），horizon-track用于跨会话长目标跟踪。ADR-099 的实施记录确认：上线后两个调查类 Agent 并列使用未出现混淆，问题驱动与种子驱动的区分在实践中成立，重叠并未成为问题。

结语

dossier-collect是 ruflo 中"用自有工具面拼装成熟调查模式"的典型样本：不引入 Python 运行时、不新增 MCP 服务器、不依赖外部站点清单，仅靠记忆、AgentDB、向量检索、知识图谱、Web、代码库与 Git 这组既有原语，就实现了 maigret 式的并行扇出 + 递归扩张 + 结构化档案。它的图谱输出、逐条溯源与预算硬约束，使其特别适合"调查某个符号 / 模块 / 依赖 / ADR / 人物"这类需要向外扩张而非回答单一问题的任务。