pi-web-ui 0.86.2 → 0.87.0

package/CHANGELOG.md

@@ -10,6 +10,42 @@
 
 ## [Unreleased]
 
+## [0.87.0] — 2026-09-16
+
+### Added
+
+- **插件市场支持「从目录同步」**（issue #165）—— 设置面板插件市场头部新增同步入口：填一个目录文档 URL（http(s)）或本地绝对路径，一键同步可安装列表（走服务端现成的 `plugin_catalog_sync` 通道：同校验、同原子写盘；可选同步后安装全部条目 / 整体替换，逐条安装结果就地回显）。成功同步过的 URL 记在浏览器 localStorage（最近 8 个），一点即重同步。第三方仓库从此不需要再为同步专门发一个占位插件。
+- **`install --catalog <url>` 与 `PI_WEB_PLUGIN_CATALOG_URL`**（issue #165）—— headless/预置场景：CLI 从目录文档同步列表并逐条安装/更新（已安装默认跳过，`--force` 更新，`--replace` 整体替换，单条失败不中断整批；`--build` / `--no-build` 对逐条同样生效）；服务端启动时若配了该环境变量则自动同步一次并安装，失败只告警不阻断启动。
+
+- **DSH 引擎复刻 dsh-web 四模式 Agent 预设** —— standard（全功能）/ PTC（`run_code` 组合面）/ minimal（单持久 shell）/ cordis（组合创作），与官方同名录同语义：新对话下拉选择、空白会话可切换、首轮发言后锁定、默认预设在设置面板配置、自建预设（`$DSH_HOME/.agent-presets`）照常上架。自定义系统提示词改走独立 host section（standard/ptc/cordis 下发，minimal 按官方语义压住）。已知限制：自建组合里写裸包名的无法挂载（launcher 式 boot 的 baseUrl 所限）；问卷/技能目录钩子改挂 agent scope（旧 host 写法在新版运行时已失效）。
+
+- **未发送的输入框草稿跨刷新/切换自动恢复**（issue #166，单中心文件方案）—— 以前刷新页面、切会话再回来，输入框里没发出去的字全丢。现在打字时前端每 2s 防抖 + 失焦/切会话即时把草稿存到服务端 `<dataDir>/composer-drafts.json`（按 sessionId 键入，每会话只留最新一条；`localStorage` 同步镜像一层，兜住崩溃和关闭页面的最后一击），切会话/`newChat`/刷新重连时的全量快照把草稿带回来（本地没动过才恢复，绝不覆盖正在打的字）。发送成功、会话删除即清，30 天未更新兜底清扫。增量快照不带草稿（无 60ms 热帧开销），不进 LLM 上下文、不污染历史搜索，pi 引擎独有（DSH 暂无）。
+- **语音输入插件支持一键安装本地 Whisper** —— 🎤 浮层里点一下，服务端自动装 transformers.js 运行时 + 下载模型（base 约 290MB / tiny 约 150MB，可在设置里切），以后录音不出本机、不要 key 也能转写；新 `engine` 设置（auto/local/remote，默认 auto 本地优先、挂了切远端）。服务端录音改走浏览器现场编码的 16k 单声道 WAV（AudioWorklet，ScriptProcessor 兜底），不再拼 MediaRecorder mime，服务端也无需装 ffmpeg。
+
+### Fixed
+
+- **插件 `ensureDeps` 遇到带版本号的依赖永远判缺失** —— `isDepAvailable` 把 `foo@1.2.3` 原样丢给 `require.resolve`（它不认 `@后缀`，恒 `MODULE_NOT_FOUND`），于是 pin 了版本的插件每次都重跑 `npm install`，装完还报“仍缺”。现在先剥掉版本再探测（只判存在，不审计版本；安装时 pin 照走）。
+- **语音输入在 Edge 上“完全不能识别”且报错看不懂** —— 现在浮层按错误码给中文解释：非安全上下文（`http://局域网IP` 打开被浏览器掐语音+麦克风，指路 localhost）、`network`（Edge 语音服务要联网，代理/VPN 可能拦）、`not-allowed`（麦克风权限，指路地址栏 🔒）；听写中多了一个「改用服务端录音」按钮，一键绕过抽风的浏览器识别；浏览器静默断句续听加了 2 次上限，防无限空转。
+- **DSH 引擎在新版 dsh 运行时下无法启动** —— wrapper 调的 `ctx.userQuestions.registerProvider` 已被上游删除，boot 直接 `TypeError` 崩溃。现在按官方 waterfall 语义把问卷 answerer 注册到每个 agent scope。
+- **DSH 引擎底栏没有上下文占用 / 缓存命中 / 回复速率** —— 新版 dsh 运行时取消了持久的 `assistant/chunk`（逐 chunk 事件），
+  改成 agent scope 的 `agent/assistant-stream` 直播帧，usage 只在结算时随 `assistant/message.usage` 落一次；jsonrpc 面两样都收不到，
+  于是 streamingMessage / 速率 / 底栏统计全空。现在 wrapper 用 `{ global: true }` 订阅直播帧转成 `assistant.stream` 通知，服务端与老
+  `assistant/chunk` 共用一条 chunk 管线（`conv.liveChunks` 互斥），usage 走 `assistant/message.usage` 回填；没有 usage 时上下文显示 `—`
+  而不是 `0 / 1.0M`。回归：`tests/unit/dsh-usage.test.ts` + `tests/dsh-stats-test.mjs`（已进冒烟清单）。
+- **DSH 部署人设（`override.patch.yml`）键名写错** —— `persona:` 不是 schema 字段（应为 `personaPrefix:`），被 zod 静默丢弃，自定义系统提示词一直没进过运行时。
+- **同 sessionId 重建抛 `already exists`** —— 运行时重启/优雅关闭后，磁盘已有的会话 id 走 `agents.create` 必撞；现在自动转 `agents.resume`（官方恢复路径，附带缝合被中断的 turn），预设按日志记录优先恢复。
+- **只有源码的插件不再装出“沉默的死插件”**（issue #165）—— `install` 在“有构建声明但无产物”时默认直接构建（以前只打印一行极易错过的提示，装完是个什么都不加载的空目录），构建前先打印解析出的 install/command；产物已提交的仓库行为不变。`--no-build` 保留旧的装空目录行为（明确打印跳过原因），与 `--build` 互斥。设置面板的「源码构建」勾选框语义相应变为“强制重编”（不勾选时源码插件也会自动构建）。
+- **顶栏「⋯」溢出菜单在 DOM 里但永远点不到**（issue #162）—— 菜单元件挂在 `.view-switch{overflow:hidden}`（桌面端圆角药丸容器的裁剪）/ `.topbar-actions` 横滑容器（窄屏 ≤768px）里面，往下展开的部分全被祖先裁掉，`z-index` 再高也出不来；藏进溢出菜单的条目实际不可达。现在菜单经 portal 到 `document.body` + `position: fixed`（与右键菜单同路），按触发按钮实测锚定、视口钳制（下方放不下翻到上方），并补上点外面 / Esc 关闭（滚动/缩放时重跟锚点，不关闭）。另修一个连带坑：关闭回调若是内联箭头，effect 每 render 解绑/重绑全套 document 监听，离散按键可能正好落在空窗里导致 Esc 丢键 —— 关闭走 ref，监听只装一次。回归：`tests/ui-layout-ui-test.mjs` 新增「真的可见可点」断言（`elementFromPoint` 落在菜单内）。
+
+<!-- auto-i18n:start -->
+### i18n
+
+- 前端新增 key（61）：`atMentions`、`atMenuHint`、`fileOpenPreview`、`fileEnterDir`、`fileNewFile`、`fileNewDir`、`fileRename`、`fileNamePlaceholder`、`fileDuplicate`、`fileCut`、`fileCopyEntry`、`filePaste`、`fileDelete`、`fileDeleteConfirm`、`fileCopyRelPath`、`fileRefresh`、`providerAuthHint`、`oauthLogin`、`oauthLogout`、`oauthConnected`、`oauthDeviceCode`、`oauthOpenVerification`、`oauthContinue`、`pluginCatalogSync`、`pluginCatalogSyncHint`、`pluginCatalogSyncSource`、`pluginCatalogSyncSubmit`、`pluginCatalogSyncInstall`、`pluginCatalogSyncReplace`、`pluginCatalogSyncRecent`、`pluginCatalogSyncOk`、`pluginCatalogSyncInstalled`、`dshPreset`、`dshPresetNewChat`、`dshPresetLocked`、`dshPresetBlankOnly`、`dshPresetBroken`、`dshPresetUser`、`dshPresetDefaultTag`、`dshPresetCurrent`、`dshPresetMinimalNote`、`dshDefaultPreset`、`dshDefaultPresetDesc`、`dshPresetUserNote`、`dshPerm`、`dshPermReadOnly`、`dshPermReadOnlyDesc`、`dshPermWorkspaceWrite`、`dshPermWorkspaceWriteDesc`、`dshPermFullAccess`、`dshPermFullAccessDesc`、`dshPermFullAccessTag`、`dshPermCustom`、`dshPermConfirmFull`、`dshPermDefault`、`dshPermDefaultDesc`、`pluginDomNeed`、`pluginDomDesc`、`pluginDomGrant`、`pluginDomRevoke`、`pluginDomGranted`
+- 前端中文变更（1）：`pluginBuildHint`
+- 前端英文变更（1）：`pluginBuildHint`
+- 服务端新增 key（2）：`plugininstaller.build.conflict`、`plugins.host.engines.mismatch`
+<!-- auto-i18n:end -->
+
 ## [0.86.2] — 2026-09-15
 
 ### Fixed
@@ -27,22 +63,22 @@
 ### Added
 
 - **插件安装 / 更新 / 卸载改为后台作业，不再抢走设置面板**（issue #152）—— 以前点安装会在可见终端里跑 CLI，同时把设置弹窗
-关掉、主视图切到终端；连装几个插件就得「装一个、重开设置、再导航回市场」。现在作业跑在服务端（`server/plugin-installer.ts`
-，执行的仍是同一个 CLI），输出按行回传，**设置面板原地显示进度**（进行中带最后一行输出，失败可就地展开输出尾部）；同一时刻
-只允许一个作业（两个 install 写同一目录必出半装状态），另有 15 分钟看门狗与「取消」。托管实例（`PI_WEB_MANAGED=1`）与
-CLI 缺失都会明确拒绝。
+  关掉、主视图切到终端；连装几个插件就得「装一个、重开设置、再导航回市场」。现在作业跑在服务端（`server/plugin-installer.ts`
+  ，执行的仍是同一个 CLI），输出按行回传，**设置面板原地显示进度**（进行中带最后一行输出，失败可就地展开输出尾部）；同一时刻
+  只允许一个作业（两个 install 写同一目录必出半装状态），另有 15 分钟看门狗与「取消」。托管实例（`PI_WEB_MANAGED=1`）与
+  CLI 缺失都会明确拒绝。
 - **`host.reloadCatalog()`：受支持的插件市场目录同步**（issue #148）—— 第三方插件以前只能派发私有浏览器事件 + 开可见终
-端来同步自己的插件清单（私有事件随时会变、宿主更新没有回执）。现在有一条一等公民路径：`reloadCatalog(url 或本地路径,
+  端来同步自己的插件清单（私有事件随时会变、宿主更新没有回执）。现在有一条一等公民路径：`reloadCatalog(url 或本地路径,
 { install?, replace? })` —— 服务端拉取 → 用市场「添加到列表」同一套规则校验 → **原子写** `<dataDir>/plugin-catalog.json`
-（形状不对 / 解析失败 / 读不到时一个字节都不写，旧目录保持有效）→ 可选逐条安装（已装走更新，失败逐条记录不中断整批）→
-重载插件并把新列表推给所有客户端 → 结构化回执 `{ok, error?, entries?, installed?}`。
+  （形状不对 / 解析失败 / 读不到时一个字节都不写，旧目录保持有效）→ 可选逐条安装（已装走更新，失败逐条记录不中断整批）→
+  重载插件并把新列表推给所有客户端 → 结构化回执 `{ok, error?, entries?, installed?}`。
 - **插件 UI 扩展点框架：11 个挂载点，插件只声明、宿主负责渲染**（issue #146 完整版）—— v1 那条 `topbar` 专用声明长成
-了一套通用 slot 框架。manifest 的 `ui` 字段（或运行时 `host.ui.*`）可以往 `topbar.primary` / `topbar.overflow` /
-`bottombar` / `composer.actions` / `message.actions` / `rightpanel.tabs` / `contextmenu.topbar|message|session|file` /
-`settings.pages` 这 11 个挂载点声明条目（`{id, label, labelEn?, icon?, kind?, order?, group?, hidden?, action?, view?,
+  了一套通用 slot 框架。manifest 的 `ui` 字段（或运行时 `host.ui.*`）可以往 `topbar.primary` / `topbar.overflow` /
+  `bottombar` / `composer.actions` / `message.actions` / `rightpanel.tabs` / `contextmenu.topbar|message|session|file` /
+  `settings.pages` 这 11 个挂载点声明条目（`{id, label, labelEn?, icon?, kind?, order?, group?, hidden?, action?, view?,
 when?, children?}`，也收 `topbar` / `settings` 这类简写别名）；宿主负责渲染、排序、**溢出菜单**、可访问性、用户偏好与
-审计，插件不碰 DOM，动作由插件客户端经 `host.onUiAction(name, fn)` 接管（按需加载它的 bundle，最终没人接管就提示一句，
-不让按钮看起来点了没用）。
+  审计，插件不碰 DOM，动作由插件客户端经 `host.onUiAction(name, fn)` 接管（按需加载它的 bundle，最终没人接管就提示一句，
+  不让按钮看起来点了没用）。
   - **插件能整理宿主内置条目**：`ui.arrange` 可以把内置入口（id 形如 `host:settings`）移到别的槽位、隐藏、改顺序/分组/
     文案。内置条目表是 `web/src/ui-slots.ts` 的 `BUILTIN_UI_ITEMS`（32 条，逐条对应代码里真实存在的入口，不臆造）。
   - **用户偏好永远最后说话**：设置面板「界面插件 → 界面布局」按槽位列出所有条目，可逐条隐藏 / ↑↓ 调序 / 「恢复」单条
@@ -89,10 +125,10 @@ when?, children?}`，也收 `topbar` / `settings` 这类简写别名）；宿主
   （4 加了 `reloadCatalog` / `openSession` / `onTopbarAction`，5 把顶栏动作推广成通用 `onUiAction`，6 加了 `sessions`
   与多根 `openSession`；`onTopbarAction` 保留为别名）。插件可用 `version` 判断宿主能力，老宿主上不会拿到 undefined 接口。
 - **`pi-web-ui install --build`：源码安装时隔离构建**（issue #150）—— 插件仓库可以只提交 TypeScript 源码，不必再把
-`index.mjs` / `client/entry.mjs` 产物提交进仓库。构建在临时目录里完成：只装插件声明的构建依赖
-（`npm install --ignore-scripts`，不执行任意生命周期脚本）→ 跑 manifest.build.command（缺省回落 package.json 的
-`scripts.build`）→ 校验 `outputs` 产物齐全 → **成功后才替换目标目录**（失败时上一版插件原样可用、无半装状态）。设置面
-板的插件市场有「源码构建」勾选项，等价 `--build`，网络安装入口全部纳入托管实例（`PI_WEB_MANAGED`）拒绝面。
+  `index.mjs` / `client/entry.mjs` 产物提交进仓库。构建在临时目录里完成：只装插件声明的构建依赖
+  （`npm install --ignore-scripts`，不执行任意生命周期脚本）→ 跑 manifest.build.command（缺省回落 package.json 的
+  `scripts.build`）→ 校验 `outputs` 产物齐全 → **成功后才替换目标目录**（失败时上一版插件原样可用、无半装状态）。设置面
+  板的插件市场有「源码构建」勾选项，等价 `--build`，网络安装入口全部纳入托管实例（`PI_WEB_MANAGED`）拒绝面。
 - **vscode-editor 插件：SSH 主机支持私钥路径 / 口令 / agent，还能从 `~/.ssh/config` 批量导入**（issue #149）—— 以前主机编辑只有密码与内联 PEM 私钥两项：带口令的私钥没地方填口令（连上就挂），用 `~/.ssh/id_rsa` 这类文件路径的得把私钥全文粘贴进来，ssh-agent 更没入口。现在编辑框多了三项：私钥路径（支持 `~` 展开，填写则优先用文件、不必粘贴全文）、私钥口令 passphrase（留空=保持不变，连接时透给 ssh2）、agent socket（如 `$SSH_AUTH_SOCK`，与密码/私钥互斥）；「从 ssh config 导入」按钮解析本机 `~/.ssh/config` 列出候选（已导入的标出跳过），勾选批量导入 —— 导入只存私钥路径引用，不读私钥内容。解析语义对齐 OpenSSH：同块先出现的值优先，`Host *` 块只充当默认值继承、不产出候选，含通配符的别名不产出。
 - **检查更新走你自己的 npm 源，不再卡在官方源上**（issue #151）—— 配了镜像/私有源的用户（`<agentDir>/npm/.npmrc`，`pi update` 经 npm 本来就认这一份），以前顶栏更新检查还直连 `registry.npmjs.org`：镜像用户查不到新版、私有源用户直接 401。现在检查更新读同一份 `.npmrc` 解析 registry + 认证头（`_authToken` 优先、`_auth` 其次，同源才带），无文件/无配置时回落官方源。pi 与 DSH 双引擎同修。
 - **桌面版里「浏览器操作」给明确结论，不再让人白装扩展**（issue #153）—— 桌面窗口（Electron）里没有 Chrome 扩展运行时，page-picker 扩展永远装不上；以前面板还是网页版那四步安装引导，用户跟着做完才发现此路不通，模型调 `browser_page` 还要干等 3 秒桥超时。现在桌面壳里面板直接给结论 + 「用默认浏览器打开当前地址」按钮（去网页版按四步装即可），`queryBrowserControl` 与服务端 `pageCall` 都短路返回「改用网页版」的错误，不碰扩展桥。
@@ -101,11 +137,11 @@ when?, children?}`，也收 `topbar` / `settings` 这类简写别名）；宿主
 ### Changed
 
 - **插件 `apiVersion: 2` 起「不写 `permissions`」等于默认拒绝**（issue #146 完整版）—— 宿主设施版本升到
-`PLUGIN_API_VERSION = 2`。以前 `permissions` 缺省是「旧格式全权模式」：受控宿主 API 一律放行、只在日志里警告一次；
-现在只要 manifest 声明了 `apiVersion: 2`，没写 `permissions` 就按**空能力集**处理 —— `fs` / `http` / `tools` / `ui` /
-`chat` 这些受控入口逐个拒绝（`manifest.ui` 整份忽略），日志里写明缺哪个能力族。**对插件作者的含义**：升到 2 就得同时
-补上 `permissions`（哪怕只是加一个顶栏按钮，也要写 `"permissions": ["ui"]`）。不写 `apiVersion` 的老插件仍是 v1 +
-旧全权模式（只警告、行为不变），所以升级可以按插件逐个进行；`apiVersion` 比宿主新才会被拒绝激活，并提示升级 pi-web-ui。
+  `PLUGIN_API_VERSION = 2`。以前 `permissions` 缺省是「旧格式全权模式」：受控宿主 API 一律放行、只在日志里警告一次；
+  现在只要 manifest 声明了 `apiVersion: 2`，没写 `permissions` 就按**空能力集**处理 —— `fs` / `http` / `tools` / `ui` /
+  `chat` 这些受控入口逐个拒绝（`manifest.ui` 整份忽略），日志里写明缺哪个能力族。**对插件作者的含义**：升到 2 就得同时
+  补上 `permissions`（哪怕只是加一个顶栏按钮，也要写 `"permissions": ["ui"]`）。不写 `apiVersion` 的老插件仍是 v1 +
+  旧全权模式（只警告、行为不变），所以升级可以按插件逐个进行；`apiVersion` 比宿主新才会被拒绝激活，并提示升级 pi-web-ui。
 
 ### Fixed
 
@@ -114,12 +150,14 @@ when?, children?}`，也收 `topbar` / `settings` 这类简写别名）；宿主
 - **输入框里的一行 JSX 注释不再渲染成可见文本** —— `ChatInput.tsx` 里 `/* … */` 写在了 JSX 子节点位置，会被当成文本渲染出来；已改为 `{/* … */}`。
 
 <!-- auto-i18n:start -->
+
 ### i18n
 
 - 前端新增 key（44）：`elsewhereBadge`、`elsewhereTip`、`workspaceRoots`、`workspaceRootsHint`、`addWorkspaceRoot`、`addWorkspaceRootHint`、`removeWorkspaceRoot`、`browserControlDesktop`、`browserControlDesktopLead`、`browserControlOpenInBrowser`、`devNoCache`、`devNoCacheDesc`、`autoReload`、`autoReloadDesc`、`pluginJobRunning`、`pluginJobDone`、`pluginJobFailed`、`pluginBuildSource`、`pluginBuildHint`、`uiLayoutTitle`、`uiLayoutHint`、`pluginTopbarMore`、`uiLayoutTopbar`、`uiLayoutTopbarOverflow`、`uiLayoutBottombar`、`uiLayoutComposer`、`uiLayoutMessage`、`uiLayoutRightPanel`、`uiLayoutSettingsPages`、`uiLayoutRestore`、`uiLayoutRestoreAll`、`uiLayoutArranged`、`uiLayoutEmpty`、`pluginGrantsTitle`、`pluginGrantsHint`、`pluginGrantsEmpty`、`pluginGrantsRevoke`、`pluginGrantRequestTitle`、`pluginGrantRequestBody`、`pluginGrantAllow`、`pluginGrantDeny`、`pluginUiNoHandler`、`pluginSessionGrantTitle`、`pluginSessionGrantBody`
 - 前端中文变更（3）：`pluginUpdateHint`、`pluginInstallHint`、`pluginUninstallHint`
 - 前端英文变更（3）：`pluginUpdateHint`、`pluginInstallHint`、`pluginUninstallHint`
 - 服务端新增 key（15）：`plugincatalog.sync.fetch.failed`、`plugincatalog.sync.http`、`plugincatalog.sync.too.large`、`plugincatalog.sync.source.invalid`、`plugincatalog.sync.read.failed`、`plugincatalog.sync.source.missing`、`plugincatalog.sync.parse.failed`、`plugincatalog.sync.shape`、`plugininstaller.id.invalid`、`plugininstaller.source.invalid`、`plugininstaller.managed`、`plugininstaller.busy`、`plugininstaller.cli.missing`、`plugininstaller.cancelled`、`plugininstaller.timeout`
+
 <!-- auto-i18n:end -->
 
 ## [0.85.0] — 2026-09-14

package/README.md

@@ -153,7 +153,7 @@ theme switching, and a full settings panel — tuned for daily development.
 - **`edit_soft`** — a looser `edit` (default off) for when indentation or whitespace makes the built-in tool fail: exact substring first, then trimmed line-core matching, `newText` written verbatim with the file's line endings/BOM preserved, and a diff + unified patch in the result. It also tolerates sloppy input (a JSON string, a bare object, legacy top-level `oldText`/`newText`).
 - **`delegate_task`** — hands a specialist template a six-section brief (TASK / EXPECTED OUTCOME / REQUIRED TOOLS / MUST DO / MUST NOT DO / CONTEXT) validated on the server: a missing template, a task under 20 characters or any empty section is rejected, and the error tells the model which templates it may use. Cards render the brief as labelled sections, and a finished delegation gets a button that jumps to the subagent's conversation.
 - **`ask_user_question`** — the pi engine has no questionnaire tool, so pi-web-ui adds one: the model asks structured questions (single/multi-select with rich option previews, plus free text) which open as a dialog; answers go back as the tool result, cancelling returns a tool error, waiting for you is exempt from the tool watchdog, and an unanswered questionnaire survives a page refresh or reconnect.
-- **MCP servers** — drop a `<dataDir>/mcp.json` (`{"servers":{"github":{"command":"node","args":["mcp.js"],"cwd":"/x"}}}`) and every tool a stdio MCP server advertises becomes an ordinary agent tool, executed server-side; one server failing to start only logs a line and leaves the others working. The file is read at startup, so restart pi-web-ui after editing it.
+- **MCP servers** — drop a `<dataDir>/mcp.json` (`{"servers":{"github":{"command":"node","args":["mcp.js"],"cwd":"/x"}}}`) and every tool a stdio MCP server advertises becomes an ordinary agent tool, executed server-side; one server failing to start only logs a line and leaves the others working. The file is **hot-reloaded**: saving it applies within a second or two, no restart needed — and only the servers whose spec actually changed are restarted (a malformed file is reported and the running servers are kept).
 - **Extension UI bridge** — pi extensions can drive the browser: `setWidget` renders live panels under the file tree (click a title to open it centred), `setStatus` puts text in the status bar, `notify` raises a toast, and `select` / `confirm` / `input` open an inline request panel above the composer with Markdown-rendered options (Esc cancels). ANSI colour codes in widget text are stripped, so extension footers don't arrive as escape-sequence noise.
 - **Plugin extras** — plugins can register `/commands` (badge “plugin”, executed server-side without spending tokens), register background tasks with their own stop button, declare a settings form, subscribe to run/tool/conversation events, and reach the host from their client bundle via `window.__piWebUiHost`. See [Plugins](#plugins).
 

package/bin/pi-web-ui.mjs

@@ -43,11 +43,12 @@ import {
 	realpathSync,
 	readFileSync,
 	readdirSync,
+	renameSync,
 	rmSync,
 	writeFileSync,
 } from "node:fs";
 import { homedir, tmpdir, userInfo } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { fileURLToPath } from "node:url";
 
@@ -116,6 +117,10 @@ server 选项:
   install 选项: --name <id> 自定义插件目录名（默认取仓库名）
                 --data-dir <dir> 数据目录（默认 ~/.pi-web）
                 --force 目标已存在时覆盖
+                --build 强制源码构建（隔离目录编译，见下）
+                --no-build 即使只有源码也不构建（产物缺失的插件装上后不加载）
+                --catalog <url> 目录同步模式：读目录文档 → 写可安装列表 → 逐条安装
+                --replace 配合 --catalog：整体替换列表（默认按 id 合并）
 
 环境变量（flag 优先，环境变量后备）:
   PI_WEB_PORT / PI_WEB_CWD / PI_WEB_DATA_DIR / PI_WEB_ENGINE / PI_WEB_HOST /
@@ -163,6 +168,11 @@ UI plugins (installed into <data-dir>/plugins/; refresh browser to activate whil
   install options: --name <id>   Custom plugin directory name (default: repo name)
                    --data-dir <dir>  Data directory (default: ~/.pi-web)
                    --force       Overwrite if target already exists
+                   --build       Force a source build (isolated build, see below)
+                   --no-build    Never build, even for source-only plugins
+                   --catalog <url> Catalog mode: read a catalog document, write the
+                                 installable list, then install every entry
+                   --replace     With --catalog: replace the whole list (default merges by id)
 
 Environment variables (flag takes precedence, env var as fallback):
   PI_WEB_PORT / PI_WEB_CWD / PI_WEB_DATA_DIR / PI_WEB_ENGINE / PI_WEB_HOST /
@@ -273,6 +283,15 @@ function parseFlags(argv) {
 			case "--build":
 				opts.build = true;
 				break;
+			case "--no-build":
+				opts.noBuild = true;
+				break;
+			case "--catalog":
+				opts.catalog = take("--catalog");
+				break;
+			case "--replace":
+				opts.replace = true;
+				break;
 			case "--check-updates":
 				opts.checkUpdates = true;
 				break;
@@ -1441,6 +1460,7 @@ const PLUGIN_ID_RE = /^[A-Za-z0-9_-]+$/;
 
 const PLUGIN_HELP = `用法:
   pi-web-ui install <源> [选项]     安装 GitHub 上的界面插件
+  pi-web-ui install --catalog <目录> [选项]  同步插件市场目录并逐条安装
   pi-web-ui uninstall <id> [选项]   卸载已安装的界面插件
   pi-web-ui plugins [选项]          列出已安装的界面插件
 
@@ -1449,13 +1469,21 @@ const PLUGIN_HELP = `用法:
   https://github.com/owner/repo                     完整 URL（.git 可省）
   https://github.com/o/r/tree/dev/sub/dir           指定分支 + 仓库内子目录
   以上任意写法末尾加 #分支或tag                      指定分支/tag（如 owner/repo#v1.2）
-  /path/to/plugin-dir                 install 选项:
+  /path/to/plugin-dir                 本地目录（离线开发调试）
+  目录写法（--catalog 用）：
+  https://example.com/catalog.json                  远端目录文档（数组或 {entries:[...]}）
+  /path/to/catalog.json               本地目录文档（绝对路径）
+  install 选项:
   --name <id>       插件目录名/id（默认取仓库名或 manifest.id，仅限字母数字-_）
   --data-dir <dir>  数据目录（默认 ~/.pi-web 或 $PI_WEB_DATA_DIR）
   --force           目标目录已存在时覆盖（覆盖前自动备份旧版本）
-  --build           源码安装：在隔离临时目录里按插件声明安装构建依赖并编译
+  --build           强制源码构建：在隔离临时目录里按插件声明安装构建依赖并编译
                     （manifest.build 或 package.json 的 scripts.build），
-                    成功且产物齐全后才替换目标目录，失败不留半装状态         目标目录已存在时覆盖（覆盖前自动备份旧版本）
+                    成功且产物齐全后才替换目标目录，失败不留半装状态
+  --no-build        即使插件只有源码也不构建（与 --build 互斥；装出来的插件因缺产物不会被加载）
+  --catalog <目录>  目录同步模式：读目录文档 → 原子写入可安装列表 → 逐条安装/更新
+                    （已安装的条目默认跳过，加 --force 则更新；单条失败不中断整批）
+  --replace         配合 --catalog：整体替换可安装列表（默认按 id 合并，保留旧条目）
 
 plugins 选项:
   --check-updates   逐个对比最近安装版本与远端 HEAD，列出可更新插件
@@ -1656,30 +1684,50 @@ function buildPluginSource(pluginRoot, tmpDir, manifest) {
 	return buildDir;
 }
 
-async function pluginInstallCmd(argv) {
-	const { opts, positionals } = parseFlags(argv);
-	if (opts.help) {
-		console.log(PLUGIN_HELP);
-		return;
+/**
+ * 构建决策（issue #165：--build 自动推断）。
+ *
+ * 只有源码、没有产物（index.mjs 与 client/entry.mjs 都缺）且存在可解析的构建声明 =
+ * “不构建这次安装必死”，此时默认直接构建（ previously 只打印一行提示，等用户滚回去重加
+ * --build）。产物已提交的仓库不受影响（mode=none，什么都不跑）。
+ * --no-build 保留旧的“装个空目录”行为（脚本化镜像/检查用），并明确打印跳过原因。
+ */
+function decideBuildAction({ pluginRoot, manifest, build, noBuild }) {
+	if (build && noBuild) throw new Error("--build 与 --no-build 不能同时用（二选一）");
+	const plan = resolveBuildPlan(pluginRoot, manifest);
+	const artifactsMissing =
+		!existsSync(join(pluginRoot, "index.mjs")) && !existsSync(join(pluginRoot, "client", "entry.mjs"));
+	if (build) {
+		if (!plan)
+			throw new Error(
+				"插件没有声明构建方式：请在 manifest.json 里加 build.command（或 package.json 的 scripts.build），或去掉 --build",
+			);
+		return { mode: "explicit", plan };
 	}
-	if (positionals.length !== 1)
-		fail(`用法: pi-web-ui install <源> [--name <id>] [--data-dir <dir>] [--force] [--build]\n${PLUGIN_HELP}`);
-	const rawSpec = positionals[0];
-	const pluginsDir = join(pluginDataDir(opts), "plugins");
-	// 本地目录直接装（离线开发调试），否则从 GitHub 拉取
+	if (plan && artifactsMissing) {
+		if (noBuild) return { mode: "skipped", plan };
+		return { mode: "auto", plan };
+	}
+	return { mode: "none", plan };
+}
+
+/**
+ * 装一个插件（单源模式与目录模式共用）：拉取/定位 → 读 manifest → 构建决策 →
+ * 覆盖（备份+保留 config.json）→ 落盘 → 记录来源/sha。
+ * 失败抛 Error（目录模式逐条 try/catch 继续下一条，单源模式由调用方转 fail）。
+ */
+async function installOnePlugin({ rawSpec, name, force, build, noBuild, dataDir }) {
+	const pluginsDir = join(dataDir, "plugins");
 	const localCandidate = resolve(rawSpec.replace(/^file:\/\//, ""));
 	const isLocal = existsSync(localCandidate);
 	const src = isLocal ? null : parsePluginSource(rawSpec);
 	const tmp = mkdtempSync(join(tmpdir(), "pi-web-ui-plugin-"));
-	let backupTs = null;
 	try {
 		let checkout;
 		try {
 			checkout = isLocal ? localCandidate : await acquireRepo(src, tmp);
 		} catch (err) {
-			console.error(`✖ ${err?.message ?? err}`);
-			process.exitCode = 1;
-			return;
+			throw new Error(`${err?.message ?? err}`);
 		}
 		const repoLabel = isLocal ? localCandidate : `${src.owner}/${src.repo}`;
 		const pluginRoot = locatePluginRoot(checkout, src?.subpath, repoLabel);
@@ -1687,25 +1735,23 @@ async function pluginInstallCmd(argv) {
 		try {
 			manifest = JSON.parse(readFileSync(join(pluginRoot, "manifest.json"), "utf8"));
 		} catch (err) {
-			fail(`manifest.json 不是合法 JSON：${err?.message ?? err}`);
+			throw new Error(`manifest.json 不是合法 JSON：${err?.message ?? err}`);
 		}
-		// 源码构建（--build，issue #150）：在临时目录里装依赖 + 编译，成功后才进入
-		// 覆盖流程——构建失败 = 目标目录完全没被动过（上一版插件照常可用）。
+		// 构建决策（issue #150 的 --build + issue #165 的自动推断）：构建在临时目录里完成，
+		// 成功后才进入覆盖流程——构建失败 = 目标目录完全没被动过（上一版插件照常可用）。
+		const decision = decideBuildAction({ pluginRoot, manifest, build: build === true, noBuild: noBuild === true });
 		let installRoot = pluginRoot;
-		if (opts.build) {
+		if (decision.mode === "explicit" || decision.mode === "auto") {
+			console.log(
+				`· 源码构建（${decision.mode === "auto" ? "自动推断：有构建声明但无产物" : "--build"}）：先 ${decision.plan.install}，再 ${decision.plan.command}`,
+			);
 			try {
 				installRoot = buildPluginSource(pluginRoot, tmp, manifest);
 			} catch (err) {
-				process.exitCode = 1;
-				console.error(`✖ ${err?.message ?? err}`);
-				return;
+				throw new Error(`${err?.message ?? err}`);
 			}
-		} else if (
-			resolveBuildPlan(pluginRoot, manifest) &&
-			!existsSync(join(pluginRoot, "index.mjs")) &&
-			!existsSync(join(pluginRoot, "client", "entry.mjs"))
-		) {
-			console.log("· 这个插件声明了构建、但目录里还没有产物：加 --build 可在安装时构建");
+		} else if (decision.mode === "skipped") {
+			console.log("· 跳过构建（--no-build）：目录里没有产物，装上后该插件不会被加载");
 		}
 		// 默认 id：子目录名 > 仓库名 > 本地目录名
 		const sourceName = src?.subpath ? src.subpath.split("/").pop() : (src?.repo ?? localCandidate.split(/[\\/]/).pop());
@@ -1713,16 +1759,17 @@ async function pluginInstallCmd(argv) {
 			String(manifest.id ?? sourceName)
 				.replace(/[^A-Za-z0-9_-]/g, "-")
 				.replace(/^-+|-+$/g, "") || "plugin";
-		const id = opts.name ?? fallbackId;
-		if (!PLUGIN_ID_RE.test(id)) fail(`非法插件 id "${id}"（仅限字母数字-_，可用 --name <id> 自定义）`);
+		const id = name ?? fallbackId;
+		if (!PLUGIN_ID_RE.test(id)) throw new Error(`非法插件 id "${id}"（仅限字母数字-_，可用 --name <id> 自定义）`);
 		const target = join(pluginsDir, id);
+		let backupTs = null;
 		let prevConfig = null;
 		const CONFIG_NAME = "config.json";
 		if (existsSync(target)) {
-			if (!opts.force) fail(`插件目录已存在：${target}\n  加 --force 覆盖，或用 --name <id> 换个名字。`);
+			if (!force) throw new Error(`插件目录已存在：${target}\n  加 --force 覆盖，或用 --name <id> 换个名字。`);
 			// 更新前备份旧版本（<dataDir>/plugin-backups/<id>-<ts>/，保留最近 3 份），
 			// 失败时自动回滚。备份与安装同 filter：不带 .git/node_modules。
-			backupTs = ensurePluginBackup(pluginDataDir(opts), id, { source: rawSpec });
+			backupTs = ensurePluginBackup(dataDir, id, { source: rawSpec });
 			// 插件凭据/配置不因升级丢失：先取出旧 config.json，拷完新文件后原样放回
 			try {
 				prevConfig = readFileSync(join(target, CONFIG_NAME), "utf8");
@@ -1736,10 +1783,10 @@ async function pluginInstallCmd(argv) {
 			cpSync(installRoot, target, { recursive: true, filter: PLUGIN_COPY_FILTER });
 		} catch (err) {
 			// 拷贝失败 → 有备份则自动回滚，保持旧版本可用
-			if (backupTs && restorePluginBackup(pluginDataDir(opts), id)) {
-				fail(`插件更新失败：${err?.message ?? err}\n  已自动回滚到更新前版本。`);
+			if (backupTs && restorePluginBackup(dataDir, id)) {
+				throw new Error(`插件更新失败：${err?.message ?? err}\n  已自动回滚到更新前版本。`);
 			}
-			fail(`插件更新失败：${err?.message ?? err}\n  （无可用备份，请重新 install --force）`);
+			throw new Error(`插件更新失败：${err?.message ?? err}\n  （无可用备份，请重新 install --force）`);
 		}
 		if (prevConfig !== null && !existsSync(join(target, CONFIG_NAME))) {
 			writeFileSync(join(target, CONFIG_NAME), prevConfig);
@@ -1758,14 +1805,239 @@ async function pluginInstallCmd(argv) {
 		} catch {
 			/* 尽力而为 */
 		}
+		return { id, target, manifest, buildMode: decision.mode };
+	} finally {
+		rmSync(tmp, { recursive: true, force: true });
+	}
+}
+
+/**
+ * 目录文档校验（issue #165 的 CLI --catalog）。
+ *
+ * 规则与 server/plugin-catalog.ts 的 toEntry 对齐（id 字符集、source 形状、字段裁剪），
+ * 仅放宽一条：CLI 跑在使用者的本机信任上下文里，允许已存在的本地目录源（离线开发、
+ * 本地目录同步）；服务端 toEntry（网络/插件触发）仍只收远端源。两边规则若漂移，
+ * tests/plugin-catalog-cli-test.mjs 的行为断言会先响（离线全链路）。
+ */
+function isCatalogEntrySource(s) {
+	if (!s || s.length > 300) return false;
+	// 本地目录：CLI 才放行（存在性检查，file:// 前缀兼容 install 单源写法）
+	try {
+		if (existsSync(resolve(s.replace(/^file:\/\//, "")))) return true;
+	} catch {
+		/* 非法路径字符：走下面的远端规则 */
+	}
+	if (/^https?:\/\//.test(s)) return true;
+	const spec = s.split("#")[0].replace(/\/+$/, "");
+	const segs = spec.split("/").filter(Boolean);
+	if (segs.length < 2) return false;
+	for (const seg of segs) if (seg === "." || seg === "..") return false;
+	return true;
+}
+
+function deriveCatalogEntryId(rawId, source) {
+	if (rawId && PLUGIN_ID_RE.test(rawId)) return rawId;
+	try {
+		const local = resolve(source.replace(/^file:\/\//, ""));
+		if (existsSync(local)) {
+			const base = local.split(/[\\/]/).pop() || "plugin";
+			const cleaned = base.replace(/[^A-Za-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+			return cleaned || "plugin";
+		}
+	} catch {
+		/* 走远端规则 */
+	}
+	const spec = source.split("#")[0].replace(/\/+$/, "");
+	const segs = spec.split("/").filter(Boolean);
+	const last = segs.length >= 2 ? segs[segs.length - 1] : (segs[0] ?? "plugin");
+	const cleaned = last.replace(/[^A-Za-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+	return cleaned || "plugin";
+}
+
+function catalogEntryFromRaw(raw) {
+	if (!raw || typeof raw !== "object") return null;
+	const source = typeof raw.source === "string" ? raw.source.trim() : "";
+	if (!isCatalogEntrySource(source)) return null;
+	const id = deriveCatalogEntryId(typeof raw.id === "string" ? raw.id.trim() : undefined, source);
+	if (!PLUGIN_ID_RE.test(id)) return null;
+	const str = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+	const name = str(raw.name) ?? id;
+	const description = str(raw.description);
+	const descriptionEn = str(raw.descriptionEn);
+	const icon = str(raw.icon);
+	const homepage = str(raw.homepage);
+	return {
+		id,
+		name,
+		source,
+		...(description ? { description } : {}),
+		...(descriptionEn ? { descriptionEn } : {}),
+		...(icon ? { icon } : {}),
+		...(homepage ? { homepage } : {}),
+	};
+}
+
+/** 目录文档形状：JSON 数组或 {entries:[...]}；非法条目丢弃并计数（与服务端同语义）。 */
+function normalizeCatalogEntries(raw) {
+	const list = Array.isArray(raw)
+		? raw
+		: raw && typeof raw === "object" && Array.isArray(raw.entries)
+			? raw.entries
+			: null;
+	if (!list) throw new Error('目录 JSON 需为数组，或 {"entries": [...]} 形状');
+	const entries = [];
+	let skipped = 0;
+	for (const it of list) {
+		const e = catalogEntryFromRaw(it);
+		if (e) entries.push(e);
+		else skipped++;
+	}
+	return { entries, skipped };
+}
+
+/** 读目录文档：http(s) 拉取（30s 超时），其余当本地绝对路径（与服务端同口径）。 */
+async function readCatalogDocumentText(source) {
+	const src = String(source ?? "").trim();
+	if (!src) throw new Error("缺少目录来源（--catalog <url 或本地绝对路径>）");
+	if (/^https?:\/\//i.test(src)) {
+		let res;
+		try {
+			res = await fetch(src, { redirect: "follow", signal: AbortSignal.timeout(30_000) });
+		} catch (err) {
+			throw new Error(`拉取目录失败：${err?.message ?? err}`);
+		}
+		if (!res.ok) throw new Error(`拉取目录失败：HTTP ${res.status}`);
+		const text = await res.text();
+		if (text.length > 1024 * 1024) throw new Error("目录文档过大（> 1024 KB）");
+		return text;
+	}
+	if (!isAbsolute(src)) throw new Error("本地目录文档需为绝对路径（远端用 http(s) URL）");
+	try {
+		return readFileSync(src, "utf8");
+	} catch (err) {
+		throw new Error(`读取目录文件失败：${err?.message ?? err}`);
+	}
+}
+
+function readCatalogFileEntries(customPath) {
+	try {
+		const raw = JSON.parse(readFileSync(customPath, "utf8"));
+		if (raw && typeof raw === "object" && Array.isArray(raw.entries)) return raw.entries;
+	} catch {
+		/* 无文件/坏文件 = 空列表 */
+	}
+	return [];
+}
+
+function writeCatalogFileEntries(customPath, entries) {
+	mkdirSync(dirname(customPath), { recursive: true });
+	const tmp = `${customPath}.tmp-${process.pid}`;
+	writeFileSync(tmp, JSON.stringify({ entries }, null, 2) + "\n");
+	renameSync(tmp, customPath);
+}
+
+/** install --catalog <url>：同步可安装列表 + 逐条安装/更新（单条失败不中断整批）。 */
+async function installCatalogCmd(opts) {
+	const dataDir = pluginDataDir(opts);
+	const customPath = join(dataDir, "plugin-catalog.json");
+	const pluginsDir = join(dataDir, "plugins");
+	const text = await readCatalogDocumentText(opts.catalog).catch((err) => fail(`${err?.message ?? err}`));
+	let raw;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		fail(`目录 JSON 解析失败：${err?.message ?? err}`);
+	}
+	let entries;
+	let skipped = 0;
+	try {
+		({ entries, skipped } = normalizeCatalogEntries(raw));
+	} catch (err) {
+		fail(`${err?.message ?? err}`);
+	}
+	// 到这里才动磁盘：形状不对的文档绝不覆盖有效列表（与服务端同纪律）。
+	if (opts.replace) {
+		writeCatalogFileEntries(customPath, entries);
+	} else {
+		const prev = readCatalogFileEntries(customPath).filter((x) => x && typeof x === "object");
+		const next = [...prev];
+		for (const e of entries) {
+			const idx = next.findIndex((x) => x.id === e.id);
+			if (idx >= 0) next[idx] = e;
+			else next.push(e);
+		}
+		writeCatalogFileEntries(customPath, next);
+	}
+	console.log(
+		`· 目录同步：${entries.length} 条合法${skipped ? `（丢弃 ${skipped} 条非法）` : ""}${opts.replace ? "（整体替换）" : "（按 id 合并）"} → ${customPath}`,
+	);
+	let okCount = 0;
+	let failCount = 0;
+	let skipCount = 0;
+	for (const e of entries) {
+		if (existsSync(join(pluginsDir, e.id)) && !opts.force) {
+			console.log(`· 跳过 ${e.id}（已安装，加 --force 更新）`);
+			skipCount++;
+			continue;
+		}
+		try {
+			await installOnePlugin({
+				rawSpec: e.source,
+				name: e.id,
+				force: true,
+				build: opts.build === true,
+				noBuild: opts.noBuild === true,
+				dataDir,
+			});
+			console.log(`✔ ${e.id} 安装成功`);
+			okCount++;
+		} catch (err) {
+			console.error(`✖ ${e.id} 安装失败：${err?.message ?? err}`);
+			failCount++;
+		}
+	}
+	console.log(`✔ 目录安装完成：${okCount} 成功 / ${failCount} 失败 / ${skipCount} 跳过（已安装）`);
+	if (failCount) process.exitCode = 1;
+}
+
+async function pluginInstallCmd(argv) {
+	const { opts, positionals } = parseFlags(argv);
+	if (opts.help) {
+		console.log(PLUGIN_HELP);
+		return;
+	}
+	// 目录同步模式（issue #165）：install --catalog <url> —— 读目录文档 → 校验 →
+	// 原子写盘 → 逐条安装/更新（与服务端 plugin-catalog-sync 同语义）。
+	if (opts.catalog !== undefined) {
+		if (positionals.length !== 0)
+			fail(
+				`用法: pi-web-ui install --catalog <目录> [--data-dir <dir>] [--force] [--build|--no-build] [--replace]\n${PLUGIN_HELP}`,
+			);
+		if (opts.name) fail("--catalog 模式下 --name 无意义（目录名/id 来自目录条目）");
+		await installCatalogCmd(opts);
+		return;
+	}
+	if (positionals.length !== 1)
+		fail(
+			`用法: pi-web-ui install <源> [--name <id>] [--data-dir <dir>] [--force] [--build|--no-build]\n${PLUGIN_HELP}`,
+		);
+	try {
+		const { id, target, manifest } = await installOnePlugin({
+			rawSpec: positionals[0],
+			name: opts.name,
+			force: opts.force === true,
+			build: opts.build === true,
+			noBuild: opts.noBuild === true,
+			dataDir: pluginDataDir(opts),
+		});
 		console.log(
 			`✔ 已安装插件 ${id}${manifest.name && manifest.name !== id ? `（${manifest.name}）` : ""}${manifest.version ? ` v${manifest.version}` : ""}`,
 		);
 		if (manifest.description) console.log(`  ${manifest.description}`);
 		console.log(`  位置: ${target}`);
 		console.log(`  生效: 服务运行中刷新浏览器即可加载；未运行则下次启动生效。卸载: pi-web-ui uninstall ${id}`);
-	} finally {
-		rmSync(tmp, { recursive: true, force: true });
+	} catch (err) {
+		fail(`${err?.message ?? err}`);
 	}
 }