用途
graph-code 是一个代码智能(Code Intelligence)技能,用于操作结构化的代码知识图谱。该图谱由 Tree-sitter 生成的节点和边组成,存储在 .code-graph/graph.db(SQLite 数据库)中,通过 python .claude/scripts/code_graph 命令行工具进行访问。
主要能力
该技能提供六种模式,每次调用只能使用一种模式:
- build:构建、更新或同步代码图谱(首次使用时安装图谱工具)。支持 --scope={full|update|sync},默认自动检测。
- query:查询关系,包括调用者(callers)、被调用者(callees)、导入(imports)、导入者(importers)、测试(tests)、继承者(inheritors)、文件结构、搜索、查找路径(find-path)、批量查询。
- trace:通过 CALLS、事件、总线消息和 API 端点追踪完整系统流程。支持 --direction、--depth N、--edge-kinds、--node-mode 等参数。
- blast-radius:分析当前 git 变更的影响,包括受影响的文件和函数、测试缺口、风险等级。
- connect-api:检测前端到后端的 API 连接并创建 API_ENDPOINT 边。
- export:导出完整或过滤后的 JSON 图谱快照,或将单个文件导出为 Mermaid 图表。支持 --format={json|mermaid},默认 JSON。
使用方式
调用时需指定模式,例如 $graph-code export --format=mermaid <file>。模式可以是 --mode=build|query|trace|blast-radius|connect-api|export,或作为第一个参数直接给出这六个词之一。模式之后的所有内容都是该模式自己的参数。
关键规则:
- 每次调用只使用一种模式。如果没有模式且没有匹配的模式词,应显示模式分派表并通过提问工具询问用户选择哪种模式;自然语言请求若恰好匹配某一行的意图列,则选择该行的模式;否则显示表格,绝不猜测。
- 始终向 CLI 传递 --json,使输出结构化且可解析。
- 如果图谱未构建(.code-graph/graph.db 不存在),应明确报告“graph not built — run $graph-code --mode=build, or continue with grep”并停止该模式。这对调用者来说不是错误。
- 所有声明必须基于证据(file:line),置信度超过 80% 才可行动。
- 每个步骤开始/完成时保持任务跟踪更新。
每种模式在使用前必须先完整读取对应的参考文件(references/mode-<x>.md),例如 build 模式读取 references/mode-build.md,query 模式读取 references/mode-query.md,以此类推。
适用场景
- 需要了解代码结构关系时,如“谁调用了这个函数”“什么导入了这个模块”“相关文件有哪些”“依赖什么”“测试在哪里”“继承自什么”。
- 需要追踪系统流程时,如“当 X 发生时会发生什么”“什么触发了 X”“通过 X 的完整流程”“前端到后端的流程”。
- 需要评估代码变更影响时,如“blast radius”“影响分析”“我的变更的结构性影响”。
- 需要连接前后端 API 时,如“connect api”“api connections”“frontend backend”。
- 需要导出图谱时,如“export graph”“JSON dump”“export Mermaid”“graph diagram”“visualize graph”。
限制
- 图谱可能过期或不完整(滞后于未提交的编辑和未索引的路径),应将其视为提示而非证明。重要内容需通过阅读文件或 grep 验证。
- 对于低风险或局部变更,可以跳过图谱。
- 该技能对其他技能或工作流不是强制性的。
- 当 grep 和阅读文件本身可能无法揭示高风险影响范围(共享契约、大量调用者、跨模块或跨服务流程、公共 API)时,图谱可作为补充提示。
- 该技能不包含任何关于收费、价格或平台的信息。
协议
该技能携带 end-to-start-debugger-trace 协议:对于非平凡 bug、验证失败、回归修复、改变行为的代码或不清楚的代码流,在修复前应从观察到的输出向后追踪每条供给路径。建立假设、权威不变量所有者和前向证明;在不可信边界保留验证。普通的工件审查或图谱查询本身不触发调试工作流。