Understand-Anything 节点ID命名规范深度解析file:、function: 前缀规则与别名归一化完全指南【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-AnythingUnderstand-Anything 是一款将任意代码库转换为交互式知识图谱的开源工具支持在 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等 AI 编程助手中直接探索、搜索并提问。而这一切的地基是一套严格的节点 ID 命名规范——每个文件、函数、类、配置都在图谱中拥有file:、function:这样带前缀的唯一身份。本文带你完整读懂这套规范的设计逻辑与别名归一化机制帮你快速上手知识图谱数据格式。为什么知识图谱需要「节点 ID 命名规范」知识图谱由两类元素组成节点Node文件、函数、类、模块、配置、文档等边Edgeimports、calls、contains等关系边通过节点 ID 引用两端因此ID 就是图谱的主键。一旦 ID 写错比如 LLM 输出src/utils.ts而不是file:src/utils.ts引用它的边就会悬空整个子图随之断裂。Understand-Anything 因此做了两件事定义一套统一的前缀格式类型前缀:路径[:名称]内置一套归一化流水线自动修复 LLM 生成的各种不规范 ID核心实现位于 normalize-graph.ts完整规范文档见 SKILL.md。13 种节点类型前缀一览知识图谱共定义 13 种节点类型每种对应一个或多个合法前缀类型说明ID 规范file源码文件file:相对路径function函数或方法function:相对路径:名称class类、接口、类型class:相对路径:名称module逻辑模块/包module:名称concept抽象概念或模式concept:名称config配置文件YAML/JSON/TOMLconfig:相对路径document文档Markdown 等document:相对路径service可部署服务定义service:相对路径table数据库表/迁移table:相对路径:表名endpointAPI 端点/路由endpoint:相对路径:端点名pipelineCI/CD 流水线pipeline:相对路径schemaSchema 定义schema:相对路径resource基础设施资源resource:相对路径完整定义可参考 SKILL.md 中的 KnowledgeGraph Schema 参考。两大核心前缀file: 与 function:绝大多数图谱节点由这两类构成file:src/index.ts—— 文件节点前缀后紧跟相对路径function:src/utils.ts:formatDate—— 函数节点三段式类型:路径:函数名构建时图谱会在文件与函数之间自动建立contains边权重 1.0函数之间建立calls边权重 0.8。生成逻辑见 graph-builder.ts。 记住这个规律文件类节点是两段符号类节点是三段类型:路径:名称。别名归一化normalizeNodeId 如何修复脏 ID真实场景中LLM 分批分析产出的 ID 五花八门。归一化函数 normalizeNodeId() 能自动修复以下四类问题且幂等——正确 ID 原样通过原始 ID问题修复后修复类型file:file:src/foo.tsfile:src/foo.ts双重前缀my-project:file:src/foo.tsfile:src/foo.ts项目名前缀frontend/src/utils.tsfile:frontend/src/utils.ts裸路径缺前缀formatDate带 filePath 元数据func:src/utils.ts:formatDate从元数据重建file:src/foo.tsfile:src/foo.ts首尾空白修复策略分三步剥离开头非法片段按冒号逐段剥离直到遇到合法前缀file、func、class、config等 16 种或耗尽为止处理双重前缀如file:file:src/foo.ts跳过外层保留内层兜底重建裸 ID 若是函数/类节点会用节点的filePathname元数据重建为完整三段式 ID所有行为均有测试覆盖可参考 normalize-graph.test.ts。批量归一化流水线从 LLM 输出到最终图谱单个 ID 修好了还不够——边Edge引用的也是 ID。normalizeBatchOutput() 执行完整的批量流水线Pass 1归一化所有节点 ID同时把复杂度值如数字4、字符串trivial映射到simple/moderate/complex去重同 ID 节点只保留最后一个Pass 2通过 ID 映射表重写所有边的source/target引用对映射表未覆盖的端点再从边 ID 自身推断类型二次归一化丢弃悬空边引用不存在节点的边被移除并记录原因missing-source/missing-target同时合并脚本 merge-batch-graphs.py 还会执行一个经典修复func:→function:前缀归一化——这是 LLM 最常见的输出变体脚本会在 stderr 报告修复数量如170 × func: → function:语义层面的剩余问题由 assemble-reviewer 智能体 接手复核。类型别名表LLM 写错类型也能自动纠正除了 ID节点的type字段也有别名归一化。核心别名表 NODE_TYPE_ALIASES 覆盖了 LLM 常用的非正式叫法func、fn、method→functioninterface、struct→classdoc、readme、docs→documentci、job→pipelineapi、route、query→endpointdb、migration、view→table边类型同样有一张 EDGE_TYPE_ALIASES 表extends→inherits、invokes→calls、import→imports等。有意思的是implemented_by被故意排除在别名之外——因为它会反转边的方向自动纠正比保留正确语义更有风险。新手速查三句话记住命名规范✅ 文件节点file:src/App.tsx配置config:tsconfig.json文档document:README.md✅ 符号节点function:src/utils.ts:formatDate、class:src/models/User.ts:User路径 名称缺一不可✅ 拿不准就交给归一化——只要节点带有type、filePath、name元数据normalizeNodeId就能自动重建正确 ID了解规范后你可以打开仪表盘直观查看每个节点的真实 ID 与连接关系写在最后节点 ID 命名规范看似枯燥实则是 Understand-Anything 知识图谱教代码能力的基石统一的主键让边引用可靠、让增量更新可比对、让 LLM 的随机输出变得可控。掌握file:/function:前缀规则与别名归一化机制你就能读懂甚至手写一份合格的知识图谱 JSON——这正是玩转这套工具的第一步。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
