graphify 跨仓库知识图谱实战：`graphify clone` 克隆 GitHub 仓库与 `merge-graphs` 多仓合并指南

graphify 跨仓库知识图谱实战graphify clone克隆 GitHub 仓库与merge-graphs多仓合并指南【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify导读本篇以 graphify 的 Trae 技能参考文档 github-and-merge.md 为主线系统讲解如何把一个或多个 GitHub 仓库 URL、或多个本地子目录变成一份可查询的统一知识图谱graph.json。你将掌握graphify clone的仓库克隆与复用机制、graphify extract的逐目录提取方式、以及graphify merge-graphs的跨仓库合并原理与实战参数最终把多套代码库做成一张携带repo来源标记的图谱并对合并后的图直接执行graphify query无需重新提取。适用触发器当用户传入一个或多个https://github.com/...URL或者点名要合并多个本地子文件夹为一个图谱时就应当加载本文档对应的处理流程。本文为纯 CLI 流程可服务于 CI、脚本与人工操作不依赖图形界面。一、先弄清命令全景clone / extract / merge-graphs / query 各管一段整个工作流由四条 CLI 子命令协作完成每一段都只解决一个问题子命令职责典型输入 → 产物graphify clone克隆 GitHub 仓库到本地缓存目录https://github.com/...→~/.graphify/repos/owner/repographify extract对单个目录跑完整提取流水线检测 → AST 提取 → 语义提取 → 合并 → 聚类一个本地路径 →该路径/graphify-out/graph.jsongraphify merge-graphs把多份graph.json合成为一张带repo来源标记的图N 份 graph.json → 一份合并图graphify query在既有图谱上直接问答graph.json 问题 → 图遍历结果输出目录默认名为graphify-out可通过环境变量GRAPHIFY_OUT覆盖支持相对名或绝对路径该默认值在 paths.py 中统一定义GRAPHIFY_OUT os.environ.get(GRAPHIFY_OUT, graphify-out)。注意它随进程启动前设置才生效因此所有命令共用同一套目录约定这是理解输出放哪的关键。核心判断一旦目标路径下已经存在graphify-out/graph.json后续任意代码库问题都会走快路径——直接graphify query该合并图不再重新提取也不受图体积门槛限制。二、Step 0克隆 GitHub 仓库仅在给出 GitHub URL 时执行2.1 单仓库克隆LOCAL_PATH$(graphify clone github-url [--branch branch]) # 后续所有步骤都以 LOCAL_PATH 作为扫描目标命令执行成功后在标准输出打印本地路径graphify clone的 CLI 分支在 cli.py 中直接print(local_path)因此可以直接用$(...)捕获路径供后续步骤使用。2.2 底层克隆逻辑源码级说明clone命令最终调用_clone_repo()cli.py其关键行为URL 归一化去掉末尾/若不以.git结尾则自动补.gitowner/repo 提取用正则github\.com://([^/]?)(?:\.git)?$解析识别不出合法 GitHub URL 时直接报错退出默认落盘位置~/.graphify/repos/owner/repo可用--out dir覆盖浅克隆git clone --depth 1只取最新快照重复运行复用目标已存在时不再 clone而是执行git pull origin -- branch拉取更新报Repo already cloned ... pulling latest...只有 pull 失败才打印 warning 并继续使用旧副本注意pull 失败不会中断流程见代码注释分支安全校验--branch以-开头会被判定为非法分支名并退出成功提示克隆或拉取结束打印Ready at: dest并返回该路径。2.3 多仓库克隆构建跨仓库图谱的输入阶段# 逐个克隆然后对每个仓库分别跑完整流水线最后合并 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.jsongraphify 始终克隆到~/.graphify/repos/owner/repo并在重复运行中复用既有克隆节省带宽与磁盘合并图中的每个节点都带repo属性因此可以按来源仓库过滤子图。三、多个本地子文件夹的合并monorepo 或多服务布局当需要合并的不是 GitHub 仓库、而是同一个工作区下的多个子目录时有一个关键陷阱必须先说清楚Skill 流水线会把全部中间产物与最终产物写到当前工作目录下的graphify-out/。如果对每个子文件夹分别跑一次 skill它们会互相覆盖同一个输出目录。因此正确做法是不要对每个子目录跑 skill而是直接用 CLI 对每个子文件夹分别执行graphify extract——CLI 会把graphify-out/放进被扫描路径内部见 cli.pyout_root out_dir.resolve() if out_dir else target再拼接graphify_out out_root / _GRAPHIFY_OUTgraphify 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|claude|openai|deepseek|ollama随后在项目根目录统一合并graphify merge-graphs \ ./core/graphify-out/graph.json \ ./service/graphify-out/graph.json \ ./platform/graphify-out/graph.json \ --out graphify-out/graph.jsongraphify extract是面向 CI/脚本的无头全流水线命令cli.py 用法注释detect → AST 提取代码 → 对文档/论文/图片做 LLM 语义提取 → merge → build → cluster → 写出。其可用参数还包括--model M、--mode deep、--out DIR|--output DIR--output是--out的别名、--google-workspace、--no-cluster、--no-gitignore、--code-only、--no-dedup、--max-workers N、--token-budget N、--max-concurrency N、--api-timeout S等多数设None即用库默认值。当graphify-out/graph.json一旦存在快路径即接管任何代码库问题直接在合并图上跑graphify query——无需重新提取也没有尺寸门槛。四、深入 merge-graphs合并时到底发生了什么merge-graphs要求至少传入两个 graph.json未指定--out时默认输出到graphify-out/merged-graph.jsoncli.py。其实现cli.py远比简单拼接复杂下面按执行顺序拆解4.1 输入归一化与图类型统一依次校验输入文件存在并执行图体积上限检查超限退出兼容历史版本若数据只有edges键而无links则重命名为links#738方向标记保留把每条边的_src/_tgt一并读入无则回退到source/target保证后续以无向图存储时不会丢失真实边方向#2261/#2309hyperedges 双槽位兼容node_link_graph只还原嵌套graph.hyperedges槽位若超图只存在于顶层键则做回退读取#2484/#2485图类型统一不同时间/路径产出的 graph.json 可能是Graph、DiGraph、MultiGraph、MultiDiGraph中的任意一种而nx.compose要求类型一致因此全部归一化为普通无向Graph#1606详见 cli.py。4.2 唯一 repo 标签杜绝同名目录坍缩merge-graphs从每个输入的graphify-out父目录名推导 repo 标签。朴素做法直接用目录名但src/graphify-out与frontend/src/graphify-out都会得到src会让不同实体的同 stem 节点 ID 碰撞、被nx.compose静默合并成不存在的跨运行时边#1729。distinct_repo_tags()build.py保证前缀唯一先按父目录名生成重复时用上级目录加宽为frontend_src仍重复则追加索引后缀-2、-3确保没有任何两份输入共享前缀。4.3 节点前缀化与来源标记每个图经prefix_graph_for_global()build.py处理所有节点 ID 改写为{repo_tag}::{原id}label保留原样仅用于展示节点写入repo repo_tag属性并新增local_id记录原始 ID边的_src/_tgt依据 relabel 表同步改写hyperedges 同步重挂成员节点 ID 走同一张 relabel 表映射超图自身的id也加repo_tag::前缀防止不同仓库的同名超图在合并后碰撞#2484/#1691。4.4 社区 ID 偏移避免跨仓库社区错误融合每个输入图都把社区从 0 开始编号若合并时原样携带仓库 A 的 community 0 与仓库 B 的 community 0 会被当成同一社区聚合视图把无关社区融合成一个 meta 节点#3014。因此合并时对后续输入逐个累加community_offset第一个输入保持原 ID偏移 0后续输入在加偏移的同时把原始社区记录到local_community保留各仓库自身的分区cli.py。4.5 跨仓库共享类型连接由于每个节点 ID 都加了仓库前缀两个仓库声明同一个契约类型时会产生两个互不相连的节点。link_shared_type_declarations()cross_repo_types.py按命名空间 名称 repo 标签分组对成员跨至少两个仓库、且同名声明在不同仓库间两两加边上下文为cross_repo这样图遍历就能跨越仓库边界——只连边、不合节点避免误并两个内容不同但同名的实体。若产生此类连接命令行会打印linked N type declaration(s) shared across repos。4.6 超图去重与写出合并后清掉 compose 残留的 hyperedges把收集到的全部前缀化超图交给attach_hyperedges按 id 去重重挂最终以node_link_data(..., edgeslinks)写出并恢复_src/_tgt标记的真实方向同时把超图写入顶层键#2485双槽位格式保证所有历史读取方都能读到。命令结束会打印Merged 3 graphs - 节点数 nodes, 边数 edges Written to: out_path五、合并之后对跨仓库图直接查询合并产物生成后后续环节与单仓库完全一致走 query.md 描述的快路径graphify query QUESTION # 或: graphify query QUESTION --dfs --budget 3000由于每个节点带repo属性、每个 ID 带repo_tag::前缀你可以按来源过滤——这既回答了这段逻辑在哪个仓库的溯源问题也让跨仓库调用/契约消费关系可视化。整个过程中没有向量库参与图由本地确定性 AST 解析与结构化的语义抽取构建每条边都有据可查这也是跨仓库图谱能被graphify query直接回答的根本原因。六、与其它参考文档的配合若问题针对既有图而非新建流程加载 query.md需要自定义语义抽取的节点/边/超图 JSON 结构、file_type六值code/document/paper/image/rationale/concept与节点 ID 规范时加载 extraction-spec.md合并完成后要导出 HTML / Obsidian / GraphML 等格式加载 exports.md涉及增量更新文件变更后只重跑变更部分加载 update.md涉及监听目录加载 add-watch.md涉及 hook 加载 hooks.md。七、测试证据与可验证边界merge-graphs的行为在仓库测试中有完整覆盖读者可在 tests/test_merge_graphs_cli.py 中核对输入图为有向/多图混合时正常合并test_merge_graphs_mixed_directed_and_multigraph同名 repo 目录不会坍缩、标签加宽保证唯一test_merge_graphs_same_named_repo_dirs_do_not_collapse、test_distinct_repo_tags_unit导入边方向在合并后得到保留test_merge_graphs_preserves_import_edge_direction断言边repo1::rota → repo1::collections等方向不变超图从所有输入携带、去重并兼容仅存在于顶层键的情况test_merge_graphs_carries_hyperedges_from_all_inputs、test_merge_graphs_hyperedges_dedup_on_shared_prefixed_id、test_merge_graphs_reads_top_level_only_hyperedges社区 ID 被偏移到共享 ID 空间、各仓库社区互不融合test_merge_graphs_offsets_communities_so_repos_do_not_fuse。这些测试既验证了上文所述的节点 ID 前缀、边方向还原、超图跨仓重挂与社区防碰撞等实现细节也构成了本指南各结论的直接依据。八、实操速查表与常见坑8.1 子命令与默认值速查操作命令产物位置克隆单仓库graphify clone url [--branch b] [--out dir]默认~/.graphify/repos/owner/repostdout 输出路径逐目录提取graphify extract path [--backend ...] [--out ...]默认path/graphify-out/跨仓合并graphify merge-graphs g1 g2 [...] --out out缺省graphify-out/merged-graph.json≥2 输入查询graphify query Q读取当前目录graphify-out/graph.json覆盖输出目录环境变量GRAPHIFY_OUT全局生效需进程启动前设置8.2 高频坑位Skill 与 CLI 的输出位置不同skill 写当前工作目录的graphify-out/CLI extract 写被扫描路径内部的graphify-out/。多子目录合并务必用 CLI否则互相 clobber。repo 目录同名两个输入的同名 graphify-out 父目录会让朴素标签碰撞distinct_repo_tags会加宽/加索引自动化解观察命令输出中的 note 即可确认。边方向合并图在内存中是无向Graph方向靠_src/_tgt标记保留并写出不要误以为方向丢失。backend 参数--backend支持gemini|kimi|claude|openai|deepseek|ollama取决于你设置了哪把 API Keygraphify extract会自动选择有 Key 的后端。克隆复用重复执行graphify clone会拉取更新而非重新克隆若要全新副本指定不同的--out即可。输出文章结束【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考