graphify 跨仓库知识图谱：graphify clone 拉取 GitHub 仓库与 merge-graphs 合并多库图谱的完整实战

本文基于 graphify 仓库中面向 Kiro Agent 的技能参考文档 github-and-merge.md，讲解当用户传入一个或多个 GitHub 仓库地址（或指定多个需要合并进一张图谱的本地子目录）时，如何用 graphify clone 与 graphify merge-graphs 构建可查询的跨仓库知识图谱。读完本篇，你将掌握仓库克隆缓存机制、跨库图谱合并的正确姿势、monorepo 多子目录场景的避坑方法，以及合并产物中 repo 标签与跨仓库类型连接的底层原理。

适用场景：什么时候触发这条流程

参考文档开篇给出了明确的加载条件：当用户传入了一个或多个 https://github.com/... 形式的仓库地址，或者指定了多个需要合并进同一张图谱的本地子文件夹时，就应使用本文档描述的流程。整个流程分为三个阶段：

1. Step 0 —— 如果给了 GitHub URL，先用 graphify clone 把仓库拉到本地缓存目录；
2. 逐库/逐子目录跑管线 —— 对每个目标路径执行提取，产出各自的 graph.json；
3. 合并 —— 用 graphify merge-graphs 把多份 graph.json 合成一张跨库图谱，之后直接对它做 graphify query。

下面按文档原始脉络逐步展开，并在每个环节结合 graphify/cli.py 的源码印证实际行为。

Step 0 单仓库克隆：graphify clone 的缓存与分支控制

对单个 GitHub 仓库，文档给出的标准操作是：

LOCAL_PATH=$(graphify clone <github-url> [--branch <branch>])
# Use LOCAL_PATH as the target for all subsequent steps

命令执行后会把克隆得到的本地路径打印到 stdout，因此可以直接用命令替换捕获为 LOCAL_PATH，供后续所有步骤使用。这一行为可以在 clone 子命令的派发逻辑中得到确认：命令末尾的 print(local_path) 正是为 shell 捕获设计的（见 graphify/cli.py）。

clone 命令支持两个可选参数，从 graphify/cli.py 的参数解析循环可以确认：

参数	作用
--branch <branch>	克隆或拉取时指定分支；若分支名以 - 开头会直接报错退出
--out <dir>	覆盖默认缓存目录，把仓库克隆到自定义路径

其底层实现 _clone_repo（见 graphify/cli.py）有三个关键行为值得注意：

• URL 规范化：先剥掉结尾的 /，若 URL 不带 .git 后缀则补上再交给 git clone；并通过正则从 URL 中提取 owner/repo 用于拼接缓存路径。非 GitHub 风格的 URL 会报错退出。
• 浅克隆：首次克隆使用 git clone --depth 1，只拉取最新提交，对"只为建图"的场景足够且更快。
• 重复运行复用克隆：默认克隆目录为 ~/.graphify/repos/<owner>/<repo>。如果目标目录已存在，命令不再克隆，而是执行 git pull（指定分支时追加 origin -- <branch>）来更新到最新——这与文档中"reuses existing clones on repeat runs"的表述一致。若 pull 失败只会打印 warning，不会中断流程。

多仓库场景：逐库跑管线，再 merge-graphs

文档给出的跨仓库（cross-repo graph）完整操作序列是：

# Clone each repo, run the full pipeline on each, then merge
graphify clone <url1>   # → ~/.graphify/repos/<owner1>/<repo1>
graphify clone <url2>   # → ~/.graphify/repos/<owner2>/<repo2>
# Run /graphify on each local path to produce their graph.json files
# Then merge:
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-out/graph.json，最后一次性合并。文档特别强调了一条贯穿始终的不变量：合并后图谱中的每个节点都携带 repo 属性，可以按来源仓库过滤。这条属性是 merge-graphs 在合并阶段写入的，后文会看到具体实现。

多个本地子目录：为什么必须绕开技能管线

对于 monorepo 或多服务布局（多个本地子文件夹要合并进一张图），文档指出了技能流程的一个陷阱：技能管线会把所有中间产物和最终产物都写到当前工作目录下的 graphify-out/。如果在每个子目录上分别以技能方式运行，后一次运行会覆盖（clobber）前一次的输出目录。

正确的做法是直接用 CLI 对每个子目录执行 extract——CLI 模式会把 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
# Add --backend gemini|kimi|openai|deepseek|claude-cli depending on which API key you have set

# Then merge at the project root:
graphify merge-graphs \
  ./core/graphify-out/graph.json \
  ./service/graphify-out/graph.json \
  ./platform/graphify-out/graph.json \
  --out graphify-out/graph.json

注意两点：

• 文档明确提示 extract 可追加 --backend gemini|kimi|openai|deepseek|claude-cli，取决于你配置了哪家 API 的 key；
• 合并步骤建议在项目根目录执行，输出到根目录的 graphify-out/graph.json，与技能管线的默认输出位置一致。

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

文档结尾说明了一个重要收益：一旦 graphify-out/graph.json 存在，"fast path"就接管了——任何针对代码库的问题都直接对合并后的图谱执行 graphify query，无需重新提取，也不受大小门槛（size gate）限制。也就是说，跨库合并完成后，日常问答的查询成本与单库场景相同，重活儿（克隆、逐库提取、合并）只在更新仓库时才需要重复。

源码纵深：merge-graphs 到底做了什么

merge-graphs 的完整实现在 graphify/cli.py。结合源码，文档中"每个节点携带 repo 属性"背后的机制可以拆解为以下环节：

参数与输入校验

• 用法为 graphify merge-graphs <graph1.json> <graph2.json> [...] [--out merged.json]，至少需要两个图谱文件，否则打印用法并退出（见 graphify/cli.py）；
• --out 缺省时输出到 graphify-out/merged-graph.json；
• 每个输入文件都会先经过大小上限检查：超过 _MERGE_MAX_NODES = 100_000（见 graphify/cli.py）的合并结果会中止，防止产出无法使用的巨型图。

输入归一化：兼容新旧格式

合并前对每份 graph.json 做防御性归一化（见 graphify/cli.py）：

• 旧版本可能把边写在 edges 键下，新版为 links，两者自动兼容；
• 用 _src/_tgt 标记在加载前后保存边的真实方向，避免无向图加载丢失方向信息；
• hyperedges（超边）若只存在于文件顶层而非嵌套的 graph 槽位，会回退读取顶层键，防止超边在合并中静默丢失。

此外所有输入图被统一转成普通的无向 nx.Graph（_to_simple，见 graphify/cli.py），因为不同提取路径产出的图可能是 DiGraph 或 MultiGraph，直接 nx.compose 会因类型不一致而报错。

节点前缀与 repo 标签

合并的核心动作是对每份图调用 prefix_graph_for_global，用"仓库标签"前缀所有节点 ID。仓库标签由 distinct_repo_tags 生成：默认取 graphify-out 的父目录名作为标签，但如果多个输入的目录名冲突（例如 src/graphify-out 与 frontend/src/graphify-out 都会得到 src），标签会自动加宽为 父目录_目录名（如 frontend_src），再辅以序号后缀保证唯一。源码注释指出这是为了防止不同仓库中同名的节点被 nx.compose 悄悄合并成同一个实体。

这正是文档所说"merged graph carries a repo attribute"的来源：前缀化的节点 ID 与 repo 节点属性一起，让查询和可视化都能按来源仓库过滤，也支持后续按标签把某个仓库的节点从图中剪掉（prune_repo_from_graph，见 graphify/build.py）。

社区 ID 偏移与超边保全

每份输入图的社区编号都从 0 开始，直接合并会让不同仓库的社区号撞车。合并逻辑为每份输入分配递增的 community_offset（第一个输入保持原编号），把各仓库的社区号平移进统一的编号空间（见 graphify/cli.py）。超边则先收集所有输入的前缀化超边，在 compose 完成后再以并集形式重新挂回，避免 dict.update 式的覆盖只留下最后一份输入的超边。

跨仓库同型类型连接：same_type_as

合并阶段还有一个专门的跨库语义连接：link_shared_type_declarations（模块说明见 graphify/cross_repo_types.py）。由于所有节点 ID 都被仓库标签前缀化，两个服务各自声明的同一个契约类型在合并图里是两个不相连的节点——例如消息总线场景中，生产者仓库引用 SyncProductUpsertToSearchEvent，消费者仓库实现 IConsumer<SyncProductUpsertToSearchEvent>，合并图原本无法在这两者之间走通一跳。

该处理对"命名空间 + 类型名都相同、且分属不同仓库"的类型声明两两添加一条 same_type_as 边（confidence="INFERRED"，confidence_score=0.9，context="cross_repo"）。源码注释给出了一个实测例子：在一对分别声明了 1440 和 262 个类型的 .NET 服务上，"命名空间+名称"匹配只产生 7 对边，全部是共享的 EventManager.Models.*Event 契约类型——说明要求命名空间能很好地抑制误连。注意它只加边、不合并节点：两个仓库的契约副本可能已经漂移，合并会掩盖这种差异，保留各自的成员、文件与来源信息更稳妥。合并完成后，终端会打印 linked N type declaration(s) shared across repos 提示连接数量（见 graphify/cli.py）。

输出

合并结果通过原子写（write_json_atomic）落盘，并同时维护 links 与 hyperedges 双槽位，终端输出形如 Merged 2 graphs -> N nodes, M edges 与最终文件路径。测试侧，合并流程的行为由 tests/test_merge_graphs_cli.py 覆盖，跨库同型连接由 tests/test_cross_repo_shared_types.py 验证。

小结与适用限制

回到文档本身给出的心智模型，整个流程可以浓缩为三句话：

1. 给了 GitHub URL：graphify clone 落到 ~/.graphify/repos/<owner>/<repo>，浅克隆、可指定分支、重复运行自动 git pull 复用；
2. 多目标合并：无论目标来自 GitHub 克隆还是本地子目录，都是"每个目标独立产出 graphify-out/graph.json，再一次性 merge-graphs"；本地多子目录场景务必用 CLI 的 extract（输出在扫描路径内部）而非技能管线（输出固定写当前目录），否则输出目录会被互相覆盖；
3. 合并产物即查询入口：合并后的 graph.json 节点带 repo 属性，graphify query 直接可用，不需要重新提取。

需要留意的适用前提与限制：合并要求每份输入图都已成功产出（至少两个输入文件），合并结果超过约 10 万节点会被上限保护中止；clone 仅识别 GitHub 风格的 URL；社区视图在合并后是各仓库分区平移拼合的结果，跨仓库的连通语义主要由 same_type_as 等显式连接提供。