它是什么
Graphify 是一个把「代码库及其周边资料」转换成可查询知识图谱的工具。它接收的不只是源代码，还包括项目文档、SQL schema、配置文件乃至 PDF 文档，把这些异构内容解析成统一的图结构，再以 /graphify 技能（skill）的形式接入 Claude Code、Cursor、Codex、Gemini CLI 等主流 AI 编程助手，让助手能够基于图去检索和推理，而不是在文件堆里做关键词搜索。
要理解它的价值，需要先看现状：AI 编程助手在单文件、单函数层面已经相当好用，但一旦涉及跨模块调用链、跨语言引用、以及"这段代码对应哪张数据库表"这类问题，效果往往会明显下降。常见的补救办法是把仓库切块做向量检索，但向量检索擅长找"语义相近的文本"，并不擅长表达"谁调用了谁""哪张表的哪个字段被谁写入"这类结构化关系。Graphify 的思路是把这些关系显式建模成图的边，让查询能沿着边精确跳转。
官方描述中特别强调"本地确定性 AST 解析"（local deterministic AST parsing），这句话包含两层信息：一是解析在本地完成，代码不必为建图而外传；二是解析基于语法树而非模型推断，因此同一份输入会得到同一份结果，可复现、可审查。这与纯 LLM 抽取方案形成了明显区隔。
核心功能 / 内容清单
- 多源输入统一建模：把代码、文档、SQL schema、配置文件、PDF 这几类通常分散在不同工具里的资料，统一纳入同一张图谱。这样做的意义在于，真实工程问题很少只落在单一来源上——一个字段的变更往往同时牵涉代码、迁移脚本和接口文档。
- 本地确定性 AST 解析：以语法树为基础抽取代码中的符号、定义与引用关系。相比让模型"读代码猜关系"，AST 解析对函数定义、导入、类成员这类结构信息的准确率更稳定，也不会因为模型幻觉凭空造出一条不存在的调用边。
- 可查询的知识图谱：图谱建好后，节点与边构成了可遍历的结构，查询可以从任意一个锚点出发（某个文件、某张表、某个配置项），沿着引用关系外扩，回答"影响面有多大""还有谁依赖它"这类问题。
- 以
/graphify技能接入多个 AI 助手：README 明确列出了 Claude Code、Cursor、Codex、Gemini CLI 四个宿主。技能形态意味着它不是一个需要单独切换的独立应用，而是嵌进既有工作流，把图谱能力作为助手的"外挂记忆"与检索后端。 - 多语种文档覆盖：仓库提供简体中文、日语、韩语、德语、法语、西班牙语、印地语、葡萄牙语、俄语、阿拉伯语等数十种 README 翻译版本，说明项目在跨地区开发者中有一定的使用基础，也降低了非英语使用者的上手门槛。
- Apache-2.0 许可：允许商业使用、修改与再分发，对团队内部集成和二次开发比较友好。
典型使用场景
场景一：接手陌生的大型仓库，需要快速建立全局认知。 传统做法是顺着入口文件一路读下去，或者在 IDE 里反复"跳转到定义"，遇到多语言混编（比如前端 TS + 后端 Go + 一堆 YAML 配置）时极易迷失。用 Graphify 建图后，可以直接提问"这个服务对外暴露的入口有哪些""某个配置项被哪些模块消费"，让助手沿着图谱给出有依据的答案，而不是靠通读文件猜结构。
场景二：代码与数据库 schema 的关联排查。 这是工程中高频但工具支持很弱的一环：某张表要被下线或改字段，需要找出所有读写它的代码位置。ORM 抽象层往往让 grep 表名变得不可靠（表名可能来自常量拼接或迁移文件）。Graphify 把 SQL schema 与代码放进同一张图后，这类"表—代码"的双向查询就有了明确的落点。
场景三：把规范文档纳入检索范围。 团队常有一份 PDF 形式的接口规范或设计文档，与代码长期脱节。Graphify 支持 PDF 输入，意味着可以就"文档里描述的某个流程，实际代码是怎么实现的"进行跨来源提问，减少在文档与仓库之间反复切换的成本。
场景四：为 AI 助手提供更精准的上下文。 与其把大量文件切片塞进上下文窗口，不如先通过图查询定位到真正相关的节点子集再交给模型。这既能降低 token 消耗，也能减少"检索到似是而非的片段导致模型答偏"的情况。
适合谁用
- 维护大型多语言仓库的后端 / 全栈工程师：日常需要在跨模块、跨语言边界上追踪依赖，图谱能显著缩短定位时间。
- 数据工程师与后端数据侧开发者：经常要在 schema 与代码之间来回核对，这类"结构化但分散"的信息正是图谱的强项。
- 架构师与技术负责人：做影响面分析、依赖梳理、遗留系统摸底时，一张可视化的关系图比逐文件阅读更容易形成判断。
- AI 编程助手的重度用户：已经在用 Claude Code、Cursor、Codex 或 Gemini CLI，希望把助手的检索能力从"文本相似"升级到"结构可达"。
- 不太适合的情况：项目规模很小、单文件即可理解时，建图带来的收益可能低于其准备成本；只做单点问答、不需要跨文件关系推理的场景，也没有必要引入。
快速上手
整体路径是"装好 → 注册技能 → 指向仓库 → 建图 → 提问"，但具体命令、目录约定与参数以官方 README 为准。大致流程如下：
1. 获取仓库（仓库带有版本标签，例如 v8），按官方说明完成环境准备与安装。
2. 在目标助手（Claude Code / Cursor / Codex / Gemini CLI）中注册 /graphify 技能，使其能够被唤起。
3. 将技能指向要分析的项目目录，触发一次解析与建图。首次建图通常是最耗时的一步。
4. 图建好后，用自然语言向助手提问，由助手通过 /graphify 查询图谱并组织答案。
需要注意的是，Graphify 是"技能 + 图谱"的组合，宿主助手的配置方式差异较大，安装步骤请严格参照官方 README；仓库同时提供多语种文档，中文使用者可直接查阅对应翻译版本。
注意事项
- 首次建图的成本：解析是本地进行的，大型 monorepo 在首次全量建图时对 CPU 与磁盘会有明显消耗，耗时也可能较长。建议先在小范围目录上验证效果再铺开。
- 解析覆盖率决定效果上限：AST 解析对语言与代码形态有依赖。动态语言、代码生成产物、模板文件、宏展开等场景，往往无法被完整解析，图谱在这些区域可能出现缺失。遇到查询结果不全时，先确认对应文件是否被正确解析，而不是直接归因于模型。
- 图谱是快照，会随代码过期：代码持续变更后，图谱需要重建或增量更新，否则助手会基于过期结构作答。把它纳入日常流程（例如在较大改动后重建）比"建一次用很久"更可靠。
- PDF 等非结构化来源的抽取质量参差：扫描件、复杂排版、图表密集的 PDF，其文本抽取结果通常不稳定，涉及这类来源的问答需要人工复核。
- 隐私边界要分清两层：本地解析意味着建图过程不必把代码发往外部；但宿主 AI 助手本身的查询与推理环节是否联网、上下文是否外传，取决于该助手自身的配置，两者不能混为一谈。在受合规约束的环境中需要分别确认。
- 许可与义务：Apache-2.0 允许商用与修改，但要求保留版权与许可声明，且软件按"原样"提供、不附带担保。若在其之上做二次分发，需按许可要求处理声明与变更说明。
- 不要把图谱当作唯一事实来源：图谱是索引与导航，最终判断仍应回到源码本身。尤其在涉及重构、删表等高风险操作时，图谱给出的结论应作为线索而非结论依据。