@jerryliang122/openclaw-qqbot 1.0.0

package/src/features/approval-utils.ts

@@ -0,0 +1,21 @@
+/**
+ * 审批 payload 判断逻辑。
+ *
+ * 仅保留 isApprovalPayload —— 用于在出站链路中识别审批类 payload，
+ * 从而抑制框架侧重复的审批 prompt（native 审批由 approval-capability 处理）。
+ */
+
+/** 检查 payload 是否为审批消息（execApproval / plugin approval） */
+export function isApprovalPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') return false;
+  const p = payload as Record<string, unknown>;
+  const cd = p.channelData;
+  if (cd && typeof cd === 'object' && !Array.isArray(cd)) {
+    const execApproval = (cd as Record<string, unknown>).execApproval;
+    if (execApproval && typeof execApproval === 'object' && !Array.isArray(execApproval)) {
+      return true;
+    }
+  }
+  const text = typeof p.text === 'string' ? p.text : '';
+  return /(?:Plugin|Exec) approval (?:required|allowed|denied|expired)/i.test(text);
+}

package/src/features/command-panel.ts

@@ -0,0 +1,301 @@
+/**
+ * 指令面板自动同步（QQ Bot 指令面板 API，/v2/panels，2026-08-12 上线）
+ *
+ * gateway ready 后（initFeatures 触发）把 openclaw tier=essential 的原生指令
+ * 注册到 QQ Bot 指令面板，c2c / group 各一个（target_type=all）。
+ * 用户点击面板项 → 指令文本填入输入框 → 用户发送 → 以普通文本进入框架 →
+ * 框架文本斜杠指令路由执行（本插件不声明 capabilities.nativeCommands，
+ * 避免与 commands.text=false 配置冲突）。
+ *
+ * 平台约束（官方文档）：
+ *  - 面板项 name ≤14 字符、desc ≤30 字符、每面板 ≤20 项、每 bot ≤20 个面板
+ *  - POST /v2/panels 限 10 QPM — 常规同步 2 GET（c2c+group 各一页）+ 2 POST，余量充足
+ *  - GET /v2/panels 限 30 QPM，**scope 为必填查询参数**（缺失报 40030011 生效场景不合法），
+ *    列表分页（next_cursor / is_end）
+ *
+ * 幂等识别：自家面板用 panel.remark = "openclaw-qqbot:auto:<scope>" 打标；
+ * remark 不匹配的面板（用户在开放平台手动创建的）绝不修改或删除。
+ *
+ * 同步时机：每进程每账号仅一次（防 WebSocket resumed 重连时 onReady 重复触发）；
+ * 同步失败会释放 once-guard，下次重连可重试。全程错误只记日志，绝不阻断启动。
+ */
+import type { OpenClawConfig } from 'openclaw/plugin-sdk/config-contracts';
+import {
+  findCommandByNativeName,
+  listNativeCommandSpecsForConfig,
+} from 'openclaw/plugin-sdk/native-command-registry';
+import type { NativeCommandSpec } from 'openclaw/plugin-sdk/native-command-registry';
+import { tryGetBotForAccount } from '../bot-instance.js';
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+
+/** 自家面板的 remark 前缀（后接 scope：c2c / group） */
+const PANEL_REMARK_PREFIX = 'openclaw-qqbot:auto:';
+/** 同步的面板 scope（channel/dm 属于频道产品，本插件不涉及） */
+const PANEL_SCOPES = ['c2c', 'group'] as const;
+/** 平台限制：面板项 name 最大长度（约 7 个汉字） */
+const PANEL_ITEM_NAME_MAX = 14;
+/** 平台限制：面板项 desc 最大长度（约 15 个汉字） */
+const PANEL_ITEM_DESC_MAX = 30;
+/** 平台限制：每面板最大项数 */
+const PANEL_ITEM_LIMIT = 20;
+/** 列表分页：每页条数（官方上限 50）；循环上限防意外无限翻页 */
+const PANEL_LIST_PAGE_SIZE = 50;
+const PANEL_LIST_MAX_PAGES = 5;
+/** openclaw 命令注册表的 provider 标识 */
+const QQBOT_PROVIDER = 'qqbot';
+
+/** 面板项（type=command：点击后 name 文本填入聊天输入框） */
+export interface CommandPanelItem {
+  type: 'command';
+  name: string;
+  desc: string;
+}
+
+/** SDK ApiGateway 的结构子集（便于测试注入 fake） */
+export interface CommandPanelApi {
+  get<T = unknown>(path: string, query?: Record<string, string | number | boolean>): Promise<T>;
+  post<T = unknown>(path: string, body?: unknown): Promise<T>;
+  put<T = unknown>(path: string, body?: unknown): Promise<T>;
+  delete<T = unknown>(path: string): Promise<T>;
+}
+
+/** GET /v2/panels 返回的面板记录（字段位置防御式兼容两种嵌套） */
+interface PanelRecord {
+  panel_id?: string;
+  id?: string;
+  remark?: string;
+  panel?: { remark?: string; version?: number } | null;
+}
+
+/** 单个 scope 的同步结果 */
+export interface CommandPanelSyncResult {
+  scope: string;
+  action: 'created' | 'updated';
+  itemCount: number;
+  duplicatesRemoved: number;
+}
+
+// ── 纯函数：指令选取 ──
+
+/**
+ * 从原生指令 spec 列表选取 essential 指令并映射为面板项。
+ * tierOf 为指令名 → tier 的回查函数（NativeCommandSpec 不携带 tier，
+ * 需经 findCommandByNativeName 回查 ChatCommandDefinition；undefined 视为 standard）。
+ */
+export function selectEssentialCommands(
+  specs: readonly NativeCommandSpec[],
+  tierOf: (nativeName: string) => string | undefined,
+  log?: PluginLogger,
+): CommandPanelItem[] {
+  const items: CommandPanelItem[] = [];
+  for (const spec of specs) {
+    if (spec.isAlias) continue;
+    if (tierOf(spec.name) !== 'essential') continue;
+    const name = `/${spec.name}`;
+    if (name.length > PANEL_ITEM_NAME_MAX) {
+      log?.warn(
+        `[command-panel] 指令 ${name} 超过面板 name 上限 ${PANEL_ITEM_NAME_MAX} 字符，未注册（用户仍可手动输入）`,
+      );
+      continue;
+    }
+    items.push({ type: 'command', name, desc: truncateDesc(spec.description) });
+    if (items.length >= PANEL_ITEM_LIMIT) break;
+  }
+  return items;
+}
+
+/** desc 归一为单行并截断到平台上限 */
+function truncateDesc(desc: string): string {
+  const cleaned = (desc ?? '').replace(/\s+/g, ' ').trim();
+  return cleaned.length > PANEL_ITEM_DESC_MAX ? cleaned.slice(0, PANEL_ITEM_DESC_MAX) : cleaned;
+}
+
+// ── 同步核心（可独立测试） ──
+
+/**
+ * 把 items 整包同步到 c2c / group 两个面板（幂等）：
+ * 无自家面板 → POST 创建；有一个 → PUT 覆盖；有重复 → PUT 第一个并 DELETE 其余。
+ * remark 不匹配的面板不触碰。
+ */
+export async function syncAccountCommandPanels(
+  api: CommandPanelApi,
+  items: readonly CommandPanelItem[],
+  log?: PluginLogger,
+): Promise<CommandPanelSyncResult[]> {
+  const byScope = await listPanels(api, log);
+  const results: CommandPanelSyncResult[] = [];
+  for (const scope of PANEL_SCOPES) {
+    const remark = panelRemark(scope);
+    const mine = byScope[scope].filter((p) => panelRemarkOf(p) === remark);
+    if (mine.length === 0) {
+      await api.post('/v2/panels', {
+        scope,
+        target_type: 'all',
+        panel: { items, remark },
+      });
+      results.push({ scope, action: 'created', itemCount: items.length, duplicatesRemoved: 0 });
+      continue;
+    }
+    const [keep, ...duplicates] = mine;
+    await api.put(`/v2/panels/${panelIdOf(keep)}`, {
+      panel: { items, remark },
+    });
+    let removed = 0;
+    for (const dup of duplicates) {
+      const id = panelIdOf(dup);
+      if (!id) continue;
+      await api.delete(`/v2/panels/${id}`);
+      removed++;
+    }
+    results.push({ scope, action: 'updated', itemCount: items.length, duplicatesRemoved: removed });
+  }
+  return results;
+}
+
+/** 列表按 scope 分桶：GET 必传 scope，每个 scope 的同步只看自己场景的面板 */
+type PanelsByScope = Record<(typeof PANEL_SCOPES)[number], PanelRecord[]>;
+
+async function listPanels(api: CommandPanelApi, log?: PluginLogger): Promise<PanelsByScope> {
+  // 官方文档（bot.q.qq.com GET /v2/panels）：scope 为必填查询参数，缺失时服务端报
+  // 40030011「生效场景不合法」；列表按 next_cursor / is_end 分页。故按 scope 各查一遍。
+  const byScope: PanelsByScope = { c2c: [], group: [] };
+  for (const scope of PANEL_SCOPES) {
+    let cursor = '';
+    for (let page = 0; page < PANEL_LIST_MAX_PAGES; page++) {
+      const query: Record<string, string | number | boolean> = { scope, limit: PANEL_LIST_PAGE_SIZE };
+      if (cursor) query.cursor = cursor;
+      const raw: unknown = await api.get('/v2/panels', query);
+      const records = extractPanelRecords(raw);
+      byScope[scope].push(...records);
+      if (records.length === 0 && page === 0) {
+        log?.debug(
+          `[command-panel] GET /v2/panels?scope=${scope} 拉到 0 条记录，响应形状: ${JSON.stringify(raw).slice(0, 500)}`,
+        );
+      }
+      cursor = extractNextCursor(raw);
+      if (!cursor || extractIsEnd(raw)) break;
+    }
+  }
+  return byScope;
+}
+
+/** 官方列表响应形如 { records, next_cursor, is_end }；旧/未知形状无分页字段时返回空串 */
+function extractNextCursor(raw: unknown): string {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    const v = (raw as Record<string, unknown>).next_cursor;
+    if (typeof v === 'string') return v;
+  }
+  return '';
+}
+
+function extractIsEnd(raw: unknown): boolean {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    const v = (raw as Record<string, unknown>).is_end;
+    if (typeof v === 'boolean') return v;
+  }
+  return false;
+}
+
+function extractPanelRecords(raw: unknown): PanelRecord[] {
+  if (Array.isArray(raw)) return raw.filter(isPanelRecord);
+  if (raw && typeof raw === 'object') {
+    for (const key of ['records', 'panels', 'data', 'list', 'items'] as const) {
+      const value = (raw as Record<string, unknown>)[key];
+      if (Array.isArray(value)) return value.filter(isPanelRecord);
+    }
+  }
+  return [];
+}
+
+function isPanelRecord(value: unknown): value is PanelRecord {
+  return Boolean(value) && typeof value === 'object';
+}
+
+function panelRemark(scope: string): string {
+  return PANEL_REMARK_PREFIX + scope;
+}
+
+/** remark 可能扁平在记录上，也可能嵌在 panel 对象里 */
+function panelRemarkOf(record: PanelRecord): string | undefined {
+  return record.remark ?? record.panel?.remark ?? undefined;
+}
+
+function panelIdOf(record: PanelRecord): string | undefined {
+  return record.panel_id ?? record.id ?? undefined;
+}
+
+// ── 编排入口（initFeatures 调用） ──
+
+/** 每进程每账号只同步一次（防 resumed 重连重复触发） */
+const syncedAccounts = new Set<string>();
+
+/** 测试钩子：清除 once-guard */
+export function clearCommandPanelSynced(accountId?: string): void {
+  if (accountId === undefined) syncedAccounts.clear();
+  else syncedAccounts.delete(accountId);
+}
+
+/**
+ * 同步账号的指令面板（fire-and-forget，错误只记日志）。
+ * 任何异常都不抛出，绝不影响消息收发。
+ */
+export async function syncCommandPanels(
+  account: ResolvedQQBotAccount,
+  cfg: unknown,
+  log?: PluginLogger,
+): Promise<void> {
+  if (!account.commandPanelNative) return;
+  if (syncedAccounts.has(account.accountId)) return;
+
+  const bot = tryGetBotForAccount(account.accountId);
+  if (!bot) {
+    log?.debug(`[command-panel] bot 未就绪，跳过本次面板同步: ${account.accountId}`);
+    return;
+  }
+
+  syncedAccounts.add(account.accountId);
+  try {
+    const items = buildEssentialItems(cfg, log);
+    if (items.length === 0) {
+      log?.warn('[command-panel] 未选取到任何 essential 指令，跳过面板同步（避免清空现有面板）');
+      return;
+    }
+    const results = await syncAccountCommandPanels(bot.api, items, log);
+    for (const r of results) {
+      log?.info(
+        `[command-panel] ${r.scope} 面板已${r.action === 'created' ? '创建' : '更新'}：${r.itemCount} 项指令` +
+          (r.duplicatesRemoved > 0 ? `，清理重复面板 ${r.duplicatesRemoved} 个` : ''),
+      );
+    }
+  } catch (err) {
+    // 失败释放 once-guard：resumed 重连会再次触发 initFeatures，提供一次重试机会
+    syncedAccounts.delete(account.accountId);
+    log?.warn(`[command-panel] 指令面板同步失败（不影响消息收发）: ${formatError(err)}`);
+  }
+}
+
+/** 枚举 openclaw 原生指令并选取 essential 子集 */
+function buildEssentialItems(cfg: unknown, log?: PluginLogger): CommandPanelItem[] {
+  let specs: NativeCommandSpec[];
+  try {
+    specs = listNativeCommandSpecsForConfig(cfg as OpenClawConfig, {
+      provider: QQBOT_PROVIDER,
+      includeBundledChannelFallback: false,
+    });
+  } catch (err) {
+    log?.warn(`[command-panel] 枚举 openclaw 原生指令失败: ${formatError(err)}`);
+    return [];
+  }
+  return selectEssentialCommands(
+    specs,
+    (name) =>
+      findCommandByNativeName(name, QQBOT_PROVIDER, { includeBundledChannelFallback: false })?.tier,
+    log,
+  );
+}
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/features/credential-backup.ts

@@ -0,0 +1,74 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 存储路径：~/.openclaw/qqbot/data/credential-backup/current.json
+ * 使用子目录避免被框架 SQLite 迁移扫描（迁移只匹配 data/credential-backup.json）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getQQBotDataDir } from '../utils/platform.js';
+
+const BACKUP_DIR = 'credential-backup';
+const BACKUP_FILENAME = 'current.json';
+
+interface CredentialBackup {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  savedAt: string;
+}
+
+function getBackupPath(): string {
+  return path.join(getQQBotDataDir('data'), BACKUP_DIR, BACKUP_FILENAME);
+}
+
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void {
+  if (!appId || !clientSecret) return;
+  try {
+    const backupPath = getBackupPath();
+    const dir = path.dirname(backupPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    const data: CredentialBackup = {
+      accountId,
+      appId,
+      clientSecret,
+      savedAt: new Date().toISOString(),
+    };
+    const tmpPath = backupPath + '.tmp';
+    fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmpPath, backupPath);
+  } catch {
+    // 非关键操作，静默忽略
+  }
+}
+
+/**
+ * 从暂存文件读取凭证（仅在配置为空时调用）
+ * 返回 null 表示无可用备份
+ */
+export function loadCredentialBackup(accountId?: string): CredentialBackup | null {
+  try {
+    const backupPath = getBackupPath();
+    if (fs.existsSync(backupPath)) {
+      return readBackupFile(backupPath, accountId);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readBackupFile(filePath: string, accountId?: string): CredentialBackup | null {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const data: CredentialBackup = JSON.parse(raw);
+  if (!data.appId || !data.clientSecret) return null;
+  if (accountId && data.accountId !== accountId) return null;
+  return data;
+}

package/src/features/group-mode-store.ts

@@ -0,0 +1,79 @@
+/**
+ * 群推送模式推断存储（内存，跨重启不保留）
+ *
+ * 群主把 bot 拉进群时会选推送模式（AT 纯 / AT+最近N≤10 / 全量），这是群主侧
+ * 的设置，插件不可控、同账号各群混合存在。平台只通过事件类型暴露这个事实：
+ * - GROUP_AT_MESSAGE_CREATE → AT 系（纯 AT 或 AT+最近N，两者无法区分）
+ * - GROUP_MESSAGE_CREATE    → 全量模式（bot 像普通群成员收到所有消息）
+ *
+ * 推断结果供 /bot-group-info 展示与排障（"这个群为什么没上下文"——群主设的
+ * 是纯 AT 模式）。模式变化打 INFO 日志留痕。
+ */
+
+/** 平台推送模式（按事件类型推断） */
+export type GroupPushMode = 'at' | 'full';
+
+export interface GroupModeFacts {
+  /** 推断的推送模式（按最近一次事件类型） */
+  mode: GroupPushMode;
+  /** 最近一次见到的事件类型（原文保留） */
+  lastEventType: string;
+  /** 曾见过 msg_elements（AT+最近N 的上下文载体，或用户引用/转发消息） */
+  sawMsgElements: boolean;
+  /** 首次/最近观测时间（epoch ms） */
+  firstSeenAt: number;
+  updatedAt: number;
+}
+
+const MAX_TRACKED_GROUPS = 1000;
+
+const store = new Map<string, GroupModeFacts>();
+
+function storeKey(accountId: string, groupOpenid: string): string {
+  return `${accountId}:${groupOpenid}`;
+}
+
+/** 记录一次群事件观测；推断模式变化时返回新模式（供调用方打日志），否则 null */
+export function recordGroupEvent(
+  accountId: string,
+  groupOpenid: string,
+  eventType: string,
+  hasMsgElements: boolean,
+): GroupPushMode | null {
+  const key = storeKey(accountId, groupOpenid);
+  const now = Date.now();
+  const mode: GroupPushMode = eventType === 'GROUP_MESSAGE_CREATE' ? 'full' : 'at';
+  const prev = store.get(key);
+
+  if (prev) {
+    const modeChanged = prev.mode !== mode;
+    prev.lastEventType = eventType;
+    prev.mode = mode;
+    prev.sawMsgElements = prev.sawMsgElements || hasMsgElements;
+    prev.updatedAt = now;
+    return modeChanged ? mode : null;
+  }
+
+  if (store.size >= MAX_TRACKED_GROUPS) {
+    // 简单防膨胀：丢弃最早观测的一半（推断数据可随时重建，不值得引入 LRU 复杂度）
+    const keys = [...store.entries()].sort((a, b) => a[1].updatedAt - b[1].updatedAt);
+    for (const [k] of keys.slice(0, Math.floor(keys.length / 2))) store.delete(k);
+  }
+  store.set(key, {
+    mode,
+    lastEventType: eventType,
+    sawMsgElements: hasMsgElements,
+    firstSeenAt: now,
+    updatedAt: now,
+  });
+  return null; // 首次观测不视为「变化」
+}
+
+export function getGroupModeFacts(accountId: string, groupOpenid: string): GroupModeFacts | undefined {
+  return store.get(storeKey(accountId, groupOpenid));
+}
+
+/** 测试用：清空存储 */
+export function _resetGroupModeStore(): void {
+  store.clear();
+}

package/src/features/history-store.ts

@@ -0,0 +1,75 @@
+import { MemoryHistoryStore } from '@tencent-connect/qqbot-nodejs';
+import type { HistoryStore, HistoryEntry } from '@tencent-connect/qqbot-nodejs';
+
+/** 出站历史条目（在 HistoryEntry 上附加 isBot 标记，rolling 模式裁剪用） */
+export type OutboundHistoryEntry = HistoryEntry & { isBot: true };
+
+let _store: HistoryStore | null = null;
+
+export function getHistoryStore(): HistoryStore {
+  if (!_store) _store = new MemoryHistoryStore();
+  return _store;
+}
+
+/** 用 accountId 前缀隔离多账号，避免同群历史串用 */
+export function historyGroupKey(accountId: string, groupId: string): string {
+  return `${accountId}:${groupId}`;
+}
+
+/** 清空群历史（dispatch 完成后调用，historyMode=clear 语义） */
+export function clearGroupHistory(accountId: string, groupId: string): void {
+  _store?.clear?.(historyGroupKey(accountId, groupId));
+}
+
+/**
+ * bot 出站消息记入群历史（historyMode=rolling 语义）。
+ * 仅群消息回复需要；条目带 isBot=true，供裁剪定位"bot 最后一条发言"。
+ */
+export function recordOutboundToGroupHistory(
+  accountId: string,
+  groupOpenid: string,
+  entry: { messageId: string; senderId: string; senderName?: string; content: string },
+  limit: number,
+): void {
+  if (limit <= 0) return;
+  const historyEntry: OutboundHistoryEntry = {
+    messageId: entry.messageId,
+    senderId: entry.senderId,
+    senderName: entry.senderName,
+    content: entry.content,
+    timestamp: Date.now(),
+    isBot: true,
+  };
+  void _store?.append?.(historyGroupKey(accountId, groupOpenid), historyEntry, limit);
+}
+
+/**
+ * rolling 模式裁剪：删除最后一条 bot 出站（含）之前的全部条目，
+ * 保留其后的人类消息（下次 @ 时组包，AI 由此知道自己上次说到哪）。
+ * 无 bot 出站记录时不动（保守：等价于不清）。返回保留的条数（供日志）。
+ */
+export function trimGroupHistoryAfterLastBot(accountId: string, groupId: string, limit: number): number {
+  const store = _store;
+  if (!store?.list || !store.clear || !store.append) return 0;
+  const key = historyGroupKey(accountId, groupId);
+  const listed = store.list(key, 1_000_000);
+  if (listed instanceof Promise) return 0; // 异步后端不支持同步裁剪（当前为 MemoryHistoryStore 同步实现）
+  const entries: HistoryEntry[] = listed;
+  if (entries.length === 0) return 0;
+
+  let lastBotIdx = -1;
+  for (let i = entries.length - 1; i >= 0; i--) {
+    if ((entries[i] as { isBot?: boolean }).isBot === true) {
+      lastBotIdx = i;
+      break;
+    }
+  }
+  if (lastBotIdx < 0) return 0;
+
+  const kept = entries.slice(lastBotIdx + 1);
+  store.clear(key);
+  for (const e of kept) {
+    store.append(key, e, Math.max(limit, kept.length));
+  }
+  return kept.length;
+}

package/src/features/msgid-cache.ts

@@ -0,0 +1,55 @@
+/**
+ * 消息 ID 缓存 — 记录最近处理的 msgId，供被动回复使用。
+ *
+ * 场景：外部调用发送消息时没有上下文，
+ * 从缓存获取最近一条未过期的 msgId 作为被动回复目标。
+ */
+
+interface CachedMsgId {
+  msgId: string;
+  timestamp: number;
+}
+
+const MAX_PER_TARGET = 10;
+const TTL_GROUP = 5 * 60 * 1000;   // 5 分钟
+const TTL_C2C = 30 * 60 * 1000;   // 30 分钟
+const MAX_TARGETS = 200;
+
+const cache = new Map<string, CachedMsgId[]>();
+
+export function cacheMsgId(scope: string, targetId: string, msgId: string): void {
+  if (!scope || !targetId || !msgId) return;
+  const key = `${scope}:${targetId}`;
+  const existing = cache.get(key);
+  if (existing) {
+    // LRU: 删除再重新插入
+    cache.delete(key);
+    existing.push({ msgId, timestamp: Date.now() });
+    if (existing.length > MAX_PER_TARGET) existing.shift();
+    cache.set(key, existing);
+  } else {
+    cache.set(key, [{ msgId, timestamp: Date.now() }]);
+    if (cache.size > MAX_TARGETS) {
+      const oldest = cache.keys().next().value;
+      if (oldest) cache.delete(oldest);
+    }
+  }
+}
+
+export function getCachedMsgId(scope: string, targetId: string): string | undefined {
+  const key = `${scope}:${targetId}`;
+  const list = cache.get(key);
+  if (!list || list.length === 0) return undefined;
+  const now = Date.now();
+  const ttl = scope === 'group' ? TTL_GROUP : TTL_C2C;
+  for (let i = list.length - 1; i >= 0; i--) {
+    if (now - list[i].timestamp < ttl) {
+      return list[i].msgId;
+    }
+  }
+  return undefined;
+}
+
+export function clearMsgIdCache(scope: string, targetId: string): void {
+  cache.delete(`${scope}:${targetId}`);
+}

package/src/features/outbound-echo-store.ts

@@ -0,0 +1,46 @@
+/**
+ * 出站消息回声登记
+ *
+ * SDK message-filter 文档注明：QQ 可能把机器人自己的出站消息回投为入站
+ * 事件（群聊尤其常见）。c2c 事件不映射 author.bot，SDK 的 skipSelfEcho
+ * 过滤对私聊回声无效 —— 这里按「近期出站消息 id」自行比对。
+ *
+ * 出站 id 来源：wrapBotSendForRefIndex（sendText / sendMedia / 流式
+ * complete 的返回值 msg.id）。若平台回声携带新 id 而非原 id，比对会
+ * miss —— 由 inbound-guard 的空内容/去重检查兜底。
+ */
+
+const TTL_MS = 30 * 60 * 1000; // 与 msgid-cache 的 c2c TTL 对齐
+const MAX_ENTRIES = 2000;
+
+const seen = new Map<string, number>(); // `${accountId}:${messageId}` -> 记录时间
+
+function prune(now: number): void {
+  for (const [key, ts] of seen) {
+    if (seen.size <= MAX_ENTRIES && now - ts <= TTL_MS) break;
+    seen.delete(key);
+  }
+}
+
+export function recordOutboundMessageId(accountId: string, messageId: string | undefined | null): void {
+  if (!messageId) return;
+  seen.set(`${accountId}:${messageId}`, Date.now());
+  prune(Date.now());
+}
+
+export function isOutboundEcho(accountId: string, messageId: string | undefined | null): boolean {
+  if (!messageId) return false;
+  const key = `${accountId}:${messageId}`;
+  const ts = seen.get(key);
+  if (ts === undefined) return false;
+  if (Date.now() - ts > TTL_MS) {
+    seen.delete(key);
+    return false;
+  }
+  return true;
+}
+
+/** 测试用：清空登记表 */
+export function clearOutboundEchoStore(): void {
+  seen.clear();
+}