dsh-crossterm 0.3.38 → 0.3.39

package/README.md

@@ -257,6 +257,35 @@ dsh plugin --profile desktop remove dsh-crossterm
 > 残骸，而百度网盘列目录一页只给 200 条 —— 真实 json 被挤到了第二页。现在列目录会翻页，
 > 云端也不再上传 `.tmp`。
 
+### 云端目录：账号 / 设备 / 共享（0.3.39）
+
+打开云同步后，插件会在云盘的大文件夹（默认 `dsh`）下按账号和设备建目录，不用手动摆：
+
+```
+dsh/
+  <账号>/                       ← _account.json：ownerDevice（第一个进云的设备 = 管理员）
+    <设备>/                     ← _device.json：role（admin/member）、lastSeen、版本
+      sessions/<会话>/            part-0001.bin… full-<时间>.bin  + _session.json（水位标注）
+      attachments/<sha256>        附件按内容寻址，天生去重
+    shared/                    ← 云端设备共享文件夹：跨设备的信息、文件、邮件都走这里
+      <设备>/
+        inbox/                 收件箱（别的设备投给你的信）
+        done/                  收完归档
+        files/<mailId>/        附件
+```
+
+- **账号**：默认取云盘账号名；想改名在 `config.json` 写 `cloudAccount`，或设环境变量 `DSH_ACCOUNT`。
+- **角色**：账号下第一个进云的设备自动是 `admin`（看 `_account.json.ownerDevice`），之后的是 `member`。
+- **收信（云端中转站）**：每 20 秒查一次自己的 `inbox/`，取信 → 存本机
+  `<总线目录>/cloud/relay/incoming/` → 按**收件人会话名**投递 → 归档到 `done/` 再从收件箱删。
+- **会话备份**：每 5 分钟一轮，按字节增量（**不解压** transcript）：首次整份 `full-*.bin`，
+  之后只传新增那段 `part-NNNN.bin`；`_session.json` 里的 `bytes` 就是「备份到哪了」的标注，
+  下次从标注往后继续。附件单轮 20 个、会话单轮 20 个，余量下一轮接着传。
+- 卡片三行：**云端账号**（角色 + 设备号）、**云端中转站**（已收 / 失败 / 间隔）、
+  **会话备份**（会话数 · 体积 · 上次时间）；按钮 **收信**、**备份会话** 可手动催一轮。
+- 命令行等价物：`term_cloud action="home"`（看状态）、`action="layout"`（重建目录）、
+  `action="relay"`（收一轮）、`action="backup"`（备份一轮）。
+
 ### 手动 / 自动注入开关（三层）
 
 | 层 | 开关 | 粒度 |

package/client/client.js

@@ -156,6 +156,20 @@ window.__ModuleLoader__.load({
 				.join("；");
 		}
 
+		function sizeText(bytes) {
+			const n = Number(bytes || 0);
+			if (n < 1024) return n + " B";
+			if (n < 1024 * 1024) return (n / 1024).toFixed(1) + " KB";
+			if (n < 1024 * 1024 * 1024) return (n / 1024 / 1024).toFixed(1) + " MB";
+			return (n / 1024 / 1024 / 1024).toFixed(2) + " GB";
+		}
+
+		function backupText(backup) {
+			if (!backup || !backup.files) return "还没有备份（会在开云同步后自动开始）";
+			const when = backup.lastAt ? agoText(backup.lastAt) : "未知";
+			return `${backup.files} 个会话 · ${sizeText(backup.bytes)} · 上次 ${when}`;
+		}
+
 		function Card() {
 			const [open, setOpen] = React.useState(false);
 			const [status, setStatus] = React.useState(null);
@@ -270,9 +284,48 @@ window.__ModuleLoader__.load({
 				}
 			};
 
+			const onRelayCloud = async () => {
+				setBusy("relay");
+				setMsg("正在检查云端收件箱…");
+				try {
+					const data = await call("/crossterm/api/home?action=relay");
+					const relay = (data && data.relay) || {};
+					setMsg(
+						data && data.ok
+							? `收信完成：拉到 ${relay.fetched || 0} 封，投递 ${relay.delivered || 0} 封${relay.failed ? "，失败 " + relay.failed : ""}`
+							: "收信失败：" + ((data && (data.message || relay.error)) || "未知错误"),
+					);
+					if (data && data.home && status) setStatus({ ...status, home: data.home });
+				} catch (error) {
+					setMsg("收信失败：" + String((error && error.message) || error));
+				} finally {
+					setBusy("");
+				}
+			};
+
+			const onBackupNow = async () => {
+				setBusy("backup");
+				setMsg("正在备份会话…");
+				try {
+					const data = await call("/crossterm/api/backup", "POST");
+					const b = (data && data.backup) || {};
+					setMsg(
+						data && data.ok
+							? `备份完成：会话 ${(b.sessions && b.sessions.uploaded) || 0} 个，附件 ${(b.attachments && b.attachments.uploaded) || 0} 个（${Math.round((b.ms || 0) / 1000)} 秒）`
+							: "备份失败：" + ((data && data.message) || "未知错误"),
+					);
+					if (data && data.home && status) setStatus({ ...status, home: data.home });
+				} catch (error) {
+					setMsg("备份失败：" + String((error && error.message) || error));
+				} finally {
+					setBusy("");
+				}
+			};
+
 			const version = status ? "v" + status.version : "";
 			const mode = status && status.install ? status.install.mode : "";
 			const cloud = (status && status.cloud) || {};
+			const home = (status && status.home) || null;
 			const subtitle = status
 				? `${status.node || "本机"} · ${status.chains && status.chains.length ? status.chains.join(" / ") : "未入链"}`
 				: "加载中…";
@@ -360,12 +413,29 @@ window.__ModuleLoader__.load({
 									: null,
 							),
 						),
+						home && home.layout
+							? h(FriendlyRow, {
+								label: "云端账号",
+								value: `${home.layout.account}（${home.layout.role === "admin" ? "管理员" : "成员"}）· 设备 ${home.layout.deviceId}`,
+							})
+							: null,
+						home && home.relay
+							? h(FriendlyRow, {
+								label: "云端中转站",
+								value: `已收 ${home.relay.processed || 0} 封，失败 ${home.relay.failed || 0} 封 · 每 ${Math.round((home.relay.intervalMs || 0) / 1000)} 秒查一次`,
+							})
+							: null,
+						home && home.backup
+							? h(FriendlyRow, { label: "会话备份", value: backupText(home.backup) })
+							: null,
 						h(
 							"div",
 							{ style: S.actions },
 							h("button", { style: S.btn, onClick: onCheck, disabled: busy !== "" }, busy === "check" ? "检查中…" : "检查更新"),
 							h("button", { style: S.btnPrimary, onClick: onUpdate, disabled: busy !== "" }, busy === "update" ? "更新中…" : "更新"),
 							h("button", { style: S.btn, onClick: () => void loadDevices(), disabled: Boolean(devices && devices.loading) }, devices && devices.loading ? "读取中…" : "刷新设备"),
+							h("button", { style: S.btn, onClick: onRelayCloud, disabled: busy !== "" }, busy === "relay" ? "收信中…" : "收信"),
+							h("button", { style: S.btn, onClick: onBackupNow, disabled: busy !== "" }, busy === "backup" ? "备份中…" : "备份会话"),
 						),
 						msg ? h("div", { style: S.msg }, msg) : null,
 					),

package/lib/bus.js

@@ -22,7 +22,7 @@ import os from 'node:os'
 import path from 'node:path'
 import crypto from 'node:crypto'
 
-export const VERSION = '0.3.38'
+export const VERSION = '0.3.39'
 
 /** DSH 的家目录：与宿主其它状态（sessions / profiles）同一个根，多终端天然共享 */
 export function dshHome() {
@@ -63,6 +63,14 @@ const DEFAULTS = {
   cloudEnabled: false,
   cloudRoot: '/dsh云盘/crossterm/bus',
   cloudIntervalMs: 4000,
+  // 云端目录（0.3.39 起）：<cloudHome>/<账号>/<设备>/ + <账号>/shared/<设备>/inbox
+  cloudHome: 'dsh',
+  cloudAccount: '',
+  relayIntervalMs: 20000,
+  backupIntervalMs: 300000,
+  backupSessionsPerRun: 20,
+  backupAttachmentsPerRun: 20,
+  attachmentBackupEnabled: true,
   baiduAppFile: '',
   baiduAuthFile: '',
   cloudStateFile: '',

package/lib/cloud/home.js

@@ -0,0 +1,152 @@
+// 云端目录编排（0.3.39）：把「账号/设备/共享收件箱 + 中转站 + 会话备份」串起来
+//   start() 后按两个定时器跑：relayIntervalMs 收信投递、backupIntervalMs 会话增量备份
+import fs from 'node:fs'
+import path from 'node:path'
+import { ensureLayout, readLayoutCache, DEFAULT_HOME } from './layout.js'
+import { createRelay } from './relay.js'
+import { backupSessions, backupAttachments, backupSummary } from './session-backup.js'
+
+/**
+ * @param {object} opts
+ * @param {object} opts.cfg 插件配置（readConfig 结果）
+ * @param {object} opts.device { nodeId, name, version, platform, sessions }
+ * @param {object} opts.pan 云盘客户端
+ * @param {string} opts.busDir 总线根（<DSH_HOME>/crossterm）
+ * @param {Function} opts.deliver async ({ to, envelope, files }) => { ok, sessionId, reason }
+ * @param {Function} [opts.names] 返回 { <会话短号>: { name } }，给 _session.json 补显示名
+ * @param {Function} [opts.log]
+ */
+export function createCloudHome({ cfg, device, pan, busDir, deliver, names, log = () => {} }) {
+  const home = path.dirname(busDir)
+  const root = path.join(busDir, 'cloud')
+  fs.mkdirSync(root, { recursive: true })
+  const cacheFile = path.join(root, 'layout.json')
+  const relayDir = path.join(root, 'relay')
+  const relayState = path.join(relayDir, 'state.json')
+  const backupState = path.join(root, 'backup-state.json')
+  const sessionsRoot = path.join(home, 'sessions')
+  const attachmentsRoot = path.join(home, 'attachments', 'v1', 'objects')
+
+  let timers = []
+  let started = false
+  let layoutBusy = null
+  let backupBusy = null
+  let relayTimer = 0
+  let backupTimer = 0
+
+  const relay = createRelay({
+    pan,
+    getLayout: () => getLayout(false),
+    localDir: relayDir,
+    stateFile: relayState,
+    deliver,
+    log: (line) => log('relay: ' + line),
+  })
+
+  async function getLayout(force = false) {
+    if (!force && layoutBusy) return layoutBusy
+    layoutBusy = (async () => {
+      try {
+        const info = await ensureLayout({
+          pan,
+          cfg,
+          device,
+          cacheFile,
+          force,
+          log: (line) => log('layout: ' + line),
+        })
+        return info
+      } catch (e) {
+        const msg = (e && e.message) || String(e)
+        log(`建云端目录失败：${msg}`)
+        const cached = readLayoutCache(cacheFile)
+        if (cached) return { ...cached, cached: true, error: msg }
+        return { error: msg }
+      } finally {
+        layoutBusy = null
+      }
+    })()
+    return layoutBusy
+  }
+
+  async function backupNow() {
+    if (backupBusy) return backupBusy
+    backupBusy = (async () => {
+      const layout = await getLayout(false)
+      if (!layout || !layout.paths) return { ok: false, error: layout?.error || '云端目录还没准备好' }
+      const namesMap = typeof names === 'function' ? names() || {} : {}
+      const sessionNames = {}
+      for (const [short, rec] of Object.entries(namesMap)) sessionNames[short] = { name: rec?.name || '', cwd: rec?.cwd || '' }
+      const started = Date.now()
+      const sessions = await backupSessions({
+        pan,
+        layout,
+        sessionsRoot,
+        tmpDir: path.join(root, 'tmp'),
+        stateFile: backupState,
+        log: (line) => log('backup: ' + line),
+        maxSessions: Number(cfg.backupSessionsPerRun || 20),
+        names: sessionNames,
+      })
+      let attachments = { ok: true, uploaded: 0, skipped: 0, pending: 0 }
+      if (cfg.attachmentBackupEnabled !== false) {
+        attachments = await backupAttachments({
+          pan,
+          layout,
+          objectsRoot: attachmentsRoot,
+          stateFile: backupState,
+          log: (line) => log('backup: ' + line),
+          maxFiles: Number(cfg.backupAttachmentsPerRun || 20),
+        })
+      }
+      const out = { ok: sessions.ok && attachments.ok, ms: Date.now() - started, sessions, attachments, summary: backupSummary(backupState) }
+      log(`会话备份：上传 ${sessions.uploaded} 个会话 / ${attachments.uploaded} 个附件（失败 ${sessions.error || attachments.error || '无'}）`)
+      return out
+    })()
+    try { return await backupBusy } finally { backupBusy = null }
+  }
+
+  async function relayNow() {
+    return relay.poll()
+  }
+
+  async function send(opts) {
+    return relay.sendEnvelope(opts)
+  }
+
+  function status() {
+    const layout = readLayoutCache(cacheFile)
+    return {
+      home: `${cfg.cloudHome || DEFAULT_HOME}`,
+      layout: layout
+        ? { account: layout.account, role: layout.role, deviceId: layout.deviceId, paths: layout.paths, ensuredAt: layout.ensuredAt }
+        : null,
+      relay: { ...relay.stats(), intervalMs: relayTimer },
+      backup: { ...backupSummary(backupState), intervalMs: backupTimer },
+      roots: { sessions: sessionsRoot, attachments: attachmentsRoot },
+    }
+  }
+
+  function start() {
+    if (started) return
+    started = true
+    relayTimer = Number(cfg.relayIntervalMs || 20000)
+    backupTimer = Number(cfg.backupIntervalMs || 300000)
+    void getLayout(false).catch(() => {})
+    timers.push(setInterval(() => { void relayNow().catch(() => {}) }, relayTimer))
+    timers.push(setInterval(() => { void backupNow().catch(() => {}) }, backupTimer))
+    for (const t of timers) if (t && typeof t.unref === 'function') t.unref()
+    // 启动 8 秒后先跑一轮收信、30 秒后跑第一轮备份（别和宿主启动抢资源）
+    setTimeout(() => { void relayNow().catch(() => {}) }, 8000)
+    setTimeout(() => { void backupNow().catch(() => {}) }, 30000)
+    log(`云端目录就绪：relay ${relayTimer}ms / backup ${backupTimer}ms（根 ${cfg.cloudHome || DEFAULT_HOME}）`)
+  }
+
+  function stop() {
+    started = false
+    for (const t of timers) clearInterval(t)
+    timers = []
+  }
+
+  return { start, stop, status, getLayout, backupNow, relayNow, send, cacheFile, relayDir }
+}

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'
@@ -96,9 +96,33 @@ export function createPan({ appFile, authFile, log = () => {} }) {
     return { errno: 0, list: all }
   }
 
-  async function put(localPath, remotePath) {
+  // 建目录：xpan 的 create 带 isdir=1；已存在（31061 / -8）视为成功
+  async function mkdir(remotePath) {
+    await ensureToken()
+    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 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(
@@ -137,6 +161,20 @@ 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)
@@ -166,5 +204,5 @@ export function createPan({ appFile, authFile, log = () => {} }) {
     )
   }
 
-  return { uinfo, ls, lsAll, 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),
+  }
+}

package/lib/index.js

@@ -36,6 +36,7 @@ import {
 import { deriveNameFromFile, findTranscript } from './names.js'
 import { createPan } from './cloud/pan.js'
 import { createCloud } from './cloud/sync.js'
+import { createCloudHome } from './cloud/home.js'
 import { runSetup } from './cloud/setup.js'
 import { registerWeb } from './web.js'
 
@@ -730,6 +731,69 @@ class CrossTerm {
     return { ok: true, sessionId, files: landed }
   }
 
+  // ── 云端中转站（0.3.39）────────────────────────────────────────────────
+
+  /** 按会话名（也接受短号/完整 id）找本终端里的会话 */
+  resolveByName(raw) {
+    const s = String(raw || '').trim()
+    if (!s) return ''
+    const lower = s.toLowerCase()
+    const list = this.sessions()
+    const exact = list.find((x) => [x.name, x.title, x.short, x.id].some((v) => String(v || '').trim().toLowerCase() === lower))
+    if (exact) return exact.id
+    const part = list.find((x) => [x.name, x.title].some((v) => String(v || '').trim().toLowerCase().includes(lower)))
+    if (part) return part.id
+    return this.resolveSessionId(s) || ''
+  }
+
+  /** 中转站投递：把云端收件箱里的一封信投进本机对应会话（按收件人会话名） */
+  async relayDeliver({ to, envelope = {}, files = [] }) {
+    const targets = (Array.isArray(to) ? to : String(to || '').split(/[,，;；\s]+/))
+      .map((s) => String(s || '').trim())
+      .filter(Boolean)
+    if (!targets.length) return { ok: false, reason: '信封里没有收件人（要填会话名）' }
+    const controller = this.sessionController()
+    if (!controller || typeof controller.prompt !== 'function') {
+      return { ok: false, reason: '本 Host 没有 sessionController.prompt，中转站只能留件' }
+    }
+    const from = envelope.from || {}
+    const lines = ['[云端中转站] 收到 1 封']
+    lines.push(`来自：${from.name || from.nodeId || '未知设备'}${from.nodeId ? ` (${from.nodeId})` : ''}`)
+    if (envelope.subject) lines.push(`主题：${envelope.subject}`)
+    if (envelope.text) lines.push('', String(envelope.text).trim())
+    const landed = files.filter((f) => f && f.local)
+    if (landed.length) {
+      lines.push('', '附件已保存到本机：')
+      for (const f of landed) lines.push(`- ${f.local}（${formatBytes(f.bytes || 0)}）`)
+    }
+    const bad = files.filter((f) => !f || !f.local)
+    if (bad.length) lines.push('', `（有 ${bad.length} 个附件没下载下来：${bad.map((f) => (f && f.name) || '未知').join('、')}）`)
+    lines.push('', `（这封信由云端中转站投递；收件人：${targets.join('、')}。回复用 term_send。）`)
+    const text = lines.join('\n')
+    const delivered = []
+    const failed = []
+    for (const target of targets) {
+      const sessionId = this.resolveByName(target)
+      if (!sessionId) { failed.push({ target, reason: '本机没有这个会话' }); continue }
+      try {
+        await this.promptSession(controller, { id: `relay-${Date.now()}-${shortId(sessionId)}` }, sessionId, text)
+        delivered.push(sessionId)
+        await this.note(`relay delivered -> ${this.labelOf(sessionId)}`)
+      } catch (e) {
+        failed.push({ target, reason: (e && e.message) || String(e) })
+      }
+    }
+    if (!delivered.length) return { ok: false, reason: `投递失败：${failed.map((f) => `${f.target}（${f.reason}）`).join('、')}` }
+    return { ok: true, sessionId: delivered[0], delivered, failed }
+  }
+
+  /** 给云端备份用的「会话短号 → 显示名」表 */
+  sessionNames() {
+    const out = {}
+    for (const s of this.sessions()) out[s.short] = { name: s.name || '', cwd: s.cwd || '' }
+    return out
+  }
+
   // ── 会话链（一串特征码链接多个会话）────────────────────────────────────
 
   async loadLinks() {
@@ -1161,10 +1225,42 @@ class CrossTerm {
     })
     this.cloud.start()
     void this.note(`cloud sync 启动 → ${this.cfg.cloudRoot}（${this.cfg.cloudIntervalMs}ms）`)
+    this.enableCloudHome(pan)
     return this.cloud
   }
 
+  /** 云端目录（账号/设备/共享收件箱）+ 中转站 + 会话备份，见 lib/cloud/home.js */
+  enableCloudHome(pan) {
+    if (this.home) return this.home
+    try {
+      this.home = createCloudHome({
+        cfg: this.cfg,
+        device: {
+          nodeId: this.nodeId,
+          name: this.cfg.name,
+          version: VERSION,
+          platform: process.platform,
+          sessions: this.sessions().length,
+        },
+        pan,
+        busDir: this.bus.root,
+        deliver: (opts) => this.relayDeliver(opts),
+        names: () => this.sessionNames(),
+        log: (m) => void this.note('cloud: ' + m),
+      })
+      this.home.start()
+    } catch (e) {
+      this.home = null
+      void this.warn('云端目录启动失败：' + ((e && e.message) || String(e)))
+    }
+    return this.home
+  }
+
   disableCloud() {
+    if (this.home) {
+      this.home.stop()
+      this.home = null
+    }
     if (!this.cloud) return false
     this.cloud.stop()
     this.cloud = null
@@ -1196,6 +1292,7 @@ class CrossTerm {
     if (this.timer) clearInterval(this.timer)
     this.timer = undefined
     if (this.cloud) { this.cloud.stop(); this.cloud = null }
+    if (this.home) { this.home.stop(); this.home = null }
     await this.bus.leave(this.nodeId).catch(() => {})
     await this.note('stopped')
   }
@@ -1617,14 +1714,33 @@ function buildTools(term, agent, part = 'all') {
 
   const cloud = defineTool({
     name: 'term_cloud',
-    description: '云总线同步：查看/开启/关闭本机总线与云端目录的镜像同步，或立刻同步一次；setup 可一键配置自己的云盘（弹出记事本填 AppKey/AppSecret → 浏览器授权 → 自动开启同步）。',
+    description: '云总线同步：查看/开启/关闭本机总线与云端目录的镜像同步，或立刻同步一次；setup 可一键配置自己的云盘（弹出记事本填 AppKey/AppSecret → 浏览器授权 → 自动开启同步）；home/layout/relay/backup 管理云端目录（账号/设备/共享收件箱/中转站/会话备份）。',
     parameters: {
-      action: { type: 'string', enum: ['status', 'start', 'stop', 'once', 'setup'], description: 'status=查看状态；start=开启（本进程内生效）；stop=关闭；once=立刻同步一次；setup=一键配置自己的云盘' },
+      action: { type: 'string', enum: ['status', 'start', 'stop', 'once', 'setup', 'home', 'layout', 'relay', 'backup'], description: 'status=查看状态；start=开启（本进程内生效）；stop=关闭；once=立刻同步一次；setup=一键配置自己的云盘；home=云端目录/中转站/备份概况；layout=重建云端目录；relay=立刻收一轮云端收件箱；backup=立刻备份一轮会话' },
       code: { type: 'string', description: '仅 setup 用：授权回调 URL 里的 code（浏览器没自动回调时手动粘贴）；不填则插件自己起本地回调等待' },
     },
     output: {
       schema: { type: 'json' },
       render: textRender((v) => {
+        if (v && v.home) {
+          const h = v.home
+          const lines = []
+          if (h.layout) {
+            lines.push(`云端账号：${h.layout.account}（角色 ${h.layout.role === 'admin' ? '管理员' : '成员'}，设备 ${h.layout.deviceId}）`)
+            const p = h.layout.paths || {}
+            lines.push(`设备目录：${p.deviceDir || '(未建)'}`)
+            lines.push(`我的收件箱：${p.inboxDir || '(未建)'}`)
+            lines.push(`会话备份：${p.sessionDir || '(未建)'}（${h.backup?.files || 0} 个会话，已备份 ${formatBytes(h.backup?.bytes || 0)}）`)
+          } else {
+            lines.push('云端目录：还没建好（可能没连云盘，或建目录失败）')
+          }
+          if (h.relay) lines.push(`中转站：已收 ${h.relay.processed || 0} 封，失败 ${h.relay.failed || 0} 封，每 ${Math.round((h.relay.intervalMs || 0) / 1000)} s 查一次`)
+          if (h.backup?.lastAt) lines.push(`上次备份：${new Date(h.backup.lastAt).toISOString()}（${h.backup.lastCount || 0} 个会话）`)
+          if (v.layout) lines.push(`目录动作：${v.layout.created?.length ? '新建 ' + v.layout.created.join('、') : '已存在'}`)
+          if (v.relay) lines.push(`本轮收信：拉取 ${v.relay.fetched || 0} 封，投递 ${v.relay.delivered || 0}，失败 ${v.relay.failed || 0}`)
+          if (v.backup) lines.push(`本轮备份：会话 ${v.backup.sessions?.uploaded || 0}，附件 ${v.backup.attachments?.uploaded || 0}，耗时 ${v.backup.ms || 0} ms`)
+          return lines.join('\n')
+        }
         if (v && v.setup) {
           const s = v.setup
           const lines = []
@@ -1666,6 +1782,24 @@ function buildTools(term, agent, part = 'all') {
           term.enableCloud()
           return { ok: true, status: term.cloud ? term.cloud.status() : undefined, setup: ret }
         }
+        else if (action === 'home' || action === 'layout' || action === 'relay' || action === 'backup') {
+          if (!term.cloud) term.enableCloud()
+          const h = term.home
+          if (!h) return { ok: false, detail: '云同步没开（先 action="start"，或在设置里开云同步）' }
+          if (action === 'layout') {
+            const layout = await h.getLayout(true)
+            return { ok: !!(layout && layout.paths), home: h.status(), layout }
+          }
+          if (action === 'relay') {
+            const relay = await h.relayNow()
+            return { ok: relay.ok !== false, relay, home: h.status() }
+          }
+          if (action === 'backup') {
+            const backup = await h.backupNow()
+            return { ok: backup.ok !== false, backup, home: h.status() }
+          }
+          return { ok: true, home: h.status() }
+        }
         else if (action === 'once') {
           const c = term.cloud || term.enableCloud()
           const result = await c.once()

package/lib/web.js

@@ -258,6 +258,8 @@ function statusOf(term) {
       provider,
     },
     chains,
+    // 云端目录（0.3.39）：账号/角色/设备目录/中转站/会话备份
+    home: term.home ? term.home.status() : null,
   }
 }
 
@@ -316,6 +318,70 @@ export function registerWeb(ctx, term, log) {
             },
           }),
         )
+        disposers.push(
+          webCtx.webServer.register({
+            kind: 'exact',
+            path: '/crossterm/api/home',
+            handler: async (req, res) => {
+              const cfg = term.cfg || {}
+              if (!statusOf(term).cloud.configured) {
+                json(res, 200, { ok: false, configured: false, message: '这台机器还没连接云盘：先「配置云盘」' })
+                return
+              }
+              try {
+                if (!term.home) term.enableCloud()
+                const home = term.home
+                if (!home) {
+                  json(res, 200, { ok: false, configured: true, message: '云端目录还没启动（云同步可能被关掉了）' })
+                  return
+                }
+                const url = String((req && req.url) || '')
+                const action = (() => {
+                  try { return String(new URL(url, 'http://x').searchParams.get('action') || '') } catch { return '' }
+                })()
+                if (action === 'layout') {
+                  const layout = await home.getLayout(true)
+                  log(`home: 云端目录 ${layout && layout.paths ? layout.paths.deviceDir : '未建好'}`)
+                  json(res, 200, { ok: !!(layout && layout.paths), home: home.status(), layout })
+                  return
+                }
+                if (action === 'relay') {
+                  const relay = await home.relayNow()
+                  json(res, 200, { ok: relay.ok !== false, relay, home: home.status() })
+                  return
+                }
+                if (action === 'backup') {
+                  const backup = await home.backupNow()
+                  json(res, 200, { ok: backup.ok !== false, backup, home: home.status() })
+                  return
+                }
+                json(res, 200, { ok: true, configured: true, home: home.status(), cloudRoot: cfg.cloudRoot || '' })
+              } catch (error) {
+                json(res, 200, { ok: false, configured: true, message: String((error && error.message) || error) })
+              }
+            },
+          }),
+        )
+        disposers.push(
+          webCtx.webServer.register({
+            kind: 'exact',
+            path: '/crossterm/api/backup',
+            handler: async (req, res) => {
+              try {
+                if (!term.home) term.enableCloud()
+                if (!term.home) {
+                  json(res, 200, { ok: false, message: '云端目录还没启动（先在卡片上打开云同步）' })
+                  return
+                }
+                const result = await term.home.backupNow()
+                log(`backup: 会话 ${result.sessions ? result.sessions.uploaded : 0}，附件 ${result.attachments ? result.attachments.uploaded : 0}`)
+                json(res, 200, { ok: result.ok !== false, backup: result, home: term.home.status() })
+              } catch (error) {
+                json(res, 200, { ok: false, message: String((error && error.message) || error) })
+              }
+            },
+          }),
+        )
         disposers.push(
           webCtx.webServer.register({
             kind: 'exact',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crossterm",
-  "version": "0.3.38",
+  "version": "0.3.39",
   "description": "DSH 跨终端互联：同一账号下的多个 DSH 终端/进程互发邮件与文件（主题内联、正文落盘，收件方自己读）",
   "type": "module",
   "main": "./lib/index.js",