【rpi 更新 远程模式】 服务端 + 客户端模式
内容提要
rpi 新增远程模式：agent 在服务端无头运行，客户端仅作终端界面，不加载 provider、工具或 session。服务端启动时打印 token，客户端通过 --token 或环境变量认证，认证为连接级。协议分层清晰，客户端零本地资源，支持流式渲染和斜杠命令，但会话树类命令不可用。项目已开源。
延伸解读
远程模式的核心：客户端零本地资源
rpi 的远程模式将 agent 完全放在服务端运行，客户端仅作为终端界面，不加载 provider、工具、扩展或创建 session 文件。这意味着客户端无需任何本地 agent 资源，所有计算和状态都在服务端。这种设计适合算力在服务器、需要多前端连接同一会话，或在无头 CI/沙箱中驱动 agent 的场景。
Token 认证：连接级安全与灵活传递
服务端默认启用 token 认证，启动时打印随机 token，也可通过 --token 指定或 --no-token 关闭（仅限可信本地环境）。客户端可用 --token 参数或 RPI_SERVER_TOKEN 环境变量传递，后者避免 token 写入命令历史。认证是连接级的，连接后必须先 authenticate，否则其他请求会被拒绝，错误码统一为 -32001。
协议分层：清晰职责与线协议稳定
rpi 远程层参考 pi 的分层思想，但完全用 Rust 实现。协议定义在 protocol.rs 中，服务端与客户端共用，确保线协议不会两端漂移。无头 agent 循环、服务端适配、客户端连接、会话模型和 TUI 各司其职。--connect 在 CLI 入口最早被拦截，直接跳过本地 provider、harness、session 和 extension 的构建，实现客户端零本地资源。
远程 TUI 的能力与限制
远程 TUI 支持流式渲染回复、思考过程和工具调用，并提供斜杠命令如 /abort、/state、/model、/thinking、/tools、/exit 等。但会话树类命令（/tree、/fork、/switch、/export、/name、/reload）在远程模式下明确不可用，因为它们依赖本地 harness 状态。这种设计避免了在远程模式下假装支持本地功能，保持了行为的一致性。
Q&A
rpi 的远程模式是什么？
rpi 新增的远程模式让 agent 在服务端无头运行，客户端仅作为纯输入/显示的终端界面，不加载 provider、工具、扩展或创建 session 文件，所有 agent 资源都在服务端。
如何启动 rpi 服务端并连接客户端？
服务端启动命令：rpi --server --port 9899，启动时会打印 token。客户端连接命令：rpi --connect 127.0.0.1:9899 --token <token>，token 也可通过环境变量 RPI_SERVER_TOKEN 传递。
rpi 远程模式的 token 认证是如何工作的？
服务端默认启用 token 认证，启动时打印 token。客户端可通过 --token 参数或环境变量 RPI_SERVER_TOKEN 传递 token，--token 优先。认证是连接级的，连接建立后必须先 authenticate，否则其他请求（包括 subscribe）会被拒绝，错误码为 -32001。
远程模式下客户端支持哪些斜杠命令？
支持 /abort（中断当前运行）、/state（刷新 model/thinking/工具）、/model <id>（切换模型）、/thinking <level>（设置思考级别）、/tools（查看当前启用的工具）、/exit（退出）。Ctrl+C 在运行中为中断，空闲时为退出。
为什么远程模式下会话树类命令不可用？
会话树类命令（/tree、/fork、/switch、/export、/name、/reload）依赖本地 harness 状态，而远程模式下客户端不加载本地 harness，因此这些命令会明确提示不可用，不应假装可用。
rpi 远程模式的架构分层是怎样的？
分层包括：协议层（crates/pi-cli/src/remote/protocol.rs，定义 RemoteEvent/RemoteCommand/RemoteResponse）、无头 agent 循环（crates/pi-cli/src/modes.rs）、服务端适配（rpi-package/packages/rpi-server，处理 TCP JSON-RPC 等）、客户端连接（crates/pi-cli/src/remote/client.rs）、客户端会话模型（crates/pi-cli/src/remote/session.rs）和客户端 TUI（crates/pi-cli/src/remote/tui.rs）。
rpi 远程模式适用于哪些场景？
适用于：算力在服务器上（agent 需要跑在装有代码、凭据、工具链的机器上，本地只敲键盘）；一个服务端多个前端（多个客户端连同一个 agent 会话）；无头 CI/沙箱（先起无头 agent，再用脚本或 UI 驱动）。
