@pandablessing/dsh-user-sync 0.0.0-stage → 1.0.0

package/lib/index.js

@@ -0,0 +1,593 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isPackageId } from './archive.js';
+import { deriveAccountKey } from './auth.js';
+import { resolvePaths } from './paths.js';
+import { installMissing, planPluginRecovery } from './plugins.js';
+import { ALL_MODULES, scanAssets } from './scan.js';
+import { createScheduler } from './scheduler.js';
+import { loadState, saveState } from './state.js';
+import { createSync } from './sync.js';
+import { createApiTransport } from './transport/api.js';
+import { createFolderTransport } from './transport/folder.js';
+export const name = 'dsh-user-sync';
+/** 不硬依赖任何服务：依赖缺失时降级，不把条目停在 pending。 */
+export const inject = [];
+/** 非用户级模块：默认不选，首次勾选要提示一次。 */
+const NON_USER_LEVEL = ['projectMemory', 'sessions'];
+/**
+ * 记录插件自身错误。绝不向外抛：任何插件 bug 都不应阻止 DSH 启动。
+ * 日志落在 $DSH_HOME/user-sync/plugin-error.log（与状态文件同目录）。
+ * base 可显式传入，测试用它隔离到临时目录，避免污染真实日志。
+ */
+/** 找 DSH 运行时自带的 node 可执行文件（Electron 的 process.execPath 不能用）。 */
+function findRuntimeNode() {
+    const root = join(homedir(), '.dsh', 'dsh-runtimes');
+    try {
+        for (const dir of readdirSync(root, { withFileTypes: true })) {
+            if (!dir.isDirectory())
+                continue;
+            for (const candidate of [
+                join(root, dir.name, 'dependencies', 'node', 'bin', 'node.exe'),
+                join(root, dir.name, 'dependencies', 'node', 'bin', 'node'),
+            ]) {
+                if (existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    catch {
+        // 没有运行时就回退失败
+    }
+    return null;
+}
+const PLUGIN_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+export function logPluginError(where, error, base = process.env.DSH_HOME || join(homedir(), '.dsh')) {
+    const line = `${new Date().toISOString()} [${where}] ${error?.stack ?? String(error)}\n`;
+    try {
+        const dir = join(base, 'user-sync');
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(join(dir, 'plugin-error.log'), line);
+    }
+    catch {
+        // 写日志失败也不能抛
+    }
+    try {
+        console.error(`[dsh-user-sync] ${where}:`, error);
+    }
+    catch {
+        // 控制台不可用时忽略
+    }
+}
+const json = (data, status = 200) => new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json' } });
+export function apply(ctx) {
+    let logBase = process.env.DSH_HOME || join(homedir(), '.dsh');
+    const log = (where, error) => logPluginError(where, error, logBase);
+    try {
+        const profileContext = readService(ctx, 'profileContext');
+        const paths = resolvePaths({
+            profileContext,
+            env: process.env,
+            userHome: homedir(),
+        });
+        // 日志跟随本 profile 的 DSH 主目录；测试里即临时目录，不污染真实日志
+        logBase = paths.dshHome;
+        const statePath = join(paths.dshHome, 'user-sync', 'state.json');
+        const authPath = join(paths.dshHome, 'user-sync', 'auth.json');
+        const folderDir = join(paths.dshHome, 'user-sync', 'remote');
+        /**
+         * 传输选择：配了服务地址就用运营方 API，否则回退本地目录（无服务端调试）。
+         * 面板已隐藏「传输方式」，不再读 state.transport——避免历史设置把正式环境切成 folder。
+         */
+        const buildTransport = () => {
+            const state = loadState(statePath);
+            if (state.baseUrl) {
+                try {
+                    return createApiTransport({ baseUrl: state.baseUrl, authPath });
+                }
+                catch (error) {
+                    log('transport-api', error);
+                }
+            }
+            return createFolderTransport({ dir: folderDir });
+        };
+        const sync = createSync({
+            dshHome: paths.dshHome,
+            userHome: paths.userHome,
+            profileName: paths.profileName,
+            transport: buildTransport(),
+        });
+        const scheduler = createScheduler({ sync, statePath });
+        const scanSummary = () => {
+            // 计数按全部模块扫描，勾选只决定打包范围；否则未勾选的模块会显示 0，误导用户。
+            const { entries, errors, skipped, totalBytes } = scanAssets({
+                dshHome: paths.dshHome,
+                userHome: paths.userHome,
+                profileName: paths.profileName,
+                modules: ALL_MODULES,
+            });
+            const counts = {};
+            for (const entry of entries)
+                counts[entry.module] = (counts[entry.module] ?? 0) + 1;
+            // 插件清单模块展示「装了什么插件」：直接读 profile 的 package.json dependencies
+            let plugins = [];
+            try {
+                const pkg = JSON.parse(readFileSync(join(paths.profileDir, 'package.json'), 'utf8'));
+                plugins = Object.entries(pkg.dependencies ?? {}).map(([name, spec]) => ({ name, spec: String(spec) }));
+            }
+            catch {
+                plugins = [];
+            }
+            // 已勾选模块的统计：面板「已选」口径，避免把未选的会话体积算进去
+            const selectedModules = sync.getModules();
+            const selected = entries.filter((entry) => selectedModules.includes(entry.module));
+            // 同步范围内（不含会话）的统计：面板「全部」显示用，避免会话体积误导
+            const syncable = entries.filter((entry) => entry.module !== 'sessions');
+            return {
+                modules: selectedModules,
+                allModules: ALL_MODULES,
+                counts,
+                plugins,
+                selectedFiles: selected.length,
+                syncableFiles: syncable.length,
+                syncableBytes: syncable.reduce((sum, entry) => sum + entry.size, 0),
+                selectedBytes: selected.reduce((sum, entry) => sum + entry.size, 0),
+                // 每个模块具体包含哪些文件：面板「查看」展开用，按模块分组、路径升序
+                files: entries.map((entry) => ({ module: entry.module, path: entry.path, size: entry.size, title: entry.title ?? null })),
+                totalFiles: entries.length,
+                totalBytes,
+                errors,
+                skipped: skipped.slice(0, 50),
+            };
+        };
+        /** handler 异常落盘：面板显示「接口错误」时可直接从 state.diagnostics.lastError 定位。 */
+        const recordHandlerError = (where, error) => {
+            log(`handler-${where}`, error);
+            try {
+                const state = loadState(statePath);
+                state.diagnostics = {
+                    ...(state.diagnostics ?? {}),
+                    lastError: {
+                        at: new Date().toISOString(),
+                        where,
+                        message: error?.message ?? String(error),
+                        stack: String(error?.stack ?? error).slice(0, 1500),
+                    },
+                };
+                saveState(statePath, state);
+            }
+            catch {
+                // 落盘失败不影响响应
+            }
+        };
+        let pluginManager = null;
+        const routes = [
+            {
+                // 最小同步路由：用于区分「同步 handler 本身不可用」与「status/scan 具体逻辑抛错」
+                path: '/api/dsh-user-sync/ping',
+                methods: ['GET'],
+                requestBody: 'buffered',
+                fetch: async () => {
+                    try {
+                        appendFileSync(join(logBase, 'user-sync', 'ping.log'), `${new Date().toISOString()} ping called\n`);
+                    }
+                    catch {
+                        // 诊断失败不影响响应
+                    }
+                    return new Response('pong');
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/status',
+                methods: ['GET'],
+                requestBody: 'buffered',
+                fetch: () => {
+                    try {
+                        const state = loadState(statePath);
+                        const scheduled = scheduler.settings();
+                        // 宿主侧探针：与 /scan 同一条扫描路径，便于对照面板是否拿不到数据
+                        let probe = null;
+                        try {
+                            const summary = scanSummary();
+                            probe = { totalFiles: summary.totalFiles, counts: summary.counts, errors: summary.errors.length };
+                        }
+                        catch (error) {
+                            probe = { error: error.message };
+                        }
+                        return json({
+                            installed: true,
+                            version: PLUGIN_VERSION,
+                            dshHome: paths.dshHome,
+                            profile: paths.profileName,
+                            resolvedBy: paths.resolvedBy,
+                            probe,
+                            transport: sync.getTransportId(),
+                            transportSetting: state.transport ?? 'folder',
+                            baseUrl: state.baseUrl ?? null,
+                            account: { hint: state.accountKeyHint ?? null, paired: Boolean(state.pairedAt) },
+                            deviceId: state.deviceId ?? null,
+                            lastApplied: state.lastApplied ?? null,
+                            lastUploaded: state.lastUploaded ?? null,
+                            consent: state.consent ?? null,
+                            warnedModules: state.warnedModules ?? [],
+                            diagnostics: state.diagnostics ?? null,
+                            modules: sync.getModules(),
+                            scheduler: {
+                                autoCheck: scheduled.autoCheck,
+                                intervalHours: scheduled.intervalHours,
+                                lastCheckAt: scheduled.lastCheckAt,
+                                lastDecision: scheduled.lastDecision,
+                                lastCheckError: scheduled.lastCheckError,
+                            },
+                        });
+                    }
+                    catch (error) {
+                        recordHandlerError('status', error);
+                        return json({ error: 'E_STATUS', detail: String(error?.stack ?? error) }, 500);
+                    }
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/scan',
+                methods: ['GET'],
+                requestBody: 'buffered',
+                fetch: () => {
+                    try {
+                        const summary = scanSummary();
+                        // 落盘诊断：面板显示异常时可直接从 state 读到宿主真实扫描结果
+                        try {
+                            const state = loadState(statePath);
+                            state.diagnostics = {
+                                ...(state.diagnostics ?? {}),
+                                lastScan: {
+                                    at: new Date().toISOString(),
+                                    dshHome: paths.dshHome,
+                                    profile: paths.profileName,
+                                    modules: summary.modules,
+                                    totalFiles: summary.totalFiles,
+                                    counts: summary.counts,
+                                },
+                            };
+                            saveState(statePath, state);
+                        }
+                        catch {
+                            // 诊断失败不影响扫描
+                        }
+                        return json(summary);
+                    }
+                    catch (error) {
+                        recordHandlerError('scan', error);
+                        return json({ error: error.message, detail: String(error?.stack ?? '') }, 500);
+                    }
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/config',
+                methods: ['GET', 'POST'],
+                requestBody: 'buffered',
+                fetch: async (request) => {
+                    if (request.method === 'GET') {
+                        const state = loadState(statePath);
+                        const settings = scheduler.settings();
+                        return json({
+                            modules: sync.getModules(),
+                            autoCheck: settings.autoCheck,
+                            intervalHours: settings.intervalHours,
+                            transport: state.transport ?? 'folder',
+                            baseUrl: state.baseUrl ?? null,
+                        });
+                    }
+                    const body = (await request.json());
+                    const state = loadState(statePath);
+                    if (Array.isArray(body?.modules)) {
+                        const requested = body.modules.filter((item) => ALL_MODULES.includes(item));
+                        if (requested.length === 0)
+                            return json({ error: 'E_NO_VALID_MODULE' }, 400);
+                        const warned = Array.isArray(state.warnedModules) ? state.warnedModules : [];
+                        const newly = requested.filter((item) => NON_USER_LEVEL.includes(item) && !warned.includes(item));
+                        if (newly.length > 0 && body?.confirmNonUserLevel !== true) {
+                            return json({ warning: newly, note: '非用户级内容可能包含工作内容' });
+                        }
+                        // 注意：必须写进本函数的 state 对象，由末尾统一 saveState；
+                        // 之前调 sync.setModules（内部写盘）后再用旧 state 覆盖，导致设置被回滚。
+                        state.modules = requested;
+                        if (newly.length > 0) {
+                            state.warnedModules = [...new Set([...warned, ...newly])];
+                        }
+                    }
+                    if (typeof body?.transport === 'string') {
+                        if (!['folder', 'api'].includes(body.transport))
+                            return json({ error: 'E_BAD_TRANSPORT' }, 400);
+                        state.transport = body.transport;
+                    }
+                    if (typeof body?.baseUrl === 'string') {
+                        const url = body.baseUrl.trim();
+                        if (url && !/^https?:\/\//.test(url))
+                            return json({ error: 'E_BAD_BASE_URL' }, 400);
+                        state.baseUrl = url || null;
+                    }
+                    if (typeof body?.autoCheck === 'boolean')
+                        state.autoCheck = body.autoCheck;
+                    if (body?.intervalHours !== undefined && Number.isFinite(Number(body.intervalHours))) {
+                        state.intervalHours = Math.min(168, Math.max(1, Number(body.intervalHours)));
+                    }
+                    saveState(statePath, state);
+                    try {
+                        sync.setTransport(buildTransport());
+                    }
+                    catch (error) {
+                        log('set-transport', error);
+                    }
+                    return json({
+                        modules: Array.isArray(state.modules) ? state.modules : sync.getModules(),
+                        autoCheck: state.autoCheck ?? true,
+                        intervalHours: state.intervalHours ?? 6,
+                        transport: state.transport ?? 'folder',
+                        baseUrl: state.baseUrl ?? null,
+                        transportNow: sync.getTransportId(),
+                    });
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/consent',
+                methods: ['POST'],
+                requestBody: 'buffered',
+                fetch: async (request) => {
+                    const body = (await request.json());
+                    const state = loadState(statePath);
+                    if (body?.accepted) {
+                        state.consent = { acceptedAt: new Date().toISOString(), version: 1 };
+                    }
+                    else {
+                        delete state.consent;
+                    }
+                    saveState(statePath, state);
+                    return json({ consent: state.consent ?? null });
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/upload',
+                methods: ['POST'],
+                requestBody: 'buffered',
+                fetch: async () => {
+                    const state = loadState(statePath);
+                    if (!state.consent?.acceptedAt) {
+                        return json({ ok: false, code: 'E_CONSENT_REQUIRED', detail: '请先同意隐私说明再上传' }, 403);
+                    }
+                    return json(await sync.upload());
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/check',
+                methods: ['GET'],
+                requestBody: 'buffered',
+                fetch: async () => {
+                    const result = (await sync.check());
+                    if (pluginManager && result.meta?.dependencies) {
+                        try {
+                            const bundles = await pluginManager.listBundles();
+                            const installed = bundles.filter((bundle) => bundle.installed).map((bundle) => bundle.name);
+                            const dependencies = (result.meta?.dependencies ?? {});
+                            result.plugins = planPluginRecovery({ dependencies, installed });
+                        }
+                        catch (error) {
+                            result.plugins = { error: error.message };
+                        }
+                    }
+                    return json(result);
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/install',
+                methods: ['POST'],
+                requestBody: 'buffered',
+                fetch: async (request) => {
+                    const pm = pluginManager;
+                    if (!pm)
+                        return json({ ok: false, error: 'E_NO_PLUGIN_MANAGER' }, 503);
+                    const body = (await request.json());
+                    const packages = Array.isArray(body?.packages)
+                        ? body.packages.filter((item) => typeof item?.name === 'string')
+                        : [];
+                    if (packages.length === 0)
+                        return json({ ok: false, error: 'E_NO_PACKAGES' }, 400);
+                    const results = await installMissing({
+                        plan: { missing: packages },
+                        installBundle: (spec) => pm.installBundle(spec),
+                    });
+                    // pnpm 的 .modules.yaml 可能残留「已安装」记录，导致 installBundle 返回成功却不落盘；
+                    // 装完检查目录，缺失时强制重装（pnpm install --force），保证「装了就是真的装了」。
+                    const missingDirs = packages.filter((item) => !existsSync(join(paths.profileDir, 'node_modules', item.name)));
+                    if (missingDirs.length > 0) {
+                        try {
+                            // process.execPath 是 Electron 主程序，必须找 DSH 运行时的 node
+                            const runtime = findRuntimeNode();
+                            const pnpmCjs = runtime ? join(dirname(runtime), '..', '..', 'pnpm', 'bin', 'pnpm.cjs') : '';
+                            if (!runtime || !existsSync(pnpmCjs))
+                                throw new Error('runtime node/pnpm not found');
+                            execFileSync(runtime, [pnpmCjs, 'install', '--force'], {
+                                cwd: paths.profileDir,
+                                stdio: 'ignore',
+                                timeout: 300000,
+                            });
+                            for (const item of missingDirs) {
+                                const ok = existsSync(join(paths.profileDir, 'node_modules', item.name));
+                                const entry = results.find((result) => result.name === item.name);
+                                if (entry)
+                                    entry.ok = ok;
+                            }
+                        }
+                        catch (error) {
+                            log('pnpm-force', error);
+                        }
+                    }
+                    return json({ ok: results.every((item) => item.ok), results });
+                },
+            },
+            {
+                path: '/api/dsh-user-sync/apply',
+                methods: ['POST'],
+                requestBody: 'buffered',
+                fetch: async (request) => {
+                    const body = (await request.json());
+                    if (!isPackageId(String(body?.name ?? '')))
+                        return json({ error: 'E_BAD_NAME' }, 400);
+                    return json(await sync.applyRemote(String(body.name)));
+                },
+            },
+        ];
+        // pluginManager 也可能晚到；用于缺失插件检测与安装（§7.8）
+        try {
+            ctx.inject?.(['pluginManager'], (c) => {
+                try {
+                    pluginManager = c.get('pluginManager');
+                }
+                catch (error) {
+                    log('plugin-manager', error);
+                }
+            });
+        }
+        catch (error) {
+            log('plugin-manager-inject', error);
+        }
+        // PLUG-07 探针：本插件条目是否在 configEditor.entries() 可见（设置面板能否自助写回）
+        try {
+            ctx.inject?.(['configEditor'], (c) => {
+                try {
+                    const editor = c.get('configEditor');
+                    const entries = typeof editor?.entries === 'function' ? editor.entries() : [];
+                    const visible = entries.some((entry) => entry?.options?.id === 'user-sync');
+                    const state = loadState(statePath);
+                    state.diagnostics = {
+                        ...(state.diagnostics ?? {}),
+                        configEditorVisible: visible,
+                        configEditorEntries: entries.length,
+                        checkedAt: new Date().toISOString(),
+                    };
+                    saveState(statePath, state);
+                }
+                catch (error) {
+                    log('config-editor', error);
+                }
+            });
+        }
+        catch (error) {
+            log('config-editor-inject', error);
+        }
+        // 启动时把宿主扫描结果写进 diagnostics：面板异常时可直接从 state 读到宿主真相
+        try {
+            const summary = scanSummary();
+            const state = loadState(statePath);
+            state.diagnostics = {
+                ...(state.diagnostics ?? {}),
+                scanAtBoot: {
+                    at: new Date().toISOString(),
+                    dshHome: paths.dshHome,
+                    userHome: paths.userHome,
+                    profile: paths.profileName,
+                    totalFiles: summary.totalFiles,
+                    counts: summary.counts,
+                },
+            };
+            saveState(statePath, state);
+        }
+        catch (error) {
+            log('scan-at-boot', error);
+        }
+        // connection 服务在 apply 时可能还没就绪（web 启动顺序），必须用 ctx.inject 等待；
+        // 直接 ctx.get 会拿到 undefined，导致所有 API 路由静默不注册、面板按钮全部 404。
+        try {
+            ctx.inject?.(['connection'], (c) => {
+                try {
+                    const connection = c.get('connection');
+                    const register = connection?.fetch?.register;
+                    if (typeof register !== 'function') {
+                        log('routes', new Error('connection 缺少 fetch.register'));
+                        return;
+                    }
+                    for (const route of routes) {
+                        c.effect(() => register(route), `dsh-user-sync: ${route.path}`);
+                    }
+                }
+                catch (error) {
+                    log('routes', error);
+                }
+            });
+        }
+        catch (error) {
+            log('routes-inject', error);
+        }
+        // 官方账号自动配对：拿 accountKey 后按配置自动 register/login，用户无感（§9.3、§17.2）。
+        try {
+            ctx.inject?.(['deepseekAccount'], (c) => {
+                void (async () => {
+                    try {
+                        const account = c.get('deepseekAccount');
+                        const profile = await account.getProfile({
+                            version: PLUGIN_VERSION,
+                            locale: 'zh-CN',
+                            timezoneOffsetSeconds: -new Date().getTimezoneOffset() * 60,
+                        });
+                        const accountId = profile?.status === 'ready' ? profile.value?.id : null;
+                        if (!accountId)
+                            return;
+                        const accountKey = deriveAccountKey(accountId);
+                        const state = loadState(statePath);
+                        state.accountKeyHint = accountKey.slice(0, 6);
+                        saveState(statePath, state);
+                        if (state.transport === 'api' && state.baseUrl) {
+                            const api = createApiTransport({ baseUrl: state.baseUrl, authPath });
+                            await api.register(accountKey);
+                            const next = loadState(statePath);
+                            next.pairedAt = new Date().toISOString();
+                            saveState(statePath, next);
+                        }
+                    }
+                    catch (error) {
+                        log('pair', error);
+                    }
+                })();
+            });
+        }
+        catch (error) {
+            log('pair-inject', error);
+        }
+        ctx.effect?.(() => {
+            scheduler.start();
+            return () => scheduler.stop();
+        }, 'dsh-user-sync: scheduler');
+        ctx.effect?.(() => () => {
+            // 宿主半边没有常驻资源；生命周期钩子留给后续清理
+        }, 'dsh-user-sync: lifecycle');
+        try {
+            ctx.logger?.('dsh-user-sync')?.info?.('已挂载', { dshHome: paths.dshHome, profile: paths.profileName });
+        }
+        catch {
+            // logger 形态不同不影响挂载
+        }
+        return { paths, sync, scheduler, routes };
+    }
+    catch (error) {
+        log('apply', error);
+        return undefined;
+    }
+}
+function readService(ctx, key) {
+    try {
+        return ctx.get?.(key, false);
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/lww.js

@@ -0,0 +1,64 @@
+/**
+ * 新覆盖旧判定（G7）。
+ * 只按包级 createdAt 比较，不看文件 mtime；两侧相差 ≤ 5 分钟视为并发，转人工确认。
+ */
+export const CLOCK_SKEW_MS = 5 * 60 * 1000;
+export function decide({ remote = null, lastApplied = null, lastUploaded = null, localFiles, appliedFiles, clockSkewMs = CLOCK_SKEW_MS, } = {}) {
+    const localChanged = detectLocalChanges(localFiles, appliedFiles);
+    if (!remote) {
+        return { action: 'push', reason: 'remote-missing', localChanged, remoteUpdated: false };
+    }
+    // 远端就是本机上次上传的那份包：只看本机在上传后有没有再改动。
+    // 否则「刚上传 → 再检查」会被误判成两侧并发。
+    if (lastUploaded?.packageId && remote.packageId && lastUploaded.packageId === remote.packageId) {
+        return localChanged
+            ? { action: 'push', reason: 'local-changed-since-upload', localChanged, remoteUpdated: false }
+            : { action: 'skip', reason: 'in-sync', localChanged, remoteUpdated: false };
+    }
+    const remoteUpdated = !lastApplied || compareTime(remote.createdAt, lastApplied.createdAt) > 0;
+    if (!localChanged && !remoteUpdated) {
+        return { action: 'skip', reason: 'in-sync', localChanged, remoteUpdated };
+    }
+    if (remoteUpdated && !localChanged) {
+        return { action: 'pull', reason: 'remote-newer', localChanged, remoteUpdated };
+    }
+    if (!remoteUpdated && localChanged) {
+        return { action: 'push', reason: 'local-newer', localChanged, remoteUpdated };
+    }
+    // 两侧都有更新：拿远端包与「本机上次上传」比；相差 ≤ 阈值转人工
+    const remoteTime = toEpoch(remote.createdAt);
+    const uploadTime = toEpoch(lastUploaded?.createdAt);
+    const skewMs = Math.abs(remoteTime - uploadTime);
+    if (skewMs <= clockSkewMs) {
+        return { action: 'confirm', reason: 'clock-skew', localChanged, remoteUpdated, skewMs };
+    }
+    if (remoteTime > uploadTime) {
+        return { action: 'pull', reason: 'remote-newer', localChanged, remoteUpdated, skewMs };
+    }
+    return { action: 'push', reason: 'local-newer', localChanged, remoteUpdated, skewMs };
+}
+/** 解析时间字符串为毫秒；无法解析视为 0（最旧）。 */
+export function toEpoch(value) {
+    if (value === null || value === undefined)
+        return 0;
+    const time = Date.parse(value);
+    return Number.isFinite(time) ? time : 0;
+}
+/** 比较两个时间字符串；缺省视为 0（最旧）。 */
+export function compareTime(a, b) {
+    const ta = toEpoch(a);
+    const tb = toEpoch(b);
+    return ta === tb ? 0 : ta > tb ? 1 : -1;
+}
+/** 本地是否相对上次应用有改动：新增、删除、内容变化都算。 */
+export function detectLocalChanges(localFiles, appliedFiles) {
+    if (!localFiles || !appliedFiles)
+        return false;
+    if (localFiles.size !== appliedFiles.size)
+        return true;
+    for (const [path, sha] of localFiles) {
+        if (appliedFiles.get(path) !== sha)
+            return true;
+    }
+    return false;
+}