代码在开发机上，模型和工具也已经配好了。如果只是想换一台电脑看看任务进度，或者用手机翻一下刚才的修改，是否还需要把整套环境重新装一遍？

这篇介绍一下 pi-rust 生态里的 rpi-web。它给原生 rpi 编程助手提供了一个浏览器工作区：打开项目，选择会话，看模型回复，也看它调用了哪些工具、读了什么文件、执行了什么命令。

先看实际界面。对话里既有 Markdown 回答，也有可以展开的工具卡片，输入区则保留了模型、思考深度和上下文用量等入口。

图 1：真实开发工作区里的已有会话，本地路径和自定义模型信息已遮挡。图中测试数字属于历史回答，不是本文重新执行的测试。

下面的截图来自开发部署，其中包含尚需新版前后端配合的功能。安装部分会单独标明可用版本，不把开发界面当作所有已发布版本的能力承诺。

三个名字，先分清各自做什么

第一次接触这个项目，容易被几个名字绕住：

• pi-rust 是 Rust 实现的 Agent 项目，提供模型调用、工具执行和会话等能力。
• rpi 是其中可以直接运行的命令行程序，也是 Web 工作区背后的原生宿主。
• rpi-package 是扩展与相关组件的仓库，本文的 rpi-web 就在它的 packages/rpi-web 目录里。

打开网页以后，真正读写文件、执行命令和调用模型的，仍然是服务端的 rpi。浏览器负责显示与交互。

这个分工决定了它的使用方式：服务跑在自己的电脑上，就操作这台电脑的项目；服务跑在服务器上，就操作服务器上的项目。手机打开页面后，并不会自动获得手机里的文件，也不需要在手机上安装 Rust 工具链。

对 Rust 社区的朋友补充一点实现背景：后端使用 Rust 和 Axum，浏览器前端是 React/Vite。发行版把构建好的前端资源打包进扩展或可执行程序，日常使用不用再启动一个 Node.js 服务。

项目地址：https://github.com/pi-rust/rpi-package。

先选项目，再开始一段对话

rpi-web 的左侧按项目组织会话。同一个仓库里的代码阅读、问题排查、修改尝试，可以放在不同会话里，不必挤进一条越来越长的聊天记录。

图 2：只截取一个项目的会话分组。项目决定工作目录，会话用于区分任务上下文。

新建会话时，后端会以所选项目为工作目录，启动独立的 rpi --mode rpc 子进程。这里的 RPC 可以理解为 Web 服务与原生 Agent 之间的命令、事件通道，浏览器不直接执行这些工具。

不过，独立会话不等于独立文件副本。两个会话如果指向同一个项目，仍可能修改同一批文件。需要同时尝试互相冲突的方案时，应先准备独立工作目录或 Git worktree，而不是只点两次“新建会话”。

第一次试用，我建议先发一个范围很小的只读请求：

读取 README.md 和 Cargo.toml，说明这个项目的入口在哪里，
以及应该怎样运行测试。先不要修改文件，也不要执行测试。

这是建议读者尝试的输入，不是上面截图的原始问题。先做这一步，可以确认项目目录是否选对、模型能否调用读取工具，再决定要不要让它修改代码。

回答之外，还能看到它具体做了什么

编程助手说“已经处理好了”，接下来最需要确认的是：它到底动了哪里？

工具调用在对话里显示为卡片。平时可以收起长输出，需要核对时再展开，查看调用参数、命令和结果。read、bash、edit 这些原生工具名默认直接显示，方便把一段回答与它之前的动作对起来。

例如，读项目时可以核对它实际读取的路径；执行测试时可以打开命令和输出；涉及代码修改时，再看文件与 Git 差异。这样就不用仅凭最后一句总结判断任务是否完成。

右上角的文件按钮可以打开项目面板。下面是直接预览仓库 Cargo.toml 的效果：

图 3：文件树和带行号的只读预览。文件面板用于查看；Agent 是否能修改项目，由它启用的工具和权限决定。

这个面板不等于一个完整的在线 IDE。它更适合在对话旁边核对文件内容、查看 Git 变更，减少来回切换窗口。Agent 的写入工具会直接修改项目文件，并不等待在预览面板里点“接受”。修改产生后，先核对 diff，再运行项目自己的测试，最后决定是否提交；一句“完成”不能代替这些检查。

从侧栏底部打开“运行时设置”，可以选择模型、调整思考深度、查看上下文占用和启用的工具。遇到“为什么这次没用某个工具”时，可以先检查它是否出现在列表里、是否已经启用。

图 4：当前实例的运行时设置，自定义模型名称已遮挡。工具列表取决于宿主配置和已安装扩展，不是安装 Web 后就自动获得图中的全部工具。

如果页面能打开，但模型请求失败，先检查服务进程的模型凭据和所选模型。浏览器能登录，只能说明工作区访问成功，不代表模型服务已经授权。

对话长了，怎么回到前面那一步？

长任务里经常需要回看前面提出的要求，或者确认某一轮到底执行了哪些动作。开发版在对话左侧加了一条很窄的问题时间线：沿着问题刻度，可以定位到相应的对话位置。需要查看尚未加载的历史时，会在正文里打开只读历史窗口，再通过“回到最新消息”返回当前对话。

另一个入口是工具栏里的“执行轨迹”。它把已加载的消息和已观测事件整理成调用树与时间轴，选中一步后，再看对应的输入、输出或状态。

图 5：已有会话的执行轨迹，执行标识已遮挡。图里的“未知”和“起点未知”保留原样，不能据此补出完整执行顺序。

这个面板没有连接外部 Langfuse 服务，也不是完整的模型 API 请求日志。它整理的是当前工作区已经拿到的信息。没记录到的耗时、没加载的历史，不会因为打开面板就全部补齐。

它可以帮助找到已有记录里耗时较长的步骤。不过，一个轮次的总耗时不等于模型接口延迟，各工具耗时也不能简单相加当成整轮耗时。截图里的虚线明确提示“只有耗时，起点未知”，没有补画出未经记录的执行顺序。

这些历史查询和轨迹展示需要匹配的 Web、后端与原生宿主。升级时要一起核对版本，不能只替换浏览器静态文件。

跑起来：从原生扩展开始

如果已经在用 rpi，可以直接把 Web 装成一个扩展；还没安装宿主的话，先从 pi-rust 的发行页选择对应平台的程序，并确认 rpi --version 能正常输出。

宿主下载：https://github.com/bigfish1913/pi-rust/releases。

本文在 Windows 上使用 rpi 0.15.0 + rpi-web 0.1.27，实际检查了扩展安装、服务启动、首页访问和空会话创建；没有在这个隔离环境里发起真实模型请求。

为什么固定 Web 版本？截至 2026 年 11 月 1 日核查时，仓库里的 0.1.28、0.1.29 发布条目还没有预编译附件，0.1.27 的附件齐全。下面先用这个版本完成上手，前面展示的开发版新功能不都包含在其中。

rpi install rpi-web --github pi-rust/rpi-package --version 0.1.27

接着进入希望操作的项目目录。启动前，先让这个终端里的 rpi 能找到模型凭据。已有 CLI 配置可以沿用；第一次配置时，下面以 Anthropic 环境变量为例。

Linux / macOS：

export ANTHROPIC_API_KEY='替换为你自己的 API key'

Windows / PowerShell：

$env:ANTHROPIC_API_KEY = '替换为你自己的 API key'

模型服务和调用额度需要自行准备。使用其他模型服务时，按宿主文档配置对应的提供商或网关。API key 不要写进准备提交到 Git 的文件里。

然后在项目目录执行：

rpi --webserver=init
rpi --webserver

第一条创建项目的 .rpi/web.json，不会覆盖已有配置。默认内容很短：

{
  "project": "..",
  "rpiBin": "rpi",
  "port": 3030
}

project 相对于配置文件所在目录解析，所以 .rpi/web.json 里的 .. 正好指向项目根目录。

第二条启动服务。终端显示 Running 后，打开 http://127.0.0.1:3030/，选择项目、新建会话，再试试前面的只读请求。保持终端运行，按 Ctrl+C 才会停止服务。端口被占用时，可以临时改成 rpi --webserver --port 3031。

发行扩展已经包含前端，不需要另外运行 npm install。如果启动后仍进入终端聊天，先检查 Web 扩展是否安装到当前用户使用的扩展目录；--webserver 是 Web 0.1.7 起提供的首选入口，旧资料里的 --web 仍作为兼容别名保留。

也可以选择独立程序 rpi-web。它与扩展共用 Web 实现，但仍需要能启动 rpi 宿主。例如从解压后的发行目录运行：

./rpi-web --project /path/to/project --rpi-bin /path/to/rpi --assets ./assets --port 3030

Windows 下对应 rpi-web.exe 和 rpi.exe，路径换成自己的实际位置即可。下载独立版时选择带 standalone 的归档，并保留完整的 assets/ 目录，别和扩展动态库包混淆。

Web 发行页：https://github.com/pi-rust/rpi-package/releases?q=rpi-web-v。

放到开发机上，再从手机打开

当本机已经能完成一次对话，再考虑远程访问会更容易排查问题。手机端延续了相同的对话和工具卡片，侧栏、面板会按窄屏布局收起。

图 6：浏览器以 390px 宽度截取的实际页面，不是实体手机性能测试；本地路径和自定义模型信息已遮挡。

默认服务只监听 127.0.0.1，其他设备访问不到。局域网使用至少要把三件事分别配好：监听地址、允许的访问 Host、工作区密码。

例如，在 Linux / macOS 的服务端终端中，用实际局域网 IP 替换下面的 192.168.1.10：

export RPI_WEB_PASSWORD='替换为足够长的访问密码'
export RPI_WEB_ALLOWED_HOSTS='192.168.1.10:3030,127.0.0.1:3030,localhost:3030'
rpi --webserver --bind 0.0.0.0 --port 3030

这样才是在对外监听，并允许相应的 Host。RPI_WEB_ALLOWED_HOSTS 填的是主机名或 IP 加端口，不要填 http://、路径或末尾斜杠。如果仍连不上，再检查端口和防火墙，而不是反复更换模型 API key。

通过公网域名访问，还要把该域名加入允许列表，在前面配置 HTTPS 反向代理。代理需保留浏览器的 Host，设置 X-Forwarded-Proto: https，并关闭流式响应缓冲，否则可能出现访问被拒绝或回复攒到一起才显示。环境变量在启动时读取，修改后需要重启；程序不会自动读取 .env 文件。

工作区密码和模型 API key 是两回事。 前者决定谁能进入工作区，后者用于调用模型。当前访问保护使用共享密码，访客共享服务的项目与会话，不是每个人登录后都有独立空间。

所以，更合适的起点是自己的开发机或受控服务器。不要把它当成可以直接开放给陌生人的多租户平台；项目分组也不是工具执行的安全沙箱。公网部署前，先限制服务账号的文件权限和可用工具，再决定谁可以进入。

长期使用还需要保留数据：项目代码仍在项目目录，原生会话记录由宿主保存，Web 的 registry 保存会话索引与组织信息。只备份一个索引文件，不能替代对话记录；容器重建时，也要保留服务用户的模型配置和扩展目录。

停止 Web 服务会清理会话子进程。重启后可以重新打开已保存的会话，但不能据此假定停止前的任务会自动接着执行。

可以从一个现有项目试起

如果已经有一个能工作的 rpi 项目，可以先只加 Web 入口：读一遍 README，展开工具卡片核对路径，再打开文件面板看内容。确认这条路径跑通后，再尝试修改和测试，最后才是远程部署。

如果希望保留自己的模型配置、扩展和项目目录，又需要从浏览器查看工具过程，rpi-web 可以提供这个入口。需要在网页里完整编辑、调试代码，或给不同用户分配隔离空间，则不能只靠当前的 Web 工作区。

想继续看配置与实现，可从使用指南进入：https://github.com/pi-rust/rpi-package/blob/ed9ea3e506d6ad08fc73d63cdd245ad0d5fb5b1f/packages/rpi-web/README.md。这是本文核查的源码版本，开发截图与后续发行版可能存在差异。

也欢迎 Rust 社区的朋友试用、提 issue，或者一起补充扩展和界面能力。

• rpi-package：https://github.com/pi-rust/rpi-package
• pi-rust：https://github.com/bigfish1913/pi-rust
• 🏠 官网与文档：https://rpi.bigfisharc.cn/
• ✍️ 个人博客：https://blog.bigfisharc.cn/