mirror of
https://mirror.skon.top/github.com/sliverp/qqbot
synced 2026-05-01 06:10:58 +08:00
Merge branch 'fix/repo-migration-and-scripts'
This commit is contained in:
rianli
65
README.md
65
README.md
@@ -10,7 +10,7 @@
|
||||
|
||||
[](./LICENSE)
|
||||
[](https://bot.q.qq.com/wiki/)
|
||||
[](https://github.com/tencent-connect/openclaw-qq)
|
||||
[](https://github.com/tencent-connect/openclaw-qqbot)
|
||||
[](https://nodejs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
|
||||
@@ -50,6 +50,8 @@ Scan to join the QQ group chat
|
||||
<details>
|
||||
<summary><b>🎙️ Voice Messages (STT)</b> — AI understands voice messages, auto-transcribes speech to text</summary>
|
||||
|
||||
With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.
|
||||
|
||||
> **You**: *(send a voice message)* "What's the weather like tomorrow in Shenzhen?"
|
||||
>
|
||||
> **QQBot**: Tomorrow (March 7, Saturday) Shenzhen weather forecast 🌤️ ...
|
||||
@@ -61,6 +63,8 @@ Scan to join the QQ group chat
|
||||
<details>
|
||||
<summary><b>📄 File Understanding</b> — Send any file, AI reads and understands it</summary>
|
||||
|
||||
Send any file to the bot — novels, reports, spreadsheets — AI automatically recognizes the content and gives an intelligent reply.
|
||||
|
||||
> **You**: *(send a TXT file of "War and Peace")*
|
||||
>
|
||||
> **QQBot**: Got it! You uploaded the Chinese version of "War and Peace" by Leo Tolstoy. This appears to be the opening of Chapter 1...
|
||||
@@ -72,6 +76,8 @@ Scan to join the QQ group chat
|
||||
<details>
|
||||
<summary><b>🖼️ Image Understanding</b> — Vision-capable models can see and describe images</summary>
|
||||
|
||||
If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI can understand images too. This is a general multimodal capability, not plugin-specific.
|
||||
|
||||
> **You**: *(send an image)*
|
||||
>
|
||||
> **QQBot**: Haha, so cute! Is that a QQ penguin in a lobster costume? 🦞🐧 ...
|
||||
@@ -87,6 +93,12 @@ Scan to join the QQ group chat
|
||||
>
|
||||
> **QQBot**: Here you go! 🐱
|
||||
|
||||
AI uses the `<qqimg>` tag to send images. Both local file paths and URLs are supported. Formats: jpg/png/gif/webp/bmp.
|
||||
|
||||
```
|
||||
<qqimg>~/.openclaw/qqbot/images/cute-cat.png</qqimg>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
|
||||
|
||||
</details>
|
||||
@@ -98,6 +110,12 @@ Scan to join the QQ group chat
|
||||
>
|
||||
> **QQBot**: *(sends a voice message)*
|
||||
|
||||
AI uses the `<qqvoice>` tag to send voice messages. Formats: mp3/wav/silk/ogg. Works without ffmpeg.
|
||||
|
||||
```
|
||||
<qqvoice>~/.openclaw/qqbot/tts/joke.silk</qqvoice>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
|
||||
|
||||
</details>
|
||||
@@ -109,6 +127,12 @@ Scan to join the QQ group chat
|
||||
>
|
||||
> **QQBot**: *(sends a .txt file)*
|
||||
|
||||
AI uses the `<qqfile>` tag to send files. PDF, Excel, ZIP, TXT — any format, up to 20MB.
|
||||
|
||||
```
|
||||
<qqfile>~/.openclaw/qqbot/downloads/war-and-peace-ch1.txt</qqfile>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
|
||||
|
||||
</details>
|
||||
@@ -120,11 +144,40 @@ Scan to join the QQ group chat
|
||||
>
|
||||
> **QQBot**: *(sends a video)*
|
||||
|
||||
AI uses the `<qqvideo>` tag to send videos. Both local files and URLs are supported. Large files (>5MB) auto-show "uploading..." status.
|
||||
|
||||
```
|
||||
<qqvideo>~/.openclaw/qqbot/downloads/demo.mp4</qqvideo>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
|
||||
|
||||
</details>
|
||||
|
||||
> For a deep dive into rich media capabilities, see the [Media Guide](docs/qqbot-media-guide.md).
|
||||
### Rich Media Tag Reference
|
||||
|
||||
| Tag | Direction | Usage | Notes |
|
||||
|-----|-----------|-------|-------|
|
||||
| `<qqimg>path</qqimg>` | Send | Image | Local path or URL, jpg/png/gif/webp/bmp |
|
||||
| `<qqvoice>path</qqvoice>` | Send | Voice | mp3/wav/silk/ogg, no ffmpeg required |
|
||||
| `<qqfile>path</qqfile>` | Send | File | Any format, up to 20MB |
|
||||
| `<qqvideo>path</qqvideo>` | Send | Video | Local path or URL |
|
||||
| Voice message | Receive | STT | Auto-transcribe with configured STT model |
|
||||
| File attachment | Receive | File | Auto-download and feed content to AI |
|
||||
| Image attachment | Receive | Vision | Requires vision-capable model |
|
||||
|
||||
### Try It Yourself
|
||||
|
||||
| Direction | You say | AI does |
|
||||
|-----------|---------|---------|
|
||||
| Receive voice | Send a voice message asking about weather | STT auto-transcribes, AI replies with text |
|
||||
| Receive file | Send a file to the bot | AI reads file content, gives intelligent reply |
|
||||
| Send image | "Draw me a cat" | Calls drawing tool, sends image back |
|
||||
| Send voice | "Tell me a joke in voice" | TTS generates voice, sends voice message |
|
||||
| Send file | "Generate a file for me" | Creates file, sends via `<qqfile>` |
|
||||
| Send video | "Send me a video" | Sends video via `<qqvideo>` |
|
||||
|
||||
**Under the hood:** Tag variant auto-correction (30+ variants like `<qq_img>`, `<image>`, `＜qqimg＞` are all recognized), upload caching (dedup within short windows), ordered queue delivery, and multi-layer audio format fallback.
|
||||
|
||||
---
|
||||
|
||||
@@ -165,7 +218,7 @@ Scan to join the QQ group chat
|
||||
**Option A: One-Click Install & Run (Recommended)**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tencent-connect/openclaw-qq.git && cd openclaw-qq
|
||||
git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
|
||||
bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
|
||||
```
|
||||
|
||||
@@ -174,7 +227,7 @@ The script handles everything: cleanup old plugins → install deps → register
|
||||
**Option B: Manual Step-by-Step**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tencent-connect/openclaw-qq.git && cd openclaw-qq
|
||||
git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
|
||||
npm install --omit=dev
|
||||
openclaw plugins install .
|
||||
```
|
||||
@@ -412,7 +465,7 @@ bash ./scripts/pull-latest.sh --repo <git-url> # use a different repo
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tencent-connect/openclaw-qq.git && cd openclaw-qq
|
||||
git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
|
||||
npm install --omit=dev
|
||||
bash ./scripts/upgrade.sh
|
||||
openclaw plugins install .
|
||||
@@ -424,7 +477,7 @@ openclaw gateway restart
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- [Rich Media Guide](docs/qqbot-media-guide.md) — images, voice, video, files
|
||||
- [Rich Media Guide](docs/qqbot-media-guide.md) — detailed STT/TTS config examples and tag usage
|
||||
- [Command Reference](docs/commands.md) — OpenClaw CLI commands
|
||||
- [Changelog](docs/changelog/) — release notes ([latest: 1.5.4](docs/changelog/1.5.4.md))
|
||||
|
||||
|
||||
65
README.zh.md
65
README.zh.md
@@ -10,7 +10,7 @@
|
||||
|
||||
[](./LICENSE)
|
||||
[](https://bot.q.qq.com/wiki/)
|
||||
[](https://github.com/tencent-connect/openclaw-qq)
|
||||
[](https://github.com/tencent-connect/openclaw-qqbot)
|
||||
[](https://nodejs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
|
||||
@@ -47,6 +47,8 @@
|
||||
<details>
|
||||
<summary><b>🎙️ 语音消息（STT）</b> — 配置 STT 后，自动将语音转录为文字理解</summary>
|
||||
|
||||
配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
|
||||
|
||||
> **你**：*（发送一段语音）*"明天深圳天气怎么样"
|
||||
>
|
||||
> **QQBot**：明天（3月7日 周六）深圳的天气预报 🌤️ ...
|
||||
@@ -58,6 +60,8 @@
|
||||
<details>
|
||||
<summary><b>📄 文件理解</b> — 发文件给 AI，自动识别内容并智能回复</summary>
|
||||
|
||||
用户发文件给 AI，AI 同样能接住。不管是一本小说还是一份报告，AI 会自动识别文件内容并给出智能回复。
|
||||
|
||||
> **你**：*（发送《战争与和平》TXT 文件）*
|
||||
>
|
||||
> **QQBot**：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？
|
||||
@@ -69,6 +73,8 @@
|
||||
<details>
|
||||
<summary><b>🖼️ 图片理解</b> — 主模型支持视觉能力时，发图片 AI 也能看懂</summary>
|
||||
|
||||
如果主模型支持视觉（如腾讯混元 `hunyuan-vision`），用户发图片 AI 也能看懂。这是多模态模型的通用能力，非插件专属功能。
|
||||
|
||||
> **你**：*（发送一张图片）*
|
||||
>
|
||||
> **QQBot**：哈哈，好可爱！这是QQ企鹅穿上小龙虾套装吗？🦞🐧 ...
|
||||
@@ -84,6 +90,12 @@
|
||||
>
|
||||
> **QQBot**：给你画好了！🐱
|
||||
|
||||
AI 通过 `<qqimg>` 标签发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
|
||||
|
||||
```
|
||||
<qqimg>~/.openclaw/qqbot/images/cute-cat.png</qqimg>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
|
||||
|
||||
</details>
|
||||
@@ -95,6 +107,12 @@
|
||||
>
|
||||
> **QQBot**：*（发送一条语音消息）*
|
||||
|
||||
AI 通过 `<qqvoice>` 标签发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
|
||||
|
||||
```
|
||||
<qqvoice>~/.openclaw/qqbot/tts/joke.silk</qqvoice>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
|
||||
|
||||
</details>
|
||||
@@ -106,6 +124,12 @@
|
||||
>
|
||||
> **QQBot**：*（发送 .txt 文件）*
|
||||
|
||||
AI 通过 `<qqfile>` 标签发送文件。PDF、Excel、ZIP、TXT，什么格式都能发，最大 20MB。
|
||||
|
||||
```
|
||||
<qqfile>~/.openclaw/qqbot/downloads/战争与和平_第一章.txt</qqfile>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
|
||||
|
||||
</details>
|
||||
@@ -117,11 +141,40 @@
|
||||
>
|
||||
> **QQBot**：*（发送视频）*
|
||||
|
||||
AI 通过 `<qqvideo>` 标签发送视频，支持本地文件和公网 URL。大文件（>5MB）自动提示"正在上传..."。
|
||||
|
||||
```
|
||||
<qqvideo>~/.openclaw/qqbot/downloads/demo.mp4</qqvideo>
|
||||
```
|
||||
|
||||
<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
|
||||
|
||||
</details>
|
||||
|
||||
> 富媒体能力（图片、语音、视频、文件）的完整说明请参阅 [富媒体指南](docs/qqbot-media-guide.md)。
|
||||
### 富媒体标签参考
|
||||
|
||||
| 标签 | 方向 | 用途 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `<qqimg>路径</qqimg>` | 发送 | 图片 | 本地路径或 URL，jpg/png/gif/webp/bmp |
|
||||
| `<qqvoice>路径</qqvoice>` | 发送 | 语音 | mp3/wav/silk/ogg，无需 ffmpeg |
|
||||
| `<qqfile>路径</qqfile>` | 发送 | 文件 | 任意格式，最大 20MB |
|
||||
| `<qqvideo>路径</qqvideo>` | 发送 | 视频 | 本地路径或 URL |
|
||||
| 语音消息 | 接收 | STT | 自动转录，需配置 STT 模型 |
|
||||
| 文件附件 | 接收 | 文件 | 自动下载并将内容交给 AI |
|
||||
| 图片附件 | 接收 | 视觉 | 需主模型支持视觉能力 |
|
||||
|
||||
### 体验演示场景
|
||||
|
||||
| 方向 | 你说 | AI 做 |
|
||||
|------|------|-------|
|
||||
| 接收语音 | 发送一段语音提问天气 | STT 自动转录，AI 理解后文字回复 |
|
||||
| 接收文件 | 发送一个文件给机器人 | AI 识别文件内容，智能分析回复 |
|
||||
| 发送图片 | "帮我画一只猫咪" | 调用绘图工具，生成图片发回 |
|
||||
| 发送语音 | "用语音讲个笑话" | TTS 生成语音，直接发送语音消息 |
|
||||
| 发送文件 | "帮我生成一个文件" | 生成文件并通过 `<qqfile>` 发送 |
|
||||
| 发送视频 | "发个视频给我" | 通过 `<qqvideo>` 直接发送视频 |
|
||||
|
||||
**底层细节：** 标签容错（自动纠正 `<qq_img>`、`<image>`、`＜qqimg＞` 等 30 多种变体写法）、上传缓存（短时间内相同文件自动复用）、有序队列发送（混合消息按顺序投递，单项失败不影响其他）、音频格式多层降级。
|
||||
|
||||
---
|
||||
|
||||
@@ -161,7 +214,7 @@
|
||||
**方式一：一键安装并启动（推荐）**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tencent-connect/openclaw-qq.git && cd openclaw-qq
|
||||
git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
|
||||
bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
|
||||
```
|
||||
|
||||
@@ -170,7 +223,7 @@ bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
|
||||
**方式二：手动分步安装**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tencent-connect/openclaw-qq.git && cd openclaw-qq
|
||||
git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
|
||||
npm install --omit=dev
|
||||
openclaw plugins install .
|
||||
```
|
||||
@@ -408,7 +461,7 @@ bash ./scripts/pull-latest.sh --repo <git-url> # 使用其他仓库地
|
||||
### 从源码升级
|
||||
|
||||
```bash
|
||||
git clone https://github.com/tencent-connect/openclaw-qq.git && cd openclaw-qq
|
||||
git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
|
||||
npm install --omit=dev
|
||||
bash ./scripts/upgrade.sh
|
||||
openclaw plugins install .
|
||||
@@ -420,7 +473,7 @@ openclaw gateway restart
|
||||
|
||||
## 📚 文档
|
||||
|
||||
- [富媒体指南](docs/qqbot-media-guide.md) — 图片、语音、视频、文件
|
||||
- [富媒体指南](docs/qqbot-media-guide.md) — 详细的 STT/TTS 配置示例和标签用法
|
||||
- [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
|
||||
- [更新日志](docs/changelog/) — 各版本变更记录（[最新: 1.5.4](docs/changelog/1.5.4.md)）
|
||||
|
||||
|
||||
Reference in New Issue
Block a user