@zhin.js/adapter-qq 1.0.83 → 1.1.0

package/README.md

@@ -1,6 +1,17 @@
 # @zhin.js/adapter-qq
 
-Zhin.js QQ 官方机器人适配器，基于 QQ 官方机器人 API 开发，支持频道、群聊和私聊消息。
+Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 **WebSocket Gateway**（`qq-official-bot`）收发消息（无需 host-router / host-http）。
+
+## 功能
+
+- WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
+- 解析私聊 / 群 / 频道消息
+- 出站 `send({ conversation, payload })` → QQ API（`conversation.kind`/`id`/`parent` 结构化寻址）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- Webhook / middleware 模式已实现（经 `httpHostToken` 注册 POST 路由）
+- AI `@` 触发标注：群消息（GROUP_AT_MESSAGE_CREATE 仅 @ 时下发）与频道 `mentions[].bot` 会在入站 metadata 标 `mentioned: true`（新 Plugin Runtime 纯文本 content 经 metadata 传递 @）
+- 群事件：机器人进群/退群、群成员加入/退出、入群申请（支持 `$approve()` / `$reject()`）
+- 完整 SDK 业务 API：通过 `qqClient.get(context, endpoint).api` 使用群管理、禁言、自动审批策略、自定义菜单、指令面板等 `qq-official-bot` 能力
 
 ## 安装
 
@@ -8,275 +19,167 @@ Zhin.js QQ 官方机器人适配器，基于 QQ 官方机器人 API 开发，支
 pnpm add @zhin.js/adapter-qq
 ```
 
-## 配置
-
-### 基础配置
-
-```typescript
-import { defineConfig } from 'zhin.js';
-
-export default defineConfig({
-  bots: [
-    {
-      context: 'qq',
-      name: '你的机器人ID', // 机器人的 AppID
-      appID: process.env.QQ_APP_ID,
-      token: process.env.QQ_TOKEN,
-      secret: process.env.QQ_SECRET,
-      mode: 'public', // 或 'private'
-      platform: 'qq', // 'qq' | 'qzone'
-      data_dir: './data' // 数据存储目录
-    }
-  ],
-  plugins: [
-    'http',
-    'adapter-qq'
-  ]
-})
-```
-
-### 完整配置选项
-
-```typescript
-const config: QQBotConfig = {
-  context: 'qq',
-  name: '机器人ID',
-  appID: 'YOUR_APP_ID',        // 机器人 AppID（必需）
-  token: 'YOUR_TOKEN',         // 机器人 Token（必需）
-  secret: 'YOUR_SECRET',       // 机器人 Secret（必需）
-  mode: 'public',              // 'public' | 'private' 接收模式
-  platform: 'qq',              // 'qq' | 'qzone' 平台类型
-  intents: [                   // 事件订阅意图
-    'GUILDS',
-    'GUILD_MEMBERS',
-    'DIRECT_MESSAGE',
-    'GROUP_AT_MESSAGE_CREATE'
-  ],
-  data_dir: './data',          // 数据目录（可选）
-  sandbox: false               // 是否为沙箱环境（可选）
-}
-```
-
-## 获取配置信息
-
-### 1. 注册 QQ 机器人
-
-1. 访问 [QQ 开放平台](https://q.qq.com/bot)
-2. 登录并创建机器人应用
-3. 在「开发设置」中获取：
-   - **AppID**: 机器人应用 ID
-   - **Token**: 机器人令牌
-   - **Secret**: 机器人密钥
+## Plugin Runtime
 
-### 2. 配置权限
+- `@zhin.js/adapter` — 约定式 `adapters/qq.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **无需** `@zhin.js/host-http` / `@zhin.js/host-router`（WebSocket 路径）
 
-在机器人设置中：
-- 配置需要的事件订阅
-- 设置消息接收模式（公域/私域）
-- 添加频道/群聊白名单（如需要）
+入站：`gateway.receive({ conversation, message, content, sender, metadata })`（ConversationRef 结构化寻址）  
+出站：`send({ conversation, payload })` → `sendPrivateMessage` / `sendGroupMessage` / `sendGuildMessage`
 
-### 3. 事件订阅（Intents）
+## 前置条件
 
-可订阅的事件类型：
-- `GUILDS` - 频道事件
-- `GUILD_MEMBERS` - 成员变动
-- `GUILD_MESSAGES` - 频道消息
-- `DIRECT_MESSAGE` - 私信消息
-- `GROUP_AT_MESSAGE_CREATE` - 群聊 @ 消息
-- `INTERACTION` - 互动事件
+| 要求 | 说明 |
+|------|------|
+| **AppID / Secret** | [QQ 开放平台](https://q.qq.com/) 创建机器人应用并获取 |
+| **WebSocket（默认）** | `qq-official-bot` 正向连接；无需公网回调 |
+| **host-http** | WebSocket **不需要**；Webhook / middleware 模式需要（经 `httpHostToken`） |
 
-## 使用示例
+必填字段（`endpoints[i]`）：`name`、`appid`、`secret`。
 
-### 基础消息处理
+## 最小配置
 
-```typescript
-import { addCommand, MessageCommand } from 'zhin.js'
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
+```yaml
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  qq:
+    # mode: websocket   # 默认
+    endpoints:
+      - name: my-qq-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+        # botKind / intents 可由向导写入；`qq.endpoint add` 扫码后会追问公域/私域再写入
 ```
 
-### 频道消息
-
-```typescript
-import { onMessage } from 'zhin.js'
-
-onMessage(async (message) => {
-  // 仅处理频道消息
-  if (message.$channel.type === 'channel') {
-    console.log(`频道消息：${message.$raw}`)
-  }
-})
+### botKind 与 intents
+
+WebSocket Identify 的 `intents` **必须与开放平台已开通的权限一致**，否则会断连。
+群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT` 和 `GROUP_MEMBER`；差异只在频道消息 intent：
+
+| `botKind` | 频道消息 intent | 共用 intents |
+|-----------|-----------------|--------------|
+| `public`（默认，公域） | `PUBLIC_GUILD_MESSAGES`（仅 @） | `GROUP_AND_C2C_EVENT`, `GROUP_MEMBER`, `GUILDS`, `GUILD_MEMBERS`, `DIRECT_MESSAGE` |
+| `private`（私域） | `GUILD_MESSAGES`（频道全量） | 同上 |
+
+公域机器人订阅 `GUILD_MESSAGES` 会 Identify 失败断连。显式配置 `intents` 时优先于 `botKind`。
+`create-zhin` / `zhin setup` 会询问公/私域并写入；`qq.endpoint add` 扫码成功后在同一会话追问 `public`/`private`（或 `公域`/`私域`），确认后一次性写 `.env` 与 yaml。
+
+多账号：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  qq:
+    mode: websocket
+    endpoints:
+      - name: main-bot
+        appid: ${QQ_APPID}
+        secret: ${QQ_SECRET}
+        botKind: public
+        intents:
+          - GROUP_AND_C2C_EVENT
+          - GROUP_MEMBER
+          - GUILDS
+          - GUILD_MEMBERS
+          - DIRECT_MESSAGE
+          - PUBLIC_GUILD_MESSAGES
+      - name: private-bot
+        appid: ${QQ_APPID_2}
+        secret: ${QQ_SECRET_2}
+        botKind: private
+        intents:
+          - GROUP_AND_C2C_EVENT
+          - GROUP_MEMBER
+          - GUILDS
+          - GUILD_MEMBERS
+          - DIRECT_MESSAGE
+          - GUILD_MESSAGES
 ```
 
-### 群聊消息
-
-```typescript
-import { onGroupMessage } from 'zhin.js'
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-qq`（`instanceKey: qq`）。
 
-onGroupMessage(async (message) => {
-  console.log(`群聊消息来自：${message.$sender.name}`)
-  console.log(`消息内容：${message.$raw}`)
-})
-```
-
-### 私聊消息
+## Endpoint 管理命令
 
-```typescript
-import { onPrivateMessage } from 'zhin.js'
+适配器自带 `qq.endpoint` 命令组（聊天内直接使用，默认无前缀；受 `commandPrefix` 影响）：
 
-onPrivateMessage(async (message) => {
-  await message.$reply('收到你的私信了！')
-})
-```
+| 命令 | 说明 |
+|------|------|
+| `qq.endpoint add [name]` | 手机 QQ 扫码绑定 → **追问公域/私域** → 一次性写入 `.env` + `plugins.qq.endpoints`（重启生效） |
+| `qq.endpoint cancel` | 取消进行中的扫码绑定或待确认的公域/私域选择 |
+| `qq.endpoint list` | 列出运行中与配置中的 endpoints |
+| `qq.endpoint remove <name>` | 从配置移除 endpoint（`.env` 键保留，可手动清理） |
 
-### 发送不同类型消息
-
-```typescript
-addCommand(new MessageCommand('card')
-  .action(async (message) => {
-    // 发送 Ark 模板卡片
-    return {
-      type: 'ark',
-      template_id: 23,
-      kv: [
-        { key: '#TITLE#', value: '标题' },
-        { key: '#DESC#', value: '描述' },
-        { key: '#PROMPT#', value: '提示' }
-      ]
-    }
-  })
-)
-
-addCommand(new MessageCommand('embed')
-  .action(async (message) => {
-    // 发送 Embed 消息
-    return {
-      type: 'embed',
-      title: 'Embed 标题',
-      prompt: '消息提示',
-      thumbnail: { url: 'https://example.com/image.png' },
-      fields: [
-        { name: '字段1', value: '值1' }
-      ]
-    }
-  })
-)
-```
+add/cancel/remove 受 `master` 限制：实例配置声明了 `master`（顶层或 `endpoints[i].master`）时仅
+master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoint 的 `master`）。二维码当前以链接文本下发
+（出站富媒体待迁移），用手机 QQ 打开链接即可扫码。
 
-## 消息类型支持
+## 环境变量
 
-### 接收消息类型
+| 变量 | 说明 |
+|------|------|
+| `QQ_APPID` / `QQ_BOT_APPID` | 应用 AppID |
+| `QQ_SECRET` / `QQ_BOT_SECRET` | 应用 Secret |
+| `QQ_BOT_NAME` | 可选，默认 endpoint 名 |
 
-- ✅ 文本消息
-- ✅ @ 提及
-- ✅ 图片消息
-- ✅ 表情消息
-- ✅ Ark 模板消息
-- ✅ Embed 消息
-- ✅ Markdown 消息
+## Webhook / middleware
 
-### 发送消息类型
+`mode: webhook` 或 `mode: middleware` 经 `httpHostToken` 注册 POST 路由（默认 `/qq/webhook`），使用 qq-official-bot Middleware 接收器验签并入站；出站仍走 QQ HTTP API。Host 需注入 `httpHostToken`。
 
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ Ark 模板消息
-- ✅ Embed 富文本消息
-- ✅ Markdown 消息
-- ✅ 消息引用（回复）
+## AI 工具（Skill）
 
-## API 方法
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具 | `agent/tools/`（频道、角色等） |
+| 技能说明 | `agent/skills/qq.md` |
 
-### 基础方法
+## 平台 Client 与 QQ API
 
-```typescript
-const bot = app.adapters.get('qq')?.bots.get('你的机器人ID')
+`qqClient` 返回当前 endpoint 的传输 client。常用发送、撤回、频道查询仍有顶层快捷方法；
+`client.api` 暴露完整的 `qq-official-bot` 1.3 业务 Service 与实体入口；连接启停仍由 Endpoint 生命周期统一管理：
 
-// 发送私信
-await bot.sendPrivateMessage(userId, '消息内容')
+```ts
+import { qqClient } from '@zhin.js/adapter-qq';
 
-// 发送群消息
-await bot.sendGroupMessage(groupId, '消息内容')
+const client = qqClient.get(context, 'my-qq-bot');
 
-// 发送频道消息
-await bot.sendGuildMessage(channelId, '消息内容')
+const group = await client.api.groupService.getInfo(groupOpenid);
+const requests = await client.api.groupService.getJoinRequests(groupOpenid);
+await client.api.groupService.setMemberMute(groupOpenid, [
+  { op: 'add', member_openid: memberOpenid, mute_expire_at: expiresAt },
+]);
 
-// 撤回消息
-await bot.$recallMessage(messageId)
+const menu = await client.api.menuPanelService.getCustomMenu();
+const panels = await client.api.menuPanelService.getCommandPanels({ scope: 'group' });
 ```
 
-## 消息 ID 格式
+群管理接口中有部分是白名单能力，入群审批和禁言还要求机器人具备群管理员权限；
+具体可用范围以 QQ 开放平台为准。
 
-本适配器使用特殊的消息 ID 格式来区分不同类型的消息：
+## 平台权限（platform permit）
 
-- 私信：`private-{userId}:{messageId}`
-- 群聊：`group-{groupId}:{messageId}`
-- 频道：`channel-{channelId}:{messageId}`
-- 私域频道：`direct-{guildId}:{messageId}`
+platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；`@zhin.js/tool` descriptor 保留 `platforms` / `scopes` / `permissions`，CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 执行门禁。
 
-## 注意事项
+## Markdown 与交互输出
 
-### 接收模式
+QQ Endpoint 声明原生 `markdown` / `keyboard` 能力。普通 AI Markdown 会保留为 QQ Markdown
+消息；命令或 Agent 通过 `UserInteraction.ask()` 发起 `confirm` / `select` 时，会生成
+Markdown + 指令按钮组。按钮值与手动输入共用同一解析入口，不维护 QQ 专用交互状态。
 
-- **公域模式 (public)**: 仅接收 @ 机器人的消息
-- **私域模式 (private)**: 可接收频道内所有消息（需要申请权限）
+不支持原生按钮的 Adapter 会在 Core 中把同一 keyboard 语义降级为编号列表，并保存数字到
+payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `MediaRef` 出站链投递。
 
-### 频率限制
+## 故障排查
 
-QQ 机器人有严格的频率限制：
-- 主动消息：每个用户每天 5 条
-- 被动消息（回复）：无限制
-- 建议在被动模式下使用（用户 @ 后回复）
-
-### 沙箱环境
-
-开发时可以使用沙箱环境测试：
-
-```typescript
-{
-  context: 'qq',
-  sandbox: true,  // 启用沙箱
-  // ...其他配置
-}
-```
-
-## 常见问题
-
-### Q: 机器人无法收到消息？
-
-A: 检查以下几点：
-1. AppID、Token、Secret 是否正确
-2. 事件订阅（Intents）是否包含对应类型
-3. 公域模式下消息是否 @ 了机器人
-4. 机器人是否已加入对应频道/群聊
-
-### Q: 发送消息失败？
-
-A: 可能的原因：
-1. 超过主动消息频率限制
-2. 没有对应频道/群的发送权限
-3. 消息格式不符合规范
-4. Token 已过期或失效
-
-### Q: 如何处理不同平台？
-
-A: 使用 `platform` 配置：
-- `qq`: QQ 频道和群聊
-- `qzone`: QQ 空间（如支持）
-
-## 相关链接
-
-- [QQ 开放平台](https://q.qq.com/bot)
-- [QQ 机器人开发文档](https://bot.q.qq.com/wiki/)
-- [Zhin.js 官方文档](https://github.com/zhinjs/zhin)
+| 现象 | 排查 |
+| --- | --- |
+| Gateway Identify 后断线 | 检查 `botKind` 与 intents；公域机器人不要订阅受限 intent |
+| 二维码绑定后仍离线 | 在 Console 登录待办确认结果，并检查 App ID、Secret 与 Token |
+| Webhook 无事件 | 检查 HTTP Host、公网路径、平台回调与签名参数 |
+| Markdown/按钮发送失败 | 检查平台模板与权限，并按 Endpoint 能力降级 |
 
 ## 许可证
 
 MIT License
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！

package/adapters/qq.js

@@ -0,0 +1,50 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/qq.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from "../lib/endpoint.js";
+import { resolveQqConfig, } from "../lib/protocol.js";
+import { qqRuntimeStateToken } from "../lib/qq-runtime-state.js";
+export { QqHttpEndpoint, QqWebsocketEndpoint, } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    operations: ['recall'],
+    // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
+    // markdown/keyboard 原生按钮承载交互段。
+    segments: {
+        supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'markdown', 'keyboard'],
+        markdown: 'native',
+        outboundMedia: ['url', 'upload'],
+        interactive: 'native',
+    },
+    create(context) {
+        const config = resolveQqConfig(context.config);
+        // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
+        const state = context.use(qqRuntimeStateToken);
+        state.endpoints.set(config.id, {
+            id: config.id,
+            mode: config.mode,
+        });
+        // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
+        // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
+        const endpoint = config.mode === 'websocket'
+            ? new QqWebsocketEndpoint({
+                id: context.id,
+                config,
+            })
+            : new QqHttpEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                config,
+            });
+        // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq.endpoint list 仍显示运行中。
+        const stopEndpoint = endpoint.stop.bind(endpoint);
+        endpoint.stop = async () => {
+            state.endpoints.delete(config.id);
+            await stopEndpoint();
+        };
+        return endpoint;
+    },
+});

package/adapters/qq.ts

@@ -0,0 +1,71 @@
+/**
+ * Convention entry: discover `adapters/qq.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { QqHttpEndpoint, QqWebsocketEndpoint } from '../src/endpoint.js';
+import {
+  resolveQqConfig,
+  type QqAdapterConfig,
+} from '../src/protocol.js';
+import { qqRuntimeStateToken } from '../src/qq-runtime-state.js';
+
+export {
+  QqHttpEndpoint,
+  QqWebsocketEndpoint,
+} from '../src/endpoint.js';
+export type {
+  CreateQqBot,
+  CreateQqHttpBot,
+  QqBotTransport,
+  QqEndpointOptions,
+  QqHttpBotTransport,
+  QqHttpEndpointOptions,
+} from '../src/endpoint.js';
+
+declare module '@zhin.js/core' {
+  interface AdapterEndpoints {
+    qq: import('../src/endpoint.js').QqWebsocketEndpoint;
+  }
+}
+
+export default defineAdapter<QqAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  operations: ['recall'],
+  // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
+  // markdown/keyboard 原生按钮承载交互段。
+  segments: {
+    supported: ['text', 'mention', 'image', 'audio', 'video', 'file', 'reply', 'markdown', 'keyboard'],
+    markdown: 'native',
+    outboundMedia: ['url', 'upload'],
+    interactive: 'native',
+  },
+  create(context) {
+    const config = resolveQqConfig(context.config);
+    // 注册到插件运行时状态（qq.endpoint list 的"运行中"数据源）
+    const state = context.use(qqRuntimeStateToken);
+    state.endpoints.set(config.id, {
+      id: config.id,
+      mode: config.mode,
+    });
+    // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
+    // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
+    const endpoint = config.mode === 'websocket'
+      ? new QqWebsocketEndpoint({
+        id: context.id,
+        config,
+      })
+      : new QqHttpEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        config,
+      });
+    // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq.endpoint list 仍显示运行中。
+    const stopEndpoint = endpoint.stop.bind(endpoint);
+    endpoint.stop = async () => {
+      state.endpoints.delete(config.id);
+      await stopEndpoint();
+    };
+    return endpoint;
+  },
+});

package/agent/PERMITS.md

@@ -0,0 +1,25 @@
+# QQ 官方频道 Platform Permits
+
+> 与 QQ 群 `group_*` **分开命名**，仅用于 guild/channel 场景。
+
+## 入站字段
+
+`message_type === guild` 时 `getGuildMember` + `getGuildInfo`（TTL 60s）：
+
+| 字段 | 取值 |
+|------|------|
+| `$sender.role` | `owner` · `admin` · `member` |
+| `$sender.permissions` | `guild_owner` · `guild_admin` · `manage_roles` · `manage_channels` · 角色 ID |
+
+## Permit 词汇表
+
+| `platform(qq,…)` | 含义 |
+|------------------|------|
+| `guild_owner` | 频道主 |
+| `guild_admin` | 频道管理员 |
+| `manage_roles` | 管理身份组 |
+| `manage_channels` | 管理子频道 |
+
+## 工厂映射
+
+`scene_admin` → `guild_admin` · `scene_owner` → `guild_owner`

package/{skills/qq/SKILL.md → agent/skills/qq.md}

@@ -5,7 +5,7 @@ platforms:
 description: >-
   QQ 官方机器人管理能力。当用户在 QQ 官方机器人（非 OneBot/NapCat）中请求群管（踢人、
   禁言、全员禁言）、频道/子频道管理、角色管理（创建/添加/移除角色）、
-  或查询成员详情时使用。即使用户没有明确提到 QQ 官方机器人，只要 Bot 平台是 qq
+  或查询成员详情时使用。即使用户没有明确提到 QQ 官方机器人，只要 Endpoint 平台是 qq
   （官方 API）且涉及上述操作，就应触发。仅有昵称时先 list_members 查 user_id。
 keywords:
   - qq

package/agent/tools/add_role.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; channel_id: string; user_id: string; role_id: string }>({
+  description: '给成员添加 QQ 频道角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+    channel_id: z.string().describe('子频道 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermit('manage_roles')],
+  async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
+    return { success, message: success ? '已给成员添加角色' : '操作失败' };
+  },
+});

package/agent/tools/channel_info.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ channel_id: string }>({
+  description: '获取 QQ 频道中指定子频道的详细信息',
+  inputSchema: z.object({
+    channel_id: z.string().describe('子频道 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermit('guild_admin')],
+  async execute({ channel_id  }: { channel_id: string }, context) {
+    const client = context.$client;
+    return client.getChannelInfo(channel_id);
+  },
+});

package/agent/tools/create_role.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string; name: string; color?: number }>({
+  description: '创建 QQ 频道角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+    name: z.string().describe('角色名称'),
+    color: z.number().optional().describe('颜色（RGB 十进制数值）'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermit('guild_owner')],
+  async execute({ guild_id, name, color  }: { guild_id: string; name: string; color?: number }, context) {
+    const client = context.$client;
+    const role = await client.createGuildRole(guild_id, name, color);
+    return { success: !!role, role, message: role ? `角色 "${name}" 创建成功` : '创建失败' };
+  },
+});

package/agent/tools/list_channels.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { platformPermit } from '../../src/platform-permit.js';
+
+export default defineAgentTool<{ guild_id: string }>({
+  description: '获取 QQ 频道下的子频道列表',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermit('manage_channels')],
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const channels = await client.getChannels(guild_id);
+    return { channels, count: channels.length };
+  },
+});

package/agent/tools/list_guilds.ts

@@ -0,0 +1,14 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<Record<string, never>>({
+  description: '获取 QQ 频道列表',
+  inputSchema: z.object({}),
+  adapter: 'qq',
+  tags: ['qq'],
+  async execute(_input, context) {
+    const client = context.$client;
+    const guilds = await client.getGuilds();
+    return { guilds, count: guilds.length };
+  },
+});