pi-web-ui 0.31.0 → 0.34.0

package/dist/server/plugins.js

@@ -0,0 +1,368 @@
+/**
+ * pi-web-ui 插件管理器 —— 可选界面组件的加载与桥接。
+ *
+ * 一个插件 = <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 } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+/** 合法插件 id：字母/数字/下划线/连字符，防路径穿越（同 themes.ts 的做法）。 */
+const ID_RE = /^[A-Za-z0-9_-]+$/;
+export class PluginManager {
+    dataDir;
+    cwd;
+    loaded = new Map();
+    /** 已 import 过但无入口/失败的目录——避免重复 import 与重复报错。 */
+    attempted = new Set();
+    senders = new Set();
+    messageHandlers = new Map();
+    /** 插件注册的 AI 工具：pluginId → (name → 定义)。宿主经 agentTools() 读取。 */
+    agentTools = new Map();
+    /** AI 工具集合变化回调（index.ts 接到 AgentService，把新工具推入活跃会话）。 */
+    onAgentToolsChanged = undefined;
+    /** 服务端重载纪元：每次 reload() +1，前端用作 import 缓存击穿参数。 */
+    epochCounter = 0;
+    constructor(dataDir, cwd) {
+        this.dataDir = dataDir;
+        this.cwd = cwd;
+    }
+    get pluginsDir() {
+        return join(this.dataDir, "plugins");
+    }
+    /** 当前重载纪元（随 plugins 消息下发）。 */
+    get epoch() {
+        return this.epochCounter;
+    }
+    addSender(send, cid) {
+        const s = { cid, send };
+        this.senders.add(s);
+        return () => this.senders.delete(s);
+    }
+    /** 客户端上行：路由给对应插件的处理器；未知/未激活的插件静默丢弃。 */
+    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 {
+                h(payload, from);
+            }
+            catch (err) {
+                console.error(`[plugin:${pluginId}] message handler failed:`, err);
+            }
+        }
+    }
+    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。
+     *  返回新目录清单（含激活结果）。 */
+    async reload() {
+        this.dispose();
+        this.attempted.clear();
+        this.epochCounter += 1;
+        return this.ensureLoaded();
+    }
+    /** 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 工具（扁平化，按插件 id 稳定排序）。 */
+    getAgentTools() {
+        const out = [];
+        for (const table of [...this.agentTools.values()].sort())
+            out.push(...table.values());
+        return out;
+    }
+    /** 注册一个供 AI 调用的工具；重名拒绝并返回空操作注销函数。 */
+    registerAgentTool(pluginId, tool) {
+        if (!tool || typeof tool.execute !== "function" || !tool.name || !tool.description) {
+            console.error(`[plugin:${pluginId}] registerAgentTool: 缺少 name/description/execute，忽略`);
+            return () => { };
+        }
+        let table = this.agentTools.get(pluginId);
+        if (!table)
+            this.agentTools.set(pluginId, (table = new Map()));
+        if (table.has(tool.name)) {
+            console.error(`[plugin:${pluginId}] AI 工具 "${tool.name}" 重复注册，忽略`);
+            return () => { };
+        }
+        table.set(tool.name, tool);
+        console.log(`[plugin:${pluginId}] registered AI tool: ${tool.name}`);
+        try {
+            this.onAgentToolsChanged?.();
+        }
+        catch (err) {
+            console.error("[plugins] onAgentToolsChanged failed:", err);
+        }
+        return () => {
+            if (table.delete(tool.name)) {
+                if (table.size === 0)
+                    this.agentTools.delete(pluginId);
+                try {
+                    this.onAgentToolsChanged?.();
+                }
+                catch {
+                    /* shutting down */
+                }
+            }
+        };
+    }
+    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);
+        }
+        for (const off of [...(p.agentToolUnsubscribers ?? [])]) {
+            try {
+                off();
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        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 off of [...(p.agentToolUnsubscribers ?? [])]) {
+                try {
+                    off();
+                }
+                catch {
+                    /* shutting down */
+                }
+            }
+        }
+        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,
+                });
+            }
+            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 unregisterTools = [];
+        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);
+            },
+            // 包一层：插件反激活时自动注销它注册的全部 AI 工具，不留悬挂项。
+            registerAgentTool: (tool) => {
+                const off = this.registerAgentTool(info.id, tool);
+                unregisterTools.push(off);
+                return () => {
+                    const i = unregisterTools.indexOf(off);
+                    if (i >= 0)
+                        unregisterTools.splice(i, 1);
+                    off();
+                };
+            },
+            dir,
+            dataDir: this.dataDir,
+            cwd: this.cwd,
+            log: (...args) => console.log(`[plugin:${info.id}]`, ...args),
+        };
+        try {
+            const mod = (await import(pathToFileURL(join(dir, "index.mjs")).href));
+            const ret = await mod.default?.activate?.(host);
+            this.loaded.set(info.id, {
+                info: { ...info },
+                deactivate: typeof ret === "function" ? ret : undefined,
+                toolHandlers,
+                agentToolUnsubscribers: unregisterTools,
+            });
+            console.log(`[plugin:${info.id}] activated (v${info.version ?? "?"})`);
+        }
+        catch (err) {
+            this.loaded.set(info.id, {
+                info: { ...info, error: err.message },
+                toolHandlers,
+            });
+            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;
+}
+/**
+ * 把插件 AI 工具定义同步进一个「会话状对象」（SDK AgentSession 的结构子集：
+ * 内部 _customTools 数组 + _refreshToolRegistry()——refresh 会重读数组，且新
+ * 工具名自动加入活跃集）。新增/更新/移除三向 diff；对象不兼容（SDK 改名）返回
+ * null 由调用方静默降级。返回新的已注入名单。
+ *
+ * 纯函数、不 import SDK —— vitest 直接测（tests/unit/plugin-tools.test.ts）。
+ */
+export function syncPluginToolsIntoSession(session, defs, prevNames) {
+    if (!Array.isArray(session._customTools) || typeof session._refreshToolRegistry !== "function")
+        return null;
+    const byName = new Map(session._customTools.map((d) => [d.name, d]));
+    let changed = false;
+    for (const d of defs) {
+        if (byName.get(d.name) !== d) {
+            byName.set(d.name, d);
+            changed = true;
+        }
+    }
+    for (const name of prevNames) {
+        if (!defs.some((d) => d.name === name) && byName.has(name)) {
+            byName.delete(name);
+            changed = true;
+        }
+    }
+    if (!changed)
+        return new Set(defs.map((d) => d.name));
+    session._customTools = [...byName.values()];
+    session._refreshToolRegistry();
+    return new Set(defs.map((d) => d.name));
+}

package/dist/server/protocol-version.js

@@ -8,4 +8,4 @@
  * its own copy in web/src/protocol-version.ts; scripts/check-protocol-sync.mjs
  * verifies the two never drift.
  */
-export const PROTOCOL_VERSION = 5;
+export const PROTOCOL_VERSION = 7;

package/dist/server/settings-service.js

@@ -100,16 +100,20 @@ export class SettingsService {
                 promptMode: this.settings.promptMode,
                 customSystemPrompt: this.settings.customSystemPrompt,
                 terminalToolsEnabled: this.settings.terminalToolsEnabled,
+                terminalBash: this.settings.terminalBash,
+                terminalBashIdleMs: this.settings.terminalBashIdleMs,
                 visionBridgeEnabled: this.settings.visionBridgeEnabled,
                 visionBridgeModel: this.settings.visionBridgeModel,
                 visionBridgePromptMode: this.settings.visionBridgePromptMode,
                 visionBridgePrompt: this.settings.visionBridgePrompt,
                 reviewPrompt: this.settings.reviewPrompt,
                 reviewDisabledSkills: [...this.settings.reviewDisabledSkills],
+                disabledPlugins: [...(this.settings.disabledPlugins ?? [])],
                 // The built-in prompts, so the replace-mode editors can prefill the
                 // text they would otherwise replace (empty until the resource-loader
                 // has run once for the system prompt).
                 defaultSystemPrompt: this.host.effectiveDefaultSystemPrompt(),
+                effectiveSystemPrompt: this.host.effectiveSystemPrompt(),
                 visionBridgeDefaultPrompt: SYSTEM_PROMPT,
                 visionModels: this.collectVisionModels(),
                 disabledSkills: [...this.settings.disabledSkills],
@@ -153,9 +157,19 @@ export class SettingsService {
         if (partial.disabledExtensions !== undefined) {
             this.settings.disabledExtensions = partial.disabledExtensions;
         }
+        // 插件开关是纯 UI 隐藏（不进 needsReload——运行时无需重载）。
+        if (partial.disabledPlugins !== undefined) {
+            this.settings.disabledPlugins = partial.disabledPlugins;
+        }
         if (partial.terminalToolsEnabled !== undefined) {
             this.settings.terminalToolsEnabled = partial.terminalToolsEnabled;
         }
+        if (partial.terminalBash !== undefined) {
+            this.settings.terminalBash = partial.terminalBash;
+        }
+        if (partial.terminalBashIdleMs !== undefined) {
+            this.settings.terminalBashIdleMs = Math.max(0, Math.floor(partial.terminalBashIdleMs) || 0);
+        }
         if (partial.visionBridgeEnabled !== undefined) {
             this.settings.visionBridgeEnabled = partial.visionBridgeEnabled;
         }
@@ -193,6 +207,8 @@ export class SettingsService {
             disabledSkills: [...this.settings.disabledSkills],
             disabledExtensions: [...this.settings.disabledExtensions],
             terminalToolsEnabled: this.settings.terminalToolsEnabled,
+            terminalBash: this.settings.terminalBash,
+            terminalBashIdleMs: this.settings.terminalBashIdleMs,
             reviewPrompt: this.settings.reviewPrompt,
             reviewDisabledSkills: [...this.settings.reviewDisabledSkills],
         };
@@ -218,6 +234,9 @@ export class SettingsService {
             disabledExtensions: [...p.disabledExtensions],
             // 旧版持久化的预设可能没有该字段——保留当前值。
             terminalToolsEnabled: p.terminalToolsEnabled ?? this.settings.terminalToolsEnabled,
+            // 终端接管偏好随预设走；旧预设缺字段时保留当前值。
+            terminalBash: p.terminalBash ?? this.settings.terminalBash,
+            terminalBashIdleMs: p.terminalBashIdleMs ?? this.settings.terminalBashIdleMs,
             reviewPrompt: p.reviewPrompt ?? this.settings.reviewPrompt,
             reviewDisabledSkills: [
                 ...(p.reviewDisabledSkills ?? this.settings.reviewDisabledSkills),