pi-web-ui 0.15.6 → 0.16.1

package/README.zh-CN.md

@@ -1,367 +1,71 @@
-# 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 附加。
-- **图片问答。** 除了从右侧文件树附加工作区图片，还可以**直接粘贴截图（Ctrl+V）、把图片拖到
-  输入框、或点输入框的 🖼 按钮上传**——浏览器先把图片等比缩到 ≤1568px 再编码，图片随消息
-  发送（`prompt.attachments[].imageData` base64），无需存在于工作区。当前模型不支持识图时
-  会提示；非识图模型看不到图片。
-- **文件对话。** 任意本地文件（文本/二进制）也可以直接**拖入输入框或用 📎 按钮上传**——浏览器
-  把内容以 base64 发送（`prompt.attachments[].fileData`），服务端存到 `~/.pi-web/uploads/<clientId>/`
-  并作为附件附加：小文本文件直接内联给模型看，大文件/二进制以绝对路径引用（模型的 read 工具
-  支持绝对路径，可按需读取）；上限 20MB。
-- **带行号选区的文件预览。** 在右侧面板点击文件名（或其 👁 按钮）打开带行号的预览弹窗。
-  点击 / 拖拽 / 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 在服务端进程内运行，
+事件经 WebSocket 流式推送到浏览器。支持思考块与工具调用、附件与图片问答、内置终端、
+模型管理等功能。需要 Node.js ≥ 22.19 及配置好的 pi 环境。
+
+## 界面截图
+
+![pi-web-ui 主界面](assets/shot.jpeg)
+
+## 安装
+
+```bash
+npm i -g pi-web-ui            # 全局安装（推荐）
+npx pi-web-ui                 # 或免安装直接跑（拉取最新版，启动在 :8787）
+npm i -g .                    # 或安装本地 checkout
+```
+
+## 启动
+
+```bash
+pi-web-ui                                           # 前台，http://localhost:8787
+PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui     # 自定义端口 / 工作目录
+```
+
+## 停止
+
+- **前台**：在运行它的终端里按 `Ctrl+C`。
+- **作为服务**：`pi-web-ui server stop`（停止实例；开机自启保留，直到 `server uninstall`）。
+
+## 更新
+
+```bash
+npm i -g pi-web-ui@latest     # 升级到最新发布版本
+pi-web-ui server restart      # 重启服务使新版本生效（前台运行则手动重启）
+```
+
+## 卸载
+
+```bash
+npm uninstall -g pi-web-ui
+```
+
+卸载**不会**删除你的聊天记录 —— 会话数据存放在 `<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                  # 彻底移除服务
+pi-web-ui server shortcut                   # 桌面一键启动图标
+```
+
+- **macOS** → launchd 代理（无需 sudo），日志 `/tmp/pi-web-ui.log` / `.err`
+- **Linux** → systemd unit（`systemctl enable --now`），日志 `journalctl -u pi-web-ui -f`
+- **Windows** → 计划任务（登录自启，隐藏 PowerShell 窗口，无黑窗）
+
+选项：`--port`（默认 8787）、`--cwd`（工作目录）、`--data-dir`（会话目录）、
+`--name`（自定义服务名）。重复执行 `server install` 并传入新选项即可重新生成配置
+并重启服务 —— 这就是修改已装服务端口/工作目录的方式。
+
+## License
+
+MIT

package/dist/server/agent-service.js

@@ -11,7 +11,7 @@
  * so reconnects just re-request a snapshot.
  */
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, } from "node:fs";
+import { existsSync, readFileSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, getAgentDir, SessionManager, } from "@earendil-works/pi-coding-agent";
@@ -728,6 +728,14 @@ export class ClientSession {
     disposed = false;
     /** pi-config readiness check, cached briefly so 60ms snapshots don't hit disk. */
     piCheckCache = null;
+    /** fs.watch on the currently-listed directory — file changes push an instant
+     *  refresh (`file_changed`) so the tree updates without waiting for the 10s
+     *  poll. Only the listed directory is watched (one level); navigating
+     *  re-watches the new target. fs.watch isn't available on every platform /
+     *  filesystem — failures silently fall back to the poll. */
+    fsWatcher = null;
+    watchPath = null;
+    watchTimer = null;
     constructor(clientId, cwd, agentDir, stateStore) {
         this.clientId = clientId;
         this.cwd = cwd;
@@ -829,8 +837,11 @@ export class ClientSession {
         this.sinks.delete(send);
         // No sockets left for this client — kill its terminals so processes don't
         // survive a closed tab / dropped connection.
-        if (this.sinks.size === 0)
+        if (this.sinks.size === 0) {
             this.terminals.killAll();
+            // No sockets → nobody to refresh; drop the dir watcher too.
+            this.unwatchDir();
+        }
     }
     /** Broadcast to every connected socket of this client. */
     emit(msg) {
@@ -2432,6 +2443,9 @@ export class ClientSession {
             // always use "/", but relative() returns "\\" on Windows.
             const rel = rawRel.split(sep).join("/");
             const { entries, truncated, error } = await readDirForUI(target, rel);
+            // Watch the listed directory (only after a successful read — a missing
+            // dir throws above and must not create a watcher on a phantom path).
+            this.watchDir(target, rel);
             if (error) {
                 // Windows-only: unreadable system dirs degrade to an empty list
                 // with a warning instead of a hard error — the panel stays usable.
@@ -2461,6 +2475,56 @@ export class ClientSession {
             });
         }
     }
+    /** Watch a directory for changes so the file panel refreshes instantly
+     *  instead of waiting for the 10s poll. Watches the directory exactly as
+     *  listed (one level); navigating re-watches the new target. fs.watch is
+     *  unavailable on some platforms/filesystems — failures silently fall back
+     *  to the poll. */
+    watchDir(absPath, rel) {
+        if (this.disposed || this.watchPath === rel)
+            return;
+        this.unwatchDir();
+        this.watchPath = rel;
+        try {
+            // persistent: false — the watcher must not keep the process alive.
+            this.fsWatcher = watch(absPath, { persistent: false }, () => {
+                // Burst events (npm install, git ops, editor save→rename) are
+                // debounced into a single refresh.
+                if (this.watchTimer)
+                    return;
+                this.watchTimer = setTimeout(() => {
+                    this.watchTimer = null;
+                    this.emit({ type: "file_changed", path: this.watchPath ?? "" });
+                }, 400);
+            });
+            this.fsWatcher.on("error", () => {
+                // Directory deleted / unsupported fs — stop watching; the poll (or
+                // the next navigation) restores things.
+                this.unwatchDir();
+            });
+        }
+        catch {
+            // fs.watch unsupported (some network mounts, containers) — poll covers it.
+            this.fsWatcher = null;
+            this.watchPath = null;
+        }
+    }
+    unwatchDir() {
+        if (this.watchTimer) {
+            clearTimeout(this.watchTimer);
+            this.watchTimer = null;
+        }
+        if (this.fsWatcher) {
+            try {
+                this.fsWatcher.close();
+            }
+            catch {
+                // already closed
+            }
+            this.fsWatcher = null;
+        }
+        this.watchPath = null;
+    }
     /** Read a workspace file for the preview panel (size-capped, binary-safe). */
     async readFile(relPath) {
         try {
@@ -2827,6 +2891,7 @@ export class ClientSession {
             clearInterval(this.widgetsTimer);
             this.widgetsTimer = null;
         }
+        this.unwatchDir();
         this.webUi.dispose();
         for (const conv of this.convs.values()) {
             conv.unsubscribe?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-web-ui",
-  "version": "0.15.6",
+  "version": "0.16.1",
   "description": "Web chat interface for the pi coding agent, powered by the pi SDK (@earendil-works/pi-coding-agent) — one-command run, Docker/systemd/launchd deployable",
   "license": "MIT",
   "type": "module",