@youweichen/pi-harness 0.0.0-stage → 1.0.0

package/dist/server/plugins.js

@@ -0,0 +1,712 @@
+/**
+ * pi-harness 插件管理器 —— 可选界面组件的加载与桥接。
+ *
+ * 一个插件 = <dataDir>/plugins/<id>/ 目录：
+ *   manifest.json   元数据 { id?, name, version?, description? }（id 缺省取目录名）
+ *   index.mjs       服务端入口（可选）：export default { activate(host) → deactivate? }
+ *   client/         前端资源（可选），经 /plugins/<id>/client/* 以静态文件暴露；
+ *     entry.mjs      视图入口：export default { mount(el, ctx) → cleanup? }
+ *
+ * 设计要点：
+ * - 不装即不存在：目录不在就没有任何协议/UI 痕迹；每次客户端 attach 时重扫目录，
+ *   新丢进来的插件无需重启服务即可出现在顶栏（import 只做一次并缓存）。
+ * - id 必须匹配 ID_RE，防路径穿越；client 静态服务同样逐段校验。
+ * - host 窄接口：broadcast(pluginId, payload) 广播 plugin_data、onMessage 注册
+ *   客户端上行处理、dataDir/cwd/log 环境。发送通道由 index.ts 注入（每个 socket
+ *   的 send 函数），插件本身不接触 ws。
+ * - activate 抛错只标记 error 字段并记日志，绝不影响主进程。
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PluginStorage, PluginSecrets, ensurePluginDeps, WorkspaceFS } from "./plugin-facilities.js";
+import { createHash } from "node:crypto";
+/** 合法插件 id：字母/数字/下划线/连字符，防路径穿越。 */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+/** 宿主提供的插件设施版本——manifest 声明的 apiVersion 高于此值则拒绝激活，
+ *  插件能拿到明确的「请升级 pi-harness」而不是在新接口上莫名 undefined。 */
+export const PLUGIN_API_VERSION = 1;
+/** 消息处理器超时：仅作为不再等待的日志阈值（响应由 handler 自己发出）。 */
+const MESSAGE_TIMEOUT_MS = 30_000;
+/** host.fs 被能力门控拒绝时的共享 rejected promise（类型对齐用）。 */
+const NO_FS_PROMISE = Promise.reject(new Error('插件未声明能力 "fs"（manifest.permissions）——请求被拒'));
+NO_FS_PROMISE.catch(() => { }); // 避免未处理 rejection 噪音；调用方 await 时拿到错误
+// ---------------------------------------------------------------------------
+// 声明式设置 schema（manifest "settings"）
+// ---------------------------------------------------------------------------
+const SETTING_TYPES = new Set(["text", "password", "number", "boolean", "select"]);
+/** 解析 manifest.settings → 合法 schema（坏字段跳过，最多 32 个）。 */
+function parseSettingsSchema(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const f of raw) {
+        if (!f || typeof f !== "object")
+            continue;
+        const o = f;
+        const key = typeof o.key === "string" ? o.key.trim() : "";
+        const type = typeof o.type === "string" ? o.type : "";
+        if (!key || !SETTING_TYPES.has(type) || out.some((x) => x.key === key))
+            continue;
+        const field = {
+            key,
+            type: type,
+            label: typeof o.label === "string" && o.label ? o.label : key,
+            ...(o.default !== undefined ? { default: o.default } : {}),
+            ...(typeof o.min === "number" ? { min: o.min } : {}),
+            ...(typeof o.max === "number" ? { max: o.max } : {}),
+            ...(Array.isArray(o.options)
+                ? { options: o.options.filter((x) => typeof x === "string") }
+                : {}),
+            ...(typeof o.hint === "string" ? { hint: o.hint } : {}),
+        };
+        out.push(field);
+        if (out.length >= 32)
+            break;
+    }
+    return out;
+}
+/** 从 <pluginDir>/storage.json 读 settings 存值，按 schema 并默认值。 */
+function storedSettingsValues(dir, schema) {
+    const out = {};
+    let stored = {};
+    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;
+        }
+    }
+    catch {
+        /* 无存储文件 = 全默认 */
+    }
+    for (const f of schema)
+        out[f.key] = stored[f.key] ?? f.default;
+    return out;
+}
+/** 校验并写回 settings（storage.json 的 settings 键，原子写）；返回错误信息或 null。 */
+function saveSettingsValues(dir, schema, values) {
+    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: `${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") {
+            if (v !== undefined && !f.options?.includes(String(v)))
+                return { error: `${f.label} 值非法`, clean };
+            clean[f.key] = v === undefined ? f.default : String(v);
+        }
+        else {
+            clean[f.key] = v === undefined ? (f.default ?? "") : String(v);
+        }
+    }
+    try {
+        // 保留 storage.json 里其它键（插件自己的数据），只动 settings。
+        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: clean }));
+        renameSync(tmp, file);
+    }
+    catch (err) {
+        console.error(`[plugins] settings persist failed (${dir}):`, err);
+    }
+    return { clean };
+}
+export class PluginManager {
+    dataDir;
+    loaded = new Map();
+    /** 已 import 过但无入口/失败的目录——避免重复 import 与重复报错。 */
+    attempted = new Set();
+    senders = new Set();
+    messageHandlers = new Map();
+    /** 插件常驻任务：pluginId → Map<taskId, PluginBgTask>。宿主经 bgTasks() 读取。 */
+    pluginBgTasks = new Map();
+    /** 任务集合变化回调（index.ts 接到 AgentService，重推 bg_servers）。 */
+    onBgTasksChanged = undefined;
+    /** 服务端重载纪元：每次 reload() +1，前端用作 import 缓存击穿参数。 */
+    epochCounter = 0;
+    /** 当前全局工作区（host.cwd 的背后存储）——随 notifyCwd 更新。 */
+    cwdValue;
+    constructor(dataDir, cwd) {
+        this.dataDir = dataDir;
+        this.cwdValue = resolve(cwd);
+    }
+    /** index.ts 在客户端 set_cwd 成功后调用：更新全局工作区并扇出给
+     *  所有已激活插件的 onCwdChange 钩子（异常隔离，不炸主进程）。 */
+    notifyCwd(next) {
+        const abs = resolve(next);
+        if (abs === this.cwdValue)
+            return; // 幂等：重复通知/同路径 no-op
+        this.cwdValue = abs;
+        for (const [id, p] of this.loaded) {
+            for (const h of p.cwdHandlers) {
+                try {
+                    h(abs);
+                }
+                catch (err) {
+                    console.error(`[plugin:${id}] cwd-change handler failed:`, err);
+                }
+            }
+        }
+    }
+    get pluginsDir() {
+        return join(this.dataDir, "plugins");
+    }
+    /** 全部插件注册的斜杠命令（按插件 id 稳定排序）。 */
+    /** 按名查找命令（供 prompt() 拦截执行；找不到返回 null）。 */
+    /** 全部插件注册的常驻后台任务（扁平化为 BgServer 形状）。 */
+    bgTasks() {
+        const out = [];
+        for (const [pluginId, table] of this.pluginBgTasks) {
+            for (const t of table.values()) {
+                out.push({
+                    taskId: t.id,
+                    plugin: pluginId,
+                    since: t.since,
+                    name: t.label,
+                    ...(t.status ? { status: t.status } : {}),
+                });
+            }
+        }
+        return out;
+    }
+    /** 停止一个插件任务（kill_background_server with taskId）；返回是否命中。 */
+    stopPluginBgTask(taskId) {
+        for (const [pluginId, table] of this.pluginBgTasks) {
+            const t = table.get(taskId);
+            if (!t)
+                continue;
+            try {
+                t.stop?.();
+            }
+            catch (err) {
+                console.error(`[plugin:${pluginId}] background task ${taskId} stop failed:`, err);
+            }
+            table.delete(taskId);
+            if (table.size === 0)
+                this.pluginBgTasks.delete(pluginId);
+            try {
+                this.onBgTasksChanged?.();
+            }
+            catch { }
+            return true;
+        }
+        return false;
+    }
+    /** 保存某插件的声明式设置（⚙ 面板 → plugin_settings 消息）：按 schema 校验、
+     *  原子写 storage.json 的 settings 键、通知插件 onSettingsChanged、重推清单
+     *  让前端回显。返回错误信息或 null（成功）。 */
+    savePluginSettings(pluginId, values) {
+        if (!ID_RE.test(pluginId))
+            return { error: "非法的插件 id" };
+        const dir = join(this.pluginsDir, pluginId);
+        const info = this.loaded.get(pluginId)?.info;
+        const schema = info?.settingsSchema ?? [];
+        if (!schema.length)
+            return { error: "该插件没有声明式设置（manifest 未声明 settings）" };
+        const { error, clean } = saveSettingsValues(dir, schema, values);
+        if (error)
+            return { error };
+        // 通知插件（异常隔离）
+        for (const h of this.loaded.get(pluginId)?.settingsHandlers ?? []) {
+            try {
+                h(clean);
+            }
+            catch (err) {
+                console.error(`[plugin:${pluginId}] onSettingsChanged handler failed:`, err);
+            }
+        }
+        // 重推 plugins 清单（含新 settingsValues），前端回显。
+        void this.pushToAll().catch(() => { });
+        return {};
+    }
+    /** 当前重载纪元（随 plugins 消息下发）。 */
+    get epoch() {
+        return this.epochCounter;
+    }
+    addSender(send, cid) {
+        const s = { cid, send };
+        this.senders.add(s);
+        return () => this.senders.delete(s);
+    }
+    /** 客户端上行：路由给对应插件的处理器；未知/未激活的插件静默丢弃。
+     *  插件代码不可信——同步抛错与返回的 Promise rejection 都必须隔离在
+     *  这里，绝不能炸主进程。 */
+    handleMessage(pluginId, payload, from) {
+        if (!ID_RE.test(pluginId))
+            return;
+        const handlers = this.messageHandlers.get(pluginId);
+        if (!handlers)
+            return;
+        for (const h of handlers) {
+            try {
+                const ret = h(payload, from);
+                if (ret instanceof Promise) {
+                    ret.catch((err) => {
+                        console.error(`[plugin:${pluginId}] async message handler failed:`, err);
+                    });
+                    // 超时护栏：响应由 handler 自己 sendTo/broadcast 发出，超时只是记
+                    // 日志不再等待——绝不能让单条消息把客户端 pending 管线无限拖死。
+                    const timer = setTimeout(() => {
+                        console.error(`[plugin:${pluginId}] message handler 超时（>${MESSAGE_TIMEOUT_MS}ms），已不再等待`);
+                    }, MESSAGE_TIMEOUT_MS);
+                    void ret.finally(() => clearTimeout(timer));
+                }
+            }
+            catch (err) {
+                console.error(`[plugin:${pluginId}] message handler failed:`, err);
+            }
+        }
+    }
+    /** 首次安装/能力变更时提醒在线用户（marker 文件记录上次激活时的声明）。 */
+    async maybeConsentNotice(info, dir, perms) {
+        try {
+            const markerFile = join(dir, ".pi-approved");
+            const key = createHash("sha256").update(JSON.stringify(perms)).digest("hex").slice(0, 32);
+            let prev = "";
+            try {
+                prev = JSON.parse(readFileSync(markerFile, "utf8"))?.key ?? "";
+            }
+            catch {
+                /* 无 marker = 首次安装 */
+            }
+            if (prev === key)
+                return; // 同版本能力清单，不再打扰
+            const list = perms.length ? perms.join(", ") : "无";
+            this.notifyAll(perms.length ? "warning" : "info", `插件「${info.name}」已激活（${prev ? "能力清单变更" : "首次安装"}；声明能力：${list}）——请确认来源可信`);
+            writeFileSync(markerFile, JSON.stringify({ v: 1, key, perms }), "utf8");
+        }
+        catch (err) {
+            console.error(`[plugin:${info.id}] consent notice failed:`, err);
+        }
+    }
+    /** index.ts 的 /plugins-api/:id/* 挂载点转发到这里：找到对应插件的已注册
+     *  路由并执行；未知插件/路径 → 404，handler 抛错 → 500（不炸进程）。 */
+    handleHttp(pluginId, method, pathIn, req, res) {
+        if (!ID_RE.test(pluginId)) {
+            res.status(404).end("plugin not found");
+            return;
+        }
+        const table = this.loaded.get(pluginId)?.httpRoutes;
+        const path = "/" + pathIn.replace(/^\/+/, "");
+        const handler = table?.get(`${method.toUpperCase()} ${path}`);
+        if (!handler) {
+            res.status(404).end("not found");
+            return;
+        }
+        try {
+            handler(req, res);
+        }
+        catch (err) {
+            console.error(`[plugin:${pluginId}] http ${method} ${path} failed:`, err);
+            if (!res.headersSent)
+                res.status(500).end("internal error");
+            else
+                res.end();
+        }
+    }
+    broadcast(pluginId, payload) {
+        this.deliverAll({ type: "plugin_data", pluginId, payload });
+    }
+    /** 系统通知：发给所有 socket（复用 notice 消息，前端 toast 展示）。 */
+    notifyAll(level, text) {
+        this.deliverAll({ type: "notice", level, text });
+    }
+    /** 给指定客户端定向发一条插件消息；找不到该 socket 时静默忽略。 */
+    sendTo(clientId, pluginId, payload) {
+        for (const s of this.senders) {
+            if (s.cid() !== clientId)
+                continue;
+            try {
+                s.send({ type: "plugin_data", pluginId, payload });
+            }
+            catch {
+                /* dead socket */
+            }
+        }
+    }
+    /** 目录清单 + 当前 epoch 推给所有 socket。 */
+    async pushToAll() {
+        const list = await this.scan();
+        this.deliverAll({ type: "plugins", plugins: list, epoch: this.epochCounter });
+    }
+    /** 服务端热重载：反激活全部 → 清缓存 → 重扫重激活 → epoch+1。
+     *  返回新目录清单（含激活结果）。重激活后的插件实例是新模块，
+         *  内存状态为初始值——逐个客户端触发 onAttach 让它们重推自身状态。 */
+    async reload() {
+        this.dispose();
+        this.attempted.clear();
+        this.epochCounter += 1;
+        const list = await this.ensureLoaded();
+        for (const s of this.senders) {
+            const cid = s.cid();
+            if (cid)
+                this.notifyAttach(cid);
+        }
+        return list;
+    }
+    /** 每个客户端 attach 后调用：让各插件向该客户端推送自身完整状态。
+     *  异常隔离——单个插件钩子报错不影响其他插件与其他钩子。 */
+    notifyAttach(clientId) {
+        for (const [id, p] of this.loaded) {
+            for (const h of p.attachHandlers) {
+                try {
+                    h(clientId);
+                }
+                catch (err) {
+                    console.error(`[plugin:${id}] onAttach handler failed:`, err);
+                }
+            }
+        }
+    }
+    /** agent-service 调：把 SDK 工具执行事件扇出给所有插件（异常隔离）。 */
+    emitToolEvent(ev) {
+        for (const p of this.loaded.values()) {
+            for (const h of p.toolHandlers) {
+                try {
+                    h(ev);
+                }
+                catch (err) {
+                    console.error(`[plugin:${p.info.id}] tool-event handler failed:`, err);
+                }
+            }
+        }
+    }
+    /** 注册一个供 AI 调用的工具；重名拒绝并返回空操作注销函数。 */
+    deliverAll(msg) {
+        for (const s of this.senders) {
+            try {
+                s.send(msg);
+            }
+            catch {
+                /* dead socket — index.ts cleans it up */
+            }
+        }
+    }
+    /** 当前目录清单（重扫 manifest，不重新 import）。 */
+    async list() {
+        return this.scan();
+    }
+    /**
+     * attach 时调用：重扫目录 + 激活尚未加载的新插件。
+     * 返回给浏览器的目录（含激活失败的条目，前端显示为不可用）。
+     */
+    async ensureLoaded() {
+        const found = await this.scan();
+        for (const info of found) {
+            if (this.loaded.has(info.id) || this.attempted.has(info.id))
+                continue;
+            if (!existsSync(join(this.pluginsDir, info.id, "index.mjs")))
+                continue; // 纯前端插件
+            await this.activate(info);
+        }
+        // 已被删除的插件：调用 deactivate 并移出缓存
+        for (const [id, p] of [...this.loaded]) {
+            if (!found.some((f) => f.id === id)) {
+                this.deactivateEntry(id, p);
+            }
+        }
+        return found.map((f) => this.loaded.get(f.id)?.info ?? f);
+    }
+    /** 反激活单个插件：deactivate + 注销 AI 工具 + 清缓存。 */
+    deactivateEntry(id, p) {
+        try {
+            p.deactivate?.();
+        }
+        catch (err) {
+            console.error(`[plugin:${id}] deactivate failed:`, err);
+        }
+        this.loaded.delete(id);
+        this.messageHandlers.delete(id);
+        console.log(`[plugin:${id}] removed`);
+    }
+    /** 关机时反激活全部插件。 */
+    dispose() {
+        for (const [id, p] of this.loaded) {
+            try {
+                p.deactivate?.();
+            }
+            catch (err) {
+                console.error(`[plugin:${id}] deactivate failed:`, err);
+            }
+            // 反激活时停掉它注册的常驻后台任务（轮询器等），不留孤儿计时器。
+            for (const t of this.pluginBgTasks.get(id)?.values() ?? []) {
+                try {
+                    t.stop?.();
+                }
+                catch { }
+            }
+        }
+        this.pluginBgTasks.clear();
+        this.loaded.clear();
+        this.messageHandlers.clear();
+    }
+    /** 读 manifest 清单；坏目录（无 manifest/id 非法）直接跳过。 */
+    async scan() {
+        let names;
+        try {
+            names = await readdir(this.pluginsDir);
+        }
+        catch {
+            return []; // 目录不存在 = 没装任何插件
+        }
+        const out = [];
+        for (const name of names.sort()) {
+            if (!ID_RE.test(name))
+                continue;
+            const dir = join(this.pluginsDir, name);
+            try {
+                if (!(await stat(dir)).isDirectory())
+                    continue;
+                const raw = await readFile(join(dir, "manifest.json"), "utf8");
+                const m = JSON.parse(raw);
+                out.push({
+                    id: name,
+                    name: typeof m.name === "string" && m.name ? m.name : name,
+                    version: typeof m.version === "string" ? m.version : undefined,
+                    description: typeof m.description === "string" ? m.description : undefined,
+                    icon: typeof m.icon === "string" && m.icon.trim() ? m.icon.trim() : undefined,
+                    hasClient: existsSync(join(dir, "client", "entry.mjs")),
+                    error: this.loaded.get(name)?.info.error,
+                    // manifest 声明的能力清单（fs/net/tools…）——设置面板展示用
+                    permissions: Array.isArray(m.permissions)
+                        ? m.permissions.filter((p) => typeof p === "string" && p.length > 0).slice(0, 16)
+                        : undefined,
+                    // 声明式设置 schema + 当前存值（⚙ 面板自动渲染表单用）
+                    settingsSchema: parseSettingsSchema(m.settings),
+                    settingsValues: storedSettingsValues(dir, parseSettingsSchema(m.settings)),
+                    // 安装来源（pi-harness install 写入的 .pi-source.json）——
+                    // 设置面板据此显示「更新」按钮；手工拷入的插件没有此文件。
+                    source: await readFile(join(dir, ".pi-source.json"), "utf8")
+                        .then((raw) => {
+                        try {
+                            const s = JSON.parse(raw);
+                            return typeof s.source === "string" && s.source ? s.source : undefined;
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    })
+                        .catch(() => undefined),
+                });
+            }
+            catch {
+                continue; // 无 manifest / JSON 坏 —— 不是插件
+            }
+        }
+        return out;
+    }
+    async activate(info) {
+        this.attempted.add(info.id);
+        const dir = join(this.pluginsDir, info.id);
+        const handlers = new Set();
+        this.messageHandlers.set(info.id, handlers);
+        const toolHandlers = new Set();
+        const attachHandlers = new Set();
+        const cwdHandlers = new Set();
+        const httpRoutes = new Map();
+        const bgTaskTable = new Map();
+        const settingsHandlers = new Set();
+        // 宿主 API 版本协商：插件要的比宿主新 → 明确拒绝（而不是让它在运行期
+        // 撞 undefined 接口莫名其妙地坏）。与激活失败同一处理：error 字段 + 置灰。
+        let apiVersion = 1;
+        try {
+            apiVersion = Number(JSON.parse(readFileSync(join(dir, "manifest.json"), "utf8")).apiVersion ?? 1) || 1;
+        }
+        catch { }
+        if (apiVersion > PLUGIN_API_VERSION) {
+            const msg = `插件要求宿主 API v${apiVersion}，当前宿主 v${PLUGIN_API_VERSION} —— 请升级 pi-harness`;
+            console.error(`[plugin:${info.id}] ${msg}`);
+            this.loaded.set(info.id, { info: { ...info, error: msg }, toolHandlers, attachHandlers, cwdHandlers, httpRoutes, settingsHandlers: new Set() });
+            return;
+        }
+        // 能力声明：写了 permissions → 严格模式（受控宿主 API 按声明族强制执行）；
+        // 未写且 apiVersion < 2 → 旧全权模式（首次使用受控 API 时警告一次，v2 起默认拒绝）。
+        const permsDeclared = (info.permissions ?? []).slice();
+        const strict = permsDeclared.length > 0 || apiVersion >= 2;
+        const permFamilies = new Set(permsDeclared.map((x) => x.split(":")[0]));
+        const p = { info, toolHandlers, attachHandlers, cwdHandlers, httpRoutes, settingsHandlers };
+        p.permsDeclared = permsDeclared;
+        p.permFamilies = permFamilies;
+        p.legacyWarned = false;
+        // 每插件的私有设施：KV 存储 + 加密 secrets + 依赖自动补装（单飞）。
+        const storage = new PluginStorage(join(dir, "storage.json"));
+        const secrets = new PluginSecrets(this.dataDir, dir);
+        // 受限工作区文件访问（能力 "fs" 门控；根随 set_cwd 活值移动）。
+        const workspaceFs = new WorkspaceFS(() => self.cwdValue);
+        /** 能力门控：严格模式下查声明族；旧模式放行但每个激活期只警告一次。
+         *  返回 false = 已记日志，调用方应拒绝。 */
+        const can = (family) => {
+            if (permFamilies.has(family))
+                return true;
+            if (!strict) {
+                if (!p.legacyWarned) {
+                    p.legacyWarned = true;
+                    console.warn(`[plugin:${info.id}] manifest 未声明 permissions（旧格式全权模式）——已放行 "${family}"；apiVersion 2 起将默认拒绝，请尽快声明`);
+                }
+                return true;
+            }
+            console.error(`[plugin:${info.id}] 缺少能力声明 "${family}"（manifest.permissions）——请求被拒`);
+            return false;
+        };
+        const self = this; // 对象字面量 getter 里不能用插件宿主的 this
+        const host = {
+            broadcast: (payload) => this.broadcast(info.id, payload),
+            notify: (level, text) => this.notifyAll(level, text),
+            sendTo: (clientId, payload) => this.sendTo(clientId, info.id, payload),
+            onMessage: (h) => {
+                handlers.add(h);
+                return () => handlers.delete(h);
+            },
+            onToolEvent: (h) => {
+                toolHandlers.add(h);
+                return () => toolHandlers.delete(h);
+            },
+            onAttach: (h) => {
+                attachHandlers.add(h);
+                return () => attachHandlers.delete(h);
+            },
+            onCwdChange: (h) => {
+                cwdHandlers.add(h);
+                return () => cwdHandlers.delete(h);
+            },
+            storage,
+            secrets,
+            ensureDeps: (specs, opts) => ensurePluginDeps(dir, specs ?? [], opts?.onProgress),
+            route: (method, path, handler) => {
+                if (!can("http"))
+                    return () => { };
+                const m = String(method ?? "GET").toUpperCase();
+                if (!["GET", "POST", "PUT", "DELETE"].includes(m) || typeof path !== "string" || !path.startsWith("/") || typeof handler !== "function") {
+                    console.error(`[plugin:${info.id}] route: 非法参数（method=${method} path=${path}），忽略`);
+                    return () => { };
+                }
+                httpRoutes.set(`${m} ${path}`, handler);
+                return () => httpRoutes.delete(`${m} ${path}`);
+            },
+            // 包一层：插件反激活时自动注销它注册的全部 AI 工具，不留悬挂项。
+            dir,
+            dataDir: this.dataDir,
+            get cwd() {
+                return self.cwdValue;
+            },
+            fs: {
+                list: (relDir) => (can("fs") ? workspaceFs.list(relDir) : NO_FS_PROMISE),
+                read: (p) => (can("fs") ? workspaceFs.read(p) : NO_FS_PROMISE),
+                readText: (p, max) => (can("fs") ? workspaceFs.readText(p, max) : NO_FS_PROMISE),
+                write: (p, data) => (can("fs") ? workspaceFs.write(p, data) : NO_FS_PROMISE),
+                remove: (p) => (can("fs") ? workspaceFs.remove(p) : NO_FS_PROMISE),
+            },
+            registerBackgroundTask: (task) => {
+                const id = String(task?.id ?? "").trim();
+                if (!id || bgTaskTable.has(id)) {
+                    console.error(`[plugin:${info.id}] registerBackgroundTask: 非法/重复 id「${task?.id}」，忽略`);
+                    return { update: () => { }, unregister: () => { } };
+                }
+                const entry = {
+                    id,
+                    label: String(task?.label ?? id),
+                    since: Date.now(),
+                    ...(typeof task?.stop === "function" ? { stop: task.stop } : {}),
+                    ...(typeof task?.status === "string" ? { status: task.status } : {}),
+                };
+                bgTaskTable.set(id, entry);
+                this.pluginBgTasks.set(info.id, bgTaskTable);
+                const fire = () => {
+                    try {
+                        this.onBgTasksChanged?.();
+                    }
+                    catch { }
+                };
+                fire();
+                return {
+                    update: (next) => {
+                        if (!bgTaskTable.has(id))
+                            return;
+                        if (next.label !== undefined)
+                            entry.label = String(next.label);
+                        if (next.status !== undefined)
+                            entry.status = next.status;
+                        if (typeof next.stop === "function")
+                            entry.stop = next.stop;
+                        fire();
+                    },
+                    unregister: () => {
+                        if (bgTaskTable.delete(id)) {
+                            if (bgTaskTable.size === 0)
+                                this.pluginBgTasks.delete(info.id);
+                            fire();
+                        }
+                    },
+                };
+            },
+            getSettings: () => storedSettingsValues(dir, info.settingsSchema ?? []),
+            onSettingsChanged: (h) => {
+                settingsHandlers.add(h);
+                return () => settingsHandlers.delete(h);
+            },
+            log: (...args) => console.log(`[plugin:${info.id}]`, ...args),
+        };
+        try {
+            // Node 对同一 URL 的 import() 永远返回缓存模块——追加 epoch 作查询串
+            // 击穿缓存，让 plugins_reload 后的重新激活能拿到磁盘上的新代码。
+            const mod = (await import(pathToFileURL(join(dir, "index.mjs")).href + `?e=${this.epochCounter}`));
+            const ret = await mod.default?.activate?.(host);
+            this.loaded.set(info.id, {
+                info: { ...info },
+                deactivate: typeof ret === "function" ? ret : undefined,
+                toolHandlers,
+                attachHandlers,
+                cwdHandlers,
+                httpRoutes,
+                settingsHandlers,
+            });
+            console.log(`[plugin:${info.id}] activated (v${info.version ?? "?"})`);
+            // 首次安装/能力变更提醒（尽力而为）：<dir>/.pi-approved 记录上次激活时
+            // 的能力清单——新装或 permissions 变更后向在线客户端推一条警告通知，
+            // 用户装前可见、日常启动不打扰。
+            void this.maybeConsentNotice(info, dir, permsDeclared);
+        }
+        catch (err) {
+            httpRoutes.clear();
+            this.loaded.set(info.id, {
+                info: { ...info, error: err.message },
+                toolHandlers,
+                attachHandlers,
+                cwdHandlers,
+                httpRoutes,
+                settingsHandlers: new Set(),
+            });
+            console.error(`[plugin:${info.id}] activate failed:`, err);
+        }
+    }
+}
+/**
+ * 把 /plugins/:id/client/<rest> 安全映射到 <pluginsDir>/<id>/client/<rest>。
+ * 返回绝对路径；任何越界/非法 id 返回 null（调用方回 404）。
+ */
+export function resolvePluginClientFile(pluginsDir, id, rest) {
+    if (!ID_RE.test(id))
+        return null;
+    const root = resolve(join(pluginsDir, id, "client"));
+    // rest 由 express 路由保证不带 ".."，但双保险：resolve 后必须仍在 root 内
+    const abs = resolve(root, rest);
+    if (abs !== root && !abs.startsWith(root + sep))
+        return null;
+    return abs;
+}