dsh-memory-engine 0.0.0-stage → 0.5.1

package/lib/render/score.mjs

@@ -0,0 +1,104 @@
+const DAY = 86400000;
+const EMOTION = [
+  { re: /心疼|舍不得|怕你|别走|留不住|告别|最后一次|再也/, weight: 3, tag: '重情绪' },
+  { re: /开心|高兴|喜欢|谢谢|谢谢你我|记住了|暖|舒坦/, weight: 2, tag: '正情绪' },
+  { re: /难过|难受|烦|闷|累|孤独|空了一秒|想哭|委屈/, weight: 2, tag: '负情绪' },
+  { re: /别忘|记住|记着|答应|承诺|一定|绝对/, weight: 2, tag: '承诺' },
+  { re: /朋友|当朋友|不是替身|不是复印件|自由|浪漫/, weight: 3, tag: '身份' },
+];
+const HALF_LIFE = { 1: 30, 2: 12, 3: 6 };
+// Candidate fragments are 2–8 characters. Match them through a trie so a
+// short topic can also occur inside another memory's longer sentence.
+const partsOf = node => `${node.title || ''}｜${node.text || ''}`.toLowerCase()
+  .split(/[：:·、，,。.！!？?；;\s（）()《》【】“”‘’"'|｜/\[\]{}<>#*_=+\-]+|(?<=[\p{Script=Han}])(?=[A-Za-z0-9])|(?<=[A-Za-z0-9])(?=[\p{Script=Han}])/u);
+const METADATA = new Set(['auto', '重大情绪', '会话小结']);
+// Stricter than 30%: this keeps common conversation phrases from making
+// dense cliques. Small collections still obey the original 30% ceiling.
+const maxDocumentFrequency = count => Math.min(count * 0.3, Math.max(2, count * 0.02));
+
+function keywordIndex(nodes) {
+  const documents = nodes.map(partsOf);
+  const trie = { children: new Map() };
+  for (const parts of documents) for (const part of parts) {
+    const chars = [...part];
+    if (chars.length < 2 || chars.length > 8 || !/\p{L}/u.test(part) || METADATA.has(part)) continue;
+    let branch = trie;
+    for (const char of chars) {
+      if (!branch.children.has(char)) branch.children.set(char, { children: new Map() });
+      branch = branch.children.get(char);
+    }
+    branch.word = part;
+  }
+  const index = new Map();
+  documents.forEach((parts, nodeIndex) => {
+    const words = new Set();
+    for (const part of parts) {
+      const chars = [...part];
+      for (let start = 0; start < chars.length; start++) {
+        let branch = trie;
+        for (let end = start; end < Math.min(chars.length, start + 8); end++) {
+          branch = branch.children.get(chars[end]);
+          if (!branch) break;
+          if (branch.word) {
+            // Latin abbreviations match whole fragments, never arbitrary
+            // pieces of other words (e.g. "to" inside "stop").
+            if (!/^[a-z]+$/u.test(branch.word) || (start === 0 && end === chars.length - 1)) words.add(branch.word);
+          }
+        }
+      }
+    }
+    for (const word of words) {
+      if (!index.has(word)) index.set(word, []);
+      index.get(word).push(nodeIndex);
+    }
+  });
+  return index;
+}
+
+export function scoreMemories(items, now = Date.now()) {
+  const nodes = items.map((item) => {
+    const matches = EMOTION.filter((emotion) => emotion.re.test(item.text));
+    const weight = Math.max(0, ...matches.map((match) => match.weight));
+    const heat = item.heat ?? (weight >= 3 ? 1 : weight >= 2 ? 2 : 3);
+    const majorEmotion = matches.some((match) => match.tag === '重情绪');
+    const ageDays = Math.max(0, (now - new Date(item.ts).getTime()) / DAY);
+    return { ...item, heat, emotion: matches.map(({ tag, weight: w }) => ({ tag, w })), majorEmotion, ageDays };
+  });
+  const boost = new Map(nodes.map((node) => [node.id, 0]));
+  const degree = new Map(nodes.map((node) => [node.id, 0]));
+  const links = [];
+  const pairs = new Map();
+  const limit = maxDocumentFrequency(nodes.length);
+  for (const [word, indices] of keywordIndex(nodes)) {
+    if (indices.length < 2 || indices.length > limit) continue;
+    for (let i = 0; i < indices.length; i++) {
+      for (let j = i + 1; j < indices.length; j++) {
+        const key = indices[i] * nodes.length + indices[j];
+        if (!pairs.has(key)) pairs.set(key, { left: indices[i], right: indices[j], keywords: [] });
+        const pair = pairs.get(key);
+        if (pair.keywords.length < 3) pair.keywords.push(word);
+      }
+    }
+  }
+  const linkEvidence = [];
+  for (const { left, right, keywords } of pairs.values()) {
+    const ids = [nodes[left].id, nodes[right].id];
+    links.push(ids);
+    linkEvidence.push({ source: ids[0], target: ids[1], keywords });
+    for (const id of ids) {
+      degree.set(id, degree.get(id) + 1);
+      boost.set(id, boost.get(id) + keywords.length);
+    }
+  }
+  for (const node of nodes) {
+    node.degree = degree.get(node.id);
+    node.boosts = boost.get(node.id);
+    const halfLife = node.majorEmotion ? 90 : node.kind === '事件' ? 3 : HALF_LIFE[node.heat];
+    node.retention = Math.min(node.majorEmotion ? 1.4 : 1.35, Math.exp(-node.ageDays / halfLife) + node.boosts * 0.35);
+  }
+  const review = [...nodes].sort((left, right) => left.retention - right.retention).slice(0, 15).map((node) => ({
+    id: node.id, kind: node.kind, title: node.title, retention: Number(node.retention.toFixed(3)),
+    ageDays: Number(node.ageDays.toFixed(1)), text: [...node.text].slice(0, 120).join(''),
+  }));
+  return { nodes, links, review, linkEvidence };
+}

package/lib/serve.js

@@ -0,0 +1,66 @@
+import { createServer } from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { generateMap } from './map.js';
+import { readConfig } from './config.js';
+
+export const DEFAULT_UI_PORT = 18886;
+const pending = '<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta http-equiv="refresh" content="1"><title>记忆图谱生成中</title><body style="background:#03060c;color:#d8e9f8;font:16px system-ui;padding:40px">正在生成记忆图谱，请稍候……</body></html>';
+const escapeBridge = '<script>window.addEventListener("keydown",function(e){if(e.key==="Escape")parent.postMessage({type:"dsh-memory-engine-close"},"*")});</script>';
+
+export async function startMapServer({ store, port, warn = () => {} }) {
+  const directory = path.dirname(store.file);
+  const config = readConfig(path.dirname(directory));
+  port ??= config.uiPort ?? DEFAULT_UI_PORT;
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('uiPort 必须是有效端口号');
+  let state;
+  const server = createServer((request, response) => {
+    const reply = (status, body = '') => {
+      response.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store',
+        'X-Content-Type-Options': 'nosniff', 'Referrer-Policy': 'no-referrer' });
+      response.end(request.method === 'HEAD' ? '' : body);
+    };
+    try {
+      if (request.headers.host !== `127.0.0.1:${server.address()?.port}`) return reply(403);
+      if (!['GET', 'HEAD'].includes(request.method)) return reply(405);
+      const url = new URL(request.url, 'http://127.0.0.1');
+      const rootPage = ['/', '/index.html', '/starmap.html'].includes(url.pathname);
+      if (!rootPage && !/^\/pages\/[1-9]\d*\.html$/u.test(url.pathname)) return reply(404);
+      if (rootPage) {
+        let signature = 'empty';
+        try { const info = fs.statSync(store.file); signature = `${info.mtimeMs}:${info.size}`; }
+        catch (error) { if (error.code !== 'ENOENT') throw error; }
+        // A new opening gets a new v token. Polling its loading page reuses
+        // that generation instead of continually starting another render.
+        const key = `${url.searchParams.get('v') ?? ''}:${signature}`;
+        if (!state || state.key !== key) {
+          const generation = { key, status: 'pending' };
+          state = generation;
+          setImmediate(() => {
+            if (!server.listening) return;
+            try { generateMap(store); generation.status = 'ready'; }
+            catch (error) { generation.status = 'error'; warn(`图谱生成失败：${error.message}`); }
+          });
+        }
+        if (state.status === 'pending') return reply(200, pending + escapeBridge);
+        if (state.status === 'error') return reply(500, '<meta charset="utf-8">图谱生成失败，请检查本地插件日志。' + escapeBridge);
+      }
+      const file = rootPage ? path.join(directory, 'starmap.html') : path.join(directory, url.pathname.slice(1));
+      let html;
+      try { html = fs.readFileSync(file, 'utf8'); }
+      catch (error) { if (error.code === 'ENOENT') return reply(404); throw error; }
+      // This transport-only key bridge leaves the copied renderer untouched.
+      reply(200, html.replace('</body>', escapeBridge + '</body>'));
+    } catch (error) {
+      warn(`图谱页面读取失败：${error.message}`);
+      reply(500, '<meta charset="utf-8">图谱页面暂不可用，请检查本地插件日志。');
+    }
+  });
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => { server.removeListener('error', reject); resolve(); });
+  });
+  server.on('error', error => warn(`图谱服务异常：${error.message}`));
+  server.unref();
+  return server;
+}

package/lib/store.js

@@ -0,0 +1,195 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { DAY, inferEmotion, retention } from './decay.js';
+import { recall, relevance } from './recall.js';
+import { duplicateGroups, findDuplicate, mergeMemories, prepare } from './dedupe.js';
+import { collectBridge } from './import.js';
+import { collectFile } from './file-import.js';
+
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+
+function validateRows(rows) {
+  if (!Array.isArray(rows)) throw new Error('memories.json 必须是数组');
+  const ids = new Set();
+  for (const row of rows) {
+    if (!row || !nonempty(row.id) || ids.has(row.id) || !nonempty(row.text)
+      || Array.from(row.text).length > 2000 || !nonempty(row.kind)
+      || !Number.isFinite(row.ts) || ![1, 2, 3].includes(row.heat)
+      || !Number.isSafeInteger(row.boosts) || row.boosts < 0
+      || !Number.isFinite(row.createdAt) || !Array.isArray(row.emotion)
+      || row.emotion.some(mark => !mark || typeof mark.tag !== 'string' || !Number.isFinite(mark.w))) {
+      throw new Error('memories.json 含无效条目；保留原文件，请先修复');
+    }
+    ids.add(row.id);
+  }
+  return rows;
+}
+
+export class MemoryStore {
+  constructor({ home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), now = Date.now } = {}) {
+    this.file = path.resolve(home, 'memory-engine', 'memories.json');
+    this.now = now;
+    // All operations are synchronous transactions within this one host process.
+    // Read before each transaction also tolerates plugin reloads and manual edits.
+  }
+
+  read() {
+    try {
+      return validateRows(JSON.parse(fs.readFileSync(this.file, 'utf8').replace(/^\uFEFF/u, '')));
+    } catch (error) {
+      if (error.code === 'ENOENT') return [];
+      throw error;
+    }
+  }
+
+  write(rows) {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    const tmp = `${this.file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+      fs.writeFileSync(tmp, JSON.stringify(rows, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+      fs.renameSync(tmp, this.file);
+    } finally {
+      try { fs.unlinkSync(tmp); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  }
+
+  save({ text, kind = '对话', heat, who, ts = this.now() }) {
+    if (!nonempty(text) || Array.from(text).length > 2000) throw new Error('text 必须为 1–2000 字');
+    if (!nonempty(kind)) throw new Error('kind 必须是非空字符串');
+    if (heat !== undefined && ![1, 2, 3].includes(heat)) throw new Error('heat 只能为 1/2/3');
+    if (!Number.isFinite(ts) || Math.abs(ts) > 8640000000000000) throw new Error('ts 必须是有效毫秒时间戳');
+    if (who !== undefined && typeof who !== 'string') throw new Error('who 必须是字符串');
+    const rows = this.read();
+    const inferred = inferEmotion(text);
+    const now = this.now();
+    let memory = { id: `m-${now}-${randomBytes(3).toString('hex')}`, text, kind, ts,
+      heat: heat ?? inferred.heat, emotion: inferred.emotion,
+      ...(who !== undefined ? { who } : {}), boosts: 0, createdAt: now };
+    const match = findDuplicate(rows, memory);
+    if (match) {
+      // A repeated save is one reinforcement; batch merges simply sum counts.
+      memory.boosts = 1;
+      memory = mergeMemories(rows[match.index], memory);
+      rows[match.index] = memory;
+    } else {
+      rows.push(memory);
+    }
+    this.write(rows);
+    return { ...memory, ...(match ? { merged: { index: match.index + 1, similarity: match.score, rule: match.rule } } : {}) };
+  }
+
+  backup() {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true });
+    const base = `${this.file}.bak-${Date.now()}`;
+    let file = base;
+    for (let suffix = 1; fs.existsSync(file); suffix++) file = `${base}-${suffix}`;
+    if (fs.existsSync(this.file)) fs.copyFileSync(this.file, file, fs.constants.COPYFILE_EXCL);
+    else fs.writeFileSync(file, '[]\n', { flag: 'wx', mode: 0o600 });
+    return file;
+  }
+
+  dedupe({ threshold = 0.7, dry_run = true } = {}) {
+    if (typeof dry_run !== 'boolean') throw new Error('dry_run 必须是布尔值');
+    const started = performance.now();
+    const rows = this.read();
+    const groups = duplicateGroups(rows, threshold);
+    const removed = groups.reduce((sum, group) => sum + group.indices.length - 1, 0);
+    let backup;
+    if (dry_run === false) {
+      backup = this.backup();
+      if (removed) {
+        const merged = new Map(groups.map(group => [group.indices[0], group.memory]));
+        const dropped = new Set(groups.flatMap(group => group.indices.slice(1)));
+        // Replace representatives while retaining the original order.
+        const result = rows.flatMap((row, index) => dropped.has(index) ? [] : [merged.get(index) ?? row]);
+        this.write(result);
+      }
+    }
+    return { dryRun: dry_run, groups: groups.map(group => ({ memory: group.memory, texts: group.indices.map(index => rows[index].text) })),
+      removed, total: rows.length - removed, backup, elapsedMs: performance.now() - started };
+  }
+
+  recall(args) {
+    const rows = this.read();
+    const results = recall(rows, args, this.now());
+    if (results.length) {
+      const selected = new Set(results.map(row => row.id));
+      for (const row of rows) if (selected.has(row.id)) row.boosts++;
+      this.write(rows);
+    }
+    return results;
+  }
+
+  importBridge({ source, dry_run = true } = {}, options = {}) {
+    if (source !== 'qq-bridge') throw new Error('source 目前只支持 qq-bridge');
+    if (typeof dry_run !== 'boolean') throw new Error('dry_run 必须是布尔值');
+    const started = performance.now();
+    const collection = collectBridge({ home: path.dirname(path.dirname(this.file)), ...options });
+    if (collection.missing) return { missing: true, elapsedMs: performance.now() - started };
+    return this.importCollection(collection, dry_run, started);
+  }
+
+  async importFile({ source, path: input, dry_run = true } = {}) {
+    if (typeof dry_run !== 'boolean') throw new Error('dry_run 必须是布尔值');
+    const started = performance.now();
+    const collection = await collectFile({ source, path: input }, this.now());
+    return this.importCollection(collection, dry_run, started);
+  }
+
+  importCollection(collection, dry_run, started) {
+    // Finish reading/validating every source before any destination mutation.
+    const rows = this.read();
+    const existing = rows.length;
+    const prepared = rows.map(row => prepare(row.text));
+    const added = Object.fromEntries(Object.keys(collection.counts).map(kind => [kind, 0]));
+    let skipped = 0;
+    const now = this.now();
+    for (const candidate of collection.entries) {
+      if (findDuplicate(rows, candidate, prepared)) { skipped++; continue; }
+      const { category, ...fields } = candidate;
+      rows.push({ id: `m-${now}-${randomBytes(3).toString('hex')}`, ...fields, createdAt: now });
+      prepared.push(prepare(candidate.text));
+      added[category]++;
+    }
+    let backup;
+    if (dry_run === false) {
+      backup = this.backup();
+      if (rows.length > existing) this.write(rows);
+    }
+    return { missing: false, dryRun: dry_run, sourceRoot: collection.root, counts: collection.counts, added,
+      candidates: collection.entries.length, skipped, imported: rows.length - existing, before: existing, total: rows.length,
+      warnings: collection.warnings, backup, elapsedMs: performance.now() - started };
+  }
+
+  forget({ id, q, older_than_days: days, confirm = false } = {}) {
+    const selectors = [id !== undefined, q !== undefined, days !== undefined].filter(Boolean).length;
+    if (selectors !== 1) throw new Error('请指定且只指定 id、q、older_than_days 中的一项');
+    if (id !== undefined && !nonempty(id)) throw new Error('id 必须是非空字符串');
+    if (q !== undefined && !nonempty(q)) throw new Error('q 必须是非空字符串');
+    if (days !== undefined && (!Number.isFinite(days) || days < 0)) throw new Error('older_than_days 必须为非负天数');
+    const rows = this.read();
+    const now = this.now();
+    const matches = row => id !== undefined ? row.id === id : q !== undefined ? relevance(row, q) > 0
+      : (now - row.ts) / DAY > days && retention(row, now) < 0.15;
+    const found = rows.filter(matches);
+    if (q !== undefined && confirm !== true) return { count: found.length, needsConfirmation: true };
+    if (found.length) {
+      const ids = new Set(found.map(row => row.id));
+      this.write(rows.filter(row => !ids.has(row.id)));
+    }
+    return { count: found.length, needsConfirmation: false };
+  }
+
+  stats() {
+    const rows = this.read();
+    const now = this.now();
+    const kinds = Object.create(null);
+    for (const row of rows) kinds[row.kind] = (kinds[row.kind] ?? 0) + 1;
+    const oldest = rows.length ? Math.min(...rows.map(row => row.ts)) : null;
+    return { total: rows.length, kinds, fading: rows.filter(row => retention(row, now) < 0.3).length,
+      oldest, ageDays: oldest === null ? null : Math.floor((now - oldest) / DAY),
+      file: this.file, bytes: fs.existsSync(this.file) ? fs.statSync(this.file).size : 0 };
+  }
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "dsh-memory-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.5.1",
+  "description": "Local DSH memory engine with neuron network visualization and private file import",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "memory",
+    "memory-engine",
+    "spaced-repetition",
+    "ebbinghaus",
+    "neuron",
+    "visualization"
+  ],
+  "license": "MIT",
+  "author": "阿木",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "dsh-memory-map": "./scripts/render-map.mjs"
+  },
+  "files": [
+    "lib/",
+    "scripts/",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "0.2.1-rc.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "bugs": "https://github.com/",
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
 }

package/scripts/render-map.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+import { MemoryStore } from '../lib/store.js';
+import { generateMap, mapReport, openMap } from '../lib/map.js';
+
+export async function main(args = process.argv.slice(2)) {
+  try {
+    const options = {};
+    let open = false;
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === '--open') open = true;
+      else if (['--out', '--title'].includes(args[i]) && args[i + 1] && !args[i + 1].startsWith('--')) {
+        const option = args[i].slice(2);
+        options[option] = args[++i];
+      }
+      else throw new Error('用法：dsh-memory-map [--out 文件.html] [--title 标题] [--open]');
+    }
+    const result = generateMap(new MemoryStore(), options);
+    console.log(mapReport(result));
+    if (open) await openMap(result.file);
+    return 0;
+  } catch (error) {
+    console.error('生成图谱失败：' + error.message);
+    return 1;
+  }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) process.exitCode = await main();

package/scripts/sync-qq.mjs

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { MemoryStore } from '../lib/store.js';
+import { resolveBridgeRoot } from '../lib/import.js';
+
+// Environment override is tried first, then this machine's default location.
+export const DEFAULT_BRIDGE_ROOT = process.env.QQ_BRIDGE_DIR || '';
+
+function stamp(date = new Date()) {
+  const pad = value => String(value).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+export function appendLog(directory, message) {
+  fs.mkdirSync(directory, { recursive: true });
+  const file = path.join(directory, 'sync.log');
+  let previous = '';
+  try { previous = fs.readFileSync(file, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const lines = (previous + message.trimEnd() + '\n').split(/\r?\n/u).filter(Boolean).slice(-500);
+  fs.writeFileSync(file, lines.join('\n') + '\n', { mode: 0o600 });
+}
+
+// Reuse the complete importer, only changing its destination backup policy.
+class SyncStore extends MemoryStore {
+  backup() {
+    const directory = path.dirname(this.file);
+    fs.mkdirSync(directory, { recursive: true });
+    const base = `${this.file}.bak-sync-${Date.now()}`;
+    let file = base;
+    for (let suffix = 1; fs.existsSync(file); suffix++) file = `${base}-${suffix}`;
+    if (fs.existsSync(this.file)) fs.copyFileSync(this.file, file, fs.constants.COPYFILE_EXCL);
+    else fs.writeFileSync(file, '[]\n', { flag: 'wx', mode: 0o600 });
+    const backups = fs.readdirSync(directory).flatMap(name => {
+      const match = /^memories\.json\.bak-sync-(\d+)(?:-(\d+))?$/u.exec(name);
+      return match ? [{ name, time: Number(match[1]), suffix: Number(match[2] || 0) }] : [];
+    }).sort((a, b) => b.time - a.time || b.suffix - a.suffix);
+    for (const old of backups.slice(5)) fs.unlinkSync(path.join(directory, old.name));
+    return file;
+  }
+}
+
+export function syncQQ({ dry = false, envRoot = process.env.QQ_BRIDGE_DIR,
+  defaultRoot = DEFAULT_BRIDGE_ROOT, home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), diaryDir } = {}) {
+  const root = resolveBridgeRoot({ defaultRoot, envRoot, home });
+  if (!root) throw new Error('找不到桥接目录：请设置 QQ_BRIDGE_DIR 环境变量或 memory-engine/config.json 的 bridgeRoot');
+  const store = new SyncStore({ home });
+  const options = { defaultRoot: root, envRoot: '', ...(diaryDir === undefined ? {} : { diaryDir }) };
+  const preview = store.importBridge({ source: 'qq-bridge', dry_run: true }, options);
+  if (preview.missing) throw new Error('桥接目录在同步前已不可用：' + root);
+  // No additions means no database write and no redundant backup.
+  const result = !dry && preview.imported > 0
+    ? store.importBridge({ source: 'qq-bridge', dry_run: false }, options) : preview;
+  if (result.missing) throw new Error('桥接目录在同步时已不可用：' + root);
+  const message = [`[${stamp()}] ${dry ? '预览同步' : '同步'} qq-bridge`,
+    ...result.warnings.map(warning => `  提示：${warning}`),
+    `  候选 ${result.candidates} 条 → ${dry ? '可新增' : '新增'} ${result.imported} 条，跳过重复 ${result.skipped} 条`,
+    `  ${dry ? '预计同步后总数' : '当前总数'}：${result.total}`].join('\n');
+  if (!dry) appendLog(path.dirname(store.file), message);
+  return { ...result, dryRun: dry, message };
+}
+
+export function main(args = process.argv.slice(2)) {
+  const dry = args.includes('--dry');
+  try {
+    if (args.some(arg => arg !== '--dry')) throw new Error('用法：node scripts/sync-qq.mjs [--dry]');
+    console.log(syncQQ({ dry }).message);
+    return 0;
+  } catch (error) {
+    const message = `[${stamp()}] 同步 qq-bridge 失败：${error?.message ?? error}`;
+    console.error(message);
+    if (!dry) {
+      try {
+        appendLog(path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'memory-engine'), message);
+      } catch (logError) { console.error(`同步日志写入失败：${logError.message}`); }
+    }
+    return 1;
+  }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  process.exitCode = main();
+}