code-review-graph 结构化代码审查指南：基于知识图谱的 risk-aware 审查工作流

code-review-graph 结构化代码审查指南基于知识图谱的 risk-aware 审查工作流【免费下载链接】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本篇技术指南聚焦 code-review-graph 项目中内置的review-changesSkill讲解如何借助本地代码知识图谱完成一次风险感知risk-aware的结构化代码审查从变更检测、受影响执行流定位、测试覆盖核对到爆炸半径评估最后按风险等级输出可合并的审查结论。读完本文你将掌握一套完整的图谱驱动审查流程、各 MCP 工具的调用顺序与参数语义以及将任意审查/调试/重构任务控制在 5 次工具调用、800 输出 token 以内的省 token 实践。一、Skill 概述review-changes是什么review-changes是 code-review-graph 提供的内置技能之一其声明定义位于 skills/review-changes/SKILL.md同时在 skills.py 中以同名review-changes.md注册二者内容保持一致。Skill 的定位description是Perform a structured code review using change detection and impact即利用知识图谱完成变更检测 影响分析驱动的结构化审查。它的核心思想是审查者不必通读整个仓库而是先由图谱把改动映射到受影响的具体函数、执行流与社区再针对高风险点做定向深入。Skill 自身也明确提示了一条边界——The graph narrows scope; it does not replace the source图谱缩小范围但不能替代源码即图谱只负责缩小审查视野真正给出结论前仍需阅读实现与测试。该 Skill 依赖的底层能力包括图存储SQLite、Git 变更解析、流程flows与社区communities检测、TESTED_BY测试关联边等这些由仓库中的 changes.py、tools/context.py、tools/review.py 等模块共同支撑。二、五步审查流程详解SKILL.md 定义了 5 个明确步骤每一步对应一个或多个 MCP 工具。下面结合 main.py 中的工具签名逐一展开。第 1 步运行detect_changes_tool获取风险评分变更分析这是审查的入口工具定义于 main.py。它的核心能力是把 Git diff 映射到受影响函数、流程、社区与测试覆盖缺口返回风险评分risk score和按优先级排序的审查项detect_changes_tool( base: str HEAD~1, # 对比的 Git ref默认与 HEAD~1 对比 changed_files: list[str] | None None, # 变更文件列表缺省时从 git 自动检测 include_source: bool False, # 是否携带变更函数的源码片段 max_depth: int 2, # 影响半径 BFS 遍历深度 repo_root: str | None None, # 仓库根路径缺省自动检测 detail_level: str standard, # standard 全量输出 / minimal 省 token 摘要 max_results: int 25, # 变更函数/测试缺口/文件的最大返回数 max_flows: int 20, # 内嵌受影响流程数量仅流程元数据 )底层实现位于 changes.py 的analyze_changes它先通过parse_diff_ranges解析 diff 得到变更区间再经map_changes_to_nodes把区间映射到图节点Function/Test/Class节点随后对每个变更节点计算风险分最后聚合出summary、risk_score、changed_functions、affected_flows、test_gaps与review_priorities六类输出。其中review_priorities取风险分最高的前 10 个函数是审查者应优先关注的对象。一个真实的工具输出示例非本仓库数据来自测试夹具 detect_changes_sample.json大致长这样{ summary: Analyzed 2 changed file(s):\n - 3 changed function(s)/class(es)\n - 2 affected flow(s)\n - 1 test gap(s)\n - Overall risk score: 0.72\n - Untested: rotate_token, risk_score: 0.72, changed_functions: [ { name: rotate_token, qualified_name: auth/session.py::rotate_token, kind: Function, file_path: auth/session.py, line_start: 42, line_end: 78, risk_score: 0.72 } ] }第 2 步运行get_affected_flows_tool定位受影响的执行路径拿到风险清单后下一步是回答这次改动会波及哪些用户可见或关键的执行路径。get_affected_flows_tool定义于 main.py其实现get_affected_flows_func位于 tools/review.pyget_affected_flows_tool( changed_files: list[str] | None None, # 缺省自动检测 git 变更 base: str HEAD~1, repo_root: str | None None, detail_level: str standard, # standard 含完整步骤 / minimal 仅流程元数据 max_flows: int 50, # 最大返回流程数0 表示不限制 )从源码注释可以读出两个关键事实detail_levelminimal只返回每个流程的名称、关键度criticality、深度与节点计数等元数据而standard模式会为每个流程附带完整的steps列表——一个 standard 流程大约消耗 980 token而 minimal 仅约 18 token见 tools/review.py。因此审查场景下第 2 步通常用minimal拿到全量受影响流程清单再对其中最关键的个别流程升级到standard查看步骤细节。standard模式会将可见流程限制在 25 个以内、minimal限制在 500 个以内并共享 400 步的总步数预算避免深调用链把响应撑爆。第 3 步对每个高风险函数运行query_graph_toolpatterntests_for核对测试覆盖query_graph_tool定义于 main.py是一个预定义查询工具支持十余种关系模式query_graph_tool( pattern: str, # 查询模式名见下方清单 target: str, # 目标节点名、限定名或文件路径 repo_root: str | None None, detail_level: str standard, max_results: int 100, )审查流程第 3 步专门使用patterntests_for来查询哪些测试覆盖了该目标。除此之外源码中列出的可用模式还包括callers_of谁调用了目标、callees_of目标调用了谁、imports_of/importers_of导入关系、children_of文件/类内包含的节点、inheritors_of继承者、triggers_of/triggered_by调度器与任务、publishers_of/listeners_of/handlers_of/endpoints_for事件与端点、consumers_ofSpring 配置属性消费者以及file_summary文件内全部节点等。之所以能通过tests_for核对覆盖是因为解析器会为生产函数 → 测试函数建立TESTED_BY边存储方向为 source生产节点、target测试节点见 changes.py 的注释说明。审查时只需在detect_changes_tool给出的高风险函数上逐一执行tests_for即可确认其是否真有测试兜底而不是靠猜测。第 4 步运行get_impact_radius_tool理解爆炸半径get_impact_radius_tool定义于 main.py用于回答改了这个函数还有哪些函数/类/文件会被间接影响get_impact_radius_tool( changed_files: list[str] | None None, # 缺省自动检测 git 变更 max_depth: int 2, # 依赖图中的跳数hop上限 repo_root: str | None None, base: str HEAD~1, detail_level: str standard, # standard 全量 / minimal 紧凑摘要 )max_depth控制 BFS 遍历深度默认 2 跳。这一步骤的价值在于风险分高但爆炸半径小的改动与风险分中等但牵一发动全身的改动审查策略完全不同——前者聚焦函数本身后者需要扩大到所有下游调用方一起评审。第 5 步为无测试覆盖的变更提出具体测试用例最后对第 3 步中确认为无测试覆盖test gap的变更审查者应提出具体的测试用例建议。这一步虽然没有专属工具但detect_changes_tool已经替你完成了缺口枚举在 changes.py 中变更函数若不存在任何TESTED_BY出边就会被记入test_gaps列表测试函数本身与少数豁免名单除外。你只需针对列表中的每一项结合第 2 步确认的受影响流程与第 4 步确认的爆炸半径设计覆盖正常路径、边界条件与异常路径的测试即可。三、输出格式按风险等级分组的审查结论SKILL.md 要求最终审查结论采用如下结构按风险等级high / medium / low分组并包含四个要素What changed and why it matters改了什么、为什么重要——可直接引用detect_changes_tool的summary与changed_functionsTest coverage status测试覆盖状态——来自tests_for查询结果与test_gaps列表Suggested improvements改进建议——结合受影响流程与爆炸半径给出Overall merge recommendation整体合并建议——基于risk_score综合判断。detect_changes_tool输出的risk_score本身即为分级依据get_minimal_context的实现tools/context.py使用风险分 0.7 判为 high、 0.4 判为 medium、否则为 low的阈值审查结论中的分组可沿用这一口径保证机器与人的判断一致。四、Token 效率规则≤5 次调用、≤800 tokenSKILL.md 给出了三条硬性效率规则这也是 code-review-graph 强调的 local-first 上下文节约理念在审查场景的落地先调用get_minimal_context_tool(taskyour task)再使用其他图谱工具。该工具定义于 main.py返回约 100 token 的极紧凑上下文包含图统计、风险评分、Top 社区/流程与下一步建议工具是整个审查的零成本入口。其底层 tools/context.py 还会做三件事图缺失时返回status: not_ready并提示先建图图节点为空时返回empty_graph当图谱构建于不同 Git commithead_matches_build为 false时返回stale_graph提示先更新图谱——避免在过期图上做出错误审查结论。所有调用优先使用detail_levelminimal仅在 minimal 不足以支撑判断时才升级到standard。前文已给出量级对比一个 standard 流程约 980 token vs minimal 约 18 tokenget_architecture_overview_tool的 minimal 模式可把典型输出从 600KB 压到 5KB 以内见 main.py 注释。目标任何审查/调试/重构任务 ≤5 次工具调用、≤800 总输出 token。同时坚持改动代码前先读实现与测试——图谱负责缩小范围阅读源码负责给出最终判断。关于上下文节约的量化说明可参考 context_savings.py工具会在响应中附带context_savings元数据saved_tokens、saved_percent所有数字均标注estimated: true表示估算值。五、风险评分原理compute_risk_score的评分因子detect_changes_tool输出的风险分并非拍脑袋而是由 changes.py 的compute_risk_score依据六个因子加权累加最终收敛到 0.0–1.0评分因子权重/封顶说明流程参与度Flow participation每个流程成员 0.05封顶 0.25按流程关键度加权属于关键执行路径的节点风险更高跨社区调用Community crossing每个跨社区调用者 0.05封顶 0.15调用者来自不同社区说明耦合面广测试覆盖Test coverage无测试 0.305 条TESTED_BY边降至 0.05未测试节点显著加分的核心因子安全敏感性Security sensitivity命中安全关键词 0.20如名称/限定名包含认证、令牌等关键词调用者数量Caller count调用者数/20封顶 0.10被越多处调用改动波及面越大变更频率Change frequency可选提交次数/10封顶 0.15由include_churn开关控制默认关闭测试覆盖是其中权重最高的单一因子。这一行为被 tests/test_changes.py 明确验证未测试函数与已测试函数在测试覆盖因子上的得分差为 0.30 − 0.05同时verify_auth_token这类含安全关键词的函数得分必然高于普通process_data风险分始终保持在 [0, 1] 区间内test_risk_score_range。六、如何开始使用review-changes作为内置 Skill随项目一并分发安装与启用方式与项目整体一致参考 README.md 与 USAGE.md。使用前需满足两个前置条件已构建知识图谱get_minimal_context_tool与detect_changes_tool都会在缺少图谱时返回not_ready/missing_graph提示需先执行建图流程图谱与当前 Git commit 一致若图谱构建于不同 commit工具会返回stale_graph提示先更新图谱防止基于过期数据给出错误审查结论。满足条件后审查的最小可用序列即为本文第二部分的五步流程且第 1 步之前务必补上get_minimal_context_tool(taskreview changes)作为第 0 步入口。对于大型 PR还可借助环境变量CRG_MAX_CHANGED_FUNCS默认 500限制变更函数处理量并在detect_changes_tool超时默认由CRG_TOOL_TIMEOUT控制时按提示调整作用域见 main.py。七、小结review-changes把代码审查从一次漫无目的的全文阅读变成了一条由知识图谱驱动的、可量化、可复现的工作流最小上下文入场 → 风险评分定位 → 受影响流程确认 → 测试覆盖核对 → 爆炸半径评估 → 缺口测试建议。它的设计要点可以概括为三句话先用get_minimal_context_tool以约 100 token 摸清全局所有查询默认detail_levelminimal把审查控制在 5 次调用 / 800 token 以内图谱负责缩小范围源码负责最终判断。【免费下载链接】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），仅供参考