dsh-config-manager 0.2.4 → 0.3.0

package/src/core/backup.ts

@@ -593,6 +593,53 @@ export type PruneSelector = (
 export const fallbackPruneSelector: PruneSelector = (metas, policy) =>
   selectPruneCandidates(metas, policy.keepLast);
 
+/* ---------------- BK-05：反悔副本（pre-restore）保留策略 ----------------
+ *
+ * 反悔副本 = 恢复链路在覆盖/删除前落的原文副本（restore.ts:888 起写 <snapshotDir>/pre-restore/<attempt>/）。
+ * 它与快照本体的生命周期**不是一回事**：本体可以按保留策略回收（历史回滚点），
+ * 反悔副本却是用户「把刚才这次恢复撤回去」的最后一份原文，整条链路上没有第二份
+ * （不在 blobs 里、不进同步、不进导出）。所以两套策略分开：
+ *  - 快照本体：既有 RetentionPolicyLike（宿主可注入 GFS）；
+ *  - 反悔副本：只按「份数 + 天数」淘汰，常量在 core 内固定（无宿主可调项 —— 少了它等于没有反悔能力）。
+ */
+export const PRE_RESTORE_KEEP_ATTEMPTS = 5;
+export const PRE_RESTORE_KEEP_DAYS = 30;
+/** 反悔副本目录名（restore.ts 写入侧同一常量值；这里是读侧，绝不与写侧分叉） */
+const PRE_RESTORE_DIR_NAME = 'pre-restore';
+
+/** 解析反悔副本 attempt 目录名里的时间戳（本地时间 yyyyMMdd-HHmmss-SSS，可选 -N 去重后缀）。 */
+function parsePreRestoreStamp(name: string): number | null {
+  const m = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})-(\d{3})(?:-\d+)?$/.exec(name);
+  if (m === null) return null;
+  const at = new Date(
+    Number(m[1]), Number(m[2]) - 1, Number(m[3]),
+    Number(m[4]), Number(m[5]), Number(m[6]), Number(m[7]),
+  ).getTime();
+  return Number.isFinite(at) ? at : null;
+}
+
+/** 一条反悔副本 attempt 的淘汰计划（删除**前**就进 PrunePlan，供审计与界面展示）。 */
+export interface PrunePreRestoreDrop {
+  snapshotId: string;
+  attempt: string;
+  /** count = 超出份数上限；over-age = 超过保留天数 */
+  reason: 'count' | 'over-age';
+  /** 该 attempt 目录里的文件数（用户能看出「删了多少份原文」） */
+  files: number;
+}
+
+/** 一轮保留清理的**计划**（在真正 rm 之前回调出去；也是 pruneNow 的返回值）。 */
+export interface PrunePlan {
+  /** 将回收的快照 id（目录内的快照本体，不含 pre-restore 子树） */
+  removeSnapshots: string[];
+  /** 因存在反悔副本而**不**整目录删的快照 id（只删本体内容、留下 pre-restore/） */
+  keepPreRestoreFor: string[];
+  /** 反悔副本 attempt 级淘汰计划 */
+  dropPreRestore: PrunePreRestoreDrop[];
+  /** 计划删除的具体路径（相对快照根、'/' 分隔；审计「到底删了什么」） */
+  paths: string[];
+}
+
 export interface FileSnapshotStoreOptions {
   /** 快照根目录（宿主决定，如 ~/.dsh/dsh-config-manager/snapshots） */
   dir: string;
@@ -608,6 +655,8 @@ export interface FileSnapshotStoreOptions {
    * 缺省 = 不记录（不改变 prune 行为、不污染核心引擎）。
    */
   onPrune?: (removedIds: string[]) => void;
+  /** BK-05：保留清理的**计划**回调（在真正删除之前，best-effort；抛错不影响清理） */
+  onPrunePlan?: (plan: PrunePlan) => void;
   /**
    * m-retention：快照保留策略提供者（GFS 分层；可配置）。
    * 缺省 = `SNAPSHOT_RETENTION_LIMIT`（= 既有的「保留最近 10 个」，行为不变）。
@@ -722,7 +771,8 @@ export class FileSnapshotStore implements SnapshotStore {
  *  自动淘汰，只能手动删除（deleteSnapshot）。
  *  Phase 4 F3：被 active/quarantine 未收敛 journal 引用的 snapshot（recovery 回滚点）
  *  必须豁免——引用提供者（referencedSnapshotIds）返回的 id 绝不自动清理。 */
-  private async prune(): Promise<void> {
+  private async prune(): Promise<PrunePlan> {
+    const emptyPlan: PrunePlan = { removeSnapshots: [], keepPreRestoreFor: [], dropPreRestore: [], paths: [] };
     const dir = this.options.dir;
     const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
     // F3：被未收敛 journal 引用的快照**绝不自动清理**。判据是「读不到 ≠ 没有引用」——
@@ -734,7 +784,7 @@ export class FileSnapshotStore implements SnapshotStore {
         referenced = await this.options.referencedSnapshotIds();
       } catch (err) {
         this.options.onWarn?.(engineMsg('core.backup.pruneAbandoned', { reason: err instanceof Error ? err.message : String(err) }));
-        return;
+        return emptyPlan;
       }
     }
     // m-retention：策略读取失败 → 回退缺省（绝不因策略提供者异常而误删/崩溃）
@@ -762,17 +812,108 @@ export class FileSnapshotStore implements SnapshotStore {
         // 损坏 / 非快照目录：跳过（与 listSnapshots 语义一致）
       }
     }
-    const removedIds: string[] = [];
+    // --- BK-05：先出计划，再删 ---
+    // 快照本体与反悔副本是两套生命周期：本体按保留策略回收，pre-restore 按「份数 + 天数」淘汰。
+    // 计划必须在 rm **之前**成型并回调出去——删完再报等于审计拿不到原始状态。
+    const plan: PrunePlan = {
+      removeSnapshots: [],
+      keepPreRestoreFor: [],
+      dropPreRestore: await this.collectPreRestorePlan(),
+      paths: [],
+    };
+    /** 每个待回收快照：目录名 → 要删的子项（保持 pre-restore 不动） */
+    const removals: { id: string; children: string[]; hasPre: boolean }[] = [];
     for (const id of selector(metas, policy)) {
       const target = path.join(dir, id);
       if (!target.startsWith(dir)) continue; // 越界 id 跳过（不删、不抛，同 save/readBlob 包含性约定）
+      const children = await fs.readdir(target).catch(() => [] as string[]);
+      const hasPre = children.includes(PRE_RESTORE_DIR_NAME);
+      removals.push({ id, children, hasPre });
+      plan.removeSnapshots.push(id);
+      for (const child of children) {
+        if (child === PRE_RESTORE_DIR_NAME) continue;
+        plan.paths.push(id + '/' + child);
+      }
+    }
+    for (const drop of plan.dropPreRestore) plan.paths.push(drop.snapshotId + '/pre-restore/' + drop.attempt + '/');
+    this.options.onPrunePlan?.(plan);
+    if (plan.removeSnapshots.length === 0 && plan.dropPreRestore.length === 0) return plan;
+
+    // 1) 回收快照本体：有反悔副本的快照**不整目录删**（否则唯一那份原文跟着消失），逐项删其余内容
+    const removedIds: string[] = [];
+    for (const removal of removals) {
+      const target = path.join(dir, removal.id);
+      for (const child of removal.children) {
+        if (child === PRE_RESTORE_DIR_NAME) continue;
+        await fs.rm(path.join(target, child), { recursive: true, force: true });
+      }
+      if (removal.hasPre) plan.keepPreRestoreFor.push(removal.id);
+      else await fs.rm(target, { recursive: true, force: true });
+      removedIds.push(removal.id);
+    }
+    // 2) 反悔副本 attempt 级淘汰（份数超限 / 超过保留天数）
+    for (const drop of plan.dropPreRestore) {
+      await fs.rm(path.join(dir, drop.snapshotId, PRE_RESTORE_DIR_NAME, drop.attempt), { recursive: true, force: true });
+    }
+    // 3) 收尾：快照本体已回收（无 snapshot.json）且反悔副本也空了 ⇒ 不留空壳目录
+    const touched = new Set<string>([...plan.keepPreRestoreFor, ...plan.dropPreRestore.map((d) => d.snapshotId)]);
+    for (const id of touched) {
+      const target = path.join(dir, id);
+      const hasSnapshot = await fs.stat(path.join(target, 'snapshot.json')).catch(() => null) !== null;
+      if (hasSnapshot) continue;
+      const left = await fs.readdir(path.join(target, PRE_RESTORE_DIR_NAME)).catch(() => null);
+      if (left !== null && left.length > 0) continue;
       await fs.rm(target, { recursive: true, force: true });
-      removedIds.push(id);
     }
     // Phase 6：自动保留清理历史回调（best-effort；不改变 prune 行为）
     if (removedIds.length > 0) {
       try { this.options.onPrune?.(removedIds); } catch { /* 历史回调失败不阻断 */ }
     }
+    return plan;
+  }
+
+  /**
+   * BK-05：反悔副本（pre-restore）淘汰计划 —— 只看**份数与天数**，与快照本体的保留策略无关。
+   *
+   * 为什么单独一套：快照本体是「历史回滚点」，可被 GFS 策略批量回收；反悔副本是用户把
+   * 刚才那次恢复撤回去的**唯一**原文（不在 blobs、不进同步、不进导出），它只需要「别无限长」，
+   * 不需要也不该受 keepLast/keepMonthly 影响 —— 否则一次批量淘汰会把最近几次恢复的反悔点一起抹掉。
+   * attempt 名即恢复时间戳（restore.ts 的 preRestoreStamp，本地时间 yyyyMMdd-HHmmss-SSS[-序号]）；
+   * 解析不出来回落目录 mtime（手工改名的残留也能被淘汰，不会永久占位）。
+   */
+  private async collectPreRestorePlan(): Promise<PrunePreRestoreDrop[]> {
+    const dir = this.options.dir;
+    const drops: PrunePreRestoreDrop[] = [];
+    const now = Date.now();
+    const maxAgeMs = PRE_RESTORE_KEEP_DAYS * 24 * 60 * 60 * 1000;
+    for (const entry of await fs.readdir(dir, { withFileTypes: true }).catch(() => [])) {
+      if (!entry.isDirectory()) continue;
+      const preRoot = path.join(dir, entry.name, PRE_RESTORE_DIR_NAME);
+      const attempts = await fs.readdir(preRoot, { withFileTypes: true }).catch(() => null);
+      if (attempts === null) continue;
+      const rows: { attempt: string; at: number; files: number }[] = [];
+      for (const a of attempts) {
+        if (!a.isDirectory()) continue;
+        const at = parsePreRestoreStamp(a.name)
+          ?? (await fs.stat(path.join(preRoot, a.name)).then((s) => s.mtimeMs).catch(() => now));
+        const names = await fs.readdir(path.join(preRoot, a.name), { recursive: true }).catch(() => [] as string[]);
+        rows.push({ attempt: a.name, at, files: names.length });
+      }
+      rows.sort((x, y) => y.at - x.at); // 新 → 旧
+      rows.forEach((row, index) => {
+        if (index >= PRE_RESTORE_KEEP_ATTEMPTS) {
+          drops.push({ snapshotId: entry.name, attempt: row.attempt, reason: 'count', files: row.files });
+        } else if (now - row.at > maxAgeMs) {
+          drops.push({ snapshotId: entry.name, attempt: row.attempt, reason: 'over-age', files: row.files });
+        }
+      });
+    }
+    return drops;
+  }
+
+  /** BK-05：手动触发一轮保留清理（与 save 后的自动清理同一实现）。 */
+  async pruneNow(): Promise<PrunePlan> {
+    return this.prune();
   }
 
   async load(id: string): Promise<Snapshot> {

package/src/core/import-defaults.ts

@@ -0,0 +1,13 @@
+/**
+ * 导入执行策略的**唯一缺省**（IE-02）。
+ *
+ * 为什么单独一个零依赖模块：这个缺省必须被四处引用 —— 引擎 `src/core/importer.ts`、
+ * HTTP 路由 `src/routes/import.ts`、UI 向导 `src/ui/import-wizard.ts`、同步通道
+ * `src/sync/sync-engine.ts`。而 `src/ui/import-wizard.ts` 会被 `src/client/run-store.ts`
+ * 作为**值**导入并打进浏览器 bundle，所以它不能从 `src/core/importer.ts` 取这个值
+ * （那条路径经 Analyzer 拖进 node 内建与 ZIP 依赖）。本文件零依赖，两端都能安全引入。
+ *
+ * 语义：任一计划项失败立即整体回滚（安全侧，也就是 UI 文案「失败时整体回滚（推荐）」）。
+ * 要「单项失败如实记录并继续其余项」必须显式传 `false`，不再靠各入口各写一份缺省。
+ */
+export const DEFAULT_ROLLBACK_ON_ERROR = true;

package/src/core/importer.ts

@@ -11,6 +11,13 @@
 import type { ZipArchive, ZipSafetyLimits } from '../utils/zip.ts';
 import type { MsgFunc } from './messages.ts';
 import { Analyzer } from './analyzer.ts';
+import { DEFAULT_ROLLBACK_ON_ERROR } from './import-defaults.ts';
+
+/**
+ * 缺省值的规范定义在 `./import-defaults.ts`（零依赖，UI 向导与浏览器 bundle 也引入它）；
+ * 这里再导出一份，宿主侧调用方（路由、同步通道、CLI）可以从引擎门面拿，不必记两个路径。
+ */
+export { DEFAULT_ROLLBACK_ON_ERROR };
 import type { PlanItemProgress } from './analyzer.ts';
 import type { BootSafetyReport } from './boot-safety.ts';
 import type {
@@ -41,7 +48,10 @@ export interface ExecuteOptions {
   secretInputs?: Record<string, string>;
   /** 加密备份解密结果（仅内存；解密必须经 m4 encryption provider） */
   decryptedCredentials?: Map<string, string>;
-  /** 任一项失败立即整体回滚（默认 false：单项失败如实记录并继续其余项） */
+  /**
+   * 任一项失败立即整体回滚。缺省 = `DEFAULT_ROLLBACK_ON_ERROR`（`./import-defaults.ts`，全仓唯一一份）；
+   * 要「单项失败如实记录并继续其余项」必须显式传 `false`。
+   */
   rollbackOnError?: boolean;
   /** m1：每完成一个计划项的进度回调（透传给 Analyzer；不传则无埋点） */
   onItem?: (info: PlanItemProgress) => void;
@@ -97,7 +107,7 @@ export class Importer {
       confirm: opts.confirm,
       secretInputs: opts.secretInputs,
       decryptedCredentials: opts.decryptedCredentials,
-      rollbackOnError: opts.rollbackOnError,
+      rollbackOnError: opts.rollbackOnError ?? DEFAULT_ROLLBACK_ON_ERROR,
       onItem: opts.onItem,
       onItemStart: opts.onItemStart,
       onLog: opts.onLog,

package/src/core/integrity-extra-entries.test.ts

@@ -0,0 +1,205 @@
+/**
+ * SEC-05 回归：校验表只做「正向」校验 —— 表里登记的逐条比对，**表外的归档条目没人管**。
+ * 文件类分区又是按归档名原样落盘的，于是「ZIP 有、checksums 没登记」的文件照样被写进目标目录，
+ * 完整性声明形同虚设（审计 docs/research/dsh-config-manager-technical-audit.md SEC-05）。
+ *
+ * 修后口径：
+ *  - 会落盘的文件分区条目（Create/Update/Conflict）若不在 checksums 表内 ⇒ 计划项升级为 Error（逐条零写入），
+ *    整包仍 valid（表外 ≠ 被篡改，只留一条 warning）；
+ *  - 校验表**缺失或为空** ⇒ 一个条目都没被校验，文件分区条目同样逐条拦（RV1-F1，否则删表即绕过）；
+ *  - 历史包兼容开关 extraEntryExemptSections（默认空）按分区豁免，豁免分区退回「只告警」旧行为；
+ *  - 「不在任何文件分区前缀下」的散落条目仍是告警（守 tests/conformance/roundtrip.test.ts INT-01）。
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { Analyzer } from './analyzer.ts';
+import { Importer } from './importer.ts';
+import { createAdapters } from '../adapters/index.ts';
+import { makeContext, MemSnapshotStore } from '../adapters/test-helpers.ts';
+import { writeZip } from '../utils/zip.ts';
+import { buildManifest } from '../schema/manifest.ts';
+import { buildChecksums } from '../utils/hashing.ts';
+import { SECTION_IDS, SECTION_FILE_PREFIXES, SECTION_JSON_PATHS } from '../schema/config.ts';
+import { UNVERIFIED_FILE_ENTRY_CODE } from '../security/integrity.ts';
+import type { SectionId } from '../schema/types.ts';
+import type { HostContext } from './types.ts';
+
+const SETTINGS = JSON.stringify({
+  version: 1,
+  namespaces: { llm: { value: { model: 'deepseek-chat' }, revision: 1, secrets: [] } },
+});
+const DECISIONS = { strategy: 'merge' as const, resolutions: {}, pathMappings: [] };
+/** skills 分区在 ZIP 内的真实前缀（custom/skills/），从注册表派生，不写死布局。 */
+const SKILL_PREFIX = SECTION_FILE_PREFIXES['skills']!;
+const SKILL_REL = 'demo/SKILL.md';
+const SKILL_ENTRY = SKILL_PREFIX + SKILL_REL;
+/** 不在任何文件分区前缀下的散落条目（INT-01 用）。 */
+const ROGUE_ENTRY = 'injected/rogue.json';
+
+/** 造包：settings + skills 声明为包含；unlisted 里的条目进 ZIP 但不进 checksums 表。 */
+async function buildBundle(
+  opts: { unlisted?: string[]; declareSkills?: boolean; checksums?: 'omit' | 'empty' } = {},
+): Promise<{ zipPath: string; tmp: string }> {
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dcm-sec05-'));
+  const flags: Record<string, boolean> = {};
+  for (const sid of SECTION_IDS) flags[sid] = false;
+  flags['settings'] = true;
+  flags['skills'] = opts.declareSkills !== false;
+  const manifest = buildManifest({
+    exporterVersion: '0.1.0',
+    dshVersion: '0.1.54',
+    platform: 'win32',
+    arch: 'x64',
+    sections: flags as Record<SectionId, boolean>,
+    containsSecrets: false,
+    encrypted: false,
+    encryption: null,
+  });
+  const contentEntries = [
+    { name: SECTION_JSON_PATHS['settings']!, data: Buffer.from(SETTINGS, 'utf8') },
+    { name: SKILL_ENTRY, data: Buffer.from('# demo skill', 'utf8') },
+    { name: ROGUE_ENTRY, data: Buffer.from('{"rogue":true}', 'utf8') },
+  ];
+  const unlisted = new Set(opts.unlisted ?? []);
+  const checksums = buildChecksums(contentEntries.filter((e) => !unlisted.has(e.name)));
+  const entries = [
+    ...contentEntries,
+    { name: 'manifest.json', data: Buffer.from(JSON.stringify(manifest), 'utf8') },
+    // RV1-F1：表缺失（'omit'）与表为空（'empty'）都必须逐条 fail-closed —— 两种形态曾被当成「没事」。
+    ...(opts.checksums === 'omit'
+      ? []
+      : [{
+        name: 'integrity/checksums.json',
+        data: Buffer.from(opts.checksums === 'empty' ? '{}' : JSON.stringify(checksums), 'utf8'),
+      }]),
+  ];
+  const zipPath = path.join(tmp, 'bundle.zip');
+  await writeZip(zipPath, entries);
+  return { zipPath, tmp };
+}
+
+function mkCtx(): HostContext {
+  return makeContext('linux', '/home/bob');
+}
+
+function mkAnalyzer(ctx: HostContext, extraEntryExemptSections?: readonly SectionId[]): Analyzer {
+  return new Analyzer({
+    ctx,
+    adapters: createAdapters({ namespaces: ['llm'] }),
+    snapshotStore: new MemSnapshotStore(),
+    ...(extraEntryExemptSections ? { extraEntryExemptSections } : {}),
+  });
+}
+
+function mkImporter(ctx: HostContext): Importer {
+  return new Importer({ ctx, adapters: createAdapters({ namespaces: ['llm'] }), snapshotStore: new MemSnapshotStore() });
+}
+
+test('SEC-05/① 对照：文件分区条目全量登记 → 不阻断，计划项照常 Create', async () => {
+  const { zipPath } = await buildBundle();
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const analysis = await importer.analyzeImport(zipPath);
+  assert.equal(analysis.valid, true, '全量登记不应阻断');
+  assert.deepEqual(analysis.errors, []);
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const item = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(item, 'skills 分区应有 SKILL.md 计划项');
+  assert.equal(item!.kind, 'Create');
+});
+
+test('SEC-05/② 表外文件分区条目 → 计划项 Error（零写入），analysis 只留一条 warning', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [SKILL_ENTRY] });
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const analysis = await importer.analyzeImport(zipPath);
+  // 表外 ≠ 被篡改：逐条 Error 已保证零写入，把整包判死只会拒绝整笔合法导入（含一个多余文件的历史包），
+  // 却没多拦住任何一次写盘 ⇒ valid 保持 true，错误面只留一条 warning 点名该条目。
+  assert.equal(analysis.valid, true, '表外条目不得把整包判死');
+  assert.deepEqual(analysis.errors, [], '表外条目不进 errors（不阻断整体导入）');
+  const named = analysis.warnings.some((w) => w.includes(SKILL_REL) || w.includes(SKILL_ENTRY));
+  assert.ok(named, 'warnings 必须点名该条目，实际: ' + JSON.stringify(analysis.warnings));
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const item = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(item, '被阻断条目仍要出现在计划里（用户能看到为什么没导）');
+  assert.equal(item!.kind, 'Error');
+  assert.equal(item!.severity, 'error');
+  assert.ok(item!.detail?.includes(UNVERIFIED_FILE_ENTRY_CODE), 'detail 应带错误码，实际: ' + String(item!.detail));
+});
+
+test('SEC-05/③ 按分区豁免 → 退回只告警（历史包兼容开关，默认关）', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [SKILL_ENTRY] });
+  const ctx = mkCtx();
+  const analyzer = mkAnalyzer(ctx, ['skills']);
+  const analysis = await analyzer.analyzeImport(zipPath);
+  assert.equal(analysis.valid, true, '豁免分区不得阻断');
+  assert.ok(analysis.warnings.some((w) => w.includes(SKILL_ENTRY)), '豁免也要留告警，不能静默放行');
+  const plan = await analyzer.createImportPlan(zipPath, DECISIONS);
+  const item = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.equal(item!.kind, 'Create', '豁免分区应照常落盘');
+});
+
+test('SEC-05/④ 非文件分区的散落条目仍只告警（守 INT-01 口径）', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [ROGUE_ENTRY] });
+  const ctx = mkCtx();
+  const analysis = await mkImporter(ctx).analyzeImport(zipPath);
+  assert.equal(analysis.valid, true, '散落条目不阻断');
+  assert.deepEqual(analysis.errors, []);
+  assert.ok(analysis.warnings.some((w) => w.includes(ROGUE_ENTRY)), '散落条目必须有告警（不得静默忽略）');
+});
+
+test('SEC-05/⑤ 执行被阻断的计划 → 表外文件零落盘', async () => {
+  const { zipPath } = await buildBundle({ unlisted: [SKILL_ENTRY] });
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const skillItem = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(skillItem, '被阻断条目应在计划里');
+  const result = await importer.executeImportPlan(zipPath, plan, { confirm: true });
+  const blocked = result.executed.find((e) => e.itemId === skillItem!.id);
+  assert.equal(blocked?.status, 'failed', '被阻断项执行结果必须是 failed');
+  assert.equal(await ctx.fs.exists(SKILL_ENTRY), false, '表外条目绝不能被写进目标');
+});
+
+/* ─── RV1-F1：表缺失 / 表为空 ⇒ 逐条 fail-closed（删掉表就等于关掉 SEC-05 的那个绕过） ─── */
+
+async function expectFailClosed(mode: 'omit' | 'empty'): Promise<void> {
+  const { zipPath } = await buildBundle({ checksums: mode });
+  const ctx = mkCtx();
+  const importer = mkImporter(ctx);
+  const analysis = await importer.analyzeImport(zipPath);
+  // 逐条 fail-closed，不是整包拒：settings 这类非文件分区照常可导，判死的只是完整性管不到的文件分区条目。
+  assert.equal(analysis.valid, true, '表缺失/为空不得把整包判死（旧包仍要能用）');
+  assert.deepEqual(analysis.errors, []);
+  assert.ok(
+    analysis.warnings.some((w) => w.includes(SKILL_ENTRY)),
+    '没有校验表时，文件分区条目必须被点名（静默放行 = 防线失效），实际: ' + JSON.stringify(analysis.warnings),
+  );
+
+  const plan = await importer.createImportPlan(zipPath, DECISIONS);
+  const skillItem = plan.items.find((i) => i.adapter === 'skills' && i.target?.ref === SKILL_REL);
+  assert.ok(skillItem, '文件分区条目应在计划里');
+  assert.equal(skillItem!.kind, 'Error', '没有校验表 ⇒ 文件分区条目一律未覆盖 ⇒ 必须拦');
+  assert.ok(String(skillItem!.detail ?? '').includes(UNVERIFIED_FILE_ENTRY_CODE), '拦下时必须带错误码');
+  assert.ok(
+    plan.items.some((i) => i.adapter === 'settings' && i.kind !== 'Error'),
+    '非文件分区（settings）不应被连带阻断',
+  );
+
+  const result = await importer.executeImportPlan(zipPath, plan, { confirm: true });
+  assert.equal(result.executed.find((e) => e.itemId === skillItem!.id)?.status, 'failed', '被拦项执行结果必须是 failed');
+  assert.equal(await ctx.fs.exists(SKILL_ENTRY), false, '没有校验表时，文件条目绝不能被写进目标');
+}
+
+test('RV1/F1⑥ 包内缺 integrity/checksums.json → 文件分区条目逐条拦、零写入（删表不能绕过 SEC-05）', async () => {
+  await expectFailClosed('omit');
+});
+
+test('RV1/F1⑦ 校验表为空 {} → 与缺失同口径（空表 = 一个条目都没校验）', async () => {
+  await expectFailClosed('empty');
+});
+

package/src/core/messages.test.ts

@@ -47,7 +47,9 @@ test('i18n(ui): zhUiT 缺省 + makeUiT 双语插值', () => {
   assert.equal(zhUiT('error.notMounted'), 'config-manager 服务未挂载（插件未加载）：请确认 profile 中已安装 dsh-config-manager 并重启 DSH');
   const enT = makeUiT('en');
   assert.equal(enT('error.notMounted'), 'config-manager service is not mounted (plugin not loaded): make sure dsh-config-manager is installed in the profile and restart DSH');
-  assert.equal(enT('report.credentialsNeedEntry', { count: '3' }), '3 credential(s) need to be entered');
+  // 2026-11-01 起复数由 `{count, plural, ...}` 段决定：3 → credentials / need
+  assert.equal(enT('report.credentialsNeedEntry', { count: '3' }), '3 credentials need to be entered');
+  assert.equal(enT('report.credentialsNeedEntry', { count: '1' }), '1 credential needs to be entered');
   // 未知键回退 zh → 键名（类型层不允许字面量，这里用宽松断言验证运行期回退）
   const loose = makeUiT('en') as (key: string) => string;
   assert.equal(loose('no.such.key'), 'no.such.key');

package/src/core/messages.ts

@@ -65,6 +65,7 @@ export const zh = {
   'import.unsupportedSectionVersion': '分区 {section} 的数据版本 {version} 高于本版本支持的 1（已跳过该分区）',
   'import.checksumsMissing': '备份未提供完整性校验表，全部条目未被校验',
   'import.extraEntries': 'ZIP 内含未登记进校验表的条目: {entries}（未被校验）',
+  'import.unverifiedFileEntry': '以下条目不在校验表内，无法校验，已逐条阻断写入（其余条目照常导入）: {entries}',
   'import.undeclaredSectionContent': '备份包含未声明的分区内容（清单里标为不包含，这些条目不会被导入）: {sections}；示例条目: {entries}',
   'import.secretsPayloadEmpty': '备份声明携带凭据值，但解出的凭据清单为空：这不是「没有凭据」，而是没读到（请确认备份密码与导出机的凭据库布局）',
   'import.migrated': '备份 schema 已从 v{from} 迁移到 v{to}',
@@ -349,6 +350,7 @@ export const zh = {
   'adapter.workspaceSessionsOutsideBundle': '另有 {count} 个会话不在此备份包内（本次未导入其数据），未登记；目标机本来就有这些会话则不受影响',
   'adapter.workspaceSessionsManual': '本机工作区服务不支持会话登记，{count} 个会话未登记：启动 DSH 后可在设置里重新导入，或用离线修复工具 sessions repair',
   'adapter.workspaceSessionsOwnerMissing': '找不到对应的目标工作区记录，{count} 个会话未登记：请确认备份里包含该工作区（导出会话时会自动连带其工作区）',
+  'adapter.selfImportBlocked': '包内含 {path}（同步目标配置）：已拒绝写入，本机同步目标保持不变',
   'adapter.providerMissing': '导入数据缺少 provider {route}',
   'adapter.namespaceMissing': '导入数据缺少 namespace {ref}',
 
@@ -399,6 +401,7 @@ export const zh = {
   'sync.changesSummary': 'compatibility={compatibility}，共 {count} 项变更',
   'sync.configWhitespace': '仓库地址不能包含空白字符',
   'sync.configUnparseable': '无法解析仓库地址: {url}',
+  'sync.configPrivateHost': '仓库地址指向本机或内网地址，不作为同步目标: {url}',
   'sync.configUserinfo': '请勿在仓库地址中包含用户名/密码（认证 token 请使用凭据字段，不会拼入地址）',
   'sync.state.notObject': 'sync-state.json 损坏：必须是对象',
   'sync.state.schemaUnsupported': 'sync-state.json schemaVersion 不支持: {version}（期望 {expected}）',
@@ -459,6 +462,7 @@ export const zh = {
   'sync.webdav.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}',
   'sync.pruneListFailed': '远端快照裁剪失败：无法列出远端快照，{reason}',
   'sync.pruneDeleteFailed': '远端快照裁剪失败：删除快照 {id} 失败，{reason}',
+  'sync.gcSkipped': '本轮已放弃回收远端孤立文件（{code}）：本轮不做回收，快照本身不受影响',
 
   // ---------- 配置市场（m-market：只读公开仓库目录读取 + 校验） ----------
   'market.invalidItemId': '非法市场条目 id: {id}（仅允许字母数字开头，字符限 . _ -）',
@@ -571,6 +575,7 @@ export const en: Record<keyof typeof zh, string> = {
   'import.unsupportedSectionVersion': 'Section {section} data version {version} is higher than the supported version 1 (section skipped)',
   'import.checksumsMissing': 'Backup provides no integrity checksum table; no entry was verified',
   'import.extraEntries': 'ZIP contains entries not registered in the checksum table: {entries} (not verified)',
+  'import.unverifiedFileEntry': 'These entries are not covered by the checksum table and cannot be verified, so each was blocked (the rest import normally): {entries}',
   'import.undeclaredSectionContent': 'Backup contains content for undeclared sections (not marked as included; these entries will not be imported): {sections}; sample entries: {entries}',
   'import.secretsPayloadEmpty': 'The backup declares embedded secret values, but no credential ref could be read out of it: this is not "no credentials", it means they were not read (check the backup password and the source machine credential-store layout)',
   'import.migrated': 'Backup schema migrated from v{from} to v{to}',
@@ -855,6 +860,7 @@ export const en: Record<keyof typeof zh, string> = {
   'adapter.workspaceSessionsOutsideBundle': 'A further {count} session(s) are not part of this backup (their data was not imported) and stay unregistered; sessions that already exist on this machine are unaffected',
   'adapter.workspaceSessionsManual': 'The host workspace service cannot attach sessions; {count} session(s) are unregistered: re-import from Settings once DSH is up, or use the offline tool: sessions repair',
   'adapter.workspaceSessionsOwnerMissing': 'No matching target workspace record, {count} session(s) unregistered: make sure the backup contains that workspace (exporting sessions now carries their workspaces automatically)',
+  'adapter.selfImportBlocked': 'Package contains {path} (sync target config): write refused, local sync target unchanged',
   'adapter.providerMissing': 'Import data is missing provider {route}',
   'adapter.namespaceMissing': 'Import data is missing namespace {ref}',
 
@@ -905,6 +911,7 @@ export const en: Record<keyof typeof zh, string> = {
   'sync.changesSummary': 'compatibility={compatibility}, {count} change(s)',
   'sync.configWhitespace': 'Repository URL must not contain whitespace',
   'sync.configUnparseable': 'Cannot parse repository URL: {url}',
+  'sync.configPrivateHost': 'Repository URL points at this machine or a private network, so it is not accepted as a sync target: {url}',
   'sync.configUserinfo': 'Do not include a username/password in the repository URL (use the credential field for the auth token; it is never embedded in the URL)',
   'sync.state.notObject': 'sync-state.json is corrupt: must be an object',
   'sync.state.schemaUnsupported': 'sync-state.json schemaVersion not supported: {version} (expected {expected})',
@@ -961,6 +968,7 @@ export const en: Record<keyof typeof zh, string> = {
   'sync.webdav.snapshotInvalid': 'Snapshot {id} failed to parse or is structurally invalid: {err}',
   'sync.pruneListFailed': 'Remote snapshot pruning failed: could not list remote snapshots, {reason}',
   'sync.pruneDeleteFailed': 'Remote snapshot pruning failed: deleting snapshot {id} failed, {reason}',
+  'sync.gcSkipped': 'Skipped reclaiming remote orphan files this round ({code}); snapshots are unaffected',
 
   // ---------- config marketplace (m-market: read-only public repo directory read + validation) ----------
   'market.invalidItemId': 'Invalid marketplace item id: {id} (must start with an alphanumeric; only . _ - allowed)',

package/src/core/model-tools.test.ts

@@ -398,3 +398,36 @@ test('registerModelTools：tools 服务缺失 → 静默跳过（不抛错、不
     await fs.rm(tmp, { recursive: true, force: true })
   }
 })
+
+/* ---------------- SEC-03 读侧可见性：被拒 repoUrl 的成因必须传到模型工具错误里 ---------------- */
+
+/**
+ * 审计 SEC-01/02/03：`resolveEngine` 读到的 git 通道若因白名单被丢弃（repoUrl 是内网/环回/
+ * 带 userinfo/以 '-' 开头），修复前只抛「该通道未配置」——把「你配过但被拒」说成「你没配」，
+ * Agent 于是让用户「去配一下」，用户配了还是被拒，彻底卡死。
+ * 这里钉住：错误文本必须带上被拒地址与成因，且**绝不构造同步引擎**。
+ */
+test('SEC-03 config_sync_push：已存 repoUrl 被白名单拒绝 → 错误带真实成因（不是「未配置」）', async () => {
+  const { deps, tmp, transport } = await makeDeps()
+  try {
+    await fs.mkdir(deps.syncDir, { recursive: true })
+    await fs.writeFile(
+      path.join(deps.syncDir, 'sync-config.json'),
+      JSON.stringify({ schemaVersion: 2, transport: 'git', git: { repoUrl: 'https://192.168.1.10/owner/repo.git' } }),
+      'utf8',
+    )
+    const tools = createModelTools(deps)
+    await assert.rejects(
+      () => tools.syncPush({ channel: 'git' }),
+      (error: unknown) => {
+        const message = error instanceof Error ? error.message : String(error)
+        assert.ok(message.includes('192.168.1.10'), '错误必须带上被拒地址: ' + message)
+        assert.ok(/repo-url-invalid/.test(message), '错误必须带上机读成因码: ' + message)
+        return true
+      },
+    )
+    assert.ok(!transport.calls.includes('upload'), '被拒地址绝不发起任何远端写入')
+  } finally {
+    await fs.rm(tmp, { recursive: true, force: true })
+  }
+})

package/src/core/model-tools.ts

@@ -37,7 +37,7 @@ import { createEncryptionProvider } from '../security/encryption.ts'
 import { SECTION_IDS } from '../schema/config.ts'
 import type { SectionId } from '../schema/types.ts'
 import { parseSyncChannel, readFullSyncConfig, readSyncConfigFor, SYNC_CHANNELS } from '../sync/sync-config.ts'
-import type { SyncConfig, SyncTransportType } from '../sync/sync-config.ts'
+import type { SyncConfig, SyncConfigIssue, SyncTransportType } from '../sync/sync-config.ts'
 import type { ConfigAdapter, HostContext, SecretScanner } from './types.ts'
 import { runWithMutationLock } from '../utils/env-lock.ts'
 
@@ -92,17 +92,33 @@ function filterSectionIds(ids: readonly string[]): SectionId[] {
   return ids.filter((id): id is SectionId => (SECTION_IDS as readonly string[]).includes(id))
 }
 
+/**
+ * SEC-03：把「读侧被白名单丢弃的配置」翻成一句可执行的补充说明。
+ * 只挑本通道的 issue —— git 地址被拒不该出现在 webdav 的错误里。
+ */
+function describeConfigIssues(issues: readonly SyncConfigIssue[], channel: SyncTransportType): string {
+  const own = issues.filter((issue) => issue.channel === channel)
+  if (own.length === 0) return ''
+  return own.map((issue) => `config issue ${issue.code} (${issue.channel}): ${issue.message}`).join('; ')
+}
+
 /** 解析同步引擎：channel 缺省取已配置的活动通道（git/webdav），未配置则抛可操作错误。 */
 async function resolveEngine(
   deps: ModelToolsDeps,
   channel?: SyncTransportType,
 ): Promise<{ engine: SyncEngine; channel: SyncTransportType }> {
+  // SEC-03：两处读取都收集 issues —— 否则「地址被安全校验拒掉」会被报成
+  // 「sync-config.json 缺失或损坏」，让模型/用户反复重填同一个被拒地址。
+  const issues: SyncConfigIssue[] = []
   // 未显式指定通道 → 取已配置的活动通道（唯一判定口径 parseSyncChannel；缺省 git）
-  const full = channel === undefined ? await readFullSyncConfig(deps.syncDir) : null
+  const full = channel === undefined ? await readFullSyncConfig(deps.syncDir, issues) : null
   const ch: SyncTransportType = channel ?? parseSyncChannel(full?.transport) ?? 'git'
-  const cfg = await readSyncConfigFor(deps.syncDir, ch)
+  const cfg = await readSyncConfigFor(deps.syncDir, ch, issues)
   if (cfg === null) {
-    throw new Error(engineMsg('core.modelTools.syncChannelNotConfigured', { channel: ch }))
+    const base = engineMsg('core.modelTools.syncChannelNotConfigured', { channel: ch })
+    const detail = describeConfigIssues(issues, ch)
+    // 无 issue = 真的没配（保持原文案）；有 issue = 说清成因，绝不吞掉
+    throw new Error(detail === '' ? base : `${base} — ${detail}`)
   }
   return { engine: deps.makeSyncEngine(cfg), channel: ch }
 }