@jerryliang122/openclaw-qqbot 1.0.0

package/src/outbound-adapter.ts

@@ -0,0 +1,323 @@
+/**
+ * QQBot Outbound 适配器
+ *
+ * 封装 sendText/sendMedia 流式等出站操作，提供配额感知的发送能力。
+ *
+ * 两层结构：
+ * - createQQBotOutboundAdapter —— 内部配额包装（sendTextWithQuota / sendMediaWithQuota），
+ *   供中间件/流式路径使用；
+ * - createQQBotChannelOutbound —— 框架 ChannelOutboundAdapter 契约入口
+ *   （sendText / sendMedia / chunker / sanitizeText 等）。
+ *   openclaw 的 channel-selection 通过 outbound.sendText（或 message.send.text /
+ *   deliveryMode === "gateway"）判定通道可用，缺失会导致
+ *   "Channel is unavailable: qqbot"。
+ */
+
+import { checkAndConsumePassiveReplyQuota, checkPassiveReplyQuota, inferQQBotScope } from './features/quota-manager.js';
+import type { PluginLogger } from './utils/plugin-logger.js';
+import type { ResolvedQQBotAccount } from './types.js';
+import type { SendMediaParams, SendMediaResult } from './outbound/media-send.js';
+import type { SendResult } from './outbound/outbound-service.js';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { resolveQQBotAccount } from './config.js';
+import { parseTarget } from './outbound/target.js';
+import { getCachedMsgId } from './features/msgid-cache.js';
+import { sanitizeQQBotText } from './outbound/sanitize.js';
+import { chunkQQBotMarkdown } from './outbound/chunker.js';
+import { isApprovalPayload } from './features/approval-utils.js';
+import { TEXT_CHUNK_LIMIT } from './constants.js';
+import { tryGetQQBotRuntime } from './runtime.js';
+import { getAdapters } from './adapter/resolve.js';
+
+export type SendTextFn = (params: {
+  to: string;
+  text: string;
+  accountId?: string;
+  replyToId?: string;
+  account: ResolvedQQBotAccount;
+  quotaReserved?: boolean;
+}) => Promise<SendResult>;
+
+export type SendMediaFn = (params: SendMediaParams) => Promise<SendMediaResult>;
+
+export interface QQBotOutboundAdapterParams {
+  sendText?: SendTextFn;
+  sendMedia?: SendMediaFn;
+  shouldSuppressLocalPayloadPrompt?: (params: { payload: unknown }) => boolean;
+  shouldTreatDeliveredTextAsVisible?: (params: { kind: string; text?: string }) => boolean;
+  preferFinalAssistantVisibleText?: boolean;
+  beforeDeliverPayload?: (params: {
+    cfg: unknown;
+    target: { to: string; accountId?: string; replyToId?: string };
+    hint?: unknown;
+    payload?: unknown;
+  }) => Promise<{ mode: 'passive' | 'proactive'; msgId?: string } | void>;
+}
+
+export interface QQBotOutboundAdapter {
+  sendTextWithQuota: (params: {
+    to: string;
+    text: string;
+    accountId?: string;
+    replyToId?: string;
+    account: ResolvedQQBotAccount;
+    log?: PluginLogger;
+  }) => Promise<{ messageId?: string; error?: string }>;
+  sendMediaWithQuota: (params: {
+    to: string;
+    source: string;
+    text?: string;
+    accountId?: string;
+    replyToId?: string;
+    account: ResolvedQQBotAccount;
+    agentId?: string;
+    log?: PluginLogger;
+  }) => Promise<{ messageId?: string; error?: string }>;
+  canSendTyping: (params: {
+    to: string;
+    accountId: string;
+    replyToId: string;
+    log?: PluginLogger;
+  }) => Promise<boolean>;
+  shouldSuppressLocalPayloadPrompt: (params: { payload: unknown }) => boolean;
+  shouldTreatDeliveredTextAsVisible: (params: { kind: string; text?: string }) => boolean;
+  preferFinalAssistantVisibleText: boolean;
+}
+
+let lazySendText: SendTextFn | undefined;
+let lazySendMedia: SendMediaFn | undefined;
+
+async function getSendText(): Promise<SendTextFn> {
+  if (!lazySendText) {
+    const mod = await import('./outbound/outbound-service.js');
+    lazySendText = mod.sendText;
+  }
+  return lazySendText;
+}
+
+async function getSendMedia(): Promise<SendMediaFn> {
+  if (!lazySendMedia) {
+    const mod = await import('./outbound/media-send.js');
+    lazySendMedia = mod.sendMedia;
+  }
+  return lazySendMedia;
+}
+
+/**
+ * 创建 QQBot Outbound 适配器
+ */
+export function createQQBotOutboundAdapter(params: QQBotOutboundAdapterParams): QQBotOutboundAdapter {
+  const {
+    sendText: injectedSendText,
+    sendMedia: injectedSendMedia,
+    shouldSuppressLocalPayloadPrompt = () => false,
+    shouldTreatDeliveredTextAsVisible = () => true,
+    preferFinalAssistantVisibleText = true,
+    beforeDeliverPayload,
+  } = params;
+
+  return {
+    sendTextWithQuota: async ({ to, text, accountId, replyToId, account, log }) => {
+      const scope = inferQQBotScope(to);
+      const resolvedAccountId = accountId || account.accountId;
+
+      // 使用原子操作检查并消耗配额
+      const { canReply, rollback } = await checkAndConsumePassiveReplyQuota({
+        accountId: resolvedAccountId,
+        msgId: replyToId,
+        scope,
+        log,
+      });
+
+      const sendTextFn = injectedSendText || await getSendText();
+      const result = await sendTextFn({
+        to,
+        text,
+        accountId: resolvedAccountId,
+        replyToId: canReply ? replyToId : undefined,
+        account,
+        quotaReserved: canReply,
+      });
+
+      // 发送失败时回滚配额
+      if (canReply && replyToId && result.error) {
+        rollback();
+        log?.debug?.(`[${resolvedAccountId}] rollback quota: send failed`);
+      } else if (!canReply) {
+        log?.info?.(`[${resolvedAccountId}] [quota] fallback to proactive send: quota exhausted or no msgId`);
+      }
+
+      return result;
+    },
+
+    sendMediaWithQuota: async ({ to, source, text, accountId, replyToId, account, agentId, log }) => {
+      const scope = inferQQBotScope(to);
+      const resolvedAccountId = accountId || account.accountId;
+
+      // 使用原子操作检查并消耗配额
+      const { canReply, rollback } = await checkAndConsumePassiveReplyQuota({
+        accountId: resolvedAccountId,
+        msgId: replyToId,
+        scope,
+        log,
+      });
+
+      const sendMediaFn = injectedSendMedia || await getSendMedia();
+      const result = await sendMediaFn({
+        to,
+        source,
+        text,
+        replyToId: canReply ? replyToId : undefined,
+        accountId: resolvedAccountId,
+        agentId,
+        log,
+        quotaReserved: canReply,
+      });
+
+      // 发送失败时回滚配额
+      if (canReply && replyToId && result.error) {
+        rollback();
+        log?.debug?.(`[${resolvedAccountId}] rollback quota: send failed`);
+      }
+
+      return result;
+    },
+
+    canSendTyping: async ({ to, accountId, replyToId, log }) => {
+      const scope = inferQQBotScope(to);
+
+      if (scope !== 'c2c' || !replyToId) {
+        return false;
+      }
+
+      const canPassiveReply = await checkPassiveReplyQuota({
+        accountId,
+        msgId: replyToId,
+        scope: 'c2c',
+      });
+
+      if (!canPassiveReply) {
+        return false;
+      }
+
+      return true;
+    },
+
+    shouldSuppressLocalPayloadPrompt,
+    shouldTreatDeliveredTextAsVisible,
+    preferFinalAssistantVisibleText,
+  };
+}
+
+// ── 框架契约入口（openclaw ChannelOutboundAdapter）──
+
+/** 框架 sendText / sendMedia 上下文（openclaw ChannelOutboundContext 子集） */
+export interface ChannelOutboundSendContext {
+  to: string;
+  text?: string;
+  mediaUrl?: string;
+  accountId?: string | null;
+  replyToId?: string | null;
+  cfg: OpenClawConfig;
+}
+
+export interface ChannelOutboundDeliveryResult {
+  channel: 'qqbot';
+  messageId: string;
+}
+
+/** 恢复 MCP agentId 路由：media-send 用它解析相对路径的工作区 */
+function resolveMCPAgentId(
+  to: string,
+  accountId: string,
+  cfg: unknown,
+  log?: PluginLogger,
+): string | undefined {
+  try {
+    const parts = to.split(':');
+    const scope = parts[1];
+    const peerId = parts[2];
+    if (!scope || !peerId) return undefined;
+    const rt = tryGetQQBotRuntime();
+    if (!rt) return undefined;
+    const route = getAdapters(rt).resolveAgentRoute?.({
+      cfg, channel: 'qqbot', accountId,
+      peer: { kind: scope === 'group' ? 'group' : 'direct', id: peerId },
+    });
+    log?.debug?.(`resolveMCPAgentId to=${to} => agentId=${route?.agentId ?? 'none'}`);
+    return route?.agentId;
+  } catch { return undefined; }
+}
+
+/**
+ * 被动优先的 replyToId 解析：框架未显式给 replyToId 时（message 工具 / 框架
+ * 直发路径），从 msgid-cache 取该会话最新未过期 msg_id，让发送走配额感知的
+ * 被动通道（保每日主动预算）。无缓存（静群超 TTL）→ undefined → 主动发送。
+ */
+function resolvePassiveFirstReplyToId(to: string, explicitReplyToId?: string | null): string | undefined {
+  if (explicitReplyToId) return explicitReplyToId;
+  try {
+    const { scope, targetId } = parseTarget(to);
+    if (!targetId) return undefined;
+    return getCachedMsgId(scope, targetId);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 创建框架 ChannelOutboundAdapter 契约入口。
+ *
+ * 框架可用性判定要求 outbound.sendText 存在（channel-resolution.ts /
+ * channel-bootstrap.runtime.ts），sendText/sendMedia 内部走配额感知包装，
+ * 配额耗尽时自动降级主动消息。
+ */
+export function createQQBotChannelOutbound(params: QQBotOutboundAdapterParams = {}) {
+  const quotaAdapter = createQQBotOutboundAdapter(params);
+
+  return {
+    ...quotaAdapter,
+    deliveryMode: 'direct' as const,
+
+    sendText: async (ctx: ChannelOutboundSendContext): Promise<ChannelOutboundDeliveryResult> => {
+      const account = resolveQQBotAccount(ctx.cfg, ctx.accountId ?? undefined);
+      const result = await quotaAdapter.sendTextWithQuota({
+        to: ctx.to,
+        text: ctx.text ?? '',
+        accountId: ctx.accountId ?? undefined,
+        replyToId: resolvePassiveFirstReplyToId(ctx.to, ctx.replyToId),
+        account,
+      });
+      if (result.error) throw new Error(result.error);
+      return { channel: 'qqbot', messageId: result.messageId ?? '' };
+    },
+
+    sendMedia: async (ctx: ChannelOutboundSendContext): Promise<ChannelOutboundDeliveryResult> => {
+      const account = resolveQQBotAccount(ctx.cfg, ctx.accountId ?? undefined);
+      const resolvedAccountId = ctx.accountId ?? account.accountId;
+      const result = await quotaAdapter.sendMediaWithQuota({
+        to: ctx.to,
+        source: ctx.mediaUrl ?? '',
+        text: ctx.text,
+        accountId: resolvedAccountId,
+        replyToId: resolvePassiveFirstReplyToId(ctx.to, ctx.replyToId),
+        account,
+        agentId: resolveMCPAgentId(ctx.to, resolvedAccountId, ctx.cfg),
+      });
+      if (result.error) throw new Error(result.error);
+      return { channel: 'qqbot', messageId: result.messageId ?? '' };
+    },
+
+    sanitizeText: ({ text }: { text: string }) => sanitizeQQBotText(text),
+    chunker: (text: string, limit: number) => chunkQQBotMarkdown(text, limit),
+    chunkerMode: 'markdown' as const,
+    textChunkLimit: TEXT_CHUNK_LIMIT,
+    shouldSuppressLocalPayloadPrompt: ({ payload }: { payload: unknown }) => isApprovalPayload(payload),
+  };
+}
+
+export const qqbotChannelOutbound = createQQBotChannelOutbound({
+  shouldSuppressLocalPayloadPrompt: () => false,
+  shouldTreatDeliveredTextAsVisible: () => true,
+  preferFinalAssistantVisibleText: true,
+});

package/src/plugin-base.ts

@@ -0,0 +1,42 @@
+/**
+ * QQBot 插件基础配置
+ *
+ * 参考 Telegram 插件的 createTelegramPluginBase
+ */
+
+import { qqbotSetupWizard } from './setup/surface.js';
+
+export interface QQBotPluginBaseParams {
+  setupWizard?: typeof qqbotSetupWizard;
+}
+
+export function createQQBotPluginBase(params: QQBotPluginBaseParams = {}) {
+  const { setupWizard = qqbotSetupWizard } = params;
+
+  return {
+    id: 'qqbot' as const,
+    meta: {
+      id: 'qqbot',
+      label: 'QQ Bot',
+      selectionLabel: 'QQ Bot',
+      docsPath: '/docs/channels/qqbot',
+      blurb: 'Connect to QQ via official QQ Bot API',
+      order: 50,
+    },
+    capabilities: {
+      chatTypes: ['direct', 'group'] as Array<'direct' | 'group'>,
+      media: true,
+      reactions: false,
+      threads: false,
+    },
+    setupWizard: setupWizard as any,
+    reload: {
+      configPrefixes: ['channels.qqbot'],
+    },
+    defaults: {
+      queue: {
+        debounceMs: 1000,
+      },
+    },
+  };
+}

package/src/request-context.ts

@@ -0,0 +1,50 @@
+/**
+ * 请求级上下文（基于 AsyncLocalStorage）
+ *
+ * 解决并发消息下工具获取当前会话信息的竞态问题。
+ * gateway 在处理每条入站消息时通过 runWithRequestContext() 建立作用域，
+ * 作用域内的所有异步代码（包括 AI agent 调用、tool execute）
+ * 都能通过 getRequestContext() 安全地拿到当前请求的上下文。
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export interface RequestContext {
+  /** 投递目标地址，如 qqbot:c2c:xxx 或 qqbot:group:xxx */
+  target: string;
+  /** 当前请求的 QQBot 账户 ID（多账户场景） */
+  accountId?: string;
+  /** 当前消息 ID */
+  messageId?: string;
+  /** 发送者 open_id */
+  openId?: string;
+}
+
+const asyncLocalStorage = new AsyncLocalStorage<RequestContext>();
+
+/**
+ * 在请求级作用域中执行回调
+ */
+export function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T {
+  return asyncLocalStorage.run(ctx, fn);
+}
+
+/**
+ * 获取当前请求的上下文
+ */
+export function getRequestContext(): RequestContext | undefined {
+  return asyncLocalStorage.getStore();
+}
+
+/**
+ * 获取当前请求的投递目标地址
+ */
+export function getRequestTarget(): string | undefined {
+  return asyncLocalStorage.getStore()?.target;
+}
+
+/**
+ * 获取当前请求的账户 ID
+ */
+export function getRequestAccountId(): string | undefined {
+  return asyncLocalStorage.getStore()?.accountId;
+}

package/src/runtime.ts

@@ -0,0 +1,42 @@
+/**
+ * QQBot 插件运行时管理。
+ *
+ * 日志统一由 `utils/plugin-logger.ts` 提供，此处只管理 runtime 实例。
+ */
+
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+import { setOpenClawVersion } from "./bot-instance.js";
+import { flushAllRefIndexStores } from "./features/ref-index-store.js";
+import { getOpenclawVersion } from "./utils/pkg-version.js";
+
+let runtime: PluginRuntime | null = null;
+let exitHooksInstalled = false;
+
+export function setQQBotRuntime(next: PluginRuntime) {
+  runtime = next;
+  const version = getOpenclawVersion(next.version);
+  setOpenClawVersion(version);
+  installExitHooksOnce();
+}
+
+function installExitHooksOnce(): void {
+  if (exitHooksInstalled) return;
+  exitHooksInstalled = true;
+
+  const flush = () => {
+    try { flushAllRefIndexStores(); } catch {}
+  };
+
+  process.on('beforeExit', flush);
+  process.on('SIGINT', () => { flush(); process.exit(0); });
+  process.on('SIGTERM', () => { flush(); process.exit(0); });
+}
+
+export function getQQBotRuntime(): PluginRuntime {
+  if (!runtime) throw new Error("QQBot runtime not initialized");
+  return runtime;
+}
+
+export function tryGetQQBotRuntime(): PluginRuntime | null {
+  return runtime;
+}

package/src/setup/account-key.ts

@@ -0,0 +1,41 @@
+/**
+ * 账户键解析 — setup / login 共用
+ *
+ * 统一确定扫码/绑定凭据应写入哪个账户键。
+ */
+
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { listQQBotAccountIds, resolveQQBotAccount } from '../config.js';
+
+/**
+ * 解析凭据写入的目标账户键。
+ *
+ * @param cfg    当前配置
+ * @param appId  扫码或输入的 AppID
+ * @param resolvedId  用户显式指定的账户名（如 --account / setup wizard），可选
+ * @returns 账户键
+ *
+ * 优先级：
+ *   1. resolvedId 指定 → 直接使用
+ *   2. 已有同 appId 的账户 → 刷新凭据（复用该账户键）
+ *   3. 零账户 → 'default'（首次配置）
+ *   4. 已有其他账户 → appId（新增独立账户）
+ */
+export function resolveAccountKey(
+  cfg: OpenClawConfig,
+  appId: string,
+  resolvedId?: string | null,
+): string {
+  if (resolvedId) return resolvedId;
+
+  // 同 appId → 刷新
+  for (const id of listQQBotAccountIds(cfg)) {
+    if (resolveQQBotAccount(cfg, id).appId === appId) return id;
+  }
+
+  // 零账户 → default
+  if (listQQBotAccountIds(cfg).length === 0) return 'default';
+
+  // 新增账户
+  return appId;
+}

package/src/setup/finalize.ts

@@ -0,0 +1,110 @@
+/**
+ * openclaw setup 引导 — QQ Bot 扫码/手动绑定
+ */
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { formatDocsLink } from '../adapter/setup.js';
+import { qrConnect } from '@tencent-connect/qqbot-connector';
+import { DEFAULT_ACCOUNT_ID, applyQQBotAccountConfig, resolveQQBotAccount } from '../config.js';
+import { resolveAccountKey } from './account-key.js';
+
+type Prompter = {
+  select: (opts: { message: string; options: Array<{ value: string; label: string; hint?: string }> }) => Promise<string>;
+  text: (opts: { message: string; validate?: (v: string) => string | undefined }) => Promise<string>;
+  note: (msg: string, title?: string) => Promise<void>;
+};
+
+type Runtime = {
+  log: (msg: string) => void;
+  error: (msg: string) => void;
+};
+
+function isConfigured(cfg: OpenClawConfig, accountId: string): boolean {
+  const account = resolveQQBotAccount(cfg, accountId);
+  return Boolean(account.appId && account.clientSecret);
+}
+
+async function linkViaQrCode(cfg: OpenClawConfig, _accountId: string, prompter: Prompter, rt: Runtime): Promise<OpenClawConfig> {
+  try {
+    const accounts: Array<{ appId: string; appSecret: string; userOpenid?: string }> = await qrConnect({ source: 'openclaw' });
+
+    if (accounts.length === 0) {
+      await prompter.note('未获取到任何 QQ Bot 账号信息。', 'QQ Bot');
+      return cfg;
+    }
+
+    let next = cfg;
+    for (const { appId, appSecret, userOpenid } of accounts) {
+      // 同 appId 刷新；零账户 default；已有账户新增 appId
+      const key = resolveAccountKey(cfg, appId);
+      next = applyQQBotAccountConfig(next, key, { appId, clientSecret: appSecret });
+      next = applyAccountDefaults(next, key, userOpenid);
+      rt.log(`绑定成功！账户: ${key} (AppID: ${appId})`);
+    }
+
+    return next;
+  } catch (err) {
+    rt.error(`QQ Bot 绑定失败: ${String(err)}`);
+    await prompter.note(`绑定失败，您可以稍后手动配置。\n文档: ${formatDocsLink('/channels/qqbot', 'qqbot')}`, 'QQ Bot');
+    return cfg;
+  }
+}
+
+async function linkViaManual(cfg: OpenClawConfig, _accountId: string, prompter: Prompter): Promise<OpenClawConfig> {
+  const appIdInput = await prompter.text({ message: '请输入 QQ Bot AppID', validate: (v) => v.trim() ? undefined : 'AppID 不能为空' });
+  const secret = await prompter.text({ message: '请输入 QQ Bot AppSecret', validate: (v) => v.trim() ? undefined : 'AppSecret 不能为空' });
+  const appId = appIdInput.trim();
+  const key = resolveAccountKey(cfg, appId);
+  let next = applyQQBotAccountConfig(cfg, key, { appId, clientSecret: secret.trim() });
+  next = applyAccountDefaults(next, key);
+  await prompter.note('✔ QQ Bot 配置完成！', 'QQ Bot');
+  return next;
+}
+
+export async function finalizeQQBotSetup(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  prompter: Prompter;
+  runtime: Runtime;
+}): Promise<{ cfg: OpenClawConfig }> {
+  const accountId = params.accountId.trim() || DEFAULT_ACCOUNT_ID;
+  const configured = isConfigured(params.cfg, accountId);
+
+  const mode = await params.prompter.select({
+    message: configured ? 'QQ 已绑定，选择操作' : '选择 QQ 绑定方式',
+    options: [
+      { value: 'qr', label: '扫码绑定（推荐）', hint: '使用 QQ 扫描二维码自动完成绑定' },
+      { value: 'manual', label: '手动输入 QQ Bot AppID 和 AppSecret', hint: '需到 QQ 开放平台 q.qq.com 查看' },
+      { value: 'skip', label: configured ? '保持当前配置' : '稍后配置' },
+    ],
+  });
+
+  let next = params.cfg;
+  if (mode === 'qr') {
+    next = await linkViaQrCode(next, accountId, params.prompter, params.runtime);
+  } else if (mode === 'manual') {
+    next = await linkViaManual(next, accountId, params.prompter);
+  } else if (!configured) {
+    await params.prompter.note('您可以稍后运行以下命令重新配置：\n  openclaw channels add', 'QQ Bot');
+  }
+
+  return { cfg: next };
+}
+
+export function applyAccountDefaults(cfg: OpenClawConfig, accountId: string, userOpenid?: string): OpenClawConfig {
+  const next = { ...cfg, channels: { ...cfg.channels } };
+  const qqbot = { ...(next.channels?.qqbot as Record<string, unknown> ?? {}) } as Record<string, unknown>;
+
+  const defaults: Record<string, unknown> = { streaming: { mode: 'partial' }, dmPolicy: 'allowlist', mediaMaxMb: 200 };
+  if (userOpenid) defaults.allowFrom = [userOpenid];
+
+  if (accountId === DEFAULT_ACCOUNT_ID) {
+    Object.assign(qqbot, defaults);
+  } else {
+    const accounts = { ...(qqbot.accounts as Record<string, unknown> ?? {}) };
+    accounts[accountId] = { ...(accounts[accountId] as Record<string, unknown> ?? {}), ...defaults };
+    qqbot.accounts = accounts;
+  }
+
+  next.channels = { ...next.channels, qqbot };
+  return next;
+}