sunerpy/codegraph-rust

# CodeGraph-Rust [](https://github.com/sunerpy/codegraph-rust/actions/workflows/ci.yml) [](#license) CodeGraph 读取代码库，提取符号及其关系（通过 tree-sitter），将它们持久化到特定于项目的 SQLite 数据库中（包含 FTS5 搜索），并通过 CLI 和 MCP stdio server 公开结果。 二进制文件中没有任何 AI/LLM —— 输出是字节稳定且确定性的。 ## 快速开始 **安装（Linux / macOS）：** ``` curl -fsSL https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.sh | sh ``` **安装（Windows, PowerShell）：** ``` irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.ps1 | iex ``` **索引项目并查询它：** ``` codegraph init /path/to/project # create .codegraph/ and run the first index codegraph query "" -p /path/to/project # full-text search codegraph serve --mcp --path /path/to/project # MCP server (--path optional, defaults to cwd) ``` ## 安装说明 CLI 包是 **`codegraph-rs`** —— 一个名为 `codegraph` 的单一二进制文件。SQLite 被编译在内（不需要系统 SQLite）。未发布到 crates.io。

🤖 对于 AI agent / LLM —— 请先阅读本节

你是一个 AI 编码 agent。CodeGraph 是一个确定性的代码知识图谱 （tree-sitter + SQLite/FTS5），它回答关于代码库的结构性问题 —— “谁调用了 X”、“更改 X 会破坏什么”、“X 在哪里”、“这个区域如何 工作” —— 通过**一次亚毫秒级的查询，而不是数十次的 grep + 文件读取**。 它返回逐字的源码以及调用者/被调用者/影响图谱，因此你能以更少的 token 和往返次数获得更准确的上下文。它内部没有 AI/LLM —— 它纯粹是 预计算的结构，供_你_使用。 **安装 + 索引一个项目** —— 优先使用单行安装程序（下载 预构建的二进制文件；不需要 Rust 工具链，无需等待编译）： ``` # Linux / macOS — 一键安装（推荐） curl -fsSL https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.sh | sh # Windows (PowerShell 5.1+) irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.ps1 | iex # 备选方案 — 从源码构建（仅当你拥有 Rust toolchain 时） cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs # binary: `codegraph` codegraph init /path/to/project # create the index DB (.codegraph/) codegraph index /path/to/project # parse + build the graph ``` **将其用作 MCP server（推荐用于 agent）。** 它通过 stdio 进行 MCP 通信： ``` codegraph serve --mcp # defaults to cwd (recommended: use codegraph install) codegraph serve --mcp --path /path/to/project # optional: pin to a specific project ``` 自动将其注册到你的 agent 配置中（Claude Code、Cursor、Codex CLI、 opencode、Hermes、Gemini CLI、Antigravity、Kiro）： ``` codegraph install --yes # detects installed agents and wires them up ``` **你可以调用的 MCP 工具**（对于已索引的源码，优先使用这些而不是 grep/read）： | 工具 | 用途 | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `codegraph_explore` | 首要工具 —— “X 是如何工作的”、架构、流程、考察某个区域。一次调用即可返回按文件分组的相关的符号源码。 | | `codegraph_search` | 按名称定位符号（类型 + 文件:行号 + 签名） | | `codegraph_node` | 读取符号/文件的逐字源码 + 其调用者/被调用者轨迹（一个更智能的 `Read`） | | `codegraph_callers` / `codegraph_callees` | 谁调用了这个 / 这个调用了什么 | | `codegraph_impact` | 修改符号的影响范围（传递性的） | | `codegraph_files` / `codegraph_status` | 列出目录 / 检查索引就绪状态 | **经验法则：**在读取文件之前先使用 `codegraph_explore`；信任 其结果（完整的 AST 解析 —— 无需用 grep 再次验证）；使用 `codegraph_impact` 进行重构影响范围分析，而不是手动遍历调用者。索引比文件写入 延迟约 1 秒；工具响应会标记任何过期的文件。

### 单行安装（脚本） 最快的途径 —— 脚本会检测你的平台，下载正确的二进制文件， 并将其放到你的 PATH 中： ``` # Linux / macOS curl -fsSL https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.sh | sh # Windows (PowerShell 5.1+) irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.ps1 | iex ``` 设置 `CODEGRAPH_VERSION=v0.3.0` 可以固定到特定的发布版本，而不是最新版本。 ### 预构建二进制文件 从 [Releases](https://github.com/sunerpy/codegraph-rust/releases) 页面下载一个压缩包，将其解压， 并把 `codegraph` 放到你的 PATH 中。资产命名为 `codegraph--.`： | 平台 | 架构 | Target | 扩展名 | | -------- | ----------------------- | ---------------------------- | ------- | | Linux | x86_64 (静态, musl) | `x86_64-unknown-linux-musl` | .tar.gz | | Linux | aarch64 (静态, musl) | `aarch64-unknown-linux-musl` | .tar.gz | | macOS | x86_64 | `x86_64-apple-darwin` | .tar.gz | | macOS | aarch64 (Apple Silicon) | `aarch64-apple-darwin` | .tar.gz | | Windows | x86_64 | `x86_64-pc-windows-msvc` | .zip | | Windows | aarch64 (ARM64) | `aarch64-pc-windows-msvc` | .zip | Linux 构建是静态链接的（musl）—— 没有 glibc 或 SQLite 系统依赖。 ### 使用 cargo（从 git） ``` cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs ``` 有关完整的源码构建（优化的二进制文件 + 开发者目标），请参阅 [`docs/architecture.md`](docs/architecture.md) 或运行 `make help`。 ## MCP 快速注册 添加到你的 agent 的 MCP 配置中（或者运行 `codegraph install --yes` 来自动完成）： ``` { "mcpServers": { "codegraph": { "command": "codegraph", "args": ["serve", "--mcp"], }, }, } ``` **默认（无 `-p`）：** MCP server 从 agent 的工作目录解析项目， 因此一个配置适用于你所有的项目 —— 每个项目只需 使用 `codegraph index` 进行索引。**可选的 `-p ` / `--path `：** 将 server 固定到一个项目，而不论 cwd 是什么（例如 `"args": ["serve", "--mcp", "-p", "/abs/path/to/project"]`）。 支持的 agent：Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、 Gemini CLI、Antigravity IDE、Kiro。 ``` codegraph install --yes # auto-detect installed agents codegraph install --target=claude,cursor --yes # explicit list codegraph install --target=auto --local # project-local config ``` 完整的 MCP 工具参考：[`docs/mcp.md`](docs/mcp.md)。 ## 将 CodeGraph 与 LLM 一起使用 CodeGraph **没有内置的 LLM**，但其设计旨在为一个 LLM 提供数据。分工 如下：CodeGraph 以亚毫秒级的速度产生确定性的结构事实（调用图、影响范围， 中心性）；你的 LLM 在已经定位的小上下文上进行推理。 两种模式：**MCP**（agent 直接调用 codegraph 工具）或 **后端 编排**（你的服务调用 `export`/`explore`，组装 prompt，喂给 你的 LLM）。一个可运行的示例： ``` python examples/llm_orchestration.py --repo . --query "how does indexing work" ``` 请参阅 [`examples/llm_orchestration.py`](examples/llm_orchestration.py) 获取完整的 脚本。这两种模式都没有触及“无 AI”护栏 —— 该护栏只是禁止在 codegraph 二进制文件本身_内部_嵌入 LLM 库。 ## CLI 子命令 核心命令：`init`、`index`、`sync`、`query`、`files`、`status`、`serve`、 `callers`、`callees`、`impact`、`affected`、`check`、`export`、`unlock`。 Agent / 安装命令：`install`、`uninstall`、`self-update`、`completions` （`--install` 会为 bash/zsh/fish/powershell/elvish 设置 Tab 补全）。 路径约定：大多数遍历命令（`init`/`index`/`status`/`callers` 等） 接受项目路径作为位置参数或 `-p/--path`；`query`/`files`/ `serve` 使用 `-p/--path`。 ## CodeGraph 能做什么（和不能做什么） **能做的：** 跨越约 29 种语言的确定性代码结构提取（TypeScript、 Python、Go、Rust、Java、C/C++、C#、Vue、Svelte、GDScript 等 —— 详见 [`docs/grammar-manifest.md`](docs/grammar-manifest.md)），跨文件解析、 图谱遍历、FTS5 搜索、带有确定性 PageRank 中心性的全图导出、MCP/CLI 接口， 以及黄金标准的字节稳定输出。 **不能做的：** 二进制文件内部没有任何 AI / 向量 / embedding / LLM（硬性 约束，由 `scripts/guardrail.sh` 强制执行）；没有语义搜索；没有超出固定 `LANGUAGES` 集合的 语言。 ## 文档 - [`docs/architecture.md`](docs/architecture.md) —— crate 依赖图， 提取/解析/遍历/搜索 pipeline，daemon/watch 生命周期。 - [`docs/data-model.md`](docs/data-model.md) —— SQLite/FTS5 存储契约。 - [`docs/equivalence.md`](docs/equivalence.md) —— 三级等价性 oracle， 黄金标准重新生成，`KNOWN_DIFFS.md` 格式。 - [`docs/grammar-manifest.md`](docs/grammar-manifest.md) / [`docs/embedded-extraction.md`](docs/embedded-extraction.md) —— 语言支持 和提取层级。 - [`docs/cli.md`](docs/cli.md) —— 完整的 CLI 子命令参考（20 个子命令， 所有 flag）。 - [`docs/mcp.md`](docs/mcp.md) —— MCP server 协议，所有 10 个工具，JSON-RPC 详情。 - [`examples/`](examples/) —— codegraph + LLM 编排示例。 - [`docs/readme/README.zh-CN.md`](docs/readme/README.zh-CN.md) —— 中文说明. ## License MIT —— 见 [`LICENSE-MIT`](LICENSE-MIT)。

标签：MCP服务器, SOC Prime, SQLite, 云安全监控, 代码知识图谱, 代码索引, 可视化界面, 开发工具, 通知系统, 静态分析