pi-web：把 Pi Coding Agent 的会话留在真实工作区里
Pi Coding Agent 的 Web UI，使会话在真实工作空间中保持活动状态。
秒懂
- 它是什么？
- pi-web 是一个面向 Pi Coding Agent 的 Web 界面，它让代理会话在浏览器断开后依然存活，并允许你从任意设备监督运行在真实仓库和 git worktree 中的任务。本文基于 README 和项目结构，分析其核心模型、远程优先的设计、安全边界，以及适合谁使用。
- 适合谁用？
- pi-web 适合那些已经使用 Pi Coding Agent，并且希望把代理任务从本地终端搬到常驻服务器或开发机上的人。它解决了一个真实痛点：浏览器断开后会话不再丢失。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 4 天前。
- 用什么语言写的？
- 主要是 TypeScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题
AI 编程代理通常跑在本地终端里，浏览器一关，会话就断了。pi-web 把 Pi Coding Agent 的会话放到真实的工作区中，让它们在你离开后继续运行。它的目标用户很明确：那些在服务器、云 VM 或家庭实验室机器上跑代理任务的人。你不需要把代码、工具和构建缓存搬到云端，而是让代理在它们原本所在的地方工作，浏览器只充当控制面板。对于需要长时间运行的代理任务，或者想从手机、平板、笔记本随时查看进度的开发者来说，这是一个直接的解决方案。
核心模型：机器、项目、工作区、会话
pi-web 的组织方式在 README 里画得很清楚。Machine 是一个本地或远程的 pi-web 运行时端点；Project 是那台机器上的一个文件夹；Workspace 是提供者拥有的工作目录，内置的 Git 会发现 worktree，否则就用项目文件夹本身；Session 则是在工作区内运行的 Pi Coding Agent 聊天。典型流程是先添加项目，选择工作区或 git worktree，启动会话，让代理干活，然后从任何浏览器回来查看。这个模型的关键在于，会话绑定在工作区上，而不是绑定在浏览器的标签页上。所以即使你关掉浏览器，代理进程依然在服务器上运行。
安装与启动：真实的命令
安装步骤相当直接。你需要 Node.js 22.19.0 或更新版本，npm，以及配置好的 Pi Coding Agent 0.84.0 或更高版本。全局安装命令是 npm install -g @jmfederico/pi-web --allow-scripts=node-pty。这里有个细节：在 npm 12 上，使用 scoped flag 可以让 node-pty 准备它的原生模块，而不必为其他依赖启用安装脚本。安装后运行 pi-web install 和 pi-web doctor 来检查和启动服务，然后打开 http://127.0.0.1:8504。日常管理命令包括 pi-web status、pi-web logs、pi-web restart 和 pi-web uninstall。这些命令都写在 README 里，没有歧义。
远程优先的设计与机器集群
pi-web 的设计是远程优先的。它鼓励你把 pi-web 跑在一台常驻机器上，而不是你的笔记本上。更进一步，它可以注册其他 pi-web 运行时作为远程机器，形成一个集群。一个面向浏览器的 pi-web 实例可以代理来自可信远程机器的项目、文件、Git 状态、会话、终端、活动以及 Pi 包管理。当你选择一个远程机器时，设置标签会标明目标。但要注意，网关级别的设置，比如主机、端口、允许的主机、已注册的机器和令牌，以及键盘快捷键，始终留在本地。这个区分很重要，它意味着你可以在浏览器端控制哪些机器可访问，但机器上的具体配置是分布式的。
插件机制与 Pi 包的区别
pi-web 支持浏览器插件和可选的基于 sessiond 的工作区提供者。内置的 Git 功能使用了与插件相同的公共提供者和后端接口，这意味着第三方插件可以扩展工作区的类型。但 README 特别提醒：Pi 包是 Pi 包管理器的一个概念，一个 Pi 包可能包含 pi-web 插件，但安装包和启用插件是两个不同的操作。服务端相关的更改需要重启会话守护进程。这个区分容易混淆，尤其是你从 Pi 生态迁移过来时。如果你打算写插件，需要先理解这个生命周期，否则可能会遇到配置不生效的问题。
配置：全局与项目级
配置文件有两个层级。全局配置位于 $PI_WEB_CONFIG 或 ~/.config/pi-web/config.json，项目级配置放在 <project>/.pi-web/config.json。常见的配置项包括主机和端口、路径访问权限、上传设置、插件启用状态、快捷键以及会话守护进程选项。在设置界面中，影响机器的配置会针对选定的机器，而网关设置则保持本地。这意味着你可以在一个浏览器界面里管理多台机器的行为，但网络层面的边界仍然由每台机器的本地配置决定。这种分离是合理的，但你需要记住哪些设置是全局的，哪些是局部的，否则容易在排查问题时找错地方。
安全模型：明确的信任边界
README 用很直白的语言说明了安全模型：pi-web 假设可信用户、可信仓库和可信服务器路径。它不是沙箱，不是权限系统，也不是多租户平台。不要直接把它暴露到公共互联网，除非你使用了可信网络、防火墙、VPN、SSH 隧道或经过认证的反向代理。这个警告不是套话，而是项目的核心边界。pi-web 的设计目标是方便，而不是隔离。如果你需要让多个互不信任的用户共享一个实例，这个项目会是一个安全隐患。它的适用场景是个人或小团队在受控网络内使用。
编辑结论
pi-web 适合那些已经使用 Pi Coding Agent，并且希望把代理任务从本地终端搬到常驻服务器或开发机上的人。它解决了一个真实痛点：浏览器断开后会话不再丢失。但它的安全模型明确假设可信用户和可信仓库，不是沙箱，也不是多租户平台，绝不能直接暴露到公网。采用前先确认你的 Pi Coding Agent 版本不低于 0.84.0，Node.js 版本不低于 22.19.0，并仔细阅读安全模型和远程访问指南。如果你需要多租户隔离或细粒度权限控制，这个项目不适合你，应该寻找真正的沙箱方案。pi-web 的价值在于简单直接，它把工作区持久化这件事做对了，但你要自己负责网络边界。
社区笔记