sebdenes/code-graph-rca
GitHub: sebdenes/code-graph-rca
通过 tree-sitter 解析代码库构建调用图与 git 感知索引，以 MCP 工具形式为 AI 编辑器提供结构化的代码推理和自动化根因分析能力。
Stars: 1 | Forks: 0
# Halo
**关于代码的结构化事实，通过 MCP 暴露给任何 AI agent。**
`code-graph-rca` · `cgrca` · MIT
当 AI agent 调查你的代码库中的故障时，它需要了解的不仅仅是代码*说了什么*。它还需要知道什么调用了什么、最近更改了什么、数据流向哪里、谁依赖于谁。这些上下文信息存在于你的 AST 和 git 历史中。Halo 提取、索引这些信息，并将其作为 MCP 工具暴露出来，供 agent 调用。
Agent 依然是 Agent。Halo 是它以前不具备的结构化视角和记忆。
## Halo 的功能
一个长期运行的守护程序使用 tree-sitter 解析你的代码库，在 SQLite 中构建调用图 + 导入图 + 符号索引，并监控文件系统。一个经过校准的 7 信号评分器根据时效性 × 接近度 × 歧义性 × 共变性 × 子系统 × 复杂性 × 数据流对符号进行排名。
该图和评分器作为十个工具暴露给任何支持 MCP 的编辑器（Cursor, Claude Code, Cody, Cline, Continue, Windsurf, Zed）：
| 工具 | 解答的问题 |
|---|---|
| `cgrca_definitionOf` | 这个符号在哪里声明？文件、行范围、签名、导出标志、语言、子系统。 |
| `cgrca_callersOf` | 谁调用了这个？深度为 N 的反向调用树，去重处理，带有置信度。 |
| `cgrca_calleesOf` | 这调用了什么？前向调用树。未解析的目标作为 grep 线索提供给 agent。 |
| `cgrca_pathBetween` | 数据如何从 A 流向 B？基于 CALLS + 参数绑定边的最短路径。 |
| `cgrca_recentlyChangedNear` | 最近谁更改了这个？针对符号行的 `git log -L`，最近 N 次提交。 |
| `cgrca_symbolsInFile` | 这个文件里有什么？快速的文件级别概览。 |
| `cgrca_rca` | 从堆栈跟踪、失败测试、符号或文件生成的完整排名候选 RCA。 |
| `cgrca_rcaPrompt` | 功能同上，但返回组装好的 Markdown 提示词——可直接放入推理循环中。 |
| `cgrca_rcaWithReasoning` | 通过宿主 LLM 进行 LLM 增强的 RCA。 |
| `cgrca_enrichCandidates` | 获取任何 `(file, symbol)` 候选集，并为每个候选项注释函数体 + 调用者 + 被调用者 + 最近提交。 |
此外，还提供用于高级流程的 `cgrca_scope`、`cgrca_currentSelection`、`cgrca_publishSelection`。
## 这解决了什么问题
**浪费的分诊时间。** 当 agent 需要猜测代码结构时，它会陷入循环——读取文件、重新读取文件、向用户请求提示、臆造函数名。使用 Halo 后，通常前三次工具调用就能将调查定位到正确的子系统中。
**偏离目标的文件选择。** 7 信号评分器会奖励那些在故障附近最近更改过的代码、在结构上接近入口点的代码，以及与相关修复共同变化的代码。Agent 的排名候选反映的是工程师实际的分诊方式，而不是 prose 表面提及的内容。
**过时的上下文。** 静态文档在编写后的第二天就会过时。而该图每次都会根据你的代码和 git 日志重新构建。
**繁琐的手动集成。** `cgrca init` 会检测你拥有哪些支持 MCP 的编辑器，注册这些工具，并生成一个 `AGENTS.md` 文件，以便 agent 知道何时调用哪个工具。编辑器本身无需任何配置。
## 安装
```
npm i -g code-graph-rca # CLI + MCP server + daemon
npm i -g code-graph-rca-ui # Constellation / RCA / Impact viewer (optional)
npm i -g code-graph-rca-github-app # PR review + incident webhook bot (optional)
```
## 30 秒上手
```
cd your-repo
cgrca init --yes # detect editors, register MCP, drop AGENTS.md
cgrca daemon start # warm queries — sub-50ms on the second hit
```
打开你的编辑器。Halo 的 MCP 工具现在已可供你的 agent 使用。
CLI 演示：`cgrca rca symbol:foo` — 排名的因果候选项将以表格形式打印。
## 具体示例
故障：*"用户在会话中随机被登出，auth handler 中没有错误。*
Agent 调用 Halo：
- `recentlyChangedNear("SessionStore.touch")` → "6 天前在提交 `a8f3` 中修改 — *'idle 时轮换 session keys'*."
- `callersOf("rotate_keys")` → "从 `middleware.before_request` 调用（距离每个端点上游 2 跳）。"
- `pathBetween("Request.cookies", "rotate_keys")` → "通过 `middleware/cookies.py:54` → `session/store.py:118` 流转。"
7 信号评分器将 `rotate_keys@session/store.py:118` 排在 #1：高时效性 × 与故障面的短接近度 × 与 auth 子系统的强共变性。
Agent 现在拥有了结构化的证据，可以确定假设并提出修复建议。
## 三大接口
**MCP 服务器** — 核心产品。Stdio 传输，任何支持 MCP 的编辑器都能自动识别。`cgrca init` 负责连接配置。
**CLI** — 用于脚本编写、CI、调试：
```
cgrca rca symbol:login # rank a known symbol
cgrca rca file:src/auth.py # rank within a file
cgrca rca test:tests/test_auth.py # from a failing test
cgrca rca "users randomly get logged out" # free-text
cgrca rca "users randomly get logged out" --llm # LLM re-rank (needs ANTHROPIC_API_KEY)
cgrca callers handle_login --depth 3 # walk the call graph
cgrca define UserSession --language python # find declarations
cgrca changed handle_login --since 30 # who touched this lately
```
**GitHub App + 事件 webhook** — PR 审查机器人将排名候选作为评论发布；Sentry / 通用 webhook 会创建带有排名候选和初步假设的 issue。
## 架构
**先定范围后索引。** 在导入 + 反向调用者上进行有界 BFS，选取故障点周围 5-10k 行的代码。两遍 tree-sitter 解析器构建内存中的 SQLite（或使用 `--persist 标签：AI智能体, AI编程助手, Claude, Cursor, CVE检测, Git, LSP, MCP, MITM代理, RCA, SQLite, tree-sitter, WebSocket, 云安全监控, 代码上下文, 代码分析, 代码变更追踪, 代码图谱, 代码审查, 代码库管理, 代码检索, 代码理解, 代码索引, 依赖分析, 凭证管理, 威胁情报, 开发者工具, 故障排查, 数据管道, 暗色界面, 根因分析, 自动化攻击, 调用图, 软件工程, 软件开发, 静态分析