ruflo-knowledge-graph：基于 AgentDB 的代码知识图谱构建、存储与 Pathfinder 图遍历

ruflo-knowledge-graph：基于 AgentDB 的代码知识图谱构建、存储与 Pathfinder 图遍历

【免费下载链接】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-knowledge-graph插件文档为主线，系统讲解该插件如何从源码与文档中提取实体（类、函数、模块、类型、概念）与关系（imports、extends、implements、depends-on、calls），将其以层级节点加因果边的形式存入 AgentDB 的knowledge-graph命名空间，并用 Pathfinder 算法按边权与语义相似度打分、剪枝、排序遍历图谱。读完本篇，你将掌握该插件的安装方式、kg命令的 5 个子命令、实体/关系建模规范、底层 MCP 工具调用链、工具名漂移（embeddings_embed→embeddings_generate）这一真实 Bug 的修复过程，以及用 smoke 脚本作为插件契约的验证手段。

插件定位与组成

ruflo-knowledge-graph是 ruflo（The original agent meta-harness）的一个 Claude Code 插件，定位是一句话：Knowledge graph construction — entity extraction, relation mapping, and pathfinder graph traversal（知识图谱构建——实体抽取、关系映射与 Pathfinder 图遍历），见 plugins/ruflo-knowledge-graph/README.md。

从插件清单 plugins/ruflo-knowledge-graph/.claude-plugin/plugin.json 可以确认其元数据：

• 版本：0.2.1
• 作者：ruvnet
• 协议：MIT
• 关键词：ruflo、knowledge-graph、entities、relations、pathfinder、mcp、pathfinder-traversal、entity-extraction

其整体工作流是：从代码和文档中抽取实体与关系 → 构建一个可导航的知识图谱（层级节点 + 因果边，存储在 AgentDB 中）→ 使用 Pathfinder 算法遍历图谱，路径按边权与语义相似度打分。

插件的目录结构（1 agent + 2 skills + 1 command）与 README 描述一一对应：

plugins/ruflo-knowledge-graph/ ├── .claude-plugin/plugin.json # 插件清单 ├── agents/graph-navigator.md # graph-navigator agent ├── commands/kg.md # /kg 命令（5 个子命令） ├── skills/ │ ├── kg-extract/SKILL.md # /kg-extract <path> │ └── kg-traverse/SKILL.md # /kg-traverse <entity> [--depth N] ├── docs/adrs/0001-knowledge-graph-contract.md ├── scripts/smoke.sh # 契约级 smoke 测试（10 项检查） └── README.md

安装方式

插件通过 Claude Code 的--plugin-dir参数本地加载：

claude --plugin-dir plugins/ruflo-knowledge-graph

加载后即可获得graph-navigatoragent、kg-extract/kg-traverse两个 skill，以及带 5 个子命令的kg命令。

操作面：Agent、Skills 与 5 个 kg 子命令

graph-navigator agent

plugins/ruflo-knowledge-graph/agents/graph-navigator.md 中定义的graph-navigatoragent 使用sonnet模型，职责有五：

1. 从代码和文档中抽取实体（classes、functions、modules、concepts、types）；
2. 映射实体间关系：imports、extends、implements、depends-on、calls、references；
3. 以层级节点存实体、以因果边存关系，构建知识图谱；
4. 用 Pathfinder 算法遍历图谱：种子节点 → 扩展因果边 → 按相关性打分 → 剪枝低相似度路径；
5. 回答图谱查询，如「谁依赖 X？」「从 A 到 B 的路径是什么？」「连接度最高的节点有哪些？」

两个 Skill

kg 命令（5 个子命令）

plugins/ruflo-knowledge-graph/commands/kg.md 定义了完整命令面：

kg extract <path> # 从源文件抽取实体与关系 kg traverse <entity> # 从种子实体开始 Pathfinder 遍历 kg relations <entity> # 列出某实体的全部直接关系 kg visualize # 知识图谱的 ASCII 可视化 kg search <query> # 跨图谱语义搜索

各子命令的执行细节（摘自kg.md）：

• kg extract <path>：递归扫描<path>下的类、函数、模块、类型与配置引用；为每个实体记录类型、名称、文件位置、描述；映射关系；通过agentdb_hierarchical-store存入knowledge-graph命名空间；为每条关系创建agentdb_causal-edge因果边；最后汇报实体总数、关系总数与按类型分布。
• kg traverse <entity>：先用agentdb_hierarchical-recall查种子实体，再沿因果边向外扩展（默认深度 3）；每条路径按relevance = edge_weight * semantic_similarity(query, node)打分；剪掉累计得分低于 0.3 的路径；返回 top 10 路径（含实体、关系、分数）。
• kg relations <entity>：查询 source 或 target 匹配该实体的因果边，按关系类型分组，以表格展示关系、方向（入边/出边）、目标实体、权重。
• kg visualize：从knowledge-graph命名空间召回全部实体与边，识别连接度 top 10 的节点，渲染简化图谱并附实体类型与关系类型的图例。
• kg search <query>：通过agentdb_pattern-search搜索实体（注意：semanticRouter控制器在当前 AgentDB 构建中为enabled: false，pattern-search 是可用替代方案），再用因果边扩展上下文，按 pattern-match 分数排序，输出实体名、类型、文件位置与相关度分数；需要更高保真语义相似度时可退回embeddings_generate+ 手动余弦。

实体类型与关系模型

实体类型（6 类）

关系类型与权重

plugins/ruflo-knowledge-graph/skills/kg-extract/SKILL.md 是抽取行为的执行规范，定义了 7 类关系及其权重：

skill 文档中有一条关键约束：TypeScript 的import type和行内type修饰符（import { type Foo, bar }）在编译期会被擦除，绝不能计为值导入——它们是一条独立的弱关系。错误分类会产生「幻影运行时循环」（phantom runtime cycles）。skill 中给出了区分两类导入的正则提示：

^\s*import\s+type\s+ → type-depends-on（整条导入均为类型导入） ^\s*import\s*\{[^}]*\btype\s+\w+ → 拆分：type 修饰符 → type-depends-on，值修饰符 → imports ^\s*import\s+[^{]*\bfrom\s+ → imports（值导入）

值得注意的是，type-depends-on边「永不用于循环检测或运行时影响分析」。另从 agents/graph-navigator.md 的结构看，agent 层还维护了一张参照关系表（imports 1.0、extends 0.9、implements 0.9、depends-on 0.8、calls 0.7、references 0.5、tests 0.6），其中包含tests关系（如auth.test.tstestsAuthService）；实际抽取落库时以 kg-extract skill 中的权重规范为准。

存储模型：AgentDB 命名空间与工具名漂移修复

命名空间协调

README 的「Namespace coordination」一节明确了存储约定：

• 本插件拥有knowledge-graph命名空间（kebab-case），遵循 ruflo-agentdb 的 ADR-0001「Namespace convention」；
• 保留命名空间（pattern、claude-memories、default）禁止被影子覆盖；
• 实体节点经agentdb_hierarchical-store写入；关系边经agentdb_causal-edge写入；语义索引用embeddings_generate。

一个真实的 Bug：embeddings_embed并不存在

ADR-0001 记录了本插件最重要的契约决策：skills/kg-extract/SKILL.md与agents/graph-navigator.md曾引用mcp__plugin_ruflo-core_ruflo__embeddings_embed，但真实工具名是embeddings_generate——embeddings_embed这个 MCP 工具根本不存在，任何调用都会以 "tool not found" 失败。在 CLI 源码中可以确认真实工具注册于 embeddings-tools.ts，其描述为「Generate embeddings for text (Euclidean or hyperbolic) … Pair with memory_store / agentdb_pattern-search to land the vector against your knowledge base」。

ADR 的决策要点：

1. 在 skill 与 agent 两个文件中将embeddings_embed重命名为embeddings_generate；
2. README 增补 Compatibility（pin v3.6）、Namespace coordination、Verification 与 Architecture Decisions 章节；
3. scripts/smoke.sh以 10 项结构检查作为插件契约，其中包含对工具名漂移的回归检查——确保embeddings_embed不再出现在任何工具调用点；
4. 插件元数据保持 minor 节奏（关键词补入mcp、pathfinder-traversal、entity-extraction）。

ADR 状态为 Accepted，且注明实现状态：v0.2.0+ 已发货、命名空间已声明、smoke 契约已就位。

Pathfinder 遍历算法

README 给出的五步流程：

1. Seed（种子）— 从目标实体节点出发；
2. Expand（扩展）— 沿因果边向外扩展（深度可配，默认 3）；
3. Score（打分）—relevance = edge_weight * semantic_similarity(query, node)；
4. Prune（剪枝）— 移除累计得分低于阈值（默认 0.3）的路径；
5. Rank（排序）— 按累计相关性返回 top-K 路径。

结合 skills/kg-traverse/SKILL.md 的七步执行规范，可以看到打分环节的落地实现比 README 公式更具体：

• Seed：agentdb_hierarchical-recall按名查种子实体；
• Expand：agentdb_causal-edge查种子相连的全部边，递归向外扩展到指定深度（默认 3）；
• Score：累计得分取乘积形式cumulative_score = product(edge_weight * keyword_similarity(query, node))，由agentdb_pattern-search提供相似度——因为semanticRouter控制器在当前 AgentDB 构建中enabled: false（skill 中注明，另见项目 issue #2049）；对更高保真语义相似度的需求，可退回embeddings_generate+ 手动余弦，但这不是步骤 3 运行的必要条件；
• Prune：累计得分 < 0.3 的路径移除；
• Rank：按累计得分降序排序；
• Synthesize：调agentdb_context-synthesize将 top 路径合成为连贯摘要；
• Report：输出 top 10 路径，含实体链、关系类型、累计得分与合成上下文。

skill 还给出 CLI 兜底方式：

npx @claude-flow/cli@latest memory search --query "relations for ENTITY_NAME" --namespace knowledge-graph

此外，graph-navigator agent 定义了任务完成后的学习回路：神经训练（hooks post-task --train-neural true加neural train --pattern-type knowledge-graph --epochs 10）与记忆学习（把成功图谱模式与实体抽取结果按entity-ENTITY_NAME/pattern-PATTERN_NAME键存入knowledge-graph命名空间）。

G7 控制器（ruflo 3.6.23+ / 3.6.24 激活）

README 依据 ADR-095 列出了本插件图遍历可借助的五个已关闭的 AgentDB 控制器缺口：

• gnnService— 基于 AgentDB 因果图的 GNN 嵌入 + 关系打分，为 Pathfinder 的semantic_similarity(query, node)项提供结构感知增强：与已确认相关节点互为图邻居的节点会获得加权提升；
• rvfOptimizer— 向量块持久化前的量化 + 去重。知识图谱索引中常存在大量近重复实体向量（同一类被多个模块 re-export），rvfOptimizer 会透明地将其折叠；
• mutationGuard+attestationLog+GuardedVectorBackend— 底层向量存储的证明门控写入。当图谱跨越信任边界（如联邦知识导入）时，.swarm/attestation.db中的 attestation 链记录每次变更以供事后审计。

尚待实现的graphAdapter控制器将为此插件提供一等公民的图数据库后端（替代目前「在 AgentDB 扁平因果边表之上构建图视图」的方式），同样由 ADR-095 跟踪。运行时状态可通过agentdb_controllers或agentdb_healthMCP 工具检查。

验证：smoke 脚本即契约

该插件的兼容性约定是：CLI pin 到@claude-flow/cliv3.6 major+minor；bash plugins/ruflo-knowledge-graph/scripts/smoke.sh是契约，期望输出10 passed, 0 failed。

scripts/smoke.sh 的 10 项检查逐一对应 ADR 的契约要素：

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

这套「smoke-as-contract」做法的意义在于：插件的工具名引用、版本 pin、命名空间声明等契约要素不靠人肉审查，而是由可重复执行的脚本在每次变更时机械校验。

相关插件与延伸阅读

• ruflo-agentdb— G7 控制器的运行时载体，命名空间规范的属主；两者同装可覆盖完整的「图谱 + 遍历」能力；
• ruflo-ruvector— 为图谱节点的快速语义搜索提供 HNSW 索引；
• ruflo-adr— ADR 依赖图与本插件共享同一因果边模型。

架构决策与契约细节可继续深入：ADR-0001 契约文档、kg 命令定义、kg-extract skill 与 kg-traverse skill。适用前提提醒：本插件面向 ruflo 3.6 系列（G7 控制器特性要求 3.6.23+），且semanticRouter控制器当前不可用，语义路由统一以agentdb_pattern-search（必要时embeddings_generate+ 手动余弦）替代。

【免费下载链接】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