@jerryliang122/openclaw-qqbot 1.0.0

package/src/middleware/inbound-guard.ts

@@ -0,0 +1,102 @@
+/**
+ * 入站事件守卫
+ *
+ * 拦截三类「非真实用户输入」的入站推送（均有平台文档/SDK 注释背书，
+ * 详见 AGENTS.md「入站事件守卫」条目）：
+ * 1. 出站回声 —— QQ 会把 bot 自己发出的消息回投为入站事件
+ *    （SDK message-filter 注释；c2c 事件无 author.bot，SDK 过滤不到），
+ *    按 outbound-echo-store 登记的近期出站消息 id 比对。
+ * 2. 重复推送 —— 平台事件文档要求按 msg_seq / message_scene.ext 的
+ *    msg_idx 去重（「为确保消息可达，相同 msg_id 可能重复推送」），
+ *    SDK 内置去重窗口仅 5s，这里补 30 分钟长窗口。
+ * 3. 空内容事件 —— content 空白且无附件、无 msg_elements 的推送
+ *    （重推副本 / 结构化回执形态）。注意：带 msg_elements 的 103
+ *    引用/转发消息是真实用户操作，必须放行（quoteRef 会渲染引用块）。
+ *
+ * 每次拦截打 INFO 日志（含 msgType / scene / payload 摘要）——这是
+ * 入站事件唯一的非 DEBUG 级痕迹，用于事后取证定位事件真身。
+ *
+ * 挂载位置：messageFilter 之后、policyInjector 之前（链条最前端，
+ * 避免污染群历史、烧 typing 被动回复配额）。
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import { isOutboundEcho } from '../features/outbound-echo-store.js';
+
+const DEDUP_TTL_MS = 30 * 60 * 1000; // 覆盖 c2c msg_id 30 分钟被动回复有效期
+const DEDUP_MAX = 5000;
+const PAYLOAD_PREVIEW_CHARS = 300;
+
+const dedupSeen = new Map<string, number>(); // dedupKey -> 首次见到的时间
+
+function truncateText(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function payloadPreview(raw: unknown): string {
+  try {
+    return truncateText(JSON.stringify(raw ?? {}), PAYLOAD_PREVIEW_CHARS);
+  } catch {
+    return '<unserializable>';
+  }
+}
+
+export interface InboundGuardParams {
+  accountId: string;
+}
+
+export function inboundGuard(params: InboundGuardParams): Middleware {
+  return async (ctx, next) => {
+    const msg = ctx.message as Record<string, any> | undefined;
+    const accountId = params.accountId;
+    const messageId: string | undefined = msg?.messageId;
+    const kind: string = msg?.kind ?? '?';
+
+    // 1. 出站回声：入站 id 命中近期出站消息 id
+    if (isOutboundEcho(accountId, messageId)) {
+      ctx.log.info(`[guard] dropped outbound-echo msgId=${messageId ?? '?'} kind=${kind}`);
+      ctx.stop('outbound-echo');
+      return;
+    }
+
+    // 2. 重复推送：msgId + msgIdx 长窗口去重
+    const msgIdx: string | undefined = msg?.msgIdx;
+    const dedupKey = `${accountId}:${kind}:${messageId ?? ''}:${msgIdx ?? ''}`;
+    const now = Date.now();
+    const firstSeen = dedupSeen.get(dedupKey);
+    if (firstSeen !== undefined && now - firstSeen <= DEDUP_TTL_MS) {
+      ctx.log.info(
+        `[guard] dropped duplicate-push msgId=${messageId ?? '?'} msgIdx=${msgIdx ?? ''} kind=${kind} ageMs=${now - firstSeen}`,
+      );
+      ctx.stop('duplicate-push');
+      return;
+    }
+    dedupSeen.set(dedupKey, now);
+    if (dedupSeen.size > DEDUP_MAX) {
+      for (const [key, ts] of dedupSeen) {
+        if (dedupSeen.size <= DEDUP_MAX && now - ts <= DEDUP_TTL_MS) break;
+        dedupSeen.delete(key);
+      }
+    }
+
+    // 3. 空内容事件：无文本、无附件、无消息元素
+    const contentBlank = !String(msg?.content ?? '').trim();
+    const hasAttachments = Array.isArray(msg?.attachments) && msg.attachments.length > 0;
+    const hasElements = Array.isArray(msg?.msgElements) && msg.msgElements.length > 0;
+    if (contentBlank && !hasAttachments && !hasElements) {
+      ctx.log.info(
+        `[guard] dropped contentless msgId=${messageId ?? '?'} kind=${kind}` +
+          ` msgType=${msg?.msgType ?? '?'} scene=${msg?.messageScene?.source ?? '?'}` +
+          ` payload=${payloadPreview(msg?.raw)}`,
+      );
+      ctx.stop('contentless');
+      return;
+    }
+
+    await next();
+  };
+}
+
+/** 测试用：清空去重表 */
+export function clearInboundGuardDedup(): void {
+  dedupSeen.clear();
+}

package/src/middleware/policy-injector.ts

@@ -0,0 +1,71 @@
+/**
+ * 动态策略注入中间件
+ *
+ * 每条消息到达时，按 groupId 解析群配置并注入 `ctx.state.policy`。
+ * SDK 内置中间件（mentionGate、historyBuffer 等）自动从 `ctx.state.policy`
+ * 读取动态策略作为 fallback，无需各自注册 `resolveConfig`。
+ *
+ * 优先级链（与旧版一致）：
+ *   具体群配置 > 通配符 "*" > defaultRequireMention > 硬编码默认值
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { resolveGroupConfigFromAccount } from '../config.js';
+
+/**
+ * 创建 policy injector 中间件。
+ *
+ * 注入的 `ctx.state.policy` 结构：
+ * ```
+ * {
+ *   scope: "c2c" | "group",
+ *   group: {
+ *     requireMention: boolean,
+ *     ignoreOtherMentions: boolean,
+ *     historyLimit: number,
+ *     // ... 可扩展任意字段
+ *   }
+ * }
+ * ```
+ *
+ * 使用者可在 `policy.group` 上添加自定义字段，如：
+ * ```
+ * ctx.state.policy.toolPolicy = "full";
+ * ```
+ * 自定义中间件通过 `ctx.state.policy` 读取即可。
+ */
+export function createPolicyInjector(account: ResolvedQQBotAccount): Middleware {
+  return async (ctx, next) => {
+    const msg = ctx.message as any;
+    const scope = msg.kind as 'c2c' | 'group' | 'dm' | 'channel';
+
+    const policy: Record<string, unknown> = {
+      scope,
+      accountId: account.accountId,
+      // 访问控制：dmPolicy（c2c） / groupPolicy（group），默认 allowlist
+      c2cMode: account.config?.dmPolicy ?? 'allowlist',
+      groupMode: account.config?.groupPolicy ?? 'allowlist',
+      allowFrom: account.config?.allowFrom ?? [],
+      groupAllowFrom: account.config?.groupAllowFrom ?? [],
+    };
+
+    if (scope === 'group') {
+      const groupOpenid = msg.groupOpenid ?? '';
+      const groupCfg = resolveGroupConfigFromAccount(account, groupOpenid);
+      // room_event 群：门控放行全部消息（mentionGate 以 requireMention=false
+      // 通过并保留 wasMentioned 标记），未 @/称呼/引用的消息在 dispatch 侧
+      // 分类为 room_event 被动房间事件（仅全量模式群实际会有这类消息到达）
+      const roomEvent = groupCfg.unmentionedInbound === 'room_event';
+      policy.group = {
+        requireMention: roomEvent ? false : groupCfg.requireMention,
+        ignoreOtherMentions: groupCfg.ignoreOtherMentions,
+        historyLimit: groupCfg.historyLimit,
+        prompt: groupCfg.prompt,
+        unmentionedInbound: groupCfg.unmentionedInbound,
+      };
+    }
+
+    ctx.state.policy = policy;
+    await next();
+  };
+}

package/src/middleware/secret-capture.ts

@@ -0,0 +1,161 @@
+/**
+ * 密钥捕获中间件
+ *
+ * 当会话存在 pending 密钥输入（secret-input-store）时，拦截该 c2c 用户的
+ * 下一条文本消息：就地执行 `openclaw secrets store set` 并把结果直接回复
+ * 给用户，消息本身不进入框架 —— 密钥值绝不进入 AI 转录 / 框架日志。
+ *
+ * 挂载位置：slashCommand 之后、groupMessageCoalescer 之前
+ * （/bot-* 命令优先可用；拦截后不再触发 typing 与 envelope 组装）。
+ *
+ * 红线：多问题 ask_user 答案 / 确认卡消息必须放行 —— 吞掉真实用户消息
+ * 会导致挂起的 ask_user 永不成单（AGENTS.md 2026-08-24 事故）。
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import { findPendingMultiQuestionByConversation } from '../features/question-helpers.js';
+import { checkAndConsumePassiveReplyQuota } from '../features/quota-manager.js';
+import {
+  runSecretsReload,
+  runSecretsStoreSet,
+  maskSecret,
+  type SecretsStoreSetResult,
+} from '../features/secret-store-cli.js';
+import {
+  cancelPendingSecretInput,
+  findPendingSecretInput,
+  takePendingSecretInput,
+} from '../features/secret-input-store.js';
+
+const CANCEL_KEYWORDS = new Set(['取消', 'cancel', '#cancel', '/cancel']);
+
+export function isSecretInputCancelKeyword(text: string): boolean {
+  return CANCEL_KEYWORDS.has(text.trim().toLowerCase());
+}
+
+/** 配额感知的直接回复：优先被动（msg_id），配额耗尽/发送失败降级主动 */
+async function replyToUser(
+  ctx: any,
+  accountId: string,
+  text: string,
+): Promise<void> {
+  const msgId = ctx.replyTarget?.msgId as string | undefined;
+  if (msgId) {
+    const { canReply, rollback } = checkAndConsumePassiveReplyQuota({
+      accountId,
+      msgId,
+      scope: 'c2c',
+    });
+    if (canReply) {
+      try {
+        await ctx.bot.sendText(ctx.replyTarget, text);
+        return;
+      } catch {
+        rollback();
+        // 落到主动降级
+      }
+    }
+  }
+  const proactiveTarget = { scope: 'c2c' as const, targetId: ctx.message.senderId as string };
+  await ctx.bot.sendText(proactiveTarget, text).catch(() => {/* 尽力而为 */});
+}
+
+function formatSetFailure(name: string, result: SecretsStoreSetResult): string {
+  const reason = result.timedOut
+    ? '执行超时'
+    : result.error
+      ? result.error
+      : `退出码 ${result.exitCode ?? '无'}`;
+  const lines = [`❌ 保存 \`${name}\` 失败（${reason}）。`];
+  if (!result.error && result.output) {
+    lines.push('', '```', result.output, '```');
+  }
+  lines.push(
+    '',
+    '可能原因：openclaw 版本过旧（需支持 `openclaw secrets store set`），或本机 CLI 不可用。',
+    '密钥未被保存，可稍后重试或改在终端执行。',
+  );
+  return lines.join('\n');
+}
+
+export interface SecretCaptureParams {
+  accountId: string;
+  /** 测试注入：替换 secrets store set 执行器 */
+  runSet?: typeof runSecretsStoreSet;
+  /** 测试注入：替换 secrets reload */
+  runReload?: typeof runSecretsReload;
+}
+
+export function secretCapture(params: SecretCaptureParams): Middleware {
+  const { accountId, runSet = runSecretsStoreSet, runReload = runSecretsReload } = params;
+
+  return async (ctx, next) => {
+    // 仅 c2c：密钥不应出现在群聊（工具侧发卡时已限制，此处双保险）
+    if (ctx.message.kind !== 'c2c') {
+      await next();
+      return;
+    }
+    const senderId = ctx.message.senderId as string;
+    const pending = findPendingSecretInput(accountId, senderId);
+    if (!pending) {
+      await next();
+      return;
+    }
+
+    // 红线：多问题 ask_user 进行中 → 其答案/确认卡消息优先，绝不拦截
+    if (findPendingMultiQuestionByConversation('c2c', senderId)) {
+      await next();
+      return;
+    }
+
+    const text = ((ctx.message.content as string | undefined) ?? '').trim();
+
+    if (isSecretInputCancelKeyword(text)) {
+      cancelPendingSecretInput(accountId, senderId);
+      ctx.log?.info?.(`[secret-input] cancelled by user (${pending.name})`);
+      await replyToUser(ctx, accountId, `已取消 \`${pending.name}\` 的密钥输入。需要时请重新发起。`);
+      ctx.stop('secret-capture:cancelled');
+      return;
+    }
+
+    // 空文本 / 纯附件：提示重发，保留 pending 继续等待
+    if (!text) {
+      await replyToUser(
+        ctx,
+        accountId,
+        `请直接以文本形式发送 **${pending.name}** 的值（可发送「取消」退出）。`,
+      );
+      ctx.stop('secret-capture:empty_input');
+      return;
+    }
+
+    // 一次性消费，防重复处理
+    const entry = takePendingSecretInput(accountId, senderId);
+    if (!entry) {
+      await next();
+      return;
+    }
+
+    const result = await runSet({ name: entry.name, kind: entry.kind, value: text });
+    let reloadOk = false;
+    if (result.ok) {
+      reloadOk = await runReload();
+    }
+    const masked = maskSecret(text);
+    const kindLabel = entry.kind === 'env' ? '代理可读环境变量' : `kind: ${entry.kind}`;
+    const reply = result.ok
+      ? [
+          `✅ 已保存 \`${entry.name}\`（${kindLabel}，值已隐藏：\`${masked}\`）`,
+          reloadOk
+            ? '已触发 `secrets reload`。'
+            : '提示：若该名称被 SecretRef 引用，可执行 `openclaw secrets reload` 使其立即生效。',
+        ].join('\n')
+      : formatSetFailure(entry.name, result);
+
+    ctx.log?.info?.(
+      `[secret-input] store set ${entry.name} kind=${entry.kind} ok=${result.ok}` +
+        ` exit=${result.exitCode ?? 'n/a'}${result.timedOut ? ' (timeout)' : ''}`,
+    );
+    await replyToUser(ctx, accountId, reply);
+    ctx.stop('secret-capture:consumed');
+  };
+}

package/src/middleware/typing.ts

@@ -0,0 +1,110 @@
+/**
+ * C2C "正在输入"指示器中间件（替代 SDK 的 typingIndicator）。
+ *
+ * 与 SDK 版的三点差异：
+ * 1. 续期间隔默认 20s 且强制不低于 20s（QPS 约束，事件触发的续期
+ *    同样受此间距保护）
+ * 2. 配额感知：typing 通知携带入站 msg_id 时属于被动回复、消耗该
+ *    msg_id 的被动配额，与真正的回复消息共享额度（经同一 limiter
+ *    记账）。被动配额耗尽后与回复消息一样自动降级为主动发送
+ *    （不带 msg_id），续期不会中断
+ * 3. 出站消息后续期：QQ 客户端收到机器人消息（如思维链中间输出）
+ *    会自动终止"正在输入"显示。若框架任务仍在进行，本中间件在
+ *    每条消息发出 POST_MESSAGE_REFRESH_DELAY_MS 后补发一次续期；
+ *    若该消息是最终回复（处理链完成），会话已结束，自然不再续期
+ *
+ * QQ 客户端行为：退出聊天界面再进入后指示器会消失，只有收到新的
+ * input_notify 推送才会重新显示 —— 这是需要周期性续期的原因。
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import { rollbackPassiveSlot, tryAcquirePassiveSlot } from '../outbound/outbound-service.js';
+import { subscribeOutboundMessage } from '../features/typing-refresh.js';
+
+/** QPS 约束：续期间隔不得低于 20s */
+export const MIN_TYPING_INTERVAL_MS = 20_000;
+const DEFAULT_TYPING_INTERVAL_MS = 20_000;
+/** 服务端输入状态窗口（秒），QQ 平台窗口上限约 60s */
+const TYPING_DURATION_SEC = 60;
+/** 出站消息后延迟多久补发续期 */
+export const POST_MESSAGE_REFRESH_DELAY_MS = 5_000;
+
+export function resolveTypingIntervalMs(input: number | undefined): number {
+  return Math.max(input ?? DEFAULT_TYPING_INTERVAL_MS, MIN_TYPING_INTERVAL_MS);
+}
+
+export interface TypingIndicatorMiddlewareOptions {
+  accountId: string;
+  /** 续期间隔 ms，默认 20_000，低于 20_000 会被钳制到 20_000 */
+  intervalMs?: number;
+}
+
+export function c2cTypingIndicator(opts: TypingIndicatorMiddlewareOptions): Middleware {
+  const accountId = opts.accountId;
+  const intervalMs = resolveTypingIntervalMs(opts.intervalMs);
+
+  return async (ctx, next) => {
+    // QQ 开放平台限制：input_notify 仅支持 C2C（私聊）
+    if (ctx.message.kind !== 'c2c') {
+      await next();
+      return;
+    }
+
+    let periodic: NodeJS.Timeout | null = null;
+    let refresh: NodeJS.Timeout | null = null;
+    let lastSentAt = 0;
+    let active = true;
+
+    const sendNow = (): void => {
+      if (!active) return;
+      // 被动配额可用 → 占用并带 msg_id 发送；耗尽 → 不带 msg_id 主动发送，
+      // 与回复消息的降级策略一致（见 outbound-service 的统一配额预留）
+      const passive = tryAcquirePassiveSlot(accountId, ctx.replyTarget.msgId);
+      const target = passive
+        ? ctx.replyTarget
+        : { scope: 'c2c' as const, targetId: ctx.replyTarget.targetId };
+      ctx.bot.sendTyping(target, TYPING_DURATION_SEC).catch((err: unknown) => {
+        if (passive) rollbackPassiveSlot(accountId, ctx.replyTarget.msgId);
+        ctx.log?.debug?.(`[typing] failed: ${err instanceof Error ? err.message : String(err)}`);
+      });
+      lastSentAt = Date.now();
+      // 以本次发送为锚点重置周期续期，避免与事件续期撞车
+      if (periodic) clearInterval(periodic);
+      periodic = setInterval(sendNow, intervalMs);
+    };
+
+    // 出站消息会终止客户端的输入状态显示 → 5s 后补发；
+    // 与上次 typing 发送不足 intervalMs 时顺延（QPS 间距保护）
+    const schedulePostMessageRefresh = (): void => {
+      if (!active) return;
+      if (refresh) clearTimeout(refresh);
+      refresh = setTimeout(() => {
+        refresh = null;
+        const wait = intervalMs - (Date.now() - lastSentAt);
+        if (wait > 0) {
+          refresh = setTimeout(() => {
+            refresh = null;
+            sendNow();
+          }, wait);
+        } else {
+          sendNow();
+        }
+      }, POST_MESSAGE_REFRESH_DELAY_MS);
+    };
+
+    // 订阅本会话的出站消息信号（ accountId + targetId 对应同一 C2C 用户）
+    const unsubscribe = subscribeOutboundMessage(
+      accountId, 'c2c', ctx.replyTarget.targetId, schedulePostMessageRefresh,
+    );
+
+    sendNow();
+
+    try {
+      await next();
+    } finally {
+      active = false;
+      unsubscribe();
+      if (periodic) clearInterval(periodic);
+      if (refresh) clearTimeout(refresh);
+    }
+  };
+}