mrexodia/toilet-pi

# Toilet-Pi 从浏览器控制你的 [pi](https://github.com/earendil-works/pi) 会话。 Toilet-Pi 为你提供了一个跨计算机查看 pi 会话的移动端友好视图。你可以监视活跃的工作、发送 prompt、中止运行、在后台恢复非活跃会话，或者在项目中启动新会话。 ## 工作原理 ``` Browser │ ▼ Central Toilet-Pi server ▲ ▲ │ │ Host supervisor Pi extension (one per machine) (one per running session) │ └── starts background pi sessions on demand ``` 中央服务器是一个轻量级的 WebSocket 枢纽：它维护着已连接机器的实时概览，并负责路由浏览器命令和会话事件。每台机器上运行的 supervisor 能够发现本地会话文件，并可以启动后台 pi 进程。常规的交互式 pi 会话通过 Toilet-Pi 扩展直接连接。 这种设计提供了一种跨多个计算机的统一 UI，而无需将本地会话文件或模型凭证移动到服务器。每台机器的连接均为出站连接，因此当 Toilet-Pi 不可用时，交互式 pi 仍能独立运行；并且随着机器和会话的重新连接，服务器状态也会自动重建。 ## 功能特性 - 实时访问常规的交互式 pi 会话 - 按机器或项目对会话进行分组 - 远程发送 prompt 和中止运行 - 为非活跃会话提供后台恢复功能 - 从浏览器启动新的后台会话 - 无缝回切至本地 pi TUI 如果 Toilet-Pi 处于离线状态，交互式 pi 依然可以正常使用。后台会话在与服务器断开连接时会自动停止，从而防止隐藏的孤儿进程更改会话。 ## 环境要求 - Node.js 22.19 或更高版本 - [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) - Git ## 快速开始 ### 1. 安装 Toilet-Pi 克隆本仓库，安装相关依赖，并直接从 GitHub 安装 pi 包： ``` git clone https://github.com/mrexodia/toilet-pi.git cd toilet-pi npm run setup pi install https://github.com/mrexodia/toilet-pi ``` 如果之后需要更新已安装的扩展，请运行 `pi update --extensions`，然后重启 pi 或者运行 `/reload`。 ### 2. 启动服务器 ``` npm start ``` 服务器会打印出一个 **Admin 登录 URL**。在浏览器中打开该 URL。 默认情况下，服务器运行在 `http://localhost:3457`。其生成的 admin token 保存在 `~/.pi/agent/toilet-pi-server.json` 中。 ### 3. 连接你的机器 在 Web UI 中： 1. 打开 **Installation**。 2. 生成一个机器连接 URL。 3. 复制该 URL。 然后在目标机器上打开 pi 并运行： ``` /toilet-pi wss://your-server/ws?token=... ``` 请使用 Web UI 生成的确切 `ws://` 或 `wss://` URL。不要使用浏览器的 Admin 登录 URL。 ### 4. 启动 supervisor 在每台已连接的机器上保持以下程序运行： ``` npm run supervisor ``` supervisor 负责让本地会话和项目变得可见，并在收到浏览器请求时启动后台 pi 进程。 ### 5. 使用 Toilet-Pi 打开 Web UI 即可执行以下操作： - 检查跨已连接机器的各类会话 - 向活跃会话发送 prompt - 通过发送 prompt 来恢复非活跃会话 - 从 **Projects** 视图中启动新会话 - 中止正在进行的运行 常规的本地 pi 会话会通过 `toilet-pi.ts` 自动连接。 ## 常用 pi 命令 ``` /toilet-pi ``` 输入或替换该机器的连接 URL。 ``` /ws ``` 显示当前的 Toilet-Pi 连接状态。 若要在不永久安装扩展的情况下进行尝试： ``` pi -e https://github.com/mrexodia/toilet-pi ``` ## 添加其他计算机 在每一台需要添加的计算机上： 1. 使用 `git clone https://github.com/mrexodia/toilet-pi.git` 克隆本仓库。 2. 进入仓库目录并运行 `npm run setup`。 3. 运行 `pi install https://github.com/mrexodia/toilet-pi`。 4. 从 Web UI 的 **Installation** 中生成一个新的机器 URL。 5. 在 pi 中运行 `/toilet-pi `。 6. 运行 `npm run supervisor` 启动 supervisor。 请为每台计算机生成独立的机器 URL。 ## Cloudflare Workers 部署 首先生成一个高强度的服务器 token： ``` node --input-type=module -e "import { randomBytes } from 'node:crypto'; console.log(randomBytes(32).toString('base64url'))" ``` 然后部署服务器和 Web UI。当 Wrangler 提示输入 secret 值时，请粘贴刚刚生成的 token： ``` cd server npx wrangler login npx wrangler secret put TOILET_PI_SERVER_TOKEN cd .. npm run deploy ``` 部署完成后，打开： ``` https://your-worker.workers.dev/#token=YOUR_SERVER_TOKEN ``` supervisor 和 pi 扩展依然需要在每台已连接的计算机上本地运行。 ## 配置说明 常用的环境变量： | 变量 | 用途 | | --- | --- | | `PORT` | 本地服务器端口；默认为 `3457` | | `TOILET_PI_PUBLIC_URL` | Node 服务器的公共 URL 覆盖 | | `TOILET_PI_SERVER_TOKEN` | 固定的 admin token，用于替代本地自动生成的 token | | `TOILET_PI_HOST_ID` | 机器的自定义名称 | | `TOILET_PI_SESSION_DIR` | 自定义的 pi 会话目录 | | `TOILET_PI_PI_COMMAND` | 用于启动 pi 的路径或命令 | | `TOILET_PI_SERVER_URL` | 机器连接 URL 覆盖 | | `PI_CODING_AGENT_DIR` | 覆盖 pi 的配置目录 | 机器配置通常存储在 `~/.pi/agent/toilet-pi.json` 中。 ## 故障排除 - **机器不可见：** 确保该机器上正在运行 `npm run supervisor`。 - **交互式会话不可见：** 通过 `pi list` 确认已安装该包，然后重启 pi 或运行 `/reload`。 - **非活跃会话无法启动：** 该机器的 supervisor 必须处于已连接状态。 - **配置了错误的服务器：** 使用新生成的机器 URL 重新运行 `/toilet-pi`。 - **远程访问失败：** 当在外部网络（非本地网络）暴露 Toilet-Pi 时，请务必使用 HTTPS/WSS。 ## 安全性与持久化 请将 Admin 登录 URL、服务器 token 和机器 URL 视为机密信息。在进行远程部署时请使用 HTTPS。 服务器会话状态保存在内存中，并会随着客户端的重新连接而重建。你实际的 pi 会话文件始终保留在各自的原始机器上。 ## 许可证 MPL-2.0

标签：AI编程助手, GNU通用公共许可证, MITM代理, Node.js, SOC Prime, WebSocket, 依赖分析, 开发工具, 暗色界面, 程序员工具, 网络安全研究, 自动化攻击, 运维管理, 远程控制