dsh-plugin-tool-management 0.11.0 → 0.12.0

package/lib/context-inject.js

@@ -71,6 +71,7 @@
 // 遥测同理（`noteToolUse` 自己吞异常）：它绝不能影响工具本身。
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SessionSeq } from '@deepseek-ai/dsh-session';
+import { clearRuntimeNote, noteRuntime } from './compat/runtime-notes.js';
 /**
  * 权威域顺序（界面勾选、注入消息先后都按它）。
  * 场景和记忆排第一：它是"当前模式"的框架，先给框架再给内容。
@@ -415,6 +416,38 @@ function kindOfMessage(message) {
     const source = message?.source;
     return source && typeof source.kind === 'string' ? source.kind : undefined;
 }
+// B4：关域拦截的**顺序自检**。官方那两条注入行与本插件同挂在这条瀑布上，拦截成立的剩余前提是
+// "本插件排在它们上游"（本插件用 `{ prepend: true }` 把自己钉在钩子表最前，所以真正还依赖的
+// 只剩一条：官方那两条仍用**默认 push** 方式注册）。这仍是非契约事实（见 pre-step 监听器里的
+// 注释）。官方哪天改成 prepend 抢到更前面，症状就是「关了域、模型还是收到内容」，且**完全没有
+// 报错**。这里做最轻的自检：关域生效期间连续 N 个真实 turn 一条都没剔到，就上报一次；
+// 剔到过就收掉那条上报。如实写清两种可能（顺序变了 / 官方这一轮本来没内容），
+// 不把它说成一定是事故。
+const SUPPRESSION_SUSPECT_TURNS = 5;
+function suppressionVerdict(active, dropped, counter) {
+    if (!active) {
+        counter.turns = 0;
+        counter.drops = 0;
+        clearRuntimeNote('official-suppression');
+        return;
+    }
+    counter.turns += 1;
+    counter.drops += dropped;
+    if (counter.drops > 0) {
+        counter.turns = 0;
+        clearRuntimeNote('official-suppression');
+        return;
+    }
+    if (counter.turns < SUPPRESSION_SUSPECT_TURNS)
+        return;
+    noteRuntime({
+        id: 'official-suppression',
+        label: '官方注入的关域拦截',
+        kind: 'read',
+        fallback: 'inform-only',
+        detail: `关掉的注入域已连续 ${counter.turns} 轮没有拦到任何官方消息（自检）：可能是瀑布注册顺序变了导致拦截失效，也可能是官方那两条注入行这几轮本来就没有内容。可到「注入实况」对照模型实际收到的内容。`,
+    });
+}
 /** 实况展示用的 kind 表：本插件的五条 + 官方两条。 */
 const LIVE_KINDS = new Map([
     ...PLUGIN_KINDS,
@@ -567,6 +600,18 @@ export function createContextInjector(deps) {
     const ctx = deps.ctx;
     if (!ctx || typeof ctx.on !== 'function')
         return { dispose: () => { }, live, noteToolUse };
+    /** B4 自检计数（每个注入器实例各自一份，随实例销毁而消失）。 */
+    const suppressionCounter = { turns: 0, drops: 0 };
+    // `{ prepend: true }` —— 位置**必须**钉在钩子表最前，理由见 `next()` 之后那段注释
+    // （关域拦截只在上游成立）。这里不靠"谁先注册"：cordis 的 Loader 是**并发**挂载条目的
+    // （`await Promise.allSettled(config.map((options) => this.create(options)))`，
+    // cordis-plugin-loader/lib/index.js），每个官方包 apply 的完成先后由模块导入与 IO 决定，
+    // 逐次启动都可能不同；本插件的条目又是补丁层 `insert` 推到条目列表**末尾**的
+    // （dsh-app-boot/lib/index.js：顶层 insert 走 `data.push(...insert)`）。
+    // 2026-09-20 实测到那次翻转：关掉技能 / 提示词域后，官方注入照旧进上下文。
+    // `prepend` 由 cordis `EventsService.register()` 实现（`hooks[options.prepend ? 'unshift' : 'push']`），
+    // 于是不论挂载先后，本插件都排在官方那两条**默认 push** 注册的注入行之前 ——
+    // 顺序从"竞态"变成"约定"。
     const stop = ctx.on('agent/pre-step', async (payload, next) => {
         // 令牌门禁在**最前面**：没验过令牌时这一轮整个不放行，`next()` 都不必跑（后面那些注入
         // 本来就是给模型看的，模型这一步根本不会被调用）。宿主据此把 turn 收成 `blocked`。
@@ -603,17 +648,31 @@ export function createContextInjector(deps) {
             // 边界说明：这不是改官方包、也不是改宿主机制 —— pre-step 的 decision 本来就是每个插件
             // 都能改的那条缝（官方自己就在这里追加消息），我们只把它剔出这一步的批次。代价是官方
             // 插件每一步都会重新渲染并尝试注入（它的历史读的是会话事件，读不到被拦下的那条），
-            // 模型侧不受影响。位置在本监听器 `next()` 之后：本插件在这条瀑布里位于官方之前
-            // （自己的消息总落在批次末尾，实测），所以官方这一步追加的消息在这里看得见。
+            // 模型侧不受影响。
+            // **为什么 `prepend` 是必需的**：官方那两条注入行都在 `await next()` **之后**才往
+            // `decision.messages` 里追加（dsh-tool-skill 末尾 `[...decision.messages, catalog]`；
+            // dsh-agent-instructions `toSpliced(lastClaimedIndex + 1, 0, desired)`），而瀑布的
+            // `next()` 只做"取钩子表的下一个"。所以只有排在他们**上游**的监听器，其 `next()`
+            // 返回时才看得见这些追加 —— 本插件的过滤在 `next()` 之后，位置必须在上游。
             const suppressedKinds = officialKindsToSuppress(settings);
             let messages = messagesOf(decision);
             if (suppressedKinds.size > 0) {
+                let dropped = 0;
                 const kept = messages.filter((message) => {
                     const kind = kindOfMessage(message);
-                    return kind === undefined || !suppressedKinds.has(kind);
+                    if (kind !== undefined && suppressedKinds.has(kind)) {
+                        dropped += 1;
+                        return false;
+                    }
+                    return true;
                 });
                 if (kept.length !== messages.length)
                     messages = kept;
+                // B4 自检：只有"这一步真的在拦"时才有意义（令牌门禁 reject、空 turn 早退都在上面）。
+                suppressionVerdict(true, dropped, suppressionCounter);
+            }
+            else {
+                suppressionVerdict(false, 0, suppressionCounter);
             }
             const facts = await deps.factsFor(agent);
             const sections = selectInjections(domains, settings, facts, agent);
@@ -692,13 +751,17 @@ export function createContextInjector(deps) {
             log('context injection failed: ' + String((error && error.message) || error));
             return decision;
         }
-    });
+    }, { prepend: true });
     return {
-        dispose: () => { try {
-            if (typeof stop === 'function')
-                stop();
-        }
-        catch { /* ignore */ } },
+        dispose: () => {
+            try {
+                if (typeof stop === 'function')
+                    stop();
+            }
+            catch { /* ignore */ }
+            // 注入通道没了，自检结论也失效（B4）——留着会让兼容页报一件不存在的事。
+            clearRuntimeNote('official-suppression');
+        },
         live,
         noteToolUse,
     };

package/lib/index.js

@@ -10,6 +10,7 @@
 //
 // Build: `tsc -p tsconfig.json` compiles this to lib/index.js (the shipped
 // artifact — same convention as DSH's own packages, which ship compiled JS).
+import { symbols } from '@deepseek-ai/cordis';
 import { defineTool as hostDefineTool } from '@deepseek-ai/dsh-tools';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
@@ -26,6 +27,8 @@ import { createSubagentCatalog } from './subagents/catalog.js';
 import { createSkillCatalog } from './skills/catalog.js';
 import { DEFAULT_INJECT_SETTINGS, createContextInjector, normalizeInjectSettings, subagentDepthOf, } from './context-inject.js';
 import { isApprovalNever } from './approval-policy.js';
+import { checkPatchWrite, takePatchGuardWarnings } from './compat/patch-dialect.js';
+import { clearRuntimeNote, noteRuntime } from './compat/runtime-notes.js';
 import { reachNoticeForAgent } from './compat/preset-reach.js';
 import { TOKEN_CODE_BAD, TOKEN_MSG, fenceRejection, secretOpRejection } from './http-fence.js';
 import { createMcpManager } from './mcp/manager.js';
@@ -85,9 +88,22 @@ function serializeTurns(turns, format) {
     }
     return turns.map((t) => (t.role === 'user' ? '## User\n' : '### Assistant\n') + t.text).join('\n\n');
 }
+/**
+ * `inject` 的服务名清单（单一来源）：既声明给宿主，也是「挂载心跳」与 doctor 核对的内容。
+ *
+ * 为什么值得单列：任何一个名字被官方改名，本插件**根本不会 apply** —— 实测（2026-09-20，本仓库
+ * cordis）cordis 对未解析的 inject 既不抛错、不打日志、不发 warning，只把该 Fiber 停在非活动态。
+ * 那种情形下探测表 / 上报通道 / 兼容页**全都不存在**（失败域里一个信号都没有），本插件两次
+ * "宿主起不来"的历史事故也属于这一类。心跳文件是事后唯一的线索：doctor 读它 + 这份名单，
+ * 才能说清"插件这一轮没挂上，去核对这几个服务名"。
+ */
+export const INJECT_SERVICES = [
+    'timer', 'fs', 'settings', 'sandboxPolicy', 'webServer', 'tools', 'skills', 'sessions',
+    'agents', 'workspaceRegistry', 'sessionProjectionCache', 'sessionPersistence',
+];
 export default {
     name: 'dsh-plugin-tool-management-host',
-    inject: ['timer', 'fs', 'settings', 'sandboxPolicy', 'webServer', 'tools', 'skills', 'sessions', 'agents', 'workspaceRegistry', 'sessionProjectionCache', 'sessionPersistence'],
+    inject: [...INJECT_SERVICES],
     apply(ctx, config) {
         // 布局迁移必须**先于任何读盘**：hub 内的旧名（`agents-md/` → `prompts/` 等）与
         // `$DSH_HOME` 根下的插件侧车 / 日志 / patch 备份，都要在服务读它们之前搬到位。
@@ -130,6 +146,14 @@ export default {
         }
         catch (e) {
             console.error('[dsh-plugin-tool-management] skills provider setup failed:', message(e));
+            // B3：技能 provider 没挂上 → 技能页与 agent 技能目录静默失效。此前只落 console。
+            noteRuntime({
+                id: 'skills-provider',
+                label: '技能 provider 装配',
+                kind: 'read',
+                fallback: 'inform-only',
+                detail: '技能 provider 装配失败（' + message(e) + '）：技能启用/停用与 agent 技能目录这一轮不生效。',
+            });
         }
         // ---------- 提示词预设库（hub/prompts/）+ 切换 ----------
         // DSH 全局指令基线只有 ~/.dsh/AGENTS.md 一个文件，无内置多预设切换；
@@ -610,8 +634,43 @@ export default {
         }
         catch (e) {
             console.error('[dsh-plugin-tool-management] context injection setup failed:', message(e));
+            // B3：装配失败此前只落 console —— 用户界面上"注入块看起来正常、实际什么都没注入"。
+            noteRuntime({
+                id: 'context-injection',
+                label: '上下文注入通道',
+                kind: 'read',
+                fallback: 'inform-only',
+                detail: '注入通道装配失败（' + message(e) + '）：五个注入域的内容这一轮不会被送进模型。',
+            });
         }
         void readInjectSettings().catch(() => { });
+        // B3 挂载心跳：apply 真跑到了这里，就记一笔「本插件在这一刻挂上了、声明的是这 12 个服务名」。
+        // 官方改名 inject 服务名时插件**不会 apply**，界面上「连插件都不见了」—— 那时唯一的线索
+        // 就是这份心跳没更新。doctor 读 hub/mount.json 并打印，配合官方日志即可定论（实测见
+        // INJECT_SERVICES 的注释）。失败只记日志，绝不因为它挡住启动。
+        void writeJsonFile(hubPath('mount.json'), {
+            at: Date.now(),
+            iso: new Date().toISOString(),
+            version: PKG_VERSION,
+            injects: [...INJECT_SERVICES],
+        }).catch((e) => { ctx.logger?.warn?.('mount heartbeat write failed: ' + message(e)); });
+        // B3 符号断言：probe.ts 的 unwrap 用硬编码的 `Symbol.for('cordis.original')`，与 cordis
+        // 导出的 `symbols.original` 必须是同一个符号。不是的话，探针会把代理当原始对象、身份判定失真。
+        try {
+            if (Symbol.for('cordis.original') === symbols.original) {
+                clearRuntimeNote('cordis-original-symbol');
+            }
+            else {
+                noteRuntime({
+                    id: 'cordis-original-symbol',
+                    label: 'cordis 原始对象符号',
+                    kind: 'read',
+                    fallback: 'inform-only',
+                    detail: 'cordis 导出的 symbols.original 与 Symbol.for("cordis.original") 不是同一个符号：能力探测可能把代理当原始对象，身份判定会失真。',
+                });
+            }
+        }
+        catch (e) { /* 拿不到 symbols 就跳过（探针自己也有一条退路） */ }
         // 预热放到下一轮事件循环：此时 apply 的同步初始化（补丁路径、tools 服务…）已全部完成，
         // 避免在初始化中途就去读 MCP 补丁与工具 schema。
         setTimeout(() => {
@@ -1113,8 +1172,17 @@ export default {
          */
         async function writePatch(abs, content) {
             const policy = await sandboxPolicy.resolve({ mode: 'danger-full-access' });
+            let previous = '';
+            try {
+                previous = await readPatch(abs);
+            }
+            catch (e) { /* 读不到就没有基线，校验按「没有基线」判 */ }
+            // 写前校验（非对称策略，理由与三条分支见 compat/patch-dialect.ts 的文件头）：
+            // 只有「我们这次把产物改成了官方解析不了的样子」才拦；复刻过期 / 依赖缺失一律放行 + 上报。
+            const verdict = await checkPatchWrite(previous, content);
+            if (!verdict.allow)
+                throw new Error(verdict.error);
             try {
-                const previous = await readPatch(abs);
                 if (previous && previous !== content)
                     await backupPatchFile(abs, previous);
             }
@@ -1134,6 +1202,21 @@ export default {
                 throw e;
             }
         }
+        /**
+         * 写入回执的 warning 附着点：把本次请求里「补丁校验没做成」的结论挂在结果上。
+         *
+         * 口径与既有回执一致 —— `warning` 是**一个字符串**（MCP 域已有同款字段，界面按
+         * `mcp.msg.warn` 渲染）。原有 warning 保留，本插件的追加在后面，用「；」分隔。
+         */
+        function withPatchWarnings(result) {
+            const warnings = takePatchGuardWarnings();
+            if (warnings.length === 0 || !result || typeof result !== 'object')
+                return result;
+            const extra = warnings.join('；');
+            if (typeof result.warning === 'string' && result.warning !== '')
+                return { ...result, warning: result.warning + '；' + extra };
+            return { ...result, warning: extra };
+        }
         /**
          * 找到本插件 loader 行所在的补丁文件。返回 0 / 1 / 多份，多份时调用方必须拒绝自动改：
          * 同一条 loader 行出现在两份补丁里会让宿主起不来（重复 id），与 duplicateGuard 同一口径。
@@ -1465,6 +1548,11 @@ export default {
                 listPatchBackups,
                 cleanPatchBackups,
                 getContextInjectorLive: () => contextInjectorLive,
+                // 功能总览（B6）的三层合成：令牌实况与兼容页「访问令牌」同源；场景锁定与写门禁同源；
+                // 停用工具数读 mcp 的 TTL 缓存（无 I/O）。
+                readTokenState: async () => ({ active: TOKEN !== '', accepted: TOKEN !== '' && acceptedThisBoot() }),
+                lockedSceneNames: () => lockedSceneNames(),
+                disabledToolCount: () => mcp.disabledToolCount(),
                 message,
                 compatLog,
             }),
@@ -2041,6 +2129,31 @@ export default {
             mcp.warmUp().catch(() => { });
         }
         catch (e) { /* ignore */ }
+        // 可见性半边（B1）：官方 `tools.restrict()` 要求 **agent scope**，所以停用的工具要
+        // 逐个 agent 应用 —— 与技能侧同一套生命周期写法（`agent/created` / `agent/disposed`
+        // + 启动期扫一遍 `agents.list()`，见 skills/service.ts）。
+        if (typeof ctx.on === 'function') {
+            try {
+                ctx.effect(() => {
+                    const stop = ctx.on('agent/created', (payload) => {
+                        mcp.attachAgent(payload && payload.agent);
+                    });
+                    return typeof stop === 'function' ? stop : () => { };
+                }, 'dsh-plugin-tool-management: mcp visibility (agent created)');
+                ctx.effect(() => {
+                    const stop = ctx.on('agent/disposed', (payload) => {
+                        mcp.detachAgent(payload && payload.agent);
+                    });
+                    return typeof stop === 'function' ? stop : () => { };
+                }, 'dsh-plugin-tool-management: mcp visibility (agent disposed)');
+                const agents = typeof ctx.get === 'function' ? ctx.get('agents') : undefined;
+                if (agents && typeof agents.list === 'function') {
+                    for (const agent of agents.list())
+                        mcp.attachAgent(agent);
+                }
+            }
+            catch (e) { /* agents 服务不可用 → 仅靠事件（与技能侧同一退路） */ }
+        }
         if (typeof tools.guard === 'function') {
             ctx.effect(() => tools.guard((exec) => {
                 try {
@@ -2245,7 +2358,7 @@ export default {
                             // 设置 / 关闭令牌：同样就地处理（理由见 tokenConfigure 的注释 —— 也正因为不进
                             // handlers，模型侧没有任何工具能间接关掉它）。
                             if (op === 'token-configure') {
-                                res.end(JSON.stringify(await tokenConfigure(payload.args || {}, tokenAccepted)));
+                                res.end(JSON.stringify(withPatchWarnings(await tokenConfigure(payload.args || {}, tokenAccepted))));
                                 return;
                             }
                             // 「清除令牌」的配套：把「本次启动已验过」的闩重新挂上。没有它，解锁一次之后
@@ -2264,7 +2377,7 @@ export default {
                                 return;
                             }
                             const result = await fn(payload.args || {});
-                            res.end(JSON.stringify(result === undefined ? { ok: true } : result));
+                            res.end(JSON.stringify(withPatchWarnings(result === undefined ? { ok: true } : result)));
                         }
                         catch (e) {
                             res.end(JSON.stringify({ ok: false, error: message(e) }));

package/lib/mcp/manager.js

@@ -17,6 +17,7 @@
 // **正向依赖**（本文件调用外部）：补丁行解析用 ./patch-yaml.ts、打码判据用 ./secret-guard.ts，
 // 其余 14 项（ensurePaths / withWriteLock / readPatch / pluginInventory / memoriesService 等）
 // 由 deps 显式传入。
+import { clearRuntimeNote, noteRuntime } from '../compat/runtime-notes.js';
 import { MCP_CLIENT_MODULE } from '../host-names.js';
 import { hubPath } from '../hub.js';
 import { planOverrideCompaction } from './override-blocks.js';
@@ -445,11 +446,82 @@ export function createMcpManager(deps) {
             return { ok: true, serverName, disabled: map[serverName] || [] };
         });
     }
-    // Visibility seam: keep one active restriction, refreshed whenever the tool
-    // set or the disabled set changes. `restrict` fails on unknown names, so the
-    // deny list is always intersected with the currently registered tools.
-    let restrictDisposer = null;
+    // Visibility seam: keep one active restriction per **agent scope**, refreshed whenever
+    // the tool set or the disabled 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 名单里筛掉 —— 停用静默复活。
     let restrictTimer = null;
+    /** 已应用名单的键；相同即返回（防自激，也让每次 tools/change 变成一次廉价判等）。 */
+    let appliedNamesKey = null;
+    /** 当前期望的 deny 名单（agent 晚到 / 重放时用它）。 */
+    let desiredNames = [];
+    /** agent → 撤掉这层限制的 disposer。 */
+    const agentRestrictions = new Map();
+    /** 见过的 agent（重放时逐个重新应用；disposed 时移除）。 */
+    const seenAgents = new Set();
+    function scopedToolsOf(agent) {
+        const scoped = agent && agent.ctx && agent.ctx.tools;
+        return scoped && typeof scoped === 'object' ? scoped : undefined;
+    }
+    /** 把当前名单装到某个 agent scope 上（空名单 = 没有要摘的工具，不碰它）。 */
+    function restrictAgent(agent) {
+        if (desiredNames.length === 0)
+            return;
+        const scoped = scopedToolsOf(agent);
+        if (!scoped || typeof scoped.restrict !== 'function') {
+            // agent scope 上没有 tools 面（或它没有 restrict）：这半边做不成，如实说 ——
+            // 静默跳过会让人以为"停用工具从模型工具表里消失"已经生效。
+            noteRuntime({
+                id: 'mcp-tool-visibility',
+                label: '停用工具的可见性',
+                kind: 'write',
+                fallback: 'inform-only',
+                detail: 'agent scope 上没有可用的 tools.restrict（官方接口变了或该 scope 未暴露 tools）：停用的 MCP 工具仍会出现在模型可见的工具表里，执行侧拦截仍然生效。',
+            });
+            return;
+        }
+        try {
+            const dispose = scoped.restrict({ deny: desiredNames });
+            agentRestrictions.set(agent, typeof dispose === 'function' ? dispose : () => { });
+            clearRuntimeNote('mcp-tool-visibility');
+        }
+        catch (e) {
+            // 这个名字在这个 scope 里认不出 / scope 已经收了：可见性半边没生效。执行侧的 guard
+            // 仍然拦住调用，所以功能不缺 —— 但必须如实上报，不能假装成功（此前正是静默吞掉）。
+            noteRuntime({
+                id: 'mcp-tool-visibility',
+                label: '停用工具的可见性',
+                kind: 'write',
+                fallback: 'inform-only',
+                detail: '停用的 MCP 工具没能从模型可见的工具表里摘掉（' + message(e) + '）：执行侧拦截仍然生效，模型仍能看到该工具的名字。',
+            });
+        }
+    }
+    /** agent 上线（`agent/created` 或启动期的 agent 列表）：登记并立刻应用当前名单。 */
+    function attachAgent(agent) {
+        if (!agent || (typeof agent !== 'object' && typeof agent !== 'function'))
+            return;
+        seenAgents.add(agent);
+        restrictAgent(agent);
+    }
+    /** agent 下线（`agent/disposed`）：先撤限制再销登记（撤限制会把 disposer 摘掉）。 */
+    function detachAgent(agent) {
+        seenAgents.delete(agent);
+        const dispose = agentRestrictions.get(agent);
+        agentRestrictions.delete(agent);
+        if (dispose) {
+            try {
+                dispose();
+            }
+            catch (e) { /* ignore */ }
+        }
+    }
     async function applyToolRestrictions() {
         if (typeof tools.restrict !== 'function')
             return;
@@ -474,19 +546,23 @@ export function createMcpManager(deps) {
                     wanted.push(fullName);
         }
         const names = wanted.filter((name) => registered.has(name));
-        if (restrictDisposer) {
+        const key = names.join('\u0000');
+        if (key === appliedNamesKey)
+            return;
+        appliedNamesKey = key;
+        desiredNames = names;
+        // 每次重放先撤旧限制：名单变短（重新启用某个工具）时，只有撤掉这层限制它才会重新可见。
+        for (const [agent, dispose] of agentRestrictions) {
+            agentRestrictions.delete(agent);
             try {
-                restrictDisposer();
+                dispose();
             }
             catch (e) { /* ignore */ }
-            restrictDisposer = null;
         }
         if (!names.length)
             return;
-        try {
-            restrictDisposer = tools.restrict({ deny: names });
-        }
-        catch (e) { /* registry race: the next tools/change event retries */ }
+        for (const agent of seenAgents)
+            restrictAgent(agent);
     }
     function scheduleToolRestrictions() {
         if (restrictTimer)
@@ -1637,13 +1713,15 @@ export function createMcpManager(deps) {
             clearTimeout(restrictTimer);
             restrictTimer = null;
         }
-        if (restrictDisposer) {
+        // 插件卸载时把挂在每个 agent scope 上的限制都撤掉（否则那些 scope 会继续背着一层名单）。
+        for (const [, release] of agentRestrictions) {
             try {
-                restrictDisposer();
+                release();
             }
             catch (e) { /* ignore */ }
-            restrictDisposer = null;
         }
+        agentRestrictions.clear();
+        seenAgents.clear();
     }
     return {
         stateCatalog: mcpStateCatalog,
@@ -1674,8 +1752,18 @@ export function createMcpManager(deps) {
         mcpmRowsWithNotes,
         readPluginSettings,
         isToolDisabled: (name) => isToolDisabledIn(disabledToolsCache ? disabledToolsCache.value : {}, name),
+        /** 停用表里的工具条数（读 TTL 缓存；功能总览用）。 */
+        disabledToolCount: () => {
+            const map = disabledToolsCache ? disabledToolsCache.value : {};
+            let n = 0;
+            for (const list of Object.values(map))
+                n += Array.isArray(list) ? list.length : 0;
+            return n;
+        },
         warmUp,
         scheduleToolRestrictions,
+        attachAgent,
+        detachAgent,
         dispose,
     };
 }

package/lib/ops/compat.js

@@ -6,8 +6,10 @@
 //
 // 边界纪律：本文件只负责「op 的实现」，不负责 ops 表之外的接线（MCP 写后刷新、场景锁定
 // 守卫仍作用在组装后的整张表上，见 index.ts）。
-import { EXPECTED_MIN_HOST_VERSION, EXPECTED_PEER_RANGE, VERIFIED_HOST_VERSION, summarize, } from '../compat/probe.js';
+import { EXPECTED_MIN_HOST_VERSION, EXPECTED_PEER_RANGE, VERIFIED_HOST_VERSION, routeFor, summarize, } from '../compat/probe.js';
+import { INJECT_DOMAIN_KEYS } from '../context-inject.js';
 import { assessPresetReach } from '../compat/preset-reach.js';
+import { runtimeNotes } from '../compat/runtime-notes.js';
 import { pluginLog } from '../skills/service.js';
 export function buildCompatOps(deps) {
     return {
@@ -29,13 +31,30 @@ export function buildCompatOps(deps) {
                     };
                 }
                 const summary = summarize(assessment);
+                // 运行时降级（A1 的补丁校验、A2 的投影缓存适配、B3 的装配层…）统一在这里并进
+                // findings/degraded：它们不是宿主能力，但必须各占一行 —— 否则用户只能在事故之后
+                // 才知道某道保险没生效。上报口径见 compat/runtime-notes.ts。
+                const extraFindings = runtimeNotes().map((note) => ({
+                    id: note.id,
+                    label: note.label,
+                    kind: note.kind,
+                    owner: 'plugin',
+                    fallback: note.fallback,
+                    state: 'not-available',
+                    missing: [],
+                    detail: note.detail,
+                }));
+                const findings = [...assessment.findings, ...extraFindings];
+                const degraded = [...assessment.degraded, ...extraFindings];
+                const merged = { ...assessment, findings, degraded };
+                const summaryMerged = extraFindings.length === 0 ? summary : summarize(merged);
                 // 每次刷新都留一条结构化日志：升级当天就能在日志里看到降级发生。
                 if (force || !deps.compatLog.version || deps.compatLog.version !== assessment.identity.version) {
                     deps.compatLog.version = assessment.identity.version;
                     void pluginLog()('compat/probe', {
                         hostVersion: assessment.identity.version,
-                        summary,
-                        degraded: assessment.degraded.map((item) => ({ id: item.id, state: item.state, detail: item.detail })),
+                        summary: summaryMerged,
+                        degraded: degraded.map((item) => ({ id: item.id, state: item.state, detail: item.detail })),
                         blockers: assessment.identity.blockers,
                         sameAsHost: assessment.identity.sameAsHost,
                     }).catch(() => { });
@@ -45,15 +64,15 @@ export function buildCompatOps(deps) {
                     host: { version: assessment.identity.version, modules: assessment.identity.modules },
                     sameAsHost: assessment.identity.sameAsHost,
                     unverified: assessment.identity.unverified,
-                    findings: assessment.findings,
-                    degraded: assessment.degraded,
+                    findings,
+                    degraded,
                     blockers: assessment.identity.blockers,
                     mayDelete: assessment.mayDelete,
                     verifiedVersion: VERIFIED_HOST_VERSION,
                     expectedPeerRange: EXPECTED_PEER_RANGE,
                     minHostVersion: EXPECTED_MIN_HOST_VERSION,
                     generatedAt: assessment.generatedAt,
-                    summary,
+                    summary: summaryMerged,
                 };
             }
             catch (e) {
@@ -91,6 +110,77 @@ export function buildCompatOps(deps) {
         },
         // 注入设置（读 / 写）：压制型预设下是否仍然注入 + 各域开关。界面在「兼容」页。
         'inject-settings': (args) => deps.injectSettingsOp(args),
+        // 功能总览（B6）：**按功能点**回答"现在每一项到底能不能用"，三层合成 ——
+        //   ① 装配层（listener / provider / 适配是否真的挂上，来自运行时上报通道）
+        //   ② 宿主能力层（compat 探测的路由判定）
+        //   ③ 用户配置层（开关 / 令牌 / 场景锁定）
+        // 数据全部来自已有的缓存状态与运行时上报，**不新增宿主探测**（避免哨兵真调一类的开销）。
+        // 行内 `tab` 供界面跳转到对应页签；`state` 取值见下方约定。
+        'feature-overview': async () => {
+            try {
+                const registry = deps.getSessionsRegistry();
+                const assessment = registry && typeof registry.capabilities === 'function' ? registry.capabilities() : undefined;
+                const notes = new Map(runtimeNotes().map((note) => [note.id, note]));
+                const settings = await deps.readInjectSettings();
+                const domainsOn = INJECT_DOMAIN_KEYS.filter((key) => settings.domains[key] !== false);
+                const token = await deps.readTokenState();
+                const lockedScenes = await deps.lockedSceneNames();
+                const disabledTools = deps.disabledToolCount();
+                const routeOf = (operation) => assessment === undefined ? undefined : routeFor(assessment, operation);
+                /** 一行一个功能点：状态三层合成，`detail` 写明依据。 */
+                const rows = [];
+                const push = (key, label, tab, state, detail) => rows.push({ key, label, tab, state, detail });
+                // 前置项：插件挂载（这一行本身说明 12 个 inject 都解析了 —— 否则 apply 根本不会跑）；
+                // 启动期那段 `!!js` 表达式若抛错，插件同样不会挂上（它的 try/catch 就是为了不抛）。
+                const mountNote = notes.get('cordis-original-symbol');
+                push('mount', '插件挂载', 'compat', mountNote === undefined ? 'ok' : 'degraded', mountNote === undefined ? '12 个 inject 服务全部解析，插件已挂载（详见 doctor 的挂载心跳）' : mountNote.detail);
+                // 装配层：有上报就是降级，附上报里的原因；没有就是正常。
+                const assemblyRows = [
+                    ['patch-write-guard', '宿主配置写入（补丁校验）', 'mcp'],
+                    ['context-injection', '上下文注入通道', 'compat'],
+                    ['official-suppression', '官方注入的关域拦截', 'compat'],
+                    ['skills-provider', '技能 provider 装配', 'skills'],
+                    ['projection-cache-adapter', '投影缓存删除屏障', 'sessions'],
+                    ['mcp-tool-visibility', '停用工具的可见性', 'mcp'],
+                ];
+                for (const [noteId, label, tab] of assemblyRows) {
+                    const note = notes.get(noteId);
+                    push(noteId, label, tab, note === undefined ? 'ok' : 'degraded', note === undefined ? '装配正常，无降级上报' : note.detail);
+                }
+                // 宿主能力层：删除 / 归档 / 恢复 / 批量各自由路由判定回答（与服务端执行同源）。
+                const deleteRoute = routeOf('delete');
+                push('session-delete', '会话删除', 'sessions', deleteRoute === undefined ? 'unknown' : deleteRoute.via === 'none' ? 'unavailable' : 'ok', deleteRoute === undefined ? '能力探测不可用（归档服务未挂载）'
+                    : deleteRoute.via === 'none' ? '宿主缺少该路径所需能力：' + deleteRoute.refusals.map((item) => item.label).join('、')
+                        : `可用（路径：${deleteRoute.via}）`);
+                for (const [operation, label] of [['archive', '归档'], ['unarchive', '恢复'], ['batch', '批量操作'], ['list', '历史列表']]) {
+                    const decision = routeOf(operation);
+                    push('session-' + operation, `会话${label}`, 'sessions', decision === undefined ? 'unknown' : decision.via === 'none' ? 'unavailable' : 'ok', decision === undefined ? '能力探测不可用（归档服务未挂载）'
+                        : decision.via === 'none' ? '宿主缺少该路径所需能力：' + decision.refusals.map((item) => item.label).join('、')
+                            : `可用（路径：${decision.via}）`);
+                }
+                // 用户配置层：注入域 / 令牌 / 场景锁定 / 停用工具数。
+                push('injection-domains', '注入域开关', 'compat', domainsOn.length === 0 ? 'disabled' : 'ok', domainsOn.length === 0 ? '五个注入域全部关闭（用户设置）' : `${domainsOn.length}/5 个域开启：${domainsOn.join('、')}`);
+                push('token', '访问令牌', 'compat', !token.active ? 'disabled' : token.accepted ? 'ok' : 'locked', !token.active ? '未启用（宿主没配令牌，或令牌功能被关掉）'
+                    : token.accepted ? '已生效且本次启动已通过验证' : '已生效，本次启动尚未验证：写操作与对话会被拦住，到本页下方填写令牌');
+                push('scene-lock', '场景锁定', 'scenes', lockedScenes.length === 0 ? 'ok' : 'locked', lockedScenes.length === 0 ? '无锁定场景' : `锁定中：${lockedScenes.join('、')}（写门禁按锁定场景生效）`);
+                push('mcp-tools', 'MCP 工具停用', 'mcp', disabledTools === 0 ? 'ok' : 'partial', disabledTools === 0 ? '没有停用的工具' : `${disabledTools} 个工具处于停用态（执行拦截 + 可见性摘除）`);
+                push('native-delete', '宿主原生删除入口', 'compat', notes.has('workspace.delete-native') ? 'partial' : 'ok', notes.get('workspace.delete-native')?.detail ?? '宿主未提供原生删除入口（本插件自有完整序列）');
+                // 身份 / 版本：与 compat-status 同一份数据。
+                const identity = assessment?.identity;
+                const identityIssue = identity !== undefined && (identity.blockers.length > 0 || Object.values(identity.sameAsHost).some((same) => same === false));
+                push('host-identity', '宿主身份与模块', 'compat', assessment === undefined ? 'unknown' : identityIssue ? 'degraded' : 'ok', assessment === undefined ? '能力探测不可用（归档服务未挂载）'
+                    : identityIssue ? '存在阻塞项：' + (identity?.blockers ?? []).join('；')
+                        : `模块与宿主同源（宿主 DSH ${identity?.version ?? '?'}）`);
+                // 无独立装配点的域：没有上报就是正常（如实说明依据是"没有降级上报"）。
+                for (const [key, label, tab] of [['memory', '记忆', 'memory'], ['prompts', '提示词', 'prompts'], ['subagents', '子智能体', 'subagents'], ['scenes', '场景档案', 'scenes']]) {
+                    push(key, label, tab, 'ok', '无降级上报（装配失败会出现在这里）');
+                }
+                return { ok: true, rows, generatedAt: Date.now() };
+            }
+            catch (e) {
+                return { ok: false, error: deps.message(e) };
+            }
+        },
         // patch 备份（改宿主配置前的整份副本）：列清单只读，清理按写门禁。
         // 每份备份里都是**明文**凭据，所以给一个显式出口让人能删掉多余的副本（理由见
         // cleanPatchBackups 的注释）。清单不带文件内容，只给名字 / 层级 / 时间 / 大小。