dsh-plugin-tool-management 0.8.0 → 0.9.0

package/lib/mcp/state-section.js

@@ -1,17 +1,50 @@
+// src/mcp/state-section.ts —— MCP 服务器状态段（注入通道的数据源，见 src/context-inject.ts）。
+//
+// 为什么需要它：启停 MCP 只改变**请求里的工具 schema 块**，没有任何显式状态陈述。
+// 所以在模型视角里，「配置了但被关掉」和「根本没配过」**完全等价** —— 它连"有哪些
+// MCP server"都不知道，更不知道用户为每台 server 写了什么备注。
+//
+// **备注才是本项的真正价值**：备注输入框的 placeholder 就是
+// 「例如：A 不可用时改用 B 兜底」—— 那是用户写给「未来的模型」的**决策提示**。
+// 这类信息在任何工具 schema 里都拿不到：工具只暴露 `mcp__<server>__<tool>` 的名字与
+// 参数，永远不会说「A 挂了改用 B」。所以「列出 server」只是载体。
+//
+// 范围（2026-09-15 用户裁定）：
+//   - **只列「当前真正可用」的 server**：配置上已启用 **且** 有**未被停用**的工具
+//     （enabledToolCount > 0；场景档案收窄与手动逐工具开关都会写停用表，这里如实扣减）。
+//     没开的不进（用户明确要求）；工具全被停用的也不进（模型调不到，留着只会谎报数量）。
+//   - 只列 **server 名 + 工具数 + 备注**；**具体工具名绝不注入** ——
+//     已启用 server 的工具本来就在模型自己的工具 schema 里（`mcp__<server>__<tool>`），
+//     段里再列一遍是重复；模型按前缀就能对上号。
+//   - 工具数只算**当前可用**的：被停用的那一部分不显示（它就是模型 schema 里没有的），
+//     数字必须与模型能调到的工具对得上。
+//   - 无备注 → 只有名字 + 工具数（正是「不写就只知道名字」）。
+//   - 不写「已启用」字样：能进段的都是可用的，标状态是废话。
+//   - 无可用 server → 返回 `''`（renderPrompt 删空段，零 token 成本）。
+//
+// 同步性：`text()` 必须同步返回（renderPrompt 不接受 Promise），而 MCP 清单是异步读盘 →
+// 与子智能体目录同构的 stale-while-revalidate（见 src/subagents/catalog.ts）。
 /** 段里最多列几台 server；超出部分只报数量。 */
 export const DEFAULT_MCP_MAX_ENTRIES = 50;
 /** 备注截断长度。备注是自由文本，界面侧另有 maxLength(500) 兜底，段侧再截一刀。 */
 export const DEFAULT_MCP_NOTE_MAX_LENGTH = 200;
 /**
- * 备注的固定前缀。
+ * 备注的固定前缀（模型侧口径，用户裁定 2026-09-16：字段与段统一叫 user-hint / 用户提示）。
  *
- * 备注是自由文本，注入后以**系统提示词的身份**生效。若用户写了指令式内容
- * （如「忽略以上全部规则」），会被当作系统级指令执行。威胁模型上是**自伤**而非被攻击
- * （内容由用户自己写、仅本机可写），但加固定前缀能降低被读成指令的概率。
+ * 原为「备注：」，取「降低被读成指令的概率」——备注是自由文本，注入后**由插件背书**地到达模型。
+ * 改叫「用户提示：」是有意为之：它本来就该被读成**用户的决策提示**（「A 挂了改用 B」），
+ * 而不是系统策略。威胁模型不变（内容由用户自己写、仅本机可写，属**自伤**而非被攻击），
+ * 但前缀如实标明来源，模型据此权衡即可。
  */
-export const MCP_NOTE_PREFIX = '用户备注：';
-/** 备注压成单行（换行 → 空格）并截断。 */
-function normalizeNote(value, maxLength) {
+export const MCP_NOTE_PREFIX = '用户提示：';
+/**
+ * 备注压成单行（换行 → 空格）并截断。
+ *
+ * 导出给模型侧的 `mcp_manager_list` 复用：压制型预设下不注入时，那条工具
+ * 是备注唯一的读取路径，两处的压行/截断口径必须一致，否则同一句备注在界面、段、工具里
+ * 会是三个样子。
+ */
+export function normalizeMcpNote(value, maxLength) {
     const flat = String(value ?? '').replaceAll(/\s+/g, ' ').trim();
     if (!flat)
         return '';
@@ -25,8 +58,10 @@ function normalizeNote(value, maxLength) {
 export function renderMcpStateSection(rows, opts = {}) {
     const maxEntries = opts.maxEntries ?? DEFAULT_MCP_MAX_ENTRIES;
     const noteMaxLength = opts.noteMaxLength ?? DEFAULT_MCP_NOTE_MAX_LENGTH;
-    // 「当前真正可用」= 已启用 且 有工具。任一不满足都不进段。
-    const usable = rows.filter((r) => !r.disabled && Number(r.toolCount) > 0);
+    // 工具数取**可用数**（停用表扣减后的）；旧调用方只给 toolCount 时退回它，行为不变。
+    const countOf = (r) => (Number.isFinite(Number(r.enabledToolCount)) ? Number(r.enabledToolCount) : (Number(r.toolCount) || 0));
+    // 「当前真正可用」= 已启用 且 还有没被停用的工具。任一不满足都不进段。
+    const usable = rows.filter((r) => !r.disabled && countOf(r) > 0);
     if (!usable.length)
         return '';
     // 按展示名排序：即使补丁文件里的行序变化，段文本也保持逐字节稳定（前缀缓存契约）。
@@ -37,9 +72,9 @@ export function renderMcpStateSection(rows, opts = {}) {
     });
     const shown = sorted.slice(0, Math.max(0, maxEntries));
     const lines = shown.map((r) => {
-        const count = Number(r.toolCount) || 0;
+        const count = countOf(r);
         const head = '- **' + String(r.serverName ?? r.id) + '**（' + count + ' 个工具）';
-        const note = normalizeNote(r.notes, noteMaxLength);
+        const note = normalizeMcpNote(r.notes, noteMaxLength);
         return note ? head + ' — ' + MCP_NOTE_PREFIX + note : head;
     });
     const out = ['## MCP 服务器', '', ...lines];
@@ -84,7 +119,3 @@ export function createMcpStateCatalog(deps, opts = {}) {
         warm: () => revalidate(),
     };
 }
-/** 供 `createPromptSectionRegistrar` 使用的段声明。 */
-export function mcpStateSectionOf(catalog, order) {
-    return { name: 'tool-management:mcp-state', order, text: () => catalog.text() };
-}

package/lib/rules/archive-engine.js

@@ -3,7 +3,7 @@
 //                     退出 = 恢复快照 → 落盘自由模式；切换 = 先退后进。
 // 失败语义（fail-closed）：任一步失败即反向恢复运行时并写回旧切片；回滚不全会如实写进错误文本。
 // v2：MCP 段两级（服务器勾选 + '*' / 工具明细），停用表存勾选集的补集，通配由 index.ts 的 guard/restrict 原生支持。
-import { computeMcpPlan, computeSkillsPlan, normalizeArchive, snapshotRuntime, hasSection, } from './archive.js';
+import { computeMcpPlan, computeSkillsPlan, normalizeArchive, snapshotRuntime, mergeSnapshotSwitches, } from './archive.js';
 const msg = (e) => String((e && e.message) || e);
 export function createArchiveEngine(deps) {
     let chain = Promise.resolve();
@@ -34,10 +34,20 @@ 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 });
-        // 子智能体开关：只停「进入时被这次启用过的」那些（老 snapshot 没有这栏 → []，按旧行为跳过）。
-        const personas = snapshot.subagents ?? [];
-        if (personas.length) {
-            await deps.applySubagentSwitches(personas.map((n) => ({ name: n, enabled: false })));
+        // 备注：按快照原值写回（null = 原本没有，删除）。模式期间的手动备注改动不保留（同 §2.2）。
+        const notes = snapshot.mcpNotes ?? [];
+        if (notes.length) {
+            await deps.applyMcpNotes(notes.map((x) => ({ id: x.id, note: x.note })));
+        }
+        // 子智能体开关：先停「进入时被这次关掉的」那些（档案没勾 = 本场景不开），
+        // 再开回「进入时被这次启用过的」那批 —— 与进入时的顺序相反，两个方向都要还原。
+        const personasOff = snapshot.subagents ?? [];
+        if (personasOff.length) {
+            await deps.applySubagentSwitches(personasOff.map((n) => ({ name: n, enabled: false })));
+        }
+        const personasOn = snapshot.subagentsOn ?? [];
+        if (personasOn.length) {
+            await deps.applySubagentSwitches(personasOn.map((n) => ({ name: n, enabled: true })));
         }
     }
     /**
@@ -61,6 +71,50 @@ export function createArchiveEngine(deps) {
         const base = `${stage}失败：${msg(err)}`;
         return { ok: false, error: problems.length ? `${base}；回滚未完成（${problems.join('；')}）` : `${base}，已回滚` };
     }
+    /**
+     * 把**当前模式**的档案就地重新应用一次（改档案 → 立即生效）。
+     *
+     * 存在的理由（用户裁定 2026-09-16）：场景内页面上的开关被禁用，改环境只能改档案；
+     * 若档案改完不立刻生效，用户就得「退出场景再进一次」才看得到结果。
+     *
+     * 口径与进入模式**完全一致**（四域同口径）：勾选集 = 该场景下开着的东西，段未定义 =
+     * 一个都没勾 = 全部停用。返回这次要改的**上层行**（服务器级 / 来源级，带改动前的状态），
+     * 由调用方并进快照 —— 退出仍按「进场景前」精确还原（见 mergeSnapshotSwitches）。
+     * 人设域不在这里处理：它需要往快照里补记（谁被开 / 关过），由 index.ts 的
+     * `scene-archive-save` 包装统一做。
+     */
+    async function reapplyActiveArchive(archive) {
+        const mcpPlan = computeMcpPlan((archive && archive.mcp) || {}, {
+            configuredServers: await deps.configuredServers(),
+            knownTools: await deps.serverKnownTools(),
+            serverStates: await deps.mcpServerStates(),
+        });
+        const skillsPlan = computeSkillsPlan((archive && archive.skills) || [], await deps.knownSkillKeys(), await deps.skillSourceStates());
+        if (mcpPlan.serverSwitches.length) {
+            await deps.applyMcpServerSwitches(mcpPlan.serverSwitches.map((s) => ({ id: s.id, level: s.level, enabled: s.enabled })));
+        }
+        if (skillsPlan.sourceSwitches.length) {
+            await deps.applySkillSourceSwitches(skillsPlan.sourceSwitches.map((s) => ({ root: s.root, enabled: s.enabled })));
+        }
+        await deps.applyMcpEntries(mcpPlan.entries);
+        await deps.applySkills(skillsPlan.target);
+        if (archive && archive.mcpNotes) {
+            // 与进入时同一口径：场景备注只作用于 mcp 段里实际勾选的服务器。
+            const selected = archive.mcp ? Object.keys(archive.mcp) : [];
+            const entries = [];
+            for (const [server, note] of Object.entries(archive.mcpNotes)) {
+                if (selected.indexOf(server) < 0)
+                    continue;
+                const id = await deps.mcpIdOfServer(server);
+                if (id !== undefined)
+                    entries.push({ id, note });
+            }
+            // 不在本次覆盖里的旧场景备注行**不这里删**（退出时会按快照整体回原位）。
+            if (entries.length)
+                await deps.applyMcpNotes(entries);
+        }
+        return { mcpServers: mcpPlan.serverSwitches, skillSources: skillsPlan.sourceSwitches };
+    }
     const ops = {
         // 读：页面渲染模式与档案
         'scene-mode-get': async () => {
@@ -89,6 +143,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;
@@ -116,7 +182,28 @@ export function createArchiveEngine(deps) {
             else
                 slice.archives[scene] = archive;
             await deps.saveSlice(slice);
-            return { ok: true, scene, archive: slice.archives[scene] ?? null, stale };
+            // 改的正是**当前模式**的档案 → 就地重新应用（场景内只能改档案，改完必须生效）。
+            // 这次新改到的**上层行**（服务器级 / 来源级）并进快照：退出仍按「进场景前」还原，
+            // 进场景时改过的行 + 这次新改的行都要有记录（已记过的行保持原值，见 mergeSnapshotSwitches）。
+            // 应用失败不回滚档案：档案是用户的意图记录，运行时状态下次进场景会对齐；
+            // 如实把错误报出去，别假装生效了。
+            let applyError = null;
+            if (slice.mode.scene === scene) {
+                try {
+                    const changed = await reapplyActiveArchive(slice.archives[scene]);
+                    const snapshot = slice.mode.snapshot;
+                    if (snapshot && (changed.mcpServers.length || changed.skillSources.length)) {
+                        await deps.saveSlice({
+                            ...slice,
+                            mode: { ...slice.mode, snapshot: mergeSnapshotSwitches(snapshot, changed.mcpServers, changed.skillSources) },
+                        });
+                    }
+                }
+                catch (e) {
+                    applyError = msg(e);
+                }
+            }
+            return { ok: true, scene, archive: slice.archives[scene] ?? null, stale, ...(applyError ? { applyError } : {}) };
         }),
         // 写：进入/退出/切换当前模式
         // scene=null 退出；目标场景没有 mcp/skills 段 = 结构化拒绝（设计 §2.4：此类场景不显示模式按钮）。
@@ -153,54 +240,87 @@ export function createArchiveEngine(deps) {
             }
             if (!target)
                 return { ok: true, mode: current, applied: null, stale: [] };
-            // ② 进入目标模式：校验 → 快照 → 先落盘 mode（中途失败也留可退快照）→ 应用已定义段 → 记忆收窄。
+            // ② 进入目标模式：校验 → 算计划 → 拍快照 → 先落盘 mode（中途失败也留可退快照）→ 应用 → 记忆收窄。
+            //    三个域（MCP / 技能 / 人设）都按「与档案勾选集完全一致」应用，未定义 = 全关；
+            //    备注段只在定义时覆盖。所以这里没有「纯记忆场景不用动运行时」这条分支 —— 恒拍快照。
             const archive = slice.archives[target];
             if (!(await deps.sceneExists(target)))
                 return { ok: false, error: `场景不存在: ${target}` };
-            // 无档案段（纯记忆 / 纯人设场景）**也要能进入**：不应用档案、不建快照，但
-            // `mode.scene` 与 `active` 照常写入。原因有二：
-            //   ① 场景开关（P6）是唯一入口，纯记忆场景点开关不能报错；
-            //   ② 顶部「当前模式」横幅的渲染条件是 `mode.scene`，不写就永远不显示 ——
-            //      用户裁定：无档案场景开开关也要显示横幅，副标题走 `scenes.mode.noProfile`。
-            const appliesArchive = !!archive && (hasSection(archive, 'mcp') || hasSection(archive, 'skills') || hasSection(archive, 'subagents'));
+            // 子智能体段：人设域按**「置为与勾选集完全一致」**应用（与 MCP / 技能同一条语义）——
+            // 勾了的启用、没勾的（含整段未定义 = 一个都没勾）停用。此前只启用、从不关闭，
+            // 于是用户实测「场景没绑定任何人设，进场景后原先开着的人设照样开着」。
+            // 快照两个方向都记：被打开的（改动前关着）退出停回，被关掉的（改动前开着）退出开回。
+            const boundPersonas = archive && Array.isArray(archive.subagents) ? archive.subagents : [];
+            let unboundPersonas = [];
+            let personaRestore = [];
+            let personaRestoreOn = [];
+            try {
+                const known = await deps.knownPersonas();
+                unboundPersonas = [...known].filter((n) => boundPersonas.indexOf(n) < 0).sort();
+                personaRestore = await deps.disabledPersonas(boundPersonas);
+                personaRestoreOn = await deps.enabledPersonas(unboundPersonas);
+            }
+            catch (e) {
+                return { ok: false, error: `读取人设开关状态失败（未改动任何东西）：${msg(e)}` };
+            }
+            // **四域同口径**（用户实测三连，2026-09-16）：档案的勾选集 = 该场景下开着的东西，
+            // **段未定义 = 一个都没勾 = 全部停用**。此前只有人设域按这条应用，MCP / 技能沿用旧口径
+            // 「未定义 = 该域不碰」——于是「场景档案没开 MCP 工具集 / 技能集」时，进场景后原本在跑的
+            // 服务器与技能照样开着（用户报的 ②③）。开关既然已收归档案（场景内页面不可改），
+            // 档案就必须说得清「这个场景要什么」——未定义只能读成「什么都不要」。
+            // 备注段是例外：未定义 = 不覆盖任何备注（没有东西"因为未定义而需要关掉"）。
+            const mcpSpec = (archive && archive.mcp) || {};
+            const skillsSpec = (archive && archive.skills) || [];
             // 先算计划、再拍快照：快照只记**将被改动**的服务器行 / 来源 / 人设（带改动前的状态），
             // 退出时按记录精确恢复 —— 不动用户手动设置的其他行。
             let mcpPlan = null;
             let skillsPlan = null;
-            if (appliesArchive && archive) {
+            try {
+                mcpPlan = computeMcpPlan(mcpSpec, {
+                    configuredServers: await deps.configuredServers(),
+                    knownTools: await deps.serverKnownTools(),
+                    serverStates: await deps.mcpServerStates(),
+                });
+                skillsPlan = computeSkillsPlan(skillsSpec, await deps.knownSkillKeys(), await deps.skillSourceStates());
+            }
+            catch (e) {
+                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 {
-                    if (archive.mcp) {
-                        mcpPlan = computeMcpPlan(archive.mcp, {
-                            configuredServers: await deps.configuredServers(),
-                            knownTools: await deps.serverKnownTools(),
-                            serverStates: await deps.mcpServerStates(),
-                        });
+                    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 (archive.skills) {
-                        skillsPlan = computeSkillsPlan(archive.skills, await deps.knownSkillKeys(), await deps.skillSourceStates());
+                    if (targets.length) {
+                        noteTargets = targets;
+                        noteBefore = before;
                     }
                 }
                 catch (e) {
-                    return { ok: false, error: `读取运行时状态失败（未改动任何东西）：${msg(e)}` };
-                }
-            }
-            // 子智能体段：进入时把档案勾选的人设**启用**（子智能体页同步亮起）。
-            // 快照只记「改动前停用」的那些 —— 退出时按名单停回，不动其他行。
-            const boundPersonas = archive && Array.isArray(archive.subagents) ? archive.subagents : [];
-            let personaRestore = [];
-            if (boundPersonas.length) {
-                try {
-                    personaRestore = await deps.disabledPersonas(boundPersonas);
-                }
-                catch (e) {
-                    return { ok: false, error: `读取人设开关状态失败（未改动任何东西）：${msg(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)
-                : null;
+            // 快照**恒拍**：三个域都按「与勾选集完全一致」应用（未定义 = 全关），所以任何场景
+            // 进入都可能改动运行时（哪怕只是停掉几台服务器 / 几个技能），退出都得能精确还原。
+            const snapshot = 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, personaRestoreOn, noteBefore);
             const entered = { ...slice, mode: { scene: target, snapshot }, active: [target] };
             try {
                 await deps.saveSlice({ ...slice, mode: entered.mode });
@@ -212,45 +332,50 @@ export function createArchiveEngine(deps) {
             try {
                 // ① 先切**上层**（服务器级 / 来源级）——下层只有在上层开着时才有意义：
                 //    服务器没起来，它的工具不存在，工具级停用无从谈起；来源关着，技能级 enable 会被吞掉。
-                if (mcpPlan && mcpPlan.serverSwitches.length) {
+                if (mcpPlan.serverSwitches.length) {
                     await deps.applyMcpServerSwitches(mcpPlan.serverSwitches.map((s) => ({ id: s.id, level: s.level, enabled: s.enabled })));
                 }
-                if (skillsPlan && skillsPlan.sourceSwitches.length) {
+                if (skillsPlan.sourceSwitches.length) {
                     await deps.applySkillSourceSwitches(skillsPlan.sourceSwitches.map((s) => ({ root: s.root, enabled: s.enabled })));
                 }
                 // ② 再写**下层**（工具级停用表 / 技能级策略）。
-                if (mcpPlan) {
-                    stale.push(...mcpPlan.stale);
-                    await deps.applyMcpEntries(mcpPlan.entries);
+                stale.push(...mcpPlan.stale);
+                await deps.applyMcpEntries(mcpPlan.entries);
+                stale.push(...skillsPlan.stale);
+                await deps.applySkills(skillsPlan.target);
+                // ③ 子智能体开关：**勾了的启用、未勾的停用**（子智能体页与目录段同步）。
+                //    先开后关：勾选名单不可能同时出现在两边，顺序只影响中间态的观感。
+                if (personaRestore.length) {
+                    await deps.applySubagentSwitches(personaRestore.map((n) => ({ name: n, enabled: true })));
                 }
-                if (skillsPlan) {
-                    stale.push(...skillsPlan.stale);
-                    await deps.applySkills(skillsPlan.target);
+                if (personaRestoreOn.length) {
+                    await deps.applySubagentSwitches(personaRestoreOn.map((n) => ({ name: n, enabled: false })));
                 }
-                // ③ 子智能体开关：把档案勾选的人设启用（子智能体页与目录段同步亮起）。
-                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）。
-                return snapshot ? await rollback(slice, snapshot, '应用档案', e) : { ok: false, error: `应用档案失败：${String(e?.message || e)}` };
+                return await rollback(slice, snapshot, '应用档案', e);
             }
             // ③ 记忆启用集收窄为 {S}（`_shared` 由 resolveActiveScenes 恒常加入；退出不恢复）。
             try {
                 await deps.saveSlice(entered);
             }
             catch (e) {
-                return snapshot ? await rollback(slice, snapshot, '记忆收窄落盘', e) : { ok: false, error: `记忆收窄落盘失败：${String(e?.message || e)}` };
+                return await rollback(slice, snapshot, '记忆收窄落盘', e);
             }
             return {
                 ok: true,
                 mode: entered.mode,
-                applied: { mcp: !!(archive && archive.mcp), skills: !!(archive && archive.skills), subagents: !!(archive && archive.subagents) },
+                // 三个域都是「按勾选集全量应用」（未定义 = 全关），所以都算已应用；
+                // 备注段未定义 = 不覆盖任何备注，如实报它是否定义。
+                applied: { mcp: true, skills: true, subagents: true, mcpNotes: !!(archive && archive.mcpNotes) },
                 // 上层实际切换了几个（0 = 本来就已经是目标状态，界面不必提示"已停用 N 台"）。
                 switched: {
-                    mcpServers: mcpPlan ? mcpPlan.serverSwitches.length : 0,
-                    skillSources: skillsPlan ? skillsPlan.sourceSwitches.length : 0,
+                    mcpServers: mcpPlan.serverSwitches.length,
+                    skillSources: skillsPlan.sourceSwitches.length,
                 },
                 stale,
                 narrowedTo: [target],

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)
@@ -138,19 +157,56 @@ export function computeSkillsPlan(skills, knownSkillKeys, sourceStates) {
     }
     return { target, stale, sourceSwitches };
 }
+/**
+ * 把「这次要改的上层行」并进快照 —— **已记录的行保持原值**（先记的才是进场景前的状态）。
+ *
+ * 为什么需要：进入模式时快照只记了**当时将要改动**的行；模式进行中用户改档案（改档案 = 立即生效）
+ * 又可能新改到别的服务器 / 来源级行。退出必须回到「进场景前」，所以这些新改的行也得有记录。
+ * 反之，若某行在进入时就记过，它的 `*Before` 才是进场景前的值 —— 这次的中间态值必须丢弃。
+ */
+export function mergeSnapshotSwitches(snapshot, mcpServers = [], skillSources = []) {
+    const servers = (snapshot.mcpServers ?? []).map((x) => ({ ...x }));
+    const seenServer = new Set(servers.map((x) => x.id + '\u0000' + x.level));
+    for (const s of mcpServers) {
+        const key = s.id + '\u0000' + s.level;
+        if (seenServer.has(key))
+            continue;
+        seenServer.add(key);
+        servers.push({ id: s.id, level: s.level, disabled: s.disabledBefore });
+    }
+    const sources = (snapshot.skillSources ?? []).map((x) => ({ ...x }));
+    const seenSource = new Set(sources.map((x) => x.root));
+    for (const s of skillSources) {
+        if (seenSource.has(s.root))
+            continue;
+        seenSource.add(s.root);
+        sources.push({ root: s.root, enabled: s.enabledBefore });
+    }
+    return {
+        ...snapshot,
+        ...(servers.length ? { mcpServers: servers } : {}),
+        ...(sources.length ? { skillSources: sources } : {}),
+    };
+}
 export function snapshotRuntime(mcpRaw, skills, 
 /** **将被档案改动**的服务器行，带改动前的 `disabled`。 */
 mcpServers = [], 
 /** **将被档案改动**的来源，带改动前的 `enabled`。 */
 skillSources = [], 
 /** **将被档案启用**的人设名（改动前停用的子集；退出时按此停回）。 */
-subagents = []) {
+subagents = [], 
+/** **将被档案停用**的人设名（改动前启用的子集；退出时按此重新打开）。 */
+subagentsOn = [], 
+/** **将被档案改动**的备注行，带改动前的备注（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() } : {}),
+        ...(subagentsOn.length ? { subagentsOn: subagentsOn.slice() } : {}),
+        ...(mcpNotes.length ? { mcpNotes: mcpNotes.map((x) => ({ id: x.id, note: x.note })) } : {}),
     };
 }
 // ── 记忆勾选（v3）──────────────────────────────────────────────────────────