@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/src/utils/ssrf-guard.ts

@@ -48,13 +48,40 @@ export function isReservedAddr(ip: string): boolean {
 
 const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
 
+/** QQ 官方媒体/API 域名白名单，匹配时跳过 DNS 解析检查 */
+const QQ_TRUSTED_DOMAINS = new Set([
+  // QQ Bot API
+  "api.sgroup.qq.com",
+  "sandbox.api.sgroup.qq.com",
+  // QQ Bot Token
+  "bots.qq.com",
+  // QQ 多媒体上传/下载
+  "multimedia.nt.qq.com.cn",
+  "multimedia.nt.qq.com",
+  // QQ 群文件
+  "grouppro.grouppro.qq.com",
+]);
+
+/** 检查 hostname 是否匹配 QQ 白名单（支持子域名通配 *.example.com） */
+function isQQTrustedDomain(hostname: string): boolean {
+  if (QQ_TRUSTED_DOMAINS.has(hostname)) return true;
+  // 检查一级子域名：*.multimedia.nt.qq.com.cn
+  const dot = hostname.indexOf('.');
+  if (dot > 0) {
+    const parent = hostname.slice(dot + 1);
+    return QQ_TRUSTED_DOMAINS.has(parent);
+  }
+  return false;
+}
+
 /**
  * 校验远程 URL 是否可安全请求。
  *
  * 规则：
  * 1. 仅放行 http / https 协议
- * 2. 若 URL 直接携带 IP 则即时判定
- * 3. 若为域名则先做 DNS 解析，逐条检查解析结果
+ * 2. QQ 白名单域名直接放行（免 DNS 解析）
+ * 3. 若 URL 直接携带 IP 则即时判定
+ * 4. 若为域名则先做 DNS 解析，逐条检查解析结果
  *
  * @throws {Error} 当 URL 指向受限地址时
  */
@@ -70,6 +97,9 @@ export async function validateRemoteUrl(raw: string): Promise<void> {
   // 去掉 IPv6 方括号
   const host = url.hostname.replace(/^\[|\]$/g, "");
 
+  // QQ 官方域名 → 免 DNS 检查直接放行
+  if (isQQTrustedDomain(host)) return;
+
   if (net.isIP(host)) {
     assertPublicAddr(host, raw);
     return;

package/src/utils/stt.ts

@@ -0,0 +1,137 @@
+/**
+ * STT (Speech-to-Text) 语音转文字服务
+ *
+ * 支持 OpenAI 兼容的 /audio/transcriptions 接口。
+ * 配置优先级：
+ *   1. channels.qqbot.stt（插件级）
+ *   2. 框架级 audio model 配置
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface STTConfig {
+  enabled: boolean;
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+}
+
+/**
+ * 从 OpenClaw 配置中解析 STT 设置
+ */
+export function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null {
+  const channels = asRecord(cfg.channels);
+  const qqbot = asRecord(channels?.qqbot);
+  const sttCfg = asRecord(qqbot?.stt);
+
+  // 显式禁用
+  if (sttCfg?.enabled === false) {
+    return null;
+  }
+
+  const models = asRecord(cfg.models);
+  const providers = asRecord(models?.providers);
+
+  // 1. 插件级 STT 配置
+  if (sttCfg) {
+    const providerId = readString(sttCfg, 'provider') ?? 'openai';
+    const providerCfg = asRecord(providers?.[providerId]);
+    const baseUrl = readString(sttCfg, 'baseUrl') ?? readString(providerCfg, 'baseUrl');
+    const apiKey = readString(sttCfg, 'apiKey') ?? readString(providerCfg, 'apiKey');
+    const model = readString(sttCfg, 'model') ?? 'whisper-1';
+    if (baseUrl && apiKey) {
+      return { enabled: true, baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, model };
+    }
+  }
+
+  // 2. 框架级 audio model fallback
+  const tools = asRecord(cfg.tools);
+  const media = asRecord(tools?.media);
+  const audio = asRecord(media?.audio);
+  const audioModels = audio?.models;
+  const audioModelEntry = Array.isArray(audioModels) ? asRecord(audioModels[0]) : undefined;
+  if (audioModelEntry) {
+    const providerId = readString(audioModelEntry, 'provider') ?? 'openai';
+    const providerCfg = asRecord(providers?.[providerId]);
+    const baseUrl = readString(audioModelEntry, 'baseUrl') ?? readString(providerCfg, 'baseUrl');
+    const apiKey = readString(audioModelEntry, 'apiKey') ?? readString(providerCfg, 'apiKey');
+    const model = readString(audioModelEntry, 'model') ?? 'whisper-1';
+    if (baseUrl && apiKey) {
+      return { enabled: true, baseUrl: baseUrl.replace(/\/+$/, ''), apiKey, model };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 调用 STT 服务转录音频文件
+ */
+export async function transcribeAudio(
+  audioPath: string,
+  cfg: Record<string, unknown>,
+): Promise<string | null> {
+  const sttCfg = resolveSTTConfig(cfg);
+  if (!sttCfg) {
+    return null;
+  }
+
+  const fileBuffer = fs.readFileSync(audioPath);
+  const fileName = sanitizeFileName(path.basename(audioPath));
+  const mime = guessMimeType(fileName);
+
+  const form = new FormData();
+  form.append('file', new Blob([fileBuffer], { type: mime }), fileName);
+  form.append('model', sttCfg.model);
+
+  const resp = await fetch(`${sttCfg.baseUrl}/audio/transcriptions`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${sttCfg.apiKey}` },
+    body: form,
+  });
+
+  if (!resp.ok) {
+    const detail = await resp.text().catch(() => '');
+    throw new Error(`STT failed (HTTP ${resp.status}): ${detail.slice(0, 300)}`);
+  }
+
+  const result = (await resp.json()) as { text?: string };
+  return result.text?.trim() || null;
+}
+
+// ── 内部工具函数 ──
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function readString(obj: Record<string, unknown> | undefined, key: string): string | undefined {
+  const val = obj?.[key];
+  if (typeof val === 'string' && val.trim()) {
+    return val.trim();
+  }
+  return undefined;
+}
+
+function sanitizeFileName(name: string): string {
+  return name.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+function guessMimeType(fileName: string): string {
+  const ext = path.extname(fileName).toLowerCase();
+  const mimeMap: Record<string, string> = {
+    '.wav': 'audio/wav',
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.flac': 'audio/flac',
+    '.m4a': 'audio/mp4',
+    '.aac': 'audio/aac',
+    '.silk': 'audio/silk',
+    '.amr': 'audio/amr',
+    '.pcm': 'audio/pcm',
+  };
+  return mimeMap[ext] ?? 'application/octet-stream';
+}

package/src/utils/voice-text.ts

@@ -0,0 +1,61 @@
+/**
+ * 语音转录文本格式化工具
+ *
+ * 将 STT / ASR 转录结果格式化为用户可读文本，注入到 AI 的入站消息中。
+ */
+
+/** 转录来源 */
+export type TranscriptSource = 'stt' | 'asr' | 'fallback';
+
+/**
+ * 单条语音转录结果
+ *
+ * 设计原则：行存自洽 — 单条语音的转录文本、来源、媒体引用全部聚合在
+ * 一个对象中，避免与 `ProcessedAttachments` 上的多个平行数组按下标对齐。
+ * 渲染层（如 `buildDynamicCtx`）通过 `transcripts.map(...)` 投影出
+ * `paths` / `urls` / `asrTexts` 列表。
+ */
+export interface VoiceTranscript {
+  /** 转录文本（STT/ASR/fallback 三选一的最终结果） */
+  text: string;
+  /** 转录来源 */
+  source: TranscriptSource;
+  /** 音频时长（秒） */
+  duration?: number;
+  /** 本地音频路径（下载/转码后的 wav 等） */
+  localPath?: string;
+  /** 远端音频 URL（未本地化时的兜底引用） */
+  remoteUrl?: string;
+  /** 平台原始 ASR 文本（不一定等于 `text`，例如 STT 成功时 text=STT 结果） */
+  asrReferText?: string;
+}
+
+/**
+ * 格式化单条或多条语音转录为文本
+ */
+export function formatVoiceText(transcripts: VoiceTranscript[]): string {
+  if (transcripts.length === 0) {
+    return '';
+  }
+  if (transcripts.length === 1) {
+    const t = transcripts[0];
+    const durationStr = t.duration ? ` (${formatDuration(t.duration)})` : '';
+    return `[Voice message${durationStr}] ${t.text}`;
+  }
+  return transcripts.map((t, i) => {
+    const durationStr = t.duration ? ` (${formatDuration(t.duration)})` : '';
+    return `[Voice ${i + 1}${durationStr}] ${t.text}`;
+  }).join('\n');
+}
+
+/**
+ * 格式化时长（秒 → "Xs" 或 "M:SS"）
+ */
+export function formatDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.round(seconds)}s`;
+  }
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.round(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}

package/tsconfig.json

@@ -3,7 +3,8 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
-    "declaration": true,
+    "declaration": false,
+    "noEmit": true,
     "outDir": "./dist",
     "rootDir": ".",
     "strict": true,

package/tsup.config.ts

@@ -0,0 +1,57 @@
+import { defineConfig } from 'tsup';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PKG_VERSION = JSON.parse(readFileSync('package.json', 'utf8')).version;
+
+function sanitizeDist() {
+  const exitFile = join('dist', 'index.cjs');
+  let src = readFileSync(exitFile, 'utf8');
+
+  // protobufjs 使用 new Function 生成序列化代码（合法场景），别名消除误报
+  src = src.replace('"use strict";', '"use strict";\nvar _F=Function;');
+  src = src.replace(/\bnew\s+Function\s*\(/g, 'new _F(');
+
+  writeFileSync(exitFile, src);
+}
+
+export default defineConfig({
+  entry: ['index.ts'],
+  format: ['cjs'],
+  outDir: 'dist',
+  dts: true,
+  splitting: false,
+  clean: true,
+  define: {
+    '__PLUGIN_VERSION__': JSON.stringify(PKG_VERSION),
+  },
+  external: [
+    'openclaw',
+    /^openclaw\/plugin-sdk(\/.+)?$/,
+  ],
+  noExternal: [
+    '@tencent-connect/qqbot-nodejs',
+    '@tencent-connect/qqbot-connector',
+    'ws',
+  ],
+  esbuildPlugins: [
+    {
+      name: 'fix-qrcode-terminal',
+      setup(build) {
+        build.onLoad({ filter: /qrcode-terminal\/lib\/main\.js$/ }, async (args) => {
+          const fs = await import('node:fs');
+          let source = fs.readFileSync(args.path, 'utf8');
+          source = source.replace(/\\033/g, '\\x1b');
+          return { contents: source, loader: 'js' };
+        });
+      },
+    },
+  ],
+  outExtension: () => ({ js: '.cjs' }),
+  platform: 'node',
+  target: 'node18',
+  sourcemap: true,
+  async onSuccess() {
+    sanitizeDist();
+  },
+});

package/dist/index.d.ts

@@ -1,18 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-declare const plugin: {
-    id: string;
-    name: string;
-    description: string;
-    configSchema: unknown;
-    register(api: OpenClawPluginApi): void;
-};
-export default plugin;
-export { qqbotPlugin } from "./src/channel.js";
-export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
-export { qqbotOnboardingAdapter } from "./src/onboarding.js";
-export * from "./src/types.js";
-export * from "./src/api.js";
-export * from "./src/config.js";
-export * from "./src/gateway.js";
-export * from "./src/outbound.js";
-export * from "./src/transport/index.js";

package/dist/index.js

@@ -1,27 +0,0 @@
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
-import { qqbotPlugin } from "./src/channel.js";
-import { setQQBotRuntime } from "./src/runtime.js";
-import { registerChannelTool } from "./src/tools/channel.js";
-import { registerRemindTool } from "./src/tools/remind.js";
-const plugin = {
-    id: "openclaw-qqbot",
-    name: "QQ Bot",
-    description: "QQ Bot channel plugin",
-    configSchema: emptyPluginConfigSchema(),
-    register(api) {
-        setQQBotRuntime(api.runtime);
-        api.registerChannel({ plugin: qqbotPlugin });
-        registerChannelTool(api);
-        registerRemindTool(api);
-    },
-};
-export default plugin;
-export { qqbotPlugin } from "./src/channel.js";
-export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
-export { qqbotOnboardingAdapter } from "./src/onboarding.js";
-export * from "./src/types.js";
-export * from "./src/api.js";
-export * from "./src/config.js";
-export * from "./src/gateway.js";
-export * from "./src/outbound.js";
-export * from "./src/transport/index.js";

package/dist/src/admin-resolver.d.ts

@@ -1,33 +0,0 @@
-/**
- * 管理员解析器模块
- * - 管理员 openid 持久化读写
- * - 升级问候目标读写
- * - 启动问候语发送
- */
-export interface AdminResolverContext {
-    accountId: string;
-    appId: string;
-    clientSecret: string;
-    log?: {
-        info: (msg: string) => void;
-        error: (msg: string) => void;
-    };
-}
-/**
- * 读取 admin openid（按 accountId + appId 区分）
- * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
- */
-export declare function loadAdminOpenId(accountId: string, appId: string): string | undefined;
-export declare function saveAdminOpenId(accountId: string, appId: string, openid: string): void;
-export declare function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string, log?: {
-    info: (msg: string) => void;
-}): string | undefined;
-export declare function clearUpgradeGreetingTargetOpenId(accountId: string, appId: string): void;
-/**
- * 解析管理员 openid：
- * 1. 优先读持久化文件（按 accountId + appId 区分）
- * 2. fallback 取第一个私聊用户，并写入文件锁定
- */
-export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "appId" | "log">): string | undefined;
-/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
-export declare function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void;

package/dist/src/admin-resolver.js

@@ -1,157 +0,0 @@
-/**
- * 管理员解析器模块
- * - 管理员 openid 持久化读写
- * - 升级问候目标读写
- * - 启动问候语发送
- */
-import path from "node:path";
-import * as fs from "node:fs";
-import { getQQBotDataDir } from "./utils/platform.js";
-import { listKnownUsers } from "./known-users.js";
-import { getAccessToken, sendProactiveC2CMessage } from "./api.js";
-import { getStartupGreetingPlan, markStartupGreetingSent, markStartupGreetingFailed } from "./startup-greeting.js";
-// ---- 文件路径 ----
-function safeName(id) {
-    return id.replace(/[^a-zA-Z0-9._-]/g, "_");
-}
-/** 新版 admin 文件路径（按 accountId + appId 区分） */
-function getAdminMarkerFile(accountId, appId) {
-    return path.join(getQQBotDataDir("data"), `admin-${safeName(accountId)}-${safeName(appId)}.json`);
-}
-/** 旧版 admin 文件路径（仅按 accountId 区分，用于迁移兼容） */
-function getLegacyAdminMarkerFile(accountId) {
-    return path.join(getQQBotDataDir("data"), `admin-${accountId}.json`);
-}
-function getUpgradeGreetingTargetFile(accountId, appId) {
-    return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeName(accountId)}-${safeName(appId)}.json`);
-}
-// ---- 管理员 openid 持久化 ----
-/**
- * 读取 admin openid（按 accountId + appId 区分）
- * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
- */
-export function loadAdminOpenId(accountId, appId) {
-    try {
-        // 1. 先尝试新版路径
-        const newFile = getAdminMarkerFile(accountId, appId);
-        if (fs.existsSync(newFile)) {
-            const data = JSON.parse(fs.readFileSync(newFile, "utf8"));
-            if (data.openid)
-                return data.openid;
-        }
-        // 2. fallback 旧版路径（仅按 accountId）
-        const legacyFile = getLegacyAdminMarkerFile(accountId);
-        if (fs.existsSync(legacyFile)) {
-            const data = JSON.parse(fs.readFileSync(legacyFile, "utf8"));
-            if (data.openid) {
-                // 自动迁移：写到新路径，删除旧文件
-                saveAdminOpenId(accountId, appId, data.openid);
-                try {
-                    fs.unlinkSync(legacyFile);
-                }
-                catch { /* ignore */ }
-                return data.openid;
-            }
-        }
-    }
-    catch { /* 文件损坏视为无 */ }
-    return undefined;
-}
-export function saveAdminOpenId(accountId, appId, openid) {
-    try {
-        fs.writeFileSync(getAdminMarkerFile(accountId, appId), JSON.stringify({ accountId, appId, openid, savedAt: new Date().toISOString() }));
-    }
-    catch { /* ignore */ }
-}
-// ---- 升级问候目标 ----
-export function loadUpgradeGreetingTargetOpenId(accountId, appId, log) {
-    try {
-        const file = getUpgradeGreetingTargetFile(accountId, appId);
-        if (fs.existsSync(file)) {
-            const data = JSON.parse(fs.readFileSync(file, "utf8"));
-            if (!data.openid) {
-                log?.info(`[qqbot:${accountId}] upgrade-greeting-target file found but openid is empty`);
-                return undefined;
-            }
-            if (data.appId && data.appId !== appId) {
-                log?.info(`[qqbot:${accountId}] upgrade-greeting-target appId mismatch: file=${data.appId}, current=${appId}`);
-                return undefined;
-            }
-            if (data.accountId && data.accountId !== accountId) {
-                log?.info(`[qqbot:${accountId}] upgrade-greeting-target accountId mismatch: file=${data.accountId}, current=${accountId}`);
-                return undefined;
-            }
-            log?.info(`[qqbot:${accountId}] upgrade-greeting-target loaded: openid=${data.openid}`);
-            return data.openid;
-        }
-        else {
-            log?.info(`[qqbot:${accountId}] upgrade-greeting-target file not found: ${file}`);
-        }
-    }
-    catch (err) {
-        log?.info(`[qqbot:${accountId}] upgrade-greeting-target file read error: ${err}`);
-    }
-    return undefined;
-}
-export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
-    try {
-        const file = getUpgradeGreetingTargetFile(accountId, appId);
-        if (fs.existsSync(file)) {
-            fs.unlinkSync(file);
-        }
-    }
-    catch { /* ignore */ }
-}
-// ---- 解析管理员 ----
-/**
- * 解析管理员 openid：
- * 1. 优先读持久化文件（按 accountId + appId 区分）
- * 2. fallback 取第一个私聊用户，并写入文件锁定
- */
-export function resolveAdminOpenId(ctx) {
-    const saved = loadAdminOpenId(ctx.accountId, ctx.appId);
-    if (saved)
-        return saved;
-    const first = listKnownUsers({ accountId: ctx.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
-    if (first) {
-        saveAdminOpenId(ctx.accountId, ctx.appId, first);
-        ctx.log?.info(`[qqbot:${ctx.accountId}] Auto-detected admin openid: ${first} (persisted)`);
-    }
-    return first;
-}
-// ---- 启动问候语 ----
-/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
-export function sendStartupGreetings(ctx, trigger) {
-    (async () => {
-        const plan = getStartupGreetingPlan(ctx.accountId, ctx.appId);
-        if (!plan.shouldSend || !plan.greeting) {
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (${plan.reason ?? "debounced"}, trigger=${trigger})`);
-            return;
-        }
-        const upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId, ctx.log);
-        // 没有 upgrade-greeting-target 文件 → 不是通过 /bot-upgrade 触发的升级
-        // （console 手动重启、脚本升级等场景），静默更新 marker 不发消息
-        if (!upgradeTargetOpenId) {
-            markStartupGreetingSent(ctx.accountId, ctx.appId, plan.version);
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Version changed but no upgrade-greeting-target, silently updating marker (trigger=${trigger})`);
-            return;
-        }
-        try {
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Sending startup greeting to upgrade-requester (trigger=${trigger}): "${plan.greeting}"`);
-            const token = await getAccessToken(ctx.appId, ctx.clientSecret);
-            const GREETING_TIMEOUT_MS = 10_000;
-            await Promise.race([
-                sendProactiveC2CMessage(token, upgradeTargetOpenId, plan.greeting),
-                new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
-            ]);
-            markStartupGreetingSent(ctx.accountId, ctx.appId, plan.version);
-            clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
-            ctx.log?.info(`[qqbot:${ctx.accountId}] Sent startup greeting to upgrade-requester: ${upgradeTargetOpenId}`);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            markStartupGreetingFailed(ctx.accountId, ctx.appId, plan.version, message);
-            ctx.log?.error(`[qqbot:${ctx.accountId}] Failed to send startup greeting: ${message}`);
-        }
-    })();
-}