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

package/sync.js

@@ -0,0 +1,1548 @@
+/**
+ * dsh-cloud-sync — 同步引擎（Host 侧，不依赖任何第三方包）。
+ *
+ * 设计要点
+ * ────────
+ * 1. 通道只用 SSH：复用用户已有的 jdcloud 私钥，服务器上不装服务、不开端口。
+ *    传输协议 = 自带实现的 tar 流（不经 Windows 自带 tar，避免 GBK 代码页把中文名
+ *    写坏；也不经 scp，少一个二进制依赖），直接管道进 `ssh ... tar -xf -`。
+ * 2. 增量：客户端扫一份清单（相对路径 + 大小 + mtime），与服务端 manifest.json 比，
+ *    只传变化的文件；mtime 容差 2 秒（tar 只存到秒）。
+ * 3. 删除传播：本地没有、服务端有的条目 → 服务端挪进 trash/<时间戳>/，保留 N 天
+ *    后自动清理。这样会话临时目录插件 7 天清理掉的老会话、老附件，云端不会越攒越多。
+ * 4. 覆盖留底：推送覆盖前把服务端旧版本拷进 versions/<时间戳>/，保留 N 天。
+ * 5. 恢复只补不删：拉取只写「本地没有」或「云端更新」的文件，覆盖前先备份到
+ *    <DSH_HOME>/.cloud-sync/backup/<时间戳>/；最近 5 分钟内改过的本地文件一律跳过。
+ *
+ * 目录结构（服务端）
+ *   /opt/dsh-sync/machines/<机器名>/manifest.json
+ *   /opt/dsh-sync/machines/<机器名>/files/dsh/...               ← ~/.dsh 里的同步内容
+ *   /opt/dsh-sync/machines/<机器名>/files/plugins/<名字>/...     ← 本地 link 插件源码
+ *   /opt/dsh-sync/trash/<时间戳>/...                             ← 删除回收站
+ *   /opt/dsh-sync/versions/<时间戳>/...                          ← 被覆盖的旧版本
+ */
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { spawn } from 'node:child_process'
+
+/* ── 配置 ───────────────────────────────────────────────────────────────── */
+
+/**
+ * 默认值。**包内不含任何服务器地址与密钥路径**：`host` / `identityFile` 必须由使用者在
+ * profile 的 `cordis.patch.yml` 里显式配置（或由 Agent 代填），没配置时插件不联网。
+ */
+export const DEFAULTS = {
+  host: '',
+  port: 22,
+  identityFile: '',
+  remoteRoot: '/opt/dsh-sync',
+  connectionFile: '',
+  machineId: '',
+  localPluginRoot: 'D:/DSH工作区',
+  intervalMinutes: 5,
+  dailySync: false,
+  autoSync: true,
+  applyRemoteDeletes: true,
+  pauseWhenIdle: true,
+  idlePauseMinutes: 10,
+  restoreOnEmpty: true,
+  includeAttachments: true,
+  includeCredentials: true,
+  includeKeyruleSecrets: true,
+  includeLocalPlugins: true,
+  quietSeconds: 10,
+  trashDays: 14,
+  versionDays: 7,
+  backupDays: 7,
+}
+
+/**
+ * 读「连接信息」文件（默认 `<DSH_HOME>/keyrule-secrets/ssh.json`）。
+ * 这样服务器地址不用写死在插件里，跟着钥则目录一起同步即可。
+ * 格式：{"host":"root@1.2.3.4","identityFile":"C:/.../key.pem","port":22}
+ */
+function readConnectionFile(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, '')
+    const parsed = JSON.parse(raw)
+    return parsed !== null && typeof parsed === 'object' ? parsed : {}
+  } catch {
+    return {}
+  }
+}
+
+/** 把 Config 里的值归一化成一个纯对象（缺省值补齐、数字转正、字符串去空格）。 */
+export function normalizeConfig(raw) {
+  const input = raw !== null && typeof raw === 'object' ? raw : {}
+  const pick = (key) => (input[key] === undefined || input[key] === null ? DEFAULTS[key] : input[key])
+  const num = (value, fallback, min) => {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) && parsed >= min ? Math.round(parsed) : fallback
+  }
+  const text = (value, fallback) => {
+    const trimmed = typeof value === 'string' ? value.trim() : ''
+    return trimmed === '' ? fallback : trimmed
+  }
+  const flag = (value, fallback) => (typeof value === 'boolean' ? value : fallback)
+  const out = {
+    host: text(pick('host'), DEFAULTS.host),
+    port: num(pick('port'), DEFAULTS.port, 1),
+    identityFile: text(pick('identityFile'), DEFAULTS.identityFile).replace(/\\/g, '/'),
+    connectionFile: text(pick('connectionFile'), DEFAULTS.connectionFile),
+    remoteRoot: text(pick('remoteRoot'), DEFAULTS.remoteRoot).replace(/\/+$/, '') || DEFAULTS.remoteRoot,
+    machineId: sanitizeMachineId(text(pick('machineId'), '')),
+    localPluginRoot: text(pick('localPluginRoot'), DEFAULTS.localPluginRoot).replace(/\\/g, '/').replace(/\/+$/, ''),
+    intervalMinutes: num(pick('intervalMinutes'), DEFAULTS.intervalMinutes, 1),
+    dailySync: flag(pick('dailySync'), DEFAULTS.dailySync),
+    autoSync: flag(pick('autoSync'), DEFAULTS.autoSync),
+    applyRemoteDeletes: flag(pick('applyRemoteDeletes'), DEFAULTS.applyRemoteDeletes),
+    pauseWhenIdle: flag(pick('pauseWhenIdle'), DEFAULTS.pauseWhenIdle),
+    idlePauseMinutes: num(pick('idlePauseMinutes'), DEFAULTS.idlePauseMinutes, 1),
+    restoreOnEmpty: flag(pick('restoreOnEmpty'), DEFAULTS.restoreOnEmpty),
+    includeAttachments: flag(pick('includeAttachments'), DEFAULTS.includeAttachments),
+    includeCredentials: flag(pick('includeCredentials'), DEFAULTS.includeCredentials),
+    includeKeyruleSecrets: flag(pick('includeKeyruleSecrets'), DEFAULTS.includeKeyruleSecrets),
+    includeLocalPlugins: flag(pick('includeLocalPlugins'), DEFAULTS.includeLocalPlugins),
+    quietSeconds: num(pick('quietSeconds'), DEFAULTS.quietSeconds, 0),
+    trashDays: num(pick('trashDays'), DEFAULTS.trashDays, 1),
+    versionDays: num(pick('versionDays'), DEFAULTS.versionDays, 1),
+    backupDays: num(pick('backupDays'), DEFAULTS.backupDays, 1),
+  }
+  // 连接信息可以不写进配置：默认去钥则目录读 keyrule-secrets/ssh.json（该目录本身在同步范围内）
+  if (out.host === '') {
+    const file = out.connectionFile !== ''
+      ? out.connectionFile
+      : path.join(dshHome(), 'keyrule-secrets', 'ssh.json')
+    const saved = readConnectionFile(file)
+    if (typeof saved.host === 'string' && saved.host.trim() !== '') out.host = saved.host.trim()
+    if (out.identityFile === '' && typeof saved.identityFile === 'string' && saved.identityFile.trim() !== '') {
+      out.identityFile = saved.identityFile.trim().replace(/\\/g, '/')
+    }
+    if (saved.port !== undefined && Number.isFinite(Number(saved.port)) && Number(saved.port) > 0) {
+      out.port = Math.round(Number(saved.port))
+    }
+  }
+  return out
+}
+
+/** 是否已经配置好服务器（没配置时不联网、不报错，只提示去填）。 */
+export function isConfigured(config) {
+  return typeof config?.host === 'string' && config.host.trim() !== ''
+}
+
+/** 机器名只用安全字符，避免拼进远程脚本时出事。 */
+export function sanitizeMachineId(value) {
+  const cleaned = String(value ?? '').trim().replace(/[^A-Za-z0-9._-]/g, '-').replace(/^-+|-+$/g, '')
+  return cleaned.slice(0, 48)
+}
+
+/** 当前机器名（默认用主机名；用户可在 Config 里覆盖）。 */
+export function defaultMachineId() {
+  try {
+    return sanitizeMachineId(os.hostname()) || 'machine'
+  } catch {
+    return 'machine'
+  }
+}
+
+/** DSH 主目录。 */
+export function dshHome() {
+  return process.env.DSH_HOME !== undefined && process.env.DSH_HOME !== ''
+    ? process.env.DSH_HOME
+    : path.join(os.homedir(), '.dsh')
+}
+
+/** 当前 profile 名。 */
+export function profileName() {
+  return process.env.DSH_PROFILE !== undefined && process.env.DSH_PROFILE !== '' ? process.env.DSH_PROFILE : 'desktop'
+}
+
+/** 当前 profile 目录。 */
+export function profileDir(dshRoot = dshHome(), profile = profileName()) {
+  return process.env.DSH_PROFILE_DIR !== undefined && process.env.DSH_PROFILE_DIR !== ''
+    ? process.env.DSH_PROFILE_DIR
+    : path.join(dshRoot, 'profiles', profile)
+}
+
+/**
+ * 找到 dshRoot 对应的 profile 目录：只有 dshRoot 就是真正的 DSH 主目录时才用
+ * `DSH_PROFILE_DIR`（自测/恢复到一个临时目录时不能被骗）。
+ */
+function resolveProfileDir(dshRoot, profile, explicit) {
+  if (explicit !== undefined && explicit !== '') return explicit
+  try {
+    if (path.resolve(dshRoot) === path.resolve(dshHome())) return profileDir(dshRoot, profile)
+  } catch { /* 比较失败就退回默认推导 */ }
+  return path.join(dshRoot, 'profiles', profile)
+}
+
+/* ── 本地记忆：删过的文件（墓碑）与本机拥有过的文件清单 ────────────────── */
+
+function cloudStateDir(dshRoot) {
+  return path.join(dshRoot, '.cloud-sync')
+}
+
+function listDirSafe(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return []
+  }
+}
+
+function readJsonSafe(file, fallback) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+    return parsed !== null && typeof parsed === 'object' ? parsed : fallback
+  } catch {
+    return fallback
+  }
+}
+
+function writeJsonSafe(file, value) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const temp = `${file}.tmp`
+    fs.writeFileSync(temp, JSON.stringify(value), 'utf8')
+    fs.renameSync(temp, file)
+  } catch { /* 记忆文件写不进去不影响同步本身 */ }
+}
+
+/** 本机删掉过的文件（相对路径 → 删除时间）。恢复时遇到它就不拉回来。 */
+export function readTombstones(dshRoot) {
+  return readJsonSafe(path.join(cloudStateDir(dshRoot), 'tombstones.json'), {})
+}
+
+function writeTombstones(dshRoot, map) {
+  const cutoff = Date.now() - 90 * 24 * 60 * 60 * 1000
+  const kept = {}
+  for (const [rel, at] of Object.entries(map ?? {})) {
+    if (Number(at) >= cutoff) kept[rel] = Number(at)
+  }
+  writeJsonSafe(path.join(cloudStateDir(dshRoot), 'tombstones.json'), kept)
+}
+
+/** 本机「确实拥有过」的文件（相对路径 → {s,m}）：用来区分「本地删了」和「新机还没有」。 */
+export function readKnown(dshRoot) {
+  return readJsonSafe(path.join(cloudStateDir(dshRoot), 'known.json'), {})
+}
+
+function writeKnown(dshRoot, map) {
+  writeJsonSafe(path.join(cloudStateDir(dshRoot), 'known.json'), map)
+}
+
+/**
+ * 清理本机 .cloud-sync 下的历史垃圾：过期的恢复备份目录、崩在半路的暂存目录。
+ * 只动插件自己建的 backup/ 与 staging/，不碰别的。
+ */
+export function pruneLocalState(dshRoot, backupDays) {
+  const removed = { backups: 0, staging: 0, quarantined: 0 }
+  const cutoff = Date.now() - Math.max(1, backupDays) * 24 * 60 * 60 * 1000
+  for (const [key, dirName] of [['backups', 'backup'], ['quarantined', 'removed']]) {
+    const root = path.join(cloudStateDir(dshRoot), dirName)
+    for (const entry of listDirSafe(root)) {
+      if (!entry.isDirectory()) continue
+      const full = path.join(root, entry.name)
+      try {
+        if (fs.statSync(full).mtimeMs < cutoff) {
+          fs.rmSync(full, { recursive: true, force: true })
+          removed[key] += 1
+        }
+      } catch { /* 单个删不掉就留到下次 */ }
+    }
+  }
+  const stagingRoot = path.join(cloudStateDir(dshRoot), 'staging')
+  const stagingCutoff = Date.now() - 24 * 60 * 60 * 1000
+  for (const entry of listDirSafe(stagingRoot)) {
+    const full = path.join(stagingRoot, entry.name)
+    try {
+      if (fs.statSync(full).mtimeMs < stagingCutoff) {
+        fs.rmSync(full, { recursive: true, force: true })
+        removed.staging += 1
+      }
+    } catch { /* 同上 */ }
+  }
+  return removed
+}
+
+/* ── 跨机共享的删除记录（云端 shared/tombstones.json） ─────────────────── */
+
+/** 合并多份删除记录：同一路径取最晚的删除时间。 */
+export function mergeTombstones(...maps) {
+  const out = {}
+  for (const map of maps) {
+    for (const [rel, at] of Object.entries(map ?? {})) {
+      const ts = Number(at) || 0
+      if (ts > (out[rel] ?? 0)) out[rel] = ts
+    }
+  }
+  return out
+}
+
+async function readSharedTombstones(config) {
+  const file = `${config.remoteRoot}/shared/tombstones.json`
+  try {
+    const result = await runSsh(config, `cat ${shQuote(file)} 2>/dev/null || true`)
+    if (result.code !== 0 || result.stdout.trim() === '') return {}
+    const parsed = JSON.parse(result.stdout)
+    const out = {}
+    for (const [rel, at] of Object.entries(parsed ?? {})) {
+      if (!isSafeRel(rel)) continue
+      const ts = Number(at) || 0
+      if (ts > 0) out[rel] = ts
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+async function writeSharedTombstones(config, map) {
+  const cutoff = Date.now() - 180 * 24 * 60 * 60 * 1000
+  const kept = {}
+  for (const [rel, at] of Object.entries(map ?? {})) {
+    if (Number(at) >= cutoff) kept[rel] = Number(at)
+  }
+  const file = `${config.remoteRoot}/shared/tombstones.json`
+  await runSsh(config, `mkdir -p ${shQuote(`${config.remoteRoot}/shared`)} && cat > ${shQuote(file)}`, {
+    stdin: JSON.stringify(kept),
+  })
+  return kept
+}
+
+/** 把本机的删除记录并进云端共享文件（只增不减，按最晚时间合并）；revived 里的条目会被撤掉。 */
+async function syncSharedTombstones(config, tombstones, log, revived = []) {
+  try {
+    const sharedAfter = await readSharedTombstones(config)
+    for (const rel of revived) delete sharedAfter[rel]
+    const merged = mergeTombstones(sharedAfter, tombstones)
+    for (const rel of revived) delete merged[rel]
+    if (JSON.stringify(merged) === JSON.stringify(sharedAfter)) return
+    await writeSharedTombstones(config, merged)
+  } catch (error) {
+    log(`同步删除记录失败（不影响本次操作）：${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+/**
+ * 跨机删除的范围：**默认整个 ~/.dsh 都跟随**（会话、storages、data、附件，以及
+ * 插件在 ~/.dsh 下自己建的数据目录，如 h3-kit / llm-deepseek）。
+ * 只有这几类永远不跨机删除——别的机器可能还要用，删了会让那边登录失效或插件加载失败：
+ *   - `plugins/`：本地 link 插件源码，靠 npm 版本管理；
+ *   - `dsh/profiles/`：profile 配置，靠「覆盖更新」而不是删除来同步；
+ *   - `dsh/.credentials.yaml`、`dsh/keyrule-secrets/`：凭据与密钥。
+ */
+const CROSS_MACHINE_DELETE_EXCLUDE = ['plugins/', 'dsh/profiles/', 'dsh/.credentials.yaml', 'dsh/keyrule-secrets/']
+
+/** 导出给自测/诊断用：这条相对路径会不会跟着别的机器一起删。 */
+export function crossMachineDeletable(rel) {
+  return !CROSS_MACHINE_DELETE_EXCLUDE.some((prefix) => rel.startsWith(prefix))
+}
+
+/**
+ * 把共享删除记录落到本机：比删除记录旧的文件移到 `.cloud-sync/removed/<时间戳>/`（可找回）。
+ * 比记录新的文件视为「删掉后又被重建」，保留不动，由调用方把记录撤掉。
+ * @returns {Promise<{removed: string[], revived: string[]}>}
+ */
+export async function applyTombstones(options) {
+  const config = options.config
+  const dshRoot = options.dshRoot ?? dshHome()
+  const log = options.log ?? (() => {})
+  const tombstones = options.tombstones ?? {}
+  const inventory = buildInventory({ config, dshHome: dshRoot, profile: options.profile })
+  const removed = []
+  const revived = []
+  const stamp = timestamp()
+  for (const [rel, at] of Object.entries(tombstones)) {
+    if (!crossMachineDeletable(rel)) continue
+    const entry = inventory.entries.get(rel)
+    if (entry === undefined) continue
+    if (entry.mtimeMs > Number(at) + 2000) {
+      revived.push(rel)
+      continue
+    }
+    const quarantine = path.join(dshRoot, '.cloud-sync', 'removed', stamp, ...rel.split('/'))
+    try {
+      await fsp.mkdir(path.dirname(quarantine), { recursive: true })
+      await fsp.rename(entry.abs, quarantine)
+      removed.push(rel)
+    } catch (error) {
+      log(`无法移除 ${rel}：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  return { removed, revived }
+}
+
+/* ── 命令执行 ───────────────────────────────────────────────────────────── */
+
+/** Windows 自带 OpenSSH 的绝对路径（PATH 里没有时兜底）。 */
+function sshBinary() {
+  if (process.platform !== 'win32') return 'ssh'
+  const candidates = [
+    process.env.DSH_CLOUD_SYNC_SSH,
+    path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'OpenSSH', 'ssh.exe'),
+  ].filter((item) => typeof item === 'string' && item !== '')
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) return candidate
+    } catch { /* 下一个候选 */ }
+  }
+  return 'ssh'
+}
+
+/** 远程命令里出现的字符串一律单引号包裹。 */
+export function shQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`
+}
+
+/** 拼出 ssh 的固定参数（不含目标与命令）。 */
+function sshOptions(config) {
+  const args = ['-p', String(config.port), '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=15', '-o', 'ServerAliveInterval=20', '-o', 'StrictHostKeyChecking=accept-new']
+  if (config.identityFile !== '' && fs.existsSync(config.identityFile)) args.push('-i', config.identityFile)
+  return args
+}
+
+/** 打开一条 ssh 通道，返回子进程（stdin/stdout 均为管道）。 */
+export function spawnSsh(config, remoteCommand) {
+  const args = [...sshOptions(config), config.host, remoteCommand]
+  return spawnChild(sshBinary(), args)
+}
+
+function spawnChild(bin, args) {
+  return spawn(bin, args, { windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })
+}
+
+/** 跑一条远程命令，收集输出；超时就杀掉，避免一个卡住的连接拖死整个任务。 */
+export async function runSsh(config, remoteCommand, options = {}) {
+  const child = spawnSsh(config, remoteCommand)
+  const out = []
+  const err = []
+  child.stdout.on('data', (chunk) => out.push(chunk))
+  child.stderr.on('data', (chunk) => err.push(chunk))
+  if (options.stdin !== undefined) child.stdin.end(options.stdin)
+  else child.stdin.end()
+  const timeoutMs = options.timeoutMs ?? 60000
+  const timer = setTimeout(() => child.kill(), timeoutMs)
+  if (typeof timer.unref === 'function') timer.unref()
+  const code = await new Promise((resolve, reject) => {
+    child.on('error', reject)
+    child.on('close', resolve)
+  }).finally(() => clearTimeout(timer))
+  return {
+    code,
+    stdout: Buffer.concat(out).toString('utf8'),
+    stderr: Buffer.concat(err).toString('utf8'),
+  }
+}
+
+/* ── tar 流（自带实现） ─────────────────────────────────────────────────── */
+
+const BLOCK = 512
+/** 传输卡死判定：连续这么久没收到/发出数据就杀掉 ssh，让任务失败重试而不是永远挂着。 */
+const STALL_MS = 120000
+
+function octal(value, width) {
+  const text = Math.max(0, Math.floor(value)).toString(8)
+  return text.padStart(width - 1, '0').slice(-(width - 1)) + '\0'
+}
+
+/** ustar：把长路径拆成 prefix(155) + name(100)；拆不开返回 undefined。 */
+function ustarSplit(name) {
+  const bytes = Buffer.byteLength(name, 'utf8')
+  if (bytes <= 100) return { name, prefix: '' }
+  for (let index = name.lastIndexOf('/'); index > 0; index = name.lastIndexOf('/', index - 1)) {
+    const prefix = name.slice(0, index)
+    const rest = name.slice(index + 1)
+    if (Buffer.byteLength(prefix, 'utf8') <= 155 && Buffer.byteLength(rest, 'utf8') <= 100) {
+      return { prefix, name: rest }
+    }
+  }
+  if (bytes > 255) return undefined
+  const lastSlash = name.lastIndexOf('/')
+  return { name: name.slice(lastSlash + 1), prefix: name.slice(0, lastSlash) }
+}
+
+function tarHeader(fields) {
+  const header = Buffer.alloc(BLOCK, 0)
+  header.write(fields.name ?? '', 0, 100, 'utf8')
+  header.write(octal(fields.mode ?? 0o644, 8), 100, 8, 'ascii')
+  header.write(octal(0, 8), 108, 8, 'ascii')
+  header.write(octal(0, 8), 116, 8, 'ascii')
+  header.write(octal(fields.size ?? 0, 12), 124, 12, 'ascii')
+  header.write(octal(fields.mtime ?? 0, 12), 136, 12, 'ascii')
+  header.write('        ', 148, 8, 'ascii')
+  header.write(fields.typeflag ?? '0', 156, 1, 'ascii')
+  header.write(fields.linkname ?? '', 157, 100, 'utf8')
+  header.write('ustar\0', 257, 6, 'ascii')
+  header.write('00', 263, 2, 'ascii')
+  header.write('root', 265, 32, 'ascii')
+  header.write('root', 297, 32, 'ascii')
+  header.write(octal(0, 8), 329, 8, 'ascii')
+  header.write(octal(0, 8), 337, 8, 'ascii')
+  header.write(fields.prefix ?? '', 345, 155, 'utf8')
+  let sum = 0
+  for (let index = 0; index < BLOCK; index += 1) sum += header[index]
+  header.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148, 8, 'ascii')
+  return header
+}
+
+function padding(size) {
+  const rest = size % BLOCK
+  return rest === 0 ? 0 : BLOCK - rest
+}
+
+async function writeChunk(stream, buffer) {
+  if (buffer.length === 0) return
+  if (stream.destroyed || stream.writableEnded) throw new Error('传输通道已关闭')
+  if (stream.write(buffer)) return
+  await new Promise((resolve) => {
+    const cleanup = () => {
+      stream.off('drain', onDrain)
+      stream.off('close', onClose)
+    }
+    const onDrain = () => {
+      cleanup()
+      resolve()
+    }
+    const onClose = () => {
+      cleanup()
+      resolve()
+    }
+    stream.once('drain', onDrain)
+    stream.once('close', onClose)
+  })
+}
+
+/**
+ * 把一批文件写成 tar 流灌进目标流。
+ * @param {import('node:stream').Writable} stream - ssh 的 stdin。
+ * @param {{name: string, abs: string, size: number, mtimeMs: number, mode?: number}[]} entries
+ * @param {(done: number, total: number) => void} [onProgress]
+ */
+export async function writeTar(stream, entries, onProgress) {
+  const total = entries.reduce((sum, entry) => sum + entry.size, 0)
+  let done = 0
+  for (const entry of entries) {
+    const split = ustarSplit(entry.name)
+    let headerName
+    let prefix = ''
+    if (split === undefined) {
+      const longName = Buffer.from(`${entry.name}\0`, 'utf8')
+      await writeChunk(stream, tarHeader({ name: '././@LongLink', mode: 0o644, size: longName.length, mtime: Math.floor(entry.mtimeMs / 1000), typeflag: 'L' }))
+      await writeChunk(stream, longName)
+      await writeChunk(stream, Buffer.alloc(padding(longName.length), 0))
+      headerName = entry.name.slice(entry.name.lastIndexOf('/') + 1).slice(0, 100)
+    } else {
+      headerName = split.name
+      prefix = split.prefix
+    }
+    await writeChunk(stream, tarHeader({
+      name: headerName,
+      prefix,
+      mode: entry.mode ?? 0o644,
+      size: entry.size,
+      mtime: Math.floor(entry.mtimeMs / 1000),
+    }))
+    const handle = await fsp.open(entry.abs, 'r')
+    try {
+      let remaining = entry.size
+      const buffer = Buffer.allocUnsafe(Math.min(1 << 20, Math.max(entry.size, 1)))
+      while (remaining > 0) {
+        const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, remaining), null)
+        if (bytesRead === 0) throw new Error(`文件在打包过程中变短：${entry.abs}`)
+        await writeChunk(stream, buffer.subarray(0, bytesRead))
+        remaining -= bytesRead
+        done += bytesRead
+        if (onProgress !== undefined) onProgress(done, total)
+      }
+    } finally {
+      await handle.close()
+    }
+    const rest = padding(entry.size)
+    if (rest > 0) await writeChunk(stream, Buffer.alloc(rest, 0))
+  }
+  await writeChunk(stream, Buffer.alloc(BLOCK * 2, 0))
+}
+
+/** 带缓冲的字节读取器：从 ssh stdout 里按 tar 头逐块取出内容。 */
+export class ByteReader {
+  constructor(stream, onActivity) {
+    this.iterator = stream[Symbol.asyncIterator]()
+    this.chunk = null
+    this.offset = 0
+    this.ended = false
+    this.total = 0
+    this.onActivity = onActivity
+  }
+
+  async nextChunk() {
+    const { value, done } = await this.iterator.next()
+    if (done === true) {
+      this.ended = true
+      this.chunk = null
+      return false
+    }
+    if (this.onActivity !== undefined) this.onActivity()
+    this.chunk = value
+    this.offset = 0
+    return true
+  }
+
+  async readExact(size) {
+    const parts = []
+    let need = size
+    while (need > 0) {
+      if (this.chunk === null) {
+        if (this.ended || !(await this.nextChunk())) break
+      }
+      const available = this.chunk.length - this.offset
+      if (available <= 0) {
+        this.chunk = null
+        continue
+      }
+      const take = Math.min(available, need)
+      parts.push(this.chunk.subarray(this.offset, this.offset + take))
+      this.offset += take
+      need -= take
+      this.total += take
+      if (this.offset >= this.chunk.length) this.chunk = null
+    }
+    return parts.length === 0 ? Buffer.alloc(0) : parts.length === 1 ? parts[0] : Buffer.concat(parts, size - need)
+  }
+
+  async skip(size) {
+    let need = size
+    while (need > 0) {
+      const part = await this.readExact(Math.min(need, 1 << 20))
+      if (part.length === 0) return
+      need -= part.length
+    }
+  }
+}
+
+function readOctal(buffer, offset, length) {
+  const text = buffer.subarray(offset, offset + length).toString('ascii').replace(/\0.*$/, '').trim()
+  if (text === '') return 0
+  const value = Number.parseInt(text, 8)
+  return Number.isFinite(value) ? value : 0
+}
+
+function readString(buffer, offset, length) {
+  const slice = buffer.subarray(offset, offset + length)
+  const end = slice.indexOf(0)
+  return (end === -1 ? slice : slice.subarray(0, end)).toString('utf8')
+}
+
+function parsePax(buffer) {
+  const out = {}
+  let offset = 0
+  while (offset < buffer.length) {
+    const space = buffer.indexOf(0x20, offset)
+    if (space === -1) break
+    const length = Number.parseInt(buffer.subarray(offset, space).toString('ascii'), 10)
+    if (!Number.isFinite(length) || length <= 0) break
+    const record = buffer.subarray(space + 1, offset + length - 1)
+    const equals = record.indexOf(0x3d)
+    if (equals > 0) out[record.subarray(0, equals).toString('utf8')] = record.subarray(equals + 1).toString('utf8')
+    offset += length
+  }
+  return out
+}
+
+/**
+ * 读 tar 流。回调负责消费每个普通文件的内容。
+ * @param {ByteReader} reader
+ * @param {(file: {name: string, size: number, mtimeMs: number, mode: number, reader: ByteReader}) => Promise<void>} onFile
+ */
+export async function readTar(reader, onFile) {
+  let longName
+  let pax = {}
+  let files = 0
+  for (;;) {
+    const header = await reader.readExact(BLOCK)
+    if (header.length < BLOCK) break
+    if (header.every((byte) => byte === 0)) break
+    const typeflag = header.subarray(156, 157).toString('ascii')
+    const size = readOctal(header, 124, 12)
+    const prefix = readString(header, 345, 155)
+    const baseName = readString(header, 0, 100)
+    const name = longName ?? (prefix === '' ? baseName : `${prefix}/${baseName}`)
+    const mtimeMs = readOctal(header, 136, 12) * 1000
+    const mode = readOctal(header, 100, 8)
+
+    if (typeflag === 'L') {
+      const content = await reader.readExact(size)
+      longName = content.subarray(0, Math.max(0, content.length - 1)).toString('utf8')
+      await reader.skip(padding(size))
+      continue
+    }
+    if (typeflag === 'x') {
+      const content = await reader.readExact(size)
+      pax = parsePax(content)
+      await reader.skip(padding(size))
+      continue
+    }
+    if (typeflag === 'g' || typeflag === 'K') {
+      await reader.skip(size + padding(size))
+      continue
+    }
+    longName = undefined
+    const effectiveName = pax.path !== undefined && pax.path !== '' ? pax.path : name
+    const effectiveMtime = pax.mtime !== undefined ? Math.round(Number.parseFloat(pax.mtime) * 1000) : mtimeMs
+    pax = {}
+    if (typeflag === '0' || typeflag === '\0' || typeflag === ' ' || typeflag === '') {
+      await onFile({ name: effectiveName, size, mtimeMs: effectiveMtime, mode, reader })
+      await reader.skip(padding(size))
+      files += 1
+      continue
+    }
+    // 目录/链接等：跳过内容
+    await reader.skip(size + padding(size))
+  }
+  return { files }
+}
+
+/* ── 清单扫描 ───────────────────────────────────────────────────────────── */
+
+/** 通用排除：任何层级都不带（可重建 / 版本控制 / 日志 / 备份）。 */
+const EXCLUDE_RE = /(?:^|\/)(?:node_modules|\.git|\.DS_Store|\.dsh-market|\.plugin-manager|\.cloud-sync|dsh-runtimes|cache|__pycache__)(?:\/|$)|\.(?:log|tmp|part|swp)$|\.bak(?:[-.]|$)/
+
+/** 机器相关的小文件（用量统计、匿名 ID、旧凭据残片）：不跨机。 */
+const MACHINE_FILES = /^(?:\.dshw-|\.anonymous-user-id$|\.credentials\.yaml\.newmachine$)/
+
+/**
+ * ~/.dsh 里哪些路径要同步：**黑名单制**——默认整目录都带，只排除
+ * 「可重建 / 机器相关 / 不能乱传」的那几类。
+ * 这样任何插件在 ~/.dsh 下新建的目录（h3-kit、llm-deepseek、…）都会自动进入同步，
+ * 不需要再来改代码加白名单。
+ */
+function includeDshFile(rel, config, profile) {
+  if (rel === '') return false
+  if (EXCLUDE_RE.test(rel)) return false
+  const base = rel.slice(rel.lastIndexOf('/') + 1)
+  if (MACHINE_FILES.test(base)) return false
+  // 会话临时目录簿记：本机专用，换机没意义
+  if (rel.startsWith('data/') && rel.slice(5).startsWith('session-tmpdir-')) return false
+  // 三个开关关掉时，等同于把对应内容加进黑名单
+  if (!config.includeAttachments && rel.startsWith('attachments/')) return false
+  if (!config.includeCredentials && rel === '.credentials.yaml') return false
+  if (!config.includeKeyruleSecrets && rel.startsWith('keyrule-secrets/')) return false
+  return true
+}
+
+function includePluginFile(rel) {
+  if (rel === '') return false
+  if (EXCLUDE_RE.test(rel)) return false
+  if (rel.startsWith('_tmp/') || rel.startsWith('node_modules/')) return false
+  return true
+}
+
+/** 读 profile 的 package.json，取出所有 link: 插件（名字 + 绝对目录）。 */
+export function readLinkPlugins(dir) {
+  const file = path.join(dir, 'package.json')
+  if (!fs.existsSync(file)) return []
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))
+  } catch {
+    return []
+  }
+  const out = []
+  for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
+    if (typeof spec !== 'string' || !spec.startsWith('link:')) continue
+    const target = spec.slice(5).replace(/\\/g, '/').replace(/\/+$/, '')
+    out.push({ name, target })
+  }
+  return out
+}
+
+function walkTree(root, prefix, include, out, errors) {
+  const stack = ['']
+  while (stack.length > 0) {
+    const rel = stack.pop()
+    const dir = rel === '' ? root : path.join(root, rel.split('/').join(path.sep))
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch (error) {
+      if (rel !== '') errors.push(`${prefix}/${rel}: ${error instanceof Error ? error.message : String(error)}`)
+      continue
+    }
+    for (const entry of entries) {
+      const childRel = rel === '' ? entry.name : `${rel}/${entry.name}`
+      const full = path.join(root, childRel.split('/').join(path.sep))
+      if (entry.isDirectory()) {
+        if (EXCLUDE_RE.test(`${childRel}/`)) continue
+        stack.push(childRel)
+        continue
+      }
+      if (!entry.isFile()) continue
+      if (!include(childRel)) continue
+      try {
+        const stat = fs.statSync(full)
+        out.set(`${prefix}/${childRel}`, {
+          abs: full,
+          size: stat.size,
+          mtimeMs: Math.round(stat.mtimeMs),
+          mode: (stat.mode & 0o111) !== 0 ? 0o755 : 0o644,
+        })
+      } catch (error) {
+        errors.push(`${prefix}/${childRel}: ${error instanceof Error ? error.message : String(error)}`)
+      }
+    }
+  }
+}
+
+/**
+ * 扫描本地同步集合。
+ * @returns {{entries: Map<string, {abs: string, size: number, mtimeMs: number, mode: number}>, errors: string[], plugins: {name: string, target: string, exists: boolean}[]}}
+ */
+export function buildInventory(options) {
+  const config = options.config
+  const dshRoot = options.dshHome ?? dshHome()
+  const profile = options.profile ?? profileName()
+  const entries = new Map()
+  const errors = []
+  walkTree(dshRoot, 'dsh', (rel) => includeDshFile(rel, config, profile), entries, errors)
+
+  const plugins = []
+  if (config.includeLocalPlugins) {
+    const dir = resolveProfileDir(dshRoot, profile, options.profileDir)
+    for (const plugin of readLinkPlugins(dir)) {
+      const exists = fs.existsSync(plugin.target)
+      plugins.push({ ...plugin, exists })
+      if (!exists) {
+        errors.push(`插件 ${plugin.name} 的目录不存在：${plugin.target}`)
+        continue
+      }
+      walkTree(plugin.target, `plugins/${plugin.name}`, includePluginFile, entries, errors)
+    }
+  }
+  return { entries, errors, plugins }
+}
+
+/** 供状态面板估算本地同步集合大小，不触发任何传输。 */
+export function localSummary(config) {
+  const inventory = buildInventory({ config, dshHome: dshHome(), profile: profileName() })
+  let bytes = 0
+  for (const entry of inventory.entries.values()) bytes += entry.size
+  return { files: inventory.entries.size, bytes, errors: inventory.errors.length, plugins: inventory.plugins.length }
+}
+
+/** 只算本地指纹（不联网）：用来判断「这一轮到底有没有变化」。 */
+export function localFingerprint(config, dshRoot = dshHome(), profile = profileName()) {
+  return inventoryFingerprint(buildInventory({ config, dshHome: dshRoot, profile }))
+}
+
+/* ── 远程操作 ───────────────────────────────────────────────────────────── */
+
+function machineDir(config, machineId) {
+  return `${config.remoteRoot}/machines/${machineId}`
+}
+
+/** 确保服务端目录存在。 */
+export async function ensureRemoteRoot(config) {
+  const script = [
+    `mkdir -p ${shQuote(`${config.remoteRoot}/machines`)} ${shQuote(`${config.remoteRoot}/trash`)} ${shQuote(`${config.remoteRoot}/versions`)}`,
+    'echo READY',
+  ].join('\n')
+  const result = await runSsh(config, script)
+  if (result.code !== 0 || !result.stdout.includes('READY')) {
+    throw new Error(`无法在服务器上准备目录（退出码 ${result.code}）：${result.stderr.trim() || result.stdout.trim()}`)
+  }
+}
+
+/** 拉取某台机器的 manifest（不存在时返回空清单）。 */
+export async function readRemoteManifest(config, machineId) {
+  const file = `${machineDir(config, machineId)}/manifest.json`
+  const result = await runSsh(config, `cat ${shQuote(file)} 2>/dev/null || true`)
+  const text = result.stdout.trim()
+  if (text === '') return { version: 1, machine: machineId, updatedAt: '', entries: {} }
+  try {
+    const parsed = JSON.parse(text)
+    return {
+      version: 1,
+      machine: typeof parsed.machine === 'string' ? parsed.machine : machineId,
+      updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+      entries: parsed.entries !== null && typeof parsed.entries === 'object' ? parsed.entries : {},
+    }
+  } catch {
+    throw new Error('服务端 manifest.json 解析失败（可能写坏，可在服务器上删掉它再全量推一次）')
+  }
+}
+
+/** 列出服务端已有的机器槽位。 */
+export async function listMachines(config) {
+  const script = [
+    `cd ${shQuote(config.remoteRoot)} 2>/dev/null || { echo NO_ROOT; exit 0; }`,
+    'echo ROOT',
+    'for d in machines/*/; do',
+    '  [ -d "$d" ] || continue',
+    '  id=${d#machines/}; id=${id%/}',
+    '  if [ -f "machines/$id/manifest.json" ]; then',
+    '    echo "M $id $(stat -c %s "machines/$id/manifest.json" 2>/dev/null || echo 0) $(stat -c %Y "machines/$id/manifest.json" 2>/dev/null || echo 0) $(du -sb "machines/$id/files" 2>/dev/null | cut -f1)"',
+    '  else',
+    '    echo "M $id 0 0 0"',
+    '  fi',
+    'done',
+    'echo "DF $(df -B1 /opt 2>/dev/null | awk \'NR==2{print $4}\')"',
+  ].join('\n')
+  const result = await runSsh(config, script)
+  const machines = []
+  let freeBytes
+  for (const line of result.stdout.split(/\r?\n/)) {
+    if (line.startsWith('M ')) {
+      const [, id, manifestBytes, manifestMtime, filesBytes] = line.split(' ')
+      machines.push({
+        id,
+        manifestBytes: Number(manifestBytes) || 0,
+        manifestMtime: (Number(manifestMtime) || 0) * 1000,
+        filesBytes: Number(filesBytes) || 0,
+      })
+    } else if (line.startsWith('DF ')) {
+      freeBytes = Number(line.slice(3)) || undefined
+    }
+  }
+  return { ok: result.code === 0, machines, freeBytes, error: result.code === 0 ? undefined : result.stderr.trim() }
+}
+
+/* ── 推送 ───────────────────────────────────────────────────────────────── */
+
+function groupOf(rel) {
+  const parts = rel.split('/')
+  if (parts[0] === 'plugins' && parts.length > 2) return `plugins/${parts[1]}`
+  return parts[0]
+}
+
+function memberOf(rel) {
+  const parts = rel.split('/')
+  if (parts[0] === 'plugins' && parts.length > 2) return parts.slice(2).join('/')
+  return parts.slice(1).join('/')
+}
+
+function rootOf(group, options) {
+  if (group === 'dsh') return options.dshHome
+  const plugin = options.plugins.find((item) => `plugins/${item.name}` === group)
+  return plugin?.target
+}
+
+/** 本地同步集合的「指纹」：文件数 + 总字节 + 最大 mtime。用来判断这一轮要不要连服务器。 */
+function inventoryFingerprint(inventory) {
+  let bytes = 0
+  let maxMtime = 0
+  for (const entry of inventory.entries.values()) {
+    bytes += entry.size
+    if (entry.mtimeMs > maxMtime) maxMtime = entry.mtimeMs
+  }
+  return `${inventory.entries.size}:${bytes}:${maxMtime}`
+}
+
+/** 一次 ssh 连接里备好目录并取回共享删除记录（省一次握手）。 */
+async function bootRemote(config) {
+  const script = [
+    `mkdir -p ${shQuote(`${config.remoteRoot}/machines`)} ${shQuote(`${config.remoteRoot}/trash`)} ${shQuote(`${config.remoteRoot}/versions`)} ${shQuote(`${config.remoteRoot}/shared`)}`,
+    'echo ===DSH_TOMBSTONES===',
+    `cat ${shQuote(`${config.remoteRoot}/shared/tombstones.json`)} 2>/dev/null || true`,
+  ].join('\n')
+  const result = await runSsh(config, script)
+  if (result.code !== 0) {
+    throw new Error(`连不上服务器（退出码 ${result.code}）：${result.stderr.trim() || result.stdout.trim()}`)
+  }
+  const [, tail = ''] = result.stdout.split('===DSH_TOMBSTONES===')
+  const tombstones = {}
+  try {
+    const parsed = JSON.parse(tail.trim() || '{}')
+    for (const [rel, at] of Object.entries(parsed ?? {})) {
+      if (!isSafeRel(rel)) continue
+      const ts = Number(at) || 0
+      if (ts > 0) tombstones[rel] = ts
+    }
+  } catch { /* 记录文件坏了就当空的，下一轮推送会重建 */ }
+  return tombstones
+}
+
+/**
+ * 增量推送。删除走服务端回收站，覆盖前留旧版本。
+ * @returns {Promise<object>} 结果摘要
+ */
+export async function push(options) {
+  const config = options.config
+  if (!isConfigured(config)) throw new Error('未配置服务器：请在 profile 的 cordis.patch.yml 里设置 host（和 identityFile），或让 Agent 帮忙填')
+  const log = options.log ?? (() => {})
+  const machine = config.machineId !== '' ? config.machineId : defaultMachineId()
+  const dshRoot = options.dshHome ?? dshHome()
+  const profile = options.profile ?? profileName()
+
+  // 先按云端共享的删除记录清理本机：别的机器删掉的东西，这台也别留着、也别再传回去
+  const sharedBefore = await bootRemote(config)
+  let applied = { removed: [], revived: [] }
+  if (config.applyRemoteDeletes && Object.keys(sharedBefore).length > 0) {
+    applied = await applyTombstones({ config, dshRoot, profile, tombstones: sharedBefore, log })
+    if (applied.removed.length > 0) log(`按云端删除记录移除本机 ${applied.removed.length} 个文件（放进 .cloud-sync/removed/，可找回）`)
+    if (applied.revived.length > 0) log(`另有 ${applied.revived.length} 个文件比删除记录新，保留`)
+  }
+
+  const inventory = buildInventory({ config, dshHome: dshRoot, profile, profileDir: options.profileDir })
+  const fingerprint = inventoryFingerprint(inventory)
+
+  // 快速通道：本地文件和上一轮成功推送时一模一样、也没被云端删除记录改动过
+  // → 云端清单不可能变（这个槽位只有本机在写），不必再拉 179KB 的 manifest
+  const fpFile = path.join(cloudStateDir(dshRoot), 'fingerprint.json')
+  const previousFingerprint = readJsonSafe(fpFile, {})
+  if (previousFingerprint.value === fingerprint
+    && Number(previousFingerprint.deferred) === 0
+    && applied.removed.length === 0) {
+    writeTombstones(dshRoot, mergeTombstones(readTombstones(dshRoot), sharedBefore))
+    log(`本地无变化，跳过清单比对（${inventory.entries.size} 个文件）`)
+    return { ok: true, skipped: true, fastPath: true, machine, uploaded: 0, deleted: 0, deferred: 0, total: inventory.entries.size, bytes: 0 }
+  }
+
+  log(`扫描完成：${inventory.entries.size} 个文件${inventory.errors.length === 0 ? '' : `（${inventory.errors.length} 个读取失败）`}`)
+
+  const remote = await readRemoteManifest(config, machine)
+  const remoteCount = Object.keys(remote.entries).length
+  // 本地记忆：删过的文件（墓碑，含云端共享的）与「确实拥有过」的清单。本地又出现的文件要清掉墓碑。
+  const tombstones = mergeTombstones(readTombstones(dshRoot), sharedBefore)
+  for (const rel of inventory.entries.keys()) delete tombstones[rel]
+  // 跳过最近 quietSeconds 内还在写的文件：它们下一轮再传。真正的防撕裂靠后面的暂存核对。
+  const quietMs = config.quietSeconds * 1000
+  const cutoff = Date.now() - quietMs
+
+  const changed = []
+  const deferred = []
+  for (const [rel, entry] of inventory.entries) {
+    const previous = remote.entries[rel]
+    const same = previous !== undefined
+      && Number(previous.s) === entry.size
+      && Math.abs(Number(previous.m) - entry.mtimeMs) <= 2000
+    if (same) continue
+    if (quietMs > 0 && entry.mtimeMs > cutoff) {
+      deferred.push(rel)
+      continue
+    }
+    changed.push(rel)
+  }
+
+  const deletions = []
+  if (inventory.errors.length === 0) {
+    for (const rel of Object.keys(remote.entries)) {
+      if (inventory.entries.has(rel)) continue
+      // 某个类别被关掉时，不要把它当成「本地删了」去清云端
+      if (!config.includeLocalPlugins && rel.startsWith('plugins/')) continue
+      if (!config.includeAttachments && rel.startsWith('dsh/attachments/')) continue
+      if (!config.includeCredentials && rel === 'dsh/.credentials.yaml') continue
+      if (!config.includeKeyruleSecrets && rel.startsWith('dsh/keyrule-secrets/')) continue
+      deletions.push(rel)
+      tombstones[rel] = Date.now()
+    }
+  } else {
+    log(`有 ${inventory.errors.length} 个文件读不到，本次跳过删除传播（避免误删云端文件）`)
+  }
+
+  log(`云端已有 ${remoteCount} 个文件；本次待传 ${changed.length} 个、待删 ${deletions.length} 个、留到下轮 ${deferred.length} 个`)
+  if (changed.length === 0 && deletions.length === 0) {
+    writeTombstones(dshRoot, tombstones)
+    if (deferred.length === 0) writeJsonSafe(fpFile, { value: fingerprint, deferred: 0 })
+    return { ok: true, skipped: true, machine, uploaded: 0, deleted: 0, total: inventory.entries.size, deferred: deferred.length, bytes: 0 }
+  }
+
+  const mDir = machineDir(config, machine)
+  // 每台机器用自己的 incoming 目录：多台同时推时不会互相清掉对方的上传
+  const incomingDir = `${mDir}/incoming/${machine}`
+  const setup = await runSsh(config, `rm -rf ${shQuote(incomingDir)} && mkdir -p ${shQuote(incomingDir)}`)
+  if (setup.code !== 0) throw new Error(`服务端准备目录失败：${setup.stderr.trim()}`)
+
+  const groups = new Map()
+  for (const rel of changed) {
+    const group = groupOf(rel)
+    const list = groups.get(group) ?? []
+    list.push(rel)
+    groups.set(group, list)
+  }
+
+  let uploaded = 0
+  const uploadedRels = new Set()
+  // 本地暂存：会话日志/投影缓存是边跑边改的，直接从源文件打 tar 会撞上「读一半变了」。
+  // 先复制到暂存并核对大小，再打包暂存副本；核对不过的文件留到下一轮。
+  const stagingRoot = path.join(dshRoot, '.cloud-sync', 'staging', `${process.pid}-${Date.now()}`)
+  try {
+    for (const [group, rels] of groups) {
+      const root = rootOf(group, { dshHome: dshRoot, plugins: inventory.plugins })
+      if (root === undefined) {
+        log(`跳过未知分组 ${group}`)
+        continue
+      }
+      const entries = []
+      for (const rel of rels) {
+        const entry = inventory.entries.get(rel)
+        const stagedPath = path.join(stagingRoot, ...group.split('/'), ...memberOf(rel).split('/'))
+        try {
+          await fsp.mkdir(path.dirname(stagedPath), { recursive: true })
+          await fsp.copyFile(entry.abs, stagedPath)
+          const [sourceAfter, stagedStat] = await Promise.all([fsp.stat(entry.abs), fsp.stat(stagedPath)])
+          if (sourceAfter.size !== entry.size || stagedStat.size !== entry.size) {
+            deferred.push(rel)
+            await fsp.rm(stagedPath, { force: true })
+            log(`文件在准备上传时又变了，留到下一轮：${rel}`)
+            continue
+          }
+          entries.push({ name: memberOf(rel), abs: stagedPath, size: entry.size, mtimeMs: entry.mtimeMs, mode: entry.mode, rel })
+        } catch (error) {
+          deferred.push(rel)
+          log(`读取失败，跳过：${rel}（${error instanceof Error ? error.message : String(error)}）`)
+        }
+      }
+      if (entries.length === 0) continue
+      const groupBytes = entries.reduce((sum, item) => sum + item.size, 0)
+      log(`上传 ${group}：${entries.length} 个文件 / ${(groupBytes / 1048576).toFixed(2)} MB`)
+      const target = `${incomingDir}/${group}`
+      const child = spawnSsh(config, `mkdir -p ${shQuote(target)} && tar -xf - -C ${shQuote(target)}`)
+      const stderr = []
+      child.stderr.on('data', (chunk) => stderr.push(chunk))
+      child.stdin.on('error', () => {})
+      const closed = new Promise((resolve) => {
+        child.on('error', (error) => resolve({ code: -1, stderr: error.message }))
+        child.on('close', (code) => resolve({ code, stderr: Buffer.concat(stderr).toString('utf8') }))
+      })
+      let lastActivity = Date.now()
+      let stalled = false
+      const stallTimer = setInterval(() => {
+        if (Date.now() - lastActivity > STALL_MS) {
+          stalled = true
+          lastActivity = Date.now()
+          child.kill()
+        }
+      }, 10000)
+      if (typeof stallTimer.unref === 'function') stallTimer.unref()
+      try {
+        await writeTar(child.stdin, entries, (done, total) => {
+          lastActivity = Date.now()
+          if (options.onProgress !== undefined) options.onProgress({ phase: `上传 ${group}`, done, total })
+        })
+        child.stdin.end()
+      } catch (error) {
+        child.kill()
+        throw error
+      } finally {
+        clearInterval(stallTimer)
+      }
+      const result = await closed
+      if (stalled) {
+        throw new Error(`上传 ${group} 时传输卡住（${Math.round(STALL_MS / 1000)} 秒没有进展），已断开；服务端只收到半截进入临时目录，不会污染现有备份，稍后重试即可`)
+      }
+      if (result.code !== 0) throw new Error(`上传 ${group} 失败（退出码 ${result.code}）：${String(result.stderr).trim()}`)
+      uploaded += entries.length
+      for (const entry of entries) uploadedRels.add(entry.rel)
+    }
+  } finally {
+    await fsp.rm(stagingRoot, { recursive: true, force: true }).catch(() => {})
+  }
+
+  // 清单 = 云端原有条目 + 本次真正上传的条目 − 删除项（避免把「留到下轮」的文件误标为已存在）
+  const mergedEntries = {}
+  for (const [rel, meta] of Object.entries(remote.entries)) mergedEntries[rel] = meta
+  for (const rel of uploadedRels) {
+    const entry = inventory.entries.get(rel)
+    if (entry !== undefined) mergedEntries[rel] = { s: entry.size, m: entry.mtimeMs }
+  }
+  for (const rel of deletions) delete mergedEntries[rel]
+  const nextManifest = { version: 1, machine, updatedAt: new Date().toISOString(), entries: mergedEntries }
+
+  if (deletions.length > 0) {
+    const payload = deletions.join('\n') + '\n'
+    const write = await runSsh(config, `cat > ${shQuote(`${mDir}/deletions.txt`)}`, { stdin: payload })
+    if (write.code !== 0) throw new Error('写入删除清单失败')
+  }
+  await writeRemoteManifest(config, machine, nextManifest, true)
+
+  const commit = await runSsh(config, commitScript(config, machine))
+  if (commit.code !== 0) throw new Error(`服务端提交失败（退出码 ${commit.code}）：${commit.stderr.trim() || commit.stdout.trim()}`)
+
+  const remoteBytes = Number((commit.stdout.match(/BYTES (\d+)/) ?? [])[1]) || 0
+  log(`提交完成：${uploaded} 个文件上传，${deletions.length} 个删除，云端合计 ${(remoteBytes / 1048576).toFixed(1)} MB`)
+  // 记下「哪些删掉了」「哪些本机确实有」：下次恢复据此判断，不会把本地删掉的会话又拉回来
+  writeTombstones(dshRoot, tombstones)
+  writeKnown(dshRoot, mergedEntries)
+  writeJsonSafe(fpFile, { value: fingerprint, deferred: deferred.length })
+  // 删除记录同步到云端共享文件，别的机器（或另一台上的 DSH）据此同样删掉
+  await syncSharedTombstones(config, tombstones, log, applied.revived)
+  const pruned = pruneLocalState(dshRoot, config.backupDays)
+  if (pruned.backups > 0 || pruned.staging > 0 || pruned.quarantined > 0) {
+    log(`顺手清理本机旧备份 ${pruned.backups} 份、隔离文件 ${pruned.quarantined} 份、残留暂存 ${pruned.staging} 份`)
+  }
+  return {
+    ok: true,
+    skipped: false,
+    machine,
+    uploaded,
+    deleted: deletions.length,
+    deferred: deferred.length,
+    total: inventory.entries.size,
+    bytes: remoteBytes,
+    changedBytes: changed.reduce((sum, rel) => sum + (inventory.entries.get(rel)?.size ?? 0), 0),
+  }
+}
+
+async function writeRemoteManifest(config, machine, manifest, staging = false) {
+  const file = `${machineDir(config, machine)}/${staging ? 'manifest.new.json' : 'manifest.json'}`
+  const result = await runSsh(config, `mkdir -p ${shQuote(path.posix.dirname(file))} && cat > ${shQuote(file)}`, {
+    stdin: JSON.stringify(manifest),
+  })
+  if (result.code !== 0) throw new Error(`写入 manifest 失败：${result.stderr.trim()}`)
+}
+
+function commitScript(config, machine) {
+  const mDir = machineDir(config, machine)
+  const trash = `${config.remoteRoot}/trash`
+  const versions = `${config.remoteRoot}/versions`
+  const incoming = `incoming/${machine}`
+  return [
+    'set -u',
+    `cd ${shQuote(mDir)} || exit 3`,
+    // 多台机器可能同时提交：用文件锁串行化，后到的等前一个提交完
+    'exec 9>.dsh-sync.lock',
+    'flock -w 120 9 || { echo "LOCK_TIMEOUT" >&2; exit 6; }',
+    'TS=$(date +%Y%m%d-%H%M%S)',
+    'if [ -s deletions.txt ]; then',
+    `  T=${shQuote(trash)}/$TS`,
+    '  mkdir -p "$T"',
+    '  while IFS= read -r p; do',
+    '    [ -n "$p" ] || continue',
+    '    if [ -f "files/$p" ]; then',
+    '      mkdir -p "$T/$(dirname "$p")" 2>/dev/null || true',
+    '      mv -f "files/$p" "$T/$p" 2>/dev/null || true',
+    '    fi',
+    '  done < deletions.txt',
+    'fi',
+    '# 删空的目录顺手收掉，别在云端越留越多空壳',
+    'find files -depth -type d -empty -delete 2>/dev/null || true',
+    `if [ -d ${incoming} ]; then`,
+    `  V=${shQuote(versions)}/$TS`,
+    `  find ${incoming} -type f -print > .incoming-list 2>/dev/null || true`,
+    '  if [ -s .incoming-list ]; then',
+    '    while IFS= read -r f; do',
+    `      rel=\${f#${incoming}/}`,
+    '      if [ -f "files/$rel" ]; then',
+    '        mkdir -p "$V/$(dirname "$rel")" 2>/dev/null || true',
+    '        cp -p "files/$rel" "$V/$rel" 2>/dev/null || true',
+    '      fi',
+    '    done < .incoming-list',
+    '  fi',
+    '  rm -f .incoming-list',
+    '  mkdir -p files',
+    `  cp -a ${incoming}/. files/ || exit 4`,
+    `  rm -rf ${incoming}`,
+    '  find files -depth -type d -empty -delete 2>/dev/null || true',
+    'fi',
+    'if [ -f manifest.new.json ]; then',
+    '  mv -f manifest.new.json manifest.json || exit 5',
+    'fi',
+    'rm -f deletions.txt',
+    `find ${shQuote(trash)} ${shQuote(versions)} -mindepth 1 -maxdepth 1 -type d -mtime +${config.trashDays} -exec rm -rf {} + 2>/dev/null || true`,
+    'find incoming -mindepth 1 -maxdepth 1 -type d -empty -delete 2>/dev/null || true',
+    'echo "BYTES $(du -sb files 2>/dev/null | cut -f1)"',
+    'echo OK',
+  ].join('\n')
+}
+
+/* ── 恢复 ───────────────────────────────────────────────────────────────── */
+
+function isSafeRel(rel) {
+  if (typeof rel !== 'string' || rel === '') return false
+  if (rel.includes('\0')) return false
+  if (rel.startsWith('/') || /^[A-Za-z]:/.test(rel)) return false
+  const parts = rel.split('/')
+  return parts.every((part) => part !== '' && part !== '.' && part !== '..')
+}
+
+/** 服务端 profile package.json 里的 link 插件目录（用于在新机上摆放插件源码）。 */
+async function remoteLinkPlugins(config, machine, profile) {
+  const file = `${machineDir(config, machine)}/files/dsh/profiles/${profile}/package.json`
+  const result = await runSsh(config, `cat ${shQuote(file)} 2>/dev/null || true`)
+  const text = result.stdout.trim()
+  if (text === '') return []
+  try {
+    const manifest = JSON.parse(text)
+    const out = []
+    for (const [name, spec] of Object.entries(manifest.dependencies ?? {})) {
+      if (typeof spec !== 'string' || !spec.startsWith('link:')) continue
+      out.push({ name, target: spec.slice(5).replace(/\\/g, '/').replace(/\/+$/, '') })
+    }
+    return out
+  } catch {
+    return []
+  }
+}
+
+/**
+ * 从云端恢复：只补缺失/云端更新的文件，覆盖前先本地备份。
+ * @param {{config: object, from?: string, force?: boolean, log?: Function, onProgress?: Function, dshHome?: string, profile?: string}} options
+ */
+export async function pull(options) {
+  const config = options.config
+  if (!isConfigured(config)) throw new Error('未配置服务器：请在 profile 的 cordis.patch.yml 里设置 host（和 identityFile），或让 Agent 帮忙填')
+  const log = options.log ?? (() => {})
+  const dshRoot = options.dshHome ?? dshHome()
+  const profile = options.profile ?? profileName()
+  const localProfileDir = resolveProfileDir(dshRoot, profile, options.profileDir)
+
+  let from = options.from
+  if (from === undefined || from === '') {
+    const listing = await listMachines(config)
+    const candidates = listing.machines.filter((item) => item.manifestBytes > 0)
+    if (candidates.length === 1) from = candidates[0].id
+    else if (candidates.length === 0) throw new Error('云端还没有任何备份（先在旧机器上推送一次）')
+    else throw new Error(`云端有 ${candidates.length} 台机器的备份（${candidates.map((item) => item.id).join('、')}），请指定从哪台恢复`)
+  }
+  const remote = await readRemoteManifest(config, from)
+  const remoteEntries = Object.keys(remote.entries)
+  if (remoteEntries.length === 0) throw new Error(`机器 ${from} 在云端没有清单`)
+
+  // 插件源码落点：优先用服务端 package.json 里记录的 link 路径，本机没有就放到 localPluginRoot 下
+  const pluginTargets = new Map()
+  const remotePlugins = config.includeLocalPlugins ? await remoteLinkPlugins(config, from, profile) : []
+  for (const plugin of remotePlugins) {
+    const hasPrefix = remoteEntries.some((rel) => rel.startsWith(`plugins/${plugin.name}/`))
+    if (!hasPrefix) continue
+    let target = plugin.target
+    if (!fs.existsSync(target)) {
+      const fallback = `${config.localPluginRoot}/${plugin.name}`
+      try {
+        fs.mkdirSync(fallback, { recursive: true })
+        target = fallback
+      } catch (error) {
+        log(`无法创建插件目录 ${fallback}：${error instanceof Error ? error.message : String(error)}`)
+        continue
+      }
+    }
+    pluginTargets.set(plugin.name, target)
+  }
+
+  // 先按云端共享删除记录清理本机：别的机器删掉的东西，这台也删（放进 removed/，可找回）
+  const shared = await readSharedTombstones(config)
+  let applied = { removed: [], revived: [] }
+  if (config.applyRemoteDeletes && Object.keys(shared).length > 0) {
+    applied = await applyTombstones({ config, dshRoot, profile, tombstones: shared, log })
+    if (applied.removed.length > 0) log(`按云端删除记录移除本机 ${applied.removed.length} 个文件（放进 .cloud-sync/removed/，可找回）`)
+    if (applied.revived.length > 0) log(`另有 ${applied.revived.length} 个文件比删除记录新，保留`)
+  }
+  const inventory = buildInventory({ config, dshHome: dshRoot, profile, profileDir: localProfileDir })
+  // 本地记忆：墓碑 = 本机删过的（含云端共享的）；known = 本机确实拥有过的
+  const tombstones = mergeTombstones(readTombstones(dshRoot), shared)
+  const known = readKnown(dshRoot)
+  for (const rel of inventory.entries.keys()) delete tombstones[rel]
+  const now = Date.now()
+  const wanted = []
+  let skippedRecent = 0
+  let skippedDeleted = 0
+  for (const rel of remoteEntries) {
+    if (!isSafeRel(rel)) {
+      log(`忽略非法路径：${rel}`)
+      continue
+    }
+    if (config.includeAttachments === false && rel.startsWith('dsh/attachments/')) continue
+    const meta = remote.entries[rel] ?? {}
+    const remoteMtime = Number(meta.m) || 0
+    const tomb = Number(tombstones[rel]) || 0
+    if (options.force !== true && tomb > 0 && tomb >= remoteMtime) {
+      skippedDeleted += 1
+      continue
+    }
+    const local = inventory.entries.get(rel)
+    if (local === undefined) {
+      if (options.force !== true && known[rel] !== undefined) {
+        // 本机以前确实有、现在没了 = 本地删掉的，不拉回来
+        tombstones[rel] = Date.now()
+        skippedDeleted += 1
+        continue
+      }
+      wanted.push({ rel, mtimeMs: remoteMtime })
+      continue
+    }
+    if (remoteMtime <= local.mtimeMs + 2000) continue
+    if (options.force !== true && now - local.mtimeMs < 5 * 60 * 1000) {
+      skippedRecent += 1
+      continue
+    }
+    wanted.push({ rel, mtimeMs: remoteMtime })
+  }
+  log(`云端 ${remoteEntries.length} 个文件，需要恢复 ${wanted.length} 个${skippedRecent === 0 ? '' : `（${skippedRecent} 个本地刚改过，跳过）`}${skippedDeleted === 0 ? '' : `（${skippedDeleted} 个本地删过，不拉回）`}`)
+  if (wanted.length === 0) {
+    writeTombstones(dshRoot, tombstones)
+    await syncSharedTombstones(config, tombstones, log, applied.revived)
+    pruneLocalState(dshRoot, config.backupDays)
+    return { ok: true, from, restored: 0, bytes: 0, skipped: 0, plugins: pluginTargets.size, skippedRecent, skippedDeleted, removed: applied.removed.length }
+  }
+
+  const backupDir = path.join(dshRoot, '.cloud-sync', 'backup', timestamp())
+  const groups = new Map()
+  for (const item of wanted) {
+    const group = groupOf(item.rel)
+    const list = groups.get(group) ?? []
+    list.push(item)
+    groups.set(group, list)
+  }
+
+  let restored = 0
+  let skipped = 0
+  let bytes = 0
+  const restoredRels = new Set()
+
+  for (const [group, items] of groups) {
+    const mDir = machineDir(config, from)
+    const list = items.map((item) => memberOf(item.rel)).join('\n') + '\n'
+    const child = spawnSsh(config, `cd ${shQuote(`${mDir}/files/${group}`)} && tar -cf - -T -`)
+    const stderr = []
+    child.stderr.on('data', (chunk) => stderr.push(chunk))
+    child.stdin.on('error', () => {})
+    child.stdin.write(list)
+    child.stdin.end()
+    let lastActivity = Date.now()
+    let stalled = false
+    const reader = new ByteReader(child.stdout, () => { lastActivity = Date.now() })
+    const stallTimer = setInterval(() => {
+      if (Date.now() - lastActivity > STALL_MS) {
+        stalled = true
+        lastActivity = Date.now()
+        child.kill()
+      }
+    }, 10000)
+    if (typeof stallTimer.unref === 'function') stallTimer.unref()
+    const closed = new Promise((resolve) => {
+      child.on('error', (error) => resolve({ code: -1, stderr: error.message }))
+      child.on('close', (code) => resolve({ code, stderr: Buffer.concat(stderr).toString('utf8') }))
+    })
+
+    try {
+      await readTar(reader, async (file) => {
+        const rel = `${group}/${file.name}`
+        if (!isSafeRel(rel)) {
+          await file.reader.skip(file.size)
+          return
+        }
+        const target = resolveTarget(rel, { dshHome: dshRoot, pluginTargets })
+        if (target === undefined) {
+          await file.reader.skip(file.size)
+          skipped += 1
+          return
+        }
+        await fsp.mkdir(path.dirname(target), { recursive: true })
+        if (fs.existsSync(target)) {
+          const backup = path.join(backupDir, rel.split('/').join(path.sep))
+          await fsp.mkdir(path.dirname(backup), { recursive: true })
+          await fsp.copyFile(target, backup).catch(() => {})
+        }
+        const temp = `${target}.dsh-sync-${process.pid}.tmp`
+        const handle = await fsp.open(temp, 'w')
+        try {
+          let remaining = file.size
+          while (remaining > 0) {
+            const chunk = await file.reader.readExact(Math.min(remaining, 1 << 20))
+            if (chunk.length === 0) break
+            await handle.write(chunk)
+            remaining -= chunk.length
+            bytes += chunk.length
+            if (options.onProgress !== undefined) options.onProgress({ phase: `恢复 ${group}`, done: bytes, total: undefined })
+          }
+          if (remaining > 0) throw new Error(`文件不完整：${rel}`)
+        } finally {
+          await handle.close()
+        }
+        await fsp.rename(temp, target)
+        if (file.mtimeMs > 0) await fsp.utimes(target, new Date(file.mtimeMs), new Date(file.mtimeMs)).catch(() => {})
+        restored += 1
+        restoredRels.add(rel)
+      })
+    } finally {
+      clearInterval(stallTimer)
+      const result = await closed
+      if (stalled) {
+        throw new Error(`恢复 ${group} 时传输卡住（${Math.round(STALL_MS / 1000)} 秒没有数据），已断开；云端数据没动，稍后重试即可`)
+      }
+      if (result.code !== 0) {
+        log(`恢复 ${group} 时远端退出码 ${result.code}：${String(result.stderr).trim()}`)
+      }
+    }
+  }
+
+  log(`恢复完成：${restored} 个文件，${skipped} 个找不到落点而被跳过`)
+  await rewriteProfileLinks(localProfileDir, pluginTargets, log)
+
+  // 记下「本机现在确实有哪些文件」：下次恢复时，本机拥有过但已经不在的，视为本地删除，不再拉回。
+  const nextKnown = { ...known }
+  for (const [rel, entry] of inventory.entries) nextKnown[rel] = { s: entry.size, m: entry.mtimeMs }
+  for (const rel of restoredRels) {
+    const meta = remote.entries[rel]
+    if (meta !== undefined) nextKnown[rel] = { s: Number(meta.s) || 0, m: Number(meta.m) || 0 }
+  }
+  writeKnown(dshRoot, nextKnown)
+  writeTombstones(dshRoot, tombstones)
+  // force 恢复回来的文件视为「删掉后又被重建」：同时把共享删除记录撤掉，免得别的机器又删它
+  await syncSharedTombstones(config, tombstones, log, options.force === true ? [...applied.revived, ...restoredRels] : applied.revived)
+  const pruned = pruneLocalState(dshRoot, config.backupDays)
+  if (pruned.backups > 0 || pruned.staging > 0) log(`顺手清理本机旧备份 ${pruned.backups} 份、残留暂存 ${pruned.staging} 份`)
+  return { ok: true, from, restored, bytes, skipped, plugins: pluginTargets.size, skippedRecent, skippedDeleted, removed: applied.removed.length }
+}
+
+function timestamp() {
+  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 resolveTarget(rel, context) {
+  const parts = rel.split('/')
+  if (parts[0] === 'dsh') return path.join(context.dshHome, ...parts.slice(1))
+  if (parts[0] === 'plugins' && parts.length > 2) {
+    const target = context.pluginTargets.get(parts[1])
+    if (target === undefined) return undefined
+    return path.join(target, ...parts.slice(2))
+  }
+  return undefined
+}
+
+/** 恢复后把 profile package.json 里指向别处的 link: 路径改成本机实际目录。 */
+async function rewriteProfileLinks(profileDirPath, pluginTargets, log) {
+  if (pluginTargets.size === 0) return
+  const file = path.join(profileDirPath, 'package.json')
+  let manifest
+  try {
+    manifest = JSON.parse(await fsp.readFile(file, 'utf8').then((text) => text.replace(/^\uFEFF/, '')))
+  } catch {
+    return
+  }
+  let changed = false
+  for (const [name, target] of pluginTargets) {
+    const spec = manifest.dependencies?.[name]
+    if (typeof spec !== 'string' || !spec.startsWith('link:')) continue
+    const current = spec.slice(5).replace(/\\/g, '/').replace(/\/+$/, '')
+    if (current === target) continue
+    manifest.dependencies[name] = `link:${target}`
+    changed = true
+    log(`插件 ${name} 的 link 路径改到 ${target}`)
+  }
+  if (!changed) return
+  await fsp.writeFile(file, JSON.stringify(manifest, null, 2) + '\n', 'utf8')
+  log('profile package.json 已更新：装好插件依赖后重启 DSH 生效')
+}
+
+/* ── 连接自检 ───────────────────────────────────────────────────────────── */
+
+/** 检查 ssh 是否可用（面板状态与推送前用）。 */
+export async function checkConnection(config) {
+  const started = Date.now()
+  try {
+    const result = await runSsh(config, 'printf "PONG %s" "$(hostname)"')
+    const ok = result.code === 0 && result.stdout.includes('PONG')
+    return {
+      ok,
+      server: ok ? result.stdout.trim().replace(/^PONG\s*/, '') : undefined,
+      ms: Date.now() - started,
+      error: ok ? undefined : (result.stderr.trim() || `退出码 ${result.code}`),
+    }
+  } catch (error) {
+    return { ok: false, ms: Date.now() - started, error: error instanceof Error ? error.message : String(error) }
+  }
+}