【RPI 项目】如果你想拥有自己的 Agent，为什么值得从 rpi 开始（一个Rust 版本Pi）
内容提要
rpi 是一套可嵌入自有程序的 Rust Agent 运行时，将 AI、Agent 循环、工具、会话持久化和 CLI 分层解耦。其优势是启动快、内存低、安装简单、以库为核心，并通过独立插件 SDK 提供可审查的扩展边界，适合在 Rust 服务中嵌入 Agent 或直接使用其终端 CLI。
延伸解读
分层架构的实际意义
rpi 将 Agent 运行时拆分为 rpi-ai、rpi-agent、rpi-tools、rpi-harness 和 rpi-cli 等独立层，每层职责明确。这种设计让开发者能在不启动完整 CLI 的情况下嵌入 Agent，用假 Provider 测试，或替换执行环境。例如，修改配置文件时，模型只提出工具调用，实际执行由工具层完成，而会话恢复由 harness 负责。这种解耦意味着更换界面或执行环境不会重写核心逻辑，提升了灵活性和可测试性。
性能优势的适用场景
根据项目在 Windows 11 上的 benchmark，rpi 的冷启动约 17.7 毫秒，Agent ready 后内存占用约 12.0 MiB，release 二进制约 21.8 MiB。这些数据表明其启动快、内存低，适合本地 CLI、后台常驻任务和多 session 并行场景。但需注意，这些是特定环境下的测试结果，未涵盖模型延迟、工具循环吞吐或长时间 TUI 渲染成本，实际表现可能因操作系统和工作负载而异。
插件扩展的安全边界
rpi-plugin-sdk 是一个独立的 leaf crate，不依赖其他 rpi-* crate，通过 #[repr(C)] ABI、版本协商和边界错误处理来定义插件与宿主的契约。这意味着第三方扩展无需了解 Agent loop 内部实现，也不必与整个 workspace 绑定。宿主加载 cdylib 插件后，通过 C ABI 注册工具并传递 JSON 数据。这种设计让扩展边界可独立审查和测试，避免了核心二进制膨胀，同时允许工具和 Provider 按需逐步加入。
当前局限与未来方向
rpi 目前仍在发展中，Provider 和 OAuth 集成、多 Agent 协作、语义记忆、历史 session 搜索、TUI 完善以及 Browser、Side panel 等能力都有待增强。但这些并非 runtime 的缺陷，而是有意将产品能力放在核心之外，避免 Agent loop 被特定 UI、Provider 或记忆实现绑死。项目优先保证核心运行时的边界、可测试性和恢复语义，再逐步补齐上层功能。因此，rpi 适合需要嵌入 Agent 的 Rust 服务、内部代码助手或低延迟本地工具等场景。
Q&A
rpi 是什么？它和普通的 coding agent 有什么区别？
rpi 是一套可嵌入自有程序的 Rust Agent 运行时，将 AI、Agent 循环、工具、会话持久化和 CLI 分层解耦。与普通 coding agent 不同，rpi 的目标不是把所有功能塞进一个终端程序，而是把 Agent 的核心运行时拆出来，让你可以把 Agent 当成自己的基础设施，嵌入到自己的产品、服务或开发工具中。
rpi 的架构分层是怎样的？各层负责什么？
rpi 分为五层：rpi-ai 负责消息、流式响应和 Provider 抽象；rpi-agent 负责 Agent loop、工具、事件、取消和队列；rpi-tools 提供 read/write/edit/bash 等工具；rpi-harness 负责 session、JSONL 持久化、压缩和崩溃恢复；rpi-cli 提供 TUI、一次性命令、JSON 模式和插件加载。这种分层决定了你可以不启动完整 CLI 就把 Agent 嵌入自己的程序。
rpi 在性能和资源占用方面有什么优势？
rpi 采用 Rust 原生实现，CLI 是 runtime 之上的轻量入口，因此安装包小、启动路径短、运行时开销低。根据项目 README 的 release benchmark（Windows 11、x86_64、rustc 1.97.1），rpi --version 中位数为 17.5 ms，冷启动为 17.7 ms，Agent ready 后 RSS 为 12.0 MiB，release 二进制为 21.8 MiB。这些优势对本地 CLI、后台任务和多 session 场景尤其有价值。
如何安装和快速开始使用 rpi？
可以通过预编译二进制安装：curl -fsSL https://raw.githubusercontent.com/bigfish1913/pi-rust/main/scripts/install.sh | sh；如果本机已有 Rust，也可以使用 cargo install rpi-cli。安装后，设置 ANTHROPIC_API_KEY 环境变量，然后运行 rpi 进入交互模式，或使用 rpi -p "summarize the README" 执行一次性任务，需要脚本消费事件时可切换到 JSON 模式：rpi --mode json -p "list the crates"。
rpi 的插件机制有什么特点？为什么说插件边界可以单独审查？
rpi 的插件机制基于独立的 rpi-plugin-sdk，它是一个 leaf crate，不依赖其他 rpi-* crate，使用 #[repr(C)] 的 ABI 数据结构、版本协商和边界上的错误处理。插件和宿主之间交换的是明确的契约，而不是宿主内部不断变化的 Rust 模块。宿主加载 cdylib 插件，协商 ABI 版本，通过 C ABI 注册工具，并在边界内传递 JSON 和结果。这样第三方扩展不必了解 Agent loop 的内部实现，也不必和整个 workspace 绑定，插件协议和宿主实现之间有一层可以独立讨论、测试和审查的边界。
rpi 目前有哪些局限性或未来发展方向？
rpi 当前仍有继续发展的方向：Provider 和 OAuth 集成还可以继续扩展；多 Agent 协作和 worker 调度仍有发展空间；语义记忆、历史 session 搜索和自动记忆整理还可以独立增强；TUI 还可以继续完善 session 管理、任务面板和信息展示；Browser、Side panel、Mermaid 和 PDF 等能力可以按实际场景逐步加入。这些并不是 rpi 作为 runtime 的缺陷，而是把能力放在 runtime 之外逐步扩展，避免核心 Agent loop 被某一种 UI、Provider 或记忆实现绑死。
哪些场景适合使用 rpi？
rpi 适合以下场景：给自己的 Rust 服务嵌入 Agent；构建内部代码助手，而不是把 Agent 当成黑盒命令；需要低启动延迟和低常驻内存的本地工具；希望用一个二进制快速安装并开始使用；需要控制工具执行环境和权限边界；计划让多个团队通过插件扩展工具和 Provider；希望 CLI、后台服务和 SDK 使用同一套 Agent 实现。当前最适合两类使用方式：直接使用终端 CLI，或把核心 crate 嵌入自己的程序。
