pi-web-ui 0.94.1 → 0.96.0

package/dist/server/plugins.js

@@ -21,16 +21,20 @@ import { existsSync, readFileSync, renameSync, watch as fsWatch, writeFileSync }
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { pick } from "./i18n.js";
-import { PluginStorage, PluginSecrets, ensurePluginDeps, WorkspaceFS } from "./plugin-facilities.js";
+import { PluginStorage, PluginSecrets, ensurePluginDeps, WorkspaceFS, withFileRmwLock } from "./plugin-facilities.js";
 import { parseCronSpec, armDelay, nextCronFire, loadScheduleRecords, saveScheduleRecords, } from "./plugin-schedule.js";
 import { PluginPermissionStore } from "./plugin-permissions.js";
 import { readCatalog, addCustomEntry, removeCustomEntry } from "./plugin-catalog.js";
 import { PluginGrantsStore, normalizeGrantPath } from "./plugin-grants.js";
 import { normalizeIconSvg } from "./icon-svg.js";
 import { PluginDomConsent, declarationWantsDom } from "./plugin-dom.js";
+import { validatePluginManifest, formatManifestIssue, isKnownPermission } from "./plugin-manifest-validate.js";
+import { buildPluginApiCatalog } from "./plugin-api-catalog.js";
+import { AGENT_TOOL_CATALOG } from "./tool-manager.js";
+import { applyPostEdit, denialText, freezeParams, isBlockingDecision, normalizePostEdit, normalizePreDecision, withGuardTimeout, } from "./plugin-tool-guard.js";
 // 工作区根的归一化与 client-state 共用一份（同一份语义：只收绝对路径 / 去重 / 上限）。
 import { normalizeWorkspaceRoots } from "./client-state.js";
-import { createProject } from "./plugin-project.js";
+import { createProject, isInsideRoot, realPathOfNearest, } from "./plugin-project.js";
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -79,6 +83,81 @@ export function isPluginLogsRequest(p) {
     const o = p;
     return o[PLUGIN_LOGS_HOST_KEY] === "logs" && (o.op === "get" || o.op === "clear" || o.op === undefined);
 }
+/**
+ * per-plugin 可逆副作用栈（effect 栈）。
+ *
+ * 宿主每个注册面（事件订阅 / AI 工具 / 命令 / HTTP 路由 / 反向代理 / fs.watch /
+ * 定时任务 / 后台任务 / UI 条目 / 设置回调…）在内部 `add(label, dispose)` 登记一条
+ * disposer，反激活时**逆序**回卷 —— 插件不必记得注销，也不会因为漏掉一处就留下
+ * 孤儿订阅、定时器、路由或事件处理器（热重载后事件双触发、定时器叠加、watcher
+ * 堆积都是这个漏法的症状）。
+ *
+ * 与「每个注册函数自己返回注销函数」（插件主动调用）是**同一件事的两面**：
+ * 返回给插件的注销函数 = `remove(item)`（只撤这一条、幂等），反激活 = `release()`。
+ * 插件自建的副作用（自己的 setInterval、EventEmitter 监听…）可经 `host.effect()`
+ * 挂进来，同样享受逆序回卷 + 泄漏归因。
+ */
+export class PluginEffectStack {
+    pluginId;
+    diag;
+    items = [];
+    released = false;
+    constructor(pluginId, 
+    /** 记录一条诊断（cleanup 抛错时调用；不抛错、不阻断回卷）。 */
+    diag) {
+        this.pluginId = pluginId;
+        this.diag = diag;
+    }
+    /** 登记一条副作用；返回「只撤这一条」的注销函数（幂等，重复调用无副作用）。 */
+    add(label, dispose) {
+        const item = { label, dispose };
+        this.items.push(item);
+        return () => this.remove(item);
+    }
+    /** 当前未回卷的副作用数（单测断言「activate → deactivate 后栈空」）。 */
+    get size() {
+        return this.items.length;
+    }
+    /** 未回卷的副作用标签（按登记顺序，排障用）。 */
+    labels() {
+        return this.items.map((i) => i.label);
+    }
+    /** 撤销单条：先从栈里摘掉，再跑它的 dispose（幂等 —— 摘不到说明已撤过）。 */
+    remove(item) {
+        const i = this.items.indexOf(item);
+        if (i < 0)
+            return;
+        this.items.splice(i, 1);
+        try {
+            item.dispose();
+        }
+        catch (err) {
+            this.report(item.label, err);
+        }
+    }
+    /** 逆序回卷全部副作用；返回**失败**（dispose 抛错）的标签列表，绝不抛出。 */
+    release() {
+        if (this.released)
+            return [];
+        this.released = true;
+        const failed = [];
+        while (this.items.length > 0) {
+            const item = this.items.pop();
+            try {
+                item.dispose();
+            }
+            catch (err) {
+                failed.push(item.label);
+                this.report(item.label, err);
+            }
+        }
+        return failed;
+    }
+    report(label, err) {
+        console.warn(`[plugin:${this.pluginId}] effect "${label}" cleanup failed:`, err);
+        this.diag?.(`effect "${label}" cleanup failed: ${err?.message ?? String(err)}`);
+    }
+}
 /** 宿主提供的插件设施版本——manifest 声明的 apiVersion 高于此值则拒绝激活，
  *  插件能拿到明确的「请升级 pi-web-ui」而不是在新接口上莫名 undefined。
  *  1 = 初始：storage/secrets/命令/HTTP 路由/工具注册/受限 fs/后台任务。
@@ -173,7 +252,7 @@ const SETTING_OPTIONS_FROM = new Set(["models", "thinkingLevels"]);
  * 不认识的 slot / kind / when 直接丢弃（旧宿主读到新字段也不会崩，新宿主读到旧字段同理）。
  * 归属由宿主决定：全局 id = `<pluginId>:<itemId>`。
  */
-const UI_SLOTS = new Set([
+export const UI_SLOTS = new Set([
     "topbar.primary",
     "topbar.overflow",
     "bottombar",
@@ -198,7 +277,7 @@ const UI_SLOTS = new Set([
     "modal.dialog",
 ]);
 /** manifest 里可以写更自然的简写（作者少踩坑）：解析时映射到完整 slot 名。 */
-const UI_SLOT_ALIASES = {
+export const UI_SLOT_ALIASES = {
     topbar: "topbar.primary",
     "topbar.more": "topbar.overflow",
     composer: "composer.actions",
@@ -208,7 +287,7 @@ const UI_SLOT_ALIASES = {
     modal: "modal.dialog",
 };
 /** 合法的条目种类（缺省 action；settings.pages 缺省 page）。 */
-const UI_KINDS = new Set([
+export const UI_KINDS = new Set([
     "view",
     "action",
     "badge",
@@ -554,6 +633,69 @@ export function parseUiArrange(raw, diagnostics) {
     }
     return out;
 }
+/** 解析 manifest.requires → 归一化硬依赖声明（P2-8，坏形状宽容忽略：
+ *  形状错在 P1-6 校验层已拒，这里只管把合法部分抽出来供展示 + activate 判定）。 */
+export function parseRequires(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    const out = {};
+    if (typeof o.hostApi === "number" && Number.isInteger(o.hostApi) && o.hostApi >= 1)
+        out.hostApi = o.hostApi;
+    if (Array.isArray(o.families)) {
+        const fams = o.families
+            .filter((x) => typeof x === "string" && x.trim().length > 0)
+            .map((x) => x.trim())
+            .slice(0, 8);
+        if (fams.length)
+            out.families = fams;
+    }
+    if (Array.isArray(o.plugins)) {
+        const deps = o.plugins
+            .filter((x) => typeof x === "string" && ID_RE.test(x.trim()))
+            .map((x) => x.trim())
+            .slice(0, 16);
+        if (deps.length)
+            out.plugins = deps;
+    }
+    return out.hostApi !== undefined || out.families !== undefined || out.plugins !== undefined ? out : undefined;
+}
+/** 依赖拓扑排序（P2-8）：按 requires.plugins 把被依赖者排前面；同层保持扫描顺序。
+ *  返回 { order }（可激活顺序）+ { cyclic }（环/挂在环上的，调用方直接拒）。
+ *  边只连「本次扫描里存在」的对等端；缺失的对端由 activate 判定点名拒绝。 */
+export function sortByRequires(ids, depsOf) {
+    const indeg = new Map();
+    const edges = new Map();
+    const idSet = new Set(ids);
+    for (const id of ids) {
+        indeg.set(id, 0);
+        edges.set(id, []);
+    }
+    for (const id of ids) {
+        const seen = new Set();
+        for (const dep of depsOf(id)) {
+            if (!idSet.has(dep) || dep === id || seen.has(dep))
+                continue;
+            seen.add(dep);
+            edges.get(dep).push(id);
+            indeg.set(id, (indeg.get(id) ?? 0) + 1);
+        }
+    }
+    const queue = ids.filter((id) => (indeg.get(id) ?? 0) === 0);
+    const order = [];
+    while (queue.length) {
+        const cur = queue.shift();
+        order.push(cur);
+        for (const next of edges.get(cur) ?? []) {
+            const d = (indeg.get(next) ?? 1) - 1;
+            indeg.set(next, d);
+            if (d === 0)
+                queue.push(next);
+        }
+    }
+    const ordered = new Set(order);
+    return { order, cyclic: ids.filter((id) => !ordered.has(id)) };
+}
 /** 合并 manifest 基线与运行时注册：运行时同 id 覆盖，removed 里的删除；arrange 追加。 */
 function mergeUiPluginUi(base, rt) {
     const items = new Map();
@@ -607,53 +749,161 @@ function parseSettingsSchema(raw) {
 function secretSettingKey(key) {
     return `setting:${key}`;
 }
-/** 从 <pluginDir>/storage.json 读 settings 存值，按 schema 并默认值。
- *  secret 字段不返回明文：有 secrets 时返回有无（布尔），调用方是浏览器；
- *  插件运行时要真值请用 runtimeSettingsValues。 */
-function storedSettingsValues(dir, schema, secrets) {
-    const out = {};
-    let stored = {};
+/** 用户 overlay 原文件（P2-9）：`<dataDir>/plugin-overrides/<id>.json` 的 settings 节。
+ *  缺文件 = 没写（不警告）；坏形状 → 警告并整体忽略（用户自己的文件，不连坐插件）。
+ *  顶层未知键忽略（前向兼容）；每键校验在 cleanOverlaySettings 里按 schema 做。 */
+function readSettingsOverlayFile(dataDir, pluginId) {
+    const empty = { raw: {}, warnings: [] };
+    if (!ID_RE.test(pluginId))
+        return empty;
+    let parsed;
     try {
-        const parsed = JSON.parse(readFileSync(join(dir, "storage.json"), "utf8"));
-        if (parsed && typeof parsed === "object" && parsed.settings && typeof parsed.settings === "object") {
-            stored = parsed.settings;
-        }
+        parsed = JSON.parse(readFileSync(join(dataDir, "plugin-overrides", `${pluginId}.json`), "utf8"));
     }
     catch {
-        /* 无存储文件 = 全默认 */
+        return empty;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { raw: {}, warnings: [`settings override ignored: ${pluginId}.json must be an object`] };
+    }
+    const o = parsed;
+    if (o.settings === undefined)
+        return empty;
+    if (!o.settings || typeof o.settings !== "object" || Array.isArray(o.settings)) {
+        return { raw: {}, warnings: [`settings override ignored: ${pluginId}.json settings must be an object`] };
     }
+    return { raw: o.settings, warnings: [] };
+}
+/** 按 schema 清洗 overlay 值（P2-9）：secret 一律拒绝（明文永不进加密 store）+
+ *  诊断；类型不对/越界/非法候选 → 警告并丢该键；schema 外的键 → 警告并忽略（拼写检查）。 */
+function cleanOverlaySettings(schema, raw, lang) {
+    const values = {};
+    const warnings = [];
+    const byKey = new Map(schema.map((f) => [f.key, f]));
+    for (const [k, v] of Object.entries(raw)) {
+        const f = byKey.get(k);
+        if (!f) {
+            warnings.push(`settings override ignored: unknown key "${k.slice(0, 64)}"`);
+            continue;
+        }
+        if (f.type === "secret") {
+            warnings.push(`settings override ignored: secret "${k.slice(0, 64)}" never comes from overlay`);
+            continue;
+        }
+        const r = cleanNonSecretSettingsField(f, v, lang);
+        if (r.error) {
+            warnings.push(`settings override ignored: "${k.slice(0, 64)}": ${r.error}`);
+            continue;
+        }
+        values[k] = r.value;
+    }
+    return { values, warnings };
+}
+/** 三层合并（P2-9）：schema 默认 < overlay（用户钉住的新默认，不 fork）< storage.json
+ *  （面板保存，最高）。stored 不清洗（保存路径已洗过，可信）；overlay 已预洗。
+ *  secret 走加密 store，overlay 永不参与。 */
+function resolveSettingsValues(schema, stored, overlay, secrets) {
+    const values = {};
+    const sources = {};
     for (const f of schema) {
         if (f.type === "secret") {
-            // 浏览器侧只看到有无（布尔），明文永不下发；无 secrets 上下文（如单测）回落 false。
-            out[f.key] = secrets ? secrets.has(secretSettingKey(f.key)) : false;
+            if (secrets?.get) {
+                const got = secrets.get(secretSettingKey(f.key));
+                values[f.key] = got ?? f.default ?? "";
+                sources[f.key] = got !== undefined ? "stored" : "default";
+            }
+            else if (secrets?.has) {
+                const has = secrets.has(secretSettingKey(f.key));
+                values[f.key] = has;
+                sources[f.key] = has ? "stored" : "default";
+            }
+            else {
+                values[f.key] = false;
+                sources[f.key] = "default";
+            }
             continue;
         }
-        out[f.key] = stored[f.key] ?? f.default;
+        const s = stored[f.key];
+        if (s !== undefined && s !== null) {
+            values[f.key] = s;
+            sources[f.key] = "stored";
+        }
+        else if (f.key in overlay) {
+            values[f.key] = overlay[f.key];
+            sources[f.key] = "override";
+        }
+        else {
+            values[f.key] = f.default;
+            sources[f.key] = "default";
+        }
     }
-    return out;
+    return { values, sources };
 }
-/** 插件运行时视角的设置值：非 secret 与 storedSettingsValues 同口径；secret 返回真值
- *  （无则回落默认值/空串）。只给插件服务端代码用，绝不下发浏览器。 */
-function runtimeSettingsValues(dir, schema, secrets) {
-    const out = {};
-    let stored = {};
+/** 从 <pluginDir>/storage.json 读 settings 存值，按 schema 并默认值。
+ *  secret 字段不返回明文：有 secrets 时返回有无（布尔），调用方是浏览器；
+ *  插件运行时要真值请用 runtimeSettingsValues。 */
+function readStoredSettings(dir) {
     try {
         const parsed = JSON.parse(readFileSync(join(dir, "storage.json"), "utf8"));
         if (parsed && typeof parsed === "object" && parsed.settings && typeof parsed.settings === "object") {
-            stored = parsed.settings;
+            return parsed.settings;
         }
     }
     catch {
         /* 无存储文件 = 全默认 */
     }
-    for (const f of schema) {
-        if (f.type === "secret") {
-            out[f.key] = secrets.get(secretSettingKey(f.key)) ?? f.default ?? "";
-            continue;
+    return {};
+}
+function storedSettingsValues(dir, schema, secrets, overlay = {}) {
+    // 浏览器侧 secret 只看到有无（布尔），明文永不下发；无 secrets 上下文（如单测）回落 false。
+    return resolveSettingsValues(schema, readStoredSettings(dir), overlay, secrets ? { has: (k) => secrets.has(k) } : undefined).values;
+}
+/** 插件运行时视角的设置值：非 secret 与 storedSettingsValues 同口径；secret 返回真值
+ *  （无则回落默认值/空串）。只给插件服务端代码用，绝不下发浏览器。 */
+function runtimeSettingsValues(dir, schema, secrets, overlay = {}) {
+    return resolveSettingsValues(schema, readStoredSettings(dir), overlay, { get: (k) => secrets.get(k) }).values;
+}
+/** 清洗单个非 secret 设置值（P2-9 抽出：保存路径与 overlay 复用同一套口径）。
+ *  v === undefined → 回落 schema 默认；类型不对/越界/非法候选 → error（调用方丢弃该键）。
+ *  secret 字段不在这里处理（overlay 直接拒绝，明文永不进加密 store）。 */
+function cleanNonSecretSettingsField(f, v, lang) {
+    if (f.type === "number") {
+        const n = v === undefined ? Number(f.default ?? 0) : Number(v);
+        if (!Number.isFinite(n) || (f.min !== undefined && n < f.min) || (f.max !== undefined && n > f.max)) {
+            return {
+                error: pick(lang, `${f.label} 超出范围`, `${f.label} out of range`, "plugins.settings.out.of.range", {
+                    "f.label": f.label,
+                }),
+            };
         }
-        out[f.key] = stored[f.key] ?? f.default;
+        return { value: n };
     }
-    return out;
+    if (f.type === "boolean") {
+        return { value: v === undefined ? Boolean(f.default) : Boolean(v) };
+    }
+    if (f.type === "select") {
+        const s = v === undefined ? "" : String(v);
+        // optionsFrom（宿主数据源）：候选值在浏览器侧现算，服务端无从校验，
+        // 只做个长度护栏；非法值由用的时候（如 host.chat 切模型）报错。
+        if (f.optionsFrom) {
+            if (s.length > 200) {
+                return {
+                    error: pick(lang, `${f.label} 过长`, `${f.label} too long`, "plugins.settings.too.long", {
+                        "f.label": f.label,
+                    }),
+                };
+            }
+            return { value: v === undefined ? (f.default ?? "") : s };
+        }
+        if (v !== undefined && !f.options?.includes(s))
+            return {
+                error: pick(lang, `${f.label} 值非法`, `Invalid value for ${f.label}`, "plugins.settings.invalid.value", {
+                    "f.label": f.label,
+                }),
+            };
+        return { value: v === undefined ? f.default : s };
+    }
+    return { value: v === undefined ? (f.default ?? "") : String(v) };
 }
 /** 校验并写回 settings（storage.json 的 settings 键，原子写）；返回错误信息或 null。
  *  secret 字段写加密 secrets（明文永不落盘、不进 storage.json）：空串/缺省 = 不改；
@@ -665,45 +915,11 @@ lang, secrets) {
     const clean = {};
     for (const f of schema) {
         const v = values?.[f.key];
-        if (f.type === "number") {
-            const n = v === undefined ? Number(f.default ?? 0) : Number(v);
-            if (!Number.isFinite(n) || (f.min !== undefined && n < f.min) || (f.max !== undefined && n > f.max)) {
-                return {
-                    error: pick(l, `${f.label} 超出范围`, `${f.label} out of range`, "plugins.settings.out.of.range", {
-                        "f.label": f.label,
-                    }),
-                    clean,
-                };
-            }
-            clean[f.key] = n;
-        }
-        else if (f.type === "boolean") {
-            clean[f.key] = v === undefined ? Boolean(f.default) : Boolean(v);
-        }
-        else if (f.type === "select") {
-            const s = v === undefined ? "" : String(v);
-            // optionsFrom（宿主数据源）：候选值在浏览器侧现算，服务端无从校验，
-            // 只做个长度护栏；非法值由用的时候（如 host.chat 切模型）报错。
-            if (f.optionsFrom) {
-                if (s.length > 200) {
-                    return {
-                        error: pick(l, `${f.label} 过长`, `${f.label} too long`, "plugins.settings.too.long", {
-                            "f.label": f.label,
-                        }),
-                        clean,
-                    };
-                }
-                clean[f.key] = v === undefined ? (f.default ?? "") : s;
-                continue;
-            }
-            if (v !== undefined && !f.options?.includes(s))
-                return {
-                    error: pick(l, `${f.label} 值非法`, `Invalid value for ${f.label}`, "plugins.settings.invalid.value", {
-                        "f.label": f.label,
-                    }),
-                    clean,
-                };
-            clean[f.key] = v === undefined ? f.default : s;
+        if (f.type !== "secret") {
+            const r = cleanNonSecretSettingsField(f, v, l);
+            if (r.error)
+                return { error: r.error, clean };
+            clean[f.key] = r.value;
         }
         else if (f.type === "secret") {
             // 空串/缺省 = 不改（浏览器侧回显的本来就是有无布尔，前端把“没碰”发成空串）。
@@ -742,16 +958,20 @@ lang, secrets) {
             if (!secretKeys.has(k))
                 persist[k] = v;
         const file = join(dir, "storage.json");
-        let existing = {};
-        try {
-            existing = JSON.parse(readFileSync(file, "utf8"));
-        }
-        catch {
-            /* 首次 */
-        }
-        const tmp = `${file}.tmp-${process.pid}`;
-        writeFileSync(tmp, JSON.stringify({ ...existing, settings: persist }));
-        renameSync(tmp, file);
+        // 与 PluginStorage.set/delete 同一把按文件路径的 RMW 锁（见 plugin-facilities.ts
+        // 的 withFileRmwLock）：两个「读-改-写」者串行，谁也不会拿旧快照抹掉对方刚写的键。
+        withFileRmwLock(file, () => {
+            let existing = {};
+            try {
+                existing = JSON.parse(readFileSync(file, "utf8"));
+            }
+            catch {
+                /* 首次 */
+            }
+            const tmp = `${file}.tmp-${process.pid}`;
+            writeFileSync(tmp, JSON.stringify({ ...existing, settings: persist }));
+            renameSync(tmp, file);
+        });
     }
     catch (err) {
         console.error(`[plugins] settings persist failed (${dir}):`, err);
@@ -1003,6 +1223,17 @@ export class PluginManager {
         this.senders.add(s);
         return () => this.senders.delete(s);
     }
+    /** 当前在线（hello 过）的 clientId 去重集合。插件授权弹窗广播后按它做应答
+     *  来源绑定——广播后才连上的端没见过弹窗，不许代答（index.ts 三类授权应答校验）。 */
+    onlineClientIds() {
+        const out = new Set();
+        for (const s of this.senders) {
+            const cid = s.cid();
+            if (cid)
+                out.add(cid);
+        }
+        return [...out];
+    }
     /** 客户端上行：路由给对应插件的处理器；未知/未激活的插件静默丢弃。
      *  插件代码不可信——同步抛错与返回的 Promise rejection 都必须隔离在
      *  这里，绝不能炸主进程。 */
@@ -1169,6 +1400,11 @@ export class PluginManager {
             return false;
         return !this.domConsentStore.has(pluginId);
     }
+    /** plugin_dom_consent 两步握手的预检（index.ts 用）：只有声明了 dom 能力的
+     *  插件才允许生成在途 consent 请求——任意 pluginId 进不来，在途表不膨胀。 */
+    isDomPlugin(pluginId) {
+        return this.domWants.get(pluginId) === true;
+    }
     /** 特权 DOM 授权/撤销（设置面板 plugin_dom_consent）。
      *  返回 { changed }：变了才 epoch+1 重推（浏览器按新 epoch 重拉 bundle，
      *  失败缓存随 syncPluginViews 的 epoch 切换清掉）；目标不是 wantsDom 插件
@@ -1229,6 +1465,81 @@ export class PluginManager {
             }
         }
     }
+    /** agent-service 调（P1-5）：bash/read 执行前的守卫求值。首个 deny/ask 胜出；
+     *  守卫抛错/超时一律按弃权（不阻断）。无守卫时回 allow，调用方可直接放行。 */
+    async evaluateToolPre(req, lang = "en") {
+        const frozen = {
+            toolName: req.toolName,
+            params: freezeParams(req.params),
+            conversationId: req.conversationId,
+        };
+        for (const p of this.loaded.values()) {
+            for (const h of p.preGuards ?? []) {
+                let raw;
+                try {
+                    raw = await withGuardTimeout(Promise.resolve().then(() => h(frozen)));
+                }
+                catch (err) {
+                    console.error(`[plugin:${p.info.id}] tool-pre guard failed (abstained):`, err);
+                    this.pushRuntimeDiag(p.info.id, `tool-pre guard threw, abstained (${req.toolName})`);
+                    continue;
+                }
+                if (raw === undefined)
+                    continue;
+                const d = normalizePreDecision(raw);
+                if (!isBlockingDecision(d))
+                    continue;
+                this.pushRuntimeDiag(p.info.id, `tool-pre ${d.decision} ${req.toolName} (by ${p.info.id})`);
+                return { verdict: d, pluginId: p.info.id };
+            }
+        }
+        return { verdict: { decision: "allow" } };
+    }
+    /** agent-service 调（P1-5）：bash/read 执行后的守卫合并。逐个顺序合进结果；
+     *  抛错/超时的那个被跳过（其余继续）。返回合并后的 content（无编辑回 undefined）。 */
+    async evaluateToolPost(req, lang = "en") {
+        let content = Array.isArray(req.result?.content)
+            ? [...req.result.content]
+            : undefined;
+        const base = { ...req.result, ...(content ? { content: [...content] } : {}) };
+        let touched = false;
+        const pluginIds = [];
+        const frozenReq = {
+            toolName: req.toolName,
+            params: freezeParams(req.params),
+            result: req.result,
+            conversationId: req.conversationId,
+        };
+        for (const p of this.loaded.values()) {
+            for (const h of p.postGuards ?? []) {
+                let raw;
+                try {
+                    raw = await withGuardTimeout(Promise.resolve().then(() => h(frozenReq)));
+                }
+                catch (err) {
+                    console.error(`[plugin:${p.info.id}] tool-post guard failed (skipped):`, err);
+                    this.pushRuntimeDiag(p.info.id, `tool-post guard threw, skipped (${req.toolName})`);
+                    continue;
+                }
+                const edit = normalizePostEdit(raw);
+                if (!edit)
+                    continue;
+                const merged = applyPostEdit(base, edit, lang);
+                base.content = merged.content;
+                Object.assign(base, merged);
+                touched = true;
+                pluginIds.push(p.info.id);
+                this.pushRuntimeDiag(p.info.id, `tool-post edited ${req.toolName} (by ${p.info.id})`);
+            }
+        }
+        if (!touched)
+            return undefined;
+        return { content: base.content, pluginIds };
+    }
+    /** 阻断时给模型看的一句话（pre 守卫命中后由 agent-service 取用）。 */
+    guardDenialText(verdict, pluginId, lang = "en") {
+        return denialText(verdict, pluginId, lang);
+    }
     /** index.ts 注入：读取当前打开对话的快照（轨迹类插件经 host.getActiveConversation 调用）。 */
     conversationProvider = undefined;
     /** index.ts 注入：插件无头调用 agent（微信通道等经 host.chat 调用）。 */
@@ -1351,13 +1662,37 @@ export class PluginManager {
     }
     /** 当前打开对话的快照（无提供者/暂无对话时返回 null）。 */
     getActiveConversation() {
+        let snap;
         try {
-            return this.conversationProvider?.() ?? null;
+            snap = this.conversationProvider?.() ?? null;
         }
         catch (err) {
             console.error("[plugins] conversationProvider failed:", err);
             return null;
         }
+        if (!snap)
+            return null;
+        // 交给插件前做防御性拷贝：provider 回的是快照管线的**活引用** —— messages
+        // 数组与元素对象都被 60ms 推送管线缓存复用（lastMessagesArray / uiMessageCache），
+        // 插件原地改一个字段/挪一个元素，污染的就是推给真实客户端的快照。浅拷数组 +
+        // 元素对象 structuredClone；元素是纯 JSON 结构（details 已过 JSON.stringify 闸），
+        // structuredClone 不会失败，JSON 往返只是万一携带不可克隆值时的兜底。
+        return {
+            ...snap,
+            messages: snap.messages.map((m) => {
+                try {
+                    return structuredClone(m);
+                }
+                catch {
+                    try {
+                        return JSON.parse(JSON.stringify(m));
+                    }
+                    catch {
+                        return { ...m }; // 连 JSON 往返都失败（循环引用）：至少不共享顶层对象
+                    }
+                }
+            }),
+        };
     }
     /** agent-service 调：当前打开对话变了（切历史会话/切 running 对话/新对话）——
      *  轨迹类插件靠它重拉时间线（异常隔离）。 */
@@ -1435,13 +1770,23 @@ export class PluginManager {
             out.push(...table.values());
         return out;
     }
-    /** 注册一个供 AI 调用的工具；重名拒绝并返回空操作注销函数。 */
+    /** 注册一个供 AI 调用的工具；重名拒绝并返回空操作注销函数。
+     *  跨插件重名同样拒绝（与 registerCommand 同口径）：工具进会话时按名字合入
+     *  （syncPluginToolsIntoSession 的 byName 覆盖），重名意味着后注册者静默抢注
+     *  前者的工具，必须在这里挡下。 */
     registerAgentTool(pluginId, tool) {
         if (!tool || typeof tool.execute !== "function" || !tool.name || !tool.description) {
             console.error(`[plugin:${pluginId}] registerAgentTool: 缺少 name/description/execute，忽略`);
             this.pushRuntimeDiag(pluginId, "registerAgentTool: missing name/description/execute, ignored");
             return () => { };
         }
+        for (const [pid, other] of this.agentTools) {
+            if (pid !== pluginId && other.has(tool.name)) {
+                console.error(`[plugin:${pluginId}] AI 工具 "${tool.name}" 已被插件 ${pid} 注册，忽略重复`);
+                this.pushRuntimeDiag(pluginId, `agent tool "${tool.name}": already registered by plugin ${pid}, ignored`);
+                return () => { };
+            }
+        }
         let table = this.agentTools.get(pluginId);
         if (!table)
             this.agentTools.set(pluginId, (table = new Map()));
@@ -1618,13 +1963,61 @@ export class PluginManager {
     async list(lang) {
         return this.scan(lang);
     }
+    /** 机器可读的注册面目录（P2-7）：slot 别名/kind/例子 + 工具目录 +
+     *  宿主方法表 + 当前占用者（现算）。只读装配，无副作用。 */
+    getApiCatalog() {
+        const counts = new Map();
+        const add = (pluginId, slot) => {
+            let m = counts.get(slot);
+            if (!m)
+                counts.set(slot, (m = new Map()));
+            m.set(pluginId, (m.get(pluginId) ?? 0) + 1);
+        };
+        for (const [pid, base] of this.uiBase)
+            for (const it of base.items ?? [])
+                add(pid, it.slot);
+        for (const [pid, rt] of this.uiRuntime)
+            for (const it of rt.items.values())
+                add(pid, it.slot);
+        return buildPluginApiCatalog({
+            slots: [...UI_SLOTS],
+            aliases: { ...UI_SLOT_ALIASES },
+            kinds: [...UI_KINDS],
+            agentTools: AGENT_TOOL_CATALOG.map((t) => ({
+                name: t.name,
+                group: t.group,
+                defaultOn: t.defaultOn,
+                dshVisible: t.dshVisible,
+            })),
+            occupantsOf: (slot) => {
+                const m = counts.get(slot);
+                if (!m)
+                    return [];
+                return [...m].map(([pluginId, items]) => ({ pluginId, items }));
+            },
+        });
+    }
     /**
      * attach 时调用：重扫目录 + 激活尚未加载的新插件。
      * 返回给浏览器的目录（含激活失败的条目，前端显示为不可用）。
      */
     async ensureLoaded(lang) {
+        const l = lang?.() ?? "en";
         const found = await this.scan(lang);
-        for (const info of found) {
+        const byId = new Map(found.map((f) => [f.id, f]));
+        const scannedIds = new Set(byId.keys());
+        // P2-8：依赖拓扑排序激活（被依赖者先行；决定启动时机的是依赖，不是目录顺序）。
+        // 边只连本次扫描里存在的对端；缺失的对端由 activate 点名拒绝。环上节点直接拒。
+        const { order, cyclic } = sortByRequires(found.map((f) => f.id), (id) => (byId.get(id)?.requires?.plugins ?? []).filter((d) => scannedIds.has(d)));
+        for (const cycId of cyclic) {
+            const info = byId.get(cycId);
+            if (this.loaded.has(info.id) || this.attempted.has(info.id))
+                continue;
+            const msg = pick(l, `插件 requires 存在循环依赖（${cycId}）—— 请先解环再激活`, `Plugin has cyclic requires (${cycId}) — break the cycle first`, "plugins.requires.cycle", { id: cycId });
+            this.setFrozenRefusal(info, msg, `cyclic requires (${cycId})`);
+        }
+        for (const id of order) {
+            const info = byId.get(id);
             if (this.loaded.has(info.id) || this.attempted.has(info.id))
                 continue;
             if (!existsSync(join(this.pluginsDir, info.id, "index.mjs")))
@@ -1638,6 +2031,8 @@ export class PluginManager {
                 this.deactivateEntry(id, p);
             }
         }
+        // P2-8 级联：提供方刚坏（被删/失败/被拒）→ 仍在跑的消费方一并反激活 + 教学占位。
+        this.cascadeRequiresRefusals(found, lang);
         return found.map((f) => {
             const base = this.loaded.get(f.id)?.info ?? f;
             // 运行相位（设置面板清单用）：宿主持有实例即 active（含激活失败的占位行；
@@ -1650,32 +2045,23 @@ export class PluginManager {
             return rest;
         });
     }
-    /** 反激活清理：把该插件名下全部订阅/注册一次收完（工具/命令/watch/定时/
-     *  总线/stats/流式——参考 agentToolUnsubscribers 模式，新增订阅一律走这里）。 */
+    /** 反激活清理：把该插件名下全部订阅/注册一次收完。
+     *
+     *  两段：① 副作用栈逆序回卷（插件注册的全部可逆副作用都在里面 —— 工具/命令/路由/
+     *  代理/watch/定时/后台任务/事件订阅/UI 条目…；跑不干净的记一条诊断）；
+     *  ② 兜底回收全局表里按 pluginId 索引的残留（老宿主激活的实例没有栈、或
+     *  插件绕过 host 自己往表里塞过东西：代理前缀按 id 过滤清一遍，幂等）。 */
     releaseEntry(p) {
-        // 该插件注册的代理前缀随反激活一起回收（全局表按 pluginId 过滤；
+        // ① 逆序回卷。失败项已在栈内打过诊断，这里不再重复。
+        const failed = p.effects?.release() ?? [];
+        if (failed.length > 0)
+            console.warn(`[plugin:${p.info.id}] ${failed.length} effect(s) failed to clean up: ${failed.join(", ")}`);
+        // ② 兜底：代理前缀随反激活一起回收（全局表按 pluginId 过滤；
         // Map 迭代中删除是良定义的：删过的条目不会再被访问到）。
         for (const [prefix, hit] of this.proxyRoutes) {
             if (hit.pluginId === p.info.id)
                 this.proxyRoutes.delete(prefix);
         }
-        // eslint-disable-next-line unicorn/no-useless-spread -- snapshot: handlers may unsubscribe mid-emit
-        for (const off of [
-            ...(p.agentToolUnsubscribers ?? []),
-            ...(p.commandUnsubscribers ?? []),
-            ...(p.watchUnsubscribers ?? []),
-            ...(p.scheduleUnsubscribers ?? []),
-            ...(p.busUnsubscribers ?? []),
-            ...(p.statsUnsubscribers ?? []),
-            ...(p.streamingUnsubscribers ?? []),
-        ]) {
-            try {
-                off();
-            }
-            catch {
-                /* already gone */
-            }
-        }
     }
     /** 反激活单个插件：deactivate + 注销 AI 工具 + 清缓存。
      *
@@ -1709,17 +2095,26 @@ export class PluginManager {
         this.epochCounter += 1;
         console.log(`[plugin:${id}] removed`);
     }
-    /** 关机时反激活全部插件。 */
+    /** 关机 / reload 时反激活全部插件（dispose 后 loaded 为空，后续 releaseEntry 是 no-op）。 */
     dispose() {
+        const pluginIds = new Set();
         for (const [id, p] of this.loaded) {
+            pluginIds.add(id);
             try {
                 p.deactivate?.();
             }
             catch (err) {
                 console.error(`[plugin:${id}] deactivate failed:`, err);
             }
-            this.releaseEntry(p);
-            // 反激活时停掉它注册的常驻后台任务（轮询器等），不留孤儿计时器。
+        }
+        // ① 先回卷全部 effect 栈（含 bgTask 停表、工具/命令/路由/watch/UI 条目注销），
+        //    并把 loaded 清掉 —— 之后逐个走 releaseEntry 的兜底回收。
+        for (const [id, p] of this.loaded) {
+            p.effects?.release();
+            this.loaded.delete(id);
+        }
+        // ② 兜底：停掉任何没经 effect 栈登记的常驻后台任务，不留孤儿计时器。
+        for (const id of pluginIds) {
             for (const t of this.pluginBgTasks.get(id)?.values() ?? []) {
                 try {
                     t.stop?.();
@@ -1729,6 +2124,11 @@ export class PluginManager {
                 }
             }
         }
+        // ③ 兜底：清掉插件名下的代理前缀（该插件名下但未经栈登记的残留）。
+        for (const prefix of [...this.proxyRoutes.keys()]) {
+            if (pluginIds.has(this.proxyRoutes.get(prefix).pluginId))
+                this.proxyRoutes.delete(prefix);
+        }
         this.pluginBgTasks.clear();
         this.loaded.clear();
         this.messageHandlers.clear();
@@ -1762,6 +2162,43 @@ export class PluginManager {
                 this.domWants.set(name, wantsDom);
                 // 本轮 manifest 解析的诊断（重算覆盖；运行时诊断另存在 runtimeDiags）。
                 const uiDiags = [];
+                // P1-6：manifest 本体先校验，失败即拒（坏配置不进运行时）。
+                const mv = validatePluginManifest(m, name);
+                for (const w of mv.warnings)
+                    uiDiags.push(formatManifestIssue(w));
+                if (mv.errors.length > 0) {
+                    for (const e of mv.errors)
+                        uiDiags.push(formatManifestIssue(e));
+                    const first = mv.errors[0];
+                    const msg = pick(l, `manifest 校验失败：${first.message}（${name}/）—— 修复后点“重新扫描”`, `manifest validation failed: ${first.messageEn} (${name}/) — fix it, then hit Rescan`, "plugins.manifest.invalid", { name, path: first.path });
+                    console.error(`[plugin:${name}] ${msg}`);
+                    this.manifestDiags.set(name, uiDiags);
+                    const refused = [...uiDiags, ...(this.runtimeDiags.get(name) ?? [])].slice(0, 100);
+                    out.push({
+                        id: name,
+                        name: typeof m.name === "string" && m.name ? m.name : name,
+                        hasClient: existsSync(join(dir, "client", "entry.mjs")),
+                        error: msg,
+                        view: false,
+                        ...(refused.length ? { diagnostics: refused } : {}),
+                    });
+                    const lpRefused = this.loaded.get(name);
+                    if (lpRefused) {
+                        if (refused.length)
+                            lpRefused.info.diagnostics = [...refused];
+                        else
+                            delete lpRefused.info.diagnostics;
+                    }
+                    continue;
+                }
+                // P2-9：声明式设置的三层合并（schema 默认 < 用户 overlay < 面板保存值）。
+                // overlay 先读先洗，警告进诊断（英文短句，随清单下发）；secret 永不来自 overlay。
+                const settingsSchemaForScan = parseSettingsSchema(m.settings);
+                const overlayFileForScan = readSettingsOverlayFile(this.dataDir, name);
+                const overlayForScan = cleanOverlaySettings(settingsSchemaForScan, overlayFileForScan.raw, "en");
+                for (const w of [...overlayFileForScan.warnings, ...overlayForScan.warnings])
+                    uiDiags.push(`override: ${w}`);
+                const resolvedSettingsForScan = resolveSettingsValues(settingsSchemaForScan, readStoredSettings(dir), overlayForScan.values, { has: (k) => new PluginSecrets(this.dataDir, dir).has(k) });
                 out.push({
                     id: name,
                     name: typeof m.name === "string" && m.name ? m.name : name,
@@ -1792,6 +2229,9 @@ export class PluginManager {
                     peerPlugins: Array.isArray(m.peerPlugins)
                         ? m.peerPlugins.filter((x) => typeof x === "string" && ID_RE.test(x)).slice(0, 16)
                         : undefined,
+                    // 硬依赖声明（manifest "requires"，P2-8）：形状坏的在 P1-6 校验层已拒，
+                    // 这里只做宽容解析供展示 + activate 语义判定（缺失/失败/环/版本/能力即拒）。
+                    requires: parseRequires(m.requires),
                     // 特权 DOM：permissions 含 dom 族 → bundle 默认 403，需用户逐个授权。
                     // wantsDom 缓进 domWants（静态门禁查它，不必每次 readdir）；error 在未授权时
                     // 直接写明原因（tab 置灰 + 设置行提示），授权后下次 scan 自动清除。
@@ -1807,8 +2247,9 @@ export class PluginManager {
                         }
                         : {}),
                     // 声明式设置 schema + 当前存值（⚙ 面板自动渲染表单用）
-                    settingsSchema: parseSettingsSchema(m.settings),
-                    settingsValues: storedSettingsValues(dir, parseSettingsSchema(m.settings), new PluginSecrets(this.dataDir, dir)),
+                    settingsSchema: settingsSchemaForScan,
+                    settingsValues: resolvedSettingsForScan.values,
+                    settingsSources: resolvedSettingsForScan.sources,
                     // 可渲染的 fenced-code 语言（manifest "renderers"）——前端据此按需加载
                     renderers: Array.isArray(m.renderers)
                         ? m.renderers.filter((r) => typeof r === "string" && r.length > 0).slice(0, 32)
@@ -1823,6 +2264,39 @@ export class PluginManager {
                     composerProviders: Array.isArray(m.composerProviders)
                         ? m.composerProviders.filter((r) => typeof r === "string" && r.length > 0).slice(0, 32)
                         : undefined,
+                    // 文件单击查看器声明：只下发扩展名/处理器 id/优先级，实际 DOM
+                    // 渲染仍由客户端 bundle 提供，避免 manifest 携带可执行内容。
+                    fileHandlers: (() => {
+                        if (!Array.isArray(m.fileHandlers))
+                            return undefined;
+                        const rows = m.fileHandlers
+                            .filter((x) => Boolean(x) && typeof x === "object" && !Array.isArray(x))
+                            .slice(0, 32)
+                            .map((x) => {
+                            const extensions = Array.isArray(x.extensions)
+                                ? x.extensions
+                                    .filter((e) => typeof e === "string" && /^\.[A-Za-z0-9][A-Za-z0-9._-]*$/.test(e.trim()))
+                                    .map((e) => e.trim().toLowerCase())
+                                    .slice(0, 32)
+                                : [];
+                            if (!extensions.length)
+                                return null;
+                            const id = typeof x.id === "string" && /^[A-Za-z0-9_-]+$/.test(x.id) ? x.id : "default";
+                            return {
+                                id,
+                                extensions: [...new Set(extensions)],
+                                priority: Number.isFinite(Number(x.priority))
+                                    ? Math.max(-1000, Math.min(1000, Number(x.priority)))
+                                    : 0,
+                                ...(typeof x.label === "string" && x.label.trim() ? { label: x.label.trim().slice(0, 120) } : {}),
+                                ...(typeof x.labelEn === "string" && x.labelEn.trim()
+                                    ? { labelEn: x.labelEn.trim().slice(0, 120) }
+                                    : {}),
+                            };
+                        })
+                            .filter((x) => x !== null);
+                        return rows.length ? rows : undefined;
+                    })(),
                     // 是否有独立视图 tab（manifest "view"，缺省 true）；纯 renderer 插件写 false
                     view: typeof m.view === "boolean" ? m.view : true,
                     // 客户端 bundle 是否常驻加载（manifest "preload"，缺省 false）：无视图
@@ -1910,22 +2384,120 @@ export class PluginManager {
         }
         return out;
     }
+    /** 非 activate 上下文的拒绝占位（P2-8 环/级联）：空集合 + error + 诊断，
+     *  与各门控的占位行同形（ensureLoaded 照例跳过，reload 重算刷新）。 */
+    setFrozenRefusal(info, msg, diagEn) {
+        console.error(`[plugin:${info.id}] ${msg}`);
+        this.pushRuntimeDiag(info.id, diagEn);
+        this.loaded.set(info.id, {
+            info: { ...info, error: msg, diagnostics: this.diagnosticsOf(info.id) },
+            toolHandlers: new Set(),
+            runHandlers: new Set(),
+            convChangeHandlers: new Set(),
+            attachHandlers: new Set(),
+            cwdHandlers: new Set(),
+            httpRoutes: new Map(),
+            settingsHandlers: new Set(),
+        });
+    }
+    /** 级联（P2-8）：提供方刚坏掉（被删/失败/被拒）→ 仍在跑的消费方一并反激活 +
+     *  留教学占位。循环直到一轮无变化（链式依赖一轮收敛），返回受影响的 id。
+     *  hostApi/families 运行时不变，这里只查 plugins 对端（目录在 + 后端 peer 激活成功）。 */
+    cascadeRequiresRefusals(found, lang) {
+        const l = lang?.() ?? "en";
+        const byId = new Map(found.map((f) => [f.id, f]));
+        const hit = [];
+        for (;;) {
+            let changed = false;
+            for (const [id, p] of [...this.loaded]) {
+                if (p.info.error)
+                    continue;
+                const req = byId.get(id)?.requires ?? p.info.requires;
+                if (!req?.plugins?.length)
+                    continue;
+                for (const dep of req.plugins) {
+                    let why = "";
+                    let whyEn = "";
+                    if (dep === id) {
+                        why = `插件 requires 依赖了自己（${dep}）—— 请删掉这条自依赖`;
+                        whyEn = `Plugin requires itself (${dep}) — remove the self-dependency`;
+                    }
+                    else if (!byId.has(dep)) {
+                        why = `插件 requires 对等插件「${dep}」但它已不在（被删/被拒）—— 装回来或去掉这条依赖`;
+                        whyEn = `Plugin requires peer "${dep}" which is gone (removed or refused) — reinstall it or drop the dependency`;
+                    }
+                    else if (existsSync(join(this.pluginsDir, dep, "index.mjs"))) {
+                        const peer = this.loaded.get(dep);
+                        if (!peer || peer.info.error) {
+                            why = `插件 requires 对等插件「${dep}」但它已失败/停止：${peer?.info.error ?? "未激活"}—— 修好它或去掉这条依赖`;
+                            whyEn = `Plugin requires peer "${dep}" which failed/stopped: ${peer?.info.error ?? "inactive"} — fix it or drop the dependency`;
+                        }
+                    }
+                    if (!why)
+                        continue;
+                    const msg = pick(l, why, whyEn, "plugins.requires.cascade", { dep });
+                    this.deactivateEntry(id, p);
+                    this.setFrozenRefusal(byId.get(id) ?? p.info, msg, whyEn);
+                    hit.push(id);
+                    changed = true;
+                    break;
+                }
+            }
+            if (!changed)
+                break;
+        }
+        return hit;
+    }
     async activate(info, lang) {
         const l = lang?.() ?? "en";
         this.attempted.add(info.id);
         const dir = join(this.pluginsDir, info.id);
+        // P1-6：manifest 本体失败即拒（scan 缓存可能过期，这里重读重判，半途注册的副作用不留）。
+        try {
+            const rawManifest = readFileSync(join(dir, "manifest.json"), "utf8");
+            const parsedManifest = JSON.parse(rawManifest);
+            const mvActivate = validatePluginManifest(parsedManifest, info.id);
+            if (mvActivate.errors.length > 0) {
+                const first = mvActivate.errors[0];
+                const msg = pick(l, `manifest 校验失败：${first.message} —— 修复后点“重新扫描”`, `manifest validation failed: ${first.messageEn} — fix it, then hit Rescan`, "plugins.manifest.invalid", { name: info.id, path: first.path });
+                console.error(`[plugin:${info.id}] ${msg}`);
+                for (const e of mvActivate.errors)
+                    this.pushRuntimeDiag(info.id, formatManifestIssue(e));
+                for (const w of mvActivate.warnings)
+                    this.pushRuntimeDiag(info.id, formatManifestIssue(w));
+                this.loaded.set(info.id, {
+                    info: { ...info, error: msg, diagnostics: this.diagnosticsOf(info.id) },
+                    toolHandlers: new Set(),
+                    runHandlers: new Set(),
+                    convChangeHandlers: new Set(),
+                    attachHandlers: new Set(),
+                    cwdHandlers: new Set(),
+                    httpRoutes: new Map(),
+                    settingsHandlers: new Set(),
+                });
+                return;
+            }
+        }
+        catch {
+            // 读不到/解析失败 → 走原有的 broken 占位逻辑（scan 里已产出，不在这里重复拒绝）。
+        }
         const handlers = new Set();
         this.messageHandlers.set(info.id, handlers);
         const toolHandlers = new Set();
+        const preGuards = new Set();
+        const postGuards = new Set();
         const runHandlers = new Set();
         const convChangeHandlers = new Set();
         const attachHandlers = new Set();
         const cwdHandlers = new Set();
         const httpRoutes = new Map();
-        const unregisterTools = [];
-        const unregisterCommands = [];
         const bgTaskTable = new Map();
         const settingsHandlers = new Set();
+        // 可逆副作用栈：本插件的全部注册面（工具/命令/路由/代理/watch/定时/后台任务/
+        // UI 条目/事件订阅…）都经 effects.add 登记，反激活时**逆序**回卷 —— 插件忘写
+        // 注销也不会留下孤儿订阅/定时器/路由（热重载后事件双触发、定时器叠加、watcher
+        // 堆积都是这个漏法的症状）。cleanup 抛错只记诊断，不阻断回卷。
+        const effects = new PluginEffectStack(info.id, (m) => this.pushRuntimeDiag(info.id, m));
         // 宿主 API 版本协商：插件要的比宿主新 → 明确拒绝（而不是让它在运行期
         // 撞 undefined 接口莫名其妙地坏）。与激活失败同一处理：error 字段 + 置灰。
         let apiVersion = 1;
@@ -1956,6 +2528,76 @@ export class PluginManager {
         const permsDeclared = (info.permissions ?? []).slice();
         const strict = permsDeclared.length > 0 || apiVersion >= 2;
         const permFamilies = new Set(permsDeclared.map((x) => x.split(":")[0]));
+        // 硬依赖声明（manifest "requires"，P2-8）：任一条不满足即拒绝激活 + 教学式错误
+        // （peerPlugins 仍是缺失只警告的软依赖）。形状坏的在 P1-6 校验层已提前拒，
+        // 这里只做语义判定：hostApi 下限、能力族已知+已声明、对等插件已安装且激活成功。
+        const req = info.requires;
+        if (req) {
+            const refuseRequires = (zh, en, key, vars) => {
+                const msg = pick(l, zh, en, key, vars);
+                console.error(`[plugin:${info.id}] ${msg}`);
+                this.pushRuntimeDiag(info.id, en);
+                this.loaded.set(info.id, {
+                    info: { ...info, error: msg, diagnostics: this.diagnosticsOf(info.id) },
+                    toolHandlers,
+                    runHandlers,
+                    convChangeHandlers,
+                    attachHandlers,
+                    cwdHandlers,
+                    httpRoutes,
+                    settingsHandlers: new Set(),
+                });
+                return true;
+            };
+            if (req.hostApi !== undefined && req.hostApi > PLUGIN_API_VERSION) {
+                refuseRequires(`插件要求宿主 API v${req.hostApi}+，当前宿主 v${PLUGIN_API_VERSION} —— 请升级 pi-web-ui`, `Plugin requires host API v${req.hostApi}+ but the host is v${PLUGIN_API_VERSION} — please upgrade pi-web-ui`, "plugins.requires.hostapi", { hostApi: req.hostApi, PLUGIN_API_VERSION });
+                return;
+            }
+            let refused = false;
+            for (const f of req.families ?? []) {
+                if (!isKnownPermission(f)) {
+                    refuseRequires(`插件 requires 声明了未知能力族「${f}」（拼写？或需要更新 pi-web-ui）—— 请修正 manifest.requires.families`, `Plugin requires unknown family "${f}" (typo? or needs newer pi-web-ui) — fix manifest.requires.families`, "plugins.requires.family.unknown", { family: f });
+                    refused = true;
+                    break;
+                }
+                const fam = f.split(":")[0];
+                if (!permFamilies.has(fam)) {
+                    refuseRequires(`插件 requires 需要「${fam}」族，但 permissions 里没声明 —— 加上它，否则运行时必被门控拒绝`, `Plugin requires family "${fam}" but does not declare it in permissions — add it, otherwise every call will be denied`, "plugins.requires.family.undeclared", { family: fam });
+                    refused = true;
+                    break;
+                }
+            }
+            if (refused)
+                return;
+            for (const dep of req.plugins ?? []) {
+                if (dep === info.id) {
+                    refuseRequires(`插件 requires 依赖了自己（${dep}）—— 请删掉这条自依赖`, `Plugin requires itself (${dep}) — remove the self-dependency`, "plugins.requires.self", { dep });
+                    refused = true;
+                    break;
+                }
+                if (!existsSync(join(this.pluginsDir, dep, "manifest.json"))) {
+                    refuseRequires(`插件 requires 对等插件「${dep}」但它没安装（plugins/${dep}/ 缺失）—— 先装上它`, `Plugin requires peer "${dep}" which is not installed (plugins/${dep}/ missing) — install it first`, "plugins.requires.peer.missing", { dep });
+                    refused = true;
+                    break;
+                }
+                if (existsSync(join(this.pluginsDir, dep, "index.mjs"))) {
+                    const peer = this.loaded.get(dep);
+                    if (!peer) {
+                        refuseRequires(`插件 requires 对等插件「${dep}」但它尚未激活 —— 请先解决它的问题`, `Plugin requires peer "${dep}" which is not active yet — fix it first`, "plugins.requires.peer.inactive", { dep });
+                        refused = true;
+                        break;
+                    }
+                    if (peer.info.error) {
+                        refuseRequires(`插件 requires 对等插件「${dep}」但它激活失败：${peer.info.error}`, `Plugin requires peer "${dep}" which failed to activate: ${peer.info.error}`, "plugins.requires.peer.failed", { dep });
+                        refused = true;
+                        break;
+                    }
+                }
+                // 纯前端对等端（无 index.mjs）：目录存在即满足，它没有激活态。
+            }
+            if (refused)
+                return;
+        }
         // 引擎约束（manifest engines["pi-web-ui"]）：不满足即拒绝激活（与 apiVersion 超前同级处理）。
         // 解析失败 → 警告放行不阻断；对等依赖缺失 → 只警告不断活。
         const enginesReq = info.engines?.["pi-web-ui"];
@@ -1989,12 +2631,7 @@ export class PluginManager {
                 this.pushRuntimeDiag(info.id, `peer plugin missing: ${peer} (warn only, activation continues)`);
             }
         }
-        // 新增订阅的取消函数（反激活时经 releaseEntry 统一释放）。
-        const watchSubs = [];
-        const scheduleSubs = [];
-        const busSubs = [];
-        const statsSubs = [];
-        const streamingSubs = [];
+        // 新增订阅的取消函数（反激活时经 effects 栈统一逆序释放）。
         // 出站网络白名单（scan 解析的 manifest netAllowlist 快照）。
         const netAllow = info.netAllowlist ?? [];
         // 每插件的私有设施：KV 存储 + 加密 secrets + 依赖自动补装（单飞）。
@@ -2013,6 +2650,23 @@ export class PluginManager {
                 return abs;
             throw new Error(`目录未授权：先 await host.fs.requestAccess(dir)（${abs}）`);
         };
+        /** 写类操作（write/remove）的 realpath 复核：allowAbs 是纯字符串判定，
+         *  授权目录里的符号链接/junction 能把写入/递归删除引到授权范围之外。
+         *  取目标最近已存在祖先的 realpath，要求它仍落在（工作区或该插件任一
+         *  已授权目录）的 realpath 内。读/list/stat 保持字符串校验（高频路径，
+         *  且读不存在「把内容写到别处」的风险）。 */
+        const assertRealInsideGrant = async (abs) => {
+            const targetReal = realPathOfNearest(abs);
+            if (!targetReal)
+                throw new Error(`无法解析真实路径：${abs}`);
+            const granted = self.grants.list().find((g) => g.pluginId === info.id)?.paths ?? [];
+            for (const r of [self.cwdValue, ...granted]) {
+                const rootReal = realPathOfNearest(resolve(r)) ?? resolve(r);
+                if (isInsideRoot(rootReal, targetReal))
+                    return;
+            }
+            throw new Error(`路径越界（符号链接指向授权范围之外）：${abs}`);
+        };
         const crossDirFs = {
             list: async (absDir) => {
                 const abs = allowAbs(absDir);
@@ -2027,11 +2681,13 @@ export class PluginManager {
             },
             write: async (absPath, data) => {
                 const abs = allowAbs(absPath);
+                await assertRealInsideGrant(abs);
                 await mkdir(dirname(abs), { recursive: true });
                 await writeFile(abs, data);
             },
             remove: async (absPath) => {
                 const abs = allowAbs(absPath);
+                await assertRealInsideGrant(abs);
                 await rm(abs, { recursive: true, force: true });
             },
             stat: async (absPath) => {
@@ -2155,6 +2811,18 @@ export class PluginManager {
                 toolHandlers.add(h);
                 return () => toolHandlers.delete(h);
             },
+            onToolPre: (h) => {
+                if (!can("tools"))
+                    return () => { };
+                preGuards.add(h);
+                return () => preGuards.delete(h);
+            },
+            onToolPost: (h) => {
+                if (!can("tools"))
+                    return () => { };
+                postGuards.add(h);
+                return () => postGuards.delete(h);
+            },
             onRunEvent: (h) => {
                 runHandlers.add(h);
                 return () => runHandlers.delete(h);
@@ -2366,13 +3034,7 @@ export class PluginManager {
             },
             registerCommand: (cmd) => {
                 const off = this.registerCommand(info.id, cmd);
-                unregisterCommands.push(off);
-                return () => {
-                    const i = unregisterCommands.indexOf(off);
-                    if (i >= 0)
-                        unregisterCommands.splice(i, 1);
-                    off();
-                };
+                return effects.add(`command:/${String(cmd?.name ?? "?").replace(/^\/+/, "")}`, off);
             },
             storage,
             secrets,
@@ -2389,8 +3051,9 @@ export class PluginManager {
                     self.pushRuntimeDiag(info.id, `route: invalid method/path (method=${String(method)} path=${String(path)}), ignored`);
                     return () => { };
                 }
-                httpRoutes.set(`${m} ${path}`, handler);
-                return () => httpRoutes.delete(`${m} ${path}`);
+                const key = `${m} ${path}`;
+                httpRoutes.set(key, handler);
+                return effects.add(`route:${key}`, () => httpRoutes.delete(key));
             },
             registerProxy: (prefix, target) => {
                 if (!can("http"))
@@ -2401,22 +3064,16 @@ export class PluginManager {
                     self.pushRuntimeDiag(info.id, `registerProxy: invalid prefix/target or taken (prefix=${String(prefix)}), ignored`);
                     return () => { };
                 }
-                return () => {
+                return effects.add(`proxy:${p}`, () => {
                     self.unregisterProxy(info.id, p);
-                };
+                });
             },
             // 包一层：插件反激活时自动注销它注册的全部 AI 工具，不留悬挂项。
             registerAgentTool: (tool) => {
                 if (!can("tools"))
                     return () => { };
                 const off = this.registerAgentTool(info.id, tool);
-                unregisterTools.push(off);
-                return () => {
-                    const i = unregisterTools.indexOf(off);
-                    if (i >= 0)
-                        unregisterTools.splice(i, 1);
-                    off();
-                };
+                return effects.add(`agentTool:${String(tool?.name ?? "?")}`, off);
             },
             dir,
             dataDir: this.dataDir,
@@ -2495,8 +3152,7 @@ export class PluginManager {
                             /* already closed */
                         }
                     };
-                    watchSubs.push(off);
-                    return off;
+                    return effects.add(`watch:${String(relPath)}`, off);
                 },
             },
             project: {
@@ -2543,6 +3199,13 @@ export class PluginManager {
                     }
                 };
                 fire();
+                effects.add(`bgTask:${id}`, () => {
+                    if (bgTaskTable.delete(id)) {
+                        if (bgTaskTable.size === 0)
+                            self.pluginBgTasks.delete(info.id);
+                        fire();
+                    }
+                });
                 return {
                     update: (next) => {
                         if (!bgTaskTable.has(id))
@@ -2600,13 +3263,13 @@ export class PluginManager {
                     }
                     if (added.length)
                         void self.pushToAll().catch(() => { });
-                    return () => {
+                    return effects.add(`ui:register(${added.join(",") || "none"})`, () => {
                         if (!added.length)
                             return;
                         for (const id of added)
                             self.removeUiItem(info.id, id);
                         void self.pushToAll().catch(() => { });
-                    };
+                    });
                 },
                 update: (id, patch) => {
                     if (!can("ui"))
@@ -2618,8 +3281,23 @@ export class PluginManager {
                         self.pushRuntimeDiag(info.id, `ui.update: unknown id "${String(id).slice(0, 32)}", ignored`);
                         return;
                     }
-                    const merged = { ...base, ...patch, id, slot: base.slot };
-                    self.uiRuntimeFor(info.id).items.set(id, merged);
+                    // 与注册同一条校验管线：patch 合进 base 后整体过 parseUiItem，
+                    // 非法字段按 parse 语义丢弃/回落（未知键清掉、iconSvg 重新归一化、
+                    // 超长截断、progress 夹取），id 与 slot 不可被 patch 改写。
+                    const diags = [];
+                    const mergedRaw = typeof patch === "object" && patch !== null && !Array.isArray(patch)
+                        ? { ...base, ...patch, id, slot: base.slot }
+                        : { ...base, id, slot: base.slot };
+                    const parsed = parseUiItem(mergedRaw, base.slot, diags);
+                    for (const m of diags)
+                        self.pushRuntimeDiag(info.id, `ui.update: ${m}`);
+                    if (!parsed) {
+                        // 合并结果不合法（典型：patch 把 label 改成空）——按现有 parse 语义
+                        // 视为无效更新，保留原条目。
+                        self.pushRuntimeDiag(info.id, `ui.update: merged item invalid, update ignored`);
+                        return;
+                    }
+                    self.uiRuntimeFor(info.id).items.set(id, parsed);
                     void self.pushToAll().catch(() => { });
                 },
                 remove: (id) => {
@@ -2643,7 +3321,13 @@ export class PluginManager {
                 },
                 list: () => self.uiOf(info.id) ?? { items: [], arrange: [] },
             },
-            getSettings: () => runtimeSettingsValues(dir, info.settingsSchema ?? [], secrets),
+            getSettings: () => {
+                // P2-9：运行时视角同样走三层合并（警告已在 scan 落诊断，这里静默用值）。
+                const schema = info.settingsSchema ?? [];
+                const overlayFile = readSettingsOverlayFile(self.dataDir, info.id);
+                const overlay = cleanOverlaySettings(schema, overlayFile.raw, "en");
+                return runtimeSettingsValues(dir, schema, secrets, overlay.values);
+            },
             onSettingsChanged: (h) => {
                 settingsHandlers.add(h);
                 return () => settingsHandlers.delete(h);
@@ -2915,7 +3599,7 @@ export class PluginManager {
                     }
                 };
                 // 反激活只停表、不断持久化：下次 activate 重调 schedule() 即按落盘声明重建。
-                scheduleSubs.push(cancelTimer);
+                effects.add(`schedule:${sid}`, cancelTimer);
                 return off;
             },
             models: {
@@ -2938,64 +3622,27 @@ export class PluginManager {
             },
             onStats: (h) => {
                 self.statsHandlers.add(h);
-                const off = () => {
+                return effects.add("onStats", () => {
                     self.statsHandlers.delete(h);
-                };
-                statsSubs.push(off);
-                return () => {
-                    const i = statsSubs.indexOf(off);
-                    if (i >= 0)
-                        statsSubs.splice(i, 1);
-                    off();
-                };
+                });
             },
             onStreaming: (h) => {
                 self.streamingHandlers.add(h);
-                const off = () => {
+                return effects.add("onStreaming", () => {
                     self.streamingHandlers.delete(h);
-                };
-                streamingSubs.push(off);
-                return () => {
-                    const i = streamingSubs.indexOf(off);
-                    if (i >= 0)
-                        streamingSubs.splice(i, 1);
-                    off();
-                };
+                });
             },
             net: {
                 fetch: async (url, init) => {
                     if (!can("net"))
                         return { ok: false, error: '插件未声明能力 "net"（manifest.permissions）——请求被拒' };
-                    try {
-                        const u = new URL(String(url));
-                        if (u.protocol !== "http:" && u.protocol !== "https:") {
-                            return { ok: false, error: `net: 不支持的协议 ${u.protocol}` };
-                        }
+                    return pluginNetFetch(url, init, {
                         // 白名单：主机相等或 .后缀匹配；空表即全拒（fail-closed）。
                         // 用户动态批准的主机（host.requestPermission）同样放行，免改 manifest 重装。
-                        const hostname = u.hostname.toLowerCase();
-                        const allowed = netAllow.some((entry) => hostname === entry || hostname.endsWith(`.${entry}`)) ||
-                            self.permGrants.has(info.id, "net", { host: hostname });
-                        if (!allowed)
-                            return {
-                                ok: false,
-                                error: `net: 主机 ${u.hostname} 未授权（manifest.netAllowlist 或 host.requestPermission 申请）`,
-                            };
-                        if (init?.body !== undefined && Buffer.byteLength(String(init.body), "utf8") > 1024 * 1024) {
-                            return { ok: false, error: "net: body 超过 1MB 上限" };
-                        }
-                        const res = await globalThis.fetch(String(url), {
-                            method: init?.method ?? "GET",
-                            ...(init?.headers ? { headers: init.headers } : {}),
-                            ...(init?.body !== undefined ? { body: init.body } : {}),
-                            signal: AbortSignal.timeout(15_000),
-                        });
-                        const text = (await res.text()).slice(0, 512 * 1024);
-                        return { ok: true, status: res.status, text };
-                    }
-                    catch (err) {
-                        return { ok: false, error: err.message };
-                    }
+                        hostAllowed: (hostname) => netAllow.some((entry) => hostname === entry || hostname.endsWith(`.${entry}`)) ||
+                            self.permGrants.has(info.id, "net", { host: hostname }),
+                        fetchImpl: (input, reqInit) => globalThis.fetch(input, reqInit),
+                    });
                 },
             },
             events: {
@@ -3038,18 +3685,11 @@ export class PluginManager {
                     if (!set)
                         self.busHandlers.set(t, (set = new Set()));
                     set.add(handler);
-                    const off = () => {
+                    return effects.add(`bus:${t}`, () => {
                         set.delete(handler);
                         if (set.size === 0)
                             self.busHandlers.delete(t);
-                    };
-                    busSubs.push(off);
-                    return () => {
-                        const i = busSubs.indexOf(off);
-                        if (i >= 0)
-                            busSubs.splice(i, 1);
-                        off();
-                    };
+                    });
                 },
             },
             log: (levelOrArg, ...args) => {
@@ -3068,6 +3708,14 @@ export class PluginManager {
                 else
                     console.log(line);
             },
+            effect: (label, dispose) => {
+                if (typeof dispose !== "function")
+                    return () => { };
+                const name = String(label ?? "")
+                    .trim()
+                    .slice(0, 64) || "anonymous";
+                return effects.add(`plugin:${name}`, dispose);
+            },
         };
         try {
             // Node 对同一 URL 的 import() 永远返回缓存模块——追加 epoch 作查询串
@@ -3083,17 +3731,13 @@ export class PluginManager {
                 info: { ...info, ...(combined ? { diagnostics: combined } : {}) },
                 deactivate: typeof ret === "function" ? ret : undefined,
                 toolHandlers,
+                preGuards,
+                postGuards,
                 runHandlers,
                 convChangeHandlers,
                 attachHandlers,
                 cwdHandlers,
-                agentToolUnsubscribers: unregisterTools,
-                commandUnsubscribers: unregisterCommands,
-                watchUnsubscribers: watchSubs,
-                scheduleUnsubscribers: scheduleSubs,
-                busUnsubscribers: busSubs,
-                statsUnsubscribers: statsSubs,
-                streamingUnsubscribers: streamingSubs,
+                effects,
                 httpRoutes,
                 permsDeclared,
                 permFamilies,
@@ -3108,9 +3752,14 @@ export class PluginManager {
             void this.maybeConsentNotice(info, dir, permsDeclared);
         }
         catch (err) {
+            // 激活失败：先把这一轮已经登记的可逆副作用逆序回卷（半途注册的工具/路由/
+            // 定时器不能留着 —— 插件已经坏了，谁也不会来撤它们），再留一条错误占位行。
+            const failed = effects.release();
             httpRoutes.clear();
             self.activatingGates.delete(info.id);
             this.pushRuntimeDiag(info.id, `activate failed: ${err.message}`);
+            if (failed.length > 0)
+                this.pushRuntimeDiag(info.id, `activate failed with ${failed.length} effect(s) not cleaned: ${failed.join(", ")}`);
             this.loaded.set(info.id, {
                 info: { ...info, error: err.message, diagnostics: this.diagnosticsOf(info.id) },
                 toolHandlers,
@@ -3221,3 +3870,99 @@ export function syncPluginToolsIntoSession(session, defs, prevNames) {
     session._refreshToolRegistry();
     return new Set(defs.map((d) => d.name));
 }
+/** net.fetch 的手动重定向跳数上限。 */
+const NET_FETCH_MAX_REDIRECTS = 5;
+/**
+ * net.fetch 的白名单 + 手动重定向循环（抽出为纯可注入函数，vitest 直测）。
+ *
+ * 为什么不用 redirect:"follow"：跟随重定向不复查白名单，会把「只授权了 A 主机」
+ * 变成「A 主机一跳把你带到任意主机/内网地址」（经典白名单绕过跳板）。所以：
+ *  - 每一跳（含首次）的目标 host 都重新过 allowHost（manifest 白名单 + 用户动态批准）；
+ *  - redirect:"manual"，至多 NET_FETCH_MAX_REDIRECTS 跳；
+ *  - 跨宿主重定向剥掉 authorization/cookie 头（浏览器同款语义，防凭据外带）；
+ *  - 303 一律转 GET 并丢 body；其余 3xx 保持原 method/body（307/308 语义）；
+ *  - 响应文本整体回给插件的现状保留（512KB 截断不变）；
+ *  - timeout 是整条请求链（含所有跳）共享的墙钟预算（与原实现 15s 同量级）。
+ */
+export async function pluginNetFetch(url, init, deps) {
+    const deadline = Date.now() + Math.max(1000, Number(deps.timeoutMs ?? 15_000));
+    let current = String(url ?? "");
+    let method = init?.method;
+    let headers = init?.headers;
+    let body = init?.body;
+    for (let hop = 0;; hop++) {
+        let u;
+        try {
+            u = new URL(current);
+        }
+        catch {
+            return { ok: false, error: `net: 无效 URL ${current}` };
+        }
+        if (u.protocol !== "http:" && u.protocol !== "https:") {
+            return { ok: false, error: `net: 不支持的协议 ${u.protocol}` };
+        }
+        // 白名单：主机相等或 .后缀匹配；空表即全拒（fail-closed）。每一跳都查。
+        if (!deps.hostAllowed(u.hostname.toLowerCase())) {
+            return {
+                ok: false,
+                error: `net: 主机 ${u.hostname} 未授权（manifest.netAllowlist 或 host.requestPermission 申请）`,
+            };
+        }
+        if (body !== undefined && Buffer.byteLength(String(body), "utf8") > 1024 * 1024) {
+            return { ok: false, error: "net: body 超过 1MB 上限" };
+        }
+        let res;
+        try {
+            res = await deps.fetchImpl(current, {
+                ...(method ? { method } : {}),
+                ...(headers ? { headers } : {}),
+                ...(body !== undefined ? { body } : {}),
+                redirect: "manual",
+                signal: AbortSignal.timeout(Math.max(1000, deadline - Date.now())),
+            });
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+        // 3xx 且带 location → 手动跳下一跳（目标 host 重新过上面的白名单）。
+        if (res.status >= 300 && res.status < 400) {
+            const loc = res.headers.get("location");
+            if (loc) {
+                if (hop >= NET_FETCH_MAX_REDIRECTS) {
+                    return { ok: false, error: `net: 重定向超过 ${NET_FETCH_MAX_REDIRECTS} 跳上限` };
+                }
+                let next;
+                try {
+                    next = new URL(loc, u);
+                }
+                catch {
+                    return { ok: false, error: `net: 重定向目标无效 ${loc}` };
+                }
+                if (next.hostname.toLowerCase() !== u.hostname.toLowerCase() && headers) {
+                    // 跨宿主：凭据类头不外带。
+                    const stripped = {};
+                    for (const [k, v] of Object.entries(headers)) {
+                        const key = k.toLowerCase();
+                        if (key === "authorization" || key === "cookie")
+                            continue;
+                        stripped[k] = v;
+                    }
+                    headers = stripped;
+                }
+                if (res.status === 303) {
+                    method = "GET";
+                    body = undefined;
+                }
+                current = next.toString();
+                continue;
+            }
+        }
+        try {
+            const text = (await res.text()).slice(0, 512 * 1024);
+            return { ok: true, status: res.status, text };
+        }
+        catch (err) {
+            return { ok: false, error: err.message };
+        }
+    }
+}