dsh-crossterm 0.3.37 → 0.3.39

package/lib/cloud/layout.js

@@ -0,0 +1,190 @@
+// 云端目录规则（0.3.39）：
+//   <大文件夹>/<账号>/                       账号文件夹（第一个进入的设备 = 管理员）
+//   <大文件夹>/<账号>/<设备>/                 设备文件夹（会话备份、附件）
+//   <大文件夹>/<账号>/shared/                云端设备共享文件夹（跨设备传输）
+//   <大文件夹>/<账号>/shared/<设备>/inbox/    每台设备自己的收件箱
+//   <大文件夹>/<账号>/shared/<设备>/done/     已投递归档
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const LAYOUT_VERSION = 1
+export const DEFAULT_HOME = 'dsh'
+export const ACCOUNT_FILE = '_account.json'
+export const DEVICE_FILE = '_device.json'
+export const INBOX_FILE = '_inbox.json'
+const CACHE_MS = 10 * 60 * 1000
+
+/** 目录名净化：去掉路径分隔符/控制字符/中文等非 ASCII（云盘接口对特殊字符不友好） */
+export function sanitize(raw, fallback = 'default') {
+  const s = String(raw ?? '').trim()
+  if (!s) return fallback
+  const ascii = s.replace(/[^\x20-\x7e]/g, '').replace(/[\\/:*?"<>|]+/g, '-')
+  const out = ascii.replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^[.-]+/, '').replace(/[.-]+$/, '').slice(0, 64)
+  return out || fallback
+}
+
+export function buildPaths({ home = DEFAULT_HOME, account = 'default', deviceId = 'device' } = {}) {
+  const base = '/' + String(home || DEFAULT_HOME).replace(/^\/+|\/+$/g, '')
+  const accountDir = `${base}/${account}`
+  const sharedDir = `${accountDir}/shared`
+  const deviceRoot = `${sharedDir}/${deviceId}`
+  const deviceDir = `${accountDir}/${deviceId}`
+  return {
+    base,
+    accountDir,
+    sharedDir,
+    deviceRoot,
+    deviceDir,
+    inboxDir: `${deviceRoot}/inbox`,
+    doneDir: `${deviceRoot}/done`,
+    sessionDir: `${deviceDir}/sessions`,
+    attachmentDir: `${deviceDir}/attachments`,
+    accountFile: `${accountDir}/${ACCOUNT_FILE}`,
+    deviceFile: `${deviceDir}/${DEVICE_FILE}`,
+    inboxFile: `${deviceRoot}/${INBOX_FILE}`,
+  }
+}
+
+/**
+ * 账号名：配置手填 > DSH_ACCOUNT 环境变量 > 云盘账号昵称 > uk > default
+ * （本机 .credentials.yaml 里拿不到 dsh 账号名，token 是不透明串，asar 也没有 account 服务）
+ */
+export async function resolveAccount(pan, cfg = {}, log = () => {}) {
+  if (cfg.cloudAccount) return { account: sanitize(cfg.cloudAccount), source: 'config' }
+  if (process.env.DSH_ACCOUNT) return { account: sanitize(process.env.DSH_ACCOUNT), source: 'env' }
+  try {
+    const info = await pan.uinfo()
+    const name = info?.netdisk_name || info?.baidu_name || ''
+    if (name) return { account: sanitize(name), source: 'cloud', name, uk: info?.uk }
+    if (info?.uk) return { account: sanitize(String(info.uk)), source: 'cloud-uk', uk: info.uk }
+  } catch (e) {
+    log(`读云盘账号失败：${(e && e.message) || String(e)}`)
+  }
+  return { account: 'default', source: 'fallback' }
+}
+
+function readCache(file) {
+  if (!file) return null
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+}
+
+function writeCache(file, value) {
+  if (!file) return
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(value, null, 2), 'utf8')
+  } catch { /* ignore */ }
+}
+
+async function readJson(pan, remote, log) {
+  try {
+    const r = await pan.getBuffer(remote)
+    return JSON.parse(r.buffer.toString('utf8'))
+  } catch (e) {
+    const msg = (e && e.message) || String(e)
+    if (!/没有该文件/.test(msg)) log(`读 ${remote} 失败：${msg}`)
+    return null
+  }
+}
+
+const iso = (ts = Date.now()) => new Date(ts).toISOString()
+
+/**
+ * 建立/校正云端目录结构，返回 { account, role, paths, created, accountInfo, deviceInfo }
+ * @param {{pan: object, cfg: object, device: {nodeId: string, name?: string, version?: string, platform?: string, sessions?: number}, cacheFile?: string, force?: boolean, log?: Function}} opts
+ */
+export async function ensureLayout({ pan, cfg = {}, device = {}, cacheFile, force = false, log = () => {} }) {
+  const nodeId = sanitize(device.nodeId || 'device')
+  const cached = readCache(cacheFile)
+  if (!force && cached && cached.deviceId === nodeId && Date.now() - Number(cached.at || 0) < CACHE_MS && cached.paths) {
+    return { ...cached, cached: true, ensuredAt: cached.at }
+  }
+
+  const who = await resolveAccount(pan, cfg, log)
+  const paths = buildPaths({ home: cfg.cloudHome || DEFAULT_HOME, account: who.account, deviceId: nodeId })
+  const dirs = [
+    paths.base,
+    paths.accountDir,
+    paths.sharedDir,
+    paths.deviceDir,
+    paths.deviceRoot,
+    paths.inboxDir,
+    paths.doneDir,
+    paths.sessionDir,
+    paths.attachmentDir,
+  ]
+  const created = []
+  for (const dir of dirs) {
+    const r = await pan.mkdir(dir)
+    if (!r.ok) throw new Error(`建目录失败 ${dir}（errno=${r.errno}）`)
+    if (r.created) created.push(dir)
+  }
+
+  // 角色：账号文件夹里第一个写下 _account.json 的设备是管理员，其余是成员
+  let accountInfo = await readJson(pan, paths.accountFile, log)
+  let role = 'admin'
+  if (!accountInfo) {
+    accountInfo = {
+      account: who.account,
+      accountSource: who.source,
+      cloudUk: who.uk || '',
+      ownerDevice: nodeId,
+      ownerName: device.name || nodeId,
+      role: 'admin',
+      version: LAYOUT_VERSION,
+      createdAt: iso(),
+      note: '账号云端目录；ownerDevice 是该账号云端的管理员设备，其余设备为成员',
+    }
+    await pan.putBuffer(Buffer.from(JSON.stringify(accountInfo, null, 2), 'utf8'), paths.accountFile)
+    log(`云端账号目录已创建，本机成为管理员：${paths.accountDir}`)
+  } else {
+    role = accountInfo.ownerDevice === nodeId ? 'admin' : 'member'
+  }
+
+  const oldDevice = (await readJson(pan, paths.deviceFile, () => {})) || {}
+  const deviceInfo = {
+    nodeId,
+    name: device.name || oldDevice.name || nodeId,
+    role,
+    version: device.version || '',
+    platform: device.platform || '',
+    sessions: Number(device.sessions || 0),
+    joinedAt: oldDevice.joinedAt || iso(),
+    lastSeen: iso(),
+    account: who.account,
+  }
+  await pan.putBuffer(Buffer.from(JSON.stringify(deviceInfo, null, 2), 'utf8'), paths.deviceFile)
+
+  const oldInbox = (await readJson(pan, paths.inboxFile, () => {})) || {}
+  const inboxInfo = {
+    nodeId,
+    name: deviceInfo.name,
+    version: deviceInfo.version,
+    role,
+    createdAt: oldInbox.createdAt || iso(),
+    updatedAt: iso(),
+    note: '本设备收件箱：别的设备发来的消息/文件先落在这里，本机的中转站定时取走',
+  }
+  await pan.putBuffer(Buffer.from(JSON.stringify(inboxInfo, null, 2), 'utf8'), paths.inboxFile)
+
+  const out = {
+    at: Date.now(),
+    ensuredAt: iso(),
+    deviceId: nodeId,
+    account: who.account,
+    accountSource: who.source,
+    role,
+    paths,
+    created,
+    accountInfo,
+    deviceInfo,
+  }
+  writeCache(cacheFile, out)
+  return out
+}
+
+/** 只读缓存，拿不到就返回 null（给 status 卡片用，不触网） */
+export function readLayoutCache(cacheFile) {
+  const c = readCache(cacheFile)
+  return c && c.paths ? c : null
+}

package/lib/cloud/pan.js

@@ -1,4 +1,4 @@
-// 百度网盘最小客户端（插件内置版）：uinfo / ls / put / get / rm，走 xpan openapi
+// 百度网盘最小客户端（插件内置版）：uinfo / ls / mkdir / put / get / rm，走 xpan openapi
 // 凭证文件由调用方给出：app 文件含 appKey/appSecret，auth 文件含 accessToken/refreshToken
 import fs from 'node:fs'
 import path from 'node:path'
@@ -73,14 +73,56 @@ export function createPan({ appFile, authFile, log = () => {} }) {
     return api(`https://pan.baidu.com/rest/2.0/xpan/nas?method=uinfo&access_token=${encodeURIComponent(tok)}`)
   }
 
+  async function lsPage(dir, start, limit) {
+    await ensureToken()
+    return api(`https://pan.baidu.com/rest/2.0/xpan/file?method=list&access_token=${encodeURIComponent(tok)}&dir=${encodeURIComponent(dir)}&order=time&start=${start}&limit=${limit}`)
+  }
+
   async function ls(dir = '/') {
+    return lsPage(dir, 0, 200)
+  }
+
+  // 一个目录超过 200 个文件时必须翻页，否则第 201 个之后永远看不见
+  // （presence/ 里被 .tmp 残骸占满时，真实 node json 就躲在第二页）。
+  async function lsAll(dir = '/', pageSize = 200) {
+    const all = []
+    for (let page = 0; page < 50; page += 1) {
+      const j = await lsPage(dir, page * pageSize, pageSize)
+      if (j.errno !== 0) return j
+      const list = j.list || []
+      all.push(...list)
+      if (list.length < pageSize) return { ...j, list: all, errno: 0 }
+    }
+    return { errno: 0, list: all }
+  }
+
+  // 建目录：xpan 的 create 带 isdir=1；已存在（31061 / -8）视为成功
+  async function mkdir(remotePath) {
     await ensureToken()
-    return api(`https://pan.baidu.com/rest/2.0/xpan/file?method=list&access_token=${encodeURIComponent(tok)}&dir=${encodeURIComponent(dir)}&order=time&start=0&limit=200`)
+    const j = await api(
+      `https://pan.baidu.com/rest/2.0/xpan/file?method=create&access_token=${encodeURIComponent(tok)}`,
+      new URLSearchParams({ path: remotePath, isdir: '1', size: '0', block_list: '[]', rtype: '3' }),
+    )
+    if (j.errno === 0) return { ok: true, path: remotePath, created: true }
+    if (j.errno === 31061 || j.errno === -8) return { ok: true, path: remotePath, existed: true }
+    // 有些错误码（如父目录刚建好时的竞态）其实目录已存在，用列目录复核一次
+    const list = await lsAll(path.posix.dirname(remotePath))
+    const name = path.posix.basename(remotePath)
+    if (list.errno === 0 && (list.list || []).some((f) => f.server_filename === name && f.isdir === 1)) {
+      return { ok: true, path: remotePath, existed: true }
+    }
+    return { ok: false, path: remotePath, errno: j.errno, raw: j }
   }
 
-  async function put(localPath, remotePath) {
+  async function exists(remotePath) {
+    const list = await lsAll(path.posix.dirname(remotePath))
+    if (list.errno !== 0) return false
+    const name = path.posix.basename(remotePath)
+    return (list.list || []).some((f) => f.server_filename === name)
+  }
+
+  async function putBuffer(buf, remotePath) {
     await ensureToken()
-    const buf = await readFile(localPath)
     const md5 = md5hex(buf)
     const size = buf.length
     const pre = await api(
@@ -119,11 +161,25 @@ export function createPan({ appFile, authFile, log = () => {} }) {
     return { path: remotePath, size, md5: upj.md5, fs_id: cr.fs_id }
   }
 
+  async function put(localPath, remotePath) {
+    const buf = await readFile(localPath)
+    return putBuffer(buf, remotePath)
+  }
+
+  /** 读回云端文件内容（小文件用，中转站/标注用） */
+  async function getBuffer(remotePath) {
+    const tmp = path.join(process.env.TEMP || '/tmp', `pan-${Date.now()}-${path.posix.basename(remotePath)}`)
+    const r = await get(remotePath, tmp)
+    const buf = fs.readFileSync(tmp)
+    try { fs.rmSync(tmp, { force: true }) } catch { /* ignore */ }
+    return { ...r, buffer: buf }
+  }
+
   async function get(remotePath, localPath) {
     await ensureToken()
     const dir = path.posix.dirname(remotePath)
     const name = path.posix.basename(remotePath)
-    const list = await ls(dir)
+    const list = await lsAll(dir)
     if (list.errno !== 0) throw new Error('列目录失败：' + JSON.stringify(list))
     const hit = (list.list || []).find((f) => f.server_filename === name && f.isdir === 0)
     if (!hit) throw new Error('远端没有该文件：' + remotePath)
@@ -148,5 +204,5 @@ export function createPan({ appFile, authFile, log = () => {} }) {
     )
   }
 
-  return { uinfo, ls, put, get, rm, ensureToken }
+  return { uinfo, ls, lsAll, mkdir, exists, put, putBuffer, get, getBuffer, rm, ensureToken }
 }

package/lib/cloud/relay.js

@@ -0,0 +1,196 @@
+// 云端中转站（0.3.39）：
+//   收信侧：定时扫 <账号>/shared/<本机>/inbox/*.json → 下载附件到本地 → 按收件人（会话名）投递 → 云端归档到 done/
+//   发信侧：sendEnvelope() 把信封写到目标设备的 inbox/，附件写到 files/<邮件id>/
+// 信封格式（与老邮件兼容）：
+//   { id, from: {nodeId,name}, to: '<会话名>' | ['会话名', …], text, files: [{name, size}], createdAt }
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex')
+const nowIso = () => new Date().toISOString()
+
+function loadState(file) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return { at: j.at || 0, processed: j.processed || {}, failed: j.failed || {}, sent: j.sent || [] }
+  } catch {
+    return { at: 0, processed: {}, failed: {}, sent: [] }
+  }
+}
+
+function saveState(file, state) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(state, null, 2), 'utf8')
+  } catch { /* ignore */ }
+}
+
+const isTmp = (name) => /\.tmp$/.test(name) || name.startsWith('.')
+
+function parseEnvelope(text) {
+  const j = JSON.parse(text)
+  const to = Array.isArray(j.to) ? j.to : j.to || j.toSession || j.recipient || ''
+  return {
+    id: String(j.id || j.mailId || ''),
+    from: j.from || {},
+    to,
+    text: String(j.text || j.body || ''),
+    subject: String(j.subject || ''),
+    files: Array.isArray(j.files) ? j.files : [],
+    createdAt: j.createdAt || Date.now(),
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {object} opts.pan
+ * @param {Function} opts.getLayout 返回 ensureLayout() 结果（异步）
+ * @param {string} opts.localDir 本地落地目录（收件箱缓存、附件）
+ * @param {string} opts.stateFile 本地已处理清单
+ * @param {Function} opts.deliver async ({ to, envelope, files }) => { ok, sessionId, reason }
+ * @param {Function} [opts.log]
+ */
+export function createRelay({ pan, getLayout, localDir, stateFile, deliver, log = () => {} }) {
+  let running = false
+  const stats = { at: 0, scanned: 0, delivered: 0, failed: 0, pending: 0, sent: 0, lastError: '' }
+
+  async function downloadAttachment(layout, mailId, file, destDir) {
+    // 附件既可能在 files/<id>/ 下，也可能就在 inbox/ 同级（老信封）
+    const candidates = [
+      `${layout.paths.sharedDir}/${layout.deviceId}/files/${mailId}/${file.name}`,
+      `${layout.paths.inboxDir}/${file.name}`,
+      file.cloudPath || '',
+    ].filter(Boolean)
+    for (const remote of candidates) {
+      try {
+        const dst = path.join(destDir, file.name)
+        await pan.get(remote, dst)
+        return { name: file.name, local: dst, remote, bytes: fs.statSync(dst).size }
+      } catch { /* try next */ }
+    }
+    return { name: file.name, local: '', remote: candidates[0] || '', error: '下载失败' }
+  }
+
+  async function poll() {
+    if (running) return { ...stats, running: true }
+    running = true
+    const state = loadState(stateFile)
+    try {
+      const layout = await getLayout()
+      if (!layout || !layout.paths) return { ...stats, running: true, error: '云端目录还没准备好' }
+      const list = await pan.lsAll(layout.paths.inboxDir)
+      if (list.errno !== 0) {
+        stats.at = Date.now()
+        return { ...stats, error: `列收件箱失败 errno=${list.errno}` }
+      }
+      const files = (list.list || []).filter((f) => f.isdir === 0 && !isTmp(f.server_filename))
+      stats.scanned = files.length
+      stats.delivered = 0
+      stats.failed = 0
+      stats.pending = 0
+      const incomingDir = path.join(localDir, 'incoming')
+      fs.mkdirSync(incomingDir, { recursive: true })
+
+      for (const f of files) {
+        const name = f.server_filename
+        if (state.processed[name]) continue
+        const localJson = path.join(incomingDir, name)
+        let envelope
+        try {
+          await pan.get(`${layout.paths.inboxDir}/${name}`, localJson)
+          envelope = parseEnvelope(fs.readFileSync(localJson, 'utf8'))
+        } catch (e) {
+          stats.failed += 1
+          stats.lastError = `读取 ${name} 失败：${(e && e.message) || String(e)}`
+          log(stats.lastError)
+          continue
+        }
+        const mailId = envelope.id || path.basename(name, '.json')
+        const fileDir = path.join(localDir, 'files', mailId)
+        fs.mkdirSync(fileDir, { recursive: true })
+        const landed = []
+        for (const file of envelope.files) {
+          const got = await downloadAttachment(layout, mailId, file, fileDir)
+          landed.push(got)
+        }
+        let result
+        try {
+          result = await deliver({ to: envelope.to, envelope, files: landed })
+        } catch (e) {
+          result = { ok: false, reason: (e && e.message) || String(e) }
+        }
+        if (result && result.ok) {
+          stats.delivered += 1
+          state.processed[name] = { at: nowIso(), mailId, sessionId: result.sessionId || '', to: String(envelope.to) }
+          // 云端归档：先放 done/，再删收件箱里的原件
+          try {
+            await pan.mkdir(layout.paths.doneDir)
+            await pan.put(localJson, `${layout.paths.doneDir}/${name}`)
+            await pan.rm(`${layout.paths.inboxDir}/${name}`)
+          } catch (e) {
+            log(`归档 ${name} 失败：${(e && e.message) || String(e)}`)
+          }
+          log(`中转站投递 ${mailId} → ${result.sessionId || String(envelope.to)}`)
+        } else {
+          stats.pending += 1
+          const key = `${name}`
+          state.failed[key] = { at: nowIso(), reason: (result && result.reason) || '投递失败', tries: Number(state.failed?.[key]?.tries || 0) + 1 }
+          log(`中转站留件 ${name}：${(result && result.reason) || '投递失败'}`)
+        }
+        saveState(stateFile, { ...state, at: Date.now() })
+      }
+      stats.at = Date.now()
+      saveState(stateFile, { ...state, at: Date.now() })
+      return { ...stats }
+    } catch (e) {
+      stats.lastError = (e && e.message) || String(e)
+      log(`中转站巡检失败：${stats.lastError}`)
+      return { ...stats, error: stats.lastError }
+    } finally {
+      running = false
+    }
+  }
+
+  /** 发信：把信封写到目标设备的共享收件箱（同账号下的设备目录） */
+  async function sendEnvelope({ toDevice, toSession, text, files = [], from = {}, subject = '' }) {
+    const layout = await getLayout()
+    if (!layout || !layout.paths) return { ok: false, reason: '云端目录还没准备好' }
+    const shared = await pan.lsAll(layout.paths.sharedDir)
+    if (shared.errno !== 0) return { ok: false, reason: `列共享目录失败 errno=${shared.errno}` }
+    const devices = (shared.list || []).filter((f) => f.isdir === 1 && !isTmp(f.server_filename))
+    const wanted = String(toDevice || '').trim().toLowerCase()
+    const hit = devices.find((d) => d.server_filename.toLowerCase() === wanted)
+    if (!hit) return { ok: false, reason: `共享目录里没有这台设备：${toDevice}（现有：${devices.map((d) => d.server_filename).join('、') || '无'}）` }
+    const target = hit.server_filename
+    const mailId = `m-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`
+    const inboxDir = `${layout.paths.sharedDir}/${target}/inbox`
+    await pan.mkdir(inboxDir)
+    const envelope = {
+      id: mailId,
+      from,
+      to: toSession || '',
+      subject,
+      text: String(text || ''),
+      files: files.map((f) => ({ name: path.basename(f), size: fs.existsSync(f) ? fs.statSync(f).size : 0 })),
+      createdAt: Date.now(),
+      via: 'crossterm-relay',
+    }
+    if (files.length) {
+      const fileDir = `${layout.paths.sharedDir}/${target}/files/${mailId}`
+      await pan.mkdir(fileDir)
+      for (const f of files) await pan.put(f, `${fileDir}/${path.basename(f)}`)
+    }
+    const tmp = path.join(localDir, 'outgoing')
+    fs.mkdirSync(tmp, { recursive: true })
+    const localJson = path.join(tmp, `${mailId}.json`)
+    fs.writeFileSync(localJson, JSON.stringify(envelope, null, 2), 'utf8')
+    await pan.put(localJson, `${inboxDir}/${mailId}.json`)
+    const state = loadState(stateFile)
+    state.sent = (state.sent || []).concat([{ id: mailId, at: nowIso(), device: target, to: envelope.to, files: envelope.files.length }]).slice(-200)
+    saveState(stateFile, { ...state, at: Date.now() })
+    return { ok: true, mailId, device: target, to: envelope.to, files: envelope.files.length, path: `${inboxDir}/${mailId}.json` }
+  }
+
+  return { poll, sendEnvelope, stats: () => ({ ...stats }), localDir, stateFile, sha256 }
+}

package/lib/cloud/session-backup.js

@@ -0,0 +1,188 @@
+// 会话备份（0.3.39）：把本机会话数据按「字节增量」备份进
+//   <账号>/<设备>/sessions/<会话>/part-NNNN.bin + _session.json（水位标注）
+//   <账号>/<设备>/attachments/<sha256>（附件内容寻址，天然去重）
+// transcript 是**多帧 zstd**，解压要流式处理，所以这里备份原始字节、不解压；
+// 下次备份从 _session.json 里记的 bytes 之后继续传（用户要求「备份完加标注」）。
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex')
+
+function loadState(file) {
+  try {
+    const j = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return { at: j.at || 0, sessions: j.sessions || {}, attachments: j.attachments || {} }
+  } catch {
+    return { at: 0, sessions: {}, attachments: {} }
+  }
+}
+
+function saveState(file, state) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(state, null, 2), 'utf8')
+  } catch { /* ignore */ }
+}
+
+/** 列出 <sessionsRoot>/<workspaceKey>/<sessionId>/session.v4.jsonl.zstd */
+export function listTranscripts(sessionsRoot) {
+  const out = []
+  let wsKeys = []
+  try { wsKeys = fs.readdirSync(sessionsRoot, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) } catch { return out }
+  for (const ws of wsKeys) {
+    const wsDir = path.join(sessionsRoot, ws)
+    let ids = []
+    try { ids = fs.readdirSync(wsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name) } catch { continue }
+    for (const id of ids) {
+      const dir = path.join(wsDir, id)
+      let files = []
+      try { files = fs.readdirSync(dir) } catch { continue }
+      const file = files.find((f) => f === 'session.v4.jsonl.zstd') || files.find((f) => f.endsWith('.jsonl.zstd'))
+      if (!file) continue
+      const full = path.join(dir, file)
+      let st = null
+      try { st = fs.statSync(full) } catch { continue }
+      out.push({ sessionId: id, workspaceKey: ws, dir, file: full, size: st.size, mtimeMs: st.mtimeMs })
+    }
+  }
+  return out
+}
+
+function partName(n) {
+  return `part-${String(n).padStart(4, '0')}.bin`
+}
+
+/**
+ * 找会话显示名：names 的键可能是完整 sessionId，也可能是 8 位短号
+ * （Term.sessionNames() 用短号），两边都试一遍。
+ */
+function pickName(names, sessionId) {
+  if (!names) return null
+  if (names[sessionId]) return names[sessionId]
+  const bare = String(sessionId).replace(/^session-/, '')
+  const short = bare.slice(0, 8)
+  return names[short] || names[bare] || null
+}
+
+/**
+ * 备份会话（增量）
+ * @param {object} opts
+ * @param {object} opts.pan 云盘客户端
+ * @param {object} opts.layout ensureLayout() 的返回值
+ * @param {string} opts.sessionsRoot 例如 C:\Users\x\.dsh\sessions
+ * @param {string} opts.tmpDir 上传中转目录（本地）
+ * @param {string} opts.stateFile 水位/去重状态文件（本地）
+ * @param {Function} [opts.log]
+ * @param {number} [opts.maxSessions] 单轮最多处理多少个会话
+ * @param {object} [opts.names] sessionId → { name, cwd }
+ */
+export async function backupSessions({ pan, layout, sessionsRoot, tmpDir, stateFile, log = () => {}, maxSessions = 40, names = {} }) {
+  const state = loadState(stateFile)
+  const remoteRoot = layout.paths.sessionDir
+  const all = listTranscripts(sessionsRoot)
+  const result = { ok: true, total: all.length, uploaded: 0, skipped: 0, bytes: 0, sessions: [], error: '' }
+  fs.mkdirSync(tmpDir, { recursive: true })
+  let handled = 0
+
+  for (const item of all) {
+    if (handled >= maxSessions) break
+    const prev = state.sessions[item.sessionId] || { bytes: 0, parts: 0 }
+    if (prev.bytes === item.size) { result.skipped += 1; continue }
+    handled += 1
+    try {
+      const remoteDir = `${remoteRoot}/${item.sessionId}`
+      await pan.mkdir(remoteDir)
+      const grew = item.size > prev.bytes && prev.bytes > 0
+      let from = grew ? prev.bytes : 0
+      let partNo = grew ? Number(prev.parts || 1) + 1 : 1
+      const fd = fs.openSync(item.file, 'r')
+      const len = item.size - from
+      const buf = Buffer.alloc(len)
+      try { fs.readSync(fd, buf, 0, len, from) } finally { fs.closeSync(fd) }
+      const name = grew ? partName(partNo) : `full-${Date.now()}.bin`
+      const local = path.join(tmpDir, name)
+      fs.writeFileSync(local, buf)
+      const up = await pan.put(local, `${remoteDir}/${name}`)
+      try { fs.rmSync(local, { force: true }) } catch { /* ignore */ }
+      const chunks = grew ? (prev.chunks || []).concat([{ name, from, to: item.size, sha256: sha256(buf) }]) : [{ name, from: 0, to: item.size, sha256: sha256(buf) }]
+      const known = pickName(names, item.sessionId) || {}
+      const marker = {
+        sessionId: item.sessionId,
+        workspaceKey: item.workspaceKey,
+        name: known.name || prev.name || '',
+        cwd: known.cwd || prev.cwd || '',
+        bytes: item.size,
+        parts: chunks.length,
+        chunks,
+        size: item.size,
+        mtimeMs: item.mtimeMs,
+        updatedAt: new Date().toISOString(),
+        note: 'bytes = 已备份到的字节位置；下次只传 bytes 之后的新内容',
+      }
+      await pan.putBuffer(Buffer.from(JSON.stringify(marker, null, 2), 'utf8'), `${remoteDir}/_session.json`)
+      state.sessions[item.sessionId] = { bytes: item.size, parts: chunks.length, chunks, name: marker.name, cwd: marker.cwd, updatedAt: marker.updatedAt, fs_id: up.fs_id }
+      result.uploaded += 1
+      result.bytes += buf.length
+      result.sessions.push({ sessionId: item.sessionId, name: marker.name, bytes: buf.length, from, part: name })
+      saveState(stateFile, { ...state, at: Date.now() })
+    } catch (e) {
+      result.ok = false
+      result.error = `${item.sessionId}: ${(e && e.message) || String(e)}`
+      log(`会话备份失败 ${item.sessionId}：${result.error}`)
+      break
+    }
+  }
+  saveState(stateFile, { ...state, at: Date.now() })
+  return result
+}
+
+/**
+ * 备份附件（内容寻址，按 sha256 文件名去重；单轮有上限，剩下的下一轮继续）
+ */
+export async function backupAttachments({ pan, layout, objectsRoot, stateFile, log = () => {}, maxFiles = 40 }) {
+  const state = loadState(stateFile)
+  const remoteDir = layout.paths.attachmentDir
+  const result = { ok: true, total: 0, uploaded: 0, skipped: 0, bytes: 0, pending: 0, error: '' }
+  let files = []
+  try { files = fs.readdirSync(objectsRoot, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name) } catch { return result }
+  result.total = files.length
+  const todo = files.filter((f) => !state.attachments[f])
+  result.skipped = files.length - todo.length
+  result.pending = Math.max(0, todo.length - maxFiles)
+  if (!todo.length) return result
+  await pan.mkdir(remoteDir)
+  for (const name of todo.slice(0, maxFiles)) {
+    const full = path.join(objectsRoot, name)
+    try {
+      const st = fs.statSync(full)
+      await pan.put(full, `${remoteDir}/${name}`)
+      state.attachments[name] = { size: st.size, at: new Date().toISOString() }
+      result.uploaded += 1
+      result.bytes += st.size
+      saveState(stateFile, { ...state, at: Date.now() })
+    } catch (e) {
+      result.ok = false
+      result.error = `${name}: ${(e && e.message) || String(e)}`
+      log(`附件备份失败 ${name}：${result.error}`)
+      break
+    }
+  }
+  saveState(stateFile, { ...state, at: Date.now() })
+  return result
+}
+
+export function backupSummary(stateFile) {
+  const state = loadState(stateFile)
+  const sessions = Object.values(state.sessions)
+  return {
+    at: state.at || 0,
+    lastAt: state.at || 0,
+    sessions: sessions.length,
+    files: sessions.length,
+    lastCount: sessions.length,
+    bytes: sessions.reduce((a, s) => a + Number(s.bytes || 0), 0),
+    attachments: Object.keys(state.attachments).length,
+    attachmentBytes: Object.values(state.attachments).reduce((a, s) => a + Number(s.size || 0), 0),
+  }
+}