dsh-config-manager 0.1.71 → 0.1.73

package/lib/core/analyzer.d.ts

@@ -171,11 +171,20 @@ export declare class Analyzer {
      * 未采用其导入内容的 Conflict 都不写目标，记录只会保守化 reconcile 而无收益。
      */
     private shouldJournalStep;
-    /** 文件类且可指纹 → 返回 home-relative 目标路径（posix）；否则 null（不可指纹外部项）。
+    /** 文件类且可指纹 → 返回「根相对路径」（journal 的 ref 身份）；否则 null（不可指纹外部项）。
      *  profile 必须传入：plugins 分区的 pnpm-workspace.yaml / patch 文件位于
      *  `profiles/<profile>/` 下，缺了它算出的相对路径不存在 → 指纹恒 null（issue #35）。 */
     private static fileRelFor;
-    /** 读目标文件算 sha256（home-relative；经 HostContext.fs 使测试 mock 可注入）。失败返回 null。 */
+    /**
+     * 文件类且可指纹 → 返回「该分区自己的门面 + 绝对路径」。
+     *
+     * 为什么不能只拿 home-relative 路径去读：`pluginData` / `pluginAssets` 的根是**系统 home**
+     * （见 `core/backup.ts` 的 `fsForSection`），用 `ctx.fs` 读会落到 $DSH_HOME 下的错误位置
+     * 或被越界守卫拦下 —— 指纹会静默变成「读不到」，reconcile 因此永远判不出是否已应用。
+     * 宿主未提供该门面 / 路径不可解析 → null（保守：不可证明）。
+     */
+    private static fileTargetFor;
+    /** 读目标文件算 sha256（经该分区自己的门面，测试 mock 可注入）。失败返回 null。 */
     private fileFp;
     private applyOne;
 }

package/lib/core/analyzer.js

@@ -19,7 +19,7 @@ import { isAbsolutePath, applyPrefixMappings } from '../utils/paths.js';
 import { parseZip } from '../utils/zip.js';
 import { loadTombstones, isTombstoned } from '../schema/tombstones.js';
 import { DEFAULT_SENSITIVE_RELS, restoreVaultFiles } from '../security/vault.js';
-import { createSnapshot, planItemWritesTarget, resolveFileTarget, resolveFileTargetRel } from './backup.js';
+import { createSnapshot, fsForSection, planItemWritesTarget, resolveFileTarget, resolveFileTargetRel } from './backup.js';
 import { isCredentialConfigured } from './credential-status.js';
 import { rollback } from './rollback.js';
 import { compatibilityReasons, computeCompatibility } from './validator.js';
@@ -790,7 +790,7 @@ export class Analyzer {
                 let beforeFp = null;
                 if (Analyzer.fileRelFor(item, importCtx.target.profile) !== null) {
                     rel = Analyzer.fileRelFor(item, importCtx.target.profile);
-                    beforeFp = await this.fileFp(importCtx, rel);
+                    beforeFp = await this.fileFp(importCtx, item);
                 }
                 beforeFpByItem.set(item.id, beforeFp);
                 await sb.recordStep({
@@ -896,7 +896,7 @@ export class Analyzer {
                     const rel = Analyzer.fileRelFor(item, importCtx.target.profile);
                     let afterFp = null;
                     if (rel !== null && outcome.executed.status === 'ok') {
-                        afterFp = await this.fileFp(importCtx, rel);
+                        afterFp = await this.fileFp(importCtx, item);
                     }
                     await sb.recordStep({
                         id: item.id,
@@ -1227,7 +1227,7 @@ export class Analyzer {
     shouldJournalStep(item) {
         return planItemWritesTarget(item);
     }
-    /** 文件类且可指纹 → 返回 home-relative 目标路径（posix）；否则 null（不可指纹外部项）。
+    /** 文件类且可指纹 → 返回「根相对路径」（journal 的 ref 身份）；否则 null（不可指纹外部项）。
      *  profile 必须传入：plugins 分区的 pnpm-workspace.yaml / patch 文件位于
      *  `profiles/<profile>/` 下，缺了它算出的相对路径不存在 → 指纹恒 null（issue #35）。 */
     static fileRelFor(item, profile) {
@@ -1238,11 +1238,34 @@ export class Analyzer {
             return null;
         return resolveFileTargetRel(item.adapter, ref, profile);
     }
-    /** 读目标文件算 sha256（home-relative；经 HostContext.fs 使测试 mock 可注入）。失败返回 null。 */
-    async fileFp(ctx, rel) {
+    /**
+     * 文件类且可指纹 → 返回「该分区自己的门面 + 绝对路径」。
+     *
+     * 为什么不能只拿 home-relative 路径去读：`pluginData` / `pluginAssets` 的根是**系统 home**
+     * （见 `core/backup.ts` 的 `fsForSection`），用 `ctx.fs` 读会落到 $DSH_HOME 下的错误位置
+     * 或被越界守卫拦下 —— 指纹会静默变成「读不到」，reconcile 因此永远判不出是否已应用。
+     * 宿主未提供该门面 / 路径不可解析 → null（保守：不可证明）。
+     */
+    static fileTargetFor(ctx, item) {
+        if (!isFileSection(item.adapter))
+            return null;
+        const ref = item.target?.ref;
+        if (ref === undefined || ref === '')
+            return null;
+        try {
+            return { fs: fsForSection(ctx.target, item.adapter), abs: resolveFileTarget(ctx.target, item.adapter, ref) };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** 读目标文件算 sha256（经该分区自己的门面，测试 mock 可注入）。失败返回 null。 */
+    async fileFp(ctx, item) {
+        const target = Analyzer.fileTargetFor(ctx, item);
+        if (target === null)
+            return null;
         try {
-            const data = await ctx.target.fs.readFile(rel);
-            return sha256Hex(data);
+            return sha256Hex(await target.fs.readFile(target.abs));
         }
         catch {
             return null;

package/lib/core/backup-plan.d.ts

@@ -11,6 +11,16 @@ export declare const DEFAULT_BACKUP_SECTIONS: readonly SectionId[];
 export declare const OPT_IN_BACKUP_SECTIONS: readonly SectionId[];
 /** 全部可离线收集的分区（默认 ∪ 显式选中） */
 export declare const OFFLINE_BACKUP_SECTIONS: readonly SectionId[];
+/**
+ * 离线 CLI **明确不收集**的分区（第三方插件数据）。
+ *
+ * 为什么不做：它的收集目标不是静态路径，而是「本机内置来源注册表 + 已安装插件自述声明」推导出来的
+ * 区域（见 `core/plugin-data-registry.ts`），还要尊重环境变量覆盖判定 —— 这套判定住在 adapter 里
+ * （走 HostContext 门面），而 CLI 的硬约束是**绝不 import DSH 门面**（peer 缺失也要能跑）。
+ * 在这里手抄一份区域表会立刻与注册表漂移（正是本文件开头反复说的那类缺陷），所以选择**显式不适用**：
+ * 用户显式 `--sections pluginData` 时给一条可执行的提示（改用 GUI 导出/导入），而不是静默不收。
+ */
+export declare const OFFLINE_EXCLUDED_SECTIONS: readonly SectionId[];
 /**
  * 离线**无法**收集的分区（需要 DSH Service 门面读值/权威脱敏）。仅用于报告与参数校验，
  * 绝不写进归档：这些分区的权威形态是 GUI 导出（经 DSH `describe({redactSecrets:true})`

package/lib/core/backup-plan.js

@@ -32,6 +32,8 @@
  *    目标越出 homeDir 或断链的链接跳过但**写进 warnings**——绝不静默少收内容；
  *    普通目录**超过层级上限**同样留痕（cli-F2），且告警措辞按**真实来源**分派（t37：链接类 vs 目录超深）；
  *  - 命中 `isReservedInternalRel` 的内部命名空间（locks/snapshots/transactions…）跳过；
+ *  - 运行时依赖目录 node_modules（任意深度）**整棵跳过**（issue #76：与 plugins 分区的 npm pack 同口径，
+ *    依赖树可由包内 package.json / lock 重建），跳过了哪些目录、各多少文件一律写进 warnings；
  *  - `pluginFiles`（`dsh-ssh.json` 等第三方插件自有文件）**默认不收**：该分区与 GUI
  *    侧同为 deviceSpecific「任意文件直通、无内容过滤」，`dsh-ssh.json` 里是明文主机
  *    密码——必须由用户显式 `--sections pluginFiles` 选中，并附带显式告警
@@ -39,6 +41,7 @@
  *
  * 零 DSH 运行时依赖：仅 `node:fs/promises` + `node:path` + 本仓库零依赖模块。
  */
+import { engineMsg } from './messages-core.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { listRecursiveFollowingLinks } from '../utils/recursive-walk.js';
@@ -60,6 +63,16 @@ export const OPT_IN_BACKUP_SECTIONS = ['pluginFiles'];
 export const OFFLINE_BACKUP_SECTIONS = [
     ...DEFAULT_BACKUP_SECTIONS, ...OPT_IN_BACKUP_SECTIONS,
 ];
+/**
+ * 离线 CLI **明确不收集**的分区（第三方插件数据）。
+ *
+ * 为什么不做：它的收集目标不是静态路径，而是「本机内置来源注册表 + 已安装插件自述声明」推导出来的
+ * 区域（见 `core/plugin-data-registry.ts`），还要尊重环境变量覆盖判定 —— 这套判定住在 adapter 里
+ * （走 HostContext 门面），而 CLI 的硬约束是**绝不 import DSH 门面**（peer 缺失也要能跑）。
+ * 在这里手抄一份区域表会立刻与注册表漂移（正是本文件开头反复说的那类缺陷），所以选择**显式不适用**：
+ * 用户显式 `--sections pluginData` 时给一条可执行的提示（改用 GUI 导出/导入），而不是静默不收。
+ */
+export const OFFLINE_EXCLUDED_SECTIONS = ['pluginData', 'pluginAssets'];
 /**
  * 离线**无法**收集的分区（需要 DSH Service 门面读值/权威脱敏）。仅用于报告与参数校验，
  * 绝不写进归档：这些分区的权威形态是 GUI 导出（经 DSH `describe({redactSecrets:true})`
@@ -71,7 +84,10 @@ export const OFFLINE_UNAVAILABLE_SECTIONS = [
 // 加载期自检（注册表派生，t30）：三个离线清单里的 id 必须都是**已注册分区**。
 // 「离线可收集性」是注册表未建模的另一条轴（要脱离 DSH 读盘收集），故这三份清单仍是显式声明；
 // 但拼错 id / 分区改名过去会让该分区「静默永不收集、永不报告」，现在模块加载即失败。
-for (const id of [...DEFAULT_BACKUP_SECTIONS, ...OPT_IN_BACKUP_SECTIONS, ...OFFLINE_UNAVAILABLE_SECTIONS]) {
+for (const id of [
+    ...DEFAULT_BACKUP_SECTIONS, ...OPT_IN_BACKUP_SECTIONS, ...OFFLINE_UNAVAILABLE_SECTIONS,
+    ...OFFLINE_EXCLUDED_SECTIONS,
+]) {
     requireSectionMeta(id);
 }
 /**
@@ -109,8 +125,8 @@ const SECTION_SPECS = {
         baseDir: '',
         files: ['dsh-ssh.json', 'pet.json'],
         dirs: ['plugin-config'],
-        label: 'Plugin Files',
-        risk: '第三方插件自有文件不受控（dsh-ssh.json 内含明文主机密码等），仅在你确认内容后才应纳入备份',
+        label: "Other Plugins' Loose Files",
+        get risk() { return engineMsg('core.backupPlan.pluginFilesRisk'); },
     },
     // adapters/self.ts（baseDir='dsh-config-manager'，SELF_CONFIG_FILES 白名单）
     self: {
@@ -124,7 +140,7 @@ const SECTION_SPECS = {
             'dsh-config-manager/market/market-config.json',
             'dsh-config-manager/exports/.backup-notes.json',
         ],
-        label: 'Plugin Self Config',
+        label: "This Plugin's Own Config",
     },
 };
 /**
@@ -134,13 +150,16 @@ const SECTION_SPECS = {
  * 跳过原因；而 `too-deep` 自 cli-F2 起对**普通目录**同样会记录（此前只有链接超深才记）—— 整块内容被
  * 深度上限裁掉时若仍写成「链接未进备份」，用户看到的原因就与真实来源（目录层级超出上限）不符。
  * 措辞里**不编具体层数**：上限常量住在 utils/recursive-walk.ts，本模块不 import 它的私有常量。
+ *
+ * 路径**不叠加分区前缀**：内核返回的 `s.path` 已是 homeDir 相对路径（含分区目录），再加一层
+ * 会打印成 `skills/skills/...`（真机规模探针实测），与相邻的「目录读取失败」行口径也不一致。
  */
-function skippedLinkWarning(label, s) {
-    const at = `${label}/${s.path}（${s.reason}）`;
+function skippedLinkWarning(s) {
+    const at = engineMsg('core.backupPlan.pathWithReason', { path: s.path, reason: s.reason });
     if (s.reason === 'too-deep') {
-        return `层级超过上限未进备份（目录或链接目标超出深度上限） / nesting limit exceeded, content NOT in this backup: ${at}`;
+        return engineMsg('core.backupPlan.tooDeep', { at });
     }
-    return `链接未进备份 / link NOT in this backup: ${at}`;
+    return engineMsg('core.backupPlan.linkSkipped', { at });
 }
 /**
  * 递归列出目录下全部普通文件（**相对 homeDir** 的 posix 路径，已排序）；目录不存在 → 空。
@@ -149,16 +168,23 @@ function skippedLinkWarning(label, s) {
  * 并把「跟随了多少链接」「哪些链接/目录没进来（及原因）」写进 warnings。
  * 旧实现遇到链接目录直接跳过且零告警，用户拿到的是「成功但缺斤少两」的备份。
  */
-async function listFilesRecursive(dirAbs, homeDir, warnings, label) {
+async function listFilesRecursive(dirAbs, homeDir, warnings) {
     const listing = await listRecursiveFollowingLinks(dirAbs, homeDir);
     for (const s of listing.skippedLinks) {
-        warnings.push(skippedLinkWarning(label, s));
+        warnings.push(skippedLinkWarning(s));
     }
     for (const dir of listing.unreadableDirs) {
-        warnings.push(`目录读取失败，其内容未进备份 / directory unreadable, content NOT in this backup: ${dir}`);
+        warnings.push(engineMsg('core.backupPlan.dirUnreadable', { dir }));
+    }
+    // issue #76：运行时依赖目录整棵跳过（内容未进备份）——必须可见，绝不静默。
+    for (const dep of listing.skippedDepDirs) {
+        const files = dep.files === null
+            ? engineMsg('core.backupPlan.countNotMeasured')
+            : engineMsg('core.backupPlan.fileCount', { count: dep.files });
+        warnings.push(engineMsg('core.backupPlan.depDirSkipped', { path: dep.path, files }));
     }
     if (listing.followedLinks > 0) {
-        warnings.push(`已跟随 ${listing.followedLinks} 个链接目录收集内容 / followed ${listing.followedLinks} linked director(ies)`);
+        warnings.push(engineMsg('core.backupPlan.followedLinks', { count: listing.followedLinks }));
     }
     return listing.paths;
 }
@@ -171,15 +197,20 @@ function toRelativePath(baseDir, homeRel) {
 }
 /** `--sections` 取值校验：返回选中分区或可读错误（未知 id 一律拒绝并列出合法值） */
 export function parseSectionsArg(raw) {
-    const parts = raw.split(/[,，\s]+/).filter((p) => p !== '');
+    const parts = raw.split(/[,\uFF0C\s]+/).filter((p) => p !== '');
     if (parts.length === 0) {
-        return { ok: false, error: '`--sections` 缺值 / missing value for `--sections`' };
+        return { ok: false, error: engineMsg('core.backupPlan.sectionsMissingValue') };
+    }
+    // 显式请求「不支持离线」的分区 → 单独一条可执行提示（不得当成「不存在的分区」）
+    const notOffline = parts.filter((p) => OFFLINE_EXCLUDED_SECTIONS.includes(p));
+    if (notOffline.length > 0) {
+        return { ok: false, error: engineMsg('core.backupPlan.sectionNotOffline', { section: notOffline.join(', ') }) };
     }
     const unknown = parts.filter((p) => !OFFLINE_BACKUP_SECTIONS.includes(p));
     if (unknown.length > 0) {
         return {
             ok: false,
-            error: `未知分区 / unknown section(s): ${unknown.join(', ')}（可用 / available: ${OFFLINE_BACKUP_SECTIONS.join(', ')}）`,
+            error: engineMsg('core.backupPlan.unknownSections', { unknown: unknown.join(', '), available: OFFLINE_BACKUP_SECTIONS.join(', ') }),
         };
     }
     // 去重并保持声明顺序，保证产物可复现
@@ -207,7 +238,7 @@ export async function collectBackupEntries(homeDir, only = []) {
         let excluded = 0;
         const push = (zipName, data) => {
             if (!isPathSafe(zipName)) {
-                warnings.push(`跳过不安全条目名 / unsafe entry name skipped: ${zipName}`);
+                warnings.push(engineMsg('core.backupPlan.unsafeEntryName', { name: zipName }));
                 excluded += 1;
                 return;
             }
@@ -229,7 +260,7 @@ export async function collectBackupEntries(homeDir, only = []) {
             catch (err) {
                 // 不存在 → 静默跳过（按需创建的文件，如 dsh-ssh.json）
                 if (err.code !== 'ENOENT') {
-                    warnings.push(`探测失败 / stat failed: ${norm}（${err instanceof Error ? err.message : String(err)}）`);
+                    warnings.push(engineMsg('core.backupPlan.statFailed', { path: norm, reason: err instanceof Error ? err.message : String(err) }));
                 }
                 return;
             }
@@ -242,7 +273,7 @@ export async function collectBackupEntries(homeDir, only = []) {
                 push(`${prefix}${toRelativePath(spec.baseDir, norm)}`, new Uint8Array(data));
             }
             catch (err) {
-                warnings.push(`读取失败 / read failed: ${norm}（${err instanceof Error ? err.message : String(err)}）`);
+                warnings.push(engineMsg('core.backupPlan.readFailed', { path: norm, reason: err instanceof Error ? err.message : String(err) }));
             }
         };
         // 1) 固定文件（存在才收）
@@ -251,7 +282,7 @@ export async function collectBackupEntries(homeDir, only = []) {
         // 2) 递归目录（跟随 junction/符号链接；未跟随的链接与不可读目录写进 warnings）
         for (const dirRel of spec.dirs ?? []) {
             const dirAbs = path.join(homeDir, ...normalizePath(dirRel).split('/'));
-            const rels = await listFilesRecursive(dirAbs, homeDir, warnings, normalizePath(dirRel));
+            const rels = await listFilesRecursive(dirAbs, homeDir, warnings);
             for (const homeRel of rels)
                 await consider(homeRel);
         }
@@ -264,7 +295,7 @@ export async function collectBackupEntries(homeDir, only = []) {
         }
         else {
             empty.push(sectionId);
-            warnings.push(`分区无内容，未写入 / section empty, skipped: ${sectionId}`);
+            warnings.push(engineMsg('core.backupPlan.sectionEmpty', { section: sectionId }));
         }
     }
     return { entries, sections, warnings, included, empty };

package/lib/core/backup-verify.js

@@ -28,6 +28,7 @@
  *    （实测 `verifyChecksums` 只调用 `map.get()`，不会整体物化 Map）。
  *    对 MB 级的 DSH 配置备份完全可接受。
  */
+import { engineMsg } from './messages-core.js';
 import fs from 'node:fs/promises';
 import { verifyChecksums } from '../utils/hashing.js';
 import { isENOENT } from '../utils/guards.js';
@@ -114,7 +115,7 @@ export async function verifyBackupZip(zipPath) {
     try {
         const stat = await fs.stat(zipPath);
         if (!stat.isFile()) {
-            errors.push(`不是普通文件（目录或特殊文件）/ not a regular file: ${zipPath}`);
+            errors.push(engineMsg('core.backupVerify.notRegularFile', { zip: zipPath }));
             return makeResult(zipPath, 'MISSING', errors, warnings);
         }
         sizeBytes = stat.size;
@@ -122,11 +123,11 @@ export async function verifyBackupZip(zipPath) {
     }
     catch (err) {
         if (isENOENT(err)) {
-            errors.push(`备份文件不存在 / backup file not found: ${zipPath}`);
+            errors.push(engineMsg('core.backupVerify.fileNotFound', { zip: zipPath }));
             return makeResult(zipPath, 'MISSING', errors, warnings);
         }
         // 文件在但读不动（EACCES / EBUSY / IO 错）：这是自检自身的失败，不是「备份坏了」
-        errors.push(`备份文件不可读 / backup file unreadable: ${msgOfError(err)}`);
+        errors.push(engineMsg('core.backupVerify.fileUnreadable', { reason: msgOfError(err) }));
         return makeResult(zipPath, 'VERIFY_ERROR', errors, warnings);
     }
     /** 已知字节数后的骨架（后续阶段失败时保留体积信息） */
@@ -137,7 +138,7 @@ export async function verifyBackupZip(zipPath) {
         /* ---------------- 2. 打开为 ZIP ---------------- */
         // 整体加密容器不是 ZIP（先识别，给出比「ZIP 损坏」准确得多的结论）
         if (isArchiveBlob(buf)) {
-            errors.push('整体加密备份容器（DCA1）需先用密码解密为 ZIP 才能自检 / encrypted container must be decrypted first');
+            errors.push(engineMsg('core.backupVerify.encryptedContainer'));
             return withSize('UNSUPPORTED');
         }
         let archive;
@@ -145,7 +146,7 @@ export async function verifyBackupZip(zipPath) {
             archive = createHardenedZipParser()(buf);
         }
         catch (err) {
-            errors.push(`ZIP 无法打开 / cannot open as ZIP: ${msgOfError(err)}`);
+            errors.push(engineMsg('core.backupVerify.cannotOpenZip', { reason: msgOfError(err) }));
             return withSize('CORRUPT');
         }
         const metas = archive.entries();
@@ -154,12 +155,12 @@ export async function verifyBackupZip(zipPath) {
             file: zipPath, verdict, sizeBytes, entryCount, errors, warnings,
         });
         if (entryCount === 0) {
-            errors.push('空 ZIP（0 条目）/ empty archive');
+            errors.push(engineMsg('core.backupVerify.emptyArchive'));
             return withEntries('CORRUPT');
         }
         /* ---------------- 3. manifest.json ---------------- */
         if (!archive.has(MANIFEST_FILE)) {
-            errors.push(`缺少 ${MANIFEST_FILE}（不是本插件导出的备份）/ ${MANIFEST_FILE} missing`);
+            errors.push(engineMsg('core.backupVerify.missingManifest', { file: MANIFEST_FILE }));
             return withEntries('CORRUPT');
         }
         let manifestRaw;
@@ -168,7 +169,7 @@ export async function verifyBackupZip(zipPath) {
         }
         catch (err) {
             // 条目本身读不出来（CRC 失败/解压失败）→ 归档损坏，而非 manifest 语义非法
-            errors.push(`${MANIFEST_FILE} 无法读取（归档损坏）/ unreadable entry: ${msgOfError(err)}`);
+            errors.push(engineMsg('core.backupVerify.manifestUnreadable', { file: MANIFEST_FILE, reason: msgOfError(err) }));
             return withEntries('CORRUPT');
         }
         let manifest;
@@ -176,7 +177,7 @@ export async function verifyBackupZip(zipPath) {
             manifest = parseManifest(manifestRaw);
         }
         catch (err) {
-            errors.push(`${MANIFEST_FILE} 非法 / invalid manifest: ${msgOfError(err)}`);
+            errors.push(engineMsg('core.backupVerify.invalidManifest', { file: MANIFEST_FILE, reason: msgOfError(err) }));
             return withEntries('CORRUPT');
         }
         const sections = Object.entries(manifest.sections ?? {})
@@ -187,12 +188,12 @@ export async function verifyBackupZip(zipPath) {
         });
         if (!isSupported(manifest.schemaVersion)) {
             // 版本超范围是「本插件读不了」，不是「备份坏了」——明确区分，避免误导用户重导
-            errors.push(`schema 版本不受支持 / unsupported schema version: ${describeVersion(manifest.schemaVersion)}`);
+            errors.push(engineMsg('core.backupVerify.unsupportedSchema', { version: describeVersion(manifest.schemaVersion) }));
             return withManifest('UNSUPPORTED');
         }
         /* ---------------- 4. integrity/checksums.json ---------------- */
         if (!archive.has(CHECKSUMS_FILE)) {
-            errors.push(`缺少 ${CHECKSUMS_FILE}（无法做完整性校验）/ ${CHECKSUMS_FILE} missing`);
+            errors.push(engineMsg('core.backupVerify.missingChecksums', { file: CHECKSUMS_FILE }));
             return withManifest('CORRUPT');
         }
         let table;
@@ -201,7 +202,7 @@ export async function verifyBackupZip(zipPath) {
         }
         catch (err) {
             // readEntryText 的 CRC/解压失败与「表结构非法」都归 CORRUPT（两者都说明备份不可信）
-            errors.push(`${CHECKSUMS_FILE} 非法或不可读 / invalid or unreadable checksums table: ${msgOfError(err)}`);
+            errors.push(engineMsg('core.backupVerify.invalidChecksums', { file: CHECKSUMS_FILE, reason: msgOfError(err) }));
             return withManifest('CORRUPT');
         }
         // 4a. 完整性比对：**复用官方 verifyChecksums**（与导出侧 buildChecksums 同源同口径），
@@ -209,7 +210,7 @@ export async function verifyBackupZip(zipPath) {
         const unreadableNames = new Set();
         const unreadable = [];
         const lazyEntries = new LazyEntryMap(archive, unreadableNames, (name, reason) => {
-            unreadable.push(`${name}（${reason}）`);
+            unreadable.push(engineMsg('core.backupVerify.unreadableEntry', { name, reason }));
         });
         const tableKeys = Object.keys(table);
         const check = verifyChecksums(lazyEntries, table);
@@ -219,10 +220,10 @@ export async function verifyBackupZip(zipPath) {
         // 4b. 结构提示：未纳入校验表的条目（导出器只把 manifest 与校验表自身排除在外）
         if (tableKeys.length === 0) {
             if (entryCount > NON_DATA_ENTRIES.size) {
-                errors.push('校验表为空但归档含数据条目 / empty checksums table with data entries');
+                errors.push(engineMsg('core.backupVerify.emptyTableWithData'));
                 return withManifest('CORRUPT');
             }
-            warnings.push('校验表为空（归档仅含 manifest 与校验表自身）/ empty checksums table');
+            warnings.push(engineMsg('core.backupVerify.emptyTable'));
         }
         const covered = new Set(tableKeys);
         const uncovered = metas
@@ -230,7 +231,7 @@ export async function verifyBackupZip(zipPath) {
             .map((m) => m.name);
         if (uncovered.length > 0) {
             const shown = uncovered.slice(0, 5).join(', ');
-            warnings.push(`含未纳入校验表的条目 ${uncovered.length} 个 / entries not covered by checksums: ${shown}${uncovered.length > 5 ? ', …' : ''}`);
+            warnings.push(engineMsg('core.backupVerify.uncoveredEntries', { count: uncovered.length, shown, suffix: uncovered.length > 5 ? ', …' : '' }));
         }
         // 4c. 结构提示：manifest 声明包含的分区在归档内应有对应条目
         for (const id of sections) {
@@ -238,31 +239,31 @@ export async function verifyBackupZip(zipPath) {
             const jsonPath = SECTION_JSON_PATHS[id];
             if (prefix !== undefined) {
                 if (!metas.some((m) => m.name.startsWith(prefix) && m.name !== prefix)) {
-                    warnings.push(`manifest 声明分区 ${id} 但归档内无对应文件 / declared section has no entries: ${id}`);
+                    warnings.push(engineMsg('core.backupVerify.declaredSectionNoEntries', { id }));
                 }
             }
             else if (jsonPath !== undefined && !archive.has(jsonPath)) {
-                warnings.push(`manifest 声明分区 ${id} 但缺少 ${jsonPath} / declared section payload missing: ${id}`);
+                warnings.push(engineMsg('core.backupVerify.declaredSectionPayloadMissing', { id, path: jsonPath }));
             }
         }
         if (manifest.security?.encrypted === true && !metas.some((m) => SECRETS_ENC_RE.test(m.name))) {
-            warnings.push('manifest 标记加密但归档内无凭据密文条目 / encrypted flag without secrets entry');
+            warnings.push(engineMsg('core.backupVerify.encryptedFlagNoSecrets'));
         }
         /* ---------------- 裁决 ---------------- */
         if (missing.length > 0) {
-            errors.push(`校验表内条目缺失（${missing.length}）/ missing entries: ${missing.join(', ')}`);
+            errors.push(engineMsg('core.backupVerify.missingEntries', { count: missing.length, list: missing.join(', ') }));
         }
         if (mismatched.length > 0) {
-            errors.push(`条目 SHA-256 不符（${mismatched.length}）/ hash mismatch: ${mismatched.join(', ')}`);
+            errors.push(engineMsg('core.backupVerify.hashMismatch', { count: mismatched.length, list: mismatched.join(', ') }));
         }
         if (unreadable.length > 0) {
-            errors.push(`条目无法读取（${unreadable.length}）/ unreadable entries: ${unreadable.join(', ')}`);
+            errors.push(engineMsg('core.backupVerify.unreadableEntries', { count: unreadable.length, list: unreadable.join(', ') }));
         }
         return withManifest(missing.length > 0 || mismatched.length > 0 || unreadable.length > 0 ? 'CORRUPT' : 'OK');
     }
     catch (err) {
         // 5. 自检自身异常：如实报 VERIFY_ERROR，绝不降级成 OK
-        errors.push(`自检过程异常 / verification error: ${msgOfError(err)}`);
+        errors.push(engineMsg('core.backupVerify.verificationError', { reason: msgOfError(err) }));
         return withSize('VERIFY_ERROR');
     }
 }

package/lib/core/backup.d.ts

@@ -1,5 +1,5 @@
 import type { SectionId } from '../schema/types.ts';
-import type { ConfigAdapter, HostContext, ImportPlan, PlanItem, Snapshot, SnapshotStatus, SnapshotStore } from './types.ts';
+import type { ConfigAdapter, FileSystemFacade, HostContext, ImportPlan, PlanItem, Snapshot, SnapshotStatus, SnapshotStore } from './types.ts';
 /**
  * 「会写目标」的**单点事实源**：该计划项是否会被引擎交给 `adapter.applyItem`
  * （即可能产生目标写入）。
@@ -38,6 +38,25 @@ export declare function planItemWritesTarget(item: PlanItem, exec?: PlanItemExec
  * 行 id 是任意字符串，无法靠形状判断它是不是一个路径。
  */
 export declare const PLUGIN_PATCH_REF_PREFIX = "patchFile:";
+/**
+ * 以**系统 home 为根**的文件类分区（ref 是系统 home 相对路径）。
+ *
+ * 为什么单独一组：`FileSystemFacade` 被限制在 $DSH_HOME 内，而第三方插件的数据常在 $DSH_HOME 之外
+ * （`~/.dsh-wallpaper-engine/`、`~/.mnemon/` …）。这两个分区的路径解析与 I/O 门面都换根，
+ * 其余分区一字不动 —— 单根不变量只在**这两个分区**上被显式放宽，且仍然只允许白名单区域。
+ */
+export declare const OS_HOME_FILE_SECTIONS: ReadonlySet<SectionId>;
+/** 该分区文件目标的根（`dsh` = $DSH_HOME；`osHome` = 系统 home） */
+export declare function sectionFileRoot(adapter: SectionId): 'dsh' | 'osHome';
+/** 系统 home：宿主显式给就用它，否则进程 `homedir()`（`~` 的定义，不是猜） */
+export declare function osHomeDirOf(ctx: HostContext): string;
+/**
+ * 该分区文件 I/O 应使用的门面。
+ *
+ * `osHome` 分区必须用 `homeFs`：缺了它**显式抛错**，绝不退回 `ctx.fs` —— 那会把
+ * `~/.mnemon/x.db` 写成 `$DSH_HOME/.mnemon/x.db`（看起来成功、实际写错位置）。
+ */
+export declare function fsForSection(ctx: HostContext, adapter: SectionId): FileSystemFacade;
 /** 解析文件类目标的绝对路径（引擎通用快照与回滚共用） */
 export declare function resolveFileTarget(ctx: HostContext, adapter: SectionId, ref: string): string;
 /**
@@ -144,6 +163,11 @@ export interface FileSnapshotStoreOptions {
      * 未注入 → `fallbackPruneSelector`（只按 keepLast，等价既有 FIFO；分层字段被忽略 = 保守少删）。
      */
     pruneSelector?: PruneSelector;
+    /**
+     * 诊断回调（可选）：保留清理**被放弃**或失败时的可见线索。
+     * 缺省 = 不记录（不改变行为）；宿主接 `host.log.warn` —— 「这轮为什么没清理」必须能查。
+     */
+    onWarn?: (message: string) => void;
 }
 /** 文件快照存储：<dir>/<id>/snapshot.json + <dir>/<id>/blobs/* */
 export declare class FileSnapshotStore implements SnapshotStore {