graphify 跨仓库图谱构建实战：从 GitHub 克隆到多仓库 graph.json 合并

本文基于 graphify 的 Codex 技能参考文档 github-and-merge.md，完整讲解当用户给出一个或多个 https://github.com/... URL、或需要把多个本地子目录合成一张知识图谱时的标准工作流：如何用 graphify clone 拉取仓库、如何对每个子目录独立执行 graphify extract、如何用 graphify merge-graphs 合并出带 repo 溯源属性的交叉仓库图谱，并深入源码说明节点前缀、社区 ID 偏移、超边归并与共享类型连接等底层机制。读完本文，你可以独立完成跨仓库/多服务的图谱构建，并直接在合并后的图谱上执行 graphify query。

适用场景：什么时候加载这份参考

参考文档开头给出了明确的触发条件：

Load this when the user passed one or more https://github.com/... URLs, or named several local subfolders to merge into one graph.

也就是说，两种入口都会走到这条流程：

1. 用户传入了 GitHub URL——需要先克隆到本地缓存目录，再对其执行完整流水线；
2. 用户点名多个本地子目录（monorepo 或 multi-service 布局）——需要对每个子目录分别抽取，再合并到项目根目录。

两条路径最终都收敛到同一个产物：一份 graphify-out/graph.json（或用户指定的合并输出路径），之后所有代码库问答都直接在这份合并图谱上运行 graphify query，无需重新抽取。

Step 0：克隆 GitHub 仓库（仅当给定 GitHub URL 时）

单仓库克隆

LOCAL_PATH=$(graphify clone <github-url> [--branch <branch>])
# 后续所有步骤都以 LOCAL_PATH 为目标路径

命令通过 shell 捕获 clone 的输出，把本地路径作为变量传给后续步骤。

多仓库：构建交叉仓库图谱

# 每个仓库分别克隆、跑完整流水线，最后合并
graphify clone <url1>   # → ~/.graphify/repos/<owner1>/<repo1>
graphify clone <url2>   # → ~/.graphify/repos/<owner2>/<repo2>
# 对每个本地路径分别运行 /graphify，生成各自的 graph.json
# 然后合并：
graphify merge-graphs \
  ~/.graphify/repos/<owner1>/<repo1>/graphify-out/graph.json \
  ~/.graphify/repos/<owner2>/<repo2>/graphify-out/graph.json \
  --out graphify-out/cross-repo-graph.json

参考文档同时说明了两条关键约定：

• Graphify 克隆到 ~/.graphify/repos/<owner>/<repo>，重复运行同一 URL 时会复用已有克隆（执行 git pull 而不是重新 clone）；
• 合并后图谱中的每个节点都带有 repo 属性，可以按来源过滤。

graphify clone 的源码实现

clone 子命令的实现在 graphify/cli.py 的 _clone_repo 函数中，可以对照参考文档逐条验证其行为：

• URL 规范化：先剥离尾部 /，再补上 .git 后缀用于实际克隆命令；
• owner/repo 提取：用正则 github\.com://([^/]+?)(?:\.git)?$ 解析 URL，无法识别的地址会直接报错退出（error: not a recognised GitHub URL）；
• 默认落盘路径：~/.graphify/repos/<owner>/<repo>，也可用 --out <dir> 覆盖；
• 浅克隆：首次克隆使用 git clone --depth 1，并支持 --branch <branch> 指定分支（分支名以 - 开头会被拒绝，避免与选项混淆）；
• 复用逻辑：目标目录已存在时改为 git pull（带分支时执行 git pull origin -- <branch>），pull 失败只打印 warning 而不中断，与参考文档"reuses existing clones on repeat runs"的表述一致；
• 命令入口在 graphify/cli.py 的 cmd == "clone" 分支中，完整用法为 graphify clone <github-url> [--branch <branch>] [--out <dir>]。

多本地子目录合并：monorepo 与 multi-service 布局

参考文档特别强调了一个陷阱：技能（skill）流水线会把所有中间和最终产物写到当前工作目录下的 graphify-out/。如果对每个子目录分别运行技能，各次运行会互相覆盖同一输出目录。正确做法是直接调用 CLI，因为 graphify extract 会把 graphify-out/ 放在被扫描路径内部：

graphify extract ./core/     # → ./core/graphify-out/graph.json
graphify extract ./service/  # → ./service/graphify-out/graph.json
graphify extract ./platform/ # → ./platform/graphify-out/graph.json
# 视你配置了哪个 API key，追加 --backend gemini|kimi|openai|deepseek|claude-cli

# 然后在项目根目录合并：
graphify merge-graphs \
  ./core/graphify-out/graph.json \
  ./service/graphify-out/graph.json \
  ./platform/graphify-out/graph.json \
  --out graphify-out/graph.json

要点：

• 每个子目录的产物路径形如 <子目录>/graphify-out/graph.json，天然隔离，不会互相覆盖；
• --backend 的取值取决于你本地配置的 API key（gemini、kimi、openai、deepseek、claude-cli）；
• 合并输出建议放在项目根目录的 graphify-out/graph.json，这样与单仓库布局的"快路径"保持一致。

合并后的快路径：graphify query 直接生效

参考文档最后一句给出了合并完成后的使用方式：

Once graphify-out/graph.json exists, the fast path above takes over: any codebase question runs graphify query directly on the merged graph — no re-extraction, no size gate.

即只要 graphify-out/graph.json 存在，代码库问答就直接在合并图谱上查询——不重新抽取、不走体积门槛检查。这让"克隆 → 抽取 → 合并"一次性建图后，后续所有跨仓库问答都是纯查询开销。

深入原理：graphify merge-graphs 在源码里做了什么

参考文档给出了命令形态，而实现细节集中在 graphify/cli.py 的 cmd == "merge-graphs" 分支。以下机制解释了合并图谱为什么可以正确表达"来自不同仓库的多个代码库"。

1. 参数解析与输入校验

• 用法：graphify merge-graphs <graph1.json> <graph2.json> [...] [--out merged.json]，至少需要两个输入图，否则打印 usage 并退出；
• --out 缺省时输出到 graphify-out/merged-graph.json；
• 每个输入文件都会先经过体积上限检查（_enforce_graph_size_cap_or_exit），加载后合并结果还要经过 10 万节点上限 的二次校验：超过 100_000 节点直接 sys.exit(1) 中止合并，防止产出不可用的巨型图谱；
• 格式兼容：graphify 通过 node_link_data 写出的键是 links，但旧版本可能用 edges（见源码注释中的 issue #738），加载前会做一次 edges → links 归一化。

2. 节点 ID 加仓库前缀，并写入 repo / local_id 属性

这是"每个节点带 repo 属性"这一承诺的实现来源。graphify/build.py 的 prefix_graph_for_global 函数：

• 将全部节点 ID 重写为 repo_tag::<原ID> 形式，label 保持不变（仍用于展示）；
• 为每个节点写入 repo 属性（值为仓库标签）和 local_id 属性（保存前缀前的原始 ID，便于回溯）；
• 边上的 _src/_tgt 方向标记同步重写到新 ID；
• 超边（hyperedges）的 nodes 成员与 id 也按同一张重命名表重写——否则合并后成员 ID 会悬空（源码注释引用的 #2484）。

3. 仓库标签去重：避免同名目录造成"静默合并"

graphify/build.py 的 distinct_repo_tags 解释了为什么不能简单地用"graphify-out 的父目录名"当标签：src/graphify-out 和 frontend/src/graphify-out 都会得出标签 src，两个仓库里同为 app 的节点就会被 nx.compose 静默合并成一个（issue #1729）。策略是：

1. 标签冲突时，用各自父目录名加宽（如 frontend_src）；
2. 仍重复则追加 -N 索引后缀，保证任何两个输入图绝不共享前缀；
3. 触发加宽时命令行会打印 note: repo dir names collide; using distinct tags: ...。

4. 社区 ID 偏移：让聚合社区视图不串库

每个输入图的社区编号都从 0 开始，原样带进合并图会导致不相干的社区融合成一个元节点（#3014）。因此在 graphify/cli.py 中，每合成一张输入图就累进一次 community_offset：prefix_graph_for_global 把偏移量加到节点的整数 community 上，并把原始值保留在 local_community 中；第一个输入保持偏移 0。

5. 图类型归一化与超边归并

• nx.compose 要求所有输入图同型。不同抽取路径产出的 graph.json 可能一个是 MultiGraph 另一个是 Graph，甚至方向性不一致（有向/无向），直接 compose 会抛出 "All graphs must be directed or undirected"（#1606），所以加载后统一转成无向 nx.Graph；
• nx.compose 对图级属性是"后写覆盖前写"，超边列表若放任不管只剩最后一个输入的内容。源码先把每个输入图的超边收集到统一列表，compose 后清掉残留，再用 attach_hyperedges 按 ID 去重后整体挂回（#2484）；
• 写盘时同时输出 graph.hyperedges 嵌套槽位和顶层 hyperedges 键（#2485），保证新旧读取器都能读到；
• 输出前用输入时保存的 _src/_tgt 标记恢复每条边的真实方向，最后经 write_json_atomic 原子写入（该函数位于 graphify/paths.py）。

6. 跨仓库共享类型连接：same_type_as 边

这是交叉仓库图谱最有价值的特性之一，实现在 graphify/cross_repo_types.py。由于所有节点 ID 都加了仓库前缀，两个服务各自声明的同一契约类型（比如消息事件契约）在合并图中是两个互不相连的节点；link_shared_type_declarations 会对"命名空间 + 类型名相同、且来自至少两个不同仓库"的声明两两加一条边：

• 关系名 same_type_as，context="cross_repo"，confidence="INFERRED"，confidence_score=0.9；
• 只加边、不合并节点——两边各自保留自己的成员、文件与出处信息，避免掩盖两个仓库间契约的漂移；
• 要求命名空间匹配，防止"只是短名撞车"的两个类被误连（模块 docstring 中给出的实证：一对 .NET 服务共 1440 + 262 个声明类型，仅 7 对 EventManager.Models.*Event 契约被连接，无其他误配）。

合并完成后命令行会打印 linked N type declaration(s) shared across repos 以及最终的节点/边统计和输出路径。

验证：对应的测试用例

合并链路的正确性由仓库中的测试锁定，排查行为时可以直接对照：

• tests/test_merge_graphs_cli.py：覆盖 merge-graphs 命令的参数解析、标签冲突、方向恢复等 CLI 行为；
• tests/test_cross_repo_shared_types.py：覆盖跨仓库同名类型的 same_type_as 连接逻辑；
• tests/test_build_merge_shrink_guard.py 与 tests/test_build_merge_hyperedges_and_prune.py：覆盖增量合并（merge_raw_extraction）时的节点缩水保护与超边保留。

小结

参考文档 github-and-merge.md 给出的最小操作序列可以浓缩为三步：

场景	命令	产物
单仓库 GitHub URL	graphify clone <url> [--branch <b>]	~/.graphify/repos/<owner>/<repo>（浅克隆，重复运行转 pull）
多仓库 / 多子目录	对每份路径分别跑流水线或 graphify extract <子目录>/	各自的 <路径>/graphify-out/graph.json
合并	graphify merge-graphs a.json b.json ... --out <out>	带 repo 属性节点、same_type_as 跨界边的合并图谱

合并完成后，graphify query 直接作用于合并图谱，不再触发重新抽取。理解源码层面的节点前缀、标签去重、社区偏移与超边归并机制后，你可以准确判断合并结果中任意一条边、任何一个 repo 过滤维度的来源，并定位标签冲突或方向丢失等边界问题的处理位置。