dsh-plugin-tool-management 0.17.0 → 0.18.0

package/lib/ops/snapshot.js

@@ -26,10 +26,11 @@ const F_SCENES = 'scenes.json';
 const D_MEMORIES = 'memories';
 const D_SUBAGENTS = 'subagents';
 const D_PROMPTS = 'prompts';
+const D_QUICK = 'quick-prompts';
 const D_SKILLS = 'skills';
-/** 三个"文件域"：整个目录打进一份 zip，键是相对路径。 */
-const FILE_DOMAINS = [D_MEMORIES, D_SUBAGENTS, D_PROMPTS];
-const ALL_DOMAINS = ['mcp', D_MEMORIES, D_SUBAGENTS, D_PROMPTS, D_SKILLS, 'settings', 'scenes'];
+/** 四个"文件域"：整个目录打进一份 zip，键是相对路径。 */
+const FILE_DOMAINS = [D_MEMORIES, D_SUBAGENTS, D_PROMPTS, D_QUICK];
+const ALL_DOMAINS = ['mcp', D_MEMORIES, D_SUBAGENTS, D_PROMPTS, D_QUICK, D_SKILLS, 'settings', 'scenes'];
 function stamp() {
     return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
 }
@@ -86,7 +87,7 @@ function namesOf(res, prefer) {
         return [];
     const bags = [res.data, res].filter(Boolean);
     for (const bag of bags) {
-        for (const key of ['rows', 'personas', 'presets', 'scenes', 'skills', 'list', 'entries', 'items']) {
+        for (const key of ['rows', 'personas', 'presets', 'prompts', 'scenes', 'skills', 'list', 'entries', 'items']) {
             const arr = bag[key];
             if (!Array.isArray(arr))
                 continue;
@@ -236,11 +237,12 @@ export function createSnapshotOps(deps) {
             return { ok: false, error: '写 mcp.json 失败: ' + deps.message(e) };
         }
         domains.mcp = mcpOut.length;
-        // ── 文件域：记忆 / 子智能体 / 提示词，各打进一份 zip（键 = 相对路径）──────────
+        // ── 文件域：记忆 / 子智能体 / 提示词 / 快捷提示词，各打进一份 zip（键 = 相对路径）──
         const roots = {
             [D_MEMORIES]: deps.hubPath(D_MEMORIES),
             [D_SUBAGENTS]: deps.hubPath(D_SUBAGENTS),
             [D_PROMPTS]: deps.promptsDir(),
+            [D_QUICK]: deps.quickPromptsDir(),
         };
         for (const kind of FILE_DOMAINS) {
             const files = await walk(roots[kind]);
@@ -352,6 +354,7 @@ export function createSnapshotOps(deps) {
             mcp: namesOf(await deps.invokeOp('mcpm-list', {}), ['serverName']),
             [D_SUBAGENTS]: namesOf(await deps.invokeOp('subagent-list', {}), ['name']),
             [D_PROMPTS]: namesOf(await deps.invokeOp('agentsmd-list', {}), ['id']),
+            [D_QUICK]: namesOf(await deps.invokeOp('quickprompt-list', {}), ['id']),
             [D_MEMORIES]: namesOf(await deps.invokeOp('rules-list', {}), ['id']),
             scenes: sceneRecordsOf(await deps.invokeOp('rules-list', {})).map((r) => r.name),
         };
@@ -493,12 +496,13 @@ export function createSnapshotOps(deps) {
                 throw new Error(String((res && res.error) || 'subagent-import 失败'));
             return { imported: (res.imported || []).length, skipped: skipped + (res.skipped || []).length };
         });
-        await run(D_PROMPTS, async () => {
-            const zip = files[D_PROMPTS + '.zip'];
+        // 两个提示词域同形：`<id>/<正文>` + 可选 `<id>/meta.json`，一次一份地导入。差别只在
+        // 正文文件名与 op 名（快捷域没有独立的 import op，`create` 就是那个形状），所以共用一段。
+        const importPromptLike = (domain, docName, importOp, updateOp) => run(domain, async () => {
+            const zip = files[domain + '.zip'];
             if (!zip)
                 return { imported: 0, skipped: 0 };
             const entries = unzipSync(new Uint8Array(await readFile(zip)));
-            // 提示词的落点是 `<id>/AGENTS.md`（+ 可选 `<id>/meta.json`），而 `agentsmd-import` 一次一份。
             const bodies = {};
             const metas = {};
             let skipped = 0;
@@ -509,7 +513,7 @@ export function createSnapshotOps(deps) {
                     continue;
                 }
                 const text = Buffer.from(bytes).toString('utf8');
-                if (parts[1] === 'AGENTS.md')
+                if (parts[1] === docName)
                     bodies[parts[0]] = text;
                 else if (parts[1] === 'meta.json') {
                     try {
@@ -521,17 +525,17 @@ export function createSnapshotOps(deps) {
             let imported = 0;
             for (const id of Object.keys(bodies)) {
                 const desc = String((metas[id] && metas[id].description) || '');
-                const res = await deps.invokeOp('agentsmd-import', { id, content: bodies[id], description: desc });
+                const res = await deps.invokeOp(importOp, { id, content: bodies[id], description: desc });
                 if (res && res.ok) {
                     imported += 1;
                     continue;
                 }
-                // 同名预设 `agentsmd-import` 一律拒（它不覆盖）。覆盖模式下改走 upsert 那条 update 路径。
+                // 同名一律拒（两个 import 口都不覆盖）。覆盖模式下改走 upsert 那条 update 路径。
                 if (!overwrite) {
                     skipped += 1;
                     continue;
                 }
-                const upd = await deps.invokeOp('agentsmd-update', { id, nextId: id, content: bodies[id], description: desc });
+                const upd = await deps.invokeOp(updateOp, { id, nextId: id, content: bodies[id], description: desc });
                 if (upd && upd.ok)
                     imported += 1;
                 else
@@ -539,6 +543,8 @@ export function createSnapshotOps(deps) {
             }
             return { imported, skipped };
         });
+        await importPromptLike(D_PROMPTS, 'AGENTS.md', 'agentsmd-import', 'agentsmd-update');
+        await importPromptLike(D_QUICK, 'PROMPT.md', 'quickprompt-create', 'quickprompt-update');
         await run(D_MEMORIES, async () => {
             const zip = files[D_MEMORIES + '.zip'];
             if (!zip)

package/lib/prompts/quick-service.js

@@ -0,0 +1,211 @@
+// dsh-plugin-tool-management —— 快捷提示词库（hub/quick-prompts/）。
+//
+// 与「全局提示词预设」（`./service.ts`）是**两件事**，别混着看：
+//   预设 = 一份会覆盖写 `~/.dsh/AGENTS.md` 的指令基线，进上下文、被场景绑定、模型能在之间挑；
+//   快捷 = 用户存好的一段现成文字，只由**用户自己**在对话框 `/` 菜单里点出来贴进草稿。
+//
+// 所以它**不注入上下文、不进场景**，实现上靠"另起一份存储"来保证：预设服务的
+// `list()` 只扫 `hub/prompts/` 下的合法目录，注入取的是场景绑定的那份正文，模型工具
+// `prompt_manager_list` 复用的又是 `agentsmd-list` —— 四条路径各自只认 `hub/prompts/`，
+// 快捷词放在隔壁目录里就天然进不去。**不要**为了少一个目录把它塞进 prompts/ 加个标记位：
+// 那等于让四条路径各自学会过滤，漏一条就是"快捷词被当成基线注入"。
+// 条目那颗开关（`enabled`）只管"在不在对话框 `/` 菜单里出现"，同样不碰上面四条路径。
+//
+// `list()` 连**正文一起给**，不是偷懒省一次请求：宿主的 `settle()` 拿到 onPick 的返回值后
+// **同步**执行插入（input-trigger client.js），异步读正文来不及 —— 点的时候手里就得有那段字。
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isValidPresetId, normalizePresetId } from './preset-id.js';
+import { listTrashEntries, moveOutOfTrash, moveToTrash, purgeTrashEntry, readTrashEntry } from '../hub.js';
+/** 快捷提示词正文的文件名。与预设的 `AGENTS.md` 刻意不同名：这两个库不该被互换过。 */
+const FILENAME = 'PROMPT.md';
+/** 侧车（说明 + 启停），与正文同目录：正文本身一个字都不该被这些元信息污染。 */
+const META_FILE = 'meta.json';
+export function createQuickPromptsService(deps) {
+    const message = (e) => String((e && e.message) || e);
+    const idError = (raw) => {
+        const result = normalizePresetId(raw);
+        return result.ok ? null : result.error;
+    };
+    /** 侧车读回来的形状：缺字段一律按"没动过"解释（说明为空、开关为开）。 */
+    async function readMeta(id) {
+        try {
+            const parsed = JSON.parse(await readFile(join(deps.dir, id, META_FILE), 'utf8'));
+            return {
+                description: typeof parsed.description === 'string' ? parsed.description : '',
+                // 只有明确写着 false 才算关：这颗开关之前的老库根本没有这个字段，默认必须是"照常在 / 里出现"。
+                enabled: parsed.enabled !== false,
+            };
+        }
+        catch {
+            return { description: '', enabled: true };
+        }
+    }
+    /**
+     * 侧车写：`undefined` = 那一项不动（空串 / `true` 才是明确回到默认）。
+     * 两项都回到默认时连文件一起删 —— 不留空壳（原来"说明清空就删侧车"那条纪律照旧）。
+     */
+    async function writeMeta(id, patch) {
+        const cur = await readMeta(id);
+        const description = patch.description === undefined ? cur.description : String(patch.description).trim();
+        const enabled = patch.enabled === undefined ? cur.enabled : patch.enabled === true;
+        const body = {};
+        if (description !== '')
+            body.description = description;
+        if (enabled !== true)
+            body.enabled = false;
+        const file = join(deps.dir, id, META_FILE);
+        try {
+            if (!Object.keys(body).length) {
+                await rm(file, { force: true });
+                return;
+            }
+            await writeFile(file, JSON.stringify(body, null, 2) + '\n', 'utf8');
+        }
+        catch { /* 元信息写不进去不该让保存失败：正文才是本体 */ }
+    }
+    async function list() {
+        try {
+            let entries = [];
+            try {
+                entries = await readdir(deps.dir, { withFileTypes: true });
+            }
+            catch { /* 库还没建过 = 空 */ }
+            const ids = entries.filter((e) => e.isDirectory() && isValidPresetId(e.name)).map((e) => e.name);
+            const prompts = await Promise.all(ids.map(async (id) => {
+                const meta = await readMeta(id);
+                return {
+                    id,
+                    description: meta.description,
+                    enabled: meta.enabled,
+                    // 读不到的那条（正文被外部删了）给空串：界面上仍然列出来，用户能看见"它在但没内容"，
+                    // 而不是凭空少一条却查不出为什么。
+                    content: await readFile(join(deps.dir, id, FILENAME), 'utf8').catch(() => ''),
+                };
+            }));
+            prompts.sort((a, b) => a.id.localeCompare(b.id));
+            return { ok: true, prompts };
+        }
+        catch (e) {
+            return { ok: false, error: message(e) };
+        }
+    }
+    async function create(id, content, description) {
+        const bad = idError(id);
+        if (bad)
+            return { ok: false, error: '非法 id：' + bad };
+        const safeId = String(id ?? '').trim();
+        const dir = join(deps.dir, safeId);
+        try {
+            await stat(dir);
+            return { ok: false, error: 'id 已存在：' + safeId };
+        }
+        catch { /* 不存在，继续 */ }
+        await mkdir(dir, { recursive: true });
+        await writeFile(join(dir, FILENAME), String(content ?? ''), 'utf8');
+        await writeMeta(safeId, { description });
+        return { ok: true, id: safeId };
+    }
+    async function update(id, content, nextId, description) {
+        const bad = idError(id);
+        if (bad)
+            return { ok: false, error: '非法 id：' + bad };
+        const safeId = String(id ?? '').trim();
+        try {
+            await stat(join(deps.dir, safeId));
+        }
+        catch {
+            return { ok: false, error: '快捷提示词不存在：' + safeId };
+        }
+        let targetId = safeId;
+        if (nextId !== undefined && String(nextId).trim() !== safeId) {
+            const badNext = idError(nextId);
+            if (badNext)
+                return { ok: false, error: '非法新 id：' + badNext };
+            targetId = String(nextId).trim();
+            try {
+                await stat(join(deps.dir, targetId));
+                return { ok: false, error: '新 id 已存在：' + targetId };
+            }
+            catch { /* 可用 */ }
+            try {
+                await rename(join(deps.dir, safeId), join(deps.dir, targetId));
+            }
+            catch (e) {
+                return { ok: false, error: '改名失败：' + message(e) };
+            }
+        }
+        await writeFile(join(deps.dir, targetId, FILENAME), String(content ?? ''), 'utf8');
+        await writeMeta(targetId, { description });
+        return { ok: true, id: targetId, ...(targetId === safeId ? {} : { renamedFrom: safeId }) };
+    }
+    /**
+     * 启停：只写侧车那一个字段，正文与说明一律不动。
+     * 目录不存在时照实拒绝 —— 静默"成功"会在界面上留下一颗凭空出现的开关。
+     */
+    async function setEnabled(id, enabled) {
+        const safeId = String(id ?? '').trim();
+        const bad = idError(safeId);
+        if (bad)
+            return { ok: false, error: '非法 id：' + bad };
+        try {
+            await stat(join(deps.dir, safeId));
+        }
+        catch {
+            return { ok: false, error: '快捷提示词不存在：' + safeId };
+        }
+        await writeMeta(safeId, { enabled });
+        return { ok: true, id: safeId, enabled };
+    }
+    /** 删除 = 整个目录进回收站（与预设同一条纪律：不静默删用户写的东西）。 */
+    async function remove(id) {
+        const safeId = String(id ?? '').trim();
+        const bad = idError(safeId);
+        if (bad)
+            return { ok: false, error: '非法 id：' + bad };
+        const dir = join(deps.dir, safeId);
+        try {
+            await stat(dir);
+        }
+        catch {
+            return { ok: false, error: '快捷提示词不存在：' + safeId };
+        }
+        const moved = await moveToTrash('quick-prompts', safeId, [{ from: dir, dest: 'prompt' }]);
+        if (moved.ok === false)
+            return { ok: false, error: '移入回收站失败：' + moved.error };
+        return { ok: true, id: safeId };
+    }
+    async function trashList() {
+        return { ok: true, trash: await listTrashEntries('quick-prompts') };
+    }
+    async function trashRestore(id) {
+        const entry = await readTrashEntry('quick-prompts', String(id ?? '').trim());
+        if (!entry)
+            return { ok: false, error: '回收站条目不存在：' + String(id ?? '').trim() };
+        const bad = idError(entry.name);
+        if (bad)
+            return { ok: false, error: '回收站里的 id 不合法：' + bad };
+        const target = join(deps.dir, entry.name);
+        try {
+            await stat(target);
+            return { ok: false, error: '无法恢复，同 id 已存在：' + entry.name };
+        }
+        catch { /* 可用 */ }
+        try {
+            await mkdir(deps.dir, { recursive: true });
+            await moveOutOfTrash('quick-prompts', entry.id, 'prompt', target);
+        }
+        catch (e) {
+            return { ok: false, error: '恢复失败：' + message(e) };
+        }
+        await purgeTrashEntry('quick-prompts', entry.id);
+        return { ok: true, id: entry.name };
+    }
+    async function trashDelete(id) {
+        const clean = String(id ?? '').trim();
+        if (!(await purgeTrashEntry('quick-prompts', clean)))
+            return { ok: false, error: '回收站条目不存在：' + clean };
+        return { ok: true, id: clean };
+    }
+    return { list, create, update, setEnabled, remove, trashList, trashRestore, trashDelete };
+}

package/lib/scene-linkage.js

@@ -0,0 +1,184 @@
+export function installSceneLinkage(deps) {
+    /**
+     * 人设改名后同步场景绑定：场景档案的 `subagents` 名单存的是**人设名**，
+     * 不跟着改就会留一个悬空引用（界面把它报成 stale，用户看到「人设不存在」却找不到地方改）。
+     * 绑定存在 memories-index.json 里，人设服务看不到它，所以在这一层补一次（同提示词改名的做法）。
+     */
+    async function rebindSubagentInArchives(from, to) {
+        try {
+            const slice = await deps.memoriesService.readArchiveSlice();
+            const touched = {};
+            for (const [scene, archive] of Object.entries(slice.archives || {})) {
+                const list = archive.subagents;
+                if (!Array.isArray(list) || !list.includes(from))
+                    continue;
+                touched[scene] = { ...archive, subagents: list.map((n) => (n === from ? to : n)) };
+            }
+            const names = Object.keys(touched);
+            // 逐场景增量（审查 P2-3）：此前整表回写，会把窗口期里别人保存的**别的场景**档案抹掉。
+            for (const scene of names)
+                await deps.memoriesService.saveArchive(scene, touched[scene]);
+            return names.length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    /**
+     * 人设改名后同步运行时快照（F-025）：退出还原按 `subagentsAll` 逐名走，快照里
+     * 还留着旧名的话，退出会「旧名静默跳过、新名不还原」—— 被改名的人设停留在
+     * 场景期间状态。快照在进入场景时拍、改名发生在进入后，只能在改名时跟着改。
+     */
+    async function renameSubagentInSnapshot(from, to) {
+        try {
+            const slice = await deps.memoriesService.readArchiveSlice();
+            const mode = slice && slice.mode;
+            const snapshot = mode && mode.snapshot;
+            if (!snapshot)
+                return;
+            let changed = false;
+            const next = { ...snapshot };
+            if (snapshot.subagentsAll && Object.prototype.hasOwnProperty.call(snapshot.subagentsAll, from)) {
+                const all = {};
+                for (const [k, v] of Object.entries(snapshot.subagentsAll)) {
+                    all[k === from ? to : k] = v;
+                    if (k === from)
+                        changed = true;
+                }
+                next.subagentsAll = all;
+            }
+            for (const field of ['subagents', 'subagentsOn']) {
+                const list = snapshot[field];
+                if (Array.isArray(list) && list.includes(from)) {
+                    next[field] = list.map((n) => (n === from ? to : n));
+                    changed = true;
+                }
+            }
+            if (changed)
+                await deps.memoriesService.patchIndex({ mode: { ...mode, snapshot: next } });
+        }
+        catch { /* 快照同步失败不阻断改名本身；残留与修复前一致 */ }
+    }
+    const baseSubagentUpdate = deps.subagentService.ops['subagent-update'];
+    if (typeof baseSubagentUpdate === 'function') {
+        deps.subagentService.ops['subagent-update'] = async (args) => {
+            const res = await baseSubagentUpdate(args);
+            if (res && res.ok !== false && res.renamedFrom) {
+                const from = String(res.renamedFrom);
+                const to = String(res.name);
+                void rebindSubagentInArchives(from, to);
+                void renameSubagentInSnapshot(from, to);
+            }
+            return res;
+        };
+    }
+    /**
+     * 快捷提示词改名后同步场景档案（与人设改名那两条同一件事）：档案里存的还是旧 id 的话，
+     * 下一次进场景它会被当成 stale 丢掉 —— 用户看到的就成了"改了个名字，场景里的勾选悄悄没了"，
+     * 而且那条快捷词还会在进场景时被停用（它不在勾选集里了）。
+     */
+    async function rebindQuickPromptInArchives(from, to) {
+        try {
+            const slice = await deps.memoriesService.readArchiveSlice();
+            const touched = [];
+            for (const [scene, archive] of Object.entries(slice.archives || {})) {
+                const list = archive.quickPrompts;
+                if (!Array.isArray(list) || !list.includes(from))
+                    continue;
+                touched.push([scene, { ...archive, quickPrompts: list.map((n) => (n === from ? to : n)) }]);
+            }
+            // 逐场景增量写（与审查 P2-3 同一条口径）：整表回写会抹掉窗口期里别人存的别的场景。
+            for (const [scene, next] of touched)
+                await deps.memoriesService.saveArchive(scene, next);
+        }
+        catch { /* 同步失败不阻断改名本身；残留由档案保存时的 stale 清理兜住 */ }
+    }
+    const baseQuickPromptUpdate = deps.quickPromptOps['quickprompt-update'];
+    if (typeof baseQuickPromptUpdate === 'function') {
+        deps.quickPromptOps['quickprompt-update'] = async (args) => {
+            const res = await baseQuickPromptUpdate(args);
+            if (res && res.ok !== false && res.renamedFrom)
+                void rebindQuickPromptInArchives(String(res.renamedFrom), String(res.id));
+            return res;
+        };
+    }
+    // 模式切换会改人设开关（进入=启用勾选的，退出=按快照停回）——目录段立即重算，
+    // 别等 1s TTL：切完场景紧接着的下一轮请求就该看到新名单。
+    const baseSceneModeSet = deps.archiveService.ops['scene-mode-set'];
+    if (typeof baseSceneModeSet === 'function') {
+        deps.archiveService.ops['scene-mode-set'] = async (args) => {
+            // 锁定的场景不能关闭（用户裁定）：退出模式（scene=null）和切换到别的场景
+            // 都意味着先退出当前模式 —— 当前模式场景处于锁定状态时一律拒绝。
+            // 目标就是当前场景 = 无操作，放行（引擎自己会 early-return）。
+            try {
+                const slice = await deps.memoriesService.readArchiveSlice();
+                const current = slice.mode && slice.mode.scene;
+                if (current && args && 'scene' in (args || {})) {
+                    const target = args.scene == null ? null : String(args.scene).trim() || null;
+                    if (target !== current) {
+                        const locked = await deps.lockedSceneNames();
+                        if (locked.includes(current)) {
+                            return { ok: false, error: `场景「${current}」已锁定：先解锁再关闭` };
+                        }
+                    }
+                }
+            }
+            catch { /* 守卫读状态失败不拦正常流程（引擎自身校验兜底） */ }
+            const res = await baseSceneModeSet(args);
+            if (res && res.ok !== false) {
+                // 进/退/切换模式会改 MCP 启停（服务器级）与备注（场景备注覆盖/恢复），
+                // 状态段必须立即重算 —— 场景退出后下一次请求就该看到恢复的全局备注与启停。
+                void deps.subagentCatalog.refresh().catch(() => { });
+                void deps.mcp.stateCatalog.refresh().catch(() => { });
+            }
+            return res;
+        };
+    }
+    /**
+     * 模式进行中保存当前场景的档案时，联动人设开关：**档案 = 这个场景开着的人设**
+     * （与进入场景时同一口径，见 archive-engine）——
+     *   新勾进来的立即启用，并追加进快照的「退出时停回」名单；
+     *   取消勾选的立即停用；其中「进场景前就开着」的那些追加进快照的「退出时开回」名单
+     *   （在停回名单里的说明是本次进场景才打开的，退出本来就该关，不进开回名单）。
+     */
+    const baseSceneArchiveSave = deps.archiveService.ops['scene-archive-save'];
+    if (typeof baseSceneArchiveSave === 'function') {
+        deps.archiveService.ops['scene-archive-save'] = async (args) => {
+            const res = await baseSceneArchiveSave(args);
+            try {
+                const bound = res && res.ok !== false && res.archive && Array.isArray(res.archive.subagents) ? res.archive.subagents : [];
+                const slice = await deps.memoriesService.readArchiveSlice();
+                const mode = slice.mode;
+                if (mode && mode.scene === res.scene) {
+                    const every = (await deps.subagentService.list()).map((p) => p.name);
+                    const unbound = every.filter((n) => bound.indexOf(n) < 0);
+                    const toOn = await deps.subagentService.enabledStore.disabledAmong(bound);
+                    const toOff = await deps.subagentService.enabledStore.enabledAmong(unbound);
+                    if (toOn.length)
+                        await deps.subagentService.enabledStore.setEnabled(toOn, true);
+                    if (toOff.length)
+                        await deps.subagentService.enabledStore.setEnabled(toOff, false);
+                    if (toOn.length || toOff.length)
+                        void deps.subagentCatalog.refresh();
+                    const snapshot = mode.snapshot;
+                    // 新快照带**全量映射**（`subagentsAll`，v0.9.1）→ 退出按映射逐个精确还原，这两个
+                    // 部分名单不再需要，也不再往新快照里写（老快照没有映射，仍然照旧维护，见
+                    // archive-engine 的 restoreSnapshot 兼容分支）。
+                    if (snapshot && !snapshot.subagentsAll && (toOn.length || toOff.length)) {
+                        const backOn = Array.isArray(snapshot.subagents) ? snapshot.subagents.slice() : [];
+                        const offList = Array.isArray(snapshot.subagentsOn) ? snapshot.subagentsOn.slice() : [];
+                        for (const n of toOn)
+                            if (backOn.indexOf(n) < 0)
+                                backOn.push(n);
+                        for (const n of toOff)
+                            if (backOn.indexOf(n) < 0 && offList.indexOf(n) < 0)
+                                offList.push(n);
+                        await deps.memoriesService.patchIndex({ mode: { ...mode, snapshot: { ...snapshot, subagents: backOn, subagentsOn: offList } } });
+                    }
+                }
+            }
+            catch { /* 联动失败不阻断档案保存本身；开关会在下次进/退模式时对齐 */ }
+            return res;
+        };
+    }
+}

package/lib/sessions/archive-schemas.js

@@ -0,0 +1,121 @@
+export const sessionIdSchema = {
+    parse(value) {
+        if (typeof value !== "string" || value.length === 0)
+            throw new TypeError(`sessionId must be a non-empty string, got ${String(value)}`);
+        return value;
+    },
+};
+export const workspaceIdSchema = {
+    parse(value) {
+        if (typeof value !== "string" || value.length === 0)
+            throw new TypeError(`workspaceId must be a non-empty string, got ${String(value)}`);
+        return value;
+    },
+};
+export const archivedSetSchema = {
+    parse(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new TypeError("result must be an object");
+        const ids = value.archivedSessionIds;
+        if (!Array.isArray(ids) || ids.some((id) => typeof id !== "string"))
+            throw new TypeError("archivedSessionIds must be a string array");
+        return value;
+    },
+};
+export const deletedSchema = {
+    parse(value) {
+        if (typeof value !== "object" ||
+            value === null ||
+            Array.isArray(value) ||
+            value.deleted !== true)
+            throw new TypeError("deleted must be true");
+        return value;
+    },
+};
+export const archivedBatchTargetSchema = {
+    // 校验通过后原样返回记录，调用方按 scope 判别式收窄（宿主返回值校验器，故返回 any）。
+    parse(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new TypeError("target must be an object");
+        if (value.scope === "all" || value.scope === "ungrouped")
+            return value;
+        if (value.scope === "workspace" &&
+            typeof value.workspaceId === "string" &&
+            value.workspaceId.length > 0)
+            return value;
+        if (value.scope === "sessions" &&
+            Array.isArray(value.sessionIds) &&
+            value.sessionIds.length > 0 &&
+            value.sessionIds.every((id) => typeof id === "string" && id.length > 0))
+            return value;
+        throw new TypeError("target.scope must be all, ungrouped, workspace with a non-empty workspaceId, or sessions with non-empty sessionIds");
+    },
+};
+export const unarchivedBatchSchema = {
+    parse(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new TypeError("result must be an object");
+        if (!Array.isArray(value.archivedSessionIds) ||
+            value.archivedSessionIds.some((id) => typeof id !== "string"))
+            throw new TypeError("archivedSessionIds must be a string array");
+        if (!Array.isArray(value.unarchivedSessionIds) ||
+            value.unarchivedSessionIds.some((id) => typeof id !== "string"))
+            throw new TypeError("unarchivedSessionIds must be a string array");
+        return value;
+    },
+};
+export const archivedWorkspaceBatchSchema = {
+    parse(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new TypeError("result must be an object");
+        if (!Array.isArray(value.archivedSessionIds) ||
+            value.archivedSessionIds.some((id) => typeof id !== "string"))
+            throw new TypeError("archivedSessionIds must be a string array");
+        if (!Array.isArray(value.archivedSessionIdsAdded) ||
+            value.archivedSessionIdsAdded.some((id) => typeof id !== "string"))
+            throw new TypeError("archivedSessionIdsAdded must be a string array");
+        return value;
+    },
+};
+export const deletedBatchSchema = {
+    parse(value) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            throw new TypeError("result must be an object");
+        for (const key of [
+            "requestedSessionIds",
+            "deletedSessionIds",
+            "skippedSessionIds",
+        ]) {
+            if (!Array.isArray(value[key]) ||
+                value[key].some((id) => typeof id !== "string"))
+                throw new TypeError(`${key} must be a string array`);
+        }
+        if (!Array.isArray(value.failures) ||
+            value.failures.some((failure) => typeof failure !== "object" ||
+                failure === null ||
+                typeof failure.sessionId !== "string" ||
+                typeof failure.message !== "string"))
+            throw new TypeError("failures must contain sessionId/message objects");
+        return value;
+    },
+};
+export const archivedSessionMetadataSchema = {
+    parse(value) {
+        if (typeof value !== "object" ||
+            value === null ||
+            Array.isArray(value) ||
+            !Array.isArray(value.items))
+            throw new TypeError("result.items must be an array");
+        if (value.items.some((item) => typeof item !== "object" ||
+            item === null ||
+            typeof item.sessionId !== "string" ||
+            typeof item.createdAt !== "number" ||
+            !Number.isFinite(item.createdAt)))
+            throw new TypeError("items must contain sessionId/createdAt objects");
+        if (value.repairedSessionIds !== void 0 &&
+            (!Array.isArray(value.repairedSessionIds) ||
+                value.repairedSessionIds.some((id) => typeof id !== "string")))
+            throw new TypeError("repairedSessionIds must be a string array");
+        return value;
+    },
+};

package/lib/sessions/path-key.js

@@ -0,0 +1,46 @@
+// 工作区路径的归一化比较键与展示名。
+//
+// 从 sessions/workspace.ts 整段搬来，一行未改。workspacePathKey 的口径注释里写着它不是
+// 「只用于分组」而是决定会话挂回哪条登记，也写着它比宿主 realpathNormalize 更宽 ——
+// 那两条是本插件的已知假设，改这个文件前先读它们。
+/**
+ * 路径比较键：工作区的唯一性在宿主侧是 realpath 字符串相等（dsh-workspace
+ * `realpathNormalize`），Windows 盘符大小写与分隔符拼写却可能不同，因此比较前
+ * 先归一化。
+ *
+ * ⚠ 它不是"只用于分组"：它决定**哪些会话被挂回哪条登记** —— `registerWorkspace` 会调
+ * `attachKnownSessions`，后者按这个键挑选会话并写宿主记账（`sessionIds`）；
+ * `ensureWorkspaceAccounting` 也拿它当去重键后 `host.create` + 挂回。
+ * 而且它比宿主更宽：宿主 `realpathNormalize` 只是 `fs.realpath`（**不做大小写归一**），
+ * 本函数在 Windows 上 `toLowerCase()` ⇒ `C:\Proj` 与 `c:\proj` 在插件里同组、在宿主里
+ * 可以是两条登记。挂回前应以宿主 `resolveByPath` 实际返回的 id 复核，而不是按归一字符串匹配。
+ * @param {string} path - 原始路径。
+ * @returns {string} 归一化后的比较键（空路径返回空串）。
+ */
+export function workspacePathKey(path) {
+    const raw = String(path ?? "").trim();
+    if (!raw)
+        return "";
+    const windows = /^[A-Za-z]:[\\/]/.test(raw) || raw.startsWith("\\\\");
+    let out = windows ? raw.replace(/\//g, "\\") : raw;
+    while (out.length > 1 && (out.endsWith("\\") || out.endsWith("/")))
+        out = out.slice(0, -1);
+    return windows ? out.toLowerCase() : out;
+}
+/**
+ * 展示用目录名（与宿主 `defaultWorkspaceTitle` 同义：末段，无末段则用根拼写）。
+ * @param {string} path - 原始路径。
+ * @returns {string} 非空展示名。
+ */
+export function workspaceBaseName(path) {
+    const raw = String(path ?? "").trim();
+    if (!raw)
+        return "";
+    const trimmed = raw.replace(/[\\/]+$/, "");
+    const index = Math.max(trimmed.lastIndexOf("\\"), trimmed.lastIndexOf("/"));
+    const segment = index >= 0 ? trimmed.slice(index + 1) : trimmed;
+    if (segment)
+        return segment;
+    const root = trimmed.match(/^(?:[A-Za-z]:[\\/]|[\\/]{1,2})/);
+    return root ? root[0] : trimmed || raw;
+}