dsh-plugin-tool-management 0.8.0 → 0.8.5

package/lib/index.js

@@ -319,11 +319,15 @@ export default {
                 const raw = await readDisabledTools();
                 for (const [server, list] of Object.entries(raw))
                     out[server] = list.filter((t) => t !== '*');
+                // 「已知工具」缓存：未运行服务器也能按最后见过的名单计算补集。
+                for (const [server, list] of Object.entries(await readKnownMcpTools())) {
+                    out[server] = [...new Set([...(out[server] || []), ...list])].sort();
+                }
                 let schemas = [];
                 try {
                     schemas = await tools.schemas();
                 }
-                catch { /* 无 live 工具 → 仅启停表 */ }
+                catch { /* 无 live 工具 → 仅停用表 + 缓存 */ }
                 for (const s of schemas) {
                     const p = toolKeyParts(String((s && s.name) || ''));
                     if (!p)
@@ -399,6 +403,31 @@ export default {
                 // 补丁改动由宿主热重载（实测 ≤5s）。这里**不等**，避免进入模式被拖住十几秒；
                 // 界面在应用完成后即可用，工具集合会在数秒内补齐。
             },
+            // 场景备注（v0.8.1）：备注写在 `dsh-plugin-tool-management-notes.json`（按 loader id），
+            // 场景档案按 serverName 存 —— 引擎负责映射与读写，与 mcpm-note 同一条写锁。
+            currentMcpNotes: async () => ({ ...(await readNotes()) }),
+            applyMcpNotes: async (entries) => {
+                await withWriteLock(async () => {
+                    const map = Object.assign({}, await readNotes(true));
+                    for (const e of entries) {
+                        if (e.note)
+                            map[e.id] = e.note;
+                        else
+                            delete map[e.id];
+                    }
+                    const p = await ensurePaths();
+                    await writeJsonFile(sidecarPath(p.home, 'dsh-plugin-tool-management-notes.json'), map);
+                    notesCache = { at: Date.now(), value: map };
+                });
+            },
+            mcpIdOfServer: async (serverName) => {
+                const r = await mcpmListView();
+                for (const row of ((r && r.rows) || [])) {
+                    if (String(row.serverName || row.id) === serverName)
+                        return String(row.id);
+                }
+                return undefined;
+            },
             skillSourceStates: async () => {
                 const r = await skillsService.ops['skill-state']({});
                 const roots = (r && r.data && r.data.roots) || [];
@@ -562,8 +591,12 @@ export default {
                 }
                 catch { /* 守卫读状态失败不拦正常流程（引擎自身校验兜底） */ }
                 const res = await baseSceneModeSet(args);
-                if (res && res.ok !== false)
+                if (res && res.ok !== false) {
+                    // 进/退/切换模式会改 MCP 启停（服务器级）与备注（场景备注覆盖/恢复），
+                    // 状态段必须立即重算 —— 场景退出后下一次请求就该看到恢复的全局备注与启停。
                     void subagentCatalog.refresh();
+                    void mcpStateCatalog.refresh();
+                }
                 return res;
             };
         }
@@ -1569,6 +1602,34 @@ export default {
             }
             return out;
         }
+        // ---------- 「已知工具」侧车（v0.8.1）-----------------------------------
+        // MCP 工具名只在服务器**运行**时可见（tools.schemas() 里才有）。未运行的服务器在
+        // 场景档案里既显示 0 工具、工具明细也空空如也 —— 用户没法给未运行服务器挑工具。
+        // 每次枚举到 live 工具时按 serverName 记一份「最后见过的工具名」，未运行时用它兜底：
+        // 场景档案能列出/勾选，进入场景后按实际注册的工具生效（restrict 会过滤掉不存在的名字）。
+        const KNOWN_MCP_TOOLS_FILE = 'dsh-plugin-tool-management-mcp-tools.json';
+        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(sidecarPath(p.home, KNOWN_MCP_TOOLS_FILE));
+            const out = {};
+            if (raw && typeof raw === 'object') {
+                for (const serverName of Object.keys(raw)) {
+                    const list = raw[serverName];
+                    if (Array.isArray(list))
+                        out[serverName] = list.map((name) => String(name)).filter((name) => /^[A-Za-z0-9_-]{1,128}$/.test(name)).sort();
+                }
+            }
+            knownMcpToolsCache = { at: Date.now(), value: out };
+            return out;
+        }
+        async function writeKnownMcpTools(value) {
+            const p = await ensurePaths();
+            await writeJsonFile(sidecarPath(p.home, KNOWN_MCP_TOOLS_FILE), value);
+            knownMcpToolsCache = { at: Date.now(), value: value };
+        }
         /** 单工具停用判定（含整服务器通配 `*`——场景档案的"MCP 工具集=整台"写的就是它）。 */
         function isToolDisabled(map, fullName) {
             if (!fullName.startsWith('mcp__'))
@@ -1799,8 +1860,77 @@ export default {
                     toolsList.push({ name, description: '（已停用；描述暂不可用）', enabled: false, parameters: [] });
                 }
             }
+            // 「已知工具」缓存兜底：服务器没运行时 schemas() 里没有它任何工具 —— 场景档案里
+            // 想给未运行服务器挑工具就全靠这份最后见过的名单（描述/参数不可用，按名字勾选）。
+            for (const name of (await readKnownMcpTools())[serverName] || []) {
+                if (listed.has(name))
+                    continue;
+                toolsList.push({ name, description: '（服务器未运行；描述暂不可用）', enabled: !disabledHere.has(name), parameters: [] });
+                listed.add(name);
+            }
             return { ok: true, tools: toolsList };
         }
+        /**
+         * 临时启动服务器以枚举工具（v0.8.1）：从未运行过的服务器在 schemas() 与「已知工具」
+         * 缓存里都没有工具名，场景档案勾选器对它一无所知。这里**临时**把它启用（写补丁），
+         * 轮询等它的工具注册（npx 冷启动要下载，上限 30s），拿到名单后就**恢复原启停状态**——
+         * 用户环境的服务器开关不受影响。已有已知工具时直接返回现有清单，不做任何改动。
+         */
+        async function mcpmToolsRefresh(args) {
+            const serverName = String((args && args.serverName) || '').trim();
+            if (!serverName)
+                return { ok: false, error: 'serverName 不能为空' };
+            const existing = await mcpmTools({ serverName });
+            if (existing && existing.ok === false)
+                return existing;
+            if (existing && (existing.tools || []).length)
+                return existing;
+            const list = await mcpmListView();
+            const row = ((list && list.rows) || []).find((r) => String(r.serverName) === serverName);
+            if (!row)
+                return { ok: false, error: `未找到服务器: ${serverName}` };
+            if (row.level !== 'global' && row.level !== 'project') {
+                return { ok: false, error: `该服务器不驻留在补丁文件（level=${row.level}），无法临时启动；请先在 MCP 页启用它一次以记录工具` };
+            }
+            const wasDisabled = !!row.disabled;
+            try {
+                if (wasDisabled) {
+                    const r = await mcpmSetEnabled({ id: row.id, level: row.level, enabled: true });
+                    if (r && r.ok === false)
+                        return r;
+                }
+                const deadline = Date.now() + 30000;
+                for (;;) {
+                    const t = await mcpmTools({ serverName });
+                    if (t && t.ok && (t.tools || []).length) {
+                        // 记进「已知工具」缓存：以后未运行时场景档案也能列出。
+                        const names = t.tools.map((x) => String(x.name)).filter(Boolean);
+                        if (names.length) {
+                            try {
+                                const cache = await readKnownMcpTools();
+                                const merged = [...new Set([...(cache[serverName] || []), ...names])].sort();
+                                cache[serverName] = merged;
+                                await writeKnownMcpTools(cache);
+                            }
+                            catch { /* 缓存写失败不影响本次返回 */ }
+                        }
+                        return t;
+                    }
+                    if (Date.now() >= deadline)
+                        break;
+                    await new Promise((resolve) => setTimeout(resolve, 1000));
+                }
+                return { ok: false, error: `等待超时：${serverName} 在 30 秒内没有注册任何工具（服务器可能启动失败或连接过慢）` };
+            }
+            finally {
+                if (wasDisabled) {
+                    const r = await mcpmSetEnabled({ id: row.id, level: row.level, enabled: false });
+                    if (!r || r.ok === false)
+                        console.warn('[dsh-plugin-tool-management] mcpm-tools-refresh: 恢复服务器停用状态失败', serverName);
+                }
+                void mcpStateCatalog.refresh();
+            }
+        }
         async function mcpmList() {
             const p = await ensurePaths();
             const rows = [];
@@ -1822,23 +1952,54 @@ export default {
             const toolCounts = {};
             try {
                 const schemas = await tools.schemas();
+                const knownCache = await readKnownMcpTools();
+                const liveNames = {};
                 const seen = new Set();
                 for (const s of schemas) {
                     const fullName = String(s && s.name || '');
-                    seen.add(fullName);
-                    const m = fullName.match(/^mcp__([A-Za-z0-9_-]+)__/);
-                    if (m)
-                        toolCounts[m[1]] = (toolCounts[m[1]] || 0) + 1;
-                }
-                // Restricted tools may be absent from schemas(); they still belong to
-                // the per-server count so the UI does not show a phantom drop.
-                for (const fullName of disabledToolNames(await readDisabledTools())) {
                     if (seen.has(fullName))
                         continue;
-                    const m = fullName.match(/^mcp__([A-Za-z0-9_-]+)__/);
-                    if (m)
-                        toolCounts[m[1]] = (toolCounts[m[1]] || 0) + 1;
+                    seen.add(fullName);
+                    const m = fullName.match(/^mcp__([A-Za-z0-9_-]+)__(.+)$/);
+                    if (!m)
+                        continue;
+                    const list = liveNames[m[1]] || (liveNames[m[1]] = []);
+                    if (list.indexOf(m[2]) < 0)
+                        list.push(m[2]);
+                }
+                // 工具数 = live ∪ 停用表里的单个工具名 ∪ 「已知工具」缓存 —— 未运行的服务器
+                // 也能显示最后一次见过的工具数，而不是永远 0。
+                const union = {};
+                const addTool = (server, tool) => {
+                    if (!server || !tool)
+                        return;
+                    const set = union[server] || (union[server] = new Set());
+                    set.add(tool);
+                };
+                for (const [server, list] of Object.entries(liveNames))
+                    for (const t of list)
+                        addTool(server, t);
+                for (const [server, list] of Object.entries(await readDisabledTools()))
+                    for (const t of list)
+                        if (t !== '*')
+                            addTool(server, t);
+                for (const [server, list] of Object.entries(knownCache))
+                    for (const t of list)
+                        addTool(server, t);
+                for (const [server, set] of Object.entries(union))
+                    toolCounts[server] = set.size;
+                // 回写「已知工具」：live 见到的名字并入缓存（有变化才写盘，读路径上的 best-effort）。
+                let cacheChanged = false;
+                for (const [server, list] of Object.entries(liveNames)) {
+                    const prev = knownCache[server] || [];
+                    const next = [...new Set([...prev, ...list])].sort();
+                    if (next.join('\u0000') !== prev.join('\u0000')) {
+                        knownCache[server] = next;
+                        cacheChanged = true;
+                    }
                 }
+                if (cacheChanged)
+                    void writeKnownMcpTools(knownCache).catch(() => { });
             }
             catch (e) { /* ignore */ }
             let live = [];
@@ -1924,7 +2085,10 @@ export default {
                 }
                 const before = content;
                 content = appendBlock(content, buildInsertBlock(row));
-                if (args.enabled === false)
+                // v0.8.5：新增服务器默认不启动（用户裁定，与技能 / 子智能体同口径）；
+                // 显式传 enabled: true 才创建即启动。
+                const defaultDisabled = args.enabled !== true;
+                if (defaultDisabled)
                     content = appendBlock(content, buildDisableBlock(id, true));
                 const guard = duplicateGuard(before, content);
                 if (guard)
@@ -1935,7 +2099,7 @@ export default {
                 catch (e) {
                     return { ok: false, error: '写入补丁失败: ' + message(e) };
                 }
-                return { ok: true, row: { ...row, level, disabled: args.enabled === false } };
+                return { ok: true, row: { ...row, level, disabled: defaultDisabled } };
             });
         }
         async function mcpmEdit(args) {
@@ -2484,6 +2648,24 @@ export default {
                 }
                 const sessionPaths = registry.sessionPaths instanceof Map ? registry.sessionPaths : undefined;
                 const headers = registry.headers instanceof Map ? registry.headers : undefined;
+                // 「目录真实存在」检查缓存：canRegister 从「宿主 sessionPaths 命中」放宽为
+                // 「目录存在」时，同一目录只 stat 一次；结果按归一化键缓存，避免每次刷新重复探盘。
+                const dirExistsCache = new Map();
+                async function directoryExists(p) {
+                    const k = workspacePathKey(p);
+                    const hit = dirExistsCache.get(k);
+                    if (hit !== undefined)
+                        return hit;
+                    let ok = false;
+                    try {
+                        ok = (await stat(p)).isDirectory();
+                    }
+                    catch {
+                        ok = false;
+                    }
+                    dirExistsCache.set(k, ok);
+                    return ok;
+                }
                 for (const it of items) {
                     const sid = it.sessionId;
                     let wid = owned.get(sid);
@@ -2513,17 +2695,21 @@ export default {
                     const known = snapshot ? snapshot.get(workspacePathKey(path)) : undefined;
                     const existing = groupsById.get(key);
                     if (existing) {
-                        // 同目录的多个会话：目录存在（sessionPaths 命中）即可重新登记。
-                        if (canonical !== undefined)
+                        // 同目录的多个会话：宿主索引命中，或磁盘目录真实存在，即可重新登记。
+                        if (canonical !== undefined || (await directoryExists(path))) {
                             existing.canRegister = true;
+                            existing.dirMissing = false;
+                        }
                         continue;
                     }
+                    const canRegister = canonical !== undefined || (await directoryExists(path));
                     const view = {
                         id: key,
                         title: known?.title || workspaceBaseName(path) || path,
                         kind: 'detached',
                         registered: known !== undefined,
-                        canRegister: canonical !== undefined,
+                        canRegister,
+                        dirMissing: !canRegister,
                         path: known?.path || path,
                     };
                     groupsById.set(key, view);
@@ -2779,6 +2965,7 @@ export default {
             'mcpm-tool-enabled': mcpmToolEnabled,
             'skill-open': skillOpen,
             'mcpm-tools': mcpmTools,
+            'mcpm-tools-refresh': mcpmToolsRefresh,
             'mcpm-add': mcpmAdd,
             'mcpm-edit': mcpmEdit,
             'mcpm-set-enabled': mcpmSetEnabled,
@@ -2834,14 +3021,19 @@ export default {
                     if (!name || seen.has(name))
                         continue;
                     seen.add(name);
+                    const live = !!(row.live && row.live.enabled);
                     mcpServers.push({
                         name,
                         level: row.level || null,
-                        live: !!(row.live && row.live.enabled),
+                        live,
                         serverDisabled: !!row.disabled,
                         // 停用表里的 ['*'] = 整台工具停用（勾选器据此预勾，避免把"全停"读成"全启用"）。
                         allToolsDisabled: (disabledRaw[name] || []).indexOf('*') >= 0,
-                        toolCount: typeof row.toolCount === 'number' ? row.toolCount : null,
+                        // 未运行且没有任何已知工具 ⇒ null（客户端显示「工具数未知」并引导读取），
+                        // 不再给出误导性的 0。
+                        toolCount: live || Number(row.toolCount) > 0
+                            ? (typeof row.toolCount === 'number' ? row.toolCount : null)
+                            : null,
                     });
                 }
                 return {
@@ -3539,7 +3731,7 @@ export default {
         // 覆盖所有会改变「哪些 server 可用 / 有哪些备注」的写入口 —— 集中在这一处包，
         // 不需要在界面层逐个补（漏一个就会出现「改了但模型看不到」的静默不一致）。
         for (const opName of ['mcpm-add', 'mcpm-edit', 'mcpm-remove', 'mcpm-set-enabled', 'mcpm-set-all',
-            'mcpm-restart', 'mcpm-note', 'mcpm-tool-enabled', 'mcpm-import', 'mcpm-compact']) {
+            'mcpm-restart', 'mcpm-note', 'mcpm-tool-enabled', 'mcpm-import', 'mcpm-compact', 'mcpm-tools-refresh']) {
             const original = handlers[opName];
             if (typeof original !== 'function')
                 continue;
@@ -3926,9 +4118,14 @@ export default {
         if (typeof ctx.on === 'function') {
             try {
                 // MCP servers (de)register their tools as instances come and go; the
-                // visible-set restriction must track that.
+                // visible-set restriction must track that — and so must the MCP state
+                // section: 工具加载完成后若不重算，段会一直停留在「空/旧集合」的缓存值上
+                //（用户切 MCP 后立即看系统提示词就是空段 —— 2026-09-16 实测）。
                 ctx.effect(() => {
-                    const stop = ctx.on('tools/change', () => scheduleToolRestrictions());
+                    const stop = ctx.on('tools/change', () => {
+                        scheduleToolRestrictions();
+                        void mcpStateCatalog.refresh();
+                    });
                     return typeof stop === 'function' ? stop : () => { };
                 }, 'dsh-plugin-tool-management: tools/change listener');
             }

package/lib/mcp/state-section.js

@@ -9,7 +9,7 @@ export const DEFAULT_MCP_NOTE_MAX_LENGTH = 200;
  * （如「忽略以上全部规则」），会被当作系统级指令执行。威胁模型上是**自伤**而非被攻击
  * （内容由用户自己写、仅本机可写），但加固定前缀能降低被读成指令的概率。
  */
-export const MCP_NOTE_PREFIX = '用户备注：';
+export const MCP_NOTE_PREFIX = '备注：';
 /** 备注压成单行（换行 → 空格）并截断。 */
 function normalizeNote(value, maxLength) {
     const flat = String(value ?? '').replaceAll(/\s+/g, ' ').trim();

package/lib/rules/archive-engine.js

@@ -34,6 +34,11 @@ export function createArchiveEngine(deps) {
         const mcp = Object.fromEntries(Object.entries(snapshot.mcp).map(([k, v]) => [k, v.slice()]));
         await deps.applyMcpEntries(mcp);
         await deps.applySkills({ ...snapshot.skills });
+        // 备注：按快照原值写回（null = 原本没有，删除）。模式期间的手动备注改动不保留（同 §2.2）。
+        const notes = snapshot.mcpNotes ?? [];
+        if (notes.length) {
+            await deps.applyMcpNotes(notes.map((x) => ({ id: x.id, note: x.note })));
+        }
         // 子智能体开关：只停「进入时被这次启用过的」那些（老 snapshot 没有这栏 → []，按旧行为跳过）。
         const personas = snapshot.subagents ?? [];
         if (personas.length) {
@@ -89,6 +94,18 @@ export function createArchiveEngine(deps) {
                 if (hadKeys && Object.keys(archive.mcp).length === 0)
                     delete archive.mcp;
             }
+            if (archive.mcpNotes) {
+                const configured = await deps.configuredServers();
+                for (const server of Object.keys(archive.mcpNotes)) {
+                    if (configured.indexOf(server) < 0) {
+                        stale.push('mcpNotes/' + server);
+                        delete archive.mcpNotes[server];
+                    }
+                }
+                // 空段 = 无覆盖（与未定义行为相同：进入场景不覆盖任何备注），删除以免歧义。
+                if (Object.keys(archive.mcpNotes).length === 0)
+                    delete archive.mcpNotes;
+            }
             if (archive.skills) {
                 const known = await deps.knownSkillKeys();
                 const hadKeys = archive.skills.length > 0;
@@ -162,7 +179,7 @@ export function createArchiveEngine(deps) {
             //   ① 场景开关（P6）是唯一入口，纯记忆场景点开关不能报错；
             //   ② 顶部「当前模式」横幅的渲染条件是 `mode.scene`，不写就永远不显示 ——
             //      用户裁定：无档案场景开开关也要显示横幅，副标题走 `scenes.mode.noProfile`。
-            const appliesArchive = !!archive && (hasSection(archive, 'mcp') || hasSection(archive, 'skills') || hasSection(archive, 'subagents'));
+            const appliesArchive = !!archive && (hasSection(archive, 'mcp') || hasSection(archive, 'skills') || hasSection(archive, 'subagents') || hasSection(archive, 'mcpNotes'));
             // 先算计划、再拍快照：快照只记**将被改动**的服务器行 / 来源 / 人设（带改动前的状态），
             // 退出时按记录精确恢复 —— 不动用户手动设置的其他行。
             let mcpPlan = null;
@@ -196,10 +213,40 @@ export function createArchiveEngine(deps) {
                     return { ok: false, error: `读取人设开关状态失败（未改动任何东西）：${msg(e)}` };
                 }
             }
+            // 场景备注（v0.8.1）：把 `mcpNotes`（serverName → 场景备注）映射到 loader id，
+            // 记录**改动前**的备注（快照恢复用），应用时写进 notes.json 覆盖全局备注。
+            let noteTargets = null;
+            let noteBefore = [];
+            if (archive && archive.mcpNotes) {
+                try {
+                    const current = await deps.currentMcpNotes();
+                    const targets = [];
+                    const before = [];
+                    // 只对**mcp 段里实际勾选**的服务器应用场景备注：未勾选的服务器该场景根本不用它，
+                    // 覆盖它的全局备注属于误伤（2026-09-16 用户实测「没勾的服务器备注也变了」）。
+                    const selectedServers = archive.mcp ? Object.keys(archive.mcp) : [];
+                    for (const [server, note] of Object.entries(archive.mcpNotes)) {
+                        if (selectedServers.indexOf(server) < 0)
+                            continue;
+                        const id = await deps.mcpIdOfServer(server);
+                        if (id === undefined)
+                            continue; // 保存时已 stale 过，这里再兜底
+                        targets.push({ id, note });
+                        before.push({ id, note: current[id] ?? null });
+                    }
+                    if (targets.length) {
+                        noteTargets = targets;
+                        noteBefore = before;
+                    }
+                }
+                catch (e) {
+                    return { ok: false, error: `读取备注状态失败（未改动任何东西）：${msg(e)}` };
+                }
+            }
             const snapshot = appliesArchive
                 ? snapshotRuntime(await deps.currentMcpRaw(), await deps.currentSkills(), 
                 // 直接用计划带出的 `*Before`（改动前的状态），不在这里反推 —— 反推容易搞反方向。
-                (mcpPlan?.serverSwitches ?? []).map((s) => ({ id: s.id, level: s.level, disabled: s.disabledBefore })), (skillsPlan?.sourceSwitches ?? []).map((s) => ({ root: s.root, enabled: s.enabledBefore })), personaRestore)
+                (mcpPlan?.serverSwitches ?? []).map((s) => ({ id: s.id, level: s.level, disabled: s.disabledBefore })), (skillsPlan?.sourceSwitches ?? []).map((s) => ({ root: s.root, enabled: s.enabledBefore })), personaRestore, noteBefore)
                 : null;
             const entered = { ...slice, mode: { scene: target, snapshot }, active: [target] };
             try {
@@ -231,6 +278,10 @@ export function createArchiveEngine(deps) {
                 if (boundPersonas.length) {
                     await deps.applySubagentSwitches(boundPersonas.map((n) => ({ name: n, enabled: true })));
                 }
+                // ④ 场景备注：覆盖全局备注（notes.json）。恢复走快照的 mcpNotes 原值。
+                if (noteTargets && noteTargets.length) {
+                    await deps.applyMcpNotes(noteTargets.map((x) => ({ id: x.id, note: x.note })));
+                }
             }
             catch (e) {
                 // 无档案段时没有运行时改动可回滚（snapshot 为 null）。
@@ -246,7 +297,7 @@ export function createArchiveEngine(deps) {
             return {
                 ok: true,
                 mode: entered.mode,
-                applied: { mcp: !!(archive && archive.mcp), skills: !!(archive && archive.skills), subagents: !!(archive && archive.subagents) },
+                applied: { mcp: !!(archive && archive.mcp), mcpNotes: !!(archive && archive.mcpNotes), skills: !!(archive && archive.skills), subagents: !!(archive && archive.subagents) },
                 // 上层实际切换了几个（0 = 本来就已经是目标状态，界面不必提示"已停用 N 台"）。
                 switched: {
                     mcpServers: mcpPlan ? mcpPlan.serverSwitches.length : 0,

package/lib/rules/archive.js

@@ -32,6 +32,23 @@ export function normalizeMcpSpec(raw) {
     }
     return out;
 }
+/**
+ * MCP 场景备注规范化：serverName → 非空备注文本；空值/畸形形态丢弃。
+ * 空对象返回 `{}`（段已定义但无覆盖 = 合法，键存在即段已定义）。
+ */
+export function normalizeMcpNotes(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [serverRaw, v] of Object.entries(raw)) {
+        const server = serverRaw.trim();
+        const note = String(v ?? '').trim();
+        if (!server || !note)
+            continue;
+        out[server] = note;
+    }
+    return out;
+}
 /** 'mcp'/'skills'/'subagents'/'memories' 键存在且值非 null 才视为"段已定义"——存在性独立于集合空否（null/缺失 = 未定义）。 */
 export function normalizeArchive(raw) {
     const obj = (raw && typeof raw === 'object' ? raw : {});
@@ -41,6 +58,8 @@ export function normalizeArchive(raw) {
         if (mcp)
             out.mcp = mcp;
     }
+    if (obj.mcpNotes != null)
+        out.mcpNotes = normalizeMcpNotes(obj.mcpNotes);
     if (obj.skills != null)
         out.skills = normalizeStringList(obj.skills);
     if (obj.subagents != null)
@@ -144,13 +163,16 @@ mcpServers = [],
 /** **将被档案改动**的来源，带改动前的 `enabled`。 */
 skillSources = [], 
 /** **将被档案启用**的人设名（改动前停用的子集；退出时按此停回）。 */
-subagents = []) {
+subagents = [], 
+/** **将被档案改动**的备注行，带改动前的备注（null = 原本没有）。 */
+mcpNotes = []) {
     return {
         mcp: Object.fromEntries(Object.entries(mcpRaw).map(([k, v]) => [k, v.slice()])),
         skills: { ...skills },
         mcpServers: mcpServers.map((x) => ({ id: x.id, level: x.level, disabled: x.disabled })),
         skillSources: skillSources.map((x) => ({ root: x.root, enabled: x.enabled })),
         ...(subagents.length ? { subagents: subagents.slice() } : {}),
+        ...(mcpNotes.length ? { mcpNotes: mcpNotes.map((x) => ({ id: x.id, note: x.note })) } : {}),
     };
 }
 // ── 记忆勾选（v3）──────────────────────────────────────────────────────────

package/lib/rules/service.js

@@ -420,7 +420,7 @@ function parseArchives(raw) {
     }
     return out;
 }
-function parseModeState(raw) {
+export function parseModeState(raw) {
     const obj = (raw && typeof raw === 'object' ? raw : {});
     const scene = typeof obj.scene === 'string' && obj.scene.trim() !== '' ? obj.scene : null;
     const snapshotRaw = (obj.snapshot && typeof obj.snapshot === 'object' ? obj.snapshot : {});
@@ -470,6 +470,12 @@ function parseModeState(raw) {
         .map((x) => ({ root: String(x.root || ''), enabled: x.enabled === true }))
         .filter((x) => x.root !== '');
     const subagents = (Array.isArray(snapshotRaw.subagents) ? snapshotRaw.subagents : []).map((x) => String(x)).filter(Boolean);
+    // v0.8.1 的场景备注恢复名单：**必须原样透传**——这里漏掉它，退出模式时备注永不回退
+    //（与历史上 mcpServers / skillSources 被剥掉是同一类 bug）。
+    const mcpNotes = (Array.isArray(snapshotRaw.mcpNotes) ? snapshotRaw.mcpNotes : [])
+        .filter((x) => !!x && typeof x === 'object')
+        .map((x) => ({ id: String(x.id || ''), note: typeof x.note === 'string' ? x.note : null }))
+        .filter((x) => x.id !== '');
     return {
         scene,
         snapshot: scene
@@ -479,6 +485,7 @@ function parseModeState(raw) {
                 ...(mcpServers.length ? { mcpServers } : {}),
                 ...(skillSources.length ? { skillSources } : {}),
                 ...(subagents.length ? { subagents } : {}),
+                ...(mcpNotes.length ? { mcpNotes } : {}),
             }
             : null,
     };
@@ -961,7 +968,7 @@ function renderSceneMemory(probe, index, maxBytes) {
     let seq = 0;
     for (const scene of [...buckets.keys()].sort((a, b) => compareSceneBuckets(a, b, index))) {
         const sceneFiles = (buckets.get(scene) || []).slice().sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
-        const header = `${sceneHeading(scene)}\n\n`;
+        const header = `${sceneHeading(scene)}\n\n${SCENE_MEMORY_NOTE}\n\n`;
         for (const file of sceneFiles) {
             const block = `### ${ruleHeading(file)}\n\n${String(file.body ?? '').trim()}\n`;
             candidates.push({
@@ -1100,6 +1107,11 @@ function sceneLabel(scene, index) {
 }
 /** 场景标题：`''` → 全局；其余用目录名（可追溯）。 */
 const sceneHeading = (scene) => `## 场景记忆：${sceneLabel(scene)}`;
+/**
+ * 场景标题后的固定引导语（常量，不破坏前缀缓存稳定）：让模型知道这段是当前场景的
+ * 常驻参考知识，而不是对话历史或临时说明 —— 相关就用、无关可忽略。
+ */
+const SCENE_MEMORY_NOTE = '（本场景的常驻参考知识：与当前任务相关时直接采用，无关时忽略）';
 /** 单条记忆的标题：显式 description 优先；派生描述与正文重复，改用文件名。 */
 const ruleHeading = (f) => (f.descriptionDerived || !f.description ? f.name : f.description);
 const byteLen = (s) => Buffer.byteLength(s, 'utf8');

package/lib/skills/core.js

@@ -1653,6 +1653,38 @@ async function setPolicySkillEnabled(root, name, enabled, log) {
 export async function setSkillEnabled(root, name, enabled, log) {
     return setPolicySkillEnabled(root, name, enabled, log);
 }
+/**
+ * 批量显式停用技能（v0.8.5：新建 / 导入 / 回收站恢复默认不启动 —— 用户裁定）。
+ * 直接写 disabledSkills 名单（与 setSkillEnabled 同一张表），不做 frontmatter 等
+ * 二次校验——调用方传入的必然是刚落盘/刚恢复的条目。
+ * 必须在调用方的写锁（service 的 write()）内执行。
+ * @param {{ root: string, name: string }[]} entries - root = 来源 key。
+ */
+export async function markSkillsDisabled(entries, log) {
+    const list = Array.isArray(entries) ? entries : [];
+    const clean = list
+        .map((e) => ({ root: String((e && e.root) || ""), name: String((e && e.name) || "") }))
+        .filter((e) => e.root !== "" && e.name !== "");
+    if (!clean.length)
+        return { ok: true };
+    const current = await readManagerState();
+    if (current.writable === false)
+        return invalidManagerStateWrite();
+    let dirty = false;
+    for (const e of clean) {
+        const prev = current.state.disabledSkills[e.root] || [];
+        if (prev.indexOf(e.name) >= 0)
+            continue;
+        current.state.disabledSkills[e.root] = [...prev, e.name].sort();
+        dirty = true;
+    }
+    if (dirty) {
+        await writeManagerState(current.state);
+        if (log)
+            log("skill-disable-default", `默认停用 ${clean.map((e) => `${e.root}/${e.name}`).join("、")}`);
+    }
+    return { ok: true };
+}
 /**
  * 同名技能「首选来源」：默认同名技能按来源 rank 取优先级最高者生效、其余显示为被覆盖；
  * 这里让用户显式指定哪个同名技能生效（preferred=false 取消，回到 rank 顺序）。