今天 GitHub Trending 第 5 位是 Graphify-Labs/graphify,单日新增 1,407 星。同一时刻从 GitHub API 读回来:132,382★、12,688 个 fork,主语言 Python,Apache-2.0,建仓 2026 年 4 月 3 日,最近一次发布是 10 月 20 日的 0.9.93。PyPI 上这个包已经留下 261 个版本记录——半年多,平均一天一个多。
它要解决的是一个很具体的浪费:Agent 回答"这个函数在哪、谁在调它、改它会不会炸",每轮都得 grep 一遍、read 一遍,把十几个文件塞进上下文;下一次会话,同样的活再干一遍。graphify 的做法是先把整个仓库压成一张图,之后让 Agent 查图。
一句话定位:不是 RAG,是给代码修一张路网
- 入口是一条命令:
/graphify .,扫完当前目录,吐出三个文件——graph.html、GRAPH_REPORT.md、graph.json。之后 Agent 用graphify query、graphify path、graphify explain对着graph.json提问,不再反复读源文件。 - 它明确拒绝向量库。README 原话是"不是向量索引,没有 embedding,没有向量存储,是一张真的可以走的图"。节点是函数、类、文件、文档概念,边是
calls、imports、inherits、semantically_similar_to这类关系。 - 代码部分完全免费、完全本地。tree-sitter 做 AST 解析,不调用任何模型,建图这一步的 LLM 额度消耗是 0。只有文档、PDF、图片这类非代码输入,才需要一次语义解析。
- 热度不是靠新模型。这个仓库 4 月就建了,今天这波是 10 月 20 日 0.9.93 发布之后的自然发酵;0.9.93 的更新日志写着合并了 22 个社区 PR,修的全是 Kotlin 类型别名、C# 委托、Swift 宏、Rust 同模块
use这种细到语言语法层的解析问题。
仓库背后是 YC S26 的 Graphify Labs,README 顶部并排挂着商用产品 Graphify Cloud 的 14 天试用入口。开源版是完整的本地工具,云版卖的是"跨仓库、常驻、带 Sentry/Jira 连接器"的那一层。这个结构要提前知道:你用的是 Apache-2.0 的本地版,不是阉割版,但也不是他们全部的生意。
产出三件套:一个能点的网页、一份报告、一份能反复查的 JSON
| 产物 | 里面是什么 | 谁在用 |
|---|---|---|
graph.html | 力导向图,节点按社区上色,可点、可搜、可按社区过滤 | 人,第一次看清新仓库的结构 |
GRAPH_REPORT.md | 枢纽节点(god nodes)、社区划分、意外连接、建议追问的问题、导入环 | 人,做架构 review |
graph.json | NetworkX node-link 格式,节点带 id/label/file_type/source_file/source_location,边带 relation/confidence/confidence_score | Agent 和脚本,反复查询 |
README 里给了一段 FastAPI 仓库上的真实输出,能看出查询粒度:
| |
explain 回答"这个东西是什么、连了谁",path 回答"A 到 B 怎么连上的",query 用一句自然语言换回一张限定范围的子图。三个命令都落在同一个 graph.json 上,不重新读代码。
导出不止这三种:还能出 Markdown wiki(每个社区一篇)、SVG、GraphML、Obsidian vault、Cypher,以及推到 Neo4j 或 FalkorDB。对想把图接进现有数据栈的人,这一层是加分项。
核心一:代码解析全在本地,建图不烧一个 token
这是它和"把仓库喂给大模型总结"最根本的分歧点。
- 依赖里 30 个基础包,26 个是 tree-sitter 语法包。Python、JS/TS、Go、Rust、Java、C/C++、C#、Ruby、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、Elixir、Objective-C、Julia、Verilog、Fortran、Bash、JSON 都在里面,冷门的还有 Solidity、Terraform、Robot Framework、COBOL、Pascal、Common Lisp、OCaml。
graphify/extractors/目录下有 34 个提取模块,除语言外还包括 SQL 表/视图/外键、Markdown、JSON 配置、.sln工程文件。- 语言数量三个口径对不上:README 写"约 40 种",
docs/how-it-works.md的 Pass 1 写"25 种",实际目录是 34 个模块。对外宣传取最大的,文档细节取保守的,这种不一致在小步快跑的项目里很常见,但你别拿"40 种"去要求冷门语言的支持质量。 - 增量与并行:每个文件按 SHA256 指纹缓存,
--update只重抽改动过的文件;AST 抽取走ProcessPoolExecutor多进程,官方在 84 个代码文件的语料上测到比串行快约 1.66 倍。 - 升级会触发全量重抽。0.9.91、0.9.92、0.9.93 三个版本的更新日志都写着"AST 缓存 schema 变了,升级后第一次构建会重新解析"。这不是 bug,但意味着升级当天别安排大仓库的重建。
真正的收益不在"省下解析时间",而在"省下上下文":代码结构变成一份可以按需切片的 JSON,Agent 只取相关子图,不用把整个文件读进来。
核心二:每条边都标了"读到的"还是"猜的",这是最值钱的设计
大多数代码图谱工具只告诉你"A 调用 B",graphify 多给一个字段:这条关系是怎么来的。
| 标签 | 含义 | 可信度 |
|---|---|---|
EXTRACTED | 源码里写明的:import、直接调用、继承声明 | 固定 1.0 |
INFERRED | 解析器推导出来的:跨文件调用解析、上下文共现 | 0.95 / 0.85 / 0.75 / 0.65 / 0.55 五档 |
AMBIGUOUS | 拿不准,写进报告等人看 | 不给分,只标记 |
我把仓库里现成的 worked/karpathy-repos/graph.json 下载下来数了一遍:177 个节点、246 条边,其中 203 条 EXTRACTED、43 条 INFERRED,没有 AMBIGUOUS。边上的 source_location 能回到具体行号,_src/_tgt 两个字段保留方向——因为这个文件写的是 "directed": false,方向只存在于弧的顺序里,直接拿 NetworkX 的 node_link_graph() 读会把方向丢掉。
这个设计解决的是 Agent 最让人不放心的地方:它给你的结论,哪些是查到的,哪些是推的。 当 Agent 说"改这个类会波及三个服务",你能顺着 INFERRED 边回查它凭什么这么判断;如果全是猜的,至少标签会告诉你。
官方自己在 BENCHMARKS.md 里承认了这套标签的边界:在 FastAPI 的生产代码上抽查 12 条跨文件 INFERRED 边,12 条全对;但 tests/ 目录里的同名辅助函数会让 INFERRED 的 calls 边变脏。也就是说,标签的可信度跟语料干净程度直接相关,别把它当成形式化证明。
核心三:社区、枢纽节点和路径查询,回答的是"结构问题"
图建好之后,它能答的问题和 grep、向量检索不是一类。
| 你想知道 | 该用什么 | 为什么 |
|---|---|---|
| 这个仓库分几块、各块管什么 | GRAPH_REPORT.md 的社区划分 | Leiden 算法按边密度聚类,不靠 embedding,标签由模型或人工给 |
| 哪几个概念是全仓的咽喉 | god nodes 排行 | 度数最高的节点,改它们风险最大 |
| 两个看起来无关的模块怎么连上的 | graphify path A B | 图上的最短路径,每一跳都有关系类型 |
| 改这个函数会波及什么 | 邻域查询 + graphify prs 的影响面 | 顺着 calls/imports 反向走 |
| 这段代码具体怎么写的 | 还是得读源码 | 图只存结构,不存实现 |
这也决定了它不适合什么:让 graphify 回答"这个正则为什么这么写"、“这个循环的边界条件对不对”,它给不了;图里没有函数体。把它当"索引"而不是"理解",预期就对了。
和站内写过的两条路子放一起看更清楚:context-mode 是在 MCP 层把原始数据挡在上下文外,靠的是 FTS5 检索;hindsight 是把对话沉淀成长期记忆网络;graphify 走的是第三条——把代码本身变成结构化的图。三者解决的不是同一个问题,可以叠着用。
核心四:隐私边界不是一句"本地优先",要按文件类型分开看
README 把"local-first"写得很显眼,但真正的边界是分层的:
| 输入 | 在哪处理 | 要不要 API Key |
|---|---|---|
| 代码文件 | 本地 tree-sitter,不出机器 | 不要,纯离线可跑 |
| 视频 / 音频 | 本地 faster-whisper 转写 | 不要 |
| 文档、PDF、图片 | 语义解析,交给会话里的模型或你配置的后端 | 要,或复用当前会话额度 |
- 纯代码仓库可以完全离线:
graphify extract不配置任何 key 也能建图;混合仓库加--code-only,只索引代码,跳过需要模型的那部分。 - 后端优先级是自动探测的:Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama,探测时会打印是哪条环境变量做的决定,避免"以为在本地、其实发出去了"。要强制本地就
GRAPHIFY_BACKEND=ollama。 - Kimi 这个后端走的是 Moonshot 在国内的服务器,README 自己写明了。涉及数据出境/入境的团队,这一条要先看清楚。
- 没有遥测,但有查询日志:每次
query/path/explain都会写一行 JSON 到~/.cache/graphify-queries.log(时间、问题、语料、返回节点数、耗时),完整子图默认不存。介意的话GRAPHIFY_QUERY_LOG_DISABLE=1。 - 安全上做了基本功课:抓 URL 只允许 http/https 并拦
file://跳转,图文件路径必须落在graphify-out/内,节点标签会清洗控制字符、截到 256 字符。
一句话:代码不出门是真的,文档和 PDF 会出门也是真的。别用"本地优先"这四个字覆盖全部输入。
怎么用起来:两条命令,三个坑
最短路径是这样,README 自己标了"30 秒":
| |
然后在助手会话里输入 /graphify .(Codex 里是 $graphify .)。就完了。
坑在这几处:
- 包名是
graphifyy,双 y。PyPI 上其他graphify*包与他们无关,README 专门写了这一句。装错包的风险不在功能,在供应链。 - 23 个宿主,安装方式并不统一。Claude Code、CodeBuddy、Codex、OpenCode、Kilo、Copilot CLI、VS Code 聊天、Aider、OpenClaw、Factory Droid、Trae/Trae CN、Gemini CLI、Hermes、Kimi Code、Amp、Kiro、Pi、Cursor、Devin CLI、Antigravity,外加跨框架的
.agents/skills。有的写 hook,有的只写AGENTS.md或.cursor/rules规则文件——后一种不会"自动"提醒 Agent 查图,只是常驻一句提示。 .graphifyrc不配,图会"看着有内容"但实际缺符号。.h是 C 还是 C++,.m是 Objective-C 还是 MATLAB,.inc是 PHP 还是 Pascal,解析器只能选一个全局默认;选错不会报错,只会安静地少掉真符号。项目里写一行language.inc=php就能定死。
想让它常驻,graphify install --project 把技能装进当前仓库(.claude/skills/graphify/ 或 .agents/skills/graphify/),再 graphify hook install 在每次 commit 后自动重建。团队里还可以用 graphify prs 看 PR 的 CI 状态、评审状态和它落在哪个社区、和哪些 PR 抢同一块代码。
数字:哪些能核对,哪些只是自家口径
官方 BENCHMARKS.md(最后更新 2026-07-05)给的是一张横向对比表,对手是 mem0、supermemory、BM25、dense RAG:
| 基准 | graphify | 对手 | 我的读法 |
|---|---|---|---|
| LOCOMO(n=300)问答准确率 | 45.3% | supermemory 49.7%、mem0 27.3% | 它不是第一,但 ingest 成本只有 supermemory 的约 1/11 |
| LOCOMO recall@10 | 0.497 | BM25 0.362、mem0 0.048 | 检索召回这一项确实是全场最高 |
| LongMemEval-S(n=50) | 76% | dense RAG 76%、mem0 70% | 打平,不是超越 |
| ERPNext 跨工具(n=6) | 82.0% | grep/read 70.8% | 样本只有 6 题,方向可信,幅度别当真 |
| 建图 LLM 成本 | $0 | 多数系统按 token 计费 | 这条可以自己验证:断网、不配 key 也能建代码图 |
| LOCOMO ingest 成本 | 约 $1.40 | supermemory $15.67、mem0 $3.48 | 差一个数量级,是最实在的优势 |
几个必须打折的地方:
- 这是自家 harness。所有系统在同一套脚本里跑、同一个模型(Kimi K2.6)、同样的预算,方法上算规矩,但题目选择和评分标准仍由项目方定。judge 和第二 judge 的一致性 90.6%、Cohen’s kappa 0.81,这个披露比多数记忆类基准诚实。
- supermemory 的 recall 0.149 被官方自己标了星号:它自托管时锁死 768 维英文 embedder,和共用的 BGE-m3 不是一回事,所以那一列不可直接比。要比就看问答准确率。
- n=6 的代码基准撑不起"提升 11 个百分点"的结论。ERPNext 是约 100 万行的真实仓库,题目只有 6 道,每查询约 14 万 token。它证明的是"有图比纯 grep 强",不是"强 11%"。
- token 节省随语料规模剧烈变化。
docs/how-it-works.md的表格写得很清楚:52 个文件的混合语料省 71.5 倍,4 个文件 5.4 倍,6 个文件的 httpx 约 1 倍——六个文件本来就塞得进上下文,图在这里的价值是结构清晰,不是压缩。商用云页面上"砍掉 80% token"是产品口径,别当成你仓库的承诺。
另一面:13 万星和 721 个未关 issue 同时存在
把仓库的账翻开会看到另一幅图景:
- 721 个未关 issue、905 个未关 PR、1,355 个已关 issue。PR 积压比 issue 还多,说明社区提交很活跃,也说明维护带宽跟不上提交速度。
- 版本号还在 0.9.x,半年发了 261 个版本。节奏快是优点,代价是行为会变:缓存 schema 一改就全量重抽,CLI 输出和
graph.json字段也在动。 - 每版几十个修复,细到语法层。Kotlin 的
typealias、C# 的delegate、Swift 的macro、Rust 的同级mod use、C++ 里的 CUDA 限定符——这些不是"锦上添花",是解析器能不能认出符号的生死线。反过来说,你用冷门语言时,遇到解析缺边的概率不低,遇到问题先去 issue 里搜语言名。 - 图会过期。代码改了图不重建,Agent 拿到的就是旧地图;靠 hook 或 CI 才能缓解,这不是装完就一劳永逸的工具。
- 星数不等于质量。13 万星说明它踩中了"Agent 上下文太贵"这个真痛点,不说明它在你的仓库上一定准。
我的判断:谁该上、谁再等等、谁别碰
这三类人值得今天就装。
- 仓库在十万行以上、或者多服务互相调用的人。grep 出来的结果是一堆同名函数,图给的是"谁真的连到谁",这是两种体验。
- 每天让 Agent 改代码、又怕它"没看全就动手"的人。
path和explain的输出带行号和置信标签,比"我觉得应该没问题"可查。 - 想把代码库交给新同事或新 Agent 快速熟悉的人。
graph.html加GRAPH_REPORT.md是现成的架构导读,比自己画图快。
这三类可以先等等。
- 项目只有几十个文件、一个服务的人。六个文件的语料上收益约等于 1 倍,多装一层工具只是多一个要维护的产物。
- 主要拿 Agent 写文档、做内容的人。你的语料是 Markdown 和 PDF,语义解析要花 token,图的收益不如直接检索。
- 团队没有 CI 或提交钩子习惯的人。图不自动更新,三天后就失真,最后还是回去 grep。
这三类别碰。
- 把图当唯一真相的人。INFERRED 边是推导,
tests/里的同名函数就能让它变脏;关键改动还是要读源码。 - 代码不能出内网、却随手配了云后端的人。代码确实不出门,但你一旦让它解析 PDF 和图片,数据就去了模型那边;要么
--code-only,要么 Ollama。 - 从非官方渠道装"打包版"的人。包名只认
graphifyy,仓库只认Graphify-Labs/graphify。
最后说一个不用装也能拿走的点:“每条边标明来源类型"这个设计,值得抄进任何自建的知识库。 不管你是用向量库还是用文件,给每条结论加一个"直接读到 / 推导出来"的标记,人和 Agent 的信任成本都会降一截。想继续看 Agent 上下文这条线上的其他做法,可以读我们写过的 context-mode 怎么把 102KB 压成 530B,以及 ponytail 怎么用一套规则管住 Agent 的过度发挥。
本文由拾光札记编辑部整理,勘误请联系我们