pi-web-ui 0.44.1 → 0.45.0

package/README.md

@@ -1,20 +1,33 @@
-# pi-web-ui
+<div align="center">
 
-**English** | [简体中文](https://github.com/xing-shuyin/pi-web-ui/blob/main/README.zh-CN.md)
+# 💬 pi-web-ui
 
-[![npm version](https://img.shields.io/npm/v/pi-web-ui?color=cb3837&logo=npm)](https://www.npmjs.com/package/pi-web-ui)
-[![Node.js](https://img.shields.io/node/v/pi-web-ui?logo=node.js&logoColor=white)](https://nodejs.org/)
-[![License](https://img.shields.io/github/license/xing-shuyin/pi-web-ui)](LICENSE)
+**English** | [Chinese (Simplified)](https://github.com/xing-shuyin/pi-web-ui/blob/main/README.zh-CN.md)
 
-> A polished browser interface for pi: stream conversations, inspect tools, manage files,
-> and run your workspace from one place.
+*The polished browser cockpit for the [pi coding agent](https://pi.dev).*
 
-A web chat interface for the [pi coding agent](https://pi.dev) — the agent runs
-in-process via the pi SDK and streams events to the browser over WebSocket. Chat
-with thinking blocks and tool calls, attach files, ask about images, use a
-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.
+<p>
+  <a href="https://www.npmjs.com/package/pi-web-ui"><img src="https://img.shields.io/npm/v/pi-web-ui?color=cb3837&logo=npm&label=pi-web-ui" alt="npm version"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/pi-web-ui?logo=node.js&logoColor=white" alt="Node.js"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/xing-shuyin/pi-web-ui" alt="License"></a>
+  <a href="https://www.npmjs.com/package/pi-web-ui"><img src="https://img.shields.io/npm/dm/pi-web-ui?label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/xing-shuyin/pi-web-ui/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/xing-shuyin/pi-web-ui/ci.yml?branch=main&label=CI" alt="CI status"></a>
+  <a href="https://github.com/xing-shuyin/pi-web-ui/stargazers"><img src="https://img.shields.io/github/stars/xing-shuyin/pi-web-ui?style=social" alt="GitHub stars"></a>
+  <a href="https://github.com/xing-shuyin/pi-web-ui/fork"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat" alt="PRs welcome"></a>
+</p>
+
+Stream conversations, inspect tool calls, manage files, and run your workspace — all from one place.
+
+![Git source control panel](https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot4.jpeg)
+
+</div>
+
+A web chat interface for the [pi coding agent](https://pi.dev). The agent runs
+**in-process** via the pi SDK and streams events to the browser over WebSocket:
+thinking blocks, tool calls, file trees, a built-in terminal, model management,
+theme switching, and a full settings panel — tuned for daily development.
+
+> **Requirements** — Node.js ≥ 22.19 and a configured pi install.
 
 ## More from the author
 
@@ -22,34 +35,54 @@ Requires Node.js ≥ 22.19 and a configured pi install.
 >
 > [**dsh-ui-tools**](https://github.com/xing-shuyin/dsh-ui-tools) is the author's companion project for building and extending UI tools in the DSH ecosystem.
 
+## ✨ Highlights
+
+| 💬 **Chat that works like you do** | 🖼️ **Files & images** | 🧩 **Extensible by design** | 🔒 **Private by default** |
+| --- | --- | --- | --- |
+| Streaming replies, steer & follow-up queueing, slash commands, multiple conversations per project, edit-&-re-ask. | Attach files, paste images, ask about pictures (vision bridge), preview anything with GBK fallback. | Drop-in UI **plugins** (extra top-bar tabs + agent tools) and standalone **themes** — no rebuild, no restart. | Loopback-only, credential-safe: provider keys & headers never reach the browser. |
+
+## 📚 Table of Contents
+
+- 🚀 [Features](#features)
+- 🖼️ [Screenshots](#screenshots)
+- 📦 [Install](#install)
+- ⚡ [Quick start](#quick-start)
+- 🖥️ [System service](#system-service)
+- 🧩 [Plugins](#plugins)
+- 🎨 [Themes](#themes)
+- 🔒 [Security](#security)
+- 🌐 [Reverse proxy (nginx)](#reverse-proxy-nginx)
+- 🤝 [Contribute](#contribute)
+- 📄 [License](#license)
+
 ## Features
 
-**Chat**
+### 💬 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.
+- **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).
+- **Steer (follow-up queueing)** — 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**
+### 🖼️ 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.
+- Live file tree — the server watches the listed directory (`fs.watch`) and re-lists on change; oversized directories show a truncation warning.
 
-**Terminal & Git**
+### 🖥️ 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**
+### 🎛️ Models & settings
 
 - Theme switching — pick a theme in the top bar; each theme is a full standalone stylesheet (default dark + a bundled light). See [Themes](#themes) for how to add your own or contribute one.
 - Model management — edit `models.json` in the UI and set per-provider API keys (keys/headers never leave the server).
@@ -57,19 +90,19 @@ Requires Node.js ≥ 22.19 and a configured pi install.
 - 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 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.
+- Goal wizard (**AI Refine**) — 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 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**
+### 🛡️ 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.
@@ -77,20 +110,25 @@ Requires Node.js ≥ 22.19 and a configured pi install.
 - 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**
+### 🚢 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
-
-![Settings panel](https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot1.png)
 
-![Built-in terminal](https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot2.jpeg)
+## Screenshots
 
-![Chat interface](https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot3.jpeg)
+<table>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot1.png" alt="Settings panel"><br><sub>Settings panel</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot2.jpeg" alt="Built-in terminal"><br><sub>Built-in terminal</sub></td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot3.jpeg" alt="Chat interface"><br><sub>Chat interface</sub></td>
+    <td align="center"><img src="https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot4.jpeg" alt="Git source control panel"><br><sub>Git source control panel</sub></td>
+  </tr>
+</table>
 
-![Git source control panel](https://raw.githubusercontent.com/xing-shuyin/pi-web-ui/main/assets/shot4.jpeg)
 
 ## Install
 
@@ -109,26 +147,29 @@ silences the warning):
 npm i -g --allow-scripts=node-pty,@google/genai,protobufjs pi-web-ui@latest
 ```
 
-## Start
+
+## Quick start
+
+**Start**
 
 ```bash
 pi-web-ui                                           # foreground, http://localhost:8787
 PORT=9000 PI_WEB_CWD=/path/to/project pi-web-ui     # custom port / workspace
 ```
 
-## Stop
+**Stop**
 
 - **Foreground**: press `Ctrl+C` in the terminal running it.
 - **As a service**: `pi-web-ui server stop` (stops the instance; auto-start stays until `server uninstall`).
 
-## Update
+**Update**
 
 ```bash
 npm i -g pi-web-ui@latest     # upgrade to the latest published version
 pi-web-ui server restart      # restart the service to apply it (foreground: restart manually)
 ```
 
-## Uninstall
+**Uninstall**
 
 ```bash
 npm uninstall -g pi-web-ui
@@ -137,7 +178,8 @@ npm uninstall -g pi-web-ui
 Uninstalling does **not** delete your chats — session data lives in
 `<cwd>/.pi-web` (or `PI_WEB_DATA_DIR`) and survives uninstall/upgrade.
 
-## Run as a system service (auto-start on boot)
+
+## System service
 
 ```bash
 pi-web-ui server install --port 9000 --cwd /path/to/project   # install + start
@@ -164,7 +206,8 @@ Options: `--port` (default 8787), `--cwd` (workspace), `--data-dir` (sessions),
 regenerates the config and restarts the service — that's how you change its
 port/cwd.
 
-## Plugins (UI extensions)
+
+## Plugins
 
 Plugins are optional UI components (extra top-bar tabs backed by their own
 client view, optionally with a server-side entry and agent tools). They live in
@@ -257,6 +300,7 @@ pi-web-ui uninstall <id>      # remove a plugin
   disappears. Plugin configuration written inside the plugin dir is removed
   too — back up `<dataDir>/plugins/<id>/config.json` first if you need it.
 
+
 ## Themes
 
 Each theme is a **complete standalone stylesheet** — a full copy of the bundled dark `web/src/styles.css` with a different palette (no CSS-variable extraction, no base file to include). Picking a theme swaps the whole file, so any theme works with every build.
@@ -299,6 +343,7 @@ Want your theme shipped to everyone? Open a pull request at [github.com/xing-shu
 
 Rules for merged themes: the file must be a single self-contained CSS file, be a full standalone theme (no imports of the base `styles.css`), set the `--term-*` variables for a readable terminal, and override `.hljs` syntax colors for readable code.
 
+
 ## Security
 
 - **Loopback-only by default** — the server binds `127.0.0.1` and is not
@@ -316,6 +361,7 @@ Rules for merged themes: the file must be a single self-contained CSS file, be a
   `Authorization` / API keys) are never sent to the browser; the model
   management UI edits everything else and the server preserves the headers.
 
+
 ## Reverse proxy (nginx)
 
 Serve pi-web-ui behind nginx on the same host (it binds loopback only, so a
@@ -382,7 +428,31 @@ Key points:
 
 Full working example (with an frp tunnel): `deploy/nginx-subpath.conf`.
 
-## License
 
-MIT
+## Contribute
+
+pi-web-ui is a small open-source project — **your contributions are what make it grow**. Code, plugins, themes, docs, translations, ideas: everything is welcome, and every merged PR ships to all users with the next `npm publish`. ❤️
+
+| Way to contribute | How to get started |
+| --- | --- |
+| 🧩 **Write a plugin** | Build your own UI tab + agent tools. Copy `dev/plugins/demo-mailbox` as the minimal template (it doubles as the test fixture), develop locally, then either open a PR to ship it in the [catalog](#plugin-catalog) or [publish it standalone](https://github.com/xing-shuyin/pi-web-ui/tree/main/dev/plugins). |
+| 🎨 **Contribute a theme** | Copy `themes/light.css` as a self-contained template, tweak the `:root` palette + `--term-*` + `.hljs`, verify with `npm run dev`, then open a PR — full walkthrough in [Contributing a theme](#contributing-a-theme-to-the-repository-github). |
+| 💻 **Fix a bug / add a feature** | Look for [open issues](https://github.com/xing-shuyin/pi-web-ui/issues) or propose something new. Fork → branch → PR. Keep the code conventions in `AGENTS.md` (tabs, i18n keys in both languages, protocol changes in `server/protocol.ts`). |
+| 📖 **Docs & translations** | Improve the READMEs, write plugin docs, fix typos, or help translate the UI / docs into more languages. |
+| 💡 **Ideas & feedback** | Open an [issue](https://github.com/xing-shuyin/pi-web-ui/issues) or start a [discussion](https://github.com/xing-shuyin/pi-web-ui/discussions) — feature requests, bug reports, UI polish ideas, deployment experience reports. |
+
+**Before opening a PR**, a quick sanity pass keeps reviewers happy:
+
+- `npm run check:protocol` + `npm test` — protocol sync and unit tests.
+- `npm run typecheck` — no type errors.
+- `npm run build` — both frontend and backend compile.
+- For protocol changes: add branches in both `server/index.ts` and `web/src/use-chat.ts` (see the "Protocol single source" note in `AGENTS.md`).
+
+> Enjoying pi-web-ui? Give the repo a ⭐ — it helps others find it. And if you
+> built something cool on top (plugin, theme, deployment recipe), tell us — we
+> love showcasing community work.
+
+
+## License
 
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -354,6 +354,27 @@ server {
 
 带 frp 内网穿透的完整可运行示例：`deploy/nginx-subpath.conf`。
 
+## 参与贡献
+
+pi-web-ui 是一个小型开源项目 —— **你的贡献就是它成长的力量**。代码、插件、主题、文档、翻译、想法，统统欢迎；每一个合并的 PR 都会随下一次 `npm publish` 送达所有用户。❤️
+
+| 贡献方式 | 如何开始 |
+| --- | --- |
+| 🧩 **写插件** | 打造你自己的界面 tab + AI 工具。以 `dev/plugins/demo-mailbox` 为最小模板（它兼作测试夹具），本地开发后既可开 PR 收录进[插件目录](#插件目录)，也可独立发布。 |
+| 🎨 **贡献主题** | 以 `themes/light.css` 为自包含模板，调整 `:root` 配色 + `--term-*` + `.hljs`，用 `npm run dev` 验证后开 PR —— 完整步骤见[向仓库贡献主题](#向仓库贡献主题github)。 |
+| 💻 **修 bug / 加功能** | 在 [Issues](https://github.com/xing-shuyin/pi-web-ui/issues) 里挑一个，或提出新想法。Fork → 分支 → PR。代码约定见 `AGENTS.md`（Tab 缩进、i18n 双语 key、协议改动只动 `server/protocol.ts`）。 |
+| 📖 **文档与翻译** | 完善 README、补插件文档、改错别字，或帮忙把界面/文档翻译成更多语言。 |
+| 💡 **想法与反馈** | 在 [Issues](https://github.com/xing-shuyin/pi-web-ui/issues) 或 [Discussions](https://github.com/xing-shuyin/pi-web-ui/discussions) 里开帖 —— 功能建议、bug 报告、界面优化点子、部署经验分享都欢迎。 |
+
+**开 PR 前**，快速自检能让维护者更省心：
+
+- `npm run check:protocol` + `npm test` —— 协议同步与单元测试。
+- `npm run typecheck` —— 无类型错误。
+- `npm run build` —— 前后端都能编译。
+- 涉及协议改动：`server/index.ts` 与 `web/src/use-chat.ts` 两端 dispatch 都要加分支（详见 `AGENTS.md`「协议单源」）。
+
+> 喜欢 pi-web-ui？给仓库点个 ⭐，帮助更多人发现它。如果你在上面做了很酷的东西（插件、主题、部署方案），记得告诉我们 —— 我们乐于展示社区作品。
+
 ## License
 
 MIT

package/dist/server/agent-service.js

@@ -10,7 +10,7 @@
  * snapshots. The frontend is snapshot-driven (server is the source of truth),
  * so reconnects just re-request a snapshot.
  */
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, readFileSync, rmSync, statSync, writeFileSync, mkdirSync, watch, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -550,6 +550,8 @@ export class ClientSession {
             flushSnapshot: () => this.flushSnapshot(),
             isDisposed: () => this.disposed,
             getSession: () => this.session,
+            cwd: () => this.cwd,
+            agentDir: () => this.agentDir,
             isStreaming: () => this.session.isStreaming,
             reloadSession: async () => {
                 await this.session.reload();
@@ -1251,6 +1253,7 @@ export class ClientSession {
             tools: state.tools.map((t) => t.name),
             version: ++this.version,
             piConfigured: this.isPiConfigured(),
+            piAgentInstalled: this.isPiCliInstalled(),
             stats,
         };
     }
@@ -1336,6 +1339,38 @@ export class ClientSession {
         this.piCheckCache = { at: now, configured };
         return configured;
     }
+    /**
+     * Whether the pi CLI binary is installed and runnable (`pi --version`
+     * probe). Cached machine-wide (same binary for every client) for 10s —
+     * the check is only rerun after install or when the cache expires.
+     */
+    static piCliProbe = null;
+    static PI_CLI_PROBE_TTL_MS = 10_000;
+    isPiCliInstalled() {
+        const now = Date.now();
+        const cached = ClientSession.piCliProbe;
+        if (cached && now - cached.at < ClientSession.PI_CLI_PROBE_TTL_MS)
+            return cached.installed;
+        let installed = false;
+        try {
+            const res = spawnSync("pi", ["--version"], {
+                timeout: 5000,
+                stdio: "ignore",
+                // Windows: `pi` resolves to a pi.cmd shim — spawnSync can only
+                // exec those through a shell (else ENOENT).
+                shell: process.platform === "win32",
+            });
+            installed = !res.error && res.status === 0;
+        }
+        catch {
+            installed = false;
+        }
+        ClientSession.piCliProbe = { at: now, installed };
+        return installed;
+    }
+    static invalidatePiCliProbe() {
+        ClientSession.piCliProbe = null;
+    }
     /**
      * Run a command async, collecting stdout+stderr; kills on timeout.
      * Never throws / never crashes the server: spawn errors (ENOENT etc.)
@@ -1483,6 +1518,9 @@ export class ClientSession {
                 text: `pi agent 安装失败：${err.message}`,
             });
         }
+        // The CLI may just have landed on PATH (or the install may have failed) —
+        // drop the probe cache so the next snapshot re-checks.
+        ClientSession.invalidatePiCliProbe();
         this.flushSnapshot();
     }
     /** Send a snapshot immediately (cancels any pending throttled one).

package/dist/server/client-state.js

@@ -178,6 +178,7 @@ export class ClientStateStore {
             terminalBash: s?.settings?.terminalBash ?? false,
             terminalBashIdleMs: s?.settings?.terminalBashIdleMs ?? 15_000,
             thinkingWrap: s?.settings?.thinkingWrap ?? false,
+            toolsWrap: s?.settings?.toolsWrap ?? true,
             visionBridgeEnabled: s?.settings?.visionBridgeEnabled ?? true,
             visionBridgeModel: s?.settings?.visionBridgeModel ?? null,
             visionBridgePromptMode: s?.settings?.visionBridgePromptMode === "replace" ? "replace" : "append",
@@ -201,6 +202,7 @@ export class ClientStateStore {
             terminalBash: settings.terminalBash ?? cur.terminalBash ?? false,
             terminalBashIdleMs: settings.terminalBashIdleMs ?? cur.terminalBashIdleMs ?? 15_000,
             thinkingWrap: settings.thinkingWrap ?? cur.thinkingWrap ?? false,
+            toolsWrap: settings.toolsWrap ?? cur.toolsWrap ?? true,
             visionBridgeEnabled: settings.visionBridgeEnabled ?? cur.visionBridgeEnabled ?? true,
             visionBridgeModel: settings.visionBridgeModel ?? cur.visionBridgeModel ?? null,
             visionBridgePromptMode: settings.visionBridgePromptMode ??

package/dist/server/index.js

@@ -179,6 +179,11 @@ const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/dist/server or <p
 // Resolve the package root robustly: dev runs from <repo>/server (tsx), prod
 // from <pkg>/dist/server — the ancestor that actually has package.json wins.
 function resolvePkgRoot() {
+    // PI_WEB_PKG_ROOT: Electron 桌面版打包后，server 子进程从 extraResources 目录
+    //（process.resourcesPath）加载 web/dist 和 themes。通过这个 env var 告诉
+    // server 去哪里找 pkgRoot，避免 resolvePkgRoot 的候选路径找不到 package.json。
+    if (process.env.PI_WEB_PKG_ROOT)
+        return process.env.PI_WEB_PKG_ROOT;
     const candidates = [
         resolve(here, ".."),
         resolve(here, "..", ".."),
@@ -717,6 +722,7 @@ wss.on("connection", (ws) => {
                     terminalBash: msg.terminalBash,
                     terminalBashIdleMs: msg.terminalBashIdleMs,
                     thinkingWrap: msg.thinkingWrap,
+                    toolsWrap: msg.toolsWrap,
                     visionBridgeEnabled: msg.visionBridgeEnabled,
                     visionBridgeModel: msg.visionBridgeModel,
                     visionBridgePromptMode: msg.visionBridgePromptMode,

package/dist/server/protocol-version.js

@@ -8,4 +8,4 @@
  * its own copy in web/src/protocol-version.ts; scripts/check-protocol-sync.mjs
  * verifies the two never drift.
  */
-export const PROTOCOL_VERSION = 9;
+export const PROTOCOL_VERSION = 10;

package/dist/server/settings-service.js

@@ -6,7 +6,8 @@
  * 预设存取 + 何时需要 reload」，真正动 runtime 的 session.reload() 走宿主回调
  * （reloadSession 里还会刷新斜杠命令目录）。
  */
-import { basename } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { extensionKey } from "./client-state.js";
 import { findVisionModels, SYSTEM_PROMPT } from "./vision-bridge.js";
 export class SettingsService {
@@ -39,20 +40,88 @@ export class SettingsService {
         this.pendingReload = false;
         return v;
     }
+    /** 判断某个 skill 名是否仍存在于磁盘任何来源（agent 区 / 项目 .pi / 祖先
+     *  .agents/skills / npm 包内 skills）。被禁用且文件已删除的名字不应再
+     *  出现在设置面板，也不应留在持久化记录里。 */
+    skillStillOnDisk(name) {
+        const cwd = this.host.cwd();
+        const agentDir = this.host.agentDir();
+        const check = (base) => existsSync(join(base, name)) || existsSync(join(base, `${name}.md`));
+        // ① 用户区 <agentDir>/skills ② 项目 .pi/skills
+        if (check(join(agentDir, "skills")))
+            return true;
+        if (check(join(cwd, ".pi", "skills")))
+            return true;
+        // ③ 祖先链 .agents/skills（SDK collectAncestorAgentsSkillDirs 语义，最多上溯 6 层）
+        let dir = cwd;
+        for (let i = 0; i < 6 && dir !== dirname(dir); i++, dir = dirname(dir)) {
+            if (check(join(dir, ".agents", "skills")))
+                return true;
+        }
+        // ④ npm 包内 skills（agent 级 + 项目级，含 @scope 两级子包）
+        for (const npmRoot of [
+            join(agentDir, "npm", "node_modules"),
+            join(cwd, ".pi", "npm", "node_modules"),
+        ]) {
+            try {
+                for (const entry of readdirSync(npmRoot, { withFileTypes: true })) {
+                    if (!entry.isDirectory())
+                        continue;
+                    if (!entry.name.startsWith("@")) {
+                        if (check(join(npmRoot, entry.name, "skills")))
+                            return true;
+                    }
+                    else {
+                        for (const sub of readdirSync(join(npmRoot, entry.name), { withFileTypes: true })) {
+                            if (sub.isDirectory() && check(join(npmRoot, entry.name, sub.name, "skills"))) {
+                                return true;
+                            }
+                        }
+                    }
+                }
+            }
+            catch {
+                // npm 目录不存在/不可读 → 不是来源
+            }
+        }
+        return false;
+    }
     push() {
         const disabledSkills = new Set(this.settings.disabledSkills);
         const reviewDisabledSkills = new Set(this.settings.reviewDisabledSkills);
         const disabledExts = new Set(this.settings.disabledExtensions);
+        let loadedSkillNames = null;
         try {
-            // Refresh the cache with the CURRENTLY loaded set (post-filter).
-            for (const s of this.host.getSession().resourceLoader.getSkills().skills) {
+            const loadedSkills = this.host.getSession().resourceLoader.getSkills().skills;
+            const loadedExts = this.host.getSession().resourceLoader.getExtensions().extensions;
+            loadedSkillNames = new Set(loadedSkills.map((s) => s.name));
+            // Prune entries that no longer exist on disk AND aren't disabled
+            // (e.g. a skill/extension file was deleted). Disabled entries are
+            // kept so they can be re-enabled even when filtered out of the loader.
+            const keepSkills = new Set([
+                ...loadedSkills.map((s) => s.name),
+                ...this.settings.disabledSkills,
+            ]);
+            const keepExts = new Set([
+                ...loadedExts.map((e) => extensionKey(e)),
+                ...this.settings.disabledExtensions,
+            ]);
+            for (const name of [...this.knownSkills.keys()]) {
+                if (!keepSkills.has(name))
+                    this.knownSkills.delete(name);
+            }
+            for (const id of [...this.knownExtensions.keys()]) {
+                if (!keepExts.has(id))
+                    this.knownExtensions.delete(id);
+            }
+            for (const s of loadedSkills) {
                 this.knownSkills.set(s.name, {
                     name: s.name,
                     description: s.description,
                     enabled: true,
                 });
             }
-            for (const e of this.host.getSession().resourceLoader.getExtensions().extensions) {
+            for (const e of loadedExts) {
                 const id = extensionKey(e);
                 const p = e.sourceInfo?.path ?? e.path;
                 this.knownExtensions.set(id, {
@@ -68,13 +137,33 @@ export class SettingsService {
         catch {
             // Session not ready yet — keep whatever we already know.
         }
-        // Disabled entries are filtered out of the loader — keep them in the
-        // panel (with the last-known description) so they can be re-enabled.
-        for (const name of this.settings.disabledSkills) {
-            if (!this.knownSkills.has(name)) {
-                this.knownSkills.set(name, { name, description: "", enabled: false });
+        // 清理“源文件已删除”的禁用残留记录：磁盘上已不存在的技能名从
+        // disabledSkills / reviewDisabledSkills 持久化记录中移除——否则每次
+        // 推送都会把已删除的 skill 以灰条形式永恒地补回面板（“关闭过的
+        // skill 被一直记录”）。session 未就绪时保守跳过。
+        if (loadedSkillNames !== null) {
+            const stale = [
+                ...new Set([...this.settings.disabledSkills, ...this.settings.reviewDisabledSkills]),
+            ].filter((name) => !loadedSkillNames.has(name) && !this.skillStillOnDisk(name));
+            if (stale.length > 0) {
+                this.settings.disabledSkills = this.settings.disabledSkills.filter((n) => !stale.includes(n));
+                this.settings.reviewDisabledSkills = this.settings.reviewDisabledSkills.filter((n) => !stale.includes(n));
+                this.host.stateStore.saveSettings(this.host.clientId, {
+                    disabledSkills: this.settings.disabledSkills,
+                    reviewDisabledSkills: this.settings.reviewDisabledSkills,
+                });
             }
         }
+        // Disabled entries that still exist on disk are re-added (with the
+        // last-known description) so they can be re-enabled; entries whose
+        // source file was deleted are dropped instead of being resurrected.
+        for (const name of this.settings.disabledSkills) {
+            if (this.knownSkills.has(name))
+                continue;
+            if (!this.skillStillOnDisk(name))
+                continue;
+            this.knownSkills.set(name, { name, description: "", enabled: false });
+        }
         for (const id of this.settings.disabledExtensions) {
             if (!this.knownExtensions.has(id)) {
                 this.knownExtensions.set(id, {
@@ -103,6 +192,7 @@ export class SettingsService {
                 terminalBash: this.settings.terminalBash,
                 terminalBashIdleMs: this.settings.terminalBashIdleMs,
                 thinkingWrap: this.settings.thinkingWrap,
+                toolsWrap: this.settings.toolsWrap,
                 visionBridgeEnabled: this.settings.visionBridgeEnabled,
                 visionBridgeModel: this.settings.visionBridgeModel,
                 visionBridgePromptMode: this.settings.visionBridgePromptMode,
@@ -174,6 +264,9 @@ export class SettingsService {
         if (partial.thinkingWrap !== undefined) {
             this.settings.thinkingWrap = partial.thinkingWrap;
         }
+        if (partial.toolsWrap !== undefined) {
+            this.settings.toolsWrap = partial.toolsWrap;
+        }
         if (partial.visionBridgeEnabled !== undefined) {
             this.settings.visionBridgeEnabled = partial.visionBridgeEnabled;
         }
@@ -245,10 +338,11 @@ export class SettingsService {
             reviewDisabledSkills: [
                 ...(p.reviewDisabledSkills ?? this.settings.reviewDisabledSkills),
             ],
-            // Presets don't capture vision-bridge prefs — keep the current ones.
-            visionBridgeEnabled: this.settings.visionBridgeEnabled,
             // 纯 UI 偏好不进预设——保留当前值。
             thinkingWrap: this.settings.thinkingWrap,
+            toolsWrap: this.settings.toolsWrap,
+            // Presets don't capture vision-bridge prefs — keep the current ones.
+            visionBridgeEnabled: this.settings.visionBridgeEnabled,
             visionBridgeModel: this.settings.visionBridgeModel,
             visionBridgePromptMode: this.settings.visionBridgePromptMode,
             visionBridgePrompt: this.settings.visionBridgePrompt,