dsh-config-manager 0.1.71 → 0.1.72

package/lib/sync/s3/messages.d.ts

@@ -29,6 +29,13 @@ export declare const s3Zh: {
     readonly 'sync.s3.indexInvalid': '{url} 解析失败或结构非法: {err}';
     readonly 'sync.s3.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}';
     readonly 'sync.s3.indexMissingWithContent': '远端已有内容但索引 {url} 缺失（HTTP 404）：拒绝以空集合覆盖权威索引，本次上传已中止（零写入）';
+    readonly 'sync.s3.providerNoteS3': 'AWS S3（默认 us-east-1；AWS 中国区/自建网关请覆盖 endpoint）';
+    readonly 'sync.s3.providerNoteOss': '阿里云 OSS（region 必填，如 cn-hangzhou；签名方言 OSS4，头名 x-oss-*）';
+    readonly 'sync.s3.providerNoteCos': '腾讯云 COS（region 必填，如 ap-guangzhou；2024 年后新建桶只支持 virtual-host 寻址）';
+    readonly 'sync.s3.providerNoteMinio': 'MinIO / 自建网关（endpoint 必填；默认 path-style，配了域名才用 virtual-host）';
+    readonly 'sync.s3.providerNoteKodo': '七牛 Kodo S3 兼容（region 必填，如 cn-east-1；endpoint 可覆盖）';
+    readonly 'sync.s3.unknownSignatureDialect': '未知签名方言: {id}';
+    readonly 'sync.s3.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}';
 };
 export declare const s3En: Record<keyof typeof s3Zh, string>;
 /**

package/lib/sync/s3/messages.js

@@ -17,6 +17,15 @@ export const s3Zh = {
     'sync.s3.indexInvalid': '{url} 解析失败或结构非法: {err}',
     'sync.s3.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}',
     'sync.s3.indexMissingWithContent': '远端已有内容但索引 {url} 缺失（HTTP 404）：拒绝以空集合覆盖权威索引，本次上传已中止（零写入）',
+    // ---- t6（英文界面零中文）：变体说明（供 UI/文档用 msg() 解析；本字段自 t6 起是**目录键**而非文案）、
+    // 方言兜底与 blob 仓哈希形状守卫。键落本地目录 ⇒ composeMsg(host, s3Msg) 与「不传 msg」两条路径都不露裸键名。
+    'sync.s3.providerNoteS3': 'AWS S3（默认 us-east-1；AWS 中国区/自建网关请覆盖 endpoint）',
+    'sync.s3.providerNoteOss': '阿里云 OSS（region 必填，如 cn-hangzhou；签名方言 OSS4，头名 x-oss-*）',
+    'sync.s3.providerNoteCos': '腾讯云 COS（region 必填，如 ap-guangzhou；2024 年后新建桶只支持 virtual-host 寻址）',
+    'sync.s3.providerNoteMinio': 'MinIO / 自建网关（endpoint 必填；默认 path-style，配了域名才用 virtual-host）',
+    'sync.s3.providerNoteKodo': '七牛 Kodo S3 兼容（region 必填，如 cn-east-1；endpoint 可覆盖）',
+    'sync.s3.unknownSignatureDialect': '未知签名方言: {id}',
+    'sync.s3.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}',
 };
 export const s3En = {
     'sync.s3.providerUnknown': 'Unknown S3-compatible channel: {provider}',
@@ -37,6 +46,13 @@ export const s3En = {
     'sync.s3.indexInvalid': '{url} failed to parse or is structurally invalid: {err}',
     'sync.s3.snapshotInvalid': 'Snapshot {id} failed to parse or is structurally invalid: {err}',
     'sync.s3.indexMissingWithContent': 'The remote already has content but index {url} is missing (HTTP 404): refusing to overwrite the authoritative index with an empty set; this upload was aborted (zero writes)',
+    'sync.s3.providerNoteS3': 'AWS S3 (defaults to us-east-1; override endpoint for AWS China or self-hosted gateways)',
+    'sync.s3.providerNoteOss': 'Alibaba Cloud OSS (region required, e.g. cn-hangzhou; OSS4 signature dialect with x-oss-* headers)',
+    'sync.s3.providerNoteCos': 'Tencent Cloud COS (region required, e.g. ap-guangzhou; buckets created after 2024 only support virtual-host addressing)',
+    'sync.s3.providerNoteMinio': 'MinIO / self-hosted gateway (endpoint required; path-style by default, virtual-host only when a domain is configured)',
+    'sync.s3.providerNoteKodo': 'Qiniu Kodo S3-compatible (region required, e.g. cn-east-1; endpoint can be overridden)',
+    'sync.s3.unknownSignatureDialect': 'Unknown signature dialect: {id}',
+    'sync.s3.blobHashInvalid': 'Malformed content hash; refusing to write to the blob store: {hash}',
 };
 /** 插值：{param} → 形参值；缺参原样保留（与 core/messages.ts 同口径）。 */
 function interpolate(template, params) {

package/lib/sync/s3/s3-providers.d.ts

@@ -18,7 +18,10 @@ export interface S3ProviderVariant {
     endpointTemplate?: string;
     /** 默认寻址风格：true = path-style（<endpoint>/<bucket>/<key>），false = virtual-host（<bucket>.<endpoint>/<key>） */
     defaultPathStyle: boolean;
-    /** 变体说明（供 UI/文档映射成字典键；不是用户最终文案） */
+    /**
+     * 变体说明的**目录键**（自 t6 起字段是键而不是文案 —— 中文只存在于 `sync/s3/messages.ts` 的本地目录，
+     * 经 `s3Msg` / `composeMsg(host, s3Msg)` 解析成当前语言；本字段本身不渲染）。
+     */
     note: string;
 }
 /**

package/lib/sync/s3/s3-providers.js

@@ -31,26 +31,26 @@ export const S3_PROVIDER_VARIANTS = {
     s3: {
         id: 's3', dialectId: 'aws4', service: 's3', defaultRegion: 'us-east-1',
         endpointTemplate: 'https://s3.{region}.amazonaws.com', defaultPathStyle: false,
-        note: 'AWS S3（默认 us-east-1；AWS 中国区/自建网关请覆盖 endpoint）',
+        note: 'sync.s3.providerNoteS3',
     },
     oss: {
         id: 'oss', dialectId: 'oss4', service: 'oss',
         endpointTemplate: 'https://oss-{region}.aliyuncs.com', defaultPathStyle: false,
-        note: '阿里云 OSS（region 必填，如 cn-hangzhou；签名方言 OSS4，头名 x-oss-*）',
+        note: 'sync.s3.providerNoteOss',
     },
     cos: {
         id: 'cos', dialectId: 'aws4', service: 's3',
         endpointTemplate: 'https://cos.{region}.myqcloud.com', defaultPathStyle: false,
-        note: '腾讯云 COS（region 必填，如 ap-guangzhou；2024 年后新建桶只支持 virtual-host 寻址）',
+        note: 'sync.s3.providerNoteCos',
     },
     minio: {
         id: 'minio', dialectId: 'aws4', service: 's3', defaultRegion: 'us-east-1', defaultPathStyle: true,
-        note: 'MinIO / 自建网关（endpoint 必填；默认 path-style，配了域名才用 virtual-host）',
+        note: 'sync.s3.providerNoteMinio',
     },
     kodo: {
         id: 'kodo', dialectId: 'aws4', service: 's3',
         endpointTemplate: 'https://s3-{region}.qiniucs.com', defaultPathStyle: false,
-        note: '七牛 Kodo S3 兼容（region 必填，如 cn-east-1；endpoint 可覆盖）',
+        note: 'sync.s3.providerNoteKodo',
     },
 };
 /** 变体查表：非法通道 → undefined（调用方给 \`cloud.providerUnknown\` 码）。 */

package/lib/sync/s3/s3-transport.js

@@ -447,7 +447,7 @@ export class S3Transport {
         return {
             put: async (hash, bytes) => {
                 if (!BLOB_HASH_RE.test(hash)) {
-                    throw new S3TransportError('内容哈希形状非法，拒绝写入 blob 仓: ' + hash);
+                    throw new S3TransportError(this.o.msg('sync.s3.blobHashInvalid', { hash }));
                 }
                 if (index[hash] !== undefined)
                     return; // 内容未变 → 一个字都不传

package/lib/sync/s3/sigv4.js

@@ -19,6 +19,7 @@
  *  - 不做任何 I/O：请求头的注入与发送由通道层（s3-transport）负责。
  */
 import { createHash, createHmac } from 'node:crypto';
+import { s3Msg } from './messages.js';
 /** 「不校验载荷」的载荷哈希字面量（OSS4 目前只支持该取值）。 */
 export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
 /** AWS SigV4（S3 / MinIO / COS / Kodo 共用）。 */
@@ -51,7 +52,7 @@ export function sigV4Dialect(id) {
         return AWS_SIG_V4;
     if (id === 'oss4')
         return OSS_SIG_V4;
-    throw new Error('未知签名方言: ' + String(id));
+    throw new Error(s3Msg('sync.s3.unknownSignatureDialect', { id: String(id) }));
 }
 /** SHA-256 十六进制小写。 */
 export function sha256Hex(data) {

package/lib/sync/snapshot-crypto.js

@@ -17,6 +17,7 @@ import { collectCredentialRefs } from '../security/credentials-yaml.js';
 import { decryptCredentials, encryptCredentials } from '../security/encryption.js';
 import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 import { sectionsFromJsonSafe, sectionsToJsonSafe } from './snapshot-json.js';
+import { engineMsg } from './messages.js';
 /**
  * 加密整个明文 sections Record → 密文载荷（info 进 manifest 非秘密参数；data 为 base64 密文）。
  * 序列化经 snapshot-json：文件类分区字节以 base64 进入载荷，解密后还原 Uint8Array
@@ -24,18 +25,18 @@ import { sectionsFromJsonSafe, sectionsToJsonSafe } from './snapshot-json.js';
  */
 export async function encryptSectionsPayload(sections, password) {
     if (password === '')
-        throw new Error('加密密码不能为空');
+        throw new Error(engineMsg('sync.encryptPasswordRequired'));
     const { blob, info } = await encryptCredentials(stringifyJsonSafe(sectionsToJsonSafe(sections)), password);
     return { encrypted: { info, data: Buffer.from(blob).toString('base64') } };
 }
 /** 解密密文载荷 → 明文 sections Record（密码错误 / 密文被篡改 → SecurityError）。 */
 export async function decryptSectionsPayload(payload, password) {
     if (password === '')
-        throw new Error('解密密码不能为空');
+        throw new Error(engineMsg('sync.decryptPasswordRequired'));
     const plain = await decryptCredentials(Buffer.from(payload.data, 'base64'), payload.info, password);
     const parsed = parseJsonSafe(plain);
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('加密快照内容损坏：解密后不是有效的分区对象');
+        throw new Error(engineMsg('sync.encryptedContentInvalid'));
     }
     return sectionsFromJsonSafe(parsed);
 }
@@ -50,14 +51,14 @@ export function encryptionInfoOf(payload) {
  */
 export async function encryptCredentialsPayload(plaintext, password) {
     if (password === '')
-        throw new Error('加密密码不能为空');
+        throw new Error(engineMsg('sync.encryptPasswordRequired'));
     const { blob, info } = await encryptCredentials(plaintext, password);
     return { info, data: Buffer.from(blob).toString('base64') };
 }
 /** 解密凭据载荷 → `.credentials.yaml` 原文（密码错误 / 密文被篡改 → SecurityError）。 */
 export async function decryptCredentialsPayload(payload, password) {
     if (password === '')
-        throw new Error('解密密码不能为空');
+        throw new Error(engineMsg('sync.decryptPasswordRequired'));
     return await decryptCredentials(Buffer.from(payload.data, 'base64'), payload.info, password);
 }
 /**

package/lib/sync/snapshot-json.js

@@ -1,5 +1,6 @@
 import { MAX_OWN_PAYLOAD_JSON_BYTES, parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 import { isEncryptedCredentials, isEncryptedSections } from './transport.js';
+import { engineMsg } from './messages.js';
 /** 二进制数据在 JSON 中的标记对象键（base64 载荷）。 */
 const BIN_KEY = '$bin';
 /** duck-typing：文件类分区（version===1 + files 数组） */
@@ -68,7 +69,7 @@ export function sectionsFromJsonSafe(sections) {
     if (isEncryptedSections(sections))
         return sections;
     if (sections === null || typeof sections !== 'object' || Array.isArray(sections)) {
-        throw new Error('快照 sections 必须是对象');
+        throw new Error(engineMsg('sync.snapshotSectionsNotObject'));
     }
     const out = {};
     for (const [id, data] of Object.entries(sections)) {
@@ -104,7 +105,7 @@ export function deserializeSnapshot(raw) {
         && typeof snap.manifest === 'object' && snap.manifest !== null
         && typeof snap.sections === 'object' && snap.sections !== null;
     if (!okShape) {
-        throw new Error('快照 JSON 形状非法（缺少 id/createdAt/manifest/sections）');
+        throw new Error(engineMsg('sync.snapshotJsonInvalid'));
     }
     // issue #38：凭据载荷（形状不合法 → 视为不存在，不让坏数据破坏整份快照解析）
     const rawCredentials = snap.credentials;

package/lib/sync/sync-engine.d.ts

@@ -37,14 +37,17 @@ export interface SyncEngineOptions {
     /** 消息翻译器（缺省 ctx.msg ?? zh） */
     msg?: MsgFunc;
     /**
-     * 显式开启「可选分区」（OPT_IN_SYNC_SECTIONS，目前只有 sessions）在**拉取/合并/应用**侧
-     * 的参与：只有 true 时，远端快照里的可选分区才会进入临时 ZIP 与合并输入。
+     * 本次运行**显式放行的「可选分区」集合**（拉取/合并/应用 + 推送两侧共用）。
      *
-     * 缺省 false —— 自动同步等无用户确认的路径永不拉取会话；宿主只在**用户驱动**的
-     * pull / 一键同步路由上、且用户持久化的分区选择确实包含该可选分区时才传 true。
-     * （推送侧不受它影响：push 由 opts.sessions 单独把关。）
+     * 缺省空集 —— 可选分区默认永不参与同步。宿主按「该分区允许哪种驱动」决定传什么：
+     *  - 手动 push/pull / 一键同步 → 持久化选择里的全部可选分区（OPT_IN_SYNC_SECTIONS ∩ 勾选）；
+     *  - 自动同步 / model-tools → 只传 'auto' 档（AUTO_SYNC_OPT_IN_SECTION_IDS ∩ 勾选），
+     *    sessions（'manual'）因此**绝不悄悄下行/上行**。
+     *
+     * 为什么是集合而不是布尔：布尔只能表达「全放行 / 全不放行」，勾了 mcp 会连带放行
+     * sessions（issue #78 的回归点）。集合化后每个分区独立放行。
      */
-    includeOptInSections?: boolean;
+    optInSections?: readonly SectionId[];
     /**
      * 同步范围（高级/自定义导出模式持久化配置）：只处理这些 portable 分区。
      * 缺省 = 全部 portable 推荐分区。应用于 push / merge / applyMergePlan / applyItems
@@ -69,12 +72,15 @@ export interface SyncPushOptions {
     /** 仅同步指定分区（缺省 = 全部 portable 推荐分区，即「默认/快速导出」模式）。
      *  传入非 portable 或未知分区 → 忽略并告警（同步通道安全约束：
      *  deviceSpecific/platformSpecific 默认永不进入同步通道；未知 id 不静默吞掉）。
-     *  例外：OPT_IN_SYNC_SECTIONS 里的分区（目前只有 sessions）在**同时提供对应选项**
-     *  （见 sessions）时才纳入 —— 没有选项一律按非 portable 跳过并告警。 */
+     *  例外：构造期显式放行的可选分区（SyncEngineOptions.optInSections）才纳入 ——
+     *  未被放行的一律按非 portable 跳过并告警（不静默）。 */
     sections?: SectionId[];
     /**
-     * sessions（历史会话）分区选项：只有显式给出它，sessions 才被允许进入同步通道
-     * （「最新 N 个会话」上限）。缺省 / 未提供 → sessions 与其它 deviceSpecific 分区同样被跳过。
+     * sessions（历史会话）分区的**导出参数**（「最新 N 个会话」上限 / 逐会话点名）。
+     *
+     * 注意：它**不再兼任放行开关** —— 是否允许 sessions 进通道只由构造期
+     * SyncEngineOptions.optInSections 决定（issue #78 把「放行」与「参数」拆开，
+     * 否则勾了 mcp 会顺带解锁 sessions）。这里只决定「带哪几个会话」。
      *
      * include（显式勾选的会话单元 id，形如 sessions:<projectKey>/<sessionId>）非空时
      * **优先于 limit**：用户点名的对话必须赢；此时不施加「最新 N 个」数量筛选，否则会退化成
@@ -182,9 +188,16 @@ export interface ApplyReport {
     restoreId: string;
     /** 是否触发了整体回滚 */
     rolledBack: boolean;
+    /**
+     * 整体回滚是否**完整**（诚实性，2026-10）。rolledBack=true 只说明触发了回滚，
+     * 不代表每一项都补偿成功（典型：原本已存在的凭据值 DSH 不可回读、无法自动恢复）。
+     * false 时失败项已并入 warnings，界面不得渲染成「整体成功回滚」。
+     * 缺省 undefined = 没触发回滚（既有布尔字段语义不变）。
+     */
+    rollbackFull?: boolean;
     /** 失败时移到 review 队列的项（ReviewQueueItem 形态供 UI 直接渲染） */
     review: import('./review-queue.ts').ReviewQueueItem[];
-    /** 来自 Importer.ImportResult 的 warnings；UI 可用于红条提示 */
+    /** 来自 Importer.ImportResult 的 warnings；UI 可用于红条提示（含回滚未完成项） */
     warnings: string[];
 }
 /** applyItems 报告（§3.4 ApplyItemsResponse 的服务端形态） */
@@ -198,6 +211,12 @@ export interface ApplyItemsReport {
     restoreId: string;
     /** 任一失败是否整体回滚 */
     rolledBack: boolean;
+    /**
+     * 整体回滚是否**完整**（诚实性，2026-10；与 ApplyReport.rollbackFull 同一语义）：
+     * rolledBack=true 只说明触发了整体回滚。false = 有改动没能恢复，失败项已并入 warnings。
+     * 缺省 undefined = 未触发回滚（既有布尔字段语义不变）。
+     */
+    rollbackFull?: boolean;
     warnings: string[];
     failed: {
         itemId: string;
@@ -246,7 +265,8 @@ export declare class SyncEngine {
     private readonly fsx;
     private readonly msg;
     private readonly sections;
-    private readonly includeOptInSections;
+    /** 本次显式放行的可选分区（构造期已归一：只可能是 OPT_IN_SYNC_SECTIONS 的注册项） */
+    private readonly optInSections;
     /** 远端快照保留策略提供者（缺省 = 保守的「保留最近 10 个」，与改造前逐字等价） */
     private readonly retentionPolicyProvider;
     /**
@@ -270,20 +290,22 @@ export declare class SyncEngine {
     private portableAdapters;
     /**
      * 拉取/合并侧的分区范围 id 集合：portable（受注入的同步范围约束）
-     * + 实例显式开启时的可选分区（sessions）。
+     * + **本次显式放行**的可选分区（optInSections）。
      *
      * 为什么单独一个助手：pull/preview/merge 都要把「远端快照里的哪些分区转进临时 ZIP」，
      * 三处必须同一口径；散开写 `portableAdapters().map(...)` 迟早漏掉一处（漏掉的表现是
      * 「推上去了、拉下来静默没有」）。
      */
     private pullSectionIds;
+    /** 本次显式放行的「可选分区」adapter（空集 = 一个都不放行；顺序跟随 adapters） */
+    private optInAdapters;
     /**
      * push 候选 adapter：
      * - sections 缺省/空 → 全部 portable（「默认/快速导出」模式）；
      * - sections 显式给出 → 只取 portable 且命中的（「高级/自定义导出」模式）；
      *   非 portable / 未知分区 → 警告跳过（安全约束 + 不静默，用户能看见自己勾了哪个无效项）；
-     * - 例外：OPT_IN_SYNC_SECTIONS（sessions）在调用方**显式提供选项**（sessions 参数）时
-     *   才作为候选取出 —— 它是 deviceSpecific，但用户主动勾选 + 数量上限后允许同步。
+     * - 例外：本次构造显式放行的可选分区（optInSections，见 SyncEngineOptions）作为候选取出。
+     *   缺省空集 → 与改造前逐字等价（可选分区一律不进同步通道）。
      */
     private pushTargets;
     /** 结构性断言：凭据/秘密分区绝不进入同步载荷（双保险，portable 过滤之上） */

package/lib/sync/sync-engine.js

@@ -37,11 +37,39 @@ import { DEFAULT_RETENTION_POLICY, selectPruneCandidatesByPolicy } from './reten
 import { hashSection, loadSyncState, saveSyncState } from './sync-state.js';
 import { isEncryptedSections } from './transport.js';
 import { msgOf, zhMsg } from '../core/messages.js';
+import { engineMsg } from './messages.js';
 import { DEFAULT_ANCESTOR_KEEP, pruneAncestors, tryLoadAncestor, writeAncestor } from './ancestor.js';
 import { merge as mergeSections } from './merge.js';
 import { createSnapshot, selectPruneCandidates } from '../core/backup.js';
 import { rollback } from '../core/rollback.js';
 import { FileSnapshotStore } from '../core/backup.js';
+/**
+ * 失败路径的**显式兜底回滚**：把 core 的 RollbackReport 翻成「是否完整 + 告警行」。
+ *
+ * 为什么不能像改造前那样 catch 后 noop：回滚抛错或部分补偿失败会被静默吞掉，而调用方
+ * 紧接着写 rolledBack: true，界面于是把「有改动没恢复」渲染成「已整体回滚」。
+ * 现在失败项逐条进 warnings，完整度经 rollbackFull 如实回传。
+ */
+async function rollbackForFailure(ctx, snapshot, store, adapters) {
+    try {
+        const report = await rollback({ ctx, snapshot, store, adapters });
+        return { full: report.full, warnings: rollbackFailureWarnings(report, msgOf(ctx)) };
+    }
+    catch (err) {
+        // 回滚自身抛错 = 无法证明任何一项已还原：如实报「不完整」并留痕，绝不 noop
+        return {
+            full: false,
+            warnings: [engineMsg('sync.rollbackProofFailed', { err: err instanceof Error ? err.message : String(err) })],
+        };
+    }
+}
+/** RollbackReport.failed → 可读告警行（带 manualHint：人工怎么补）。 */
+function rollbackFailureWarnings(report, msg = engineMsg) {
+    return report.failed.map((f) => {
+        const hint = f.manualHint !== undefined && f.manualHint !== '' ? msg('sync.rollbackManualHintParen', { hint: f.manualHint }) : '';
+        return msg('sync.rollbackIncomplete', { item: f.item, reason: f.reason, hint });
+    });
+}
 /** 同步通道结构性排除的敏感分区（即使 portable 判定有误也双保险拒绝；
  * 注：'credentials' 不是合法 SectionId——凭据状态分区为 credentialsStatus） */
 const FORBIDDEN_SECTIONS = ['credentialsStatus', 'secrets'];
@@ -72,7 +100,8 @@ export class SyncEngine {
     fsx;
     msg;
     sections;
-    includeOptInSections;
+    /** 本次显式放行的可选分区（构造期已归一：只可能是 OPT_IN_SYNC_SECTIONS 的注册项） */
+    optInSections;
     /** 远端快照保留策略提供者（缺省 = 保守的「保留最近 10 个」，与改造前逐字等价） */
     retentionPolicyProvider;
     /**
@@ -116,7 +145,8 @@ export class SyncEngine {
         this.fsx = opts.fsx ?? createSnapshotFs();
         this.msg = opts.msg ?? msgOf(opts.ctx);
         this.sections = opts.sections !== undefined && opts.sections.length > 0 ? [...opts.sections] : undefined;
-        this.includeOptInSections = opts.includeOptInSections === true;
+        // 归一：只有注册表声明的「可选分区」能被放行 —— 调用方传错 id 不会凭空解锁别的分区
+        this.optInSections = new Set((opts.optInSections ?? []).filter((id) => OPT_IN_SYNC_SECTIONS.includes(id)));
         this.retentionPolicyProvider = opts.retentionPolicy ?? (() => DEFAULT_RETENTION_POLICY);
     }
     /** 同步只做 portable 分区（deviceSpecific/platformSpecific 永不参与）。
@@ -131,7 +161,7 @@ export class SyncEngine {
     }
     /**
      * 拉取/合并侧的分区范围 id 集合：portable（受注入的同步范围约束）
-     * + 实例显式开启时的可选分区（sessions）。
+     * + **本次显式放行**的可选分区（optInSections）。
      *
      * 为什么单独一个助手：pull/preview/merge 都要把「远端快照里的哪些分区转进临时 ZIP」，
      * 三处必须同一口径；散开写 `portableAdapters().map(...)` 迟早漏掉一处（漏掉的表现是
@@ -139,33 +169,35 @@ export class SyncEngine {
      */
     pullSectionIds() {
         const ids = this.portableAdapters().map((a) => a.id);
-        if (this.includeOptInSections) {
-            for (const a of this.adapters) {
-                if (OPT_IN_SYNC_SECTIONS.includes(a.id))
-                    ids.push(a.id);
-            }
-        }
+        for (const a of this.optInAdapters())
+            ids.push(a.id);
         return new Set(ids);
     }
+    /** 本次显式放行的「可选分区」adapter（空集 = 一个都不放行；顺序跟随 adapters） */
+    optInAdapters() {
+        if (this.optInSections.size === 0)
+            return [];
+        return this.adapters.filter((a) => this.optInSections.has(a.id));
+    }
     /**
      * push 候选 adapter：
      * - sections 缺省/空 → 全部 portable（「默认/快速导出」模式）；
      * - sections 显式给出 → 只取 portable 且命中的（「高级/自定义导出」模式）；
      *   非 portable / 未知分区 → 警告跳过（安全约束 + 不静默，用户能看见自己勾了哪个无效项）；
-     * - 例外：OPT_IN_SYNC_SECTIONS（sessions）在调用方**显式提供选项**（sessions 参数）时
-     *   才作为候选取出 —— 它是 deviceSpecific，但用户主动勾选 + 数量上限后允许同步。
+     * - 例外：本次构造显式放行的可选分区（optInSections，见 SyncEngineOptions）作为候选取出。
+     *   缺省空集 → 与改造前逐字等价（可选分区一律不进同步通道）。
      */
-    pushTargets(sections, warnings, opts) {
+    pushTargets(sections, warnings) {
         const portable = this.portableAdapters();
+        const optIn = this.optInAdapters();
+        // 默认模式（未指定 sections）：portable 全量 + 本次显式放行的可选分区。
+        // 自动同步的 push() 不带 sections，可选分区能否上榜完全由构造期 optInSections 决定
+        // （scheduler 只传 'auto' 档 → sessions 永不悄悄上行）。
         if (sections === undefined || sections.length === 0)
-            return portable;
+            return [...portable, ...optIn];
         const byId = new Map(portable.map((a) => [a.id, a]));
-        if (opts?.sessions !== undefined) {
-            for (const a of this.adapters) {
-                if (OPT_IN_SYNC_SECTIONS.includes(a.id))
-                    byId.set(a.id, a);
-            }
-        }
+        for (const a of optIn)
+            byId.set(a.id, a);
         const out = [];
         for (const id of sections) {
             const adapter = byId.get(id);
@@ -328,7 +360,7 @@ export class SyncEngine {
             throw new Error(this.msg('sync.encryptRequiresPassword'));
         }
         const plainSections = {};
-        const targets = this.pushTargets(opts.sections, warnings, opts);
+        const targets = this.pushTargets(opts.sections, warnings);
         for (const adapter of targets) {
             let section;
             try {
@@ -440,7 +472,7 @@ export class SyncEngine {
                 credentialsIncluded = false; // 读不到 = 不会带凭据；预览如实显示 false
             }
         }
-        const targets = this.pushTargets(opts.sections, warnings, opts);
+        const targets = this.pushTargets(opts.sections, warnings);
         const plainSections = {};
         const counts = {};
         for (const adapter of targets) {
@@ -942,7 +974,7 @@ export class SyncEngine {
      */
     async applyMergePlan(apply, opts = {}) {
         if (!this.importer) {
-            throw new Error('applyMergePlan: SyncEngine 缺少 importer（需在 options 中注入）');
+            throw new Error(this.msg('sync.applyMergePlanNoImporter'));
         }
         const appliedIds = apply.autoApply.map((r) => r.id);
         // 0) 空 autoApply：无物可应用，直接短路（不构造 ZIP、不调 Importer）
@@ -1001,7 +1033,7 @@ export class SyncEngine {
                     restoreId: '',
                     rolledBack: false,
                     review: [],
-                    warnings: [`应用前快照失败：${backupErr instanceof Error ? backupErr.message : String(backupErr)}`],
+                    warnings: [this.msg('sync.preApplySnapshotFailed', { err: backupErr instanceof Error ? backupErr.message : String(backupErr) })],
                 };
             }
             // 3) 真正执行：Importer.executeImportPlan（rollbackOnError=true → 任一失败整体回滚）
@@ -1017,10 +1049,8 @@ export class SyncEngine {
                 snapshotBinding: opts.snapshotBinding,
             });
             if (!result.ok) {
-                try {
-                    await rollback({ ctx: this.ctx, snapshot, store, adapters: this.adapters });
-                }
-                catch { /* noop */ }
+                // 兜底回滚：把「是否完整」与失败项一并回传（绝不吞掉，也绝不把部分回滚说成整体回滚）
+                const rb = await rollbackForFailure(this.ctx, snapshot, store, this.adapters);
                 // 失败路径不再写 review-queue（§7.4）：历史 skipped/failed 标记由上层（路由/调度器）写入。
                 return {
                     ok: false,
@@ -1028,7 +1058,8 @@ export class SyncEngine {
                     restoreId: snapshot.id,
                     rolledBack: true,
                     review: [],
-                    warnings: result.warnings ?? [],
+                    warnings: [...(result.warnings ?? []), ...rb.warnings],
+                    rollbackFull: rb.full,
                 };
             }
             // 5) 全成功 → recordBaseline（更新祖先基线指向合并后的快照）
@@ -1070,7 +1101,7 @@ export class SyncEngine {
      */
     async applyItems(zipPath, subPlan, opts = {}) {
         if (!this.importer) {
-            throw new Error('applyItems: SyncEngine 缺少 importer（需在 options 中注入）');
+            throw new Error(this.msg('sync.applyItemsNoImporter'));
         }
         if (subPlan.items.length === 0) {
             return { ok: true, applied: [], restoreId: '', rolledBack: false, warnings: [], failed: [], ineffective: [], result: null };
@@ -1093,7 +1124,7 @@ export class SyncEngine {
                 applied: [],
                 restoreId: '',
                 rolledBack: false,
-                warnings: [`应用前快照失败：${backupErr instanceof Error ? backupErr.message : String(backupErr)}`],
+                warnings: [this.msg('sync.preApplySnapshotFailed', { err: backupErr instanceof Error ? backupErr.message : String(backupErr) })],
                 failed: subPlan.items.map((i) => ({ itemId: i.id })),
                 // 快照都没建成 ⇒ 一项都没执行，全部项都未生效（与 failed 同源，界面按硬失败处理）
                 ineffective: [],
@@ -1111,20 +1142,19 @@ export class SyncEngine {
             snapshotBinding: opts.snapshotBinding,
         });
         if (!result.ok) {
-            // executeImportPlan 已内部回滚（rollbackOnError）；这里再显式 rollback 兜底（幂等）
-            try {
-                await rollback({ ctx: this.ctx, snapshot, store, adapters: this.adapters });
-            }
-            catch { /* noop */ }
+            // executeImportPlan 已内部回滚（rollbackOnError）；这里再显式 rollback 兜底（幂等），
+            // 并把「是否完整」与失败项如实回传（改造前 noop + 硬编码 rolledBack:true 会掩盖半回滚）
+            const rb = await rollbackForFailure(this.ctx, snapshot, store, this.adapters);
             return {
                 ok: false,
                 applied: [],
                 restoreId: snapshot.id,
                 rolledBack: true,
-                warnings: result.warnings ?? [],
+                warnings: [...(result.warnings ?? []), ...rb.warnings],
                 failed: result.executed.filter((e) => e.status === 'failed').map((e) => ({ itemId: e.itemId, message: e.message })),
                 ineffective: result.ineffective ?? [],
                 result,
+                rollbackFull: rb.full,
             };
         }
         // 成功：recordBaseline 更新祖先基线（合并后的快照）
@@ -1170,7 +1200,7 @@ export class SyncEngine {
     async snapshotToZip(snapshot, portableIds) {
         // 防御：加密快照必须已由调用方解密（prepareSnapshot）；此处不处理密文载荷
         if (isEncryptedSections(snapshot.sections)) {
-            throw new Error('快照仍为加密载荷，无法转 ZIP（需先解密）');
+            throw new Error(this.msg('sync.snapshotStillEncrypted'));
         }
         const entries = [];
         const sectionFlags = {};

package/lib/sync/sync-history.js

@@ -12,6 +12,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
+import { engineMsg } from './messages.js';
 export const SYNC_HISTORY_FILE = 'sync-history.json';
 export const SYNC_HISTORY_SCHEMA_VERSION = 1;
 /** 自动同步历史保留上限 */
@@ -31,26 +32,26 @@ export async function readSyncHistory(dir) {
         parsed = parseJsonSafe(raw);
     }
     catch {
-        throw new Error(`${SYNC_HISTORY_FILE} 损坏：JSON 解析失败`);
+        throw new Error(engineMsg('sync.historyJsonParseFailed', { file: SYNC_HISTORY_FILE }));
     }
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error(`${SYNC_HISTORY_FILE} 损坏：必须是对象`);
+        throw new Error(engineMsg('sync.historyNotObject', { file: SYNC_HISTORY_FILE }));
     }
     const obj = parsed;
     if (obj['schemaVersion'] !== SYNC_HISTORY_SCHEMA_VERSION) {
-        throw new Error(`${SYNC_HISTORY_FILE} 损坏：schemaVersion 必须是 ${SYNC_HISTORY_SCHEMA_VERSION}`);
+        throw new Error(engineMsg('sync.historySchemaVersionMismatch', { file: SYNC_HISTORY_FILE, version: SYNC_HISTORY_SCHEMA_VERSION }));
     }
     if (!Array.isArray(obj['autosyncEntries'])) {
-        throw new Error(`${SYNC_HISTORY_FILE} 损坏：autosyncEntries 必须是数组`);
+        throw new Error(engineMsg('sync.historyEntriesNotArray', { file: SYNC_HISTORY_FILE }));
     }
     const entries = [];
     for (const it of obj['autosyncEntries']) {
         if (it === null || typeof it !== 'object' || Array.isArray(it)) {
-            throw new Error(`${SYNC_HISTORY_FILE} 损坏：每个 entry 必须是对象`);
+            throw new Error(engineMsg('sync.historyEntryNotObject', { file: SYNC_HISTORY_FILE }));
         }
         const e = it;
         if (typeof e['direction'] !== 'string' || typeof e['status'] !== 'string' || typeof e['createdAt'] !== 'string') {
-            throw new Error(`${SYNC_HISTORY_FILE} 损坏：entry 必须含字符串 direction/status/createdAt`);
+            throw new Error(engineMsg('sync.historyEntryFieldsMissing', { file: SYNC_HISTORY_FILE }));
         }
         entries.push(it);
     }

package/lib/sync/sync-selection.d.ts

@@ -33,13 +33,24 @@ export interface SyncSelection {
 /** 全通道选择视图（v2 文件直接读取；status 路由一次返回两个通道的选择）。 */
 export type SyncSelectionByChannel = Record<SyncTransportType, SyncSelection>;
 /**
- * 显式勾选才允许进入同步通道的「可选分区」（缺省全为 deviceSpecific，不在推荐分区里）。
+ * 显式勾选才允许进入同步通道的「可选分区」。
  *
- * 目前只有 sessions（历史会话）：内容敏感 + 设备相关，**绝不默认进入同步通道**，
- * 只有用户在同步分区弹窗里显式勾选才纳入；且必须带数量上限（见 DEFAULT_SYNC_SESSIONS_LIMIT），
- * 避免一次把整棵会话树推上远端。凭据 / 密钥分区不在此列（结构性拒绝，永不进同步）。
+ * **单一事实源 = 分区注册表**（\`SectionMeta.syncOptIn !== 'off'\`）。本文件此前手写
+ * \`['sessions']\`，与 \`section-registry.ts\` 的同名字段是**两份字面量、零护栏**
+ * （改一处漏一处不会报错）—— issue #78 收敛为派生视图，并在测试里钉住。
+ *
+ * 当前 = mcp（'auto'，命令 / 路径可能机器相关）+ sessions（'manual'，内容敏感 + 设备相关）。
+ * 凭据 / 密钥分区不在此列（结构性拒绝，永不进同步）。
  */
 export declare const OPT_IN_SYNC_SECTIONS: readonly SectionId[];
+/**
+ * 「可选分区」里**允许参与自动同步**的子集（当前 = mcp）。
+ *
+ * 手动与自动的差别只在这里：sessions 是内容隐私 / 设备相关，自动同步绝不带
+ * （「会话绝不悄悄下行」从注释变成可测断言）；mcp 只是命令 / 路径可能与目标机不同，
+ * 用户显式勾选后手动与自动都带。
+ */
+export declare const AUTO_SYNC_OPT_IN_SECTIONS: readonly SectionId[];
 /** sessions 分区默认同步「最新 N 个会话」（用户可在弹窗里改；0 = 不带）。 */
 export declare const DEFAULT_SYNC_SESSIONS_LIMIT = 5;
 /** sessionsLimit 归一化：非整数 / 缺失 / 负数 → 默认值；超大 → 上限钳制。 */