sina-parsania/CodeGraph

# CodeGraph **面向 AI agents 的代码智能引擎 —— 单一自包含二进制文件，零配置，零幻影边。** CodeGraph 将任何代码仓库索引为**已解析的代码知识图谱**（SQLite），并通过 **MCP**（Claude Code、Cursor、Zed 等）和完整的 **CLI** 为 AI agents 提供服务。Agents 不再需要 grep 或阅读整个文件 —— 它们向图谱查询，即可获得带有已解析调用边的精确 `file:line` 答案。 [](../../releases)    ``` cargo install --path crates/codegraph-cli # one binary, no deps codegraph init # index + wire MCP + done ``` ## 为什么团队选择 CodeGraph | | CodeGraph | 典型的图谱工具 | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | **答案可信度** | **零幻影边** —— 模糊调用*被丢弃，绝不猜测*；每条边都带有 `justification` 标签；结果包含一个**覆盖率信号**（`may_be_incomplete`） | 默默合并同名符号，或生成带有隐藏置信度下限的猜测边 | | **模糊性** | `callers create` → **44 个可固定候选者**，按定义分组 | 一个合并的（错误的）列表，或是一个拒绝查询的黑名单 | | **速度**（实测） | 冷索引 **1.5 s**，查询 **~13 ms**，精简版二进制 **~39 MB** / 带内置 embedder **~55 MB**（发布构件包含所有功能）；**增量重建索引为 O(impact)** —— 一次编辑只会重新解析那些调用点引用了被修改定义的文件，而不是整个 repo | 2.8 s–11 s 冷启动，269 MB 二进制文件，pip/npm 安装开销 | | **确定性** | 相同 commit → **字节完全一致的图谱** —— 可安全提交和共享（`export`/`import`，体积缩小 88 %） | 依赖于机器的结果 | | **覆盖范围** | **跨服务路由枢纽**：后端路由及其前端调用者折叠到一个节点上 —— `blast_radius` 可跨越服务边界 | 各自独立的 repo 孤岛 | ## ⚡ 每个代码问题消耗的 agent token 减少约 ~20–100 倍 一个优秀的 agent 在使用 grep 回答 _"谁调用了这个？"_ 时，必须阅读每个匹配项周围的上下文。而使用 CodeGraph，它可以直接获得一个已解析的答案。在四个 repo 中的实测结果（有界、任务匹配的基准 —— 而非针对整个文件的稻草人测试）：**86 倍 · 21 倍 · 29 倍 · 100 倍**。复现命令：`python3 scripts/benchmark.py --repo `。 ## 您将获得什么 ### 🧠 Agents 可以信任的图谱 - **13 种语言**，统一的语法驱动 tree-sitter 解析器 —— Rust、Python、JS/TS、Go、Swift、Kotlin、Java、C、C++、Ruby、C#、Bash。Arrow-function/`const` 组件是一等节点；每种语言都提供了一套**黄金测试用例集**，用于严格断言哪些边必须存在（以及哪些必须不存在）。 - **分层、基于证据的解析**（每一层都遵循唯一或丢弃原则）：同文件 → `self`/`this` CHA（现已包含 Swift/Kotlin 继承）→ 字段类型（DI，包含 TS 构造函数属性 & Kotlin 构造函数 `val`s）→ 局部变量类型（包含 `new Foo()` 初始化器、泛型/`| null` 解包）→ **import 收窄**（import _即是_ 证据 —— **tsconfig `paths` 别名已解析**）→ Go package 作用域 → 全局唯一。详情：[docs/RESOLUTION.md](docs/RESOLUTION.md)。 - **`codegraph audit` —— 实测的精确度，而非自夸**：对 tree-sitter 边进行采样，将其与合并到您图谱中的编译器预言机（SCIP/IndexStore）进行验证比对，并存储 MCP `stats` 和 `report` 会反馈给 agent 的各层精确度。已发布的、可复现的数据（[docs/BENCHMARK.md](docs/BENCHMARK.md)）：**zod 上 98.7%（TS 预言机，ImportNarrowed 62/62 = 100%） · fastapi 上 93.8%（Python 预言机） · 在一个 55k 节点的私有 monorepo 上 95.0%（IndexStore）** —— 均为基于随机种子的采样的下界。审计甚至能抓出我们自己的 bug：它暴露了一个精确度仅为 27% 的 fallback 层，随后该层被直接删除，而不是被强行辩解。 - **自我修复不变量**：每次提交前，悬空边都会自动修复（复用的编译器边会进行端点过滤），并且图谱带有一个**身份戳** —— 如果图谱是为不同的 repo 构建的，或是由其他工具编写的，codegraph 将拒绝回答。 - **编译器级别的层（可选、持久）**：`codegraph scip` 会合并任何 SCIP 索引 —— 一旦您运行了它，该层就会被**自动维护**：完全重建时会复用已合并的边，并且 HEAD 的移动会自动重新运行检测到的索引器（`CODEGRAPH_AUTO_SCIP=0` 可退出）。`--features indexstore` 会读取 Swift 的 **Xcode IndexStore**（在一个真实的 iOS 应用上解析的调用增加了 +171 %）—— 在索引时合并，查询依然保持在毫秒级。 - **节点级指标**：循环复杂度、扇入/扇出（仅限已解析 —— 真实的度数）、PageRank、介数中心性、Louvain 社区。 - **增量与实时**：一次编辑只会重新解析那些调用点引用了被修改定义的文件（波及传播，O(impact) 而非 O(repo)）—— 经验证与从零开始的索引字节完全一致。MCP 服务器会监视 repo 并在后台进行修复，因此查询永远无需等待重新索引。详情：[docs/INCREMENTAL.md](docs/INCREMENTAL.md)。 ### 🔎 真正能找到东西的搜索 - **子词 FTS**：搜索 `Cook` 即可找到 `OrderCheckoutSessionViewController`（在索引时进行 camelCase/snake_case 拆分）。 - `--regex` 用于锚点/中间片段；多词 OR；通过**内置的本地 embedder** 进行**基于语义的搜索** —— _无需服务器，无需 API key_（默认使用 `bge-small`，设置 `CODEGRAPH_LOCAL_EMBED=code` 可切换至 768 维的代码训练模型；模型信息会被印记到索引中，不匹配则拒绝执行）。 - **索引化向量搜索** —— embeddings 存在于 `sqlite-vec`（`vec0`）KNN 表中，而非暴力扫描，因此语义搜索可以轻松突破过去 ~10k 向量的上限。对于增量索引触及到的符号，向量会自动刷新 —— 每次编辑后无需手动运行 `semantic-index`。 ### 🧭 图谱智能 `callers` / `callees`（带有覆盖率及可固定的候选者） · `impact`（爆炸半径） · `trace` · `implementers` · `important` · `communities` · `routes` · **`context`**（在 token 预算内，通过个性化 PageRank 查找与任务相关的符号） · **`flows`**（按关键性排名的入口点调用链） · **`cypher`**（openCypher 子集图谱查询） · 原始 SQL。 ### 🛡️ 内置感知变更的代码审查 - **`codegraph review --base origin/main --md`** —— 带有风险评分的受影响符号（乘法计算：影响范围 × 复杂度 × 未测试代码），通过一等公民 **TESTS 边**查找测试盲区，以及从 git 历史中挖掘的**共变更加提示**。 - **GitHub Action**（[`action/action.yml`](action/action.yml)）：单一二进制安装，持久的 PR 评论，可选的 `fail-on-high-risk` 门禁。无需 pip/npm。 - `dead-code` —— 连_代码库中任何调用点都未曾引用过_的候选死代码（基于原始调用点证据，已排除入口点/路由/测试）。 ### ✏️ 安全的语义编辑 `rename-symbol old new [--write]` 会重写符号及其所有已解析的引用 —— 如果有任何出现无法被明确归属，则会**拒绝执行**。它绝不会为了完成一次编辑而破坏代码。 ### 📊 可视化图谱 - **`codegraph report`** —— 确定性的 Markdown 快照（无需 LLM）：概览、各层的调用解析质量、核心符号、最强共变更。可复现，适用于 CI 差异对比。 - **`codegraph html [--open]`** —— 生成一个**自包含的**交互式 HTML 文件（力学布局，无需 CDN，无需服务器）：可离线平移/缩放已解析的图谱。文件生成在缓存图谱旁边，保持 repo 一尘不染。 ### 📦 团队就绪 - 中央缓存（`~/.cache/codegraph`）—— 保持 repo 纯净。自动 TTL 清理。 - **`export` / `import`**：提交 zstd 压缩的图谱构件；团队成员可直接跳过完整的重新索引。 - **永远保持最新**：仅基于 stat 的新旧探测 + 每次查询前自动重新索引。 - 支持 文档/PDF/URL/本地化文件的摄取 —— 代码与文档同存于一个图谱中。 ## 快速开始 ``` codegraph init # one-time: index + MCP wiring + agent nudge codegraph search OrderCheckout # subword-tolerant symbol search codegraph callers create # 44 definitions? → pinnable candidates, not a merged lie codegraph review --base develop # risk + test gaps + co-change hints for your diff codegraph flows # entry-point call chains by criticality codegraph context "auth jwt" --budget 1000 # LLM-ready task context codegraph cypher "MATCH (a)-[:Calls]->(b) WHERE b.name = 'save' RETURN a.name LIMIT 10" codegraph semantic "retry with backoff" # meaning search, serverless codegraph export # commit .codegraph/graph.db.zst for your team ``` **MCP（18 个工具）：** `search`, `callers`, `callees`, `blast_radius`, `trace_path`, `context`, `changes`, `dead_code`, `co_changes`, `implementers`, `routes`, `important`, `semantic_search`, `flows`, `graph_query`, `get_node`（带有精确跨度 `snippet`）, `architecture`, `stats` —— 每个工具都带有 agent 指导描述、覆盖率信号以及 `_hints`。 **分层答案契约**：每个图谱答案都会返回一个**精确层**（已解析的边 —— 绝非猜测）加上一个**带标签的文本层**（解析器验证过但被解析器丢弃的调用 token，已经过证据过滤：局部绑定遮蔽、外部 import 排除、最近定义归属）以及覆盖率和一个 `_fallback`。在公开评测集上的实测结果：召回率 0.87，耗时 227 bytes/answer（grep 为 0.94，耗时 2,701），精确度为 0.75 —— 真实性与覆盖率被分别标记，绝不混淆。搜索是**定义优先**的：bm25 + 标签/精确名称排名，将真实的定义置于第十二个仅仅提及它的测试之上。 **导航协议（将已知的未知转化为可操作项）**：每条边都会标明其证据类别；`stats` 会引用经审计测量的各层精确度；且每当精确的答案可能不完整时，响应都会附带一个现成的 **`_fallback` grep 模式**，以便 agent 进行验证，而不是直接断定其不存在。覆盖率的分母排除了那些**绑定到外部包 import** 的调用点（基于证据，而非启发式算法）—— `may_be_incomplete` 绝非空话。 ## 配置（全为可选项） 一切都能在**无模型、无密钥、无守护进程**的情况下运行。`codegraph init` 会写入一个带有注释的 `.codegraph.toml`；环境变量（`CODEGRAPH_*`）可覆盖配置。`codegraph doctor` 会显示当前的准备状态。 **LLM 功能（`ask`, `--rerank`, `--hyde`）—— 分层设计，全为可选项：** 1. 优先使用运行中的 OpenAI 兼容服务器（MLX → LM Studio → Ollama → 通过 API key 访问 OpenAI/Gemini）。 2. 没有服务器？使用 `--features local-llm` 编译的版本会内置一个**纯 Rust 的进程内引擎**（mistral.rs，CPU 运行 —— 支持 macOS/Linux/Windows）。默认模型：Qwen2.5-Coder-0.5B GGUF（约 400 MB，占用约 600 MB RAM），仅在真正使用时才会懒加载；自动下载一次。可通过 `CODEGRAPH_LOCAL_LLM_REPO`/`CODEGRAPH_LOCAL_LLM_FILE` 覆盖（例如使用 1.5B 模型以获得更高质量）。发布的二进制文件已包含此。 3. 安装了 Xcode Metal Toolchain 的 Mac 可以编译 `--features local-llm-metal` 以进行 GPU 推理。 语义搜索也是同样的道理：`--features local-embed` 会内置 embedder（发布的二进制文件已包含）—— 无需服务器。 ## 横向对比 完整的实测对比（包含实机运行 + 对竞品工具的源码级审计）：**[docs/BENCHMARK.md](docs/BENCHMARK.md)** · 对比路线图：[docs/plans/](docs/plans/)。 ## 架构 ``` crates/ codegraph-core types, config, deterministic ids codegraph-parse tree-sitter → nodes, calls, imports, fields, locals, metrics codegraph-graph tiered resolution (unique-or-drop), PageRank/Louvain/betweenness, flows codegraph-resolve SCIP merge (compiler-grade, optional) codegraph-indexstore Xcode IndexStore merge (Swift compiler-grade, optional) codegraph-store SQLite: nodes/edges/calls/sqlite-vec KNN/FTS5(external-content)/cochanges/meta codegraph-llm OpenAI-compat client + optional bundled embedder (fastembed) & chat engine (mistral.rs) codegraph-mcp MCP server (18 tools, generation-keyed graph cache, fs-watcher, coverage signals) codegraph-cli the `codegraph` binary ``` **设计不变量：** 单一静态二进制文件 · 确定性构建 · 精确度至上的解析 · 重量级依赖受 feature-gate 控制（`indexstore`, `local-embed`, `local-llm`, `media`）。 ## License MIT OR Apache-2.0. ⭐ **如果 CodeGraph 挽救了您 agent 的 token 消耗（它一定会的），请给本仓库点个 Star** —— 您的帮助能让更多人发现它。

标签：AI代码智能, MCP, Rust, SOC Prime, 代码搜索引擎, 代码知识图谱, 可视化界面, 多云安全, 开发工具, 网络流量审计, 通知系统, 错误基检测, 静态代码分析