@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/recent-message-cache.ts

@@ -0,0 +1,350 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/** 最近消息缓存上限（按会话 scope 隔离） */
+const MAX_RECENT_MESSAGES_PER_ACCOUNT = 200;
+
+/** 持久化 scope 上限，避免长期运行后文件无限增长 */
+const MAX_PERSISTED_SCOPES = 1000;
+
+/** 最近消息保留 30 天，超过后按 scope 清理 */
+const CACHE_SCOPE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** debounce 写盘间隔：最后一次 remember 后等待 5s */
+const FLUSH_DEBOUNCE_MS = 5000;
+
+/** 最大延迟写盘：首条脏数据后 30s 内必须落盘，防止高频场景下 debounce 饥饿 */
+const FLUSH_MAX_DELAY_MS = 30_000;
+
+/** 持久化文件格式版本 */
+const CACHE_FILE_VERSION = 1;
+
+export type CachedInboundMessage = {
+  body: string;
+  senderId: string;
+  timestampMs: number;
+};
+
+/** 持久化文件结构 */
+type CacheFile = {
+  version: number;
+  scopes: Record<string, { msgId: string; body: string; senderId: string; ts: number }[]>;
+};
+
+type LogFn = (msg: string) => void;
+
+/** 按会话 scope 隔离的最近消息缓存：clientMsgId -> 消息正文 */
+const recentMessagesByAccount = new Map<string, Map<string, CachedInboundMessage>>();
+
+/**
+ * scope 最近活跃时间，用于持久化裁剪。
+ *
+ * 运行中新写入的消息使用当前时间，而不是消息自带 timestampMs：
+ * - timestampMs 来自平台消息时间，历史消息/测试数据可能很旧
+ * - 持久化清理关心“这个会话最近是否还在被使用”
+ */
+const scopeTouchedAt = new Map<string, number>();
+
+// ── 持久化内部状态（模块级单例，多账号共享） ──
+let initialized = false;
+let stateDirPath: string | undefined;
+let logInfo: LogFn | undefined;
+let logWarn: LogFn | undefined;
+
+// ── 写入并发控制 ──
+/** 有未刷盘的内存变更 */
+let dirty = false;
+/** 正在执行写盘 */
+let writing = false;
+/** debounce 定时器：最后一次 remember 后 FLUSH_DEBOUNCE_MS 触发 */
+let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+/** maxDelay 定时器：首次 dirty 后 FLUSH_MAX_DELAY_MS 无条件触发（防饥饿安全阀） */
+let maxDelayTimer: ReturnType<typeof setTimeout> | undefined;
+
+function resolveCacheFilePath(): string {
+  return path.join(stateDirPath!, 'channel-data', 'imwe', 'recent-message-cache.json');
+}
+
+function resolveCacheTmpPath(): string {
+  return resolveCacheFilePath() + '.tmp';
+}
+
+function getRecentMessageCache(scopeKey: string): Map<string, CachedInboundMessage> {
+  const existing = recentMessagesByAccount.get(scopeKey);
+  if (existing) return existing;
+  const created = new Map<string, CachedInboundMessage>();
+  recentMessagesByAccount.set(scopeKey, created);
+  return created;
+}
+
+function touchScope(scopeKey: string, timestampMs: number): void {
+  scopeTouchedAt.set(scopeKey, Math.max(scopeTouchedAt.get(scopeKey) ?? 0, timestampMs));
+}
+
+/**
+ * 写盘前做轻量裁剪，避免 recent-message-cache.json 随会话数无限增长。
+ *
+ * 裁剪粒度选择 scope 而不是单条消息：
+ * - 单个 scope 内已有 MAX_RECENT_MESSAGES_PER_ACCOUNT 控制消息数量
+ * - 按 scope 清理可以保留引用回复所需的局部上下文，行为更可预期
+ */
+function pruneCaches(nowMs: number): void {
+  const minTimestampMs = nowMs - CACHE_SCOPE_TTL_MS;
+  for (const [scopeKey, cache] of recentMessagesByAccount) {
+    if (cache.size === 0) {
+      recentMessagesByAccount.delete(scopeKey);
+      scopeTouchedAt.delete(scopeKey);
+      continue;
+    }
+    const latest = Math.max(...Array.from(cache.values(), (message) => message.timestampMs));
+    const touchedAt = scopeTouchedAt.get(scopeKey) ?? latest;
+    // 从旧文件恢复的 scope 没有运行期 touch 记录时，退回使用消息时间判断是否过期。
+    if (touchedAt > 0 && touchedAt < minTimestampMs) {
+      recentMessagesByAccount.delete(scopeKey);
+      scopeTouchedAt.delete(scopeKey);
+      continue;
+    }
+    if (!scopeTouchedAt.has(scopeKey)) touchScope(scopeKey, latest);
+  }
+
+  if (recentMessagesByAccount.size <= MAX_PERSISTED_SCOPES) return;
+
+  // 超过总 scope 上限时，淘汰最久未活跃的 scope，避免每次整文件写盘成本持续上升。
+  const sortedScopes = Array.from(recentMessagesByAccount.keys()).sort(
+    (a, b) => (scopeTouchedAt.get(a) ?? 0) - (scopeTouchedAt.get(b) ?? 0),
+  );
+  const removeCount = recentMessagesByAccount.size - MAX_PERSISTED_SCOPES;
+  for (const scopeKey of sortedScopes.slice(0, removeCount)) {
+    recentMessagesByAccount.delete(scopeKey);
+    scopeTouchedAt.delete(scopeKey);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 持久化：从磁盘加载
+// ─────────────────────────────────────────────────────────────────────────────
+function loadFromDisk(): void {
+  if (!stateDirPath) return;
+  const filePath = resolveCacheFilePath();
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const data = JSON.parse(raw) as CacheFile;
+    if (data.version !== CACHE_FILE_VERSION) {
+      logWarn?.(`[recent-message-cache] 缓存文件版本不匹配(v${data.version})，跳过恢复`);
+      return;
+    }
+    const scopes = data.scopes;
+    if (!scopes || typeof scopes !== 'object') return;
+    let scopeCount = 0;
+    let entryCount = 0;
+    for (const [scopeKey, entries] of Object.entries(scopes)) {
+      if (!Array.isArray(entries)) continue;
+      const cache = getRecentMessageCache(scopeKey);
+      for (const e of entries) {
+        if (e.msgId && typeof e.body === 'string') {
+          cache.set(e.msgId, {
+            body: e.body,
+            senderId: e.senderId ?? '',
+            timestampMs: e.ts ?? 0,
+          });
+          touchScope(scopeKey, e.ts ?? 0);
+          entryCount++;
+        }
+      }
+      scopeCount++;
+    }
+    logInfo?.(`[recent-message-cache] 从磁盘恢复 ${scopeCount} 个 scope，${entryCount} 条消息`);
+  } catch {
+    // 文件不存在或解析失败，使用空缓存
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 持久化：写入磁盘（原子写 tmp + rename）
+// ─────────────────────────────────────────────────────────────────────────────
+function writeToDisk(): boolean {
+  if (!stateDirPath) return true;
+  const filePath = resolveCacheFilePath();
+  const tmpPath = resolveCacheTmpPath();
+  try {
+    pruneCaches(Date.now());
+    const data: CacheFile = { version: CACHE_FILE_VERSION, scopes: {} };
+    for (const [scopeKey, cache] of recentMessagesByAccount) {
+      if (cache.size === 0) continue;
+      data.scopes[scopeKey] = Array.from(cache.entries()).map(([msgId, m]) => ({
+        msgId,
+        body: m.body,
+        senderId: m.senderId,
+        ts: m.timestampMs,
+      }));
+    }
+    const dir = path.dirname(filePath);
+    fs.mkdirSync(dir, { recursive: true });
+    // 原子写：先写 tmp 文件，再 rename，防止断电导致文件损坏
+    fs.writeFileSync(tmpPath, JSON.stringify(data), 'utf-8');
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    logWarn?.(`[recent-message-cache] 持久化失败：${String(err)}`);
+    // 清理残留 tmp 文件
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch {
+      /* ignore */
+    }
+    return false;
+  }
+  return true;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 写入并发控制：双定时器 + dirty/writing 标志
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 执行刷盘：置 writing 标志，写完后检查 dirty 自动重入 */
+function doFlush(): void {
+  writing = true;
+  dirty = false;
+  clearTimers();
+  const ok = writeToDisk();
+  writing = false;
+  // IO 失败时保留 dirty，下一次 scheduleFlush 会重试当前完整内存状态。
+  if (!ok) {
+    dirty = true;
+  }
+  // 写盘期间可能来了新数据，dirty 被重新置 true
+  if (dirty) {
+    scheduleFlush();
+  }
+}
+
+function clearTimers(): void {
+  if (debounceTimer) {
+    clearTimeout(debounceTimer);
+    debounceTimer = undefined;
+  }
+  if (maxDelayTimer) {
+    clearTimeout(maxDelayTimer);
+    maxDelayTimer = undefined;
+  }
+}
+
+/**
+ * 调度延迟刷盘。
+ *
+ * 双定时器策略：
+ *   - debounceTimer：每次 rememberRecentMessage 重置，5s 内无新消息就刷盘
+ *   - maxDelayTimer：首次 dirty 时设置，30s 后无条件刷盘（防饥饿安全阀）
+ *
+ * dirty/writing 标志：
+ *   - writing 期间新数据进来 → 只标 dirty，不重复调度
+ *   - doFlush 完成后检查 dirty → 自动重入 scheduleFlush
+ */
+function scheduleFlush(): void {
+  dirty = true;
+  // 正在写盘，不重复调度；doFlush 完成后会检查 dirty 自动重入
+  if (writing) return;
+
+  // debounce 定时器：每次重置
+  if (debounceTimer) clearTimeout(debounceTimer);
+  debounceTimer = setTimeout(() => {
+    debounceTimer = undefined;
+    doFlush();
+  }, FLUSH_DEBOUNCE_MS);
+
+  // maxDelay 定时器：只设一次（安全阀，防 debounce 饥饿）
+  if (!maxDelayTimer) {
+    maxDelayTimer = setTimeout(() => {
+      maxDelayTimer = undefined;
+      doFlush();
+    }, FLUSH_MAX_DELAY_MS);
+  }
+}
+
+// ═════════════════════════════════════════════════════════════════════════════
+// 公共 API
+// ═════════════════════════════════════════════════════════════════════════════
+
+/**
+ * 初始化缓存：设置持久化目录并从磁盘恢复已有缓存。
+ *
+ * 幂等：多账号场景下只在首次调用时执行磁盘加载，后续调用为空操作。
+ * 应在 channel.ts 的 startAccount 中调用，轮询启动之前。
+ */
+export function init(stateDir: string, options?: { logInfo?: LogFn; logWarn?: LogFn }): void {
+  if (initialized) return;
+  initialized = true;
+  stateDirPath = stateDir;
+  logInfo = options?.logInfo;
+  logWarn = options?.logWarn;
+  loadFromDisk();
+}
+
+/**
+ * 强制将所有内存缓存写入磁盘（清除所有定时器，立即刷盘）。
+ *
+ * 多账号场景下每个 stopAccount 都可安全调用：写盘是幂等的，
+ * 每次调用都会把当前完整内存状态序列化到同一个文件。
+ */
+export function forceFlushAll(): void {
+  // 正在写盘中 → 不需要重复触发，doFlush 完成后会处理 dirty
+  if (writing) {
+    dirty = true;
+    clearTimers();
+    return;
+  }
+  dirty = false;
+  clearTimers();
+  if (!writeToDisk()) {
+    // stopAccount 场景也可能遇到临时 IO 错误，保留 dirty 并交给后台定时器重试。
+    dirty = true;
+    scheduleFlush();
+  }
+}
+
+export function rememberRecentMessage(
+  scopeKey: string,
+  message: {
+    msgId: string;
+    body: string;
+    senderId: string;
+    timestampMs: number;
+  },
+): void {
+  const cache = getRecentMessageCache(scopeKey);
+  cache.set(message.msgId, {
+    body: message.body,
+    senderId: message.senderId,
+    timestampMs: message.timestampMs,
+  });
+  // 这里记录运行期活跃时间；消息自身 timestampMs 仍原样保存，用于展示/恢复语义。
+  touchScope(scopeKey, Date.now());
+  while (cache.size > MAX_RECENT_MESSAGES_PER_ACCOUNT) {
+    const oldestKey = cache.keys().next().value;
+    if (!oldestKey) break;
+    cache.delete(oldestKey);
+  }
+  if (stateDirPath) {
+    scheduleFlush();
+  }
+}
+
+export function resolveQuotedMessage(
+  scopeKey: string,
+  referenceClientMsgId: string | undefined,
+): CachedInboundMessage | undefined {
+  if (!referenceClientMsgId) return undefined;
+  return getRecentMessageCache(scopeKey).get(referenceClientMsgId);
+}
+
+/** 测试用：清空内存缓存和全部持久化状态 */
+export function clearRecentMessagesForTest(): void {
+  recentMessagesByAccount.clear();
+  scopeTouchedAt.clear();
+  clearTimers();
+  dirty = false;
+  writing = false;
+  initialized = false;
+  stateDirPath = undefined;
+  logInfo = undefined;
+  logWarn = undefined;
+}