rpg-encoder

Name: rpg-encoder
Author: userFRM

本地服务

github.com/userFRM开发工具3128 周前更新

代码仓库

关于 rpg-encoder

rpg-encoder 是一个基于 Tree-sitter 的代码语义图工具，为 AI 编码 Agent 提供仓库级的代码理解能力。它不仅记录调用关系，还为每个函数提取意图级别的功能描述，并通过 MCP 工具以较少的调用次数返回结构化结果。

主要功能

01基于 Tree-sitter 提取实体与依赖关系
02为函数和类生成意图级功能描述
03将功能组织为三级语义层级
04通过语义快照概览整个仓库
05支持增量同步与影响范围分析

适用场景

01让 AI 助手按意图查找相关代码而非依赖 grep
02规划修改并分析变更的影响范围
03在大型仓库中快速理解模块职责与依赖

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "userfrm-rpg-encoder": {
      "command": "npx",
      "args": [
        "-y",
        "rpg-encoder"
      ]
    }
  }
}

启动命令npx -y rpg-encoder

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmrpg-encoder0.6.7stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

rpg-encoder

为你的 AI Agent 打造理解代码库的大脑。

AI 编码 Agent 大多会把工具调用浪费在用 grep、cat、find 和读取文件摸索代码库上。rpg-encoder 解决了这个问题。它借助 Tree-sitter 构建代码的语义图——不仅记录什么调用了什么，还描述每个函数的作用——并通过 MCP 让 AI 助手只需一次工具调用，就能理解整个代码库。

没有 RPG：34,000 次混乱的 grep/cat/find 调用。有了 RPG：一次 semantic_snapshot 调用即可返回整个代码库的结构化地图。

快速开始

claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server

只需一条命令。适用于 Claude Code、Cursor、opencode、Windsurf 或任何兼容 MCP 的 Agent。无需 Rust 工具链、无需克隆、无需构建——npx 会为你的平台下载预构建的二进制文件。

然后打开任意代码库并告诉你的 Agent：

“为这个代码库构建并提升 RPG”

你的 Agent 会处理所有事情：为实体建立索引（几秒钟），读取每个函数并添加意图级特征（几分钟），将它们组织成语义层级，并为团队提交 .rpg/graph.json。

对于约有 100 个或更多实体的代码库，lifting_status 会提示你的 Agent 将提升循环交给子 Agent 或成本更低的模型——特征提取是模式匹配，而不是创新推理。如果你的运行时不支持子 Agent 机制，可在终端中使用 API 密钥运行 rpg-encoder lift --provider anthropic|openai——CLI 会直接驱动外部大模型，无需 Agent 参与。CLI 完成后，在当前会话中调用 reload_rpg 以加载更新后的图。CLI 会提升尚无特征的实体；对于过时实体（已有特征，但代码更改后已过时）的重新提升，则由会话内的 MCP 流程处理，而非 CLI。

完成提升后，可以试试：

“什么代码负责身份验证？”——即使没有任何内容命名为“auth”，也能找到相关代码
“显示所有依赖数据库连接的内容”
“规划一个为 API 端点添加速率限制的变更”

优先使用 RPG，而不是 `grep`、`cat`、`find`

服务说明会告诉你的 Agent：对于任何有关代码结构或行为的问题，优先使用 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 或读取文件；不要用它们查询代码结构。

工作原理

四阶段流水线：解析（tree-sitter）→ 提取（动宾特征）→ 组织（三层层级）→ 理解（LLM 获取完整仓库知识）

解析 — Tree-sitter 从 15 种语言中提取实体（函数、类、方法）和依赖边（导入、调用、继承）。
提取 — LLM（你的 Agent，或 Haiku 这类低成本 API）读取每个实体，并写出动宾特征：“验证 JWT 令牌”、“将配置序列化到磁盘”。
组织 — 特征聚类成三层语义层级（领域 → 类别 → 子类别），依据的是代码的功能，而非文件树。
理解 — semantic_snapshot 将整个图压缩到约 25K 个令牌。你的 LLM 读取一次，就能了解整个仓库。

语义快照

整个仓库——约 500K 个令牌的源代码——压缩 20 倍，成为约 25K 个令牌的快照，其中包含层级、特征、依赖关系和热点

LLM 无需逐个搜索文件，只需调用一次 semantic_snapshot，即可获得：

层级 — 每个功能领域及其汇总特征
实体 — 按领域分组的每个函数、类、方法及其语义特征
依赖骨架 — 包含限定名称的精简调用图
热点 — 连接最多的 10 个实体（架构骨干）

约 25K 个令牌可覆盖约 1000 个实体。这只占 1M 上下文窗口的 2–3%——LLM 每次会话开始时就已了解你的仓库。

自维护图

Git HEAD 变更 → RPG Server 自动同步 → update_rpg 应用新增项/修改项/移除项 → 图始终保持最新，无需 Agent 操作

每当工作树发生变化（已提交、已暂存或未暂存），MCP 服务都会在响应下一个查询前自动重新同步。基于 (path, size, mtime) 生成的变更集哈希可确保同一文件反复保存时只触发一次同步，而空闲查询不会触发同步。还会检测还原操作：如果之前处于脏状态的文件恢复到 HEAD 状态，图也会随之还原。

两种提取方式

模式	命令	成本	由谁支付
Agent 提取	“构建并提取 RPG”	订阅令牌	你的 Claude Code / Cursor 订阅
自主提取	`auto_lift(provider="anthropic", api_key_env="ANTHROPIC_API_KEY")`	每 100 个实体约 $0.02	外部 API 密钥（Haiku、GPT-4o-mini、OpenRouter、Gemini）

auto_lift 会直接调用低成本的外部 LLM——你的编码订阅不会承担提取任务。使用 api_key_env 从环境变量读取密钥，避免密钥出现在工具调用记录中。

架构

你的代码库（15 种语言）→ RPG 引擎（5 个 Rust crate：parser、encoder、nav、lift、mcp）→ 通过 MCP Protocol 连接的客户端（Claude Code、Cursor、opencode）

七个 Rust crate，一个 MCP 服务二进制文件，一个 CLI 二进制文件：

Crate	作用
`rpg-core`	图类型（RPGraph、Entity、HierarchyNode）、存储、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`	一次调用即可理解整个代码仓库的语义（1000 个实体约需 25K 个 token）
`search_node`	按意图或关键词搜索实体（混合嵌入 + 词法评分）
`fetch_node`	获取实体元数据、源代码、依赖项和层级上下文
`explore_rpg`	遍历依赖图（上游、下游或两者）
`context_pack`	单次调用即可搜索 + 获取 + 探索，并设置 token 预算

规划与分析（7 个工具）

工具	描述
`impact_radius`	BFS 可达性分析——“哪些内容依赖 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`	获取实体源代码，供你的 Agent 分析
`submit_lift_results`	将 Agent 的语义特征提交回图中
`finalize_lifting`	汇总文件级特征，重建层级元数据
`get_files_for_synthesis`	获取文件级实体特征，以便进行整体综合
`submit_file_syntheses`	提交文件级整体摘要
`build_semantic_hierarchy`	获取领域发现和层级分配提示词
`submit_hierarchy`	将层级分配应用到图中
`get_routing_candidates`	获取需要语义路由的实体（已漂移或新提升的实体）
`submit_routing_decisions`	提交路由决策（层级路径或“保留”）

支持的语言

通过 Tree-sitter 支持 15 种语言：

语言	实体提取	依赖解析
Python	函数、类、方法	imports、调用、继承
Rust	函数、结构体、trait、impl 方法	use、调用、trait 实现
TypeScript	函数、类、方法、接口	imports、调用、继承
JavaScript	函数、类、方法	imports、调用、继承
Go	函数、结构体、方法、接口	imports、调用
Java	类、方法、接口	imports、调用、继承
C / C++	函数、类、方法、结构体	includes、调用、继承
C#	类、方法、接口	using、调用、继承
PHP	函数、类、方法	use、调用、继承
Ruby	类、方法、模块	require、调用、继承
Kotlin	函数、类、方法	imports、调用、继承
Swift	函数、类、结构体、协议	imports、调用、继承
Scala	函数、类、对象、trait	imports、调用、继承
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"]
    }
  }
}

服务会根据当前工作目录自动检测项目根目录，无需指定路径参数。

命令行

npm install -g rpg-encoder

# Build a graph
rpg-encoder build

# Query
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

# Autonomous lifting via API
rpg-encoder lift --provider anthropic --dry-run  # estimate cost
rpg-encoder lift --provider anthropic           # lift with Haiku (~$0.02/100 entities)

# Incremental update
rpg-encoder update

# Pre-commit hook (auto-updates graph on commit)
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。

文档

RPG 对比 — 与 GitNexus、Serena、Repomix 等工具的客观比较
论文实现忠实度 — 与研究论文逐算法对比
使用案例 — RPG 可实现功能的实际示例
更新日志 — 发布历史

灵感与参考

rpg-encoder 基于 RPG-Encoder 研究论文的理论框架构建，并借鉴了代码智能领域中各种工具的灵感进行原创扩展：

RPG-Encoder 论文（Luo 等人，2026，Microsoft Research）— 语义提升模型、三级层次结构构建、增量演化算法、形式化图模型 G = (V_H ∪ V_L, E_dep ∪ E_feature)。
GitNexus — 预计算关系智能、影响范围分析、Claude Code hooks。它表明，代码图工具只有做到无形，才能成为必不可少的工具。
Serena — 通过 LSP 实现符号级精度。它证明，实时代码感知比批量分析更重要。
TOON — 面向 LLM 优化输出的 Token-Oriented Object Notation。

这是一个独立实现。所有代码均为原创作品，并遵循 MIT 许可证。与 Microsoft 无关联，也未获得其认可。