@tencent-connect/openclaw-qqbot 1.6.3-alpha.channel → 1.6.4-alpha.0

package/clawdbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -1,6 +1,7 @@
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
+import { registerChannelTool } from "./src/tools/channel.js";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -9,6 +10,7 @@ const plugin = {
     register(api) {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
+        registerChannelTool(api);
     },
 };
 export default plugin;

package/dist/src/api.d.ts

@@ -81,6 +81,15 @@ export declare function sendChannelMessage(accessToken: string, channelId: strin
     id: string;
     timestamp: string;
 }>;
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export declare function sendDmMessage(accessToken: string, guildId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
 export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
 export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
 export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{

package/dist/src/api.js

@@ -340,6 +340,17 @@ export async function sendChannelMessage(accessToken, channelId, content, msgId)
         ...(msgId ? { msg_id: msgId } : {}),
     });
 }
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export async function sendDmMessage(accessToken, guildId, content, msgId) {
+    return apiRequest(accessToken, "POST", `/dms/${guildId}/messages`, {
+        content,
+        ...(msgId ? { msg_id: msgId } : {}),
+    });
+}
 export async function sendGroupMessage(accessToken, groupOpenid, content, msgId) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
     const body = buildMessageBody(content, msgId, msgSeq);

package/dist/src/slash-commands.js

@@ -144,13 +144,25 @@ function findCli() {
     return null;
 }
 /**
- * 找到升级脚本路径
+ * 找到升级脚本路径（兼容源码运行、dist 运行、已安装扩展目录）
  */
 function getUpgradeScriptPath() {
     const currentFile = fileURLToPath(import.meta.url);
-    const scriptDir = path.resolve(path.dirname(currentFile), "..", "..", "scripts");
-    const scriptPath = path.join(scriptDir, "upgrade-via-npm.sh");
-    return fs.existsSync(scriptPath) ? scriptPath : null;
+    const currentDir = path.dirname(currentFile);
+    const candidates = [
+        path.resolve(currentDir, "..", "..", "scripts", "upgrade-via-npm.sh"),
+        path.resolve(currentDir, "..", "scripts", "upgrade-via-npm.sh"),
+        path.resolve(process.cwd(), "scripts", "upgrade-via-npm.sh"),
+    ];
+    const homeDir = getHomeDir();
+    for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+        candidates.push(path.join(homeDir, `.${cli}`, "extensions", "openclaw-qqbot", "scripts", "upgrade-via-npm.sh"));
+    }
+    for (const p of candidates) {
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
 }
 /**
  * 在 Windows 上查找可用的 bash（Git Bash / WSL 等）
@@ -184,25 +196,19 @@ function findBash() {
  * - 异步执行升级脚本（--no-restart，只做文件替换）
  * - 脚本完成后触发 gateway restart（当前进程会被杀掉）
  * - 新进程启动时 getStartupGreeting() 检测到版本变更，自动通知管理员
- *
- * @returns true 表示已启动升级流程，false 表示无法执行（如 Windows 无 bash）
  */
 function fireHotUpgrade(targetVersion) {
     const scriptPath = getUpgradeScriptPath();
     if (!scriptPath)
-        return false;
+        return { ok: false, reason: "no-script" };
     const cli = findCli();
     if (!cli)
-        return false;
+        return { ok: false, reason: "no-cli" };
     const bash = findBash();
     if (!bash)
-        return false;
-    const args = ["--no-restart"];
-    if (targetVersion) {
-        args.push("--version", targetVersion);
-    }
+        return { ok: false, reason: "no-bash" };
     // 异步执行升级脚本
-    execFile(bash, [scriptPath, ...args], {
+    execFile(bash, [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])], {
         timeout: 120_000,
         env: { ...process.env },
         ...(isWindows() ? { windowsHide: true } : {}),
@@ -213,104 +219,51 @@ function fireHotUpgrade(targetVersion) {
         // 文件替换成功，触发 gateway restart
         execFile(cli, ["gateway", "restart"], { timeout: 30_000 }, () => { });
     });
-    return true;
+    return { ok: true };
 }
 /**
- * /bot-upgrade — 查看版本更新状态 + 升级指引（根据 upgradeMode 决定行为）
- */
-registerCommand({
-    name: "bot-upgrade",
-    description: "查看版本更新与升级指引",
-    handler: (ctx) => {
-        // 升级相关指令仅在私聊中可用
-        if (ctx.type !== "c2c") {
-            return `💡 请在私聊中使用此指令`;
-        }
-        const upgradeMode = ctx.accountConfig?.upgradeMode || "doc";
-        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
-        const info = getUpdateInfo();
-        const lines = [];
-        lines.push(`📌当前版本：v${PLUGIN_VERSION}`);
-        if (info.checkedAt === 0) {
-            lines.push(`⏳ 版本检查中，请稍后再试`);
-            return lines.join("\n");
-        }
-        else if (info.error) {
-            lines.push(`⚠️ 版本检查失败`);
-            lines.push(`⬆️升级指引：[点击查看](${url})`);
-            return lines.join("\n");
-        }
-        else if (info.hasUpdate && info.latest) {
-            lines.push(`🆕最新可用版本：v${info.latest}`);
-        }
-        else {
-            lines.push(`✅ 当前已是最新版本`);
-            return lines.join("\n");
-        }
-        // 有新版本：根据 upgradeMode 决定行为
-        if (upgradeMode === "hot-reload") {
-            const started = fireHotUpgrade(info.latest);
-            if (!started) {
-                lines.push(`⚠️ 当前环境不支持热更新（需要 bash 环境）`);
-                lines.push(`⬆️升级指引：[点击查看](${url})`);
-                return lines.join("\n");
-            }
-            lines.push(``);
-            lines.push(`🔄 正在执行热更新到 v${info.latest}...`);
-            lines.push(`⏳ 升级过程约需 30~60 秒，完成后会自动通知您`);
-            return lines.join("\n");
-        }
-        // doc 模式：展示升级文档
-        lines.push(`⬆️升级指引：[点击查看](${url})`);
-        lines.push(`🌟官方 GitHub 仓库：[点击前往](https://github.com/tencent-connect/openclaw-qqbot/)`);
-        lines.push(``, `> 💡 提示：管理员可通过 <qqbot-cmd-input text="/bot-hot-upgrade" show="/bot-hot-upgrade"/> 直接执行热更新`);
-        return lines.join("\n");
-    },
-});
-/**
- * /bot-hot-upgrade — 直接执行热更新（无论 upgradeMode 配置如何）
+ * /bot-upgrade — 统一升级入口：能热更就热更，失败则返回升级指引
  *
  * 支持参数：
- *   /bot-hot-upgrade           — 升级到 latest
- *   /bot-hot-upgrade 1.6.4     — 升级到指定版本
- *   /bot-hot-upgrade --force   — 强制升级（即使当前已是最新版）
+ *   /bot-upgrade           — 检查更新后自动热更
+ *   /bot-upgrade 1.6.4     — 升级到指定版本
+ *   /bot-upgrade --force   — 强制升级（即使当前已是最新版）
  */
 registerCommand({
-    name: "bot-hot-upgrade",
-    description: "直接执行热更新升级",
+    name: "bot-upgrade",
+    description: "检查更新并自动热更（失败则返回升级指引）",
     handler: (ctx) => {
         // 升级相关指令仅在私聊中可用
         if (ctx.type !== "c2c") {
             return `💡 请在私聊中使用此指令`;
         }
-        // 前置检查
-        const scriptPath = getUpgradeScriptPath();
-        if (!scriptPath) {
-            return "❌ 升级脚本不存在，请检查安装是否完整";
-        }
-        const cli = findCli();
-        if (!cli) {
-            return "❌ 未找到 openclaw / clawdbot / moltbot CLI";
-        }
+        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
         const args = ctx.args.trim();
         const info = getUpdateInfo();
-        // 解析参数
         const isForce = args.includes("--force");
         const versionArg = args.replace("--force", "").trim() || undefined;
-        // 如果没有指定版本，先检查是否有更新
         if (!versionArg && !isForce) {
             if (info.checkedAt === 0) {
                 return `⏳ 版本检查中，请稍后再试`;
             }
-            if (!info.hasUpdate && !info.error) {
-                return `✅ 当前版本 v${PLUGIN_VERSION} 已是最新，无需升级\n\n> 💡 使用 /bot-hot-upgrade --force 可强制重新安装`;
+            if (info.error) {
+                return `⚠️ 版本检查失败\n⬆️升级指引：[点击查看](${url})`;
+            }
+            if (!info.hasUpdate) {
+                return `✅ 当前版本 v${PLUGIN_VERSION} 已是最新，无需升级\n\n> 💡 使用 /bot-upgrade --force 可强制重新安装`;
             }
         }
         const targetVersion = versionArg || info.latest || undefined;
         // 异步执行升级
-        const started = fireHotUpgrade(targetVersion);
-        if (!started) {
-            return `❌ 当前环境不支持热更新（需要 bash 环境）\n\n> Windows 用户请安装 Git for Windows 后重试，或手动执行升级脚本`;
+        const startResult = fireHotUpgrade(targetVersion);
+        if (!startResult.ok) {
+            if (startResult.reason === "no-script") {
+                return `❌ 未找到本地升级脚本\n⬆️升级指引：[点击查看](${url})`;
+            }
+            if (startResult.reason === "no-cli") {
+                return `❌ 未找到 openclaw / clawdbot / moltbot CLI\n⬆️升级指引：[点击查看](${url})`;
+            }
+            return `❌ 当前环境不支持热更新（需要 bash 环境）\n⬆️升级指引：[点击查看](${url})\n\n> Windows 用户请安装 Git for Windows 后重试，或手动执行升级脚本`;
         }
         const lines = [
             `🔄 开始热更新...`,

package/index.ts

@@ -3,6 +3,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
+import { registerChannelTool } from "./src/tools/channel.js";
 
 const plugin = {
   id: "openclaw-qqbot",
@@ -12,6 +13,7 @@ const plugin = {
   register(api: OpenClawPluginApi) {
     setQQBotRuntime(api.runtime);
     api.registerChannel({ plugin: qqbotPlugin });
+    registerChannelTool(api);
   },
 };
 

package/moltbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/openclaw.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.3-alpha.channel",
+  "version": "1.6.4-alpha.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/qqbot-channel/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: qqbot-channel
+description: QQ 频道管理技能。查询频道列表、子频道、成员、发帖、公告、日程等操作。使用 qqbot_channel_api 工具代理 QQ 开放平台 HTTP 接口，自动处理 Token 鉴权。当用户需要查看频道、管理子频道、查询成员、发布帖子/公告/日程时使用此技能。
+metadata: {"openclaw":{"emoji":"📡","requires":{"config":["channels.qqbot"]}}}
+---
+
+# QQ 频道 API 请求指导
+
+`qqbot_channel_api` 是一个 QQ 开放平台 HTTP 代理工具，**自动填充鉴权 Token**。你只需要指定 HTTP 方法、API 路径、请求体和查询参数。
+
+## 📚 详细参考文档
+
+每个接口的完整参数说明、返回值结构和枚举值定义：
+- `references/api_references.md`
+
+---
+
+## 🔧 工具参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `method` | string | 是 | HTTP 方法：`GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
+| `path` | string | 是 | API 路径（不含域名），如 `/guilds/{guild_id}/channels`，需替换占位符为实际值 |
+| `body` | object | 否 | 请求体 JSON（POST/PUT/PATCH 使用） |
+| `query` | object | 否 | URL 查询参数键值对，值为字符串类型 |
+
+> 基础 URL：`https://api.sgroup.qq.com`，鉴权头 `Authorization: QQBot {token}` 由工具自动填充。
+
+---
+
+## ⭐ 接口速查
+
+### 频道（Guild）
+
+| 操作 | 方法 | 路径 | 参数说明 |
+|------|------|------|----------|
+| 获取频道列表 | `GET` | `/users/@me/guilds` | query: `before`, `after`, `limit`(最大100) |
+| 获取频道 API 权限 | `GET` | `/guilds/{guild_id}/api_permission` | — |
+
+### 子频道（Channel）
+
+| 操作 | 方法 | 路径 | 参数说明 |
+|------|------|------|----------|
+| 获取子频道列表 | `GET` | `/guilds/{guild_id}/channels` | — |
+| 获取子频道详情 | `GET` | `/channels/{channel_id}` | — |
+| 创建子频道 | `POST` | `/guilds/{guild_id}/channels` | body: `name`\*, `type`\*, `position`\*, `sub_type`, `parent_id`, `private_type`, `private_user_ids`, `speak_permission`, `application_id` |
+| 修改子频道 | `PATCH` | `/channels/{channel_id}` | body: `name`, `position`, `parent_id`, `private_type`, `speak_permission`（至少一个） |
+| 删除子频道 | `DELETE` | `/channels/{channel_id}` | ⚠️ 不可逆 |
+
+**子频道类型（type）**：`0`=文字, `2`=语音, `4`=分组(position≥2), `10005`=直播, `10006`=应用, `10007`=论坛
+
+### 成员（Member）
+
+| 操作 | 方法 | 路径 | 参数说明 |
+|------|------|------|----------|
+| 获取成员列表 | `GET` | `/guilds/{guild_id}/members` | query: `after`(首次填0), `limit`(1-400) |
+| 获取成员详情 | `GET` | `/guilds/{guild_id}/members/{user_id}` | — |
+| 获取身份组成员列表 | `GET` | `/guilds/{guild_id}/roles/{role_id}/members` | query: `start_index`(首次填0), `limit`(1-400) |
+| 获取在线成员数 | `GET` | `/channels/{channel_id}/online_nums` | — |
+
+### 公告（Announces）
+
+| 操作 | 方法 | 路径 | 参数说明 |
+|------|------|------|----------|
+| 创建公告 | `POST` | `/guilds/{guild_id}/announces` | body: `message_id`, `channel_id`, `announces_type`(0=成员,1=欢迎), `recommend_channels`(最多3条) |
+| 删除公告 | `DELETE` | `/guilds/{guild_id}/announces/{message_id}` | message_id 设 `all` 删除所有 |
+
+### 论坛（Forum）— 仅私域机器人
+
+| 操作 | 方法 | 路径 | 参数说明 |
+|------|------|------|----------|
+| 获取帖子列表 | `GET` | `/channels/{channel_id}/threads` | — |
+| 获取帖子详情 | `GET` | `/channels/{channel_id}/threads/{thread_id}` | — |
+| 发表帖子 | `PUT` | `/channels/{channel_id}/threads` | body: `title`\*, `content`\*, `format`(1=文本,2=HTML,3=Markdown,4=JSON，默认3) |
+| 删除帖子 | `DELETE` | `/channels/{channel_id}/threads/{thread_id}` | ⚠️ 不可逆 |
+| 发表评论 | `POST` | `/channels/{channel_id}/threads/{thread_id}/comment` | body: `thread_author`\*, `content`\*, `thread_create_time`, `image` |
+
+### 日程（Schedule）
+
+| 操作 | 方法 | 路径 | 参数说明 |
+|------|------|------|----------|
+| 创建日程 | `POST` | `/channels/{channel_id}/schedules` | body: `{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }` |
+| 修改日程 | `PATCH` | `/channels/{channel_id}/schedules/{schedule_id}` | body: `{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }` |
+| 删除日程 | `DELETE` | `/channels/{channel_id}/schedules/{schedule_id}` | ⚠️ 不可逆 |
+
+**提醒类型（remind_type）**：`"0"`=不提醒, `"1"`=开始时, `"2"`=5分钟前, `"3"`=15分钟前, `"4"`=30分钟前, `"5"`=60分钟前
+
+> `*` 表示必填参数
+
+---
+
+## 💡 调用示例
+
+### 获取频道列表
+
+```json
+{
+  "method": "GET",
+  "path": "/users/@me/guilds",
+  "query": { "limit": "100" }
+}
+```
+
+### 获取子频道列表
+
+```json
+{
+  "method": "GET",
+  "path": "/guilds/123456/channels"
+}
+```
+
+### 创建子频道
+
+```json
+{
+  "method": "POST",
+  "path": "/guilds/123456/channels",
+  "body": {
+    "name": "新频道",
+    "type": 0,
+    "position": 1,
+    "sub_type": 0
+  }
+}
+```
+
+### 获取成员列表（分页）
+
+```json
+{
+  "method": "GET",
+  "path": "/guilds/123456/members",
+  "query": { "after": "0", "limit": "100" }
+}
+```
+
+### 发表论坛帖子
+
+```json
+{
+  "method": "PUT",
+  "path": "/channels/789012/threads",
+  "body": {
+    "title": "公告标题",
+    "content": "# 标题\n\n公告内容",
+    "format": 3
+  }
+}
+```
+
+### 创建日程
+
+```json
+{
+  "method": "POST",
+  "path": "/channels/456789/schedules",
+  "body": {
+    "schedule": {
+      "name": "周会",
+      "start_timestamp": "1770733800000",
+      "end_timestamp": "1770737400000",
+      "remind_type": "2"
+    }
+  }
+}
+```
+
+### 创建推荐子频道公告
+
+```json
+{
+  "method": "POST",
+  "path": "/guilds/123456/announces",
+  "body": {
+    "announces_type": 0,
+    "recommend_channels": [
+      { "channel_id": "789012", "introduce": "欢迎来到攻略频道" }
+    ]
+  }
+}
+```
+
+### 删除所有公告
+
+```json
+{
+  "method": "DELETE",
+  "path": "/guilds/123456/announces/all"
+}
+```
+
+---
+
+## 🔄 常用操作流程
+
+### 获取频道和子频道信息
+
+```
+1. GET /users/@me/guilds → 获取频道列表，拿到 guild_id
+2. GET /guilds/{guild_id}/channels → 获取子频道列表，拿到 channel_id
+3. GET /channels/{channel_id} → 获取子频道详情
+```
+
+### 论坛发帖 + 评论
+
+```
+1. GET /guilds/{guild_id}/channels → 找到论坛子频道（type=10007）
+2. PUT /channels/{channel_id}/threads → 发表帖子
+3. GET /channels/{channel_id}/threads → 获取帖子列表
+4. GET /channels/{channel_id}/threads/{thread_id} → 获取帖子详情（含 author_id）
+5. POST /channels/{channel_id}/threads/{thread_id}/comment → 发表评论
+```
+
+### 成员管理
+
+```
+1. GET /users/@me/guilds → 获取 guild_id
+2. GET /guilds/{guild_id}/members?after=0&limit=100 → 获取成员列表
+   翻页：用上次最后一个 user.id 作为 after，直到返回空数组
+3. GET /guilds/{guild_id}/members/{user_id} → 获取指定成员详情
+```
+
+### 展示成员头像
+
+成员详情返回的 `user.avatar` 是头像 URL，**必须使用 Markdown 图片语法展示**，让用户直接看到头像图片，而非纯文本链接：
+
+```
+成员信息：
+· 昵称：{nick}
+· 头像：
+![头像]({user.avatar})
+```
+
+> **禁止**将头像 URL 作为纯文本或超链接展示（如 `查看头像`），必须用 `![描述](URL)` 语法内联显示。频道的 `icon` 字段同理。
+
+---
+
+## 🚨 错误码处理
+
+| 错误码 | 说明 | 解决方案 |
+|--------|------|----------|
+| **401** | Token 鉴权失败 | 检查 AppID 和 ClientSecret 配置 |
+| **11241** | 频道 API 无权限 | 前往 QQ 开放平台申请权限，或调用 `GET /guilds/{guild_id}/api_permission` 查看可用权限 |
+| **11242** | 仅私域机器人可用 | 需在 QQ 开放平台将机器人切换为私域模式 |
+| **11243** | 需要管理频道权限 | 确保机器人拥有管理权限 |
+| **11281** | 日程频率限制 | 单管理员/天限 10 次，单频道/天限 100 次 |
+| **304023** | 推荐子频道超限 | 推荐子频道最多 3 条 |
+
+---
+
+## ⚠️ 注意事项
+
+1. **路径中的占位符**（如 `{guild_id}`、`{channel_id}`）必须替换为实际值
+2. **query 参数的值必须为字符串类型**，如 `{ "limit": "100" }` 而非 `{ "limit": 100 }`
+3. **成员列表翻页**时可能返回重复成员，需按 `user.id` 去重
+4. **公告**的两种类型（消息公告和推荐子频道公告）会互相顶替
+5. **日程**的时间戳为毫秒级字符串
+6. **删除操作不可逆**，请谨慎使用
+7. **论坛操作**仅私域机器人可用
+8. **子频道分组**（type=4）的 `position` 必须 >= 2
+9. **日程操作**有频率限制：单个管理员每天 10 次，单个频道每天 100 次
+10. **头像/图标展示**：成员 `user.avatar` 和频道 `icon` 等图片 URL 必须使用 Markdown 图片语法 `![描述](URL)` 展示，禁止作为纯文本或超链接展示