pi-web-ui 0.95.0 → 0.96.0

package/CHANGELOG.md

@@ -10,6 +10,41 @@
 
 ## [Unreleased]
 
+## [0.96.0] — 2026-09-26
+
+### Added
+
+- **内置 LSP 工具新增四个语义动作（#331 Phase 1）** —— `documentSymbol`（分层符号大纲，带行跨度与 300 条防洪截断）、`read_symbol`（按符号名/点分路径精准读取实现体，双遍扫描精确匹配优先、400 行截断、未命中时自愈提示可用符号）、`workspaceSymbol`（工作区全局符号搜索，100 条上限，可不传 `path` 自动探测主文件路由语言服务）、`cascade`（编辑影响级联：查引用方文件并聚合其编译诊断，改坏签名当轮即暴露）。提示词开销保持 ~350 tokens；设置页工具说明中英文同步。
+- **系统提示词与工具 schema token 占用实时估算** —— 设置面板「系统提示词」支持直接查看当前会话实际生效的完整系统提示词与工具 schema 定义，并展示粗略 token 估算值与上下文总占用；工作区与活跃会话切换时主动同步最新设置快照，避免提示词上下文陈旧。
+- **核心内置工具独立开关与运行时门控** —— 设置页新增「核心工具」配置区，支持独立开启/禁用 `bash`、`read`、`edit`、`write` 原生核心工具；工具禁用状态随会话即时生效，并在系统提示词与 tools schema 中同步过滤与剔除，杜绝无效工具调用。
+- **新增内置主题** —— 新增三款内置现代与古典主题：赛博科幻暗色 HUD 风格「以太座舱 (Aetheris HUD)」、古籍朱印浅色风「朱批 (Vermilion Manuscript)」与深色夜读风「朱批·夜 (Vermilion Night)」。
+- **消息气泡复制菜单与直接重问增强** —— 消息底栏复制按钮升级为下拉菜单，支持一键复制 Markdown、纯文本或生成长图 PNG；新增「直接重问」快捷按钮，无需重新聚焦编辑框即可立即复用上一条指令；消息气泡增加右键上下文菜单，支持快速复制、编辑/直接重问、派生分支、回滚到此与语音朗读。
+- **TTS 语音朗读与流式生成提示音** —— 助手消息气泡支持单条 TTS 语音朗读与停止；新增流式开始与完成提示音，后台生成完毕及时提醒。
+
+### Fixed
+
+- **非全功能预设（如代码开发/极简/纯对话）下提示词泄露已禁用工具指南修复** —— `before_agent_start` 提示词组装现在严格按会话当前真正处于活跃状态的工具集合（`activeTools`）过滤 Guidelines 与 Snippets，防止未启用的工具（如 `plan_update`、`ask_user_question`、`subagent_*` 等）的提示词指南被无差别注入到给模型的系统提示词中；彻底解决在「代码开发」预设下 AI 因收到动代码前调用 `plan_update` 的硬性指令而误调用未激活工具导致报错无效的问题；会话创建（`makeRuntimeFactory`）与重载（`reloadSession`）全生命周期对齐当前会话预设门控。
+- **助手气泡 Fork / 回滚无法解析修复（#381）** —— 统一 `server/serialize.ts` 的 `uiMessageId` 与 `findEntryByUiId` 算法为单一事实源，彻底修复从助手气泡触发分支派生（Fork）或回滚到此消息时因 ID 生成算法漂移导致的解析失败问题。
+- **悬空工具调用修复收紧分支与上线检查（#332）** —— `healDanglingToolCallFile` 与 `findDanglingToolCalls` 现在严格过滤 `stopReason` 为 `error` 或 `aborted` 的 assistant（不上线幽灵调用，避免在文件尾补合成结果构造出孤儿 `role: "tool"` 导致 DeepSeek/OpenAI 400 报错），且文件落盘修复仅沿活跃分支 `lastId` 向上回溯当前尾部生效 assistant，彻底跳过老分支遗留的悬空调用，防止跨分支污染。
+- **微信通道插件问题修复（#345）** —— 微信回包自动剥离内部控制标记（如 `[[plan:...]]`、`[[todo:...]]`、`[[conv:...]]`、`[[notify:...]]` 等），仅向微信发送用户可见正文；按微信用户 ID 隔离 `accountId`（`wx_${hash}`），为每个用户分配独立的伪客户端与会话，防止上下文串扰与关闭冲突；增加 `earlyRuns` 机制妥善承接极快完成的运行事件，消除回包竞态。
+- **SoL-Pi 节能看板弹窗展示优化** —— 扩展运行与配置区域默认采用折叠组件收拢，避免未折叠时挤占弹窗主视区。
+
+### Changed
+
+- **输入框 `@` 提及支持技能（skills）自动补全** —— 在消息文本任意位置键入 `@` 或 `@skill:` 即可弹出技能候选列表（名称匹配优先于描述匹配，支持中英文双语描述检索与 `@page` 页面置顶防挤占）；点选后自动在光标处插入 `@skill:<name>` 词元，与 Pi 运行时的技能提升扩展无缝联动。
+- **收敛型澄清提问与决策就绪型计划规范（#330）** —— `ask_user_question` 现在单次严格限制 1~3 个问题（优先 1 个，超过 3 个直接报错阻断，防止问卷轰炸），选项 schema 收紧为 2~4 个互斥选项且推荐方案置顶，选项 description 要求一句话说明影响与权衡；`plan_update` 提示词升级为「决策就绪型」规划：动代码前先在步骤中落实排查发现（Discovery）、受影响文件清单（File Touch List）与风险回滚预案（Rollback），并随执行实时流转步骤状态。目标向导（`goal_ask` / wizardPrompt）与 DSH 澄清提示词同步对齐收敛型交互。
+
+<!-- auto-i18n:start -->
+### i18n
+
+- 前端新增 key（49）：`reaskDirectly`、`reaskDirectlyTip`、`kindPlugin`、`pluginCheckUpdates`、`pluginCheckUpdatesHint`、`pluginUpdateAvailableBadge`、`pluginUpdateAvailableDetail`、`pluginAllUpToDate`、`piCoreSplitRun`、`piSdkSplitNote`、`piSdkBundledNote`、`installGlobalEngineBtn`、`installGlobalEngineTabTitle`、`saveResultUnknown`、`questionNoneAvailable`、`notifyApprovalTitle`、`notifyApprovalBody`、`notifyApprovalBodyTool`、`sound.approval`、`sound.approval.desc`、`settingsSoundVoice`、`ttsHeader`、`ttsEnable`、`ttsEnableDesc`、`ttsAnnounce`、`ttsAnnounceDesc`、`ttsReadReplies`、`ttsReadRepliesDesc`、`ttsRate`、`ttsVoice`、`ttsVoiceAuto`、`ttsVoiceOnline`、`ttsUnavailable`、`ttsPreviewLine`、`ttsAnnounceDone`、`ttsAnnounceQuestion`、`ttsAnnounceError`、`ttsAnnounceApproval`、`speakMsg`、`stopSpeakingMsg`、`apiKeySavedHint`、`settingsViewPromptTokens`、`settingsPromptContextTotal`、`toolsSectionCore`、`toolsCoreHint`、`toolCoreBashDesc`、`toolCoreReadDesc`、`toolCoreEditDesc`、`toolCoreWriteDesc`
+- 前端中文变更（2）：`settingsViewToolsSchema`、`lspToolEnabledDesc`
+- 前端英文变更（2）：`settingsViewToolsSchema`、`lspToolEnabledDesc`
+- 服务端新增 key（3）：`plugincatalog.sync.doc.invalid`、`terminals.bash.nosentinel.note`、`terminals.command.blocked`
+- 服务端文案变更（1）：`terminals.bash.timeout`
+- 服务端删除 key（2）：`plugincatalog.sync.source.invalid`、`plugincatalog.sync.read.failed`
+<!-- auto-i18n:end -->
+
 ## [0.95.0] — 2026-09-24
 
 ### Added
@@ -30,9 +65,11 @@
 - **受控的持久代码求值沙箱工具 `eval`（opt-in，默认关）** — 新第一方 customTool：在隔离子进程中执行 Python（`py`）或 JavaScript/TypeScript（`js`/`ts`），变量与导入跨调用保持，顶层表达式自动求值回显（省掉以往 `write` 临时脚本 → `bash` 跑 → 删文件的三步流程）。设计要点：① 默认关（`AGENT_TOOL_CATALOG` 里 `defaultOn: false`），关掉 AI 不知道有它，杜绝「什么问题都塞进内核」的工具挤占；② 每个会话一个独立内核进程 + 独立临时目录（cwd 不落在项目里，项目路径经 `PROJECT_DIR` 变量显式引用），关对话 / 停服务即回收进程树（Windows `taskkill /F /T`，Unix `SIGKILL` 进程组），不留孤儿；③ 单请求默认 15s、上限 120s 硬超时，超时杀进程树后内核自动重启，不会把会话拖死；④ 驱动协议串行排队，并行 `eval` 调用不会互相覆盖 resolver；⑤ stderr 持续排空，避免原生扩展写满管道缓冲造成假超时。DSH 引擎无 customTool 注册面，不接。
 
 ### Changed
+
 - **插件 manifest 校验失败即拒（P1-6）** — 坏 manifest 不再带病启动：`id` 非法/与目录名不一致、`apiVersion` 非法、未知能力拼写、`engines`/`permissions`/`ui` 坏形状、v2 不声明 `permissions`、有 `ui` 声明却无 `ui` 能力，都会拒绝激活（scan 置红 + 诊断随清单下发，activate 重判）。以前其中两类（v2 无能力声明、只有别的能力却写 `ui`）是"激活成功但 ui 静默忽略"，现在是明确拒绝；纯警告（坏文本字段/坏数组字段/截断）仍不阻断。未来版本（`apiVersion` 大于宿主）仍走版本门出"请升级"，校验层不抢错。
 
 ### Fixed
+
 - **目标调研向导：切会话不再丢弃调研成果，且消息流里有「原始目标草案」卡片（#292）** — 两处修复：① `setGoal` 新增 `targetConvId`，调研收敛后把目标写到**发起调研的那个对话**（原来是硬读 `activeConv` 再一刀切丢：「已切换对话，目标调研结果已丢弃」——用户在向导问答期间切去看代码/文档是常态，多轮问答瞬间白做）；发起会话已关闭时响亮拒绝而不是静默丢。完成通知随之改成点名会话（`🎯 会话「title」目标调研完成，目标已设为…`），取消/无结果时也告诉用户草案还在哪儿。② 调研开始先往发起对话推一张只读「🎯 原始目标草案」卡片，排在所有提问之前——调研被超时/取消打断后，用户至少能把自己最初写的那段需求读回来、复制重试，而不是面对一片空白。
 - **子代理（in-memory 会话）的扩展错误不再按轮数刷屏（#298）** — `SessionManager.inMemory(cwd)` 建出来的子代理会话取不到会话目录（`getSessionDir()` 返回空串），而 SDK 的 `ExtensionRunner.emitContext()` 在**每次 provider 请求**前都会跑一遍扩展的 `context` hook，于是「会话目录依赖型」扩展（如 SoL-Pi 的 `runtimeRoot()`）每轮都抛同一个错。原 `bindExtensions` 的 `onError` 把错误原样广播成 notice：不去重、不带会话归属、不落服务端日志，一个子代理跑 N 轮就弹 N 条，且看不出是哪个会话出的问题。现改为共享的 `makeExtensionErrorReporter()`：① 同一会话内「扩展 + 事件 + 错误文本」只提示一次；② 子代理的 notice 带 `子代理 <conversationId>：` 前缀（与同函数内其它子代理通知口径一致）；③ 全量错误（含 extensionPath / event / stack）始终 `console.error` 落服务端日志。主对话（持久会话）行为不变，只是多了去重与日志。
 - **插件市场仅同步列表时保留已激活插件实例（#296，感谢 @StarryJia）** — 启动预同步和手动目录同步不再重载插件，避免重新激活时重复广播当前工作目录。
@@ -45,6 +82,7 @@
 - **任务执行看板与对话列等宽** — Plan Mode 的任务执行看板（`PlanBoard`）此前写死左右各 16px 外边距，没走 `.main` 的列 token（`--chat-inset`）：桌面 / 宽屏聊天列下比消息列与输入框宽一截、手机上又比它们窄一点，左右边缘始终对不齐。现改为同一条列 token（`.plan-board` 落进 `styles.css`，与 `.goalbar` / 问卷面板同口径），任何视口宽度与「宽屏聊天列」开关下都与输入框严格齐平。回归：`tests/chat-column-align-test.mjs` 新增看板条目。
 
 <!-- auto-i18n:start -->
+
 ### i18n
 
 - 前端新增 key（104）：`newChatEphemeral`、`newChatEphemeralTip`、`ephemeralBadge`、`ephemeralBannerText`、`elsewhereActions`、`takeoverConfirm`、`saveEphemeral`、`forkSession`、`forkSessionTip`、`rollbackSession`、`rollbackSessionTip`、`rollbackConfirm`、`rollbackRestoreWorkspace`、`rollbackRestoreWorkspaceTip`、`toolApprovalTitle`、`toolApprovalApprove`、`toolApprovalDeny`、`toolApprovalEditAndRun`、`toolApprovalRiskAlert`、`toolApprovalCommand`、`toolApprovalParams`、`toolApprovalEditPlaceholder`、`toolApprovalReason`、`toolApprovalCategory`、`toolApprovalAllowCategory`、`toolApprovalAllowCategoryHint`、`toolApprovalAllowConversation`、`toolApprovalAllowConversationHint`、`toolApprovalEnabled`、`toolApprovalEnabledDesc`、`toolApprovalPolicyTitle`、`toolApprovalPolicyAllowAll`、`toolApprovalPolicyRevoke`、`toolApprovalPolicyHint`、`settingsApprovalRules`、`settingsApprovalRulesDesc`、`manageApprovalRules`、`approvalRuleNew`、`approvalRuleEdit`、`approvalRuleDelete`、`approvalRuleReset`、`approvalRuleResetConfirm`、`approvalRuleDeleteConfirm`、`approvalRuleActionAsk`、`approvalRuleActionDeny`、`approvalRuleActionAllow`、`approvalRuleTools`、`approvalRuleToolsTip`、`approvalRuleField`、`approvalRuleFieldCommand`、`approvalRuleFieldPath`、`approvalRuleFieldParams`、`approvalRuleMatch`、`approvalRuleMatchRegex`、`approvalRuleMatchGlob`、`approvalRuleMatchContains`、`approvalRuleMatchPrefix`、`approvalRuleMatchOutsideWs`、`approvalRuleValue`、`approvalRuleValueTip`、`approvalRuleLabel`、`approvalRuleLabelEn`、`approvalRuleReason`、`approvalRuleReasonEn`、`approvalRuleEnabled`、`approvalRuleBuiltin`、`approvalRuleEmpty`、`approvalRuleMoveUp`、`approvalRuleMoveDown`、`planBoardTitle`、`planBoardSteps`、`planBoardProgress`、`planBoardNoPlan`、`planBoardCompleted`、`planBoardInProgress`、`planBoardPending`、`planBoardFailed`、`clear`、`confirm`、`forkBadge`、`forkBadgeTip`、`goalBarBlocked`、`toolsPresetBanner`、`toolsBackToStandard`、`toolsBlockedByPreset`、`skillsHiddenByPreset`、`terminalBashMaxForegroundMs`、`terminalBashMaxForegroundMsDesc`、`pluginInspectAlreadyInstalled`、`pluginInspectInvalid`、`pluginInspectNotPlugin`、`pluginInspectNetwork`、`uiLayoutDiagTitle`、`uiLayoutDiagHint`、`planUpdateEnabledDesc`、`planUpdateOffHint`、`compactContextEnabledDesc`、`compactContextOffHint`、`evalEnabledDesc`、`evalOffHint`、`patchToolEnabledDesc`、`patchToolOffHint`、`lspToolEnabledDesc`、`lspToolOffHint`
@@ -54,6 +92,7 @@
 - 服务端新增 key（14）：`editsoft.fragment.not.supported`、`goal.wizard.draft.card`、`goal.autonomous.pass`、`goal.review.blocked`、`goal.autonomous.continue`、`goal.review.blocked_msg`、`plugins.requires.cycle`、`plugins.manifest.invalid`、`plugins.requires.cascade`、`subagents.handoff.self`、`subagents.handoff.not.found`、`subagents.handoff.success`、`subagents.handoff.failed`、`terminals.bash.background.elapsed`
 - 服务端文案变更（1）：`terminals.bash.background.running`
 - 服务端删除 key（2）：`dsh.attach.file.large`、`dsh.attach.file.ref.fallback`
+
 <!-- auto-i18n:end -->
 
 ## [0.94.1] — 2026-09-22
@@ -1254,7 +1293,9 @@ when?, children?}`，也收 `topbar` / `settings` 这类简写别名）；宿主
 - 0.35.1（2026-08-27）：编辑重问保留附件（#18）+ 全窗口拖放（#19）。
 - 0.29.0（2026-08-23）：全局搜索弹窗（Ctrl+K）+ 消息列表惰性窗口化。
 
-[Unreleased]: https://github.com/xing-shuyin/pi-web-ui/compare/v0.93.0...main
+[Unreleased]: https://github.com/xing-shuyin/pi-web-ui/compare/v0.96.0...main
+[0.96.0]: https://github.com/xing-shuyin/pi-web-ui/releases/tag/v0.96.0
+[0.95.0]: https://github.com/xing-shuyin/pi-web-ui/releases/tag/v0.95.0
 [0.94.1]: https://github.com/xing-shuyin/pi-web-ui/releases/tag/v0.94.1
 [0.94.0]: https://github.com/xing-shuyin/pi-web-ui/releases/tag/v0.94.0
 [0.93.0]: https://github.com/xing-shuyin/pi-web-ui/releases/tag/v0.93.0

package/bin/pi-web-ui.mjs

@@ -27,6 +27,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { createConnection } from "node:net";
 import { get as httpGet } from "node:http";
+import { createInterface } from "node:readline/promises";
 import {
 	ensureBackup as ensurePluginBackup,
 	restoreBackup as restorePluginBackup,
@@ -55,9 +56,9 @@ import { fileURLToPath } from "node:url";
 const BIN_DIR = dirname(fileURLToPath(import.meta.url));
 /** <pkg>/dist/server/index.js — the actual server entry. */
 const SERVER_ENTRY = join(BIN_DIR, "..", "dist", "server", "index.js");
-/** 可选的「优先用全局/祖先那份 pi SDK」解析钩子（issue #260，`PI_WEB_SDK=global` 才生效）。
+/** 「机器上有更新的 pi 副本就跟随它」解析钩子（issue #260；#321 起默认启用）。
  *  必须早于任何 SDK 静态 import 加载 —— 所以每条启动路径都把它当 `--import` 传进去；
- *  默认不启用时它自己什么都不做（见 server/resolve-global-sdk.ts）。 */
+ *  PI_WEB_SDK=bundled 显式钉死自带副本（见 server/resolve-global-sdk.ts）。 */
 const SDK_HOOK = join(BIN_DIR, "..", "dist", "server", "resolve-global-sdk.js");
 /** dist 可能是旧构建（没有这个钩子文件）—— 只有文件在才注入：`--import <missing>` 会让
  *  CLI/服务直接起不来，那比少个开关严重得多。 */
@@ -108,8 +109,9 @@ server 选项:
   --engine <pi|dsh> 智能体引擎（默认 $PI_WEB_ENGINE 或 pi）
   --host <addr>     监听地址（默认 $PI_WEB_HOST 或 127.0.0.1；0.0.0.0 供局域网/容器）
   --agent-dir <dir> pi 配置目录（默认 $PI_CODING_AGENT_DIR 或 ~/.pi/agent）
-  --name <name>     服务名（默认 pi-web-ui；macOS 的 launchd label
-                    为 com.xingshuyin.pi-web-ui，自定义名时为 com.<name>.server）
+  --name <name>     服务名（默认 pi-web-ui；仅限字母/数字/-/_，字母或数字开头，
+                    最长 64 字符。macOS 的 launchd label 为 com.xingshuyin.pi-web-ui，
+                    自定义名时为 com.<name>.server）
   --print           只打印将生成的配置文件，不实际安装
 
 平台: macOS → launchd 用户代理 · Linux → systemd · Windows → 登录自启 Run 键
@@ -128,7 +130,8 @@ server 选项:
   install 选项: --name <id> 自定义插件目录名（默认取仓库名）
                 --data-dir <dir> 数据目录（默认 ~/.pi-web）
                 --force 目标已存在时覆盖
-                --build 强制源码构建（隔离目录编译，见下）
+                --build 强制源码构建（隔离目录编译，见下；不加 --build 时若插件只有
+                        源码，交互终端会询问是否构建并需输入 y 确认，非交互环境跳过）
                 --no-build 即使只有源码也不构建（产物缺失的插件装上后不加载）
                 --catalog <url> 目录同步模式：读目录文档 → 写可安装列表 → 逐条安装
                 --replace 配合 --catalog：整体替换列表（默认按 id 合并）
@@ -161,7 +164,8 @@ Server options:
   --engine <pi|dsh> Agent engine (default $PI_WEB_ENGINE or pi)
   --host <addr>     Listen address (default $PI_WEB_HOST or 127.0.0.1; 0.0.0.0 for LAN/containers)
   --agent-dir <dir> pi config directory (default $PI_CODING_AGENT_DIR or ~/.pi/agent)
-  --name <name>     Service name (default pi-web-ui; macOS launchd label is
+  --name <name>     Service name (default pi-web-ui; alphanumeric, "-" and "_" only,
+                    starting with a letter or digit, max 64 chars. macOS launchd label is
                     com.xingshuyin.pi-web-ui, or com.<name>.server for custom names)
   --print           Only print generated config files (no actual install)
 
@@ -181,7 +185,9 @@ 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)
+                   --build       Force a source build (isolated build, see below). Without it,
+                                 a source-only plugin asks for confirmation on a TTY (answer y to
+                                 build) and skips the build in non-interactive environments
                    --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
@@ -519,8 +525,16 @@ function winIcoPath() {
 	return join(winServiceDir(), APP_ICO_NAME);
 }
 
-/** Full path to Windows PowerShell 5.1. */
+/** Full path to Windows PowerShell. Prefers pwsh.exe (PowerShell 7) when it is
+ * resolvable on PATH: some machines ship Windows PowerShell 5.1 as a broken
+ * stub whose launch fails silently, so probe for a working shell first and
+ * fall back to the built-in path. */
 function winPowershell() {
+	const which = spawnSync("where.exe", ["pwsh.exe"], { encoding: "utf8" });
+	if (which.status === 0) {
+		const first = (which.stdout ?? "").trim().split(/\r?\n/)[0];
+		if (first) return first;
+	}
 	return join(process.env.SystemRoot ?? "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
 }
 
@@ -535,12 +549,13 @@ function winWscript() {
  * Resolve the real node binary. fnm/volta/nvm shims (e.g. fnm_multishells)
  * point into temp dirs that vanish when the installing shell exits — the
  * baked-in launcher scripts must use the stable real path instead.
+ * Also applies resolveNode() so Bun-hosted pi never bakes in pi.exe.
  */
 function realNode() {
 	try {
-		return realpathSync(process.execPath);
+		return realpathSync(resolveNode());
 	} catch {
-		return process.execPath;
+		return resolveNode();
 	}
 }
 
@@ -682,7 +697,11 @@ function buildWinHiddenVbs(ps1Path) {
 function installWinShortcut(opts) {
 	const { name, port, cwd, dataDir, engine, host, agentDir } = serviceOptions(opts);
 	const env = serviceEnv(port, cwd, dataDir, engine, host, agentDir);
-	const url = `http://localhost:${port}`;
+	// The server binds 127.0.0.1 by default; PowerShell 7's Invoke-WebRequest
+	// resolves `localhost` to ::1 first and hangs until TimeoutSec when nothing
+	// listens on IPv6, making the health probe misfire ("server not running").
+	// Pin the probe (and the opened URL) to the IPv4 loopback the server uses.
+	const url = `http://127.0.0.1:${port}`;
 	const ps1Path = winShortcutPs1Path(name);
 	const ps1 = buildWinShortcutPs1(env, cwd, name, url, winLogPath(name), winPidFilePath(name));
 	if (opts.print) {
@@ -986,19 +1005,53 @@ function launchWinService(vbsPath) {
 	child.unref();
 }
 
+/**
+ * PID 文件记录的是看门狗 PowerShell 的 $PID（winPowershell() 可能选 pwsh.exe），
+ * node 是它的子进程 —— 这三者是本服务实例的合理映像名。taskkill /T /F 是树级强杀，
+ * PID 若已退出被系统复用就会误杀无辜进程，所以杀前必须核对映像名。
+ */
+const WIN_SERVICE_IMAGE_RE = /^(powershell|pwsh|node)\.exe$/i;
+
+/** tasklist 查询 PID 对应的进程映像名；查询失败/无此进程返回 null（无法核实）。 */
+function winPidImageName(pid) {
+	const res = spawnSync("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"], { encoding: "utf8" });
+	if (res.status !== 0) return null;
+	const line = (res.stdout ?? "").split(/\r?\n/).find((l) => l.trim());
+	if (!line) return null; // tasklist 的 "INFO: 无任务" 输出没有 CSV 行
+	return (line.match(/^"([^"]+)"/) ?? [])[1] ?? null;
+}
+
 /** Kill a running Windows instance via its PID file (whole tree). */
 function stopWinInstance(name) {
 	const pid = winReadPid(name);
 	if (pid) {
 		if (pidAlive(pid)) {
-			run("taskkill", ["/PID", String(pid), "/T", "/F"], {
-				ignoreError: true,
-				silent: true,
-			});
-			// taskkill /F 异步生效：等到进程树真正退出（restart 需要避免端口竞争）
-			const deadline = Date.now() + 5000;
-			while (Date.now() < deadline && pidAlive(pid)) {
-				spawnSync("ping", ["-n", "2", "127.0.0.1"], { stdio: "ignore" });
+			// PID 可能已退出并被系统复用给别的进程：杀前核对映像名，不符则警告并跳过，
+			// 绝不 taskkill /T /F 盲杀。macOS/Linux 无按 PID 杀的路径（launchctl/systemctl
+			// 按服务单元管理），只有 Windows 需要这道核对。
+			const image = winPidImageName(pid);
+			if (image === null) {
+				console.warn(
+					ZH
+						? `⚠ 无法核实 PID ${pid} 的进程映像名（tasklist 不可用或进程已消失），跳过强制结束以防误杀`
+						: `⚠ Cannot verify the image name of PID ${pid} (tasklist unavailable or process gone), skipping force-kill to avoid killing an unrelated process`,
+				);
+			} else if (!WIN_SERVICE_IMAGE_RE.test(image)) {
+				console.warn(
+					ZH
+						? `⚠ PID ${pid} 现在是 ${image}，不是本服务的进程（PID 可能已被复用），跳过强制结束`
+						: `⚠ PID ${pid} is now ${image}, not a pi-web-ui process (PID may have been reused), skipping force-kill`,
+				);
+			} else {
+				run("taskkill", ["/PID", String(pid), "/T", "/F"], {
+					ignoreError: true,
+					silent: true,
+				});
+				// taskkill /F 异步生效：等到进程树真正退出（restart 需要避免端口竞争）
+				const deadline = Date.now() + 5000;
+				while (Date.now() < deadline && pidAlive(pid)) {
+					spawnSync("ping", ["-n", "2", "127.0.0.1"], { stdio: "ignore" });
+				}
 			}
 		}
 		rmSync(winPidFilePath(name), { force: true });
@@ -1110,9 +1163,27 @@ function effectivePort(opts) {
 	return String(opts.port ?? process.env.PI_WEB_PORT ?? "8787");
 }
 
+/**
+ * 服务名（--name）统一校验。name 会被原样拼进 systemd unit 文件名
+ * (/etc/systemd/system/<name>.service)、Windows 启动脚本/PID 文件路径
+ * (%APPDATA%\pi-web-ui\<name>.ps1) 与 HKCU Run 键值名 —— 不限字符集时，
+ * 路径分隔符/引号/空格都能进这些拼接点（路径穿越或 unit 内容注入）。
+ * 收紧为：字母或数字开头，仅字母/数字/-/_，最长 64 字符。
+ */
+function serviceName(opts) {
+	const name = opts.name ?? "pi-web-ui";
+	if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name))
+		fail(
+			ZH
+				? `无效服务名 "${name}"（仅限字母/数字/-/_，字母或数字开头，最长 64 字符）`
+				: `Invalid service name "${name}" (alphanumeric, "-" and "_" only; must start with a letter or digit; max 64 chars)`,
+		);
+	return name;
+}
+
 /** Shared option normalization for install. */
 function serviceOptions(opts) {
-	const name = opts.name ?? "pi-web-ui";
+	const name = serviceName(opts);
 	const port = effectivePort(opts);
 	if (!/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535) {
 		fail(ZH ? `无效端口: ${port}` : `Invalid port: ${port}`);
@@ -1267,7 +1338,7 @@ function installSystemd(opts) {
 }
 
 function uninstallLaunchd(opts) {
-	const name = opts.name ?? "pi-web-ui";
+	const name = serviceName(opts);
 	const label = serviceLabel(name);
 	const plist = launchAgentPlist(name);
 	run("launchctl", ["bootout", `gui/${uid()}/${label}`], {
@@ -1285,7 +1356,7 @@ function uninstallLaunchd(opts) {
 }
 
 function uninstallSystemd(opts) {
-	const name = opts.name ?? "pi-web-ui";
+	const name = serviceName(opts);
 	ensureRootForSystemctl();
 	run("systemctl", ["disable", "--now", `${name}.service`], {
 		ignoreError: true,
@@ -1368,7 +1439,7 @@ function installWindows(opts) {
 }
 
 function uninstallWindows(opts) {
-	const name = opts.name ?? "pi-web-ui";
+	const name = serviceName(opts);
 	winRunKeyDelete(name);
 	// 历史计划任务（旧版本 install 可能注册过）
 	if (winTaskExists(name)) {
@@ -1503,7 +1574,7 @@ async function setQuiesce(opts, on) {
 }
 
 function controlService(action, opts) {
-	const name = opts.name ?? "pi-web-ui";
+	const name = serviceName(opts);
 
 	if (isMac) {
 		const label = serviceLabel(name);
@@ -2072,11 +2143,13 @@ function buildPluginSource(pluginRoot, tmpDir, manifest) {
  * 构建决策（issue #165：--build 自动推断）。
  *
  * 只有源码、没有产物（index.mjs 与 client/entry.mjs 都缺）且存在可解析的构建声明 =
- * “不构建这次安装必死”，此时默认直接构建（ previously 只打印一行提示，等用户滚回去重加
- * --build）。产物已提交的仓库不受影响（mode=none，什么都不跑）。
+ * “不构建这次安装必死”，此前会直接自动构建；但构建命令来自远端 manifest/package.json，
+ * 经 shell:true 执行属于任意命令执行面，非交互环境下静默跑等于替用户放行。
+ * 收紧后（审计修复）：mode=auto 只表示“有构建声明且必要”，是否真正执行由
+ * installOnePlugin 二次把关 —— 交互 TTY 且用户输入 y 才跑，否则跳过并警告。
  * --no-build 保留旧的“装个空目录”行为（脚本化镜像/检查用），并明确打印跳过原因。
  */
-function decideBuildAction({ pluginRoot, manifest, build, noBuild }) {
+function decideBuildAction({ pluginRoot, manifest, build, noBuild, isCatalog = false }) {
 	if (build && noBuild)
 		throw new Error(
 			ZH ? "--build 与 --no-build 不能同时用（二选一）" : "--build and --no-build cannot be used together (pick one)",
@@ -2085,12 +2158,14 @@ function decideBuildAction({ pluginRoot, manifest, build, noBuild }) {
 	const artifactsMissing =
 		!existsSync(join(pluginRoot, "index.mjs")) && !existsSync(join(pluginRoot, "client", "entry.mjs"));
 	if (build) {
-		if (!plan)
+		if (!plan) {
+			if (isCatalog) return { mode: "none", plan };
 			throw new Error(
 				ZH
 					? "插件没有声明构建方式：请在 manifest.json 里加 build.command（或 package.json 的 scripts.build），或去掉 --build"
 					: "Plugin has no build declaration: add build.command to manifest.json (or scripts.build in package.json), or remove --build",
 			);
+		}
 		return { mode: "explicit", plan };
 	}
 	if (plan && artifactsMissing) {
@@ -2100,12 +2175,31 @@ function decideBuildAction({ pluginRoot, manifest, build, noBuild }) {
 	return { mode: "none", plan };
 }
 
+/**
+ * 交互确认：插件声明的构建命令将经 shell 在本机执行（install + command 都来自
+ * 远端 manifest/package.json），必须用户显式输入 y 才跑。仅 TTY 下会被调用。
+ */
+async function confirmSourceBuild(plan) {
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		const answer = await rl.question(
+			ZH
+				? `⚠ 插件声明了以下构建命令，将在本机以 shell 执行：\n    1) ${plan.install}\n    2) ${plan.command}\n  确认执行？输入 y 继续，其他任意键跳过构建: `
+				: `⚠ The plugin declares the following build commands, which will run through a shell on this machine:\n    1) ${plan.install}\n    2) ${plan.command}\n  Proceed? Enter y to run, anything else to skip the build: `,
+		);
+		const normalized = answer.trim().toLowerCase();
+		return normalized === "y" || normalized === "yes";
+	} finally {
+		rl.close();
+	}
+}
+
 /**
  * 装一个插件（单源模式与目录模式共用）：拉取/定位 → 读 manifest → 构建决策 →
  * 覆盖（备份+保留 config.json）→ 落盘 → 记录来源/sha。
  * 失败抛 Error（目录模式逐条 try/catch 继续下一条，单源模式由调用方转 fail）。
  */
-async function installOnePlugin({ rawSpec, name, force, build, noBuild, dataDir }) {
+async function installOnePlugin({ rawSpec, name, force, build, noBuild, dataDir, isCatalog = false }) {
 	const pluginsDir = join(dataDir, "plugins");
 	const localCandidate = resolve(rawSpec.replace(/^file:\/\//, ""));
 	const isLocal = existsSync(localCandidate);
@@ -2132,9 +2226,36 @@ async function installOnePlugin({ rawSpec, name, force, build, noBuild, dataDir
 		}
 		// 构建决策（issue #150 的 --build + issue #165 的自动推断）：构建在临时目录里完成，
 		// 成功后才进入覆盖流程——构建失败 = 目标目录完全没被动过（上一版插件照常可用）。
-		const decision = decideBuildAction({ pluginRoot, manifest, build: build === true, noBuild: noBuild === true });
+		const decision = decideBuildAction({
+			pluginRoot,
+			manifest,
+			build: build === true,
+			noBuild: noBuild === true,
+			isCatalog,
+		});
+		// 授权把关（审计修复）：--build 显式传参行为不变；mode=auto 的构建命令来自
+		// 远端 manifest/package.json 且经 shell:true 执行 —— 非交互环境绝不自动跑
+		// （跳过并警告），交互 TTY 也要用户显式输入 y 才执行。
+		let authorized = decision.mode === "explicit";
+		if (decision.mode === "auto") {
+			if (!process.stdin.isTTY) {
+				console.warn(
+					ZH
+						? "⚠ 插件声明了构建命令但未授权执行，已跳过构建 —— 传 --build 或手动构建后再安装"
+						: "⚠ Plugin declares build commands but they were not authorized; skipping the build — pass --build or build manually before installing",
+				);
+			} else {
+				authorized = await confirmSourceBuild(decision.plan);
+				if (!authorized)
+					console.warn(
+						ZH
+							? "⚠ 未确认执行构建命令，已跳过构建 —— 需要时传 --build 或手动构建后再安装"
+							: "⚠ Build commands not confirmed; skipping the build — pass --build or build manually if needed",
+					);
+			}
+		}
 		let installRoot = pluginRoot;
-		if (decision.mode === "explicit" || decision.mode === "auto") {
+		if (authorized) {
 			console.log(
 				ZH
 					? `· 源码构建（${decision.mode === "auto" ? "自动推断：有构建声明但无产物" : "--build"}）：先 ${decision.plan.install}，再 ${decision.plan.command}`
@@ -2151,6 +2272,12 @@ async function installOnePlugin({ rawSpec, name, force, build, noBuild, dataDir
 					? "· 跳过构建（--no-build）：目录里没有产物，装上后该插件不会被加载"
 					: "· Skipping build (--no-build): no artifacts in directory, plugin will not load after install",
 			);
+		} else if (decision.mode === "auto") {
+			console.log(
+				ZH
+					? "· 已跳过构建：目录里没有产物，装上后该插件不会被加载（授权后重装可补产物）"
+					: "· Build skipped: no artifacts in directory, plugin will not load after install (re-install with authorization to build)",
+			);
 		}
 		// 默认 id：子目录名 > 仓库名 > 本地目录名
 		const sourceName = src?.subpath ? src.subpath.split("/").pop() : (src?.repo ?? localCandidate.split(/[\\/]/).pop());
@@ -2430,6 +2557,7 @@ async function installCatalogCmd(opts) {
 				build: opts.build === true,
 				noBuild: opts.noBuild === true,
 				dataDir,
+				isCatalog: true,
 			});
 			console.log(ZH ? `✔ ${e.id} 安装成功` : `✔ ${e.id} installed`);
 			okCount++;