rpi 这些扩展到底怎么选？一张工具地图看懂 16 个 Rust 插件

rpi 已经有一批常见的原生 Rust 插件。数量上还没有成熟生态那么多，但任务规划、代码分析、网络访问、运行观测、消息渠道和语音交互等日常场景，基本都已经有对应能力可以使用。

如果只看包名，rpi-packages 很容易变成一张“功能名词表”：todo、goal、lens、MCP、Langfuse、voice……每个词都认识，真正要装哪个却不容易判断。

这篇文章先把目前已有的扩展整体展示出来，再按使用场景说明它们分别解决什么问题。你可以把它当成一张选型地图：先从任务找到需要的能力，再决定安装哪些包，而不是把整个扩展目录全部装上。后续如果你正在使用其他原生 Rust 插件，也欢迎补充。

先看全貌：扩展彼此独立，由宿主按需加载

这些扩展不是一条预先连好的流水线。每个包都以独立扩展的形式加载到 rpi 宿主中，是否安装、是否调用、是否和其他包组合，都由具体任务和宿主逻辑决定。

下面用表格展示这些独立扩展的能力分类。分类只用于帮助选型，不代表扩展之间存在调用关系：

表 1：扩展按使用场景分类。每个扩展可以独立安装；表中的分类不是运行时调用顺序。

这张表有一个容易忽略的边界：扩展不是一个统一的“大插件”。rpi-todo 保存会话内待办，rpi-goal 保存项目目标；rpi-permissions 给出权限判定，但仍需要宿主在工具执行前接入检查；rpi-subagents 生成委派描述，当前版本并不自动启动完整的子 Agent。

1. 任务规划：先决定做什么，再开始改文件

rpi-plan-mode：把“探索”和“执行”分开

复杂任务最怕一上来就改代码。rpi-plan-mode 提供 /plan 命令，也注册了 plan_mode_start 和 plan_mode_complete 工具。

进入计划模式后，活动工具会收紧到只读探索和完成计划。计划确认后，才恢复之前的工具集。它适合：

• 需要先阅读多个模块的仓库改动；
• 有几种实现方案，需要比较后再动手；
• 希望把计划保存到当前会话分支，并在恢复时继续使用。

它解决的是执行顺序和决策边界，不是项目管理系统。计划模式不会替你完成实现。

rpi-goal：记录一个持续目标

rpi-goal 面向的是“这一阶段要完成什么”，例如“完成插件发布前检查”。目标状态保存在项目的 .rpi/goals.json，支持开始、更新、暂停、恢复、完成和归档，也能设置最大轮数或最长时间。

/goal start 发布前完成所有扩展的兼容性检查
/goal limit 20 30m
/goal update --status "已完成构建，开始运行 smoke check"
/goal pause
/goal resume

goal 和 todo 不应互相替代：前者是持续目标，后者是目标下面的具体动作。

rpi-todo：跟踪当前会话的下一步

rpi-todo 管理当前会话分支里的任务清单，状态通过工具结果保存，并在恢复会话、分叉会话或切换分支时重建。

{
   "action":"add","text":"运行 cargo test --workspace"}
{
   "action":"update","id":1,"status":"in_progress"}
{
   "action":"update","id":1,"status":"completed"}

它有意不提供项目级 backlog、标签或外部 JSON 文件。因此，它更像 Agent 当前这轮工作的“白板”，而不是团队任务系统。

rpi-ask-user：遇到选择时停下来问人

当 Agent 面临“选 Linux 还是 Windows”“是否允许修改这个目录”“在两个方案中选哪个”时，可以用 rpi-ask-user 发起结构化提问。它支持选项、多选、自由输入、补充说明、超时和取消。

这个扩展依赖交互式 UI。没有交互式 UI 的宿主会返回明确错误：ask_user requires an interactive UI。所以它适合 TUI 工作流，不适合被误当成无界面的自动化输入接口。

2. 代码理解与检查：减少“全仓库塞进上下文”

rpi-codegraph：查询符号和调用关系

rpi-codegraph 不会每次请求都扫描整个工作区，而是连接本地 CodeGraph SQLite 索引，提供边界明确的查询：

• codegraph_search：搜索符号；
• codegraph_node：查看一个符号或源文件；
• codegraph_callers / codegraph_callees：查询调用者和被调用者；
• codegraph_impact：查询有限范围的影响面；
• codegraph_explore：按文件组织相关源码；
• codegraph_files：查看索引文件树；
• codegraph_status：检查索引状态。

使用前要安装外部 CodeGraph CLI，并在项目中执行初始化：

npm install -g @colbymchenry/codegraph
cd /path/to/project
codegraph init -i

它的价值在于回答“这个符号被谁调用”“改动可能影响哪里”，而不是替代普通的 read、grep 和 find。

rpi-lens：只执行允许的检查

rpi-lens 注册 code_lens，当前只允许四类检查：

git diff --check
cargo check
cargo fmt --check
cargo clippy -- -D warnings

每条命令都有最多 120 秒的超时，输出也有上限。这样做牺牲了任意命令的灵活性，换来更小的执行面和更可控的上下文大小。它适合改动后的快速体检，但不能代替项目自己的单元测试、集成测试和发布检查。

rpi-subagents：描述委派边界

rpi-subagents 的 delegate_task 会生成带有角色、轮次和超时限制的非递归委派描述。当前 rpi ABI 还没有暴露完整的子 Agent 启动动作，因此真正的调度仍由宿主负责。

这意味着它可以作为多 Agent 工作流的接口，却不是“安装后自动并行”的调度平台。阅读文档时，应该把“委派描述”和“子进程执行”分开理解。

3. 外部信息和服务：四个独立入口

这几个包都与“外部能力”有关，但职责并不相同。它们可以被同一个 Agent 分别调用，也可以只安装其中一个：

图 2：实线关系不存在；虚线表示宿主可以加载或组合，websearch 与 webfetch 也不是必须绑定安装。

rpi-websearch 与 rpi-webfetch：发现线索，再读取原文

rpi-websearch 使用无需 API key 的搜索来源，返回标题、URL、摘要、来源标签和结构化查询结果；在可用时还会补充 Wikipedia 结果。

rpi-webfetch 则负责获取公开 HTTP(S) 页面，并返回有大小限制的可读文本。它会拒绝私有地址、带凭据的 URL 和过大的响应，也会阻止解析到本地或私有地址范围的主机名。

两者最好组合使用：搜索只负责找到候选来源，抓取负责读取原文。搜索摘要不能自动等价于事实证据。

rpi-mcp-adapter：把 MCP 服务接进 rpi

这个扩展提供三个稳定工具：

正常使用优先走 mcp_list 和 mcp_call；mcp_request 是低层通道，不负责初始化。

例如，.rpi/mcp.json 可以配置一个 Playwright 服务：

{
   
  "mcpServers": {
   
    "playwright": {
   
      "command": "node",
      "args": ["server.js", "--extension"],
      "timeout": 60
    }
  }
}

MCP 适合“把外部工具服务纳入 Agent 工具循环”，不等于所有 HTTP API 都自动变成 MCP 服务。

rpi-server：让其他程序连接 rpi

rpi-server 提供 TCP JSONL / JSON-RPC、会话管理和事件流订阅。它更像 rpi 的服务集成层：其他客户端可以创建会话、发送任务并观察运行事件。

rpi --server
rpi --server --bind 127.0.0.1 --port 9800

它不是现成的图形界面，也不能仅凭命令名称就与其他远程模式互换。需要对接时，应先确认协议、端口、会话生命周期和认证边界。

4. 观测、安全和交互：让运行过程可见、可控、可追踪

rpi-run-stats：在终端里看当前运行指标

执行 /stats on 后，扩展会在 TUI 右上角打开一个监控面板，显示：轮次、Provider steps、输出 TPS、TTFT、响应时间、滚动 60 秒 TPM、输入/输出/cache token、错误数和美元成本。

/stats on
/stats
/stats position top-left
/stats off

面板使用宿主提供的通用声明式接口。宿主版本过旧时，插件可以收集数据，但不一定能显示面板；终端窄于 80 列时面板也会自动隐藏。

rpi-langfuse：把一次任务拆成可追踪的动作

rpi-langfuse 把 Agent 生命周期转换成 Langfuse 中的 trace 和 observation：

它可以自动记录 session、模型请求与响应、工具调用、turn、agent 和上下文压缩，也提供 langfuse_trace、langfuse_score 和 langfuse_prompt 工具。

当前 README 以 Langfuse v4 的 OTLP/HTTP JSON 传输为边界。使用时需要配置 Langfuse 地址和项目凭据；插件负责采集和上报，不会自动替代评估标准，也不会仅凭记录判断回答是否正确。

rpi-permissions：提供策略判定，而不是完整沙箱

rpi-permissions 读取项目级 .pi/permissions.json 或全局权限配置，支持 check、grant、revoke 和 list。规则按 Tool(pattern) 描述，拒绝规则优先；存在允许列表时，未匹配的调用会被拒绝。

它的边界很重要：插件返回策略判断，宿主仍需要在 before_tool_call 钩子中执行这个判断。安装插件本身不等于系统级权限隔离。

5. 把 Agent 带出终端：飞书和语音

仓库已经有真实的飞书运行截图，可以用来理解“入口换了，但执行环境仍然是运行 rpi 的工作区”这件事。

图 3：飞书消息进入 rpi Agent 后的实际回复。截图证明的是该次飞书场景中的显示结果，不代表其他扩展都有同样的界面。

rpi-im-message：接入飞书 / Lark 长连接

rpi-im-message 使用官方 Rust SDK 的 WebSocket 长连接，提供 start、status、list、receive、send 和 stop 等动作。发送内容支持普通文本、Markdown 富文本和交互卡片。

配置可以放在环境变量指定的文件、项目 .rpi/im.json 或全局 ~/.rpi/agent/im.json。应用密钥建议通过环境变量提供，不要提交进代码仓库。

开启 autoReply 后，飞书消息会交给当前 rpi Agent，工具调用过程可以单独反馈，最终回答再发回原会话。飞书应用仍需开启机器人能力、订阅消息事件并授予对应权限。

rpi-voice：给 TUI 增加听说能力

rpi-voice 不是另一个独立语音助手，而是加载进 rpi TUI 的扩展：

• /voice：录音、转写，并把结果放进输入框；
• /voice ptt：按住快捷键说话，松开后转写；
• /voice auto：连续对话；
• 自动 TTS：朗读 Agent 回复，默认关闭；
• Markdown 感知：朗读前去掉代码围栏、链接和强调标记；
• pet 模式：在支持通用面板的宿主中显示一个会说话的陪伴面板。

默认 STT 引擎是本地 SenseVoice；也可以切换到 OpenAI-compatible API。启用本地 STT 构建时，需要额外的 C++、cmake 和 libclang 构建环境，模型文件约 240 MB；“本地运行”不等于“构建过程没有依赖”。

当前包清单：按能力快速查找

catalog/packages.json 当前列出 15 个扩展；工作区另外包含 rpi-server。表中前 15 个包的版本来自本地 catalog，rpi-server 的版本来自其 Cargo.toml：

安装和验证：使用 rpi 安装扩展

这些扩展直接通过 rpi 按包名安装：

rpi install rpi-todo
rpi install rpi-codegraph
rpi install rpi-lens

也可以把命令中的包名替换为表格里的其他扩展。需要固定版本时，使用 --version：

rpi install rpi-todo --version 0.2.1

安装后重启 rpi，再确认对应的工具或命令是否已经注册。不同扩展的额外前置条件不同：

• CodeGraph 需要先建立项目索引；
• MCP 需要配置 MCP 服务；
• Langfuse 需要端点和凭据；
• 飞书需要应用权限和长连接配置；
• 语音需要音频设备以及 STT 条件；
• 交互式提问和运行面板需要宿主提供对应的 UI 能力。

安装成功只代表扩展可以被发现，不代表外部服务、权限策略或模型调用已经配置完成。

最后：怎么选，取决于你正在解决哪种问题

• 想让 Agent 先想清楚再改：rpi-plan-mode + rpi-ask-user；
• 想让 Agent 记住目标和当前步骤：rpi-goal + rpi-todo；
• 想让 Agent 读懂大型代码库：rpi-codegraph + rpi-lens；
• 想让 Agent 查资料并读取原文：rpi-websearch + rpi-webfetch；
• 想让 Agent 连接外部工具服务：rpi-mcp-adapter；
• 想知道 Agent 到底慢在哪里、错在哪里：rpi-run-stats + rpi-langfuse；
• 想把 Agent 接到协作消息里：rpi-im-message；
• 想减少键盘输入，或让回复 读出来：rpi-voice；
• 想让其他程序 远程驱动 rpi：rpi-server。

这套扩展的意义不在于数量最多，而在于已经把日常 Agent 工作流拆成了可以独立使用的能力：规划、探索、执行、观测和交互各自有边界。后续如果你发现还有值得补充的原生 Rust 插件，也欢迎继续补充这张清单。