@jerryliang122/openclaw-qqbot 1.0.8 → 2.0.0

package/dist/index.d.cts

@@ -203,8 +203,9 @@ interface QQBotAccountConfig {
         sendMode?: 'stream' | 'static';
     };
     /**
-     * STT (语音转文字) 配置
-     * 配置后，收到语音消息时会自动调用 STT 服务转录为文字
+     * STT (语音转文字) 行为开关
+     * 转录凭证统一走框架 tools.media.audio.models；
+     * 框架未配置时直接使用 QQ 平台转写（asr_refer_text）
      */
     stt?: STTChannelConfig;
     /**
@@ -289,17 +290,30 @@ interface AudioFormatPolicy {
 }
 /**
  * STT (语音转文字) 配置
+ *
+ * 2026-10 起转录统一走框架音频理解管线（tools.media.audio.models 凭证），
+ * 本块只保留行为开关；旧凭证键已废弃（检测到会打迁移提示日志）。
+ * 框架 STT 未配置时，QQ 平台转写（asr_refer_text）直接作为唯一来源。
  */
 interface STTChannelConfig {
-    /** 是否启用 STT（默认 true，配置了 baseUrl+apiKey 即自动启用） */
+    /**
+     * 是否启用框架 STT 转录（默认 true）。
+     * false = 不调用外部 STT，语音只用平台转写（或无转写时占位文本）。
+     */
     enabled?: boolean;
-    /** STT 服务提供商 ID（对应 models.providers 中的 key，默认 "openai"） */
+    /**
+     * 平台转写（asr_refer_text）参与开关。默认参与：
+     * 框架 STT 未配置时直接作为唯一来源，STT 失败/为空时兜底。
+     * 设为 false 恢复严格模式——所有场景丢弃平台转写。
+     */
+    asrFallback?: boolean;
+    /** @deprecated 2026-10 起忽略——STT 凭证统一配置在框架 tools.media.audio.models */
     provider?: string;
-    /** STT API 地址（如 https://api.openai.com/v1） */
+    /** @deprecated 同上 */
     baseUrl?: string;
-    /** STT API 密钥 */
+    /** @deprecated 同上 */
     apiKey?: string;
-    /** STT 模型名称（默认 "whisper-1"） */
+    /** @deprecated 同上 */
     model?: string;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jerryliang122/openclaw-qqbot",
-  "version": "1.0.8",
+  "version": "2.0.0",
   "description": "QQ Bot channel plugin for OpenClaw (independently maintained fork)",
   "publishConfig": {
     "access": "public",

package/src/middleware/attachment.ts

@@ -15,7 +15,7 @@ import {
   isVoiceAttachment,
 } from '@tencent-connect/qqbot-nodejs/protocol';
 import type { MessageAttachment } from '../types.js';
-import { transcribeAudio, resolveSTTConfig, shouldUsePlatformAsr } from '../utils/stt.js';
+import { shouldUsePlatformAsr, isFrameworkSttConfigured, hasLegacySttCredentials, transcribeAudioViaFramework } from '../utils/stt.js';
 import { formatVoiceText, formatDuration, type VoiceTranscript, type TranscriptSource } from '../utils/voice-text.js';
 import { downloadRemoteMedia } from '../adapter/media.js';
 import { getAdapters } from '../adapter/resolve.js';
@@ -96,8 +96,9 @@ export async function processAttachments(
   cfg: Record<string, unknown>,
   log?: Log,
 ): Promise<ProcessedAttachments> {
-  const sttCfg = resolveSTTConfig(cfg);
   const usePlatformAsr = shouldUsePlatformAsr(cfg);
+  const sttConfigured = isFrameworkSttConfigured(cfg);
+  warnLegacySttCredentials(cfg, log);
   const audioPolicy = resolveAudioPolicy(cfg);
 
   const imageUrls: string[] = [];
@@ -120,7 +121,7 @@ export async function processAttachments(
     }
 
     if (isVoice) {
-      const transcript = await processVoiceAttachment(att, sttCfg, usePlatformAsr, audioPolicy, log);
+      const transcript = await processVoiceAttachment(att, cfg, usePlatformAsr, sttConfigured, audioPolicy, log);
       return { type: 'voice' as const, transcript };
     }
 
@@ -208,29 +209,42 @@ function kindFromContentType(contentType: string | undefined): InboundMediaEntry
 
 // ── 语音处理 ──
 
+/** 废弃插件级 STT 凭证的一次性迁移提示（每进程一条，避免每条语音刷屏） */
+let legacySttWarned = false;
+
+function warnLegacySttCredentials(cfg: Record<string, unknown>, log?: Log): void {
+  if (!legacySttWarned && hasLegacySttCredentials(cfg)) {
+    legacySttWarned = true;
+    log?.info(
+      'Voice: channels.qqbot.stt credentials (provider/baseUrl/apiKey/model) are deprecated and ignored; ' +
+        'configure tools.media.audio.models instead — platform asr_refer_text is used when framework STT is absent',
+    );
+  }
+}
+
 async function processVoiceAttachment(
   att: MessageAttachment,
-  sttCfg: ReturnType<typeof resolveSTTConfig>,
+  cfg: Record<string, unknown>,
   usePlatformAsr: boolean,
+  sttConfigured: boolean,
   audioPolicy: AudioPolicyResolved,
   log?: Log,
 ): Promise<VoiceTranscript> {
-  // 平台转写（asr_refer_text）仅在显式 asrFallback: true 时参与；
-  // 缺省/false 时在所有场景下丢弃——包括 STT 未配置（语音落占位文本）
-  // 与 STT 失败（不当兜底），三条泄漏路径（转写成功携带 / 转写失败回退 /
-  // 下载失败回退）一并堵死。
+  // 平台转写（asr_refer_text，QQ 平台自动 STT 随事件 JSON 下发）：
+  // 默认参与——框架 STT 未配置时直接作为唯一来源，STT 失败时兜底；
+  // 仅 asrFallback: false（严格模式）时在所有场景丢弃。
   const rawAsrText = att.asr_refer_text?.trim() || undefined;
   const asrReferText = usePlatformAsr ? rawAsrText : undefined;
   // 远端 URL 兜底：优先 wav_url，其次原始 url
   const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || undefined;
 
-  // STT 未配置：占位文本；显式 asrFallback: true 时退回平台转写
-  if (!sttCfg) {
+  // 框架 STT 未配置 → 平台转写直接作为 transcript（无下载、无外部调用）
+  if (!sttConfigured) {
     if (!usePlatformAsr && rawAsrText) {
-      log?.info(`Voice: STT not configured; platform asr_refer_text discarded (asrFallback not enabled)`);
+      log?.info(`Voice: framework STT not configured; platform asr_refer_text discarded (asrFallback: false)`);
     }
     if (asrReferText) {
-      log?.debug?.(`Voice: using asr_refer_text (STT not configured, asrFallback enabled)`);
+      log?.debug?.(`Voice: using platform asr_refer_text (framework STT not configured)`);
       return { text: asrReferText, source: 'asr', asrReferText, remoteUrl };
     }
     return {
@@ -281,17 +295,18 @@ async function processVoiceAttachment(
 
   if (localPath) {
     try {
-      const transcript = await transcribeAudio(localPath, cfg2stt(sttCfg));
+      const transcript = await transcribeAudioViaFramework(localPath, cfg);
       if (transcript) {
-        log?.debug?.(`Voice STT: ${transcript.slice(0, 80)}...`);
+        log?.debug?.(`Voice STT (framework): ${transcript.slice(0, 80)}...`);
         return { text: transcript, source: 'stt', duration, localPath, remoteUrl, asrReferText };
       }
     } catch (err) {
-      log?.error(`Voice STT failed: ${err instanceof Error ? err.message : String(err)}`);
+      log?.error(`Voice STT (framework) failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 
   if (asrReferText) {
+    log?.debug?.(`Voice: falling back to platform asr_refer_text after framework STT failure`);
     return { text: asrReferText, source: 'asr', duration, localPath, remoteUrl, asrReferText };
   }
 
@@ -334,10 +349,6 @@ function normalizeFormats(formats: string[]): string[] {
   });
 }
 
-function cfg2stt(sttCfg: NonNullable<ReturnType<typeof resolveSTTConfig>>): Record<string, unknown> {
-  return { channels: { qqbot: { stt: sttCfg } } };
-}
-
 // ── 文件工具 ──
 
 function normalizeUrl(url: string | undefined): string {

package/src/openclaw-plugin-sdk.d.ts

@@ -77,6 +77,32 @@ declare module "openclaw/plugin-sdk" {
     execute: (toolCallId: string, params: unknown) => Promise<AgentToolResult> | AgentToolResult;
   }
 
+  /**
+   * 工具工厂上下文（registerTool 工厂形式）
+   *
+   * 框架在装配当前 run 的工具面（或缓存描述符路径下的每次执行）时调用
+   * 工厂，ctx 携带 run 级会话信息——其中 deliveryContext 是框架按当前
+   * run 的 sessionCtx 派生的可信投递路由（2026-09-23 修复：延迟/排队
+   * turn 中 ALS 请求上下文失效时，工具由此回退解析会话目标）。
+   * 仅声明本项目实际使用的字段，其余字段经索引签名透传。
+   */
+  export interface PluginToolFactoryContext {
+    config?: OpenClawConfig;
+    runtimeConfig?: OpenClawConfig;
+    agentId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    messageChannel?: string;
+    agentAccountId?: string;
+    /** 可信投递路由：{ channel, to, accountId, threadId? } */
+    deliveryContext?: { channel?: string; to?: string; accountId?: string; threadId?: string };
+    /** 当前入站 turn 的平台原生会话 ID */
+    nativeChannelId?: string;
+    /** 当前入站 turn 的发送者 ID（运行时提供，非工具参数） */
+    requesterSenderId?: string;
+    [key: string]: unknown;
+  }
+
   /**
    * Tool 注册选项
    */
@@ -103,8 +129,18 @@ declare module "openclaw/plugin-sdk" {
     };
     /** 注册频道 */
     registerChannel<TAccount = unknown>(options: { plugin: ChannelPlugin<TAccount> }): void;
-    /** 注册工具 */
-    registerTool(tool: AnyAgentTool, opts?: ToolRegistrationOptions): void;
+    /**
+     * 注册工具。支持两种形式：
+     * - 静态定义（AnyAgentTool）
+     * - 工厂函数：每次工具装配/执行时由框架调用，ctx 携带 run 级
+     *   deliveryContext 等会话信息（推荐需要感知当前会话的工具使用）
+     */
+    registerTool(
+      tool:
+        | AnyAgentTool
+        | ((ctx: PluginToolFactoryContext) => AnyAgentTool | AnyAgentTool[] | null | undefined),
+      opts?: ToolRegistrationOptions,
+    ): void;
     /** 其他 API 方法 */
     [key: string]: unknown;
   }

package/src/tools/platform.ts

@@ -1,8 +1,8 @@
 import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
 import { listQQBotAccountIds } from '../config.js';
-import { getBotForAccount } from '../bot-instance.js';
-import { getRequestAccountId } from '../request-context.js';
+import { resolveGatewayForSend } from '../outbound/outbound-service.js';
 import { createPluginLogger } from '../utils/plugin-logger.js';
+import { resolveToolSessionRoute, type ToolDeliveryContext } from './tool-session.js';
 
 // 工具 execute 无 logger 参数；request-context 活跃期间 enrichMeta
 // 自动带上 accountId/openId/messageId
@@ -71,6 +71,8 @@ function validatePath(path: string): string | null {
  *  - 频道（Guild/Channel/Member/Announce/Forum/Schedule）→ 见 qqbot-channel skill
  *  - 群（Group/Member）→ 见 qqbot-group skill
  */
+// 工厂注册形式（2026-09-23 修复）：turn 被框架延迟/排队执行（ALS 失效）时，
+// 从 deliveryContext 回退解析账户（见 tool-session.ts）。
 export function registerPlatformTool(api: OpenClawPluginApi): void {
   const cfg = api.config;
   if (!cfg) return;
@@ -79,78 +81,90 @@ export function registerPlatformTool(api: OpenClawPluginApi): void {
   if (accountIds.length === 0) return;
 
   api.registerTool(
-    {
-      name: 'qqbot_platform_api',
-      label: 'QQBot Platform API Gateway',
-      description:
-        'QQ 开放平台统一 HTTP API 网关，自动填充鉴权 Token。' +
-        '常用接口速查：' +
-        '【频道】GET /users/@me/guilds | /guilds/{guild_id}/channels | /channels/{channel_id} | ' +
-        '【群】GET /v2/groups/{group_id}/bot_state | /v2/groups/{group_id}/members/{member_id} | /v2/groups/{group_id}/info。' +
-        '更多接口和参数详情请阅读 qqbot-channel 和 qqbot-group skill。',
-      parameters: PlatformApiSchema,
-      async execute(_toolCallId, params) {
-        const p = params as {
-          method: string;
-          path: string;
-          body?: Record<string, unknown>;
-          query?: Record<string, string>;
-        };
-
-        if (!p.method) return json({ error: 'method 为必填参数' });
-        if (!p.path) return json({ error: 'path 为必填参数' });
-
-        const method = p.method.toUpperCase();
-        if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
-          return json({ error: `不支持的 HTTP 方法: ${method}` });
-        }
-
-        const pathError = validatePath(p.path);
-        if (pathError) return json({ error: pathError });
-
-        const accountId = getRequestAccountId();
-        if (!accountId) {
-          return json({ error: '无法获取当前请求的账号信息，此工具仅支持在消息会话中使用' });
-        }
-
-        try {
-          const bot = getBotForAccount(accountId);
-          const apiGateway = bot.api;
-          const startedAt = Date.now();
-
-          let data: unknown;
-          switch (method) {
-            case 'GET':
-              data = await apiGateway.get(p.path, p.query);
-              break;
-            case 'POST':
-              data = await apiGateway.post(p.path, p.body);
-              break;
-            case 'PUT':
-              data = await apiGateway.put(p.path, p.body);
-              break;
-            case 'PATCH':
-              data = await apiGateway.patch(p.path, p.body);
-              break;
-            case 'DELETE':
-              data = await apiGateway.delete(p.path);
-              break;
+    (factoryCtx) => {
+      const delivery = (factoryCtx as { deliveryContext?: ToolDeliveryContext }).deliveryContext;
+      return {
+        name: 'qqbot_platform_api',
+        label: 'QQBot Platform API Gateway',
+        description:
+          'QQ 开放平台统一 HTTP API 网关，自动填充鉴权 Token。' +
+          '常用接口速查：' +
+          '【频道】GET /users/@me/guilds | /guilds/{guild_id}/channels | /channels/{channel_id} | ' +
+          '【群】GET /v2/groups/{group_id}/bot_state | /v2/groups/{group_id}/members/{member_id} | /v2/groups/{group_id}/info。' +
+          '更多接口和参数详情请阅读 qqbot-channel 和 qqbot-group skill。',
+        parameters: PlatformApiSchema,
+        async execute(_toolCallId: string, params: unknown) {
+          const p = params as {
+            method: string;
+            path: string;
+            body?: Record<string, unknown>;
+            query?: Record<string, string>;
+          };
+
+          if (!p.method) return json({ error: 'method 为必填参数' });
+          if (!p.path) return json({ error: 'path 为必填参数' });
+
+          const method = p.method.toUpperCase();
+          if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+            return json({ error: `不支持的 HTTP 方法: ${method}` });
+          }
+
+          const pathError = validatePath(p.path);
+          if (pathError) return json({ error: pathError });
+
+          // 会话路由：ALS 优先，deliveryContext 回退（延迟/排队 turn）
+          const route = resolveToolSessionRoute(delivery);
+          if (!route) {
+            return json({
+              error:
+                '当前运行没有 QQ 会话来源（可能由定时任务或框架内部触发的 run），' +
+                '无法确定调用哪个 QQ Bot 账户。请在 QQ 消息会话中使用本工具。',
+            });
           }
 
-          toolLog.info(`${method} ${p.path} ok (${Date.now() - startedAt}ms)`, { accountId });
-          return json(data);
-        } catch (err: unknown) {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
-          toolLog.warn(`${method} ${p.path} failed status=${apiErr.httpStatus ?? '?'} code=${apiErr.bizCode ?? '?'}: ${errMsg}`, { accountId });
-          return json({
-            error: errMsg,
-            status: apiErr.httpStatus,
-            code: apiErr.bizCode,
-            path: p.path,
-          });
-        }
-      },
+          try {
+            const resolvedGateway = resolveGatewayForSend(route.accountId ?? 'default');
+            if (!resolvedGateway) {
+              return json({ error: `账户 ${route.accountId ?? 'default'} 的 gateway 尚未启动` });
+            }
+            const bot = resolvedGateway.gw.bot;
+            const apiGateway = bot.api;
+            const startedAt = Date.now();
+
+            let data: unknown;
+            switch (method) {
+              case 'GET':
+                data = await apiGateway.get(p.path, p.query);
+                break;
+              case 'POST':
+                data = await apiGateway.post(p.path, p.body);
+                break;
+              case 'PUT':
+                data = await apiGateway.put(p.path, p.body);
+                break;
+              case 'PATCH':
+                data = await apiGateway.patch(p.path, p.body);
+                break;
+              case 'DELETE':
+                data = await apiGateway.delete(p.path);
+                break;
+            }
+
+            toolLog.info(`${method} ${p.path} ok (${Date.now() - startedAt}ms)`, { accountId: resolvedGateway.accountId });
+            return json(data);
+          } catch (err: unknown) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
+            toolLog.warn(`${method} ${p.path} failed status=${apiErr.httpStatus ?? '?'} code=${apiErr.bizCode ?? '?'}: ${errMsg}`, { accountId: route.accountId ?? 'default' });
+            return json({
+              error: errMsg,
+              status: apiErr.httpStatus,
+              code: apiErr.bizCode,
+              path: p.path,
+            });
+          }
+        },
+      };
     },
     { name: 'qqbot_platform_api' },
   );

package/src/tools/remind.ts

@@ -1,5 +1,5 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { getRequestTarget, getRequestAccountId } from "../request-context.js";
+import { resolveToolSessionRoute, type ToolDeliveryContext } from "./tool-session.js";
 
 // ========== 类型定义 ==========
 
@@ -218,52 +218,62 @@ function formatDelay(ms: number): string {
 
 // ========== 注册入口 ==========
 
+// 工厂注册形式（2026-09-23 修复）：turn 被框架延迟/排队执行（ALS 失效）时，
+// 从 deliveryContext 回退解析投递目标（见 tool-session.ts）。
 export function registerRemindTool(api: OpenClawPluginApi): void {
   api.registerTool(
-    {
-      name: "qqbot_remind",
-      label: "QQBot 定时提醒",
-      description:
-        "创建、查询、删除 QQ 定时提醒。" +
-        "使用简单参数即可，无需手动构造 cron JSON。\n" +
-        "创建提醒：action=add, content=提醒内容, to=目标地址, time=时间\n" +
-        "查看提醒：action=list\n" +
-        "删除提醒：action=remove, jobId=任务ID（先 list 获取）\n" +
-        "时间格式示例：\"5m\"(5分钟后) \"1h\"(1小时后) \"0 8 * * *\"(每天8点)",
-      parameters: RemindSchema,
-      execute(_toolCallId, params) {
-        const p = params as RemindParams;
+    (factoryCtx) => {
+      const delivery = (factoryCtx as { deliveryContext?: ToolDeliveryContext }).deliveryContext;
+      return {
+        name: "qqbot_remind",
+        label: "QQBot 定时提醒",
+        description:
+          "创建、查询、删除 QQ 定时提醒。" +
+          "使用简单参数即可，无需手动构造 cron JSON。\n" +
+          "创建提醒：action=add, content=提醒内容, to=目标地址, time=时间\n" +
+          "查看提醒：action=list\n" +
+          "删除提醒：action=remove, jobId=任务ID（先 list 获取）\n" +
+          "时间格式示例：\"5m\"(5分钟后) \"1h\"(1小时后) \"0 8 * * *\"(每天8点)",
+        parameters: RemindSchema,
+        async execute(_toolCallId: string, params: unknown) {
+          const p = params as RemindParams;
 
-        // ===== list =====
-        if (p.action === "list") {
-          return json({
-            _instruction: "请立即使用 cron 工具执行以下参数",
-            cronParams: { action: "list" },
-          });
-        }
+          // ===== list =====
+          if (p.action === "list") {
+            return json({
+              _instruction: "请立即使用 cron 工具执行以下参数",
+              cronParams: { action: "list" },
+            });
+          }
 
-        // ===== remove =====
-        if (p.action === "remove") {
-          if (!p.jobId) {
-            return json({ error: "action=remove 时 jobId 为必填参数。请先用 action=list 获取 jobId。" });
+          // ===== remove =====
+          if (p.action === "remove") {
+            if (!p.jobId) {
+              return json({ error: "action=remove 时 jobId 为必填参数。请先用 action=list 获取 jobId。" });
+            }
+            return json({
+              _instruction: "请立即使用 cron 工具执行以下参数",
+              cronParams: { action: "remove", jobId: p.jobId },
+            });
           }
-          return json({
-            _instruction: "请立即使用 cron 工具执行以下参数",
-            cronParams: { action: "remove", jobId: p.jobId },
-          });
-        }
 
-        // ===== add =====
-        if (!p.content) {
-          return json({ error: "action=add 时 content（提醒内容）为必填参数" });
-        }
-        // 优先使用 AI 传入的 to，否则自动从请求级上下文获取（AsyncLocalStorage）
-        const resolvedTo = p.to || getRequestTarget();
-        if (!resolvedTo) {
-          return json({ error: "action=add 时无法确定投递目标地址。请稍后重试。" });
-        }
-        // 从请求上下文获取当前账户 ID（多账户场景），fallback 到 "default"
-        const resolvedAccountId = getRequestAccountId() || "default";
+          // ===== add =====
+          if (!p.content) {
+            return json({ error: "action=add 时 content（提醒内容）为必填参数" });
+          }
+          // 优先使用 AI 传入的 to；否则双层解析当前会话路由：
+          // ALS 请求级上下文优先，框架 run 级 deliveryContext 回退
+          const route = resolveToolSessionRoute(delivery);
+          const resolvedTo = p.to || route?.target;
+          if (!resolvedTo) {
+            return json({
+              error:
+                "action=add 时无法确定投递目标地址（当前 run 无 QQ 会话来源）。" +
+                '请显式传入 to（格式：qqbot:c2c:user_openid 或 qqbot:group:group_openid）后重试。',
+            });
+          }
+          // 账户 ID：会话路由优先，fallback 到 "default"
+          const resolvedAccountId = route?.accountId || "default";
         if (!p.time) {
           return json({ error: "action=add 时 time（时间）为必填参数。示例：\"5m\"、\"1h30m\"、\"0 8 * * *\"" });
         }
@@ -299,7 +309,8 @@ export function registerRemindTool(api: OpenClawPluginApi): void {
           cronParams: onceJob,
           summary: `⏰ ${formatDelay(delayMs)}后提醒: "${p.content}"`,
         });
-      },
+        },
+      };
     },
     { name: "qqbot_remind" },
   );