dsh-plugin-tool-management 0.16.5 → 0.17.0

package/lib/ops/snapshot.js

@@ -14,8 +14,9 @@
 //      导出物不该顺手把它们带走；要完整导出必须显式传 `includeSecrets:true`（界面二次确认）。
 //      打码值导回来由 `secret-guard` 拿目标机的旧真值顶替（`mcpm-import` 既有的行为）。
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 import { unzipSync, zipSync } from 'fflate';
+import { maskSecretValue, maskUrlQuery } from '../mcp/secret-guard.js';
 const SNAP_PREFIX = 'dsh-tool-management-snapshot-';
 /** 快照目录里各部分的名字（导入侧按这些名字找东西，别改）。 */
 const F_MANIFEST = 'manifest.json';
@@ -29,7 +30,6 @@ 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'];
-const MASKED = '••••••';
 function stamp() {
     return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
 }
@@ -110,6 +110,43 @@ function namesOf(res, prefer) {
     }
     return [];
 }
+/**
+ * 从 `skill-state` 的返回里取「<来源>/<技能名>」清单。
+ *
+ * 为什么不能复用 `namesOf`（2026-09-30 审查 P1-6）：`skill-state` 的形状是
+ * `{ ok, data: { roots: [{ key, skills: [{ name, declaredName, … }] }] } }` —— 顶层键是
+ * `roots`，而 `namesOf` 只找 `rows / personas / presets / scenes / skills / list / entries /
+ * items` 这些**数组**键，一个都对不上 → 恒返回 `[]` → 技能域**永远导出 0 项**，而界面显示的
+ * 是"迁移完成"。key 用**声明名**（frontmatter `name`），口径与 `index.ts` 的
+ * `skillArchiveKeysOfRoot` 一致（档案里存的就是声明名，用条目名拼会在 stale 校验里被丢掉）。
+ */
+function skillKeysOf(res) {
+    if (!res || res.ok === false)
+        return [];
+    for (const bag of [res.data, res].filter(Boolean)) {
+        const roots = bag.roots;
+        if (!Array.isArray(roots))
+            continue;
+        const out = [];
+        for (const root of roots) {
+            const rootKey = String(root?.key || '');
+            if (!rootKey)
+                continue;
+            const skills = root.skills;
+            if (!Array.isArray(skills))
+                continue;
+            for (const sk of skills) {
+                const s = sk;
+                const name = String((s && (s.declaredName || s.name)) || '');
+                if (name)
+                    out.push(rootKey + '/' + name);
+            }
+        }
+        if (out.length)
+            return out;
+    }
+    return [];
+}
 /** 场景清单（带 label / description / 提示词绑定）：`rules-list` 的 scenes 那一栏，读不到就是空。 */
 function sceneRecordsOf(res) {
     const bags = [res && res.data, res].filter(Boolean);
@@ -128,11 +165,18 @@ function sceneRecordsOf(res) {
     }
     return [];
 }
+/**
+ * 键值对打码：**走 `secret-guard` 的唯一口径**（`$VAR` / `!!js` 这类间接引用原样保留）。
+ *
+ * 这里曾经自己写了一份「所有键一律打成 `••••••`」的版本 —— 与 MCP 列表视图的口径不一致，
+ * 结果是配置里的间接引用被当成密钥导出、导回来时 `resolveMaskedKv` 顶替不出真值只能丢键。
+ * 打码形态只允许有一处定义（审查 P0-4）。
+ */
 function maskKv(map) {
     const out = {};
     if (map && typeof map === 'object' && !Array.isArray(map)) {
         for (const k of Object.keys(map))
-            out[k] = MASKED;
+            out[k] = maskSecretValue(map[k]);
     }
     return out;
 }
@@ -175,8 +219,14 @@ export function createSnapshotOps(deps) {
                 copy.env = maskKv(copy.env);
             if (copy.headers)
                 copy.headers = maskKv(copy.headers);
+            // URL 查询串走 `secret-guard.maskUrlQuery`（与 MCP 列表视图同一口径）。这里原先是**自写的
+            // 一条窄正则** `([?&](?:key|token|secret|password)=)`，只认四个固定参数名 ——
+            // `?api_key=` / `?access_token=` / `?sig=` / `?client_secret=` 这类 MCP 托管服务最常见的
+            // 形态全部漏掉，而这正是「凭据挂在 URL 上」的主流写法。后果不是界面显示问题：默认
+            // （`includeSecrets` 缺省 false）导出的 `mcp.json` 里就是**明文凭据**，而这份目录的用途
+            // 就是拷去 U 盘 / 网盘 / 另一台机器（审查 P0-4）。
             if (typeof copy.url === 'string')
-                copy.url = copy.url.replace(/([?&](?:key|token|secret|password)=)[^&]*/gi, '$1' + MASKED);
+                copy.url = maskUrlQuery(copy.url);
             return copy;
         });
         try {
@@ -215,7 +265,7 @@ export function createSnapshotOps(deps) {
         }
         // ── 技能：源目录在外部（不在 hub），交给既有的 `bundle-export` 走它自己的收集路径 ──
         const skillState = await deps.invokeOp('skill-state', {});
-        const skillKeys = namesOf(skillState, ['key']).filter((k) => k.indexOf('/') > 0);
+        const skillKeys = skillKeysOf(skillState);
         if (!skillKeys.length)
             notes.push('技能这次没导出：没从 skill-state 读到「<来源>/<名字>」形态的清单');
         if (skillKeys.length) {
@@ -385,13 +435,23 @@ export function createSnapshotOps(deps) {
             return { ok: false, error: read.error };
         const { files } = read;
         const report = [];
-        /** 一个域失败只记在这一行上：迁移的意义正是「哪域没过来」看得清，不是整批回滚。 */
+        /**
+         * 一个域失败只记在这一行上：迁移的意义正是「哪域没过来」看得清，不是整批回滚。
+         *
+         * `warning` 也要透传（2026-09-30 审查 P2-9）：各域的 import op 会用它报"带过来了但有
+         * 东西被跳过"（`mcpm-import` 的「这些密钥已是打码占位符，请在编辑里重新填写」就是其中
+         * 最重要的一条）。此前只取 imported/skipped，于是"迁移成功"的界面下藏着一份**需要用户
+         * 动手补的密钥清单**，用户在另一台机器上等到调用工具时才发现。
+         */
         async function run(domain, task) {
             if (domains.indexOf(domain) < 0)
                 return;
             try {
                 const r = await task();
-                report.push({ domain, imported: r.imported, skipped: r.skipped });
+                report.push({
+                    domain, imported: r.imported, skipped: r.skipped,
+                    ...(r.warning ? { warnings: [r.warning] } : {}),
+                });
             }
             catch (e) {
                 report.push({ domain, imported: 0, skipped: 0, error: deps.message(e) });
@@ -404,7 +464,12 @@ export function createSnapshotOps(deps) {
             const res = await deps.invokeOp('mcpm-import', overwrite ? { json: raw, conflict: 'overwrite' } : { json: raw });
             if (!res || res.ok === false)
                 throw new Error(String((res && res.error) || 'mcpm-import 失败'));
-            return { imported: (res.added || []).length + (res.overwritten || []).length, skipped: (res.skipped || []).length };
+            return {
+                imported: (res.added || []).length + (res.overwritten || []).length,
+                skipped: (res.skipped || []).length,
+                // 「打码占位符被跳过」这类结论必须跟着走：它是用户要动手补的清单，不是内部细节。
+                ...(typeof res.warning === 'string' && res.warning ? { warning: res.warning } : {}),
+            };
         });
         await run(D_SUBAGENTS, async () => {
             const zip = files[D_SUBAGENTS + '.zip'];
@@ -499,6 +564,7 @@ export function createSnapshotOps(deps) {
                 (byScene[scene] || (byScene[scene] = [])).push({ name, data: Buffer.from(bytes).toString('base64') });
             }
             let imported = 0;
+            const reasons = [];
             for (const scene of Object.keys(byScene)) {
                 const res = await deps.invokeOp('rules-import', { scene, files: byScene[scene] });
                 if (!res || res.ok === false) {
@@ -507,9 +573,19 @@ export function createSnapshotOps(deps) {
                 }
                 const data = res.data || res;
                 imported += (data.imported || []).length;
-                skipped += (data.skipped || []).length;
+                const skippedRows = Array.isArray(data.skipped) ? data.skipped : [];
+                skipped += skippedRows.length;
+                // `rules-import` 的 skipped 是 `{name, reason}` —— 只数个数会把「为什么没过来」
+                // 丢掉，而那正是用户要照着修的东西（名字不合法 / 正文超限 / 附件重名）。
+                // 上限 5 条：这是提示不是日志，界面上一行放不下更多（审查 P2-9 同一条口径）。
+                for (const row of skippedRows.slice(0, 5)) {
+                    const name = String((row && row.name) || '');
+                    const reason = String((row && row.reason) || '');
+                    if (reason)
+                        reasons.push(`${name ? name + '：' : ''}${reason}`);
+                }
             }
-            return { imported, skipped };
+            return { imported, skipped, ...(reasons.length ? { warning: reasons.join('；') } : {}) };
         });
         await run('scenes', async () => {
             if (!files[F_SCENES])
@@ -577,9 +653,26 @@ export function createSnapshotOps(deps) {
             let imported = 0;
             let skipped = 0;
             for (const zip of zips) {
-                const res = await deps.invokeOp('skill-import', overwrite ? { source: zip, conflict: 'overwrite' } : { source: zip });
+                // 走 `skill-upload`（把 zip 读成 base64）而**不是** `skill-import`（2026-09-30 审查 P1-6）：
+                // 导出侧产出的是 `bundle-export` 打的**一个 zip**（内含 `<技能名>/<文件>`），而
+                // `skill-import` 的 `analyzeSource` 用 `lstat` + `endsWith('.md')` 判定来源，**完全不认识
+                // `.zip`** —— 喂过去必然 `error.source.unrecognized`，该域整行报错。zip 的解包只存在于
+                // `skill-upload` 这条链（`importUploadedSkill` → `prepareUploadedSource` → `writeUploadedZip`）；
+                // 已实测它能正确吃下这种形态（`<技能名>/SKILL.md` → 落 `hub/skills/<技能名>/`）。
+                let b64;
+                try {
+                    b64 = (await readFile(zip)).toString('base64');
+                }
+                catch (e) {
+                    throw new Error(`读取技能包失败：${deps.message(e)}`);
+                }
+                const res = await deps.invokeOp('skill-upload', {
+                    name: basename(zip).replace(/\.zip$/i, ''),
+                    zip: b64,
+                    ...(overwrite ? { conflict: 'overwrite' } : {}),
+                });
                 if (!res || res.ok === false)
-                    throw new Error(String((res && res.error) || 'skill-import 失败'));
+                    throw new Error(String((res && res.error) || 'skill-upload 失败'));
                 const data = res.data || {};
                 imported += (data.imported || []).length;
                 skipped += (data.skipped || []).length + (data.failed || []).length;

package/lib/ops/trash.js

@@ -2,7 +2,7 @@
 //
 // 删除进回收站、从回收站恢复、回收站列出与彻底删除。与记忆正文 ops 分域，
 // 但共用 copyIntoMemoriesTrash 等入口，经 MemoriesOpsCtx 显式传入。
-import { copyFile, lstat, mkdir, readFile, readdir, rm, stat } from 'node:fs/promises';
+import { copyFile, cp, 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';
@@ -45,7 +45,14 @@ export function buildTrashOps(rc) {
         catch {
             return fail('error.rules.notFound', `回收站条目不存在：${trashId}`);
         }
-        if (!manifest || typeof manifest.name !== 'string' || typeof manifest.group !== 'string' || !isValidGroupSegment(manifest.name)) {
+        if (!manifest || typeof manifest.name !== 'string' || typeof manifest.group !== 'string'
+            || !isValidGroupSegment(manifest.name)
+            // `group` 是**磁盘数据**（manifest.json 可能被手改 / 别的进程写 / 随一份恶意档案包进来），
+            // 而它是拼进 `join(memoriesRoot, group)` 的那一段 —— 只判类型的话 `../..` 就能把正文写到
+            // 记忆根之外（`mkdir({recursive:true})` 还会顺手把目录建出来）。同文件 `rulesTrashList`
+            // 一直是有这道判据的（`if (group !== '' && !isValidGroupPath(group)) continue`），
+            // 两条路径口径必须一致（审查 P0-3）。
+            || (manifest.group !== '' && !isValidGroupPath(manifest.group))) {
             return fail('error.rules.notFound', `回收站条目损坏：${trashId}`);
         }
         // 恢复目标已存在（期间用户重建了同名规则）→ 拒绝，避免覆盖。
@@ -54,14 +61,43 @@ export function buildTrashOps(rc) {
             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 });
+        // 落点根内断言（realpath 口径）：`isValidGroupPath` 只挡 `..` 与分隔符，挡不住
+        // 「中间目录是指向根外的链接」。与 `rulesRemove` 的删除前断言同一道闸。
+        const groupDir = join(memoriesRoot, manifest.group);
+        const denied = await refuseOutsideRoot(groupDir);
+        if (denied)
+            return denied;
+        // 恢复 = 先复制、后删回收站条目。**复制中途失败必须回滚**（2026-09-30 审查 F11）：
+        // 原来这里 `cp` / `copyFile` 都没有 try/catch，失败时目标留下半份内容、回收站条目仍在，
+        // 于是下一次点恢复会撞上面那条「同名记忆已存在」—— 这条记忆**永远恢复不了**，只能人工
+        // 去删目录。场景回收站（`sceneTrashRestore`）早有这条回滚（`moveIntoTrash` 反向搬回），
+        // 记忆回收站这条缺了。这里方向相反：源还在回收站，所以回滚是**删掉没放完整的副本**。
+        const target = form === 'bundle'
+            ? join(groupDir, manifest.name)
+            : join(groupDir, manifest.name + '.md');
+        try {
+            await mkdir(groupDir, { recursive: true });
+            if (form === 'bundle')
+                await cp(join(trashDir, 'bundle'), target, { recursive: true });
+            else
+                await copyFile(join(trashDir, 'rule.md'), target);
         }
-        else {
-            await mkdir(join(memoriesRoot, manifest.group), { recursive: true });
-            await copyFile(join(trashDir, 'rule.md'), join(memoriesRoot, manifest.group, manifest.name + '.md'));
+        catch (e) {
+            let cleaned = true;
+            try {
+                await rm(target, { recursive: true, force: true });
+            }
+            catch (cleanupError) {
+                // 落点**本来就没建成**时（父路径不是目录 → ENOTDIR；`force` 已吞掉 ENOENT），
+                // 没有残留要清，别把它报成「清理失败」——那会让用户去手工删一个不存在的路径。
+                const code = cleanupError?.code;
+                cleaned = code === 'ENOENT' || code === 'ENOTDIR';
+            }
+            // 清理失败也如实说清楚，别让用户以为还能原样重试。
+            const tail = cleaned
+                ? '（未放回完整的落点已清理，回收站条目仍在，可直接重试）'
+                : `（未放回完整的落点没能清理：${target}，请先手工删除再重试）`;
+            return fail('error.rules.ioFailed', `恢复记忆失败：${String(e?.message ?? e)}${tail}`);
         }
         await rm(trashDir, { recursive: true, force: true });
         invalidateSnapshot();

package/lib/prompts/service.js

@@ -17,6 +17,11 @@ import { join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { isValidPresetId, LAST_APPLIED_PRESET_ID, normalizePresetId } from './preset-id.js';
 import { listTrashEntries, moveOutOfTrash, moveToTrash, purgeTrashEntry, readTrashEntry } from '../hub.js';
+// 全局 AGENTS.md 的落盘走**原子写**（temp + rename，见 `memories/index-io.ts`）。
+// 为什么非它不可（2026-09-30 审查 P2-2）：这个文件是宿主**每个 agent/pre-step 都会 stat 并
+// 重读**的，裸 `writeFile` 在中断/断电时会留下**半截内容** —— 而半截的提示词会原样进模型
+// 上下文（截断点还可能在代码块中间）。原子写保证读到的是「要么旧、要么新」的完整内容。
+import { writeFileAtomically } from '../memories/index-io.js';
 const FILENAME = 'AGENTS.md';
 /** 描述侧车：与 AGENTS.md 同目录，避免描述的文字被当成提示词正文注入。 */
 const META_FILE = 'meta.json';
@@ -321,7 +326,7 @@ export function createPromptsService(_ctx, deps) {
         }
         const prev = await readGlobal();
         const backedUp = await backupGlobal(prev);
-        await writeFile(await deps.getGlobalAgentsMdPath(), content, 'utf8');
+        await writeFileAtomically(await deps.getGlobalAgentsMdPath(), content);
         await writeAppliedId(safeId);
         return { ok: true, id: safeId, backedUp };
     }
@@ -335,7 +340,7 @@ export function createPromptsService(_ctx, deps) {
         const prev = await readGlobal();
         const backedUp = await backupGlobal(prev);
         try {
-            await writeFile(await deps.getGlobalAgentsMdPath(), text, 'utf8');
+            await writeFileAtomically(await deps.getGlobalAgentsMdPath(), text);
         }
         catch (e) {
             return { ok: false, error: '写入全局 AGENTS.md 失败：' + message(e) };

package/lib/request-gate.js

@@ -4,18 +4,19 @@
 //   * 访问令牌（可选）—— 两条用途：宿主浏览器鉴权的逃生口，以及写操作的纵深防御；
 //   * 写 / 敏感 op 白名单 —— 哪些 op 要凭令牌（含"只读但会泄露明文"与"只读但会改宿主状态"）；
 //     清单本身在 `./op-registry.ts`，本文件只拼装（`opsWith` / `frozenOps`）。
-//   * 场景锁定 —— 任一场景 locked=true 时五个管理域整体冻结；
+//   * 场景锁定 —— 任一场景 locked=true 时五个管理域整体冻结。判据是 `createFrozenGate`，
+//     HTTP handlers 与**模型侧 op 表**各装一次，用的是同一份函数；
 //   * handlers 后处理 —— 把上面三条装到 op 表上（包装顺序即语义，见 installHandlerGuards）。
 //
 // 为什么抽出来：四段分散在 apply() 的 220 / 902 / 1650 / 1928，靠闭包共享 handlers 与
 // memoriesService。抽成工厂后依赖改为显式入参，index.ts 只剩四行装配 —— 而引用点用解构
 // 保持原名字，一行没动（改名才是这类搬迁最容易出静默错误的地方）。
 //
-// **一处必须守住的不变量**：handlers 的后处理顺序。`guardLockedOps` / `syncSceneArchiveOnSwitch`
+// **一处必须守住的不变量**：handlers 的后处理顺序。冻结包装 / `syncSceneArchiveOnSwitch`
 // 都是「读原函数 → 换包装」的原地改写，先装的在内层、后装的在外层；`annotateLocked` 只挂在
 // 五个读 op 上。整段照搬、顺序未变。
 import { createHash, timingSafeEqual } from 'node:crypto';
-import { frozenOps, opsWith } from './op-registry.js';
+import { OP_REGISTRY, frozenOps, opsWith } from './op-registry.js';
 /**
  * 建访问令牌三件套。**必须**从 apply 的第二个参数取配置 ——
  * 读 `ctx.config` 不是注入服务，启动时会抛 "cannot get property without inject"。
@@ -114,10 +115,13 @@ export function createOpWhitelist(deps) {
 }
 // ---------- 场景锁定守卫（v0.8）----------
 // 任一场景 locked=true = 五个管理域（MCP/技能/子智能体/记忆/提示词）整体冻结：
-// 下面列出的写 op 一律拒绝；界面按钮同步禁用，这里是兜底（防止绕过界面直接打 op）。
-// 只包 **handlers** 这一层是有意的：进/退模式的运行时应用走的是内部函数与
-// service.ops（applyMcpServerSwitches / applySkills / applySubagentSwitches / patchIndex），
-// 不经过 handlers —— 锁定就是为了让场景能按原样启动，运行时应用不能被自己挡住。
+// 冻结清单里的写 op 一律拒绝；界面按钮同步禁用，这里是兜底（防止绕过界面直接打 op）。
+//
+// 装在**哪一层**：HTTP handlers 一层 + 模型侧 op 表一层（index.ts 的 `auditOps`），
+// 两层用同一个判据（`createFrozenGate`）。**不装在 service.ops 上**是有意的：进/退模式的
+// 运行时应用走的是内部函数与 service.ops（applyMcpServerSwitches / applySkills /
+// applySubagentSwitches / patchIndex），不经过 handlers —— 锁定就是为了让场景能按原样启动，
+// 运行时应用不能被自己挡住。
 // 例外里的例外：scene-archive-save / rules-remove-scene 只对**被锁的那个场景**拒绝。
 export function createSceneLock(deps) {
     async function lockedSceneNames() {
@@ -144,12 +148,104 @@ export function createSceneLock(deps) {
     }
     return { lockedSceneNames, activeSceneName, lockedSceneGuard };
 }
+/** 「改它」的兜底动词（登记表里没有专门文案时用）。 */
+const FROZEN_DEFAULT_VERB = '修改';
+const ACTIVE_SCENE_LABEL = { 'rules-set-active': '切换场景' };
+const SELF_SCENE_LABEL = { 'scene-archive-save': '改档案', 'rules-remove-scene': '删除' };
+/**
+ * 场景冻结的**唯一判据**：`op` + `args` → 拒绝文案（null = 放行）。
+ *
+ * 三种口径的语义登记在 `./op-registry.ts` 的 `frozenScope` 上，这里只实现：
+ *   all          —— 只要有场景锁着就拒（不看 args）。
+ *   active-scene —— 只在"锁着的场景正在生效"且这次提交**改了启用集合**时拒
+ *                   （同集合的重复提交放行：它没改变任何东西，不该被"冻结"挡下来）。
+ *   self-scene   —— 只挡被锁的那个场景自己（目标从 `args.scene` / `args.name` 取）。
+ *
+ * 为什么抽成一个函数：HTTP handlers 与**模型侧 op 表**（index.ts 的 `auditOps`）必须用
+ * 同一份判据。此前只包 handlers —— 模型工具拿的是 `service.ops`，于是"锁一个**非活动**
+ * 场景"在 HTTP 上被拒、在模型侧五个域全放行（审查 F3，0.17.0 修）。判据只写一遍，
+ * 两侧就不可能再分家。
+ *
+ * 判据只读 `args`、不落盘，所以对同一次调用可以安全地判两次（handlers 与模型侧各一次）。
+ */
+export function createFrozenGate(deps) {
+    const { lockedSceneNames, activeSceneName } = deps;
+    return async function frozenRejection(op, args) {
+        const cls = OP_REGISTRY[op];
+        if (!cls || cls.frozen !== true)
+            return null;
+        const scope = cls.frozenScope ?? 'all';
+        if (scope === 'active-scene') {
+            const scene = await activeSceneName();
+            if (!scene || !(await lockedSceneNames()).includes(scene))
+                return null;
+            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 null;
+            const what = ACTIVE_SCENE_LABEL[op] ?? '改它';
+            return `场景「${scene}」已锁定：先到场景页解锁再${what}（锁定期间改启用集合会让模型侧的写门禁失效）`;
+        }
+        if (scope === 'self-scene') {
+            const scene = String((args && (args.scene || args.name)) || '').trim();
+            if (!scene)
+                return null;
+            if (!(await lockedSceneNames()).includes(scene))
+                return null;
+            return `场景「${scene}」已锁定：先解锁再${SELF_SCENE_LABEL[op] ?? '改它'}`;
+        }
+        const locked = await lockedSceneNames();
+        return locked.length ? `场景已锁定（${locked.join('、')}）：先到场景页解锁再${FROZEN_DEFAULT_VERB}` : null;
+    };
+}
+// ── 3.6 模型侧 op 表的冻结闸（与 handlers 同一份判据）────────────────────────
+/**
+ * 给**模型侧**的 op 表装冻结闸（审查 F3，0.17.0）。
+ *
+ * 为什么抽成一个函数、而不是在 index.ts 里手写 for 循环：模型侧与 HTTP 侧必须用**同一个**
+ * `frozen` 判据对象。写成两个循环、各自去 `createFrozenGate`，就给了"两边又分家"的机会 ——
+ * 而 F3 的成因正是两侧判据不同。抽出来之后，契约测试可以直接拿真实的 `createFrozenGate`
+ * 与真实的 `installHandlerGuards` 对同一个 op 比对两侧结论。
+ *
+ * **不改动传入的表**：返回新表。场景引擎直调的是原表（`applySkills` → `service.ops`），
+ * 装在原表上会把场景自己锁死。
+ *
+ * @param ops    原始 op 表
+ * @param frozen `createFrozenGate(...)` 的返回值
+ * @param after  成功后的回调（挂流水用）。被拒时**不调用** —— 什么都没改。
+ */
+export function guardModelOps(ops, frozen, after) {
+    const out = {};
+    for (const [opName, fn] of Object.entries(ops)) {
+        if (typeof fn !== 'function') {
+            out[opName] = fn;
+            continue;
+        }
+        out[opName] = async (args) => {
+            const denied = await frozen(opName, args || {});
+            if (denied)
+                return { ok: false, error: denied };
+            const result = await fn(args || {});
+            if (after)
+                after(opName, args || {}, result);
+            return result;
+        };
+    }
+    return out;
+}
+/** 单个 op 版本（`guardModelOps` 的一元特例）：给不经 op 表的调用点用。 */
+export function guardModelOp(opName, fn, frozen, after) {
+    return guardModelOps({ [opName]: fn }, frozen, after)[opName];
+}
 export function installHandlerGuards(deps) {
     const { handlers, lockedSceneNames, activeSceneName, syncSwitchToScene, subagentToolFailures } = deps;
     /**
      * 包一层：开关成功后把改动同步进当前场景档案（见 syncSwitchToScene）。
      * 失败只挂 `sceneSyncError`，不改写原操作的成功结论 —— 运行时确实改了，档案没跟上要说得清。
-     * 锁定仍由 `guardLockedOps` 挡住（更靠内的那层包装先执行）。
+     * 锁定由更靠内的冻结包装挡住（先装的在内层，它返回 `ok:false` 时这里不会去同步档案）。
      */
     function syncSceneArchiveOnSwitch(opNames) {
         for (const opName of opNames) {
@@ -165,64 +261,27 @@ export function installHandlerGuards(deps) {
             };
         }
     }
-    function guardLockedOps(opNames, what) {
-        for (const opName of opNames) {
+    // 冻结清单与档案同步清单都来自 `./op-registry.ts`：加 op 时在那里登记一条，这里不再抄。
+    // 三种口径（all / active-scene / self-scene）现在合成**一个**判据函数（`createFrozenGate`），
+    // 由 `frozenOps()`（不带 scope = 全部冻结 op）一次装完。原先它们分散成三段手写包装，
+    // 而模型侧 op 表压根没装 —— 这正是 F3 的成因（见 `createFrozenGate` 的注释）。
+    // 包装顺序不变：冻结仍在**内层**，`syncSceneArchiveOnSwitch` 在外层（前者返回 ok:false 时
+    // 后者不会去同步档案）。
+    {
+        const frozen = createFrozenGate({ lockedSceneNames, activeSceneName });
+        for (const opName of frozenOps()) {
             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);
+                const denied = await frozen(opName, args);
+                return denied ? { ok: false, error: denied } : original(args);
             };
         }
     }
-    // 冻结清单与档案同步清单都来自 `./op-registry.ts`：加 op 时在那里登记一条，这里不再抄。
-    guardLockedOps(frozenOps('all'), '修改');
     // 场景内「开关」类操作（用户裁定 2026-09-17）：未锁定时**可用**，改动同步进当前场景档案。
     // 与「锁定」正交：锁定冻结全部写操作，这里只是把页面开关的意图也写进档案。
     syncSceneArchiveOnSwitch(opsWith('syncsArchive'));
-    // 口径 `frozenScope: 'active-scene'` 的那几条（判据与理由登记在 op-registry.ts 的
-    // `rules-set-active` 条目上）。没有锁定场景在生效时（全局态 / 场景未锁）照旧可用。
-    const ACTIVE_SCENE_LABEL = { 'rules-set-active': '切换场景' };
-    for (const opName of frozenOps('active-scene')) {
-        const what = ACTIVE_SCENE_LABEL[opName] ?? '改它';
-        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);
-        };
-    }
-    // 被锁场景自身的档案与删除：只挡它自己，别的场景照常（口径 `frozenScope: 'self-scene'`）。
-    // 目标场景一律从 `args.scene` / `args.name` 里取 —— 这两个键名就是本插件 op 的惯例。
-    const SELF_SCENE_LABEL = { 'scene-archive-save': '改档案', 'rules-remove-scene': '删除' };
-    for (const opName of frozenOps('self-scene')) {
-        const what = SELF_SCENE_LABEL[opName] ?? '改它';
-        const original = handlers[opName];
-        if (typeof original !== 'function')
-            continue;
-        handlers[opName] = async (args) => {
-            const scene = String((args && (args.scene || args.name)) || '').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) {

package/lib/scene-prompt-sync.js

@@ -24,8 +24,11 @@
 //   `driver()`     —— 谁在驱动基线（提示词页「应用」据此判断：应用别的份 = 换掉该场景的绑定）；
 //   `refs()`       —— 每个预设被谁引用（删除保护的唯一依据：场景绑定 / 基线当前内容 / 退出恢复目标）；
 //   `baseline()`   —— 进场景前的基线快照（退出场景后要恢复的那一份）。
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, stat } from 'node:fs/promises';
 import { dirname } from 'node:path';
+// 基线快照走原子写（temp + rename）：它是「退出场景时恢复 AGENTS.md」的**唯一依据**，
+// 裸写中断留下半截 JSON 会让 `readBaseline` 解析失败（审查 P2-16）。
+import { writeFileAtomically } from './memories/index-io.js';
 export function createScenePromptSync(deps) {
     const warn = (message) => { try {
         deps.logger?.warn?.(message);
@@ -48,13 +51,35 @@ export function createScenePromptSync(deps) {
             return null;
         }
     }
+    /** 快照文件是否**存在**（不看内容）。用来把「没有快照」与「快照读不出来」分开。 */
+    async function baselineExists() {
+        try {
+            return (await stat(deps.baselineFile)).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 写基线快照。**失败必须让调用方看得见**（2026-09-30 审查 F14）。
+     *
+     * 原来这里 catch 后只 `warn` 并返回 void，于是「快照没写成」与「写成了」在调用方眼里
+     * 完全一样 —— 结果就是：AGENTS.md 被切到场景态、而退出场景时恢复不回来，用户看到的是
+     * 「没场景驱动所以什么都没做」。这正是「看起来成功」那类失败。
+     * @returns 失败原因（原样回给调用方拼进提示）；成功返回 null。
+     */
     async function writeBaseline(next) {
         try {
             await mkdir(dirname(deps.baselineFile), { recursive: true });
-            await writeFile(deps.baselineFile, JSON.stringify(next), 'utf8');
+            // 原子写（2026-09-30 审查 P2-16）：裸写在中断/断电时会留下半截 JSON → `readBaseline`
+            // 解析失败返回 null → 退出场景**不恢复** AGENTS.md，用户的提示词基线悄悄留在场景态。
+            await writeFileAtomically(deps.baselineFile, JSON.stringify(next));
+            return null;
         }
         catch (e) {
-            warn(`scene-prompt: could not persist baseline: ${String(e)}`);
+            const reason = String(e);
+            warn(`scene-prompt: could not persist baseline: ${reason}`);
+            return reason;
         }
     }
     async function state() {
@@ -157,25 +182,39 @@ export function createScenePromptSync(deps) {
                 return { applied: current.presetId, unchanged: true };
             // 进场景的第一笔写入之前，先记下当时的基线（已有快照就不覆盖：连续切场景时
             // 基线始终是"进场景之前"那一份）。
+            let baselineError;
             const saved = await readBaseline();
             if (!saved || saved.content === null) {
                 const cur = await deps.prompts.getCurrent();
-                await writeBaseline({
+                const failed = await writeBaseline({
                     v: 1,
                     at: Date.now(),
                     presetId: cur && cur.ok && cur.presetId ? String(cur.presetId) : null,
                     content: cur && cur.ok && cur.exists ? String(cur.content) : null,
                 });
+                // 基线写不进去 = 退出场景时恢复不回来。**照旧进场景**（那是用户的要求），
+                // 但必须当场说出来，别让用户以为还能退回去（审查 F14）。
+                if (failed !== null) {
+                    baselineError = `进场景前的提示词基线没能写入（${failed}）：AGENTS.md 已切到场景「${current.scene}」绑定的预设，但退出场景时恢复不回原来的内容（${deps.baselineFile}）。`;
+                }
             }
             const res = await deps.prompts.apply(current.presetId);
             if (res && res.ok === false)
-                return { error: String(res.error || '写入 AGENTS.md 失败') };
-            return { applied: current.presetId };
+                return { error: String(res.error || '写入 AGENTS.md 失败'), ...(baselineError ? { baselineError } : {}) };
+            return { applied: current.presetId, ...(baselineError ? { baselineError } : {}) };
         }
         // 没有场景驱动 → 如果刚从驱动态退出，把进场景前的基线写回去。
         const saved = await readBaseline();
-        if (!saved || saved.content === null)
+        if (!saved || saved.content === null) {
+            // 「没有快照」是常态（没进过场景）；「快照文件在、但读不出来」是**故障** ——
+            // 那意味着恢复目标丢了，AGENTS.md 的提示词基线会悄悄留在场景态。这里曾经一律
+            // 静默 `unchanged`，用户看到的是"没场景驱动所以什么都没做"（审查 P2-16）。
+            if (await baselineExists()) {
+                warn(`scene-prompt: baseline snapshot exists but is unreadable: ${deps.baselineFile}`);
+                return { error: `基线快照读不出来（文件可能损坏），未能恢复 AGENTS.md：${deps.baselineFile}` };
+            }
             return { unchanged: true };
+        }
         const res = await deps.prompts.restore(saved.content);
         if (res && res.ok === false)
             return { error: String(res.error || '恢复 AGENTS.md 失败') };