dsh-config-manager 0.1.71 → 0.1.73

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

@@ -59,6 +59,17 @@ const DEFAULT_AUTHOR = { name: 'DSH Config Sync', email: 'sync@dsh.local' };
 const DEFAULT_CREDENTIAL_USERNAME = 'oauth2';
 /** 快照 id 安全字符集：字母数字开头，仅 . _ -；防路径穿越与 commit message 注入 */
 const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/**
+ * SSH 主机密钥校验失败（issue #79）：git 只回一句 `Host key verification failed`，
+ * 用户拿不到任何可操作信息（要不要信任？怎么写 known_hosts？）。识别后换成可操作文案。
+ */
+const SSH_HOST_KEY_RE = /host key verification failed|remote host identification has changed|no matching host key/i;
+/**
+ * 工作副本与远端不是同一条历史（issue #79）：改成一个「另一个仓库」的地址后，
+ * `pull --ff-only` 会以 refusing to merge unrelated histories / Not possible to fast-forward 失败。
+ * 这类失败与网络无关，必须给「改回地址或重建工作副本」的出口，而不是只丢一句原始 stderr。
+ */
+const DIVERGED_HISTORY_RE = /refusing to merge unrelated histories|unrelated histories|not possible to fast-forward/i;
 const defaultExec = async (cmd, args, opts) => {
     try {
         const { stdout, stderr } = await execFileAsync(cmd, args, {
@@ -326,6 +337,12 @@ export class GitTransport {
         const fsx = createSnapshotFs();
         await fsx.mkdir(this.o.workDir); // 不存在则创建
         if (await fsx.exists(path.join(this.o.workDir, '.git'))) {
+            // issue #79：已有工作副本时**也必须**让 origin 跟随 repoUrl。
+            // 此前这里直接 `repoReady = true; return`，repoUrl 只在首次 clone 时被使用 ——
+            // 于是「改仓库地址」对已存在的工作副本完全无效：pull/push 全走旧 origin，
+            // 而失败面表现为旧地址的网络超时（真机：局域网地址 → Tailscale 地址后同步长期失败），
+            // 用户会误判成网络/凭据问题。
+            await this.reconcileOrigin();
             this.repoReady = true;
             return;
         }
@@ -346,6 +363,116 @@ export class GitTransport {
         await this.runGit(['config', 'user.email', this.o.author.email]);
         this.repoReady = true;
     }
+    /**
+     * 让工作副本的 origin 与配置的 repoUrl 保持一致（issue #79）。
+     *
+     * 幂等：地址已一致时**一条写命令都不发**（只读 get-url）。三条边界：
+     *  - 读不出 origin（无该 remote）→ `remote add origin`，否则 `push -u origin` 永远失败；
+     *  - 读得出但为空串 → 视为「读不到」，**不改写**（不拿不确定的读取结果去覆盖用户的仓库配置）；
+     *  - push URL 可被单独配置（`git remote set-url --push`）→ 不一致时一并跟随，否则推送仍走旧地址。
+     */
+    async reconcileOrigin() {
+        const current = await this.runGit(['remote', 'get-url', 'origin'], { allowNonZero: true });
+        const origin = current.code === 0 ? current.stdout.trim() : '';
+        if (current.code !== 0) {
+            await this.runGit(['remote', 'add', 'origin', this.o.repoUrl]);
+        }
+        else if (origin !== '' && origin !== this.o.repoUrl) {
+            await this.runGit(['remote', 'set-url', 'origin', this.o.repoUrl]);
+        }
+        const push = await this.runGit(['remote', 'get-url', '--push', 'origin'], { allowNonZero: true });
+        const pushUrl = push.code === 0 ? push.stdout.trim() : '';
+        if (pushUrl !== '' && pushUrl !== this.o.repoUrl) {
+            await this.runGit(['remote', 'set-url', '--push', 'origin', this.o.repoUrl]);
+        }
+    }
+    /**
+     * ssh 远端的主机提示（issue #79 主机密钥错误文案用）；非 ssh 或解析不出 → 空串。
+     * 只回传 host[:port]（不含用户名与仓库路径），地址由调用方经 mask() 处理。
+     */
+    sshHostHint() {
+        const url = this.o.repoUrl;
+        if (/^ssh:\/\//i.test(url)) {
+            try {
+                const u = new URL(url);
+                return u.port === '' ? u.hostname : `${u.hostname}:${u.port}`;
+            }
+            catch {
+                return '';
+            }
+        }
+        // scp 形态：git@host:path（可带端口需用 ssh:// 形态，这里只取主机）
+        const scp = /^[^@/]+@([^:/]+)(?::(\d+))?:/.exec(url);
+        if (scp === null)
+            return '';
+        const host = scp[1] ?? '';
+        const port = scp[2];
+        return port === undefined ? host : `${host}:${port}`;
+    }
+    /**
+     * 工作副本自检（issue #79，只读）：origin / push URL 是否已跟随 repoUrl。
+     *
+     * **默认只做 2 条本地只读命令**（get-url ×2，毫秒级）——它挂在 `GET /sync/status` 上，
+     * 每次打开面板都会跑；`rev-list`/`status` 在大工作副本（会话 blob 上千文件）上会明显变慢，
+     * 因此放进 `detail: true`（供「重建工作副本」前评估数据量等场景显式索取）。
+     */
+    async inspectWorkDir(opts = {}) {
+        const fsx = createSnapshotFs();
+        if (!(await fsx.exists(path.join(this.o.workDir, '.git')))) {
+            return { path: this.o.workDir, exists: false, origin: null, pushUrl: null, match: false, ahead: null, dirty: null };
+        }
+        const originRes = await this.runGit(['remote', 'get-url', 'origin'], { allowNonZero: true });
+        const origin = originRes.code === 0 ? originRes.stdout.trim() : '';
+        const pushRes = await this.runGit(['remote', 'get-url', '--push', 'origin'], { allowNonZero: true });
+        const pushRaw = pushRes.code === 0 ? pushRes.stdout.trim() : '';
+        let ahead = null;
+        let dirty = null;
+        if (opts.detail === true) {
+            // 未上行的本地提交：HEAD 可达、但任何远端跟踪引用都不可达的提交数（无 upstream 也能算）
+            const aheadRes = await this.runGit(['rev-list', '--count', 'HEAD', '--not', '--remotes'], { allowNonZero: true });
+            const parsed = aheadRes.code === 0 ? Number.parseInt(aheadRes.stdout.trim(), 10) : Number.NaN;
+            ahead = Number.isFinite(parsed) ? parsed : null;
+            const statusRes = await this.runGit(['status', '--porcelain'], { allowNonZero: true });
+            dirty = statusRes.code === 0 ? statusRes.stdout.trim() !== '' : null;
+        }
+        return {
+            path: this.o.workDir,
+            exists: true,
+            origin: origin === '' ? null : origin,
+            pushUrl: pushRaw === '' ? null : pushRaw,
+            // 读不出 origin（null）→ 不算 match（状态接口据此提示「工作副本地址未知」）
+            match: origin === this.o.repoUrl && (pushRaw === '' || pushRaw === this.o.repoUrl),
+            ahead,
+            dirty,
+        };
+    }
+    /**
+     * 重建工作副本（issue #79 的自救入口）：
+     *  - `relink`：只把 origin / push URL 重新指向 repoUrl（**非破坏性**：不碰工作树与本地提交）；
+     *  - `reclone`：删除工作副本目录后重新 clone（**丢弃未上行的本地提交**；调用方必须先让用户确认）。
+     *
+     * 安全边界：`reclone` 只在目录**确实是 git 工作副本**（有 .git）时才删；目录非空且无 .git
+     * 一律拒绝（与 ensureRepo 同一句 workDirNotRepo）—— 绝不删来路不明的目录。
+     */
+    async rebuildWorkDir(mode) {
+        this.repoReady = false;
+        if (mode === 'relink') {
+            await this.ensureRepo(); // .git 存在 → reconcileOrigin
+            return;
+        }
+        const fsx = createSnapshotFs();
+        await fsx.mkdir(this.o.workDir);
+        if (!(await fsx.exists(path.join(this.o.workDir, '.git')))) {
+            const entries = await fsx.readdir(this.o.workDir);
+            if (entries.length > 0) {
+                throw new GitTransportError(this.msg('sync.git.workDirNotRepo', { dir: this.o.workDir }), { kind: 'protocol', retryable: false });
+            }
+            await this.ensureRepo(); // 空目录 → 直接 clone
+            return;
+        }
+        await fs.rm(this.o.workDir, { recursive: true, force: true });
+        await this.ensureRepo();
+    }
     /**
      * pull --ff-only 同步远端；无本地提交（全新仓库）或无 upstream 时静默跳过。
      * opts.retryable=true（仅 list / download 等**幂等读**路径传）：瞬时网络故障走有限指数退避重试。
@@ -361,7 +488,15 @@ export class GitTransport {
                 return;
             if (/no tracking information/i.test(res.stderr))
                 return; // 无 upstream（初始状态）→ 跳过
-            throw new GitTransportError(this.msg('sync.git.pullFailed', { err: this.mask(res.stderr, await this.readTokenOnce()) }), classifyNetworkErrorText(res.stderr));
+            const combined = res.stderr + ' ' + res.stdout;
+            // issue #79：这两类失败与网络无关，必须给「改回地址 / 重建工作副本」的出口
+            if (SSH_HOST_KEY_RE.test(combined)) {
+                throw new GitTransportError(this.hostKeyMessage(), { kind: 'auth', retryable: false });
+            }
+            if (DIVERGED_HISTORY_RE.test(combined)) {
+                throw new GitTransportError(this.msg('sync.git.historyDiverged', { dir: this.o.workDir }), { kind: 'conflict', retryable: false });
+            }
+            throw new GitTransportError(this.msg('sync.git.pullFailed', { err: this.mask(res.stderr, await this.readTokenOnce()) }), classifyNetworkErrorText(combined));
         };
         if (opts.retryable === true)
             await withSyncRetry(attempt, this.o.retry);
@@ -396,8 +531,13 @@ export class GitTransport {
         try {
             const result = await this.o.exec(this.o.gitBin, [...extra, ...args], { cwd, timeoutMs: this.o.timeoutMs });
             if (result.code !== 0 && !opts.allowNonZero) {
+                const combined = result.stderr + ' ' + result.stdout;
                 // 统一分类（超时 / 网络 / 鉴权 / 5xx…）：上层可据 kind / retryable 分流，不必解析 message
-                const classified = classifyNetworkErrorText(result.stderr + ' ' + result.stdout);
+                const classified = classifyNetworkErrorText(combined);
+                // issue #79：SSH 主机密钥校验失败 → 换成「怎么信任该主机」的可操作说明（绝不自动信任）
+                if (SSH_HOST_KEY_RE.test(combined)) {
+                    throw new GitTransportError(this.hostKeyMessage(), { kind: 'auth', retryable: false });
+                }
                 // 推送 + 鉴权失败：git 原文只说「认证失败」——换成能照做的说明（令牌失效 / 无写权限 / 远端禁用了密码推送）
                 const message = opts.requirePushToken === true && classified.kind === 'auth'
                     ? this.msg('sync.git.pushAuthFailed', { err: this.mask(result.stderr, token) })
@@ -473,6 +613,16 @@ export class GitTransport {
         }
         return out;
     }
+    /**
+     * SSH 主机密钥失败的**可操作**文案（issue #79）。有 host 提示时带上 host[:port]；
+     * 解析不出主机（异常地址）走无主机变体，绝不把解析失败的地址硬塞进文案。
+     */
+    hostKeyMessage() {
+        const host = this.sshHostHint();
+        return host === ''
+            ? this.msg('sync.git.hostKeyUnverifiedNoHost')
+            : this.msg('sync.git.hostKeyUnverified', { host });
+    }
     blobsDir() {
         return path.join(this.o.workDir, BLOBS_REL);
     }

package/lib/sync/github-auth.js

@@ -24,6 +24,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { defaultFetcher } from '../utils/proxy.js';
+import { engineMsg } from './messages.js';
 /** GitHub device flow 第一步：请求设备码 */
 export const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code';
 /** GitHub device flow 第三步：轮询换取 access token */
@@ -51,7 +52,7 @@ export class GitHubAuthError extends Error {
 async function parseGitHubJson(response, context) {
     const text = await response.text();
     if (text.trim() === '') {
-        throw new GitHubAuthError(`${context}: GitHub 返回空响应（HTTP ${response.status}）`, 'empty_response', response.status);
+        throw new GitHubAuthError(engineMsg('sync.githubEmptyResponse', { context, status: response.status }), 'empty_response', response.status);
     }
     try {
         const parsed = JSON.parse(text);
@@ -61,7 +62,7 @@ async function parseGitHubJson(response, context) {
         return parsed;
     }
     catch {
-        throw new GitHubAuthError(`${context}: GitHub 返回了无法解析的响应（HTTP ${response.status}），请稍后重试`, 'invalid_json', response.status);
+        throw new GitHubAuthError(engineMsg('sync.githubInvalidJson', { context, status: response.status }), 'invalid_json', response.status);
     }
 }
 /**
@@ -79,7 +80,7 @@ export class GitHubAuthClient {
      */
     async startDeviceFlow(clientId, scope = GITHUB_DEVICE_FLOW_SCOPE) {
         if (typeof clientId !== 'string' || clientId === '') {
-            throw new GitHubAuthError('client_id 必须是非空字符串', 'invalid_client_id');
+            throw new GitHubAuthError(engineMsg('sync.githubClientIdRequired'), 'invalid_client_id');
         }
         const body = new URLSearchParams();
         body.set('client_id', clientId);
@@ -93,13 +94,13 @@ export class GitHubAuthClient {
             });
         }
         catch (err) {
-            throw new GitHubAuthError(`请求 GitHub 设备码失败：${err instanceof Error ? err.message : String(err)}`, 'network_error');
+            throw new GitHubAuthError(engineMsg('sync.githubDeviceCodeRequestFailed', { err: err instanceof Error ? err.message : String(err) }), 'network_error');
         }
-        const parsed = await parseGitHubJson(response, '请求设备码');
+        const parsed = await parseGitHubJson(response, engineMsg('sync.githubContextDeviceCode'));
         const ghError = parsed['error'];
         if (typeof ghError === 'string' && ghError !== '') {
             const desc = parsed['error_description'];
-            throw new GitHubAuthError(`GitHub 拒绝了设备码请求：${typeof desc === 'string' && desc !== '' ? desc : ghError}`, ghError, response.status);
+            throw new GitHubAuthError(engineMsg('sync.githubDeviceCodeDenied', { detail: typeof desc === 'string' && desc !== '' ? desc : ghError }), ghError, response.status);
         }
         const deviceCode = parsed['device_code'];
         const userCode = parsed['user_code'];
@@ -107,7 +108,7 @@ export class GitHubAuthClient {
         if (typeof deviceCode !== 'string' || deviceCode === ''
             || typeof userCode !== 'string' || userCode === ''
             || typeof verificationUri !== 'string' || verificationUri === '') {
-            throw new GitHubAuthError('GitHub 设备码响应缺少必要字段（device_code/user_code/verification_uri）', 'invalid_response', response.status);
+            throw new GitHubAuthError(engineMsg('sync.githubDeviceCodeFieldsMissing'), 'invalid_response', response.status);
         }
         const expiresIn = typeof parsed['expires_in'] === 'number' && Number.isFinite(parsed['expires_in'])
             ? Math.min(Math.max(Math.floor(parsed['expires_in']), 1), DEVICE_CODE_MAX_EXPIRES_IN)
@@ -139,9 +140,9 @@ export class GitHubAuthClient {
             });
         }
         catch (err) {
-            throw new GitHubAuthError(`交换 GitHub token 失败：${err instanceof Error ? err.message : String(err)}`, 'network_error');
+            throw new GitHubAuthError(engineMsg('sync.githubTokenExchangeFailed', { err: err instanceof Error ? err.message : String(err) }), 'network_error');
         }
-        const parsed = await parseGitHubJson(response, '交换 token');
+        const parsed = await parseGitHubJson(response, engineMsg('sync.githubContextTokenExchange'));
         const accessToken = parsed['access_token'];
         if (typeof accessToken === 'string' && accessToken !== '') {
             return { ok: true, accessToken };

package/lib/sync/layout.js

@@ -7,6 +7,7 @@
  * 核心逻辑经 SnapshotFs 注入（默认 node:fs/promises）。
  */
 import path from 'node:path';
+import { engineMsg } from './messages.js';
 import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 import { sha256Hex } from '../utils/hashing.js';
 import { filePrefixOf, jsonPathOf, SECTION_FILE_PREFIXES, SECTION_IDS, SECTION_JSON_PATHS, } from '../schema/section-registry.js';
@@ -101,18 +102,18 @@ export async function listSnapshotFiles(fsx, dir) {
 export async function writeSnapshotToDir(snapshot, dir, fsx = createSnapshotFs(), opts = {}) {
     // 加密快照不写散文件目录（本地不落盘：密文/明文都不落；远端已存密文）
     if (isEncryptedSections(snapshot.sections)) {
-        throw new Error('加密快照不写散文件目录（本地不落盘；请直接使用密文传输）');
+        throw new Error(engineMsg('sync.layoutEncryptedDirUnsupported'));
     }
     // issue #38：凭据载荷只随加密快照的密文单文件布局传输。散文件布局无法承载它，
     // 静默丢弃 = 「勾了导出密钥却什么也没导」，因此这里显式拒绝（调用方本不该走到这里）。
     if (snapshot.credentials !== undefined) {
-        throw new Error('凭据载荷只能随加密快照的密文单文件布局传输（散文件目录不落任何凭据）');
+        throw new Error(engineMsg('sync.layoutCredentialsNeedEncryptedLayout'));
     }
     const sectionHashes = {};
     for (const [id, data] of Object.entries(snapshot.sections)) {
         const sid = id;
         if (!LAYOUT_SECTION_IDS.includes(sid)) {
-            throw new Error(`分区 ${sid} 不在散文件布局支持范围（SECTION_JSON_PATHS / SECTION_FILE_PREFIXES）`);
+            throw new Error(engineMsg('sync.layoutSectionUnsupported', { section: sid }));
         }
         sectionHashes[sid] = hashSection(data);
     }
@@ -122,7 +123,7 @@ export async function writeSnapshotToDir(snapshot, dir, fsx = createSnapshotFs()
             continue;
         for (const file of data.files) {
             if (!isSafeRelPath(file.relativePath)) {
-                throw new Error(`非法文件相对路径: ${file.relativePath}（分区 ${sid}）`);
+                throw new Error(engineMsg('sync.layoutFileRelPathInvalid', { path: file.relativePath, section: sid }));
             }
         }
     }
@@ -177,24 +178,24 @@ export async function writeSnapshotToDir(snapshot, dir, fsx = createSnapshotFs()
 export async function readSnapshotFromDir(dir, fsx = createSnapshotFs(), opts = {}) {
     const manifestAbs = joinFs(dir, SNAPSHOT_MANIFEST_FILE);
     if (!(await fsx.exists(manifestAbs))) {
-        throw new Error(`快照目录缺少 ${SNAPSHOT_MANIFEST_FILE}: ${dir}`);
+        throw new Error(engineMsg('sync.layoutManifestMissing', { file: SNAPSHOT_MANIFEST_FILE, dir }));
     }
     const parsed = parseJsonSafe(Buffer.from(await fsx.readFile(manifestAbs)).toString('utf8'));
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('manifest.json 损坏：必须是对象');
+        throw new Error(engineMsg('sync.layoutManifestNotObject'));
     }
     const m = parsed;
     if (typeof m['id'] !== 'string' || typeof m['createdAt'] !== 'string'
         || m['manifest'] === null || typeof m['manifest'] !== 'object'
         || m['sectionHashes'] === null || typeof m['sectionHashes'] !== 'object') {
-        throw new Error('manifest.json 损坏：缺少 id/createdAt/manifest/sectionHashes');
+        throw new Error(engineMsg('sync.layoutManifestMissingFields'));
     }
     const manifest = parsed;
     const sections = {};
     const declared = Object.keys(manifest.sectionHashes);
     for (const sid of declared) {
         if (!LAYOUT_SECTION_IDS.includes(sid)) {
-            throw new Error(`manifest 声明了布局不支持的分区 ${sid}`);
+            throw new Error(engineMsg('sync.layoutManifestSectionUnsupported', { section: sid }));
         }
     }
     // JSON 分区
@@ -203,7 +204,7 @@ export async function readSnapshotFromDir(dir, fsx = createSnapshotFs(), opts =
             continue;
         const abs = joinFs(dir, rel);
         if (!(await fsx.exists(abs))) {
-            throw new Error(`快照缺少 JSON 分区文件 ${rel}（${sid}）`);
+            throw new Error(engineMsg('sync.layoutJsonSectionMissing', { path: rel, section: sid }));
         }
         sections[sid] = parseJsonSafe(Buffer.from(await fsx.readFile(abs)).toString('utf8'));
     }
@@ -216,10 +217,10 @@ export async function readSnapshotFromDir(dir, fsx = createSnapshotFs(), opts =
         if (await fsx.exists(refsAbs)) {
             const parsedRefs = parseJsonSafe(Buffer.from(await fsx.readFile(refsAbs)).toString('utf8'));
             if (!isBlobRefsSection(parsedRefs)) {
-                throw new Error(`外置引用文件形状非法: ${blobRefsFile(sid)}`);
+                throw new Error(engineMsg('sync.layoutBlobRefsInvalid', { file: blobRefsFile(sid) }));
             }
             if (opts.blobs === undefined) {
-                throw new Error(`快照的 ${sid} 分区是内容寻址外置形态，但当前通道未提供 blob 仓`);
+                throw new Error(engineMsg('sync.layoutBlobRefsNoSink', { section: sid }));
             }
             sections[sid] = await refsToSection(parsedRefs, opts.blobs);
             continue;
@@ -231,7 +232,7 @@ export async function readSnapshotFromDir(dir, fsx = createSnapshotFs(), opts =
                 sections[sid] = { version: 1, files: [] };
                 continue;
             }
-            throw new Error(`快照缺少文件分区目录 ${prefix}（${sid}）`);
+            throw new Error(engineMsg('sync.layoutFileSectionDirMissing', { prefix, section: sid }));
         }
         const rels = await listSnapshotFiles(fsx, baseAbs);
         const files = [];

package/lib/sync/messages.d.ts

@@ -0,0 +1,63 @@
+import type { MsgFunc } from '../core/msg-types.ts';
+export declare const zh: {
+    readonly 'sync.ancestorSnapshotIdRequired': 'loadAncestor: snapshotId 不能为空';
+    readonly 'sync.snapshotSectionsNotObject': '快照 sections 必须是对象';
+    readonly 'sync.snapshotJsonInvalid': '快照 JSON 形状非法（缺少 id/createdAt/manifest/sections）';
+    readonly 'sync.snapshotStillEncrypted': '快照仍为加密载荷，无法转 ZIP（需先解密）';
+    readonly 'sync.encryptPasswordRequired': '加密密码不能为空';
+    readonly 'sync.decryptPasswordRequired': '解密密码不能为空';
+    readonly 'sync.encryptedContentInvalid': '加密快照内容损坏：解密后不是有效的分区对象';
+    readonly 'sync.layoutEncryptedDirUnsupported': '加密快照不写散文件目录（本地不落盘；请直接使用密文传输）';
+    readonly 'sync.layoutCredentialsNeedEncryptedLayout': '凭据载荷只能随加密快照的密文单文件布局传输（散文件目录不落任何凭据）';
+    readonly 'sync.layoutSectionUnsupported': '分区 {section} 不在散文件布局支持范围（SECTION_JSON_PATHS / SECTION_FILE_PREFIXES）';
+    readonly 'sync.layoutFileRelPathInvalid': '非法文件相对路径: {path}（分区 {section}）';
+    readonly 'sync.layoutManifestMissing': '快照目录缺少 {file}: {dir}';
+    readonly 'sync.layoutManifestNotObject': 'manifest.json 损坏：必须是对象';
+    readonly 'sync.layoutManifestMissingFields': 'manifest.json 损坏：缺少 id/createdAt/manifest/sectionHashes';
+    readonly 'sync.layoutManifestSectionUnsupported': 'manifest 声明了布局不支持的分区 {section}';
+    readonly 'sync.layoutJsonSectionMissing': '快照缺少 JSON 分区文件 {path}（{section}）';
+    readonly 'sync.layoutBlobRefsInvalid': '外置引用文件形状非法: {file}';
+    readonly 'sync.layoutBlobRefsNoSink': '快照的 {section} 分区是内容寻址外置形态，但当前通道未提供 blob 仓';
+    readonly 'sync.layoutFileSectionDirMissing': '快照缺少文件分区目录 {prefix}（{section}）';
+    readonly 'sync.blobMissing': '内容的 blob 缺失（{hash}，{path}）：远端仓不完整，拒绝降级为空分区';
+    readonly 'sync.webdav.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}';
+    readonly 'sync.reviewQueueNotObject': 'sync-review-queue.json 损坏：必须是对象';
+    readonly 'sync.reviewQueueItemsNotArray': 'sync-review-queue.json 损坏：items 必须是数组';
+    readonly 'sync.reviewQueueItemNotObject': 'sync-review-queue.json 损坏：每个 item 必须是对象';
+    readonly 'sync.reviewQueueItemFieldsMissing': 'sync-review-queue.json 损坏：item 必须含字符串 id/sectionId/kind/description';
+    readonly 'sync.reviewQueueItemNotFound': 'resolveItem: 未找到 itemId {id}';
+    readonly 'sync.historyJsonParseFailed': '{file} 损坏：JSON 解析失败';
+    readonly 'sync.historyNotObject': '{file} 损坏：必须是对象';
+    readonly 'sync.historySchemaVersionMismatch': '{file} 损坏：schemaVersion 必须是 {version}';
+    readonly 'sync.historyEntriesNotArray': '{file} 损坏：autosyncEntries 必须是数组';
+    readonly 'sync.historyEntryNotObject': '{file} 损坏：每个 entry 必须是对象';
+    readonly 'sync.historyEntryFieldsMissing': '{file} 损坏：entry 必须含字符串 direction/status/createdAt';
+    readonly 'sync.githubEmptyResponse': '{context}: GitHub 返回空响应（HTTP {status}）';
+    readonly 'sync.githubInvalidJson': '{context}: GitHub 返回了无法解析的响应（HTTP {status}），请稍后重试';
+    readonly 'sync.githubClientIdRequired': 'client_id 必须是非空字符串';
+    readonly 'sync.githubDeviceCodeRequestFailed': '请求 GitHub 设备码失败：{err}';
+    readonly 'sync.githubDeviceCodeDenied': 'GitHub 拒绝了设备码请求：{detail}';
+    readonly 'sync.githubDeviceCodeFieldsMissing': 'GitHub 设备码响应缺少必要字段（device_code/user_code/verification_uri）';
+    readonly 'sync.githubTokenExchangeFailed': '交换 GitHub token 失败：{err}';
+    readonly 'sync.githubContextDeviceCode': '请求设备码';
+    readonly 'sync.githubContextTokenExchange': '交换 token';
+    readonly 'sync.rollbackProofFailed': '回滚失败（未能证明已恢复）：{err}';
+    readonly 'sync.rollbackManualHintParen': '（{hint}）';
+    readonly 'sync.rollbackIncomplete': '回滚未完成：{item} —— {reason}{hint}';
+    readonly 'sync.applyMergePlanNoImporter': 'applyMergePlan: SyncEngine 缺少 importer（需在 options 中注入）';
+    readonly 'sync.applyItemsNoImporter': 'applyItems: SyncEngine 缺少 importer（需在 options 中注入）';
+    readonly 'sync.preApplySnapshotFailed': '应用前快照失败：{err}';
+    readonly 'sync.autosyncApplyMergeFailed': 'applyMergePlan 执行失败';
+    readonly 'sync.autosyncPushFailed': 'push 失败';
+    readonly 'sync.autosyncConsecutiveFailureNotified': '连续失败 {count} 次，已通知';
+    readonly 'sync.backupExportsDirUnreadable': '导出目录读不出来（{code}）：{dir}';
+    readonly 'sync.backupFileNameInvalid': '非法备份文件名: {name}';
+    readonly 'sync.backupTriggerManual': '手动备份';
+    readonly 'sync.backupTriggerScheduled': '定时备份';
+    readonly 'sync.backupHistoryDone': '{trigger}完成：{zip}';
+    readonly 'sync.backupHistorySkipped': '{trigger}跳过：{reason}';
+    readonly 'sync.backupHistoryFailed': '{trigger}失败';
+};
+export declare const en: Record<keyof typeof zh, string>;
+/** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */
+export declare const engineMsg: MsgFunc;

package/lib/sync/messages.js

@@ -0,0 +1,149 @@
+/**
+ * 同步域（src/sync/**）的追加消息目录（zh 源 / en 镜像），归 t6 作用域。
+ *
+ * 为什么不写进 \`src/core/messages.ts\`：该文件不在本作用域的 inScope 内，且既有 372 键有冻结指纹
+ * （改既有键即红灯）。本模块经 \`registerMessageCatalog\` 注册一本**追加目录**：engineMsg / makeMsg 的查找
+ * 顺序是「既有目录 → en 下回退既有 zh → 注册目录 → 键名」，因此本域新键**只在既有目录未命中时生效**，
+ * 不可能遮蔽 core 的既有键（含 sync.git.* / sync.webdav.* 的既有键）。
+ *
+ * 纪律：
+ *  - zh 值 = 改动前的既有中文文案**逐字原样**（只把字面量搬进目录，拼接顺序/空格/全角标点不变）；
+ *  - en 为 \`Record<keyof typeof zh, string>\` —— 缺键/多键即编译错误；
+ *  - 本域消费面是注入的 \`MsgFunc\`（ctx.msg / sync-engine 的 this.msg）与 \`engineMsg\`，两者都查注册目录；
+ *  - **导入本模块即完成注册**：凡引用本域键的模块都要 import 本模块（或 import 它导出的 engineMsg）。
+ *  - 例外（不得改动）：\`src/sync/s3/messages.ts\` 与 \`src/sync/gist/messages.ts\` 是通道**本地**目录，
+ *    它们的键经 \`composeMsg(host, local)\` 解析（t79/t90 的既有护栏断言 core 直查必然回退键名 ⇒
+ *    那两本目录**不得**注册进这里，否则既有回归护栏的前提被打破）。s3/gist 的新键一律落进各自本地目录。
+ */
+import { engineMsg as engineMsgOf, registerMessageCatalog } from '../core/engine-locale.js';
+export const zh = {
+    // ---------- 快照 / 祖先 ----------
+    'sync.ancestorSnapshotIdRequired': 'loadAncestor: snapshotId 不能为空',
+    'sync.snapshotSectionsNotObject': '快照 sections 必须是对象',
+    'sync.snapshotJsonInvalid': '快照 JSON 形状非法（缺少 id/createdAt/manifest/sections）',
+    'sync.snapshotStillEncrypted': '快照仍为加密载荷，无法转 ZIP（需先解密）',
+    'sync.encryptPasswordRequired': '加密密码不能为空',
+    'sync.decryptPasswordRequired': '解密密码不能为空',
+    'sync.encryptedContentInvalid': '加密快照内容损坏：解密后不是有效的分区对象',
+    // ---------- 散文件布局 ----------
+    'sync.layoutEncryptedDirUnsupported': '加密快照不写散文件目录（本地不落盘；请直接使用密文传输）',
+    'sync.layoutCredentialsNeedEncryptedLayout': '凭据载荷只能随加密快照的密文单文件布局传输（散文件目录不落任何凭据）',
+    'sync.layoutSectionUnsupported': '分区 {section} 不在散文件布局支持范围（SECTION_JSON_PATHS / SECTION_FILE_PREFIXES）',
+    'sync.layoutFileRelPathInvalid': '非法文件相对路径: {path}（分区 {section}）',
+    'sync.layoutManifestMissing': '快照目录缺少 {file}: {dir}',
+    'sync.layoutManifestNotObject': 'manifest.json 损坏：必须是对象',
+    'sync.layoutManifestMissingFields': 'manifest.json 损坏：缺少 id/createdAt/manifest/sectionHashes',
+    'sync.layoutManifestSectionUnsupported': 'manifest 声明了布局不支持的分区 {section}',
+    'sync.layoutJsonSectionMissing': '快照缺少 JSON 分区文件 {path}（{section}）',
+    'sync.layoutBlobRefsInvalid': '外置引用文件形状非法: {file}',
+    'sync.layoutBlobRefsNoSink': '快照的 {section} 分区是内容寻址外置形态，但当前通道未提供 blob 仓',
+    'sync.layoutFileSectionDirMissing': '快照缺少文件分区目录 {prefix}（{section}）',
+    // ---------- 内容寻址 blob 仓 ----------
+    'sync.blobMissing': '内容的 blob 缺失（{hash}，{path}）：远端仓不完整，拒绝降级为空分区',
+    'sync.webdav.blobHashInvalid': '内容哈希形状非法，拒绝写入 blob 仓: {hash}',
+    // ---------- 审查队列 ----------
+    'sync.reviewQueueNotObject': 'sync-review-queue.json 损坏：必须是对象',
+    'sync.reviewQueueItemsNotArray': 'sync-review-queue.json 损坏：items 必须是数组',
+    'sync.reviewQueueItemNotObject': 'sync-review-queue.json 损坏：每个 item 必须是对象',
+    'sync.reviewQueueItemFieldsMissing': 'sync-review-queue.json 损坏：item 必须含字符串 id/sectionId/kind/description',
+    'sync.reviewQueueItemNotFound': 'resolveItem: 未找到 itemId {id}',
+    // ---------- 同步历史 ----------
+    'sync.historyJsonParseFailed': '{file} 损坏：JSON 解析失败',
+    'sync.historyNotObject': '{file} 损坏：必须是对象',
+    'sync.historySchemaVersionMismatch': '{file} 损坏：schemaVersion 必须是 {version}',
+    'sync.historyEntriesNotArray': '{file} 损坏：autosyncEntries 必须是数组',
+    'sync.historyEntryNotObject': '{file} 损坏：每个 entry 必须是对象',
+    'sync.historyEntryFieldsMissing': '{file} 损坏：entry 必须含字符串 direction/status/createdAt',
+    // ---------- GitHub 设备码登录 ----------
+    'sync.githubEmptyResponse': '{context}: GitHub 返回空响应（HTTP {status}）',
+    'sync.githubInvalidJson': '{context}: GitHub 返回了无法解析的响应（HTTP {status}），请稍后重试',
+    'sync.githubClientIdRequired': 'client_id 必须是非空字符串',
+    'sync.githubDeviceCodeRequestFailed': '请求 GitHub 设备码失败：{err}',
+    'sync.githubDeviceCodeDenied': 'GitHub 拒绝了设备码请求：{detail}',
+    'sync.githubDeviceCodeFieldsMissing': 'GitHub 设备码响应缺少必要字段（device_code/user_code/verification_uri）',
+    'sync.githubTokenExchangeFailed': '交换 GitHub token 失败：{err}',
+    'sync.githubContextDeviceCode': '请求设备码',
+    'sync.githubContextTokenExchange': '交换 token',
+    // ---------- 回滚 / 应用 ----------
+    'sync.rollbackProofFailed': '回滚失败（未能证明已恢复）：{err}',
+    'sync.rollbackManualHintParen': '（{hint}）',
+    'sync.rollbackIncomplete': '回滚未完成：{item} —— {reason}{hint}',
+    'sync.applyMergePlanNoImporter': 'applyMergePlan: SyncEngine 缺少 importer（需在 options 中注入）',
+    'sync.applyItemsNoImporter': 'applyItems: SyncEngine 缺少 importer（需在 options 中注入）',
+    'sync.preApplySnapshotFailed': '应用前快照失败：{err}',
+    // ---------- 自动同步 ----------
+    'sync.autosyncApplyMergeFailed': 'applyMergePlan 执行失败',
+    'sync.autosyncPushFailed': 'push 失败',
+    'sync.autosyncConsecutiveFailureNotified': '连续失败 {count} 次，已通知',
+    // ---------- 备份产物 / 调度 ----------
+    'sync.backupExportsDirUnreadable': '导出目录读不出来（{code}）：{dir}',
+    'sync.backupFileNameInvalid': '非法备份文件名: {name}',
+    'sync.backupTriggerManual': '手动备份',
+    'sync.backupTriggerScheduled': '定时备份',
+    'sync.backupHistoryDone': '{trigger}完成：{zip}',
+    'sync.backupHistorySkipped': '{trigger}跳过：{reason}',
+    'sync.backupHistoryFailed': '{trigger}失败',
+};
+export const en = {
+    'sync.ancestorSnapshotIdRequired': 'loadAncestor: snapshotId must not be empty',
+    'sync.snapshotSectionsNotObject': 'Snapshot sections must be an object',
+    'sync.snapshotJsonInvalid': 'Malformed snapshot JSON (missing id/createdAt/manifest/sections)',
+    'sync.snapshotStillEncrypted': 'The snapshot is still an encrypted payload and cannot be converted to ZIP (decrypt it first)',
+    'sync.encryptPasswordRequired': 'The encryption password must not be empty',
+    'sync.decryptPasswordRequired': 'The decryption password must not be empty',
+    'sync.encryptedContentInvalid': 'The encrypted snapshot is corrupt: after decryption it is not a valid sections object',
+    'sync.layoutEncryptedDirUnsupported': 'Encrypted snapshots are not written as a loose-file directory (nothing is stored locally; transfer the ciphertext instead)',
+    'sync.layoutCredentialsNeedEncryptedLayout': 'Credential payloads can only travel inside the single ciphertext file of an encrypted snapshot (the loose-file layout stores no credentials)',
+    'sync.layoutSectionUnsupported': 'Section {section} is outside the loose-file layout support range (SECTION_JSON_PATHS / SECTION_FILE_PREFIXES)',
+    'sync.layoutFileRelPathInvalid': 'Invalid relative file path: {path} (section {section})',
+    'sync.layoutManifestMissing': 'Snapshot directory is missing {file}: {dir}',
+    'sync.layoutManifestNotObject': 'manifest.json is corrupt: must be an object',
+    'sync.layoutManifestMissingFields': 'manifest.json is corrupt: missing id/createdAt/manifest/sectionHashes',
+    'sync.layoutManifestSectionUnsupported': 'The manifest declares section {section}, which the layout does not support',
+    'sync.layoutJsonSectionMissing': 'Snapshot is missing the JSON section file {path} ({section})',
+    'sync.layoutBlobRefsInvalid': 'Malformed external reference file: {file}',
+    'sync.layoutBlobRefsNoSink': 'Section {section} of the snapshot uses content-addressed external form, but the current channel provides no blob store',
+    'sync.layoutFileSectionDirMissing': 'Snapshot is missing the file section directory {prefix} ({section})',
+    'sync.blobMissing': 'The blob for {path} is missing ({hash}): the remote store is incomplete, refusing to degrade to an empty section',
+    'sync.webdav.blobHashInvalid': 'Malformed content hash; refusing to write to the blob store: {hash}',
+    'sync.reviewQueueNotObject': 'sync-review-queue.json is corrupt: must be an object',
+    'sync.reviewQueueItemsNotArray': 'sync-review-queue.json is corrupt: items must be an array',
+    'sync.reviewQueueItemNotObject': 'sync-review-queue.json is corrupt: every item must be an object',
+    'sync.reviewQueueItemFieldsMissing': 'sync-review-queue.json is corrupt: an item must contain the strings id/sectionId/kind/description',
+    'sync.reviewQueueItemNotFound': 'resolveItem: no item found for itemId {id}',
+    'sync.historyJsonParseFailed': '{file} is corrupt: JSON parsing failed',
+    'sync.historyNotObject': '{file} is corrupt: must be an object',
+    'sync.historySchemaVersionMismatch': '{file} is corrupt: schemaVersion must be {version}',
+    'sync.historyEntriesNotArray': '{file} is corrupt: autosyncEntries must be an array',
+    'sync.historyEntryNotObject': '{file} is corrupt: every entry must be an object',
+    'sync.historyEntryFieldsMissing': '{file} is corrupt: an entry must contain the strings direction/status/createdAt',
+    'sync.githubEmptyResponse': '{context}: GitHub returned an empty response (HTTP {status})',
+    'sync.githubInvalidJson': '{context}: GitHub returned an unparsable response (HTTP {status}), please retry later',
+    'sync.githubClientIdRequired': 'client_id must be a non-empty string',
+    'sync.githubDeviceCodeRequestFailed': 'Failed to request the GitHub device code: {err}',
+    'sync.githubDeviceCodeDenied': 'GitHub rejected the device code request: {detail}',
+    'sync.githubDeviceCodeFieldsMissing': 'The GitHub device code response is missing required fields (device_code/user_code/verification_uri)',
+    'sync.githubTokenExchangeFailed': 'Failed to exchange the GitHub token: {err}',
+    'sync.githubContextDeviceCode': 'device code request',
+    'sync.githubContextTokenExchange': 'token exchange',
+    'sync.rollbackProofFailed': 'Rollback failed (could not prove anything was restored): {err}',
+    'sync.rollbackManualHintParen': ' ({hint})',
+    'sync.rollbackIncomplete': 'Rollback incomplete: {item} — {reason}{hint}',
+    'sync.applyMergePlanNoImporter': 'applyMergePlan: SyncEngine is missing the importer (must be injected via options)',
+    'sync.applyItemsNoImporter': 'applyItems: SyncEngine is missing the importer (must be injected via options)',
+    'sync.preApplySnapshotFailed': 'Pre-apply snapshot failed: {err}',
+    'sync.autosyncApplyMergeFailed': 'applyMergePlan failed',
+    'sync.autosyncPushFailed': 'push failed',
+    'sync.autosyncConsecutiveFailureNotified': 'Failed {count} times in a row; notification sent',
+    'sync.backupExportsDirUnreadable': 'Cannot read the export directory ({code}): {dir}',
+    'sync.backupFileNameInvalid': 'Invalid backup file name: {name}',
+    'sync.backupTriggerManual': 'Manual backup',
+    'sync.backupTriggerScheduled': 'Scheduled backup',
+    'sync.backupHistoryDone': '{trigger} finished: {zip}',
+    'sync.backupHistorySkipped': '{trigger} skipped: {reason}',
+    'sync.backupHistoryFailed': '{trigger} failed',
+};
+registerMessageCatalog({ id: 'sync-domain', zh, en });
+/** 本域活翻译器（与 core 的 engineMsg 同一实现；导入本模块即完成目录注册）。 */
+export const engineMsg = engineMsgOf;
+//# sourceMappingURL=messages.js.map

package/lib/sync/review-queue.js

@@ -16,6 +16,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 import { atomicWriteFile } from '../utils/atomic-write.js';
+import { engineMsg } from './messages.js';
 export const REVIEW_QUEUE_FILE = 'sync-review-queue.json';
 export const EMPTY_REVIEW_QUEUE = { items: [], updatedAt: '' };
 /** 读取待审队列；文件不存在 → 返回空队列；损坏 JSON 抛错。 */
@@ -25,21 +26,21 @@ export async function readReviewQueue(stateDir, fsx = fs) {
         const raw = await fsx.readFile(file, 'utf8');
         const parsed = parseJsonSafe(raw);
         if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-            throw new Error('sync-review-queue.json 损坏：必须是对象');
+            throw new Error(engineMsg('sync.reviewQueueNotObject'));
         }
         const obj = parsed;
         if (!Array.isArray(obj['items'])) {
-            throw new Error('sync-review-queue.json 损坏：items 必须是数组');
+            throw new Error(engineMsg('sync.reviewQueueItemsNotArray'));
         }
         const items = [];
         for (const it of obj['items']) {
             if (it === null || typeof it !== 'object' || Array.isArray(it)) {
-                throw new Error('sync-review-queue.json 损坏：每个 item 必须是对象');
+                throw new Error(engineMsg('sync.reviewQueueItemNotObject'));
             }
             const i = it;
             if (typeof i['id'] !== 'string' || typeof i['sectionId'] !== 'string'
                 || typeof i['kind'] !== 'string' || typeof i['description'] !== 'string') {
-                throw new Error('sync-review-queue.json 损坏：item 必须含字符串 id/sectionId/kind/description');
+                throw new Error(engineMsg('sync.reviewQueueItemFieldsMissing'));
             }
             items.push(i);
         }
@@ -94,7 +95,7 @@ export async function resolveItem(stateDir, itemId, decision, now = () => new Da
     const current = await readReviewQueue(stateDir, fsx);
     const idx = current.items.findIndex((i) => i.id === itemId);
     if (idx === -1)
-        throw new Error(`resolveItem: 未找到 itemId ${itemId}`);
+        throw new Error(engineMsg('sync.reviewQueueItemNotFound', { id: itemId }));
     current.items[idx] = { ...current.items[idx], decision, decidedAt: now().toISOString() };
     current.updatedAt = now().toISOString();
     await writeReviewQueue(stateDir, current, fsx);