pi-web-ui 0.22.1 → 0.24.0

package/README.md

@@ -9,6 +9,65 @@ built-in terminal, manage models, tweak the system prompt, toggle skills and
 extensions on/off, and save/apply settings presets — all from a settings panel.
 Requires Node.js ≥ 22.19 and a configured pi install.
 
+## Features
+
+**Chat**
+
+- Streaming agent chat over WebSocket — the pi SDK runs in-process; events are pushed as snapshots (60 ms throttled) and the browser renders them.
+- Thinking blocks, tool-call cards and bash outputs with live status (running → finished · waiting for the model · duration).
+- **补充 (steer)** — send a follow-up while the agent is replying; it is queued and injected as soon as the current turn's tool calls settle (the "Interrupt" equivalent of the pi CLI).
+- **Slash commands** — `/` opens a command picker (built-in / extension / template / skill); built-ins include `/new /model /compact /cwd /thinking /resume`, plus `/help` (command list) and `/copy` (copy last reply).
+- **Multiple conversations per project** — each conversation gets its own agent runtime and keeps running in the background after you switch away; the "Running conversations" list shows stream progress and lets you switch back.
+- **Edit & re-ask** — fork any past question into a new branch and re-prompt; the original conversation stays untouched.
+- Long threads auto-collapse messages older than 30 into lazy summary rows (click to expand).
+- Question navigation — a floating rail plus per-question tags to jump between questions.
+
+**Files, images & attachments**
+
+- Three attachment modes: `inline` (≤12 KB), `reference` (path only), `lines` (selected ranges) — over-limit ones degrade automatically.
+- Paste / drag-drop / upload images — resized client-side and sent as image content when the model supports vision (warning otherwise).
+- **Vision bridge** — when the current model is text-only, images are transcribed into text evidence by an auto-discovered vision model (cached per batch; model & on/off configurable in Settings).
+- Attach arbitrary files without a workspace path — stored in a global uploads dir, inlined when small, referenced by absolute path otherwise.
+- File preview — line numbers, click/drag/Shift selection (add to chat as `lines`), GBK fallback decoding, binary hex view, media preview over HTTP with Range support, and a download button.
+- Live file tree — the server watches the listed directory (fs.watch) and re-lists on change; oversized directories show a truncation warning.
+
+**Terminal & Git**
+
+- Built-in terminal (xterm.js + node-pty) with per-client PTY management; Windows auto-selects Git Bash (busybox fallback).
+- **Source control (Git) panel** — status / branch / diff / untracked files via a hidden query terminal; commit, switch branch, push and pull run in the visible terminal and auto-switch to the terminal view.
+
+**Models & settings**
+
+- Model management — edit `models.json` in the UI and set per-provider API keys (keys/headers never leave the server).
+- Thinking level per model (only the levels the model actually supports are shown).
+- First-run setup wizard.
+- Settings panel — system prompt (append or replace), toggle skills/extensions on/off with immediate effect, save/apply/delete settings presets, and vision-bridge model & switch.
+
+**Goal mode**
+
+- Goal bar — set a target with a review model, max rounds and a lock switch.
+- Goal wizard ("AI 提炼") — turns a raw request into a concrete goal through a guided questionnaire.
+- Automatic review loop — after each turn an independent review session checks the goal against the final text and `git diff HEAD`; on fail the feedback is injected as steer until it passes (or the round cap is hit).
+
+**Background tasks**
+
+- Background-task panel — servers launched by the agent are detected via port snapshots and listed (port/pid/name); stop one or kill all.
+- Tool watchdog — a tool call running over 20 minutes is aborted automatically.
+- **Stop bash command only** — abort a running bash tool without killing the conversation.
+
+**Safety & operations**
+
+- Loopback-only by default; set `PI_WEB_HOST=0.0.0.0` for LAN / containers.
+- WebSocket Origin/Host same-authority check — cross-origin pages are rejected (403); `PI_WEB_ALLOW_ORIGINS` whitelist for reverse proxies.
+- Quiesce drain mode via a local control socket (`server status|quiesce|unquiesce`).
+- Credentials stay server-side — provider headers are never sent to the browser.
+- Sound alerts, Chinese/English UI, and a recent-projects list (click to switch workspace).
+
+**Deploy & update**
+
+- Foreground, global npm install, Docker (docker-compose), macOS launchd, Linux systemd, Windows Task Scheduler, and a desktop shortcut (`server shortcut`).
+- In-app self-update — checks the npm registry, installs and auto-restarts the service.
+
 ## Screenshots
 
 ![pi-web-ui main interface](https://cdn.jsdelivr.net/gh/xing-shuyin/pi-web-ui@main/assets/shot.jpeg)
@@ -68,8 +127,31 @@ pi-web-ui server stop                       # stop (auto-start stays)
 pi-web-ui server start                      # start again
 pi-web-ui server uninstall                  # remove the service entirely
 pi-web-ui server shortcut                   # desktop one-click launch icon
+pi-web-ui server quiesce                    # drain: refuse NEW chats/messages, let running ones finish
+pi-web-ui server unquiesce                  # reopen admission
 ```
 
+`server status` also shows live stats via a local control socket (version,
+PID, quiesce state, connected browsers, running conversations) — the same
+socket drives `quiesce`/`unquiesce`.
+
+## Security
+
+- **Loopback-only by default** — the server binds `127.0.0.1` and is not
+  reachable from the network unless you explicitly set `PI_WEB_HOST=0.0.0.0`
+  (e.g. LAN access, Docker port mapping — the compose file sets it for you).
+- **WebSocket origin check** — browser pages connecting to `/ws` must present
+  an `Origin` whose hostname **and port** match the request `Host`;
+  cross-origin pages are rejected with 403. Non-browser clients (no `Origin`)
+  are unaffected. Add `PI_WEB_ALLOW_ORIGINS=http://your-host:port` for
+  reverse-proxy setups.
+- **Quiesce** — `server quiesce` refuses new prompts/forks/session resumes
+  until you `server unquiesce`; in-flight runs finish cleanly (useful before
+  upgrades/backups).
+- **Credentials stay server-side** — provider `headers` (which may carry
+  `Authorization` / API keys) are never sent to the browser; the model
+  management UI edits everything else and the server preserves the headers.
+
 - **macOS** → launchd agent (no sudo), logs to `/tmp/pi-web-ui.log` / `.err`
 - **Linux** → systemd unit (`systemctl enable --now`), logs via `journalctl -u pi-web-ui -f`
 - **Windows** → Task Scheduler logon task (hidden PowerShell window, no black console)
@@ -82,3 +164,4 @@ port/cwd.
 ## License
 
 MIT
+

package/README.zh-CN.md

@@ -7,6 +7,65 @@
 模型管理，以及设置面板（自定义系统提示词、技能/插件开关、设置预设一键应用）等功能。
 需要 Node.js ≥ 22.19 及配置好的 pi 环境。
 
+## 功能特性
+
+**对话**
+
+- WebSocket 流式聊天 —— pi SDK 在服务端进程内运行，事件以快照（60ms 节流）推送，浏览器按快照渲染。
+- 思考块、工具调用卡片、bash 输出，实时显示状态（执行中 → 已结束 · 等模型 · 耗时）。
+- **补充（steer）** —— 回复流式中可排队发送跟进消息，当前回合工具结算后立即注入（对应 pi CLI 的 Enter 打断语义）。
+- **斜杠命令** —— 输入 `/` 弹出命令选择器（内置 / 扩展 / 模板 / 技能）；内置 `/new /model /compact /cwd /thinking /resume`，另有 `/help`（命令清单）与 `/copy`（复制上一条回复）。
+- **每项目多对话并发** —— 每个对话独立 agent runtime，切走后仍在后台运行；「运行的对话」列表显示流式进度，可随时切回。
+- **编辑重问** —— 把任意历史问题 fork 成新分支重新提问，原对话不受影响。
+- 超过 30 条的消息自动折叠为摘要行（惰性渲染，点击展开）。
+- 问题导航 —— 右侧浮动导航条 + 每个问题顶部的序号标签，一键跳转。
+
+**文件、图片与附件**
+
+- 三种附件模式：`inline`（≤12KB 内联）、`reference`（仅路径引用）、`lines`（选中行），超限自动降级。
+- 粘贴 / 拖拽 / 上传图片 —— 浏览器端自动缩放，模型支持识图时作为图片内容发送（不支持时提示警告）。
+- **视觉桥** —— 当前模型不支持识图时，把图片交给自动发现的视觉模型转写成文字证据（按批次缓存，可在设置里指定模型/开关）。
+- 免工作区路径附加任意文件 —— 存入全局上传目录，小文件内联，其余以绝对路径引用。
+- 文件预览 —— 行号、点选/拖拽/Shift 选区（可添加到对话为 lines 附件）、GBK 回退解码、二进制十六进制视图、媒体 HTTP 预览（支持 Range）、下载按钮。
+- 实时文件树 —— 服务端对当前列出目录 fs.watch，改动即静默重列；超大目录显示截断提示。
+
+**终端与 Git**
+
+- 内置终端（xterm.js + node-pty），每客户端独立 PTY 管理；Windows 自动选择 Git Bash（busybox 兜底）。
+- **源代码管理（Git）面板** —— 经隐藏查询终端展示 status / branch / diff / 未跟踪文件；提交、切换分支、推送、拉取复用可见终端并自动切换到终端视图。
+
+**模型与设置**
+
+- 模型管理 —— UI 里编辑 models.json、按 provider 设置 API key（密钥/headers 永不下发浏览器）。
+- 思考强度（thinking level）按模型切换（只显示该模型实际支持的档位）。
+- 首次配置引导（PiSetupModal）。
+- 设置面板 —— 系统提示词（追加或整体替换）、技能/插件一键开关（即时生效）、设置预设保存/应用/删除、视觉桥模型与开关。
+
+**目标（Goal）模式**
+
+- GoalBar 目标栏 —— 设置目标 + 审查模型 + 最大轮数 + 锁定开关。
+- 目标调研向导（「AI 提炼」）—— 通过引导式问卷把原始需求收敛成明确目标。
+- 自动审查循环 —— 每轮结束后用独立审查会话核对「目标 + 最终文本 + git diff HEAD」；不达标就把审查意见作为 steer 注入重改，直到通过或达到轮数上限。
+
+**后台任务**
+
+- 后台任务面板 —— 通过端口快照检测 agent 启动的服务（端口/pid/名称），可单独停止或全部关闭。
+- 工具看门狗 —— 单个工具调用超过 20 分钟自动中断会话。
+- **只停止 bash 命令** —— 中止运行中的 bash 工具而不打断对话。
+
+**安全与运维**
+
+- 默认只绑 loopback；局域网 / 容器需显式 `PI_WEB_HOST=0.0.0.0`。
+- WebSocket Origin/Host 同权威校验 —— 跨源页面直接拒绝（403）；反代场景用 `PI_WEB_ALLOW_ORIGINS` 白名单。
+- 本地控制 socket 提供 `server status|quiesce|unquiesce`（排空模式：拒绝新工作、存量跑完）。
+- 凭据不下发浏览器 —— provider headers（可能含 Authorization/API key）永不发送到前端。
+- 声音提醒、中英文界面、最近项目列表（点击即切换工作目录）。
+
+**部署与更新**
+
+- 前台运行 / 全局 npm 安装 / Docker（docker-compose）/ macOS launchd / Linux systemd / Windows 计划任务 / 桌面快捷方式（`server shortcut`）。
+- 界面内自更新 —— 对比 npm registry 版本，安装后自动重启服务。
+
 ## 界面截图
 
 ![pi-web-ui 主界面](https://cdn.jsdelivr.net/gh/xing-shuyin/pi-web-ui@main/assets/shot.jpeg)
@@ -64,8 +123,25 @@ pi-web-ui server stop                       # 停止（开机自启保留）
 pi-web-ui server start                      # 再次启动
 pi-web-ui server uninstall                  # 彻底移除服务
 pi-web-ui server shortcut                   # 桌面一键启动图标
+pi-web-ui server quiesce                    # 排空：拒绝新的对话/消息，存量运行继续跑完
+pi-web-ui server unquiesce                  # 解除排空，恢复接收新工作
 ```
 
+`server status` 还会经本地控制 socket 显示实时状态（版本、PID、排空状态、
+浏览器连接数、运行中对话数）——`quiesce`/`unquiesce` 也走同一个 socket。
+
+## 安全
+
+- **默认只绑 loopback** —— 服务器只监听 `127.0.0.1`，不暴露到网络；需要局域网访问或
+  Docker 端口映射时显式设置 `PI_WEB_HOST=0.0.0.0`（docker-compose.yml 已内置）。
+- **WebSocket Origin 校验** —— 浏览器页面连 `/ws` 时其 Origin 的 hostname **和端口**
+  必须与请求 Host 一致，跨源页面直接 403；无 Origin 的非浏览器客户端不受影响。
+  反向代理场景可用 `PI_WEB_ALLOW_ORIGINS=http://你的域名:端口` 放行。
+- **Quiesce 排空** —— `server quiesce` 后拒绝新的 prompt/编辑重问/会话恢复，存量运行
+  跑完为止（升级/备份前用）；`server unquiesce` 恢复。
+- **凭据不下发浏览器** —— provider 的 `headers`（可能含 Authorization / API key）
+  永不发给浏览器；模型管理 UI 编辑其他字段，服务端自动保留 headers。
+
 - **macOS** → launchd 代理（无需 sudo），日志 `/tmp/pi-web-ui.log` / `.err`
 - **Linux** → systemd unit（`systemctl enable --now`），日志 `journalctl -u pi-web-ui -f`
 - **Windows** → 计划任务（登录自启，隐藏 PowerShell 窗口，无黑窗）

package/bin/pi-web-ui.mjs

@@ -23,6 +23,7 @@
  * PI_CODING_AGENT_DIR。
  */
 import { spawnSync } from "node:child_process";
+import { createConnection } from "node:net";
 import { get as httpGet } from "node:http";
 import {
 	chmodSync,
@@ -60,6 +61,8 @@ const HELP = `pi-web-ui v${pkg.version} — web chat for the pi coding agent
   pi-web-ui server shortcut [选项]        在桌面创建「一键启动」图标（启动服务并打开浏览器）
   pi-web-ui server uninstall [选项]       卸载系统服务（同时移除桌面图标）
   pi-web-ui server start|stop|restart|status [选项]
+  pi-web-ui server quiesce [选项]          进入排空模式：拒绝新的对话/消息/编辑，存量运行继续跑完
+  pi-web-ui server unquiesce [选项]        解除排空模式，恢复接收新工作
   pi-web-ui --version / --help
 
 server 选项:
@@ -1069,6 +1072,90 @@ function uninstallWindows(opts) {
 	console.log(`🗑  已移除桌面快捷方式`);
 }
 
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Local control socket (status / quiesce / unquiesce). The server listens on
+// a mode-0600 Unix socket (POSIX) or a named pipe (Windows) under its data
+// dir; same path rules as server/control-socket.ts so the CLI and server
+// always agree without sharing code.
+// ---------------------------------------------------------------------------
+
+/** Resolve the control socket path for the given options. */
+function controlPath(opts) {
+	const dir = opts.dataDir
+		? resolve(opts.dataDir)
+		: process.env.PI_WEB_DATA_DIR
+			? resolve(process.env.PI_WEB_DATA_DIR)
+			: join(homedir(), ".pi-web");
+	return isWin
+		? `\\\\.\\pipe\\pi-web-ui-${String(opts.port ?? process.env.PORT ?? "8787")}`
+		: join(dir, "pi-web-ui.sock");
+}
+
+/** Send one control command to a RUNNING server; resolves null if unreachable. */
+function controlCommand(opts, cmd) {
+	const path = controlPath(opts);
+	return new Promise((resolvePromise) => {
+		const sock = createConnection(path);
+		let done = false;
+		const finish = (v) => {
+			if (done) return;
+			done = true;
+			clearTimeout(timer);
+			sock.destroy();
+			resolvePromise(v);
+		};
+		const timer = setTimeout(() => finish(null), 3000);
+		let buf = "";
+		sock.on("connect", () => sock.write(JSON.stringify({ cmd }) + "\n"));
+		sock.on("data", (chunk) => {
+			buf += chunk.toString("utf8");
+			const nl = buf.indexOf("\n");
+			if (nl >= 0) {
+				try {
+					finish(JSON.parse(buf.slice(0, nl)));
+				} catch {
+					finish(null);
+				}
+			}
+		});
+		sock.on("error", () => finish(null));
+		sock.on("close", () => finish(null));
+	});
+}
+
+/** Append the live server status (via the control socket) to `server status`. */
+async function printLiveStatus(opts) {
+	const st = await controlCommand(opts, "status");
+	if (!st || !st.ok) {
+		console.log("   (服务器未运行或控制通道不可达 — 启动后可查 server status 实时信息)");
+		return;
+	}
+	console.log("   --- 实时状态 (control socket) ---");
+	console.log(`   版本 : ${st.version} · PID ${st.pid}`);
+	console.log(`   目录 : ${st.cwd}`);
+	console.log(
+		`   排空 : ${st.quiesced ? `是（自 ${new Date(st.quiescedSince).toLocaleString()}）` : "否"}`,
+	);
+	console.log(
+		`   连接 : ${st.connectedClients} 个浏览器 · ${st.activeConversations} 个运行中对话 · ${st.pendingMessages} 条排队消息`,
+	);
+}
+
+/** `server quiesce|unquiesce` — toggle the admission gate on a RUNNING server. */
+async function setQuiesce(opts, on) {
+	const st = await controlCommand(opts, on ? "quiesce" : "unquiesce");
+	if (!st || !st.ok) {
+		fail(`服务器未运行或控制通道不可达（${controlPath(opts)}）`);
+	}
+	console.log(
+		on
+			? "⏸  已进入排空模式（quiesce）：拒绝新的对话/消息/编辑，存量运行继续跑完。\n" +
+				"    跑完后用 pi-web-ui server unquiesce 恢复。"
+			: "▶  已解除排空模式（unquiesce）：恢复接收新的对话/消息/编辑。",
+	);
+}
+
 function controlService(action, opts) {
 	const name = opts.name ?? "pi-web-ui";
 
@@ -1279,12 +1366,21 @@ async function serverCmd(argv) {
 		case "start":
 		case "stop":
 		case "restart":
-		case "status":
 			controlService(action, opts);
 			break;
+		case "status":
+			controlService("status", opts);
+			await printLiveStatus(opts);
+			break;
+		case "quiesce":
+			await setQuiesce(opts, true);
+			break;
+		case "unquiesce":
+			await setQuiesce(opts, false);
+			break;
 		default:
 			fail(
-				`未知操作: ${action}（install / shortcut / uninstall / start / stop / restart / status）`,
+				`未知操作: ${action}（install / shortcut / uninstall / start / stop / restart / status / quiesce / unquiesce）`,
 			);
 	}
 }