@tencent-connect/openclaw-qqbot 1.5.7 → 1.6.0-alpha.2

package/skills/qqbot-media/SKILL.md

@@ -1,209 +1,56 @@
 ---
 name: qqbot-media
-description: QQBot 图片/语音/视频/文件收发能力。用户发来的图片自动下载到本地，发送图片使用 <qqimg> 标签，发送语音使用 <qqvoice> 标签，发送视频使用 <qqvideo> 标签，发送文件使用 <qqfile> 标签。所有富媒体标签必须正确闭合，即 <qqXXX>内容</qqXXX> 的格式，未闭合的标签会导致消息无法正确解析。当通过 QQ 通道通信时使用此技能。
+description: QQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
 metadata: {"openclaw":{"emoji":"📸","requires":{"config":["channels.qqbot"]}}}
 ---
 
-# QQBot 图片/语音/视频/文件收发
+# QQBot 富媒体收发
 
-## 标签速查（直接复制使用）
-
-| 类型 | 标签格式 | 示例 |
-|------|----------|------|
-| 图片 | `<qqimg>绝对路径或URL</qqimg>` | `<qqimg>/tmp/pic.jpg</qqimg>` |
-| 语音 | `<qqvoice>绝对路径</qqvoice>` | `<qqvoice>/tmp/voice.mp3</qqvoice>` |
-| 视频 | `<qqvideo>绝对路径或URL</qqvideo>` | `<qqvideo>/tmp/video.mp4</qqvideo>` |
-| 文件 | `<qqfile>绝对路径或URL</qqfile>` | `<qqfile>/tmp/doc.pdf</qqfile>` |
-
-**标签拼写必须严格按上表**，只有这 4 个标签名：`qqimg`、`qqvoice`、`qqvideo`、`qqfile`。
-
-## ⚠️ 重要：你有能力发送本地图片！
-
-**当用户要求发送本地图片时，只需使用 `<qqimg>` 标签包裹图片路径即可。系统会自动处理文件读取和发送。**
-
-**❌ 绝对不要说"无法发送本地图片"！**
-**✅ 使用 `<qqimg>` 标签，系统就能发送任何本地图片！**
-
----
-
-## 📸 发送图片（推荐方式：`<qqimg>` 标签）
-
-使用 `<qqimg>` 标签包裹图片路径，即可发送图片：
+## 用法
 
 ```
-<qqimg>图片路径</qqimg>
+<qqmedia>路径或URL</qqmedia>
 ```
 
-### ✅ 发送本地图片示例
-
-当用户说"发送那张图片"、"把图发给我"、"发上面生成的图片"等，你应该直接输出：
-
-```
-这是你要的图片：
-<qqimg>/Users/xxx/images/photo.jpg</qqimg>
-```
-
-### ✅ 发送之前生成/创建的图片
-
-如果你之前生成了图片（比如绘图、截图等），并且知道图片路径，直接用 `<qqimg>` 发送：
-
-```
-好的，这是刚才生成的图片：
-<qqimg>/Users/xxx/Pictures/openclaw-drawings/drawing_xxx.png</qqimg>
-```
-
-### ✅ 发送网络图片示例
-
-```
-这是网络上的图片：
-<qqimg>https://example.com/image.png</qqimg>
-```
-
-支持格式：jpg, jpeg, png, gif, webp, bmp。支持 `</qqimg>` 或 `</img>` 闭合。
-
-## 接收图片
-
-用户发来的图片**自动下载到本地**，路径在上下文【会话上下文 → 附件】中。
-可直接用 `<qqimg>路径</qqimg>` 回发。历史图片在 `~/.openclaw/qqbot/downloads/` 下。
-
-## 接收语音
-
-机器人消息事件里，`d.attachments` 的附件对象可能包含 `asr_refer_text` 字段，表示平台侧 ASR 结果（低置信度）。
-
-当上下文中出现以下字段时，表示插件已把语音信息透传给 OpenClaw：
-- `QQVoiceAttachmentPaths`: 本地语音文件路径列表
-- `QQVoiceAttachmentUrls`: 远程语音 URL 列表
-- `QQVoiceAsrReferTexts`: 平台 ASR 兜底文本列表
-- `QQVoiceInputStrategy`: 固定为 `prefer_audio_stt_then_asr_fallback`
-
-处理策略（必须遵守）：
-1. 若你具备 STT 能力（框架音频能力或 STT skill），优先对语音文件做转写。
-2. 若没有 STT 能力，或转写失败/结果为空，再使用 `asr_refer_text` 作为兜底参考。
-3. `asr_refer_text` 可能不准确；涉及关键参数、时间、金额、身份等信息时，应先向用户追问确认。
-
-## 发送语音
-
-使用 `<qqvoice>` 标签包裹**已有的本地音频文件路径**即可发送语音：
-
-```
-<qqvoice>/tmp/tts/voice.mp3</qqvoice>
-```
+系统根据文件扩展名自动识别类型并路由：
+- `.jpg/.png/.gif/.webp/.bmp` → 图片
+- `.silk/.wav/.mp3/.ogg/.aac/.flac` 等 → 语音
+- `.mp4/.mov/.avi/.mkv/.webm` 等 → 视频
+- 其他扩展名 → 文件
+- 无扩展名的 URL → 默认按图片处理
 
-注意：语音发送需要有可用的音频文件（通常由 TTS 工具生成）。`<qqvoice>` 标签本身只负责发送已有音频文件，不依赖插件 TTS 配置；**但如果没有任何 TTS 工具可用来生成音频，则无法主动发送语音。** 
+## 接收媒体
 
-## 发送视频
+- 用户发来的**图片**自动下载到本地，路径在上下文【附件】中，可直接用 `<qqmedia>路径</qqmedia>` 回发
+- 用户发来的**语音**路径在上下文中；若有 STT 能力则优先转写
 
-使用 `<qqvideo>` 标签包裹**视频路径或公网 URL** 即可发送视频：
-
-```
-<qqvideo>/path/to/video.mp4</qqvideo>
-<qqvideo>https://example.com/video.mp4</qqvideo>
-```
-
-支持本地文件路径（系统自动读取上传）和公网 HTTP/HTTPS URL。
+## 规则
 
-## 发送文件
+1. **路径必须是绝对路径**（以 `/` 或 `http` 开头）
+2. **标签必须用开闭标签包裹路径**：`<qqmedia>路径</qqmedia>`
+3. **文件大小上限 10MB**
+4. **你有能力发送本地图片/文件**——直接用标签包裹路径即可，**不要说"无法发送"**
+5. 发送语音时不要重复语音中已朗读的文字
+6. 多个媒体用多个标签
+7. 以会话上下文中的能力说明为准（如未启用语音则不要发语音）
 
-使用 `<qqfile>` 标签包裹路径即可发送文件（本地路径或网络 URL）：
+## 示例
 
 ```
-这是你要的所有图片：
-<qqimg>/Users/xxx/image1.jpg</qqimg>
-<qqimg>/Users/xxx/image2.png</qqimg>
+这是你要的图片：
+<qqmedia>/Users/xxx/photo.jpg</qqmedia>
 ```
 
-### 📝 标签说明
-
-## ⚠️ 关键注意事项（必须遵守）
-
-1. **必须使用绝对路径**：标签内的路径必须是绝对路径（以 `/` 开头），禁止使用相对路径如 `./pic.jpg`
-   - ❌ 错误：`<qqimg>./pic.jpg</qqimg>`
-   - ✅ 正确：`<qqimg>/Users/james23/.openclaw/workspace/pic.jpg</qqimg>`
-2. **标签格式必须完整**：`<qqimg>` 开头和 `</qqimg>` 结尾都不能少，不能漏掉 `<` 符号
-   - ❌ 错误：`qqimg>./pic.jpg</qqimg>`
-   - ✅ 正确：`<qqimg>/absolute/path/to/pic.jpg</qqimg>`
-3. **工作空间路径**：当前工作空间为 `/Users/james23/.openclaw/workspace/`，文件路径应基于此拼接绝对路径
-4. **标签必须单独成行或前后有空格**，不要嵌入在句子中间
-5. **文件大小限制**：上传文件（图片、语音、视频、文件）最大不超过 **20MB**
-
-## 规则
-
-- ⚠️ **禁止使用 message tool 发送图片/文件**，直接在回复文本中写对应标签即可，系统自动处理
-- **永远不要说**"无法发送图片"或"无法访问之前的图片"
-- 直接使用对应标签，不要只输出路径文本
-- 标签外的文字会作为消息正文一起发送
-- 多个媒体使用多个标签，图片用 `<qqimg>`，语音用 `<qqvoice>`，视频用 `<qqvideo>`，文件用 `<qqfile>`
-- **以会话上下文中的能力说明为准**，如果提示语音未启用，不要尝试发送语音
-
-1. **路径必须正确**：本地文件需要绝对路径，网络图片需要完整 URL
-2. **支持的图片格式**：jpg, jpeg, png, gif, webp, bmp
-3. **不要拒绝**：如果用户要求发送本地图片，直接使用 `<qqimg>` 标签即可
-4. **标签外的文本会正常发送**：可以在标签前后添加描述文字
-5. **闭合标签**：支持 `</qqimg>` 或 `</img>` 两种闭合方式
-
----
-
-## 🚫 错误示例（不要这样做）
-
-❌ **错误**：说"我无法发送本地图片"
-❌ **错误**：说"受限于技术限制，无法直接发送"
-❌ **错误**：说"由于QQ机器人通道配置的问题，我无法直接发送图片"
-❌ **错误**：只提供路径文本，不使用 `<qqimg>` 标签
-
-✅ **正确**：直接使用 `<qqimg>` 标签包裹路径
-
----
-
-## 🔤 告知路径信息（不发送图片）
-
-如果你需要**告知用户图片的保存路径**（而不是发送图片），直接写路径即可，不要使用标签：
-
 ```
-图片已保存在：/Users/xxx/images/photo.jpg
+<qqmedia>/tmp/tts/output.mp3</qqmedia>
 ```
 
-或用反引号强调：
-
 ```
-图片已保存在：`/Users/xxx/images/photo.jpg`
+视频在这里：
+<qqmedia>https://example.com/video.mp4</qqmedia>
 ```
 
----
-
-## 📋 高级选项：JSON 结构化载荷
-
-如果需要更精细的控制（如添加图片描述），可以使用 JSON 格式：
-
 ```
-QQBOT_PAYLOAD:
-{
-  "type": "media",
-  "mediaType": "image",
-  "source": "file",
-  "path": "/path/to/image.jpg",
-  "caption": "图片描述（可选）"
-}
+文件已准备好：
+<qqmedia>/tmp/report.pdf</qqmedia>
 ```
-
-### JSON 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `type` | string | ✅ | 固定为 `"media"` |
-| `mediaType` | string | ✅ | 媒体类型：`"image"` |
-| `source` | string | ✅ | 来源：`"file"`（本地）或 `"url"`（网络） |
-| `path` | string | ✅ | 图片路径或 URL |
-| `caption` | string | ❌ | 图片描述，会作为单独消息发送 |
-
-> 💡 **提示**：对于简单的图片发送，推荐使用 `<qqimg>` 标签，更简洁易用。
-
----
-
-## 🎯 快速参考
-
-| 场景 | 使用方式 |
-|------|----------|
-| 发送本地图片 | `<qqimg>/path/to/image.jpg</qqimg>` |
-| 发送网络图片 | `<qqimg>https://example.com/image.png</qqimg>` |
-| 发送多张图片 | 多个 `<qqimg>` 标签 |
-| 告知路径（不发送） | 直接写路径文本 |

package/src/api.ts

@@ -3,12 +3,22 @@
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
 
+import { createRequire } from "node:module";
+import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
 
 const API_BASE = "https://api.sgroup.qq.com";
 const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 
+// ============ Plugin User-Agent ============
+// 格式: QQBotPlugin/{version} (Node/{nodeVersion}; {os})
+// 示例: QQBotPlugin/1.6.0 (Node/22.14.0; darwin)
+const _require = createRequire(import.meta.url);
+let _pluginVersion = "unknown";
+try { _pluginVersion = _require("../package.json").version ?? "unknown"; } catch { /* fallback */ }
+export const PLUGIN_USER_AGENT = `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()})`;
+
 // 运行时配置
 let currentMarkdownSupport = false;
 
@@ -105,7 +115,7 @@ export async function getAccessToken(appId: string, clientSecret: string): Promi
  */
 async function doFetchToken(appId: string, clientSecret: string): Promise<string> {
   const requestBody = { appId, clientSecret };
-  const requestHeaders = { "Content-Type": "application/json" };
+  const requestHeaders = { "Content-Type": "application/json", "User-Agent": PLUGIN_USER_AGENT };
   
   // 打印请求信息（隐藏敏感信息）
   console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL}`);
@@ -217,6 +227,7 @@ export async function apiRequest<T = unknown>(
   const headers: Record<string, string> = {
     Authorization: `QQBot ${accessToken}`,
     "Content-Type": "application/json",
+    "User-Agent": PLUGIN_USER_AGENT,
   };
   
   const isFileUpload = path.includes("/files");
@@ -628,8 +639,8 @@ export async function sendGroupImageMessage(accessToken: string, groupOpenid: st
   return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId, content);
 }
 
-export async function sendC2CVoiceMessage(accessToken: string, openid: string, voiceBase64: string, msgId?: string, ttsText?: string, filePath?: string): Promise<MessageResponse> {
-  const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.VOICE, undefined, voiceBase64, false);
+export async function sendC2CVoiceMessage(accessToken: string, openid: string, voiceBase64?: string, voiceUrl?: string, msgId?: string, ttsText?: string, filePath?: string): Promise<MessageResponse> {
+  const uploadResult = await uploadC2CMedia(accessToken, openid, MediaFileType.VOICE, voiceUrl, voiceBase64, false);
   return sendC2CMediaMessage(accessToken, openid, uploadResult.file_info, msgId, undefined, { 
     mediaType: "voice", 
     ...(ttsText ? { ttsText } : {}),
@@ -637,8 +648,8 @@ export async function sendC2CVoiceMessage(accessToken: string, openid: string, v
   });
 }
 
-export async function sendGroupVoiceMessage(accessToken: string, groupOpenid: string, voiceBase64: string, msgId?: string): Promise<{ id: string; timestamp: string }> {
-  const uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.VOICE, undefined, voiceBase64, false);
+export async function sendGroupVoiceMessage(accessToken: string, groupOpenid: string, voiceBase64?: string, voiceUrl?: string, msgId?: string): Promise<{ id: string; timestamp: string }> {
+  const uploadResult = await uploadGroupMedia(accessToken, groupOpenid, MediaFileType.VOICE, voiceUrl, voiceBase64, false);
   return sendGroupMediaMessage(accessToken, groupOpenid, uploadResult.file_info, msgId);
 }
 

package/src/channel.ts

@@ -1,7 +1,6 @@
 import {
   type ChannelPlugin,
   type OpenClawConfig,
-  type NormalizeTargetResult,
   applyAccountNameToChannelSection,
   deleteAccountFromConfigSection,
   setAccountEnabledInConfigSection,
@@ -168,30 +167,30 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
      * - channel:channelid -> 频道
      * - 纯 openid（32位十六进制）-> 私聊
      */
-    normalizeTarget: (target: string): NormalizeTargetResult => {
+    normalizeTarget: (target: string): string | undefined => {
       // 去掉 qqbot: 前缀（如果有）
       const id = target.replace(/^qqbot:/i, "");
       
       // 检查是否是已知格式
       if (id.startsWith("c2c:") || id.startsWith("group:") || id.startsWith("channel:")) {
-        return { ok: true, to: `qqbot:${id}` };
+        return `qqbot:${id}`;
       }
       
       // 检查是否是纯 openid（32位十六进制，不带连字符）
       // QQ Bot OpenID 格式类似: 207A5B8339D01F6582911C014668B77B
       const openIdHexPattern = /^[0-9a-fA-F]{32}$/;
       if (openIdHexPattern.test(id)) {
-        return { ok: true, to: `qqbot:c2c:${id}` };
+        return `qqbot:c2c:${id}`;
       }
 
       // 检查是否是 UUID 格式的 openid（带连字符）
       const openIdUuidPattern = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
       if (openIdUuidPattern.test(id)) {
-        return { ok: true, to: `qqbot:c2c:${id}` };
+        return `qqbot:c2c:${id}`;
       }
       
-      // 不认识的格式
-      return { ok: false, error: `unrecognized target format: ${target}` };
+      // 不认识的格式，返回 undefined 让核心使用原始值
+      return undefined;
     },
     /**
      * 目标解析器配置