用途
codegraph-brain（又名 CGIS：Code Graph Intelligence System）是一个“AI 智能体可以查询而不是猜测”的代码图谱。当 AI 智能体需要询问“如果我修改这里，什么会被破坏？”时，它返回调用链，而不是靠猜测。CGIS 用 tree-sitter 解析代码仓库，生成由全限定符号以及它们之间的调用、导入和包含关系组成的图，将图存储于 SQLite，并通过 MCP 提供给 AI 智能体。
主要能力
- 解析语言：Python、TypeScript / TSX。
- 将每个调用点在源码允许时解析为全限定名；无法解析的边保持标记为 unresolved 并计数，不会用看似合理的猜测填充。
- 通过 MCP 提供图给 AI 智能体使用。
- 内置 Guardian：图谱感知的代码审查工具，使用图谱作为上下文审查 Pull Request，而不仅仅是 diff 文本。Guardian 在 CI 中运行并发布锚定到精确行的内联评论。
- 两阶段、召回优先：finder 发现所有可能的缺陷（针对召回率优化），独立的 skeptic 阶段过滤误报。
- 本地或云端 LLM，无锁定：可指向 Ollama（qwen2.5-coder、llama3.1、granite-code 等）进行免费本地推理，或指向云端的 Mistral / Gemini，也可以混合使用。
- 确定性锚定：每条内联评论由 diff 中的逐字引用定位，而非模型（常常错误）的行号猜测。
- 全部 14 个工具及参数见 MCP_REFERENCE.md。
使用方式
在 Claude Code 中（最快）安装后会提供 MCP 服务器、一个教导智能体何时查询图谱而非读取文件的 skill，以及用于首次使用时构建图谱的 /cgis:ingest。服务器通过 uvx 按需从 PyPI 拉取，无需克隆或构建。
其他 MCP 客户端（Cursor、Claude Desktop 等）也可使用。
从终端使用：或永久安装：pip install codegraph-brain（Python 3.12+），然后直接使用 cgis。完整命令列表见 CLI_USAGE.md。
工作原理
- 提取：tree-sitter 解析器将每个文件转换为节点和原始调用边。
- 解析：ResolverEngine 将原始调用映射为全限定名，或显式标记为未解析。
- 存储：SQLite 保存图谱；查询为对其的广度优先遍历。
细节及 CGIS 每次变更时从自身源码重新生成的流水线图见 HOW_IT_WORKS.md。
适用场景
- 变更影响分析与调用链追踪。
- 多跳影响分析、授权可达性审计、耦合指标和架构漂移检测。
- AI 智能体替代 grep 和读取整个文件。
- 代码审查（Guardian）在 CI 中运行，基于图谱上下文检测结构和约定缺陷。
限制与注意事项
- 需要 Python 3.12+ 和 uv。
- 支持语言仅限 Python 和 TypeScript / TSX。
- 对于无法解析的调用边，明确保持为未解析并计数；存在已知的解析器缺口（例如在应用根目录摄取会剥离导入携带的 app. 前缀，在包根目录摄取后报告百分比不同）。
- CGIS 不收集任何数据：无遥测、无分析、无账号；代码和图谱保留在用户机器上。唯一例外是可选的：若使用云模型运行 Guardian，则会将审查的 diff 发送给所选提供商。详见 PRIVACY.md。
- 贡献标准见 CONTRIBUTING.md：严格 MyPy、linting、ontology compliance。
商业审计服务
CGIS 免费且可自行运行。作者还提供代码库结构固定价格审计服务：授权覆盖、爆炸半径、耦合、架构漂移，五个工作日内交付，固定价格 $2,400，并列出分析无法看到的内容。
