dsh-plugin-tool-management 0.16.6 → 0.18.0

package/lib/memories/archive-engine.js

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

package/lib/memories/archive.js

@@ -64,6 +64,9 @@ export function normalizeArchive(raw) {
         out.skills = normalizeStringList(obj.skills);
     if (obj.subagents != null)
         out.subagents = normalizeStringList(obj.subagents);
+    // 快捷提示词：`!= null` 才算定义（空表 = 定义了但全不勾 = 进入后全部停用，必须留住）。
+    if (obj.quickPrompts != null)
+        out.quickPrompts = normalizeStringList(obj.quickPrompts);
     if (obj.memories != null)
         out.memories = normalizeStringList(obj.memories);
     // 工具表方案是**标量**不是集合：空串 / 非字符串一律视为未绑定（段不存在）。
@@ -208,7 +211,12 @@ mcpNotes = [],
  */
 subagentStates = null, 
 /** 进场景前的模型工具表关停名单（null = 这次不进快照，退出也就不动工具表）。 */
-toolTableHidden = null) {
+toolTableHidden = null, 
+/**
+ * 进场景前**每一条**快捷提示词的开关（null = 档案没定义 quickPrompts 段 → 这一域不碰，
+ * 也就不进快照，退出同样一个字不动）。
+ */
+quickPromptStates = null) {
     return {
         mcp: Object.fromEntries(Object.entries(mcpRaw).map(([k, v]) => [k, v.slice()])),
         skills: { ...skills },
@@ -219,6 +227,7 @@ toolTableHidden = null) {
         ...(subagentStates ? { subagentsAll: { ...subagentStates } } : {}),
         ...(mcpNotes.length ? { mcpNotes: mcpNotes.map((x) => ({ id: x.id, note: x.note })) } : {}),
         ...(toolTableHidden ? { toolTableHidden: toolTableHidden.slice() } : {}),
+        ...(quickPromptStates ? { quickPromptsAll: { ...quickPromptStates } } : {}),
     };
 }
 // ── 记忆勾选（v3）──────────────────────────────────────────────────────────

package/lib/memories/discovery.js

@@ -0,0 +1,261 @@
+// 规则/记忆的**发现**：扫一个来源目录读成条目、把 frontmatter 投成规则、按老布局搬家。
+//
+// 声明从 memories/snapshot.ts 按行号区间搬来，正文一字未改（唯一的容差是
+// `--export-top-level` 加的 `export ` 前缀，moved-verify 逐字对拍）。
+//
+// 为什么与快照分两层：发现是「读外面进来的东西」（官方技能目录、AGENTS.md、旧布局），
+// 快照是「记下当前场景长什么样并写回索引」。两者各自演化的方向不同 —— 前者跟着**来源形状**
+// 变，后者跟着**索引字段**变。
+import { statSync } from 'node:fs';
+import { cp, lstat, mkdir, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { resolveDshHome, unquote } from '../skills/core.js';
+import { MAX_SOURCE_DEPTH, MAX_DIRECTORIES, MAX_ENTRIES, MAX_DESCRIPTION_LENGTH, DEFAULT_ORDER, GLOBAL_SCENE, LEGACY_BUNDLE_DOC, bundleDocName, SEGMENT_RULE_HINT, isValidGroupSegment } from './constants.js';
+import { pathExists } from './index-io.js';
+export const identity = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+export async function discover(memoriesRoot) {
+    const entries = new Map();
+    const shadowed = [];
+    const groups = new Set();
+    const scenes = [];
+    const warnings = [];
+    const rootPath = resolve(memoriesRoot);
+    try {
+        const st = await lstat(rootPath);
+        if (!st.isDirectory() || st.isSymbolicLink())
+            return { entries, shadowed, groups, scenes, warnings, truncated: false };
+    }
+    catch {
+        return { entries, shadowed, groups, scenes, warnings, truncated: false };
+    }
+    const queue = [
+        { path: rootPath, group: '', depth: 0, ancestors: new Set() },
+    ];
+    let directories = 0;
+    let itemCount = 0;
+    let truncated = false;
+    const addEntry = (entry) => {
+        const existing = entries.get(entry.id);
+        if (!existing) {
+            entries.set(entry.id, entry);
+            return;
+        }
+        if (entry.kind === 'bundle' && existing.kind === 'flat') {
+            shadowed.push({ ...existing, shadowed: true });
+            entries.set(entry.id, entry);
+            return;
+        }
+        if (entry.kind === 'flat' && existing.kind === 'bundle') {
+            shadowed.push({ ...entry, shadowed: true });
+        }
+    };
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        if (directories >= MAX_DIRECTORIES || itemCount >= MAX_ENTRIES) {
+            truncated = true;
+            break;
+        }
+        const current = queue[cursor];
+        let realDirectory;
+        let dirents = [];
+        try {
+            realDirectory = await realpath(current.path);
+            if (current.ancestors.has(identity(realDirectory)))
+                continue;
+            const dir = await readdir(current.path, { withFileTypes: true });
+            directories++;
+            for (const item of dir) {
+                if (itemCount >= MAX_ENTRIES) {
+                    truncated = true;
+                    break;
+                }
+                itemCount++;
+                dirents.push(item);
+            }
+        }
+        catch {
+            continue; // 失效链接或不可读目录不阻断其他来源
+        }
+        // bundle 检查：当前目录含 `<目录名>.md`（或旧版 `SKILL.md`）→ 它是规则叶子，父路径为场景。
+        //
+        // **根下的一级目录恒为场景**（`parentGroup === ''` 时不做 bundle 判断）——与
+        // `probeSceneFilesSync`（注入段）同口径。场景 `1` 里一条叫 `1` 的记忆（`memories/1/1.md`）
+        // 与「根层的 bundle `1`」在磁盘上同形，认成后者会把整个场景目录吃成叶子：同场景其余
+        // 记忆全从列表消失、多出一条「未归属场景」的同名记忆，新建记忆还会被误报「同名 bundle
+        // 遮蔽」（2026-09-16 用户实测）。根层因此没有 bundle，只有 legacy 裸 .md（见 rulesCheck 的 noScene）。
+        if (current.group !== '') {
+            const sepIdx = current.group.lastIndexOf('/');
+            const parentGroup = sepIdx >= 0 ? current.group.slice(0, sepIdx) : '';
+            const name = sepIdx >= 0 ? current.group.slice(sepIdx + 1) : current.group;
+            let docPath = '';
+            if (parentGroup !== '') {
+                for (const candidate of [bundleDocName(name), LEGACY_BUNDLE_DOC]) {
+                    const p = join(current.path, candidate);
+                    try {
+                        const st = await lstat(p);
+                        if (st.isFile() && !st.isSymbolicLink()) {
+                            docPath = p;
+                            break;
+                        }
+                    }
+                    catch { /* 该候选名不存在 → 试下一个 */ }
+                }
+            }
+            if (docPath !== '') {
+                const id = parentGroup ? `${parentGroup}/${name}` : name;
+                addEntry({ id, group: parentGroup, name, kind: 'bundle', docPath, entryPath: current.path });
+                continue;
+            }
+        }
+        if (current.group !== '') {
+            groups.add(current.group);
+            // 一级目录 = 场景名（多段场景名用 '/' 连接，见 isValidGroupPath）。
+            if (current.depth === 1)
+                scenes.push(current.group);
+        }
+        dirents.sort((a, b) => a.name.localeCompare(b.name));
+        const ancestors = new Set(current.ancestors).add(identity(realDirectory));
+        for (const item of dirents) {
+            if (item.name.startsWith('.'))
+                continue; // 隐藏目录/文件跳过
+            const path = join(current.path, item.name);
+            try {
+                const st = await lstat(path);
+                // 符号链接一律不跟随：注入路径（`probeSceneFilesSync`）本来就不跟随，两端必须同口径 ——
+                // 否则列表里会出现**永远注入不进去**的记忆（用户打开开关却什么也没发生）。顺带也关掉了
+                // 「链接指向根外、写操作顺着链接穿透出去」这条路（写入侧另有 realpath 断言兜底）。
+                if (st.isSymbolicLink())
+                    continue;
+                if (st.isDirectory()) {
+                    if (!isValidGroupSegment(item.name)) {
+                        warnings.push(`跳过非法目录名（${SEGMENT_RULE_HINT}）：${current.group ? current.group + '/' : ''}${item.name}`);
+                        continue;
+                    }
+                    if (current.depth >= MAX_SOURCE_DEPTH || queue.length >= MAX_DIRECTORIES) {
+                        truncated = true;
+                        continue;
+                    }
+                    queue.push({
+                        path,
+                        group: current.group ? `${current.group}/${item.name}` : item.name,
+                        depth: current.depth + 1,
+                        ancestors,
+                    });
+                    continue;
+                }
+                if (!st.isFile())
+                    continue;
+                if (!item.name.toLowerCase().endsWith('.md'))
+                    continue; // 只认 .md
+                const name = item.name.slice(0, -3);
+                const id = current.group ? `${current.group}/${name}` : name;
+                addEntry({ id, group: current.group, name, kind: 'flat', docPath: path, entryPath: path });
+            }
+            catch {
+                /* 来源在扫描期间失效时跳过 */
+            }
+        }
+    }
+    return { entries, shadowed, groups, scenes, warnings, truncated };
+}
+export function deriveDescription(body) {
+    const text = String(body ?? '').trim();
+    if (!text)
+        return '';
+    const heading = /^#\s+(.+)$/m.exec(text);
+    const raw = heading && heading[1].trim() ? heading[1].trim() : text.split(/\r?\n/, 1)[0].trim();
+    return raw.slice(0, MAX_DESCRIPTION_LENGTH);
+}
+export function deriveFromDoc(entry, doc) {
+    const declaredName = doc.map.name != null && String(doc.map.name).trim() !== '' ? unquote(String(doc.map.name)).trim() : '';
+    const name = declaredName || entry.name;
+    let description = doc.map.description != null ? unquote(String(doc.map.description)).trim() : '';
+    let descriptionDerived = false;
+    if (description === '') {
+        description = deriveDescription(doc.body);
+        descriptionDerived = true;
+    }
+    const globs = doc.map.globs != null && String(doc.map.globs).trim() !== '' ? String(doc.map.globs).trim() : undefined;
+    let whenToUse;
+    if (doc.map.whenToUse != null && String(doc.map.whenToUse).trim() !== '') {
+        whenToUse = String(doc.map.whenToUse).trim();
+    }
+    else if (globs) {
+        whenToUse = `适用路径：${globs}`;
+    }
+    const metadata = doc.map.metadata !== undefined ? doc.map.metadata : undefined;
+    return { name, description, descriptionDerived, whenToUse, globs, metadata };
+}
+export function projectRule(entry, derived, idxEntry) {
+    // 体积按**正文文件**算（bundle 的附件不计：附件不进注入正文）。一次 stat 一条记忆，
+    // 结果随快照的 1s TTL 缓存一起复用；读不到就不带这个字段，别把"不知道"报成 0 B。
+    let size;
+    try {
+        size = statSync(entry.docPath).size;
+    }
+    catch {
+        size = undefined;
+    }
+    const rule = {
+        id: entry.id,
+        group: entry.group,
+        name: derived.name,
+        form: entry.kind,
+        path: entry.docPath,
+        ...(size !== undefined ? { bytes: size } : {}),
+        description: derived.description,
+        ...(derived.descriptionDerived ? { descriptionDerived: true } : {}),
+        ...(derived.whenToUse !== undefined ? { whenToUse: derived.whenToUse } : {}),
+        ...(derived.globs !== undefined ? { globs: derived.globs } : {}),
+        ...(derived.metadata !== undefined ? { metadata: derived.metadata } : {}),
+        enabled: idxEntry?.enabled ?? true,
+        order: idxEntry?.order ?? DEFAULT_ORDER,
+        tags: Array.isArray(idxEntry?.tags) ? idxEntry.tags : [],
+        pinned: idxEntry?.pinned === true,
+        note: typeof idxEntry?.note === 'string' ? idxEntry.note : '',
+        ...(typeof idxEntry?.updatedAt === 'string' ? { updatedAt: idxEntry.updatedAt } : {}),
+    };
+    return rule;
+}
+export async function relocateLegacyLayout(memoriesRoot) {
+    const home = resolveDshHome();
+    const legacyRoots = [join(home, 'scene-memory'), join(home, 'rules')];
+    for (const legacyRoot of legacyRoots) {
+        if (!(await pathExists(legacyRoot)))
+            continue;
+        if (identity(resolve(legacyRoot)) === identity(resolve(memoriesRoot)))
+            continue; // 自定义 roots 落在旧路径 → 不自我搬移
+        let items;
+        try {
+            items = await readdir(legacyRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const item of items) {
+            if (item.name.startsWith('.'))
+                continue;
+            const src = join(legacyRoot, item.name);
+            // 根层 .md = 旧的「全局」桶 → 搬进 `global/`，文件名保留（否则多套一层目录）。
+            // 其余条目（场景目录）整体搬进 memories/，目录名保留。
+            const isRootMd = item.isFile() && item.name.toLowerCase().endsWith('.md');
+            const destDir = isRootMd ? join(memoriesRoot, GLOBAL_SCENE) : memoriesRoot;
+            const dest = join(destDir, item.name);
+            try {
+                if (await pathExists(dest))
+                    continue;
+                await mkdir(destDir, { recursive: true });
+                try {
+                    await rename(src, dest);
+                }
+                catch {
+                    // 跨设备/被占用 → 复制后删源；复制失败则保留源文件（宁可重复，不可丢失）。
+                    await cp(src, dest, { recursive: true });
+                    await rm(src, { recursive: true, force: true });
+                }
+            }
+            catch {
+                /* 单项失败不阻断其余项（如文件被外部程序锁住，下次启动再试） */
+            }
+        }
+    }
+}

package/lib/memories/export-plan.js

@@ -0,0 +1,42 @@
+// 记忆导出的落盘映射：把「导出哪几条记忆」算成 zip 里的条目与缺失清单。
+//
+// 从 memories/service.ts 整段搬来，一行未改。它是纯函数（不碰磁盘）——flat / bundle 两种
+// 形态与「场景名本身可含 /」的口径都写在它自己的注释里，那条口径两边必须一致。
+import { dirname } from 'node:path';
+/**
+ * 记忆导出的落盘映射（`bundle-export` 的 `kind: 'memories'` 用，见 design-plan D14）。
+ *
+ * 记忆有两种形态（见文件头）：flat = `<场景>/<name>.md`，bundle = `<场景>/<name>/<name>.md`；
+ * 而且**场景名本身可含 `/`**（多段场景名，见 `isValidGroupPath`）。所以「按 id 的最后一个
+ * `/` 切出场景与名字、再拼 `.md`」是错的：bundle 会被读成 `<场景>/<name>.md` → 读不到 →
+ * 该项目静默丢失（只在 `missing` 里留个名，界面按「导出成功」显示）。
+ *
+ * 这里一律按索引里那条规则自己的 `path` 与 `form` 决定；bundle 只交出目录，由调用方
+ * 把目录内的文件全部打包（与技能分支同口径）。索引里没有、或已被同名 bundle 遮蔽的 id
+ * 进 `missing`——遮蔽的 flat 不会被加载，导出去只会让人以为它能用。
+ *
+ * 纯函数（不碰磁盘），可直接断言。
+ */
+export function planMemoryExport(names, rules) {
+    const list = Array.isArray(names) ? names.map((n) => String(n).trim()).filter(Boolean) : [];
+    const byId = new Map();
+    for (const row of (Array.isArray(rules) ? rules : [])) {
+        const id = row && typeof row.id === 'string' ? row.id : '';
+        if (id !== '')
+            byId.set(id, row);
+    }
+    const entries = [];
+    const missing = [];
+    for (const id of list) {
+        const row = byId.get(id);
+        const abs = row && typeof row.path === 'string' ? row.path : '';
+        if (!row || abs === '' || row.shadowed === true) {
+            missing.push(id);
+            continue;
+        }
+        entries.push(row.form === 'bundle'
+            ? { id, zip: id, abs: dirname(abs), kind: 'dir' }
+            : { id, zip: `${id}.md`, abs, kind: 'file' });
+    }
+    return { entries, missing };
+}