@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/outbound/tts-provider.ts

@@ -0,0 +1,84 @@
+/**
+ * TTS（文字转语音）集成接口
+ *
+ * audioAsVoice 语音回复能力：
+ *   text → TTS → audioPath → SILK 转换 → Base64 → sendVoice
+ *
+ * 本模块定义接口和桥接逻辑。实际 TTS 引擎由 openclaw 框架的
+ * tts-runtime 插件提供（通过 runtime 注入），本文件不内置 TTS 实现。
+ */
+import { convertSilkToWav } from '@tencent-connect/qqbot-nodejs/protocol';
+
+/**
+ * TTS Provider 接口（由框架注入或用户自定义）
+ */
+export interface TTSProvider {
+  /** 文字转语音 → 返回本地音频文件路径（wav/mp3 等） */
+  textToSpeech(params: { text: string; cfg?: unknown; channel?: string; accountId?: string }): Promise<string | null>;
+  /** 音频文件 → SILK Base64（用于 QQ 发送） */
+  audioFileToSilkBase64?(audioPath: string): Promise<string | null>;
+}
+
+/**
+ * 从 runtime 尝试获取 TTS provider
+ *
+ * openclaw 框架通过 `runtime.channel.runtimeContexts` 或直接挂载 `runtime.tts`
+ * 提供 TTS 能力。本函数做兼容性探测。
+ */
+export function resolveTTSProvider(runtime: any): TTSProvider | undefined {
+  // 方式 1: runtime.tts (直接挂载)
+  if (runtime?.tts?.textToSpeech) {
+    return runtime.tts;
+  }
+  // 方式 2: channel runtime context 注册
+  const tts = runtime?.channel?.runtimeContexts?.get?.('tts'); // @adapter-bypass: TTS 扩展点探测，非核心 channel API
+  if (tts?.textToSpeech) {
+    return tts;
+  }
+  return undefined;
+}
+
+/**
+ * 将音频文件转换为 SILK Base64（QQ 语音消息格式）
+ *
+ * 如果 TTS provider 提供了 audioFileToSilkBase64，使用它；
+ * 否则尝试直接读取文件返回 Base64（假设已经是 SILK 格式）。
+ */
+export async function audioToSilkBase64(
+  audioPath: string,
+  provider?: TTSProvider,
+): Promise<string | null> {
+  // 优先使用 provider 的转换方法
+  if (provider?.audioFileToSilkBase64) {
+    return provider.audioFileToSilkBase64(audioPath);
+  }
+
+  // Fallback：尝试 SDK 内置的 SILK 转换
+  try {
+    const { default: fs } = await import('node:fs');
+    const buffer = fs.readFileSync(audioPath);
+    return buffer.toString('base64');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 完整的 TTS → SILK → Base64 流程
+ *
+ * 返回可以直接传给 sendVoice({ base64 }) 的 Base64 字符串。
+ */
+export async function textToVoiceBase64(
+  text: string,
+  provider: TTSProvider,
+  opts?: { cfg?: unknown; accountId?: string },
+): Promise<string | null> {
+  const audioPath = await provider.textToSpeech({
+    text,
+    cfg: opts?.cfg,
+    channel: 'qqbot',
+    accountId: opts?.accountId,
+  });
+  if (!audioPath) return null;
+  return audioToSilkBase64(audioPath, provider);
+}

package/src/request-context.ts

@@ -6,43 +6,44 @@
  * 作用域内的所有异步代码（包括 AI agent 调用、tool execute）
  * 都能通过 getRequestContext() 安全地拿到当前请求的上下文。
  */
-import { AsyncLocalStorage } from "node:async_hooks";
+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>();
 
 /**
- * 在请求级作用域中执行回调。
- * 作用域内所有同步/异步代码都能通过 getRequestContext() 获取上下文。
+ * 在请求级作用域中执行回调
  */
 export function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T {
   return asyncLocalStorage.run(ctx, fn);
 }
 
 /**
- * 获取当前请求的上下文，不存在时返回 undefined。
+ * 获取当前请求的上下文
  */
 export function getRequestContext(): RequestContext | undefined {
   return asyncLocalStorage.getStore();
 }
 
 /**
- * 获取当前请求的投递目标地址。
- * 便捷方法，等价于 getRequestContext()?.target。
+ * 获取当前请求的投递目标地址
  */
 export function getRequestTarget(): string | undefined {
   return asyncLocalStorage.getStore()?.target;
 }
 
 /**
- * 获取当前请求的账户 ID。
- * 便捷方法，等价于 getRequestContext()?.accountId。
+ * 获取当前请求的账户 ID
  */
 export function getRequestAccountId(): string | undefined {
   return asyncLocalStorage.getStore()?.accountId;

package/src/runtime.ts

@@ -1,17 +1,42 @@
+/**
+ * QQBot 插件运行时管理。
+ *
+ * 日志统一由 `utils/plugin-logger.ts` 提供，此处只管理 runtime 实例。
+ */
+
 import type { PluginRuntime } from "openclaw/plugin-sdk";
-import { setOpenClawVersion } from "./api.js";
+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;
-  // 将框架版本注入 User-Agent（runtime 注入后才能拿到准确版本）
-  setOpenClawVersion(next.version);
+  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");
-  }
+  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 { DEFAULT_ACCOUNT_ID, formatDocsLink } from '../adapter/setup.js';
+import { qrConnect } from '@tencent-connect/qqbot-connector';
+import { 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;
+}

package/src/setup/login.ts

@@ -0,0 +1,197 @@
+/**
+ * QQ Bot QR 登录 — 两阶段接口适配
+ *
+ * 使用 @tencent-connect/qqbot-connector 的 startQrConnect 回调 API，
+ * 将扫码绑定流程拆分为 start / wait 两个阶段，对接 ChannelPlugin 的
+ * gateway.loginWithQrStart / loginWithQrWait。
+ */
+import { startQrConnect, type QrConnectCredentials } from '@tencent-connect/qqbot-connector';
+
+// ── 类型 ──
+
+export interface QrLoginStartResult {
+  qrDataUrl?: string;
+  message: string;
+}
+
+export interface QrLoginWaitResult {
+  connected: boolean;
+  message: string;
+  credentials?: QrConnectCredentials[];
+}
+
+// ── 挂起的登录会话 ──
+
+interface PendingSession {
+  /** 等待扫码结果的 Promise（onSuccess resolve, onFailure reject） */
+  credentialsPromise: Promise<QrConnectCredentials[]>;
+  /** 取消当前流程 */
+  dispose: () => void;
+}
+
+const pendingSessions = new Map<string, PendingSession>();
+
+// ── 启动 QR 登录 ──
+
+export function startQrLogin(accountId?: string, source = 'openclaw'): Promise<QrLoginStartResult> {
+  const key = accountId ?? 'default';
+
+  // 清理旧会话
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+
+  return new Promise((resolve) => {
+    let credentialsResolve: (creds: QrConnectCredentials[]) => void;
+    let credentialsReject: (err: Error) => void;
+
+    // 凭据 Promise — 在 onSuccess/onFailure 中 settle
+    const credentialsPromise = new Promise<QrConnectCredentials[]>((res, rej) => {
+      credentialsResolve = res;
+      credentialsReject = rej;
+    });
+
+    const dispose = startQrConnect(
+      {
+        onQrDisplayed(url) {
+          resolve({
+            qrDataUrl: url,
+            message: '请使用手机 QQ 扫描二维码完成绑定',
+          });
+        },
+        onSuccess: (creds) => credentialsResolve!(creds),
+        onFailure: (err) => credentialsReject!(err),
+      },
+      { displayQrCodeToConsole: true, source },
+    );
+
+    pendingSessions.set(key, { dispose, credentialsPromise });
+  });
+}
+
+// ── 等待扫码结果 ──
+
+export async function waitQrLogin(accountId?: string): Promise<QrLoginWaitResult> {
+  const key = accountId ?? 'default';
+  const session = pendingSessions.get(key);
+
+  if (!session) {
+    return { connected: false, message: '没有正在进行的登录会话，请先运行 login 命令。' };
+  }
+
+  try {
+    const credentials = await session.credentialsPromise;
+    pendingSessions.delete(key);
+
+    if (credentials.length === 0) {
+      return { connected: false, message: '未获取到 QQ Bot 凭据。' };
+    }
+
+    return {
+      connected: true,
+      message: `绑定成功！AppID: ${credentials.map((c) => c.appId).join(', ')}`,
+      credentials,
+    };
+  } catch (err) {
+    pendingSessions.delete(key);
+    return {
+      connected: false,
+      message: `绑定失败: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ── 主动取消 ──
+
+export function cancelQrLogin(accountId?: string): void {
+  const key = accountId ?? 'default';
+  pendingSessions.get(key)?.dispose();
+  pendingSessions.delete(key);
+}
+
+// ── 解析 channelInput (appId:clientSecret) ──
+
+export function parseChannelInput(channelInput?: string | null): { appId: string; clientSecret: string } | null {
+  if (!channelInput) return null;
+  const parts = channelInput.trim().split(':');
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return { appId: parts[0], clientSecret: parts[1] };
+  }
+  return null;
+}
+
+// ── auth.login 入口 ──
+
+export interface QqbotLoginParams {
+  cfg: Record<string, unknown>;
+  accountId?: string | null;
+  channelInput?: string | null;
+  verbose?: boolean;
+  /** 框架注入的 runtime（含 config 持久化 API） */
+  [key: string]: unknown;
+}
+
+/**
+ * auth.login 完整实现。
+ *
+ * 账号策略：
+ *   --account <id>  → 写入指定账户
+ *   channelInput     → 用 appId 作为账户键
+ *   QR 扫码         → 用扫码返回的 appId 作为新账户键
+ */
+export async function qqbotLogin({
+  cfg,
+  accountId,
+  channelInput,
+  verbose,
+  ...rest
+}: QqbotLoginParams): Promise<void> {
+  // 延迟导入，避免循环依赖
+  const { applyQQBotAccountConfig } = await import('../config.js');
+  const { persistAuthConfig } = await import('../adapter/resolve.js');
+  const { applyAccountDefaults } = await import('./finalize.js');
+  const { resolveAccountKey } = await import('./account-key.js');
+
+  const runtime: Record<string, unknown> = rest as any;
+  const resolvedId = accountId ? accountId.trim().toLowerCase() : null;
+
+  // 如果传了 appId:clientSecret，直接写入配置
+  const parsed = parseChannelInput(channelInput);
+  if (parsed) {
+    const key = resolveAccountKey(cfg as any, parsed.appId, resolvedId);
+    const result = applyQQBotAccountConfig(cfg as any, key, {
+      appId: parsed.appId,
+      clientSecret: parsed.clientSecret,
+    });
+    Object.assign(cfg, result);
+    // 对齐 setup：写入默认 streaming/dmPolicy
+    const withDefaults = applyAccountDefaults(cfg as any, key);
+    Object.assign(cfg, withDefaults);
+    await persistAuthConfig(runtime, cfg, 'restart');
+    if (verbose) console.log(`QQ Bot 已配置 (${key}) AppID: ${parsed.appId}`);
+    return;
+  }
+
+  // QR 扫码登录
+  const { qrDataUrl, message } = await startQrLogin(resolvedId || 'pending');
+  console.log(`\n${message}`);
+  if (qrDataUrl) console.log(`QR 链接: ${qrDataUrl}`);
+
+  const result = await waitQrLogin(resolvedId || 'pending');
+  if (!result.connected || !result.credentials) {
+    throw new Error(result.message);
+  }
+
+  for (const cred of result.credentials) {
+    const key = resolveAccountKey(cfg as any, cred.appId, resolvedId);
+    const next = applyQQBotAccountConfig(cfg as any, key, {
+      appId: cred.appId,
+      clientSecret: cred.appSecret,
+    });
+    Object.assign(cfg, next);
+    // 对齐 setup：写入默认 streaming/dmPolicy，扫码用户加入白名单
+    const withDefaults = applyAccountDefaults(cfg as any, key, cred.userOpenid);
+    Object.assign(cfg, withDefaults);
+  }
+  await persistAuthConfig(runtime, cfg, 'restart');
+  console.log(`QQ Bot 登录成功！`);
+}

package/src/setup/surface.ts

@@ -0,0 +1,40 @@
+/**
+ * OpenClaw setup 向导 — QQ Bot 配置界面
+ */
+import type { ChannelSetupWizard } from '../adapter/setup.js';
+import { createStandardChannelSetupStatus, setSetupChannelEnabled } from '../adapter/setup.js';
+import { listQQBotAccountIds, resolveQQBotAccount, resolveDefaultQQBotAccountId } from '../config.js';
+import { finalizeQQBotSetup } from './finalize.js';
+
+const CHANNEL = 'qqbot' as const;
+
+export const qqbotSetupWizard: ChannelSetupWizard = {
+  channel: CHANNEL,
+  status: createStandardChannelSetupStatus({
+    channelLabel: 'QQ Bot',
+    configuredLabel: 'configured',
+    unconfiguredLabel: 'needs AppID + AppSecret',
+    configuredHint: 'configured',
+    unconfiguredHint: 'needs AppID + AppSecret',
+    configuredScore: 1,
+    unconfiguredScore: 6,
+    resolveConfigured: ({ cfg, accountId }) =>
+      (accountId ? [accountId] : listQQBotAccountIds(cfg as any)).some((id) => {
+        const account = resolveQQBotAccount(cfg as any, id);
+        return Boolean(account.appId && account.clientSecret);
+      }),
+  }),
+  // 未配置时默认使用 default 账号，有账户时框架会提示选择
+  resolveAccountIdForConfigure: async ({ cfg, shouldPromptAccountIds, accountOverride, defaultAccountId }) => {
+    if (accountOverride) return accountOverride;
+    const ids = listQQBotAccountIds(cfg as any);
+    if (ids.length === 0) return 'default';
+    if (!shouldPromptAccountIds) return ids[0];
+    return defaultAccountId || resolveDefaultQQBotAccountId(cfg as any);
+  },
+  credentials: [],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  finalize: (async ({ cfg, accountId, prompter, runtime }: any) =>
+    finalizeQQBotSetup({ cfg, accountId, prompter: prompter as any, runtime: runtime as any })) as any,
+  disable: (cfg) => { setSetupChannelEnabled(cfg, CHANNEL, false); return cfg; },
+};