项目介绍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 install to your first conversation in about three minutes.

1. 安装1. Install

一行命令安装预编译二进制，脚本会自动匹配你当前的平台： Install the prebuilt binary with one command — the script matches your current platform automatically:

# Linux（x86_64 / aarch64，glibc 与 musl 自动识别）
$ curl -fsSL https://revpi.dev/install.sh | sh

# macOS（Apple silicon）
$ curl -fsSL https://revpi.dev/install.sh | sh

# Windows（x86_64，PowerShell）
PS> irm https://revpi.dev/install.ps1 | iex

默认安装位置：Linux / macOS 为 ~/.local/bin（--prefix 可覆盖，需写入系统目录时脚本会提示用 sudo 重跑）；Windows 为 %LOCALAPPDATA%\Programs\rpi（-Prefix 可覆盖）。安装目录不在 PATH 时，脚本会打印对应的 PATH 配置提示。 Default locations: ~/.local/bin on Linux / macOS (override with --prefix; the script suggests re-running with sudo for system directories) and %LOCALAPPDATA%\Programs\rpi on Windows (-Prefix). When the install directory is not on your PATH, the script prints the exact line to add.

手动安装：从 GitHub Releases 下载对应平台的 rpi-<version>-<target>.tar.gz（Windows 为 .zip）与 .sha256 校验文件，核对校验和后解压到 PATH 中的任意目录。 Manual install: download rpi-<version>-<target>.tar.gz (.zip on Windows) and its .sha256 sidecar for your platform from GitHub Releases, verify the checksum, and unpack the binary anywhere on your PATH.

也可以从源码构建：需要安装 Rust 工具链。构建产物是单个可执行文件 target/release/rpi，可以拷贝到 PATH 中的任意位置。 You can also build from source: 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/revpidev/rpi.git
$ cd rpi
$ cargo build --release
$ ./target/release/rpi

2. 更新2. Update

一条命令自更新到最新版本；失败（如权限不足）时会给出 sudo 重跑或手动替换的具体指引： Self-update to the latest release with one command; on failure (e.g. permissions) it prints exact sudo / manual-replace guidance:

$ rpi update --self

重新运行安装脚本同样可以更新。Windows 上运行中的可执行文件无法被替换，请退出 rpi 后重新运行 install.ps1 或按提示手动替换。有新版本时交互模式启动横幅会提示 rpi update --self。 Re-running the install script updates an existing installation too. On Windows a running executable cannot replace itself — exit rpi and re-run install.ps1 (or follow the printed manual steps). The interactive-mode startup banner points at rpi update --self when a new version is available.

3. 卸载3. Uninstall

$ rpi self-uninstall           # 删除二进制与安装清单，保留 ~/.rpi 数据
$ rpi self-uninstall --purge   # 连同 ~/.rpi（会话、认证、设置）一起删除

默认保留 ~/.rpi 数据目录（交互式运行会先询问，非交互默认保留），卸载结束会打印遗留物清单。Windows 无法删除运行中的可执行文件，self-uninstall 会跳过并打印需要手动删除的准确路径（rpi.exe、rpi.install.json）。 The ~/.rpi data directory is kept by default (interactive runs ask first; non-interactive runs always keep), and the command prints a leftover list when done. Windows cannot delete a running executable, so self-uninstall skips it and prints the exact paths (rpi.exe, rpi.install.json) to remove by hand.

4. 配置模型4. 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.

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

6. （可选）关闭网络请求6. (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.

配置参考Configuration

所有配置项、默认值与作用位置。改动保存后重启 rpi 生效。 Every setting, its default, and where it lives. Restart rpi after editing.

配置文件Settings files

交互模式里执行 /settings 可在界面中直接修改常用项;类型写错的键会回退到默认值而不是报错。模型与 API Key 配置在 快速开始 一节。 Run /settings inside a session to edit the common items in the UI; a wrongly-typed value silently falls back to the default. Model and API-key setup lives in Quickstart.

请求超时与重试Timeouts & retry

最容易踩的一个设置:httpIdleTimeoutMs 名字里带 idle,实际是整个请求的总超时——从发起连接到流式响应读完为止,期间一直在正常收数据也会计时。默认 5 分钟;长思考档位(max 等)的深度推理模型单轮输出超过 5 分钟时,请求会在整 300 秒处被切断,表现为 error decoding response body。遇到这种情况把它调大: The one that bites most often: despite the name, httpIdleTimeoutMs is a total request timeout — it covers connecting through the last byte of a streamed response and keeps counting even while data flows. Default is 5 minutes; a deep-reasoning model on a high thinking level can exceed that in one turn, and the request is cut at exactly 300 s with error decoding response body. Raise it when that happens:

{
  "httpIdleTimeoutMs": 1800000
}

模型与会话Model & session

上下文管理Context management

界面显示Display

Shell 与编辑器Shell & editor

隐私与网络Privacy & network

rpi 默认只向三类官方端点发起非模型请求:模型目录更新、新版本检查、安装统计。三者都可以用设置键或同名环境变量指向自建地址,设为 off 整体禁用: Beyond your model providers, rpi contacts three house-keeping endpoints: model catalog refresh, version check, and install telemetry. Each can be pointed at a self-hosted URL via the setting or the matching env var, or disabled with off:

$ export RPI_MODEL_CATALOG_URL=off   # 禁用模型目录在线更新
$ export RPI_VERSION_CHECK_URL=off   # 禁用新版本检查
$ export RPI_TELEMETRY_URL=off       # 禁用安装统计上报
$ export RPI_REGISTRY_URL=off        # 禁用插件 registry(rpi install 退化为直连渠道)

扩展与包Extensions & packages

插件的安装与信任模型见 插件开发指南 与 rpi install --help。 For plugin installation and the trust model see the plugin guide and rpi install --help.

插件开发指南Plugin guide

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

两种插件形态Two plugin formats

一个插件长什么样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.