code-review-graph 图驱动排障实战用知识图谱系统化追踪与定位 Bug【免费下载链接】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-graphcode-review-graph 是一款 local-first 的代码智能知识图谱工具为 MCP 与 CLI 提供持久化的代码关系索引。本文围绕仓库内置的skills/debug-issue/SKILL.md排障技能展开介绍如何借助图谱能力语义搜索、调用链追踪、执行流分析、变更检测、影响半径分析系统化地定位问题根因并遵循 Token 效率规则以极少的调用与输出完成整个排障闭环。读完本文你将掌握一套可复现的“定位 → 溯源 → 验证”图驱动调试方法。技能文件原文位于 skills/debug-issue/SKILL.md所有工具均有对应的 Python 实现与测试覆盖可直接在 MCP 会话中调用。一、debug-issue 技能概览知识图谱如何改变调试方式传统调试依赖grep全文检索、人工阅读调用栈、手动比对 Git 历史。debug-issue 技能给出的思路是用知识图谱替代线性搜索图数据库中预先索引了函数、类、文件、模块之间的调用、引用、导入、测试关系调试者只需要通过一组语义化工具查询这些关系就能在几步之内把问题收敛到最小范围。技能核心流程摘自 SKILL.md用semantic_search_nodes_tool查找与问题相关的代码用query_graph_tool配合callers_of/callees_of追踪调用链用get_flow_tool查看疑似区域的完整执行路径用detect_changes_tool检查最近的变更是否引发问题对疑似文件使用get_impact_radius_tool了解还会影响哪些其他代码。在代码库中的真实工具名与调用方式可参考 code_review_graph/_legacy_instructions.py 中的工具说明表semantic_search_nodes_tool、query_graph_tool、detect_changes_tool、get_impact_radius_toolMCP 命名空间下工具名通常带_tool后缀底层 Python 函数定义位于 code_review_graph/tools/query.pysemantic_search_nodes、query_graph、get_impact_radius、code_review_graph/tools/flows_tools.pylist_flows、get_flow与 code_review_graph/tools/review.pydetect_changes_func。技能设计要点从“搜索”到“推理”调试的本质是沿着数据流与调用流做推理。图谱把这种推理转化为图查询定位semantic_search_nodes按名称或语义相似度定位疑似函数、类、文件溯源query_graph的callers_of谁调用了它与callees_of它调用了谁双向还原上下文执行路径get_flow还原从入口点到嫌疑点的完整调用链帮助找到触发 Bug 的入口回归风险detect_changes输出风险评分的变更分析get_impact_radius计算“影响半径”评估修复一处后还有哪些代码受影响。二、工具详解五件套的职责与参数1. semantic_search_nodes语义定位问题相关代码用于按关键词或语义相似度找到与问题相关的函数、类、文件。在 code_review_graph/tools/query.py 中实现支持query、limit、detail_level、repo_root等参数。实测用例见 tests/test_agent_transparency.py。典型调用semantic_search_nodes_tool(querylogin timeout handler, detail_levelminimal, limit5)2. query_graph调用链双向追踪执行预定义图查询。支持模式包括callers_of、references_to、callees_of、imports_of、importers_of、children_of、tests_for、inheritors_of、triggers_of、triggered_by、publishers_of、listeners_of、handlers_of、endpoints_for、consumers_of、file_summary见 code_review_graph/tools/query.py。典型调用query_graph_tool(patterncallers_of, targetUserService.login, detail_levelminimal) query_graph_tool(patterncallees_of, targetUserService.login, detail_levelminimal)技能提示强调调用者与被调用者都要查才能获得完整上下文callers 说明问题“从哪里来”callees 说明“会到哪里去”。3. get_flow / list_flows还原完整执行路径list_flows按关键性criticality列出代码库中的执行流每条流代表一个从入口点HTTP handler、CLI 命令、测试函数出发的调用链get_flow返回单条流的完整步骤含每步的函数名、文件、行号并可选择附带源码片段include_source见 code_review_graph/tools/flows_tools.py。典型调用list_flows_tool(sort_bycriticality, limit20, detail_levelminimal) get_flow_tool(flow_namehandle_request, include_sourceFalse, max_steps50)技能提示查看受影响的流以找到触发 Bug 的入口点——Bug 往往在某一执行流中暴露找到该流就能顺藤摸瓜。4. detect_changes排查近期变更是否为元凶风险评分的变更分析工具底层实现为detect_changes_funccode_review_graph/tools/review.py。它基于 Git diff 自动检测变更文件输出risk_score、test_gap_count、test_gaps等字段minimal模式仅返回 summary、risk_score、变更文件数、测试缺口数与 Top 3 审查优先级。典型调用detect_changes_tool(baseHEAD~1, detail_levelminimal)技能提示最近的变更是新问题最常见的来源——多数回归型 Bug 都能追溯到一次提交。5. get_impact_radius评估修复影响半径对疑似文件计算“爆炸半径”blast radius从变更文件出发在图谱上按max_depth跳数遍历返回直接变更节点、受影响节点、受影响文件与连接边并附带影响评分与截断标记code_review_graph/tools/query.py。参数包括changed_files缺省时自动从 git diff 检测、max_depth默认 2、max_results默认 500、base默认HEAD~1、detail_level。典型调用get_impact_radius_tool(changed_files[src/user.py], max_depth2, detail_levelminimal)技能提示对疑似文件执行此工具能同时看到“还会影响谁”——修复方案不能只看局部还要覆盖受影响路径上的其他调用方与测试。三、排障工作流五步系统化定位将上述工具串联为可复现的调试流程对应 SKILL.md 的 Steps 部分第 1 步 语义定位 semantic_search_nodes_tool(query问题关键词, limit5) 第 2 步 调用链 query_graph_tool(patterncallers_of, target嫌疑函数) query_graph_tool(patterncallees_of, target嫌疑函数) 第 3 步 执行流 list_flows_tool(sort_bycriticality) → get_flow_tool(flow_name相关流) 第 4 步 变更检测 detect_changes_tool(baseHEAD~1) 第 5 步 影响半径 get_impact_radius_tool(changed_files[疑似文件])仓库内debug_issue_promptcode_review_graph/prompts.py给出了同构的引导式工作流可作为排障的“标准答案”对照get_minimal_context(taskdebug: 问题描述)获取最小上下文semantic_search_nodes(query描述关键词, detail_levelminimal, limit5)定位对 Top 1-2 结果执行query_graph(patterncallers_of, targetname, detail_levelminimal)若涉及执行流调用get_flow(name相关流)获取最相关的一条流仅在需要追踪特定变更的爆炸半径时才调用get_review_context或get_impact_radius。两个版本的差别在于debug_issue_prompt是给 LLM Agent 的显式指令模板SKILL.md 则是 MCP 场景下供 Agent 读取的技能文档两者共享同一套工具契约可互为补充。四、Token 效率规则以最小上下文完成排障SKILL.md 后半部分规定了严格的 Token 效率纪律这是把排障成本控制在 LLM 上下文预算内的关键先调get_minimal_context_tool(taskyour task)再调用其他图谱工具。该工具在 code_review_graph/tools/context.py 中实现返回约 100 token 的极简上下文图统计节点/边/文件数、风险评分high/medium/low、Top 3 社区、Top 3 关键流以及基于任务关键词的“下一步工具建议”例如任务含debug、bug、error、fix时建议semantic_search_nodes、query_graph、get_flow与 debug-issue 技能的工具组合完全对应。图谱缺失、为空或 Git commit 与构建不一致时会返回status: not_ready并提示先执行build_or_update_graph。所有调用使用detail_levelminimal仅在 minimal 不足以定位时升级为standard。minimal模式下query_graph将可见结果截断为 5 条并报告精确省略数code_review_graph/tools/query.pyget_impact_radius返回精简的风险汇总与 Top 5 关键实体code_review_graph/tools/query.py。目标任何 review / debug / refactor 任务在≤5 次工具调用、≤800 个输出 token内完成。get_minimal_context的next_tool_suggestions机制code_review_graph/tools/context.py正是为压缩调用次数而设计——一次调用即可获得后续路径的推荐。关键纪律图谱只负责缩小范围不能替代源码。改代码前必须阅读实现与测试本身——图给出“看哪里”源码给出“是什么”。该纪律贯穿仓库内其他技能如 skills/explore-codebase/SKILL.md、skills/review-changes/SKILL.md是全仓库通用的约定tests/test_pr779_edges.py会校验技能文件中get_minimal_context_tool等关键工具名的正确性tests/test_hints.py验证query_graph、get_flow、semantic_search_nodes等调试向工具组合会被推断为debugging意图——从测试侧印证了这套工具组合就是项目认定的“调试签名”。五、完整排障示例登录超时问题假设收到反馈“登录接口偶发超时”按 SKILL.md 流程执行第 0 步Token 效率规则get_minimal_context_tool(taskdebug: login timeout) # 返回节点/边/文件统计、Risk、Top 社区、Top 关键流、下一步工具建议第 1 步语义定位semantic_search_nodes_tool(querylogin handler, detail_levelminimal, limit5)第 2 步双向调用链query_graph_tool(patterncallers_of, targetAuthController.login, detail_levelminimal) query_graph_tool(patterncallees_of, targetAuthController.login, detail_levelminimal)callers_of回答“谁在什么路径上调用它”callees_of列出其内部依赖如 Redis、DB 访问、外部 HTTP 调用——超时嫌疑往往在某个 callee 上。第 3 步执行流list_flows_tool(sort_bycriticality, limit10, detail_levelminimal) get_flow_tool(flow_namelogin, include_sourceTrue)用include_sourceTrue直接拿到每步源码片段快速目检耗时点。第 4 步变更检测detect_changes_tool(baseHEAD~1, detail_levelminimal)若输出risk_score偏高且test_gap_count非零重点检查高风险变更文件是否引入超时。第 5 步影响半径get_impact_radius_tool(changed_files[src/auth/redis_client.py], max_depth2, detail_levelminimal)确认修复 redis 客户端超时后还有哪些调用方如验证码服务、刷新 token 流程受影响一并验证。整个流程控制在 5 次调用以内且除第 3 步外均使用minimal粒度完全符合 Token 效率目标。六、经验法则与使用限制技能 Tips 三条经验法则来自 SKILL.md调用者与被调用者都要查才能理解完整上下文——只查一边容易误判问题归属查看受影响的执行流找到触发 Bug 的入口点——从入口到嫌疑点逐段验证比直接猜嫌疑函数更可靠最近的变更是新问题最常见的来源——遇到回归先跑detect_changes_tool比从头追调用链更高效。使用前提与限制必须先构建图谱get_minimal_context等工具在无图、空图或图谱 Git commit 与当前工作区不一致时返回not_ready见 code_review_graph/tools/context.py需先执行build_or_update_graph。图谱缩小范围、不替代源码图查询给出候选路径最终结论必须回到源码与测试验证。适用范围该技能针对代码层面的可追溯问题调用关系、执行流、回归不适用于无法在图谱中体现的环境配置、运行时资源或外部服务类问题对这类问题图谱工具只能辅助缩小嫌疑范围。语言覆盖图谱对受支持语言Python、TypeScript、Java、Go、Rust 等的解析质量取决于对应 resolver跨语言调用追踪能力随语言组合而异详见 docs/CUSTOM_LANGUAGES.md。七、与其他技能的关系debug-issue 技能不是孤立存在而是仓库“技能矩阵”的一环完整列表见 skills/ 目录explore-codebase/SKILL.md从整体图统计、架构、社区到局部语义搜索、关系查询理解代码库是 debug-issue 的前置能力review-changes/SKILL.md变更审查工作流与 debug-issue 第 4-5 步detect_changesget_impact_radius共用同一套“变更 → 风险 → 影响”工具链review-pr/SKILL.md 与 review-delta/SKILL.md面向 PR 与增量评审回归风险的排查思路可复用refactor-safely/SKILL.md重构前用get_impact_radius评估影响半径与调试中的“修复影响评估”是同一机制。这些技能共享统一的 Token 效率规则与工具契约可组合出“探索 → 定位 → 修复 → 验证”的完整闭环。要理解工具的底层数据模型与存储可进一步阅读 docs/schema.md要掌握 CLI 与 MCP 的接入方式可参考 docs/USAGE.md 与 docs/COMMANDS.md。【免费下载链接】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），仅供参考