Graphify 全面解析 & GitNexus 替换评估

一、Graphify 架构速览

一句话:tree-sitter AST 提取器 + networkx 图 + Leiden 社区检测 + 10 种导出格式 + 9 种 Agent 平台集成脚本。 零 LLM 依赖,"智能"部分全部外包给宿主 Agent(Claude Code / Codex / OpenCode / ...)。

依赖(全部本地库,无 LLM SDK)

# 核心
networkx
tree-sitter >= 0.23.0
tree-sitter-{python,javascript,typescript,go,rust,java,c,cpp,ruby,
             c-sharp,kotlin,scala,php,swift,lua,zig,powershell,
             elixir,objc,julia}  # 22 种语言

# 可选 extras
mcp            # MCP server
neo4j          # 直推图数据库
pypdf          # PDF 文本提取
graspologic    # Leiden(否则回落 Louvain)
python-docx    # Office
faster-whisper # 视频转写
yt-dlp         # YouTube 下载

二、执行流程 & 关键发现

# 实际执行顺序(由 skill.md 协调)
detect.detect(root)                        # detect.py:329  扫描+分类
  ↓ 并行
  ├── extract.extract(code_paths)          # extract.py:2639  tree-sitter AST
  └── [宿主 Agent subagent 读 PDF / 图 / markdown] → JSON
cache.save_semantic_cache(...)             # cache.py:119
build.build([ast_result, semantic_result]) # build.py:84
cluster.cluster(G)                         # cluster.py:59  Leiden/Louvain
analyze.god_nodes + surprising_connections # analyze.py:42/61
report.generate(...)                       # report.py:14
export.to_html / to_json / to_obsidian     # export.py:329/285/447

三、核心模块逐个解剖

3.1 extract.py(2804 行) —— 真正的发动机

架构模式:LanguageConfig dataclass(extract.py:24-60)+ 通用 _extract_generic()(extract.py:645-1010)+ 每种语言一个配置实例 + 少数语言特有的 walker。

class LanguageConfig:
    class_types        # 哪些 tree-sitter 节点类型算"类"
    function_types     # 哪些算"函数"
    import_types
    call_types
    name_field         # 默认从哪个 field 拿名字
    body_field
    function_boundary_types  # 递归到这里停
    import_handler     # 每种语言 import 语法不一样,单独回调
    resolve_function_name_fn # C/C++ 用 declarator 解包
    extra_walk_fn      # JS 箭头、C# namespace 等特殊分支

13 种语言走通用路径(extract.py:419-627),7 种独立手写(因为 tree-sitter 节点命名差太大): extract_go(190 行)extract_rust(168 行)extract_zig、 extract_powershell、extract_objc、extract_elixir、extract_julia。

两遍 walk:

1. 结构 walk(extract.py:703-866):进 class 建节点 + contains/method/inherits 边;进 function 记下 body 挂到 function_bodies 列表
2. 调用图 walk(extract.py:877+):对每个 function body 再 walk,找 callee 名字,查 label_to_nid 建 calls 边

3.2 detect.py(502 行) —— 文件扫描

• _looks_like_paper()(detect.py:68)用 13 条正则(arxiv / doi / \cite{} / \d{4}\.\d{4,5})判断一个 .md 是不是学术论文转出来的 —— 命中 ≥3 条升级为 PAPER
• _SENSITIVE_PATTERNS(detect.py:33-40)过滤 .env / .pem / id_rsa / aws_credentials —— 默认不读密钥文件
• _SKIP_DIRS(detect.py:238)自动跳 venv / node_modules / .git / dist / build
• .graphifyignore 支持向上查找到 .git 目录为止(detect.py:266)
• convert_office_file(detect.py:194)把 .docx / .xlsx 转 markdown sidecar,哈希命名避冲突

3.3 cache.py(154 行) —— SHA256 内容缓存

• file_hash = SHA256(content) ⊕ SHA256(resolved_path)(cache.py:20)—— 路径加进哈希防同内容碰撞
• 贴心细节:Markdown 的 YAML frontmatter 会先剥离再哈希(cache.py:10-17),metadata 变更(reviewed/status/tags)不触发重抽取
• 存成 graphify-out/cache/{hash}.json,os.replace 原子写

3.4 cluster.py(137 行) —— Leiden / Louvain

• 先试 graspologic.partition.leiden,失败 fallback 到 networkx.community.louvain_communities(cluster.py:22-52)
• 孤立点(degree 0)Leiden 会 warning,单独抠出来每个自成一个社区(cluster.py:77-91)
• 大社区限制 _MAX_COMMUNITY_FRACTION = 0.25:超过总节点 25% 的社区二次 Leiden 拆分(cluster.py:93)
• 最后按 size 降序重编号 —— 社区 0 永远是最大的(可复现)
• PowerShell 5.1 缓冲污染 workaround:graspologic 会吐 ANSI 转义,专门包了 redirect_stdout(cluster.py:11-20,issue #19)

3.5 analyze.py(537 行) —— "智能"层

其实都是 networkx 一行题。

god_nodes(analyze.py:42)= dict(G.degree()) 排序,过滤掉文件节点 + concept 节点,取 top_n。 所谓"god nodes" = 度数最高的真实实体。_is_file_node(analyze.py:11-38)过滤三类伪节点:文件级 hub、.method() 方法桩、孤立 func()。

_surprise_score()(analyze.py:131-184)是一个朴素加权:

• 置信度加成:AMBIGUOUS +3 / INFERRED +2 / EXTRACTED +1
• 跨文件类型(code↔paper/image)+2
• 跨 repo(顶级目录不同)+2
• 跨社区(Leiden 说结构上远)+1
• semantically_similar_to 关系 ×1.5
• 低度节点(≤2)连到高度节点(≥5)+1,生成 "peripheral → hub" 叙述

3.6 serve.py(364 行) —— MCP 服务器

暴露 7 个 MCP 工具:query_graph、get_node、get_neighbors、get_community、god_nodes、graph_stats、shortest_path(serve.py:156-226)。

3.7 export.py(1001 行) —— 十种输出

• to_json / to_cypher / to_html(交互 vis.js 单文件)/ to_obsidian(每节点一 md,每社区一 hub,带 wikilinks)
• to_canvas(Obsidian Canvas)/ push_to_neo4j(bolt 协议直推)/ to_graphml(Gephi/yEd)/ to_svg
• MAX_NODES_FOR_VIZ = 5_000(export.py:19)—— 超过就不出 HTML

3.8 security.py(197 行) —— SSRF 防护

validate_url 解析 hostname → getaddrinfo → 拒绝 is_private / is_reserved / is_loopback / is_link_local,加黑名单 metadata.google.internal (security.py:14-64)。_NoFileRedirectHandler 重写 HTTPRedirectHandler, 每次 redirect 都重新校验一遍 —— 防 open-redirect SSRF。写一个抓取模块就自带这种层次的防护,不常见。

四、"GraphRAG" 噱头验证

"GraphRAG" 按微软原论文定义:LLM 抽实体 + LLM 抽关系 + LLM 写社区摘要 + 分层答案合成。Graphify 对齐情况:

结论:这不是 GraphRAG,是"一个有置信度标签的 tree-sitter 代码图谱工具 + Obsidian 导出器 + 9 个 Agent 平台的 SKILL.md 胶水"。 技术本身合格(8k LOC 大部分在 extract.py 真的干活),但把它叫 "GraphRAG AI 架构助理" 是营销话术。

五、"71.5× token 节省" 真相

拆开 benchmark.py 看(benchmark.py:1-130):

_CHARS_PER_TOKEN = 4
corpus_tokens   = corpus_words * 100 // 75   # 1 词 ≈ 1.33 token
query_tokens    = BFS 子图渲染文本长度 // 4
reduction_ratio = corpus_tokens / avg(query_tokens of 5 个固定英文问题)

# 5 个固定问题(benchmark.py:55-61)
"how does authentication work"
"what is the main entry point"
"how are errors handled"
"what connects the data layer to the api"
"what are the core abstractions"

六、设计亮点(这些可以抄)

七、技术短板

1. 22 语言"支持"很不均匀:只有 Python 做了跨文件 uses 推断,其他 21 种只有"同文件级 calls + imports"。多语言 polyglot 项目图质量会肉眼可见不如 Python。
2. _extract_python_rationale(extract.py:1011)基于 docstring 的 "X because Y" heuristics 脆得很。
3. 查询不是语义搜索,是子串 +1/+0.5 打分,没有 embedding/BM25/stemming。中英混合语料不友好。
4. _make_id 用 re.sub(r"[^a-zA-Z0-9]+", "_", combined)(extract.py:14)—— 对中文/非 ASCII 标识符直接 collapse 成空串,中文代码库识别不了。
5. C++ 模板/宏、Python metaclass/装饰器动态类、JS Proxy/Reflect 这类 AST 看不穿的东西通通识别不出来 —— 本质上是静态结构提取。
6. benchmark 的 71.5×:固定 5 个英文问题 + 子串匹配选起点。
7. 无类型系统:没有 symbol table、没有 type env、没有方法解析顺序(MRO)。
8. _is_file_node 启发式(analyze.py:11-38)在非 Python 语言下容易误伤 —— Go/Rust 函数都是 () 结尾,又按 degree 判断……补丁摞补丁。
9. PyPI 包名 graphifyy(两个 y,因为 graphify 被占),看得出作者赶时间。

八、GitNexus vs Graphify 对比

你的工作看板现在用的是 ~/Projects/code/20260319-gitnexus/(来源 abhigyanpatwari/GitNexus,17.8k stars,浏览器端 WASM 方案)。

ast-cache.ts           call-processor.ts         call-routing.ts
cluster-enricher.ts    community-processor.ts    entry-point-scoring.ts
export-detection.ts    filesystem-walker.ts      framework-detection.ts
heritage-processor.ts  import-processor.ts       language-config.ts
mro-processor.ts       named-binding-extraction.ts
parsing-processor.ts   pipeline.ts               process-processor.ts
resolution-context.ts  structure-processor.ts    symbol-table.ts
tree-sitter-queries.ts type-env.ts               type-extractors/
resolvers/             workers/

九、最终建议