dsh-config-manager 0.1.78 → 0.1.80

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

@@ -40,3 +40,14 @@ export interface SyncHistoryFile {
 export declare function readSyncHistory(dir: string): Promise<SyncHistoryFile>;
 /** 追加一条自动同步执行记录（升序），裁剪到 AUTOSYNC_HISTORY_KEEP 条，原子写。 */
 export declare function appendAutosyncEntry(dir: string, entry: AutosyncHistoryEntry, now?: () => Date): Promise<void>;
+/**
+ * 给指定 createdAt 的自动同步记录补 notifiedAt 并落盘（issue #105）。
+ *
+ * 为什么不再借道 autosync-config：此前「连续失败 ≥ 3」的通知文案被写进 lastRunMessage，
+ * 与「本轮错误原文」抢同一个字段 —— 界面据此渲染出与真实状态无关的通知文案。
+ * 通知的持久痕迹只留历史 entry 的 notifiedAt；未命中记录返回 false（不写文件）。
+ */
+export declare function markAutosyncNotified(dir: string, createdAt: string, notifiedAt: string, opts?: {
+    now?: () => Date;
+    readHistory?: (dir: string) => Promise<SyncHistoryFile>;
+}): Promise<boolean>;

package/lib/sync/sync-history.js

@@ -75,4 +75,24 @@ export async function appendAutosyncEntry(dir, entry, now = () => new Date()) {
     const data = stringifyJsonSafe(current, { space: 2 });
     await atomicWriteFile(target, data, { mode: 0o600 });
 }
+/**
+ * 给指定 createdAt 的自动同步记录补 notifiedAt 并落盘（issue #105）。
+ *
+ * 为什么不再借道 autosync-config：此前「连续失败 ≥ 3」的通知文案被写进 lastRunMessage，
+ * 与「本轮错误原文」抢同一个字段 —— 界面据此渲染出与真实状态无关的通知文案。
+ * 通知的持久痕迹只留历史 entry 的 notifiedAt；未命中记录返回 false（不写文件）。
+ */
+export async function markAutosyncNotified(dir, createdAt, notifiedAt, opts = {}) {
+    const readHistory = opts.readHistory ?? readSyncHistory;
+    const current = await readHistory(dir);
+    const entry = current.autosyncEntries.find((e) => e.createdAt === createdAt);
+    if (entry === undefined)
+        return false;
+    entry.notifiedAt = notifiedAt;
+    current.updatedAt = (opts.now ?? (() => new Date()))().toISOString();
+    await fs.mkdir(dir, { recursive: true });
+    const target = path.join(dir, SYNC_HISTORY_FILE);
+    await atomicWriteFile(target, stringifyJsonSafe(current, { space: 2 }), { mode: 0o600 });
+    return true;
+}
 //# sourceMappingURL=sync-history.js.map

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

@@ -1,6 +1,7 @@
 import type { MsgFunc } from '../core/messages.ts';
 import type { SectionData, SectionId } from '../schema/types.ts';
 import type { SnapshotFs } from './fs.ts';
+import './messages.ts';
 export declare const SYNC_STATE_SCHEMA_VERSION = 3;
 /**
  * 历史可读取版本（均在内存中迁移到当前版本，不就地改写磁盘）：
@@ -16,6 +17,24 @@ export interface SyncSectionState {
     hash: string;
     updatedAt: string;
 }
+/**
+ * 待裁决的合并状态（基线纪律，2026-10）。
+ *
+ * 非空 = 上一次三方合并**仍有未裁决的冲突**，因此 lastSnapshotId 刻意**不推进**：
+ * 远端的最新快照下一轮仍会被当作「比基线新」而重新合并，冲突因此重新出现，直到用户裁决完。
+ * 若在冲突未裁决时就推进基线，冲突内容会在下一轮静默消失（远端那一版改动永远不再被讨论）。
+ *
+ * 纯可选字段：**不提升 SYNC_STATE_SCHEMA_VERSION**（旧文件缺该字段 → 读取形状逐键不变；
+ * 旧版本代码读到新文件也只是忽略它）。
+ */
+export interface PendingMerge {
+    /** 冲突所针对的**远端**快照 id（基线指针此刻仍停在更早的那一个）。 */
+    remoteSnapshotId: string;
+    /** 仍未裁决的分区 id（非空；空 = 没有待裁决内容，调用方应清除该字段）。 */
+    sections: SectionId[];
+    /** 该待裁决状态**首次**出现的时刻（ISO-8601 UTC；跨轮保留首次时间，便于界面讲「挂了多久」）。 */
+    since: string;
+}
 /** sync-state.json 结构 */
 export interface SyncState {
     schemaVersion: number;
@@ -48,6 +67,19 @@ export interface SyncState {
      * 本机若又出现该会话的实体，对应墓碑会被撤销（有实体 = 没删）。
      */
     deletedSessions?: string[];
+    /**
+     * cloud-sync 借鉴项 ⑥：本设备的**稳定**同步身份（首次推送时生成并持久化）。
+     *
+     * deviceId = 随机 UUID（换主机名/改机器名都不变，历史列表据此认出「同一台设备」）；
+     * deviceName = 人类可读名（缺省取主机名）。缺省 = 旧文件 / 从未推送（不猜）。
+     */
+    deviceId?: string;
+    deviceName?: string;
+    /**
+     * 基线纪律（2026-10）：未裁决冲突记录。非空 = 基线指针**刻意停在旧值**，
+     * 让冲突在下一轮重新出现（详见 PendingMerge）。
+     */
+    pendingMerge?: PendingMerge;
 }
 /**
  * 分区内容 hash：
@@ -60,5 +92,16 @@ export declare function hashSection(data: SectionData): string;
  * 旧版本文件（v1/v2）→ 在内存中迁移到当前版本（见 SYNC_STATE_SUPPORTED_VERSIONS），
  * 不在磁盘上就地升级（首次 saveSyncState 时才写回新版本）。 */
 export declare function loadSyncState(dir: string, fsx?: SnapshotFs, msg?: MsgFunc): Promise<SyncState>;
+/**
+ * 解析（必要时生成并持久化）本设备的同步身份（cloud-sync 借鉴项 ⑥）。
+ *
+ * - deviceId 一旦生成就持久化在 sync-state.json → 历史列表能认出「同一台设备」；
+ * - deviceName 缺省取主机名，取不到（容器/无主机名）时用字典里的兜底文案，绝不写空串；
+ * - **只在首次生成时写盘**（已有 id → 纯读，不产生额外写）。
+ */
+export declare function resolveDeviceIdentity(dir: string, hostName: string, fsx?: SnapshotFs, msg?: MsgFunc): Promise<{
+    id: string;
+    name: string;
+}>;
 /** 保存同步状态（自动创建目录） */
 export declare function saveSyncState(dir: string, state: SyncState, fsx?: SnapshotFs): Promise<void>;

package/lib/sync/sync-state.js

@@ -3,10 +3,13 @@
  * 记录上次同步时间与各分区内容 hash，供变更检测（与远端快照对比决定是否重传）。
  * 纯逻辑 + 可注入 fs；不触碰真实 ~/.dsh。
  */
+import { randomUUID } from 'node:crypto';
 import { sha256Hex } from '../utils/hashing.js';
 import { parseJsonSafe, stringifyJsonSafe } from '../utils/json.js';
 import { zhMsg } from '../core/messages.js';
 import { createSnapshotFs, joinFs } from './fs.js';
+// 侧效应导入：注册同步域追加消息目录（sync.deviceNameFallback 等 ⑥ 新键必须能解析，绝不露裸键名）
+import './messages.js';
 export const SYNC_STATE_SCHEMA_VERSION = 3;
 /**
  * 历史可读取版本（均在内存中迁移到当前版本，不就地改写磁盘）：
@@ -72,6 +75,24 @@ function readStringArray(raw) {
     }
     return out;
 }
+/**
+ * 读取可选 pendingMerge（基线纪律）。
+ *
+ * 形状不符（损坏/被篡改/分区清单为空）→ undefined = 按「无待裁决冲突」处理：
+ * 这里**绝不抛错**（一个诊断字段不该让 loadSyncState 整体失败），也绝不把空清单当成
+ * 「所有冲突都解决了」—— 空清单只是没有内容可记录。
+ */
+function readPendingMerge(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    if (typeof o['remoteSnapshotId'] !== 'string' || typeof o['since'] !== 'string')
+        return undefined;
+    const sections = readStringArray(o['sections']);
+    if (sections.length === 0)
+        return undefined;
+    return { remoteSnapshotId: o['remoteSnapshotId'], sections: sections, since: o['since'] };
+}
 /** 读取同步状态；文件不存在 → 返回缺省空状态（从未同步）。
  * 旧版本文件（v1/v2）→ 在内存中迁移到当前版本（见 SYNC_STATE_SUPPORTED_VERSIONS），
  * 不在磁盘上就地升级（首次 saveSyncState 时才写回新版本）。 */
@@ -122,6 +143,11 @@ export async function loadSyncState(dir, fsx = createSnapshotFs(), msg = zhMsg)
         // 绝不采用一个来路不明的目录名。
         ancestorId: rawAncestorId ?? (fileVersion < SYNC_STATE_SCHEMA_VERSION ? rawLastSnapshotId : ''),
         lastSnapshotId: rawLastSnapshotId,
+        // ⑥：只有文件里确实写过才回填（缺席 = 从未记录 → 下次推送才生成，绝不在这里凭空造一个 id）
+        ...(typeof obj['deviceId'] === 'string' && obj['deviceId'] !== '' ? { deviceId: obj['deviceId'] } : {}),
+        ...(typeof obj['deviceName'] === 'string' && obj['deviceName'] !== '' ? { deviceName: obj['deviceName'] } : {}),
+        // 基线纪律：同样「写过才回填」—— 缺席 = 无待裁决冲突（旧文件读回形状逐键不变）
+        ...(readPendingMerge(obj['pendingMerge']) !== undefined ? { pendingMerge: readPendingMerge(obj['pendingMerge']) } : {}),
     };
     const t = obj['transport'];
     if (t !== undefined) {
@@ -132,6 +158,24 @@ export async function loadSyncState(dir, fsx = createSnapshotFs(), msg = zhMsg)
     }
     return state;
 }
+/**
+ * 解析（必要时生成并持久化）本设备的同步身份（cloud-sync 借鉴项 ⑥）。
+ *
+ * - deviceId 一旦生成就持久化在 sync-state.json → 历史列表能认出「同一台设备」；
+ * - deviceName 缺省取主机名，取不到（容器/无主机名）时用字典里的兜底文案，绝不写空串；
+ * - **只在首次生成时写盘**（已有 id → 纯读，不产生额外写）。
+ */
+export async function resolveDeviceIdentity(dir, hostName, fsx = createSnapshotFs(), msg = zhMsg) {
+    const state = await loadSyncState(dir, fsx, msg);
+    const trimmedHost = typeof hostName === 'string' ? hostName.trim() : '';
+    const name = (typeof state.deviceName === 'string' && state.deviceName !== '' ? state.deviceName : '')
+        || (trimmedHost !== '' ? trimmedHost : msg('sync.deviceNameFallback'));
+    if (typeof state.deviceId === 'string' && state.deviceId !== '')
+        return { id: state.deviceId, name };
+    const id = randomUUID();
+    await saveSyncState(dir, { ...state, deviceId: id, deviceName: name }, fsx);
+    return { id, name };
+}
 /** 保存同步状态（自动创建目录） */
 export async function saveSyncState(dir, state, fsx = createSnapshotFs()) {
     await fsx.mkdir(dir);

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

@@ -0,0 +1,76 @@
+import type { Logger } from '../utils/logger.ts';
+import type { WatchTarget } from './watch-scope.ts';
+/** fs.watch 返回的句柄（只用到 close）。 */
+export interface WatchHandle {
+    close(): void;
+}
+/** fs.watch 的最小签名（测试注入假实现）。 */
+export type WatchFactory = (absPath: string, opts: {
+    recursive: boolean;
+}, listener: (event: string, filename: string | null) => void) => WatchHandle;
+/** 缺省去抖窗口：一次「保存配置」产生的连续事件合并为一次触发。 */
+export declare const DEFAULT_WATCH_DEBOUNCE_MS = 1500;
+/** 缺省自写回声窗口：resume 后这段时间内的事件一律忽略。 */
+export declare const DEFAULT_WATCH_QUIET_MS = 2000;
+export interface SyncWatcherOptions {
+    /** `$DSH_HOME` 绝对路径 */
+    homeDir: string;
+    /** 监听目标（`watch-scope.buildWatchTargets` 的产物） */
+    targets: readonly WatchTarget[];
+    log: Logger;
+    /** 去抖窗口到期：把这一批变更的 home 相对路径交给上层（已过滤噪声）。 */
+    onFlush: (changed: readonly string[]) => void;
+    debounceMs?: number;
+    quietAfterSuspendMs?: number;
+    watchFactory?: WatchFactory;
+    /** 时间源 / 计时器（测试注入） */
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (timer: ReturnType<typeof setTimeout>) => void;
+}
+export declare class SyncWatcher {
+    private readonly homeDir;
+    private readonly log;
+    private readonly onFlush;
+    private readonly debounceMs;
+    private readonly quietAfterSuspendMs;
+    private readonly watchFactory;
+    private readonly now;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private targets;
+    private attachments;
+    private pending;
+    private timer;
+    private started;
+    private suspended;
+    private quietUntil;
+    constructor(opts: SyncWatcherOptions);
+    /** 是否已启动。 */
+    isStarted(): boolean;
+    /** 当前实际挂上的监听数（诊断/测试用）。 */
+    attachmentCount(): number;
+    /** 启动监听（重复调用是幂等的）。 */
+    start(): void;
+    /** 停止监听并丢弃未触发的变更（插件卸载 / 自动同步关闭时必须调）。 */
+    stop(): void;
+    /** 换监听目标（分区选择/配置变化）；已启动则原子重启。 */
+    setTargets(targets: readonly WatchTarget[]): void;
+    /**
+     * 进入「自写中」：屏蔽事件并丢弃已积累的变更。
+     *
+     * 在 runOnce 开始时调用 —— 同步自家的 apply/push 会写 settings.yaml / patch / skills，
+     * 那些写入不是用户改动。
+     */
+    suspend(): void;
+    /** 退出「自写中」：随后进入静默窗口，避免收尾写入的回声立刻触发下一轮。 */
+    resume(): void;
+    /** 立即处理当前积累的变更（测试用；正常路径靠定时器）。 */
+    flushNow(): void;
+    private attachAll;
+    private attach;
+    private onRawEvent;
+    private scheduleFlush;
+    private flush;
+    private clearPendingTimer;
+}

package/lib/sync/sync-watcher.js

@@ -0,0 +1,202 @@
+/**
+ * m-autosync-realtime：本地文件监听器（fs.watch + 去抖 + 自写回声屏蔽）。
+ *
+ * 存在的理由：改造前的自动同步**只靠定时器**（最短 5 分钟），本地改完配置得等下一轮才上行，
+ * 与「像 VS Code 那样改完就同步」的预期不符（issue: 自动同步不自动）。
+ *
+ * 设计要点：
+ *  - **文件目标监听父目录**（非递归）+ 按 basename 过滤：原子写是 temp + rename，
+ *    直接监听文件本身会在 rename 后失去句柄（Linux inode 变化），监听父目录才稳；
+ *  - **去抖**（缺省 1500ms）：一次保存往往连写多个文件（settings.yaml + patch），
+ *    合并成一次触发，绝不为每个字节排一轮同步；
+ *  - **自写回声屏蔽**：调度器在 runOnce 前后 suspend()/resume()，resume 后再静默
+ *    `quietAfterSuspendMs`（缺省 2000ms）——否则「同步把远端内容写回本地」自身就会触发下一轮，
+ *    形成 push→apply→push 的死循环；
+ *  - **静默窗口只「推迟」不「丢弃」**：窗口内到达的事件记进 pending 并排一枚窗口结束后的补跑定时器
+ *    （真机实测：窗口内保存若直接丢弃，用户改完要等一整轮兜底间隔才上行 —— 与「改完就同步」不符）。
+ *    自家回声由引擎的分区 hash 比对判成「无变化」，多跑一轮不产生任何传输；
+ *  - **纯监听、不做判定**：这里只说「有东西变了」（附带 home 相对路径），究竟哪些分区真的变了
+ *    由引擎的 `hasLocalChanges()`（分区 hash 比基线）回答 —— 监听器绝不猜。
+ *
+ * 可靠性取舍：监听失败（ENOENT / 平台不支持 recursive）只 `log.debug/warn`，绝不抛错 ——
+ * 自动同步的兜底始终是定时器，监听掉线只是退回「等下一轮」，不能让宿主启动失败。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isNoiseRelPath, targetAbsPath, toHomeRelPath } from './watch-scope.js';
+/** 缺省去抖窗口：一次「保存配置」产生的连续事件合并为一次触发。 */
+export const DEFAULT_WATCH_DEBOUNCE_MS = 1500;
+/** 缺省自写回声窗口：resume 后这段时间内的事件一律忽略。 */
+export const DEFAULT_WATCH_QUIET_MS = 2000;
+export class SyncWatcher {
+    homeDir;
+    log;
+    onFlush;
+    debounceMs;
+    quietAfterSuspendMs;
+    watchFactory;
+    now;
+    setTimer;
+    clearTimer;
+    targets;
+    attachments = [];
+    pending = new Set();
+    timer = null;
+    started = false;
+    suspended = false;
+    quietUntil = 0;
+    constructor(opts) {
+        this.homeDir = opts.homeDir;
+        this.targets = opts.targets;
+        this.log = opts.log;
+        this.onFlush = opts.onFlush;
+        this.debounceMs = opts.debounceMs ?? DEFAULT_WATCH_DEBOUNCE_MS;
+        this.quietAfterSuspendMs = opts.quietAfterSuspendMs ?? DEFAULT_WATCH_QUIET_MS;
+        this.watchFactory = opts.watchFactory ?? defaultWatchFactory;
+        this.now = opts.now ?? (() => Date.now());
+        this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = opts.clearTimer ?? ((t) => clearTimeout(t));
+    }
+    /** 是否已启动。 */
+    isStarted() {
+        return this.started;
+    }
+    /** 当前实际挂上的监听数（诊断/测试用）。 */
+    attachmentCount() {
+        return this.attachments.length;
+    }
+    /** 启动监听（重复调用是幂等的）。 */
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.attachAll();
+    }
+    /** 停止监听并丢弃未触发的变更（插件卸载 / 自动同步关闭时必须调）。 */
+    stop() {
+        this.started = false;
+        this.suspended = false;
+        this.quietUntil = 0;
+        this.clearPendingTimer();
+        this.pending.clear();
+        for (const a of this.attachments) {
+            try {
+                a.handle.close();
+            }
+            catch {
+                /* 尽力而为：句柄可能已被平台回收 */
+            }
+        }
+        this.attachments = [];
+    }
+    /** 换监听目标（分区选择/配置变化）；已启动则原子重启。 */
+    setTargets(targets) {
+        this.targets = targets;
+        if (!this.started)
+            return;
+        this.stop();
+        this.started = true;
+        this.attachAll();
+    }
+    /**
+     * 进入「自写中」：屏蔽事件并丢弃已积累的变更。
+     *
+     * 在 runOnce 开始时调用 —— 同步自家的 apply/push 会写 settings.yaml / patch / skills，
+     * 那些写入不是用户改动。
+     */
+    suspend() {
+        this.suspended = true;
+        this.clearPendingTimer();
+        this.pending.clear();
+    }
+    /** 退出「自写中」：随后进入静默窗口，避免收尾写入的回声立刻触发下一轮。 */
+    resume() {
+        if (!this.suspended)
+            return;
+        this.suspended = false;
+        this.quietUntil = this.now() + this.quietAfterSuspendMs;
+    }
+    /** 立即处理当前积累的变更（测试用；正常路径靠定时器）。 */
+    flushNow() {
+        this.flush();
+    }
+    attachAll() {
+        for (const target of this.targets)
+            this.attach(target);
+    }
+    attach(target) {
+        const abs = targetAbsPath(this.homeDir, target);
+        const isDir = target.kind === 'dir';
+        const watchedDir = isDir ? abs : path.dirname(abs);
+        const fileBase = isDir ? null : path.basename(abs);
+        try {
+            const handle = this.watchFactory(watchedDir, { recursive: isDir ? target.recursive : false }, (event, filename) => {
+                this.onRawEvent(target, watchedDir, fileBase, filename);
+            });
+            this.attachments.push({ target, watchedDir, fileBase, handle });
+            this.log.debug(`自动同步监听已挂载：${target.relPath}`, { watchedDir });
+        }
+        catch (err) {
+            // 路径不存在 / 平台不支持：不阻断启动，兜底是定时器
+            this.log.debug(`自动同步监听未挂载：${target.relPath}`, { error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    onRawEvent(target, watchedDir, fileBase, filename) {
+        if (!this.started || this.suspended)
+            return;
+        // 静默窗口内到达的事件：先记账，窗口一结束就补跑一次判定（丢弃会让用户改动漏掉一整轮兜底间隔）
+        const quietRemainingMs = this.quietUntil - this.now();
+        let abs;
+        if (fileBase !== null) {
+            // 文件目标：只关心父目录里同名文件的事件（原子写的 temp 名字被噪声规则挡掉）
+            if (filename !== null && path.basename(filename) !== fileBase)
+                return;
+            abs = path.join(watchedDir, fileBase);
+        }
+        else {
+            if (filename === null)
+                return;
+            abs = path.join(watchedDir, filename);
+        }
+        const rel = toHomeRelPath(this.homeDir, abs);
+        if (rel === null || isNoiseRelPath(rel))
+            return;
+        void target; // sections 仅用于诊断；判定交给引擎的分区 hash
+        this.pending.add(rel);
+        this.scheduleFlush(quietRemainingMs > 0 ? quietRemainingMs + this.debounceMs : this.debounceMs);
+    }
+    scheduleFlush(delayMs = this.debounceMs) {
+        if (this.timer !== null)
+            return;
+        this.timer = this.setTimer(() => {
+            this.timer = null;
+            this.flush();
+        }, delayMs);
+    }
+    flush() {
+        if (this.pending.size === 0)
+            return;
+        const quietRemainingMs = this.quietUntil - this.now();
+        if (quietRemainingMs > 0) {
+            // 去抖定时器提前到期：推迟到窗口结束，既不丢用户改动、也不把自家收尾写入当触发
+            this.scheduleFlush(quietRemainingMs + this.debounceMs);
+            return;
+        }
+        const changed = [...this.pending];
+        this.pending.clear();
+        try {
+            this.onFlush(changed);
+        }
+        catch (err) {
+            this.log.warn('自动同步监听回调失败', { error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    clearPendingTimer() {
+        if (this.timer === null)
+            return;
+        this.clearTimer(this.timer);
+        this.timer = null;
+    }
+}
+const defaultWatchFactory = (absPath, opts, listener) => fs.watch(absPath, { recursive: opts.recursive }, listener);
+//# sourceMappingURL=sync-watcher.js.map

package/lib/sync/text-merge.d.ts

@@ -0,0 +1,85 @@
+/**
+ * m-sync-flow：行级文本三方合并 + 递归 JSON 结构化合并（零依赖纯函数）。
+ *
+ * 职责边界（本文件只做纯计算：不读配置、不落盘、不打日志）：
+ *  - looksLikeText / tryParseJson：内容形态判定（文本 / JSON）；
+ *  - mergeJsonValues：JSON 值级递归三方合并（对象按 key 递归；数组绝不按索引合并）；
+ *  - mergeTextThreeWay：文本级三方合并（三段都是合法 JSON 时优先走结构化合并）；
+ *  - mergeBytesThreeWay：字节级入口，非文本 / 超限 / 缺祖先一律如实拒绝（绝不猜）。
+ *
+ * 安全口径（改这里前先读）：
+ *  - 冲突优先于猜测：语义不明的合并（数组双侧改动、同一区域双侧改动、类型互换）一律报冲突，
+ *    绝不静默丢弃任一侧的键 / 插件配置 / 用户数据。
+ *  - 行对齐只走 LCS（base→local、base→remote），同一行内容重复时也不会错位；单侧变更区间
+ *    超过 DP 上限时退化为「整段替换」——宁可粗粒度报冲突，也不做定位猜测。
+ *  - 文本比较按「去行尾」后的内容进行：CRLF/LF 混用不得误报冲突；输出保留输入的行尾风格。
+ *  - 缺共同祖先（ancestor === undefined）→ ok:false：由上层按整文件冲突处理，本模块不猜。
+ */
+/** 文本判定与文本合并的缺省字节上限：1 MiB。超限一律按「太大不合并」处理。 */
+export declare const TEXT_MERGE_MAX_BYTES: number;
+/** 单条冲突。local/remote/ancestor 是原始值：JSON 合并给原始 JSON 值，文本合并给字符串片段。 */
+export interface TextMergeConflict {
+    /** 冲突位置：JSON 合并是点号路径（'a.b.c'，根为 ''）；文本合并是 'line 12-14'（或单点 'line 7'）。 */
+    path: string;
+    reason: 'overlap' | 'array' | 'format' | 'binary' | 'too-large';
+    local?: unknown;
+    remote?: unknown;
+    ancestor?: unknown;
+}
+/** JSON 值级合并结果；ok 为 false 时 merged 缺省（绝不把半成品当结果）。 */
+export interface JsonMergeResult {
+    ok: boolean;
+    merged?: unknown;
+    conflicts: TextMergeConflict[];
+}
+/** 合并内容形态：合法 JSON 文本 / 行级文本 / 二进制 / 超限。 */
+export type TextMergeKind = 'text' | 'json' | 'binary' | 'too-large';
+/** 文本（或字节）三方合并结果。 */
+export interface TextMergeResult {
+    ok: boolean;
+    merged?: string;
+    conflicts: TextMergeConflict[];
+    kind: TextMergeKind;
+}
+/** 字节三方合并结果。 */
+export interface TextBytesMergeResult {
+    ok: boolean;
+    merged?: Uint8Array;
+    conflicts: TextMergeConflict[];
+    kind: TextMergeKind;
+}
+/**
+ * 是否像文本：含 NUL 字节 / 非法 UTF-8 / 超过 maxBytes（缺省 1 MiB）→ false。
+ * 只做形态判定，不做解码；调用方拿到 true 后可用 UTF-8 解码。
+ */
+export declare function looksLikeText(bytes: Uint8Array, maxBytes?: number): boolean;
+/** 严格 JSON 解析（不做 JSON5 / 注释 / 尾逗号宽容）：解析失败返回 ok:false。 */
+export declare function tryParseJson(text: string): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+/**
+ * 三方合并 JSON 值（递归，任意深度）。
+ *  - 双侧相同 → 该值（收敛）；
+ *  - 仅一侧相对祖先改动 → 采纳该侧；
+ *  - 对象（祖先缺省或同为对象）→ 按键递归，**缺失键 = 删除语义**：
+ *      一侧删除 + 另一侧未改 → 删除胜出；一侧删除 + 另一侧改了 → 冲突；
+ *      单侧新增（祖先没有）→ 采纳；双侧都新增且不同 → 冲突；
+ *  - 数组绝不按索引合并：双侧都改且不 deepEqual → 冲突（reason='array'）；
+ *  - 其余（标量双向改动、类型互换）→ 冲突（reason='overlap'）。
+ */
+export declare function mergeJsonValues(ancestor: unknown, local: unknown, remote: unknown, path?: string): JsonMergeResult;
+/**
+ * 行级三方合并：base→local、base→remote 各自算变更区间，不重叠的全部应用；
+ * 重叠区间两侧结果逐字相同 → 收敛为一份，否则冲突（path='line X-Y'）。
+ */
+export declare function mergeTextThreeWay(ancestor: string, local: string, remote: string): TextMergeResult;
+/**
+ * 字节三方合并：
+ *  - ancestor === undefined → ok:false（无共同祖先，由上层按整文件冲突处理，绝不猜）；
+ *  - 任一侧二进制 / 超限（含 ancestor）→ ok:false，kind 如实（'binary' / 'too-large'）；
+ *  - 否则解码为文本走 mergeTextThreeWay，成功后按 UTF-8 编码回字节。
+ */
+export declare function mergeBytesThreeWay(ancestor: Uint8Array | undefined, local: Uint8Array, remote: Uint8Array): TextBytesMergeResult;