@whispering233/ai-editor-server 0.0.33 → 0.0.38

package/dist/backup.js

@@ -1,14 +1,17 @@
 // 自动备份与恢复（B2.2 + B2.5 + B2.6）
 //
 // 职责：
-// - 备份管道：三文件 + wal_checkpoint → .backups/<YYYYMMDD-HHmmssSSS>[-<kind>][-<名称>].zip
-// （复用导出打包；毫秒精度；kind 段：手动备份落 -m[-<名称>]、
-// 自动备份/覆盖前快照纯时间戳、重命名后自动备份落 -a-<名称>）
+// - 备份管道：三文件 + wal_checkpoint → .backups/<YYYYMMDD-HHmmssSSS>-<自动|手动>-<设备>[-<标签>]-人物N-设定N-章N.zip
+// （复用导出打包；毫秒精度；类型段：手动备份落「手动」、自动备份/覆盖前快照落「自动」）
 // - 保留策略：每项目保留最近 MAX_BACKUPS_PER_PROJECT 份，超出删除最旧（含覆盖前快照；
-// 新旧格式文件名均参与——parseBackupFileName 兼容解析）
+// **只有唯一命名格式的文件参与**——parseBackupFileName 解析，旧命名份留盘但不识别）
+// - 升级兜底：打开项目时若 .backups/ 有文件但无一可解析（旧命名残留）→ ensureParseableBackup
+// 立即生成一份新格式备份（不重命名旧份：旧份无设备/统计信息，硬补会谎报）
 // - 自动定时器：跟随当前项目生命周期（middleware/project.ts setCurrentProject 挂载启停），
 // 有变更才备份（三文件 + data.db-wal 伴生文件 mtime 与 .backups/ 最新备份时间比较，
-// 无状态、服务重启不丢；F2：WAL 模式写只刷新 -wal，补查避免漏检 data.db 变更）
+// 无状态、服务重启不丢；F2：WAL 模式写只刷新 -wal，补查避免漏检 data.db 变更）；
+// 频率关闭时回落 `setProjectTick` 注入的兑底间隔（卡 7：自动推送挂在同一条 tick 链上，
+// 按 2h 排程——不新起第二个定时器）
 // - 备份包校验（restore 与 import 共用）：zip 解析/白名单/三文件齐全/顶层/
 // data.db user_version 三态分流（绝不静默重建）
 // - restore：fileName 白名单 → 覆盖前自动快照 → 校验 → 原子替换三文件
@@ -22,8 +25,9 @@ import { basename, dirname, join } from "node:path";
 import { Unzip, UnzipInflate, zipSync } from "fflate";
 import { BACKUP_FREQUENCIES, DEFAULT_BACKUP_FREQUENCY_MINUTES, formatBackupFileName, MAX_BACKUPS_PER_PROJECT, MAX_BACKUP_NAME_LENGTH, parseBackupFileName, sanitizeBackupName } from "@whispering233/ai-editor-shared";
 import { PROJECT_EXPORT_FILE_NAMES } from "@whispering233/ai-editor-shared/schemas";
-import { closeDatabase, checkpointWal, DATA_DB_FILE_NAME, ensureSchemaCompatible, getUserVersion, hasMigrationPath, openDatabase, OUTLINE_FILE_NAME, PROJECT_FILE_NAME, readAgentsFile, readProjectFile, SCHEMA_VERSION, writeAgentsFile, } from "@whispering233/ai-editor-db";
+import { AGENTS_FILE_NAME, closeDatabase, checkpointWal, DATA_DB_FILE_NAME, ensureSchemaCompatible, getBackupStats, getUserVersion, hasMigrationPath, openDatabase, OUTLINE_FILE_NAME, PROJECT_FILE_NAME, readAgentsFile, readProjectFile, SCHEMA_VERSION, writeAgentsFile, } from "@whispering233/ai-editor-db";
 import { SESSIONS_DIR_NAME } from "@whispering233/ai-editor-agent";
+import { currentDeviceName } from "./cloud/device.js";
 import { HttpError } from "./middleware/error.js";
 /** 备份目录名（项目目录内 .backups/，随书籍移动自然携带） */
 export const BACKUPS_DIR_NAME = ".backups";
@@ -35,7 +39,7 @@ const REFERENCE_DIR_NAME = "references";
  * 白名单前缀 + 递归打包 + 参与变更判定 + 恢复时整体覆盖。
  * `SESSIONS_DIR_NAME` 取自 agent 包的 pi 运行时（会话目录的唯一事实来源；pi 的 session 文件落在此目录）。
  */
-const PACKED_DIR_NAMES = [REFERENCE_DIR_NAME, SESSIONS_DIR_NAME];
+export const PACKED_DIR_NAMES = [REFERENCE_DIR_NAME, SESSIONS_DIR_NAME];
 /** 备份包条目白名单判定（三文件 + 打包目录前缀——逐名比对天然防 zip 路径穿越；
  * 目录子路径拒绝含 `..` 的条目防相对路径逃逸） */
 export function isAllowedBackupEntry(name) {
@@ -81,6 +85,63 @@ function overwriteDirFromEntries(dir, dirName, entries) {
         writeFileAtomic(target, entries[key]);
     }
 }
+/**
+ * 用备份条目与本机现有文件做**并集合并**（云拉取语义；本地 restore 不走这里）：
+ * 逐文件三方比较（本机 / 云端那份 / 基线 `baseEntries`）——
+ *
+ * | 本机 | 云端 | 基线 | 动作 |
+ * | 有 | 有 | — | 写云端那份（同名 = 同一资产） |
+ * | 有 | 无 | ✔ | 删本机（云端删除传播） |
+ * | 有 | 无 | ✘ | 保留本机（本机新增） |
+ * | 无 | 有 | ✔ | **不写回**（本机删除优先，不被复活） |
+ * | 无 | 有 | ✘ | 写进来（云端新增） |
+ *
+ * 基线由 `cloud.json` 的 `books[<id>].baseEntries`（= 最近一次推送/拉取包的条目）提供。
+ */
+function mergeDirFromEntries(dir, dirName, entries, baseEntries) {
+    const baseDir = join(dir, dirName);
+    const rel = (key) => key.slice(dirName.length + 1);
+    const localSet = new Set(listDirFiles(dir, dirName));
+    const cloudKeys = Object.keys(entries).filter((k) => k.startsWith(`${dirName}/`) && rel(k) !== "");
+    const cloudSet = new Set(cloudKeys.map(rel));
+    const baseSet = new Set(baseEntries.filter((e) => e.startsWith(`${dirName}/`) && rel(e) !== "").map(rel));
+    const counts = { kept: 0, written: 0, removed: 0 };
+    const safeSegments = (path) => {
+        const segments = path.split("/");
+        return segments.includes("..") ? null : segments; // 白名单已校验，双保险
+    };
+    // 本机侧：云端没有的份，按基线判「云端删了它」还是「本机新增」
+    for (const path of localSet) {
+        if (cloudSet.has(path))
+            continue; // 两边都有 → 由云端侧写云端那份
+        const segments = safeSegments(path);
+        if (segments === null)
+            continue;
+        if (baseSet.has(path)) {
+            rmSync(join(baseDir, ...segments), { force: true });
+            counts.removed += 1;
+        }
+        else {
+            counts.kept += 1;
+        }
+    }
+    // 云端侧：本机没有的份，按基线判「本机删了它」（不复活）还是「云端新增」
+    for (const key of cloudKeys) {
+        const path = rel(key);
+        const segments = safeSegments(path);
+        if (segments === null)
+            continue;
+        const isLocalNew = !localSet.has(path);
+        if (isLocalNew && baseSet.has(path))
+            continue; // 本机删除优先
+        const target = join(baseDir, ...segments);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileAtomic(target, entries[key]);
+        if (isLocalNew)
+            counts.written += 1;
+    }
+    return counts;
+}
 /** 解压总字节预算（200MB，zip 炸弹防御——与 import 同款，restore 复用） */
 const MAX_UNZIP_BUDGET = 200 * 1024 * 1024;
 /**
@@ -93,16 +154,16 @@ const MAX_UNZIP_BUDGET = 200 * 1024 * 1024;
 const BACKUP_CHANGE_TOLERANCE_MS = 1000;
 /**
  * 备份文件名白名单校验（renameBackup / restoreBackup 共用，防路径穿越）：
- * parseBackupFileName 全格式校验（时间戳部分 ^$ 锚定纯数字 + 名称部分拒绝 /\\，
- * 天然防路径分隔符与 `..` 穿越；含旧格式兼容解析）；非法 → 400 VALIDATION_ERROR（文案统一）。
+ * parseBackupFileName 全格式校验（时间戳部分 ^$ 锚定纯数字 + 设备/标签部分拒绝 /\\，
+ * 天然防路径分隔符与 `..` 穿越；旧命名不可解析 ⇒ 同样被拒）；非法 → 400 VALIDATION_ERROR（文案统一）。
  *
- * @returns 解析结果（校验通过即返回非 null——调用方直接取 time/kind/name，免二次解析）
+ * @returns 解析结果（校验通过即返回非 null——调用方直接取 time/kind/name/device/stats，免二次解析）
  * @throws HttpError 400 VALIDATION_ERROR（文件名格式非法）
  */
 function assertBackupFileNameFormat(fileName) {
     const parsed = parseBackupFileName(fileName);
     if (parsed === null) {
-        throw new HttpError(400, "VALIDATION_ERROR", `备份文件名格式非法（仅接受 <YYYYMMDD-HHmmssSSS>[-<kind>][-<名称>].zip 时间戳格式）: ${fileName}`);
+        throw new HttpError(400, "VALIDATION_ERROR", `备份文件名格式非法（仅接受 <YYYYMMDD-HHmmssSSS>-<自动|手动>-<设备>[-<标签>]-人物N-设定N-章N.zip）: ${fileName}`);
     }
     return parsed;
 }
@@ -131,38 +192,33 @@ export function createBackupZip(project) {
     return zipSync(zipEntries, { level: 6 });
 }
 /**
- * 生成不冲突的备份文件名：`<YYYYMMDD-HHmmssSSS>[-<kind>][-<名称>].zip`（毫秒精度 +
- * kind 段；shared formatBackupFileName；kind 缺省 auto——纯时间戳；带自定义名称 →
- * `-a-<名称>`（auto）/ `-m-<名称>`（manual））。
- *
- * 同毫秒冲突（如「立即备份 + restore 覆盖前快照」连续触发，理论罕见）处理：
- * 时间戳 +1 毫秒循环去重，**保持 <YYYYMMDD-HHmmssSSS>[-<kind>][-<名称>].zip 格式**——
- * parseBackupFileName 解析与 restore 白名单校验不受影响。
+ * 生成不冲突的备份文件名：`<时间戳>-<类型>-<设备>[-<标签>]-人物N-设定N-章N.zip`（毫秒精度 +
+ * 设备段 + 统计段；shared formatBackupFileName）。同毫秒冲突（如「立即备份 + restore 覆盖前
+ * 快照」连续触发，理论罕见）处理：时间戳 +1 毫秒循环去重，**保持格式契约可解析**。
  *
  * @returns { fileName, date }——date 为最终去重后的时间戳（与 fileName 时间戳段一致，
  * 调用方直接用于构造 createdAt，免 parse 回读）
  */
 function uniqueBackupFileName(backupsDir, date, opts) {
-    const kind = opts?.kind ?? "auto";
-    const name = opts?.name;
-    let fileName = formatBackupFileName(date, { kind, name });
+    const { kind = "auto", name, device, stats } = opts;
+    let fileName = formatBackupFileName(date, { kind, name, device, stats });
     while (existsSync(join(backupsDir, fileName))) {
         date = new Date(date.getTime() + 1);
-        fileName = formatBackupFileName(date, { kind, name });
+        fileName = formatBackupFileName(date, { kind, name, device, stats });
     }
     return { fileName, date };
 }
 /**
  * 立即备份当前项目（手动触发 / 自动定时器 / restore 覆盖前快照共用）：
- * 打包 → 写入 .backups/<时间戳>[-<kind>][-<名称>].zip（毫秒精度；同毫秒 +1ms 去重）→
- * 触发保留策略清理（失败不阻塞）。
+ * 打包 → 写入 .backups/<时间戳>-<自动|手动>-<设备>[-<标签>]-人物N-设定N-章N.zip
+ * （唯一命名格式，毫秒精度；同毫秒 +1ms 去重）→ 触发保留策略清理（失败不阻塞）。
  * 写盘失败向上抛（errorHandler → 500 INTERNAL_ERROR，POST /backup 语义）。
  *
- * @param opts.kind 备份类型（缺省 "auto"）：手动触发传 "manual"（文件名落 -m 段）；
- * 自动备份/覆盖前快照不传（auto，纯时间戳）
+ * @param opts.kind 备份类型（缺省 "auto"）：手动触发传 "manual"（文件名落「手动」段）；
+ * 自动备份/覆盖前快照不传（auto，「自动」段）
  * @param opts.name 手动备份自定义名称（仅带名称的手动/重命名场景传入）：
  * sanitizeBackupName 是名称校验/规范化**唯一执行点**——非法（含路径分隔符/超长/纯点）→
- * 400 VALIDATION_ERROR；自动备份/覆盖前快照不传 name，文件名保持纯时间戳。
+ * 400 VALIDATION_ERROR；自动备份/覆盖前快照不传 name，文件名无标签段。
  * 注意：name 仅在 opts.name !== undefined 且 sanitize 通过后传入 formatBackupFileName。
  */
 export function writeBackup(project, opts) {
@@ -175,10 +231,14 @@ export function writeBackup(project, opts) {
         }
         name = sanitized;
     }
+    // 统计快照在打包前取（同一连接同一时刻视角）；设备名 = 当前生效值
+    //（云端配置的 device 优先，缺省 = 本机 hostname 派生，见 cloud/device.ts）
+    const stats = getBackupStats(project.db, project.root);
+    const device = currentDeviceName();
     const zip = createBackupZip(project);
     const backupsDir = join(project.root, BACKUPS_DIR_NAME);
     mkdirSync(backupsDir, { recursive: true });
-    const { fileName, date } = uniqueBackupFileName(backupsDir, new Date(), { kind, name });
+    const { fileName, date } = uniqueBackupFileName(backupsDir, new Date(), { kind, name, device, stats });
     writeFileSync(join(backupsDir, fileName), zip); // 失败抛错 → 500（不产出半截备份）
     pruneBackups(backupsDir); // 清理失败仅记日志，不阻塞备份主流程
     return {
@@ -187,25 +247,64 @@ export function writeBackup(project, opts) {
         createdAt: toIso(date), // date = 最终去重后的时间戳，与 fileName 时间戳段一致（无状态语义）
         kind,
         ...(name !== undefined ? { name } : {}),
+        device,
+        stats,
     };
 }
 /**
- * 重命名备份（POST /project/backup/rename）：**只改名称段**，时间戳与 kind 保持。
+ * 升级兜底（卡 A）：`.backups/` 里**有文件但没有任何一份可解析**（旧命名残留形态）→
+ * 立即 `writeBackup(project, { kind: "auto" })` 生成一份新格式备份并返回 true；
+ * 已有可解析份（或目录为空/不存在）→ 什么都不做，返回 false（**不重复备份**）。
+ *
+ * 为什么需要：旧命名份不再被解析（列表/恢复/保留策略均不认），若磁盘上只剩旧命名且
+ * **自动备份频率关闭**，用户点「立即备份」前列表会是空的；这一调用保证最新数据马上有一份
+ * 新格式可列/可恢复的档。**不重命名旧份**——旧份无设备/统计信息，硬补会谎报（统计必须描述该备份的内容）。
  *
+ * best-effort：任何异常只记日志并返回 false（打开项目不得因兜底备份失败而失败）。
  *
- * 1. fileName 白名单校验：仅接受 parseBackupFileName 可解析的时间戳格式
- * `<YYYYMMDD-HHmmssSSS>[-<kind>][-<名称>].zip`（含旧格式兼容，^$ 锚定 + 名称部分拒绝 /\\，
- * 天然防路径分隔符与 `..` 穿越）→ 非法 400 VALIDATION_ERROR
+ * @returns 本次是否补了一份新格式备份
+ */
+export function ensureParseableBackup(project) {
+    try {
+        let files;
+        try {
+            files = readdirSync(join(project.root, BACKUPS_DIR_NAME), { withFileTypes: true })
+                .filter((e) => e.isFile())
+                .map((e) => e.name);
+        }
+        catch {
+            return false; // 目录不存在/不可读 → 没有「有文件但无一可解析」的形态
+        }
+        if (files.length === 0)
+            return false;
+        if (files.some((f) => parseBackupFileName(f) !== null))
+            return false; // 已有可解析份 → 不动
+        writeBackup(project, { kind: "auto" });
+        return true;
+    }
+    catch (err) {
+        console.error("[backup] 命名迁移兜底备份失败:", err);
+        return false;
+    }
+}
+/**
+ * 重命名备份（POST /project/backup/rename）：**只改名称段**，时间戳/类型/设备/统计保持。
+ *
+ *
+ * 1. fileName 白名单校验：仅接受 parseBackupFileName 可解析的唯一命名格式
+ * `<YYYYMMDD-HHmmssSSS>-<自动|手动>-<设备>[-<标签>]-人物N-设定N-章N.zip`（^$ 锚定 + 设备/标签
+ * 部分拒绝 /\\，天然防路径分隔符与 `..` 穿越；旧命名不可解析 ⇒ 无从改名）→ 非法 400 VALIDATION_ERROR
  * 2. 文件不存在 → 404 VALIDATION_ERROR
  * 3. 新名称解析：请求未传 name → 清除名称段；传空串/纯空白 → 清除名称段；
  * 非空 → sanitizeBackupName 规范化（非法 → 400 VALIDATION_ERROR，文案同 writeBackup）
- * 4. 新文件名 = formatBackupFileName(parsed.time, { kind: parsed.kind, name: 新名称 })——
- * kind 不随重命名改变（auto 重命名后仍落 -a- 段、manual 仍落 -m- 段）
+ * 4. 新文件名 = formatBackupFileName(parsed.time, { kind, name: 新名称, device, stats })——
+ * kind 不随重命名改变（auto 仍是「自动」段、manual 仍是「手动」段）；**设备与统计段保持原份的值**
+ * （它们描述该备份的来源与内容，不拿当前项目状态凑）
  * 5. 幂等：新文件名 === 原文件名（如重命名为相同名称）→ 不移动文件，直接返回当前条目
  * （重新 stat 取 size；stat 失败 → 404「备份不存在」）
  * 6. **目标冲突防御（oracle P1-1）**：新文件名已存在（≠ 原文件）→ 409
- * BACKUP_TARGET_EXISTS——POSIX rename 目标存在时静默替换，可达路径：旧秒级改名后毫秒补
- * 000 撞上毫秒为 0 的自动备份、同毫秒双 manual（T-m.zip + T-m-X.zip）清名覆盖；显式拒绝
+ * BACKUP_TARGET_EXISTS——POSIX rename 目标存在时静默替换，可达路径：同毫秒双 manual
+ * （`<T>-手动-设备-A.zip` 清标签后撞上 `<T>-手动-设备.zip`）等；显式拒绝
  * 7. renameSync 同目录原子改名（失败向上抛 → 500）；改名后统一 stat 取 size
  * （改名瞬间被删等竞态 → 404「备份不存在」）
  *
@@ -230,8 +329,13 @@ export function renameBackup(project, fileName, name) {
         if (sanitized !== null)
             nextName = sanitized;
     }
-    // 3. 新文件名（时间戳与 kind 保持原备份——kind 不随重命名改变）
-    const newFileName = formatBackupFileName(parsed.time, { kind: parsed.kind, name: nextName });
+    // 3. 新文件名（时间戳/类型/设备/统计段保持原备份——重命名只改标签段）
+    const newFileName = formatBackupFileName(parsed.time, {
+        kind: parsed.kind,
+        name: nextName,
+        device: parsed.device,
+        stats: parsed.stats,
+    });
     // 4. 幂等：名称未变 → 不移动文件，返回当前条目（重新 stat 取 size；读不到 → 404）
     if (newFileName === fileName) {
         try {
@@ -241,6 +345,8 @@ export function renameBackup(project, fileName, name) {
                 createdAt: toIso(parsed.time),
                 kind: parsed.kind,
                 ...(nextName !== undefined ? { name: nextName } : {}),
+                device: parsed.device,
+                stats: parsed.stats,
             };
         }
         catch {
@@ -248,7 +354,7 @@ export function renameBackup(project, fileName, name) {
         }
     }
     // 5. 目标冲突防御（oracle P1-1）：POSIX rename 目标存在时静默替换（数据丢失风险）——
-    // 可达路径：旧秒级改名后毫秒补 000 撞上毫秒为 0 的自动备份、同毫秒双 manual 清名覆盖等；
+    // 可达路径：同毫秒双 manual（`<T>-手动-设备-A.zip` 清标签后撞上 `<T>-手动-设备.zip`）等；
     // 显式 409 拒绝。幂等分支（target === fileName）已在第 4 步提前返回，此处必然 target ≠ fileName。
     if (existsSync(join(backupsDir, newFileName))) {
         throw new HttpError(409, "BACKUP_TARGET_EXISTS", `目标备份文件名已存在: ${newFileName}`);
@@ -269,6 +375,8 @@ export function renameBackup(project, fileName, name) {
         createdAt: toIso(parsed.time),
         kind: parsed.kind,
         ...(nextName !== undefined ? { name: nextName } : {}),
+        device: parsed.device,
+        stats: parsed.stats,
     };
 }
 /**
@@ -322,6 +430,8 @@ export function listBackups(project) {
                 createdAt: toIso(parsed.time),
                 kind: parsed.kind,
                 ...(parsed.name !== undefined ? { name: parsed.name } : {}),
+                device: parsed.device,
+                stats: parsed.stats,
             };
         }
         catch {
@@ -537,15 +647,18 @@ function latestBackupTime(backupsDir) {
     return latest;
 }
 /**
- * 三文件 + data.db-wal 伴生文件是否在 since 之后有变更（「任一 mtime 晚于
- * 上次备份时刻」；F2 修订：data.db 以 WAL 模式运行，普通写事务只追加 -wal 伴生文件、
- * 主文件 mtime 不变，故 data.db-wal 一并纳入判定）：
- * 任一文件 mtime > since + 容差 → 有变更；**主文件缺失 → 视为有变更**（防御：不静默
- * 跳过，让备份管道报错暴露损坏）；**data.db-wal 缺失 ≠ 变更**（无未 checkpoint 的写，
- * 属正常状态，跳过——与主文件缺失语义不同，否则每次 tick 都误备份，产生垃圾备份）；
- * mtime 判定见 BACKUP_CHANGE_TOLERANCE_MS 注释。
+ * 三文件 + `data.db-wal` 伴生文件 + 两个打包目录，是否在 since 之后有变更
+ *（「任一 mtime 晚于上次备份时刻」）：
+ * - 三文件：任一 mtime > since + 容差 → 有变更；**主文件缺失 → 视为有变更**（防御：不静默
+ *   跳过，让备份管道报错暴露损坏）
+ * - `data.db-wal`（F2）：普通写事务只追加 `-wal`、主文件 mtime 不变；**wal 缺失 ≠ 变更**
+ *   （无未 checkpoint 的写，属正常状态，否则每次 tick 都误备份）
+ * - `references/` 与 `sessions/`：目录内**任一文件** mtime 命中，或**目录自身** mtime 命中
+ *   （F3：删除文件不刷新任何剩余文件的 mtime，只看文件会漏检删除）；目录缺失（ENOENT）
+ *   = 无文件、不算变更；其余错误防御视为有变更
+ * mtime 判定容差见 BACKUP_CHANGE_TOLERANCE_MS 注释。
  */
-function hasFileChangesSince(project, since) {
+export function hasFileChangesSince(project, since) {
     const limit = since.getTime() + BACKUP_CHANGE_TOLERANCE_MS;
     for (const name of [PROJECT_FILE_NAME, OUTLINE_FILE_NAME, DATA_DB_FILE_NAME]) {
         try {
@@ -568,11 +681,19 @@ function hasFileChangesSince(project, since) {
         if (err.code !== "ENOENT")
             return true;
     }
-    // 打包目录（references/ 与 sessions/）：内文件任一 mtime 晚于 limit → 有变更——
-    // 本地新增/外部编辑 md 文档、新增聊天会话同样触发自动备份；目录缺失 = 无文件跳过；
+    // 打包目录（references/ 与 sessions/）：目录自身或其内任一文件 mtime 晚于 limit → 有变更——
+    // 本地新增/外部编辑 md 文档、新增聊天会话、**删除文件**同样触发自动备份；
     // 遍历竞态（读取中删除）→ 防御视为无变更（下一 tick 重检）
     try {
         for (const dirName of PACKED_DIR_NAMES) {
+            try {
+                if (statSync(join(project.root, dirName)).mtimeMs > limit)
+                    return true;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    return true;
+            }
             for (const rel of listDirFiles(project.root, dirName)) {
                 if (statSync(join(project.root, dirName, rel)).mtimeMs > limit)
                     return true;
@@ -584,6 +705,120 @@ function hasFileChangesSince(project, since) {
     }
     return false;
 }
+/**
+ * mtime 变更判定内核（`hasLocalEditsSince` 与 `hasAuthoringChangesSince` 共用，避免两份漂移）：
+ * 三文件（`data.db`/`-wal` 带 `BACKUP_CHANGE_TOLERANCE_MS` 容差，其余**严格** `>`）→ 额外单文件
+ * （`scope.extraFiles`，严格；ENOENT = 该可选文件不存在，不算变更）→ `scope.dirs` 各目录
+ * （**目录自身**与其内任一文件 mtime 命中即算「有改动」——删除文件不刷新剩余文件 mtime，
+ * 只看文件会漏检删除；目录缺失 = 无文件，不算变更）。
+ *
+ * 容差只给 `data.db` 与 `-wal` 的原因：备份/推送管道内的 `wal_checkpoint` 会把其 mtime 刷到
+ * 同步时刻，严格比较会自激误判「永远有改动」；其余文件不会被管道写入，给容差反而会让
+ * 「基准后 1 秒内的改动」被长期漏判（基准是不推进的固定值，直到下次同步才前移）。
+ */
+function hasChangesSince(project, since, scope) {
+    const strictLimit = since.getTime();
+    const tolerantLimit = strictLimit + BACKUP_CHANGE_TOLERANCE_MS;
+    for (const name of [PROJECT_FILE_NAME, OUTLINE_FILE_NAME]) {
+        try {
+            if (statSync(join(project.root, name)).mtimeMs > strictLimit)
+                return true;
+        }
+        catch {
+            return true; // 主文件缺失 = 损坏，视为有改动（不静默）
+        }
+    }
+    try {
+        if (statSync(join(project.root, DATA_DB_FILE_NAME)).mtimeMs > tolerantLimit)
+            return true;
+    }
+    catch {
+        return true;
+    }
+    const walPath = join(project.root, `${DATA_DB_FILE_NAME}-wal`);
+    try {
+        if (statSync(walPath).mtimeMs > tolerantLimit)
+            return true;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            return true;
+    }
+    for (const name of scope.extraFiles ?? []) {
+        try {
+            if (statSync(join(project.root, name)).mtimeMs > strictLimit)
+                return true;
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                return true;
+        }
+    }
+    try {
+        for (const dirName of scope.dirs) {
+            try {
+                if (statSync(join(project.root, dirName)).mtimeMs > strictLimit)
+                    return true;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    return true;
+            }
+            for (const rel of listDirFiles(project.root, dirName)) {
+                if (statSync(join(project.root, dirName, rel)).mtimeMs > strictLimit)
+                    return true;
+            }
+        }
+    }
+    catch {
+        // 遍历竞态（读取中删除）：下一次状态检查重检
+    }
+    return false;
+}
+/**
+ * 「本机创作数据自 since 后有改动」判定（**云端三态专用**，与备份定时器的 `hasFileChangesSince`
+ * 口径刻意不同——见 `docs/design/40-cloud-sync.md` §3）：
+ *
+ * - `project.json` / `outline.json` / `references/` / `sessions/`（含两目录自身 mtime）：
+ *   **严格** `mtime > since`。这些文件不会被备份/同步管道写入，容差在这里只有代价：
+ *   `lastSyncAt` 是**不推进的固定基准**（只在下一次同步时前移），容差会把 `[since, since+1s]`
+ *   内的本机改动**永久漏判**（状态误报「已同步」，用户可能因此拉取覆盖它）。
+ * - `data.db` / `data.db-wal`：保留 `BACKUP_CHANGE_TOLERANCE_MS` 容差——备份/推送管道内的
+ *   `wal_checkpoint` 会把 `data.db` mtime 刷到同步时刻，严格比较会自激误判「永远有改动」。
+ */
+export function hasLocalEditsSince(project, since) {
+    return hasChangesSince(project, since, { dirs: PACKED_DIR_NAMES });
+}
+/**
+ * 「本机**创作数据**自 since 后有改动」判定（**自动推送专用**，卡 7；`docs/design/40-cloud-sync.md` §5）：
+ * 与 `hasLocalEditsSince` 同一套 mtime 口径，但 `sessions/` **不参与**（会话是聊天产物，纯聊天时段
+ * 不该单独烧一次云盘配额——聊天记录会随下一次创作变更的 zip 一起上云，zip 永远含 `sessions/`），
+ * 并**纳入 `AGENTS.md`**（项目规则也是创作数据，改规则值得推一次）。
+ */
+export function hasAuthoringChangesSince(project, since) {
+    return hasChangesSince(project, since, { dirs: [REFERENCE_DIR_NAME], extraFiles: [AGENTS_FILE_NAME] });
+}
+/**
+ * 最新一份**可解析**备份的时间（旧命名不算；无 → null）。`hasUnbackedChanges` 的基准，
+ * 也用于「升级兜底后是否已有新格式档」的判断。
+ */
+export function latestParseableBackupTime(project) {
+    return latestBackupTime(join(project.root, BACKUPS_DIR_NAME));
+}
+/**
+ * 「本机有改动未进最新备份」（卡 B，`GET /cloud/status` 的 `local.backupStale`）：
+ * 最新一份本地备份的时间早于最新创作改动（三文件 + `references/` + `sessions/`，口径同
+ * `hasLocalEditsSince`，`data.db`/`-wal` 带 1s 容差）。**没有任何可解析备份 → true**
+ *（那时推送会 404「没有可推送的备份」，语义上也是「还没有能代表当前的档」）。
+ *
+ * 用途：自动推送的守卫（有未备份改动时跳过，不做「按需备份」——备份归本地、云端只是镜像）。
+ */
+export function hasUnbackedChanges(project) {
+    const latest = latestParseableBackupTime(project);
+    if (latest === null)
+        return true;
+    return hasLocalEditsSince(project, latest);
+}
 /**
  * 自动备份单次检查（定时器 tick 核心，纯同步、可单测）：
  *
@@ -609,11 +844,22 @@ export function maybeAutoBackup(project) {
 // ============ 定时器调度（跟随当前项目生命周期，middleware setCurrentProject 挂载） ============
 /** 当前排程的定时器句柄（null = 未排程/已停止） */
 let backupTimer = null;
+/** 已注册的 tick 钩子（缺省空 = 仅备份行为，与卡 7 之前一致） */
+let tickHooks = {};
+/**
+ * 注册 tick 钩子（`middleware/project.ts` 启动时调用一次；**整体替换**，测试可注入小间隔）。
+ * 用模块级注册而不是每次 `startAutoBackup` 传参：`overwriteProjectFiles` 尾部那次重启
+ *（restore / 导入 / 云拉取后）也必须带上同一套钩子。
+ */
+export function setProjectTick(hooks) {
+    tickHooks = hooks;
+}
 /**
  * 启动/重启自动备份调度（open/切换项目时调用；restore 后频率可能变化也调用）：
- * 按当前项目频率 setTimeout 链——每 tick 检查「有变更才备份」后按最新频率重新排程
+ * 按当前项目频率 setTimeout 链——每 tick 检查「有变更才备份」后按最新间隔重新排程
  * （tick 内重读 config，restore 改变频率无需显式通知）。
- * 频率关闭（null/0/非枚举）→ 不排程（等价停止）。
+ * 频率关闭（null/0/非枚举）→ 回落到 `tickHooks.fallbackIntervalMs()`（自动推送的 2h 兜底排程）；
+ * 两者皆空 → 不排程（等价停止）。
  */
 export function startAutoBackup(project) {
     stopAutoBackup();
@@ -626,10 +872,14 @@ export function stopAutoBackup() {
         backupTimer = null;
     }
 }
-/** 按项目当前频率排程下一次检查；频率关闭 → 不排程 */
+/**
+ * 按项目当前间隔排程下一次检查：
+ * 备份频率开启 → `freq * 60_000`；关闭 → `tickHooks.fallbackIntervalMs()`（null = 不排程）。
+ */
 function scheduleNext(project) {
     const freq = resolveBackupFrequency(project.config.backup_frequency_minutes);
-    if (freq === null)
+    const intervalMs = freq === null ? (tickHooks.fallbackIntervalMs?.() ?? null) : freq * 60_000;
+    if (intervalMs === null)
         return;
     backupTimer = setTimeout(() => {
         backupTimer = null;
@@ -639,8 +889,14 @@ function scheduleNext(project) {
         catch (err) {
             console.error("[backup] 自动备份检查失败:", err);
         }
-        scheduleNext(project); // 每次 tick 重读频率（restore/切换可能改变）
-    }, freq * 60_000);
+        try {
+            tickHooks.onTick?.(project); // 钩子抛错同样不中断调度（自动推送的失败在钩子内部自记状态）
+        }
+        catch (err) {
+            console.error("[backup] 定时器钩子失败:", err);
+        }
+        scheduleNext(project); // 每次 tick 重读频率与钩子（restore/切换/云端配置可能改变）
+    }, intervalMs);
     // unref：定时器不阻止进程退出（测试/服务关闭后无残留句柄）
     backupTimer.unref?.();
 }
@@ -663,6 +919,7 @@ export function writeProjectFilesFromBackup(dir, entries, opts = {}) {
     // （校验已通过，文件内容本身有效，部分替换可经重新恢复修复）；replaced 清单供失败日志使用（P1-2）
     const targetNames = [PROJECT_FILE_NAME, OUTLINE_FILE_NAME, DATA_DB_FILE_NAME];
     const replaced = [];
+    let merged;
     try {
         const parsedProject = JSON.parse(new TextDecoder().decode(entries[PROJECT_FILE_NAME]));
         const nextProject = {
@@ -676,10 +933,21 @@ export function writeProjectFilesFromBackup(dir, entries, opts = {}) {
         replaced.push(OUTLINE_FILE_NAME);
         writeFileAtomic(join(dir, DATA_DB_FILE_NAME), entries[DATA_DB_FILE_NAME]);
         replaced.push(DATA_DB_FILE_NAME);
-        // 打包目录整体覆盖（references/ 含 .trash/、sessions/ 会话 JSONL）——
-        // 恢复/导入是「整体还原」语义，目录以备份内容为准，本地残留不混入
-        for (const dirName of PACKED_DIR_NAMES)
-            overwriteDirFromEntries(dir, dirName, entries);
+        // 打包目录（references/ 含 .trash/、sessions/ 会话 JSONL）：
+        // - 默认「整体覆盖」——恢复/导入是「整体还原」语义，目录以备份内容为准，本地残留不混入
+        // - `mergePackedDirs`（云拉取）= 与基线做三方比较的**并集合并**（删除优先，本机新增保留）
+        for (const dirName of PACKED_DIR_NAMES) {
+            if (opts.mergePackedDirs === undefined) {
+                overwriteDirFromEntries(dir, dirName, entries);
+            }
+            else {
+                const counts = mergeDirFromEntries(dir, dirName, entries, opts.mergePackedDirs.baseEntries);
+                merged = merged ?? { kept: 0, written: 0, removed: 0 };
+                merged.kept += counts.kept;
+                merged.written += counts.written;
+                merged.removed += counts.removed;
+            }
+        }
     }
     catch (err) {
         // P1-2：失败路径日志（对齐「记日志暴露部分替换」承诺）——已替换/未替换文件清单 + 覆盖前快照名
@@ -687,6 +955,7 @@ export function writeProjectFilesFromBackup(dir, entries, opts = {}) {
         console.error(`[backup] 覆盖文件替换失败（已替换: ${replaced.join(", ") || "无"}；未替换: ${notReplaced.join(", ") || "无"}${opts.snapshotFileName !== undefined ? `；覆盖前快照: ${opts.snapshotFileName}` : ""}）`, err);
         throw err;
     }
+    return merged;
 }
 /**
  * 自动迁移：project.json 存在非空 `prompt` 且项目目录无 →
@@ -739,6 +1008,7 @@ export function migratePromptToAgents(project) {
 export function overwriteProjectFiles(project, entries, opts = {}) {
     const dbPath = join(project.root, DATA_DB_FILE_NAME);
     closeDatabase(project.db); // 释放当前连接（替换 data.db 前必须；替换失败恢复见 catch）
+    let merged;
     try {
         // 清理陈旧 WAL/SHM 残留（正常关闭通常已清理；防御：替换后新库不得复用旧 WAL）
         for (const suffix of ["-wal", "-shm"]) {
@@ -750,10 +1020,11 @@ export function overwriteProjectFiles(project, entries, opts = {}) {
                     throw err;
             }
         }
-        writeProjectFilesFromBackup(project.root, entries, {
+        merged = writeProjectFilesFromBackup(project.root, entries, {
             keepId: project.config.id,
             ...(opts.name !== undefined ? { name: opts.name } : {}),
             ...(opts.snapshotFileName !== undefined ? { snapshotFileName: opts.snapshotFileName } : {}),
+            ...(opts.mergePackedDirs !== undefined ? { mergePackedDirs: opts.mergePackedDirs } : {}),
         });
         // 重连 + 版本对齐
         let active = openDatabase(dbPath);
@@ -787,6 +1058,7 @@ export function overwriteProjectFiles(project, entries, opts = {}) {
         throw err;
     }
     startAutoBackup(project); // 重启定时器（覆盖包内频率可能不同）
+    return merged;
 }
 /**
  * 为**未打开的书**生成覆盖前快照（import 覆盖书架其他书场景，「覆盖前自动快照」）：
@@ -845,10 +1117,10 @@ function writeFileAtomic(filePath, data) {
 /**
  * 从备份恢复当前项目（POST /project/backup/restore）：
  *
- * 1. fileName 白名单校验：仅允许 `.backups/` 下时间戳格式（兼容四类：
- * `<YYYYMMDD-HHmmssSSS>[-<kind>][-<名称>].zip` 毫秒级（含 kind 段）/ `<YYYYMMDD-HHmmssSSS>-<名称>.zip`
- * 旧带名称 / 旧秒级 `<YYYYMMDD-HHmmss>.zip`——shared parseBackupFileName，^$ 锚定 + 名称部分
- * 拒绝 /\\，天然防路径分隔符与 `..` 穿越）；格式合法但文件不存在 → 404
+ * 1. fileName 白名单校验：仅允许 `.backups/` 下的**唯一命名格式**
+ * `<YYYYMMDD-HHmmssSSS>-<自动|手动>-<设备>[-<标签>]-人物N-设定N-章N.zip`（shared parseBackupFileName，
+ * ^$ 锚定 + 设备/标签部分拒绝 /\\，天然防路径分隔符与 `..` 穿越；旧命名不可解析 ⇒ 一并被拒）；
+ * 格式合法但文件不存在 → 404
  * 2. **覆盖前自动快照**：当前三文件打包为快照存入 .backups/（复用备份管道，
  * 就是普通备份文件，自然参与保留策略——后悔药）
  * 3. 备份包校验（validateBackupPackage：zip/白名单//user_version 三态，
@@ -861,9 +1133,9 @@ function writeFileAtomic(filePath, data) {
  *
  * @throws HttpError 400（文件名非法/坏包）、404（备份不存在）、409 SCHEMA_VERSION_MISMATCH
  */
-export function restoreBackup(project, fileName) {
+export function restoreBackup(project, fileName, options = {}) {
     // 1. 白名单校验（assertBackupFileNameFormat：parseBackupFileName 全格式校验，防路径穿越；
-    // 兼容毫秒级/带 kind 段/旧带名称/旧秒级文件名）
+    // 旧命名不可解析 ⇒ 一并被拒）
     assertBackupFileNameFormat(fileName);
     const backupPath = join(project.root, BACKUPS_DIR_NAME, fileName);
     if (!existsSync(backupPath)) {
@@ -878,11 +1150,19 @@ export function restoreBackup(project, fileName) {
     // 重连 data.db + 同步 config + 重启定时器。
     // name 归一为当前目录名（审核裁决：与 import 覆盖一致，维持「目录名 = 书名」
     // 不变式——id 是身份、name 是展示名；改名需求走 /project/rename）
-    overwriteProjectFiles(project, entries, { name: basename(project.root), snapshotFileName: snapshot.fileName });
+    const merged = overwriteProjectFiles(project, entries, {
+        name: basename(project.root),
+        snapshotFileName: snapshot.fileName,
+        ...(options.mergePackedDirs !== undefined ? { mergePackedDirs: options.mergePackedDirs } : {}),
+    });
     // 5. 会话无归属迁移：对话历史已出库为项目目录内 `sessions/*.jsonl`（迁移 006），归属由
     // 目录表达，不再依赖 data.db 的 project_id——恢复只需覆盖三文件 + references/
     // （`sessions/` 的入包与覆盖语义由备份管道承担，见 createBackupZip / writeProjectFilesFromBackup）。
     //：snapshot 仅含 fileName/createdAt（size 属内部信息不暴露）
-    return { snapshot: { fileName: snapshot.fileName, createdAt: snapshot.createdAt } };
+    // snapshot 仅含 fileName/createdAt（size 属内部信息不暴露）；merged 仅在并集合并模式下有值
+    return {
+        snapshot: { fileName: snapshot.fileName, createdAt: snapshot.createdAt },
+        ...(merged !== undefined ? { merged } : {}),
+    };
 }
 //# sourceMappingURL=backup.js.map