@gakr-gakr/qqbot 0.1.0

package/api.ts

@@ -0,0 +1,56 @@
+export { qqbotPlugin } from "./src/channel.js";
+export { qqbotSetupPlugin } from "./src/channel.setup.js";
+export { getFrameworkCommands } from "./src/engine/commands/slash-commands-impl.js";
+export { registerChannelTool } from "./src/bridge/tools/channel.js";
+export { registerRemindTool } from "./src/bridge/tools/remind.js";
+export { registerQQBotTools } from "./src/bridge/tools/index.js";
+export { registerQQBotFull } from "./src/bridge/channel-entry.js";
+export {
+  type AudioFormatPolicy,
+  type C2CMessageEvent,
+  type GroupMessageEvent,
+  type GuildMessageEvent,
+  type MessageAttachment,
+  type QQBotAccountConfig,
+  type QQBotConfig,
+  type QQBotDmPolicy,
+  type QQBotExecApprovalConfig,
+  type QQBotGroupPolicy,
+  type ResolvedQQBotAccount,
+  type WSPayload,
+} from "./src/types.js";
+export {
+  applyQQBotAccountConfig,
+  DEFAULT_ACCOUNT_ID,
+  listQQBotAccountIds,
+  resolveDefaultQQBotAccountId,
+  resolveQQBotAccount,
+} from "./src/bridge/config.js";
+export {
+  buildMediaTarget,
+  checkMessageReplyLimit,
+  DEFAULT_MEDIA_SEND_ERROR,
+  getMessageReplyConfig,
+  getMessageReplyStats,
+  type MediaOutboundContext,
+  type MediaTargetContext,
+  MESSAGE_REPLY_LIMIT,
+  OUTBOUND_ERROR_CODES,
+  type OutboundContext,
+  type OutboundErrorCode,
+  type OutboundResult,
+  parseTarget,
+  recordMessageReply,
+  type ReplyLimitResult,
+  resolveOutboundMediaPath,
+  resolveUserFacingMediaError,
+  sendCronMessage,
+  sendDocument,
+  sendMedia,
+  sendPhoto,
+  sendProactiveMessage,
+  sendText,
+  sendVideoMsg,
+  sendVoice,
+  setOutboundAudioPort,
+} from "./src/engine/messaging/outbound.js";

package/autobot.plugin.json

@@ -0,0 +1,167 @@
+{
+  "id": "qqbot",
+  "activation": {
+    "onStartup": false
+  },
+  "channels": ["qqbot"],
+  "contracts": {
+    "tools": ["qqbot_channel_api", "qqbot_remind"]
+  },
+  "channelEnvVars": {
+    "qqbot": ["QQBOT_APP_ID", "QQBOT_CLIENT_SECRET"]
+  },
+  "enabledByDefault": true,
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": true,
+    "$defs": {
+      "audioFormatPolicy": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "sttDirectFormats": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "uploadDirectFormats": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "transcodeEnabled": { "type": "boolean" }
+        }
+      },
+      "stt": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "provider": { "type": "string" },
+          "baseUrl": { "type": "string" },
+          "apiKey": { "type": "string" },
+          "model": { "type": "string" }
+        }
+      },
+      "secretRef": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "source": {
+            "type": "string",
+            "enum": ["env", "file", "exec"]
+          },
+          "provider": { "type": "string" },
+          "id": { "type": "string" }
+        },
+        "required": ["source", "provider", "id"]
+      },
+      "secretInput": {
+        "anyOf": [{ "type": "string", "minLength": 1 }, { "$ref": "#/$defs/secretRef" }]
+      },
+      "account": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "name": { "type": "string" },
+          "appId": { "type": "string" },
+          "clientSecret": { "$ref": "#/$defs/secretInput" },
+          "clientSecretFile": { "type": "string" },
+          "allowFrom": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "systemPrompt": { "type": "string" },
+          "markdownSupport": { "type": "boolean" },
+          "voiceDirectUploadFormats": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "audioFormatPolicy": { "$ref": "#/$defs/audioFormatPolicy" },
+          "urlDirectUpload": { "type": "boolean" },
+          "upgradeUrl": { "type": "string" },
+          "upgradeMode": {
+            "type": "string",
+            "enum": ["doc", "hot-reload"]
+          },
+          "streaming": {
+            "anyOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "object",
+                "additionalProperties": true,
+                "properties": {
+                  "mode": {
+                    "type": "string",
+                    "enum": ["off", "partial"],
+                    "default": "partial"
+                  },
+                  "c2cStreamApi": {
+                    "type": "boolean",
+                    "description": "Use QQ C2C official stream_messages API (single-message typing-style updates)."
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    },
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "name": { "type": "string" },
+      "appId": { "type": "string" },
+      "clientSecret": { "$ref": "#/$defs/secretInput" },
+      "clientSecretFile": { "type": "string" },
+      "allowFrom": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "systemPrompt": { "type": "string" },
+      "markdownSupport": { "type": "boolean" },
+      "voiceDirectUploadFormats": {
+        "type": "array",
+        "items": { "type": "string" }
+      },
+      "audioFormatPolicy": { "$ref": "#/$defs/audioFormatPolicy" },
+      "stt": { "$ref": "#/$defs/stt" },
+      "urlDirectUpload": { "type": "boolean" },
+      "upgradeUrl": { "type": "string" },
+      "upgradeMode": {
+        "type": "string",
+        "enum": ["doc", "hot-reload"]
+      },
+      "streaming": {
+        "anyOf": [
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "mode": {
+                "type": "string",
+                "enum": ["off", "partial"],
+                "default": "partial"
+              },
+              "c2cStreamApi": {
+                "type": "boolean",
+                "description": "Use QQ C2C official stream_messages API (single-message typing-style updates)."
+              }
+            }
+          }
+        ]
+      },
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "$ref": "#/$defs/account"
+        }
+      },
+      "defaultAccount": { "type": "string" }
+    }
+  }
+}

package/channel-plugin-api.ts

@@ -0,0 +1 @@
+export { qqbotPlugin } from "./src/channel.js";

package/index.ts

@@ -0,0 +1,33 @@
+import {
+  defineBundledChannelEntry,
+  loadBundledEntryExportSync,
+  type AutoBotPluginApi,
+} from "autobot/plugin-sdk/channel-entry-contract";
+
+function registerQQBotFull(api: AutoBotPluginApi): void {
+  const register = loadBundledEntryExportSync<(api: AutoBotPluginApi) => void>(import.meta.url, {
+    specifier: "./api.js",
+    exportName: "registerQQBotFull",
+  });
+  register(api);
+}
+
+export default defineBundledChannelEntry({
+  id: "qqbot",
+  name: "QQ Bot",
+  description: "QQ Bot channel plugin",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "qqbotPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-api.js",
+    exportName: "setQQBotRuntime",
+  },
+  registerFull: registerQQBotFull,
+});

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@gakr-gakr/qqbot",
+  "version": "0.1.0",
+  "private": false,
+  "description": "AutoBot QQ Bot channel plugin",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "@tencent-connect/qqbot-connector": "1.1.0",
+    "mpg123-decoder": "1.0.3",
+    "silk-wasm": "3.7.1",
+    "ws": "8.20.1",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*",
+    "@gakr-gakr/autobot": "workspace:*",
+    "@types/ws": "8.18.1",
+    "autobot": "workspace:@gakr-gakr/autobot@*"
+  },
+  "peerDependencies": {
+    "@gakr-gakr/autobot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@gakr-gakr/autobot": {
+      "optional": true
+    }
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.ts",
+    "channel": {
+      "id": "qqbot",
+      "label": "QQ Bot",
+      "selectionLabel": "QQ Bot (Official API)",
+      "detailLabel": "QQ Bot",
+      "docsPath": "/channels/qqbot",
+      "docsLabel": "qqbot",
+      "blurb": "connect to QQ via official QQ Bot API with group chat and direct message support.",
+      "systemImage": "bubble.left.and.bubble.right"
+    },
+    "install": {
+      "npmSpec": "@gakr-gakr/qqbot",
+      "localPath": "extensions/qqbot",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,9 @@
+export type { ChannelPlugin, AutoBotPluginApi, PluginRuntime } from "autobot/plugin-sdk/core";
+export type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+export type {
+  AutoBotPluginService,
+  AutoBotPluginServiceContext,
+  PluginLogger,
+} from "autobot/plugin-sdk/core";
+export type { ResolvedQQBotAccount, QQBotAccountConfig } from "./src/types.js";
+export { getQQBotRuntime, setQQBotRuntime } from "./src/bridge/runtime.js";

package/secret-contract-api.ts

@@ -0,0 +1,5 @@
+export {
+  channelSecrets,
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";

package/setup-entry.ts

@@ -0,0 +1,13 @@
+import { defineBundledChannelSetupEntry } from "autobot/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./setup-plugin-api.js",
+    exportName: "qqbotSetupPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+});

package/setup-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled setup entry imports narrow so setup loads do not pull the
+// broader QQ Bot runtime plugin surface.
+export { qqbotSetupPlugin } from "./src/channel.setup.js";

package/skills/qqbot-channel/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: qqbot-channel
+description: QQ channel management skill. Use qqbot_channel_api to list guilds and channels, inspect members, publish posts, manage announcements, and work with schedules through the QQ Open Platform HTTP API with automatic token authentication.
+metadata: { "autobot": { "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)` 展示，禁止作为纯文本或超链接展示