cortico-world-archivist 0.0.0-stage → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.3.3 — 2026-11-05
+
+首个公开发布的版本。备份与恢复都在里面。
+
+**备份**
+
+- 按间隔自动备份（默认 24 小时），启动时若已超期立刻补一次
+- 滚动保留（默认 14 份），超出自动删最老的
+- 五项可勾：工作区全部 / 工作区 git 历史 / 工作区附件（blobs） / 扩展数据 / 配置与密钥
+- 「扩展数据」自动扫描 `data/`，装了什么扩展就备份什么，只跳过可重建的运行态与缓存
+- 额外路径补漏、可选连带扩展包
+- 打包前先复制到临时目录再压缩，避免打到写了一半的文件
+- 每份 zip 带 `MANIFEST.md`，写明内容与手工恢复步骤
+
+**恢复**
+
+- 解压到临时目录 → 校验 `MANIFEST.md` → 快照当前状态到 `before-restore-<时间>/` → 才覆盖
+- 恢复范围复用备份那份勾选
+- 需要输入确认口令 `RESTORE`（或「恢复」）才会动作，输错则一个文件都不碰
+- 恢复后等 3 秒复查：若有扩展把内存里的旧数据写回磁盘，结果里直接说明「这次恢复对它们无效，请完全退出 Coopanion 后重做」
+- 跨平台：Windows 的 `Compress-Archive` 把条目名写成 `\`，解开后就地修正为目录结构（`..` 一并过滤）
+
+**其他**
+
+- 零上下文成本：`envPromptVars()` 返回 `null`、`tools()` 返回 `[]`，不占前缀、不进工具表
+- 日志写到 `<存放位置>/archivist.log`（`WorldContext` 没有 `log` 通道，所以自己写）
+- 配置项的源 id 改名后自动迁移，缺的源按默认值补齐
+- 中英双语界面文案
+
+## 0.1.0 – 0.3.2
+
+未公开的本地迭代版本。0.3.3 之前的编号只在作者本机存在。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cortico-world-archivist contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# 备份与恢复 / Backup & Restore
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 [Coopanion](https://github.com/Pal-AI-Lab) 用的 World 扩展（包名 `cortico-world-archivist`，配置段 `worlds.archivist`）：**定期备份 + 一键恢复**。
+
+她的长期记忆散在三个地方——`workspace/`（画像、自述、日记、笔记、交接档案）、`data/*.json`（事实库、向量索引、档案、反思、画像卡）、`config.json` + `.env` + `providers/`（配置与密钥）。这个扩展把三处打成一个 zip，滚动保留若干份；要回退时从任意一份放回去。
+
+**零上下文成本**：不进系统前缀（`envPromptVars()` 返回 `null`）、不注册任何工具（`tools()` 返回 `[]`）。它只在后台跑，不吃 token。
+
+## 装
+
+```
+pnpm add cortico-world-archivist        # 或在扩展市场里装
+```
+
+装完重启 Coopanion，在「世界」页启用「归档」，再打开它的配置页。
+
+## 备份
+
+| 配置项 | 说明 |
+| --- | --- |
+| 备份间隔 | 多久一次（小时）。进程重启后会检查是否超期，超了就立刻补一次 |
+| 保留份数 | 滚动保留。超过就删最老的 |
+| 存放位置 | zip 放哪。留空 = `data/archivist/`。**建议放到另一块硬盘或网盘同步目录** |
+| 备份内容 | 五项可勾：工作区全部 / git 历史 / blobs 附件 / 扩展数据 / 配置与密钥 |
+| 连带扩展包 | 把 `extensions/` 也打包。几十 MB，一般不用 |
+| 额外要备份的路径 | 一行一个。给那些把数据放在子目录、或装在别处的扩展补漏 |
+| 立即备份一次 | 拨到开 → 一分钟内开始，做完自动关回去 |
+
+「扩展数据」是**自动扫描** `data/` 目录的：装了什么扩展就备份什么，不用手动配。只跳过明确可重建的东西（运行态 JSON、缓存、`session-main.jsonl` 这类流水，以及 `media/`、`figures/`、`emoji/` 这些几十上百 MB 的素材目录）。判定标准写在 `src/config.js` 的 `DATA_SKIP` / `DATA_SKIP_DIRS` 里，附了每一条的理由。
+
+一份真实部署（9 MB 工作区 + 13 MB 记忆数据）打包后约 **15 MB，4～5 秒**。
+
+## 恢复
+
+恢复默认**只用于灾难恢复**，所以设了两道闸：
+
+1. **确认口令**：必须先输入 `RESTORE`（或「恢复」），否则「立即恢复」开关不动。
+2. **先留存再覆盖**：恢复前把当前状态复制到 `<存放位置>/before-restore-<时间>/`，后悔了还能拿回来。
+
+流程是固定的四步，顺序不能颠倒：
+
+```
+① 解压到临时目录      —— 不碰真实数据
+② 校验 MANIFEST.md    —— 不是本扩展的包直接拒绝
+③ 快照当前状态        —— before-restore-<时间>/
+④ 才复制覆盖
+```
+
+**恢复完必须重启 Coopanion。** 记忆类扩展（如 memory-extra）把数据缓存在内存里、每 2 秒全量 flush 一次，不重启会被旧内存写回去。`workspace/*.md` 是每次现读的，会立刻生效。
+
+所以恢复完会再等 3 秒复查一遍：如果 `data/` 里的文件在恢复后立刻被改写（内容变了，不只是时间戳），说明进程正把旧数据写回磁盘，这时结果里会直接说「这次恢复对它们无效，请完全退出 Coopanion 后重新恢复」，而不是留下一个看起来成功的假象。
+
+恢复与备份共用「备份内容」那份勾选：备份时打包哪些，恢复时就放回哪些。
+
+只覆盖、不删除：备份之后新写出来的文件不会被删掉。
+
+跨平台：Windows 的 `Compress-Archive` 会把条目名写成 `data\fact-store.json`（zip 规范要求 `/`）。Windows 自己解压没问题，但拿到 macOS/Linux 上会变成一堆名字里带反斜杠的平铺文件。所以解压后会就地修正这类条目名，`..` 一并过滤掉。
+
+### 老配置自动迁移
+
+配置里的源 id 改过名（早期版本叫 `memory`，现在是 `data`）。构造时会自动改名、补齐缺的源、删掉多余的键，并写回一次配置——否则面板读到 `undefined` 会把勾选框画成「没勾」，一保存就真的把那一类数据关掉了。迁移只在真的需要时才写盘。
+
+## 日志
+
+`<存放位置>/archivist.log`，一行一条，带 ISO 时间和级别：
+
+```
+2026-11-05T10:01:24.742Z INFO  开始备份（启动补备份）
+2026-11-05T10:01:28.733Z INFO  备份完成 E:\Coopanion-Archive\archivist-2026-11-05T18-01-21.zip（15.4 MB，3960 ms）
+```
+
+和 zip 放在一起，出了问题直接把这个文件发出来就行。超过 512 KB 会截断到后一半（这不是审计日志）。
+
+`WorldContext` 没有 `log` 字段（api 6 只给 `cfg` / `botDir` / `dataDir` / `persist` 这些），所以在扩展里写 `ctx.log?.info?.(...)` 是**空转**——这也是为什么它自己写文件，而不是指望框架的日志。
+
+## 已知限制
+
+- zip 打包和解压调系统能力（Windows 用 `Compress-Archive` / `Expand-Archive`，macOS/Linux 用 `zip` / `unzip`），不引第三方依赖，所以打包时源文件被并发改写可能进包失败——这也是先复制到临时目录再压缩的原因。
+- 恢复 `config.json` 会连 `worlds.archivist` 这一段一起还原，包括当时的「存放位置」。如果你改过存放位置，恢复后它也会变回去。
+- 不做增量备份，每次都是全量。这样单份 zip 自包含，恢复时不用找链条。
+
+## 开发
+
+```
+node --check src/index.js    # 语法
+```
+
+`src/` 四个文件：`index.js`（导出 World 定义）、`world.js`（生命周期、定时器、面板开关兑现）、`config.js`（默认值 + JSON Schema 表单 + 跳过名单）、`backup.js` / `restore.js`（两个执行器）。
+
+配置表单走 `webUi().config`（纯 JSON Schema，WebUI 直接渲染），不走 `webUi().panels`——后者需要预先构建 `cortico.webUiClient` 产物。
+
+MIT。

package/describe.json

@@ -0,0 +1,4 @@
+{
+  "tools": [],
+  "events": []
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "cortico-world-archivist",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.3",
+  "type": "module",
+  "author": {
+    "name": "g_zone"
+  },
+  "description": "备份与恢复 —— 定期把她的工作区、记忆数据和配置打包成 zip，滚动保留若干份；需要时一键恢复（恢复前自动留存当前状态）。零上下文成本：不进系统前缀、不占工具表。",
+  "license": "MIT",
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "main": "./src/index.js",
+  "files": [
+    "src",
+    "describe.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "cortico-world",
+    "cortico",
+    "coopanion",
+    "backup",
+    "restore",
+    "archive"
+  ],
+  "cortico": {
+    "kind": "world",
+    "api": 6,
+    "displayName": "备份与恢复",
+    "tags": [
+      "diagnostics"
+    ],
+    "locales": {
+      "zh": {
+        "displayName": "备份与恢复",
+        "description": "定期把她的一切打包成 zip：工作区（画像/自述/日记/笔记/交接档案）、记忆数据（事实库/向量索引/档案/反思）、配置与密钥。滚动保留若干份，自动清理旧的；需要时从任意一份恢复，恢复前先给当前状态留备份。不占系统前缀，不进工具表。"
+      },
+      "en": {
+        "displayName": "Backup & Restore",
+        "description": "Zip everything about her on a schedule: workspace (persona, diary, notes, handoffs), memory data, and config. Rolling retention with automatic cleanup, plus one-click restore that snapshots the current state first. Costs no prefix space and adds no tools."
+      }
+    },
+    "describe": "describe.json"
+  }
+}

package/src/backup.js

@@ -0,0 +1,376 @@
+/**
+ * 备份执行器：把勾选的源复制到临时目录 → 打包成 zip → 轮转清理旧包。
+ *
+ * 关键设计：
+ *  - 先复制到临时目录再打包，避免打包过程中源文件被改写（如 vector-memory.json 正在写）
+ *  - 临时目录放在系统 temp，不污染她的工作区
+ *  - 用系统自带能力压缩（Windows: Compress-Archive / macOS: zip），不加第三方依赖
+ *  - 任何一步失败都清理临时目录，不留下垃圾
+ */
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { copyFile, rm, mkdir, readdir, stat } from 'node:fs/promises';
+import { join, basename, dirname, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { CONFIG_FILES, CONFIG_DIRS, DATA_SKIP, DATA_SKIP_DIRS } from './config.js';
+
+/** 递归复制目录；onError 收集单个文件的失败，不中断整体。 */
+async function copyDir(src, dest, onError) {
+  await mkdir(dest, { recursive: true });
+  let entries;
+  try {
+    entries = await readdir(src, { withFileTypes: true });
+  } catch (e) {
+    onError(`${src}: ${e.code ?? e.message}`);
+    return;
+  }
+  for (const entry of entries) {
+    const s = join(src, entry.name);
+    const d = join(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDir(s, d, onError);
+    } else if (entry.isFile()) {
+      try {
+        await copyFile(s, d);
+      } catch (e) {
+        onError(`${s}: ${e.code ?? e.message}`);
+      }
+    }
+    // 符号链接与特殊文件跳过
+  }
+}
+
+/** 复制单个文件；不存在时静默跳过。 */
+async function copyOne(src, dest, onError) {
+  if (!existsSync(src)) return false;
+  try {
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(src, dest);
+    return true;
+  } catch (e) {
+    onError(`${src}: ${e.code ?? e.message}`);
+    return false;
+  }
+}
+
+/** 调系统压缩命令。返回 { ok, detail }。 */
+function compress(stageDir, zipPath) {
+  return new Promise((done) => {
+    const isWin = process.platform === 'win32';
+    let cmd, args;
+    if (isWin) {
+      // Compress-Archive 会把 stageDir 的内容打成 zip（不含 stageDir 这层）
+      cmd = 'powershell.exe';
+      args = [
+        '-NoProfile', '-NonInteractive', '-Command',
+        `Compress-Archive -Path '${join(stageDir, '*')}' -DestinationPath '${zipPath}' -CompressionLevel Optimal -Force`,
+      ];
+    } else {
+      cmd = 'zip';
+      args = ['-r', '-q', zipPath, '.'];
+    }
+    const child = spawn(cmd, args, {
+      cwd: isWin ? undefined : stageDir,
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let err = '';
+    child.stderr?.on('data', (c) => { err += c.toString(); });
+    child.on('error', (e) => done({ ok: false, detail: `压缩失败: ${e.message}` }));
+    child.on('close', (code) => {
+      if (code === 0 && existsSync(zipPath)) done({ ok: true, detail: 'ok' });
+      else done({ ok: false, detail: `压缩退出码 ${code}: ${err.slice(0, 300)}` });
+    });
+    // 10 分钟上限
+    setTimeout(() => { child.kill(); done({ ok: false, detail: '压缩超时' }); }, 10 * 60 * 1000).unref?.();
+  });
+}
+
+/** 时间戳文件名：2026-11-05T17-44-00 */
+function stamp(now = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}T${p(now.getHours())}-${p(now.getMinutes())}-${p(now.getSeconds())}`;
+}
+
+/** 从备份文件名解析时间（用于轮转排序）。解析不出返回 0。 */
+function stampOf(name) {
+  const m = /archivist-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})/.exec(name);
+  if (!m) return 0;
+  return new Date(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]).getTime();
+}
+
+/**
+ * 执行一次备份。
+ * @param {object} opts
+ * @param {string} opts.botDir
+ * @param {string} opts.dataDir
+ * @param {object} opts.cfg         worlds.archivist 的活引用
+ * @param {(msg: string, data?: object) => void} opts.log
+ * @returns {Promise<{ok: boolean, file?: string, bytes?: number, ms?: number, detail: string}>}
+ */
+export async function runBackup({ botDir, dataDir, cfg, log }) {
+  const started = Date.now();
+  const errors = [];
+  const onError = (msg) => { errors.push(msg); if (errors.length <= 20) log(`跳过 ${msg}`); };
+
+  // ---- 决定目标目录 ----
+  const destDir = cfg.destDir?.trim() ? resolve(cfg.destDir.trim()) : join(dataDir, 'archivist');
+  try {
+    mkdirSync(destDir, { recursive: true });
+  } catch (e) {
+    return { ok: false, detail: `无法创建备份目录 ${destDir}: ${e.message}` };
+  }
+
+  // ---- 暂存目录 ----
+  const stage = join(tmpdir(), `coopanion-archivist-${randomUUID()}`);
+  await mkdir(stage, { recursive: true });
+
+  try {
+    const done = [];
+
+    // ---- 1. 工作区（workspace 主体 / .git / blobs 三个独立开关） ----
+    const wantWorkspace = cfg.sources?.workspace ?? true;
+    const wantGit = cfg.sources?.['workspace-git'] ?? false;
+    const wantBlobs = cfg.sources?.['workspace-blobs'] ?? true;
+    if (wantWorkspace || wantGit || wantBlobs) {
+      const wsSrc = join(botDir, 'workspace');
+      if (existsSync(wsSrc)) {
+        const target = join(stage, 'workspace');
+        await mkdir(target, { recursive: true });
+        const skipped = new Set();
+        if (!wantBlobs) skipped.add('blobs');
+        if (!wantGit) skipped.add('.git');
+
+        if (wantWorkspace && skipped.size === 0) {
+          // 全量：一次性复制，最快
+          await copyDir(wsSrc, target, onError);
+          done.push('workspace(全量)');
+        } else if (wantWorkspace) {
+          // 主体：复制 workspace 的子项，跳过未勾选的
+          for (const entry of await readdir(wsSrc, { withFileTypes: true }).catch(() => [])) {
+            if (skipped.has(entry.name)) continue;
+            const s = join(wsSrc, entry.name);
+            const d = join(target, entry.name);
+            if (entry.isDirectory()) await copyDir(s, d, onError);
+            else if (entry.isFile()) await copyOne(s, d, onError);
+          }
+          const label = `workspace(${skipped.size ? '不含 ' + [...skipped].join('/') : '全量'})`;
+          done.push(label);
+        } else {
+          // 不需要主体，只按勾选补 .git / blobs
+          if (wantGit) {
+            const gSrc = join(wsSrc, '.git');
+            if (existsSync(gSrc)) {
+              await copyDir(gSrc, join(target, '.git'), onError);
+              done.push('git历史');
+            }
+          }
+          if (wantBlobs) {
+            const bSrc = join(wsSrc, 'blobs');
+            if (existsSync(bSrc)) {
+              await copyDir(bSrc, join(target, 'blobs'), onError);
+              done.push('blobs');
+            }
+          }
+        }
+      } else {
+        onError(`工作区不存在: ${wsSrc}`);
+      }
+    }
+
+    // ---- 2. 扩展数据（自动扫描 data 目录，跳过可重建的临时状态）----
+    if (cfg.sources?.data ?? true) {
+      const target = join(stage, 'data');
+      await mkdir(target, { recursive: true });
+      let nFiles = 0;
+      let nDirs = 0;
+
+      let entries = [];
+      try {
+        entries = await readdir(dataDir, { withFileTypes: true });
+      } catch (e) {
+        onError(`读不了数据目录 ${dataDir}: ${e.code ?? e.message}`);
+      }
+
+      for (const entry of entries) {
+        // 跳过不需要备份的目录（venv、浏览器 profile、运行日志等）
+        if (entry.isDirectory()) {
+          if (DATA_SKIP_DIRS.has(entry.name)) continue;
+          // 其它子目录整包带走（有些扩展把数据放在自己的子目录里）
+          await copyDir(join(dataDir, entry.name), join(target, entry.name), onError);
+          nDirs++;
+          continue;
+        }
+        if (!entry.isFile()) continue;
+        // 跳过可重建的状态/缓存文件
+        if (DATA_SKIP.has(entry.name)) continue;
+        // 只收数据类文件，跳过归档产物与日志
+        if (!/\.(json|jsonl|db|sqlite|yaml|yml|txt|md)$/i.test(entry.name)) continue;
+        if (await copyOne(join(dataDir, entry.name), join(target, entry.name), onError)) nFiles++;
+      }
+
+      const parts = [];
+      if (nFiles) parts.push(`${nFiles} 个文件`);
+      if (nDirs) parts.push(`${nDirs} 个目录`);
+      if (parts.length) done.push(`扩展数据(${parts.join(' + ')})`);
+    }
+
+    // ---- 2b. 用户指定的额外路径 ----
+    const extra = String(cfg.extraPaths ?? '')
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .filter((s) => !s.startsWith('#'));
+    if (extra.length) {
+      const target = join(stage, 'extra');
+      let n = 0;
+      for (const raw of extra) {
+        const abs = resolve(botDir, raw);
+        if (!existsSync(abs)) {
+          onError(`额外路径不存在: ${raw}`);
+          continue;
+        }
+        const st = statSync(abs);
+        const name = basename(abs);
+        if (st.isDirectory()) {
+          await copyDir(abs, join(target, name), onError);
+          n++;
+        } else if (st.isFile()) {
+          if (await copyOne(abs, join(target, name), onError)) n++;
+        }
+      }
+      if (n) done.push(`额外路径(${n})`);
+    }
+
+    // ---- 3. 配置与密钥 ----
+    if (cfg.sources?.config ?? true) {
+      const target = join(stage, 'config');
+      await mkdir(target, { recursive: true });
+      let n = 0;
+      for (const f of CONFIG_FILES) {
+        if (await copyOne(join(botDir, f), join(target, f), onError)) n++;
+      }
+      for (const d of CONFIG_DIRS) {
+        const src = join(botDir, d);
+        if (existsSync(src)) {
+          await copyDir(src, join(target, d), onError);
+          n++;
+        }
+      }
+      if (n) done.push(`配置(${n}项)`);
+    }
+
+    // ---- 4. 扩展包（默认关，体积大） ----
+    if (cfg.includeExtensions) {
+      // 扩展在部署的上一级：<data>\extensions
+      const extSrc = join(dirname(botDir), '..', 'extensions');
+      const extAbs = resolve(extSrc);
+      if (existsSync(extAbs)) {
+        await copyDir(extAbs, join(stage, 'extensions'), onError);
+        done.push('extensions');
+      } else {
+        onError(`扩展目录不存在: ${extAbs}`);
+      }
+    }
+
+    if (!done.length) {
+      return { ok: false, detail: `没有可备份的内容（勾选项都没匹配到文件）` };
+    }
+
+    // ---- 5. 写一份清单 ----
+    const manifest = [
+      `# Coopanion 归档清单`,
+      ``,
+      `- 时间: ${new Date().toISOString()}`,
+      `- 主机: ${process.env.COMPUTERNAME ?? process.env.HOSTNAME ?? 'unknown'}`,
+      `- botDir: ${botDir}`,
+      `- dataDir: ${dataDir}`,
+      `- 内容: ${done.join('、')}`,
+      `- 跳过: ${errors.length} 个文件（详见日志）`,
+      ``,
+      `## 恢复方式`,
+      ``,
+      `1. 解压本 zip`,
+      `2. workspace/ → 复制回 <botDir>/workspace/`,
+      `3. data/ → 复制回 <dataDir>/（各扩展的数据文件）`,
+      `4. config/config.json → 复制回 <botDir>/config.json`,
+      `5. config/.env → 复制回 <botDir>/.env`,
+      `6. config/providers/ → 复制回 <botDir>/providers/`,
+      `7. extra/ → 按原路径放回（用户指定的额外路径）`,
+      `8. 重启 Coopanion`,
+      ``,
+      `注意：data/ 里不含体积大且可重建的运行时目录`,
+      `（fish-sing 的 venv、socialmedia 的浏览器 profile、runs 日志等）。`,
+      `恢复后扩展会在下次启动时自行重建它们。`,
+      ``,
+    ].join('\n');
+    const { writeFile } = await import('node:fs/promises');
+    await writeFile(join(stage, 'MANIFEST.md'), manifest, 'utf8');
+
+    // ---- 6. 压缩 ----
+    const zipPath = join(destDir, `archivist-${stamp()}.zip`);
+    const z = await compress(stage, zipPath);
+    if (!z.ok) return { ok: false, detail: z.detail };
+
+    const bytes = statSync(zipPath).size;
+
+    // ---- 7. 轮转 ----
+    const removed = await rotate(destDir, cfg.keepCount ?? 14, log);
+
+    const ms = Date.now() - started;
+    return {
+      ok: true,
+      file: zipPath,
+      bytes,
+      ms,
+      detail: `已备份 ${done.join('、')}${errors.length ? `，跳过 ${errors.length} 个文件` : ''}${removed ? `，清理 ${removed} 份旧包` : ''}`,
+    };
+  } catch (e) {
+    return { ok: false, detail: `备份异常: ${e.message}` };
+  } finally {
+    // 无论成败都清暂存目录
+    await rm(stage, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/** 只保留最近 keep 份，返回删除数量。 */
+async function rotate(destDir, keep, log) {
+  let files;
+  try {
+    files = readdirSync(destDir).filter((f) => /^archivist-.*\.zip$/.test(f));
+  } catch {
+    return 0;
+  }
+  if (files.length <= keep) return 0;
+  const sorted = files.map((f) => ({ f, t: stampOf(f) })).sort((a, b) => a.t - b.t);
+  const drop = sorted.slice(0, sorted.length - keep);
+  let n = 0;
+  for (const { f } of drop) {
+    try {
+      await rm(join(destDir, f), { force: true });
+      n++;
+      log(`清理旧备份 ${f}`);
+    } catch {}
+  }
+  return n;
+}
+
+/** 列出已有备份（给 WebUI / 工具用）。 */
+export function listBackups(destDir) {
+  if (!destDir) return [];
+  try {
+    return readdirSync(destDir)
+      .filter((f) => /^archivist-.*\.zip$/.test(f))
+      .map((f) => {
+        const p = join(destDir, f);
+        let bytes = 0;
+        let at = 0;
+        try { const st = statSync(p); bytes = st.size; at = st.mtimeMs; } catch {}
+        return { name: f, path: p, bytes, at };
+      })
+      .sort((a, b) => b.at - a.at);
+  } catch {
+    return [];
+  }
+}