@jerryliang122/openclaw-qqbot 1.0.0

package/src/features/quota-manager.ts

@@ -0,0 +1,173 @@
+/**
+ * QQBot 被动回复配额管理
+ *
+ * C2C: 4 次/msg_id, 60 分钟
+ * Group: 5 次/msg_id, 5 分钟
+ *
+ * 重要说明：
+ * - QQ Bot 平台的 msg_id 有时效性限制（C2C: 60分钟，Group: 5分钟）
+ * - 过期后的 msg_id 不能再用于被动回复（API 会返回错误 40034128）
+ * - 这是平台限制，不是"配额恢复"
+ * - 因此 checkPassiveReplyQuota 在 msg_id 过期时返回 false，而非重置配额
+ *
+ * 使用方式：
+ * 1. 推荐：使用 checkAndConsumePassiveReplyQuota 进行原子操作（失败用 rollback 回滚）
+ * 2. 纯探测（不消耗配额）：checkPassiveReplyQuota
+ */
+
+import type { QuotaState, QuotaCheckParams } from '../types-plugin.js';
+
+const quotaCache = new Map<string, QuotaState>();
+const MAX_CACHE_SIZE = 10000;
+
+const QUOTA_LIMITS = {
+  c2c: { count: 4, ttlMs: 60 * 60 * 1000 },
+  group: { count: 5, ttlMs: 5 * 60 * 1000 },
+};
+
+/**
+ * 检查被动回复配额（纯探测，不消耗配额）。
+ * 需要同时消耗配额时使用 checkAndConsumePassiveReplyQuota。
+ */
+export function checkPassiveReplyQuota(params: QuotaCheckParams): boolean {
+  const { accountId, msgId, scope } = params;
+
+  if (!msgId) {
+    return false;
+  }
+
+  const key = `${accountId}:${scope}:${msgId}`;
+  const now = Date.now();
+
+  const cached = quotaCache.get(key);
+  if (cached) {
+    // msg_id 过期后不能再用于被动回复
+    // 这是 QQ Bot 平台限制，API 会返回错误 40034128
+    if (now > cached.expiresAt) {
+      quotaCache.delete(key);
+      return false;
+    }
+
+    const limit = QUOTA_LIMITS[scope].count;
+    if (cached.count >= limit) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * 回滚被动回复配额（API 调用失败时使用）
+ */
+export function rollbackPassiveReplyQuota(params: {
+  accountId: string;
+  msgId: string;
+  scope: 'c2c' | 'group';
+}): void {
+  const { accountId, msgId, scope } = params;
+  const key = `${accountId}:${scope}:${msgId}`;
+
+  const cached = quotaCache.get(key);
+  if (cached && cached.count > 0) {
+    cached.count -= 1;
+    quotaCache.set(key, cached);
+  }
+}
+
+/**
+ * 原子操作：检查并消耗被动回复配额
+ * 推荐使用此函数，避免 check-then-consume 竞态
+ */
+export function checkAndConsumePassiveReplyQuota(
+  params: QuotaCheckParams & { log?: { debug?: (message: string) => void } },
+): { canReply: boolean; rollback: () => void } {
+  const { accountId, msgId, scope, log } = params;
+
+  if (!msgId) {
+    return { canReply: false, rollback: () => {} };
+  }
+
+  const key = `${accountId}:${scope}:${msgId}`;
+  const now = Date.now();
+  const ttl = QUOTA_LIMITS[scope].ttlMs;
+
+  let cached = quotaCache.get(key);
+  
+  // 检查过期：msg_id 过期后不能用于被动回复
+  // 这是 QQ Bot 平台限制，API 会返回错误 40034128
+  if (cached && now > cached.expiresAt) {
+    // msg_id 已过期，不能用于被动回复
+    return { canReply: false, rollback: () => {} };
+  }
+
+  // 检查配额
+  const limit = QUOTA_LIMITS[scope].count;
+  if (cached && cached.count >= limit) {
+    return { canReply: false, rollback: () => {} };
+  }
+
+  // 原子消耗
+  cached = cached || { count: 0, expiresAt: now + ttl };
+  cached.count += 1;
+  quotaCache.set(key, cached);
+
+  // 缓存大小控制
+  if (quotaCache.size > MAX_CACHE_SIZE) {
+    const oldestKey = quotaCache.keys().next().value;
+    if (oldestKey) {
+      quotaCache.delete(oldestKey);
+    }
+  }
+
+  log?.debug?.(`[${accountId}] consumed passive quota: ${key} count=${cached.count}`);
+
+  // 返回回滚函数
+  const rollback = () => {
+    const state = quotaCache.get(key);
+    if (state && state.count > 0) {
+      state.count -= 1;
+      quotaCache.set(key, state);
+    }
+  };
+
+  return { canReply: true, rollback };
+}
+
+export function inferQQBotScope(to: string): 'c2c' | 'group' {
+  const parts = to.split(':');
+  const scope = parts[1];
+  return scope === 'group' ? 'group' : 'c2c';
+}
+
+export function clearQuotaCache(): void {
+  quotaCache.clear();
+}
+
+export function clearQuotaCacheForAccount(accountId: string): void {
+  const prefix = `${accountId}:`;
+  for (const key of quotaCache.keys()) {
+    if (key.startsWith(prefix)) quotaCache.delete(key);
+  }
+}
+
+export function getQuotaStats(accountId: string, scope: 'c2c' | 'group'): {
+  activeSessions: number;
+  totalUsage: number;
+} {
+  let activeSessions = 0;
+  let totalUsage = 0;
+
+  for (const [key, state] of quotaCache.entries()) {
+    if (key.startsWith(`${accountId}:${scope}:`)) {
+      activeSessions += 1;
+      totalUsage += state.count;
+    }
+  }
+
+  return { activeSessions, totalUsage };
+}
+
+export function __test_getQuotaCache(): Map<string, QuotaState> {
+  return quotaCache;
+}

package/src/features/ref-index-store.ts

@@ -0,0 +1,289 @@
+/**
+ * 持久化 RefIndex 存储
+ *
+ * SDK 提供的 MemoryRefIndexStore 在进程重启后即丢失，
+ * 而 QQ 引用消息（REFIDX_xxx）入站事件只携带 key，必须本地缓存才能回查。
+ *
+ * 设计：
+ *   - 内存 LRU（与 SDK 同款）保证 O(1) 读取
+ *   - JSONL 追加写持久化，进程重启时按时间顺序回放重建 LRU
+ *   - 写入触发 compact 阈值时重写文件（去重 + 截断到 maxEntries）
+ *   - 文件路径: ~/.openclaw/qqbot/data/ref-index.jsonl
+ *
+ * 实现 SDK 的 RefIndexStore 接口，可直接通过 `quoteRef({ store })` 注入。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RefEntry, RefIndexStore } from '@tencent-connect/qqbot-nodejs';
+import { getQQBotDataDir } from '../utils/platform.js';
+import { createPluginLogger, type PluginLogger } from '../utils/plugin-logger.js';
+
+// 惰性初始化：plugin-logger → runtime → 本模块 → plugin-logger 存在循环导入，
+// 顶层直接 createPluginLogger 会在部分求值顺序下踩到未初始化的 tsx helper
+// （__name is not a function，2026-09-09 群聊架构改造触发）。首次使用时再建。
+let _log: PluginLogger | undefined;
+function log(): PluginLogger {
+  return (_log ??= createPluginLogger({ prefix: '[ref-index]' }));
+}
+
+
+// ── 常量 ──
+
+const DEFAULT_MAX_ENTRIES = 50000;
+const DEFAULT_FILENAME = 'ref-index.jsonl';
+/** 当磁盘 line 数超过 maxEntries * COMPACT_RATIO 时触发 compact */
+const COMPACT_RATIO = 2;
+/** 内存 LRU 的最小容量保护值 */
+const MIN_MAX_ENTRIES = 100;
+
+// ── 磁盘行结构 ──
+
+interface DiskLine {
+  /** RefIndex 键，例如 REFIDX_xxx 或 messageId */
+  k: string;
+  /** RefEntry 内容 */
+  v: RefEntry;
+  /** 写入时间戳（毫秒） */
+  t: number;
+}
+
+// ── 持久化 Store ──
+
+export interface PersistedRefIndexStoreOptions {
+  /** 内存与磁盘的最大条目数。默认 2000。 */
+  maxEntries?: number;
+  /** 自定义存储文件路径。默认 ~/.openclaw/qqbot/data/ref-index.jsonl */
+  filePath?: string;
+}
+
+/**
+ * 持久化版本的 RefIndexStore
+ *
+ * - get：仅查内存（启动时从磁盘回放重建）
+ * - set：内存 + JSONL 追加写；磁盘行数过多时触发 compact
+ */
+export class PersistedRefIndexStore implements RefIndexStore {
+  private readonly memory = new Map<string, RefEntry>();
+  private readonly maxEntries: number;
+  private readonly filePath: string;
+  /** 当前磁盘累计写入的行数（用于 compact 阈值判断） */
+  private diskLineCount = 0;
+  /** 是否已成功初始化（磁盘回放完成） */
+  private initialized = false;
+  /** 串行化写入，防止并发 append 撕裂行 */
+  private writeChain: Promise<void> = Promise.resolve();
+
+  constructor(options: PersistedRefIndexStoreOptions = {}) {
+    this.maxEntries = Math.max(options.maxEntries ?? DEFAULT_MAX_ENTRIES, MIN_MAX_ENTRIES);
+    this.filePath = options.filePath ?? path.join(getQQBotDataDir('data'), DEFAULT_FILENAME);
+    this.init();
+  }
+
+  /**
+   * 初始化：按时间顺序回放 JSONL 重建内存 LRU
+   */
+  private init(): void {
+    try {
+      if (!fs.existsSync(this.filePath)) {
+        this.initialized = true;
+        return;
+      }
+      const raw = fs.readFileSync(this.filePath, 'utf8');
+      const lines = raw.split('\n').filter((l) => l.length > 0);
+      this.diskLineCount = lines.length;
+
+      // 按时间排序回放（防止文件被外部修改后乱序）
+      const parsed: DiskLine[] = [];
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line) as DiskLine;
+          if (obj?.k && obj?.v) {
+            parsed.push(obj);
+          }
+        } catch {
+          // 跳过损坏行
+        }
+      }
+      parsed.sort((a, b) => a.t - b.t);
+
+      for (const { k, v } of parsed) {
+        this.touchMemory(k, v);
+      }
+
+      // 启动时若磁盘行数已超阈值，立刻 compact 一次
+      if (this.diskLineCount > this.maxEntries * COMPACT_RATIO) {
+        this.compactSync();
+      }
+    } catch (err) {
+      log().error(
+        `init failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      this.initialized = true;
+    }
+  }
+
+  // ── RefIndexStore 接口 ──
+
+  get(key: string): RefEntry | undefined {
+    return this.memory.get(key);
+  }
+
+  set(key: string, entry: RefEntry): void {
+    this.touchMemory(key, entry);
+    // 追加写持久化（串行化）
+    this.writeChain = this.writeChain.then(() => this.appendToDisk(key, entry));
+  }
+
+  // ── 内部：内存 LRU 维护 ──
+
+  private touchMemory(key: string, entry: RefEntry): void {
+    // 已存在则先删除再插入，保证插入顺序 = LRU 顺序
+    if (this.memory.has(key)) {
+      this.memory.delete(key);
+    } else if (this.memory.size >= this.maxEntries) {
+      // 容量已满 → 淘汰最旧的（Map 的迭代顺序即插入顺序）
+      const oldest = this.memory.keys().next().value;
+      if (oldest !== undefined) {
+        this.memory.delete(oldest);
+      }
+    }
+    this.memory.set(key, entry);
+  }
+
+  // ── 内部：磁盘追加 + compact ──
+
+  private async appendToDisk(key: string, entry: RefEntry): Promise<void> {
+    const line: DiskLine = { k: key, v: entry, t: Date.now() };
+    const text = JSON.stringify(line) + '\n';
+    try {
+      await fs.promises.appendFile(this.filePath, text, 'utf8');
+      this.diskLineCount += 1;
+      if (this.diskLineCount > this.maxEntries * COMPACT_RATIO) {
+        await this.compact();
+      }
+    } catch (err) {
+      log().error(
+        `append failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /**
+   * 异步 compact：将内存 LRU 状态完整重写到磁盘，丢弃历史冗余。
+   */
+  private async compact(): Promise<void> {
+    const tmpPath = `${this.filePath}.tmp`;
+    try {
+      const now = Date.now();
+      // Map 迭代顺序 = 插入顺序（旧 → 新），保持 LRU 顺序
+      const lines: string[] = [];
+      for (const [k, v] of this.memory.entries()) {
+        lines.push(JSON.stringify({ k, v, t: now } satisfies DiskLine));
+      }
+      const content = lines.length > 0 ? lines.join('\n') + '\n' : '';
+      await fs.promises.writeFile(tmpPath, content, 'utf8');
+      await fs.promises.rename(tmpPath, this.filePath);
+      this.diskLineCount = lines.length;
+      log().info(
+        `compacted to ${lines.length} entries`,
+      );
+    } catch (err) {
+      log().error(
+        `compact failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      // 清理可能残留的 tmp 文件
+      try {
+        await fs.promises.unlink(tmpPath);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * 同步 compact（仅 init 阶段使用，避免回放后立刻保留巨大磁盘文件）
+   */
+  private compactSync(): void {
+    const tmpPath = `${this.filePath}.tmp`;
+    try {
+      const now = Date.now();
+      const lines: string[] = [];
+      for (const [k, v] of this.memory.entries()) {
+        lines.push(JSON.stringify({ k, v, t: now } satisfies DiskLine));
+      }
+      const content = lines.length > 0 ? lines.join('\n') + '\n' : '';
+      fs.writeFileSync(tmpPath, content, 'utf8');
+      fs.renameSync(tmpPath, this.filePath);
+      this.diskLineCount = lines.length;
+    } catch (err) {
+      log().error(
+        `compactSync failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // ── 诊断 ──
+
+  /** 当前内存中的条目数 */
+  get size(): number {
+    return this.memory.size;
+  }
+
+  /** 是否已完成初始化（磁盘回放） */
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /** 诊断快照 */
+  stats(): {
+    memoryEntries: number;
+    diskLines: number;
+    maxEntries: number;
+    filePath: string;
+  } {
+    return {
+      memoryEntries: this.memory.size,
+      diskLines: this.diskLineCount,
+      maxEntries: this.maxEntries,
+      filePath: this.filePath,
+    };
+  }
+
+  /**
+   * 强制将当前内存状态持久化到磁盘（进程退出前调用）
+   */
+  flush(): void {
+    this.compactSync();
+  }
+}
+
+// ── 默认单例（按 accountId 隔离） ──
+
+const stores = new Map<string, PersistedRefIndexStore>();
+
+/**
+ * 获取按 accountId 隔离的持久化 RefIndexStore 单例。
+ *
+ * 每个账户独立存储文件，避免多账户混用同一个 refIdx 命名空间。
+ */
+
+export function getPersistedRefIndexStore(accountId: string): PersistedRefIndexStore {
+  let store = stores.get(accountId);
+  if (!store) {
+    const filePath = path.join(getQQBotDataDir('data', accountId), DEFAULT_FILENAME);
+    store = new PersistedRefIndexStore({ filePath });
+    stores.set(accountId, store);
+  }
+  return store;
+}
+
+/**
+ * 进程退出前 flush 所有 store
+ */
+export function flushAllRefIndexStores(): void {
+  for (const store of stores.values()) {
+    store.flush();
+  }
+}

package/src/features/secret-input-store.ts

@@ -0,0 +1,118 @@
+/**
+ * 密钥输入 pending 状态机
+ *
+ * qqbot_secret_input 工具发卡时登记，secretCapture 中间件消费。
+ * 与 multi-question 暂存（question-helpers.ts）同款模式：模块级 Map +
+ * TTL setTimeout(unref) 清理。
+ *
+ * key 绑定 `accountId + c2c senderOpenid` —— pending 天然 per-user：
+ * 只有发起密钥输入的同一私聊用户的消息会被捕获，群聊不参与。
+ */
+import type { SecretStoreKind } from './secret-store-cli.js';
+
+export const DEFAULT_SECRET_INPUT_TTL_MS = 10 * 60 * 1000;
+
+export interface PendingSecretInput {
+  accountId: string;
+  senderOpenid: string;
+  /** 环境变量名（已通过 isValidSecretName 校验） */
+  name: string;
+  /** 已判定写入方式 */
+  kind: SecretStoreKind;
+  /** 用途说明（展示在卡片上，可选） */
+  description?: string;
+  createdAt: number;
+  expiresAtMs: number;
+}
+
+interface StoredPendingSecretInput extends PendingSecretInput {
+  cleanupTimer: ReturnType<typeof setTimeout>;
+}
+
+const pendingSecretInputs = new Map<string, StoredPendingSecretInput>();
+
+export function secretInputKey(accountId: string, senderOpenid: string): string {
+  return `${accountId}:c2c:${senderOpenid}`;
+}
+
+/**
+ * 登记一次密钥输入等待。必须在发送卡片之前调用（避免「先发后登」竞态）。
+ * 同一用户重复发起直接覆盖旧条目（并清理旧 timer）。
+ */
+export function registerPendingSecretInput(
+  entry: Omit<PendingSecretInput, 'expiresAtMs'>,
+  ttlMs: number = DEFAULT_SECRET_INPUT_TTL_MS,
+): void {
+  const key = secretInputKey(entry.accountId, entry.senderOpenid);
+  const existing = pendingSecretInputs.get(key);
+  if (existing) clearTimeout(existing.cleanupTimer);
+
+  const stored: StoredPendingSecretInput = {
+    ...entry,
+    expiresAtMs: Date.now() + ttlMs,
+    cleanupTimer: setTimeout(() => {
+      if (pendingSecretInputs.get(key) === stored) {
+        pendingSecretInputs.delete(key);
+      }
+    }, ttlMs),
+  };
+  stored.cleanupTimer.unref?.();
+  pendingSecretInputs.set(key, stored);
+}
+
+function lookup(accountId: string, senderOpenid: string): StoredPendingSecretInput | undefined {
+  const key = secretInputKey(accountId, senderOpenid);
+  const entry = pendingSecretInputs.get(key);
+  if (!entry) return undefined;
+  if (entry.expiresAtMs <= Date.now()) {
+    clearTimeout(entry.cleanupTimer);
+    pendingSecretInputs.delete(key);
+    return undefined;
+  }
+  return entry;
+}
+
+/** 查询进行中的密钥输入（过期条目惰性清除），不消费 */
+export function findPendingSecretInput(
+  accountId: string,
+  senderOpenid: string,
+): PendingSecretInput | undefined {
+  const entry = lookup(accountId, senderOpenid);
+  if (!entry) return undefined;
+  const { cleanupTimer: _timer, ...rest } = entry;
+  return rest;
+}
+
+/** 一次性消费：取出并删除（防同一条 pending 被处理两次） */
+export function takePendingSecretInput(
+  accountId: string,
+  senderOpenid: string,
+): PendingSecretInput | undefined {
+  const entry = lookup(accountId, senderOpenid);
+  if (!entry) return undefined;
+  clearTimeout(entry.cleanupTimer);
+  pendingSecretInputs.delete(secretInputKey(accountId, senderOpenid));
+  const { cleanupTimer: _timer, ...rest } = entry;
+  return rest;
+}
+
+/** 主动取消（用户发送「取消」/ 发卡失败回滚） */
+export function cancelPendingSecretInput(accountId: string, senderOpenid: string): boolean {
+  const key = secretInputKey(accountId, senderOpenid);
+  const entry = pendingSecretInputs.get(key);
+  if (!entry) return false;
+  clearTimeout(entry.cleanupTimer);
+  pendingSecretInputs.delete(key);
+  return true;
+}
+
+/** 测试辅助 */
+export function pendingSecretInputCount(): number {
+  return pendingSecretInputs.size;
+}
+
+/** 测试辅助：清空全部 pending（不触发 timer 回调） */
+export function clearPendingSecretInputs(): void {
+  for (const entry of pendingSecretInputs.values()) clearTimeout(entry.cleanupTimer);
+  pendingSecretInputs.clear();
+}