pi-web-ui 0.97.0 → 0.99.0

package/dist/server/plan-mode.js

@@ -46,6 +46,9 @@ const BLOCKED_TOOLS = new Set([
     "rename",
     // 版本控制写（git add/commit/checkout/reset…；git 的只读子命令走 bash 白名单）
     "git",
+    // 代码求值（eval 沙箱的 execute 直接 kernel.execute，可写真实文件系统；
+    // 默认关但用户可开，开了就是一条写路径 —— #436）
+    "eval",
     // 形态变换（会重写整个文件树）
     "format",
     "prettier",
@@ -53,25 +56,43 @@ const BLOCKED_TOOLS = new Set([
     "autofix",
 ]);
 /**
- * 计划模式下也禁掉的「旁路工具」：它们能在**别的会话**里干活，而闸门是
- * 会话级的 —— 子代理/排程对话的 planMode 是 false，等于绕过只读约束。
- * 调研靠本对话的 read/grep/只读 bash 足够，需要并行调研时先退出计划模式。
+ * 常驻终端的「写向」工具（server/terminals.ts）：直接往 PTY stdin 写字符/按键。
+ * 必须整体剥离而不只是补检查：terminal_input 只在自带换行时才过 checkSafety，
+ * terminal_key 的 Enter 连检查都没有 —— 「input(无换行) + key(Enter)」两步即可
+ * 绕过 bash 只读白名单执行任意命令（#436）。且 PTY 的行编辑缓冲在 shell 进程内，
+ * 服务端拿不到可靠的「待提交行」（退格/Ctrl+U/补全都无法镜像），按缓冲检查既会
+ * 误放也会误拦 —— 所以计划模式下干脆不给这两件工具：调研用 bash（走白名单），
+ * 观察已有终端用 terminal_read/terminal_list/terminal_wait（只读）。
  */
-const BYPASS_TOOLS = new Set([
-    "spawn",
-    "spawn_agent",
-    "subagent_spawn",
-    "delegate_task",
-    "schedule_agent",
-    "host_schedule",
-    "create_goal",
-    "set_goal",
-    "start_goal_wizard",
-    "create_conversation",
-    "fork_conversation",
-]);
+const TERMINAL_WRITE_TOOLS = new Set(["terminal_input", "terminal_key"]);
+/**
+ * 三个只读闸门（计划 / 审查者 / 目标审查）共用的「派发类」工具名：它们会把活
+ * 派到**别的会话**执行（delegate_task 走子代理 spawn 通道；schedule_task 到期
+ * 唤醒对话跑 prompt），而这三道闸门都是会话级的 —— 放行即绕过。
+ *
+ * 名单以 server/tool-manager.ts 实际注册的工具名为事实源（#436）：历史名单里的
+ * spawn / spawn_agent / subagent_spawn / schedule_agent / host_schedule /
+ * create_goal / set_goal / start_goal_wizard / create_conversation /
+ * fork_conversation / schedule / set_plan_mode 等都是协议消息名或从未注册的
+ * 幽灵名，一个真实工具都没拦住，反而掩盖了 schedule_task 这类真实旁路工具
+ * 完全可用的事实。subagent 是单 action 工具，由各闸门按 action 细分（只读
+ * action 放行，见各闸门的判定函数）。
+ */
+export const SESSION_DISPATCH_TOOLS = new Set(["delegate_task", "schedule_task"]);
+/**
+ * 计划模式下也禁掉的「旁路工具」（真实派发类，见 SESSION_DISPATCH_TOOLS）：
+ * 它们能在**别的会话**里干活，而闸门是会话级的 —— 子代理/排程对话的
+ * planMode 是 false，等于绕过只读约束。调研靠本对话的 read/grep/只读 bash
+ * 足够，需要并行调研时先退出计划模式。
+ */
+const BYPASS_TOOLS = SESSION_DISPATCH_TOOLS;
 /** 计划模式下从模型视野中彻底隐藏的写类工具与旁路工具全集。 */
-export const PLAN_MODE_BLOCKED_TOOL_NAMES = new Set([...BLOCKED_TOOLS, ...BYPASS_TOOLS, "subagent"]);
+export const PLAN_MODE_BLOCKED_TOOL_NAMES = new Set([
+    ...BLOCKED_TOOLS,
+    ...BYPASS_TOOLS,
+    ...TERMINAL_WRITE_TOOLS,
+    "subagent",
+]);
 /** bash 类工具名（terminalBash 开关分流后可能是这几个）。 */
 const BASH_TOOLS = new Set(["bash", "bash_execute", "run_command", "shell", "terminal", "terminal_exec"]);
 /** 计划模式放行的只读命令（basename，无参数）。刻意保守：宁可拒一次让模型换命令。 */
@@ -238,6 +259,10 @@ function segmentIsReadOnly(segment) {
         return false;
     if (name === "awk" && /system\s*\(/.test(rest))
         return false;
+    // find 的 -exec/-delete/-fprintf 族有写副作用（issue #483）：白名单命中不等于只读，
+    // `find . -name '*.log' -delete` / `-exec touch x {} +` 无任何重定向特征，必须显式拒。
+    if (name === "find" && args.some((a) => /^-(exec|execdir|ok|okdir|delete|fprint0|fprint|fprintf|fls)$/.test(a)))
+        return false;
     // 解释器：只放行 --version/--help 这类无副作用调用。
     if (name === "node" || name === "python" || name === "python3" || name === "npm") {
         return args.length > 0 && args.every((a) => INTERPRETER_SAFE_ARGS.has(a));
@@ -274,6 +299,7 @@ function commandOf(params) {
  * 计划模式闸门（纯函数）：命中即拒绝，并把可操作的替代路径告诉模型。
  * - 写类工具 → 拒（提示：把要做的事写进计划，用户确认后另起一轮实施）
  * - bash 非常规命令 → 拒（提示：用 read/grep/只读 git，或给出计划）
+ * - 终端写向工具（terminal_input/terminal_key）→ 拒（会绕过只读命令白名单）
  * - 旁路工具（spawn/delegate/目标模式/排程）→ 拒（会绕过本会话只读约束）
  */
 export function planModeDenial(toolName, params) {
@@ -283,14 +309,26 @@ export function planModeDenial(toolName, params) {
     if (name === "subagent") {
         const action = typeof params === "object" && params !== null ? params.action : undefined;
         const act = typeof action === "string" ? action.trim().toLowerCase() : "";
-        if (!act || act === "spawn") {
+        // 与 goal-review-gate 同口径：只读 action（get_result/list/templates，看状态
+        // 与名录）放行；其余（spawn/steer/stop/wait_all/handoff，见 subagents.ts 的
+        // SUBAGENT_ACTIONS）或未传 action 一律拒 —— steer/handoff 会向运行中的子代理
+        // 会话投指令驱动它继续写代码，子代理会话 planMode=false 工具齐全，等于绕过
+        // 本会话的只读约束（#436 此前只拒了 spawn）。
+        if (act !== "get_result" && act !== "list" && act !== "templates") {
             return {
                 kind: "bypass-tool",
-                reason: `计划模式：不能调用 subagent(action="spawn")（它会在别的会话里执行，绕过本会话的只读约束）。请在本对话内用只读工具完成调研。`,
-                reasonEn: `Plan mode: subagent(action="spawn") is unavailable (it runs outside this conversation and would bypass the read-only constraint). Research with read-only tools here.`,
+                reason: `计划模式：不能调用 subagent(action="${act || "spawn"}")（它会在别的会话里执行，绕过本会话的只读约束）。请在本对话内用只读工具完成调研。`,
+                reasonEn: `Plan mode: subagent(action="${act || "spawn"}") is unavailable (it runs outside this conversation and would bypass the read-only constraint). Research with read-only tools here.`,
             };
         }
     }
+    if (TERMINAL_WRITE_TOOLS.has(name)) {
+        return {
+            kind: "write-tool",
+            reason: `计划模式：不能调用 ${name}（终端输入/按键会绕过只读命令白名单，见 #436）。调研请用 bash 跑只读命令；观察已有终端用 terminal_read/terminal_list/terminal_wait。`,
+            reasonEn: `Plan mode: ${name} is unavailable (terminal input/keys would bypass the read-only command allowlist). Run read-only commands via bash; observe existing terminals with terminal_read/terminal_list/terminal_wait.`,
+        };
+    }
     if (BYPASS_TOOLS.has(name)) {
         return {
             kind: "bypass-tool",

package/dist/server/plugin-api-catalog.js

@@ -23,6 +23,8 @@ export const SLOT_EXAMPLES = {
     "goalbar.actions": `{ "ui": { "goalbar.actions": [{ "id": "m", "label": "目标条", "kind": "action", "action": "my:m" }] } }`,
     "notice.actions": `{ "ui": { "notice.actions": [{ "id": "m", "label": "通知动作", "kind": "action", "action": "my:m" }] } }`,
     "modal.dialog": `{ "modal": [{ "id": "m", "label": "弹窗", "kind": "action", "action": "my:m" }] }`,
+    "sidebar.left": `{ "sidebar.left": [{ "id": "m", "label": "左侧悬浮", "kind": "action", "action": "my:m" }] }`,
+    "sidebar.right": `{ "sidebar.right": [{ "id": "m", "label": "右侧悬浮", "kind": "action", "action": "my:m" }] }`,
 };
 /** 宿主方法表（与 server/plugins.ts#PluginHost 同语义的精简版：只收发现用的注册/调用面）。
  *  needs="-" = 观察/基础设施类（无需能力声明）；其余走 can() 门控。 */

package/dist/server/plugin-catalog.js

@@ -14,8 +14,8 @@
  * 设计上服务端不做网络探测（不拉 manifest）：名称/简介/图标由条目本身携带
  * （作者填），id 由来源推导或作者显式指定 —— 保持离线可用、可单测。
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 import { normalizeIconSvg } from "./icon-svg.js";
 import { pick } from "./i18n.js";
 /** 合法插件 id（与 server/plugins.ts 的 ID_RE 一致，防路径穿越）。 */
@@ -61,10 +61,7 @@ function readJsonSafe(path, fallback) {
     }
 }
 function atomicWrite(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp-${process.pid}`;
-    writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
-    renameSync(tmp, path);
+    writeJsonAtomicSync(path, data);
 }
 /** 把任意对象规范化为合法条目；非法则返回 null。 */
 function toEntry(raw, builtin) {
@@ -75,6 +72,7 @@ function toEntry(raw, builtin) {
     if (!ID_RE.test(id))
         return null;
     const name = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : id;
+    const nameEn = typeof raw.nameEn === "string" && raw.nameEn.trim() ? raw.nameEn.trim() : undefined;
     const description = typeof raw.description === "string" && raw.description.trim() ? raw.description.trim() : undefined;
     const descriptionEn = typeof raw.descriptionEn === "string" && raw.descriptionEn.trim() ? raw.descriptionEn.trim() : undefined;
     const icon = typeof raw.icon === "string" && raw.icon.trim() ? raw.icon.trim() : undefined;
@@ -85,6 +83,7 @@ function toEntry(raw, builtin) {
         name,
         source,
         builtin,
+        ...(nameEn ? { nameEn } : {}),
         ...(description ? { description } : {}),
         ...(descriptionEn ? { descriptionEn } : {}),
         ...(icon ? { icon } : {}),
@@ -231,6 +230,7 @@ export function writeCustomCatalog(customPath, incoming, replace) {
         id: e.id,
         source: e.source,
         name: e.name,
+        ...(e.nameEn ? { nameEn: e.nameEn } : {}),
         ...(e.description ? { description: e.description } : {}),
         ...(e.descriptionEn ? { descriptionEn: e.descriptionEn } : {}),
         ...(e.icon ? { icon: e.icon } : {}),

package/dist/server/plugin-dom.js

@@ -13,8 +13,9 @@
  * - 只有真正发生变更的写才落盘（临时文件 + rename 原子写）；写失败 best-effort
  *   （内存态仍生效，本次会话可用）。
  */
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 const FILE = "plugin-dom.json";
 /** manifest.permissions 条目 → 是否请求特权 DOM（只看 `:` 前的族名，与宿主 can() 同口径）。
  *  例外：`dom:anchor` 只是客户端锚点挂载点的范围 DOM（免用户授权），不触发 bundle 403；
@@ -71,9 +72,7 @@ export class PluginDomConsent {
         else
             this.granted.delete(id);
         try {
-            const tmp = join(this.dataDir, `${FILE}.tmp.${process.pid}`);
-            writeFileSync(tmp, JSON.stringify({ v: 1, granted: this.list() }), "utf8");
-            renameSync(tmp, join(this.dataDir, FILE));
+            writeJsonAtomicSync(join(this.dataDir, FILE), { v: 1, granted: this.list() });
         }
         catch {
             /* 写失败 best-effort：内存态仍生效，本次会话可用 */

package/dist/server/plugin-facilities.js

@@ -16,9 +16,10 @@
  *     不能防同一用户账号下的完整进程妥协——本地个人工具的合理折衷。
  */
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, statSync } from "node:fs";
 import { readFile as fspReadFile, readdir as fspReaddir, rm as fspRm, mkdir as fspMkdir, writeFile as fspWriteFile, appendFile as fspAppendFile, stat as fspStat, } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
+import { writeAtomicSync } from "./atomic-file.js";
 import { createRequire } from "node:module";
 import { spawnSync } from "node:child_process";
 // 与 plugin-project 共用同一套 realpath 越界复核（isInsideRoot / realPathOfNearest），
@@ -26,10 +27,7 @@ import { spawnSync } from "node:child_process";
 import { isInsideRoot, realPathOfNearest } from "./plugin-project.js";
 /** tmp+rename 原子写（错误由调用方隔离——插件设施的 IO 一律尽力而为）。 */
 function atomicWrite(file, data) {
-    mkdirSync(dirname(file), { recursive: true });
-    const tmp = `${file}.tmp-${process.pid}`;
-    writeFileSync(tmp, data);
-    renameSync(tmp, file);
+    writeAtomicSync(file, data);
 }
 // ---------------------------------------------------------------------------
 // storage.json 的进程内「读-改-写」互斥

package/dist/server/plugin-grants.js

@@ -36,8 +36,9 @@
  * 与尾部分隔符（Windows 文件系统不区分大小写），但**存储保持用户写入时的形式**
  * （不 lowerCase），否则设置面板里 `C:\Users\Foo` 会显示成 `c:\users\foo`。
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, resolve, sep } from "node:path";
+import { readFileSync } from "node:fs";
+import { isAbsolute, resolve, sep } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 /** 合法插件 id（与 server/plugins.ts 的 ID_RE 一致，防路径穿越）。 */
 const ID_RE = /^[A-Za-z0-9_-]+$/;
 /** 去掉尾部分隔符（保留根：「C:\」/「/」不能退化）。 */
@@ -93,13 +94,9 @@ function isSameOrInside(targetKey, ancestorKey) {
     const prefix = ancestorKey.endsWith(sep) ? ancestorKey : ancestorKey + sep;
     return targetKey.startsWith(prefix);
 }
-/** 原子写：临时文件 + rename（同 server/plugin-catalog.ts 的写法；本文件不 import
- *  它，避免为一个 3 行函数制造模块耦合）。 */
+/** 原子写：临时文件 + rename。 */
 function atomicWriteJson(filePath, data) {
-    mkdirSync(dirname(filePath), { recursive: true });
-    const tmp = `${filePath}.tmp-${process.pid}`;
-    writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
-    renameSync(tmp, filePath);
+    writeJsonAtomicSync(filePath, data);
 }
 /** 读文件并净化为内存表：任何异常（不存在 / 权限 / JSON 坏 / 形状不对）→ 空表。
  *  条目逐个过 normalizeGrantPath（顺手兼容手工写入的相对路径、重复项、坏 id）。 */

package/dist/server/plugin-permissions.js

@@ -13,8 +13,9 @@
  * - 内存 session 授权（仅本次运行，进程结束即失）。
  * 读坏/形状不对当空表，且不在读路径回写；只有真正变更的写才落盘（tmp+rename 原子写）。
  */
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 /** 主机匹配（与 manifest netAllowlist 同口径）：全等或点号后缀。纯函数，单测覆盖。 */
 export function permissionHostMatches(hostname, entry) {
     const h = String(hostname ?? "").toLowerCase();
@@ -63,10 +64,7 @@ export class PluginPermissionStore {
     }
     write(grants) {
         try {
-            mkdirSync(dirname(this.file()), { recursive: true });
-            const tmp = `${this.file()}.tmp-${process.pid}`;
-            writeFileSync(tmp, JSON.stringify({ v: 1, grants }));
-            renameSync(tmp, this.file());
+            writeJsonAtomicSync(this.file(), { v: 1, grants });
         }
         catch (err) {
             console.error(`[plugin-permissions] persist failed (${this.file()}):`, err);

package/dist/server/plugin-schedule.js

@@ -10,8 +10,9 @@
  *    上次触发 lastRun；fn 回调永远由插件代码在 activate 里重给（重启后重建）。
  *    坏文件当空表（不回写，避免一次磁盘抖动清空全部定时）。
  */
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomicSync } from "./atomic-file.js";
 const MONTH_NAMES = {
     jan: 1,
     feb: 2,
@@ -224,11 +225,7 @@ export function loadScheduleRecords(pluginDir) {
 /** 写持久记录（tmp+rename 原子写；失败只记日志，内存态本次会话仍生效）。 */
 export function saveScheduleRecords(pluginDir, records) {
     try {
-        mkdirSync(pluginDir, { recursive: true });
-        const file = scheduleFile(pluginDir);
-        const tmp = `${file}.tmp-${process.pid}`;
-        writeFileSync(tmp, JSON.stringify({ v: 1, schedules: records }));
-        renameSync(tmp, file);
+        writeJsonAtomicSync(scheduleFile(pluginDir), { v: 1, schedules: records });
     }
     catch (err) {
         console.error(`[plugin-schedule] persist failed (${pluginDir}):`, err);

package/dist/server/plugin-updater.js

@@ -8,13 +8,29 @@
  *   <dataDir>/plugin-backups/<id>-<ts>/  覆盖安装前的旧版本快照（保留最近 N 份）
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, cpSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
 import { pick } from "./i18n.js";
 import { parseInstallSpec, manifestCandidateUrls } from "./plugin-install-spec.js";
 const PLUGIN_ID_RE = /^[A-Za-z0-9_-]+$/;
 /** 保留的备份份数（超出删除最旧的）。 */
 export const BACKUP_KEEP = 3;
+const here = dirname(fileURLToPath(import.meta.url));
+/**
+ * 解析宿主随包根目录（优先环境变量 PI_WEB_PKG_ROOT，次之向上查找包含 package.json 的祖先目录）。
+ */
+export function resolveDefaultPkgRoot() {
+    if (process.env.PI_WEB_PKG_ROOT && existsSync(process.env.PI_WEB_PKG_ROOT)) {
+        return process.env.PI_WEB_PKG_ROOT;
+    }
+    const candidates = [resolve(here, ".."), resolve(here, "..", ".."), resolve(here, "..", "..", "..")];
+    for (const c of candidates) {
+        if (existsSync(join(c, "package.json")))
+            return c;
+    }
+    return undefined;
+}
 /** 默认执行器：execFile 直跑 git（不经 shell），15s 超时。 */
 export const execGit = (cmd, args) => new Promise((resolve) => {
     execFile(cmd, args, { timeout: 15_000, encoding: "utf8" }, (err, stdout, stderr) => {
@@ -151,25 +167,98 @@ export async function resolveRemoteSha(spec, exec = execGit) {
     const sha = res.stdout.match(/^([0-9a-f]{40,64})\s+HEAD/m)?.[1] ?? null;
     return sha ? sha.slice(0, 12) : null;
 }
-/** 简易数字 semver 比较：>0 代表 a 比 b 新。 */
+/**
+ * 语义化版本（SemVer）比较器：
+ * - 剥离前缀 `v` / `V` 及首尾空白；
+ * - 剥离 `+` 后的构建元数据（build metadata 在优先级比较中被忽略）；
+ * - 分离主要数字版本与预发布标识（prerelease，如 -beta.1）；
+ * - 支持任意段数的数字比对；
+ * - 符合 SemVer 规范：正式版 > 预发布版（例如 1.0.0 > 1.0.0-beta.1）；
+ * - 返回值：>0 代表 a 比 b 新；<0 代表 a 比 b 旧；0 代表版本一致。
+ */
 export function compareVersions(a, b) {
-    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
-    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
-    for (let i = 0; i < 3; i++) {
-        const x = pa[i] ?? 0;
-        const y = pb[i] ?? 0;
+    const clean = (s) => String(s ?? "")
+        .trim()
+        .replace(/^[vV]/, "")
+        .split("+")[0]
+        .trim();
+    const cleanA = clean(a);
+    const cleanB = clean(b);
+    if (cleanA === cleanB)
+        return 0;
+    if (!cleanA && !cleanB)
+        return 0;
+    if (!cleanA)
+        return -1;
+    if (!cleanB)
+        return 1;
+    // 拆分主版本段与 prerelease 段
+    const dashA = cleanA.indexOf("-");
+    const mainAStr = dashA >= 0 ? cleanA.slice(0, dashA) : cleanA;
+    const preA = dashA >= 0 ? cleanA.slice(dashA + 1) : null;
+    const dashB = cleanB.indexOf("-");
+    const mainBStr = dashB >= 0 ? cleanB.slice(0, dashB) : cleanB;
+    const preB = dashB >= 0 ? cleanB.slice(dashB + 1) : null;
+    // 比较主版本数字段
+    const segsA = mainAStr.split(".").map((n) => parseInt(n, 10) || 0);
+    const segsB = mainBStr.split(".").map((n) => parseInt(n, 10) || 0);
+    const maxLen = Math.max(segsA.length, segsB.length);
+    for (let i = 0; i < maxLen; i++) {
+        const x = segsA[i] ?? 0;
+        const y = segsB[i] ?? 0;
         if (x !== y)
             return x - y;
     }
+    // 主版本数字段全相同时，比较 prerelease（正式版高于任何 prerelease 版）
+    if (preA === null && preB !== null)
+        return 1;
+    if (preA !== null && preB === null)
+        return -1;
+    if (preA !== null && preB !== null) {
+        const partsA = preA.split(".");
+        const partsB = preB.split(".");
+        const maxPreLen = Math.max(partsA.length, partsB.length);
+        for (let i = 0; i < maxPreLen; i++) {
+            const pa = partsA[i];
+            const pb = partsB[i];
+            if (pa === undefined)
+                return -1;
+            if (pb === undefined)
+                return 1;
+            if (pa === pb)
+                continue;
+            const isNumA = /^\d+$/.test(pa);
+            const isNumB = /^\d+$/.test(pb);
+            if (isNumA && isNumB) {
+                const diff = parseInt(pa, 10) - parseInt(pb, 10);
+                if (diff !== 0)
+                    return diff;
+            }
+            else if (isNumA && !isNumB) {
+                return -1; // 数字标识优先级低于非数字标识
+            }
+            else if (!isNumA && isNumB) {
+                return 1;
+            }
+            else {
+                return pa.localeCompare(pb);
+            }
+        }
+    }
     return 0;
 }
 /** 判断某个插件是否属于随包维护的内置插件（官方插件）。 */
 export function isBuiltinPlugin(id, source, builtinCatalogPath) {
     if (source && /xing-shuyin\/pi-web-ui\/plugins\//i.test(source))
         return true;
-    if (builtinCatalogPath && existsSync(builtinCatalogPath)) {
+    const catPath = builtinCatalogPath ??
+        (() => {
+            const pkgRoot = resolveDefaultPkgRoot();
+            return pkgRoot ? join(pkgRoot, "plugins", "catalog.json") : undefined;
+        })();
+    if (catPath && existsSync(catPath)) {
         try {
-            const raw = JSON.parse(readFileSync(builtinCatalogPath, "utf8"));
+            const raw = JSON.parse(readFileSync(catPath, "utf8"));
             if (Array.isArray(raw)) {
                 return raw.some((e) => e?.id === id);
             }
@@ -180,9 +269,23 @@ export function isBuiltinPlugin(id, source, builtinCatalogPath) {
     }
     return false;
 }
-/** 探测远端 manifest 中的版本号（通过 raw.githubusercontent.com 或注入的 fetcher）。 */
+/** 探测远端或本地源 manifest 中的版本号（本地路径 / raw.githubusercontent.com / 注入的 fetcher）。 */
 async function fetchRemoteVersion(source, fetcher) {
     const spec = parseInstallSpec(source);
+    if (spec.kind === "path" && spec.normalized) {
+        const manifestFile = join(spec.normalized, "manifest.json");
+        if (existsSync(manifestFile)) {
+            try {
+                const data = JSON.parse(readFileSync(manifestFile, "utf8"));
+                if (typeof data?.version === "string" && data.version.trim()) {
+                    return data.version.trim();
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
     const urls = manifestCandidateUrls(spec);
     if (urls.length === 0)
         return null;
@@ -212,6 +315,8 @@ export async function checkPluginUpdates(dataDir, exec = execGit,
 /** error 字段文案语言（默认英文）；调用方可传 () => getLang() 实现跟随。 */
 lang, opts) {
     const l = lang?.() ?? "en";
+    const effectivePkgRoot = opts?.pkgRoot ?? resolveDefaultPkgRoot();
+    const effectiveCatalogPath = opts?.builtinCatalogPath ?? (effectivePkgRoot ? join(effectivePkgRoot, "plugins", "catalog.json") : undefined);
     const pluginsDir = join(dataDir, "plugins");
     let names = [];
     try {
@@ -235,23 +340,27 @@ lang, opts) {
                 localSha = readFileSync(join(dir, ".pi-git-sha"), "utf8").trim() || null;
             }
             catch {
-                localSha = null; // 无 sha 记录 → 保守认为可更新（不知道装了哪个版本）
+                localSha = null; // 无 sha 记录
             }
             let name;
             let version;
             try {
                 const m = JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8"));
                 name = m.name;
-                version = m.version;
+                if (typeof m.version === "string" && m.version.trim()) {
+                    version = m.version.trim();
+                }
             }
             catch {
                 /* 坏 manifest：仍报告 */
             }
-            const builtin = isBuiltinPlugin(n, source, opts?.builtinCatalogPath);
+            const parsedSpec = parseInstallSpec(source);
+            const isSubpath = Boolean(parsedSpec.subpath);
+            const builtin = isBuiltinPlugin(n, source, effectiveCatalogPath);
             let latestVersion = null;
-            // 本地开发模式下，如果宿主包自带 plugins/<id>/manifest.json，可直接读本地最新版本号
-            if (opts?.pkgRoot) {
-                const localPkgManifest = join(opts.pkgRoot, "plugins", n, "manifest.json");
+            // 随包或本地开发模式：若宿主包自带 plugins/<id>/manifest.json，可直接读随包最新版本号
+            if (effectivePkgRoot) {
+                const localPkgManifest = join(effectivePkgRoot, "plugins", n, "manifest.json");
                 if (existsSync(localPkgManifest)) {
                     try {
                         const rawPkg = JSON.parse(readFileSync(localPkgManifest, "utf8"));
@@ -264,15 +373,18 @@ lang, opts) {
                     }
                 }
             }
-            // 若本地未取到最新版本号，则尝试通过 fetcher 探测远端 manifest.json
-            if (!latestVersion) {
-                try {
-                    latestVersion = await fetchRemoteVersion(source, opts?.fetcher);
-                }
-                catch {
-                    latestVersion = null;
+            // 尝试通过 fetcher 探测远端 manifest.json，若拿到了更高版本则采用更高者
+            try {
+                const remoteVer = await fetchRemoteVersion(source, opts?.fetcher);
+                if (remoteVer) {
+                    if (!latestVersion || compareVersions(remoteVer, latestVersion) > 0) {
+                        latestVersion = remoteVer;
+                    }
                 }
             }
+            catch {
+                /* ignore */
+            }
             let remoteSha = null;
             let error;
             try {
@@ -282,27 +394,28 @@ lang, opts) {
                 error = err instanceof Error ? err.message : String(err);
                 remoteSha = null;
             }
-            if (!remoteSha && !latestVersion && !error)
-                error = pick(l, "无法检查（非 git 源或 git 不可用）", "Cannot check (non-git source or git unavailable)", "pluginupdate.cannot.check");
             let updatable = false;
             if (latestVersion && version) {
-                const cmp = compareVersions(latestVersion, version);
-                if (cmp > 0) {
-                    updatable = true;
-                }
-                else if (cmp === 0 && remoteSha && localSha) {
-                    updatable = localSha !== remoteSha;
-                }
-                else if (cmp === 0 && remoteSha && !localSha) {
-                    updatable = true;
-                }
-            }
-            else if (remoteSha) {
-                updatable = !localSha || localSha !== remoteSha;
+                // 两端都有版本号：版本号是唯一权威事实源。
+                // 严格大于才判定为有更新（cmp > 0）。
+                // 相同或更低（cmp <= 0）坚决判定为无更新，彻底避免主仓库无关 commit 触发的假阳性误报。
+                updatable = compareVersions(latestVersion, version) > 0;
             }
             else if (latestVersion && !version) {
+                // 远端有版本号但本地无版本号：视为可更新
                 updatable = true;
             }
+            else if (!isSubpath && remoteSha) {
+                // 仅在未能获取最新版本号且为独立仓库源（非子目录）时，才回退到基于 git commit SHA 比对
+                updatable = !localSha || localSha !== remoteSha;
+            }
+            if (!updatable && !latestVersion && !remoteSha && !error) {
+                error = pick(l, "无法检查（非 git 源或 git 不可用）", "Cannot check (non-git source or git unavailable)", "pluginupdate.cannot.check");
+            }
+            else if (!updatable && isSubpath && !latestVersion && !error) {
+                // 子目录源插件未能获取远端清单时，不凭仓库根 SHA 误报，而是提示未能获取清单
+                error = pick(l, "无法检查（未能获取远端插件清单）", "Cannot check (failed to fetch remote plugin manifest)", "pluginupdate.subpath.manifest.failed");
+            }
             out.push({
                 id: n,
                 name,

package/dist/server/plugins.js

@@ -275,6 +275,8 @@ export const UI_SLOTS = new Set([
     "goalbar.actions",
     "notice.actions",
     "modal.dialog",
+    "sidebar.left",
+    "sidebar.right",
 ]);
 /** manifest 里可以写更自然的简写（作者少踩坑）：解析时映射到完整 slot 名。 */
 export const UI_SLOT_ALIASES = {
@@ -285,6 +287,11 @@ export const UI_SLOT_ALIASES = {
     rightpanel: "rightpanel.tabs",
     settings: "settings.pages",
     modal: "modal.dialog",
+    sidebar: "sidebar.left",
+    "sidebar.left": "sidebar.left",
+    "sidebar.right": "sidebar.right",
+    leftbar: "sidebar.left",
+    rightbar: "sidebar.right",
 };
 /** 合法的条目种类（缺省 action；settings.pages 缺省 page）。 */
 export const UI_KINDS = new Set([
@@ -1473,7 +1480,11 @@ export class PluginManager {
             params: freezeParams(req.params),
             conversationId: req.conversationId,
         };
-        for (const p of this.loaded.values()) {
+        // #489：对 this.loaded 取快照再迭代——下面的 withGuardTimeout 是 await 点，
+        // 期间插件 reload/uninstall 会原地 clear 同一个 Map（实例不变），Map 迭代器
+        // 立即 done → 剩余插件的 pre 守卫一次都不被求值 → fail-open 直接放行。
+        const loadedSnapshot = [...this.loaded.values()];
+        for (const p of loadedSnapshot) {
             for (const h of p.preGuards ?? []) {
                 let raw;
                 try {
@@ -1510,7 +1521,10 @@ export class PluginManager {
             result: req.result,
             conversationId: req.conversationId,
         };
-        for (const p of this.loaded.values()) {
+        // #489：同 evaluateToolPre——await 点期间 reload 原地 clear Map 会让迭代器
+        // 提前终止，取快照迭代保证本轮请求遍历的是发起时的插件集合。
+        const postLoadedSnapshot = [...this.loaded.values()];
+        for (const p of postLoadedSnapshot) {
             for (const h of p.postGuards ?? []) {
                 let raw;
                 try {