@cxyhhhhh/openclaw-qqbot 2.0.0-dev.202607091957 → 2.0.0-dev.202607101321

package/dist/index.d.cts

@@ -30,6 +30,11 @@ interface ResolvedQQBotAccount {
     markdownSupport: boolean;
     /** User-Agent 尾部追加内容 */
     userAgentSuffix: string;
+    /**
+     * 单条消息最大处理时间（ms）。超时后 concurrencyGuard 会 abort 处理链，
+     * 释放锁并排空缓冲消息。0 表示不限制。默认 0（不限制）。
+     */
+    processingTimeoutMs: number;
     config: QQBotAccountConfig;
 }
 /** 群消息策略：open=全响应 | allowlist=白名单 | disabled=不响应 */
@@ -145,6 +150,17 @@ interface QQBotAccountConfig {
      * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
      */
     stt?: STTChannelConfig;
+    /**
+     * 单条消息最大处理时间（毫秒）。
+     * 超时后 concurrencyGuard 会 abort 处理链（取消 LLM 调用、工具执行等），
+     * 释放并发锁并排空缓冲消息。
+     *
+     * 设为 0 表示不限制超时。默认 0（不限制）。
+     *
+     * 可通过环境变量 OPENCLAW_PROCESSING_TIMEOUT_MS 覆盖全局默认值，
+     * 账户级配置优先级高于环境变量。
+     */
+    processingTimeoutMs?: number;
     /**
      * User-Agent 尾部追加内容（用于私有化部署标识等场景）
      * 追加在 `QQBotPlugin/{version} (Node/{nodeVersion}; {os}; OpenClaw/{version})` 之后
@@ -822,6 +838,12 @@ declare function resolveDefaultQQBotAccountId(cfg: OpenClawConfig): string;
  * 用于私有化部署标识等场景，追加在 UA 末尾
  */
 declare function resolveUserAgentSuffix(cfg: OpenClawConfig): string;
+/**
+ * 解析单条消息处理超时时间（ms）。
+ * 优先级：账户配置 > 环境变量 OPENCLAW_PROCESSING_TIMEOUT_MS > 默认
+ * 返回 0 表示不限制超时。
+ */
+declare function resolveProcessingTimeoutMs(accountConfig?: QQBotAccountConfig): number;
 /**
  * 解析 QQBot 账户配置
  */
@@ -854,4 +876,4 @@ declare const plugin: {
     register(api: OpenClawPluginApi): void;
 };
 
-export { type AudioFormatPolicy, type C2CMessageEvent, type CustomKeyboard, DEFAULT_ACCOUNT_ID, type DeliverDebounceConfig, type GroupConfig, type GroupMessageEvent, type GroupPolicy, type GuildMessageEvent, type InlineKeyboard, type InteractionEvent, type KeyboardAction, type KeyboardActionType, type KeyboardButton, type KeyboardModal, type KeyboardPermission, type KeyboardRenderData, type KeyboardRow, MSG_TYPE_QUOTE, MSG_TYPE_TEXT, type MessageAttachment, type MessageKeyboard, type MsgElement, PersistedRefIndexStore, type QQBotAccountConfig, type QQBotConfig, QQBotGateway, type ResolvedGroupConfig, type ResolvedQQBotAccount, type STTChannelConfig, StreamContentType, StreamInputMode, StreamInputState, type StreamMessageRequest, StreamingController, type ToolPolicy, type WSPayload, applyQQBotAccountConfig, buildUserAgent, plugin as default, dispatchToOpenClaw, flushAllRefIndexStores, getBotForAccount, getPersistedRefIndexStore, getQQBotRuntime, isGroupAllowed, listQQBotAccountIds, parseTarget, qqbotOnboardingAdapter, qqbotPlugin, resolveDefaultQQBotAccountId, resolveGroupAllowFrom, resolveGroupConfig, resolveGroupConfigFromAccount, resolveGroupName, resolveGroupPolicy, resolveGroupPrompt, resolveHistoryLimit, resolveIgnoreOtherMentions, resolveMentionPatterns, resolveQQBotAccount, resolveRequireMention, resolveToolPolicy, resolveUserAgentSuffix, sendMedia, sendText, setQQBotRuntime, shouldUseStreaming, tryGetBotForAccount };
+export { type AudioFormatPolicy, type C2CMessageEvent, type CustomKeyboard, DEFAULT_ACCOUNT_ID, type DeliverDebounceConfig, type GroupConfig, type GroupMessageEvent, type GroupPolicy, type GuildMessageEvent, type InlineKeyboard, type InteractionEvent, type KeyboardAction, type KeyboardActionType, type KeyboardButton, type KeyboardModal, type KeyboardPermission, type KeyboardRenderData, type KeyboardRow, MSG_TYPE_QUOTE, MSG_TYPE_TEXT, type MessageAttachment, type MessageKeyboard, type MsgElement, PersistedRefIndexStore, type QQBotAccountConfig, type QQBotConfig, QQBotGateway, type ResolvedGroupConfig, type ResolvedQQBotAccount, type STTChannelConfig, StreamContentType, StreamInputMode, StreamInputState, type StreamMessageRequest, StreamingController, type ToolPolicy, type WSPayload, applyQQBotAccountConfig, buildUserAgent, plugin as default, dispatchToOpenClaw, flushAllRefIndexStores, getBotForAccount, getPersistedRefIndexStore, getQQBotRuntime, isGroupAllowed, listQQBotAccountIds, parseTarget, qqbotOnboardingAdapter, qqbotPlugin, resolveDefaultQQBotAccountId, resolveGroupAllowFrom, resolveGroupConfig, resolveGroupConfigFromAccount, resolveGroupName, resolveGroupPolicy, resolveGroupPrompt, resolveHistoryLimit, resolveIgnoreOtherMentions, resolveMentionPatterns, resolveProcessingTimeoutMs, resolveQQBotAccount, resolveRequireMention, resolveToolPolicy, resolveUserAgentSuffix, sendMedia, sendText, setQQBotRuntime, shouldUseStreaming, tryGetBotForAccount };

package/openclaw.plugin.json

@@ -4,7 +4,7 @@
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
   "extensions": ["./preload.cjs"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-group", "skills/qqbot-remind", "skills/qqbot-upgrade"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-upgrade"],
   "contracts": {
     "tools": ["qqbot_platform_api", "qqbot_remind"]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxyhhhhh/openclaw-qqbot",
-  "version": "2.0.0-dev.202607091957",
+  "version": "2.0.0-dev.202607101321",
   "description": "QQ Bot channel plugin for OpenClaw",
   "publishConfig": {
     "access": "public"
@@ -41,12 +41,12 @@
     "lint:runtime": "npx tsx src/runtime-adapter/lint-runtime-access.ts"
   },
   "dependencies": {
-    "@tencent-connect/qqbot-nodejs": "npm:@cxyhhhhh/qqbot-nodejs@1.0.2-dev.202607081646",
-    "@tencent-connect/qqbot-connector": "1.2.0"
+    "@tencent-connect/qqbot-connector": "1.2.0",
+    "@tencent-connect/qqbot-nodejs": "npm:@cxyhhhhh/qqbot-nodejs@1.0.2-dev.202607101142"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "tsup": "^8.0.0",
+    "@types/node": "^20.19.43",
+    "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {

package/src/adapter/contract.ts

@@ -62,7 +62,7 @@ export function verifyRuntimeContract(rt: PluginRuntime): ContractResult {
     log.error(`BROKEN — missing: ${missing.join(', ')}`);
   }
   if (degraded.length) {
-    log.warn(`degraded: ${degraded.join(', ')}`);
+    log.debug(`degraded: ${degraded.join(', ')}`);
   }
 
   return { ok: missing.length === 0, version, missing, degraded };

package/src/config.ts

@@ -79,6 +79,9 @@ const DEFAULT_GROUP_POLICY: GroupPolicy = "open";
 /** 群历史缓存条数默认值 */
 const DEFAULT_GROUP_HISTORY_LIMIT = 20;
 
+/** 单条消息默认处理超时（0 = 不限制） */
+const DEFAULT_PROCESSING_TIMEOUT_MS = 0;
+
 const DEFAULT_GROUP_CONFIG: Omit<Required<GroupConfig>, "prompt"> = {
   requireMention: true,
   ignoreOtherMentions: false,
@@ -229,6 +232,25 @@ export function resolveUserAgentSuffix(cfg: OpenClawConfig): string {
   return qqbot?.userAgentSuffix ? String(qqbot.userAgentSuffix).trim() : '';
 }
 
+/**
+ * 解析单条消息处理超时时间（ms）。
+ * 优先级：账户配置 > 环境变量 OPENCLAW_PROCESSING_TIMEOUT_MS > 默认
+ * 返回 0 表示不限制超时。
+ */
+export function resolveProcessingTimeoutMs(
+  accountConfig?: QQBotAccountConfig,
+): number {
+  if (accountConfig?.processingTimeoutMs !== undefined) {
+    return accountConfig.processingTimeoutMs;
+  }
+  const env = process.env.OPENCLAW_PROCESSING_TIMEOUT_MS;
+  if (env) {
+    const v = Number(env);
+    if (!Number.isNaN(v) && v >= 0) return v;
+  }
+  return DEFAULT_PROCESSING_TIMEOUT_MS;
+}
+
 /**
  * 解析 QQBot 账户配置
  */
@@ -287,6 +309,7 @@ export function resolveQQBotAccount(
     systemPrompt: accountConfig.systemPrompt,
     markdownSupport: accountConfig.markdownSupport !== false,
     userAgentSuffix: resolveUserAgentSuffix(cfg),
+    processingTimeoutMs: resolveProcessingTimeoutMs(accountConfig),
     config: accountConfig,
   };
 }

package/src/dispatch/dispatch.ts

@@ -137,15 +137,16 @@ export async function dispatchToOpenClaw(
           await deliverReply(payload, info, deliverCtx);
         },
       },
-      ...(streamingController
-        ? {
-            replyOptions: {
+      replyOptions: {
+        abortSignal: ctx.signal,
+        ...(streamingController
+          ? {
               onPartialReply: async (p: { text?: string }) => {
                 if (p.text) await streamingController.onPartialReply(p.text);
               },
-            },
-          }
-        : {}),
+            }
+          : {}),
+      },
     });
     if (streamingController && !streamingController.isTerminal) {
       await streamingController.finalize();
@@ -272,6 +273,7 @@ export async function dispatchToOpenClaw(
               },
             },
             replyOptions: {
+              abortSignal: ctx.signal,
               runId: envelope.messageId,
               ...(streamingController
                 ? {

package/src/gateway/middleware-setup.ts

@@ -5,7 +5,7 @@
  * 中间件负责过滤和上下文富化；concurrencyGuard 负责串行+合并，
  * 合并后的消息继续走完剩余中间件链，最终统一由 bot.on("message") 处理转发。
  */
-import type { QQBot } from '@tencent-connect/qqbot-nodejs';
+import type { QQBot, MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
 import {
   messageFilter,
   contentSanitizer,
@@ -78,9 +78,15 @@ export function setupMiddlewares(bot: QQBot, account: ResolvedQQBotAccount, opts
   //     - 处理中消息暂存 buffer；完成后合并为一条，继续走完剩余中间件链
   //       （typingIndicator/quoteRef/attachmentProcessor/... 直到 bot.on("message")）
   //     - 合并时清除 assembledBody 让 dispatch.ts 用合并后 content 重建
+  //     - 超时后 abort 处理链（取消 LLM 调用），释放锁并排空缓冲
   bot.use(concurrencyGuard({
     strategy: 'merge',
     maxQueue: 50,
+    maxProcessingMs: account.processingTimeoutMs,
+    /** 紧急指令（/stop）跳过排队，立即处理 */
+    urgentPredicate: (ctx: MiddlewareContext) => {
+      return (ctx.message.content as string ?? '').trim() === '/stop';
+    },
     onMerge: (buffered) => {
       const last = buffered[buffered.length - 1];
       if (buffered.length === 1) return last;

package/src/outbound/cron-scheduler.ts

@@ -46,10 +46,11 @@ export class CronScheduler {
     const target = payload.target ?? defaultTarget;
     const triggerAt = resolveTriggerTime(payload.at);
     const delayMs = Math.max(0, triggerAt - Date.now());
+    const text = payload.text?.trim() ?? '定时提醒';
 
     const reminder: ScheduledReminder = {
       id,
-      text: payload.text,
+      text,
       target,
       triggerAt,
     };
@@ -60,7 +61,7 @@ export class CronScheduler {
       reminder.timer = setTimeout(async () => {
         this.reminders.delete(id);
         try {
-          await this.send(target, `⏰ ${payload.text}`);
+          await this.send(target, `⏰ ${text}`);
         } catch { /* swallow */ }
       }, delayMs);
     }
@@ -68,7 +69,7 @@ export class CronScheduler {
     this.reminders.set(id, reminder);
 
     const when = new Date(triggerAt);
-    const confirmText = `✅ Reminder scheduled for ${when.toLocaleString()}: "${payload.text}"`;
+    const confirmText = `✅ Reminder scheduled for ${when.toLocaleString()}: "${text}"`;
     return { id, triggerAt, confirmText };
   }
 

package/src/types.ts

@@ -29,6 +29,11 @@ export interface ResolvedQQBotAccount {
   markdownSupport: boolean;
   /** User-Agent 尾部追加内容 */
   userAgentSuffix: string;
+  /**
+   * 单条消息最大处理时间（ms）。超时后 concurrencyGuard 会 abort 处理链，
+   * 释放锁并排空缓冲消息。0 表示不限制。默认 0（不限制）。
+   */
+  processingTimeoutMs: number;
   config: QQBotAccountConfig;
 }
 
@@ -148,6 +153,17 @@ export interface QQBotAccountConfig {
    * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
    */
   stt?: STTChannelConfig;
+  /**
+   * 单条消息最大处理时间（毫秒）。
+   * 超时后 concurrencyGuard 会 abort 处理链（取消 LLM 调用、工具执行等），
+   * 释放并发锁并排空缓冲消息。
+   *
+   * 设为 0 表示不限制超时。默认 0（不限制）。
+   *
+   * 可通过环境变量 OPENCLAW_PROCESSING_TIMEOUT_MS 覆盖全局默认值，
+   * 账户级配置优先级高于环境变量。
+   */
+  processingTimeoutMs?: number;
   /**
    * User-Agent 尾部追加内容（用于私有化部署标识等场景）
    * 追加在 `QQBotPlugin/{version} (Node/{nodeVersion}; {os}; OpenClaw/{version})` 之后

package/src/utils/ssrf-guard.ts

@@ -48,13 +48,40 @@ export function isReservedAddr(ip: string): boolean {
 
 const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
 
+/** QQ 官方媒体/API 域名白名单，匹配时跳过 DNS 解析检查 */
+const QQ_TRUSTED_DOMAINS = new Set([
+  // QQ Bot API
+  "api.sgroup.qq.com",
+  "sandbox.api.sgroup.qq.com",
+  // QQ Bot Token
+  "bots.qq.com",
+  // QQ 多媒体上传/下载
+  "multimedia.nt.qq.com.cn",
+  "multimedia.nt.qq.com",
+  // QQ 群文件
+  "grouppro.grouppro.qq.com",
+]);
+
+/** 检查 hostname 是否匹配 QQ 白名单（支持子域名通配 *.example.com） */
+function isQQTrustedDomain(hostname: string): boolean {
+  if (QQ_TRUSTED_DOMAINS.has(hostname)) return true;
+  // 检查一级子域名：*.multimedia.nt.qq.com.cn
+  const dot = hostname.indexOf('.');
+  if (dot > 0) {
+    const parent = hostname.slice(dot + 1);
+    return QQ_TRUSTED_DOMAINS.has(parent);
+  }
+  return false;
+}
+
 /**
  * 校验远程 URL 是否可安全请求。
  *
  * 规则：
  * 1. 仅放行 http / https 协议
- * 2. 若 URL 直接携带 IP 则即时判定
- * 3. 若为域名则先做 DNS 解析，逐条检查解析结果
+ * 2. QQ 白名单域名直接放行（免 DNS 解析）
+ * 3. 若 URL 直接携带 IP 则即时判定
+ * 4. 若为域名则先做 DNS 解析，逐条检查解析结果
  *
  * @throws {Error} 当 URL 指向受限地址时
  */
@@ -70,6 +97,9 @@ export async function validateRemoteUrl(raw: string): Promise<void> {
   // 去掉 IPv6 方括号
   const host = url.hostname.replace(/^\[|\]$/g, "");
 
+  // QQ 官方域名 → 免 DNS 检查直接放行
+  if (isQQTrustedDomain(host)) return;
+
   if (net.isIP(host)) {
     assertPublicAddr(host, raw);
     return;

package/skills/qqbot-group/SKILL.md

@@ -1,75 +0,0 @@
----
-name: qqbot-group
-description: QQ 群管理技能。查询群基础信息、群成员信息、机器人群内状态。使用 qqbot_platform_api 工具调用接口，自动鉴权。当用户需要查询群信息、查看群成员、检查机器人群内状态时使用此技能。
-metadata: {"openclaw":{"emoji":"👥","requires":{"config":["channels.qqbot"]}}}
----
-
-# QQ 群 API 请求指导
-
-通过 `qqbot_platform_api` 工具调用群相关接口，鉴权由工具自动处理。
-
-详细字段说明见 `references/api_reference.md`。
-
----
-
-## ⭐ 接口速查
-
-| 操作 | 方法 | 路径 |
-|------|------|------|
-| 获取机器人群内状态 | `GET` | `/v2/groups/{group_id}/bot_state` |
-| 获取群成员信息 | `GET` | `/v2/groups/{group_id}/members/{member_id}` |
-| 获取群基础信息 | `GET` | `/v2/groups/{group_id}/info` |
-
----
-
-## 💡 调用示例
-
-### 获取机器人群内状态
-
-```json
-{
-  "method": "GET",
-  "path": "/v2/groups/G_123456789/bot_state"
-}
-```
-
-返回字段：`joined_at`（入群时间）、`allow_proactive_msg`（是否允许主动推送）、`recv_msg_setting`（`all`/`only_mention`/`mention_and_context`）、`member_role`（`member`/`owner`/`admin`）。
-
-### 获取群成员信息
-
-```json
-{
-  "method": "GET",
-  "path": "/v2/groups/G_123456789/members/o_xxxxxxxx"
-}
-```
-
-返回字段：`username`（昵称）、`member_role`、`joined_at`、`bot` 等。昵称仅在单个查询时返回。
-
-### 获取群基础信息
-
-```json
-{
-  "method": "GET",
-  "path": "/v2/groups/G_123456789/info"
-}
-```
-
-返回字段：`group_name`、`group_finger_memo`（简介）、`group_class_text`（分类）、`group_tags`（标签）、`group_member_num`（成员数）。
-
----
-
-## 💬 @群成员
-
-发送消息时使用 `<@member_id>` 语法 @指定群成员：
-
-- 格式：`<@member_id>`，例如 `<@o_xxxxxxxx>`
-- 文本消息中直接拼接即可：`你好 <@o_xxxxxxxx>，欢迎入群！`
-
----
-
-## ⚠️ 注意事项
-
-1. 路径占位符 `{group_id}`、`{member_id}` 需替换为实际值
-2. 返回时间格式为 RFC3339（如 `2026-06-23T22:03:09+08:00`）
-3. 群 openid 与频道 guild_id 是不同的概念，不要混淆

package/skills/qqbot-group/references/api_reference.md

@@ -1,94 +0,0 @@
-# QQ 开放平台群接口参考
-
-> 鉴权和请求头由 `qqbot_platform_api` 工具自动处理，无需手动管理。
-
----
-
-## 接口列表
-
-### 1. 获取机器人群内状态
-
-- 方法：`GET`
-- 路径：`/v2/groups/{group_id}/bot_state`
-
-响应参数：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| joined_at | string | 入群时间（RFC3339 格式） |
-| allow_proactive_msg | bool | 是否允许主动消息推送 |
-| recv_msg_setting | string | 接收消息设置：`all`、`only_mention`、`mention_and_context` |
-| member_role | string | 群成员角色：`member`、`owner`、`admin` |
-
-响应示例：
-
-```json
-{
-  "join_timestamp": "2026-06-23T22:03:09+08:00",
-  "allow_proactive_msg": true,
-  "recv_msg_setting": "all",
-  "member_role": "admin"
-}
-```
-
----
-
-### 2. 获取群成员信息
-
-- 方法：`GET`
-- 路径：`/v2/groups/{group_id}/members/{member_id}`
-
-响应参数：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| union_openid | string | 用户在应用/开放平台下的统一标识 |
-| user_openid | string | 用户 openid |
-| username | string | 用户昵称（仅单个查询时返回） |
-| member_role | string | 群成员角色：`member`、`owner`、`admin` |
-| joined_at | string | 入群时间（RFC3339 格式） |
-| bot | bool | 是否为机器人账号 |
-
-响应示例：
-
-```json
-{
-  "union_openid": "u_xxxxxxxx",
-  "user_openid": "o_xxxxxxxx",
-  "username": "张三",
-  "member_role": "member",
-  "joined_at": "2026-06-23T22:03:09+08:00",
-  "bot": false
-}
-```
-
----
-
-### 3. 获取群基础信息
-
-- 方法：`GET`
-- 路径：`/v2/groups/{group_id}/info`
-
-响应参数：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| group_openid | string | 群 openid |
-| group_name | string | 群名称 |
-| group_finger_memo | string | 群简介/群公告 |
-| group_class_text | string | 群分类文案 |
-| group_tags | array[] | 群标签列表 |
-| group_member_num | int | 群成员数量 |
-
-响应示例：
-
-```json
-{
-  "group_openid": "G_123456789",
-  "group_name": "技术交流群",
-  "group_finger_memo": "专注于后端技术开发交流",
-  "group_class_text": "技术-后端开发",
-  "group_tags": ["技术交流", "后端开发", "QQ机器人"],
-  "group_member_num": 1250
-}
-```