pi-web-ui 0.9.0 → 0.9.2

package/README.zh-CN.md

@@ -1,359 +1,359 @@
-# pi-web-ui
-
-[English](README.md) | **简体中文**
-
-面向 [pi 编码智能体](https://pi.dev) 的 Web 聊天界面，直接构建在
-**pi SDK**（[`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)）之上——
-无子进程、无 JSON-RPC 中间层。智能体运行在服务端进程内，通过 WebSocket 把事件流式推给浏览器。
-
-灵感来自 [Pintra (pi-vsc)](https://github.com/bilalbentoumi/pi-vsc)——它在 VS Code 里通过
-`pi --mode rpc` 实现同样的事情。本项目改用 SDK 的 `createAgentSessionRuntime` API 进程内调用
-（SDK 文档也推荐 Node.js 应用走这条路而非 RPC），因此有类型安全、直接的状态访问，以及你现有的
-pi 认证/配置/扩展——无需额外安装或配置任何东西。
-
-## 功能特性
-
-- 🧠 完整智能体循环：**思考**块（可折叠）+ 流式文本输出
-- 🛠 工具执行卡片：**实时输出流**、状态（排队 → 运行中 → 完成/出错）、参数可复制
-- 💬 会话**历史按浏览器持久化**（localStorage clientId + 每客户端会话目录）——刷新或重启后聊天记录都在。
-  会话面板还会列出当前文件夹下的 pi CLI/TUI 会话（标记为 `TUI`），可以直接从 Web 界面续聊终端对话
-- 📂 **项目记忆**：记住每个浏览器上次打开的工作目录（重启后自动恢复），左侧面板有「最近项目」
-  列表可一键切换，每个项目的会话独立保存、随时回去接着问
-- ✏️ **编辑重问**：每条历史提问下方有编辑按钮，改完从该位置重新提问——服务端 fork 出一个
-  新分支会话（该问题之前的历史完整保留），原对话原样留在会话列表，随时可切回
-- ⚡ **长对话不卡**：超过 30 条消息后，早期消息自动折叠成摘要行（角色 + 首行预览 + 块计数，
-  不渲染 Markdown/思考/工具输出），点击才展开完整内容；最近 15 条始终完整显示
-- ⬇️ **一键自更新**：右上角显示当前版本，打开更新面板检查 npm 最新版，发现新版本可一键
-  `npm i -g` 升级（更新后需重启服务生效）
-- 🔄 模型与思考强度切换（与 pi TUI 一致）、新对话、中止/停止
-- 📎 Markdown 渲染：GFM 表格、语法高亮代码块、复制按钮
-- 📁 工作区感知：智能体在你指定的目录里读/改/跑代码，使用**你自己的** `~/.pi/agent` 认证、模型、技能和扩展
-- 🌐 多个浏览器客户端各自独立会话（每个 clientId 私有会话目录）
-- 🖥 内置**终端**（xterm.js + node-pty，无需 VS Code）：三栏布局——左侧**命令列表**
-  （用户自定义命令，支持 `${pwd}`，持久化在项目 `.pi/commands.json`）、中间**终端**、
-  右侧 VSCode 风格**标签条**支持多个并发 shell。通过顶栏按钮在对话/终端视图间切换。
-
-## 快速开始
-
-需要 Node.js ≥ 22.19（pi SDK 的要求；旧版 Node 加载 SDK 时会报 `Unexpected token 'with'`）
-以及一个配置好的 pi 安装（先运行一次 `pi` 登录）。
-
-```bash
-npm install
-npm run dev          # 服务端 :8787，Web UI :5173（自动代理）
-# 打开 http://localhost:5173
-```
-
-生产模式：
-
-```bash
-npm run build        # 编译服务端 (tsc) + 前端 (vite)
-npm start            # 在 http://localhost:8787 提供全部服务
-```
-
-## npm 包（安装 / 启动 / 停止 / 更新 / 卸载）
-
-包已发布到 npm：[`pi-web-ui`](https://www.npmjs.com/package/pi-web-ui)。
-
-### 安装
-
-```bash
-# 全局安装（推荐）
-npm i -g pi-web-ui
-
-# 或免安装直接跑（拉取最新版，启动在 :8787）
-npx pi-web-ui
-
-# 或安装本地 checkout（发布前测试改动用）
-npm i -g .
-```
-
-> **npm 由 pi 托管？** 如果你的 `npm` 是拦截依赖安装脚本的 pi 包装器，装完后需要批准一次
-> node-pty 的原生构建：`npm approve-scripts node-pty@1.1.0`（标准 npm 会自动完成）。
-
-### 启动
-
-```bash
-pi-web-ui                                            # 前台，http://localhost:8787
-PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui      # 自定义端口 / 工作目录
-```
-
-想后台运行或开机自启，请使用系统服务——见
-[部署与开机自启](#部署与开机自启)（systemd / launchd / Docker）。
-
-`pi-web-ui` 命令从包安装位置提供编译好的前端和 WebSocket API——不需要仓库 checkout。
-它使用**你的** `~/.pi/agent` 配置（认证/模型/技能），并把每客户端会话存在
-`<PI_WEB_CWD>/.pi-web` 下。
-
-### 停止
-
-- **前台**：在运行它的终端按 `Ctrl+C`。
-- **systemd**：`sudo systemctl stop pi-web-ui`
-- **launchd**：`launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui`
-- **Windows（计划任务）**：`pi-web-ui server stop`（或 `schtasks /End /TN pi-web-ui`；
-  停止运行中的实例，自启保留到 `server uninstall` 为止）
-- **Docker**：`docker compose stop`（停止并删除容器：`docker compose down`）
-
-（后台进程应该用系统服务管理，而不是 `nohup`——上面的服务停止命令同时会停掉并禁用自启。）
-
-### 验证 / 版本
-
-```bash
-pi-web-ui --version     # CLI 版本
-npm ls -g pi-web-ui     # 是否已安装？哪个版本？
-which pi-web-ui         # 可执行文件位置
-```
-
-### 更新
-
-```bash
-npm i -g pi-web-ui@latest   # 升级到最新发布版
-# 之后重启服务，新版本才会生效
-```
-
-### 卸载
-
-```bash
-npm uninstall -g pi-web-ui
-```
-
-卸载**不会**删除你的聊天记录：会话数据存放在 `<PI_WEB_CWD>/.pi-web`
-（或 `PI_WEB_DATA_DIR`），卸载/升级后依然保留。
-
-### 作为系统服务管理（开机自启）
-
-把服务端安装为开机自启的系统服务，可自定义端口和工作目录：
-
-```bash
-pi-web-ui server install --port 9000 --cwd /path/to/project   # 安装并启动
-pi-web-ui server status                # 运行中？自启？
-pi-web-ui server restart               # 重启（配置变更后同样用它）
-pi-web-ui server stop                  # 停止 + 禁用自启
-pi-web-ui server start                 # 重新启动
-pi-web-ui server uninstall             # 彻底移除服务
-```
-
-- **macOS** → launchd 代理（无需 sudo）：写入并加载
-  `~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist`，崩溃自动重启
-  （`KeepAlive`），日志在 `/tmp/pi-web-ui.log` / `/tmp/pi-web-ui.err`。
-- **Linux** → systemd 单元（自动 sudo）：写入
-  `/etc/systemd/system/pi-web-ui.service` 并执行 `systemctl enable --now`，
-  日志用 `journalctl -u pi-web-ui -f` 查看。
-- **Windows** → 任务计划程序：创建登录时启动的用户任务（与 launchd 代理一致；
-  通常不需要管理员，但部分机器上 `schtasks /Create` 需要提权的 PowerShell——
-  如果 `install` 报 `ERROR: Access is denied`，请用管理员 shell 重跑）。任务通过
-  `powershell.exe -WindowStyle Hidden` 运行生成在 `%APPDATA%\pi-web-ui\pi-web-ui.ps1`
-  的 PowerShell 启动器——**不会有黑色控制台窗口**常驻，没有可被误关/误杀的东西。
-  启动器设置环境变量、cd 到工作目录、启动 node，并把日志追加到
-  `%USERPROFILE%\pi-web-ui.log`。任务 XML 保存在旁边；失败会自动重启。
-  **务必显式传 `--cwd`**——任务会继承安装时 shell 的目录，而管理员 shell 默认是
-  `C:\WINDOWS\system32`，非提权任务写不进去（启动即 EPERM）。详见
-  [Windows — 任务计划程序](#windows--任务计划程序)。
-- 选项：`--port`（默认 8787 或 `$PORT`）、`--cwd`（默认 `$PI_WEB_CWD` 或当前目录）、
-  `--data-dir`（会话目录）、`--name`（自定义服务名；macOS 标签为
-  `com.xingshuyin.pi-web-ui`，自定义名变成 `com.<name>.server`）。`--print` 预览
-  生成的 unit/plist/任务文件而不实际应用。
-- 用新参数重跑 `install` 会重新生成配置并重启服务——这就是修改已装服务端口/cwd 的方式。
-
-## 配置
-
-| 环境变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `PORT` | `8787` | HTTP/WebSocket 端口 |
-| `PI_WEB_CWD` | 服务端 cwd | 智能体操作的工作区目录（读/编辑/bash/写） |
-| `PI_WEB_DATA_DIR` | `<cwd>/.pi-web` | 每客户端会话目录的存放位置 |
-| `PI_WEB_INLINE_FILE_MAX` | `12288` (12KB) | 小于等于该大小的文本附件直接内联进模型上下文；更大的文件以路径引用方式传入，模型按需用 read 工具读取（小改动省 token） |
-| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi 配置目录（auth.json、models.json、skills、extensions） |
-
-示例——让智能体面向某个项目：
-
-```bash
-PI_WEB_CWD=/path/to/your/project npm run dev
-```
-
-## 架构
-
-```text
-Browser (React + Vite)
-   │  WebSocket JSON — 快照驱动协议 (server/protocol.ts)
-   ▼
-server/index.ts        express 静态 + ws 端点
-   │
-server/agent-service.ts   每客户端 ClientSession:
-   │   createAgentSessionRuntime({ sessionManager: SessionManager.continueRecent(cwd, sessionDir) })
-   │   session.subscribe(events) → 节流全量快照 + 实时工具增量
-   ▼
-@earendil-works/pi-coding-agent (SDK, 进程内)
-   │   ModelRuntime (auth 来自 ~/.pi/agent) · tools · extensions · skills
-   ▼
-   你的 LLM 提供商
-```
-
-关键设计点：
-
-- **快照驱动 UI。** 服务端是唯一事实源：每次 SDK 事件后调度一个节流（60 ms）的全量快照，
-  浏览器纯粹按快照渲染。重连只需重新请求 `get_state`。大载荷（工具输出、文本）在序列化时
-  做了截断（`server/serialize.ts`）。
-- **助手实时流式输出。** 进行中的消息（SDK `agent.state.streamingMessage`）被序列化进每个快照，
-  所以思考块和回答文本是**边生成边**出现在浏览器里（带闪烁光标），而不是等整轮结束才显示。
-  部分消息拿到稳定的 `stream-<ts>` id，跨快照保持挂载（展开的思考/工具块状态不丢）。
-- **按大小感知的附件。** 点击 + 把文件加入附件队列（显示在输入框上方的 chips）。发送时服务端
-  把每个文件作为独立的 custom message 附加（SDK `sendCustomMessage` + `nextTurn` asides）——
-  用户消息保持干净，每个文件渲染成自己可折叠的卡片：小文本文件（≤ `PI_WEB_INLINE_FILE_MAX`，
-  默认 12KB）直接内联，模型立即看到；更大的文件以 `<file path=...>` 引用传入，模型按需用
-  `read` 工具读取——所以附加一个 5 MB 的文件在模型真正查看前只花几个 token。图片始终以
-  image content 附加。
-- **带行号选区的文件预览。** 在右侧面板点击文件名（或其 👁 按钮）打开带行号的预览弹窗。
-  点击 / 拖拽 / Shift+点击选择行区间，然后点"添加到对话"把它作为 `lines` 附件入队——
-  服务端只内联选中的区间（`<file path=... lines="2-3">`），可以精确指向想说的代码而不必
-  倾倒整个文件。预览读取上限 512 KB，二进制文件会被检测并拒绝。
-- **实时工具输出。** `bash_execution_update` / `tool_execution_update` 事件被转发为轻量
-  `tool_delta` 消息，终端输出实时流动；最终输出在下一个快照的 toolResult 消息里到达，取代
-  delta 缓冲。
-- **隔离会话。** 每个浏览器客户端在数据目录下拥有 `sessions/<clientId>/`，重连时通过
-  `SessionManager.continueRecent` 续接。
-- **你已经拥有的一切。** 无需单独认证步骤——SDK 读取 `~/.pi/agent/auth.json` 并自动加载
-  你的全局扩展/技能。
-
-## 终端
-
-从顶栏切换终端视图（对话/终端）。它以三栏布局替代聊天界面：
-
-- **左 — 命令**：点击命令在对应目录打开终端标签页并运行。可在面板里增/改/删命令；它们保存到
-  `<project>/.pi/commands.json`（提交进仓库，与队友共享）：
-
-  ```json
-  {
-    "commands": [
-      { "name": "dev", "command": "npm run dev", "cwd": "${pwd}" },
-      { "name": "test", "command": "npm test", "cwd": "${pwd}/server" },
-      { "name": "build", "command": "npm run build", "cwd": "~/other-project" }
-    ]
-  }
-  ```
-
-  `${pwd}` 解析为智能体当前工作目录（聊天视图文件面板里显示的那个，可用 set_cwd 修改）；
-  `~` 和相对路径同样有效。命令面板顶部的 `+` 按钮新建条目。
-- **中 — 终端**：每个标签页是一个真实 PTY（macOS/Linux 是你的 `$SHELL`；Windows 是
-  PowerShell 或 cmd.exe——`$COMSPEC`）；输出实时流动，可以输入、Ctrl+C、调整大小等，和桌面
-  终端一模一样。Windows 上的 Git Bash 用户会自动拿到 `$SHELL`。
-- **右 — 终端（标签）**：VSCode 风格纵向标签条。`+` 在当前目录打开一个普通 shell。
-  关闭标签页会杀掉它的进程。
-
-说明：
-
-- 切回聊天视图时，运行中的命令继续运行。
-- 客户端的最后一个浏览器标签断开时终端会被杀掉（不留孤儿 dev server），所以断线会重置终端视图。
-
-## 协议
-
-完整 wire 格式见 `server/protocol.ts`。客户端 → 服务端：`hello`、`prompt`、`abort`、
-`new_chat`、`cycle_model`、`cycle_thinking`、`get_state`、`list_sessions`、
-`switch_session`、`list_files`、`list_models`、`set_model`、`set_thinking`、`set_cwd`、
-`complete_path`、`dialog_response`、`terminal_create`、`terminal_input`、
-`terminal_resize`、`terminal_kill`、`run_command`、`list_commands`、`save_commands`。
-服务端 → 客户端：`ready`、`snapshot`（完整 `UiState`）、`tool_delta`、`notice`、
-`terminal_output`、`terminal_exit`、`commands`。
-
-## 脚本
-
-| 脚本 | 作用 |
-| --- | --- |
-| `npm run dev` | 服务端（tsx watch）+ Vite dev server + WS 代理 |
-| `npm run build` | 类型检查 + 构建前端和服务端 |
-| `npm start` | 运行生产服务端（提供 `web/dist`） |
-| `npm run typecheck` | 双端 `tsc --noEmit` |
-| `node terminal-smoke-test.mjs` | WS 层终端/命令协议测试（先 build） |
-| `node terminal-browser-test.mjs` | 终端视图的无头浏览器 E2E（先 build） |
-
-## 部署与开机自启
-
-最快的路径：`pi-web-ui server install --port 8787 --cwd /path`——安装并让服务开机自启
-（见[作为系统服务管理（开机自启）](#作为系统服务管理开机自启)）。
-下面的手动方案保留给参考 / 非标准场景。
-
-### Docker（一条命令）
-
-```bash
-docker compose up -d     # 构建，启动在 :8787，开机自动重启
-docker compose stop      # 停止（保留容器）
-docker compose down      # 停止并删除容器
-```
-
-`docker-compose.yml` 里的 `restart: unless-stopped` 让 Docker 守护进程启动时（开机、崩溃、
-重启）把服务拉起来。挂载一个卷给 `/app/.pi-web`（会话持久化），可选地挂载你的 `~/.pi/agent`
-配置和工作区——见 `docker-compose.yml` 里的注释。
-
-### Linux — systemd
-
-```bash
-sudo npm i -g pi-web-ui
-sudo cp deploy/pi-web-ui.service /etc/systemd/system/
-# 先编辑 unit 里的 User/WorkingDirectory/Environment
-sudo systemctl daemon-reload
-sudo systemctl enable --now pi-web-ui     # 立即启动 + 每次开机启动
-sudo systemctl stop pi-web-ui             # 停止
-sudo systemctl disable pi-web-ui          # 取消开机自启
-journalctl -u pi-web-ui -f                # 日志
-```
-
-### macOS — launchd
-
-```bash
-npm i -g pi-web-ui
-cp deploy/com.xingshuyin.pi-web-ui.plist ~/Library/LaunchAgents/
-# 编辑 ProgramArguments / WorkingDirectory / PI_WEB_CWD（which pi-web-ui）
-launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist
-launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui   # 停止 + 移除自启
-# 日志：/tmp/pi-web-ui.log、/tmp/pi-web-ui.err
-```
-
-### Windows — 任务计划程序
-
-最简路径（自动生成一切，无需手改 XML）：
-
-```bat
-npm i -g pi-web-ui
-pi-web-ui server install --port 8787 --cwd C:\path\to\project
-pi-web-ui server status
-pi-web-ui server restart
-pi-web-ui server stop        :: 停止运行中的实例（自启保留）
-pi-web-ui server uninstall   :: 彻底移除任务
-```
-
-它的做法：写入 `%APPDATA%\pi-web-ui\pi-web-ui.ps1`（一个 PowerShell 启动器：设置
-`PORT`/`PI_WEB_CWD`、cd 到工作目录、启动 node 并把输出追加到 `%USERPROFILE%\pi-web-ui.log`）
-和任务计划程序 XML，然后注册一个**登录时**任务（`schtasks /Create /XML`——你登录时运行，
-与 launchd 代理一致；通常不需要管理员，但如果遇到拒绝访问，请看下面的排障说明）。任务调用
-`powershell.exe -WindowStyle Hidden`，所以服务运行**没有黑色控制台窗口**——没有可被误关/误杀
-的东西。不实际安装即可预览两个生成文件：`pi-web-ui server install --print`。
-
-手工方案用 `deploy/pi-web-ui-task.xml`：改好路径，把文件存成 **UTF-16 LE**（schtasks 要求），
-然后 `schtasks /Create /TN "pi-web-ui" /XML pi-web-ui-task.xml /F` 和
-`schtasks /Run /TN "pi-web-ui"`。
-
-> **Windows 排障**
->
-> - **`install` 报 `ERROR: Access is denied`（错误: 拒绝访问）**——部分机器上任务计划程序
->   不允许非提权令牌创建任务（删除自己拥有的任务 `schtasks /Delete` 却可以，所以
->   `server uninstall` 正常）。解决：在**管理员（提权）PowerShell** 里执行
->   `pi-web-ui server install`。
-> - **务必显式传 `--cwd`，且指向用户可写目录。** 任务会继承安装时 shell 的当前目录作为
->   工作目录。从提权 shell 安装且不带 `--cwd` 时，任务会注册成 `C:\WINDOWS\system32`，
->   服务端启动时随即报
->   `EPERM: operation not permitted, mkdir 'C:\WINDOWS\system32\.pi-web\sessions\...'`
->   ——因为登录任务以最小权限令牌运行，无法在 `system32` 下写入。请用例如
->   `--cwd C:\Users\<you>`（会话随之存到 `C:\Users\<you>\.pi-web`）。
-> - **修复已装坏的任务**（目录注册错的任务）：`pi-web-ui server uninstall`，然后
->   在提权 shell 里 `pi-web-ui server install --cwd C:\Users\<you>`。
->   用新选项重跑 `install` 也会就地重新生成任务。
->
-> **不登录也要开机启动？** 登录任务需要交互式会话，与 launchd 代理一样。
-> 无头/常开 Windows 请用 Docker（见上）。
-
-三套模板分别使用 `KeepAlive` / `Restart=on-failure` / `RestartOnFailure`，服务崩溃后
-自动重启，并在登录/开机时自动启动。
-
-## License
-
-MIT
+# pi-web-ui
+
+[English](README.md) | **简体中文**
+
+面向 [pi 编码智能体](https://pi.dev) 的 Web 聊天界面，直接构建在
+**pi SDK**（[`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)）之上——
+无子进程、无 JSON-RPC 中间层。智能体运行在服务端进程内，通过 WebSocket 把事件流式推给浏览器。
+
+灵感来自 [Pintra (pi-vsc)](https://github.com/bilalbentoumi/pi-vsc)——它在 VS Code 里通过
+`pi --mode rpc` 实现同样的事情。本项目改用 SDK 的 `createAgentSessionRuntime` API 进程内调用
+（SDK 文档也推荐 Node.js 应用走这条路而非 RPC），因此有类型安全、直接的状态访问，以及你现有的
+pi 认证/配置/扩展——无需额外安装或配置任何东西。
+
+## 功能特性
+
+- 🧠 完整智能体循环：**思考**块（可折叠）+ 流式文本输出
+- 🛠 工具执行卡片：**实时输出流**、状态（排队 → 运行中 → 完成/出错）、参数可复制
+- 💬 会话**历史按浏览器持久化**（localStorage clientId + 每客户端会话目录）——刷新或重启后聊天记录都在。
+  会话面板还会列出当前文件夹下的 pi CLI/TUI 会话（标记为 `TUI`），可以直接从 Web 界面续聊终端对话
+- 📂 **项目记忆**：记住每个浏览器上次打开的工作目录（重启后自动恢复），左侧面板有「最近项目」
+  列表可一键切换，每个项目的会话独立保存、随时回去接着问
+- ✏️ **编辑重问**：每条历史提问下方有编辑按钮，改完从该位置重新提问——服务端 fork 出一个
+  新分支会话（该问题之前的历史完整保留），原对话原样留在会话列表，随时可切回
+- ⚡ **长对话不卡**：超过 30 条消息后，早期消息自动折叠成摘要行（角色 + 首行预览 + 块计数，
+  不渲染 Markdown/思考/工具输出），点击才展开完整内容；最近 15 条始终完整显示
+- ⬇️ **一键自更新**：右上角显示当前版本，打开更新面板检查 npm 最新版，发现新版本可一键
+  `npm i -g` 升级（更新后需重启服务生效）
+- 🔄 模型与思考强度切换（与 pi TUI 一致）、新对话、中止/停止
+- 📎 Markdown 渲染：GFM 表格、语法高亮代码块、复制按钮
+- 📁 工作区感知：智能体在你指定的目录里读/改/跑代码，使用**你自己的** `~/.pi/agent` 认证、模型、技能和扩展
+- 🌐 多个浏览器客户端各自独立会话（每个 clientId 私有会话目录）
+- 🖥 内置**终端**（xterm.js + node-pty，无需 VS Code）：三栏布局——左侧**命令列表**
+  （用户自定义命令，支持 `${pwd}`，持久化在项目 `.pi/commands.json`）、中间**终端**、
+  右侧 VSCode 风格**标签条**支持多个并发 shell。通过顶栏按钮在对话/终端视图间切换。
+
+## 快速开始
+
+需要 Node.js ≥ 22.19（pi SDK 的要求；旧版 Node 加载 SDK 时会报 `Unexpected token 'with'`）
+以及一个配置好的 pi 安装（先运行一次 `pi` 登录）。
+
+```bash
+npm install
+npm run dev          # 服务端 :8787，Web UI :5173（自动代理）
+# 打开 http://localhost:5173
+```
+
+生产模式：
+
+```bash
+npm run build        # 编译服务端 (tsc) + 前端 (vite)
+npm start            # 在 http://localhost:8787 提供全部服务
+```
+
+## npm 包（安装 / 启动 / 停止 / 更新 / 卸载）
+
+包已发布到 npm：[`pi-web-ui`](https://www.npmjs.com/package/pi-web-ui)。
+
+### 安装
+
+```bash
+# 全局安装（推荐）
+npm i -g pi-web-ui
+
+# 或免安装直接跑（拉取最新版，启动在 :8787）
+npx pi-web-ui
+
+# 或安装本地 checkout（发布前测试改动用）
+npm i -g .
+```
+
+> **npm 由 pi 托管？** 如果你的 `npm` 是拦截依赖安装脚本的 pi 包装器，装完后需要批准一次
+> node-pty 的原生构建：`npm approve-scripts node-pty@1.1.0`（标准 npm 会自动完成）。
+
+### 启动
+
+```bash
+pi-web-ui                                            # 前台，http://localhost:8787
+PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui      # 自定义端口 / 工作目录
+```
+
+想后台运行或开机自启，请使用系统服务——见
+[部署与开机自启](#部署与开机自启)（systemd / launchd / Docker）。
+
+`pi-web-ui` 命令从包安装位置提供编译好的前端和 WebSocket API——不需要仓库 checkout。
+它使用**你的** `~/.pi/agent` 配置（认证/模型/技能），并把每客户端会话存在
+`<PI_WEB_CWD>/.pi-web` 下。
+
+### 停止
+
+- **前台**：在运行它的终端按 `Ctrl+C`。
+- **systemd**：`sudo systemctl stop pi-web-ui`
+- **launchd**：`launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui`
+- **Windows（计划任务）**：`pi-web-ui server stop`（或 `schtasks /End /TN pi-web-ui`；
+  停止运行中的实例，自启保留到 `server uninstall` 为止）
+- **Docker**：`docker compose stop`（停止并删除容器：`docker compose down`）
+
+（后台进程应该用系统服务管理，而不是 `nohup`——上面的服务停止命令同时会停掉并禁用自启。）
+
+### 验证 / 版本
+
+```bash
+pi-web-ui --version     # CLI 版本
+npm ls -g pi-web-ui     # 是否已安装？哪个版本？
+which pi-web-ui         # 可执行文件位置
+```
+
+### 更新
+
+```bash
+npm i -g pi-web-ui@latest   # 升级到最新发布版
+# 之后重启服务，新版本才会生效
+```
+
+### 卸载
+
+```bash
+npm uninstall -g pi-web-ui
+```
+
+卸载**不会**删除你的聊天记录：会话数据存放在 `<PI_WEB_CWD>/.pi-web`
+（或 `PI_WEB_DATA_DIR`），卸载/升级后依然保留。
+
+### 作为系统服务管理（开机自启）
+
+把服务端安装为开机自启的系统服务，可自定义端口和工作目录：
+
+```bash
+pi-web-ui server install --port 9000 --cwd /path/to/project   # 安装并启动
+pi-web-ui server status                # 运行中？自启？
+pi-web-ui server restart               # 重启（配置变更后同样用它）
+pi-web-ui server stop                  # 停止 + 禁用自启
+pi-web-ui server start                 # 重新启动
+pi-web-ui server uninstall             # 彻底移除服务
+```
+
+- **macOS** → launchd 代理（无需 sudo）：写入并加载
+  `~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist`，崩溃自动重启
+  （`KeepAlive`），日志在 `/tmp/pi-web-ui.log` / `/tmp/pi-web-ui.err`。
+- **Linux** → systemd 单元（自动 sudo）：写入
+  `/etc/systemd/system/pi-web-ui.service` 并执行 `systemctl enable --now`，
+  日志用 `journalctl -u pi-web-ui -f` 查看。
+- **Windows** → 任务计划程序：创建登录时启动的用户任务（与 launchd 代理一致；
+  通常不需要管理员，但部分机器上 `schtasks /Create` 需要提权的 PowerShell——
+  如果 `install` 报 `ERROR: Access is denied`，请用管理员 shell 重跑）。任务通过
+  `powershell.exe -WindowStyle Hidden` 运行生成在 `%APPDATA%\pi-web-ui\pi-web-ui.ps1`
+  的 PowerShell 启动器——**不会有黑色控制台窗口**常驻，没有可被误关/误杀的东西。
+  启动器设置环境变量、cd 到工作目录、启动 node，并把日志追加到
+  `%USERPROFILE%\pi-web-ui.log`。任务 XML 保存在旁边；失败会自动重启。
+  **务必显式传 `--cwd`**——任务会继承安装时 shell 的目录，而管理员 shell 默认是
+  `C:\WINDOWS\system32`，非提权任务写不进去（启动即 EPERM）。详见
+  [Windows — 任务计划程序](#windows--任务计划程序)。
+- 选项：`--port`（默认 8787 或 `$PORT`）、`--cwd`（默认 `$PI_WEB_CWD` 或当前目录）、
+  `--data-dir`（会话目录）、`--name`（自定义服务名；macOS 标签为
+  `com.xingshuyin.pi-web-ui`，自定义名变成 `com.<name>.server`）。`--print` 预览
+  生成的 unit/plist/任务文件而不实际应用。
+- 用新参数重跑 `install` 会重新生成配置并重启服务——这就是修改已装服务端口/cwd 的方式。
+
+## 配置
+
+| 环境变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `PORT` | `8787` | HTTP/WebSocket 端口 |
+| `PI_WEB_CWD` | 服务端 cwd | 智能体操作的工作区目录（读/编辑/bash/写） |
+| `PI_WEB_DATA_DIR` | `<cwd>/.pi-web` | 每客户端会话目录的存放位置 |
+| `PI_WEB_INLINE_FILE_MAX` | `12288` (12KB) | 小于等于该大小的文本附件直接内联进模型上下文；更大的文件以路径引用方式传入，模型按需用 read 工具读取（小改动省 token） |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi 配置目录（auth.json、models.json、skills、extensions） |
+
+示例——让智能体面向某个项目：
+
+```bash
+PI_WEB_CWD=/path/to/your/project npm run dev
+```
+
+## 架构
+
+```text
+Browser (React + Vite)
+   │  WebSocket JSON — 快照驱动协议 (server/protocol.ts)
+   ▼
+server/index.ts        express 静态 + ws 端点
+   │
+server/agent-service.ts   每客户端 ClientSession:
+   │   createAgentSessionRuntime({ sessionManager: SessionManager.continueRecent(cwd, sessionDir) })
+   │   session.subscribe(events) → 节流全量快照 + 实时工具增量
+   ▼
+@earendil-works/pi-coding-agent (SDK, 进程内)
+   │   ModelRuntime (auth 来自 ~/.pi/agent) · tools · extensions · skills
+   ▼
+   你的 LLM 提供商
+```
+
+关键设计点：
+
+- **快照驱动 UI。** 服务端是唯一事实源：每次 SDK 事件后调度一个节流（60 ms）的全量快照，
+  浏览器纯粹按快照渲染。重连只需重新请求 `get_state`。大载荷（工具输出、文本）在序列化时
+  做了截断（`server/serialize.ts`）。
+- **助手实时流式输出。** 进行中的消息（SDK `agent.state.streamingMessage`）被序列化进每个快照，
+  所以思考块和回答文本是**边生成边**出现在浏览器里（带闪烁光标），而不是等整轮结束才显示。
+  部分消息拿到稳定的 `stream-<ts>` id，跨快照保持挂载（展开的思考/工具块状态不丢）。
+- **按大小感知的附件。** 点击 + 把文件加入附件队列（显示在输入框上方的 chips）。发送时服务端
+  把每个文件作为独立的 custom message 附加（SDK `sendCustomMessage` + `nextTurn` asides）——
+  用户消息保持干净，每个文件渲染成自己可折叠的卡片：小文本文件（≤ `PI_WEB_INLINE_FILE_MAX`，
+  默认 12KB）直接内联，模型立即看到；更大的文件以 `<file path=...>` 引用传入，模型按需用
+  `read` 工具读取——所以附加一个 5 MB 的文件在模型真正查看前只花几个 token。图片始终以
+  image content 附加。
+- **带行号选区的文件预览。** 在右侧面板点击文件名（或其 👁 按钮）打开带行号的预览弹窗。
+  点击 / 拖拽 / Shift+点击选择行区间，然后点"添加到对话"把它作为 `lines` 附件入队——
+  服务端只内联选中的区间（`<file path=... lines="2-3">`），可以精确指向想说的代码而不必
+  倾倒整个文件。预览读取上限 512 KB，二进制文件会被检测并拒绝。
+- **实时工具输出。** `bash_execution_update` / `tool_execution_update` 事件被转发为轻量
+  `tool_delta` 消息，终端输出实时流动；最终输出在下一个快照的 toolResult 消息里到达，取代
+  delta 缓冲。
+- **隔离会话。** 每个浏览器客户端在数据目录下拥有 `sessions/<clientId>/`，重连时通过
+  `SessionManager.continueRecent` 续接。
+- **你已经拥有的一切。** 无需单独认证步骤——SDK 读取 `~/.pi/agent/auth.json` 并自动加载
+  你的全局扩展/技能。
+
+## 终端
+
+从顶栏切换终端视图（对话/终端）。它以三栏布局替代聊天界面：
+
+- **左 — 命令**：点击命令在对应目录打开终端标签页并运行。可在面板里增/改/删命令；它们保存到
+  `<project>/.pi/commands.json`（提交进仓库，与队友共享）：
+
+  ```json
+  {
+    "commands": [
+      { "name": "dev", "command": "npm run dev", "cwd": "${pwd}" },
+      { "name": "test", "command": "npm test", "cwd": "${pwd}/server" },
+      { "name": "build", "command": "npm run build", "cwd": "~/other-project" }
+    ]
+  }
+  ```
+
+  `${pwd}` 解析为智能体当前工作目录（聊天视图文件面板里显示的那个，可用 set_cwd 修改）；
+  `~` 和相对路径同样有效。命令面板顶部的 `+` 按钮新建条目。
+- **中 — 终端**：每个标签页是一个真实 PTY（macOS/Linux 是你的 `$SHELL`；Windows 是
+  PowerShell 或 cmd.exe——`$COMSPEC`）；输出实时流动，可以输入、Ctrl+C、调整大小等，和桌面
+  终端一模一样。Windows 上的 Git Bash 用户会自动拿到 `$SHELL`。
+- **右 — 终端（标签）**：VSCode 风格纵向标签条。`+` 在当前目录打开一个普通 shell。
+  关闭标签页会杀掉它的进程。
+
+说明：
+
+- 切回聊天视图时，运行中的命令继续运行。
+- 客户端的最后一个浏览器标签断开时终端会被杀掉（不留孤儿 dev server），所以断线会重置终端视图。
+
+## 协议
+
+完整 wire 格式见 `server/protocol.ts`。客户端 → 服务端：`hello`、`prompt`、`abort`、
+`new_chat`、`cycle_model`、`cycle_thinking`、`get_state`、`list_sessions`、
+`switch_session`、`list_files`、`list_models`、`set_model`、`set_thinking`、`set_cwd`、
+`complete_path`、`dialog_response`、`terminal_create`、`terminal_input`、
+`terminal_resize`、`terminal_kill`、`run_command`、`list_commands`、`save_commands`。
+服务端 → 客户端：`ready`、`snapshot`（完整 `UiState`）、`tool_delta`、`notice`、
+`terminal_output`、`terminal_exit`、`commands`。
+
+## 脚本
+
+| 脚本 | 作用 |
+| --- | --- |
+| `npm run dev` | 服务端（tsx watch）+ Vite dev server + WS 代理 |
+| `npm run build` | 类型检查 + 构建前端和服务端 |
+| `npm start` | 运行生产服务端（提供 `web/dist`） |
+| `npm run typecheck` | 双端 `tsc --noEmit` |
+| `node terminal-smoke-test.mjs` | WS 层终端/命令协议测试（先 build） |
+| `node terminal-browser-test.mjs` | 终端视图的无头浏览器 E2E（先 build） |
+
+## 部署与开机自启
+
+最快的路径：`pi-web-ui server install --port 8787 --cwd /path`——安装并让服务开机自启
+（见[作为系统服务管理（开机自启）](#作为系统服务管理开机自启)）。
+下面的手动方案保留给参考 / 非标准场景。
+
+### Docker（一条命令）
+
+```bash
+docker compose up -d     # 构建，启动在 :8787，开机自动重启
+docker compose stop      # 停止（保留容器）
+docker compose down      # 停止并删除容器
+```
+
+`docker-compose.yml` 里的 `restart: unless-stopped` 让 Docker 守护进程启动时（开机、崩溃、
+重启）把服务拉起来。挂载一个卷给 `/app/.pi-web`（会话持久化），可选地挂载你的 `~/.pi/agent`
+配置和工作区——见 `docker-compose.yml` 里的注释。
+
+### Linux — systemd
+
+```bash
+sudo npm i -g pi-web-ui
+sudo cp deploy/pi-web-ui.service /etc/systemd/system/
+# 先编辑 unit 里的 User/WorkingDirectory/Environment
+sudo systemctl daemon-reload
+sudo systemctl enable --now pi-web-ui     # 立即启动 + 每次开机启动
+sudo systemctl stop pi-web-ui             # 停止
+sudo systemctl disable pi-web-ui          # 取消开机自启
+journalctl -u pi-web-ui -f                # 日志
+```
+
+### macOS — launchd
+
+```bash
+npm i -g pi-web-ui
+cp deploy/com.xingshuyin.pi-web-ui.plist ~/Library/LaunchAgents/
+# 编辑 ProgramArguments / WorkingDirectory / PI_WEB_CWD（which pi-web-ui）
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.xingshuyin.pi-web-ui.plist
+launchctl bootout gui/$(id -u)/com.xingshuyin.pi-web-ui   # 停止 + 移除自启
+# 日志：/tmp/pi-web-ui.log、/tmp/pi-web-ui.err
+```
+
+### Windows — 任务计划程序
+
+最简路径（自动生成一切，无需手改 XML）：
+
+```bat
+npm i -g pi-web-ui
+pi-web-ui server install --port 8787 --cwd C:\path\to\project
+pi-web-ui server status
+pi-web-ui server restart
+pi-web-ui server stop        :: 停止运行中的实例（自启保留）
+pi-web-ui server uninstall   :: 彻底移除任务
+```
+
+它的做法：写入 `%APPDATA%\pi-web-ui\pi-web-ui.ps1`（一个 PowerShell 启动器：设置
+`PORT`/`PI_WEB_CWD`、cd 到工作目录、启动 node 并把输出追加到 `%USERPROFILE%\pi-web-ui.log`）
+和任务计划程序 XML，然后注册一个**登录时**任务（`schtasks /Create /XML`——你登录时运行，
+与 launchd 代理一致；通常不需要管理员，但如果遇到拒绝访问，请看下面的排障说明）。任务调用
+`powershell.exe -WindowStyle Hidden`，所以服务运行**没有黑色控制台窗口**——没有可被误关/误杀
+的东西。不实际安装即可预览两个生成文件：`pi-web-ui server install --print`。
+
+手工方案用 `deploy/pi-web-ui-task.xml`：改好路径，把文件存成 **UTF-16 LE**（schtasks 要求），
+然后 `schtasks /Create /TN "pi-web-ui" /XML pi-web-ui-task.xml /F` 和
+`schtasks /Run /TN "pi-web-ui"`。
+
+> **Windows 排障**
+>
+> - **`install` 报 `ERROR: Access is denied`（错误: 拒绝访问）**——部分机器上任务计划程序
+>   不允许非提权令牌创建任务（删除自己拥有的任务 `schtasks /Delete` 却可以，所以
+>   `server uninstall` 正常）。解决：在**管理员（提权）PowerShell** 里执行
+>   `pi-web-ui server install`。
+> - **务必显式传 `--cwd`，且指向用户可写目录。** 任务会继承安装时 shell 的当前目录作为
+>   工作目录。从提权 shell 安装且不带 `--cwd` 时，任务会注册成 `C:\WINDOWS\system32`，
+>   服务端启动时随即报
+>   `EPERM: operation not permitted, mkdir 'C:\WINDOWS\system32\.pi-web\sessions\...'`
+>   ——因为登录任务以最小权限令牌运行，无法在 `system32` 下写入。请用例如
+>   `--cwd C:\Users\<you>`（会话随之存到 `C:\Users\<you>\.pi-web`）。
+> - **修复已装坏的任务**（目录注册错的任务）：`pi-web-ui server uninstall`，然后
+>   在提权 shell 里 `pi-web-ui server install --cwd C:\Users\<you>`。
+>   用新选项重跑 `install` 也会就地重新生成任务。
+>
+> **不登录也要开机启动？** 登录任务需要交互式会话，与 launchd 代理一样。
+> 无头/常开 Windows 请用 Docker（见上）。
+
+三套模板分别使用 `KeepAlive` / `Restart=on-failure` / `RestartOnFailure`，服务崩溃后
+自动重启，并在登录/开机时自动启动。
+
+## License
+
+MIT