@sliverp/qqbot 1.3.0

package/README.md

@@ -0,0 +1,231 @@
+# QQ Bot Channel Plugin for Moltbot
+
+QQ 开放平台Bot API 的 Moltbot 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。
+
+## 功能特性
+
+- **多场景支持**：C2C 单聊、QQ 群 @消息、频道公开消息、频道私信
+- **自动重连**：WebSocket 断连后自动重连，支持 Session Resume
+- **消息去重**：自动管理 `msg_seq`，支持对同一消息多次回复
+- **系统提示词**：可配置自定义系统提示词注入到 AI 请求
+- **错误提示**：AI 无响应时自动提示用户检查配置
+
+## 使用示例：
+<img width="952" height="582" alt="image" src="https://github.com/user-attachments/assets/a16d582b-708c-473e-b3a2-e0c4c503a0c8" />
+
+## 版本更新
+**使用`openclaw plugins list`来产看插件版本，建议使用最新版的版本**
+<img width="902" height="248" alt="Clipboard_Screenshot_1769739939" src="https://github.com/user-attachments/assets/d6f37458-900c-4de9-8fdc-f8e6bf5c7ee5" />
+
+### 1.4.0（即将更新）
+- 支持Markdonw格式
+
+  
+### 1.3.0-2026.02.03
+- 支持图片收发等功能
+  <img width="924" height="428" alt="Clipboard_Screenshot_1770112572" src="https://github.com/user-attachments/assets/80f38ae9-dc40-4545-ad17-e7e254064cf4" />
+
+- 支持定时任务到时后主动推送
+  <img width="930" height="288" alt="Clipboard_Screenshot_1770112539" src="https://github.com/user-attachments/assets/9674cda0-91e9-4860-8dcc-bc50007862a2" />
+- 优化一些已知问题
+
+
+### 1.2.5-2026.02.02
+- 解除URL发送限制，现在可以直接在私聊发送URL
+  <img width="886" height="276" alt="Clipboard_Screenshot_1770092858" src="https://github.com/user-attachments/assets/c660949e-28a5-4e5f-abc2-77f0a2c67bad" />
+- 更新Bot正在输入中状态
+  <img width="740" height="212" alt="Clipboard_Screenshot_1770091969" src="https://github.com/user-attachments/assets/47835c4b-ccd2-4782-aaa6-b873cb58f7d7" />
+- 提供主动推送能力（目前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
+- 解决了长时间使用会断联的问题
+- 解决了频繁重连的问题
+- 增加了大模型调用失败后的提示消息
+
+
+### 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

package/clawdbot.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "qqbot",
+  "name": "QQ Bot Channel",
+  "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
+  "channels": ["qqbot"],
+  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "capabilities": {
+    "proactiveMessaging": true,
+    "cronJobs": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: unknown;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;
+export { qqbotPlugin } from "./src/channel.js";
+export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
+export { qqbotOnboardingAdapter } from "./src/onboarding.js";
+export * from "./src/types.js";
+export * from "./src/api.js";
+export * from "./src/config.js";
+export * from "./src/gateway.js";
+export * from "./src/outbound.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { qqbotPlugin } from "./src/channel.js";
+import { setQQBotRuntime } from "./src/runtime.js";
+const plugin = {
+    id: "qqbot",
+    name: "QQ Bot (Stream)",
+    description: "QQ Bot channel plugin with streaming message support",
+    configSchema: emptyPluginConfigSchema(),
+    register(api) {
+        setQQBotRuntime(api.runtime);
+        api.registerChannel({ plugin: qqbotPlugin });
+    },
+};
+export default plugin;
+export { qqbotPlugin } from "./src/channel.js";
+export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
+export { qqbotOnboardingAdapter } from "./src/onboarding.js";
+export * from "./src/types.js";
+export * from "./src/api.js";
+export * from "./src/config.js";
+export * from "./src/gateway.js";
+export * from "./src/outbound.js";

package/dist/src/api.d.ts

@@ -0,0 +1,194 @@
+/**
+ * QQ Bot API 鉴权和请求封装
+ */
+/**
+ * 初始化 API 配置
+ * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
+ */
+export declare function initApiConfig(options: {
+    markdownSupport?: boolean;
+}): void;
+/**
+ * 获取当前是否支持 markdown
+ */
+export declare function isMarkdownSupport(): boolean;
+/**
+ * 获取 AccessToken（带缓存 + singleflight 并发安全）
+ *
+ * 使用 singleflight 模式：当多个请求同时发现 Token 过期时，
+ * 只有第一个请求会真正去获取新 Token，其他请求复用同一个 Promise。
+ */
+export declare function getAccessToken(appId: string, clientSecret: string): Promise<string>;
+/**
+ * 清除 Token 缓存
+ */
+export declare function clearTokenCache(): void;
+/**
+ * 获取 Token 缓存状态（用于监控）
+ */
+export declare function getTokenStatus(): {
+    status: "valid" | "expired" | "refreshing" | "none";
+    expiresAt: number | null;
+};
+/**
+ * 获取并递增消息序号
+ * 返回的 seq 会基于时间戳，避免进程重启后重复
+ */
+export declare function getNextMsgSeq(msgId: string): number;
+/**
+ * API 请求封装
+ */
+export declare function apiRequest<T = unknown>(accessToken: string, method: string, path: string, body?: unknown): Promise<T>;
+/**
+ * 获取 WebSocket Gateway URL
+ */
+export declare function getGatewayUrl(accessToken: string): Promise<string>;
+/**
+ * 消息响应
+ */
+export interface MessageResponse {
+    id: string;
+    timestamp: number | string;
+}
+/**
+ * 发送 C2C 单聊消息
+ */
+export declare function sendC2CMessage(accessToken: string, openid: string, content: string, msgId?: string): Promise<MessageResponse>;
+/**
+ * 发送 C2C 输入状态提示（告知用户机器人正在输入）
+ */
+export declare function sendC2CInputNotify(accessToken: string, openid: string, msgId?: string, inputSecond?: number): Promise<void>;
+/**
+ * 发送频道消息（不支持流式）
+ */
+export declare function sendChannelMessage(accessToken: string, channelId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 发送群聊消息
+ */
+export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
+/**
+ * 主动发送 C2C 单聊消息（不需要 msg_id，每月限 4 条/用户）
+ *
+ * 注意：
+ * 1. 内容不能为空（对应 markdown.content 字段）
+ * 2. 不支持流式发送
+ */
+export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<{
+    id: string;
+    timestamp: number;
+}>;
+/**
+ * 主动发送群聊消息（不需要 msg_id，每月限 4 条/群）
+ *
+ * 注意：
+ * 1. 内容不能为空（对应 markdown.content 字段）
+ * 2. 不支持流式发送
+ */
+export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 媒体文件类型
+ */
+export declare enum MediaFileType {
+    IMAGE = 1,
+    VIDEO = 2,
+    VOICE = 3,
+    FILE = 4
+}
+/**
+ * 上传富媒体文件的响应
+ */
+export interface UploadMediaResponse {
+    file_uuid: string;
+    file_info: string;
+    ttl: number;
+    id?: string;
+}
+/**
+ * 上传富媒体文件到 C2C 单聊
+ * @param url - 公网可访问的图片 URL（与 fileData 二选一）
+ * @param fileData - Base64 编码的文件内容（与 url 二选一）
+ */
+export declare function uploadC2CMedia(accessToken: string, openid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
+/**
+ * 上传富媒体文件到群聊
+ * @param url - 公网可访问的图片 URL（与 fileData 二选一）
+ * @param fileData - Base64 编码的文件内容（与 url 二选一）
+ */
+export declare function uploadGroupMedia(accessToken: string, groupOpenid: string, fileType: MediaFileType, url?: string, fileData?: string, srvSendMsg?: boolean): Promise<UploadMediaResponse>;
+/**
+ * 发送 C2C 单聊富媒体消息
+ */
+export declare function sendC2CMediaMessage(accessToken: string, openid: string, fileInfo: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: number;
+}>;
+/**
+ * 发送群聊富媒体消息
+ */
+export declare function sendGroupMediaMessage(accessToken: string, groupOpenid: string, fileInfo: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 发送带图片的 C2C 单聊消息（封装上传+发送）
+ * @param imageUrl - 图片来源，支持：
+ *   - 公网 URL: https://example.com/image.png
+ *   - Base64 Data URL: data:image/png;base64,xxxxx
+ */
+export declare function sendC2CImageMessage(accessToken: string, openid: string, imageUrl: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: number;
+}>;
+/**
+ * 发送带图片的群聊消息（封装上传+发送）
+ * @param imageUrl - 图片来源，支持：
+ *   - 公网 URL: https://example.com/image.png
+ *   - Base64 Data URL: data:image/png;base64,xxxxx
+ */
+export declare function sendGroupImageMessage(accessToken: string, groupOpenid: string, imageUrl: string, msgId?: string, content?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
+/**
+ * 后台 Token 刷新配置
+ */
+interface BackgroundTokenRefreshOptions {
+    /** 提前刷新时间（毫秒，默认 5 分钟） */
+    refreshAheadMs?: number;
+    /** 随机偏移范围（毫秒，默认 0-30 秒） */
+    randomOffsetMs?: number;
+    /** 最小刷新间隔（毫秒，默认 1 分钟） */
+    minRefreshIntervalMs?: number;
+    /** 失败后重试间隔（毫秒，默认 5 秒） */
+    retryDelayMs?: number;
+    /** 日志函数 */
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/**
+ * 启动后台 Token 刷新
+ * 在后台定时刷新 Token，避免请求时才发现过期
+ *
+ * @param appId 应用 ID
+ * @param clientSecret 应用密钥
+ * @param options 配置选项
+ */
+export declare function startBackgroundTokenRefresh(appId: string, clientSecret: string, options?: BackgroundTokenRefreshOptions): void;
+/**
+ * 停止后台 Token 刷新
+ */
+export declare function stopBackgroundTokenRefresh(): void;
+/**
+ * 检查后台 Token 刷新是否正在运行
+ */
+export declare function isBackgroundTokenRefreshRunning(): boolean;
+export {};