pi 网页工作台 xing-shuyin/pi-web-ui

pi-web-ui

English · 简体中文 · 繁體中文

pi-web-ui 是面向 AI 编码智能体的 Web 工作台，将对话、文件、终端与 Git 放在同一个界面。它基于 pi coding agent，支持在浏览器中使用，也提供 Electron 桌面版与 Windows 便携版。

官方网站 · 文档中心 · 下载发行版 · 更新日志

快速开始

npm、npx 和源码安装需要 Node.js ≥ 22.19.0 与 npm。Windows 请先安装 Git for Windows，保留 Git Bash；Linux 请准备 Python 3、make 和 C++ 编译工具链。

npm install -g pi-web-ui@latest
cd /path/to/your-project
pi-web-ui

默认打开浏览器，地址为 http://127.0.0.1:8787。在工作台设置中配置模型提供商、凭据与模型，再开始对话。安装完成不代表模型已经可用。

不安装全局命令也可在项目目录运行：

npx pi-web-ui@latest

若 npm 12+ 阻止依赖安装脚本，按需使用以下命令；旧版 npm 使用上面的普通命令：

npm install -g --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latest
npx 对应写法：
npx --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latest

node-pty 需要安装脚本支持终端功能，请勿用 --ignore-scripts 跳过。原生模块构建失败时，参阅安装指南补齐平台工具链。

选择安装方式

| 方式 | 适用场景 | 入口与说明 |
| npm 全局安装 | 经常使用 CLI、管理后台服务 | npm install -g pi-web-ui@latest |
| npx | 快速试用、按需启动 | npx pi-web-ui@latest；仍会使用 npm 缓存与应用数据目录 |
| Electron 桌面版 | 独立桌面窗口 | Releases：按系统与架构选安装包；启动应用无需另装 Node |
| Windows 便携版 | 解压后使用、携带配置 | 同一 Releases 页选择 portable zip；解压后运行 启动Pi.bat / PiPortable.bat，配置与工作区放在便携目录中 |
| Docker 源码构建 | 容器部署 | 使用仓库的 docker-compose.yml，见下方步骤 |
| 源码运行 | 开发或自行构建 | npm ci → npm run build → npm start |
| Android / Termux | 手机本地运行 | 按安装指南的 Termux 一节准备原生构建环境 |

桌面安装包、便携包的具体平台与架构以该次 Release 附件为准。桌面应用中的插件安装和外部命令仍可能需要 Node/npm、Git 等工具；便携版也可能使用系统网络、缓存或外部工具。

前台运行与后台服务

前台默认使用当前目录作为工作区；按 Ctrl+C 停止。服务器上可禁用自动打开浏览器：

pi-web-ui --cwd "/path/to/project" --port 9000 --no-browser

确认项目、模型和终端可用后，再安装后台服务。server install 会安装并立即启动服务；server start 用于启动已经安装但停止的服务。

pi-web-ui server install --cwd "/path/to/project" --data-dir "/path/to/pi-data"
pi-web-ui server status

日常管理已安装的服务：

pi-web-ui server start # 仅在已安装且停止时使用 pi-web-ui server status pi-web-ui server restart pi-web-ui server stop

不再需要后台服务时，另行执行：

pi-web-ui server uninstall

卸载服务不会卸载 npm 包，也不会自动清理用户数据。

macOS 使用用户 launchd，Linux 使用 systemd，Windows 使用当前用户登录自启 Run 键。Windows 的实现不等同于系统级 Windows Service；Linux 安装所需权限取决于系统配置。

- 服务默认工作区为 ~/pi-web-ui；前台默认当前目录。
- CLI 服务数据默认放在 ~/.pi-web，以运行账户的家目录为准。
- pi Agent 配置默认放在 ~/.pi/agent，与工作区、服务数据目录不同。
- 建议显式固定工作区与数据目录；服务环境未必继承交互终端中的凭据和环境变量。
- server install --print 可预览配置；使用 --name my-pi 安装多实例时，后续管理命令带相同名称。

更多部署与排错说明见启动参数、服务与 /setup。

常用参数与 /setup

| 参数 | 用途与默认值 |
| --cwd <dir> | 项目工作区；包含空格的路径请加引号 |
| --port <n> | HTTP / WebSocket 端口，默认 8787 |
| --host <addr> | 监听地址，默认 127.0.0.1；0.0.0.0 监听所有 IPv4 网卡 |
| --data-dir <dir> | 服务数据目录，默认 ~/.pi-web |
| --agent-dir <dir> | pi Agent 配置目录，默认 ~/.pi/agent |
| --engine <pi\|dsh> | 执行引擎，默认 pi；DSH 需满足其运行与模型配置要求 |
| --no-browser | 前台启动时不自动打开浏览器 |
| --help / --version | 查看当前安装版本支持的参数或版本号 |

常用环境变量对应 PI_WEB_CWD、PI_WEB_PORT、PI_WEB_HOST、PI_WEB_DATA_DIR、PI_CODING_AGENT_DIR 与 PI_WEB_ENGINE。PI_WEB_SDK=bundled 可固定使用随包 SDK；没有 --sdk 参数。

本机配置入口

启动后，在运行服务的机器上打开 http://127.0.0.1:8787/setup，端口按实际配置替换。/setup 是浏览器路径，用来配置访问口令与网络；模型 API Key、登录与模型选择在工作台设置中完成。

/setup 仅接受回环连接和本机 Host，局域网 IP、公开域名及带代理转发头的请求会被拒绝。远程服务器可通过 SSH 本地转发访问：

ssh -N -L 18787:127.0.0.1:8787 user@your-server
保持连接，在本机浏览器打开 http://127.0.0.1:18787/setup

1. 核对页面显示的配置文件路径，确认实例正确。
2. 设置访问口令、监听地址、端口及按需使用的 Host / Origin 白名单。
3. 点击“保存配置”，确认保存成功；随机生成或复制链接本身不会保存。
4. 口令保存后立即热更新；网络配置保存后需重启对应进程或服务。

留空口令并保存会关闭口令认证。该页面位于口令认证前，本机用户可在忘记口令时重设。带口令的入口链接应按凭据保管。

配置保存在 <dataDir>/server-config.json。支持映射的配置按 命令行参数 → 环境变量 → 配置文件 → 默认值 取值；CLI 不自动读取任意 .env 文件。工作区与引擎仍由启动参数或环境配置。

例如启动命令仍带 --port 9000，重启后就会覆盖 /setup 保存的端口。口令虽能在当前实例热更新，重启时也需检查 访问口令环境变量 是否覆盖保存值。

跨设备访问前配置口令、网络访问范围与按需使用的 HTTPS。Host 白名单检查请求主机名，并非客户端 IP 白名单；不能当作额外的访问隔离保证。Docker 的端口映射也不等同于容器内回环连接，通常通过 Compose 配置网络与口令。

使用仓库 Compose 构建 Docker

git clone https://github.com/xing-shuyin/pi-web-ui.git
cd pi-web-ui
先编辑 docker-compose.yml，替换默认访问口令并按需配置挂载
docker compose up -d --build
docker compose ps
docker compose logs --tail=100 pi-web-ui

Compose 使用 build: . 从本地源码构建，pi-web-ui:latest 是本地镜像标签。首次启动前，将 访问口令环境变量 的示例值 change-me 换成自己的口令。

- 服务映射端口为 8787:8787，容器监听 0.0.0.0；通过宿主机地址访问。
- 命名卷 pi-web-data 挂载到 /app/.pi-web，保存服务数据。
- 操作宿主机项目时，添加绑定挂载，例如 /host/project:/workspace，并设置 PI_WEB_CWD: /workspace。
- 如需复用 pi 配置，可按 Compose 注释挂载 Agent 目录，并设置 PI_CODING_AGENT_DIR；模型凭据另行准备。

更新源码后再次执行 docker compose up -d --build。docker compose down 保留命名卷；加 --volumes 会删除卷内数据。升级前备份数据，项目文件也应放在持久挂载中。

更多步骤见 Docker 源码安装。

更新与移除

npm install -g pi-web-ui@latest
pi-web-ui server restart # 已安装服务时执行；前台进程自行重启

桌面与便携版请依对应包的更新方式操作，保留实际数据目录。移除前备份需要的对话、设置与凭据；npm 用户先卸载服务，再执行 npm uninstall -g pi-web-ui。移除包不会删除另行保存的用户数据。

可以做什么

- 对话与任务：流式回复、Markdown、图片与附件、提示词模板、历史检索，以及多对话和子代理协作。
- 项目工作台：文件浏览与编辑、预览、内置 PTY 终端、Git 状态和差异查看，在对话旁完成日常项目操作。
- 执行控制：工具审批、计划模式、目标模式与审查委派，按任务选择执行方式；实际权限取决于运行账户、工具与部署环境。
- 模型与扩展：管理提供商和模型，使用 pi / DSH 引擎及各自支持的能力；通过插件、MCP、技能和 UI 扩展点定制工作台。
- 界面与部署：多语言、主题、移动端布局、浏览器与桌面入口，以及后台服务部署。

各引擎的会话格式、工具和配置能力存在差异，切换前请参阅文档中心。界面中的审批与执行控制应结合实际系统权限使用。

界面预览

以下为仓库现有截图；具体界面随版本与主题变化。

| 对话与提示词 | 设置面板 |
| 对话与提示词 | 设置面板 |

| 内置终端 | Git 工作区 |
| 内置终端 | Git 工作区 |

文档与插件

- 完整安装指南 · 启动与服务
- 远程 SSH 项目 · 计划、目标与审查流程
- MCP 与浏览器工具 · 插件 SDK
- 社区插件目录 · 环境变量 · 部署指南

可在工作台浏览插件，或用 pi-web-ui install owner/repo 安装、pi-web-ui plugins 查看；权限与外部服务需求依插件而异。

开发与贡献

git clone https://github.com/xing-shuyin/pi-web-ui.git
cd pi-web-ui
npm ci
npm run dev

开发时访问 http://localhost:5173（Vite），后端默认端口为 8788。构建后运行：

npm run build
npm start

源码运行默认端口为 8787，npm start 不自动打开浏览器。开发规范、测试与架构入口见 AGENTS.md 和开发指南；桌面开发见 desktop/README.md。

欢迎通过 Issues 报告问题或提出需求，通过 Pull Request 提交改进。报告问题时请附版本、系统、安装方式、复现步骤与脱敏日志。

社区与联系

- QQ 交流群：1126050727
- GitHub Discussions：交流用法与想法
- GitHub Issues：问题反馈与需求建议
- dsh-ui-tools：作者相关项目，DSH 生态 UI 工具集

许可证

本项目采用 MIT License。