From 98c7a598d8807bffbac90f543be0e194b3998179 Mon Sep 17 00:00:00 2001 From: sliverp Date: Thu, 5 Feb 2026 11:24:58 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E6=A0=BC?= =?UTF-8?q?=E5=BC=8F=E5=92=8C=E5=86=85=E5=AE=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 265 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 151 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index 813d053..3cebdcc 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,96 @@ +
+ # QQ Bot Channel Plugin for Moltbot -QQ 开放平台Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。 +QQ 开放平台 Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。 -## 使用示例： -Clipboard_Screenshot_1770195414 +[![npm version](https://img.shields.io/badge/npm-v1.3.7-blue)](https://www.npmjs.com/package/@sliverp/qqbot) +[![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/) +[![Platform](https://img.shields.io/badge/platform-Moltbot-orange)](https://github.com/sliverp/moltbot) +[![Node.js](https://img.shields.io/badge/Node.js->=18-339933)](https://nodejs.org/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6)](https://www.typescriptlang.org/) +
-## 版本更新 -**使用`openclaw plugins list`来查看插件版本，建议使用最新版的版本** -Clipboard_Screenshot_1769739939 +--- -### 1.4.0（即将更新） -- 支持Markdonw格式 +## ⭐ Star 趋势 - -### 1.3.0-2026.02.03 -- 支持图片收发等功能 - Clipboard_Screenshot_1770112572 + -- 支持定时任务到时后主动推送 - Clipboard_Screenshot_1770112539 -- 优化一些已知问题 -- 支持使用npm等方式安装和升级（暂时不支持更低版本） - - 安装:`openclaw plugins install @sliverp/qqbot@1.3.7` - - 配置：`clawdbot channels add --channel qqbot --token "AppId:AppSecret"` - - 热更新：`npx -y @sliverp/qqbot@1.3.7 upgrade`。如果原来配置过AppId和AppSecret，热更新后无需再次配置。注意：npm和Openclaw会占用大量内存，小内存机器不建议使用，小内存机器建议参考下面源码热更新。 +--- -### 1.2.5-2026.02.02 -- 解除URL发送限制，现在可以直接在私聊发送URL - Clipboard_Screenshot_1770092858 -- 更新Bot正在输入中状态 - Clipboard_Screenshot_1770091969 -- 提供主动推送能力（目前AI还不知道怎么调用主动推送，相关完整Skill能力将在后续版本更新） -- 优化一些已知问题 -- 优化未收到未收到大模型响应时的提示信息 +## 📸 使用示例 +使用示例 -### 1.2.2-2026.01.31 -- 支持发送文件 -- 支持openclaw、moltbot命令行 -- 修复[health]检查提示: [health] refresh failed: Cannot read properties of undefined (reading 'appId')的问题（不影响使用） -- 修复文件发送后clawdbot无法读取的问题 +--- -### 1.2.1 -- 解决了长时间使用会断联的问题 -- 解决了频繁重连的问题 -- 增加了大模型调用失败后的提示消息 +## ✨ 功能特性 +- 🔒 **多场景支持** - C2C 私聊、群聊 @消息、频道消息、频道私信 +- 🖼️ **富媒体消息** - 支持图片收发、文件发送 +- ⏰ **定时推送** - 支持定时任务到时后主动推送 +- 🔗 **URL 无限制** - 私聊可直接发送 URL +- ⌨️ **输入状态** - Bot 正在输入中状态提示 +- 🔄 **热更新** - 支持 npm 方式安装和热更新 +- 📝 **Markdown** - 支持 Markdown 格式（即将更新） -### 1.1.0 -- 解决了一些url会被拦截的问题 -- 解决了多轮消息会发送失败的问题 -- 修复了部分图片无法接受的问题 -- 增加支持onboard的方式配置AppId 和 AppSecret +--- +## 📦 安装 -## 安装 +### 方式一：腾讯云 Lighthouse 镜像（最简单） -现已发布npm，后续配置流程相同 -`openclaw plugins install @sliverp/qqbot@1.3.7` +[![Lighthouse](https://img.shields.io/badge/腾讯云-Lighthouse_镜像-00A4FF)](https://cloud.tencent.com/product/lighthouse) -或者使用源码来安装，在插件目录下执行： +直接使用预装好的腾讯云 Lighthouse 镜像，开箱即用，无需手动安装配置。 + +### 方式二：npm 安装（推荐） + +```bash +openclaw plugins install @sliverp/qqbot@1.3.7 +``` + +### 方式三：源码安装 ```bash git clone https://github.com/sliverp/qqbot.git && cd qqbot -clawdbot plugins install . # 这一步会有点久，需要安装一些依赖。稍微耐心等待一下，尤其是小内存机器 +clawdbot plugins install . ``` -## 配置 +> 💡 安装过程需要一些时间，尤其是小内存机器，请耐心等待 + +--- + +## ⚙️ 配置 ### 1. 获取 QQ 机器人凭证 1. 访问 [QQ 开放平台](https://q.qq.com/) 2. 创建机器人应用 3. 获取 `AppID` 和 `AppSecret`（ClientSecret） -4. Token 格式为 `AppID:AppSecret`，例如 `102146862:Xjv7JVhu7KXkxANbp3HVjxCRgvAPeuAQ` +4. Token 格式：`AppID:AppSecret` ### 2. 添加配置 -#### 方式一：交互式配置 +**交互式配置：** ```bash clawdbot channels add # 选择 qqbot，按提示输入 Token ``` -#### 方式二：命令行配置 +**命令行配置：** ```bash clawdbot channels add --channel qqbot --token "AppID:AppSecret" ``` -示例： - -```bash -clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx" -``` - ### 3. 手动编辑配置（可选） -也可以直接编辑 `~/.clawdbot/clawdbot.json`： +编辑 `~/.clawdbot/clawdbot.json`： ```json { @@ -107,27 +98,28 @@ clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx" "qqbot": { "enabled": true, "appId": "你的AppID", - "clientSecret": "你的AppSecret", - "systemPrompt": "你是一个友好的助手" + "clientSecret": "你的AppSecret" } } } ``` +--- - -## 配置项说明 +## 📋 配置项说明 | 配置项 | 类型 | 必填 | 说明 | |--------|------|------|------| -| `appId` | string | 是 | QQ 机器人 AppID | -| `clientSecret` | string | 是* | AppSecret，与 `clientSecretFile` 二选一 | -| `clientSecretFile` | string | 是* | AppSecret 文件路径 | -| `enabled` | boolean | 否 | 是否启用，默认 `true` | -| `name` | string | 否 | 账户显示名称 | -| `systemPrompt` | string | 否 | 自定义系统提示词 | +| `appId` | string | ✅ | QQ 机器人 AppID | +| `clientSecret` | string | ✅* | AppSecret，与 `clientSecretFile` 二选一 | +| `clientSecretFile` | string | ✅* | AppSecret 文件路径 | +| `enabled` | boolean | ❌ | 是否启用，默认 `true` | +| `name` | string | ❌ | 账户显示名称 | +| `systemPrompt` | string | ❌ | 自定义系统提示词 | -## 支持的消息类型 +--- + +## 📨 支持的消息类型 | 事件类型 | 说明 | Intent | |----------|------|--------| @@ -136,17 +128,17 @@ clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx" | `AT_MESSAGE_CREATE` | 频道 @机器人消息 | `1 << 30` | | `DIRECT_MESSAGE_CREATE` | 频道私信 | `1 << 12` | -## 使用 +--- -### 启动 +## 🚀 使用 + +### 启动服务 -后台启动 ```bash +# 后台启动 clawdbot gateway restart -``` -前台启动, 方便试试查看日志 -```bash +# 前台启动（查看日志） clawdbot gateway --port 18789 --verbose ``` @@ -157,23 +149,35 @@ clawdbot onboard # 选择 QQ Bot 进行交互式配置 ``` -## 注意事项 +--- -1. **群消息**：需要在群内 @机器人 才能触发回复 -2. **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户 +## ⚠️ 注意事项 -## 源码热更新 +- **群消息**：需要在群内 @机器人 才能触发回复 +- **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户 -如果需要升级插件，先运行升级脚本清理旧版本： +--- + +## 🔄 升级 + +### npm 热更新 + +```bash +npx -y @sliverp/qqbot@1.3.7 upgrade +``` + +> 热更新后无需重新配置 AppId 和 AppSecret + +### 源码热更新 ```bash git clone https://github.com/sliverp/qqbot.git && cd qqbot -# 运行升级脚本（清理旧版本和配置） +# 运行升级脚本 bash ./scripts/upgrade.sh -# 重新安装插件 -clawdbot plugins install . # 这一步会有点久，需要安装一些依赖。稍微耐心等待一下，尤其是小内存机器 +# 重新安装 +clawdbot plugins install . # 重新配置 clawdbot channels add --channel qqbot --token "AppID:AppSecret" @@ -182,49 +186,82 @@ clawdbot channels add --channel qqbot --token "AppID:AppSecret" clawdbot gateway restart ``` -升级脚本会自动： -- 删除 `~/.clawdbot/extensions/qqbot` 目录 -- 清理 `clawdbot.json` 中的 qqbot 相关配置 +升级脚本会自动清理旧版本和配置。 -## 开发 +--- -```bash -# 安装依赖 -npm install -# 编译 -npm run build -# 监听模式 -npm run dev -``` +--- -## 文件结构 +## 📚 版本历史 -``` -qqbot/ -├── index.ts # 入口文件 -├── src/ -│ ├── api.ts # QQ Bot API 封装 -│ ├── channel.ts # Channel Plugin 定义 -│ ├── config.ts # 配置解析 -│ ├── gateway.ts # WebSocket 网关 -│ ├── onboarding.ts # CLI 配置向导 -│ ├── outbound.ts # 出站消息处理 -│ ├── runtime.ts # 运行时状态 -│ └── types.ts # 类型定义 -├── scripts/ -│ └── upgrade.sh # 升级脚本 -├── package.json -└── tsconfig.json -``` +
+v1.4.0（即将更新） -## 相关链接 +- 支持 Markdown 格式 + +
+ +
+v1.3.0 - 2026.02.03 + +- ✨ 支持图片收发等功能 +- ✨ 支持定时任务到时后主动推送 +- ✨ 支持使用 npm 等方式安装和升级 +- 🐛 优化一些已知问题 + +
+ +
+v1.2.5 - 2026.02.02 + +- ✨ 解除 URL 发送限制 +- ✨ 更新 Bot 正在输入中状态 +- ✨ 提供主动推送能力 +- 🐛 优化一些已知问题 + +
+ +
+v1.2.2 - 2026.01.31 + +- ✨ 支持发送文件 +- ✨ 支持 openclaw、moltbot 命令行 +- 🐛 修复 health 检查提示问题 +- 🐛 修复文件发送后 clawdbot 无法读取的问题 + +
+ +
+v1.2.1 + +- 🐛 解决长时间使用会断联的问题 +- 🐛 解决频繁重连的问题 +- ✨ 增加大模型调用失败后的提示消息 + +
+ +
+v1.1.0 + +- 🐛 解决 URL 被拦截的问题 +- 🐛 解决多轮消息发送失败的问题 +- 🐛 修复部分图片无法接收的问题 +- ✨ 增加支持 onboard 配置方式 + +
+ +--- + +## 🔗 相关链接 - [QQ 机器人官方文档](https://bot.q.qq.com/wiki/) - [QQ 开放平台](https://q.qq.com/) - [API v2 文档](https://bot.q.qq.com/wiki/develop/api-v2/) -## License +--- + +## 📄 License MIT