@jerryliang122/openclaw-qqbot 1.0.5 → 1.0.7

package/dist/index.d.cts

@@ -960,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.5",
+  "version": "1.0.7",
   "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/ctx-builder.ts

@@ -89,7 +89,26 @@ export function buildCtxPayload(params: CtxPayloadParams): any {
     },
     reply: {
       to: envelope.targetId,
-      replyToId: envelope.messageId,
+      /**
+       * ReplyToId 契约语义 = 当前消息回复(引用)的那条消息的 ID —— 对齐
+       * telegram 原生通道（replyHead?.messageId ?? visibleReplyTarget?.id），
+       * 无引用时必须为 undefined。框架将其渲染为模型可见 Conversation info
+       * 的 reply_to_id 字段。
+       *
+       * 历史版本误填 envelope.messageId（消息自身 ID），导致每条消息都呈现
+       * message_id == reply_to_id —— 被上层 agent 的 AGENTS 规则判为「内部
+       * 回灌、非新指令」而拒绝响应（2026-09-22 事故）。
+       *
+       * QQ 被动回复锚点不依赖此字段：deliverCtx.replyToId / msgid-cache 兜底
+       * （resolvePassiveFirstReplyToId）/ attachMsgIdWithQuota 均独立取值，
+       * threading resolveReplyToMode='off' 阻断框架隐式回复线程。
+       *
+       * 防御守卫：即使上游异常传入当前消息 ID（自引用），也强制置空——
+       * 「reply_to_id == message_id」这一假回灌签名在任何路径都不允许再现。
+       */
+      replyToId: envelope.quote?.messageId && envelope.quote.messageId !== envelope.messageId
+        ? envelope.quote.messageId
+        : undefined,
       originatingTo: envelope.targetId,
     },
     access: {
@@ -100,8 +119,17 @@ export function buildCtxPayload(params: CtxPayloadParams): any {
       : undefined,
     media: mediaFacts.length > 0 ? mediaFacts : undefined,
     supplemental: {
+      // quote.id 同样必须是「被引用消息」的真实 ID（ref-index 命中时），
+      // 而非当前消息 ID——框架经 applySupplementalContext 映射为
+      // ctx.ReplyToId / "Reply target of current user message"。
       quote: envelope.quote
-        ? { id: envelope.messageId, body: envelope.quote.content, sender: envelope.quote.senderId }
+        ? {
+            ...(envelope.quote.messageId && envelope.quote.messageId !== envelope.messageId
+              ? { id: envelope.quote.messageId }
+              : {}),
+            body: envelope.quote.content,
+            sender: envelope.quote.senderId,
+          }
         : undefined,
       groupSystemPrompt: envelope.systemPrompt,
     },

package/src/dispatch/envelope-builder.ts

@@ -20,7 +20,7 @@ export interface OpenClawInboundMessage {
   messageId: string;
   content: string;
   history?: Array<{ role: string; content: string; senderId?: string; senderName?: string }>;
-  quote?: { content: string; senderId: string; attachments?: unknown[] };
+  quote?: { content: string; senderId: string; messageId?: string; attachments?: unknown[] };
   attachments?: unknown[];
   /** 入站图片 URL 列表（从附件中提取） */
   imageUrls?: string[];
@@ -44,7 +44,11 @@ function mapHistory(
 }
 
 /**
- * 将 ResolvedQuote 转换为 OpenClaw quote 格式
+ * 将 ResolvedQuote 转换为 OpenClaw quote 格式。
+ *
+ * messageId 为被引用消息的真实平台消息 ID：仅 ref-index store 命中
+ * （quote.source === 'store'，entry 存在）时可取；msg_elements 兜底
+ * 解析拿不到 id，保持 undefined —— 此时框架不渲染 reply_to_id。
  */
 function mapQuote(
   quote: ResolvedQuote | undefined,
@@ -53,6 +57,7 @@ function mapQuote(
   return {
     content: quote.text,
     senderId: quote.entry?.senderId ?? '',
+    messageId: quote.entry?.messageId,
     attachments: quote.attachments as unknown[],
   };
 }

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();