diff --git a/.gitignore b/.gitignore index 76add87..0fe2f49 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ node_modules -dist \ No newline at end of file +dist +distnode_modules diff --git a/README.md b/README.md new file mode 100644 index 0000000..0eaaf1f --- /dev/null +++ b/README.md @@ -0,0 +1,221 @@ +# QQ Bot Channel Plugin for Moltbot + +QQ 开放平台Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。 + +## 功能特性 + +- **多场景支持**：C2C 单聊、QQ 群 @消息、频道公开消息、频道私信 +- **自动重连**：WebSocket 断连后自动重连，支持 Session Resume +- **消息去重**：自动管理 `msg_seq`，支持对同一消息多次回复 +- **系统提示词**：可配置自定义系统提示词注入到 AI 请求 +- **错误提示**：AI 无响应时自动提示用户检查配置 + +## 使用示例： +image + +## 版本更新 +Clipboard_Screenshot_1769739939 + +### 1.3.0（即将更新） +- 支持回复图片等功能 +- 支持定时任务到时后主动推送 + +### 1.2.5-2026.02.02 +- 解除URL发送限制，现在可以直接在私聊发送URL + Clipboard_Screenshot_1770092858 +- 更新Bot正在输入中状态 + Clipboard_Screenshot_1770091969 +- 提供主动推送能力（目前AI还不知道怎么调用主动推送，相关完整Skill能力将在后续版本更新） +- 优化一些已知问题 +- 优化未收到未收到大模型响应时的提示信息 + + +### 1.2.2 +- 支持发送文件 +- 支持openclaw、moltbot命令行 +- 修复[health]检查提示: [health] refresh failed: Cannot read properties of undefined (reading 'appId')的问题（不影响使用） +- 修复文件发送后clawdbot无法读取的问题 + +### 1.2.1 +- 解决了长时间使用会断联的问题 +- 解决了频繁重连的问题 +- 增加了大模型调用失败后的提示消息 + + +### 1.1.0 +- 解决了一些url会被拦截的问题 +- 解决了多轮消息会发送失败的问题 +- 修复了部分图片无法接受的问题 +- 增加支持onboard的方式配置AppId 和 AppSecret + + +## 安装 + +在插件目录下执行： + +```bash +git clone https://github.com/sliverp/qqbot.git && cd qqbot +clawdbot plugins install . # 这一步会有点久，需要安装一些依赖。稍微耐心等待一下，尤其是小内存机器 +``` + +## 配置 + +### 1. 获取 QQ 机器人凭证 + +1. 访问 [QQ 开放平台](https://q.qq.com/) +2. 创建机器人应用 +3. 获取 `AppID` 和 `AppSecret`（ClientSecret） +4. Token 格式为 `AppID:AppSecret`，例如 `102146862:Xjv7JVhu7KXkxANbp3HVjxCRgvAPeuAQ` + +### 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`： + +```json +{ + "channels": { + "qqbot": { + "enabled": true, + "appId": "你的AppID", + "clientSecret": "你的AppSecret", + "systemPrompt": "你是一个友好的助手" + } + } +} +``` + + + +## 配置项说明 + +| 配置项 | 类型 | 必填 | 说明 | +|--------|------|------|------| +| `appId` | string | 是 | QQ 机器人 AppID | +| `clientSecret` | string | 是* | AppSecret，与 `clientSecretFile` 二选一 | +| `clientSecretFile` | string | 是* | AppSecret 文件路径 | +| `enabled` | boolean | 否 | 是否启用，默认 `true` | +| `name` | string | 否 | 账户显示名称 | +| `systemPrompt` | string | 否 | 自定义系统提示词 | + +## 支持的消息类型 + +| 事件类型 | 说明 | Intent | +|----------|------|--------| +| `C2C_MESSAGE_CREATE` | C2C 单聊消息 | `1 << 25` | +| `GROUP_AT_MESSAGE_CREATE` | 群聊 @机器人消息 | `1 << 25` | +| `AT_MESSAGE_CREATE` | 频道 @机器人消息 | `1 << 30` | +| `DIRECT_MESSAGE_CREATE` | 频道私信 | `1 << 12` | + +## 使用 + +### 启动 + +后台启动 +```bash +clawdbot gateway restart +``` + +前台启动, 方便试试查看日志 +```bash +clawdbot gateway --port 18789 --verbose +``` + +### CLI 配置向导 + +```bash +clawdbot onboard +# 选择 QQ Bot 进行交互式配置 +``` + +## 注意事项 + +1. **群消息**：需要在群内 @机器人 才能触发回复 +2. **沙箱模式**：新创建的机器人默认在沙箱模式，需要添加测试用户 + +## 升级 + +如果需要升级插件，先运行升级脚本清理旧版本： + +```bash +git clone https://github.com/sliverp/qqbot.git && cd qqbot + +# 运行升级脚本（清理旧版本和配置） +bash ./scripts/upgrade.sh + +# 重新安装插件 +clawdbot plugins install . # 这一步会有点久，需要安装一些依赖。稍微耐心等待一下，尤其是小内存机器 + +# 重新配置 +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 +``` + +## 相关链接 + +- [QQ 机器人官方文档](https://bot.q.qq.com/wiki/) +- [QQ 开放平台](https://q.qq.com/) +- [API v2 文档](https://bot.q.qq.com/wiki/develop/api-v2/) + +## License + +MIT diff --git a/src/channel.ts b/src/channel.ts index 2a2288a..d5fd3cb 100644 --- a/src/channel.ts +++ b/src/channel.ts @@ -71,6 +71,26 @@ export const qqbotPlugin: ChannelPlugin = { reload: { configPrefixes: ["channels.qqbot"] }, // CLI onboarding wizard onboarding: qqbotOnboardingAdapter, + // 消息目标解析 + messaging: { + normalizeTarget: (target) => { + // 支持格式: qqbot:c2c:xxx, qqbot:group:xxx, c2c:xxx, group:xxx, openid + const normalized = target.replace(/^qqbot:/i, ""); + return { ok: true, to: normalized }; + }, + targetResolver: { + looksLikeId: (id) => { + // 先去掉 qqbot: 前缀 + const normalized = id.replace(/^qqbot:/i, ""); + // 支持 c2c:xxx, group:xxx, channel:xxx 格式 + if (normalized.startsWith("c2c:") || normalized.startsWith("group:") || normalized.startsWith("channel:")) return true; + // 支持纯 openid（32位十六进制） + if (/^[A-F0-9]{32}$/i.test(normalized)) return true; + return false; + }, + hint: "c2c: or group:", + }, + }, config: { listAccountIds: (cfg) => listQQBotAccountIds(cfg), resolveAccount: (cfg, accountId) => resolveQQBotAccount(cfg, accountId),