rpg-encoder

为你的代码库赋予 AI 代理一个大脑。

AI 编码代理在大多数工具调用中浪费时间，通过 `grep`、`cat`、`find` 和文件读取在代码库中摸索。`rpg-encoder` 解决了这个问题。它使用 [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) 构建代码的**语义图**——不仅是*谁调用谁*，而是*每个函数的作用*——并通过 [MCP](https://modelcontextprotocol.io/) 在单次工具调用中让 AI 助手获得整个仓库的理解。

## 快速开始 ``` claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server ``` 一条命令。适用于 Claude Code、Cursor、opencode、Windsurf 或任何 MCP 兼容代理。不需要 Rust 工具链、克隆或构建——`npx` 会为你的平台下载预编译的二进制文件。 然后打开任意仓库并告诉你的代理： 你的代理处理一切：索引实体（秒级）、读取每个函数并添加上下文级特征（几分钟）、将它们组织成语义层次结构，并将 `.rpg/graph.json` 提交给团队。 对于包含约 100+ 个实体的仓库，`lifting_status` 会提示你的代理将提升循环委托给子代理或更便宜的模型；特征提取是模式匹配，而非新颖推理。如果你的运行时没有子代理机制，可以在终端中运行 `rpg-encoder lift --provider anthropic|openai`（需提供 API 密钥），CLI 会直接调用外部 LLM 而不涉及代理。CLI 完成后，在会话中调用 `reload_rpg` 加载更新后的图。CLI 提升无特征的实体；重新提升具有特征但因代码变更而过时的实体由会话内的 MCP 流处理，而非 CLI。 提升完成后，尝试以下操作： - *“什么是认证处理逻辑？”* —— 即使没有名为“auth”的代码也能找到 - *“展示所有依赖数据库连接的部分”* - *“计划为 API 端点添加速率限制”* ## 在使用 `grep`、`cat`、`find` 之前先使用 RPG 服务器指令要求你的代理在涉及代码结构或行为的问题上**优先使用 RPG 工具**。这一习惯很重要——`grep`、`cat` 和临时文件读取会消耗令牌并错过 RPG 已知的语义关系。 | 如果你原本会使用… | 请改用… | |---|---| | `grep -r` / `rg`（按意图） | `search_node(query="…")` | | `grep -r` / `rg`（按名称） | `search_node(query="…", mode="snippets")` | | `cat` / 阅读函数 | `fetch_node(entity_id="file:name")` | | 串联 grep 查找调用者/被调用者 | `explore_rpg(entity_id="…", direction="…")` | | 递归 grep 查找“依赖 X 的东西” | `impact_radius(entity_id="…")` | | `wc -l` / `find` / `tree` | `rpg_info` | | 阅读多个文件获取上下文 | `semantic_snapshot` | | 手动搜索 → 获取 → 探索链条 | `context_pack(query="…")` | | “如何安全地重构 X” | `plan_change(goal="…")` | 除非查询涉及字面文本（字符串搜索、注释、TODO、日志消息），否则请回退到 `grep`、`cat` 或文件读取。 ## 工作原理

1. **解析** — Tree-sitter 从 15 种语言中提取实体（函数、类、方法）和依赖边（导入、调用、继承）。 2. **提升** — 一个 LLM（你的代理或如 Haiku 这类廉价 API）读取每个实体并写出动词‑对象特征：*“验证 JWT 令牌”*、*“将配置序列化到磁盘”*。 3. **组织** — 特征聚合成一个三层语义层次（区域 → 类别 → 子类），该层次由*代码行为*而非文件树自动涌现。 4. **理解** — `semantic_snapshot` 将整个图压缩为约 25K Token。你的 LLM读取一次即可“了解”整个仓库。 ### 语义快照

无需在文件间反复 `grep`，LLM 只需调用一次 `semantic_snapshot` 即可获得： - **层次结构** — 每个功能区域及其聚合特征 - **实体** — 每个函数、类、方法，按区域分组并附带语义特征 - **依赖骨架** — 浓缩的调用图（使用限定名） - **热点** — 连接度最高的前 10 个实体（架构骨干） 约 25K Token 可覆盖约 1000 个实体。这仅占 1M 上下文窗口的 2–3% — LLM 在每个会话开始时就已经“知道”你的仓库。 ### 自维护图

每当工作树发生变化（已提交、暂存或未暂存）时，MCP 服务器会在响应下一个查询前自动重新同步。`(path, size, mtime)` 上的变更集哈希意味着对同一文件的重复保存只会触发一次同步，空闲查询则不会触发。撤销操作也会被检测：如果之前脏的文件恢复到 HEAD 状态，图将被还原。 ### 两种提升模式 | 模式 | 命令 | 成本 | 费用承担方 | |------|------|------|----------| | **代理提升** | *“构建并提升 RPG”* | 订阅令牌 | 你的 Claude Code / Cursor 订阅 | | **自主提升** | `auto_lift(provider="anthropic", api_key_env="ANTHROPIC_API_KEY")` | 约 $0.02 每 100 个实体 | 外部 API 密钥（Haiku、GPT-4o-mini、OpenRouter、Gemini） | `auto_lift` 直接调用廉价的外部 LLM，你的编码订阅不会参与提升工作。使用 `api_key_env` 从环境变量解析密钥，避免在工具调用记录中暴露。 ## 架构

七个 Rust Crates、一个 MCP 服务器二进制文件和一个 CLI 二进制文件： | Crate | 作用 | |-------|------| | `rpg-core` | 图类型（RPGraph、实体、层次节点）、存储、LCA 算法 | | `rpg-parser` | Tree-sitter 实体与依赖提取（15 种语言） | | `rpg-encoder` | 编码流水线、提升工具、增量演化 | | `rpg-nav` | 搜索、获取、探索、快照、TOON 序列化 | | `rpg-lift` | 自主 LLM 提升（Anthropic、OpenAI、OpenRouter、Gemini） | | `rpg-cli` | CLI 二进制文件（`rpg-encoder`） | | `rpg-mcp` | MCP 服务器二进制文件（`rpg-mcp-server`），提供 27 个工具 | ## MCP 工具（27 个）

构建与维护（4 个工具）

| 工具 | 描述 | |------|------| | `build_rpg` | 索引代码库（运行一次，即时完成） | | `update_rpg` | 从 Git 变更进行增量更新 | | `reload_rpg` | 在外部变更后从磁盘重新加载图 | | `rpg_info` | 图统计信息、层次概览、各区域提升进度 |

导航与搜索（5 个工具）

| 工具 | 描述 | |------|------| | `semantic_snapshot` | 单次调用获取全仓库语义理解（约 25K Token 覆盖 1000 个实体） | | `search_node` | 通过混合嵌入与词法评分按意图或关键词搜索实体 | | `fetch_node` | 获取实体元数据、源代码、依赖关系及层次上下文 | | `explore_rpg` | 遍历依赖图（上游、下游或双向） | | `context_pack` | 单次调用完成搜索 + 获取 + 探索（带令牌预算） |

summary>规划与分析（7 个工具） | 工具 | 描述 | |------|------| | `impact_radius` | 可达性分析——*“哪些部分依赖 X？”* | | `plan_change` | 变更规划——找到相关实体、修改顺序及影响范围 | | `find_paths` | 两个实体之间的 K 条最短依赖路径 | | `slice_between` | 提取连接两个实体的最小子图 | | `analyze_health` | 代码健康度：耦合性、不稳定性、上帝对象、重复代码检测 | | `detect_cycles` | 发现循环依赖与架构环 | | `reconstruct_plan` | 依赖安全的重构执行计划 |

语义提升（11 个工具）

| 工具 | 描述 | |------|------| | `auto_lift` | 通过廉价 LLM API（Haiku、GPT-4o-mini、OpenRouter、Gemini）一次性自主提升 | | `lifting_status` | 仪表盘——覆盖度、各区域进度、下一步建议 | | `get_entities_for_lifting` | 获取待提升实体的源代码供代理分析 | | `submit_lift_results` | 将代理的语义特征提交回图 | | `finalize_lifting` | 聚合文件级特征并重建层次元数据 | | `get_files_for_synthesis` | 获取文件级实体特征用于整体综合 | | `submit_file_syntheses` | 提交整体文件级摘要 | | `build_semantic_hierarchy` | 获取领域发现与层次分配提示 | | `submit_hierarchy` | 将层次分配应用到图中 | | `get_routing_candidates` | 获取需要语义路由的实体（漂移或待提升） | | `submit_routing_decisions` | 提交路由决策（层次路径或“保留”） |

## 支持的语言 15 种语言通过 Tree-sitter 支持： | 语言 | 实体提取 | 依赖解析 | |------|----------|----------| | Python | 函数、类、方法 | 导入、调用、继承 | | Rust | 函数、结构体、特征、实现方法 | 用法、调用、特征实现 | | TypeScript | 函数、类、方法、接口 | 导入、调用、继承 | | JavaScript | 函数、类、方法 | 导入、调用、继承 | | Go | 函数、结构体、方法、接口 | 导入、调用 | | Java | 类、方法、接口 | 导入、调用、继承 | | C / C++ | 函数、类、方法、结构体 | 包含、调用、继承 | | C# | 类、方法、接口 | using、调用、继承 | | PHP | 函数、类、方法 | use、调用、继承 | | Ruby | 类、方法、模块 | require、调用、继承 | | Kotlin | 函数、类、方法 | 导入、调用、继承 | | Swift | 函数、类、结构体、协议 | 导入、调用、继承 | | Scala | 函数、类、对象、特征 | 导入、调用、继承 | | Bash | 函数 | source、调用 | ## 安装 ### MCP 服务器（推荐） ``` # Claude Code claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server # Cursor — add to ~/.cursor/mcp.json { "mcpServers": { "rpg": { "command": "npx", "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server"] } } } ``` 服务器会自动从当前工作目录检测项目根目录——无需传入路径参数。

CLI

``` npm install -g rpg-encoder # 构建图 rpg-encoder build # 查询 rpg-encoder search "parse entities from source code" rpg-encoder fetch "src/parser.rs:extract_entities" rpg-encoder explore "src/parser.rs:extract_entities" --direction both --depth 2 rpg-encoder info # 通过 API 自动提升 rpg-encoder lift --provider anthropic --dry-run # estimate cost rpg-encoder lift --provider anthropic # lift with Haiku (~$0.02/100 entities) # 增量更新 rpg-encoder update # 预提交钩子（提交时自动更新图） rpg-encoder hook install ```

从源码构建

``` git clone https://github.com/userFRM/rpg-encoder.git cd rpg-encoder && cargo build --release ``` 然后将 MCP 配置指向 `target/release/rpg-mcp-server`。

## 文档 - [与 GitNexus 的对比](docs/comparison.md) —— 与 GitNexus、Serena、Repomix 等工具的诚恳比较 - [论文保真度](docs/paper_fidelity.md) —— 算法与论文的逐项对比 - [使用场景](use_cases.md) —— RPG 所能实现的具体用例 - [变更日志](CHANGELOG.md) —— 发行历史 ## 灵感与参考 rpg-encoder 的构建基于 RPG-Encoder 研究的理论框架，并融合了代码智能领域多种工具的灵感： - **[RPG-Encoder 论文](https://arxiv.org/abs/2602.02084)**（Luo 等，2026，微软研究院）—— 语义提升模型、三层层次构建、增量演化算法、正式图模型 `G = (V_H ∪ V_L, E_dep ∪ E_feature)`。 - **[GitNexus](https://github.com/abhigyanpatwari/GitNexus)** —— 预计算关系智能、爆炸半径分析、Claude Code 钩子。表明代码图工具必须“隐形”才能成为必需品。 - **[Serena](https://github.com/oraios/serena)** —— 通过 LSP 实现符号级精度。证明了实时代码感知比批处理分析更重要。 - **[TOON](https://github.com/toon-format/toon)** —— 用于 LLM 优化的 Token 面向对象表示法。 这是一个独立实现。所有代码均为原创作品，采用 MIT 许可。不与微软关联，也不受其背书。 ## 许可证 [MIT](LICENSE)

标签：15种编程语言, 28种工具, AI编码助手, MCP, Rust, SEO: AI coding, SEO: codebase understanding, SEO: MCP server, SEO: Rust Tree-sitter, SEO: semantic graph, Tree-sitter, 代码库索引, 代码语义理解, 单次调用上下文, 可视化界面, 多语言支持, 安全测试框架, 文档结构分析, 树形分析, 网络流量审计, 自动同步编辑, 语义图, 通知系统