dsh-plugin-tool-management 0.17.0 → 0.18.0

package/lib/mcp/manager.js

@@ -18,13 +18,13 @@
 // 其余 14 项（ensurePaths / withWriteLock / readPatch / pluginInventory / memoriesService 等）
 // 由 deps 显式传入。
 import { clearRuntimeNote, noteRuntime } from '../compat/runtime-notes.js';
-// 配置体检查 PATH 用（见 mcpmInspect）：execFile 不走 shell，参数是数组 —— 体检只查询
-// 命令名，**绝不执行**配置里的命令本身。
-import { execFile } from 'node:child_process';
 import { MCP_CLIENT_MODULE, MCP_TOOL_PREFIX, ambiguousServerNames, looksLikeMcpPrefixDrift, serverNameCandidates, splitMcpToolName } from '../host-names.js';
 import { hubPath } from '../hub.js';
 import { planOverrideCompaction } from './override-blocks.js';
+// 配置体检的探测（PATH 查询 / 端点连通性 / 检查清单 + mcpm-inspect op），2026-10-01 剥出。
+import { createInspectProbe } from './inspect-probe.js';
 import { createMcpStateCatalog } from './state-section.js';
+import { createToolVisibility } from './tool-visibility.js';
 import { appendBlock, buildDisableBlock, buildInsertBlock, insertEntryIds, parseRows, removeEntryAll, removeMarked, spliceRanges, splitLines, } from './patch-yaml.js';
 import { describeMaskedOutcome, maskSecretValue, maskUrlQuery, maskedKeysIn, resolveMaskedKv, resolveMaskedUrl } from './secret-guard.js';
 /**
@@ -383,344 +383,18 @@ export function createMcpManager(deps) {
             return { ok: true, settings: next };
         });
     }
-    // ---------- 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 < SIDECAR_TTL_MS)
-            return disabledToolsCache.value;
-        const p = await ensurePaths();
-        const raw = await readJsonFile(mcpSidecar(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 < SIDECAR_TTL_MS)
-            return knownMcpToolsCache.value;
-        const p = await ensurePaths();
-        const raw = await readJsonFile(mcpSidecar(MCP_KNOWN_TOOLS_FILE));
-        const out = {};
-        if (raw && typeof raw === 'object') {
-            for (const serverName of Object.keys(raw)) {
-                const list = normalizeKnownTools(raw[serverName]);
-                if (list.length)
-                    out[serverName] = list;
-            }
-        }
-        knownMcpToolsCache = { at: Date.now(), value: out };
-        return out;
-    }
-    async function writeKnownMcpTools(value) {
-        const p = await ensurePaths();
-        await writeJsonFile(mcpSidecar(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 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 ensurePaths();
-        return 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 writeJsonFile(mcpSidecar(MCP_DISABLED_TOOLS_FILE), map);
-            }
-            catch (e) {
-                return { ok: false, error: '保存失败: ' + 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: '有工具没能从模型可见的工具表里摘掉（' + message(e) + '）：执行侧拦截仍然生效，模型仍能看到该工具的名字。',
-                detailKey: 'mcp-tool-visibility.partial',
-                params: { reason: 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 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 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);
-    }
+    // ---------- per-tool enable/disable + 可见性半边 → ./tool-visibility.ts ----------
+    // 那 294 行整段搬进同目录模块，靠 deps 拿这里的闭包名字（侧车读写、写锁、tools 服务、
+    // 三个侧车常量），所以母文件这一段只剩接线。
+    // 唯一被块外改写的状态是停用表缓存：改名迁移、删台、整表回写三处写它，出口两处同步读它
+    // （isToolDisabled / disabledToolSummary）—— 于是块交回两个句柄，语义与原样一致：
+    // setDisabledToolsCache(x) ≡ `disabledToolsCache = { at: Date.now(), value: x }`，
+    // disabledToolsSnapshot() ≡ `disabledToolsCache ? disabledToolsCache.value : {}`。
+    const { readDisabledTools, readKnownMcpTools, writeKnownMcpTools, mutateKnownMcpTools, mergeLiveToolsInto, mcpmToolEnabled, applyToolRestrictions, scheduleToolRestrictions, attachAgent, detachAgent, setDisabledToolsCache, disabledToolsSnapshot, disposeVisibility, } = createToolVisibility({
+        readJsonFile, writeJsonFile, ensurePaths, withWriteLock, message, tools,
+        pluginHiddenTools: deps.pluginHiddenTools, carrierHiddenTools: deps.carrierHiddenTools,
+        normalizeKnownTools, mcpSidecar, SIDECAR_TTL_MS, MCP_DISABLED_TOOLS_FILE, MCP_KNOWN_TOOLS_FILE,
+    });
     function truncateText(value, limit) {
         if (!limit || value.length <= limit)
             return value;
@@ -1427,7 +1101,7 @@ export function createMcpManager(deps) {
                         await writeJsonFile(mcpSidecar(MCP_DISABLED_TOOLS_FILE), toolMap);
                     }
                     catch (e) { /* non-fatal */ }
-                    disabledToolsCache = { at: Date.now(), value: toolMap };
+                    setDisabledToolsCache(toolMap);
                 }
                 // F-025：运行时快照的 mcp 停用表同样按 serverName 键 —— 改名不跟着改，
                 // 退出场景整体回写时旧键成死键、新名工具的停用状态丢失（回到全启用）。
@@ -1764,7 +1438,7 @@ export function createMcpManager(deps) {
                     if (Object.prototype.hasOwnProperty.call(toolMap, serverName)) {
                         delete toolMap[serverName];
                         await writeJsonFile(mcpSidecar(MCP_DISABLED_TOOLS_FILE), toolMap);
-                        disabledToolsCache = { at: Date.now(), value: toolMap };
+                        setDisabledToolsCache(toolMap);
                         await applyToolRestrictions();
                     }
                     const knownMap = Object.assign({}, await readKnownMcpTools(true));
@@ -1845,197 +1519,14 @@ export function createMcpManager(deps) {
             return { ok: true, removed: total, ids: removed, files };
         });
     }
-    // ---------- 配置体检（0.15.0 B1；0.16.5 起 streamable-http 含端点探测）--------------
-    // 对补丁文件**只读**：不写盘、不拉起子进程。对外调用两处 ——
-    //   · `where` / `which` 查 PATH：只查「这个命令名能不能找到」，绝不执行配置里的命令本身；
-    //   · streamable-http 行对配置地址发一次 GET 连通性探测（带配置的鉴权头、5 秒超时、
-    //     不读响应体 —— 与宿主连接该服务走的是同一地址同一头部，只是更轻）。
-    //
-    // 为什么单独读补丁而不复用 `mcpmList()`：那个函数顺带回写「已知工具」缓存、还要问一次
-    // schema 注册表。体检的承诺是「点了什么都不变」，所以这里只走 readPatch + parseRows。
-    const INSPECT_PATH_TIMEOUT_MS = 3000;
-    /** 命令是否在 PATH 上：`unknown`（查不了）与 `missing`（确认没有）必须分开 —— 前者不是问题。 */
-    async function probeCommandOnPath(command) {
-        if (!command)
-            return 'unknown';
-        const finder = process.platform === 'win32' ? 'where' : 'which';
-        return await new Promise((resolve) => {
-            execFile(finder, [command], { timeout: INSPECT_PATH_TIMEOUT_MS, windowsHide: true }, (error, stdout) => {
-                if (!error) {
-                    resolve(String(stdout || '').trim() ? 'ok' : 'missing');
-                    return;
-                }
-                // ENOENT = 连 where/which 自己都没跑到；killed = 超时。两种都是「无法确认」，
-                // 剩下的（退出码非 0）才是「PATH 上没有这条命令」。
-                const code = error.code;
-                if (code === 'ENOENT' || error.killed === true)
-                    resolve('unknown');
-                else
-                    resolve('missing');
-            });
-        });
-    }
-    /** streamable-http 连通性探测的超时：再长，「全部检查」就会被一台挂掉的服务拖住。 */
-    const INSPECT_PROBE_TIMEOUT_MS = 5000;
-    /** 探测失败的原因短语（进词典模板的 {reason}）：认得出常见错误码就说人话，认不出给原文截断。 */
-    function describeProbeFailure(e) {
-        const err = e;
-        if (err && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-            return '探测超时（' + Math.round(INSPECT_PROBE_TIMEOUT_MS / 1000) + ' 秒无响应）';
-        }
-        const code = err && err.cause && err.cause.code;
-        if (code === 'ENOTFOUND' || code === 'EAI_AGAIN')
-            return '域名解析失败（' + code + '）';
-        if (code === 'ECONNREFUSED')
-            return '连接被拒绝（' + code + '）';
-        if (code === 'ETIMEDOUT')
-            return '连接超时（' + code + '）';
-        if (code === 'ECONNRESET')
-            return '连接被重置（' + code + '）';
-        if (typeof code === 'string' && /CERT|SSL|TLS/.test(code))
-            return 'TLS 证书校验失败（' + code + '）';
-        const text = String((err && err.cause && err.cause.message) || (err && err.message) || e || '');
-        return text.length > 80 ? text.slice(0, 77) + '…' : text;
-    }
-    /**
-     * streamable-http 的连通性探测：对配置地址 GET 一次，**任何** HTTP 响应（含 404/405）
-     * 都算「可达」—— 探测只回答"这个地址现在连不连得上"，不校验它是不是 MCP 服务。
-     * 不读响应体：streamable-http 对 GET 常回一条 SSE 长连接，拿到状态行就取消。
-     */
-    async function probeHttpEndpoint(url, headers) {
-        const extra = {};
-        if (headers && typeof headers === 'object' && !Array.isArray(headers)) {
-            for (const [k, v] of Object.entries(headers)) {
-                if (typeof v === 'string' && v)
-                    extra[k] = v;
-            }
-        }
-        try {
-            const res = await fetch(url, { method: 'GET', headers: extra, redirect: 'follow', signal: AbortSignal.timeout(INSPECT_PROBE_TIMEOUT_MS) });
-            try {
-                await res.body?.cancel();
-            }
-            catch { /* 取消失败不影响「可达」结论 */ }
-            return { reachable: true };
-        }
-        catch (e) {
-            return { reachable: false, reason: describeProbeFailure(e) };
-        }
-    }
-    /** 一行配置 → 检查项。`level: 'warn'` 才点黄；`info` 是「查不了 / 不算问题」那类说明。 */
-    async function inspectChecks(row, duplicateIds) {
-        const checks = [];
-        const declared = String(row.transport || '');
-        const url = String(row.url || '');
-        const command = String(row.command || '');
-        // transport 缺失/不认识时按字段形状推：历史上手工改过补丁文件的行会绕过 normalize，
-        // 直接判「没有 transport」会把一条其实能用的配置说成坏的。
-        const transport = declared === 'stdio' || (!declared && command && !url) ? 'stdio'
-            : declared === 'streamable-http' || (!declared && url) ? 'streamable-http'
-                : declared;
-        if (!declared && transport)
-            checks.push({ id: 'transportMissing', level: 'info' });
-        /** 值必须是字符串映射：非对象整片算坏，对象里逐个挑出非字符串的键。 */
-        const badKv = (map) => {
-            if (map == null)
-                return [];
-            if (typeof map !== 'object' || Array.isArray(map))
-                return ['*'];
-            return Object.keys(map).filter((k) => typeof map[k] !== 'string');
-        };
-        if (transport === 'stdio') {
-            if (!command)
-                checks.push({ id: 'noCommand', level: 'warn' });
-            else {
-                // 唯一一次外部调用。npx / uvx 这类 shim 找不到时界面给的下半句是「shim 属正常可忽略」，
-                // 不让用户以为命令坏了。
-                //
-                // `params.command` 原样回给客户端：这与 `mcpm-list`（同样是**免令牌**的只读 op）一致
-                // —— 列表视图里的 `command` 一直是明文，命令名本身不是凭据（真正装凭据的 `args`
-                // 两边都不回）。若哪天要收紧，两处必须一起收，否则只是把同一份值换个 op 暴露。
-                const found = await probeCommandOnPath(command);
-                if (found === 'missing')
-                    checks.push({ id: 'cmdMissing', level: 'warn', params: { command } });
-                else if (found === 'unknown')
-                    checks.push({ id: 'cmdUnknown', level: 'info', params: { command } });
-            }
-            if (row.args != null && !Array.isArray(row.args))
-                checks.push({ id: 'argsNotArray', level: 'warn' });
-            const badEnv = badKv(row.env);
-            if (badEnv.length)
-                checks.push({ id: 'kvNotString', level: 'warn', params: { where: 'env', keys: badEnv.join('、') } });
-        }
-        else if (transport === 'streamable-http') {
-            if (!url)
-                checks.push({ id: 'noUrl', level: 'warn' });
-            // URL 一律**打码后**回给客户端（`maskUrlQuery`，与列表视图同一口径）。本 op 在登记表里
-            // 是 `readonly: true` 的免令牌 op，原先这里回的是补丁文件里的 URL 原文 —— 于是一个
-            // 无需令牌的请求就能拿到 `?api_key=…` 的明文，绕过了 `mcpm-reveal` 那道
-            // 「令牌是明文凭据最后一道防线」的设计（审查 P0-5）。路径与主机保留，定位不受影响。
-            else if (!/^https?:\/\//.test(url))
-                checks.push({ id: 'badUrl', level: 'warn', params: { url: maskUrlQuery(url) } });
-            else {
-                // 格式对了再做一次真实探测（0.16.5）：此前的体检止步于格式校验，一条编造的
-                // 地址也能拿绿点 —— 绿点承诺的「没发现问题」其实只覆盖了一半（2026-09-29 实测）。
-                const probe = await probeHttpEndpoint(url, row.headers);
-                if (!probe.reachable)
-                    checks.push({ id: 'httpUnreachable', level: 'warn', params: { url: maskUrlQuery(url), reason: probe.reason } });
-            }
-            const badHeaders = badKv(row.headers);
-            if (badHeaders.length)
-                checks.push({ id: 'kvNotString', level: 'warn', params: { where: 'headers', keys: badHeaders.join('、') } });
-        }
-        else if (!command && !url) {
-            checks.push({ id: 'noEndpoint', level: 'warn' });
-        }
-        else {
-            checks.push({ id: 'badTransport', level: 'warn', params: { transport } });
-        }
-        if (duplicateIds > 1)
-            checks.push({ id: 'nameDup', level: 'warn', params: { name: String(row.serverName || ''), count: duplicateIds } });
-        return checks;
-    }
-    async function mcpmInspect(args) {
-        const p = await ensurePaths();
-        const rows = [];
-        const errors = [];
-        for (const level of ['project', 'global']) {
-            const abs = level === 'project' ? p.projectPatch : p.globalPatch;
-            let content = '';
-            try {
-                content = await readPatch(abs);
-            }
-            catch (e) {
-                errors.push(level + ': ' + message(e));
-                continue;
-            }
-            const { rows: fileRows } = parseRows(content);
-            for (const r of fileRows)
-                rows.push(normalizeRow(r, level, abs));
-        }
-        // 重名判据：同一个 serverName 挂在**不同 id** 下。同 id 跨层是正常遮蔽（界面已有「重复 id」标签），
-        // 而按名字注册的 `mcp__<serverName>__*` 会撞车 —— 那才是配置问题。
-        const idsByName = {};
-        for (const r of rows) {
-            const n = String(r.serverName || '');
-            if (!idsByName[n])
-                idsByName[n] = new Set();
-            idsByName[n].add(String(r.id));
-        }
-        const onlyId = args && String(args.id || '') ? String(args.id) : '';
-        const onlyLevel = args && String(args.level || '') ? String(args.level) : '';
-        // 逐行检查并行跑：体检含 streamable-http 的端点探测（每次至多 5 秒超时），串行会让
-        // 「全部检查」在多台同时连不上时按行数翻倍地慢。Promise.all 保序，与旧实现一致。
-        const targets = rows.filter((r) => (!onlyId || String(r.id) === onlyId) && (!onlyLevel || String(r.level) === onlyLevel));
-        const results = await Promise.all(targets.map(async (r) => ({
-            id: r.id,
-            serverName: r.serverName,
-            level: r.level,
-            transport: r.transport || null,
-            checks: await inspectChecks(r, (idsByName[String(r.serverName || '')] || new Set()).size),
-        })));
-        return { ok: true, results, errors };
-    }
+    // ---------- 配置体检的探测（0.15.0 B1；0.16.5 起含端点探测）----------------------
+    // 正文 2026-10-01 整段搬到 ./inspect-probe.js（一字未改，只把闭包作用域的几个名字改走
+    // deps）。那段「对补丁只读、`where`/`which` 只查命令名绝不执行配置里的命令、复用列表结果
+    // 但不回写任何缓存」的口径连同理由一起搬过去了，见那边的文件头。
+    const { mcpmInspect } = createInspectProbe({
+        ensurePaths, readPatch, message, normalizeRow, mcpmList,
+    });
+    // ---------- 配置的导出 / 导入 ----------
     async function mcpmExport() {
         const p = await ensurePaths();
         const list = await mcpmList();
@@ -2257,7 +1748,7 @@ export function createMcpManager(deps) {
         await deps.withWriteLock(async () => {
             await writeJsonFile(mcpSidecar(MCP_DISABLED_TOOLS_FILE), entries);
         });
-        disabledToolsCache = { at: Date.now(), value: entries };
+        setDisabledToolsCache(entries);
         scheduleToolRestrictions();
     }
     /**
@@ -2278,18 +1769,9 @@ export function createMcpManager(deps) {
         await readDisabledTools();
         await applyToolRestrictions();
     }
-    /** 卸载清理（原 index.ts 的 cleanup effect 正文）。 */
+    /** 卸载清理（那六行随可见性段搬进 tool-visibility.ts，这里只留出口接线）。 */
     function dispose() {
-        if (restrictTimer) {
-            clearTimeout(restrictTimer);
-            restrictTimer = null;
-        }
-        // 插件卸载时把挂在每个 agent scope 上的限制都撤掉（否则那些 scope 会继续背着一层名单）。
-        epoch += 1;
-        for (const agent of [...agentRestrictions.keys()])
-            liftRestriction(agent);
-        appliedByAgent.clear();
-        seenAgents.clear();
+        disposeVisibility();
     }
     return {
         stateCatalog: mcpStateCatalog,
@@ -2321,10 +1803,10 @@ export function createMcpManager(deps) {
         configuredServerNames,
         mcpmRowsWithNotes,
         readPluginSettings,
-        isToolDisabled: (name) => isToolDisabledIn(disabledToolsCache ? disabledToolsCache.value : {}, name),
+        isToolDisabled: (name) => isToolDisabledIn(disabledToolsSnapshot(), name),
         /** 停用表的两个口径（读 TTL 缓存；功能总览用）：`*` 通配的台数 + 单独停用的工具数。 */
         disabledToolSummary: () => {
-            const map = disabledToolsCache ? disabledToolsCache.value : {};
+            const map = disabledToolsSnapshot();
             let servers = 0;
             let tools = 0;
             for (const list of Object.values(map)) {