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最初只提供三个 AgentAgent模式输出goal-plannerGOAP / A* 状态空间规划行动计划deep-researcher线性多源综合 证据分级分级发现文档horizon-tracker长周期目标跟踪 漂移检测里程碑状态ADR-099 档案调查员递归并行多源研究 指出这三个 Agent 都没有实现一种在结构上完全不同的研究模式——受 maigret并行用户名枚举 递归扩张 结构化档案报告启发而来的大规模并行广度扇出——对同一种子实体并发查询 N 个源而非串行递归扩张——第 k 轮发现的实体成为第 k1 轮的种子受深度/预算上限约束结构化档案输出——图 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-graphKG 插件关注已抽取数据的图操作而调查器关注的是采集。二、安装与入口在已安装 Claude Code 风格插件体系的 ruflo 环境中通过 marketplace 安装/plugin marketplace add ruvnet/ruflo /plugin install ruflo-goalsruflo插件的唯一新增 CLI 入口就是斜杠技能/ruflo-goals:dossier-collect无其他 CLI 面变更。插件清单 plugins/ruflo-goals/.claude-plugin/plugin.json 当前版本为 0.2.1keywords 中包含dossier、investigation、osint、mcp、evidence-grading等可用于检索与市场分类。使用前可用仓库自带契约脚本做一次健康检查bash plugins/ruflo-goals/scripts/smoke.sh # Expected: 10 passed, 0 failedsmoke.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/maxDepth2从种子出发的递归深度--max-breadth/maxBreadth8每轮每个源最多继续追踪的新实体数--sources全部适用源可用源的子集如codebase,git,memory--budget-usd/budget可选{ tokens?, usd? }触达后干净中止--exactfalse关闭嵌入相似度去重用于实体身份敏感的运行// 输入形态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代码标识符、adrADR-NNN、url或concept自由文本概念。挑选源——按源矩阵匹配种子类型默认取全部适用源。开启轨迹——调用mcp__plugin_ruflo-core_ruflo__hooks_intelligence_trajectory-start任务名为dossier:slug。第 0 轮扇出——在同一条消息中发出全部源查询。示例usernameWebSearch、对github.com/user执行WebFetch、mcp__plugin_ruflo-core_ruflo__memory_search_unifiedadrReadADR 文件、Grep引用、mcp__plugin_ruflo-core_ruflo__memory_search命名空间adrsymbolGrep、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分层上下文向量HNSWmcp__plugin_ruflo-core_ruflo__embeddings_search语义近邻知识图谱mcp__plugin_ruflo-core_ruflo__hooks_intelligence_pattern-searchkg-traverse实体边Web 搜索WebSearch用户名、URL、当前状态Web 抓取WebFetch主页、README代码库Grep、Glob、Read符号、文件路径ADR 索引mcp__plugin_ruflo-core_ruflo__memory_search命名空间adrADR 编号、设计决策Git 情报Bashgit log、git blame作者、文件历史与源矩阵配套的是 README 选择指南它明确了四种任务模式的归属避免与兄弟 Agent 混用你手上有使用一个问题deep-researcher/deep-research一个待向外扩张的种子实体dossier-investigator/dossier-collect一个多步骤目标goal-planner/goal-plan一个长周期目标horizon-tracker/horizon-trackADR-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×2sourcesUsed为[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 轮再调度第 k1 轮避免深度优先失控带来的成本爆炸。绝不静默截断永远显式标记并记录跳过了什么。去重纪律同样明确去重但不合并de-dup, dont merge——当两个源指向同一实体时在一个节点上把两者都链为独立来源而不是编造一条综合声明。默认采用嵌入相似度阈值 0.92 去重ADR-099 承认该阈值存在误报风险--exact模式关闭相似度去重被记录为低优先级跟进项首轮发布时默认阈值已够用。八、轨迹录制与持久化从第 3 步到第 11 步整个调查被包裹在智能体轨迹trajectory里trajectory-start任务dossier:slug→ 每轮trajectory-step→ 完成时trajectory-endsuccess。这不仅是可观测性手段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、广度 8ADR-097 --max-depth 1——adr类型只做一轮扇出适合快速摸清一个设计决策的引用面ADR-099 的端到端验收测试正是以ADR-097为种子期望命中实体包含federation、circuit-breaker、budgetsrc/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 / 人物这类需要向外扩张而非回答单一问题的任务。相关资源技能定义plugins/ruflo-goals/skills/dossier-collect/SKILL.mdAgent 提示词plugins/ruflo-goals/agents/dossier-investigator.md架构决策v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md插件 READMEplugins/ruflo-goals/README.md真实运行示例Markdown v3/docs/examples/dossiers/ruflo-goals/ruflo-goals.md 与 JSON v3/docs/examples/dossiers/ruflo-goals/ruflo-goals.json以及同目录下的ruvnet、adr-088示例契约验证脚本plugins/ruflo-goals/scripts/smoke.sh【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考