@leiyi-works/dsh-cloud-sync 0.0.0-stage → 0.1.6

package/index.js

@@ -0,0 +1,682 @@
+/**
+ * dsh-cloud-sync — Host 半。
+ *
+ * 把 DSH 的状态（聊天记录、工作区/定时任务、插件清单与本地插件源码、钥则、凭据）
+ * 增量推到云服务器（京东云 jdcloud，SSH 通道），换机或新机登录后一键拉回。
+ *
+ * 提供的入口：
+ *   · 设置 → 云端同步（面板）：看状态、改不了配置但能手动推/恢复
+ *   · 工具 cloud_sync_status / cloud_sync_push / cloud_sync_pull
+ *   · HTTP 前缀 /__dsh-cloud-sync/*（面板用）
+ *   · 后台定时器：默认每 24 小时自动推一次；新机本地没有任何会话时首启自动恢复
+ */
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import z from '@deepseek-ai/schemastery'
+import {
+  DEFAULTS,
+  buildInventory,
+  checkConnection,
+  dshHome,
+  listMachines,
+  localFingerprint,
+  localSummary,
+  normalizeConfig,
+  profileName,
+  pull,
+  push,
+  readRemoteManifest,
+  readLinkPlugins,
+  readTombstones,
+  defaultMachineId,
+  isConfigured,
+} from './sync.js'
+import { setSubprocessProvider } from './exec.js'
+
+/** 这些错误是「环境不具备」，重试多少次都没用：停止自动重试，交给 UI 提示。 */
+const PERMANENT_ERROR_RE = /ENOENT|EACCES|EPERM|not a function|私钥不存在|未配置服务器|Permission denied|no such identity|Cannot find module|spawn .* ENOENT/i
+
+function isPermanentError(message) {
+  return PERMANENT_ERROR_RE.test(String(message ?? ''))
+}
+
+export const name = 'dsh-cloud-sync'
+export const inject = ['tools', 'webServer']
+
+const ROUTE_PREFIX = '/__dsh-cloud-sync'
+const LOG_TAG = 'dsh-cloud-sync'
+const TICK_MS = 60 * 1000
+const BOOT_DELAY_MS = 30 * 1000
+const TOOL_WAIT_MS = 90 * 1000
+
+/** 插件配置：保存后在设置页立即生效，无需重启。 */
+export const Config = z.object({
+  host: z.string().default(DEFAULTS.host)
+    .description('云服务器 SSH 目标（user@host）。留空则从 connectionFile 读取'),
+  port: z.natural().default(DEFAULTS.port).description('SSH 端口'),
+  identityFile: z.string().default(DEFAULTS.identityFile)
+    .description('私钥路径；留空则从 connectionFile 读取'),
+  connectionFile: z.string().default(DEFAULTS.connectionFile)
+    .description('连接信息 json（默认 <DSH_HOME>/keyrule-secrets/ssh.json，随钥则目录一起同步）'),
+  identityFileGuest: z.string().default(DEFAULTS.identityFileGuest)
+    .description('guest/VM 世界里的私钥路径（手机端用；填了就不校验宿主路径）'),
+  sshBinary: z.string().default(DEFAULTS.sshBinary)
+    .description('ssh 可执行文件（留空 = 自动找；手机端可填 guest 里的绝对路径）'),
+  sshCompat: z.string().default(DEFAULTS.sshCompat)
+    .description('ssh 兼容模式：openssh（默认）/ dropbear（精简参数、-y 接受主机密钥）'),
+  connectTimeoutMs: z.natural().default(DEFAULTS.connectTimeoutMs)
+    .description('建连超时（毫秒；手机端软件模拟 SSH 很慢，建议 60000 以上）'),
+  commandTimeoutMs: z.natural().default(DEFAULTS.commandTimeoutMs)
+    .description('单条远程命令超时（毫秒）'),
+  stallMs: z.natural().default(DEFAULTS.stallMs)
+    .description('传输停滞判定（毫秒）：连续这么久没有数据就断开重试'),
+  deviceMode: z.boolean().default(DEFAULTS.deviceMode)
+    .description('设备模式：默认每天一次、不带附件/插件源码、不自动整份恢复（手机端建议开）'),
+  remoteRoot: z.string().default(DEFAULTS.remoteRoot).description('服务器上的备份根目录'),
+  machineId: z.string().default('').description('这台机器的槽位名，留空 = 主机名'),
+  localPluginRoot: z.string().default(DEFAULTS.localPluginRoot)
+    .description('新机上本地插件源码放哪（原路径不存在时用）'),
+  intervalMinutes: z.natural().default(DEFAULTS.intervalMinutes).description('自动同步间隔（分钟）；多台机器来回用时建议 5～10 分钟'),
+  dailySync: z.boolean().default(DEFAULTS.dailySync)
+    .description('改成「每天一次」：当天还没同步过就补一轮（打开 DSH 后很快检查；忽略 intervalMinutes）'),
+  pauseWhenIdle: z.boolean().default(DEFAULTS.pauseWhenIdle)
+    .description('没有会话在跑、也没有操作时暂停自动同步，等下次有动静再补一轮'),
+  idlePauseMinutes: z.natural().default(DEFAULTS.idlePauseMinutes)
+    .description('空闲多少分钟后暂停自动同步（pauseWhenIdle 打开时生效）'),
+  autoSync: z.boolean().default(DEFAULTS.autoSync).description('开启后台自动同步'),
+  applyRemoteDeletes: z.boolean().default(DEFAULTS.applyRemoteDeletes)
+    .description('别的机器删掉的文件，本机同步时也删（会先放进 .cloud-sync/removed/，可找回）'),
+  restoreOnEmpty: z.boolean().default(DEFAULTS.restoreOnEmpty).description('新机（本地没有会话）首次启动自动恢复'),
+  includeAttachments: z.boolean().default(DEFAULTS.includeAttachments).description('同步聊天图片附件（约几百 MB，一次性）'),
+  includeCredentials: z.boolean().default(DEFAULTS.includeCredentials).description('同步 .credentials.yaml（登录凭据）'),
+  includeKeyruleSecrets: z.boolean().default(DEFAULTS.includeKeyruleSecrets).description('同步 keyrule-secrets（SSH 私钥、npm token）'),
+  includeLocalPlugins: z.boolean().default(DEFAULTS.includeLocalPlugins).description('同步本地 link 插件源码'),
+  quietSeconds: z.natural().default(DEFAULTS.quietSeconds).description('推送时跳过最近 N 秒内改过的文件（这些文件下一轮再传，避免抓到写一半的内容）'),
+  trashDays: z.natural().default(DEFAULTS.trashDays).description('云端回收站保留天数（本地删掉的会话/附件）'),
+  versionDays: z.natural().default(DEFAULTS.versionDays).description('云端旧版本保留天数（被覆盖前的文件）'),
+  backupDays: z.natural().default(DEFAULTS.backupDays).description('本机恢复前备份的保留天数（超过就自动清，避免越攒越多）'),
+})
+
+function normalizeSchema(schema) {
+  if (schema === undefined) return { type: 'object', additionalProperties: true }
+  if (schema.type === 'json') return { type: 'object', additionalProperties: true }
+  return schema
+}
+
+function defineTool(spec) {
+  const parameters = spec.parameters ?? {}
+  const properties = {}
+  const required = []
+  for (const [key, definition] of Object.entries(parameters)) {
+    const { required: isRequired, ...rest } = definition
+    properties[key] = rest
+    if (isRequired === true) required.push(key)
+  }
+  const output = spec.output === undefined ? undefined : { ...spec.output, schema: normalizeSchema(spec.output.schema) }
+  return {
+    ...spec,
+    ...(output === undefined ? {} : { output }),
+    parameters: { type: 'object', properties, ...(required.length === 0 ? {} : { required }), additionalProperties: false },
+  }
+}
+
+const clean = (value) => JSON.parse(JSON.stringify(value))
+const stamp = () => {
+  const now = new Date()
+  const pad = (value) => String(value).padStart(2, '0')
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+}
+
+/** 两个时间戳是不是同一个本地日期（「每天一次」用）。 */
+function sameLocalDay(a, b) {
+  const left = new Date(Number(a))
+  const right = new Date(Number(b))
+  return left.getFullYear() === right.getFullYear()
+    && left.getMonth() === right.getMonth()
+    && left.getDate() === right.getDate()
+}
+
+/** 明天 00:05 的时间戳（每天一次的「下次」时间）。 */
+function nextLocalMidnight(now = Date.now()) {
+  const date = new Date(now)
+  date.setHours(24, 5, 0, 0)
+  return date.getTime()
+}
+
+/* ── 本地状态文件 ──────────────────────────────────────────────────────── */
+
+function stateFile() {
+  return path.join(dshHome(), '.cloud-sync', 'state.json')
+}
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile(), 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return { version: 1 }
+  }
+}
+
+function writeState(next) {
+  const file = stateFile()
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const temp = `${file}.tmp`
+    fs.writeFileSync(temp, JSON.stringify(next, null, 2), 'utf8')
+    fs.renameSync(temp, file)
+  } catch { /* 状态写不进去不影响同步本身 */ }
+}
+
+function appendLog(line) {
+  try {
+    const file = path.join(dshHome(), '.cloud-sync', 'sync.log')
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    try {
+      if (fs.statSync(file).size > 2 * 1024 * 1024) fs.renameSync(file, `${file}.1`)
+    } catch { /* 文件不存在 */ }
+    fs.appendFileSync(file, `[${new Date().toISOString()}] ${line}\n`, 'utf8')
+  } catch { /* 日志失败不影响同步 */ }
+}
+
+/* ── 运行器 ─────────────────────────────────────────────────────────────── */
+
+function createRunner(config) {
+  const job = { phase: 'idle', kind: undefined, startedAt: 0, finishedAt: 0, log: [], progress: undefined, result: undefined, error: undefined }
+  let current
+  const state = readState()
+
+  const active = () => job.phase === 'running'
+
+  const run = (kind, options = {}) => {
+    if (active()) throw new Error(`已有${job.kind === 'pull' ? '恢复' : '推送'}任务在跑，请稍候`)
+    job.phase = 'running'
+    job.kind = kind
+    job.startedAt = Date.now()
+    job.finishedAt = 0
+    job.log = []
+    job.progress = undefined
+    job.result = undefined
+    job.error = undefined
+    const lines = (line) => {
+      job.log.push(line)
+      if (job.log.length > 400) job.log = job.log.slice(-400)
+      appendLog(`${kind} ${line}`)
+    }
+    const onProgress = (progress) => {
+      job.progress = { ...progress, at: Date.now() }
+    }
+    current = (async () => {
+      try {
+        const result = kind === 'push'
+          ? await push({ config, log: lines, onProgress, auto: options.auto === true })
+          : await pull({ config, log: lines, onProgress, from: options.from, force: options.force === true })
+        job.result = clean(result)
+        job.phase = 'done'
+        const next = {
+          ...readState(),
+          version: 1,
+          machine: result.machine ?? options.from ?? readState().machine,
+          lastKind: kind,
+          lastAt: new Date().toISOString(),
+          ...(kind === 'push' ? { lastPush: clean(result), lastPushAt: Date.now() } : { lastPull: clean(result), lastPullAt: Date.now() }),
+          lastError: undefined,
+        }
+        if (kind === 'push' && result.deferred > 0) next.pendingRetryAt = Date.now() + Math.max(60 * 1000, config.quietSeconds * 1000 + 60 * 1000)
+        else delete next.pendingRetryAt
+        writeState(next)
+        return result
+      } catch (error) {
+        job.error = error instanceof Error ? error.message : String(error)
+        job.phase = 'failed'
+        const permanent = isPermanentError(job.error)
+        const next = {
+          ...readState(),
+          version: 1,
+          lastKind: kind,
+          lastAt: new Date().toISOString(),
+          lastError: { kind, message: job.error, at: new Date().toISOString(), ...(permanent ? { permanent: true } : {}) },
+          ...(permanent ? {} : { pendingRetryAt: Date.now() + 30 * 60 * 1000 }),
+        }
+        writeState(next)
+        appendLog(`${kind} 失败${permanent ? '（环境不可用，已停止自动重试）' : ''}：${job.error}`)
+        throw error
+      } finally {
+        job.finishedAt = Date.now()
+        current = undefined
+        invalidateCache()
+      }
+    })()
+    current.catch(() => {})
+    return current
+  }
+
+  return { job, run, active, state: () => readState() }
+}
+
+/* ── 面板/工具共用的状态 ────────────────────────────────────────────────── */
+
+/**
+ * 面板每 4 秒拉一次状态，不能每次都真去 ssh 数一遍云端目录：远端清单缓存 60 秒，
+ * 本地扫描缓存 10 秒，手动操作（push/pull）完成时清缓存立即刷新。
+ */
+const cache = { machines: { at: 0, value: undefined }, local: { at: 0, value: undefined } }
+const MACHINES_TTL = 60 * 1000
+const LOCAL_TTL = 10 * 1000
+
+/** 本机的「活动」状态：有几个会话在跑、最后一次有动静是什么时候。用来做空闲暂停。 */
+const activity = {
+  running: new Set(),
+  lastAt: Date.now(),
+  pausedLogged: false,
+  idleFor() {
+    return { running: activity.running.size, idleMs: Date.now() - activity.lastAt }
+  },
+}
+function invalidateCache() {
+  cache.machines.at = 0
+  cache.local.at = 0
+}
+
+async function cachedMachines(config) {
+  const now = Date.now()
+  if (cache.machines.value !== undefined && now - cache.machines.at < MACHINES_TTL) return cache.machines.value
+  let value
+  try {
+    value = await listMachines(config)
+  } catch (error) {
+    value = { ok: false, machines: [], error: error instanceof Error ? error.message : String(error) }
+  }
+  cache.machines = { at: Date.now(), value }
+  return value
+}
+
+function cachedLocal(config) {
+  const now = Date.now()
+  if (cache.local.value !== undefined && now - cache.local.at < LOCAL_TTL) return cache.local.value
+  let value
+  try {
+    value = localSummary(config)
+  } catch (error) {
+    value = { files: 0, bytes: 0, errors: 1, plugins: 0, message: error instanceof Error ? error.message : String(error) }
+  }
+  cache.local = { at: Date.now(), value }
+  return value
+}
+
+async function buildStatus(config, runner) {
+  const state = runner.state()
+  const configured = isConfigured(config)
+  const machine = config.machineId !== '' ? config.machineId : defaultMachineId()
+  const local = cachedLocal(config)
+  const remote = configured
+    ? await cachedMachines(config)
+    : { ok: false, machines: [], error: '未配置服务器（host 为空）' }
+  let deletedLocally = 0
+  try {
+    deletedLocally = Object.keys(readTombstones(dshHome())).length
+  } catch { /* 记忆文件坏了就当没有 */ }
+  const intervalMs = config.intervalMinutes * 60 * 1000
+  const lastPushAt = Number(state.lastPushAt) || 0
+  const pendingRetryAt = Number(state.pendingRetryAt) || 0
+  const intervalDue = lastPushAt === 0 ? Date.now() : lastPushAt + intervalMs
+  const dailyDoneToday = lastPushAt > 0 && sameLocalDay(lastPushAt, Date.now())
+  const nextPushAt = config.dailySync
+    ? (dailyDoneToday ? nextLocalMidnight() : Date.now())
+    : Math.max(intervalDue, pendingRetryAt > 0 ? pendingRetryAt : 0)
+  return {
+    ok: true,
+    machine,
+    config: {
+      host: config.host,
+      port: config.port,
+      identityFile: config.identityFile,
+      remoteRoot: config.remoteRoot,
+      localPluginRoot: config.localPluginRoot,
+      intervalMinutes: config.intervalMinutes,
+      dailySync: config.dailySync,
+      pauseWhenIdle: config.pauseWhenIdle,
+      idlePauseMinutes: config.idlePauseMinutes,
+      autoSync: config.autoSync,
+      restoreOnEmpty: config.restoreOnEmpty,
+      includeAttachments: config.includeAttachments,
+      includeCredentials: config.includeCredentials,
+      includeKeyruleSecrets: config.includeKeyruleSecrets,
+      includeLocalPlugins: config.includeLocalPlugins,
+      applyRemoteDeletes: config.applyRemoteDeletes,
+    },
+    local: { ...local, deletedLocally },
+    remote,
+    schedule: {
+      lastPushAt: lastPushAt || undefined,
+      nextPushAt: config.autoSync ? nextPushAt : undefined,
+      pendingRetryAt: state.pendingRetryAt,
+    },
+    idle: {
+      running: activity.running.size,
+      idleMs: Date.now() - activity.lastAt,
+      paused: activity.pausedLogged,
+      pauseWhenIdle: config.pauseWhenIdle,
+      idlePauseMinutes: config.idlePauseMinutes,
+    },
+    last: {
+      push: state.lastPush,
+      pull: state.lastPull,
+      error: state.lastError,
+      at: state.lastAt,
+    },
+    job: {
+      phase: runner.job.phase,
+      kind: runner.job.kind,
+      startedAt: runner.job.startedAt,
+      finishedAt: runner.job.finishedAt,
+      log: runner.job.log.slice(-60),
+      progress: runner.job.progress,
+      result: runner.job.result,
+      error: runner.job.error,
+    },
+  }
+}
+
+function summarizeStatus(status) {
+  const lines = []
+  lines.push(`机器槽位：${status.machine}`)
+  if (status.remote?.ok === true) {
+    lines.push(`云端：${status.remote.machines.length} 台机器${status.remote.freeBytes === undefined ? '' : `，剩余空间 ${(status.remote.freeBytes / 1073741824).toFixed(1)} GB`}`)
+    for (const item of status.remote.machines) {
+      lines.push(`  - ${item.id}：${(item.filesBytes / 1048576).toFixed(1)} MB${item.manifestMtime === 0 ? '' : `，更新于 ${new Date(item.manifestMtime).toLocaleString()}`}`)
+    }
+  } else {
+    lines.push(`云端：连不上（${status.remote?.error ?? '未知错误'}）`)
+  }
+  lines.push(`本地待同步：${status.local.files} 个文件 / ${(status.local.bytes / 1048576).toFixed(1)} MB，本地插件 ${status.local.plugins} 个`)
+  if (Number(status.local.deletedLocally) > 0) lines.push(`本地删过 ${status.local.deletedLocally} 个文件：恢复时不会把它们拉回来（强制恢复可覆盖这条规则）`)
+  const lastPush = status.last.push
+  lines.push(`上次推送：${status.last.push !== undefined ? `${new Date(Number(status.schedule.lastPushAt) || 0).toLocaleString()}（上传 ${lastPush.uploaded} 个 / 删除 ${lastPush.deleted} 个）` : '还没有'}`)
+  lines.push(`上次恢复：${status.last.pull !== undefined ? `${status.last.at}（${status.last.pull.restored} 个文件）` : '还没有'}`)
+  if (status.last.error !== undefined) lines.push(`上次失败：${status.last.error.kind} — ${status.last.error.message}`)
+  if (status.config.autoSync) {
+    lines.push(status.config.dailySync === true
+      ? `自动同步：每天一次（${status.schedule.lastPushAt !== undefined && sameLocalDay(status.schedule.lastPushAt, Date.now()) ? `今天 ${new Date(status.schedule.lastPushAt).toLocaleTimeString()} 已同步` : '今天还没同步，下次检查时会补一轮'}；下次 ${new Date(status.schedule.nextPushAt).toLocaleString()}）`
+      : `自动同步：每 ${status.config.intervalMinutes} 分钟一次（下次 ${new Date(status.schedule.nextPushAt).toLocaleString()}）`)
+  }
+  else lines.push('自动推送：已关闭')
+  if (status.idle?.paused === true) {
+    lines.push(`当前空闲暂停中（没有会话在跑，已静默 ${Math.round(status.idle.idleMs / 60000)} 分钟）；下次有操作会立即补一轮`)
+  } else if (Number(status.idle?.running) > 0) {
+    lines.push(`正在运行的会话：${status.idle.running} 个（有活动，不暂停）`)
+  }
+  if (status.job.phase === 'running') lines.push(`正在${status.job.kind === 'pull' ? '恢复' : '推送'}…（${status.job.log.slice(-1)[0] ?? ''}）`)
+  return lines.join('\n')
+}
+
+/* ── 插件入口 ───────────────────────────────────────────────────────────── */
+
+export function apply(ctx, rawConfig) {
+  const config = normalizeConfig(rawConfig)
+  // 命令执行层：优先用 DSH 的可移植 subprocess 服务（手机/沙箱环境里只有它能起进程）
+  try {
+    const subprocess = typeof ctx.get === 'function' ? ctx.get('subprocess') : undefined
+    setSubprocessProvider(subprocess)
+  } catch {
+    setSubprocessProvider(undefined)
+  }
+  const runner = createRunner(config)
+
+  /* 记「有没有会话在跑」：空闲暂停靠它判断 */
+  activity.lastAt = Date.now()
+  activity.running.clear()
+  ctx.effect(() => ctx.on('api-session/status', (sessionId, running) => {
+    try {
+      const id = String(sessionId)
+      if (running === true) activity.running.add(id)
+      else activity.running.delete(id)
+      activity.lastAt = Date.now()
+    } catch { /* 事件结构变化不影响同步本身 */ }
+  }), 'dsh-cloud-sync: session activity')
+
+  const bodyOf = async (req) => {
+    const chunks = []
+    for await (const chunk of req) chunks.push(chunk)
+    try {
+      return JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}')
+    } catch {
+      return {}
+    }
+  }
+
+  /* 工具 */
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: 'cloud_sync_status',
+    description: '查看云端同步状态：本机槽位、云端各机器备份大小与时间、上次推送/恢复结果、自动推送计划与最近日志。',
+    parameters: {},
+    output: { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: value?.summary ?? JSON.stringify(value, null, 2) }] },
+    async execute() {
+      const status = await buildStatus(config, runner)
+      return clean({ ...status, summary: summarizeStatus(status) })
+    },
+  })), 'dsh-cloud-sync: status tool')
+
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: 'cloud_sync_push',
+    description: '把本地 DSH 状态增量推到云服务器（聊天记录、工作区/定时任务、插件清单与本地插件源码、钥则、凭据、可选附件）。返回上传/删除数量；大文件首次上传可能要几分钟，超时未完成会返回 running=true，再用 cloud_sync_status 查进度。',
+    parameters: {
+      waitSeconds: { type: 'number', description: '最多等多少秒再返回（默认 90，首次全量约需 300+）' },
+    },
+    output: { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: value?.summary ?? JSON.stringify(value, null, 2) }] },
+    async execute(args) {
+      if (runner.active()) {
+        const status = await buildStatus(config, runner)
+        return clean({ ok: false, running: true, summary: `已有任务在跑：${status.job.kind}`, job: status.job })
+      }
+      const waitMs = Math.max(5, Math.min(600, Number(args?.waitSeconds) || TOOL_WAIT_MS / 1000)) * 1000
+      const promise = runner.run('push', {}).catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) }))
+      const result = await Promise.race([promise, new Promise((resolve) => setTimeout(() => resolve(undefined), waitMs))])
+      if (result === undefined) {
+        const status = await buildStatus(config, runner)
+        return clean({ ok: true, running: true, summary: `推送仍在进行中：${status.job.log.slice(-1)[0] ?? ''}`, job: status.job })
+      }
+      if (result.ok === false) return clean({ ok: false, error: result.error, summary: `推送失败：${result.error}` })
+      const summary = result.fastPath === true
+        ? `本地没有变化，本轮跳过联网比对（本地 ${result.total} 个文件；仍是每 ${config.intervalMinutes} 分钟一轮）`
+        : result.skipped === true
+          ? `没有变化，无需上传（云端已有 ${result.total} 个文件${result.deferred > 0 ? `，${result.deferred} 个刚改过的留到下轮` : ''}）`
+          : `推送完成：上传 ${result.uploaded} 个文件，删除 ${result.deleted} 个，云端合计 ${(result.bytes / 1048576).toFixed(1)} MB`
+      return clean({ ...result, summary })
+    },
+  })), 'dsh-cloud-sync: push tool')
+
+  ctx.effect(() => ctx.tools.register(defineTool({
+    name: 'cloud_sync_pull',
+    description: '从云服务器恢复 DSH 状态到本机（新机/换机后使用）：只补本地缺失或云端更新的文件，覆盖前自动本地备份，不会删除本地文件。',
+    parameters: {
+      from: { type: 'string', description: '从哪台机器的备份恢复；不填时若云端只有一台就自动用它' },
+      force: { type: 'boolean', description: '连最近 5 分钟内改过的本地文件也覆盖（默认 false）' },
+      waitSeconds: { type: 'number', description: '最多等多少秒再返回（默认 90）' },
+    },
+    output: { schema: { type: 'json' }, render: (_args, value) => [{ type: 'text', text: value?.summary ?? JSON.stringify(value, null, 2) }] },
+    async execute(args) {
+      if (runner.active()) {
+        const status = await buildStatus(config, runner)
+        return clean({ ok: false, running: true, summary: `已有任务在跑：${status.job.kind}`, job: status.job })
+      }
+      const waitMs = Math.max(5, Math.min(600, Number(args?.waitSeconds) || TOOL_WAIT_MS / 1000)) * 1000
+      const promise = runner.run('pull', { from: args?.from, force: args?.force === true })
+        .catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) }))
+      const result = await Promise.race([promise, new Promise((resolve) => setTimeout(() => resolve(undefined), waitMs))])
+      if (result === undefined) {
+        const status = await buildStatus(config, runner)
+        return clean({ ok: true, running: true, summary: `恢复仍在进行中：${status.job.log.slice(-1)[0] ?? ''}`, job: status.job })
+      }
+      if (result.ok === false) return clean({ ok: false, error: result.error, summary: `恢复失败：${result.error}` })
+      return clean({
+        ...result,
+        summary: `恢复完成：从 ${result.from} 拉回 ${result.restored} 个文件（${(result.bytes / 1048576).toFixed(1)} MB）${result.skipped > 0 ? `，${result.skipped} 个找不到落点` : ''}${result.plugins > 0 ? `，插件源码 ${result.plugins} 个` : ''}${result.skippedDeleted > 0 ? `，${result.skippedDeleted} 个本地删过的不拉回` : ''}。若恢复了插件清单，需重装插件依赖并重启 DSH。`,
+      })
+    },
+  })), 'dsh-cloud-sync: pull tool')
+
+  /* HTTP 路由（面板） */
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: ROUTE_PREFIX,
+    handler: async (req, res) => {
+      const send = (status, payload) => {
+        res.statusCode = status
+        res.setHeader('content-type', 'application/json; charset=utf-8')
+        res.setHeader('cache-control', 'no-store')
+        res.end(JSON.stringify(payload))
+      }
+      const pathname = String(req.url ?? '').split('?')[0]
+      try {
+        if (pathname.endsWith('/status') && req.method === 'GET') {
+          send(200, await buildStatus(config, runner))
+          return
+        }
+        if (pathname.endsWith('/push') && req.method === 'POST') {
+          const body = await bodyOf(req)
+          if (runner.active()) {
+            // 已经有任务在跑：不当错误，告诉面板「已在同步中」即可
+            send(202, { ok: true, alreadyRunning: true, kind: runner.job.kind })
+            return
+          }
+          try {
+            runner.run('push', { auto: body.auto === true })
+            send(202, { ok: true, phase: 'running' })
+          } catch (error) {
+            send(409, { ok: false, error: error instanceof Error ? error.message : String(error) })
+          }
+          return
+        }
+        if (pathname.endsWith('/pull') && req.method === 'POST') {
+          const body = await bodyOf(req)
+          if (runner.active()) {
+            send(202, { ok: true, alreadyRunning: true, kind: runner.job.kind })
+            return
+          }
+          try {
+            runner.run('pull', { from: typeof body.from === 'string' && body.from !== '' ? body.from : undefined, force: body.force === true })
+            send(202, { ok: true, phase: 'running' })
+          } catch (error) {
+            send(409, { ok: false, error: error instanceof Error ? error.message : String(error) })
+          }
+          return
+        }
+        if (pathname.endsWith('/connect-test') && req.method === 'POST') {
+          send(200, { ok: true, connection: await checkConnection(config) })
+          return
+        }
+        if (pathname.endsWith('/machines') && req.method === 'GET') {
+          send(200, { ok: true, ...(await listMachines(config)) })
+          return
+        }
+        send(404, { ok: false, error: 'unknown dsh-cloud-sync route' })
+      } catch (error) {
+        send(500, { ok: false, error: error instanceof Error ? error.message : String(error) })
+      }
+    },
+  }), 'dsh-cloud-sync: routes')
+
+  /* 定时器：每分钟检查一次该不该同步 */
+  ctx.effect(() => {
+    const tick = () => {
+      if (!config.autoSync || runner.active()) return
+      const state = readState()
+      // 永久性错误（环境不可用：没有 ssh、没有私钥、未配置服务器…）→ 不再自动重试，等用户手动处理
+      if (state.lastError !== undefined && state.lastError !== null && state.lastError.permanent === true) return
+      const pendingAt = Number(state.pendingRetryAt) || 0
+      if (pendingAt > Date.now()) return
+      // 上一轮有「刚改过、留到下轮」的文件：到点就补一轮，不受间隔限制
+      const retryDue = pendingAt > 0 && pendingAt <= Date.now()
+      if (!retryDue) {
+        const lastPushAt = Number(state.lastPushAt) || 0
+        if (config.dailySync) {
+          // 每天一次：今天已经同步过就不再跑，等第二天
+          if (lastPushAt > 0 && sameLocalDay(lastPushAt, Date.now())) return
+        } else if (Date.now() - lastPushAt < config.intervalMinutes * 60 * 1000) {
+          return
+        }
+      }
+      // 没有任何会话在跑、且最近一段时间没有任何操作 → 暂停联网，等下次有动静再补
+      const idle = activity.idleFor()
+      if (config.pauseWhenIdle && !retryDue && idle.running === 0 && idle.idleMs > config.idlePauseMinutes * 60 * 1000) {
+        // 事件可能漏报（例如别的进程写文件）：再用本地指纹确认一次，确实没变才暂停
+        let changed = true
+        try {
+          const saved = JSON.parse(fs.readFileSync(path.join(dshHome(), '.cloud-sync', 'fingerprint.json'), 'utf8')).value
+          changed = localFingerprint(config) !== saved
+        } catch { /* 没有指纹记录就当有变化，宁可多跑一轮 */ }
+        if (!changed) {
+          if (!activity.pausedLogged) {
+            activity.pausedLogged = true
+            appendLog(`空闲 ${Math.round(idle.idleMs / 60000)} 分钟且本地无变化，暂停自动同步（下次有操作时立即补一轮）`)
+          }
+          return
+        }
+      }
+      if (activity.pausedLogged) {
+        activity.pausedLogged = false
+        appendLog('检测到新的操作，恢复自动同步')
+      }
+      runner.run('push', { auto: true }).catch((error) => {
+        appendLog(`自动推送失败：${error instanceof Error ? error.message : String(error)}`)
+      })
+    }
+    const handle = setInterval(tick, TICK_MS)
+    if (typeof handle.unref === 'function') handle.unref()
+    // 「每天第一次打开 DSH」尽快同步：启动 20 秒后先检查一次
+    const bootCheck = setTimeout(tick, 20 * 1000)
+    if (typeof bootCheck.unref === 'function') bootCheck.unref()
+    return () => {
+      clearInterval(handle)
+      clearTimeout(bootCheck)
+    }
+  }, 'dsh-cloud-sync: scheduler')
+
+  /* 启动检查：新机（本地没有任何会话）时自动恢复 */
+  ctx.effect(() => {
+    const timer = setTimeout(async () => {
+      try {
+        if (!config.restoreOnEmpty || runner.active()) return
+        const state = readState()
+        if (state.bootstrapDone === true) return
+        const sessions = path.join(dshHome(), 'sessions')
+        let hasSession = false
+        try {
+          for (const workspace of fs.readdirSync(sessions, { withFileTypes: true })) {
+            if (!workspace.isDirectory()) continue
+            const dir = path.join(sessions, workspace.name)
+            if (fs.readdirSync(dir).length > 0) {
+              hasSession = true
+              break
+            }
+          }
+        } catch { /* 目录不存在 = 空 */ }
+        if (hasSession) {
+          writeState({ ...readState(), version: 1, bootstrapDone: true })
+          return
+        }
+        const listing = await listMachines(config)
+        const candidates = listing.machines.filter((item) => item.manifestBytes > 0)
+        if (candidates.length === 0) return
+        if (candidates.length > 1) {
+          appendLog(`本机没有任何会话，但云端有 ${candidates.length} 台机器的备份（${candidates.map((item) => item.id).join('、')}），请在设置页选择从哪台恢复`)
+          return
+        }
+        appendLog(`本机没有任何会话，自动从 ${candidates[0].id} 恢复`)
+        await runner.run('pull', { from: candidates[0].id })
+        writeState({ ...readState(), version: 1, bootstrapDone: true })
+      } catch (error) {
+        appendLog(`启动恢复失败：${error instanceof Error ? error.message : String(error)}`)
+      }
+    }, BOOT_DELAY_MS)
+    if (typeof timer.unref === 'function') timer.unref()
+    return () => clearTimeout(timer)
+  }, 'dsh-cloud-sync: bootstrap')
+
+  /* 首次启动打个日志，方便排查（不阻塞） */
+  appendLog(`插件启动：槽位 ${config.machineId !== '' ? config.machineId : defaultMachineId()}，远端 ${config.host}:${config.remoteRoot}，自动同步 ${config.autoSync ? `每 ${config.intervalMinutes} 分钟` : '关闭'}`)
+}
+
+/** 供离线自测脚本使用。 */
+export { buildInventory, readLinkPlugins, profileName }