pi-web-ui 0.96.1 → 0.98.0

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 的进程内「读-改-写」互斥
@@ -303,14 +301,47 @@ export function depName(spec) {
 function str(v) {
     return typeof v === "string" ? v.trim() : "";
 }
-/** 从插件目录出发能否解析到这个模块（模拟插件自身 import() 的查找链）。 */
+/** 纯包名（`foo` / `@scope/foo`）：能按 `node_modules/<name>/package.json` 判盘。
+ *  `node:path`、URL、相对/绝对路径、git spec 一律 false（交给 resolve 判）。 */
+function isPlainPackageName(name) {
+    return /^(?:@[a-z\d](?:[a-z\d._-]*[a-z\d])?\/)?[a-z\d](?:[a-z\d._-]*[a-z\d])?$/i.test(name);
+}
+/** 从 fromDir 沿目录树向上找 `node_modules/<name>/package.json` 是否已落盘。 */
+function depOnDisk(fromDir, name) {
+    let dir = fromDir;
+    for (;;) {
+        try {
+            if (existsSync(join(dir, "node_modules", ...name.split("/"), "package.json")))
+                return true;
+        }
+        catch {
+            /* 权限/坏路径：当作这一层没有，继续往上找 */
+        }
+        const up = dirname(dir);
+        if (!up || up === dir)
+            return false;
+        dir = up;
+    }
+}
+/** 从插件目录出发能否解析到这个模块（模拟插件自身 import() 的查找链）。
+ *
+ *  resolve 失败后再看一眼「文件是否已落盘」，这不是冗余判据而是**修 bug**（issue #383）：
+ *  Node 的 CJS 解析会把 `node_modules/<pkg>/package.json` 不存在的**负结果**缓存在
+ *  进程内存里（packageJsonReader 的路径缓存）。于是「探测缺失 → npm install 成功 →
+ *  复查」这组三连里，最后一次复查永远命中那条负缓存，恒抛
+ *  `Cannot find module`，用户看到的是「装成功了却报 npm install 没跑通」，
+ *  且非重启整个进程不能恢复。落盘判据不碰 CJS 缓存，天然免疫。
+ *
+ *  顺序保持「先 resolve 后判盘」：解析成功仍然是最强的信号（含 exports 映射等
+ *  盘上判据覆盖不到的形状），判盘只是给解析的假阴性兜底，不会放宽真缺失。 */
 export function isDepAvailable(pluginDir, spec) {
+    const name = depName(spec);
     try {
-        createRequire(join(pluginDir, "index.mjs")).resolve(depName(spec));
+        createRequire(join(pluginDir, "index.mjs")).resolve(name);
         return true;
     }
     catch {
-        return false;
+        return isPlainPackageName(name) && depOnDisk(pluginDir, name);
     }
 }
 const depInstallLocks = new Map();

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 {
@@ -1763,11 +1777,14 @@ export class PluginManager {
         }
         return out;
     }
-    /** 当前全部插件注册的 AI 工具（扁平化，按插件 id 稳定排序）。 */
+    /** 当前全部插件注册的 AI 工具（扁平化，按插件 id 稳定排序，附带所属 pluginId）。 */
     getAgentTools() {
         const out = [];
-        for (const table of [...this.agentTools.values()].sort())
-            out.push(...table.values());
+        for (const [pid, table] of [...this.agentTools.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            for (const tool of table.values()) {
+                out.push({ ...tool, pluginId: pid });
+            }
+        }
         return out;
     }
     /** 注册一个供 AI 调用的工具；重名拒绝并返回空操作注销函数。

package/dist/server/prompt-composer.js

@@ -55,9 +55,6 @@ export function isReadonlyPromptSource(token) {
  *  SDK 默认拼装的完整提示词。 */
 export const DEFAULT_PROMPT_TEMPLATE = PROMPT_TOKENS.map((t) => `{{${t}}}`).join("\n\n");
 const TOKEN_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
-export function isKnownToken(name) {
-    return PROMPT_TOKENS.includes(name);
-}
 /** 模板里出现的全部 token（含未知名，供 UI 提示）。 */
 export function collectTemplateTokens(template) {
     const out = [];
@@ -258,3 +255,15 @@ export function estimatePromptTokens(text) {
     const cjk = text.match(CJK_RE)?.length ?? 0;
     return Math.ceil(cjk + (text.length - cjk) / 4);
 }
+/** 把「早前扩展改过的提示词」拆成 SDK 原始提示词 + 扩展的首尾增补。
+ *  before_agent_start 是链式的：我们是最后一个 handler，返回 systemPrompt 等于
+ *  forceSystemPrompt 整体替换，会把别的扩展（如注入 <invoked_skill> 的）写进去的
+ *  内容一起丢掉。只要原始提示词还原样嵌在里面（纯前置/后置增补），就能把增补摘出来
+ *  重新套回我们的渲染结果上。摘不出来（中间插入 / 被整体替换）时返回 pre/post 为空、
+ *  core 为当前文本 —— 调用方退回今天的行为，绝不把整段提示词翻倍。 */
+export function splitExtensionWrap(baseline, current) {
+    const at = baseline ? current.indexOf(baseline) : -1;
+    if (at === -1)
+        return { pre: "", core: current, post: "" };
+    return { pre: current.slice(0, at), core: baseline, post: current.slice(at + baseline.length) };
+}

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 = 20;
+export const PROTOCOL_VERSION = 22;

package/dist/server/resolve-global-sdk.js

@@ -26,6 +26,7 @@
  * 或前台启动时在 import 服务入口之前先 import 它）。
  */
 import { registerHooks } from "node:module";
+import { dirname } from "node:path";
 import { pathToFileURL } from "node:url";
 import { compareVersions, sdkCopies } from "./sdk-origin.js";
 const PKG = "@earendil-works/pi-coding-agent";
@@ -40,6 +41,13 @@ export function pickGlobalSdk(copies, mode) {
     if (BUNDLED_MODES.has((mode ?? "global").trim().toLowerCase()))
         return null;
     const bundled = copies[0];
+    // 显式透传的宿主 SDK 路径（如 extensions/webui.ts 宿主传递，issue #482）：若不降级优先选用
+    if (process.env.PI_WEB_SDK_DIR) {
+        const hostCopy = copies.find((c) => dirname(c.path) === process.env.PI_WEB_SDK_DIR);
+        if (hostCopy && (!bundled || compareVersions(hostCopy.version, bundled.version) >= 0)) {
+            return hostCopy;
+        }
+    }
     // 只考虑祖先链上**严格更新**的副本，多份取版本最高的（旧的/同版本的都不折腾）。
     let best = null;
     for (const copy of copies.slice(1)) {

package/dist/server/schedule-agent-tool.js

@@ -20,7 +20,7 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { pick } from "./i18n.js";
 import { SCHEDULE_CANCEL_TOOL_NAME, SCHEDULE_LIST_TOOL_NAME, SCHEDULE_TASK_TOOL_NAME } from "./tool-manager.js";
-import { computeNextFire, describeIntervalMs, SCHEDULER_MIN_INTERVAL_MS, } from "./scheduler-tasks.js";
+import { computeNextFire, describeIntervalMs, SCHEDULER_MIN_INTERVAL_MS, SchedulerValidationError, } from "./scheduler-tasks.js";
 import { parseCronSpec } from "./plugin-schedule.js";
 /** 用户写法 → 调度规格。纯函数，可单测。
  *  收：5 字段 cron（"0 * * * *"）、相对时间（"in 30m" / "in 1h" / "in 2d"）、
@@ -180,6 +180,10 @@ export function makeScheduleTools(host, ownerConversationId, lang) {
                 });
             }
             catch (err) {
+                const L = getLang();
+                if (err instanceof SchedulerValidationError) {
+                    return text(L === "zh" ? err.messageZh : err.messageEn);
+                }
                 return text(String(err?.message ?? err));
             }
             const L = getLang();