Graphify为AI编程助手打造代码地图，查询耗时和Token消耗最多降71.5倍！
Graphify：为AI编程助手打造代码地图，查询耗时和Token消耗最多降71.5倍！
在大型代码库开发场景中，AI编程助手（CodingAgent）面临的主要瓶颈并非代码理解能力，而是缺乏对代码库整体结构和关系的全局认知，只能反复低效地“重新摸索”。Graphify通过构建代码知识图谱，为AI提供了结构化的“导航地图”，将高成本的原始理解过程转化为一次性的基础设施构建，显著提升了AI的查询效率和分析精度，在测试中实现了耗时和Token消耗的大幅降低。
CodingAgent：在代码仓库里，90%的时间都在迷路
很多研发同学都熟悉这样的场景：在大型代码仓库上变更代码，需要熟悉项目业务逻辑或评估代码变更影响时，一般会让CodingAgent通读整个项目代码。它会先根据目录结构猜测项目入口，再从入口文件开始逐级调用工具阅读代码。当上下文塞满后，就开始压缩上下文，导致上下文信息丢失。经过漫长的代码阅读和大量Token消耗，CodingAgent最终给出的结论还可能因上下文窗口限制而不精确。而且，下次开发时还得重复这个流程。
这并非特定CodingAgent的问题。Reddit的r/ClaudeCode下有个热度不低的帖子《Claude Code isn't getting worse. Your codebase is just getting bigger》，指出代码库过万行后，AI就开始挑着读，且顾头不顾尾。
实际上，CodingAgent的瓶颈并非“理解代码的能力”。即便模型参数再多、上下文窗口再长，把它放到陌生代码库中，它仍需慢慢摸索，就像新员工入职第一天就被要求重构代码，问的都是基础问题，如“这段代码在哪儿？谁在用它？”没有地图，聪明反而成了累赘，就像聪明人走进原始森林，和笨人能做的事差不多。
Graphify：给CodingAgent的地图
Graphify：生成代码地图
Graphify官方定位为“一款AI编程助手的技能”，它不是常见的个人知识管理工具，而是用于构建更易被CodingAgent使用的知识地图。它不依赖文件嵌入和相似度检索，而是将实体和关系构建成显式图谱，查询时在图上遍历，这更接近资深工程师探索陌生代码库的方式，先构建系统结构，再按结构深入，而非对源代码进行模糊搜索。
它能将代码（类、函数、导入、调用图、docstring、解释性注释）以及需求、设计、接口文档、论文、图片等辅助理解材料转化为结构化“地图”。有了这张“地图”，CodingAgent就能更好地理解、设计和编写代码。
Graphify：代码仓库的第二大脑
有人会问，Claude Code、Codex等Agent的Coding能力已很强，为何还需要Graphify？答案在于“能跑”和“跑得好”的差距。
对于边界清晰、依赖简单、业务通用且失败代价低的新项目或模块，CodingAgent凭自身能力可完成大部分工作。但随着时间推移，代码库会积累复杂度、历史债和隐性知识，项目不再“干净”。复杂度源于业务本身，一个简单表单可能关联多张数据表、多个外部系统和定制逻辑；历史债来自迭代，一些“临时方案”长期运行却无人敢动；隐性知识则存在于离职工程师的记忆、未更新的设计文档和口口相传的经验中，CodingAgent仅靠读源码难以稳定理解。
问题的本质是业务与系统知识未被结构化沉淀，只有口口相传和不健全的文档，AI反复重读源码，理解成本越来越高。Graphify将这些知识从“人脑可读”转化为“AI可导航”，把代码结构、模块关系、业务语义、设计意图编译成显式知识图谱，这是给AI用的导航系统，告诉它系统架构、各部分连接方式以及概念对应的接口和文件。所以，Graphify更像AI编程助手的“第二大脑”，与负责推理和代码生成的LLM第一大脑分工协作，让CodingAgent从“每次都重新摸索”变为“直接定位、精准作答”。
为何不直接用LLM：上下文再大，也只是个漏斗
Microsoft Research 2025年的实验表明，LLM的上下文利用率在100K token后会降至60%左右，输入越多输出越差，这不是窗口容量问题，而是注意力分配问题。Chroma的“Context Rot”研究对GPT - 4.1、Claude 4、Gemini 2.5等18个主流模型的测试结果一致：token越多，质量越差，即便未达到窗口上限。Morph LLM的实测显示，Claude Code执行35分钟任务，通常会累积80K到150K的token消耗，模型窗口即便有1M，50K左右就开始出错。这就像超大号冰箱，虽能装很多东西，但AI找东西时却无从下手。
为何不使用Vector RAG：RAG是个近视眼
主流AI Agent的检索方案Vector RAG，将代码和文档切块、向量化后进行相似度匹配，简单通用但有短板，只能找出“长得像”的内容，找不到“逻辑上连着”的内容。FalkorDB用Diffbot的KG - LM Benchmark对比发现，单跳查询时，Vector RAG与GraphRAG准确率相当，但多跳查询时，Vector RAG准确率从94%骤降至34%，复杂查询时只剩28%，而GraphRAG稳定在89%，文档规模超10万时，Vector RAG四成查询直接失败。在代码世界中，它无法将相关片段串联起来，像近视眼一样，只能看到眼前的相似度，看不到背后的关系网。
上手Graphify：快速构建代码仓库知识图谱
安装
全局安装Graphify并在Claude Code中安装Skill，安装文档参考：。
```
pip install graphifyy && graphify install
```
PyPI包当前叫"graphifyy"，因为"graphify"名字在回收中，CLI命令和skill命令仍为"graphify"。安装完成后，会在`~/.claude/skills/graphify`目录下安装 [SKILL.md](http://SKILL.md) 文件。
生成图谱
从项目根目录启动Ducc，调用graphify skill生成图谱：
```
> ./graphify .
⏺ 生成详细步骤，此处省略...
⏺ ---
Graph complete. Outputs in /Users/zhangjinlong01/Documents/projects/bsp/dave/server/src/graphify-out/
graph.html - interactive graph (community view, 313 nodes), open in browser
GRAPH_REPORT.md - audit report
graph.json - raw graph data
Token reduction: 10x fewer tokens per query (256k words → ~34k tokens per question)
---
```
初始化创建图谱使用claude sonnet 4.6模型，耗时5分钟23秒，消耗tokens：2.4k input、20.6k output。图谱生成后，项目根目录下会自动生成`graphify-out`目录，包含以下文件：
```
> tree -LACa 1 ./graphify-out/
# ./graphify-out/
# ├── .graphify_labels.json
# ├── .graphify_python
# ├── .graphify_root
# ├── GRAPH_REPORT.md <-- 摘要报告
# ├── cache <------------ 增量缓存
# ├── cost.json
# ├── graph.html <------- 可交互图谱
# ├── graph.json <------- 可持久查询的图结构
# ├── manifest.json
# └── wiki <------------- 构建可供Agent抓取的wiki（index.md + 每个community一篇文章）
```
使用图谱
在CodingAgent中可通过以下3种方式使用图谱：
- **常驻模式**：[CLAUDE.md](http://CLAUDE.md)文件中增加系统指令，让AI回答问题或搜索时优先看“地图”，而非直接看代码。
```
## graphify
This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
Rules:
- ALWAYS read graphify-out/GRAPH_REPORT.md before reading any source files, running grep/glob searches, or answering codebase questions. The graph is your primary map of the codebase.
- IF graphify-out/wiki/index.md EXISTS, navigate it instead of reading raw files
- For cross-module "how does X relate to Y" questions, prefer `graphify query ""`, `graphify path "" ""`, or `graphify explain ""` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
```
- **显示触发**：通过`/graphify`技能实现。
```
/graphify query "DAG流程是如何进行调度的"
/graphify explain "Task Controller"
/graphify path "Task Controller" "Etcd Watcher / Dispatcher"
```
- **MCP**：Graphify提供MCP供AI调用，日常使用较少，此处不赘述。
**更新图谱**：软件不断更新迭代，代码或文档修改后，可使用`/graphify update .`保持知识图谱同步，防止知识“过期”。第一次建图如数据库“初始化索引”，后续更像“增量维护索引”，Graphify生成的图谱应像代码一样纳入仓库维护，它提供了完善的自动维护手段。
揭开面纱：原理拆解
生成阶段：把知识写成普通文件
调用技能生成图谱的创建过程如下：
- **第一阶段：AST提取**：用Tree - sitter解析21种主流语言，它是增量式parser生成器，每种语言有社区维护的grammar，输入源代码可输出结构化语法树。Graphify遍历语法树，将函数定义转为节点，import转为依赖边，函数调用转为调用边，此过程不消耗LLM token。
- **第二阶段：LLM语义抽取**：AST只能看到结构，看不到函数意图。此时并行调用Claude子Agent处理文档、论文和图片，提取概念、关系和设计动机，与AST节点连接，形成“代码 + 语义”双层图。文档语义抽取需模型先读取文档，再提取概念、关系、理由、相似性等并写入Graph，抽取结果是核心语义层，而非拆碎的原文。
- **第三阶段：Leiden社区聚类**：这是图论经典算法，比Louvain算法稳定性好，它将图谱中高度相关的节点组织成“主题”，类似微信好友圈。代码或文档中频繁引用的部分会形成一个社区，每个社区代表一个功能簇，如微服务、领域模块或独立业务逻辑组。
- **第四阶段：输出结果**：将结构化结果生成为GRAPH_REPORT、graph.json、graph.html等不同视图，满足不同使用场景。Graphify输出中“God Nodes”是连接度高、代表系统核心抽象的枢纽节点，“Hyper Edges”表示多节点的Group关系。
查询阶段
没有图谱时，模型通常根据输入问题推理，如从目录结构推断程序入口、逐步文件探索或用关键词查找分析。这种方式对小型且结构清晰的代码库有效，但对中大型代码仓库，存在覆盖度有限、分析偏差和Token消耗大的问题。
在Graphify里，执行`/graphify query`时，图谱先为AI助手提供方向和定位，告知查看的源文件和位置，AI助手通过代码或文档完成证据闭环得到答案。
效果对比：有图谱 vs 无图谱
官方数据显示，在混合语料例子中，查询时最多能减少71.5倍的tokens。这表明真正昂贵的不是模型本身，而是每次重新读原始文件。Graphify将高成本的“原始理解”变为一次性构建，后续查询变为低成本图谱导航，其价值不仅在于可视化，更在于将理解转化为基础设施。
查询业务执行流程
- **测试问题**：通读项目代码，给出DAG流程从创建 -> DAG调度执行 -> Task调度执行 -> DAG执行完成（含各种完成态）的完整流程。
- **测试方法**：在使用Graphify与不使用Graphify增强的两种场景下，让CodingAgent自主探索，输出答案并对比时间和Token成本。限制AI不能参考项目已有说明与报告文档。
- **测试工具**：Claude Code/Claude Sonnet 4.6。
- **测试结论**：使用Graphify + 源码时，较使用纯源码，耗时降低约60%，输入输出Tokens降低约80%。
**使用纯源码**
执行过程和成本消耗有相关图示。产出包括Bug根因分析与解决方案，涉及DAG详情接口、手动触发接口、调度器的问题及解决方案，核心思路是提取统一的`canRunManuallyWithTriggerRule`辅助函数，三个场景共用同一套判断逻辑。
**使用Graphify + 源码**
执行过程中很多文件通过图谱定位，成本消耗有相关图示，产出为AG生命周期流程，包括DAG创建、调度触发、调度执行、Task调度执行、完成判定和完成态汇总等详细内容。
查询模块运行机制
- **测试问题**：流程引擎的认证、授权及多租户是如何实现。
- **测试方法**：同查询业务执行流程的测试方法。
- **测试工具**：Claude Code/Claude Sonnet 4.6。
- **测试结论**：使用Graphify + 源码时，较使用纯源码，耗时降低约30%，输入输出Tokens降低约55%。
**使用纯源码**
执行过程和成本消耗有相关图示，产出为认证、授权与多租户实现的详细内容，包括认证的两种机制（UUAP认证和Service Token认证）、授权的接口设计、RBAC鉴权流程、资源抽象、授权位置，多租户的Namespace概念、系统预置Namespace、Role与Namespace绑定、集群级权限以及中间件链等。
**使用Graphify + 源码**
执行过程有相关图示，成本消耗有相关图示，产出为认证、授权与多租户实现分析，包括认证的两种独立机制（UUAP SSO和ServiceToken）、授权的RBAC模型、鉴权流程、全局开关和DummyAuthorizer，多租户的隔离层次、RoleIndex的namespace隔离和数据流，以及整体架构总结和设计亮点。
开源项目对比：Graphify vs GitNexus
GitNexus：把知识锁进自己的工具
GitNexus口号是“Zero - Server代码智能引擎”，索引和可视化在浏览器运行，不依赖云端服务。但其Parser部分进行AST抽取，存储层用嵌入式图数据库，二进制格式默认存于用户HOME目录下的`~/.gitnexus/`。访问层只通过MCP Server对外暴露查询接口，这意味着代码知识被锁在其工具里，建完索引后只能按其规则访问，换机器需重建，团队共享需额外工程化操作。
Graphify：把知识写成普通文件
Graphify通过四个阶段生成文件类型的知识图谱，CodingAgent可直接读取文件获取图谱数据，无需额外组件支持和限制，还可将图谱纳入GIT管理，实现团队共享。
别让工具变成必经之路
GitNexus将知识锁在工具里，Graphify将知识变为可流通数据。GitNexus索引技术合格，但它成为工作流必经之路，任何环节出问题，链路就会瘫痪且难以及时察觉。而Graphify生成文件并伴随代码进入GIT管理，在团队协作中更实用。
Graphify并不是银弹
Graphify虽能提升AI对系统结构的理解效率，但不能替代源码、业务文档、架构约束和稳定的研发流程。
- **不能替代源代码**：Graphify可帮AI找到相关结构和概念，但最终确认函数参数签名、分支逻辑执行和异常抛出位置等问题，仍需回到代码中。合理用法是先用Graphify查地图，再回源码看现场，Graphify缩小搜索范围，源码提供最终证据。
- **更适合“带着问题查地图”**：Graphify图谱适合明确问题查询，如业务概念与代码的关联、处理场景的接口、接口更改可能影响的代码和业务等。但真实开发中需求开始往往不明确，需先细化需求，再用Graphify查询知识辅助AI理解系统和编码。
- **大规模项目开发需要“组合拳”**：Graphify擅长问题驱动的知识查找，但大规模项目中一些“整体认知型”知识，如业务理解和编码规范，更适合AI完整阅读文档，碎片化检索可能破坏内容完整性。
- **图谱本身也可能出错**：无类型的动态语言和Java Spring的依赖注入、反射、动态分发会让图谱出错，且错误隐蔽，不易发现。
后记：AI时代的地图，是给CodingAgent的
过去两年研发中使用CodingAgent，但很多同学使用还处于初始阶段，在小规模任务上还行，代码库规模增大就失灵。原因是“智能不等于全局认知”，AI即便参数多、训练数据丰富，也无法从已有代码反推具体项目架构，这是信息不对称问题。
知识图谱就是给CodingAgent的地图，它不惊艳，需花费时间构建、持续维护并与代码一起纳入GIT。但完成后，CodingAgent就能从迷茫访客变为熟悉路径的行家。所以，当CodingAgent在代码库中迷茫时，别急着升级模型或增加上下文，先给它画张地图。