Rpi

项目介绍Introduction

Rpi 是什么，从哪里来，能做什么。 What Rpi is, where it comes from, and what it can do.

Rpi 是一个运行在终端里的 AI 编程助手，用 Rust 编写。它可以读取你的代码、按你的要求修改文件、执行命令，并管理多轮会话——所有工作都在终端里完成，无需离开命令行。项目的设计源自 Pi（earendil-works/pi），并在此基础上独立演进。 Rpi is an AI coding assistant that lives in your terminal, written in Rust. It reads your code, edits files on request, runs commands, and manages multi-turn sessions — all without leaving the command line. The design originates from Pi (earendil-works/pi) and evolves independently from there.

主要特性Highlights

  • 单二进制：静态链接，无运行时依赖，拷贝即可运行。Single binary: statically linked, zero runtime dependencies, copy and run.
  • 完整终端界面：流式输出、语法高亮、斜杠命令、@ 文件引用、会话树。Complete terminal UI: streaming output, syntax highlighting, slash commands, @ file references, session tree.
  • 内置工具：读写文件、编辑代码、执行命令；长对话自动压缩上下文。Built-in tools: read/write files, edit code, run commands; automatic context compaction for long conversations.
  • 38 家模型服务商：OpenAI、Anthropic、DeepSeek、Kimi、Google、Bedrock 等开箱即用。38 model providers: OpenAI, Anthropic, DeepSeek, Kimi, Google, Bedrock and more, out of the box.
  • 插件系统：支持 WebAssembly 与原生动态库两种插件，可热重载。Plugin system: WebAssembly and native dynamic-library plugins, with hot reload.
  • 会话分享：导出 HTML 或生成分享链接。Session sharing: export to HTML or generate a share link.
  • 隐私可控：网络请求可逐项关闭，配置全部保存在本机 ~/.rpi。Privacy control: every network request can be disabled; all configuration stays in ~/.rpi.

许可证与致谢License & credits

Rpi 以 MIT 许可证开源，与上游项目 Pi 一致。感谢 earendil-works/pi 提供了设计原型。源码与 Issue 见 GitHub 仓库。 Rpi is open source under the MIT license, same as the upstream project Pi. Thanks to earendil-works/pi for the design it originates from. Source code and issues live in the GitHub repository.

快速开始Quickstart

从构建到第一次对话，大约三分钟。 From source to your first conversation in about three minutes.

1. 构建1. Build

需要安装 Rust 工具链。构建产物是单个可执行文件 target/release/rpi，可以拷贝到 PATH 中的任意位置。 You need the Rust toolchain. The build produces a single executable, target/release/rpi, which you can copy anywhere on your PATH. 

$ git clone https://github.com/zhuacloud/rpi.git
$ cd rpi
$ cargo build --release
$ ./target/release/rpi

2. 配置模型2. Configure a model

Rpi 内置了 38 家模型服务商的模型清单。大多数情况下只需要在 ~/.rpi/agent/models.json 里写入你的 API Key（以 DeepSeek 为例）： Rpi ships model catalogs for 38 providers. In most cases you only need to add your API key in ~/.rpi/agent/models.json (DeepSeek example): 

{"providers": {"deepseek": {
  "apiKey": "DEEPSEEK_API_KEY",
  "models": [{"id": "deepseek-v4-flash"}]}}}

apiKey 也可以直接写 Key 字符串；写环境变量名时会从环境读取。 apiKey accepts either a literal key or the name of an environment variable to read it from.

3. 三种运行模式3. Three run modes

命令Command 模式Mode 适用场景Use case
rpi 交互模式Interactive 日常使用：多轮对话、边聊边改代码Everyday work: multi-turn chat, edit as you go
rpi --print "..." 一次性问答One-shot 脚本集成：问一个问题，拿到答案就退出Scripting: ask one question, print the answer, exit
rpi --rpc RPC 给其他程序（编辑器、IDE）调用Driving Rpi from other programs (editors, IDEs)

4. （可选）关闭网络请求4. (Optional) Disable network requests

Rpi 默认会在线获取模型目录更新和新版本提示。如果不需要，可以用环境变量逐项关闭： By default Rpi fetches model catalog updates and new-version notices online. Each can be turned off individually: 

$ export RPI_MODEL_CATALOG_URL=off
$ export RPI_VERSION_CHECK_URL=off
$ export RPI_TELEMETRY_URL=off

全部设为 off 后，除你自己配置的模型服务商之外，Rpi 不发起任何网络请求。 With all three set to off, Rpi makes no network requests beyond the model providers you configured yourself.

更新记录Changelog

每个版本的变更记录。程序内的新版本提示也会链接到本页。 What changed in each release. The in-app update notice links here too.

0.1.0首个版本Initial release

  • 终端 AI 编程助手的完整功能：多轮对话、内置工具、会话管理。The complete terminal AI coding assistant: multi-turn chat, built-in tools, session management.
  • 交互 / 一次性问答 / RPC 三种运行模式。Three run modes: interactive, one-shot (--print) and RPC.
  • 内置 38 家模型服务商。38 built-in model providers.
  • 插件系统：WebAssembly 与原生动态库，支持热重载。Plugin system: WebAssembly and native dynamic libraries, with hot reload.
  • 会话导出 HTML 与链接分享。Session export to HTML and link sharing.

插件开发指南Plugin guide

用插件给 Rpi 增加新工具、新命令和新行为。 Extend Rpi with new tools, commands and behaviors.

两种插件形态Two plugin formats

形态Format 文件File 特点Characteristics
WebAssembly .wasm 在沙箱中运行，按声明的能力授权；可用任何能编译到 wasm32 的语言编写Runs in a sandbox with declared capabilities; write in any language that targets wasm32
原生动态库Native library .so / .dll / .dylib 性能最好，但无沙箱，拥有与 Rpi 进程相同的权限，只安装可信来源Best performance, but unsandboxed — same permissions as the Rpi process; install only from sources you trust

一个插件长什么样Anatomy of a plugin

一个插件就是一个目录，里面放一个清单元文件 rpi-extension.json 和插件本体： A plugin is a directory containing a manifest file, rpi-extension.json, plus the plugin binary: 

permission-gate/
├── rpi-extension.json   # 清单 / manifest
└── dist/
    └── permission_gate.wasm
{
  "name": "permission-gate",
  "version": "0.1.0",
  "description": "Block a tool + register a custom tool",
  "wasm": "dist/permission_gate.wasm",
  "capabilities": ["tools", "session"],
  "rpiAbi": 1
}

capabilities 声明插件需要的能力，未声明的能力在运行时会被拒绝。原生动态库插件把 wasm 字段换成 native。 capabilities declares what the plugin is allowed to do; anything undeclared is denied at runtime. Native plugins use a native field instead of wasm.

安装与重载Install & reload

把插件目录拷贝（或软链）到以下任一位置，Rpi 启动时会自动发现： Copy (or symlink) the plugin directory into either location below; Rpi discovers it at startup:

  • ~/.rpi/agent/extensions/<name>/ — 对所有项目生效applies to every project
  • .rpi/extensions/<name>/ — 仅当前项目生效applies to the current project only

修改插件后无需退出 Rpi，在会话里执行 /reload 即可热重载。 After changing a plugin, run /reload inside the session — no need to restart Rpi.

从示例开始Start from the example

仓库里的 examples/wasm-extension/ 是一个完整示例：拦截指定工具的调用，并注册一个自定义工具。构建并安装： The repository ships a complete example at examples/wasm-extension/: it intercepts calls to a specific tool and registers a custom one. Build and install it: 

$ rustup target add wasm32-unknown-unknown   # 一次性 / one-time
$ cd examples/wasm-extension
$ cargo build --target wasm32-unknown-unknown --release
$ mkdir -p dist
$ cp ../../target/wasm32-unknown-unknown/release/rpi_wasm_extension_example.wasm dist/permission_gate.wasm
$ cp -r ../wasm-extension ~/.rpi/agent/extensions/permission-gate

插件与宿主之间的完整通信规范（消息格式、能力列表、错误类型）见仓库中的 Extension ABI 文档。 The full contract between plugins and the host — message formats, capability list, error kinds — is documented in the Extension ABI document in the repository.