【rpi 进展】让 Rust Agent 更容易接入新模型：Provider 分层与插件扩展
内容提要
rpi 是 Rust 原生编码助手运行时，正在推进 Provider 分层：适配层负责供应商接入、凭据绑定与增量返回，Agent 专注工具循环、会话和取消。兼容 OpenAI 的网关可复用协议代码，但须保留独立 provider ID、模型目录、端点和凭据，避免误用官方 key。插件边界采用 C ABI 加 JSON，流式回调支持增量显示与取消。项目正征集兼容网关差异及私有认证等真实需求。
延伸解读
协议兼容不等于身份复用
文章强调，即使公司网关兼容 OpenAI 的 Chat Completions 协议，也不能因此自动使用官方的 OPENAI_API_KEY。每个网关应保留独立的 provider ID、模型目录、端点和凭据。这样做的好处是：协议修复可以共享，但切换服务时不会误用官方密钥，避免认证混淆和安全风险。
插件边界选择 C ABI + JSON 的权衡
rpi 的插件扩展采用 C ABI 函数指针和 JSON 信封，而不是直接传递 Rust trait object 或异步运行时对象。这允许插件不依赖宿主使用同一 Rust 编译器版本，但代价是插件与宿主同进程，需要处理内存所有权、动态库持有和退出时机，并且它不是安全沙箱。
流式与取消语义是接入重点
开发分支中的流式 Provider 通过回调交付 chunk，宿主将其转为事件流。文章特别关注：增量在结束前能被上层看到；一次请求只有一个终态；用户取消以 Aborted 结束，而不是再补一个成功完成。同步 FFI 调用放在 spawn_blocking 中，避免阻塞异步转发路径。
当前扩展能力的边界
文章说明，已有协议的新服务可通过 models.json 配置新身份，但插件的模型目录和认证声明还在收敛，暂时不能承诺任意新协议都能“装一个 package 就全部接好”。更特殊的请求签名、私有接口等需求，仍需沿 Provider 扩展方向接入，项目正在征集真实需求以确定边界。
Q&A
rpi 是什么？它主要用来做什么？
rpi 是 Rust 原生的 coding-agent runtime，也提供基于该运行时的终端编码助手。可以直接安装 CLI 使用，也可以把 rpi-agent 等 crate 嵌入自己的程序，自己掌控工具、事件和输出。
为什么接入兼容 OpenAI 的公司网关时不能直接用官方的 OPENAI_API_KEY？
因为协议兼容不代表身份相同。模型目录、服务端点和认证都属于网关自己的身份，即使复用请求编码和 SSE 解析代码，也要分别保留自己的 provider ID、模型目录、端点和凭据，避免误用官方 key。
rpi 的 Provider 分层是如何划分职责的？
适配层负责供应商接入、凭据绑定和增量返回；Agent 继续负责工具循环、会话和取消。这样接新服务时不需要修改 Agent 的执行逻辑。
rpi 的插件边界为什么选择 C ABI + JSON？
跨动态库直接传 Rust trait object、String 或异步运行时对象会把宿主和插件绑在不稳定的 Rust ABI 上。使用 C ABI 函数指针和 JSON 信封，字符串由分配它的一侧释放，允许插件不依赖宿主使用同一 Rust 编译器版本，但仍需遵守插件 ABI 和平台要求。
rpi 的流式 Provider 如何处理增量显示和取消？
流式 Provider 通过回调交付 chunk，宿主将其转成 Agent 和 TUI 消费的事件流。同步 FFI 调用放在 spawn_blocking 中避免阻塞异步转发。增量在结束前能被上层看到；一次请求只有一个终态；用户取消以 Aborted 结束，而不是再补一个成功完成。
目前 rpi 的 Provider 扩展有哪些限制？
插件的模型目录和认证声明还在收敛，暂时不能承诺任意新协议都能“装一个 package 就全部接好”。更特殊的请求签名、私有接口等需求可以沿 Provider 扩展方向接入，但需要进一步明确边界。
如何开始使用 rpi 或为其贡献需求？
可以通过 cargo install rpi-cli 安装 CLI，运行 rpi --help 查看帮助。项目仓库、官网和最小嵌入示例、插件示例均有链接。特别欢迎提交现有 OpenAI/Anthropic 兼容网关的差异、私有认证、模型目录、取消语义等真实需求，带接口差异或最小复现提 issue。
