
code-review-graph 图谱构建实战用 build-graph Skill 初始化与增量维护本地代码知识图谱【免费下载链接】code-review-graphLocal-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.项目地址: https://gitcode.com/GitHub_Trending/co/code-review-graph导读build-graph是 code-review-graph 项目中面向 MCP Agent 的一等公民技能Skill它把何时构建、如何构建、如何验证这一图谱生命周期问题固化成可复用的三步操作流程。本文以 skills/build-graph/SKILL.md 为核心骨架结合 code_review_graph/main.py 中的 MCP 工具实现、code_review_graph/tools/build.py 的底层构建逻辑以及 hooks/hooks.json 的自动更新机制完整讲解首次全量构建、增量更新、后处理级别、验证报告与 CLI 等价命令帮助你或你的 Agent在任何仓库中可靠地初始化并长期维护一份与代码保持同步的知识图谱。一、Skill 定位图谱生命周期的操作契约build-graphSkill 的 frontmatter 定义了它的触发语义name: build-graph技能名称同时是插件生成 Skill 目录时的发现命名测试 tests/test_skills.py 中验证了 skill 名称与目录必须是小写匹配的规范description: Build or update the code review knowledge graph. Run this first to initialize, or let hooks keep it updated automatically.明确说明该技能适合在首次初始化时调用后续日常维护交给 hooks 自动完成argument-hint: [full]提示可选传入full参数以强制全量重建。也就是说build-graph的定位是图构建协议它不关心某次具体的代码评审或检索而是回答三个问题——图谱建没建、要不要建、建完对不对。这是理解本技能在 MCP 工具链中位置的关键仓库内其余 Skill如 skills/explore-codebase/SKILL.md、skills/review-changes/SKILL.md都依赖一个已就绪的图谱而build-graph正是这个前置条件。二、三步标准工作流Skill 正文给出了一个精确的三步流程每一步都对应一个具体的 MCP 工具调用。步骤 1检查图谱状态list_graph_stats_tool先调用list_graph_stats_tool获取图谱的聚合统计信息判断当前是否已构建若last_updated为null说明图谱从未构建过进入全量构建分支若图谱已存在则进入增量更新分支。该工具在 code_review_graph/main.py 中注册文档字符串明确写着Shows total nodes, edges, languages, files, and last update time. Useful for checking if the graph is built and up to date其底层实现是 code_review_graph/tools/query.py 的list_graph_stats函数返回结果包含节点数、边数、语言分布、文件数、最近更新时间以及构建过程中的错误信息。步骤 2构建图谱build_or_update_graph_tool根据步骤 1 的分支结果选择调用参数场景调用方式行为首次搭建build_or_update_graph_tool(full_rebuildTrue)全量解析所有文件日常更新build_or_update_graph_tool()默认增量仅重解析变更文件值得注意的是即使你不传full_rebuildTrue底层实现也会兜底。在 code_review_graph/tools/build.py 中可以看到if not full_rebuild and not store.has_nodes(): full_rebuild True即图谱为空时自动回退为全量构建防止因缺少锚点而产生错误的空 diff。此外自动增量更新的 diff 基准并非简单取HEAD~1而是解析为图谱上次同步的那个 commitresolve_incremental_base这样一次update就能同步上次构建以来全部变更而不是只追平最近一次提交当找不到可用锚点时同样回退为全量构建code_review_graph/tools/build.py。步骤 3验证并报告再次调用list_graph_stats_tool构建完成后必须再次调用list_graph_stats_tool做闭环验证并报告以下指标解析的文件数files_parsed/files_updated创建的节点数与边数total_nodes/total_edges检测到的语言种类languages遇到的任何错误errors/warnings。MCP 工具内部通过with_provenance(...)包装返回结果保留溯源信息构建函数返回的summary字段会直接生成可读摘要例如全量构建Full build complete: parsed N files, created X nodes and Y edges.增量更新Incremental update: N files re-parsed, X nodes and Y edges updated. Changed: [...]. Dependents also updated: [...]code_review_graph/tools/build.py三、build_or_update_graph_tool完整参数解析Skill 文档只展示了两个最常用的调用形态但 MCP 工具本身提供了 7 个参数见 code_review_graph/main.py理解全部参数有助于在大型仓库或特殊场景下做精细控制参数类型默认值说明full_rebuildboolFalse为True时重解析所有文件默认增量仅解析变更文件repo_rootstr自动探测仓库根路径省略时自动从当前目录向上探测.git/.code-review-graph标记basestr自动解析增量 diff 基准 Git ref省略时自动解析为图谱上次构建所在 commit可显式传入如origin/main覆盖postprocessstrfull后处理级别full/minimal/none见下文第四节recurse_submodulesboolNone是否纳入 Git 子模块文件None时回退到CRG_RECURSE_SUBMODULES环境变量embedding_providerstrNone显式触发构建后嵌入刷新的 provider必须与embedding_model成对出现默认关闭embedding_modelstrNone显式嵌入刷新的模型名必须与embedding_provider成对出现两个设计细节值得强调嵌入刷新默认关闭。源码注释明确说明builds never transmit source-derived text or load an embedding model unexpectedly——构建过程默认不做任何向量嵌入保证本地优先、无隐式外部传输只有你显式传入 provider model 时才触发如embedding_providerlocal、embedding_modelall-MiniLM-L6-v2。异步线程调度。MCP 工具通过asyncio.to_thread把阻塞的全量构建/增量更新放到独立线程执行避免 stdio 事件循环被长时间构建卡死——这是针对 Windows 上ProcessPoolExecutor与同步 handler 互相阻塞的已知问题源码注释引用了 issue #46、#136的修复。四、后处理级别从原始解析到完整图postprocess参数控制构建完成后执行的增值计算理解其三级划分可以在构建速度与图谱能力之间做取舍级别执行内容适用场景full默认签名计算 FTS 全文索引 流程flows检测 社区communities检测完整能力所有下游分析可用minimal仅签名 FTS 索引追求构建速度同时保证搜索可用none跳过全部后处理仅原始解析最快后续可用postprocess命令补跑run_postprocess的实现位于 code_review_graph/tools/build.py其执行顺序与内容为调用目标解析resolve_bare_call_targets、resolve_bare_tested_by_sources、resolve_cpp_scoped_call_targets补齐裸调用/裸测试来源边签名计算为 Function/Test/Class 节点生成def name(params) - ret形式的签名并写入节点表FTS 索引重建调用 code_review_graph/search.py 的rebuild_fts_index支撑符号级全文检索流程检测调用 code_review_graph/flows.py 的trace_flows/store_flows识别跨模块调用链flow这是 review 场景中受影响的流程分析的数据基础社区检测调用 code_review_graph/communities.py 的detect_communities/store_communities对图中节点做社区划分供模块级聚合使用风险索引risk_index表按调用方数量、是否有测试覆盖、是否涉及安全关键字auth、password、token、sql等计算 0~1 的风险分code_review_graph/tools/build.py供detect-changes的风险面板消费。每个步骤都单独 try/except 包裹失败只产生warnings而不会让整个构建失败随后写入last_postprocessed_at元数据。这意味着你完全可以先用postprocessnone快速出图再在闲时调用run_postprocess_tool对应 CLIcode-review-graph postprocess补齐昂贵步骤。五、CLI 等价命令MCP 之外的同一套能力Skill 面向 MCP Agent但同一条构建链路也完整暴露为 CLI。见 docs/COMMANDS.md# 构建与更新 code-review-graph build # 全量构建 code-review-graph build --skip-flows # 解析 签名 FTS等价 postprocessminimal code-review-graph build --skip-postprocess # 仅原始解析等价 postprocessnone code-review-graph update # 增量更新 code-review-graph update --base origin/main # 自定义 base ref code-review-graph update --brief # 更新图并展示风险面板 code-review-graph update --brief --verify # 追加 tiktoken 交叉校验 code-review-graph postprocess # 补跑 flows / communities / FTS code-review-graph forget PATH [PATH ...] # 从图中剔除文件无需全量重建 code-review-graph embed --provider local # 计算向量嵌入 # 监控与检查 code-review-graph status # 图谱统计无图时退出码 1不创建 DB code-review-graph watch # 文件变更时自动更新 code-review-graph visualize # 生成交互式 HTML 图谱MCP 工具与 CLI 是同一build_or_update_graph底层函数的两种入口参数一一对应full_rebuildTrue↔build默认增量 ↔updatepostprocess↔--skip-flows/--skip-postprocess。文档还特别给出了detect-changes --brief只读快速回答当前变更影响什么约 1 秒与update --brief先增量入库再分析适合 rebase 后或疑似图过期时的选型建议。六、hooks 自动更新构建之后几乎不用手动Skill 的 Notes 强调graph auto-updates via hooks on edit/commit, so manual builds are rarely needed。仓库根目录的 hooks/hooks.json 具体展示了这条自动链路SessionStart每次会话启动执行code-review-graph status快速确认图谱健康度PostToolUseEnterWorktree切换工作树/分支后后台执行code-review-graph build保证跨分支的图谱同步PostToolUseWrite|Edit|Bash每次文件写入、编辑或执行命令后运行code-review-graph update --skip-flows以 30 秒超时保护增量入库变更文件。也就是说日常开发中图谱几乎始终与工作区保持同步build-graphSkill 更多承担的是初始化与异常恢复职责。七、存储位置、忽略规则与语言覆盖图谱存储图谱以 SQLite 数据库形式持久化在仓库根目录的.code-review-graph/graph.db。安装时 CLI 还会确保.gitignore中忽略.code-review-graph/目录见 code_review_graph/cli.py避免图谱文件进入版本控制。另有两类额外数据位置用户级配置目录~/.code-review-graphcode_review_graph/constants.py存放 watch 配置等仓库级自定义语言配置.code-review-graph/languages.toml可声明扩展名与 grammar 节点类型见 code_review_graph/custom_languages.py。忽略规则.code-review-graphignore文件用于跳过不需要入库的文件二进制文件、生成文件、以及匹配该忽略模式的文件在解析阶段被排除。这是大型仓库控制首次构建时间的主要手段——官方文档中记录的实测参考值为约 3000 文件规模下首次全量构建约 40 秒、hook 路径增量约 2.5 秒见 code_review_graph/docs/LLM-OPTIMIZED-REFERENCE.md该数据来自仓库自身基准可参考 docs/REPRODUCING.md 复现。语言覆盖Skill 声明的内置支持语言为Python、TypeScript/JavaScript、Vue、Go、Rust、Java、Scala、C#、Ruby、Kotlin、Swift、PHP、Solidity、C/C。超出内置列表的语言无需 fork可借助.code-review-graph/languages.toml扩展详见 docs/CUSTOM_LANGUAGES.md注意内置语法定义不可被覆盖。八、何时使用决策清单综合 Skill 的When to Use与底层实现逻辑以下场景应当显式调用build-graph场景推荐操作仓库首次接入build_or_update_graph_tool(full_rebuildTrue)或code-review-graph build大型重构 / 分支切换之后触发全量重建EnterWorktree hook 已自动覆盖可手动兜底图谱疑似过期或不同步先list_graph_stats_tool核对last_updated再决定全量或增量日常增量维护依赖 hooks 的update --skip-flows几乎无需手动干预一个实用的最佳实践先用list_graph_stats_tool拿到基线统计全量构建后再次调用并对比files_parsed/total_nodes/total_edges/languages四项指标把结果写入会话记录——这既是验证闭环也为后续增量更新提供了可靠的对照基准。构建失败时不要慌build_or_update_graph的每个后处理步骤都独立容错并产出warnings结合status命令与.code-review-graphignore的排除清单排查必要时以full_rebuildTrue重建即可。九、总结build-graphSkill 用极简的三步协议检查 → 构建 → 验证封装了 code-review-graph 最核心的图生命周期管理list_graph_stats_tool负责状态判断build_or_update_graph_tool依据图谱是否为空、基准 commit 是否可用自动在全量/增量之间决策postprocess三级粒度让你在速度与能力之间自由取舍而 hooks 与 CLI 则让这套能力无缝融入日常开发流。对于任何希望让 AI 编码工具只读必要上下文的团队来说掌握这一条构建链路就是掌握整个 code-review-graph 能力的起点。【免费下载链接】code-review-graphLocal-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.项目地址: https://gitcode.com/GitHub_Trending/co/code-review-graph创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考