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是 rufloThe 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 agentplugins/ruflo-knowledge-graph/agents/graph-navigator.md 中定义的graph-navigatoragent 使用sonnet模型职责有五从代码和文档中抽取实体classes、functions、modules、concepts、types映射实体间关系imports、extends、implements、depends-on、calls、references以层级节点存实体、以因果边存关系构建知识图谱用 Pathfinder 算法遍历图谱种子节点 → 扩展因果边 → 按相关性打分 → 剪枝低相似度路径回答图谱查询如「谁依赖 X」「从 A 到 B 的路径是什么」「连接度最高的节点有哪些」两个 SkillSkill用法说明kg-extract/kg-extract path从源文件抽取实体与关系构建知识图谱kg-traverse/kg-traverse entity [--depth N]从种子实体开始的 Pathfinder 遍历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.mdkg 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: falsepattern-search 是可用替代方案再用因果边扩展上下文按 pattern-match 分数排序输出实体名、类型、文件位置与相关度分数需要更高保真语义相似度时可退回embeddings_generate 手动余弦。实体类型与关系模型实体类型6 类类型示例抽取来源见 graph-navigator.mdclassUserService、AuthController源码类声明functioncalculateDiscount、handleRequest源码函数/方法声明moduleauth、payments、api目录结构与 package.jsonconceptauthentication、caching、rate-limiting文档、注释、ADRtypeUser、OrderStatus、ApiResponseTS interface、type aliasconfigdatabase、redis、jwt配置文件、环境变量关系类型与权重plugins/ruflo-knowledge-graph/skills/kg-extract/SKILL.md 是抽取行为的执行规范定义了 7 类关系及其权重关系语义权重imports值导入import { x } from ...、require(...)0.9type-depends-onTS 类型导入import type { Foo }、import { type Foo, value }0.1extends类继承0.9implements接口实现0.7depends-on构造器依赖、注入服务0.8calls函数/方法调用0.7references文档提及、注释0.3skill 文档中有一条关键约束TypeScript 的import type和行内type修饰符import { type Foo, bar }在编译期会被擦除绝不能计为值导入——它们是一条独立的弱关系。错误分类会产生「幻影运行时循环」phantom runtime cycles。skill 中给出了区分两类导入的正则提示^\s*import\stype\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。一个真实的 Bugembeddings_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 的决策要点在 skill 与 agent 两个文件中将embeddings_embed重命名为embeddings_generateREADME 增补 Compatibilitypin v3.6、Namespace coordination、Verification 与 Architecture Decisions 章节scripts/smoke.sh以 10 项结构检查作为插件契约其中包含对工具名漂移的回归检查——确保embeddings_embed不再出现在任何工具调用点插件元数据保持 minor 节奏关键词补入mcp、pathfinder-traversal、entity-extraction。ADR 状态为 Accepted且注明实现状态v0.2.0 已发货、命名空间已声明、smoke 契约已就位。Pathfinder 遍历算法README 给出的五步流程Seed种子— 从目标实体节点出发Expand扩展— 沿因果边向外扩展深度可配默认 3Score打分—relevance edge_weight * semantic_similarity(query, node)Prune剪枝— 移除累计得分低于阈值默认 0.3的路径Rank排序— 按累计相关性返回 top-K 路径。结合 skills/kg-traverse/SKILL.md 的七步执行规范可以看到打分环节的落地实现比 README 公式更具体Seedagentdb_hierarchical-recall按名查种子实体Expandagentdb_causal-edge查种子相连的全部边递归向外扩展到指定深度默认 3Score累计得分取乘积形式cumulative_score product(edge_weight * keyword_similarity(query, node))由agentdb_pattern-search提供相似度——因为semanticRouter控制器在当前 AgentDB 构建中enabled: falseskill 中注明另见项目 issue #2049对更高保真语义相似度的需求可退回embeddings_generate 手动余弦但这不是步骤 3 运行的必要条件Prune累计得分 0.3 的路径移除Rank按累计得分降序排序Synthesize调agentdb_context-synthesize将 top 路径合成为连贯摘要Report输出 top 10 路径含实体链、关系类型、累计得分与合成上下文。skill 还给出 CLI 兜底方式npx claude-flow/clilatest 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-exportrvfOptimizer 会透明地将其折叠mutationGuardattestationLogGuardedVectorBackend— 底层向量存储的证明门控写入。当图谱跨越信任边界如联邦知识导入时.swarm/attestation.db中的 attestation 链记录每次变更以供事后审计。尚待实现的graphAdapter控制器将为此插件提供一等公民的图数据库后端替代目前「在 AgentDB 扁平因果边表之上构建图视图」的方式同样由 ADR-095 跟踪。运行时状态可通过agentdb_controllers或agentdb_healthMCP 工具检查。验证smoke 脚本即契约该插件的兼容性约定是CLI pin 到claude-flow/cliv3.6 majorminorbash plugins/ruflo-knowledge-graph/scripts/smoke.sh是契约期望输出10 passed, 0 failed。scripts/smoke.sh 的 10 项检查逐一对应 ADR 的契约要素#检查项1plugin.json 声明0.2.1且含mcp、pathfinder-traversal、entity-extraction关键词2两个 skill 均存在且 frontmatter 完整name:、description:、allowed-tools:3agentgraph-navigator与 commandkg文件存在4工具调用点不再引用不存在的embeddings_embed排除 ADR/README 中对修复本身的记载5skill 与 agent 均引用真实工具embeddings_generate6/kg命令覆盖 5 个子命令extract/traverse/relations/visualize/search7README pinclaude-flow/cli至 v3.68README 存在命名空间协调声明并引用 ruflo-agentdb 的 namespace convention9ADR-0001 存在且状态为 Accepted10skill 中无通配符工具授权allowed-tools: *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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
