@jerryliang122/openclaw-qqbot 1.0.4 → 1.0.6

package/dist/index.d.cts

@@ -860,8 +860,13 @@ declare class StreamingController {
     private session;
     /** QQ 已接受的最新文本 — 单源真理 */
     private lastAcceptedFull;
-    /** 已成功发送的分片数（降级：=0 则走静态消息兜底） */
+    /** 已成功发送的分片数（降级：=0 且无外部投递则走静态消息兜底） */
     private sentChunkCount;
+    /**
+     * 标记：内容已通过非流式通道成功投递（如 ask_user 按钮卡片）。
+     * 置 true 后 handleFinalize 不再走 fallback 路径，避免框架误报 outcome=error。
+     */
+    private _deliveredExternally;
     /** 同步标志：收到第一个 onPartialReply 即置 true（不等 async 完成） */
     private _hasStarted;
     /** 串行队列 */
@@ -882,6 +887,11 @@ declare class StreamingController {
     get hasStarted(): boolean;
     get isTerminal(): boolean;
     get shouldFallbackToStatic(): boolean;
+    /**
+     * 告知控制器内容已通过外部通道投递（如 ask_user 卡片）。
+     * 后续 finalize() 不会走 fallback 路径，框架不会误报 outcome=error。
+     */
+    markDeliveredExternally(): void;
     onPartialReply(text: string): Promise<void>;
     finalize(): Promise<void>;
     /**
@@ -950,6 +960,11 @@ declare function resolveQQBotEnvClientSecret(): string;
 declare function listQQBotAccountIds(cfg: OpenClawConfig): string[];
 /**
  * 获取默认账户 ID
+ *
+ * 优先返回「可运行」的账号：
+ *   1. 顶层 default 账号可运行（appId + 凭证来源 + enabled）→ default
+ *   2. 否则第一个可运行的命名账号（accounts.<id>）
+ *   3. 都不可运行 → 保持旧行为返回 default（错误信息指向配置根因）
  */
 declare function resolveDefaultQQBotAccountId(cfg: OpenClawConfig): string;
 /**

package/package.json

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

package/src/config.ts

@@ -1,5 +1,6 @@
 import type { ResolvedQQBotAccount, QQBotAccountConfig, ToolPolicy, GroupConfig, GroupCoalesceConfig } from "./types.js";
 import type { OpenClawConfig, GroupPolicy } from "openclaw/plugin-sdk";
+import { loadCredentialBackup } from "./features/credential-backup.js";
 
 // ============ Agent-aware mentionPatterns 解析 ============
 
@@ -248,22 +249,81 @@ export function listQQBotAccountIds(cfg: OpenClawConfig): string[] {
   return Array.from(ids);
 }
 
+/**
+ * 判断一个账号形状是否「可运行」：配置内声明了 appId、未被禁用，且任一
+ * 凭证来源可用（配置内 secret / secretFile / 环境变量 / 凭证暂存备份）。
+ *
+ * appId 必须来自配置——listQQBotAccountIds 只枚举配置里有 appId 的账号，
+ * 框架据此决定启动哪些账号；备份只能补 secret（appId 在、secret 丢的
+ * 恢复场景，lifecycle 启动时会用备份恢复），不能让一个未被枚举、根本
+ * 不会被启动的账号被选为默认（Sourcery 复审：选中≠可运行）。
+ *
+ * 用于默认账号解析——只看 appId 是否存在会把已登出（secret 被删、appId 残留）
+ * 或停用的顶层账号当成默认账号，导致 message 工具等框架侧主动发送解析到
+ * 一个永远不会启动的账号（issue #15：Bot "default" not running）。
+ */
+function accountShapeRunnable(params: {
+  appId: string;
+  enabled: boolean;
+  hasSecretSource: boolean;
+  accountId: string;
+}): boolean {
+  if (!params.appId || !params.enabled) return false;
+  if (params.hasSecretSource) return true;
+  // 配置缺 secret 但备份可恢复（appId 已在配置内，账号会被枚举启动）
+  try {
+    return loadCredentialBackup(params.accountId) !== null;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * 获取默认账户 ID
+ *
+ * 优先返回「可运行」的账号：
+ *   1. 顶层 default 账号可运行（appId + 凭证来源 + enabled）→ default
+ *   2. 否则第一个可运行的命名账号（accounts.<id>）
+ *   3. 都不可运行 → 保持旧行为返回 default（错误信息指向配置根因）
  */
 export function resolveDefaultQQBotAccountId(cfg: OpenClawConfig): string {
   const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
-  // 如果有默认账户配置，返回 default
+
+  // 1. 如果默认账户可运行，返回 default
   if (qqbot?.appId || resolveQQBotEnvAppId()) {
-    return DEFAULT_ACCOUNT_ID;
+    const runnable = accountShapeRunnable({
+      appId: normalizeAppId(qqbot?.appId) || normalizeAppId(resolveQQBotEnvAppId()),
+      enabled: qqbot?.enabled !== false,
+      hasSecretSource: Boolean(
+        qqbot?.clientSecret
+        || qqbot?.clientSecretFile
+        || resolveQQBotEnvClientSecret(),
+      ),
+      accountId: DEFAULT_ACCOUNT_ID,
+    });
+    if (runnable) return DEFAULT_ACCOUNT_ID;
   }
-  // 否则返回第一个配置的账户
+
+  // 2. 否则返回第一个可运行的命名账户
   if (qqbot?.accounts) {
+    for (const [accountId, account] of Object.entries(qqbot.accounts)) {
+      if (!account) continue;
+      const runnable = accountShapeRunnable({
+        appId: normalizeAppId(account.appId),
+        enabled: account.enabled !== false,
+        hasSecretSource: Boolean(account.clientSecret || account.clientSecretFile),
+        accountId,
+      });
+      if (runnable) return accountId;
+    }
+    // 兼容旧形态：命名账号均无 appId（凭 backup 恢复）时保持原顺序返回第一个
     const ids = Object.keys(qqbot.accounts);
-    if (ids.length > 0) {
+    if (ids.length > 0 && ids.every((id) => !qqbot.accounts?.[id]?.appId)) {
       return ids[0];
     }
   }
+
+  // 3. 旧回退
   return DEFAULT_ACCOUNT_ID;
 }
 

package/src/dispatch/dispatch.ts

@@ -298,6 +298,8 @@ export async function dispatchToOpenClaw(
             try {
               await bot.sendTextWithKeyboard(replyTarget, text, keyboard as never);
               outboundSendOk++;
+              // 标记流式控制器：内容已通过外部通道投递，finalize 不走 fallback
+              streamingController?.markDeliveredExternally();
               dlog?.debug(`[question] sent ask_user with keyboard questionId=${questionId} options=${optionValues.length}`);
               return;
             } catch (err) {
@@ -331,6 +333,8 @@ export async function dispatchToOpenClaw(
                 await bot.sendTextWithKeyboard(replyTarget, cardText, keyboard as never);
                 outboundSendOk++;
               }
+              // 标记流式控制器：内容已通过外部通道投递，finalize 不走 fallback
+              streamingController?.markDeliveredExternally();
               dlog?.debug(`[question] sent multi-question ask_user questionId=${questionId} questions=${questions.length}`);
               return;
             } catch (err) {

package/src/gateway/lifecycle.ts

@@ -184,7 +184,9 @@ export async function stopAccountGracefully(params: {
     }
   }
 
-  unregisterGateway(accountId);
+  // 3. 注销 gateway（带所有权守卫：只删本实例注册的同一个 gw，
+  //    防止延迟 stop 误删新模块实例已注册的替代网关）
+  unregisterGateway(accountId, gw);
 }
 
 /**

package/src/outbound/media-send.ts

@@ -20,7 +20,7 @@ import { tryGetQQBotRuntime } from '../runtime.js';
 import { getAdapters } from '../adapter/resolve.js';
 import type { PluginLogger } from '../utils/plugin-logger.js';
 import { validateRemoteUrl } from '../utils/ssrf-guard.js';
-import { getGateway } from './outbound-service.js';
+import { resolveGatewayForSend, notRunningError } from './outbound-service.js';
 import { parseTarget } from './target.js';
 import { checkAndConsumePassiveReplyQuota } from '../features/quota-manager.js';
 import {
@@ -158,18 +158,21 @@ export async function sendMedia(params: SendMediaParams): Promise<SendMediaResul
     ?? (params.mimeType ? inferMediaKindFromMime(params.mimeType) : undefined)
     ?? inferMediaKind(resolved.path);
 
-  // 3. 获取 gateway
-  const gw = getGateway(accountId);
-  if (!gw) {
-    return { error: `Bot "${accountId}" not running` };
+  // 3. 获取 gateway（带单账号回退：issue #15——message 工具主动发媒体时
+  //    请求键可能解析到未运行的 "default"，单账号部署回退到唯一运行中的网关）。
+  //    配额记账用 resolved.accountId（实际发送账号），见 resolveGatewayForSend 注释。
+  const sendGateway = resolveGatewayForSend(accountId);
+  if (!sendGateway) {
+    return { error: notRunningError(accountId) };
   }
+  const gw = sendGateway.gw;
 
   const target = parseTarget(params.to);
 
   const reservation = params.quotaReserved || !params.replyToId
     ? { canReply: Boolean(params.replyToId), rollback: () => {} }
     : checkAndConsumePassiveReplyQuota({
-        accountId,
+        accountId: sendGateway.accountId,
         msgId: params.replyToId,
         scope: target.scope,
         log,

package/src/outbound/outbound-service.ts

@@ -8,6 +8,7 @@ import * as path from 'node:path';
 import { MediaFileType } from '@tencent-connect/qqbot-nodejs';
 import type { QQBotGateway } from '../gateway/index.js';
 import type { ResolvedQQBotAccount } from '../types.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
 import { parseTarget } from './target.js';
 import {
   checkAndConsumePassiveReplyQuota,
@@ -17,7 +18,41 @@ import {
 
 // ── Gateway 注册表（生命周期由 channel.ts 管理）──
 
-const gateways = new Map<string, QQBotGateway>();
+/**
+ * 进程级注册表桥（issue #15）：
+ *
+ * openclaw 的 message 工具在部分执行上下文（后台任务 / bootstrap 兜底注册表）
+ * 会经 jiti/二次加载产生插件的**另一个模块实例**——模块级 Map 在两个实例里
+ * 各持一份，第二实例的注册表为空，getGateway 恒 miss，主动发送全部报
+ * `Bot "<accountId>" not running`（账号 id 本身解析是对的）。gateway 是
+ * 进程级资源（WebSocket 连接），注册表挂到 globalThis（Symbol.for 跨副本
+ * 共享）让所有模块实例看到同一份。
+ */
+const GATEWAYS_REGISTRY_KEY = Symbol.for('openclaw-qqbot.gateways');
+
+const globalRegistry = globalThis as unknown as Record<symbol, unknown>;
+const gateways: Map<string, QQBotGateway> =
+  (globalRegistry[GATEWAYS_REGISTRY_KEY] as Map<string, QQBotGateway> | undefined) ?? new Map();
+globalRegistry[GATEWAYS_REGISTRY_KEY] = gateways;
+
+// 契约入口（框架直发 / message 工具 / cron）无调用方 logger 可传，
+// 回退日志用模块级 logger 兜底（与 outbound-adapter.ts 的 alog 同模式）。
+// 注意：本模块处于 bot-instance → outbound-service → plugin-logger → runtime
+// → bot-instance 的循环依赖环上，logger 必须惰性创建（顶层求值会在模块
+// 环半初始化状态下崩溃），且日志失败绝不影响发送。
+let svcLog: ReturnType<typeof createPluginLogger> | undefined;
+
+function logFallbackInfo(msg: string): void {
+  try {
+    svcLog ??= createPluginLogger({ prefix: '[outbound]' });
+    svcLog.info(msg);
+  } catch {
+    /* logging must never break sends */
+  }
+}
+
+/** 单账号回退的 INFO 日志去重：每个失效账号键只打一次，避免刷屏 */
+const gatewayFallbackLogged = new Set<string>();
 
 /**
  * 为一次实际 API 调用预留被动回复配额。
@@ -66,7 +101,16 @@ export function registerGateway(accountId: string, gw: QQBotGateway): void {
   gateways.set(accountId, gw);
 }
 
-export function unregisterGateway(accountId: string): void {
+export function unregisterGateway(accountId: string, expectGw?: QQBotGateway): void {
+  if (expectGw) {
+    // 所有权守卫（Sourcery 复审）：仅当注册表里持有的是**本实例注册的同一个
+    // gateway 对象**才注销——旧模块实例延迟执行的 stop 不得删掉新实例已经
+    // 注册的替代网关（共享注册表后，两个实例看到同一份 Map）。
+    if (gateways.get(accountId) !== expectGw) return;
+    gateways.delete(accountId);
+    clearQuotaCacheForAccount(accountId);
+    return;
+  }
   gateways.delete(accountId);
   clearQuotaCacheForAccount(accountId);
 }
@@ -75,6 +119,57 @@ export function getGateway(accountId: string): QQBotGateway | undefined {
   return gateways.get(accountId);
 }
 
+/** 注册表中所有运行中的账号 ID（诊断与单账号回退用） */
+export function getRegisteredAccountIds(): string[] {
+  return [...gateways.keys()];
+}
+
+/**
+ * 发送路径的 gateway 解析（带单账号回退，issue #15）：
+ * - 精确命中 → 直接返回
+ * - 未命中且注册表里恰好只有一个运行中的账号 → 回退到它。单账号部署下
+ *   请求键与注册键不一致只可能来自配置残影（如顶层 appId 残留的 "default"），
+ *   不存在路由歧义；回退仅打一次 INFO 便于事后取证。
+ * - 未命中且运行中账号为 0 或多个 → 返回 undefined 由调用方报错——
+ *   OpenID 跨账号不通用，多账号下盲目回退会把消息发给错误的 bot。
+ *
+ * 返回 `accountId` 为**实际发送账号**（回退时 ≠ 请求键）：被动回复配额是
+ * 平台按「真实发送账号 × msg_id」计的，配额预留/回滚必须用 resolved.accountId
+ * 记账，否则会记到从未发送的账号下（绕过或误伤限额）。
+ */
+export interface ResolvedSendGateway {
+  gw: QQBotGateway;
+  /** 实际发送账号 ID（配额记账键） */
+  accountId: string;
+  /** 回退来源账号键（仅诊断；精确命中时无此字段） */
+  fallbackFrom?: string;
+}
+
+export function resolveGatewayForSend(accountId: string): ResolvedSendGateway | undefined {
+  const gw = gateways.get(accountId);
+  if (gw) return { gw, accountId };
+  const running = getRegisteredAccountIds();
+  if (running.length === 1) {
+    const soleAccountId = running[0];
+    const soleGw = gateways.get(soleAccountId);
+    if (!soleGw) return undefined;
+    if (!gatewayFallbackLogged.has(accountId)) {
+      gatewayFallbackLogged.add(accountId);
+      logFallbackInfo(
+        `account "${accountId}" not running; falling back to sole running account "${soleAccountId}"`,
+      );
+    }
+    return { gw: soleGw, accountId: soleAccountId, fallbackFrom: accountId };
+  }
+  return undefined;
+}
+
+/** "not running" 错误（多账号时附运行中账号列表，便于排障） */
+export function notRunningError(accountId: string): string {
+  const running = getRegisteredAccountIds();
+  return `Bot "${accountId}" not running${running.length ? ` (running accounts: ${running.join(', ')})` : ''}`;
+}
+
 // ── 媒体类型映射 ──
 
 export type MediaKind = 'image' | 'voice' | 'video' | 'file';
@@ -104,17 +199,17 @@ export async function sendText(params: {
   quotaReserved?: boolean;
 }): Promise<SendResult> {
   const accountId = params.account.accountId;
-  const gw = gateways.get(accountId);
-  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const resolved = resolveGatewayForSend(accountId);
+  if (!resolved) return { error: notRunningError(accountId) };
   const target = parseTarget(params.to);
   const reservation = reservePassiveReply({
     replyToId: params.replyToId,
-    accountId,
+    accountId: resolved.accountId,
     scope: target.scope,
     quotaReserved: params.quotaReserved,
   });
   try {
-    const result = await gw.sendText(target, params.text, { msgId: reservation.msgId });
+    const result = await resolved.gw.sendText(target, params.text, { msgId: reservation.msgId });
     return { messageId: result.id };
   } catch (err: unknown) {
     reservation.rollback();
@@ -133,12 +228,12 @@ export async function sendMedia(params: {
   quotaReserved?: boolean;
 }): Promise<SendResult> {
   const accountId = params.account.accountId;
-  const gw = gateways.get(accountId);
-  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const resolved = resolveGatewayForSend(accountId);
+  if (!resolved) return { error: notRunningError(accountId) };
   const target = parseTarget(params.to);
   const reservation = reservePassiveReply({
     replyToId: params.replyToId,
-    accountId,
+    accountId: resolved.accountId,
     scope: target.scope,
     quotaReserved: params.quotaReserved,
   });
@@ -147,19 +242,19 @@ export async function sendMedia(params: {
     const msgId = reservation.msgId;
     if (kind === 'voice') {
       const source = resolveVoiceSource(params.mediaUrl);
-      const result = await gw.sendVoice(target, source, { text: params.text, msgId });
+      const result = await resolved.gw.sendVoice(target, source, { text: params.text, msgId });
       return { messageId: result.id };
     }
     if (kind === 'video') {
-      const result = await gw.sendVideo(target, params.mediaUrl, { text: params.text, msgId });
+      const result = await resolved.gw.sendVideo(target, params.mediaUrl, { text: params.text, msgId });
       return { messageId: result.id };
     }
     if (kind === 'file') {
-      const result = await gw.sendFile(target, params.mediaUrl, { text: params.text, msgId });
+      const result = await resolved.gw.sendFile(target, params.mediaUrl, { text: params.text, msgId });
       return { messageId: result.id };
     }
     const fileType = MEDIA_KIND_TO_FILE_TYPE[kind];
-    const result = await gw.sendMedia(target, params.mediaUrl, { text: params.text, msgId, fileType });
+    const result = await resolved.gw.sendMedia(target, params.mediaUrl, { text: params.text, msgId, fileType });
     return { messageId: result.id };
   } catch (err: unknown) {
     reservation.rollback();
@@ -176,17 +271,17 @@ export async function sendVoice(params: {
   quotaReserved?: boolean;
 }): Promise<SendResult> {
   const accountId = params.account.accountId;
-  const gw = gateways.get(accountId);
-  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const resolved = resolveGatewayForSend(accountId);
+  if (!resolved) return { error: notRunningError(accountId) };
   const target = parseTarget(params.to);
   const reservation = reservePassiveReply({
     replyToId: params.replyToId,
-    accountId,
+    accountId: resolved.accountId,
     scope: target.scope,
     quotaReserved: params.quotaReserved,
   });
   try {
-    const result = await gw.sendVoice(target, params.source, { msgId: reservation.msgId });
+    const result = await resolved.gw.sendVoice(target, params.source, { msgId: reservation.msgId });
     return { messageId: result.id };
   } catch (err: unknown) {
     reservation.rollback();
@@ -203,17 +298,17 @@ export async function sendVideo(params: {
   quotaReserved?: boolean;
 }): Promise<SendResult> {
   const accountId = params.account.accountId;
-  const gw = gateways.get(accountId);
-  if (!gw) return { error: `Bot "${accountId}" not running` };
+  const resolved = resolveGatewayForSend(accountId);
+  if (!resolved) return { error: notRunningError(accountId) };
   const target = parseTarget(params.to);
   const reservation = reservePassiveReply({
     replyToId: params.replyToId,
-    accountId,
+    accountId: resolved.accountId,
     scope: target.scope,
     quotaReserved: params.quotaReserved,
   });
   try {
-    const result = await gw.sendVideo(target, params.videoUrl, { msgId: reservation.msgId });
+    const result = await resolved.gw.sendVideo(target, params.videoUrl, { msgId: reservation.msgId });
     return { messageId: result.id };
   } catch (err: unknown) {
     reservation.rollback();

package/src/outbound/streaming-controller.ts

@@ -51,9 +51,15 @@ export class StreamingController {
   /** QQ 已接受的最新文本 — 单源真理 */
   private lastAcceptedFull = '';
 
-  /** 已成功发送的分片数（降级：=0 则走静态消息兜底） */
+  /** 已成功发送的分片数（降级：=0 且无外部投递则走静态消息兜底） */
   private sentChunkCount = 0;
 
+  /**
+   * 标记：内容已通过非流式通道成功投递（如 ask_user 按钮卡片）。
+   * 置 true 后 handleFinalize 不再走 fallback 路径，避免框架误报 outcome=error。
+   */
+  private _deliveredExternally = false;
+
   /** 同步标志：收到第一个 onPartialReply 即置 true（不等 async 完成） */
   private _hasStarted = false;
 
@@ -87,7 +93,15 @@ export class StreamingController {
   }
 
   get shouldFallbackToStatic(): boolean {
-    return this.isTerminal && this.sentChunkCount === 0;
+    return this.isTerminal && this.sentChunkCount === 0 && !this._deliveredExternally;
+  }
+
+  /**
+   * 告知控制器内容已通过外部通道投递（如 ask_user 卡片）。
+   * 后续 finalize() 不会走 fallback 路径，框架不会误报 outcome=error。
+   */
+  markDeliveredExternally(): void {
+    this._deliveredExternally = true;
   }
 
   // ── 入口 ──
@@ -212,6 +226,9 @@ export class StreamingController {
       } else if (this.sentChunkCount > 0 && this.lastAcceptedFull) {
         // 未提供 sendStatic → 降级标记，由上层兜底发送
         this.transition('failed', 'finalize:no_sendstatic');
+      } else if (this._deliveredExternally) {
+        // 内容已通过外部通道投递（如 ask_user 卡片），非失败
+        this.transition('done', 'finalize');
       } else {
         this.transition('done', 'finalize:fallback');
       }
@@ -227,8 +244,8 @@ export class StreamingController {
     }
 
     // 无会话 — 视有无下发决定终态
-    if (this.sentChunkCount > 0) {
-      this.transition('done', 'finalize:no_session');
+    if (this.sentChunkCount > 0 || this._deliveredExternally) {
+      this.transition('done', this.sentChunkCount > 0 ? 'finalize:no_session' : 'finalize');
     } else {
       this.transition('done', 'finalize:fallback');
     }