graphify 跨仓库知识图谱实战graphify clone 与 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当你手头有多个服务仓库、多个 monorepo 子目录甚至只是想基于 GitHub URL 直接对陌生项目做结构分析时graphify 的/graphifyskill 提供了一条完整的克隆 → 抽取 → 合并 → 查询链路。本文以 graphify/skills/opencode/references/github-and-merge.md 这份官方参考文档为主线逐步拆解graphify clone、graphify merge-graphs两条命令的用法与边界并结合 graphify/cli.py、graphify/build.py 的源码实现说明合并过程中的节点前缀、社区 ID 偏移与跨仓库类型关联等底层机制读完你可以独立完成跨仓库知识图谱的构建与检索。何时加载这条链路参考文档开宗明义当用户传入一个或多个https://github.com/...形式的 URL或者指定了多个本地子目录要合并成一张图时才需要走这条 reference。它覆盖两类典型场景跨仓库cross-repo图谱每个服务一个独立仓库各跑一遍完整 pipeline 再合并多子目录monorepo 或 multi-service 布局图谱同一个仓库内有若干独立可扫描的子目录。两类场景最终都收敛到同一个产物一份合并后的graph.json之后任何代码结构问题都直接对合并图执行graphify query无需重新抽取也不受体积门限约束原文档称之为 fast path。Step 0用 graphify clone 克隆 GitHub 仓库只有当输入是 GitHub URL 时才需要这一步。单仓库LOCAL_PATH$(graphify clone github-url [--branch branch]) # Use LOCAL_PATH as the target for all subsequent stepsclone子命令的完整用法形如Usage: graphify clone github-url [--branch branch] [--out dir]命令成功时会在最后一行打印本地路径源码中print(local_path)因此可以直接用$(...)捕获后作为后续 pipeline 的目标路径。多仓库cross-repo 图谱# 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源码印证clone 的四个关键行为结合 graphify/cli.py 中_clone_repo的实现文档中clone into~/.graphify/repos/owner/repoand reuses existing clones on repeat runs这句话可以展开为四个确定行为URL 归一化与校验自动补全/剥离.git后缀再用正则从 URL 中提取owner/repo不是 GitHub URL 会直接报错退出error: not a recognised GitHub URL。浅克隆首次克隆执行git clone --depth 1指定--branch时附加--branch branch参数只取单个 commit体积最小。复用已有克隆若目标目录默认~/.graphify/repos/owner/repo可用--out覆盖已存在则改跑git -C dest pull带 branch 时是pull origin -- branch而不是重新克隆——这就是重复运行复用已有克隆的实现来源。输出可脚本化最后一行统一打印Ready at: dest后返回dest供 shell 变量捕获。一个值得注意的细节--branch的值若以-开头会被判定为非法分支名并退出这是对选项解析误判的防御。多个本地子目录用 CLI 的 extract 代替 skill pipeline参考文档特别强调了一个容易踩的坑skill pipeline 会把所有中间与最终产物写到当前工作目录下的graphify-out/。如果对着每个子目录各跑一次 skill后一次会覆盖clobber前一次的输出目录。正确做法是直接调用 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 # 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注意--backend参数当需要对非代码内容文档、笔记等做 LLM 语义增强时按你手头配置的 API key 选择对应后端纯 AST 结构抽取则不需要。merge-graphs 做了什么前缀、标签与冲突消解graphify merge-graphs接收多个graph.json路径与一个--out输出路径。它的实现位于 graphify/cli.py配合 graphify/build.py 中的两个工具函数完成了五件关键的事。1. 每个节点打上 repo 前缀与 repo 属性prefix_graph_for_globalgraphify/build.py#L2005-L2057把输入图的每个节点 ID 重写为repo_tag::原 ID显示用的label保持不变原 ID 存入local_id属性便于回溯每个节点都会写入repo属性——这正是参考文档所说Each node in the merged graph carries arepoattribute so you can filter by origin的落点后续按来源仓库过滤、或删除某一仓库的所有节点prune_repo_from_graph都依赖这个属性边的_src/_tgt方向标记与超边hyperedge成员 ID 会同步重写到前缀形态超边 ID 本身也加前缀防止不同仓库同名超边冲突。2. 仓库标签自动消歧repo tag 的默认取值是graphify-out的父目录名。但src/graphify-out与frontend/src/graphify-out都会得到 tagsrc两个同名 tag 会把无关实体悄悄合并成同一节点源码注释中标注为 #1729。distinct_repo_tagsgraphify/build.py#L2060-L2085的消解策略是先检测冲突冲突时把标签加宽为父目录名_目录名如frontend_src仍重复则追加-2、-3索引后缀保证任意两张输入图的标签唯一。标签冲突时 CLI 会在终端打印一行提示note: repo dir names collide; using distinct tags: ...。3. 社区 ID 偏移每张输入图都从 0 开始编号自己的 community若原样带入合并图不同仓库的 community 0 会撞号聚合社区视图会把不相干的社区融合成一个元节点#3014。merge 处理因此按输入顺序维护一个community_offset第一张图保持原 ID其后每张图的community被平移到共享 ID 空间原始编号保留在local_community属性中。4. 混合图类型归一化不同 extract 路径在不同时期写出的graph.json其directed/multigraph标志未必一致而nx.compose要求所有输入图同型。实现里会把 DiGraph / MultiGraph / MultiDiGraph 一律归一为普通无向Graph合并出的跨仓库视图本来就以无向方式消费避免All graphs must be directed or undirected崩溃#1606。tests/test_merge_graphs_cli.py 用一个DiGraph Graph MultiGraph三合一输入验证了这条归一化路径并断言输出directed为false、multigraph为false且三张图的节点全部存活同一测试文件还覆盖了同名仓库目录不得折叠#1729场景def test_merge_graphs_same_named_repo_dirs_do_not_collapse(tmp_path): # #1729: two graphs under a same-named repo dir (src/graphify-out and # frontend/src/graphify-out both → tag src) share the src:: prefix, ... app_nodes [n for n in data[nodes] if n[id].endswith(::app)] assert len(app_nodes) 25. 跨仓库同名类型自动连线消息总线型架构里最有价值的一跳往往跨仓库producer 在一个仓库引用SyncProductUpsertToSearchEventconsumer 在另一个仓库实现IConsumerSyncProductUpsertToSearchEvent。由于所有节点 ID 都带仓库前缀这两个同名类型声明在合并图里默认互不相连。link_shared_type_declarationsgraphify/cross_repo_types.py在 compose 之后补上这层连线把namespace 类型名相同、且分属至少两个不同仓库的类型声明两两之间加一条same_type_as边confidenceINFERRED、confidence_score0.9、contextcross_repo。两个设计取舍值得注意要求 namespace 完全相同只凭短类名相同就连线会把无关类型误连源码 docstring 提到在一对 .NET 服务上namespacename 匹配产生 7 对全部是共享的事件契约零误报只加边、不合并节点两个仓库可能持有发生漂移drift的契约副本合并节点会掩盖这种漂移而连线既允许遍历跨越仓库边界又让两侧各自保留自己的成员、文件与来源信息。触发时 CLI 会打印linked N type declaration(s) shared across repos。此外merge 过程还会对超边做先收集、后重挂的并集处理——nx.compose合并图属性时会用 dict.update 覆盖若放任不管只有最后一张输入图的超边能存活#2484因此实现里先收集每张图前缀化后的超边、compose 完成后再统一去重挂回且同时写入顶层与graph内两个存储槽位与to_json的双槽形态保持一致。最终结果经原子写入落到--out指定路径并打印Merged N graphs - X nodes, Y edges。合并之后query 走 fast path按参考文档的收尾描述一旦graphify-out/graph.json存在后续所有代码库问题都直接对合并图执行graphify query——不再重新抽取也不再有体积门限size gate拦截。也就是说跨仓库构建的一次性成本换来的是后续持续的结构检索能力当某个仓库更新后重新git pull该仓库clone 命令对已存在克隆会自动走 pull、重新extract、重新merge-graphs即可刷新合并图。小结一条可复制的跨仓库工作流步骤命令产物/效果克隆仓库graphify clone url [--branch b]~/.graphify/repos/owner/repo已有克隆则 git pull抽取子目录graphify extract ./core/ [--backend ...]./core/graphify-out/graph.json产物落在扫描路径内部互不覆盖合并graphify merge-graphs a/graph.json b/graph.json --out graphify-out/graph.json节点带repo属性与tag::前缀同名类型自动加same_type_as边查询graphify query ...直接在合并图上执行无重新抽取、无体积门限这套链路的关键工程保障都来自源码层distinct_repo_tags防止同名目录静默合并无关节点社区 ID 偏移防止跨仓库社区撞号same_type_as边让遍历能够跨越仓库边界。测试用例如 tests/test_merge_graphs_cli.py对这些边界场景均有回归覆盖可以作为阅读实现时的最佳入口。【免费下载链接】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），仅供参考
