CGIS Code Graph

🧠 CGIS：代码图谱智能系统

让 AI Agent 查询代码图谱，而不是凭空猜测

问一句“如果我改了这里，哪些地方会出问题？”，得到的是调用链，而不是猜测。

CGIS 使用 tree-sitter 解析代码仓库，将完全限定的符号及其调用、导入和包含关系构建成图谱，存储在 SQLite 中，并通过 MCP 提供给 AI Agent。原本只能搜索并阅读整个文件的 Agent，现在可以直接查询图谱。

• 语言： Python · TypeScript / TSX · Go（仅提供结构和指标；影响分析结果只是供确认的线索，仍需阅读代码——exp4，基于一个库 golang/crypto 测量，主要涉及其 ssh 包；未在应用程序上测量）· JSON 和 YAML（仅包含数据键声明，且需通过 --data-keys 启用数据键；不包含符号、调用或影响分析）
• 运行方式： 本地运行——无需账号，不收集遥测数据；图谱不会离开你的磁盘（唯一选择加入的例外情况）

$ cgis ingest src --output graph.db
$ cgis impact cgis.query.engine.QueryEngine.get_flow_graph --db graph.db --depth 2
🔍 Analyzing transitive upstream callers of: cgis.query.engine.QueryEngine.get_flow_graph

METHOD cgis.query.engine.QueryEngine.get_flow_graph (cgis/query/engine.py:215)
├── FUNCTION cgis.query.context.context_service._collect_callees (cgis/query/context/context_service.py:44)
│   └── FUNCTION cgis.query.context.context_service.build_context (cgis/query/context/context_service.py:96)
└── METHOD cgis.guardian.collector.ContextCollector._graph_sections (cgis/guardian/collector.py:174)
    ├── METHOD cgis.guardian.collector.ContextCollector.collect_graph_context (cgis/guardian/collector.py:213)
    └── METHOD cgis.guardian.collector.ContextCollector.collect_for_chunk (cgis/guardian/collector.py:303)

真实输出——在 CGIS 自身的源代码上运行 CGIS 的结果。

---

🚀 快速入门

在 Claude Code 中使用（最快）

/plugin marketplace add zaebee/codegraph-brain
/plugin install cgis@codegraph-brain

这会安装 MCP 服务、一个教会 Agent 何时查询图谱而不是阅读文件的技能，以及用于首次构建图谱的 /cgis:ingest。服务会按需通过 uvx 从 PyPI 获取，因此无需克隆或构建。

使用其他 MCP 客户端（Cursor、Claude Desktop 等）

{
  "mcpServers": {
    "cgis": { "command": "uvx", "args": ["--from", "codegraph-brain", "cgis-mcp"] }
  }
}

在终端中使用

# No install needed — uvx fetches it from PyPI
uvx --from codegraph-brain cgis ingest ./my-project --output graph.db

uvx --from codegraph-brain cgis impact "my_module.core_function" --db graph.db --depth 5   # who calls this
uvx --from codegraph-brain cgis trace  "my_module.MyClass.run"   --db graph.db --depth 3   # what this calls
# add --format mermaid (or json) to either for a diagram or machine-readable output

也可以永久安装：运行 pip install codegraph-brain（Python 3.12+），然后直接使用 cgis。完整命令列表请见 CLI_USAGE.md。

---

📈 真实规模下的实证

CGIS 已在一个由 12 个仓库组成的实际项目中运行——涉及 4 种语言、8,146 次提交，并且每天都有代码发布。在其 FastAPI 后端中，CGIS 对 87,845 条边中的 82.7% 作出了明确分类；对剩余的 17.3%，它会如实列出，而不是虚构目标——其中也包括 CGIS 自身存在的缺口。

这个比例从 #459 的 11.4% 上升了；#459 不再把指向缺失符号的调用算作已解析。剩余部分中约有 4 个百分点是已知的解析器缺口，并非无法发现的问题：导入 app/ 时会剥去导入中带有的 app. 前缀，而导入路径尚未将两者对应起来——在包根目录下导入同一后端时，报告的比例为 13.2%。这个数字反映了该工具目前承认无法定位的部分，而且它可以朝着不利于自己的方向变化。

阅读案例研究 →——每个数据都有测量依据且可复现，包括 CGIS 无法覆盖的内容。

---

🤔 为什么选择图，以及它有何不同

文本检索会把看似相关的片段交给 Agent，但它无法判断三个名为 save 的函数中，某次调用会到达哪一个，也无法告诉你五层调用者之前是什么。只要源码允许，CGIS 就会将每个调用点解析为完全限定名称；如果无法解析，该边就会保留为未解析状态并计入统计，绝不会用看似合理的猜测填补。

如果你使用……	CGIS 还能提供
在 Agent 中使用 grep / 读取文件	一次调用即可查看传递调用者和被调用者，无需将整个文件塞进上下文
基于 LSP 的符号工具（例如 Serena）	持久化的全仓库图，用于多跳影响分析、耦合度、PageRank 和漂移分析
仓库映射（例如 aider）	可遍历、可审计的已解析边，并报告已解析 / 未解析比例

---

🤖 MCP 工具

主要工具：

工具	用途
cgis_ingest	构建或增量刷新图
cgis_overview	不知道 FQN 时，查看从何处开始：规模和最大的包
cgis_find_symbol	部分名称 → 候选 FQN
cgis_analyze_impact	如果修改此处，上游会有什么问题？
cgis_trace_flow	该调用会传递调用哪些内容？
cgis_get_structure	类 / 模块层级结构
cgis_context	为单个符号生成精简的 GraphRAG 上下文包
cgis_metrics	耦合度、上帝类、PageRank、包内聚度
cgis_audit_reachability	Authz / IDOR 覆盖情况——每个处理程序都能到达其防护逻辑吗？
cgis_drift	各领域偏离其声明模式的程度
cgis_validate	图完整性：已解析边与未解析边

全部 16 个工具及其参数：MCP_REFERENCE.md。

---

🏗️ 工作原理

1. 提取 — tree-sitter 解析器将每个文件转换为节点和原始调用边。
2. 解析 — ResolverEngine 将原始调用映射到完全限定名称，或明确保留为未解析状态。
3. 存储 — SQLite 保存图；查询通过广度优先遍历图来完成。

graph LR
    A[Source Code] --> B[Extractors]
    B --> C[Resolver Engine]
    C --> D[(SQLite Graph DB)]
    D --> E[MCP Server]
    D --> F[Prompt Compiler]
    E --> G[AI Agents]
    F --> G

详情以及 CGIS 每次发生更改时都会根据自身源码重新生成的流水线图，请参阅 HOW_IT_WORKS.md。

---

🛡️ Guardian：图谱感知代码审查

Guardian 是 CGIS 内置的大模型审查器——它以图谱为上下文审查拉取请求，而不只是查看差异文本。它在 CI 中运行，并在对应的确切代码行添加行内评论。

• 两阶段，以召回率优先： finder 会找出所有可能的缺陷（以召回率为优化目标），随后由独立的 skeptic 阶段过滤误报——这更接近人工审查的方式，也比受精确率门槛限制的单条提示词可靠得多。
• 本地或云端，不受锁定： 可使用 Ollama（qwen2.5-coder、llama3.1、granite-code 等）进行免费本地推理，也可使用云端的 Mistral / Gemini / Claude。你甚至可以混合使用——用强大的云端 finder 配合免费的本地跨模型 skeptic。
• 图谱感知上下文： 审查器可以查看影响图、架构偏移和项目本体——因此它能发现纯差异审查器无法发现的结构性缺陷和约定缺陷。
• 确定性定位： 每条行内评论都通过差异中的原文引述定位，而不是依赖模型（往往错误）的行号猜测。
• 以身作则并进行评估： Guardian 会审查 CGIS 自己的拉取请求，并通过基准测试工具与精选的真实结果进行评分——因此提示词的变更经过验证，而非凭猜测。

# Build the graph, then review a PR with a local model (no API key)
cgis ingest ./src --output graph.db
GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

# Or a Claude skeptic over a Mistral finder: Claude Haiku 5.5 unless GUARDIAN_SKEPTIC_MODEL names
# another, at GUARDIAN_ANTHROPIC_EFFORT=low unless set (low|medium|high|xhigh|max). Claude models
# reject a sampling temperature, so GUARDIAN_TEMPERATURE must be unset.
GUARDIAN_SKEPTIC=anthropic ANTHROPIC_API_KEY=... MISTRAL_API_KEY=... \
  uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

手头没有 GPU？在笔记本 GPU 上进行基准测试 →——全程免费，因为这些测试样例无需大模型裁判即可评分。或者**让 Guardian 使用远程 Ollama →**——通过 frp stcp 隧道，无需开放公网端口，并配有保护机制，拒绝审查被静默截断的提示词。

---

🔒 隐私

CGIS 不收集任何信息：没有遥测、没有分析，也无需账户。你的代码及由其构建的图谱都保留在你的机器上。唯一的例外是可选功能：如果你使用云端模型运行 Guardian，它会将待审查的差异发送给你选择的服务商。详见 PRIVACY.md。

---

🛠️ 开发

需要 Python 3.12+ 和 uv。

git clone https://github.com/zaebee/codegraph-brain && cd codegraph-brain
uv sync
make pytest

标准规范请参阅 CONTRIBUTING.md：严格的 MyPy 检查、代码检查、本体合规性。

---

💼 架构审计

CGIS 免费且可自行运行。如果你更希望直接获得分析结果，而不是使用工具，我可以为你的代码库结构提供固定价格的审计——涵盖授权覆盖率、影响范围、耦合度和架构偏移——五个工作日内交付，固定收费 $2,400，并明确列出分析无法看到的内容。阅读服务内容 →