dsh-plugin-tool-management 0.2.0 → 0.5.0

package/lib/rules/archive-engine.js

@@ -0,0 +1,191 @@
+// src/rules/archive-engine.ts —— 场景档案引擎：sidecar 读写 + 运行时应用，全部经 deps 注入（无直接 I/O）。
+// 状态机（设计 §2.2）：进入 = 快照 → 先落盘 mode（留可退路径）→ 应用已定义段 → 记忆收窄为 {S}；
+//                     退出 = 恢复快照 → 落盘自由模式；切换 = 先退后进。
+// 失败语义（fail-closed）：任一步失败即反向恢复运行时并写回旧切片；回滚不全会如实写进错误文本。
+// v2：MCP 段两级（服务器勾选 + '*' / 工具明细），停用表存勾选集的补集，通配由 index.ts 的 guard/restrict 原生支持。
+import { computeMcpPlan, computeMemoriesPlan, computeSkillsPlan, normalizeArchive, snapshotRuntime, hasSection, } from './archive.js';
+const msg = (e) => String((e && e.message) || e);
+export function createArchiveEngine(deps) {
+    let chain = Promise.resolve();
+    const serial = (task) => {
+        const queued = chain.then(task, task);
+        chain = queued.catch(() => undefined);
+        return queued;
+    };
+    /**
+     * 还原到快照（退出模式与失败回滚共用同一条路径）：
+     * MCP 停用表**按快照原文整体回写**——模式自己写进去的键（未勾服务器的 ['*']）必须随之消失，
+     * 否则退出后用户环境仍被静默停用（比"多留一个键"严重得多）；模式期间的手动改动按设计 §2.2
+     * 不保留（「退出 = 恢复 mode.snapshot」，手动改动只在「保存到场景」时回写）。
+     * 技能只写快照列出的键（这是既有批量通道的语义）：模式期间新增的技能保持现状。
+     */
+    async function restoreSnapshot(snapshot) {
+        const mcp = Object.fromEntries(Object.entries(snapshot.mcp).map(([k, v]) => [k, v.slice()]));
+        await deps.applyMcpEntries(mcp);
+        await deps.applySkills({ ...snapshot.skills });
+    }
+    /**
+     * 失败回滚：运行时还原 + 切片写回；每步失败都记下来，绝不谎报「已回滚」。
+     * 返回结构化错误（ok:false），错误文本如实区分「已回滚」与「回滚未完成」。
+     */
+    async function rollback(prev, snapshot, stage, err) {
+        const problems = [];
+        try {
+            await restoreSnapshot(snapshot);
+        }
+        catch (e) {
+            problems.push('运行时还原: ' + msg(e));
+        }
+        try {
+            await deps.saveSlice(prev);
+        }
+        catch (e) {
+            problems.push('模式状态写回: ' + msg(e));
+        }
+        const base = `${stage}失败：${msg(err)}`;
+        return { ok: false, error: problems.length ? `${base}；回滚未完成（${problems.join('；')}）` : `${base}，已回滚` };
+    }
+    const ops = {
+        // 读：页面渲染模式与档案
+        'scene-mode-get': async () => {
+            const slice = await deps.loadSlice();
+            return { ok: true, archives: slice.archives, mode: slice.mode, active: slice.active };
+        },
+        // 写：保存某场景档案（三段整体替换；键对实时发现全集校验，未知键丢弃并报告）
+        'scene-archive-save': (args) => serial(async () => {
+            const scene = String((args && args.scene) || '').trim();
+            if (!scene)
+                return { ok: false, error: '缺少场景名' };
+            if (!(await deps.sceneExists(scene)))
+                return { ok: false, error: `场景不存在: ${scene}` };
+            const archive = normalizeArchive((args && args.archive) || {});
+            const stale = [];
+            if (archive.mcp) {
+                const configured = await deps.configuredServers();
+                const hadKeys = Object.keys(archive.mcp).length > 0;
+                for (const server of Object.keys(archive.mcp)) {
+                    if (configured.indexOf(server) < 0) {
+                        stale.push('mcp/' + server);
+                        delete archive.mcp[server];
+                    }
+                }
+                // 只剔除「全 stale」段：空段是合法值（全不勾 = 全部停用），必须留下来。
+                if (hadKeys && Object.keys(archive.mcp).length === 0)
+                    delete archive.mcp;
+            }
+            if (archive.skills) {
+                const known = await deps.knownSkillKeys();
+                const hadKeys = archive.skills.length > 0;
+                stale.push(...archive.skills.filter((k) => !known.has(k)).map((k) => 'skills/' + k));
+                archive.skills = archive.skills.filter((k) => known.has(k));
+                if (hadKeys && archive.skills.length === 0)
+                    delete archive.skills;
+            }
+            if (archive.subagents) {
+                const known = await deps.knownPersonas();
+                const hadKeys = archive.subagents.length > 0;
+                stale.push(...archive.subagents.filter((p) => !known.has(p)).map((p) => 'subagents/' + p));
+                archive.subagents = archive.subagents.filter((p) => known.has(p));
+                if (hadKeys && archive.subagents.length === 0)
+                    delete archive.subagents;
+            }
+            if (archive.memories) {
+                // 记忆段只影响投影（正文是否进 system prompt），不写任何运行时状态；
+                // 这里只把已不存在的记忆 id 剔掉并上报，避免档案里留下指向空气的勾选。
+                const known = await deps.knownMemoryIds();
+                const hadKeys = archive.memories.length > 0;
+                const { stale: memStale } = computeMemoriesPlan(archive.memories, known);
+                stale.push(...memStale);
+                archive.memories = archive.memories.filter((id) => known.has(id));
+                if (hadKeys && archive.memories.length === 0)
+                    delete archive.memories;
+            }
+            const slice = await deps.loadSlice();
+            if (Object.keys(archive).length === 0)
+                delete slice.archives[scene];
+            else
+                slice.archives[scene] = archive;
+            await deps.saveSlice(slice);
+            return { ok: true, scene, archive: slice.archives[scene] ?? null, stale };
+        }),
+        // 写：进入/退出/切换当前模式
+        // scene=null 退出；目标场景没有 mcp/skills 段 = 结构化拒绝（设计 §2.4：此类场景不显示模式按钮）。
+        'scene-mode-set': (args) => serial(async () => {
+            const hasKey = args && 'scene' in (args || {});
+            if (!hasKey)
+                return { ok: false, error: '缺少 scene（null = 退出模式）' };
+            const raw = (args && args.scene) ?? null;
+            const target = raw == null ? null : String(raw).trim() || null;
+            let slice = await deps.loadSlice();
+            let current = slice.mode ?? { scene: null, snapshot: null };
+            if (target === current.scene)
+                return { ok: true, mode: current, applied: null, stale: [] };
+            // ① 退出当前模式（切换 = 先退后进）：先恢复运行时，再落盘自由模式。
+            //    恢复失败即中止且**保持原 mode 不变**——宁可留在「可再退出一次」的状态，也不吞错。
+            if (current.scene && current.snapshot) {
+                try {
+                    await restoreSnapshot(current.snapshot);
+                }
+                catch (e) {
+                    return { ok: false, error: `退出模式「${current.scene}」失败，已保持原模式（运行时可能部分残留）：${msg(e)}` };
+                }
+            }
+            if (current.scene) {
+                const exited = { ...slice, mode: { scene: null, snapshot: null } };
+                try {
+                    await deps.saveSlice(exited);
+                }
+                catch (e) {
+                    return { ok: false, error: `退出模式「${current.scene}」已恢复运行时，但模式状态落盘失败：${msg(e)}` };
+                }
+                slice = exited;
+                current = exited.mode;
+            }
+            if (!target)
+                return { ok: true, mode: current, applied: null, stale: [] };
+            // ② 进入目标模式：校验 → 快照 → 先落盘 mode（中途失败也留可退快照）→ 应用已定义段 → 记忆收窄。
+            const archive = slice.archives[target];
+            if (!(await deps.sceneExists(target)))
+                return { ok: false, error: `场景不存在: ${target}` };
+            if (!archive || (!hasSection(archive, 'mcp') && !hasSection(archive, 'skills'))) {
+                return { ok: false, error: `场景「${target}」的档案没有 MCP / 技能段（仅记忆或仅子智能体的场景不需要进入模式）` };
+            }
+            const snapshot = snapshotRuntime(await deps.currentMcpRaw(), await deps.currentSkills());
+            const entered = { ...slice, mode: { scene: target, snapshot }, active: [target] };
+            try {
+                await deps.saveSlice({ ...slice, mode: entered.mode });
+            }
+            catch (e) {
+                return { ok: false, error: '进入模式前落盘快照失败（运行时未改动）：' + msg(e) };
+            }
+            const stale = [];
+            try {
+                if (archive.mcp) {
+                    const plan = computeMcpPlan(archive.mcp, {
+                        configuredServers: await deps.configuredServers(),
+                        knownTools: await deps.serverKnownTools(),
+                    });
+                    stale.push(...plan.stale);
+                    await deps.applyMcpEntries(plan.entries);
+                }
+                if (archive.skills) {
+                    const plan = computeSkillsPlan(archive.skills, await deps.knownSkillKeys());
+                    stale.push(...plan.stale);
+                    await deps.applySkills(plan.target);
+                }
+            }
+            catch (e) {
+                return await rollback(slice, snapshot, '应用档案', e);
+            }
+            // ③ 记忆启用集收窄为 {S}（`_shared` 由 resolveActiveScenes 恒常加入；退出不恢复）。
+            try {
+                await deps.saveSlice(entered);
+            }
+            catch (e) {
+                return await rollback(slice, snapshot, '记忆收窄落盘', e);
+            }
+            return { ok: true, mode: entered.mode, applied: { mcp: !!archive.mcp, skills: !!archive.skills }, stale, narrowedTo: [target] };
+        }),
+    };
+    return { ops, writeOps: new Set(['scene-archive-save', 'scene-mode-set']) };
+}

package/lib/rules/archive.js

@@ -0,0 +1,140 @@
+// src/rules/archive.ts —— 场景档案数据模型与模式切换纯逻辑（无 I/O；I/O 由 archive-engine 注入）。
+// 勾选集语义（设计 §2.1）：段内存储「勾选的启用集合」；应用时该域置为与勾选集完全一致；
+// 段未定义 = 该域不碰；段已定义但全不勾 = 合法（全部停用）。清单只对"实时发现"的条目生效。
+// v2：MCP 段为两级——服务器勾选（mcp 键存在）+ 可选工具明细（'*' = 整台，string[] = 指定工具）。
+export function normalizeStringList(raw) {
+    if (typeof raw === 'string')
+        raw = raw.split(/[,，]/);
+    if (!Array.isArray(raw))
+        return [];
+    return [...new Set(raw.map((x) => String(x).trim()).filter(Boolean))];
+}
+/**
+ * MCP 规范化：serverName → '*' 或工具名清单；非法形态丢弃。
+ * 空清单是**合法值**（勾了服务器但一个工具都不勾 = 该服务器全部停用），必须保留——
+ * 否则「段已定义但全不勾 = 全部停用」（设计 §2.1）无法持久化。
+ */
+export function normalizeMcpSpec(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [serverRaw, v] of Object.entries(raw)) {
+        const server = serverRaw.trim();
+        if (!server)
+            continue;
+        if (v === '*' || (typeof v === 'string' && v.trim() === '*')) {
+            out[server] = '*';
+            continue;
+        }
+        if (typeof v !== 'string' && !Array.isArray(v))
+            continue; // 畸形形态（null/数字/对象）丢弃
+        out[server] = normalizeStringList(v);
+    }
+    return out;
+}
+/** 'mcp'/'skills'/'subagents'/'memories' 键存在且值非 null 才视为"段已定义"——存在性独立于集合空否（null/缺失 = 未定义）。 */
+export function normalizeArchive(raw) {
+    const obj = (raw && typeof raw === 'object' ? raw : {});
+    const out = {};
+    if (obj.mcp != null) {
+        const mcp = normalizeMcpSpec(obj.mcp);
+        if (mcp)
+            out.mcp = mcp;
+    }
+    if (obj.skills != null)
+        out.skills = normalizeStringList(obj.skills);
+    if (obj.subagents != null)
+        out.subagents = normalizeStringList(obj.subagents);
+    if (obj.memories != null)
+        out.memories = normalizeStringList(obj.memories);
+    return out;
+}
+export function hasSection(archive, section) {
+    return archive[section] !== undefined;
+}
+/**
+ * MCP 段应用计划：段已定义 → 对并集里每台服务器产出**精确停用名单（勾选集的补集）**。
+ *   服务器未勾（键缺失）→ ['*'] 整台停用（guard/restrict 原生支持通配，服务器后加载也会被拦）；
+ *   服务器勾 '*'      → [] 全启用；
+ *   服务器勾清单      → known − 勾选（未运行且无已知工具名的服务器无法枚举补集：不做停用，
+ *                       上报 `mcp/<server>/*` 让用户知道未勾项这次没生效）；
+ *   段内服务器若配置里根本不存在 → stale 上报且不写。
+ */
+export function computeMcpPlan(mcp, input) {
+    const configured = new Set(input.configuredServers);
+    const servers = new Set([...configured, ...Object.keys(input.knownTools), ...Object.keys(mcp)]);
+    const entries = {};
+    const wildcards = [];
+    const stale = [];
+    for (const server of servers) {
+        if (!configured.has(server)) {
+            if (mcp[server] !== undefined)
+                stale.push('mcp/' + server);
+            continue;
+        }
+        const spec = mcp[server];
+        if (spec === undefined) {
+            entries[server] = ['*'];
+            wildcards.push(server);
+            continue;
+        }
+        if (spec === '*') {
+            entries[server] = [];
+            continue;
+        }
+        const known = input.knownTools[server] || [];
+        if (!known.length) {
+            entries[server] = [];
+            stale.push('mcp/' + server + '/*');
+            continue;
+        }
+        const checked = new Set(spec);
+        entries[server] = known.filter((t) => !checked.has(t));
+        for (const t of spec)
+            if (known.indexOf(t) < 0)
+                stale.push('mcp/' + server + '/' + t);
+    }
+    return { entries, wildcards, stale };
+}
+/** 技能段应用计划：已知技能全集 → 勾选集决定启停。 */
+export function computeSkillsPlan(skills, knownSkillKeys) {
+    const target = {};
+    for (const key of knownSkillKeys)
+        target[key] = skills.indexOf(key) >= 0;
+    const stale = skills.filter((k) => !knownSkillKeys.has(k)).map((k) => 'skills/' + k);
+    return { target, stale };
+}
+export function snapshotRuntime(mcpRaw, skills) {
+    return {
+        mcp: Object.fromEntries(Object.entries(mcpRaw).map(([k, v]) => [k, v.slice()])),
+        skills: { ...skills },
+    };
+}
+// ── 记忆勾选（v3）──────────────────────────────────────────────────────────
+//
+// 记忆段与其余三段有一处关键差别：MCP / 技能是**运行时启停**（改了要落表、进/退模式要回滚），
+// 记忆只是**投影**（正文进 system prompt）。所以记忆段不产生"应用计划"、不进模式快照，
+// 而是在渲染时被查询——勾选后下一个请求即生效，退出模式无需回滚任何东西。
+/**
+ * 记忆是否应当注入（纯函数，供渲染路径同步调用）。
+ *
+ * 口径与其余段同构：
+ *   - 该记忆所属场景**没有** memories 段 → 全部记忆照常注入（老档案 = 未定义 = 不碰）；
+ *   - 有段 → 只有列在段里的记忆注入（段已定义但空 = 该场景记忆全部不注入）。
+ *
+ * 入参 `sceneEnabled` 是索引里的单条启停（`enabled === false` 的条目在上游已被过滤，
+ * 这里只为把两种"不注入"的原因分开，便于体检报告区分）。
+ */
+export function memoryAllowed(archives, scene, id) {
+    const archive = archives ? archives[scene] : undefined;
+    if (!archive || archive.memories === undefined)
+        return true;
+    return archive.memories.indexOf(id) >= 0;
+}
+/**
+ * 记忆段的 stale 上报（档案保存时调用）：段里引用了已经不存在的记忆 id。
+ * 记忆段不写任何运行时状态，因此除 stale 外没有别的计划产物。
+ */
+export function computeMemoriesPlan(memories, knownMemoryIds) {
+    return { stale: memories.filter((id) => !knownMemoryIds.has(id)).map((id) => 'memories/' + id) };
+}