@cxyhhhhh/openclaw-qqbot 2.0.0-dev.202607081614 → 2.0.0-dev.202607081621

package/index.ts

@@ -12,7 +12,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';
+import { registerPlatformTool } from './src/tools/platform.js';
 import { registerRemindTool } from './src/tools/remind.js';
 import { verifyRuntimeContract } from './src/runtime-adapter/contract-check.js';
 
@@ -39,7 +39,7 @@ const plugin = {
     }
 
     api.registerChannel({ plugin: qqbotPlugin as any });
-    registerChannelTool(api);
+    registerPlatformTool(api);
     registerRemindTool(api);
   },
 };

package/openclaw.plugin.json

@@ -4,9 +4,9 @@
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
   "extensions": ["./preload.cjs"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-upgrade"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-group", "skills/qqbot-remind", "skills/qqbot-upgrade"],
   "contracts": {
-    "tools": ["qqbot_channel_api", "qqbot_remind"]
+    "tools": ["qqbot_platform_api", "qqbot_remind"]
   },
   "capabilities": {
     "proactiveMessaging": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxyhhhhh/openclaw-qqbot",
-  "version": "2.0.0-dev.202607081614",
+  "version": "2.0.0-dev.202607081621",
   "description": "QQ Bot channel plugin for OpenClaw",
   "publishConfig": {
     "access": "public"
@@ -41,9 +41,8 @@
     "lint:runtime": "npx tsx src/runtime-adapter/lint-runtime-access.ts"
   },
   "dependencies": {
-    "@tencent-connect/qqbot-nodejs": "file:../qqbot-nodejs",
-    "@tencent-connect/qqbot-connector": "1.2.0",
-    "ws": "^8.20.0"
+    "@tencent-connect/qqbot-nodejs": "npm:@tencent/qqbot-nodejs@0.0.0-dev.8a6be470",
+    "@tencent-connect/qqbot-connector": "1.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/skills/qqbot-channel/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: qqbot-channel
-description: QQ 频道管理技能。查询频道列表、子频道、成员、发帖、公告、日程等操作。使用 qqbot_channel_api 工具代理 QQ 开放平台 HTTP 接口，自动处理 Token 鉴权。当用户需要查看频道、管理子频道、查询成员、发布帖子/公告/日程时使用此技能。
+description: QQ 频道管理技能。查询频道列表、子频道、成员、发帖、公告、日程等操作。使用 qqbot_platform_api 工具代理 QQ 开放平台 HTTP 接口，自动处理 Token 鉴权。当用户需要查看频道、管理子频道、查询成员、发布帖子/公告/日程时使用此技能。
 metadata: {"openclaw":{"emoji":"📡","requires":{"config":["channels.qqbot"]}}}
 ---
 
 # QQ 频道 API 请求指导
 
-`qqbot_channel_api` 是一个 QQ 开放平台 HTTP 代理工具，**自动填充鉴权 Token**。你只需要指定 HTTP 方法、API 路径、请求体和查询参数。
+`qqbot_platform_api` 是 QQ 开放平台统一 HTTP API 网关，**自动填充鉴权 Token**。你只需要指定 HTTP 方法、API 路径、请求体和查询参数即可调用频道相关接口。
 
 ## 📚 详细参考文档
 

package/skills/qqbot-group/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: qqbot-group
+description: QQ 群管理技能。查询群基础信息、群成员信息、机器人群内状态。使用 qqbot_platform_api 工具调用接口，自动鉴权。当用户需要查询群信息、查看群成员、检查机器人群内状态时使用此技能。
+metadata: {"openclaw":{"emoji":"👥","requires":{"config":["channels.qqbot"]}}}
+---
+
+# QQ 群 API 请求指导
+
+通过 `qqbot_platform_api` 工具调用群相关接口，鉴权由工具自动处理。
+
+详细字段说明见 `references/api_reference.md`。
+
+---
+
+## ⭐ 接口速查
+
+| 操作 | 方法 | 路径 |
+|------|------|------|
+| 获取机器人群内状态 | `GET` | `/v2/groups/{group_id}/bot_state` |
+| 获取群成员信息 | `GET` | `/v2/groups/{group_id}/members/{member_id}` |
+| 获取群基础信息 | `GET` | `/v2/groups/{group_id}/info` |
+
+---
+
+## 💡 调用示例
+
+### 获取机器人群内状态
+
+```json
+{
+  "method": "GET",
+  "path": "/v2/groups/G_123456789/bot_state"
+}
+```
+
+返回字段：`joined_at`（入群时间）、`allow_proactive_msg`（是否允许主动推送）、`recv_msg_setting`（`all`/`only_mention`/`mention_and_context`）、`member_role`（`member`/`owner`/`admin`）。
+
+### 获取群成员信息
+
+```json
+{
+  "method": "GET",
+  "path": "/v2/groups/G_123456789/members/o_xxxxxxxx"
+}
+```
+
+返回字段：`username`（昵称）、`member_role`、`joined_at`、`bot` 等。昵称仅在单个查询时返回。
+
+### 获取群基础信息
+
+```json
+{
+  "method": "GET",
+  "path": "/v2/groups/G_123456789/info"
+}
+```
+
+返回字段：`group_name`、`group_finger_memo`（简介）、`group_class_text`（分类）、`group_tags`（标签）、`group_member_num`（成员数）。
+
+---
+
+## 💬 @群成员
+
+发送消息时使用 `<@member_id>` 语法 @指定群成员：
+
+- 格式：`<@member_id>`，例如 `<@o_xxxxxxxx>`
+- 文本消息中直接拼接即可：`你好 <@o_xxxxxxxx>，欢迎入群！`
+
+---
+
+## ⚠️ 注意事项
+
+1. 路径占位符 `{group_id}`、`{member_id}` 需替换为实际值
+2. 返回时间格式为 RFC3339（如 `2026-06-23T22:03:09+08:00`）
+3. 群 openid 与频道 guild_id 是不同的概念，不要混淆

package/skills/qqbot-group/references/api_reference.md

@@ -0,0 +1,94 @@
+# QQ 开放平台群接口参考
+
+> 鉴权和请求头由 `qqbot_platform_api` 工具自动处理，无需手动管理。
+
+---
+
+## 接口列表
+
+### 1. 获取机器人群内状态
+
+- 方法：`GET`
+- 路径：`/v2/groups/{group_id}/bot_state`
+
+响应参数：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| joined_at | string | 入群时间（RFC3339 格式） |
+| allow_proactive_msg | bool | 是否允许主动消息推送 |
+| recv_msg_setting | string | 接收消息设置：`all`、`only_mention`、`mention_and_context` |
+| member_role | string | 群成员角色：`member`、`owner`、`admin` |
+
+响应示例：
+
+```json
+{
+  "join_timestamp": "2026-06-23T22:03:09+08:00",
+  "allow_proactive_msg": true,
+  "recv_msg_setting": "all",
+  "member_role": "admin"
+}
+```
+
+---
+
+### 2. 获取群成员信息
+
+- 方法：`GET`
+- 路径：`/v2/groups/{group_id}/members/{member_id}`
+
+响应参数：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| union_openid | string | 用户在应用/开放平台下的统一标识 |
+| user_openid | string | 用户 openid |
+| username | string | 用户昵称（仅单个查询时返回） |
+| member_role | string | 群成员角色：`member`、`owner`、`admin` |
+| joined_at | string | 入群时间（RFC3339 格式） |
+| bot | bool | 是否为机器人账号 |
+
+响应示例：
+
+```json
+{
+  "union_openid": "u_xxxxxxxx",
+  "user_openid": "o_xxxxxxxx",
+  "username": "张三",
+  "member_role": "member",
+  "joined_at": "2026-06-23T22:03:09+08:00",
+  "bot": false
+}
+```
+
+---
+
+### 3. 获取群基础信息
+
+- 方法：`GET`
+- 路径：`/v2/groups/{group_id}/info`
+
+响应参数：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| group_openid | string | 群 openid |
+| group_name | string | 群名称 |
+| group_finger_memo | string | 群简介/群公告 |
+| group_class_text | string | 群分类文案 |
+| group_tags | array[] | 群标签列表 |
+| group_member_num | int | 群成员数量 |
+
+响应示例：
+
+```json
+{
+  "group_openid": "G_123456789",
+  "group_name": "技术交流群",
+  "group_finger_memo": "专注于后端技术开发交流",
+  "group_class_text": "技术-后端开发",
+  "group_tags": ["技术交流", "后端开发", "QQ机器人"],
+  "group_member_num": 1250
+}
+```

package/src/tools/platform.ts

@@ -0,0 +1,149 @@
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+import { listQQBotAccountIds } from '../config.js';
+import { getBotForAccount } from '../bot-instance.js';
+import { getRequestAccountId } from '../request-context.js';
+
+// ========== JSON Schema ==========
+
+const PlatformApiSchema = {
+  type: 'object',
+  properties: {
+    method: {
+      type: 'string',
+      description:
+        'HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE',
+      enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+    },
+    path: {
+      type: 'string',
+      description:
+        'API 路径（不含域名），占位符需替换为实际值。' +
+        '示例：/users/@me/guilds, /guilds/{guild_id}/channels, ' +
+        '/v2/groups/{group_id}/bot_state',
+    },
+    body: {
+      type: 'object',
+      description:
+        '请求体（JSON），用于 POST/PUT/PATCH 请求。' +
+        'GET/DELETE 请求不需要此参数。',
+    },
+    query: {
+      type: 'object',
+      description:
+        'URL 查询参数（键值对），会拼接到路径后面。' +
+        '如 { "limit": "100", "after": "0" } 会拼接为 ?limit=100&after=0',
+      additionalProperties: { type: 'string' },
+    },
+  },
+  required: ['method', 'path'],
+} as const;
+
+// ========== 工具函数 ==========
+
+function json(data: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
+    details: data,
+  };
+}
+
+function validatePath(path: string): string | null {
+  if (!path.startsWith('/')) return "path 必须以 / 开头";
+  if (path.includes('..') || path.includes('//')) return "path 不允许包含 .. 或 //";
+  if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== '/') {
+    return 'path 包含非法字符';
+  }
+  return null;
+}
+
+// ========== 注册入口 ==========
+
+/**
+ * 注册 QQBot 平台统一 API 网关工具。
+ * 通过 SDK 的 bot.api 网关代理所有 QQ 开放平台 HTTP 接口 — 自动鉴权、重试、结构化错误。
+ *
+ * 覆盖范围：
+ *  - 频道（Guild/Channel/Member/Announce/Forum/Schedule）→ 见 qqbot-channel skill
+ *  - 群（Group/Member）→ 见 qqbot-group skill
+ */
+export function registerPlatformTool(api: OpenClawPluginApi): void {
+  const cfg = api.config;
+  if (!cfg) return;
+
+  const accountIds = listQQBotAccountIds(cfg);
+  if (accountIds.length === 0) return;
+
+  api.registerTool(
+    {
+      name: 'qqbot_platform_api',
+      label: 'QQBot Platform API Gateway',
+      description:
+        'QQ 开放平台统一 HTTP API 网关，自动填充鉴权 Token。' +
+        '常用接口速查：' +
+        '【频道】GET /users/@me/guilds | /guilds/{guild_id}/channels | /channels/{channel_id} | ' +
+        '【群】GET /v2/groups/{group_id}/bot_state | /v2/groups/{group_id}/members/{member_id} | /v2/groups/{group_id}/info。' +
+        '更多接口和参数详情请阅读 qqbot-channel 和 qqbot-group skill。',
+      parameters: PlatformApiSchema,
+      async execute(_toolCallId, params) {
+        const p = params as {
+          method: string;
+          path: string;
+          body?: Record<string, unknown>;
+          query?: Record<string, string>;
+        };
+
+        if (!p.method) return json({ error: 'method 为必填参数' });
+        if (!p.path) return json({ error: 'path 为必填参数' });
+
+        const method = p.method.toUpperCase();
+        if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+          return json({ error: `不支持的 HTTP 方法: ${method}` });
+        }
+
+        const pathError = validatePath(p.path);
+        if (pathError) return json({ error: pathError });
+
+        const accountId = getRequestAccountId();
+        if (!accountId) {
+          return json({ error: '无法获取当前请求的账号信息，此工具仅支持在消息会话中使用' });
+        }
+
+        try {
+          const bot = getBotForAccount(accountId);
+          const apiGateway = bot.api;
+
+          let data: unknown;
+          switch (method) {
+            case 'GET':
+              data = await apiGateway.get(p.path, p.query);
+              break;
+            case 'POST':
+              data = await apiGateway.post(p.path, p.body);
+              break;
+            case 'PUT':
+              data = await apiGateway.put(p.path, p.body);
+              break;
+            case 'PATCH':
+              data = await apiGateway.patch(p.path, p.body);
+              break;
+            case 'DELETE':
+              data = await apiGateway.delete(p.path);
+              break;
+          }
+
+          return json(data);
+        } catch (err: unknown) {
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
+          return json({
+            error: errMsg,
+            status: apiErr.httpStatus,
+            code: apiErr.bizCode,
+            path: p.path,
+          });
+        }
+      },
+    },
+    { name: 'qqbot_platform_api' },
+  );
+}

package/src/tools/channel.ts

@@ -1,148 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { resolveQQBotAccount, listQQBotAccountIds } from "../config.js";
-import { getBotForAccount } from "../bot-instance.js";
-
-// ========== JSON Schema ==========
-
-const ChannelApiSchema = {
-  type: "object",
-  properties: {
-    method: {
-      type: "string",
-      description:
-        "HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE",
-      enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
-    },
-    path: {
-      type: "string",
-      description:
-        "API 路径（不含域名），占位符需替换为实际值。" +
-        "示例：/users/@me/guilds, /guilds/{guild_id}/channels, /channels/{channel_id}",
-    },
-    body: {
-      type: "object",
-      description:
-        "请求体（JSON），用于 POST/PUT/PATCH 请求。" +
-        "GET/DELETE 请求不需要此参数。",
-    },
-    query: {
-      type: "object",
-      description:
-        "URL 查询参数（键值对），会拼接到路径后面。" +
-        "如 { \"limit\": \"100\", \"after\": \"0\" } 会拼接为 ?limit=100&after=0",
-      additionalProperties: { type: "string" },
-    },
-  },
-  required: ["method", "path"],
-} as const;
-
-// ========== 工具函数 ==========
-
-function json(data: unknown) {
-  return {
-    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
-    details: data,
-  };
-}
-
-function validatePath(path: string): string | null {
-  if (!path.startsWith("/")) return "path 必须以 / 开头";
-  if (path.includes("..") || path.includes("//")) return "path 不允许包含 .. 或 //";
-  if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== "/") {
-    return "path 包含非法字符";
-  }
-  return null;
-}
-
-// ========== 注册入口 ==========
-
-/**
- * 注册 QQ 频道 API 代理工具。
- * 使用 SDK 的 bot.api 网关替代自封装 HTTP — 自动鉴权、重试、结构化错误。
- */
-export function registerChannelTool(api: OpenClawPluginApi): void {
-  const cfg = api.config;
-  if (!cfg) return;
-
-  const accountIds = listQQBotAccountIds(cfg);
-  if (accountIds.length === 0) return;
-
-  const firstAccountId = accountIds[0];
-  const account = resolveQQBotAccount(cfg, firstAccountId);
-  if (!account.appId || !account.clientSecret) return;
-
-  api.registerTool(
-    {
-      name: "qqbot_channel_api",
-      label: "QQBot Channel API",
-      description:
-        "QQ 开放平台频道 API HTTP 代理，自动填充鉴权 Token。" +
-        "常用接口速查：" +
-        "频道列表 GET /users/@me/guilds | " +
-        "子频道列表 GET /guilds/{guild_id}/channels | " +
-        "子频道详情 GET /channels/{channel_id} | " +
-        "创建子频道 POST /guilds/{guild_id}/channels | " +
-        "成员列表 GET /guilds/{guild_id}/members?after=0&limit=100 | " +
-        "成员详情 GET /guilds/{guild_id}/members/{user_id} | " +
-        "帖子列表 GET /channels/{channel_id}/threads | " +
-        "发帖 PUT /channels/{channel_id}/threads | " +
-        "创建公告 POST /guilds/{guild_id}/announces | " +
-        "创建日程 POST /channels/{channel_id}/schedules。" +
-        "更多接口和参数详情请阅读 qqbot-channel skill。",
-      parameters: ChannelApiSchema,
-      async execute(_toolCallId, params) {
-        const p = params as { method: string; path: string; body?: Record<string, unknown>; query?: Record<string, string> };
-
-        if (!p.method) return json({ error: "method 为必填参数" });
-        if (!p.path) return json({ error: "path 为必填参数" });
-
-        const method = p.method.toUpperCase();
-        if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
-          return json({ error: `不支持的 HTTP 方法: ${method}` });
-        }
-
-        const pathError = validatePath(p.path);
-        if (pathError) return json({ error: pathError });
-
-        try {
-          // 通过 SDK bot.api 网关发送请求（自动鉴权 + 超时 + 结构化错误）
-          const bot = getBotForAccount(account.accountId);
-          const apiGateway = bot.api;
-
-          let data: unknown;
-          switch (method) {
-            case "GET":
-              data = await apiGateway.get(p.path, p.query);
-              break;
-            case "POST":
-              data = await apiGateway.post(p.path, p.body);
-              break;
-            case "PUT":
-              data = await apiGateway.put(p.path, p.body);
-              break;
-            case "PATCH":
-              data = await apiGateway.patch(p.path, p.body);
-              break;
-            case "DELETE":
-              data = await apiGateway.delete(p.path);
-              break;
-          }
-
-          return json(data);
-        } catch (err: unknown) {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          // 从 ApiError 提取结构化信息
-          const apiErr = err as { httpStatus?: number; bizCode?: number; path?: string };
-          return json({
-            error: errMsg,
-            status: apiErr.httpStatus,
-            code: apiErr.bizCode,
-            path: p.path,
-          });
-        }
-      },
-    },
-    { name: "qqbot_channel_api" },
-  );
-
-}