如果你想拥有自己的 Agent，为什么值得从 rpi 开始

如果你只是想找一个好用的 coding agent，直接安装一个现成产品通常是最省事的选择。

但如果你要把 Agent 放进自己的产品、服务或开发工具里，问题就变了：你需要的可能不是一个只能通过命令行使用的工具，而是一套自己能够拥有和控制的 Agent runtime。

这正是 rpi 的定位。

rpi 不是一个更大的 CLI

rpi 的目标不是把所有功能都塞进一个终端程序，而是把 Agent 的核心运行时拆出来：

rpi-ai       消息、流式响应和 Provider 抽象
    ↓
rpi-agent    Agent loop、工具、事件、取消和队列
    ↓
rpi-tools   read / write / edit / bash 等工具
    ↓
rpi-harness session、JSONL 持久化、压缩和崩溃恢复
    ↓
rpi-cli     TUI、一次性命令、JSON 模式和插件加载

这不是简单的目录划分。它决定了你能不能在不启动完整 CLI 的情况下，把 Agent 嵌入自己的程序；能不能用一个假的 Provider 跑完测试；能不能替换执行环境，而不是让 Agent 直接依赖真实机器。

所以 rpi 的核心卖点不是“比其他 Agent 多几个功能”，而是：你可以把 Agent 当成自己的基础设施。

一次工具调用，为什么需要这么多层

假设用户让 Agent 修改一个配置文件。模型不会直接修改磁盘，它先返回一次工具调用：读取文件、判断内容、生成编辑，然后等待工具结果。

在 rpi 里，这条链路大致经过几个职责明确的层：

1. rpi-ai 负责把 Provider 的响应转换成统一的消息和流式事件。
2. rpi-agent 负责判断下一步是否是工具调用，并驱动 Agent loop。
3. rpi-tools 根据工具 schema 执行 read、edit 或 bash。
4. 执行结果作为下一轮消息返回给 Agent。
5. rpi-harness 负责把 session 状态和运行进度写入持久化记录。
6. rpi-tui 或调用方决定如何显示事件。

模型提出“请编辑这个文件”，不等于程序已经编辑了这个文件。真正执行动作的是工具层；真正决定这次运行能否恢复的是 harness；真正决定输出长什么样的是 TUI 或宿主程序。

这套分工的价值在于，换一个界面不会重写 Agent loop，换一个执行环境也不会重写 Provider。你可以把同一个 Agent 放在终端、服务端、测试程序或自己的桌面工具里运行。

第一项优势：启动快，内存小

Agent 工具经常被当成一次性命令，但实际使用中，等待启动、加载依赖和占用常驻内存都会不断累积。rpi 选择 Rust 原生实现，并把 CLI 做成 runtime 之上的轻量入口，带来的直接结果是：安装包小、启动路径短、运行时开销低。

项目 README 中的 release benchmark 来自 Windows 11、x86_64 和 rustc 1.97.1 环境：

这里的冷启动定义为“启动进程并让 Agent 回答第一条命令”，不包含模型请求耗时。rpi --version 和冷启动几乎相同，说明初始化本身没有成为明显的启动负担。

这对三类场景尤其有价值：

• 本地 CLI：输入命令后很快看到响应，不必为一次小任务等待完整运行时加载。
• 后台任务：Agent 常驻时占用更少内存，可以把资源留给代码仓库、编译器和模型客户端。
• 多 session：每个 session 的基础开销更小，更适合并行运行审查、测试和修改任务。

需要注意的是，这些是项目在特定机器和 release 配置下的公开 benchmark，不是所有操作系统和工作负载的保证。它们也没有测量模型延迟、工具循环吞吐或长时间 TUI 渲染成本。完整测试方法和原始数据见：https://github.com/bigfish1913/pi-rust/blob/main/docs/performance/benchmark-vs-pi.md。

第二项优势：安装路径短，上手不绕

rpi 的上手不要求先搭建 Node、Python 或一整套运行环境。最直接的方式是安装一个预编译二进制：

curl -fsSL https://raw.githubusercontent.com/bigfish1913/pi-rust/main/scripts/install.sh | sh

如果本机已经有 Rust，也可以直接从 crates.io 安装：

cargo install rpi-cli
rpi --version

安装完成后，最小使用路径只有几步：

export ANTHROPIC_API_KEY=...
rpi

或者直接执行一次任务：

rpi -p "summarize the README"

需要脚本消费事件时，再切换到 JSON 模式：

rpi --mode json -p "list the crates"

这种设计让“先用起来”和“深入定制”是两条渐进路径：普通用户从一个二进制和一个命令开始；需要嵌入的开发者再使用 rpi-agent、rpi-ai 和 rpi-tools；需要扩展能力的团队再引入插件 SDK。你不必一开始就理解所有 crate，也不必先搭建完整开发环境。

第三项优势：它首先是一套库

许多 coding agent 的入口是 CLI。它们当然也有内部模块，但外部使用方式通常仍是启动一个进程，再通过标准输入输出与它交互。

rpi 把入口反过来了：CLI 是 runtime 之上的一个产品表面。

项目 README 给出了三种使用方式：

这会影响很多工程决策。比如，你要做一个内部代码审查服务，不必启动一个 TUI；要给现有编辑器增加 Agent 能力，不必解析 CLI 的输出文本；要在测试中验证工具调用，也不必真的连接线上模型。

let provider = FauxProvider::new(
    FauxScript::new().with_text("Hello from the faux provider!")
);

let agent = AgentBuilder::new()
    .model(provider.default_model().clone())
    .system_prompt("You are a helpful assistant.")
    .stream_fn(make_stream_fn(provider))
    .build()?;

agent.prompt("hi").await?;

这段代码的重点不是 API 长什么样，而是它可以在一个普通 Rust 进程里完成一次 Agent 运行。Agent 不需要通过 shell 启动另一个程序，宿主也不需要从终端输出中猜测发生了什么。

第四项优势：插件边界是可以单独审查的

rpi 没有把插件设计成“把内部 Rust 类型公开出去”。rpi-plugin-sdk 是一个独立的 leaf crate，不依赖其他 rpi-* crate，使用 #[repr(C)] 的 ABI 数据结构、版本协商和边界上的错误处理。

这意味着插件和宿主之间交换的是明确的契约，而不是宿主内部某个不断变化的 Rust 模块。

宿主 rpi
  → 加载 cdylib 插件
  → 协商 ABI 版本
  → 通过 C ABI 注册工具
  → 在边界内传递 JSON 和结果

插件 SDK 的价值不在于“今天能不能再加一个工具”。真正的价值是：第三方扩展不必了解 Agent loop 的内部实现，也不必和整个 workspace 绑定在一起。

rpi-extensions 再负责 host 侧的插件加载和异步工具桥接。这样，插件协议和宿主实现之间有一层可以独立讨论、测试和审查的边界。

这让 rpi 的扩展不会全部堆进核心二进制，也让工具和 Provider 能够按项目需要逐步加入。

rpi 的边界与下一步

介绍 rpi 的优势，不等于假装它已经解决了所有 Agent 产品问题。

当前 rpi 仍有继续发展的方向：

• Provider 和 OAuth 集成还可以继续扩展
• 多 Agent 协作和 worker 调度仍有发展空间
• 语义记忆、历史 session 搜索和自动记忆整理还可以独立增强
• TUI 还可以继续完善 session 管理、任务面板和信息展示
• Browser、Side panel、Mermaid 和 PDF 等能力可以按实际场景逐步加入

这些并不是 rpi 作为 runtime 的缺陷。恰恰相反，把这些能力放在 runtime 之外逐步扩展，能避免核心 Agent loop 被某一种 UI、Provider 或记忆实现绑死。

rpi 的优先级应该是先保证核心运行时的边界、可测试性和恢复语义，再把产品能力作为可替换的上层逐步补齐。

谁应该选择 rpi

如果你的目标是下面这些事情，rpi 值得作为起点：

• 给自己的 Rust 服务嵌入 Agent
• 构建内部代码助手，而不是把 Agent 当成黑盒命令
• 需要低启动延迟和低常驻内存的本地工具
• 希望用一个二进制快速安装并开始使用
• 需要控制工具执行环境和权限边界
• 计划让多个团队通过插件扩展工具和 Provider
• 希望 CLI、后台服务和 SDK 使用同一套 Agent 实现

rpi 当前最适合两类使用方式：一类是直接使用它提供的终端 CLI，另一类是把核心 crate 嵌入自己的程序。无论选择哪一种，底层都是同一套 Agent loop、工具协议和 session 能力。

如果你不想把 Agent 当成一个必须通过命令行驱动的黑盒，而是希望知道它如何运行、如何恢复、如何执行工具、如何被扩展，那么 rpi 的价值就很明确：

它不承诺替你做完所有产品决策，而是给你一套能够真正接管这些决策的运行时。

项目源码与文档：

• 代码仓库：https://github.com/bigfish1913/pi-rust
• 项目文档：https://rpi.laofu.online/docs.html