dsh-config-manager 0.1.78 → 0.1.80

package/lib/sync/autosync-scheduler.js

@@ -12,6 +12,12 @@
  * 互不干扰；同一时刻至多执行一个通道的 runOnce（runs.register('autosync') 全局防重，
  * 避免两个引擎并发写本地配置），另一通道的定时触发在本轮结束后自然补跑。
  *
+ * 「真·自动」（VS Code 式）两条即时通道（realtime=true 时生效）：
+ *  - **本地改动即时上行**：SyncWatcher 监听本机可同步分区（watch-scope.ts 的清单，已排除
+ *    sessions/、sync-autosync.json 等自写回声路径）→ 去抖后 trigger(channel,'local-change')；
+ *  - **远端改动即时下行**：每 remoteCheckMs（缺省 60s，可 15s–1h）廉价探测一次远端是否有新快照
+ *    → trigger(channel,'remote-poll')。定时器 interval 只作兜底。
+ *
  * 核心逻辑（runOnce）：
  *  - 读该通道配置；若 !enabled → return
  *  - runs.register('autosync') 防重复；同 kind running → 跳过
@@ -19,11 +25,16 @@
  *    → 记 skipped(未配置) → return
  *  - Phase A: engine.merge() 三方合并 → 判定 needsReview（冲突/缺失依赖/Install/Error）
  *  - 冲突 → 只挡**下行**：跳过 Phase B（绝不写本地）+ 记 conflictedSections[]，
- *    但**继续**走到 Phase C 做纯上行导出（issue #79：远端冲突不该连坐「把本机配置推上去当备份」）
+ *    但**继续**走到 Phase C（issue #79：远端冲突不该连坐「把本机配置推上去当备份」）
  *  - Phase B: 无冲突 → 按 risk.ts 的 classifyMergePlan 分流（audit-sync sync-F5）：
- *    低风险项自动应用；medium/high 项**不自动应用**并进 conflictedSections（待人工确认，绝不静默）
+ *    低风险自动应用；medium 仅当 autoApplyTier='medium'（缺省）自动应用；
+ *    high/未注册/冲突项**不自动应用**并进 conflictedSections（待人工确认，绝不静默）
  *    → engine.applyMergePlan(autoApply) 写入本地
- *  - Phase C: 完整双向 → engine.push() 上传（本轮有冲突且推送成功 → 状态 partial，不谎报 success）
+ *  - Phase C: 完整双向 → engine.push() 上传。两处策略：
+ *    ① 无冲突且推送被远端推进挡下 → skipped/partial + skipReason='conflict'（等人工）；
+ *    ② conflictPolicy='local'（缺省）且本轮有冲突 → **不写本地**，改 engine.push({force:true})
+ *       把本机版本推成新的远端最新（被覆盖的远端旧版本仍在远端历史快照里可回滚），
+ *       状态记 partial + skipReason='conflict-kept-local'（绝不谎报 success）。
  *  - 收尾：写该通道 autosync-config（lastRunAt, lastRunStatus, consecutiveFailures,
  *    lastRunHistoryId, lastRunMessage/跳过原因 —— 每轮覆盖上一轮，绝不残留旧错误）
  *
@@ -34,10 +45,12 @@
 import crypto from 'node:crypto';
 import { withMutationLock, LOCK_BLOCK_MESSAGE } from '../utils/env-lock.js';
 import { engineMsg } from './messages.js';
-import { readAutosyncConfig, writeAutosyncConfig } from './autosync-config.js';
+import { readAutosyncConfig, writeAutosyncConfig, clampRemoteCheckMs, DEFAULT_AUTOSYNC_REALTIME, DEFAULT_AUTOSYNC_REMOTE_CHECK_MS, DEFAULT_AUTOSYNC_AUTO_APPLY_TIER, DEFAULT_AUTOSYNC_CONFLICT_POLICY, } from './autosync-config.js';
 import { readSyncConfigFor, isGitConfig, isWebDavConfig, isS3Config, isGistConfig, SYNC_CHANNELS } from './sync-config.js';
-import { readSyncHistory, appendAutosyncEntry } from './sync-history.js';
+import { readSyncHistory, appendAutosyncEntry, markAutosyncNotified } from './sync-history.js';
 import { classifyMergePlan } from './risk.js';
+import { SyncWatcher } from './sync-watcher.js';
+import { buildWatchTargets } from './watch-scope.js';
 /** 间隔 → ms 换算（§4.3） */
 export function intervalToMs(interval) {
     const table = {
@@ -85,6 +98,22 @@ export class AutoSyncScheduler {
     lockCtxForJournal = null;
     /** 每通道一个定时器（git/webdav 各自 enabled 时独立排期）。 */
     timers = new Map();
+    /** realtime 通道的远端轮询定时器：与 interval 定时器**分开**，否则每次轮询都会重置兜底间隔。 */
+    remoteTimers = new Map();
+    /** 本地改动监听（只有 enabled && realtime 的通道才挂；全关 → null）。 */
+    watcher = null;
+    /** 当前需要监听的通道（setupWatchers 计算）。 */
+    realtimeChannels = [];
+    /** 运行期到达的触发：本轮收尾后立刻补跑（绝不并发写本地配置，也绝不丢）。 */
+    pendingTrigger = null;
+    /** 上次开始运行的时刻（trigger 的最小间隔合并用）。 */
+    lastRunAtMs = new Map();
+    /** 因最小间隔被推迟的触发（每通道至多一个）。 */
+    gapTimers = new Map();
+    homeDir;
+    profile;
+    makeWatcher;
+    minTriggerGapMs;
     stopped = false;
     running = false;
     constructor(opts) {
@@ -105,6 +134,10 @@ export class AutoSyncScheduler {
         this.phase3Recovery = opts.phase3Recovery;
         this.detectRemoteNew = opts.detectRemoteNew ?? defaultDetectRemoteNew;
         this.detectLocalChange = opts.detectLocalChange ?? defaultDetectLocalChange;
+        this.homeDir = opts.homeDir;
+        this.profile = opts.profile;
+        this.makeWatcher = opts.makeWatcher ?? defaultMakeWatcher;
+        this.minTriggerGapMs = opts.minTriggerGapMs ?? 3000;
     }
     /** 追加一条自动同步历史（自动带上触发通道；0x 安全：绝不覆盖调用方显式 transport）。 */
     async appendHistory(channel, entry) {
@@ -117,12 +150,22 @@ export class AutoSyncScheduler {
         this.refreshTimers();
         void this.startupRuns();
     }
-    /** 停止：清全部定时器、标记不再调度；正在执行的任务允许自然结束。 */
+    /** 停止：清全部定时器、拆掉文件监听、标记不再调度；正在执行的任务允许自然结束。 */
     stop() {
         this.stopped = true;
         for (const timer of this.timers.values())
             this.clearTimer(timer);
         this.timers.clear();
+        for (const timer of this.remoteTimers.values())
+            this.clearTimer(timer);
+        this.remoteTimers.clear();
+        for (const timer of this.gapTimers.values())
+            this.clearTimer(timer);
+        this.gapTimers.clear();
+        this.pendingTrigger = null;
+        this.watcher?.stop();
+        this.watcher = null;
+        this.realtimeChannels = [];
     }
     /** 重新加载配置（路由 POST /sync/autosync 后调用；重排所有通道定时器）。 */
     async reload() {
@@ -131,6 +174,40 @@ export class AutoSyncScheduler {
         this.refreshTimers();
     }
     refreshTimers() {
+        this.scheduleIntervalTimers();
+        this.scheduleRemoteTimers();
+        void this.setupWatchers();
+    }
+    /**
+     * 外部触发一次运行（本地改动 / 远端探测 / 另一通道让位）。
+     *
+     * - 正在跑 → 记 pendingTrigger，本轮收尾后**立刻补跑**（不并发写本地配置，也绝不丢）；
+     * - 距上次开始不足 minTriggerGapMs → 合并成一次（连续保存只跑一轮，每通道至多一个定时器）。
+     */
+    trigger(channel, reason = 'manual') {
+        if (this.stopped)
+            return;
+        if (this.running) {
+            this.pendingTrigger = { channel, reason };
+            return;
+        }
+        const waitMs = this.minTriggerGapMs - (this.now().getTime() - (this.lastRunAtMs.get(channel) ?? 0));
+        if (waitMs > 0) {
+            if (this.gapTimers.has(channel))
+                return;
+            const timer = this.setTimer(() => {
+                this.gapTimers.delete(channel);
+                this.trigger(channel, reason);
+            }, waitMs);
+            this.gapTimers.set(channel, timer);
+            return;
+        }
+        void this.runOnce(channel, { reason }).catch((err) => {
+            this.host.log.error(`自动同步触发失败（${channel}/${reason}）`, { error: err instanceof Error ? err.message : String(err) });
+        });
+    }
+    /** 兜底间隔定时器：每个 enabled 通道按各自 interval 排一次性定时器，触发后只重排自己。 */
+    scheduleIntervalTimers() {
         for (const timer of this.timers.values())
             this.clearTimer(timer);
         this.timers.clear();
@@ -146,21 +223,86 @@ export class AutoSyncScheduler {
                     this.timers.delete(channel);
                     if (this.stopped)
                         return;
-                    void this.runOnce(channel)
+                    void this.runOnce(channel, { reason: 'interval' })
                         .catch((err) => {
                         this.host.log.error(`自动同步定时触发失败（${channel}）`, { error: err instanceof Error ? err.message : String(err) });
                     })
                         .then(() => {
-                        // 本轮结束（成功 / 跳过 / 失败）后重新排定下一次；refreshTimers
-                        // 内部重读配置，若期间被关闭（enabled=false）则不再排期。
+                        // 只重排 interval 定时器（远端轮询有自己的节奏，绝不互相重置）
                         if (!this.stopped)
-                            this.refreshTimers();
+                            this.scheduleIntervalTimers();
                     });
                 }, ms);
                 this.timers.set(channel, timer);
             }).catch(() => { });
         }
     }
+    /**
+     * realtime 通道的远端轮询：按 remoteCheckMs（缺省 60s）排一次性定时器。
+     * 轮询只是「叫醒一轮 runOnce」—— 是否真的下载仍由 detectRemoteNew 判定，
+     * 所以哪怕每 60s 叫醒一次，无变化时也只会记一条 upToDate 而不会反复传输。
+     */
+    scheduleRemoteTimers() {
+        for (const timer of this.remoteTimers.values())
+            this.clearTimer(timer);
+        this.remoteTimers.clear();
+        const channels = SYNC_CHANNELS;
+        for (const channel of channels) {
+            void this.readConfig(channel).then((cfg) => {
+                if (this.stopped || !cfg.enabled || !(cfg.realtime ?? DEFAULT_AUTOSYNC_REALTIME))
+                    return;
+                const ms = clampRemoteCheckMs(cfg.remoteCheckMs ?? DEFAULT_AUTOSYNC_REMOTE_CHECK_MS);
+                const timer = this.setTimer(() => {
+                    this.remoteTimers.delete(channel);
+                    if (this.stopped)
+                        return;
+                    this.trigger(channel, 'remote-poll');
+                    // 固定节奏：轮询不等本轮跑完就排下一次（trigger 自己负责合并/排队）
+                    if (!this.stopped)
+                        this.scheduleRemoteTimers();
+                }, ms);
+                this.remoteTimers.set(channel, timer);
+            }).catch(() => { });
+        }
+    }
+    /** 按「enabled && realtime」重算监听集合：需要就挂、全关就拆（绝不留下空转句柄）。 */
+    async setupWatchers() {
+        const realtime = [];
+        for (const channel of SYNC_CHANNELS) {
+            try {
+                const cfg = await this.readConfig(channel);
+                if (cfg.enabled && (cfg.realtime ?? DEFAULT_AUTOSYNC_REALTIME))
+                    realtime.push(channel);
+            }
+            catch { /* 读配置失败 → 该通道不挂监听 */ }
+        }
+        this.realtimeChannels = realtime;
+        if (realtime.length === 0) {
+            this.watcher?.stop();
+            this.watcher = null;
+            return;
+        }
+        if (this.homeDir === undefined || this.makeWatcher === undefined)
+            return; // 未接线（测试）→ 只靠定时器
+        if (this.watcher === null) {
+            this.watcher = this.makeWatcher({
+                homeDir: this.homeDir,
+                profile: this.profile,
+                log: this.host.log,
+                onFlush: (changed) => this.onLocalChange(changed),
+            });
+            this.watcher.start();
+            this.host.log.info(`自动同步已开启本地改动监听（${realtime.join('/')}）`);
+        }
+    }
+    /** watcher 回调：任一批改动 → 让所有 realtime 通道各跑一轮（各自有变化检测，不会空转传输）。 */
+    onLocalChange(changed) {
+        if (this.stopped || changed.length === 0)
+            return;
+        this.host.log.debug(`检测到本地配置改动（${changed.length} 个路径）→ 触发自动同步`);
+        for (const channel of this.realtimeChannels)
+            this.trigger(channel, 'local-change');
+    }
     /** 启动触发下载合并（每个 enabled 通道；受各自 startupMinIntervalMs 阈值约束）。 */
     async startupRuns() {
         // 通道清单唯一来源 = SYNC_CHANNELS（此前同一数组在本文件写了两遍：漏改一处即某通道永不排期）
@@ -174,7 +316,7 @@ export class AutoSyncScheduler {
                     this.host.log.info(`自动同步启动触发跳过（${channel}）：距上次运行未达阈值`);
                     continue;
                 }
-                await this.runOnce(channel, { startup: true });
+                await this.runOnce(channel, { startup: true, reason: 'startup' });
             }
             catch (err) {
                 this.host.log.error(`启动触发下载合并失败（${channel}）`, { error: err instanceof Error ? err.message : String(err) });
@@ -187,6 +329,16 @@ export class AutoSyncScheduler {
      * @param opts.startup - true 表示启动触发变体（只做 Phase A+B，不做 Phase C push）
      */
     async runOnce(channel, opts = {}) {
+        const result = await this.runOnceInternal(channel, opts);
+        // 收尾后补跑：运行期到达的触发（watcher 连续保存 / 远端轮询 / 定时器到期）不会丢。
+        // 放在内部实现之外（而不是 finally 里）是为了让锁与 run 账**完全释放之后**才开始下一轮。
+        const pending = this.pendingTrigger;
+        this.pendingTrigger = null;
+        if (pending !== null && !this.stopped)
+            this.trigger(pending.channel, pending.reason);
+        return result;
+    }
+    async runOnceInternal(channel, opts = {}) {
         if (this.running)
             return { status: 'skipped', direction: 'none', skipReason: 'running', historyId: '', consecutiveFailures: 0 };
         const cfg = await this.readConfig(channel);
@@ -194,6 +346,9 @@ export class AutoSyncScheduler {
             return { status: 'skipped', direction: 'none', skipReason: 'disabled', historyId: '', consecutiveFailures: cfg.consecutiveFailures };
         }
         this.running = true;
+        this.lastRunAtMs.set(channel, this.now().getTime());
+        // 本轮会写本机配置（apply）→ 暂停监听，别把自己的写入当成「用户改了配置」（否则自激循环）。
+        this.watcher?.suspend();
         const nowIso = this.now().toISOString();
         const historyId = `autosync-${crypto.randomUUID()}`;
         // runs 防重复：同 kind running → 跳过（内部语义，不打搅用户）
@@ -302,8 +457,13 @@ export class AutoSyncScheduler {
             // 加密快照只通过手动推送/拉取产生与消费；自动同步仅处理普通快照。
             // list 失败宽容处理：视为无加密快照，继续正常流程（网络问题由后续链路暴露为 failed）。
             let encryptedRemote = false;
+            // 本轮远端列表：加密快照检查与「远端是否有新快照」共用同一次 list。
+            // 每次 list 都是一次真实网络往返（git = `pull --ff-only`，webdav = PROPFIND/GET），
+            // 缺省 60s 轮询下多 list 一次 = 一天白跑 1440 次往返。
+            let remoteMetas = null;
             try {
                 const metas = await engine.listSnapshots();
+                remoteMetas = metas;
                 const latestMeta = metas.length > 0 ? metas[metas.length - 1] : null;
                 encryptedRemote = latestMeta !== null && latestMeta.manifest.encrypted === true;
             }
@@ -326,7 +486,8 @@ export class AutoSyncScheduler {
             // - remoteNew：远端是否出现比本地祖先更新的快照 → 决定是否做下载合并（Phase A）；
             // - localDirty：本地 portable 配置相对基线是否真的变了 → 决定是否上传（Phase C）。
             // 定时器只是兜底轮询；真正驱动是这两个「变化」信号。
-            const remoteNew = await this.detectRemoteNew(engine);
+            // 列表拿不到（网络失败）时 remoteMetas 为 null → 检测自己再 list 一次，行为与改造前一致
+            const remoteNew = await this.detectRemoteNew(engine, remoteMetas ?? undefined);
             const localDirty = await this.detectLocalChange(engine);
             // 两端都无变化 → 什么都不做，记为 upToDate（不重复拉取/不空转）。
             if (!remoteNew && !localDirty) {
@@ -378,11 +539,15 @@ export class AutoSyncScheduler {
                 // 风险分级（audit-sync sync-F5）照旧只在无冲突时执行。
                 if (conflictedSections.length === 0) {
                     // 无冲突：按 risk.ts 的风险分级契约分流（audit-sync sync-F5）。
-                    // 此前用 buildAutoApplyPlan 无条件应用全部非冲突分区 → medium/high 分区（plugins/mcp/
-                    // workspaces 等）在无用户确认时被自动写进本地，与 classifyMergePlan 的既定口径
-                    // （低风险自动应用；medium/high → 待审）分叉，「首次同步强制预览」在自动路径上也形同虚设。
+                    // autoApplyTier（缺省 'medium'）= 「真·自动同步所有改动」的开关：low 档只自动落
+                    // 低风险分区（settings/ui/providers/prompts/skills/agentPresets/agentInstructions/self），
+                    // medium 档连 plugins / mcp 这两个中风险分区也自动落盘；**high 档永不自动**
+                    // （类型上限即 medium：secrets/credentialsStatus/pluginData/pluginFiles 根本不在同步面内）。
                     // firstSync 恒 false：真正的首次同步没有祖先基线，merge 已把两侧差异判成 conflict → 走人工确认。
-                    const apply = classifyMergePlan(mergePlan, { firstSync: false });
+                    const apply = classifyMergePlan(mergePlan, {
+                        firstSync: false,
+                        maxAutoTier: cfg.autoApplyTier ?? DEFAULT_AUTOSYNC_AUTO_APPLY_TIER,
+                    });
                     // 待审项（medium/high：决策明确但不该自动应用）必须可见 —— 进历史 conflictedSections，
                     // 绝不静默丢弃；真正的冲突已在上方记入 conflictedSections。
                     deferredSections = apply.review.map((s) => s.id);
@@ -424,14 +589,45 @@ export class AutoSyncScheduler {
             // Phase C: push 上传（完整双向）—— 仅当本地真有改动才上传（§3.1）；startup 变体不上传。
             if (!opts.startup && localDirty) {
                 try {
+                    /**
+                     * 冲突策略（conflictPolicy，缺省 'local'）：
+                     * - 'ask'：不强制，推送会被引擎的「远端已推进」前置检测挡下 → skipped/partial(conflict)；
+                     * - 'local'：**不写本地**（下行被冲突挡下），但把本机版本强制推成新的远端最新。
+                     *   force 只跳过「基线是否落后」这一道检查，仍走正常快照上传与基线记录；
+                     *   被覆盖的远端旧版本留在远端历史快照里，可手动回滚。
+                     */
+                    const forcePush = conflictedSections.length > 0 && (cfg.conflictPolicy ?? DEFAULT_AUTOSYNC_CONFLICT_POLICY) === 'local';
                     // Phase C: 完整双向 → engine.push() 上传。P0-A：外部 push 包 intent journal。
-                    const rawPush = async () => engine.push();
+                    const rawPush = async () => engine.push(forcePush ? { force: true } : {});
                     const pushReport = (this.phase3Recovery !== undefined && this.lockCtxForJournal !== null)
                         ? (await this.phase3Recovery.runExternalIntent({
                             operationType: 'autosync-push', lockCtx: this.lockCtxForJournal,
                             intent: { adapter: 'sync', ref: channel, kind: 'Push' }, fn: rawPush,
                         })).result
                         : await rawPush();
+                    if (!pushReport.ok && pushReport.conflict === true) {
+                        // 引擎前置检测拒绝写入：远端已被别的设备推进 —— 这是**有冲突待处理**，不是通道/凭据故障。
+                        // 绝不记 failed（那会累加连续失败计数并对用户发通知，把「需要用『检查远程合并』处理」
+                        // 谎报成「同步坏了」）；错误摘要保留引擎给出的说明（用户能看见到底为什么没推上去）。
+                        const message = pushReport.message ?? engineMsg('sync.autosyncPushFailed');
+                        const conflictResult = {
+                            status: conflictedSections.length > 0 ? 'partial' : 'skipped',
+                            direction: appliedSections.length ? 'both' : 'push',
+                            skipReason: 'conflict', error: message, historyId,
+                            appliedSections,
+                            ...(conflictedSections.length > 0 ? { conflictedSections } : {}),
+                            consecutiveFailures: 0,
+                        };
+                        await this.appendHistory(channel, {
+                            direction: appliedSections.length ? 'both' : 'push', status: conflictResult.status,
+                            skipReason: 'conflict', error: message,
+                            appliedSections,
+                            ...(conflictedSections.length > 0 ? { conflictedSections } : {}),
+                            createdAt: nowIso, failureCountAtRun: 0,
+                        });
+                        await this.writeFinalConfig(cfg, conflictResult, nowIso, historyId, channel);
+                        return conflictResult;
+                    }
                     if (!pushReport.ok) {
                         const error = pushReport.message ?? engineMsg('sync.autosyncPushFailed');
                         const result = {
@@ -450,22 +646,34 @@ export class AutoSyncScheduler {
                     }
                     // issue #79：上行成功但下行被冲突挡下 → partial（绝不把「半个方向完成」报成 success，
                     // 也绝不因为它报成 failed：网络与凭据都是好的，只是远端有内容要用户确认）。
+                    // conflictPolicy='local' 时冲突已被「本机覆盖远端」消解，但远端那一版确实被盖掉了 →
+                    // 同样记 partial，skipReason 换成 conflict-kept-local（界面据此说清「本机已覆盖远端」）。
+                    const keptLocal = forcePush && conflictedSections.length > 0;
                     const partial = conflictedSections.length > 0;
+                    const skipReason = keptLocal
+                        ? 'conflict-kept-local'
+                        : partial
+                            ? 'conflict'
+                            : undefined;
+                    const reportedConflicted = keptLocal
+                        ? conflictedSections
+                        : partial
+                            ? conflictedSections
+                            : deferredSections;
                     const result = {
                         status: partial ? 'partial' : 'success',
                         direction: appliedSections.length ? 'both' : 'push',
                         appliedSections, pushedSnapshotId: pushReport.snapshotId, historyId,
-                        ...(partial ? { skipReason: 'conflict' } : {}),
-                        ...(deferredSections.length > 0 ? { conflictedSections: deferredSections } : {}),
-                        ...(partial ? { conflictedSections } : {}),
+                        ...(skipReason !== undefined ? { skipReason } : {}),
+                        ...(reportedConflicted.length > 0 ? { conflictedSections: reportedConflicted } : {}),
                         consecutiveFailures: 0,
                     };
                     await this.appendHistory(channel, {
                         direction: appliedSections.length ? 'both' : 'push',
                         status: partial ? 'partial' : 'success',
                         appliedSections, pushedSnapshotId: pushReport.snapshotId,
-                        ...(partial ? { skipReason: 'conflict', conflictedSections } : {}),
-                        ...(!partial && deferredSections.length > 0 ? { conflictedSections: deferredSections } : {}),
+                        ...(skipReason !== undefined ? { skipReason } : {}),
+                        ...(reportedConflicted.length > 0 ? { conflictedSections: reportedConflicted } : {}),
                         createdAt: nowIso, failureCountAtRun: 0,
                     });
                     await this.writeFinalConfig(cfg, result, nowIso, historyId, channel);
@@ -533,6 +741,7 @@ export class AutoSyncScheduler {
         }
         finally {
             this.running = false;
+            this.watcher?.resume();
             // 收尾 RunRegistry：不 finish 会让 autosync 的 running 记录滞留，期间任何再次 runOnce
             // 都会 register('autosync') → RunConflictError → 永远 skip(conflict)，后台同步就此停摆。
             // 同一收敛点也必须在**主 try 之外**的早退路径上调用（见 finishRun 的注释）。
@@ -556,7 +765,8 @@ export class AutoSyncScheduler {
      */
     async writeFinalConfig(base, result, nowIso, historyId, channel) {
         const skipReason = result.status === 'failed' ? undefined : result.skipReason;
-        const skipCount = skipReason !== 'conflict' || result.conflictedSections === undefined
+        const countsConflicts = skipReason === 'conflict' || skipReason === 'conflict-kept-local';
+        const skipCount = !countsConflicts || result.conflictedSections === undefined
             ? undefined
             : result.conflictedSections.length;
         await this.writeConfig(channel, {
@@ -570,22 +780,22 @@ export class AutoSyncScheduler {
             lastRunSkipCount: skipCount,
         });
     }
-    /** 连续失败 ≥ 3 → 通知（host.log.warn）。 */
+    /**
+     * 连续失败 ≥ 3 → 通知（host.log.warn）。
+     *
+     * issue #105：通知的持久痕迹只留历史 entry 的 notifiedAt。
+     * 此前这里把通知文案写进 autosync-config.lastRunMessage —— 那是「本轮错误原文」的字段，
+     * 一个字段两种语义，界面就无法判断该显示什么；而且 entry.notifiedAt 只在内存对象上改、
+     * 从未落盘（sync-history 当时只有 append），通知事实其实没留下。现在两者都走一处：
+     * 通知文案只进日志，notifiedAt 落盘到历史记录。
+     */
     maybeNotify(failures, historyId, nowIso, channel) {
-        if (failures >= 3) {
-            this.host.log.warn(`自动同步连续失败 ${failures} 次，请检查仓库配置/凭据（${channel}）`);
-            // 记录 notifiedAt（更新历史 entry）
-            void this.readHistoryFn().then(async (hist) => {
-                const entry = hist.autosyncEntries.find((e) => e.createdAt === nowIso);
-                if (entry) {
-                    entry.notifiedAt = nowIso;
-                    await this.writeConfig(channel, {
-                        ...(await this.readConfig(channel)),
-                        lastRunMessage: engineMsg('sync.autosyncConsecutiveFailureNotified', { count: failures }),
-                    });
-                }
-            }).catch(() => { });
-        }
+        if (failures < 3)
+            return;
+        this.host.log.warn(`自动同步连续失败 ${failures} 次，请检查仓库配置/凭据（${channel}）`);
+        // readHistory 走注入的 readHistoryFn（测试可替换），写入仍是原子落盘
+        void markAutosyncNotified(this.syncDir, nowIso, nowIso, { readHistory: this.readHistoryFn })
+            .catch(() => { });
     }
 }
 /**
@@ -636,12 +846,13 @@ export function syncIsConfigured(cfg) {
 /**
  * 缺省远端新快照检测（§3.2）：engine 实现了 hasNewRemoteSnapshot() → 调用；
  * 否则（测试 mock 未实现）保守返回 true（假设有新生，保持旧行为=每次都尝试拉取）。
+ * `listed` 透传给引擎：本轮已 list 过就直接复用，不再多跑一次网络往返。
  */
-async function defaultDetectRemoteNew(engine) {
+async function defaultDetectRemoteNew(engine, listed) {
     const fn = engine.hasNewRemoteSnapshot;
     if (typeof fn === 'function') {
         try {
-            return await fn.call(engine);
+            return await fn.call(engine, listed);
         }
         catch {
             return true; // 检测失败保守视为有新生，避免漏拉
@@ -653,6 +864,18 @@ async function defaultDetectRemoteNew(engine) {
  * 缺省本地变化检测（§3.1）：engine 实现了 hasLocalChanges() → 调用；
  * 否则（测试 mock 未实现）保守返回 true（假设有本地改动，保持旧行为=每次都尝试上传）。
  */
+/**
+ * 缺省 watcher 工厂 = 真实 fs.watch（SyncWatcher）。
+ * targets 由 watch-scope 的静态清单派生（纯函数、不读磁盘），profile 只影响 profiles/ 下的路径。
+ */
+function defaultMakeWatcher(opts) {
+    return new SyncWatcher({
+        homeDir: opts.homeDir,
+        targets: buildWatchTargets({ homeDir: opts.homeDir, profile: opts.profile }),
+        log: opts.log,
+        onFlush: opts.onFlush,
+    });
+}
 async function defaultDetectLocalChange(engine) {
     const fn = engine.hasLocalChanges;
     if (typeof fn === 'function') {

package/lib/sync/gist/gist-transport.d.ts

@@ -1,10 +1,16 @@
 import type { MsgFunc } from '../../core/msg-types.ts';
 import { SyncTransportError } from '../transport.ts';
-import type { SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
+import type { SyncProbeResult, SyncRetryOptions, SyncSnapshot, SyncSnapshotMeta, SyncTransport, SyncTransportErrorOptions } from '../transport.ts';
 /** 缺省 GitHub API 根 */
 export declare const GIST_DEFAULT_API_BASE_URL = "https://api.github.com";
 /** 缺省文件前缀 */
 export declare const GIST_DEFAULT_FILE_PREFIX = "dsh-sync";
+/**
+ * **gist 通道不做条件写**（issue #110，2026-10 实测）：`PATCH /gists/{id}` 对**任何**条件请求头
+ * 都直接回 400 —— `Conditional request headers are not allowed in unsafe requests unless supported
+ * by the endpoint`，与 ETag 强弱无关（同一请求去掉 If-Match 即 200）。故本通道的 PATCH 一律不带
+ * `If-Match`，也**没有**写前并发保护；要并发保护请用 git / webdav / s3 通道（那里的索引写是条件写）。
+ */
 /** 请求选项：headers / body / 覆盖默认超时（ms；0 = 不超时） */
 export interface GistRequestOptions {
     headers?: Record<string, string>;
@@ -61,6 +67,12 @@ export declare class GistTransport implements SyncTransport {
     download(id: string): Promise<SyncSnapshot>;
     /** 删除远端快照（不存在视为成功）：PATCH 置 null + 写回摘除后的索引。 */
     delete(id: string): Promise<void>;
+    /**
+     * 连通性探针（cloud-sync 借鉴项 ②③）：令牌有效性（GET /user）→ gist 可读 → 快照数 →
+     * 归属提示（gist 里已有不属于本前缀的文件时给出 warning 级 hint，绝不自动删别人的文件）。
+     * 只读：不打任何 PATCH。
+     */
+    probe(): Promise<SyncProbeResult>;
     private assertSafeId;
     private gistUrl;
     private snapshotFileName;
@@ -70,6 +82,11 @@ export declare class GistTransport implements SyncTransport {
     private send;
     /** 读 gist（含全部文件条目）；404 → 明确「gist 不存在或无权访问」 */
     private readGistFiles;
+    /**
+     * 读 gist 全量文件。响应 ETag **不用**：gist 的 PATCH 端点不接受任何条件请求头（issue #110 实测），
+     * 读到强/弱 ETag 都无处可用，故这里不再解析。
+     */
+    private readGist;
     /**
      * 取某个文件的内容：gist 载荷里直接有就用它；被 GitHub 截断（\`truncated\`）或内容缺失时
      * 回落 \`raw_url\` 重新下载（跨源跳转剥离 Authorization —— gh 的 raw 地址本身不可猜）。

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

@@ -152,7 +152,7 @@ export class GistTransport {
         this.assertSafeId(snapshot.id);
         const token = await this.tokenOnce();
         const meta = computeSnapshotMeta(snapshot);
-        const files = await this.readGistFiles(token);
+        const { files } = await this.readGist(token);
         const idxRaw = await this.readFileText(files, this.indexFileName, token);
         const idxBefore = idxRaw === null ? [] : this.parseIndex(idxRaw, this.gistUrl(), token);
         const existing = idxBefore.find((m) => m.id === snapshot.id);
@@ -196,7 +196,7 @@ export class GistTransport {
     async delete(id) {
         this.assertSafeId(id);
         const token = await this.tokenOnce();
-        const files = await this.readGistFiles(token);
+        const { files } = await this.readGist(token);
         const idxRaw = await this.readFileText(files, this.indexFileName, token);
         const idx = idxRaw === null ? [] : this.parseIndex(idxRaw, this.gistUrl(), token);
         const fileName = this.snapshotFileName(id);
@@ -216,6 +216,36 @@ export class GistTransport {
         }
     }
     /* ---------------- 内部实现 ---------------- */
+    /**
+     * 连通性探针（cloud-sync 借鉴项 ②③）：令牌有效性（GET /user）→ gist 可读 → 快照数 →
+     * 归属提示（gist 里已有不属于本前缀的文件时给出 warning 级 hint，绝不自动删别人的文件）。
+     * 只读：不打任何 PATCH。
+     */
+    async probe() {
+        const token = await this.tokenOnce();
+        const userUrl = this.o.apiBaseUrl + '/user';
+        const me = await this.send('GET', userUrl, token);
+        if (me.status === 401 || me.status === 403) {
+            const body = await this.safeText(me);
+            throw new GistTransportError(await this.failText('GET', userUrl, me, token, body), this.classify(me.status, body));
+        }
+        if (!me.ok) {
+            const body = await this.safeText(me);
+            throw new GistTransportError(await this.failText('GET', userUrl, me, token, body), this.classify(me.status, body));
+        }
+        const { files } = await this.readGist(token);
+        const idxRaw = await this.readFileText(files, this.indexFileName, token);
+        const count = idxRaw === null ? 0 : this.parseIndex(idxRaw, this.gistUrl(), token).length;
+        const prefix = this.o.filePrefix + '-';
+        const foreign = Object.keys(files).filter((name) => !name.startsWith(prefix)).length;
+        return {
+            message: this.o.msg('sync.gist.probeOk', { count: String(count) }),
+            snapshotCount: count,
+            ...(foreign > 0
+                ? { hint: this.o.msg('sync.gist.probeForeignContent', { count: String(foreign), prefix: this.o.filePrefix }) }
+                : {}),
+        };
+    }
     assertSafeId(id) {
         if (typeof id !== 'string' || !SAFE_ID_RE.test(id) || RESERVED_IDS.has(id)) {
             throw new GistTransportError(this.o.msg('sync.gist.invalidSnapshotId', { id: JSON.stringify(id) }));
@@ -245,6 +275,8 @@ export class GistTransport {
                 'content-type': 'application/json',
                 'X-GitHub-Api-Version': GITHUB_API_VERSION,
                 ...(token !== '' ? { authorization: 'Bearer ' + token } : {}),
+                // 附加请求头（本通道当前不注入条件头：gist 端点拒绝任何条件请求头，见文首说明）
+                ...(opts.headers ?? {}),
             };
         try {
             return await this.o.request(method, url, {
@@ -265,6 +297,13 @@ export class GistTransport {
     }
     /** 读 gist（含全部文件条目）；404 → 明确「gist 不存在或无权访问」 */
     async readGistFiles(token) {
+        return (await this.readGist(token)).files;
+    }
+    /**
+     * 读 gist 全量文件。响应 ETag **不用**：gist 的 PATCH 端点不接受任何条件请求头（issue #110 实测），
+     * 读到强/弱 ETag 都无处可用，故这里不再解析。
+     */
+    async readGist(token) {
         const url = this.gistUrl();
         const res = await this.send('GET', url, token);
         if (res.status === 404) {
@@ -285,7 +324,7 @@ export class GistTransport {
         if (files === null || typeof files !== 'object' || Array.isArray(files)) {
             throw new GistTransportError(this.o.msg('sync.gist.indexInvalid', { url, err: 'files missing' }), { kind: 'protocol', retryable: false });
         }
-        return files;
+        return { files: files };
     }
     /**
      * 取某个文件的内容：gist 载荷里直接有就用它；被 GitHub 截断（\`truncated\`）或内容缺失时

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

@@ -16,6 +16,8 @@ export declare const gistZh: {
     readonly 'sync.gist.timeout': '{method} {url} 请求超时（{timeout}ms）';
     readonly 'sync.gist.indexInvalid': '{url} 解析失败或结构非法: {err}';
     readonly 'sync.gist.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}';
+    readonly 'sync.gist.probeOk': '连接正常（Gist 可读写，远端 {count} 份快照）';
+    readonly 'sync.gist.probeForeignContent': '该 Gist 里已有 {count} 个不属于本插件的文件：请确认这是你的同步专用 Gist（前缀 {prefix}），否则可能覆盖别人的数据';
 };
 export declare const gistEn: Record<keyof typeof gistZh, string>;
 /** 缺省（zh）Gist 通道翻译器。 */

package/lib/sync/gist/messages.js

@@ -22,6 +22,9 @@ export const gistZh = {
     'sync.gist.timeout': '{method} {url} 请求超时（{timeout}ms）',
     'sync.gist.indexInvalid': '{url} 解析失败或结构非法: {err}',
     'sync.gist.snapshotInvalid': '快照 {id} 解析失败或结构非法: {err}',
+    // ---- cloud-sync 借鉴项 ②③：探针 / 归属提示（①条件写已按 issue #110 移除，见 gist-transport.ts）----
+    'sync.gist.probeOk': '连接正常（Gist 可读写，远端 {count} 份快照）',
+    'sync.gist.probeForeignContent': '该 Gist 里已有 {count} 个不属于本插件的文件：请确认这是你的同步专用 Gist（前缀 {prefix}），否则可能覆盖别人的数据',
 };
 export const gistEn = {
     'sync.gist.gistIdRequired': 'gistId must be a non-empty string (create a (secret) gist on GitHub and paste its id)',
@@ -40,6 +43,8 @@ export const gistEn = {
     'sync.gist.timeout': '{method} {url} request timed out ({timeout}ms)',
     'sync.gist.indexInvalid': '{url} failed to parse or is structurally invalid: {err}',
     'sync.gist.snapshotInvalid': 'Snapshot {id} failed to parse or is structurally invalid: {err}',
+    'sync.gist.probeOk': 'Connection OK (gist readable and writable, {count} remote snapshots)',
+    'sync.gist.probeForeignContent': 'This gist already contains {count} files that are not ours: confirm it is your dedicated sync gist (prefix {prefix}) or you may overwrite someone else’s data',
 };
 /** 缺省（zh）Gist 通道翻译器。 */
 export const gistMsg = makeCatalogMsg(gistZh, gistEn, 'zh');