dsh-hive-queen 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# dsh-hive-queen（蜂巢 · 蜂后）
 
-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.
+蜂巢（AI 员工族群）的"蜂后"统一插件：一个蜂后，活在微信/QQ/B站/抖音四端，共享同一份记忆与人格，带分级权限、虚拟形象、多平台直播、圆桌会议、本地服务接入与飞牛运维驾驶舱。
+
+The "Queen Bee" unified plugin of the Hive (AI employee swarm) for DeepSeek Harness: one queen living across WeChat / QQ / Bilibili / Douyin, sharing one memory and one persona, with tiered permissions, a virtual avatar, multi-platform live streaming, round-table (MoA), local service integration, and a fly-ops dashboard.
+
+- 许可 / License：MIT
+- 兼容 / Engines：DSH `^0.2.1-rc.5`，Node `>=22.5.0`
+- 借鉴 / Inspired by：[dsh-fish-soul](https://github.com/Britneycode/dsh-fish-soul)（MIT）与 [dsh-self](https://github.com/xiaoyeziyinxing/dsh-self)（MIT）
+
+## 能力清单 / Capabilities
+
+| # | 能力 | 说明 |
+|---|---|---|
+| 人格 | 人格卡（SillyTavern 兼容）+ 慢慢长 + 情绪引擎 | persona.json，跨天跨通道证据才生效 |
+| 记忆 | 按人隔离（艾宾浩斯衰减 / 可纠正 / 聊完自动记）| 一个 soul.db 四端共享 |
+| 通道 | 微信（iLink 扫码，无封号）/ QQ / B站 / 抖音 | 四端统一 |
+| 权限 | 微信/QQ=control，B站/抖音=read + 目录级可勾选 | permissions.js |
+| 服务接入 | hermes / redis / NoteDiscovery / Graphiti / Qdrant | services.js，只调用不重写 |
+| 本地客户端 | 豆包 / 元宝 / kimi / GLM / workbuddy（GUI 优先）| desktop-client.js |
+| 虚拟形象 | 外貌 / 性格 / 穿搭 / 生活 / 宠物（MiniMax 数字人）| avatar.js |
+| 直播 | 抖音/B站虚拟形象直播 + 弹幕 + 打赏（OBS 推流）| live.js |
+| UI 视觉 | 形象驱动主题（随穿搭更新，默认关）| theme.js |
+| 运维 | 驾驶舱 + 服务导航 + 飞牛运维（DDNS/反代/WAF/子域名）| flyops.js |
+
+## 安装 / Install
+
+```bash
+dsh plugin --profile desktop add dsh-hive-queen
+```
+
+（桌面版也可在「设置 → 插件」搜索安装）
+
+## 配置要点 / Configuration
+
+- **微信**：`wechat` → 扫码绑定（iLink Bot，无公众号/无封号）。
+- **QQ**：`qq` → SnowLuma（OneBot 11 正向 WS，默认 `ws://127.0.0.1:3001`）。
+- **服务**：`services` → 填 hermes/redis/NoteDiscovery/Graphiti/Qdrant 地址（留空=不启用）。
+- **权限**：`permissions` → 端级 control/read + 目录级可读/可写。
+- **形象/直播**：`avatar`（MiniMax 数字人）+ `live`（OBS 推流 + 弹幕/打赏）。
+- **飞牛运维**：`flyops` → SSH 主机/端口/账号（高权限人工授权）。
+
+## 诚实边界 / Honesty
+
+虚拟形象、情绪、生活是"识别、状态模拟、策略偏置和表达生成"，非真实主观感受，无体验连续性。AI 生成直播内容需遵守平台 AIGC 标注与直播规范。
+
+## 开发 / Development
+
+```bash
+npm install && npm run build   # 构建 lib/
+npm test                        # smoke 测试
+```
+
+fork 自 fish-soul 的结构：`lib/` 为源码（ESM），`cordis.patch.yml` 为 bundle patch。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-hive-queen bundle patch: mounts the plugin into a profile.
+# id 保持 fish-soul（与 client.js 的 settings.section id 一致，避免 slot 归属错乱）；name 是 npm 包名。
+- insert:
+    - id: hive-queen
+      name: 'dsh-hive-queen'

package/lib/attachments.js

@@ -0,0 +1,187 @@
+/**
+ * attachments.js —— QQ 附件（文件消息）处理：文本类直接读进正文，看不了的格式存到插件数据目录再报路径。
+ *
+ * 只碰白名单目录里的文件（工作区 / 插件数据目录）：路径不在里面、文件已经没了、读失败，
+ * 一律保留原来的【文件：名字】占位，不往提示词里塞来路不明的东西。
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { basename, extname, join, resolve } from 'node:path';
+import { isInside } from './gateway-util.js';
+
+/** 能直接读进提示词的扩展名。 */
+const TEXT_EXT = new Set(['.txt', '.md', '.log', '.csv', '.json']);
+/** 超过这个大小就不读（提示词放不下）。 */
+const MAX_TEXT_BYTES = 256 * 1024;
+/** 直读最多读前多少字节。 */
+const MAX_READ_BYTES = 8 * 1024;
+/** 二进制落盘单文件上限（超过就保留占位）。 */
+const MAX_BINARY_BYTES = 32 * 1024 * 1024;
+/** 正文里附件的占位（onebot.js 生成的）；用户自己打的【】会被换成〔〕，撞不上。 */
+const PLACEHOLDER_RE = /【文件[^】]*】/g;
+
+/** 附件开关：读文本 / 存二进制。 */
+export function attachmentConfig(cfg) {
+	const a = cfg?.attachments ?? {};
+	return { readText: a.readText !== false, saveBinary: a.saveBinary === true };
+}
+
+/** 文件名里不能有的字符（Windows 也不能有），顺手去掉开头的小点。 */
+function safeName(name) {
+	return String(name ?? '').replace(/[\\/:*?"<>|\u0000-\u001f]/g, '_').replace(/^\.+/, '').trim().slice(0, 60);
+}
+
+/** 读前 8KB；切在多字节字符中间会多出一个替换字符，丢掉。 */
+function readHead(abs) {
+	const buf = readFileSync(abs);
+	const truncated = buf.length > MAX_READ_BYTES;
+	const slice = buf.subarray(0, MAX_READ_BYTES);
+	// 先检测是否合法 UTF-8；非法就抛异常（调用方 catch 保留占位）
+	new TextDecoder('utf-8', { fatal: true }).decode(slice);
+	const text = slice.toString('utf8');
+	// 切在多字节字符中间会多出一个替换字符（U+FFFD），丢掉
+	const clean = text.length > 0 && text.codePointAt(text.length - 1) === 0xfffd ? text.slice(0, -1) : text;
+	return { text: clean, truncated };
+}
+
+/**
+ * fileId 路线（SnowLuma 这类不给 path 的）：get_private_file_url 换直链 → 下载 → 按扩展名读进正文或落盘。
+ * 拿不到链接 / 下载失败 / 超上限：返回 null 保留占位。
+ */
+async function handleDownload(f, ctx, meta) {
+	const { name, ext, size, label, warn } = meta;
+	const fileId = String(f?.fileId ?? '').trim();
+	const fileHash = String(f?.fileHash ?? '').trim();
+	if (typeof ctx.fetchFile !== 'function') { warn('没有文件下载通道'); return null; }
+	if (size > MAX_BINARY_BYTES) { warn('太大了，没拉'); return null; }
+	let bytes = null;
+	try {
+		bytes = await ctx.fetchFile({ fileId, fileHash, url: String(f?.url ?? '') });
+	} catch {
+		warn('下载失败');
+		return null;
+	}
+	if (bytes === null || bytes.length === 0) { warn('没拉到内容'); return null; }
+	if (bytes.length > MAX_BINARY_BYTES) { warn('太大了，没拉'); return null; }
+
+	if (TEXT_EXT.has(ext)) {
+		if (!ctx.readText) return null;
+		if (bytes.length > MAX_TEXT_BYTES) { warn('太大了，没读'); return null; }
+		const slice = bytes.subarray(0, MAX_READ_BYTES);
+		try { new TextDecoder('utf-8', { fatal: true }).decode(slice); } catch { warn('不是有效 UTF-8'); return null; }
+		const text = slice.toString('utf8');
+		const clean = text.length > 0 && text.codePointAt(text.length - 1) === 0xfffd ? text.slice(0, -1) : text;
+		ctx.read.push(label);
+		const body = bytes.length > MAX_READ_BYTES ? `${clean}\n…（内容太长，只读了前 8KB）` : clean;
+		return `【文件 ${label} 内容】\n${body}`;
+	}
+
+	if (!ctx.saveBinary) return null;
+	const dir = String(ctx.dataDir ?? '');
+	if (dir === '') { warn('没有存放目录'); return null; }
+	const base = safeName(name);
+	const dest = join(dir, `${safeName(ctx.messageId) || 'file'}-${base !== '' ? base : '附件'}`);
+	try {
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(dest, bytes);
+	} catch {
+		warn('存不下来');
+		return null;
+	}
+	ctx.saved.push(dest);
+	return `【文件 ${label}：我看不了这种格式，已存到 ${dest}】`;
+}
+
+/**
+ * 一个附件怎么处理：返回替换占位的新文本，处理不了返回 null（占位原样留着）。
+ * SnowLuma 这类不给本地 path 的：先用 fetchFile（get_private_file_url 换链接再下载）拿到 bytes 再走同一套逻辑。
+ * @param {{name?: string, path?: string, url?: string, size?: number, fileId?: string, fileHash?: string}} f
+ * @param {object} ctx
+ */
+async function handleOne(f, ctx) {
+	const name = String(f?.name ?? '').trim();
+	const rawPath = String(f?.path ?? '').trim();
+	const abs = rawPath === '' ? '' : resolve(rawPath);
+	const ext = extname(name !== '' ? name : rawPath).toLowerCase();
+	const size = Number(f?.size) || 0;
+	const label = name !== '' ? name : rawPath !== '' ? basename(rawPath) : '未命名';
+	const warn = (why) => ctx.log?.('warn', `[hive-queen] 附件没读进去（${why}）：${label}`);
+
+	// SnowLuma 路线：没有本地 path，但有 fileId——先用 OneBot API 换链接下载
+	const fileId = String(f?.fileId ?? '').trim();
+	if (abs === '' && fileId !== '') return await handleDownload(f, ctx, { name, ext, size, label, warn });
+
+	if (abs === '') { warn('没有本地路径'); return null; }
+	if (!ctx.roots.some((root) => isInside(root, abs))) { warn('路径不在允许的目录里'); return null; }
+	if (!existsSync(abs)) { warn('文件不在了'); return null; }
+
+	// P0 修复：白名单和源文件都做 realpath，防符号链接 / Windows junction 绕过
+	let realRoots;
+	try { realRoots = ctx.roots.filter((r) => { try { realpathSync.native(r); return true; } catch { return false; } }).map((r) => realpathSync.native(r)); } catch { realRoots = []; }
+	let realAbs;
+	try { realAbs = realpathSync.native(abs); } catch { warn('解析真实路径失败'); return null; }
+	if (!realRoots.some((root) => isInside(root, realAbs))) { warn('真实路径越界（符号链接/junction）'); return null; }
+
+	if (TEXT_EXT.has(ext)) {
+		if (!ctx.readText) return null; // 开关关着：跟以前一样，只留占位
+		if (size > MAX_TEXT_BYTES) { warn('太大了，没读'); return null; }
+		let st;
+		try { st = statSync(realAbs); } catch { warn('拿不到文件信息'); return null; }
+		if (!st.isFile()) { warn('不是文件'); return null; }
+		if (st.size > MAX_TEXT_BYTES) { warn('太大了，没读'); return null; }
+		let head;
+		try { head = readHead(realAbs); } catch { warn('读取失败'); return null; }
+		ctx.read.push(label);
+		const body = head.truncated ? `${head.text}\n…（内容太长，只读了前 8KB）` : head.text;
+		return `【文件 ${label} 内容】\n${body}`;
+	}
+
+	if (!ctx.saveBinary) return null; // 不存二进制：跟以前一样，只留占位
+	// P1 修复：二进制也设上限，防大文件占满磁盘
+	if (size > MAX_BINARY_BYTES) { warn('二进制太大，没存'); return null; }
+	let bst;
+	try { bst = statSync(realAbs); } catch { warn('拿不到文件信息'); return null; }
+	if (!bst.isFile()) { warn('不是普通文件'); return null; }
+	if (bst.size > MAX_BINARY_BYTES) { warn('二进制太大，没存'); return null; }
+	const dir = String(ctx.dataDir ?? '');
+	if (dir === '') { warn('没有存放目录'); return null; }
+	const base = safeName(name) !== '' ? safeName(name) : safeName(basename(realAbs));
+	const dest = join(dir, `${safeName(ctx.messageId) || 'file'}-${base !== '' ? base : '附件'}`);
+	try {
+		mkdirSync(dir, { recursive: true });
+		copyFileSync(realAbs, dest);
+	} catch {
+		warn('存不下来');
+		return null;
+	}
+	ctx.saved.push(dest);
+	return `【文件 ${label}：我看不了这种格式，已存到 ${dest}】`;
+}
+
+/**
+ * 把附件处理进消息正文：占位换成内容（或存下来的路径），处理不了的占位原样留着。
+ * @param {string} text 原正文（里面有【文件：名字】占位）
+ * @param {Array<{name?: string, path?: string, url?: string, size?: number}>} files 附件（顺序与占位一致）
+ * @param {{readText?: boolean, saveBinary?: boolean, roots?: string[], dataDir?: string, messageId?: string, log?: (level: string, msg: string) => void}} opts
+ * @returns {{text: string, read: string[], saved: string[]}} read = 读进正文的附件名，saved = 落盘的绝对路径
+ */
+export async function applyAttachments(text, files, opts = {}) {
+	const src = String(text ?? '');
+	const list = Array.isArray(files) ? files : [];
+	if (list.length === 0) return { text: src, read: [], saved: [] };
+	const marks = [...src.matchAll(PLACEHOLDER_RE)];
+	if (marks.length === 0) return { text: src, read: [], saved: [] };
+	const ctx = { readText: true, saveBinary: false, roots: [], dataDir: '', messageId: '', log: () => {}, ...opts };
+	const read = [];
+	const saved = [];
+	ctx.read = read;
+	ctx.saved = saved;
+	const repl = await Promise.all(marks.map((mark, i) => (list[i] === undefined ? null : handleOne(list[i], ctx))));
+	// 从后往前替换，前面占位的位置不受影响
+	let out = src;
+	for (let i = repl.length - 1; i >= 0; i--) {
+		if (repl[i] === null) continue;
+		const at = marks[i].index;
+		out = out.slice(0, at) + repl[i] + out.slice(at + marks[i][0].length);
+	}
+	return { text: out, read, saved };
+}

package/lib/avatar.js

@@ -0,0 +1,86 @@
+/**
+ * avatar.js —— N6 唯一虚拟形象：形象数据 + MiniMax 数字人生成 + 今日穿搭。
+ *
+ *  - 形象数据存 config（avatarId / appearance / themeColor / accentColor / outfits）。
+ *  - MiniMax 数字人 API（3.7.1 密钥）：生成形象 / 口型，端点以 MiniMax 官方文档为准。
+ *  - 诚实边界：数字人形象是生成内容，非真实人格；性格由 L1 人格卡承载，形象只是外在。
+ */
+
+/** 按今日日期在穿搭列表里确定性挑一件（同一天稳定，同 theme.outfitOfDay 逻辑）。 */
+export function outfitOfDay(outfits, dateStr, fallbackColor = '#6b7fd7') {
+	const list = Array.isArray(outfits) && outfits.length > 0 ? outfits : [{ color: fallbackColor, name: '日常' }];
+	const seed = [...String(dateStr ?? '')].reduce((a, c) => a + c.charCodeAt(0), 0);
+	return list[seed % list.length];
+}
+
+export function createAvatar({ getConfig, log, fetchImpl }) {
+	const cfg = () => getConfig()?.avatar ?? {};
+	const fetchFn = fetchImpl ?? globalThis.fetch;
+
+	return {
+		/** 当前形象（合并默认）。 */
+		current() {
+			const c = cfg();
+			return {
+				avatarId: String(c.avatarId ?? ''),
+				appearance: String(c.appearance ?? ''),
+				themeColor: String(c.themeColor ?? '#6b7fd7'),
+				accentColor: String(c.accentColor ?? '#9c6bde'),
+				outfits: Array.isArray(c.outfits) ? c.outfits : [],
+				minimaxApiKey: String(c.minimaxApiKey ?? ''),
+				minimaxGroupId: String(c.minimaxGroupId ?? ''),
+			};
+		},
+
+		/** 今日穿搭。 */
+		todayOutfit(dateStr) {
+			const c = this.current();
+			return outfitOfDay(c.outfits, dateStr, c.themeColor);
+		},
+
+		/** MiniMax 文本生成：为虚拟形象生成外貌描述与主题色（端点：chatcompletion_v2）。 */
+		async generate(prompt) {
+			const c = this.current();
+			if (!c.minimaxApiKey) return null;
+			try {
+				const res = await fetchFn('https://api.minimax.chat/v1/text/chatcompletion_v2', {
+					method: 'POST',
+					headers: { 'content-type': 'application/json', authorization: `Bearer ${c.minimaxApiKey}` },
+					body: JSON.stringify({ model: 'MiniMax-M1', messages: [{ role: 'user', content: `为虚拟形象生成外貌描述与主题色：${prompt}` }] }),
+					signal: AbortSignal.timeout(30000),
+				});
+				if (!res.ok) return null;
+				const data = await res.json();
+				return data?.choices?.[0]?.message?.content ?? null;
+			} catch (err) {
+				log?.('warn', `[hive-queen] MiniMax 形象生成失败：${String(err instanceof Error ? err.message : err)}`);
+				return null;
+			}
+		},
+
+		/** MiniMax 数字人视频生成（Talking Avatar / Lip-Sync，模型 MiniMax-H3）。返回任务 id，轮询取结果。 */
+		async videoGenerate({ prompt = '', imageUrl = '', audioUrl = '' }) {
+			const c = this.current();
+			if (!c.minimaxApiKey) return null;
+			try {
+				const res = await fetchFn('https://api.minimax.chat/v1/video_generation', {
+					method: 'POST',
+					headers: { 'content-type': 'application/json', authorization: `Bearer ${c.minimaxApiKey}` },
+					body: JSON.stringify({
+						model: 'MiniMax-H3',
+						prompt,
+						...(imageUrl ? { first_frame_image: imageUrl } : {}),
+						...(audioUrl ? { audio: audioUrl } : {}),
+					}),
+					signal: AbortSignal.timeout(30000),
+				});
+				if (!res.ok) return null;
+				const data = await res.json();
+				return data?.task_id ?? data?.id ?? null;
+			} catch (err) {
+				log?.('warn', `[hive-queen] MiniMax 数字人视频生成失败：${String(err instanceof Error ? err.message : err)}`);
+				return null;
+			}
+		},
+	};
+}

package/lib/backup.js

@@ -0,0 +1,248 @@
+/**
+ * backup.js —— soul.db 备份（v0.6）：养了半年的"她"不能因为一次误删 / 硬盘坏掉就没了。
+ *
+ *  - `VACUUM INTO` 拷一份完整、一致的库（WAL 模式下也安全，不用停插件）到 $DSH_HOME/hive-queen/backups/；
+ *  - 打开自动备份时每天一份（真实时间，插件启动 1 分钟后先看一眼），只留最近 keep 份；
+ *  - 恢复（设置页点「恢复到这份」）：先校验备份能打开、结构对、quick_check 通过，记一个 restore-pending.json；
+ *    下次插件启动、打开 soul.db 之前换上去（运行中的库被很多模块拿着，不在跑着的时候硬换）。换之前把当前的库
+ *    VACUUM INTO 另存成 backups/pre-restore-时间.db（恢复错了还能换回来，最多留 3 份），再删掉旧的 -wal / -shm。
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { hiveQueenDir, getKv, setKv } from './db.js';
+import { stampLocal as stamp } from './time-util.js';
+
+const DAY_MS = 24 * 3600_000;
+const CHECK_MS = 3600_000;
+const NAME_RE = /^soul-\d{8}-\d{6}\.db$/;
+const PRE_RE = /^pre-restore-\d{8}-\d{6}\.db$/;
+const PRE_KEEP = 3;
+const REQUIRED_TABLES = ['memory', 'person', 'kv'];
+
+function pendingPath() {
+	return join(hiveQueenDir(), 'restore-pending.json');
+}
+
+/** 等着下次启动换上去的备份（没有 = null）。 */
+export function pendingRestore() {
+	try { return JSON.parse(readFileSync(pendingPath(), 'utf8')); } catch { return null; }
+}
+
+/**
+ * 带着 -wal 的库文件（恢复前另存时库打不开、只能原样拷文件 + WAL）：把 WAL 合并回主文件、改回单文件。
+ * 合并不了（库坏了）就原样留着，恢复时连 WAL 一起拷。返回合并后还有没有 -wal。
+ */
+function consolidateWal(path) {
+	if (!existsSync(`${path}-wal`)) return false;
+	try {
+		const db = new DatabaseSync(path);
+		try {
+			db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+			db.exec('PRAGMA journal_mode = DELETE');
+		} finally { db.close(); }
+	} catch { /* 合并不了：留着 WAL */ }
+	if (existsSync(`${path}-wal`) && statSync(`${path}-wal`).size === 0) rmSync(`${path}-wal`, { force: true });
+	rmSync(`${path}-shm`, { force: true });
+	return existsSync(`${path}-wal`);
+}
+
+/** 备份文件能不能用：打得开、quick_check 通过、有记忆 / 人物 / kv 表。返回 { memories, persons }。 */
+function inspectBackup(path) {
+	consolidateWal(path);
+	const db = new DatabaseSync(path, { readOnly: true });
+	try {
+		const check = db.prepare('PRAGMA quick_check').get();
+		const ok = Object.values(check ?? {})[0];
+		if (ok !== 'ok') throw new Error(`备份文件损坏（${String(ok).slice(0, 60)}）`);
+		const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name));
+		const missing = REQUIRED_TABLES.filter((t) => !tables.has(t));
+		if (missing.length > 0) throw new Error(`不像 soul.db 的备份（缺表 ${missing.join('、')}）`);
+		return {
+			memories: db.prepare("SELECT COUNT(*) AS n FROM memory WHERE status = 'active'").get().n,
+			persons: db.prepare('SELECT COUNT(*) AS n FROM person').get().n
+		};
+	} finally {
+		db.close();
+	}
+}
+
+/**
+ * 插件启动时、openDatabase() 之前调：有待恢复的备份就换上去。
+ * @returns {{file: string, safety: string|null, at: number} | null}
+ */
+export function applyPendingRestore({ log = () => {}, nowMs = Date.now() } = {}) {
+	const pending = pendingRestore();
+	if (pending === null) return null;
+	const dir = backupDir();
+	const src = join(dir, String(pending.file ?? ''));
+	const target = join(hiveQueenDir(), 'soul.db');
+	const drop = () => rmSync(pendingPath(), { force: true });
+	if (!(NAME_RE.test(pending.file) || PRE_RE.test(pending.file)) || !existsSync(src)) {
+		log('warn', `[hive-queen] 要恢复的备份 ${pending.file} 不在了，没换`);
+		drop();
+		return null;
+	}
+	try {
+		inspectBackup(src);
+	} catch (error) {
+		log('error', `[hive-queen] 要恢复的备份 ${pending.file} 校验失败，没换：${String(error instanceof Error ? error.message : error)}`);
+		drop();
+		return null;
+	}
+	// 当前的库先另存一份（VACUUM INTO 连 WAL 里没合并的也带上；库坏到打不开就原样拷文件）
+	let safety = null;
+	if (existsSync(target)) {
+		mkdirSync(dir, { recursive: true });
+		let name = `pre-restore-${stamp(nowMs)}.db`;
+		for (let i = 1; existsSync(join(dir, name)); i++) name = `pre-restore-${stamp(nowMs + i * 1000)}.db`;
+		const out = join(dir, name);
+		try {
+			const cur = new DatabaseSync(target);
+			try { cur.exec(`VACUUM INTO '${out.replace(/'/g, "''")}'`); } finally { cur.close(); }
+		} catch {
+			copyFileSync(target, out);
+			if (existsSync(`${target}-wal`)) copyFileSync(`${target}-wal`, `${out}-wal`);
+			// 最后一次 checkpoint 之后的写入都在 WAL 里：合并进另存的那份（换回去时才不会丢）
+			consolidateWal(out);
+		}
+		safety = name;
+	}
+	const tmp = `${target}.restoring`;
+	// 要恢复的那份带着 -wal（合并不了的另存）：WAL 跟着一起换上，否则最后一次 checkpoint 之后的数据全丢
+	const srcWal = consolidateWal(src) ? `${src}-wal` : null;
+	copyFileSync(src, tmp);
+	if (srcWal) copyFileSync(srcWal, `${tmp}-wal`);
+	rmSync(`${target}-wal`, { force: true });
+	rmSync(`${target}-shm`, { force: true });
+	renameSync(tmp, target);
+	if (srcWal) renameSync(`${tmp}-wal`, `${target}-wal`);
+	drop();
+	// 恢复前的另存只留最近几份
+	try {
+		const pres = readdirSync(dir).filter((f) => PRE_RE.test(f)).sort().reverse();
+		for (const f of pres.slice(PRE_KEEP)) for (const x of [f, `${f}-wal`, `${f}-shm`]) rmSync(join(dir, x), { force: true });
+	} catch { /* 下次再删 */ }
+	log('info', `[hive-queen] 已从备份 ${pending.file} 恢复 soul.db${safety ? `（恢复前的库另存为 ${safety}）` : ''}`);
+	return { file: pending.file, safety, at: nowMs };
+}
+
+export function backupDir() {
+	return join(hiveQueenDir(), 'backups');
+}
+
+export class BackupService {
+	/**
+	 * @param {object} deps
+	 * @param {import('node:sqlite').DatabaseSync} deps.db
+	 * @param {() => {auto?: boolean, keep?: number}} deps.getConfig
+	 * @param {(level: string, msg: string) => void} [deps.log]
+	 */
+	constructor({ db, getConfig, log }) {
+		this.db = db;
+		this.getConfig = getConfig;
+		this.log = log ?? (() => {});
+		this.timer = null;
+		this.first = null;
+	}
+
+	config() {
+		const c = this.getConfig() ?? {};
+		const keep = Math.floor(Number(c.keep));
+		return { auto: c.auto !== false, keep: Number.isFinite(keep) ? Math.min(60, Math.max(1, keep)) : 7 };
+	}
+
+	start() {
+		const check = () => { try { this.maybeAuto(); } catch (error) { this.log('warn', `[hive-queen] 自动备份失败：${String(error instanceof Error ? error.message : error)}`); } };
+		this.first = setTimeout(check, 60_000);
+		this.first.unref?.();
+		this.timer = setInterval(check, CHECK_MS);
+		this.timer.unref?.();
+	}
+
+	stop() {
+		clearTimeout(this.first);
+		clearInterval(this.timer);
+		this.first = null;
+		this.timer = null;
+	}
+
+	/** 自动备份打开、且距上次备份满一天：备一份。 */
+	maybeAuto(nowMs = Date.now()) {
+		const cfg = this.config();
+		if (!cfg.auto) return null;
+		const last = Number(getKv(this.db, 'backup.lastAt', 0)) || 0;
+		if (nowMs - last < DAY_MS) return null;
+		return this.backupNow(nowMs);
+	}
+
+	/** 立刻备一份；返回 { file, path, size, at }。 */
+	backupNow(nowMs = Date.now()) {
+		const dir = backupDir();
+		mkdirSync(dir, { recursive: true });
+		let name = `soul-${stamp(nowMs)}.db`;
+		for (let i = 1; existsSync(join(dir, name)); i++) name = `soul-${stamp(nowMs + i * 1000)}.db`;
+		const path = join(dir, name);
+		// VACUUM INTO 的目标路径不能用参数绑定，只能拼字符串：路径是我们自己生成的，单引号转义一下兜底
+		this.db.exec(`VACUUM INTO '${path.replace(/'/g, "''")}'`);
+		setKv(this.db, 'backup.lastAt', nowMs);
+		this.prune();
+		const size = statSync(path).size;
+		this.log('info', `[hive-queen] 已备份 soul.db → ${path}（${Math.round(size / 1024)} KB）`);
+		return { file: name, path, size, at: nowMs };
+	}
+
+	/** 只留最近 keep 份（只动我们自己生成的 soul-YYYYMMDD-HHMMSS.db）。 */
+	prune() {
+		const { keep } = this.config();
+		const files = this.list();
+		for (const f of files.slice(keep)) {
+			try { unlinkSync(join(backupDir(), f.file)); } catch { /* 下次再删 */ }
+		}
+	}
+
+	/** 现有备份，新的在前（只是自动 / 手动备份；恢复前的另存见 preRestoreList）。 */
+	list() {
+		return this.files(NAME_RE);
+	}
+
+	preRestoreList() {
+		return this.files(PRE_RE).map((f) => ({ ...f, preRestore: true }));
+	}
+
+	files(re) {
+		const dir = backupDir();
+		if (!existsSync(dir)) return [];
+		return readdirSync(dir).filter((f) => re.test(f)).map((f) => {
+			const st = statSync(join(dir, f));
+			return { file: f, size: st.size, at: st.mtimeMs };
+		}).sort((a, b) => (a.file < b.file ? 1 : -1));
+	}
+
+	/** 选一份备份，下次启动时换上去（先校验）。 */
+	stageRestore(file) {
+		const name = String(file ?? '');
+		if (!(NAME_RE.test(name) || PRE_RE.test(name))) throw new Error('不是插件生成的备份文件');
+		const path = join(backupDir(), name);
+		if (!existsSync(path)) throw new Error('这份备份不在了');
+		const info = inspectBackup(path);
+		const pending = { file: name, at: Date.now(), ...info };
+		writeFileSync(pendingPath(), JSON.stringify(pending), 'utf8');
+		this.log('info', `[hive-queen] 已选好要恢复的备份 ${name}（${info.memories} 条记忆），重启 DSH 后换上`);
+		return pending;
+	}
+
+	cancelRestore() {
+		const had = pendingRestore() !== null;
+		rmSync(pendingPath(), { force: true });
+		return had;
+	}
+
+	state() {
+		const cfg = this.config();
+		return {
+			...cfg, dir: backupDir(), lastAt: Number(getKv(this.db, 'backup.lastAt', 0)) || null, list: this.list().slice(0, 10),
+			preRestore: this.preRestoreList(), pendingRestore: pendingRestore(), lastRestored: getKv(this.db, 'backup.restored', null)
+		};
+	}
+}