GitHub 仓库克隆与跨仓库图谱合并实战graphify 的 github-and-merge 技能全解析【免费下载链接】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当用户抛来一个或多个https://github.com/...地址或者点名要把多个本地子目录monorepo / 多服务布局合并进同一张知识图谱时graphify 的github-and-merge参考文档就是整套操作流程的操作手册。它回答了两件事如何把远端仓库拉回本地并按规范产出各自的graph.json以及如何用graphify merge-graphs把多份图谱无损地拼成一张带来源标记repo属性的跨仓库图让后续所有代码问答都直接命中合并结果。阅读完本文你将掌握graphify clone、graphify extract与graphify merge-graphs三个命令的完整配合方式理解合并背后的节点前缀化、图谱类型归一化、hyperedge 收集与跨仓库类型桥接等底层机制能够稳定地把任意 N 个 GitHub 仓库或本地子项目变成一张可查询的统一知识图谱。本文以 tools/skillgen/expected/graphify__skills__droid__references__github-and-merge.md 为骨架展开所有底层结论均可在仓库源码中验证。一、技能触发条件与整体心智模型github-and-merge参考文档的定义非常清晰当用户传入一个或多个 GitHub URL或点名要把几个本地子文件夹合并为一张图时加载。它位于每个 Agent 平台的references/目录下本仓库同一份文档在agents、amp、claude、codex、droid、opencode、vscode等目录下均有同名副本属于操作型技能它不是解释某条命令的语法而是规定 Agent 面对多仓库 / 多子项目任务时应当遵循的完整管线顺序。整条管线的思维模型可以压缩成三句话克隆凡是 GitHub URL先经graphify clone落到本地缓存目录逐仓产出每个仓库或子文件夹各自跑一遍完整抽取管线各自产出独立graph.json合并复用用graphify merge-graphs把多份图谱合并为一份此后代码问题全部走graphify query快速路径——不再重复抽取、不再受规模门限约束。二、单仓库克隆graphify clone的正确用法当用户只给了一个 GitHub 地址时按参考文档执行LOCAL_PATH$(graphify clone github-url [--branch branch]) # 后续所有步骤都以 LOCAL_PATH 为扫描目标克隆默认落在~/.graphify/repos/owner/repo重复执行相同 URL 时不会重复克隆而是复用已有克隆并增量拉取。从源码看该命令的完整形态在 graphify/cli.py支持graphify clone github-url [--branch branch] [--out dir]其中--out允许自定义落盘位置此时不会写入默认缓存目录。核心实现位于 graphify/cli.py有几点值得注意的实现细节行为源码依据URL 归一化去掉结尾/没有.git则补上cli.pyowner/repo 解析正则github\.com://([^/]?)(?:\.git)?$可同时接受https://github.com/owner/repo.git与 SSH 风格gitgithub.com:owner/repocli.py默认目标目录~/.graphify/repos/owner/repo跨运行复用cli.py已存在则git pull增量更新--branch传入git pull origin -- branchcli.py全新克隆使用git clone --depth 1浅克隆加快速度cli.py分支名校验以-开头的分支名直接报错退出cli.py--out的语义值得强调参考文档与源码默认把仓库克隆进用户级缓存~/.graphify/repos与业务扫描目录隔离保证重复运行对同一 URL 只做git pull而非重新拉全量只有显式传--out时才把克隆放进指定位置。三、多仓库跨仓库图谱先克隆、逐仓出图、再合并参考文档给出了跨仓库场景的标准三段式# 1) 克隆每个仓库 graphify clone url1 # → ~/.graphify/repos/owner1/repo1 graphify clone url2 # → ~/.graphify/repos/owner2/repo2 # 2) 对每个本地路径运行完整管线各自产出 graph.json # 3) 合并 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且重复运行复用既有克隆每一份图谱各自独立产出合并后每个节点都带有repo属性可按来源过滤。第三步正是上表第三条的落地——repo属性由 graphify/build.py 的prefix_graph_for_global在合并前缀化阶段写入每个节点其取值即该输入图谱对应的repo_tag。3.1 合并命令的源码级形态graphify merge-graphs的命令行协议在 graphify/cli.pygraphify merge-graphs graph1.json graph2.json [...] [--out merged.json]参数解析位置参数为待合并图谱路径--out指定输出未传--out时默认写到graphify-out/merged-graph.jsoncli.py少于两份输入时打印用法并退出每个输入在解析前都会先过图谱大小安全门限_enforce_graph_size_cap_or_exitcli.py其底层委托graphify.security.check_graph_file_size_cap超限直接报错退出从源头拒绝超大连锁解析兼容新旧格式早期运行可能写edges键加载时统一归一到links并用_src/_tgt内联标记保留链路原始方向避免node_link_graph回读时翻转端点见 cli.py 的注释#738 / #2261 / #2309成功合并后打印汇总Merged N graphs - X nodes, Y edges并给出输出路径。3.2 合并时发生了什么前缀化、去碰撞与超边重挂合并不是简单的dict.update拼盘源码里处理了四类多图合并特有的隐患理解它们有助于预判合并结果节点 ID 前缀化避免跨仓库碰撞#1729。每个输入图会拿到一个唯一、有语义的repo_tag所有节点 ID 被改写为repo_tag::原ID形式build.py。原因是各仓库graphify-out父目录名并不唯一——src/graphify-out与frontend/src/graphify-out都退化成src同 stem 的节点 ID 若不隔离就会被静默合并成无关实体。distinct_repo_tagsbuild.py保证每个输入的前缀互不相同若朴素目录名出现碰撞CLI 会打印note: repo dir names collide; using distinct tags: ...cli.py。图谱类型归一化为简单无向Graph#1606。不同来源的输入可能是DiGraph/MultiGraph/MultiDiGraph而nx.compose要求同型合并前统一转成 graphify 默认的简单无向图cli.py因为跨仓库合并视图本来就是无向的。hyperedge 边表先收集、再整体重挂#2484。nx.compose对 graph 属性的合并是dict.update逐次迭代会覆盖掉前一张图累积的 hyperedge 列表实现先收集每份输入经前缀化改写后的 hyperedge合并完成后再通过graphify.export.attach_hyperedges去重挂回cli.py。前缀化阶段本身也会改写 hyperedge 的成员 ID 与自身 ID加repo_tag::前缀见 build.py。社区编号偏移避免元节点串扰#3014。每个输入图都把社区从 0 编号直接合并会碰撞导致聚合社区视图把互不相关的社区熔成一个 meta-node前缀化时按累计最大社区 ID 递增偏移各输入的community字段原始值记录在local_communitybuild.py、cli.py。3.3 跨仓库共享类型的桥接合并前缀化后各仓库同时声明的契约类型如两个服务共享的 DTO会变成两个互不相连的repoA::X与repoB::X节点跨仓库遍历因此断开。merge-graphs合并完成后会调用 graphify/cross_repo_types.py 的link_shared_type_declarations把这类声明连起来并打印linked N type declaration(s) shared across reposcli.py对应 issue #3007。相关行为在 tests/test_cross_repo_shared_types.py 中有直接覆盖。3.4 输出与双槽位持久化合并结果经node_link_data序列化后同时写入两个 hyperedge 槽位嵌套的graph.hyperedges与顶层hyperedges保证新旧读取方都能拿到完整边表cli.py。文件写入走graphify.paths.write_json_atomiccli.py原子落盘避免进程中断留下半截 JSON。四、多本地子文件夹monorepo / 多服务绕开输出目录覆盖的坑这是参考文档重点警告的场景。skill 管线会把所有中间产物与最终产物写进当前工作目录下的graphify-out/因此在同一个 CWD 下对每个子文件夹分别运行 skill会互相覆盖同一个输出目录。对策是改用 CLI 直接对每个子文件夹执行graphify 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 # 按你持有的 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的命名本身可通过环境变量覆盖默认值来自os.environ.get(GRAPHIFY_OUT, graphify-out)graphify/paths.py既接受相对名如graphify-out-feature也接受绝对路径如/shared/graphify-out适用于 worktree 或共享输出目录场景后端参数按你实际配置的 API key 选取如注释所示若使用无需密钥的本地提取则无需追加--backend。合并完成后的graph.json中每个节点都带repo标签即输入仓库名因此可以用graphify query结合节点属性按来源过滤例如只回答只在 service 侧出现的问题。五、合并之后graphify query快速路径接管参考文档给出这条管线的收尾规则一旦graphify-out/graph.json存在任何代码库问题都直接跑graphify query查询合并后的图——不再重新抽取也不再有规模门限no re-extraction, no size gate。这一设计把昂贵的构建与廉价的应用彻底分离克隆、逐仓抽取、合并属于一次性成本产物是持久化的graph.json而日常问答只需在图数据上做查询。CLI 对传入图谱在做查询前同样会先执行图谱大小安全校验见 cli.py、cli.py、cli.py防止恶意或损坏的 JSON 拖垮进程——参考文档所称无规模门限是指无需重跑抽取管线而非跳过安全防护。六、如何验证与深入配套测试跨仓库合并的正确性在测试层有充分覆盖可作为进一步阅读的入口tests/test_merge_graphs_cli.py覆盖merge-graphsCLI 的端到端合并行为tests/test_cross_repo_shared_types.py验证跨仓库共享类型声明在合并后被桥接相连tests/test_global_graph.py覆盖prefix_graph_for_global/distinct_repo_tags所在的全局限定逻辑。七、小结三种入口、一条管线场景入口产物单个 GitHub URLgraphify clone url后跑完整管线单仓库graph.json多个 GitHub URL逐仓clone 逐仓管线 merge-graphs带repo属性的跨仓库图多个本地子文件夹逐目录graphify extract输出落在各子目录内 根目录merge-graphs合并后的统一graph.json无论哪条入口最终都收敛到同一结果一份可直接graphify query的合并图谱。参考文档管这套流程叫 fast path takes over——把跨仓库的认知成本压到一次合并里之后每一条代码问题都在一张图上作答这正是github-and-merge参考技能存在的意义。【免费下载链接】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），仅供参考