@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/commands/bot-ping.ts

@@ -0,0 +1,33 @@
+import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
+
+/** /bot-ping — 测试当前 openclaw 与 QQ 连接的网络延迟 */
+export function botPing(): SlashCommand {
+  return {
+    name: 'bot-ping',
+    description: '测试当前 openclaw 与 QQ 连接的网络延迟',
+    usage: [
+      '/bot-ping',
+      '',
+      '测试 OpenClaw 主机与 QQ 服务器之间的网络延迟。',
+      '返回网络传输耗时和插件处理耗时。',
+    ].join('\n'),
+    handler: (ctx) => {
+      const now = Date.now();
+      const ts = (ctx.message as any).timestamp;
+      const eventTime = ts ? new Date(ts).getTime() : NaN;
+      if (isNaN(eventTime)) {
+        return '✅ pong!';
+      }
+      const totalMs = now - eventTime;
+      const qqToPlugin = ctx.receivedAt - eventTime;
+      const pluginProcess = now - ctx.receivedAt;
+      return [
+        '✅ pong！',
+        '',
+        `⏱ 延迟: ${totalMs}ms`,
+        `  ├ 网络传输: ${qqToPlugin}ms`,
+        `  └ 插件处理: ${pluginProcess}ms`,
+      ].join('\n');
+    },
+  };
+}

package/src/commands/bot-streaming.ts

@@ -0,0 +1,55 @@
+import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { updateAccountConfig, checkCommandAuth } from './config-util.js';
+
+/** /bot-streaming — 一键开关流式消息 */
+export function botStreaming(account: ResolvedQQBotAccount, getRuntime: () => PluginRuntime): SlashCommand {
+  return {
+    name: 'bot-streaming',
+    description: '一键开关流式消息',
+    scope: 'c2c',
+    authorized: checkCommandAuth,
+    usage: `/bot-streaming
+
+查看当前流式消息状态，或切换开/关。
+流式消息仅支持 C2C（私聊）场景。`,
+    handler: async (ctx) => {
+      const args = (Array.isArray(ctx.command.args) ? ctx.command.args.join(' ') : String(ctx.command.args ?? '')).trim().toLowerCase();
+      const streaming = account.config?.streaming;
+      const currentEnabled = typeof streaming === 'boolean'
+        ? streaming
+        : (streaming as any)?.mode !== 'off';
+
+      // 无参数 → 显示状态
+      if (!args) {
+        const status = currentEnabled ? '✅ 已启用' : '❌ 未启用';
+        const toggleHint = currentEnabled
+          ? '<qqbot-cmd-input text="/bot-streaming off" show="关闭流式"/>'
+          : '<qqbot-cmd-input text="/bot-streaming on" show="开启流式"/>';
+        return [
+          `🌊 流式消息状态: ${status}`,
+          '',
+          '流式消息仅支持 C2C（私聊）场景。',
+          `点击 ${toggleHint} 切换。`,
+        ].join('\n');
+      }
+
+      // on / off → 切换
+      const targetEnabled = args === 'on' || args === '1' || args === 'true';
+      if (targetEnabled === currentEnabled) {
+        return `ℹ️ 流式消息已经是${currentEnabled ? '开启' : '关闭'}状态，无需切换。`;
+      }
+
+      const error = await updateAccountConfig(account, getRuntime, (acfg) => {
+        (acfg as any).streaming = { mode: targetEnabled ? 'partial' : 'off' };
+      });
+      if (error) return error;
+
+      account.config.streaming = { mode: targetEnabled ? 'partial' : 'off' };
+      return targetEnabled
+        ? '✅ 流式消息已开启，私聊消息将以流式方式发送。'
+        : '✅ 流式消息已关闭，私聊消息将以静态方式发送。';
+    },
+  };
+}

package/src/commands/bot-upgrade.ts

@@ -0,0 +1,56 @@
+import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { getPackageVersion } from '../utils/pkg-version.js';
+import { getUpdateInfo } from '../features/update-checker.js';
+import { checkCommandAuth } from './config-util.js';
+
+const PLUGIN_VERSION = getPackageVersion();
+const DEFAULT_UPGRADE_URL = 'https://docs.qq.com/doc/DSGxOZk1oVnVKVkpq';
+const GITHUB_URL = 'https://github.com/nicepkg/openclaw';
+
+/** /bot-upgrade — 检查更新并查看升级指引 */
+export function botUpgrade(account: ResolvedQQBotAccount): SlashCommand {
+  return {
+    name: 'bot-upgrade',
+    description: '检查更新并查看升级指引',
+    scope: 'c2c',
+    authorized: checkCommandAuth,
+    usage: [
+      '/bot-upgrade              检查是否有新版本',
+    ].join('\n'),
+    handler: async () => {
+      const url = account.config.upgradeUrl ?? DEFAULT_UPGRADE_URL;
+      const info = await getUpdateInfo();
+
+      if (info.checkedAt === 0) {
+        return '⏳ 版本检查中，请稍后再试';
+      }
+
+      if (info.error) {
+        return [
+          '❌ 主机网络访问异常，无法检查更新',
+          '',
+          `查看升级指引：[点击查看](${url})`,
+        ].join('\n');
+      }
+
+      if (!info.hasUpdate) {
+        return [
+          `✅ 当前已是最新版本 v${PLUGIN_VERSION}`,
+          '',
+          `项目地址：[GitHub](${GITHUB_URL})`,
+        ].join('\n');
+      }
+
+      return [
+        '🆕 发现新版本',
+        '',
+        `当前版本：**v${PLUGIN_VERSION}**`,
+        `最新版本：**v${info.latest}**`,
+        '',
+        `📖 升级指引：[点击查看](${url})`,
+        `🌟 官方 GitHub 仓库：[点击前往](${GITHUB_URL})`,
+      ].join('\n');
+    },
+  };
+}

package/src/commands/bot-version.ts

@@ -0,0 +1,41 @@
+import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { getPackageVersion } from '../utils/pkg-version.js';
+import { getUpdateInfo } from '../features/update-checker.js';
+import { getOpenClawVersion } from '../bot-instance.js';
+
+const PLUGIN_VERSION = getPackageVersion();
+const GITHUB_URL = 'https://github.com/nicepkg/openclaw';
+
+/** /bot-version — 查看插件版本号 */
+export function botVersion(_account: ResolvedQQBotAccount): SlashCommand {
+  return {
+    name: 'bot-version',
+    description: '查看插件版本号',
+    usage: [
+      '/bot-version',
+      '',
+      '查看当前 QQBot 插件版本和 OpenClaw 框架版本。',
+      '同时检查是否有新版本可用。',
+    ].join('\n'),
+    handler: async () => {
+      const frameworkVersion = getOpenClawVersion();
+      const lines = [
+        `🦞框架版本：${frameworkVersion}`,
+        `🤖QQBot 插件版本：v${PLUGIN_VERSION}`,
+      ];
+
+      const info = await getUpdateInfo();
+      if (info.checkedAt === 0) {
+        lines.push('⏳ 版本检查中...');
+      } else if (info.error) {
+        lines.push('⚠️ 版本检查失败');
+      } else if (info.hasUpdate && info.latest) {
+        lines.push(`🆕最新可用版本：v${info.latest}，点击 <qqbot-cmd-input text="/bot-upgrade" show="/bot-upgrade"/> 查看升级指引`);
+      }
+
+      lines.push(`🌟官方 GitHub 仓库：[点击前往](${GITHUB_URL})`);
+      return lines.join('\n');
+    },
+  };
+}

package/src/commands/config-util.ts

@@ -0,0 +1,96 @@
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { SlashCommandHandlerContext } from '@tencent-connect/qqbot-nodejs';
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import { getAdapters } from '../adapter/resolve.js';
+
+/**
+ * 命令授权检查（用于 SlashCommand.authorized 回调）。
+ *
+ * 规则：
+ * - mode=open → 允许
+ * - allowFrom 为空或含 "*" → 允许
+ * - senderId 在 allowFrom 中 → 允许
+ * - 否则 → 返回错误消息
+ */
+export function checkCommandAuth(ctx: SlashCommandHandlerContext): boolean | string {
+  const p = (ctx.state as any).policy;
+  const mode = p?.c2cMode ?? 'allowlist';
+  const allowFrom: string[] = p?.allowFrom ?? [];
+  if (mode === 'open' || !allowFrom.length || allowFrom.includes('*')) return true;
+  return allowFrom.includes(ctx.message.senderId) || '⚠️ 无权限执行此命令';
+}
+
+interface PersistResult {
+  persist: (updater: (cfg: any) => void) => Promise<void>;
+}
+
+/**
+ * 底层：获取 persistConfig，统一处理 runtime/adapters 判空。
+ * @returns [error, result] — error 非空时不可用；result.persist 直接调 persistConfig。
+ */
+async function resolvePersistFn(getRuntime: () => PluginRuntime): Promise<[string | null, PersistResult | null]> {
+  const runtime = getRuntime();
+  if (!runtime) return ['⚠️ runtime 不可用，无法修改配置。', null];
+
+  const adapters = getAdapters(runtime);
+  if (!adapters.persistConfig) {
+    return ['⚠️ 当前框架版本不支持在线修改配置，请手动编辑配置文件。', null];
+  }
+
+  return [
+    null,
+    { persist: (updater: (cfg: any) => void) => adapters.persistConfig!(updater) },
+  ];
+}
+
+/**
+ * 持久化更新**账户**配置。自动处理命名账户 / 默认账户路径差异。
+ */
+export async function updateAccountConfig(
+  account: ResolvedQQBotAccount,
+  getRuntime: () => PluginRuntime,
+  updater: (accountConfig: Record<string, unknown>) => void,
+): Promise<string | null> {
+  const [err, result] = await resolvePersistFn(getRuntime);
+  if (err || !result) return err;
+
+  try {
+    await result.persist((cfg: any) => {
+      cfg.channels ??= {};
+      cfg.channels.qqbot ??= {};
+
+      const qqbot = cfg.channels.qqbot;
+      const accountId = account.accountId;
+      const isNamedAccount = accountId !== 'default' && qqbot.accounts?.[accountId];
+
+      if (isNamedAccount) {
+        qqbot.accounts[accountId] ??= {};
+        updater(qqbot.accounts[accountId]);
+      } else {
+        updater(qqbot);
+      }
+    });
+    return null;
+  } catch (e) {
+    return `⚠️ 配置修改失败：${e instanceof Error ? e.message : String(e)}`;
+  }
+}
+
+/**
+ * 持久化更新**框架通用**配置（不从 channels.qqbot.accounts 走）。
+ * 适用于 tools.exec 等非账户级字段。
+ */
+export async function updateGlobalConfig(
+  getRuntime: () => PluginRuntime,
+  updater: (cfg: any) => void,
+): Promise<string | null> {
+  const [err, result] = await resolvePersistFn(getRuntime);
+  if (err || !result) return err;
+
+  try {
+    await result.persist(updater);
+    return null;
+  } catch (e) {
+    return `⚠️ 配置修改失败：${e instanceof Error ? e.message : String(e)}`;
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,49 @@
+/**
+ * 斜杠命令注册表
+ *
+ * 通过 SDK 的 slashCommand 中间件统一注册所有内置命令。
+ * 每个命令拆分为独立文件，此处仅编排。
+ */
+import type { SlashCommand } from '@tencent-connect/qqbot-nodejs';
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { ResolvedQQBotAccount } from '../types.js';
+import { botHelp } from './bot-help.js';
+import { botPing } from './bot-ping.js';
+import { botVersion } from './bot-version.js';
+import { botMe } from './bot-me.js';
+import { botUpgrade } from './bot-upgrade.js';
+import { botStreaming } from './bot-streaming.js';
+import { botClearStorage } from './bot-clear-storage.js';
+import { botLogs } from './bot-logs.js';
+import { botApprove } from './bot-approve.js';
+import { botGroupAlways } from './bot-group-always.js';
+import { botPairing } from './bot-pairing.js';
+
+export interface CommandBuildOptions {
+  getRuntime: () => PluginRuntime;
+}
+
+/**
+ * 构建标准命令列表（匹配后直接回复，不进入 AI）
+ */
+export function buildCommandList(account: ResolvedQQBotAccount, opts: CommandBuildOptions): SlashCommand[] {
+  const commands: SlashCommand[] = [];
+
+  // help 需要访问完整命令列表，延迟绑定
+  const help = botHelp(account, () => commands);
+  commands.push(
+    help,
+    botPing(),
+    botVersion(account),
+    botMe(),
+    botUpgrade(account),
+    botLogs(opts.getRuntime()),
+    botStreaming(account, opts.getRuntime),
+    botClearStorage(account),
+    botApprove(opts.getRuntime),
+    botGroupAlways(account, opts.getRuntime),
+    botPairing(opts.getRuntime),
+  );
+
+  return commands;
+}

package/src/config.ts

@@ -69,6 +69,8 @@ function evaluateMatchedGroupAccessForPolicy(params: {
 }
 
 interface QQBotChannelConfig extends QQBotAccountConfig {
+  /** HTTP/WebSocket User-Agent 追加后缀 */
+  userAgentSuffix?: string;
   accounts?: Record<string, QQBotAccountConfig>;
 }
 
@@ -77,7 +79,10 @@ interface QQBotChannelConfig extends QQBotAccountConfig {
 const DEFAULT_GROUP_POLICY: GroupPolicy = "open";
 
 /** 群历史缓存条数默认值 */
-const DEFAULT_GROUP_HISTORY_LIMIT = 50;
+const DEFAULT_GROUP_HISTORY_LIMIT = 20;
+
+/** 单条消息默认处理超时（0 = 不限制） */
+const DEFAULT_PROCESSING_TIMEOUT_MS = 0;
 
 const DEFAULT_GROUP_CONFIG: Omit<Required<GroupConfig>, "prompt"> = {
   requireMention: true,
@@ -108,8 +113,9 @@ export function resolveGroupAllowFrom(cfg: OpenClawConfig, accountId?: string):
 
 /** 检查指定群是否被允许（使用标准策略引擎） */
 export function isGroupAllowed(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): boolean {
-  const policy = resolveGroupPolicy(cfg, accountId);
-  const allowList = resolveGroupAllowFrom(cfg, accountId);
+  const account = resolveQQBotAccount(cfg, accountId);
+  const policy = account.config?.groupPolicy ?? DEFAULT_GROUP_POLICY;
+  const allowList = (account.config?.groupAllowFrom ?? []).map((id) => String(id).trim().toUpperCase());
   const allowlistConfigured = allowList.length > 0;
   const allowlistMatched = allowList.some((id) => id === "*" || id === groupOpenid.toUpperCase());
 
@@ -120,26 +126,28 @@ export function isGroupAllowed(cfg: OpenClawConfig, groupOpenid: string, account
   }).allowed;
 }
 
-type ResolvedGroupConfig = Omit<Required<GroupConfig>, "prompt"> & Pick<GroupConfig, "prompt">;
+export type ResolvedGroupConfig = Required<GroupConfig>;
 
-/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 默认值） */
-export function resolveGroupConfig(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): ResolvedGroupConfig {
-  const account = resolveQQBotAccount(cfg, accountId);
+export function resolveGroupConfigFromAccount(account: ResolvedQQBotAccount, groupOpenid: string): ResolvedGroupConfig {
   const groups = account.config?.groups ?? {};
-
   const wildcardCfg = groups["*"] ?? {};
   const specificCfg = groups[groupOpenid] ?? {};
+  const accountDefaultRequireMention = account.config?.defaultRequireMention ?? DEFAULT_GROUP_CONFIG.requireMention;
 
   return {
-    requireMention: specificCfg.requireMention ?? wildcardCfg.requireMention ?? DEFAULT_GROUP_CONFIG.requireMention,
+    requireMention: specificCfg.requireMention ?? wildcardCfg.requireMention ?? accountDefaultRequireMention,
     ignoreOtherMentions: specificCfg.ignoreOtherMentions ?? wildcardCfg.ignoreOtherMentions ?? DEFAULT_GROUP_CONFIG.ignoreOtherMentions,
     toolPolicy: specificCfg.toolPolicy ?? wildcardCfg.toolPolicy ?? DEFAULT_GROUP_CONFIG.toolPolicy,
     name: specificCfg.name ?? wildcardCfg.name ?? DEFAULT_GROUP_CONFIG.name,
-    prompt: specificCfg.prompt ?? wildcardCfg.prompt,
+    prompt: specificCfg.prompt ?? wildcardCfg.prompt ?? DEFAULT_GROUP_PROMPT,
     historyLimit: specificCfg.historyLimit ?? wildcardCfg.historyLimit ?? DEFAULT_GROUP_CONFIG.historyLimit,
   };
 }
 
+export function resolveGroupConfig(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): ResolvedGroupConfig {
+  return resolveGroupConfigFromAccount(resolveQQBotAccount(cfg, accountId), groupOpenid);
+}
+
 /** 解析群历史消息缓存条数 */
 export function resolveHistoryLimit(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): number {
   return Math.max(0, resolveGroupConfig(cfg, groupOpenid, accountId).historyLimit);
@@ -147,10 +155,7 @@ export function resolveHistoryLimit(cfg: OpenClawConfig, groupOpenid: string, ac
 
 /** 解析群行为 PE（具体群 > "*" > 默认值） */
 export function resolveGroupPrompt(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): string {
-  const account = resolveQQBotAccount(cfg, accountId);
-  const groups = account.config?.groups ?? {};
-
-  return groups[groupOpenid]?.prompt ?? groups["*"]?.prompt ?? DEFAULT_GROUP_PROMPT;
+  return resolveGroupConfig(cfg, groupOpenid, accountId).prompt;
 }
 
 /** 解析群是否需要 @机器人才响应 */
@@ -174,6 +179,14 @@ export function resolveGroupName(cfg: OpenClawConfig, groupOpenid: string, accou
   return name || groupOpenid.slice(0, 8);
 }
 
+/**
+ * 解析 User-Agent 追加后缀（仅通道级：channels.qqbot.userAgentSuffix）
+ */
+export function resolveUserAgentSuffix(cfg: OpenClawConfig): string {
+  const qqbot = cfg.channels?.qqbot as QQBotChannelConfig | undefined;
+  return qqbot?.userAgentSuffix ? String(qqbot.userAgentSuffix).trim() : "";
+}
+
 function normalizeAppId(raw: unknown): string {
   if (raw === null || raw === undefined) return "";
   return String(raw).trim();
@@ -220,6 +233,25 @@ export function resolveDefaultQQBotAccountId(cfg: OpenClawConfig): string {
   return DEFAULT_ACCOUNT_ID;
 }
 
+/**
+ * 解析单条消息处理超时时间（ms）。
+ * 优先级：账户配置 > 环境变量 OPENCLAW_PROCESSING_TIMEOUT_MS > 默认
+ * 返回 0 表示不限制超时。
+ */
+export function resolveProcessingTimeoutMs(
+  accountConfig?: QQBotAccountConfig,
+): number {
+  if (accountConfig?.processingTimeoutMs !== undefined) {
+    return accountConfig.processingTimeoutMs;
+  }
+  const env = process.env.OPENCLAW_PROCESSING_TIMEOUT_MS;
+  if (env) {
+    const v = Number(env);
+    if (!Number.isNaN(v) && v >= 0) return v;
+  }
+  return DEFAULT_PROCESSING_TIMEOUT_MS;
+}
+
 /**
  * 解析 QQBot 账户配置
  */
@@ -276,19 +308,29 @@ export function resolveQQBotAccount(
     clientSecret,
     secretSource,
     systemPrompt: accountConfig.systemPrompt,
-    imageServerBaseUrl: accountConfig.imageServerBaseUrl || process.env.QQBOT_IMAGE_SERVER_BASE_URL,
     markdownSupport: accountConfig.markdownSupport !== false,
-    config: accountConfig,
+    userAgentSuffix: resolveUserAgentSuffix(cfg),
+    processingTimeoutMs: resolveProcessingTimeoutMs(accountConfig),
+    config: normalizeAccountConfig(accountConfig),
   };
 }
 
+/** 兼容旧版 streaming: boolean 格式 → { mode: "partial" | "off" }，对齐框架 schema */
+function normalizeAccountConfig(raw: QQBotAccountConfig): QQBotAccountConfig {
+  if (typeof (raw as any).streaming === 'boolean') {
+    const { streaming, ...rest } = raw as any;
+    return { ...rest, streaming: { mode: streaming ? 'partial' : 'off' } };
+  }
+  return raw;
+}
+
 /**
  * 应用账户配置
  */
 export function applyQQBotAccountConfig(
   cfg: OpenClawConfig,
   accountId: string,
-  input: { appId?: string; clientSecret?: string; clientSecretFile?: string; name?: string; imageServerBaseUrl?: string }
+  input: { appId?: string; clientSecret?: string; clientSecretFile?: string; name?: string }
 ): OpenClawConfig {
   const next = { ...cfg };
 
@@ -310,7 +352,6 @@ export function applyQQBotAccountConfig(
             ? { clientSecretFile: input.clientSecretFile }
             : {}),
         ...(input.name ? { name: input.name } : {}),
-        ...(input.imageServerBaseUrl ? { imageServerBaseUrl: input.imageServerBaseUrl } : {}),
       },
     };
   } else {
@@ -336,7 +377,6 @@ export function applyQQBotAccountConfig(
                 ? { clientSecretFile: input.clientSecretFile }
                 : {}),
             ...(input.name ? { name: input.name } : {}),
-            ...(input.imageServerBaseUrl ? { imageServerBaseUrl: input.imageServerBaseUrl } : {}),
           },
         },
       },