# pi-webapp

[English](README.md)

## 下载 pi 桌面版

**⬇ 测试版 · v0.1.21 / 桌面构建 6 · 内置 Pi 1.3.0**

| 你的电脑 | 下载安装包 |
| --- | --- |
| macOS · Apple 芯片（M 系列，arm64） | [下载 DMG](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-mac-arm64.dmg) |
| macOS · Intel 芯片（x64） | [下载 DMG](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-mac-x64.dmg) |
| Windows · x64 | [下载 EXE 安装程序](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-win-x64.exe) |
| Linux · x64 | [下载 AppImage](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/pi-0.1.21-desktop.6-linux-x86_64.AppImage) |

[版本说明](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.21-b6) · [SHA-256 校验和](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/SHA256SUMS) · [运行时与源码元数据](https://github.com/chengzhiyi/pi-webapp/releases/download/desktop-v0.1.21-b6/desktop-release.json) · [旧构建 5（保留回退）](https://github.com/chengzhiyi/pi-webapp/releases/tag/desktop-v0.1.20-b5) · [改用 Web/npm 方式](#安装与打开)

> **安装：** macOS 打开 DMG，将 **pi.app** 拖入“应用程序”；Windows 运行 EXE 安装程序；Linux 为 AppImage 添加可执行权限后运行，缺少 FUSE 时可加 `--appimage-extract-and-run`。已内置 Node 和锁定版本的 Pi **1.3.0**，无需另装；首次使用在设置中配置模型账户。替换前先退出旧桌面。复用外部 Web 后台时，其 Pi 仍保持原版本，不会自动停止或升级。
>
> **未签名测试版：** macOS 未公证，Windows 可能提示未知发布者；仅在确认来源可信后按单个应用的系统提示处理，不要全局关闭系统安全保护。四种实际安装包均通过原生运行冒烟，但不代表已测试所有 Linux 发行版或真实模型账户登录。不含 Windows ARM/Linux ARM；本构建尚无桌面自动更新。

![pi-webapp 封面](assets/cover-webapp.png)

**pi-webapp** 可以在本地浏览器中打开当前活跃的 Pi 编程 Agent 会话。Agent、工具和会话存储仍由 Pi 运行和管理；浏览器提供实时的对话与控制界面。

## 安装与打开

需要 Node.js 22.19 或更新版本。推荐直接运行：

```bash
npx pi-webapp
```

该命令会在后台启动 Pi，并在本地图形桌面用默认浏览器打开网页，终端可继续使用。若未找到 Pi，会自动通过 npm 安装官方 `@earendil-works/pi-coding-agent`。已有 Pi 需要 0.87.1 或更新版本；启动器不会自动覆盖旧版本。再次运行启动命令会重新打开已有服务。远程或无图形界面时只显示地址；设置 `PI_WEBAPP_AUTO_OPEN=0` 可关闭自动打开。

网页的「设置 → 通用设置 → 应用更新」会检查 npm 上的 `pi-webapp` 新版本。通过 npm 包的后台启动器运行时，点击「升级并重启」会先将新版安装并校验到 Pi 数据目录的 `pi-web/releases/`，然后重启服务，网页会在原地址重新加载。请先等待当前回复结束。若新版无法启动，启动器会恢复旧版服务。`npx` 和全局命令启动均可使用；后续启动会自动选用已安装的新版。此操作不会改动 npm 全局安装。源码目录运行和已有 Pi 终端中的 `/web` 页面可以查看版本，但不能从网页重启。若服务未恢复，可运行 `pi-webapp status` 并查看 `~/.pi/agent/pi-web/launcher.log`。

可用 `npx pi-webapp status` 查看地址，用 `npx pi-webapp stop` 停止后台服务。全局安装后可直接运行 `pi-webapp status` 和 `pi-webapp stop`。

也可以将启动器安装为全局命令：

```bash
npm install -g pi-webapp
pi-webapp
```

如果希望在已有 Pi 终端中使用，仍可按原方式安装扩展：

```bash
pi install npm:pi-webapp
pi
```

在 Pi 中输入 `/web`，即可在默认浏览器中打开界面。对于远程或无图形界面的环境，Pi 也会输出本地访问地址。该地址包含一个随机令牌，仅在当前 Pi 进程运行期间有效。再次输入 `/web` 可以重新打开界面。

## 功能

- 查看当前对话，包括 Markdown 内容、流式输出、可展开的推理过程与工具调用、Token 用量，以及逐轮执行轨迹。
- 发送消息、暂停与继续运行、启动新的 Pi 会话，以及切换当前模型或思考级别。运行时右下角显示暂停；暂停后清空输入框即可继续，刷新或重新打开会话后仍可恢复。继续通过内部控制动作恢复原任务，不新增用户消息；模型会基于已有进度发起新请求，计划模式仍需重新审批。
- 浏览工作区和已保存的会话。环境支持时可通过系统目录选择器添加工作区；通过 SSH 使用时，也可使用内置目录浏览器。
- 通过对话右上角的常驻入口打开右侧工具栏，在「工作区文件」中逐层浏览当前会话的目录，点击文件打开只读预览。对话中的工作区相对路径及工作区内绝对路径链接也会直接打开右侧预览，外部网址仍在新窗口打开。支持带行号和高亮的代码、Markdown 预览与源码切换，以及 PNG/JPEG/GIF/WebP 图片与放大查看。面板可收起、调宽、分栏或全屏，并继续承载插件内容；切换聊天会保留各自的标签和目录展开状态（刷新网页后重置）。文件树和预览提供手动刷新，每层最多显示 1000 项，文本预览上限 512 KB / 10000 行、图片上限 8 MB；HTML/SVG 显示源码，其他二进制文件显示不支持提示。文件读取限制在当前会话工作区内，包括符号链接的真实目标。
- 在右侧「开始」页选择「打开终端」，以当前会话的工作区为初始目录启动默认 shell。支持真实交互输入、持续输出、Ctrl+C、尺寸调整、分栏和全屏。切换标签、折叠侧栏和切换聊天保留进程、环境变量与终端画面；短暂断线会自动重连，未确认的输入不会重放。关闭标签或停止服务会回收进程；浏览器关闭或连接持续丢失后，后台最多保留 5 分钟。刷新网页会重置标签，不支持跨服务重启恢复进程。每会话最多 8 个终端、服务最多 32 个，保留 2000 行滚动历史。终端使用 Pi 所在用户的系统权限，工作区是初始目录，不是 shell 沙箱。
- 在右侧「开始」页选择「Git 改动」，查看当前分支、提交、基于本地记录的上游领先/落后数量，以及已暂存、未暂存、未跟踪和冲突文件。点击文件直接在 Git 面板内预览只读差异，保留文件列表且不增加标签页。列表与差异独立滚动，窄面板上下排列，宽度达到 720 px 时左右并排。选中文件高亮并随 Git 标签保留，暂存状态变化时跟随对应范围，文件不再有改动时收起预览；也可手动关闭恢复完整列表。差异隐藏原始 Git 头信息，显示新旧行号与增删行数，可用上一处／下一处按钮逐个跳转连续改动块并查看当前位置；文件权限变化、末尾无换行等信息保留为简洁提示。读取范围限制在当前会话目录内，包括仓库子目录；支持独立工作树和尚无提交的仓库。可见的 Git 标签会在 Agent 状态变化、页面重新聚焦时刷新，并每 5 秒检查一次；隐藏后停止轮询。需要在 Pi 所在机器安装 Git。最多显示 1000 个文件，差异上限 512 KB / 10000 行；二进制文件、子模块和未解决冲突显示提示。改动属于共享工作树，不代表全部由当前聊天产生；工作区与历史文件的差异视图保持只读。
- 在「Git 改动 → 改动」中，用文件右侧的 **+ / −** 逐文件暂存或取消暂存；底部固定提交栏仅提交暂存区内容（支持 Ctrl/Cmd+Enter）；点击顶部分支名称，可搜索和切换本地分支，选择「新建分支」才展开创建表单。文件列表独立滚动，仓库完整信息通过短名称的悬停提示查看。草稿随各聊天的 Git 标签保留。提交和切换分支要求仓库根目录工作区，切换还要求整个工作树干净（包括未跟踪文件）。写操作要求共用工作树的已知聊天均为空闲，并校验状态快照，遵守 Git hooks 与签名配置。冲突、未完成的 Git 操作、锁及其他工作树占用的分支会阻止相应操作。失败或结果不明时保留草稿，不自动重试。同一工作树的改动由多个聊天共享。不执行 fetch/push、强制切换、stash 或丢弃改动。
- 在「Git 改动 → 历史」中浏览提交及其分支、合并关系图，显示 HEAD、本地分支、远端跟踪分支和标签。历史每次加载 50 条；引用变化时重新加载首页，避免分页混入不同版本的历史。点击提交查看完整说明、作者与提交者、时间、父提交及改动文件，再点击文件在当前提交详情内预览只读差异，保留文件列表，不再新建差异标签。合并提交可选择比较的父提交，根提交与空目录比较。关系图展示整个仓库的提交元数据，提交文件和差异仍限制在当前会话目录内。历史选中项与已加载页随各聊天的 Git 标签保留，网页刷新后重置。远端标签仅使用本地记录，不发起拉取。
- 通过选择、拖放或粘贴附加文件，最多 20 个，每个不超过 20 MB。图片会显示预览，并作为 Pi 图片内容发送。
- 从侧栏「新会话」下方的「插件」入口管理内置 Git、文件和终端。支持列表/详情、搜索、真实启停和全局持久化；所有聊天空闲后才可切换。停用会关闭相关标签并阻止后端请求，停用终端需确认并结束此服务的全部终端。外部 Pi Web 插件展示运行时归属，仍通过「包与扩展」管理，不提供只隐藏 UI 的假开关。
- 在设置面板中管理外观、Pi 软件包、扩展、技能和模型。模型页可添加模型、编辑显示名称、上下文窗口、最大输出 token 数和输入类型，或恢复内置模型的默认参数；配置写入 Pi 的 `models.json`。网页登录会自动打开提供方授权页；当回调无法到达 Pi 时，仍可手动粘贴授权码。已保存的提供方认证可在这里移除。凭据保留在 Pi 本地的 `auth.json`，不会返回给浏览器。

如果通过 Pi 终端手动输入 `/web`，该终端会话会与浏览器保持同步。使用启动器时，Pi 在后台运行。在其他工作区打开的会话使用 Pi SDK，并加载该工作区的技能和项目上下文；已启用的 Web 插件 Pi 入口会显式加载，其他普通 Pi 扩展仍与主会话隔离。

每个聊天独立运行：切换工作区、切换聊天或新建聊天时，原任务会继续在后台执行。切回后会恢复正在输出的内容、历史记录和待处理的插件交互。“停止”只影响当前选中的聊天。会话实例会保留到 Pi 服务停止；停止或重启服务会结束后台任务。

启动时会从 Pi 已保存的会话中发现工作区，因此先前在其他目录使用 Pi 的会话也会出现在侧边栏。工作区记录和附件继续存放在 Pi 现有的 `pi-web/` 数据目录下。从侧边栏移除工作区不会删除其文件或会话；移除后如需再次显示，可以手动添加。

## 桌面端（可选）

**[下载 pi 桌面测试版](https://github.com/chengzhiyi/pi-webapp/releases)** — 目前仅发布已验收的 macOS Apple 芯片（arm64）版本。在 `desktop-v...` 预发布版本中下载 DMG，核对 `SHA256SUMS` 后安装 **pi.app**，在“pi → 关于 pi”查看构建号。测试版未签名、未公证，请勿全局关闭系统安全保护；Windows/Linux 暂不提供已验收的发行包。

同一套界面也可在名为 **pi** 的 Electron 桌面程序中使用，现有浏览器与 `/web` 方式保持不变。桌面包自带 Node/Pi，支持独立窗口、已有服务复用、在浏览器打开同一服务，以及退出时选择保留或停止后台任务。

源码构建：`npm ci` → `npm run desktop:prepare` → `npm run desktop:start`。运行 `npm run desktop:package` 生成当前系统/架构的安装包，输出到 `desktop-release/`。当前本地验证目标为 macOS arm64；Windows/Linux 打包配置需在对应系统验证。首版安装包未签名，尚无桌面自动更新。安装包文件名包含桌面构建号；“pi → 关于 pi”显示实际运行的构建号和应用位置。替换前先退出旧桌面，外部兼容 Web 后台无需停止；若替换桌面自有运行时，请先结束任务并停止该自有后台。

详细说明见 [桌面端构建、测试与发布边界](docs/desktop.md)。

## 本地开发

```bash
npm install
npm run check
npm run test
npm run build
npm run start
npm run status
npm run stop
```

`npm run start` 会构建项目、在后台启动 Pi 并打开 Web 界面。修改扩展后，运行 `npm run stop`，再运行 `npm run start`；如果使用 `pi -e .` 开发，则在 Pi 中依次输入 `/reload` 和 `/web`。仅刷新旧的浏览器页面不会替换正在运行的连接桥接代码。

与同级 `pi-extensions` 联调时，先在该目录运行 `pnpm install && pnpm build`，再运行 `pnpm dev`；在本项目设置 `PI_WEBAPP_PLUGIN_DEV_ROOTS=../pi-extensions/packages/plan-mode` 后执行 `npm run start`。浏览器资源变化后页面会刷新，Pi 入口变化后会等待代理空闲并重载扩展。完整步骤见 `pi-extensions/README.md`。

源码按职责组织：`src/adapters/pi/` 为薄 Pi 入口，`src/host/` 为前后端宿主，`src/plugins/builtin/` 分别集中 Git、文件和终端的 server/client/contract，`src/contracts/` 保存宿主跨端契约，`web/src/ui/` 保留共享 UI。详见[目录与插件管理说明](docs/architecture.md)。npm 软件包仅包含打包并压缩后的 JavaScript 扩展、构建后的 Web 资源、封面图片，以及英文和中文 README；不会发布 TypeScript 源码或 source map。代码压缩会增加阅读发布版本代码的难度，但不会对 JavaScript 加密。

## 错误采集

前后端 Sentry 错误采集默认开启，使用内置公共 DSN，无需额外配置。在启动 Pi 的环境中设置 `PI_WEB_SENTRY_DSN` 可覆盖默认项目，使用 `PI_WEB_SENTRY_ENABLED=false` 关闭。默认只采集脱敏堆栈、操作轨迹和状态摘要，不采集对话、源码正文、附件内容或凭据，不启用界面录制。默认上报地址、独立前后端 DSN 和私有 sourcemap 上传步骤见 [Sentry 配置说明](docs/sentry.md)。

## 发布

CI 会先从 npm 解析 `@chengzhiyi/pi-web-protocol` 的已发布版本，再运行 `npm ci`。
首次发布协议前，校验任务会将固定提交的 `pi-extensions` 检出到被忽略的 `.ci/`
目录，构建协议并使用本地包，完整执行检查、测试与构建；Actions 摘要会说明
宿主发布仍在等待协议初始化。正式发布始终要求准确的 npm 依赖，并将清单和
锁文件变化同步回仓库。协议发布后可以在 Actions 手动运行工作流；协议发布
不会主动触发这个仓库。

`npm publish` 会运行检查、测试和生产构建。`pi-package` 关键词使发布到 npm 的软件包有资格进入 [Pi 软件包目录](https://pi.dev/packages)；目录更新可能晚于 npm。

GitHub Actions 会在针对 `main` 的拉取请求中运行 `check`、`test` 和 `build`。代码推送到 `main` 后会再次运行这些检查，根据源码版本和 npm `latest` 版本确定下一个补丁版本，先将更新后的 `package.json` 和 `package-lock.json` 提交回 `main`，再发布到 npm。版本同步提交使用工作流的 `GITHUB_TOKEN`，不会再次触发工作流。如需开始新的次版本或主版本，请在拉取请求中同步提高两个包文件的版本。每次发布也会将包内 `pi.image` 的地址更新为该版本。仓库必须允许工作流推送到 `main`，发布才能继续。

首次自动发布前，请在 npm 的 `pi-webapp` 包设置中配置 Trusted Publishing：GitHub 所有者为 `chengzhiyi`，仓库为 `pi-webapp`，工作流文件名为 `ci.yml`，不设置环境，并允许直接执行 `npm publish`。工作流通过 GitHub OIDC 认证，无需 npm token。`package.json` 中的仓库地址应与 GitHub 仓库保持一致。

## 许可证

MIT。详见 `LICENSE` 文件。