@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

package/src/types.ts

@@ -0,0 +1,386 @@
+/**
+ * QQ Bot 配置类型
+ */
+export interface QQBotConfig {
+  appId: string;
+  clientSecret?: string;
+  clientSecretFile?: string;
+}
+
+/**
+ * 解析后的 QQ Bot 账户
+ */
+export interface ResolvedQQBotAccount {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  appId: string;
+  clientSecret: string;
+  secretSource: "config" | "file" | "env" | "none";
+  /** 系统提示词 */
+  systemPrompt?: string;
+  /** 图床服务器公网地址 */
+  imageServerBaseUrl?: string;
+  /** 是否支持 markdown 消息（默认 true） */
+  markdownSupport: boolean;
+  config: QQBotAccountConfig;
+}
+
+/** 群消息策略：open=全响应 | allowlist=白名单 | disabled=不响应 */
+export type GroupPolicy = "open" | "allowlist" | "disabled";
+
+/** 工具策略：full=全部 | restricted=限制敏感工具 | none=禁止 */
+export type ToolPolicy = "full" | "restricted" | "none";
+
+/** 单个群的配置 */
+export interface GroupConfig {
+  /** 是否需要 @机器人才响应（默认 true） */
+  requireMention?: boolean;
+  /**
+   * 是否忽略 @了其他用户但没有 @机器人的消息（默认 false）。
+   * 开启后，消息中 @了其他人但未 @bot 时直接丢弃（不记录历史、不触发 AI）。
+   */
+  ignoreOtherMentions?: boolean;
+  /** 群聊中 AI 可使用的工具范围（默认 restricted） */
+  toolPolicy?: ToolPolicy;
+  /** 群名称 */
+  name?: string;
+  /** 群消息行为 PE（未配置时使用内置默认值） */
+  prompt?: string;
+  /** 群历史消息缓存条数（0 禁用，默认 20） */
+  historyLimit?: number;
+}
+
+/**
+ * QQ Bot 账户配置
+ */
+export interface QQBotAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  appId?: string;
+  clientSecret?: string;
+  clientSecretFile?: string;
+  dmPolicy?: "open" | "pairing" | "allowlist";
+  allowFrom?: string[];
+  /** 群消息策略（默认 allowlist） */
+  groupPolicy?: GroupPolicy;
+  /** 群白名单（groupPolicy 为 allowlist 时生效） */
+  groupAllowFrom?: string[];
+  /** 群配置映射（按 groupOpenid 索引，"*" 为默认） */
+  groups?: Record<string, GroupConfig>;
+  /** 系统提示词，会添加在用户消息前面 */
+  systemPrompt?: string;
+  /** 图床服务器公网地址，用于发送图片，例如 http://your-ip:18765 */
+  imageServerBaseUrl?: string;
+  /** 是否支持 markdown 消息（默认 true，设为 false 可禁用） */
+  markdownSupport?: boolean;
+  /**
+   * @deprecated 请使用 audioFormatPolicy.uploadDirectFormats
+   * 可直接上传的音频格式（不转换为 SILK），向后兼容
+   */
+  voiceDirectUploadFormats?: string[];
+  /**
+   * 音频格式策略配置
+   * 统一管理入站（STT）和出站（上传）的音频格式转换行为
+   */
+  audioFormatPolicy?: AudioFormatPolicy;
+  /**
+   * 是否启用公网 URL 直传 QQ 平台（默认 true）
+   * 启用时：公网 URL 先直传给 QQ 开放平台的富媒体 API，平台自行拉取；失败后自动 fallback 到插件下载再 Base64 上传
+   * 禁用时：公网 URL 始终由插件先下载到本地，再以 Base64 上传（适用于 QQ 平台无法访问目标 URL 的场景）
+   */
+  urlDirectUpload?: boolean;
+  /**
+   * /bot-upgrade 指令返回的升级指引网址
+   * 默认: https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg
+   */
+  upgradeUrl?: string;
+  /**
+   * /bot-upgrade 指令的行为模式
+   * - "doc"：展示升级文档链接（默认，安全模式）
+   * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
+   */
+  upgradeMode?: "doc" | "hot-reload";
+  /**
+   * 出站消息合并回复（debounce）配置
+   * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸
+   */
+  deliverDebounce?: DeliverDebounceConfig;
+  /**
+   * 是否启用流式消息（默认 false）
+   * 启用后，AI 的回复会以流式形式逐步显示在 QQ 聊天中，
+   * 用户可以看到文字逐字出现的打字机效果。
+   * 设置为 true 可开启流式消息。
+   * 
+   * 注意：仅 C2C（私聊）支持流式消息 API。
+   */
+  streaming?: boolean;
+}
+
+/**
+ * 出站消息合并回复配置
+ */
+export interface DeliverDebounceConfig {
+  /**
+   * 是否启用合并回复（默认 true）
+   */
+  enabled?: boolean;
+  /**
+   * 合并窗口时长（毫秒），在此时间内的连续 deliver 会被合并
+   * 默认 1500ms
+   */
+  windowMs?: number;
+  /**
+   * 最大等待时长（毫秒），从第一条 deliver 开始计算，超过此时间强制发送
+   * 防止持续有新 deliver 导致一直不发送
+   * 默认 8000ms
+   */
+  maxWaitMs?: number;
+  /**
+   * 合并文本之间的分隔符
+   * 默认 "\n\n---\n\n"
+   */
+  separator?: string;
+}
+
+/**
+ * 音频格式策略：控制哪些格式可跳过转换
+ */
+export interface AudioFormatPolicy {
+  /**
+   * STT 模型直接支持的音频格式（入站：跳过 SILK→WAV 转换）
+   * 如果 STT 服务支持直接处理某些格式（如 silk/amr），可将其加入此列表
+   * 例如: [".silk", ".amr", ".wav", ".mp3", ".ogg"]
+   * 默认为空（所有语音都先转换为 WAV 再送 STT）
+   */
+  sttDirectFormats?: string[];
+  /**
+   * QQ 平台支持直传的音频格式（出站：跳过→SILK 转换）
+   * 默认为 [".wav", ".mp3", ".silk"]（QQ Bot API 原生支持的三种格式）
+   * 仅当需要覆盖默认值时才配置此项
+   */
+  uploadDirectFormats?: string[];
+  /**
+   * 是否启用语音转码（默认 true）
+   * 设为 false 可在环境无 ffmpeg 时跳过转码，直接以文件形式发送
+   * 当禁用时，非原生格式的音频会 fallback 到 sendDocument（文件发送）
+   */
+  transcodeEnabled?: boolean;
+}
+
+/**
+ * 富媒体附件
+ */
+export interface MessageAttachment {
+  content_type: string;  // 如 "image/png"
+  filename?: string;
+  height?: number;
+  width?: number;
+  size?: number;
+  url: string;
+  voice_wav_url?: string;  // QQ 提供的 WAV 格式语音直链，有值时优先使用以避免 SILK→WAV 转换
+  asr_refer_text?: string; // QQ 事件内置 ASR 语音识别文本
+}
+
+/**
+ * C2C 消息事件
+ */
+export interface C2CMessageEvent {
+  author: {
+    id: string;
+    union_openid: string;
+    user_openid: string;
+  };
+  content: string;
+  id: string;
+  timestamp: string;
+  message_scene?: {
+    source: string;
+    /** ext 数组，可能包含 ref_msg_idx=REFIDX_xxx（引用的消息）和 msg_idx=REFIDX_xxx（自身索引） */
+    ext?: string[];
+  };
+  attachments?: MessageAttachment[];
+}
+
+/**
+ * 频道 AT 消息事件
+ */
+export interface GuildMessageEvent {
+  id: string;
+  channel_id: string;
+  guild_id: string;
+  content: string;
+  timestamp: string;
+  author: {
+    id: string;
+    username?: string;
+    bot?: boolean;
+  };
+  member?: {
+    nick?: string;
+    joined_at?: string;
+  };
+  attachments?: MessageAttachment[];
+}
+
+/**
+ * 群聊 AT 消息事件
+ */
+export interface GroupMessageEvent {
+  author: {
+    id: string;
+    member_openid: string;
+    username?: string;
+    bot?: boolean;
+  };
+  content: string;
+  id: string;
+  timestamp: string;
+  group_id: string;
+  group_openid: string;
+  message_scene?: {
+    source: string;
+    ext?: string[];
+  };
+  attachments?: MessageAttachment[];
+  /** @提及列表 */
+  mentions?: Array<{
+    scope?: "all" | "single";
+    id?: string;
+    user_openid?: string;
+    member_openid?: string;
+    nickname?: string;
+    bot?: boolean;
+    /** 是否 @机器人自身 */
+    is_you?: boolean;
+  }>;
+}
+
+/**
+ * 按钮交互事件（INTERACTION_CREATE）
+ */
+export interface InteractionEvent {
+  /** 事件 ID，用于回应交互（PUT /interactions/{id}） */
+  id: string;
+  /** 事件类型：11=消息按钮 12=单聊快捷菜单 */
+  type: number;
+  /** 场景：c2c / group / guild */
+  scene?: string;
+  /** 场景类型：0=频道 1=群聊 2=单聊 */
+  chat_type?: number;
+  /** 触发时间 RFC3339 */
+  timestamp?: string;
+  /** 频道 openid（仅频道场景） */
+  guild_id?: string;
+  /** 子频道 openid（仅频道场景） */
+  channel_id?: string;
+  /** 单聊用户 openid（仅 c2c 场景） */
+  user_openid?: string;
+  /** 群 openid（仅群聊场景） */
+  group_openid?: string;
+  /** 群内触发用户 openid（仅群聊场景） */
+  group_member_openid?: string;
+  version: number;
+  data: {
+    type: number;
+    resolved: {
+      /** 按钮 action.data 值 */
+      button_data?: string;
+      /** 按钮 id */
+      button_id?: string;
+      /** 操作用户 userid（仅频道场景） */
+      user_id?: string;
+      /** 自定义菜单 id（仅菜单场景） */
+      feature_id?: string;
+      /** 操作的消息 id（仅频道场景） */
+      message_id?: string;
+      /** 配置更新：群消息模式 "mention"=@机器人时激活 "always"=总是激活 */
+      require_mention?: string;
+      /** 配置更新：群消息策略 */
+      group_policy?: GroupPolicy;
+      /** 配置更新：@文本的名称提及BOT名，多个使用,分隔 */
+      mention_patterns?: string;
+    };
+  };
+}
+
+/**
+ * WebSocket 事件负载
+ */
+export interface WSPayload {
+  op: number;
+  d?: unknown;
+  s?: number;
+  t?: string;
+}
+
+
+
+// ---- 流式消息常量 ----
+
+/** 流式消息输入模式 */
+export const StreamInputMode = {
+  /** 每次发送的 content_raw 替换整条消息内容 */
+  REPLACE: "replace",
+} as const;
+export type StreamInputMode = (typeof StreamInputMode)[keyof typeof StreamInputMode];
+
+/** 流式消息输入状态 */
+export const StreamInputState = {
+  /** 正文生成中 */
+  GENERATING: 1,
+  /** 正文生成结束（终结状态） */
+  DONE: 10,
+} as const;
+export type StreamInputState = (typeof StreamInputState)[keyof typeof StreamInputState];
+
+/** 流式消息内容类型 */
+export const StreamContentType = {
+  MARKDOWN: "markdown",
+} as const;
+export type StreamContentType = (typeof StreamContentType)[keyof typeof StreamContentType];
+
+/**
+ * 流式消息请求体
+ * 对应 StreamReq proto
+ */
+export interface StreamMessageRequest {
+  /** 输入模式 */
+  input_mode: StreamInputMode;
+  /** 输入状态 */
+  input_state: StreamInputState;
+  /** 内容类型 */
+  content_type: StreamContentType;
+  /** markdown 内容 */
+  content_raw: string;
+  /** 事件 ID */
+  event_id: string;
+  /** 原始消息 ID */
+  msg_id: string;
+  /** 流式消息 ID，首次发送后返回，后续分片需携带 */
+  stream_msg_id?: string;
+  /** 递增序号 */
+  msg_seq: number;
+  /** 同一条流式会话内的发送索引，从 0 开始，每次发送前递增；新流式会话重新从 0 开始 */
+  index: number;
+}
+
+/**
+ * 流式消息响应体
+ * 对应 StreamRsp proto
+ * 
+ * 成功时返回：{ id, timestamp, extInfo }（无 code/message）
+ * 失败时返回：{ code, message }（code > 0）
+ */
+export interface StreamMessageResponse {
+  /** 错误码，仅失败时存在（> 0 表示失败）；成功时不存在 */
+  code?: number;
+  /** 错误信息，仅失败时存在 */
+  message?: string;
+  /** 流式消息 ID */
+  id?: string;
+  /** 时间戳 */
+  timestamp?: string;
+  /** 扩展信息 */
+  extInfo?: Record<string, unknown>;
+}

package/src/typing-keepalive.ts

@@ -0,0 +1,59 @@
+/**
+ * 输入状态自动续期
+ * 在消息处理期间定时续发 "正在输入" 状态通知，确保用户持续看到 bot 在处理中。
+ * 仅 C2C 私聊有效（QQ 群聊 API 不支持输入状态通知）。
+ */
+
+import { sendC2CInputNotify } from "./api.js";
+
+// 每 50 秒续发一次（QQ API input_second=60，留 10s 余量）
+export const TYPING_INTERVAL_MS = 50_000;
+export const TYPING_INPUT_SECOND = 60;
+
+export class TypingKeepAlive {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private stopped = false;
+
+  constructor(
+    private readonly getToken: () => Promise<string>,
+    private readonly clearCache: () => void,
+    private readonly openid: string,
+    private readonly msgId: string | undefined,
+    private readonly log?: { info: (msg: string) => void; error: (msg: string) => void; debug?: (msg: string) => void },
+    private readonly logPrefix = "[qqbot]",
+  ) {}
+
+  /** 启动定时续期（首次发送由调用方自行处理，这里只负责后续续期） */
+  start(): void {
+    if (this.stopped) return;
+    this.timer = setInterval(() => {
+      if (this.stopped) { this.stop(); return; }
+      this.send().catch(() => {});
+    }, TYPING_INTERVAL_MS);
+  }
+
+  /** 停止续期 */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private async send(): Promise<void> {
+    try {
+      const token = await this.getToken();
+      await sendC2CInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+      this.log?.debug?.(`${this.logPrefix} Typing keep-alive sent to ${this.openid}`);
+    } catch (err) {
+      try {
+        this.clearCache();
+        const token = await this.getToken();
+        await sendC2CInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+      } catch {
+        this.log?.debug?.(`${this.logPrefix} Typing keep-alive failed for ${this.openid}: ${err}`);
+      }
+    }
+  }
+}

package/src/update-checker.ts

@@ -0,0 +1,174 @@
+/**
+ * 版本检查器
+ *
+ * - triggerUpdateCheck(): gateway 启动时调用，后台预热缓存
+ * - getUpdateInfo(): 每次实时查询 npm registry，返回最新结果
+ *
+ * 使用 HTTPS 直接请求 npm registry API（不依赖 npm CLI），
+ * 支持多 registry fallback：npmjs.org → npmmirror.com，解决国内网络问题。
+ */
+
+import { createRequire } from "node:module";
+import https from "node:https";
+import { getPackageVersion } from "./utils/pkg-version.js";
+
+const require = createRequire(import.meta.url);
+
+const PKG_NAME = "@tencent-connect/openclaw-qqbot";
+const ENCODED_PKG = encodeURIComponent(PKG_NAME);
+
+const REGISTRIES = [
+  `https://registry.npmjs.org/${ENCODED_PKG}`,
+  `https://registry.npmmirror.com/${ENCODED_PKG}`,
+];
+
+let CURRENT_VERSION = getPackageVersion(import.meta.url);
+
+export interface UpdateInfo {
+  current: string;
+  /** 最佳升级目标（prerelease 用户优先 alpha，稳定版用户取 latest） */
+  latest: string | null;
+  /** 稳定版 dist-tag */
+  stable: string | null;
+  /** alpha dist-tag */
+  alpha: string | null;
+  hasUpdate: boolean;
+  checkedAt: number;
+  error?: string;
+}
+
+let _log: { info: (msg: string) => void; error: (msg: string) => void; debug?: (msg: string) => void } | undefined;
+
+function fetchJson(url: string, timeoutMs: number): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { timeout: timeoutMs, headers: { Accept: "application/json" } }, (res) => {
+      if (res.statusCode !== 200) {
+        res.resume();
+        reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+        return;
+      }
+      let data = "";
+      res.on("data", (chunk: string) => { data += chunk; });
+      res.on("end", () => {
+        try { resolve(JSON.parse(data)); } catch (e) { reject(e); }
+      });
+    });
+    req.on("error", reject);
+    req.on("timeout", () => { req.destroy(); reject(new Error(`timeout fetching ${url}`)); });
+  });
+}
+
+async function fetchDistTags(): Promise<Record<string, string>> {
+  for (const url of REGISTRIES) {
+    try {
+      const json = await fetchJson(url, 10_000);
+      const tags = json["dist-tags"];
+      if (tags && typeof tags === "object") return tags;
+    } catch (e: any) {
+      _log?.debug?.(`[qqbot:update-checker] ${url} failed: ${e.message}`);
+    }
+  }
+  throw new Error("all registries failed");
+}
+
+function buildUpdateInfo(tags: Record<string, string>): UpdateInfo {
+  const currentIsPrerelease = CURRENT_VERSION.includes("-");
+  const stableTag = tags.latest || null;
+  const alphaTag = tags.alpha || null;
+
+  // 严格隔离：alpha 只跟 alpha 比，正式版只跟正式版比，不交叉
+  const compareTarget = currentIsPrerelease ? alphaTag : stableTag;
+
+  const hasUpdate = typeof compareTarget === "string"
+    && compareTarget !== CURRENT_VERSION
+    && compareVersions(compareTarget, CURRENT_VERSION) > 0;
+
+  return {
+    current: CURRENT_VERSION,
+    latest: compareTarget,
+    stable: stableTag,
+    alpha: alphaTag,
+    hasUpdate,
+    checkedAt: Date.now(),
+  };
+}
+
+/** gateway 启动时调用，保存 log 引用 */
+export function triggerUpdateCheck(log?: {
+  info: (msg: string) => void;
+  error: (msg: string) => void;
+  debug?: (msg: string) => void;
+}): void {
+  if (log) _log = log;
+  // 预热：fire-and-forget
+  getUpdateInfo().then((info) => {
+    if (info.hasUpdate) {
+      _log?.info?.(`[qqbot:update-checker] new version available: ${info.latest} (current: ${CURRENT_VERSION})`);
+    }
+  }).catch(() => {});
+}
+
+/** 每次实时查询 npm registry */
+export async function getUpdateInfo(): Promise<UpdateInfo> {
+  try {
+    const tags = await fetchDistTags();
+    return buildUpdateInfo(tags);
+  } catch (err: any) {
+    _log?.debug?.(`[qqbot:update-checker] check failed: ${err.message}`);
+    return { current: CURRENT_VERSION, latest: null, stable: null, alpha: null, hasUpdate: false, checkedAt: Date.now(), error: err.message };
+  }
+}
+
+/**
+ * 检查指定版本是否存在于 npm registry
+ * 用于 /bot-upgrade --version 的前置校验
+ */
+export async function checkVersionExists(version: string): Promise<boolean> {
+  for (const baseUrl of REGISTRIES) {
+    try {
+      const url = `${baseUrl}/${version}`;
+      const json = await fetchJson(url, 10_000);
+      if (json && json.version === version) return true;
+    } catch {
+      // try next registry
+    }
+  }
+  return false;
+}
+
+function compareVersions(a: string, b: string): number {
+  const parse = (v: string) => {
+    const clean = v.replace(/^v/, "");
+    const [main, pre] = clean.split("-", 2);
+    return { parts: main.split(".").map(Number), pre: pre || null };
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  // 先比主版本号
+  for (let i = 0; i < 3; i++) {
+    const diff = (pa.parts[i] || 0) - (pb.parts[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  // 主版本号相同：正式版 > prerelease
+  if (!pa.pre && pb.pre) return 1;
+  if (pa.pre && !pb.pre) return -1;
+  if (!pa.pre && !pb.pre) return 0;
+  // 都是 prerelease：按段逐一比较（alpha.1 vs alpha.2）
+  const aParts = pa.pre!.split(".");
+  const bParts = pb.pre!.split(".");
+  for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+    const aP = aParts[i] ?? "";
+    const bP = bParts[i] ?? "";
+    const aNum = Number(aP);
+    const bNum = Number(bP);
+    // 都是数字则按数字比较
+    if (!isNaN(aNum) && !isNaN(bNum)) {
+      if (aNum !== bNum) return aNum - bNum;
+    } else {
+      // 字符串比较
+      if (aP < bP) return -1;
+      if (aP > bP) return 1;
+    }
+  }
+  return 0;
+}