creditdaddy 0.8.0

package/src/qoderUmid.js

@@ -0,0 +1,177 @@
+/**
+ * Qoder 设备身份组件 —— 给没有 Qoder 客户端的 Linux（fnOS / NAS）提供国际版签到所需的风控身份。
+ *
+ * Qoder 国际版只向带 Cosy-MachineToken / Code / Type 的请求下发「每天领 100 Credits」，
+ * 这三个值由 Qoder 的 UMID 程序（runtime-info）生成。桌面端客户端自带它；官方 CLI
+ * @qoder-ai/qodercli 则把各平台的 UMID 二进制以 base64 内嵌在 bundle/qodercli.js 里，Linux x64 / arm64 都有。
+ *
+ * 这里在用户确认后从 npm 仓库下载官方 qodercli 包（校验 npm 的 sha512 integrity），
+ * 按本机 CPU 架构取出对应的 ELF，试跑一次确认能产出身份，再存到 ~/.creditdaddy/qoder-umid/。
+ * 不随 CreditDaddy 分发该二进制；调用方式与 qodercli 一致：runtime-info <env>，第一行输出 JSON。
+ * env：国际版 4（SINGAPORE，qodercli 的全球区取值），国内版 0（ONLINE）。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import zlib from 'node:zlib';
+import { execFile } from 'node:child_process';
+import { dataDir } from './store.js';
+import { logger } from './logger.js';
+
+const PKG = '@qoder-ai/qodercli';
+const REGISTRIES = ['https://registry.npmmirror.com', 'https://registry.npmjs.org'];
+const ELF_MACHINE = { x64: 62, arm64: 183 };
+const BUNDLE_ENTRY = 'package/bundle/qodercli.js';
+const FETCH_TIMEOUT_MS = 180_000;
+export const CLI_RISK_ENV = { qoder: 4, 'qoder-cn': 0 };
+
+export function umidSupported(platform = process.platform, arch = process.arch) {
+  return platform === 'linux' && Boolean(ELF_MACHINE[arch]);
+}
+
+const dir = () => path.join(dataDir(), 'qoder-umid');
+const binPath = () => path.join(dir(), 'runtime-info');
+const manifestPath = () => path.join(dir(), 'manifest.json');
+
+/** 已安装的组件：{ path, version, arch, sha256, installedAt, registry }；未安装返回 null */
+export function installedUmid() {
+  if (!umidSupported()) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(manifestPath(), 'utf8'));
+    if (!fs.existsSync(binPath()) || m.arch !== process.arch) return null;
+    return { ...m, path: binPath() };
+  } catch { return null; }
+}
+
+// ── 纯函数（便于单测） ──
+
+/** 最小 tar 解析：按名字取一个普通文件的内容 */
+export function tarEntry(tar, wanted) {
+  let off = 0;
+  const cstr = (b, s, n) => { const x = b.subarray(s, s + n); const z = x.indexOf(0); return x.subarray(0, z < 0 ? n : z).toString('utf8'); };
+  let longName = null;
+  while (off + 512 <= tar.length) {
+    const h = tar.subarray(off, off + 512);
+    if (h.every((b) => b === 0)) break;
+    const size = parseInt(cstr(h, 124, 12).trim() || '0', 8);
+    const type = String.fromCharCode(h[156] || 48);
+    const prefix = cstr(h, 345, 155);
+    let name = longName || (prefix ? prefix + '/' : '') + cstr(h, 0, 100);
+    longName = null;
+    const body = tar.subarray(off + 512, off + 512 + size);
+    off += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'L') { longName = body.toString('utf8').replace(/\0+$/, ''); continue; }
+    if (type === 'x') {   // pax 扩展头里的 path 覆盖下一个条目的名字
+      const m = /\d+ path=([^\n]+)\n/.exec(body.toString('utf8'));
+      if (m) longName = m[1];
+      continue;
+    }
+    if ((type === '0' || type === '\0') && name === wanted) return body;
+  }
+  return null;
+}
+
+/** 在 qodercli bundle 文本里找内嵌的 ELF（base64 字面量），按 e_machine 挑出本机架构 */
+export function extractElf(jsText, machine) {
+  const MARK = '"f0VMRgIB';   // "\x7fELF" + 64 位 + 小端 的 base64 开头
+  let i = jsText.indexOf(MARK);
+  while (i >= 0) {
+    const start = i + 1;
+    const end = jsText.indexOf('"', start);
+    if (end < 0) break;
+    const head = Buffer.from(jsText.slice(start, start + 28), 'base64');
+    if (head.length >= 20 && head.readUInt16LE(18) === machine) {
+      return Buffer.from(jsText.slice(start, end), 'base64');
+    }
+    i = jsText.indexOf(MARK, end);
+  }
+  return null;
+}
+
+/** npm integrity（sha512-<base64>）校验 */
+export function checkIntegrity(buf, integrity) {
+  const m = /^sha512-(.+)$/.exec(String(integrity || '').split(/\s+/)[0]);
+  if (!m) return false;
+  return crypto.createHash('sha512').update(buf).digest('base64') === m[1];
+}
+
+// ── 安装 ──
+
+async function fetchBuf(url) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!res.ok) throw new Error(`HTTP ${res.status}：${url}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+function testRun(file) {
+  return new Promise((resolve, reject) => {
+    execFile(file, [String(CLI_RISK_ENV.qoder)], { timeout: 30_000, maxBuffer: 1 << 20 }, (err, stdout) => {
+      try {
+        const j = JSON.parse(String(stdout).split('\n')[0]);
+        if (typeof j.machineToken === 'string' && j.machineToken && j.machineCode && j.machineType) return resolve(j);
+      } catch {}
+      reject(new Error('组件试运行失败' + (err ? '：' + err.message : '（输出里没有设备身份）')));
+    });
+  });
+}
+
+let installing = null;
+
+/** 下载官方 qodercli 包并提取本机架构的 UMID；并发调用共用同一次安装 */
+export function installUmid() {
+  if (!installing) installing = doInstall().finally(() => { installing = null; });
+  return installing;
+}
+export const umidInstalling = () => Boolean(installing);
+
+async function doInstall() {
+  if (!umidSupported()) throw new Error(`当前平台（${process.platform}/${process.arch}）不需要或不支持该组件`);
+  const errors = [];
+  for (const registry of REGISTRIES) {
+    try {
+      const meta = JSON.parse((await fetchBuf(`${registry}/${PKG.replace('/', '%2f')}/latest`)).toString('utf8'));
+      const { tarball, integrity } = meta.dist || {};
+      if (!tarball || !integrity) throw new Error('包元数据缺少 tarball / integrity');
+      logger.info('UMID', `下载 ${PKG}@${meta.version}（${registry}）`);
+      const tgz = await fetchBuf(tarball);
+      if (!checkIntegrity(tgz, integrity)) throw new Error('下载内容与 npm integrity 不一致');
+      const bundle = tarEntry(zlib.gunzipSync(tgz), BUNDLE_ENTRY);
+      if (!bundle) throw new Error(`包里没有 ${BUNDLE_ENTRY}（qodercli 结构可能变化）`);
+      const elf = extractElf(bundle.toString('latin1'), ELF_MACHINE[process.arch]);
+      if (!elf) throw new Error(`qodercli ${meta.version} 里没有 ${process.arch} 的 UMID 程序（结构可能变化）`);
+
+      fs.mkdirSync(dir(), { recursive: true, mode: 0o700 });
+      const tmp = binPath() + '.' + process.pid + '.tmp';
+      fs.writeFileSync(tmp, elf, { mode: 0o755 });
+      try { await testRun(tmp); } catch (e) { fs.rmSync(tmp, { force: true }); throw e; }
+      fs.renameSync(tmp, binPath());
+      const manifest = {
+        version: meta.version, arch: process.arch, registry,
+        sha256: crypto.createHash('sha256').update(elf).digest('hex'),
+        installedAt: new Date().toISOString(),
+      };
+      fs.writeFileSync(manifestPath(), JSON.stringify(manifest, null, 2), { mode: 0o600 });
+      logger.info('UMID', `设备身份组件已安装：qodercli ${meta.version} / ${process.arch}`);
+      return { ...manifest, path: binPath() };
+    } catch (e) {
+      errors.push(`${registry}：${e.message}`);
+      logger.warn('UMID', `从 ${registry} 安装失败：${e.message}`);
+    }
+  }
+  throw new Error('设备身份组件安装失败 —— ' + errors.join('；'));
+}
+
+export function removeUmid() {
+  fs.rmSync(dir(), { recursive: true, force: true });
+}
+
+/** 面板 / 状态接口用的摘要 */
+export function umidInfo() {
+  const m = installedUmid();
+  return {
+    supported: umidSupported(),
+    installing: umidInstalling(),
+    installed: m ? { version: m.version, arch: m.arch, installedAt: m.installedAt } : null,
+  };
+}

package/src/store.js

@@ -0,0 +1,187 @@
+/**
+ * 本地账号存储 — 数据全部留在本机（参考 WorkDaddy 的数据边界原则）。
+ *
+ * 目录：$CREDITDADDY_HOME（兼容旧的 $QODERDADDY_HOME；默认 ~/.creditdaddy）
+ *   accounts.json  账号列表（含 token，0600 权限）
+ *   state.json     运行状态（签到完成日历等）
+ * 项目曾名 QoderDaddy：默认目录不存在而 ~/.qoderdaddy 存在时，首次访问自动复制过来（旧目录保留）。
+ *
+ * 写入采用 原子写（临时文件 + rename），避免进程中断损坏数据。
+ */
+
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { PROVIDERS, productOf } from './constants.js';
+
+let migrated = false;
+
+/** 从旧版 ~/.qoderdaddy 复制数据到新目录（只在新目录尚不存在时执行一次） */
+function migrateLegacyDir(target) {
+  migrated = true;
+  const legacy = path.join(os.homedir(), '.qoderdaddy');
+  try {
+    if (fsSync.existsSync(target) || !fsSync.existsSync(legacy)) return;
+    fsSync.cpSync(legacy, target, { recursive: true, errorOnExist: false });
+    fsSync.writeFileSync(path.join(target, 'MIGRATED_FROM_QODERDADDY'), new Date().toISOString());
+  } catch {}
+}
+
+export function dataDir() {
+  const explicit = process.env.CREDITDADDY_HOME || process.env.QODERDADDY_HOME;
+  if (explicit) return explicit;
+  const target = path.join(os.homedir(), '.creditdaddy');
+  if (!migrated) migrateLegacyDir(target);
+  return target;
+}
+
+const ACCOUNTS_FILE = () => path.join(dataDir(), 'accounts.json');
+const STATE_FILE = () => path.join(dataDir(), 'state.json');
+
+async function ensureDir() {
+  await fs.mkdir(dataDir(), { recursive: true, mode: 0o700 });
+}
+
+/** 原子写：临时文件 + rename，失败不留半截文件 */
+export async function atomicWrite(file, content) {
+  const tmp = path.join(
+    path.dirname(file),
+    `.tmp-${path.basename(file)}-${crypto.randomBytes(4).toString('hex')}`
+  );
+  await fs.writeFile(tmp, content, { mode: 0o600 });
+  await fs.rename(tmp, file);
+}
+
+async function readJson(file, fallback) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (e) {
+    if (e.code === 'ENOENT') return fallback;
+    throw new Error(`读取 ${file} 失败: ${e.message}`);
+  }
+}
+
+// ─── 账号 ───
+
+export async function loadAccounts() {
+  const list = await readJson(ACCOUNTS_FILE(), []);
+  return Array.isArray(list) ? list : [];
+}
+
+export async function saveAccounts(accounts) {
+  await ensureDir();
+  await atomicWrite(ACCOUNTS_FILE(), JSON.stringify(accounts, null, 2));
+}
+
+// 进程内串行队列：所有「读-改-写」都经由 withAccounts，避免并发请求互相覆盖
+let accountsQueue = Promise.resolve();
+
+/**
+ * 串行地读取 → 修改 → 保存账号列表。fn 可直接修改传入的数组（或返回新数组），
+ * 返回 fn 的结果。fn 内不要做网络请求，以免长时间占住队列。
+ */
+export function withAccounts(fn) {
+  const run = accountsQueue.then(async () => {
+    const accounts = await loadAccounts();
+    const result = await fn(accounts);
+    await saveAccounts(accounts);
+    return result;
+  });
+  accountsQueue = run.catch(() => {});
+  return run;
+}
+
+export function newId() {
+  return crypto.randomUUID();
+}
+
+const optStr = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+
+/** 过期时间统一成 ISO 字符串（接受 ISO / 秒 / 毫秒） */
+export function normalizeExpiry(v) {
+  if (v === null || v === undefined || v === '') return null;
+  const n = typeof v === 'number' ? v : /^\d+$/.test(String(v)) ? Number(v) : NaN;
+  const d = Number.isFinite(n) ? new Date(n < 1e12 ? n * 1000 : n) : new Date(String(v));
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+/**
+ * 校验并构造账号记录（不含重复检查，由调用方负责）。
+ * 可选元数据：uid / email / refreshToken / expiresAt / source / meta（产品相关的非通用字段，如 WorkBuddy 会话信息）
+ */
+export function normalizeAccountInput({ name, provider, token, uid, email, refreshToken, expiresAt, source, meta }) {
+  if (!PROVIDERS.includes(provider)) {
+    throw new Error(`provider 必须是 ${PROVIDERS.join(' 或 ')}`);
+  }
+  const trimmed = String(token || '').trim();
+  if (!trimmed) throw new Error('token 不能为空');
+  return {
+    id: newId(),
+    name: String(name || '').trim() || null,
+    provider,
+    token: trimmed,
+    uid: optStr(uid),
+    email: optStr(email),
+    refreshToken: optStr(refreshToken),
+    expiresAt: normalizeExpiry(expiresAt),
+    source: optStr(source) || 'manual',
+    meta: meta && typeof meta === 'object' && !Array.isArray(meta) ? meta : {},
+    createdAt: new Date().toISOString(),
+    lastCheckin: null,
+    lastResult: null,
+  };
+}
+
+/** 相同 provider 下 token 相同、或 uid 相同（同一用户换了新 token）视为同一账号 */
+export function findDuplicate(accounts, provider, token, uid = null) {
+  const t = String(token || '').trim();
+  return accounts.find((a) => a.provider === provider && (a.token === t || (uid && a.uid && a.uid === uid)));
+}
+
+export function maskToken(token) {
+  if (typeof token !== 'string' || token.length < 12) return '***';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+const maskPhone = (p) => (typeof p === 'string' && p.length >= 7 ? p.slice(0, 3) + '****' + p.slice(-4) : null);
+
+/** 对外输出的脱敏账号视图 */
+export function publicAccount(a) {
+  const meta = a.meta || {};
+  return {
+    id: a.id,
+    name: a.name,
+    provider: a.provider,
+    product: productOf(a.provider),
+    tokenMasked: maskToken(a.token),
+    isPat: typeof a.token === 'string' && a.token.startsWith('pt-'),
+    uid: a.uid || null,
+    email: a.email || null,
+    expiresAt: a.expiresAt || null,
+    hasRefreshToken: Boolean(a.refreshToken),
+    source: a.source || 'manual',
+    phone: maskPhone(meta.phone),
+    domain: meta.domain || null,
+    canSwitch: Boolean(meta.session?.account || meta.credentials),
+    verified: a.verified ?? null,
+    createdAt: a.createdAt,
+    lastCheckin: a.lastCheckin,
+    lastResult: a.lastResult || null,
+  };
+}
+
+// ─── 运行状态（签到日历） ───
+
+export async function loadState() {
+  const s = await readJson(STATE_FILE(), {});
+  return s && typeof s === 'object' ? s : {};
+}
+
+export async function saveState(state) {
+  await ensureDir();
+  await atomicWrite(STATE_FILE(), JSON.stringify(state, null, 2));
+}
+
+// 导入 / 导出（含 10router 互通）见 transfer.js

package/src/tenrouter.js

@@ -0,0 +1,221 @@
+/**
+ * 10Router 集成：用 10Router 仪表盘的虚拟 key（sk-…）
+ *   1. 读取 10Router 其他供应商的额度总览（GET /api/usage/quotas，10Router 1.2.1+）
+ *   2. 把本机 ZCode / OpenCode / mirasim / 小米 MiMo 的用量同步进 10Router 的用量统计
+ *      （POST /api/settings/database/import-usage，与 10router-sync 插件同一接口，10Router 1.0.7+）
+ *
+ * 配置存 ~/.creditdaddy/tenrouter.json（0600，含 key，不随账号导出）；
+ * key 只由守护进程使用，面板拿到的永远是脱敏值。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { dataDir } from './store.js';
+import { logger } from './logger.js';
+import { SOURCES, SOURCE_LABEL, collectSource, selectSince, detectSources } from './usageSync.js';
+
+const FILE = () => path.join(dataDir(), 'tenrouter.json');
+const QUOTA_TIMEOUT_MS = 90_000;   // 10Router 端并发查询全部供应商，冷缓存时可能较慢
+const IMPORT_TIMEOUT_MS = 120_000;
+const BATCH = 5000;
+const SYNC_INTERVAL_MS = 60 * 60 * 1000;
+const DEFAULT_CONFIG = { endpoint: '', key: '', sync: { enabled: false, sources: [...SOURCES] }, syncState: {}, lastSync: null };
+
+export function loadConfig() {
+  try {
+    const c = JSON.parse(fs.readFileSync(FILE(), 'utf8'));
+    return { ...DEFAULT_CONFIG, ...c, sync: { ...DEFAULT_CONFIG.sync, ...(c.sync || {}) }, syncState: c.syncState || {} };
+  } catch { return structuredClone(DEFAULT_CONFIG); }
+}
+
+function saveConfig(c) {
+  fs.mkdirSync(dataDir(), { recursive: true, mode: 0o700 });
+  const tmp = `${FILE()}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(c, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, FILE());
+}
+
+// 读改写串行，避免面板保存与后台同步互相覆盖
+let chain = Promise.resolve();
+function withConfig(fn) {
+  const run = chain.then(async () => { const c = loadConfig(); const r = await fn(c); saveConfig(c); return r; });
+  chain = run.catch(() => {});
+  return run;
+}
+
+export function normalizeEndpoint(raw) {
+  let s = String(raw || '').trim();
+  if (!s) return '';
+  if (!/^https?:\/\//i.test(s)) s = 'http://' + s;
+  const u = new URL(s);   // 非法地址直接抛错
+  return (u.origin + u.pathname).replace(/\/+$/, '');
+}
+
+const maskKey = (k) => (k ? (k.length > 12 ? k.slice(0, 5) + '…' + k.slice(-4) : '…') : '');
+export const isConfigured = (c = loadConfig()) => Boolean(c.endpoint && c.key);
+
+/** 面板用的配置视图（key 脱敏） */
+export async function publicConfig() {
+  const c = loadConfig();
+  return {
+    configured: isConfigured(c),
+    endpoint: c.endpoint,
+    keyMasked: maskKey(c.key),
+    sync: c.sync,
+    lastSync: c.lastSync,
+    syncing: Boolean(syncing),
+    sources: await detectSources(),
+  };
+}
+
+/** 更新配置：key 留空表示保持原值；endpoint 为空 = 清除整个配置 */
+export function updateConfig({ endpoint, key, syncEnabled, sources } = {}) {
+  return withConfig((c) => {
+    if (endpoint !== undefined) {
+      c.endpoint = normalizeEndpoint(endpoint);
+      if (!c.endpoint) { Object.assign(c, structuredClone(DEFAULT_CONFIG)); return; }
+    }
+    if (typeof key === 'string' && key.trim()) {
+      const k = key.trim();
+      if (/\s/.test(k)) throw new Error('key 不能包含空白字符');
+      c.key = k;
+    }
+    if (typeof syncEnabled === 'boolean') c.sync.enabled = syncEnabled;
+    if (Array.isArray(sources)) c.sync.sources = sources.filter((s) => SOURCES.includes(s));
+  });
+}
+
+async function call(c, pathname, { method = 'GET', body, timeout = QUOTA_TIMEOUT_MS } = {}) {
+  if (!isConfigured(c)) throw Object.assign(new Error('尚未配置 10Router 地址与 key'), { code: 'NOT_CONFIGURED' });
+  let res;
+  try {
+    res = await fetch(c.endpoint + pathname, {
+      method,
+      headers: { Authorization: `Bearer ${c.key}`, Accept: 'application/json', ...(body ? { 'Content-Type': 'application/json' } : {}) },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(timeout),
+    });
+  } catch (e) {
+    throw new Error(`无法连接 10Router（${c.endpoint}）：${e.cause?.code || e.message}`);
+  }
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch {}
+  if (res.status === 401 || res.status === 403) throw Object.assign(new Error('10Router 拒绝了这个 key（请确认是仪表盘里的虚拟 key sk-…，且未被停用）'), { code: 'BAD_KEY' });
+  if (res.status === 404 && pathname.startsWith('/api/usage/quotas')) {
+    throw Object.assign(new Error('这个 10Router 版本还没有额度总览接口，需要 10Router 1.2.1 及以上'), { code: 'TOO_OLD' });
+  }
+  if (!res.ok) throw new Error(`10Router 返回 HTTP ${res.status}${data?.error ? '：' + data.error : ''}`);
+  if (data === null) throw new Error('10Router 返回的不是 JSON（地址是否指向了 10Router？）');
+  return data;
+}
+
+/** 其他供应商的额度总览（10Router 端已按仪表盘同一口径归一） */
+export async function fetchQuotas({ force = false } = {}) {
+  const data = await call(loadConfig(), '/api/usage/quotas' + (force ? '?force=1' : ''));
+  return {
+    generatedAt: data.generatedAt || new Date().toISOString(),
+    connections: Array.isArray(data.connections) ? data.connections : [],
+  };
+}
+
+/** 10Router 自身健康（/api/health，无需 key；未配置或不可达时返回 ok:false） */
+export async function fetchHealth(override) {
+  const c = { ...loadConfig(), ...(override || {}) };
+  if (!c.endpoint) return { ok: false, error: '未配置 10Router 地址' };
+  try {
+    const res = await fetch(c.endpoint + '/api/health', {
+      headers: { Accept: 'application/json', ...(c.key ? { Authorization: `Bearer ${c.key}` } : {}) },
+      signal: AbortSignal.timeout(8000),
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok || !data) return { ok: false, error: `HTTP ${res.status}` };
+    return {
+      ok: data.ok === true,
+      driver: data.driver || null,
+      lastDriverError: typeof data.lastDriverError === 'string' ? data.lastDriverError : null,
+    };
+  } catch (e) {
+    return { ok: false, error: e.cause?.code || e.message };
+  }
+}
+
+/** 测试连接：用额度接口同时验证地址与 key；老版本 10Router 只能同步用量时也视为可用 */
+export async function testConnection(override) {
+  const c = { ...loadConfig(), ...(override || {}) };
+  try {
+    const q = await call(c, '/api/usage/quotas');
+    return { ok: true, quotas: true, connections: (q.connections || []).length };
+  } catch (e) {
+    if (e.code === 'TOO_OLD') return { ok: true, quotas: false, warning: e.message };
+    return { ok: false, error: e.message, code: e.code };
+  }
+}
+
+// ── 用量同步 ──
+
+let syncing = null;
+let timer = null;
+
+/** 同步一轮；并发调用共用同一轮。dryRun 只统计不上传。 */
+export function runUsageSync({ dryRun = false, trigger = 'manual' } = {}) {
+  if (!syncing) syncing = doSync({ dryRun, trigger }).finally(() => { syncing = null; });
+  return syncing;
+}
+
+async function doSync({ dryRun, trigger }) {
+  const c = loadConfig();
+  if (!isConfigured(c)) throw Object.assign(new Error('尚未配置 10Router 地址与 key'), { code: 'NOT_CONFIGURED' });
+  const results = [];
+  for (const id of c.sync.sources) {
+    const label = SOURCE_LABEL[id];
+    try {
+      const { entries, notes, files } = await collectSource(id, { endpoint: c.endpoint });
+      if (!files) { results.push({ source: id, label, status: 'absent' }); continue; }
+      const { selected, maxTs } = selectSince(entries, c.syncState[id]?.lastTs);
+      if (dryRun || !selected.length) {
+        results.push({ source: id, label, status: dryRun ? 'dry-run' : 'up-to-date', total: entries.length, selected: selected.length, notes });
+        continue;
+      }
+      let imported = 0, skipped = 0;
+      for (let i = 0; i < selected.length; i += BATCH) {
+        const r = await call(c, '/api/settings/database/import-usage', {
+          method: 'POST', body: { usageHistory: selected.slice(i, i + BATCH) }, timeout: IMPORT_TIMEOUT_MS,
+        });
+        imported += r.imported || 0;
+        skipped += r.skipped || 0;
+      }
+      await withConfig((cc) => { cc.syncState[id] = { lastTs: maxTs, at: new Date().toISOString() }; });
+      results.push({ source: id, label, status: 'ok', total: entries.length, selected: selected.length, imported, skipped, notes });
+    } catch (e) {
+      results.push({ source: id, label, status: 'failed', error: e.message });
+      if (e.code === 'BAD_KEY') break;   // key 不对，后面的来源也不用试了
+    }
+  }
+  const imported = results.reduce((n, r) => n + (r.imported || 0), 0);
+  const failed = results.filter((r) => r.status === 'failed');
+  const summary = dryRun
+    ? '预览：' + results.map((r) => `${r.label} ${r.status === 'absent' ? '未检测到' : (r.selected ?? 0) + ' 行'}`).join('，')
+    : failed.length
+      ? `同步完成：新增 ${imported} 行，${failed.length} 个来源失败（${failed.map((r) => r.label + '：' + r.error).join('；')}）`
+      : `同步完成：新增 ${imported} 行`;
+  if (!dryRun) {
+    await withConfig((cc) => { cc.lastSync = { at: new Date().toISOString(), trigger, summary, results }; });
+    (failed.length ? logger.warn : logger.info).call(logger, '10R', summary);
+  }
+  return { summary, results };
+}
+
+/** 后台每小时同步一次（仅在配置了且开启自动同步时） */
+export function startUsageSyncScheduler() {
+  if (timer) return;
+  const tick = () => {
+    const c = loadConfig();
+    if (!isConfigured(c) || !c.sync.enabled) return;
+    runUsageSync({ trigger: 'auto' }).catch((e) => logger.warn('10R', '自动同步失败：' + e.message));
+  };
+  setTimeout(tick, 60_000).unref?.();   // 启动 1 分钟后先跑一轮
+  timer = setInterval(tick, SYNC_INTERVAL_MS);
+  timer.unref?.();
+}