ColinVaughn/CodeGraph

# CodeGraph 将任何代码文件夹转化为持久、可查询的**知识图谱**，然后查询这个 紧凑的图谱，而无需重新阅读整个代码库。CodeGraph 通过 [tree-sitter](https://tree-sitter.github.io/) 提取 30 多种语言的符号和 关系，将它们聚类为社区，凸显结构上重要的部分，并 编写机器可读的图谱以及人类可读的报告和可视化。 它是一个单一的静态 Rust 二进制文件 (`codegraph`)，没有 runtime 和解释器，外加一个 MCP server，以便 AI 编程助手可以在 grep 或读取文件之前查阅图谱。 ## Token 经济（已测量） 其核心目的是**读取简短的答案，而不是整个代码库**。在 CodeGraph 自身的源代码（199 个 Rust 文件，56,408 行，**510,966** 个 `cl100k` token）上测量，针对一个结构化问题的一个 `query_graph` 回答约为 **~1,950 个 token**（受限于其 token 预算），而阅读该答案实际触及的源文件则需： 在跨越不同子系统的六个问题中，查询图谱使用的 token 比阅读答案引用的文件 **少 27-38 倍**（总体约 **31 倍**）： | 问题 | 查询响应 | 阅读文件 | 更少的 token | |---|--:|--:|--:| | http 请求处理 | 1,804 | 48,803 | 27x | | session 创建 / 清理 | 1,974 | 65,578 | 33x | | query_graph 子图 | 2,011 | 53,759 | 27x | | 提取 walker | 1,977 | 70,443 | 36x | | PR 拉取 / 排名 | 1,926 | 73,231 | 38x | | 增量合并 | 2,010 | 53,440 | 27x | 无论 repo 变得多大，查询响应都保持很小（它受限于 token 预算），因此该比率会随着代码库的增加而增长。请注意，`graph.json` 索引本身很大， 因为它编码了每个符号和边；你永远不会将它加载到 context 中，你只需查询它并 仅返回上面的那部分切片。 **可复现。** Token 是通过 `cargo run -p codegraph-server --example tokcount` 获得的准确 `cl100k_base` 计数。基准是结果节点所在的唯一源文件 （整个文件，即保守的 grep 后读取情况；它不 计算在没有图谱的情况下你会打开的死胡同文件）。在任何 repo 上运行 `codegraph extract .` 并亲自比较。 ## 为什么 - **Token 经济。** 查询紧凑图谱的成本仅为将原始文件喂给 LLM 的一小部分，因此助手无需加载 repo 即可回答“什么调用了这个？”或“这个更改会破坏什么？”。 - **结构清晰。** God nodes、令人惊讶的跨模块连接、import cycles 和 社区结构都已为你计算好。 - **你可审计的置信度。** 每个推断出的关系都会被标记为 `EXTRACTED`、 `INFERRED` 或 `AMBIGUOUS`。 - **超越单个 repo 的扩展性。** 一个 workspace 可以通过真正的跨 repo 边解析来联邦化多个 repo（导出表面加上 import / tsconfig / module-federation 别名）。 - **默认离线。** 仅包含代码的语料库永远不会发起网络调用。唯一需要 API key 的功能是对文档和论文进行的可选语义遍历。 ## 亮点 - 通过 tree-sitter 支持 **30 多种语言**，每个语言都在 CI 中独立构建和测试，外加针对少数格式的基于 regex 的提取器，以及针对 Vue/Svelte/Astro 和 Razor/Blazor 的脚本提取。请参阅 [语言](https://github.com/ColinVaughn/CodeGraph/wiki/Languages)。 - **一条命令生成完整图谱**，外加 2D、3D 和 SVG 可视化、Markdown 报告， 以及 GraphML / Cypher / DOT / Obsidian / wiki 导出。请参阅 [输出格式](https://github.com/ColinVaughn/CodeGraph/wiki/Output-Formats)。 - **图谱查询**：相关子图搜索、最短路径、节点解释和 反向影响（“什么依赖于这个”）。请参阅 [查询](https://github.com/ColinVaughn/CodeGraph/wiki/Querying)。 - **MCP server**（协议 2025-06-18）通过 stdio 或 HTTP 暴露 17 个只读工具： 子图搜索、源代码读取、反向影响，以及 PR/working-tree 爆炸半径，外加 prompts、completions、resource subscriptions 和结构化工具输出。请参阅 [MCP Server](https://github.com/ColinVaughn/CodeGraph/wiki/MCP-Server)。 - **增量重建**、文件监视和 git hooks 保持图谱最新。请参阅 [增量更新](https://github.com/ColinVaughn/CodeGraph/wiki/Incremental-Updates)。 - **具有图谱感知能力的 PR 仪表板**，带有爆炸半径和合并顺序冲突检测。请参阅 [PR 仪表板](https://github.com/ColinVaughn/CodeGraph/wiki/PR-Dashboard)。 ## 安装 CodeGraph 使用稳定的 Rust 工具链构建（通过 [rust-toolchain.toml](rust-toolchain.toml) 锁定在 1.95）。 ``` # 从 clone 开始，将 `codegraph` binary 安装到你的 PATH： cargo install --path bin/codegraph # ...或者在 in-tree 中构建它： cargo build --release # -> target/release/codegraph ``` Linux/macOS/Windows 的预构建二进制文件附在每个带标签的 [GitHub Release](../../releases) 中（参见 `release` 工作流）。可选集成位于 feature flags 之后（默认关闭）：`pg`（Postgres 内省）、`push`（实时 Neo4j/FalkorDB 导出）和 `office` / `gws` / `media`（电子表格 / Google-Workspace / 音视频摄取），例如 `cargo install --path bin/codegraph --features pg,push`。请参阅 [安装](https://github.com/ColinVaughn/CodeGraph/wiki/Installation) 和 [配置](https://github.com/ColinVaughn/CodeGraph/wiki/Configuration)。 ## 快速入门 ``` # 1. 为当前目录构建 graph -> codegraph-out/ codegraph extract . # 2. 向 graph 提问（返回相关的 subgraph） codegraph query "authentication flow" # 3. 更改一个 symbol 会破坏什么？（反向影响） codegraph affected parse_config # 4. 通过 MCP 将 graph 提供给 AI 助手 codegraph serve ``` `extract` 遵循 `.codegraphignore` / `.gitignore` 并跳过敏感文件（`.env`、keys）。 仅包含代码的语料库完全离线运行；针对文档和论文的可选 LLM 语义遍历 （`extract --semantic`）需要 API key（例如 `OPENAI_API_KEY`）。请参阅 [快速入门](https://github.com/ColinVaughn/CodeGraph/wiki/Quickstart)。 ## 输出产物 (`codegraph-out/`) | 产物 | 它是什么 | |---|---| | `graph.json` | 完整图谱（节点-链接 JSON），查询它而无需重新读取文件 | | `GRAPH_REPORT.md` | God nodes、令人惊讶的连接、建议的问题、import cycles | | `graph.html` | 交互式 2D 浏览器（搜索 + 社区颜色） | | `graph-3d.html` | 交互式 3D 力导向图（搜索、关系切换、联邦颜色） | | `graph.svg` | 静态布局（Barnes-Hut、组件打包、资产形状化） | | `graph.graphml` / `graph.cypher` / `graph.dot` | 导入 Gephi / Neo4j / Graphviz | | `callflow.html` / `tree.html` | Mermaid 调用流程 + D3 文件树 | | `obsidian/`, `wiki/` | Obsidian vault / Markdown wiki（使用 `--obsidian` / `--wiki`） | ## 命令 | 命令 | 它的作用 | |---|---| | `extract [path]` | 构建图谱并写入 `codegraph-out/`。Flags：`--directed`、`--obsidian`、`--wiki`、`--semantic` | | `export ` | 从现有的 `graph.json` 重新生成格式（无需重建）或实时推送到 Neo4j/FalkorDB | | `query ` | 返回相关子图。Flags：`--max-nodes`、`--repo`、`--dfs` | | `path ` | 两个节点之间的最短路径 | | `explain ` | 显示一个节点及其邻居 | | `affected ` | （传递性地）依赖于某个节点的节点。Flags：`--depth`、`--relation` | | `update [paths...]` | 文件更改后增量重建（`--full` 用于完全重建） | | `watch` | 随着文件更改自动重建 | | `serve` | 运行 MCP server（stdio，或 `--http --api-key `） | | `prs [number]` | 图谱感知的 PR 仪表板 / 详情。Flags：`--triage`、`--conflicts`、`--base`、`--repo` | | `workspace ` | 多 repo / monorepo 联邦（`init`/`add`/`discover`/`build`/`federate`/`sync`/`status`/`list`） | | `global ` | 跨 repo 全局图谱存储（`~/.codegraph`） | | `merge-graphs ` | 将多个 `graph.json` 文件组合成一个带有 namespace 的图谱 | | `ingest ` | 摄取外部源（cargo / mcp / scip / pg / url；`office` / `gws` / `media` 位于 feature flags 之后） | | `hook ` | 管理 git hooks + `graph.json` 合并驱动程序 | | `install` / `uninstall [platform]` | 为主机助手安装 CodeGraph skill | | `cache ` | 维护磁盘上的提取缓存 | 包含每个 flag 的完整参考在[命令](https://github.com/ColinVaughn/CodeGraph/wiki/Commands)中。在终端运行 `codegraph --help` 以获取 flag 列表。 ## 从 AI 助手使用它 (MCP) ``` codegraph serve # stdio MCP server codegraph serve --http 127.0.0.1:8765 --api-key "$CODEGRAPH_API_KEY" # HTTP server ``` 该 server 暴露了 17 个只读工具：图谱导航（`query_graph`、`get_node`、 `get_source`、`get_neighbors`、`get_community`、`god_nodes`、`graph_stats`、`shortest_path`）、影响分析（`affected`、`find_callers`、`find_callees`）、联邦（`list_repos`、 `repo_stats`）和变更/PR 审查（`working_changes_impact`、`list_prs`、`get_pr_impact`、 `triage_prs`）。它还提供 MCP prompts、参数 completions、resource templates 和 subscriptions，以及一个小型 REST 接口（`/api/stats`、`/api/query`、...），供非 MCP 客户端使用。`codegraph install` 将图谱接入主机助手（Claude 的 `PreToolUse` hook；Codex 的原生 MCP server，使用 `codegraph install codex --global` 为 Codex 桌面应用配置）。请参阅 [MCP Server](https://github.com/ColinVaughn/CodeGraph/wiki/MCP-Server) 和 [助手集成](https://github.com/ColinVaughn/CodeGraph/wiki/Assistant-Integration)。 ## 语言 通过 tree-sitter 支持 30 多种语言，每种都在 CI 中独立构建和测试：Python、 JavaScript/TypeScript（+ JSX/TSX、Vue/Svelte/Astro）、Go、Rust、Java、C#、Kotlin、Swift、C、 C++、Objective-C、Ruby、PHP、Scala、Groovy、Lua、Dart、Elixir、Julia、Zig、Bash、PowerShell、 Verilog、Fortran，以及针对 Classic ASP、Salesforce Apex、 Pascal/Delphi 和 Razor/Blazor 的 regex/委托提取器。此外还有数据和项目格式：SQL、JSON、YAML、 HCL/Terraform、.NET 项目文件（`.csproj`/`.sln`/`.slnx`）和 Markdown 结构。 针对 PHP/Laravel 和 Dart/Flutter 的框架感知边。完整细分请见 [语言](https://github.com/ColinVaughn/CodeGraph/wiki/Languages)。 ## 文档 完整文档位于[项目 wiki](https://github.com/ColinVaughn/CodeGraph/wiki)： - **入门：** [主页](https://github.com/ColinVaughn/CodeGraph/wiki/Home) - [安装](https://github.com/ColinVaughn/CodeGraph/wiki/Installation) - [快速入门](https://github.com/ColinVaughn/CodeGraph/wiki/Quickstart) - **概念：** [架构](https://github.com/ColinVaughn/CodeGraph/wiki/Architecture) - [语言](https://github.com/ColinVaughn/CodeGraph/wiki/Languages) - **使用它：** [命令](https://github.com/ColinVaughn/CodeGraph/wiki/Commands) - [提取](https://github.com/ColinVaughn/CodeGraph/wiki/Extraction) - [查询](https://github.com/ColinVaughn/CodeGraph/wiki/Querying) - [分析和报告](https://github.com/ColinVaughn/CodeGraph/wiki/Analysis-and-Reports) - [输出格式](https://github.com/ColinVaughn/CodeGraph/wiki/Output-Formats) - [可视化](https://github.com/ColinVaughn/CodeGraph/wiki/Visualizations) - **集成：** [MCP Server](https://github.com/ColinVaughn/CodeGraph/wiki/MCP-Server) - [助手集成](https://github.com/ColinVaughn/CodeGraph/wiki/Assistant-Integration) - [摄取](https://github.com/ColinVaughn/CodeGraph/wiki/Ingestion) - [语义分析](https://github.com/ColinVaughn/CodeGraph/wiki/Semantic-Analysis) - **扩展：** [Workspaces 和联邦](https://github.com/ColinVaughn/CodeGraph/wiki/Workspaces-and-Federation) - [增量更新](https://github.com/ColinVaughn/CodeGraph/wiki/Incremental-Updates) - [PR 仪表板](https://github.com/ColinVaughn/CodeGraph/wiki/PR-Dashboard) - **参考：** [配置](https://github.com/ColinVaughn/CodeGraph/wiki/Configuration) - [开发](https://github.com/ColinVaughn/CodeGraph/wiki/Development) ## 开发 ``` cargo test --workspace --all-features # all tests cargo fmt --all --check # formatting (enforced in CI) cargo clippy --workspace --all-targets --all-features -- -D warnings ``` 代码库包含 个库 crates（`crates/*`）以及 `codegraph` 二进制文件（`bin/`）。CI 独立构建每种语言的语法，这样默默地丢弃 nodes/edges 的语法版本升级 就会在自身测试中失败。请参阅[开发](https://github.com/ColinVaughn/CodeGraph/wiki/Development) 和 [架构](https://github.com/ColinVaughn/CodeGraph/wiki/Architecture)。 ## 许可证 GNU Affero General Public License v3.0 或更高版本（`AGPL-3.0-or-later`），请参阅 [LICENSE](LICENSE)。如果你将修改后的 CodeGraph 版本作为网络服务运行（例如 HTTP MCP server），AGPL 要求你向其用户提供修改后的源代码。

标签：AI辅助编程, MCP, Mutation, Rust, tree-sitter, 云安全监控, 代码分析, 凭证管理, 可视化, 可视化界面, 测试用例, 网络流量审计, 通知系统, 静态分析