dsh-plugin-tool-management 0.10.0 → 0.12.0

package/lib/ops/trash.js

@@ -0,0 +1,140 @@
+// 规则/记忆域的**回收站 ops**（2026-09-19 从 memories/service.ts 的 createMemoriesService 闭包抽出）。
+//
+// 删除进回收站、从回收站恢复、回收站列出与彻底删除。与记忆正文 ops 分域，
+// 但共用 copyIntoMemoriesTrash 等入口，经 MemoriesOpsCtx 显式传入。
+import { copyFile, lstat, mkdir, readFile, readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isValidTrashId } from '../hub.js';
+import { LEGACY_BUNDLE_DOC, bundleDocName, isValidGroupSegment, isValidGroupPath, fail, MEMORIES_TRASH_DIR } from '../memories/constants.js';
+import { readIndex, writeIndex } from '../memories/index-io.js';
+/** 组装本域 op。rc 由 createMemoriesService 组装，契约见 ./ctx.ts。 */
+export function buildTrashOps(rc) {
+    const { buildProjected, copyIntoMemoriesTrash, invalidateSnapshot, locateRule, parseId, refuseOutsideRoot, memoriesRoot, stateDir } = rc;
+    async function rulesRemove(args) {
+        const id = String((args && args.id) || '');
+        const parts = parseId(id);
+        if (!parts)
+            return fail('error.rules.notFound', `规则不存在：${id}`);
+        const located = await locateRule(parts.group, parts.name);
+        if (!located)
+            return fail('error.rules.notFound', `规则不存在：${id}`);
+        // 删除前确认落点仍在根内（realpath 口径）：`located` 是顺着磁盘发现的，中间目录可能是链接。
+        const denied = await refuseOutsideRoot(located.entryPath);
+        if (denied)
+            return denied;
+        const trashId = await copyIntoMemoriesTrash(located, parts.group, parts.name);
+        if (located.kind === 'bundle')
+            await rm(located.entryPath, { recursive: true, force: true });
+        else
+            await rm(located.docPath, { force: true });
+        const index = await readIndex(stateDir);
+        delete index.rules[id];
+        await writeIndex(stateDir, index);
+        invalidateSnapshot();
+        return { ok: true, trashId };
+    }
+    async function rulesRestore(args) {
+        const trashId = String((args && args.trashId) || '');
+        if (!isValidTrashId(trashId))
+            return fail('error.rules.notFound', `回收站条目不存在：${trashId}`);
+        const trashDir = join(stateDir, MEMORIES_TRASH_DIR, trashId);
+        let manifest;
+        try {
+            manifest = JSON.parse(await readFile(join(trashDir, 'manifest.json'), 'utf8'));
+        }
+        catch {
+            return fail('error.rules.notFound', `回收站条目不存在：${trashId}`);
+        }
+        if (!manifest || typeof manifest.name !== 'string' || typeof manifest.group !== 'string' || !isValidGroupSegment(manifest.name)) {
+            return fail('error.rules.notFound', `回收站条目损坏：${trashId}`);
+        }
+        // 恢复目标已存在（期间用户重建了同名规则）→ 拒绝，避免覆盖。
+        const conflict = await locateRule(manifest.group, manifest.name);
+        if (conflict) {
+            return fail('error.rules.exists', `同名记忆已存在：${conflict.id}，请先移除后再恢复`);
+        }
+        const form = manifest.form === 'bundle' ? 'bundle' : 'flat';
+        if (form === 'bundle') {
+            await mkdir(join(memoriesRoot, manifest.group), { recursive: true });
+            const { cp } = await import('node:fs/promises');
+            await cp(join(trashDir, 'bundle'), join(memoriesRoot, manifest.group, manifest.name), { recursive: true });
+        }
+        else {
+            await mkdir(join(memoriesRoot, manifest.group), { recursive: true });
+            await copyFile(join(trashDir, 'rule.md'), join(memoriesRoot, manifest.group, manifest.name + '.md'));
+        }
+        await rm(trashDir, { recursive: true, force: true });
+        invalidateSnapshot();
+        return { ok: true, rule: await buildProjected(manifest.group ? `${manifest.group}/${manifest.name}` : manifest.name) };
+    }
+    /**
+     * 记忆回收站列表（只读）：`<stateDir>/memories-trash/<trashId>/`（`rulesRemove` 移入，
+     * `rulesRestore` 恢复）。损坏或内容缺失的条目跳过，不让一个坏条目挡住整份列表。
+     */
+    async function rulesTrashList() {
+        const root = join(stateDir, MEMORIES_TRASH_DIR);
+        let ids = [];
+        try {
+            ids = await readdir(root);
+        }
+        catch {
+            return { ok: true, entries: [] }; // 目录不存在 = 回收站为空
+        }
+        const entries = [];
+        for (const trashId of ids) {
+            if (!isValidTrashId(trashId))
+                continue;
+            const dir = join(root, trashId);
+            try {
+                const st = await lstat(dir);
+                if (!st.isDirectory() || st.isSymbolicLink())
+                    continue;
+                const manifest = JSON.parse(await readFile(join(dir, 'manifest.json'), 'utf8'));
+                if (!manifest || typeof manifest.name !== 'string' || !isValidGroupSegment(manifest.name))
+                    continue;
+                const group = typeof manifest.group === 'string' ? manifest.group : '';
+                if (group !== '' && !isValidGroupPath(group))
+                    continue;
+                const form = manifest.form === 'bundle' ? 'bundle' : 'flat';
+                let bytes = 0;
+                try {
+                    const bundleDoc = form === 'bundle'
+                        ? join(dir, 'bundle', bundleDocName(manifest.name))
+                        : join(dir, 'rule.md');
+                    bytes = (await stat(bundleDoc)).size;
+                }
+                catch {
+                    // 兼容旧回收站条目（正文仍叫 SKILL.md）；仍读不到就按 0 计，恢复时由 rulesRestore 兜底报错。
+                    if (form === 'bundle') {
+                        try {
+                            bytes = (await stat(join(dir, 'bundle', LEGACY_BUNDLE_DOC))).size;
+                        }
+                        catch { /* 内容缺失 */ }
+                    }
+                }
+                entries.push({ trashId, group, name: manifest.name, form, deletedAt: String(manifest.deletedAt || ''), bytes });
+            }
+            catch { /* 损坏条目跳过 */ }
+        }
+        entries.sort((a, b) => (a.deletedAt === b.deletedAt ? b.trashId.localeCompare(a.trashId) : b.deletedAt.localeCompare(a.deletedAt)));
+        return { ok: true, entries };
+    }
+    /** 永久删除回收站条目（不可恢复）。 */
+    async function rulesTrashRemove(args) {
+        const trashId = String((args && args.trashId) || '');
+        if (!isValidTrashId(trashId))
+            return fail('error.rules.notFound', `回收站条目不存在：${trashId}`);
+        const dir = join(stateDir, MEMORIES_TRASH_DIR, trashId);
+        try {
+            const st = await lstat(dir);
+            if (!st.isDirectory())
+                return fail('error.rules.notFound', `回收站条目不存在：${trashId}`);
+        }
+        catch {
+            return fail('error.rules.notFound', `回收站条目不存在：${trashId}`);
+        }
+        await rm(dir, { recursive: true, force: true });
+        return { ok: true };
+    }
+    return { rulesRemove, rulesRestore, rulesTrashList, rulesTrashRemove };
+}

package/lib/paths.js

@@ -0,0 +1,103 @@
+// dsh-plugin-tool-management —— 路径段与根内约束的**唯一口径**。
+//
+// 为什么单独抽一个模块：名字校验此前散在五处（rules / subagents / imports / skills /
+// preset-id），每处各写一套，口径不一 —— 有的漏 Windows 保留设备名（`CON` / `NUL`），
+// 有的漏 `\0` 与控制字符。于是「同一个名字在 A 域能建、在 B 域不能建」，而漏掉的那两样
+// 恰好都是**文件系统层面**的问题：Windows 上以设备名创建目录会失败，NUL 会把路径截断。
+//
+// 职责边界（写清楚是为了不再长出第六份实现）：
+//   - 只判「这个字符串能不能安全地当一个路径段」，不管业务语义（是否保留字、是否重名、
+//     是否是 kebab-case）——那些留在各域；
+//   - 长度上限由调用方给（人设名 64、技能名 128…），因为那是各域自己的策略，不是安全边界。
+import { realpath } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+/** 段名默认长度上限（字符）。 */
+export const SEGMENT_MAX_LENGTH = 128;
+/** Windows 保留设备名：不区分大小写，带扩展名同样非法（`con.md` 也不行）。 */
+const WINDOWS_DEVICE_NAME_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+/** 路径分隔符：出现即意味着「不止一段」。 */
+const SEPARATOR_RE = /[\\/]/;
+/** Windows 保留字符。 */
+const RESERVED_CHAR_RE = /[<>:"|?*]/;
+/** 控制字符（含 NUL、换行、制表）：目录名与日志会不可读，NUL 还会截断路径。 */
+const CONTROL_CHAR_RE = /[\u0000-\u001f\u007f]/;
+/**
+ * 判断一个名字能否作为**单个**路径段。
+ * @param name - 待判定的名字；非字符串按不合法处理。
+ * @param maxLength - 该域自己的长度上限。
+ * @returns 不合法的原因；`null` 表示合法。
+ */
+export function segmentProblem(name, maxLength = SEGMENT_MAX_LENGTH) {
+    if (typeof name !== 'string' || name === '')
+        return 'empty';
+    if (name.length > maxLength)
+        return 'too-long';
+    if (name === '.' || name === '..')
+        return 'dot';
+    if (name.startsWith('.'))
+        return 'hidden';
+    if (SEPARATOR_RE.test(name))
+        return 'separator';
+    if (RESERVED_CHAR_RE.test(name))
+        return 'reserved-char';
+    if (CONTROL_CHAR_RE.test(name))
+        return 'control-char';
+    if (WINDOWS_DEVICE_NAME_RE.test(name))
+        return 'device-name';
+    // 首尾空白：Windows 会静默裁剪，导致磁盘上的名字与界面显示的名字不一致。
+    if (name !== name.trim())
+        return 'padding';
+    // 末尾的点同理（`foo.` 在 Windows 上落地成 `foo`）。
+    if (/[.\s]$/.test(name))
+        return 'trailing-dot-or-space';
+    return null;
+}
+/** 便捷判定：能安全当路径段即为真。 */
+export function isValidSegment(name, maxLength = SEGMENT_MAX_LENGTH) {
+    return segmentProblem(name, maxLength) === null;
+}
+/**
+ * `child` 是否就是 `parent` 本身或位于其下（纯字符串口径，不做 realpath）。
+ * 两侧先 `resolve`，因此 `a/../b` 这类写法不会误判成越界或反之。
+ * 跨盘符时 `relative` 会返回绝对路径，所以那种情况判为「不在其下」。
+ */
+export function isSameOrDescendant(parent, child) {
+    const rel = relative(resolve(parent), resolve(child));
+    return rel === '' || (!isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`));
+}
+/** `candidate` 是否落在 `root` 内（含根本身）。 */
+export function isInsideRoot(root, candidate) {
+    return isSameOrDescendant(root, candidate);
+}
+/**
+ * 解析路径的真实落点，**末级允许不存在**：逐级向上找到最近既存祖先做 realpath，
+ * 再把尚未存在的部分接回去。
+ *
+ * 为什么需要它而不是 `lstat`：`lstat` 只看末级。中间目录若是符号链接，
+ * `<root>/办公/x.md` 拼出来看着在根内，实际会写到链接指向的地方 ——
+ * 只有把中间段也解析成真实路径才拦得住。
+ */
+export async function realPathOf(path) {
+    let current = resolve(path);
+    const missing = [];
+    for (;;) {
+        try {
+            return resolve(await realpath(current), ...missing);
+        }
+        catch {
+            const parent = dirname(current);
+            if (parent === current)
+                return resolve(path);
+            missing.unshift(basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * 路径经 realpath 解析后是否仍在根内（含根本身）。
+ * 供「写入 / 删除之前」的根内断言使用，是 `isInsideRoot` 的防符号链接版本。
+ */
+export async function isInsideRootResolved(root, candidate) {
+    const [rootReal, candidateReal] = await Promise.all([realPathOf(root), realPathOf(candidate)]);
+    return isSameOrDescendant(rootReal, candidateReal);
+}

package/lib/prompts/preset-id.js

@@ -0,0 +1,49 @@
+// dsh-plugin-tool-management —— 提示词预设 id 的唯一口径。
+//
+// 用户裁定（2026-09-15）：「id 应该什么都能写」——不再限定小写字母/数字/连字符，
+// 中文、空格、下划线、点都可以。id 同时也是**磁盘目录名**，所以只保留两类硬约束：
+//   ① 文件系统安全：交由 `../paths.js` 的共享谓词判定（不含路径分隔符与 Windows 非法字符、
+//      不以点开头/结尾、不是 `.` / `..`、不是 Windows 保留设备名、不含控制字符）；
+//   ② 一个保留字：`__last-applied__`（apply 的备份槽，不是用户预设）。
+// 这套口径由提示词服务（prompts/ 目录）与场景绑定（`scenes[].prompt`）共用，避免两处漂移。
+// 约定镜像 @deepseek-ai/dsh-agent-presets 的「id 即目录名」，但放宽了字符集。
+import { segmentProblem } from '../paths.js';
+/** id 长度上限（字符数；目录名过长在 Windows 上还受 MAX_PATH 约束）。 */
+export const PRESET_ID_MAX = 64;
+/** apply 的备份槽：不是用户预设，任何入口都不得当作预设 id。 */
+export const LAST_APPLIED_PRESET_ID = '__last-applied__';
+/** 把共享谓词给的原因翻成这个域自己的文案：规则只有一份，消息留在这里。 */
+function presetIdProblemText(problem, id) {
+    switch (problem) {
+        case 'empty': return 'id 不能为空';
+        case 'too-long': return `id 过长（≤${PRESET_ID_MAX} 字符，当前 ${id.length}）`;
+        case 'dot': return 'id 不能是「.」或「..」';
+        case 'hidden': return 'id 不能以「.」开头';
+        case 'separator': return 'id 不能含路径分隔符（/ 或 \\）';
+        case 'reserved-char': return 'id 不能含 < > : " | ? * 这些字符';
+        case 'control-char': return 'id 不能含控制字符';
+        case 'device-name': return `「${id}」是 Windows 保留设备名`;
+        case 'padding': return 'id 不能含首尾空白';
+        case 'trailing-dot-or-space': return 'id 不能以点或空格结尾（Windows 会静默去掉）';
+    }
+}
+/**
+ * 校验并归一化一个预设 id。
+ * @param raw - 用户输入或来自索引的原始值。
+ * @returns `{ ok: true, id }`（已 trim）或 `{ ok: false, error }`（给人看的中文原因）。
+ */
+export function normalizePresetId(raw) {
+    const id = String(raw ?? '').trim();
+    if (id === LAST_APPLIED_PRESET_ID)
+        return { ok: false, error: `「${LAST_APPLIED_PRESET_ID}」是「应用」的备份槽，不能用作预设 id` };
+    // 文件系统安全那一组交给共享谓词（`../paths.js`）—— 此前这里与 rules / subagents /
+    // imports / skills 各写一套，五份实现迟早会漂。长度上限仍是本域自己的策略。
+    const problem = segmentProblem(id, PRESET_ID_MAX);
+    if (problem !== null)
+        return { ok: false, error: presetIdProblemText(problem, id) };
+    return { ok: true, id };
+}
+/** 便捷判定（索引解析等只关心"能不能用"的地方）。 */
+export function isValidPresetId(raw) {
+    return normalizePresetId(raw).ok;
+}

package/lib/{agents-md → prompts}/service.js

@@ -30,7 +30,7 @@ const APPLIED_FILE = '__applied__.json';
 const BLANK_TEMPLATE = '# AGENTS.md\n\n（DSH 全局指令基线预设，待编辑）\n';
 /** 全局 AGENTS.md 的备份代际上限：与 mcpm patch 的 KEEP_PATCH_BACKUPS 同纪律。 */
 const KEEP_GLOBAL_BACKUPS = 5;
-export function createAgentsMdService(_ctx, deps) {
+export function createPromptsService(_ctx, deps) {
     const message = (e) => String((e && e.message) || e);
     /** 校验 id 并返回错误文本（合法时返回 `null`）。 */
     const idError = (raw) => {

package/lib/request-gate.js

@@ -0,0 +1,320 @@
+// HTTP 请求准入与 handlers 后处理（原 index.ts apply() 闭包内四段，2026-09-19 抽出）。
+//
+// 这一域管「谁能改、改哪些、什么时候不许改」：
+//   * 访问令牌（可选）—— 两条用途：宿主浏览器鉴权的逃生口，以及写操作的纵深防御；
+//   * 写 / 敏感 op 白名单 —— 哪些 op 要凭令牌（含"只读但会泄露明文"与"只读但会改宿主状态"）；
+//   * 场景锁定 —— 任一场景 locked=true 时五个管理域整体冻结；
+//   * handlers 后处理 —— 把上面三条装到 op 表上（包装顺序即语义，见 installHandlerGuards）。
+//
+// 为什么抽出来：四段分散在 apply() 的 220 / 902 / 1650 / 1928，靠闭包共享 handlers 与
+// memoriesService。抽成工厂后依赖改为显式入参，index.ts 只剩四行装配 —— 而引用点用解构
+// 保持原名字，一行没动（改名才是这类搬迁最容易出静默错误的地方）。
+//
+// **一处必须守住的不变量**：handlers 的后处理顺序。`guardLockedOps` / `syncSceneArchiveOnSwitch`
+// 都是「读原函数 → 换包装」的原地改写，先装的在内层、后装的在外层；`annotateLocked` 只挂在
+// 五个读 op 上。整段照搬、顺序未变。
+import { createHash, timingSafeEqual } from 'node:crypto';
+/**
+ * 建访问令牌三件套。**必须**从 apply 的第二个参数取配置 ——
+ * 读 `ctx.config` 不是注入服务，启动时会抛 "cannot get property without inject"。
+ */
+export function createAccessToken(deps) {
+    const { config } = deps;
+    // Optional access token. Enabled by setting `config.token` on this plugin's
+    // loader row (profile cordis.patch.yml override) or the
+    // DSH_PLUGIN_TOOL_MANAGEMENT_TOKEN env var. Two roles now:
+    //   1. escape hatch — a correct token is accepted *in place of* the host's
+    //      browser authentication, so curl/scripts and LAN tooling keep working;
+    //   2. defense in depth — when set, every state-changing op additionally
+    //      requires `x-dsh-token: <token>`.
+    // It is NOT the primary gate anymore: the route calls the host's
+    // connection.requestRejection fence first (Host must be loopback/LAN
+    // IP-literal → defeats DNS rebinding, plus browser-session cookie auth),
+    // so an unset token no longer means "anyone may call writes".
+    // NOTE: the entry config arrives as the SECOND apply argument (Cordis
+    // calls `callback(ctx, config)`) — never read it off `ctx.config`, which
+    // is not an injected service and throws "cannot get property without
+    // inject" at boot.
+    const CONFIG_TOKEN = String(config?.token || process.env.DSH_PLUGIN_TOOL_MANAGEMENT_TOKEN || '').trim();
+    /**
+     * `config.tokenDisabled: true` = 令牌**留在配置里**但当前不生效（用户主动关掉）。
+     *
+     * 与"没配令牌"的区别（用户裁定 2026-09-19）：关掉之后随时能开回来，不需要重新输一遍；
+     * 两者对写操作的要求一样 —— 都不带令牌。
+     */
+    const TOKEN_DISABLED = config?.tokenDisabled === true;
+    /** 写门禁用的**生效**令牌：关掉即视为没配（配置里的值原样保留）。 */
+    const TOKEN = TOKEN_DISABLED ? '' : CONFIG_TOKEN;
+    // 令牌比较走「双侧 sha256 → timingSafeEqual」：摘要定长 32 字节，无需长度分支
+    // （直接比较不等长 Buffer 会抛），逐字节的耗时不随匹配前缀长度变化 —— JS 的 ===
+    // 逐字符短路，理论上可被计时侧信道逐位猜测。
+    // 比较的是**存量**令牌（CONFIG_TOKEN）而不是生效值：关掉之后仍然要凭它才能开回来 /
+    // 换掉 / 看明文（要求 9：关闭令牌需要验证当前的令牌）。
+    const tokenMatches = (presented) => timingSafeEqual(createHash('sha256').update(presented).digest(), createHash('sha256').update(CONFIG_TOKEN).digest());
+    // 本次**进程**的标识（用户裁定 2026-09-18 第 3 条：「每次启动只用填一次，退出进程后再启动就要重填」）。
+    // 界面把"填过的令牌"和这个值绑在一起存，读到不同值就作废 —— 于是重启后必须重填，
+    // 而同一次运行内刷新页面不必重填。
+    //
+    // 用 pid + 进程启动时刻，而不是每次 apply 现生成的随机串：apply 在 HMR / 重复挂载时会再跑一次，
+    // 那时候换掉 BOOT_ID 会把用户刚填好的令牌判成过期（表现为"刚填完又要求填"）。
+    // 进程启动时刻由 `Date.now() - uptime()` 反推，同一进程内恒定、跨进程几乎不会撞。
+    const BOOT_ID = (() => {
+        try {
+            return process.pid + '-' + Math.round(Date.now() - process.uptime() * 1000);
+        }
+        catch {
+            return 'unknown';
+        }
+    })();
+    /**
+     * 「本次启动已经验过令牌」的闩。验过即置位；唯一的手动清零入口是 `unmarkAccepted`
+     * （「清除令牌」走的 `token-unaccept`，见上）。重启自然清零。
+     *
+     * 用途：`agent/pre-step` 的令牌门禁要回答"这台机器现在是不是还没人验过令牌"，而它看不到
+     * 浏览器请求头。HTTP 入口是唯一知道答案的地方（那里才知道 `x-dsh-token` 对不对），
+     * 所以由入口在验过时置位，门禁读这一个布尔 —— 两边不共享别的东西。
+     *
+     * 注意它**不是**"当前请求带没带令牌"：带上之后页面刷新、切页、轮询都不该再要求重填，
+     * 而这与界面的 bootId 口径一致（同一进程内只需填一次）。
+     *
+     * 已知边界：闩按**进程**记，不区分浏览器 —— 同一启动里任何一个客户端验对过，其它
+     * 客户端的对话也放行。这是"填一次只管本次启动"（裁定 2026-09-18 第 3 条）在 pre-step
+     * 只能看宿主全局状态下的固有代价；外层还有宿主的连接围栏（回环 / 局域网字面量 +
+     * 浏览器会话 cookie）兜着。
+     */
+    let accepted = false;
+    return {
+        CONFIG_TOKEN,
+        TOKEN_DISABLED,
+        TOKEN,
+        tokenMatches,
+        BOOT_ID,
+        acceptedThisBoot: () => accepted,
+        markAccepted: () => { accepted = true; },
+        unmarkAccepted: () => { accepted = false; },
+    };
+}
+/** 建白名单。必须在四个 service 创建之后构造（依赖其 writeOps）。 */
+export function createOpWhitelist(deps) {
+    // HTTP 写操作门禁清单。skills/rules/档案引擎域由各自 service 导出的 writeOps 派生
+    // （与其 ops 表同文件维护，新增写 op 改对应 service 即可）；本文件内联域
+    // （mcpm-* / skill-open / agentsmd-* / history-*）在此列举。
+    // 注意：必须在上述 service 创建之后构造（依赖其 writeOps）。
+    const WRITE_OPS = new Set([
+        ...deps.writeOps.skills,
+        ...deps.writeOps.memories,
+        ...deps.writeOps.archives,
+        ...deps.writeOps.subagents,
+        'mcpm-add', 'mcpm-edit', 'mcpm-remove', 'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-restart',
+        'mcpm-compact',
+        'mcpm-export', 'mcpm-import', 'mcpm-note', 'mcpm-settings', 'mcpm-tool-enabled',
+        // mcpm-tools-refresh 为了拿实时工具表会临时启用目标服务器、结束后恢复原状（两次
+        // writePatch），恢复失败还会停留在启用态 —— 是写不是读，按写门禁（与 mcpm-restart
+        // 已在清单同理；0.6.0/0.7.0 已有两次写 op 漏列前科）。
+        'mcpm-tools-refresh',
+        // mcpm-reveal returns UNMASKED secrets; even though it is a read, it is
+        // token-gated like a write — on a LAN-exposed port the token must be the
+        // last line of defense for plaintext credentials too, not just writes.
+        'mcpm-reveal',
+        'skill-open',
+        // preset-tools 是只读枚举，但枚举会为预设建立 standing mount（官方语义：每进程只挂一次）。
+        // 未授权调用者不该触发挂载 —— 按写门禁。
+        //
+        // 这条规则的范围写清楚，别当成"凡会写盘就入门禁"：`history-list` / `history-sessions`
+        // 每次都会写工作区快照、`rules-list` / `rules-read` / `rules-diagnose` 会整份覆盖写
+        // `memories-index.json`、`mcpm-list` / `mcpm-tools` 回写 `mcp-known-tools.json` ——
+        // 五个都是读 op 且**不在本清单**。判据是"会不会改**宿主或外部系统**的状态"：
+        // standing mount 改的是宿主进程，而上面那些写的是插件自己的侧车（丢了可重建）。
+        // 想要它们也带令牌就显式加进来，别靠"读操作带副作用"这句话推。
+        'preset-tools',
+        // 提示词写操作（create/update/remove 改预设库；apply 写全局 AGENTS.md；import 从外部内容建预设）
+        'agentsmd-create', 'agentsmd-update', 'agentsmd-apply', 'agentsmd-remove', 'agentsmd-import',
+        // 提示词预设的回收站（恢复 / 永久删除都是写）
+        'agentsmd-trash-restore', 'agentsmd-trash-delete',
+        // history 写操作（archive/unarchive 改归档集合；delete 永久删除；retention-set 写保留期；
+        // workspace-register 会新增一条宿主工作区登记，同样是写）
+        'history-archive', 'history-unarchive', 'history-delete', 'history-retention-set',
+        'history-unarchive-batch', 'history-delete-batch', 'history-import', 'history-export',
+        // 通用导出：往用户指定的目录写文件，按写操作门禁（token）。
+        'bundle-export',
+        'history-archive-batch', 'history-workspace-register',
+        // 注入设置（五个域开关 / 压制型预设口径）写侧车，按写操作门禁。
+        'inject-settings',
+        // 清理 patch 备份：删磁盘文件（含明文凭据副本），按写操作门禁。
+        'backups-clean',
+    ]);
+    // 会泄露明文凭据 / 完整配置的 op：**必须**带对的访问令牌，没配令牌就一律拒绝
+    // （判定在 http-fence.ts 的 secretOpRejection，含两种情况的区分与理由）。
+    const SENSITIVE_OPS = new Set(['mcpm-reveal', 'mcpm-export']);
+    return { WRITE_OPS, SENSITIVE_OPS };
+}
+// ---------- 场景锁定守卫（v0.8）----------
+// 任一场景 locked=true = 五个管理域（MCP/技能/子智能体/记忆/提示词）整体冻结：
+// 下面列出的写 op 一律拒绝；界面按钮同步禁用，这里是兜底（防止绕过界面直接打 op）。
+// 只包 **handlers** 这一层是有意的：进/退模式的运行时应用走的是内部函数与
+// service.ops（applyMcpServerSwitches / applySkills / applySubagentSwitches / patchIndex），
+// 不经过 handlers —— 锁定就是为了让场景能按原样启动，运行时应用不能被自己挡住。
+// 例外里的例外：scene-archive-save / rules-remove-scene 只对**被锁的那个场景**拒绝。
+export function createSceneLock(deps) {
+    async function lockedSceneNames() {
+        const r = await deps.readSceneList();
+        return ((r && r.scenes) || []).filter((s) => s.locked === true).map((s) => String(s.name));
+    }
+    /** 当前启用（= 已进入）的那个场景名；没有则 null。 */
+    async function activeSceneName() {
+        try {
+            const r = await deps.readSceneList();
+            return r && r.ok && r.activeScene ? String(r.activeScene) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 「当前场景已锁定」的拒绝文案（模型工具用；无活动场景 / 未锁定 → null）。 */
+    async function lockedSceneGuard() {
+        const scene = await activeSceneName();
+        if (!scene)
+            return null;
+        const locked = await lockedSceneNames();
+        return locked.includes(scene) ? `场景「${scene}」已锁定：先到场景页解锁再改。` : null;
+    }
+    return { lockedSceneNames, activeSceneName, lockedSceneGuard };
+}
+export function installHandlerGuards(deps) {
+    const { handlers, lockedSceneNames, activeSceneName, syncSwitchToScene, subagentToolFailures } = deps;
+    /**
+     * 包一层：开关成功后把改动同步进当前场景档案（见 syncSwitchToScene）。
+     * 失败只挂 `sceneSyncError`，不改写原操作的成功结论 —— 运行时确实改了，档案没跟上要说得清。
+     * 锁定仍由 `guardLockedOps` 挡住（更靠内的那层包装先执行）。
+     */
+    function syncSceneArchiveOnSwitch(opNames) {
+        for (const opName of opNames) {
+            const original = handlers[opName];
+            if (typeof original !== 'function')
+                continue;
+            handlers[opName] = async (args) => {
+                const res = await original(args);
+                if (!res || res.ok === false)
+                    return res;
+                const err = await syncSwitchToScene(opName, args);
+                return err ? { ...res, sceneSyncError: err } : res;
+            };
+        }
+    }
+    function guardLockedOps(opNames, what) {
+        for (const opName of opNames) {
+            const original = handlers[opName];
+            if (typeof original !== 'function')
+                continue;
+            handlers[opName] = async (args) => {
+                const locked = await lockedSceneNames();
+                if (locked.length)
+                    return { ok: false, error: `场景已锁定（${locked.join('、')}）：先到场景页解锁再${what}` };
+                return original(args);
+            };
+        }
+    }
+    guardLockedOps([
+        // MCP：改配置 / 服务器启停 / 工具启停 / 导入导出配置 / 备注 / 设置。
+        // restart 仍放行（它是"重连"这条恢复路径），但它**不是只读**：实现会两次 `writePatch`
+        //（先强制停用、轮询、再按重启前状态恢复）。所以它不改的是**用户选的启停值**，
+        // 不是"不碰补丁文件" —— 锁定期间它是唯一能落盘改补丁的入口，进程中断会把服务器
+        // 留在停用态。别按"只重连"去理解它。
+        'mcpm-add', 'mcpm-edit', 'mcpm-remove', 'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-tool-enabled', 'mcpm-import', 'mcpm-compact', 'mcpm-note', 'mcpm-settings',
+        // 技能：启停 / 来源启停与移除恢复 / 首选 / 删除 / 创建导入 / 自定义目录 / 回收站 / 批量启停。
+        'skill-enable', 'skill-disable', 'skill-source-enable', 'skill-source-disable', 'skill-source-remove', 'skill-source-restore',
+        'skill-prefer', 'skill-unprefer', 'skill-delete', 'skill-create', 'skill-import', 'skill-upload', 'skill-set-all',
+        'skill-custom-add', 'skill-custom-remove', 'skill-trash-restore', 'skill-trash-delete',
+        // 子智能体：开关 / 改名保存 / 删除 / 导入 / 回收站。
+        'subagent-create', 'subagent-update', 'subagent-delete', 'subagent-toggle', 'subagent-import', 'subagent-trash-restore', 'subagent-trash-delete',
+        // 记忆：增删改 / 开关 / 导入 / 回收站 / 绑定。set-active 是场景启停，不在冻结范围。
+        'rules-create', 'rules-update', 'rules-remove', 'rules-toggle', 'rules-import', 'rules-restore', 'rules-trash-remove', 'rules-attach', 'rules-detach', 'rules-set-index',
+        // 提示词：建改删 / 应用（切换生效基线）/ 导入 / 回收站。
+        'agentsmd-create', 'agentsmd-update', 'agentsmd-remove', 'agentsmd-apply', 'agentsmd-import', 'agentsmd-trash-restore', 'agentsmd-trash-delete',
+    ], '修改');
+    // 场景内「开关」类操作（用户裁定 2026-09-17）：未锁定时**可用**，改动同步进当前场景档案。
+    // 与「锁定」正交：锁定冻结全部写操作，这里只是把页面开关的意图也写进档案。
+    syncSceneArchiveOnSwitch([
+        'mcpm-set-enabled', 'mcpm-set-all', 'mcpm-tool-enabled',
+        'skill-enable', 'skill-disable', 'skill-set-all', 'skill-source-enable', 'skill-source-disable',
+        'subagent-toggle',
+    ]);
+    // `rules-set-active` 不在 `guardLockedOps` 里（场景启停本身要可用），但它能把**当前
+    // 场景清空** —— 而「当前场景已锁定」是模型侧 `lockedSceneGuard` 唯一的判据，场景一空
+    // 它就返回 null，四个写工具全部放开，运行时却仍是那个场景的档案态（2026-09-19 审计
+    // T-32）。所以这里单独挡一刀：锁着的场景正在生效时，不许改启用集合（先解锁再说）。
+    // 没有锁定场景在生效时（全局态 / 场景未锁）照旧可用 —— 那本来就是允许的。
+    for (const [opName, what] of [['rules-set-active', '切换场景']]) {
+        const original = handlers[opName];
+        if (typeof original !== 'function')
+            continue;
+        handlers[opName] = async (args) => {
+            const scene = await activeSceneName();
+            if (scene && (await lockedSceneNames()).includes(scene)) {
+                // 同集合的重复提交放行：它没有改变任何东西，不该被"冻结"挡下来。
+                const current = new Set([scene]);
+                const next = new Set((Array.isArray(args && args.scenes) ? args.scenes : [])
+                    .map((n) => String(n == null ? '' : n).trim())
+                    .filter((n) => n !== ''));
+                const same = current.size === next.size && [...current].every((n) => next.has(n));
+                if (!same) {
+                    return { ok: false, error: `场景「${scene}」已锁定：先到场景页解锁再${what}（锁定期间改启用集合会让模型侧的写门禁失效）` };
+                }
+            }
+            return original(args);
+        };
+    }
+    // 被锁场景自身的档案与删除：只挡它自己，别的场景照常。
+    for (const [opName, pickScene, what] of [
+        ['scene-archive-save', (args) => (args && args.scene) || '', '改档案'],
+        ['rules-remove-scene', (args) => (args && args.name) || '', '删除'],
+    ]) {
+        const original = handlers[opName];
+        if (typeof original !== 'function')
+            continue;
+        handlers[opName] = async (args) => {
+            const scene = String(pickScene(args) || '').trim();
+            const locked = await lockedSceneNames();
+            if (scene && locked.includes(scene))
+                return { ok: false, error: `场景「${scene}」已锁定：先解锁再${what}` };
+            return original(args);
+        };
+    }
+    // 各页列表响应带上 anyLocked + activeScene：界面据此禁用写控件、并说明
+    // 「当前处于场景 X，开关请到档案里改」（读 op，附加字段不影响既有消费方）。
+    async function annotateLocked(res) {
+        if (res && res.ok !== false) {
+            const locked = (await lockedSceneNames()).length > 0;
+            const scene = await activeSceneName();
+            res.anyLocked = locked;
+            res.activeScene = scene;
+            // 信封里再套一层 `data` 的 op（`skill-state` 就是）必须**同时**写进 `data`：
+            // 客户端 callApi 只把 `data` 交给页面，外层字段在那一层就被丢掉了 ——
+            // 于是"服务端明明标了、技能页两个横幅却从来不显示"（2026-09-19 用户报的）。
+            if (res.data && typeof res.data === 'object') {
+                res.data.anyLocked = locked;
+                res.data.activeScene = scene;
+            }
+        }
+        return res;
+    }
+    for (const opName of ['mcpm-list', 'mcpm-reveal', 'skill-state', 'subagent-list', 'agentsmd-list']) {
+        const original = handlers[opName];
+        if (typeof original !== 'function')
+            continue;
+        handlers[opName] = async (args) => annotateLocked(await original(args));
+    }
+    // 子智能体页面横幅的数据源：注册失败的工具名与原因随列表一起带出去（同一处 attach 的
+    // 语义，见上方 annotateLocked）。失败清单在 apply 期间就定下来了，这里只是挂上去。
+    {
+        const original = handlers['subagent-list'];
+        if (typeof original === 'function') {
+            handlers['subagent-list'] = async (args) => {
+                const res = await original(args);
+                if (res && res.ok !== false)
+                    res.toolFailures = subagentToolFailures.map((f) => ({ ...f }));
+                return res;
+            };
+        }
+    }
+}