@tencent-connect/openclaw-qqbot 1.6.3 → 1.6.4-alpha.qqchannel

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.2`
+### 🚀 Current Version: `v1.5.7`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -99,7 +99,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 >
 > **QQBot**: Here you go! 🐱
 
-AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
+AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
 
@@ -109,7 +109,7 @@ AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif
 >
 > **QQBot**: *(sends a voice message)*
 
-AI can send voice messages directly. Formats: mp3/wav/silk/ogg. No ffmpeg required.
+AI sends voice via `<qqvoice>path</qqvoice>`. Formats: mp3/wav/silk/ogg. No ffmpeg required.
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
 
@@ -129,7 +129,7 @@ This capability depends on OpenClaw cron scheduling and proactive messaging. If
 >
 > **QQBot**: *(sends a .txt file)*
 
-AI can send files directly. Any format, up to 20MB.
+AI sends files via `<qqfile>path</qqfile>`. Any format, up to 20MB.
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
 
@@ -139,63 +139,21 @@ AI can send files directly. Any format, up to 20MB.
 >
 > **QQBot**: *(sends a video)*
 
-AI can send videos directly. Supports local files and URLs.
+AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. Large files (>5MB) auto-show upload progress.
 
 <img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
 
-> **Under the hood:** Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
+### Rich Media Tag Reference
 
-### 🛠️ Slash Commands
+| Tag | Direction | Notes |
+|-----|-----------|-------|
+| `<qqimg>path</qqimg>` | Send | jpg/png/gif/webp/bmp, local path or URL |
+| `<qqvoice>path</qqvoice>` | Send | mp3/wav/silk/ogg, no ffmpeg required |
+| `<qqfile>path</qqfile>` | Send | Any format, up to 20MB |
+| `<qqvideo>path</qqvideo>` | Send | Local path or URL |
+| Voice / File / Image | Receive | Auto-transcribe (STT), auto-download, or vision analysis |
 
-The plugin provides built-in slash commands that are intercepted before reaching the AI queue, giving instant responses for diagnostics and management.
-
-#### `/bot-ping` — Latency Test
-
-> **You**: `/bot-ping`
->
-> **QQBot**: ✅ pong！⏱ Latency: 602ms (network: 602ms, plugin: 0ms)
-
-Measures end-to-end latency from QQ server push to plugin response, broken down into network transport and plugin processing time.
-
-<img width="360" src="docs/images/slash-ping.jpg" alt="Ping Demo" />
-
-#### `/bot-version` — Version Info
-
-> **You**: `/bot-version`
->
-> **QQBot**: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.2 / 🌟 GitHub repo
-
-Shows framework version, plugin version, and a direct link to the official repository.
-
-<img width="360" src="docs/images/slash-version.jpg" alt="Version Demo" />
-
-#### `/bot-help` — Command List
-
-> **You**: `/bot-help`
->
-> **QQBot**: Lists all available slash commands with clickable shortcuts.
-
-<img width="360" src="docs/images/slash-help.jpg" alt="Help Demo" />
-
-#### `/bot-upgrade` — Upgrade Guide
-
-> **You**: `/bot-upgrade`
->
-> **QQBot**: 📌 Current version / ✅ Up to date / ⬆️ Upgrade guide / 🌟 GitHub repo
-
-Shows current version, update status, upgrade guide link, and official repository.
-
-<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade Demo" /> 
-
-#### `/bot-logs` — Log Export
-
-> **You**: `/bot-logs`
->
-> **QQBot**: 📋 Logs packaged (~2000 lines), sending file... *(sends a .txt file)*
-
-Exports the last ~2000 lines of gateway logs as a file for quick troubleshooting.
-
-<img width="360" src="docs/images/slash-logs.jpg" alt="Logs Demo" />
+> **Under the hood:** 30+ tag variant auto-correction, upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
 
 ---
 
@@ -421,7 +379,7 @@ STT supports two-level configuration with priority fallback:
 - `provider` — references a key in `models.providers` to inherit `baseUrl` and `apiKey`
 - `voice` — voice variant
 - Set `enabled: false` to disable (default: `true`)
-- When configured, AI can generate and send voice messages
+- When configured, AI can use `<qqvoice>` tags to generate and send voice messages
 
 ---
 

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.2`
+### 🚀 当前版本： `v1.5.7`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -94,7 +94,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：画好啦！一只可爱的简笔小猫咪🐱🎨
 
-AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
+AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
 
@@ -104,7 +104,7 @@ AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/
 >
 > **QQBot**：*（发送一条语音消息）*
 
-AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
+AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
 
@@ -124,7 +124,7 @@ AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 可直接发送文件。任意格式，最大 20MB。
+AI 通过 `<qqfile>路径</qqfile>` 发送文件。任意格式，最大 20MB。
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
 
@@ -134,63 +134,21 @@ AI 可直接发送文件。任意格式，最大 20MB。
 >
 > **QQBot**：*（发送视频）*
 
-AI 可直接发送视频，支持本地文件和公网 URL。
+AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网 URL。大文件（>5MB）自动提示上传进度。
 
 <img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
 
-> **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
+### 富媒体标签参考
 
-### 🛠️ 斜杠指令
+| 标签 | 方向 | 说明 |
+|------|------|------|
+| `<qqimg>路径</qqimg>` | 发送 | jpg/png/gif/webp/bmp，本地路径或 URL |
+| `<qqvoice>路径</qqvoice>` | 发送 | mp3/wav/silk/ogg，无需 ffmpeg |
+| `<qqfile>路径</qqfile>` | 发送 | 任意格式，最大 20MB |
+| `<qqvideo>路径</qqvideo>` | 发送 | 本地路径或 URL |
+| 语音 / 文件 / 图片 | 接收 | 自动转录(STT)、自动下载、或视觉分析 |
 
-插件内置一组斜杠指令，在消息进入 AI 队列前拦截处理，即时响应，用于诊断和管理。
-
-#### `/bot-ping` — 延迟测试
-
-> **你**：`/bot-ping`
->
-> **QQBot**：✅ pong！⏱ 延迟: 602ms（网络传输: 602ms，插件处理: 0ms）
-
-测量从 QQ 服务器推送到插件响应的端到端延迟，细分网络传输和插件处理两段耗时。
-
-<img width="360" src="docs/images/slash-ping.jpg" alt="Ping 演示" />
-
-#### `/bot-version` — 版本信息
-
-> **你**：`/bot-version`
->
-> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.2 / 🌟官方 GitHub 仓库
-
-一目了然查看框架版本、插件版本，并可直接跳转官方仓库。
-
-<img width="360" src="docs/images/slash-version.jpg" alt="Version 演示" />
-
-#### `/bot-help` — 指令列表
-
-> **你**：`/bot-help`
->
-> **QQBot**：列出所有可用的斜杠指令及说明，指令可点击快速输入。
-
-<img width="360" src="docs/images/slash-help.jpg" alt="Help 演示" />
-
-#### `/bot-upgrade` — 升级指引
-
-> **你**：`/bot-upgrade`
->
-> **QQBot**：📌当前版本 / ✅当前已是最新版本 / ⬆️升级指引 / 🌟官方 GitHub 仓库
-
-显示当前版本、更新状态、升级文档链接及官方仓库入口。
-
-<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade 演示" /> 
-
-#### `/bot-logs` — 日志导出
-
-> **你**：`/bot-logs`
->
-> **QQBot**：📋 日志已打包（约 2000 行），正在发送文件… *（发送 .txt 文件）*
-
-导出最近约 2000 行网关日志为文件，方便快速排查问题。
-
-<img width="360" src="docs/images/slash-logs.jpg" alt="Logs 演示" />
+> **底层细节：** 30+ 种标签变体自动纠正、上传去重缓存、有序队列发送、音频格式多层降级。
 
 ---
 
@@ -416,7 +374,7 @@ STT 支持两级配置，按优先级查找：
 - `provider` — 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`
 - `voice` — 语音音色
 - 设置 `enabled: false` 可禁用（默认：`true`）
-- 配置后，AI 可生成并发送语音消息
+- 配置后，AI 可使用 `<qqvoice>` 标签生成并发送语音消息
 
 ---
 

package/clawdbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -1,6 +1,7 @@
 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";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -9,6 +10,7 @@ const plugin = {
     register(api) {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
+        registerChannelTool(api);
     },
 };
 export default plugin;

package/dist/src/api.d.ts

@@ -81,6 +81,15 @@ export declare function sendChannelMessage(accessToken: string, channelId: strin
     id: string;
     timestamp: string;
 }>;
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export declare function sendDmMessage(accessToken: string, guildId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
 export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
 export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
 export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{

package/dist/src/api.js

@@ -58,12 +58,8 @@ const tokenFetchPromises = new Map();
 export async function getAccessToken(appId, clientSecret) {
     const normalizedAppId = String(appId).trim();
     const cachedToken = tokenCacheMap.get(normalizedAppId);
-    // 检查缓存：未过期时复用
-    // 提前刷新阈值：取 expiresIn 的 1/3 和 5 分钟的较小值，避免短有效期 token 永远被判定过期
-    const REFRESH_AHEAD_MS = cachedToken
-        ? Math.min(5 * 60 * 1000, (cachedToken.expiresAt - Date.now()) / 3)
-        : 0;
-    if (cachedToken && Date.now() < cachedToken.expiresAt - REFRESH_AHEAD_MS) {
+    // 检查缓存：未过期 且 appId 未变化 时复用
+    if (cachedToken && Date.now() < cachedToken.expiresAt - 5 * 60 * 1000) {
         return cachedToken.token;
     }
     // Singleflight: 如果当前 appId 已有进行中的 Token 获取请求，复用它
@@ -163,8 +159,7 @@ export function getTokenStatus(appId) {
     if (!cached) {
         return { status: "none", expiresAt: null };
     }
-    const remaining = cached.expiresAt - Date.now();
-    const isValid = remaining > Math.min(5 * 60 * 1000, remaining / 3);
+    const isValid = Date.now() < cached.expiresAt - 5 * 60 * 1000;
     return { status: isValid ? "valid" : "expired", expiresAt: cached.expiresAt };
 }
 /**
@@ -340,6 +335,17 @@ export async function sendChannelMessage(accessToken, channelId, content, msgId)
         ...(msgId ? { msg_id: msgId } : {}),
     });
 }
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export async function sendDmMessage(accessToken, guildId, content, msgId) {
+    return apiRequest(accessToken, "POST", `/dms/${guildId}/messages`, {
+        content,
+        ...(msgId ? { msg_id: msgId } : {}),
+    });
+}
 export async function sendGroupMessage(accessToken, groupOpenid, content, msgId) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
     const body = buildMessageBody(content, msgId, msgSeq);

package/dist/src/channel.d.ts

@@ -1,11 +1,3 @@
 import { type ChannelPlugin } from "openclaw/plugin-sdk";
 import type { ResolvedQQBotAccount } from "./types.js";
-/** QQ Bot 单条消息文本长度上限 */
-export declare const TEXT_CHUNK_LIMIT = 5000;
-/**
- * Markdown 感知的文本分块函数
- * 委托给 SDK 内置的 channel.text.chunkMarkdownText
- * 支持代码块自动关闭/重开、括号感知等
- */
-export declare function chunkText(text: string, limit: number): string[];
 export declare const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount>;

package/dist/src/channel.js

@@ -4,16 +4,34 @@ import { sendText, sendMedia } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
-/** QQ Bot 单条消息文本长度上限 */
-export const TEXT_CHUNK_LIMIT = 5000;
 /**
- * Markdown 感知的文本分块函数
- * 委托给 SDK 内置的 channel.text.chunkMarkdownText
- * 支持代码块自动关闭/重开、括号感知等
+ * 简单的文本分块函数
+ * 用于预先分块长文本
  */
-export function chunkText(text, limit) {
-    const runtime = getQQBotRuntime();
-    return runtime.channel.text.chunkMarkdownText(text, limit);
+function chunkText(text, limit) {
+    if (text.length <= limit)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= limit) {
+            chunks.push(remaining);
+            break;
+        }
+        // 尝试在换行处分割
+        let splitAt = remaining.lastIndexOf("\n", limit);
+        if (splitAt <= 0 || splitAt < limit * 0.5) {
+            // 没找到合适的换行，尝试在空格处分割
+            splitAt = remaining.lastIndexOf(" ", limit);
+        }
+        if (splitAt <= 0 || splitAt < limit * 0.5) {
+            // 还是没找到，强制在 limit 处分割
+            splitAt = limit;
+        }
+        chunks.push(remaining.slice(0, splitAt));
+        remaining = remaining.slice(splitAt).trimStart();
+    }
+    return chunks;
 }
 export const qqbotPlugin = {
     id: "qqbot",
@@ -34,7 +52,7 @@ export const qqbotPlugin = {
          * blockStreaming: true 表示该 Channel 支持块流式
          * 框架会收集流式响应，然后通过 deliver 回调发送
          */
-        blockStreaming: true,
+        blockStreaming: false,
     },
     reload: { configPrefixes: ["channels.qqbot"] },
     // CLI onboarding wizard
@@ -187,9 +205,9 @@ export const qqbotPlugin = {
     },
     outbound: {
         deliveryMode: "direct",
-        chunker: (text, limit) => getQQBotRuntime().channel.text.chunkMarkdownText(text, limit),
+        chunker: chunkText,
         chunkerMode: "markdown",
-        textChunkLimit: 5000,
+        textChunkLimit: 2000,
         sendText: async ({ to, text, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);