dsh-plugin-tool-management 0.17.0 → 0.18.0

package/lib/mcp/tool-visibility.js

@@ -0,0 +1,388 @@
+// 工具停用的那一层边界：停用表（TTL 缓存）、「已知工具」侧车、以及把停用名单装到每个
+// agent scope 上的可见性半边（restrict）+ 执行侧要用的开关写入口。
+//
+// 正文从 mcp/manager.ts 的 createMcpManager 闭包里整段搬来，一字未改（缩进本来就同层；
+// 改的只有闭包作用域的名字走 deps —— moved-verify 按这两类容差机检）：
+// ensurePaths / readJsonFile / writeJsonFile / withWriteLock / message / tools /
+// normalizeKnownTools，以及侧车的三件常量 SIDECAR_TTL_MS / MCP_DISABLED_TOOLS_FILE /
+// MCP_KNOWN_TOOLS_FILE 与落点函数 mcpSidecar。常量按**原名**传进来，是为了让搬来的那些行
+// 不必改名 —— 这一段读起来像「读一次侧车、 TTL 内不再读盘」，靠的就是那几个熟悉的名字。
+// deps 形参仍叫 deps：块里那五处 `deps.carrierHiddenTools` / `deps.pluginHiddenTools` 是
+// 原样文本，换名就要改行。
+//
+// 为什么这一簇必须整体搬：七个可见性状态量（disabledToolsCache / knownMcpToolsCache /
+// restrictTimer / appliedNamesKey / desiredNames / agentRestrictions / appliedByAgent /
+// seenAgents / epoch）里，只有 disabledToolsCache 被块外的 ops 段直接改写（改名、删台、
+// 整表回写三处 + 出口读两处），所以它由本模块交回两个句柄：setDisabledToolsCache（按原
+// 语义刷新 `{at, value}` 那份缓存）与 disabledToolsSnapshot（同步读，无 I/O —— 工具门禁在
+// 热路径上）。其余名字块外零引用，跟着走就行。
+import { MCP_TOOL_PREFIX } from '../host-names.js';
+import { clearRuntimeNote, noteRuntime } from '../compat/runtime-notes.js';
+export function createToolVisibility(deps) {
+    // ---------- per-tool enable/disable (execution + visibility boundary) ----------
+    // dsh-mcp-client has no per-tool config, but the DSH tool runtime exposes
+    // two official seams: `tools.restrict({ deny })` removes a global tool from
+    // every scope's model-visible schema list, and `tools.guard` denies the call
+    // before the body runs. Disabled tools therefore become invisible AND
+    // uncallable — no patch rewrite, no DSH restart.
+    let disabledToolsCache = null;
+    async function readDisabledTools(force = false) {
+        if (disabledToolsCache && !force && Date.now() - disabledToolsCache.at < deps.SIDECAR_TTL_MS)
+            return disabledToolsCache.value;
+        const p = await deps.ensurePaths();
+        const raw = await deps.readJsonFile(deps.mcpSidecar(deps.MCP_DISABLED_TOOLS_FILE));
+        const out = {};
+        if (raw && typeof raw === 'object') {
+            for (const serverName of Object.keys(raw)) {
+                const list = raw[serverName];
+                if (Array.isArray(list)) {
+                    // `*` 必须原样保留：它是「整台服务器停用」的通配（场景档案未勾选的服务器写的就是它），
+                    // 被这里过滤掉的话 guard / restrict / 快照三条链路一起失效——整台停用变成空转。
+                    const names = list.map((name) => String(name)).filter((name) => name === '*' || /^[A-Za-z0-9_-]{1,128}$/.test(name));
+                    if (names.length)
+                        out[serverName] = names;
+                }
+            }
+        }
+        disabledToolsCache = { at: Date.now(), value: out };
+        return out;
+    }
+    /** Fully-qualified model-facing names (`mcp__<serverName>__<tool>`) of every disabled tool. */
+    function disabledToolNames(map) {
+        const out = [];
+        for (const serverName of Object.keys(map)) {
+            for (const tool of map[serverName])
+                out.push(MCP_TOOL_PREFIX + serverName + '__' + tool);
+        }
+        return out;
+    }
+    // ---------- 「已知工具」侧车（v0.8.1）-----------------------------------
+    // MCP 工具名只在服务器**运行**时可见（tools.schemas() 里才有）。未运行的服务器在
+    // 场景档案里既显示 0 工具、工具明细也空空如也 —— 用户没法给未运行服务器挑工具。
+    // 每次枚举到 live 工具时按 serverName 记一份「最后见过的工具名」，未运行时用它兜底：
+    // 场景档案能列出/勾选，进入场景后按实际注册的工具生效（restrict 会过滤掉不存在的名字）。
+    let knownMcpToolsCache = null;
+    async function readKnownMcpTools(force = false) {
+        if (knownMcpToolsCache && !force && Date.now() - knownMcpToolsCache.at < deps.SIDECAR_TTL_MS)
+            return knownMcpToolsCache.value;
+        const p = await deps.ensurePaths();
+        const raw = await deps.readJsonFile(deps.mcpSidecar(deps.MCP_KNOWN_TOOLS_FILE));
+        const out = {};
+        if (raw && typeof raw === 'object') {
+            for (const serverName of Object.keys(raw)) {
+                const list = deps.normalizeKnownTools(raw[serverName]);
+                if (list.length)
+                    out[serverName] = list;
+            }
+        }
+        knownMcpToolsCache = { at: Date.now(), value: out };
+        return out;
+    }
+    async function writeKnownMcpTools(value) {
+        const p = await deps.ensurePaths();
+        await deps.writeJsonFile(deps.mcpSidecar(deps.MCP_KNOWN_TOOLS_FILE), value);
+        knownMcpToolsCache = { at: Date.now(), value: value };
+    }
+    /**
+     * 「已知工具」侧车的**读-改-写**，整段在写锁内。
+     *
+     * 为什么不能「先 readKnownMcpTools() 再 writeKnownMcpTools()」（2026-09-30 审查 P2-15）：
+     * 这个侧车有两个并发写者 —— 列表轮询（`mcpmListView`，每次发现新工具就回写）与
+     * 临时启动（`mcpmTools` 等到工具注册后回写）。两步之间是队外窗口，两个写者各读到同一份
+     * 旧表、各并进自己那一台服务器的工具，后写的把先写的整份覆盖掉 —— 先那台的"曾经见过"
+     * 记录消失，未运行时场景档案里又变成 0 工具。
+     *
+     * `mutate` 收到的是**锁内刚读出来**的表（`force` 绕 TTL，否则拿到的还是锁外那份缓存）；
+     * 返回 `true` 表示有变化、需要落盘。
+     * 注意：`withWriteLock` **不可重入** —— 调用方不得已经持有写锁。
+     */
+    async function mutateKnownMcpTools(mutate) {
+        return deps.withWriteLock(async () => {
+            const known = await readKnownMcpTools(true);
+            if (!mutate(known))
+                return;
+            await writeKnownMcpTools(known);
+        });
+    }
+    /**
+     * 把「这次 live 见到的工具」并进一份已知工具表；返回是否有变化。
+     *
+     * 抽出来是为了让"要不要写盘"的判断与"锁内真正合并"用**同一个**函数：调用方先在锁外
+     * 对本地缓存跑一遍拿到 `changed`（决定要不要进锁），进锁后再对新鲜表跑一遍（那次的结果
+     * 才决定落盘）—— 两边口径不一致的话，要么白写要么漏写。
+     */
+    function mergeLiveToolsInto(known, live) {
+        let changed = false;
+        for (const [server, list] of Object.entries(live)) {
+            const prev = known[server] || [];
+            const byName = new Map(prev.map((t) => [t.name, t]));
+            for (const tool of list) {
+                const old = byName.get(tool.name);
+                if (!old) {
+                    byName.set(tool.name, tool);
+                    changed = true;
+                    continue;
+                }
+                if (tool.description && old.description !== tool.description) {
+                    byName.set(tool.name, { ...old, description: tool.description });
+                    changed = true;
+                }
+            }
+            const next = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+            if (next.length !== prev.length)
+                changed = true;
+            known[server] = next;
+        }
+        return changed;
+    }
+    async function mcpmToolEnabled(args) {
+        const serverName = String((args && args.serverName) || '').trim();
+        const tool = String((args && args.tool) || '').trim();
+        if (!/^[A-Za-z0-9_-]{1,32}$/.test(serverName))
+            return { ok: false, error: 'serverName 不合法' };
+        if (!/^[A-Za-z0-9_-]{1,128}$/.test(tool))
+            return { ok: false, error: 'tool 名称不合法' };
+        const enabled = (args && args.enabled) !== false;
+        const p = await deps.ensurePaths();
+        return deps.withWriteLock(async () => {
+            // Force re-read so an externally edited disabled-tools file is merged, not clobbered.
+            const map = Object.assign({}, await readDisabledTools(true));
+            const disabled = new Set(map[serverName] || []);
+            if (enabled)
+                disabled.delete(tool);
+            else
+                disabled.add(tool);
+            if (disabled.size)
+                map[serverName] = [...disabled].sort();
+            else
+                delete map[serverName];
+            try {
+                await deps.writeJsonFile(deps.mcpSidecar(deps.MCP_DISABLED_TOOLS_FILE), map);
+            }
+            catch (e) {
+                return { ok: false, error: '保存失败: ' + deps.message(e) };
+            }
+            disabledToolsCache = { at: Date.now(), value: map };
+            await applyToolRestrictions();
+            return { ok: true, serverName, disabled: map[serverName] || [] };
+        });
+    }
+    // Visibility seam: keep one active restriction per **agent scope**, refreshed whenever
+    // the tool set / the disabled set / this agent's carrier set changes. Three facts decide
+    // this design（都读过官方源码 dsh-tools 0.1.5-rc.2）：
+    //   · `restrict()` **要求 scoped context** —— 插件级 ctx 调用必抛 "requires a scoped
+    //     context"，这正是「停用工具从模型可见 schema 消失」这半边此前从未生效的原因（V1）；
+    //   · 每次 layer 变化（restriction 就是一次 layer effect）官方都会 emit `tools/change`
+    //     （`layers = new ScopedLayers(…, () => this.ctx.emit("tools/change"))`），而重放正挂在
+    //     `tools/change` 上 —— 名单没变还重放就是自激；
+    //   · 表要取自**不受限**的插件级视图：在 agent scope 里取 `schemas()`，第一次限制生效后
+    //     表里就没有被停用的工具了，第二次重放会把它从 deny 名单里筛掉 —— 停用静默复活。
+    // （2026-09-23：名单有三处来源，其中 `carrierHiddenTools` 逐 agent 不同，所以从"一份名单给
+    //  所有 agent"改成逐 agent 各装一层 —— 见下面 restrictAgent / appliedByAgent 的注释。）
+    let restrictTimer = null;
+    /** 已应用名单的键；相同即返回（防自激，也让每次 tools/change 变成一次廉价判等）。 */
+    let appliedNamesKey = null;
+    /** 当前期望的**全局** deny 名单（agent 晚到 / 重放时用它，再叠加该 agent 自己那份）。 */
+    let desiredNames = [];
+    /** agent → 撤掉这层限制的 disposer。 */
+    const agentRestrictions = new Map();
+    /** agent → 已应用的**合并后**名单键（名单现在与 agent 有关，不能再只记一份全局的）。 */
+    const appliedByAgent = new Map();
+    /** 见过的 agent（重放时逐个重新应用；disposed 时移除）。 */
+    const seenAgents = new Set();
+    /**
+     * 重放代数：`carrierHiddenTools` 是异步的，算名单期间可能又来了新的一轮重放（或 agent
+     * 已经下线）。每次重放自增，回来时代数对不上就作废 —— 否则会用旧名单盖掉新的那一层。
+     */
+    let epoch = 0;
+    function scopedToolsOf(agent) {
+        const scoped = agent && agent.ctx && agent.ctx.tools;
+        return scoped && typeof scoped === 'object' ? scoped : undefined;
+    }
+    /** 撤掉某个 agent 上的限制（名单变了要重装：`restrict` 是叠加层，装新的不撤旧的会越叠越多）。 */
+    function liftRestriction(agent) {
+        const release = agentRestrictions.get(agent);
+        agentRestrictions.delete(agent);
+        appliedByAgent.delete(agent);
+        if (release) {
+            try {
+                release();
+            }
+            catch (e) { /* ignore */ }
+        }
+    }
+    /** 把该 agent 该背的名单装到它 scope 上（全局那份 ∪ 它自己那份；空名单 = 不碰它）。 */
+    async function restrictAgent(agent) {
+        const mine = epoch;
+        let extra = [];
+        if (deps.carrierHiddenTools) {
+            // 判据失败一律当"没有额外要藏的"：藏错了模型就少一条路，留着只是多花 token。
+            try {
+                extra = await deps.carrierHiddenTools(agent);
+            }
+            catch (e) {
+                extra = [];
+            }
+        }
+        if (mine !== epoch)
+            return;
+        if (!seenAgents.has(agent))
+            return;
+        const names = [...new Set([...desiredNames, ...extra])];
+        const scoped = scopedToolsOf(agent);
+        if (!scoped || typeof scoped.restrict !== 'function') {
+            if (names.length === 0)
+                return;
+            // agent scope 上没有 tools 面（或它没有 restrict）：这半边做不成，如实说 ——
+            // 静默跳过会让人以为"停用工具从模型工具表里消失"已经生效。
+            noteRuntime({
+                id: 'mcp-tool-visibility',
+                label: '停用工具的可见性',
+                kind: 'write',
+                fallback: 'inform-only',
+                detail: 'agent scope 上没有可用的 tools.restrict（官方接口变了或该 scope 未暴露 tools）：停用的 MCP 工具与兼容页关掉的本插件工具仍会出现在模型可见的工具表里，执行侧拦截仍然生效。',
+                detailKey: 'mcp-tool-visibility.no-restrict',
+            });
+            return;
+        }
+        const key = names.slice().sort().join('\u0000');
+        if (appliedByAgent.get(agent) === key)
+            return;
+        liftRestriction(agent);
+        if (names.length === 0) {
+            clearRuntimeNote('mcp-tool-visibility');
+            return;
+        }
+        try {
+            const dispose = scoped.restrict({ deny: names });
+            agentRestrictions.set(agent, typeof dispose === 'function' ? dispose : () => { });
+            appliedByAgent.set(agent, key);
+            clearRuntimeNote('mcp-tool-visibility');
+        }
+        catch (e) {
+            // 这个名字在这个 scope 里认不出 / scope 已经收了：可见性半边没生效。执行侧的 guard
+            // 仍然拦住调用，所以功能不缺 —— 但必须如实上报，不能假装成功（此前正是静默吞掉）。
+            noteRuntime({
+                id: 'mcp-tool-visibility',
+                label: '停用工具的可见性',
+                kind: 'write',
+                fallback: 'inform-only',
+                detail: '有工具没能从模型可见的工具表里摘掉（' + deps.message(e) + '）：执行侧拦截仍然生效，模型仍能看到该工具的名字。',
+                detailKey: 'mcp-tool-visibility.partial',
+                params: { reason: deps.message(e) },
+            });
+        }
+    }
+    /** agent 上线（`agent/created` 或启动期的 agent 列表）：登记并立刻应用当前名单。 */
+    function attachAgent(agent) {
+        if (!agent || (typeof agent !== 'object' && typeof agent !== 'function'))
+            return;
+        seenAgents.add(agent);
+        void restrictAgent(agent).catch(() => { });
+    }
+    /** agent 下线（`agent/disposed`）：先撤限制再销登记。 */
+    function detachAgent(agent) {
+        seenAgents.delete(agent);
+        liftRestriction(agent);
+    }
+    async function applyToolRestrictions() {
+        // 全局 tools 面上没有 restrict → 可见性半边整条做不成，如实上报（2026-09-30 审查 P2-8）。
+        // 此前这里是**裸 return**：停用工具仍留在模型可见的工具表里，而兼容页因为没有上报仍报
+        // 一行"ok"，用户看到的是"停用了但工具还在"。与 `restrictAgent` 里那条 noteRuntime 同文案、
+        // 同 id（noteRuntime 按 id 覆盖，两处不会互相刷屏）。
+        if (typeof deps.tools.restrict !== 'function') {
+            noteRuntime({
+                id: 'mcp-tool-visibility',
+                label: '停用工具的可见性',
+                kind: 'write',
+                fallback: 'inform-only',
+                detail: '全局 tools 服务上没有可用的 tools.restrict（官方接口变了）：停用的 MCP 工具与兼容页关掉的本插件工具仍会出现在模型可见的工具表里，执行侧拦截仍然生效。',
+                detailKey: 'mcp-tool-visibility.no-restrict',
+            });
+            return;
+        }
+        // Force re-read: this runs on the tools/change path, which is rare, so a
+        // stale cache must not keep an externally edited deny list hidden.
+        const map = await readDisabledTools(true);
+        // 通配 `*`（整服务器停用）先展开成已注册的全名，再与精确名单合并。
+        const wanted = disabledToolNames(map);
+        let registered;
+        try {
+            registered = new Set((await deps.tools.schemas()).map((schema) => String(schema.name)));
+        }
+        catch (e) {
+            return;
+        }
+        for (const [serverName, list] of Object.entries(map)) {
+            if (list.indexOf('*') < 0)
+                continue;
+            const prefix = MCP_TOOL_PREFIX + serverName + '__';
+            for (const fullName of registered)
+                if (fullName.startsWith(prefix))
+                    wanted.push(fullName);
+        }
+        // 兼容页「模型工具表」关掉的本插件工具并进同一份名单（理由见 deps.pluginHiddenTools）。
+        // 交给上面那个 `registered` 过滤是**必要的**而不是保险：官方对认不出的名字直接抛错，
+        // 而关掉的工具里可能有一个这次根本没注册成功（注册失败会被子智能体页的黄条报出来）。
+        if (deps.pluginHiddenTools) {
+            try {
+                for (const name of deps.pluginHiddenTools())
+                    wanted.push(name);
+            }
+            catch (e) { /* 读设置失败 = 这次不摘它们 */ }
+        }
+        const names = [...new Set(wanted)].filter((name) => registered.has(name));
+        const key = names.join('\u0000');
+        // 有 `carrierHiddenTools` 时不拿全局键短路：那份名单与"官方工具此时挂没挂"有关，
+        // 而它变了不会改全局键（官方挂载/卸载本身就发 tools/change，正是靠这条通路追上）。
+        // 代价是每次 tools/change 都重算一遍 —— 逐 agent 的键判等会把绝大多数挡在装层之前，
+        // 事实读取也有 TTL 缓存；装层本身会再发一次 tools/change，那一轮键相同即收敛，不自激。
+        if (key === appliedNamesKey && deps.carrierHiddenTools === undefined)
+            return;
+        appliedNamesKey = key;
+        desiredNames = names;
+        // 每次重放先撤掉每个 agent 上的旧层：名单变短（重新启用某个工具）时，只有撤掉这层限制
+        // 它才会重新可见；名单变了（含逐 agent 那份）也必须重装而不是叠加。
+        epoch += 1;
+        for (const agent of [...agentRestrictions.keys()])
+            liftRestriction(agent);
+        for (const agent of seenAgents)
+            void restrictAgent(agent).catch(() => { });
+    }
+    function scheduleToolRestrictions() {
+        if (restrictTimer)
+            return;
+        restrictTimer = setTimeout(() => {
+            restrictTimer = null;
+            applyToolRestrictions().catch(() => { });
+        }, 300);
+    }
+    /** 卸载清理：清掉重排定时器、把挂在每个 agent scope 上的限制都撤掉（母文件 dispose 的那六行原样搬来）。 */
+    function disposeVisibility() {
+        if (restrictTimer) {
+            clearTimeout(restrictTimer);
+            restrictTimer = null;
+        }
+        // 插件卸载时把挂在每个 agent scope 上的限制都撤掉（否则那些 scope 会继续背着一层名单）。
+        epoch += 1;
+        for (const agent of [...agentRestrictions.keys()])
+            liftRestriction(agent);
+        appliedByAgent.clear();
+        seenAgents.clear();
+    }
+    return {
+        readDisabledTools,
+        readKnownMcpTools,
+        writeKnownMcpTools,
+        mutateKnownMcpTools,
+        mergeLiveToolsInto,
+        mcpmToolEnabled,
+        attachAgent,
+        detachAgent,
+        applyToolRestrictions,
+        scheduleToolRestrictions,
+        setDisabledToolsCache: (value) => { disabledToolsCache = { at: Date.now(), value }; },
+        disabledToolsSnapshot: () => (disabledToolsCache ? disabledToolsCache.value : {}),
+        disposeVisibility,
+    };
+}

package/lib/memories/archive-engine.js

@@ -58,6 +58,24 @@ export function createArchiveEngine(deps) {
         const byRoot = new Map(current.map((s) => [s.root, s.enabled]));
         return rows.filter((x) => byRoot.has(x.root) && byRoot.get(x.root) !== x.enabled);
     }
+    /**
+     * 快捷提示词段 → 应用（勾了的启用、未勾的停用），只写**状态需要变化**的那几条。
+     *
+     * 只在档案**定义了**这一段时被调用：未定义 = 这一域完全不碰（与 mcp/skills/subagents 的
+     * 「未定义 = 全关」不同，见 `SceneArchive.quickPrompts` 的注释）。
+     */
+    async function applyQuickPrompts(list) {
+        const [known, current] = await Promise.all([deps.knownQuickPrompts(), deps.quickPromptStates()]);
+        const switches = [];
+        for (const id of known) {
+            const want = list.indexOf(id) >= 0;
+            if (current[id] === want)
+                continue;
+            switches.push({ id, enabled: want });
+        }
+        if (switches.length)
+            await deps.applyQuickPromptSwitches(switches);
+    }
     /**
      * 还原到快照（退出模式与失败回滚共用同一条路径）：
      * MCP 停用表**按快照原文整体回写**——模式自己写进去的键（未勾服务器的 ['*']）必须随之消失，
@@ -67,6 +85,20 @@ export function createArchiveEngine(deps) {
      * 上层两行（服务器级 / 来源级）按**全量**快照还原 —— 只回写与现状不同的行，见
      * mcpServerRowsToRestore / skillSourceRowsToRestore。
      */
+    /**
+     * 两份名单是不是同一批名字（顺序无关）。
+     *
+     * 现在只有工具表那一档用它：档案绑的方案与当前现状是同一份关停名单时，进入这一步其实
+     * 什么都没改 —— 回执要不要提「工具表切到方案 X」就取决于这一句。
+     */
+    function sameNameList(a, b) {
+        if (!a || !b)
+            return false;
+        if (a.length !== b.length)
+            return false;
+        const set = new Set(a);
+        return b.every((x) => set.has(x));
+    }
     async function restoreSnapshot(snapshot) {
         // 顺序与进入时**相反**：先恢复服务器级 / 来源级，再恢复工具级 / 技能级 ——
         // 来源还关着的时候写技能级策略会被吞掉（`skills/core.js` 的 sourceEnabled 判定）。
@@ -108,11 +140,48 @@ export function createArchiveEngine(deps) {
                 await deps.applySubagentSwitches(personasOn.map((n) => ({ name: n, enabled: true })));
             }
         }
+        // 快捷提示词（0.18.0）：按快照的全量映射还原，但**只回写与现状不同的那几条** ——
+        // 与 mcpServerRowsToRestore 同一条理由：没变过的行不该白写一遍侧车。读不到现状就退回全量
+        // 回写（宁可多写几行，不可少还原）。老快照没有这一栏 → 一个字都不动（进场景时也没碰过）。
+        // 场景期间被删掉的条目由实现侧静默跳过：没有可还原的状态，硬写会把"退出场景"卡成报错。
+        const quickStates = snapshot.quickPromptsAll;
+        if (quickStates && typeof quickStates === 'object') {
+            const rows = Object.entries(quickStates);
+            if (rows.length) {
+                let current = null;
+                try {
+                    current = await deps.quickPromptStates();
+                }
+                catch {
+                    current = null;
+                }
+                const switches = rows
+                    .filter(([id, on]) => current === null || current[id] !== (on === true))
+                    .map(([id, on]) => ({ id, enabled: on === true }));
+                if (switches.length)
+                    await deps.applyQuickPromptSwitches(switches);
+            }
+        }
         // 模型工具表（C1）：按快照原值整体回写。老快照没有这一栏 → 一个字都不动（与进场景前一致）。
+        // 先与现状比一次：绑的方案与进场景前本来就是同一份名单时，这一步什么都没改 —— 既不该白跑
+        // 一遍"落盘 → 重排可见性 → 两个目录重算"，回执更不该跟着说「工具表按快照还原」（用户问
+        // "刚才改了什么"时凭空多一项）。读不到现状就照旧回写（宁可多写一遍，不可少还原）。
+        let toolTableRestored = false;
         if (snapshot.toolTableHidden) {
-            await deps.applyToolTableHidden(snapshot.toolTableHidden);
+            let current = null;
+            try {
+                current = await deps.currentToolTableHidden();
+            }
+            catch {
+                current = null;
+            }
+            if (current === null || !sameNameList(current, snapshot.toolTableHidden)) {
+                await deps.applyToolTableHidden(snapshot.toolTableHidden);
+                toolTableRestored = true;
+            }
         }
         deps.audit?.('scene-restore', '');
+        return { toolTable: toolTableRestored };
     }
     /**
      * 失败回滚：运行时还原 + 切片写回；每步失败都记下来，绝不谎报「已回滚」。
@@ -179,6 +248,10 @@ export function createArchiveEngine(deps) {
             if (entries.length)
                 await deps.applyMcpNotes(entries);
         }
+        // 快捷提示词：段定义了才碰（未定义 = 保持现状）。快照里的原值**不动** ——
+        // 退出场景仍回到「进场景前」那批开关，而不是回到上一次档案的勾选。
+        if (archive && Array.isArray(archive.quickPrompts))
+            await applyQuickPrompts(archive.quickPrompts);
         // 工具表方案（C1）：改档案 = 立刻生效，这一域也得跟上。快照里的原值**不动** ——
         // 退出场景仍然回到「进场景前」那份名单，而不是回到上一次档案的方案。
         const reapplyPreset = (archive && archive.toolTablePreset) || '';
@@ -241,6 +314,7 @@ export function createArchiveEngine(deps) {
                         mcpServers: Object.keys(snap.mcp || {}).length,
                         skills: Object.keys(snap.skills || {}).length,
                         subagents: personaStates ? Object.keys(personaStates).length : (snap.subagents ?? []).length + (snap.subagentsOn ?? []).length,
+                        quickPrompts: Object.keys(snap.quickPromptsAll || {}).length,
                         mcpNotes: (snap.mcpNotes ?? []).length,
                     },
                     // 记忆启用集**不随退出恢复**（设计 §2.2）：退出后仍是这个场景，界面别把它写成"会还原"。
@@ -285,6 +359,27 @@ export function createArchiveEngine(deps) {
             catch (e) {
                 return { ok: false, error: `读取人设开关状态失败：${msg(e)}` };
             }
+            // 快捷提示词：只有档案**定义了**这一段才报（未定义 = 这一域进都不进，也就没有"会改什么"）。
+            // 与进入时逐字同口径：勾了的启用、未勾的停用，且只数**现状 ≠ 目标**的那几条。
+            let quickPrompts = null;
+            if (archive && Array.isArray(archive.quickPrompts)) {
+                try {
+                    const list = archive.quickPrompts;
+                    const [known, current] = await Promise.all([deps.knownQuickPrompts(), deps.quickPromptStates()]);
+                    const on = [];
+                    const off = [];
+                    for (const id of [...known].sort()) {
+                        const want = list.indexOf(id) >= 0;
+                        if (current[id] === want)
+                            continue;
+                        (want ? on : off).push(id);
+                    }
+                    quickPrompts = { on: clip(on), off: clip(off) };
+                }
+                catch (e) {
+                    return { ok: false, error: `读取快捷提示词开关状态失败：${msg(e)}` };
+                }
+            }
             // 服务器级：计划里已只含「需要变化」的行，按目标状态分两个方向。
             const serversOn = [];
             const serversOff = [];
@@ -406,6 +501,7 @@ export function createArchiveEngine(deps) {
                     sourcesOn: clip(sourcesOn), sourcesOff: clip(sourcesOff),
                 },
                 subagents: { on: clip(personas.on), off: clip(personas.off) },
+                quickPrompts,
                 toolPreset,
                 stale: clip(stale),
                 truncated,
@@ -465,6 +561,14 @@ export function createArchiveEngine(deps) {
                 if (hadKeys && archive.subagents.length === 0)
                     delete archive.subagents;
             }
+            if (archive.quickPrompts) {
+                // 已删掉 / 改名的条目从勾选集里丢掉并报出来（与 subagents 段同一口径）。
+                // 与那三段**不同**的一点：清成空表也**不删这一栏** —— 空表说的是"进入后全部停用"，
+                // 删掉就变成"这一域不碰"，两句是相反的意思（见 SceneArchive.quickPrompts）。
+                const known = await deps.knownQuickPrompts();
+                stale.push(...archive.quickPrompts.filter((id) => !known.has(id)).map((id) => 'quickPrompts/' + id));
+                archive.quickPrompts = archive.quickPrompts.filter((id) => known.has(id));
+            }
             if (archive.toolTablePreset) {
                 // 方案名查不到（被删了 / 档案是从别的机器带来的）→ 丢弃这一栏并报告：
                 // 绑一个不存在的方案不该在进场景时变成一句"方案不存在"的硬失败。
@@ -488,6 +592,13 @@ export function createArchiveEngine(deps) {
                 if (prev && typeof prev.toolTablePreset === 'string' && prev.toolTablePreset)
                     archive.toolTablePreset = prev.toolTablePreset;
             }
+            // 快捷提示词同理：勾选入口在「修改场景」表单里，档案编辑器不带这一栏 —— **不带 ≠ 解绑**，
+            // 保留现值（解绑走 rules-update-scene 的空值；这里带上来的值仍走上面的 stale 校验）。
+            if (archive.quickPrompts === undefined) {
+                const prev = slice.archives[scene];
+                if (prev && Array.isArray(prev.quickPrompts))
+                    archive.quickPrompts = prev.quickPrompts.slice();
+            }
             // 逐场景增量写（审查 P2-3）：这里只该动 `archives[scene]` 这一条，而 `slice` 是队外
             // 读的 —— 整片回写会把窗口期里别人保存的**别的场景**档案一起抹掉。
             const archiveNext = Object.keys(archive).length === 0 ? null : archive;
@@ -532,9 +643,10 @@ export function createArchiveEngine(deps) {
                 return { ok: true, mode: current, applied: null, stale: [] };
             // ① 退出当前模式（切换 = 先退后进）：先恢复运行时，再落盘自由模式。
             //    恢复失败即中止且**保持原 mode 不变**——宁可留在「可再退出一次」的状态，也不吞错。
+            let restoredToolTable = false;
             if (current.scene && current.snapshot) {
                 try {
-                    await restoreSnapshot(current.snapshot);
+                    restoredToolTable = (await restoreSnapshot(current.snapshot)).toolTable;
                 }
                 catch (e) {
                     return { ok: false, error: `退出模式「${current.scene}」失败，已保持原模式（运行时可能部分残留）：${msg(e)}` };
@@ -554,7 +666,7 @@ export function createArchiveEngine(deps) {
                 current = exited.mode;
             }
             if (!target)
-                return { ok: true, mode: current, applied: null, stale: [] };
+                return { ok: true, mode: current, applied: null, stale: [], restored: { toolTable: restoredToolTable } };
             // ② 进入目标模式：校验 → 算计划 → 拍快照 → 先落盘 mode（中途失败也留可退快照）→ 应用 → 记忆收窄。
             //    三个域（MCP / 技能 / 人设）都按「与档案勾选集完全一致」应用，未定义 = 全关；
             //    备注段只在定义时覆盖。所以这里没有「纯记忆场景不用动运行时」这条分支 —— 恒拍快照。
@@ -660,11 +772,28 @@ export function createArchiveEngine(deps) {
                     return { ok: false, error: `场景绑定的工具表方案「${toolTablePreset}」已不存在，未进入场景（先在场景档案里换一份或取消绑定）` };
                 }
             }
+            // 这一档"报不报"看的是**名单有没有变**：绑的方案与现状是同一份关停名单时，进入这一步
+            // 什么都没改，回执再说「工具表切到方案 X」就是给"刚才改了什么"凭空添一项。
+            const toolTableSwitched = !!toolTableTarget && !sameNameList(toolTableBefore, toolTableTarget);
+            // 快捷提示词（0.18.0）：档案**定义了**这一段才碰这一域（未定义 = 保持现状，与
+            // mcp/skills/subagents 的「未定义 = 全关」不同 —— 用户 2026-10-01 裁定这一栏的默认是
+            // 「当前启用的快捷提示词」）。读现状同样放在改任何东西之前：读失败就等于什么都没动。
+            const quickList = archive && Array.isArray(archive.quickPrompts) ? archive.quickPrompts : null;
+            let quickStates = null;
+            if (quickList) {
+                try {
+                    const [known, current] = await Promise.all([deps.knownQuickPrompts(), deps.quickPromptStates()]);
+                    quickStates = Object.fromEntries([...known].map((id) => [id, current[id] === true]));
+                }
+                catch (e) {
+                    return { ok: false, error: `读取快捷提示词开关状态失败（未改动任何东西）：${msg(e)}` };
+                }
+            }
             // 快照**恒拍**：三个域都按「与勾选集完全一致」应用（未定义 = 全关），所以任何场景
             // 进入都可能改动运行时（哪怕只是停掉几台服务器 / 几个技能），退出都得能精确还原。
             // 上层两行传**现状全量**（上面的 mcpServerStates / skillSources 就是进场景前的值），
             // 不是计划里那几行 —— 退出按「现状 ≠ 记录值」回写（见 mcpServerRowsToRestore）。
-            const snapshot = snapshotRuntime(await deps.currentMcpRaw(), await deps.currentSkills(), mcpServerStates.map((s) => ({ id: s.id, level: s.level, disabled: s.disabled })), skillSources.map((s) => ({ root: s.root, enabled: s.enabled })), personaRestore, personaRestoreOn, noteBefore, personaStates, toolTableBefore);
+            const snapshot = snapshotRuntime(await deps.currentMcpRaw(), await deps.currentSkills(), mcpServerStates.map((s) => ({ id: s.id, level: s.level, disabled: s.disabled })), skillSources.map((s) => ({ root: s.root, enabled: s.enabled })), personaRestore, personaRestoreOn, noteBefore, personaStates, toolTableBefore, quickStates);
             const entered = { ...slice, mode: { scene: target, snapshot }, active: [target] };
             try {
                 // 先落 **mode**（留可退快照）；active 留到最后一步再落 —— 中途失败要能按原样退回，
@@ -705,6 +834,10 @@ export function createArchiveEngine(deps) {
                 //     所以它是"进入场景"这一动作里唯一直接改每请求内容的域）。
                 if (toolTableTarget)
                     await deps.applyToolTableHidden(toolTableTarget);
+                // ⑥ 快捷提示词：段定义了才动（勾了的启用、未勾的停用）。它不进上下文、不进注入，
+                //    改的只是"这条还在不在对话框的 `/` 菜单里"。
+                if (quickList)
+                    await applyQuickPrompts(quickList);
             }
             catch (e) {
                 return await rollback(slice, snapshot, '应用档案', e);
@@ -723,12 +856,16 @@ export function createArchiveEngine(deps) {
                 mode: entered.mode,
                 // 三个域都是「按勾选集全量应用」（未定义 = 全关），所以都算已应用；
                 // 备注段未定义 = 不覆盖任何备注，如实报它是否定义。
-                applied: { mcp: true, skills: true, subagents: true, mcpNotes: !!(archive && archive.mcpNotes), toolTable: !!toolTableTarget },
+                applied: { mcp: true, skills: true, subagents: true, mcpNotes: !!(archive && archive.mcpNotes), toolTable: !!toolTableTarget, quickPrompts: !!quickList },
                 // 上层实际切换了几个（0 = 本来就已经是目标状态，界面不必提示"已停用 N 台"）。
                 switched: {
                     mcpServers: mcpPlan.serverSwitches.length,
                     skillSources: skillsPlan.sourceSwitches.length,
+                    // 工具表：这次真的换上去的关停条数（0 = 本来就是那份，或压根没绑方案）。
+                    toolTableHidden: toolTableSwitched ? toolTableTarget.length : 0,
                 },
+                // 换上去的那份方案名，供回执点名（与上面同一个判据：没换就回空串）。
+                toolTablePreset: toolTableSwitched ? toolTablePreset : '',
                 stale,
                 narrowedTo: [target],
             };