@zhin.js/adapter-qq 1.1.16 → 1.1.18

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @zhin.js/adapter-qq
 
+## 1.1.18
+
+### Patch Changes
+
+- 6345a38: feat(adapters): add per-adapter Console pages
+
+  Every platform adapter now ships a `pages/index` Console page backed by a shared
+  `createAdapterConsolePage` component and `createAdapterConsoleRpc` server helper:
+
+  - See running endpoints, test connectivity, and manage
+    `plugins.<adapter>.endpoints` (add/remove writes `.env` references) from the
+    Console instead of chat commands.
+  - Surface LoginAssist pending tasks (QR / slider / SMS / device) so ICQQ login no
+    longer requires the terminal.
+  - QQ moves its QR binding flow (`qq endpoint add`) into Console actions with
+    public/private selection.
+  - Pages are permission-gated by `<adapter>:read`; writes need `<adapter>:write`.
+
+- ff3efe7: feat(adapters): notify masters when ICQQ or QQ goes offline and support ICQQ re-login
+
+  - Add an explicit `notify` target to ICQQ and QQ endpoint config: when the
+    transport goes offline or login fails, send a short notice through another
+    adapter instance's Endpoint via `OutboundHost`.
+  - ICQQ automatically retries login after `system.offline.kickoff` when
+    `autoReconnect` is enabled, and exposes pending QR/slider/device challenges.
+  - Add `icqq login status|qr|confirm|code|retry` recovery commands. They can be
+    invoked from the QQ conversation that received the notice; `qr` returns the
+    login QR code as an image when the notifying platform supports it.
+  - `notify.id` also counts as the master identity for the related endpoint
+    management commands, so recovery can happen from the notified conversation.
+  - Document the new config and commands in the ICQQ/QQ READMEs and generated
+    configuration reference.
+
+- 26888e4: QQ 官方适配器按官方 v2 接口向 ICQQ 能力对齐：新增 `qq-conversation` / `qq-messages` / `qq-group-directory` / `qq-group-admin` / `qq-group-state` 技能（会话信息、引用回复、撤回自己 / 成员消息、群信息与成员、移出、禁言、入群审批、禁言列表、入群申请、黑名单）及频道成员禁言 / 移出；Endpoint 管理端口补齐群成员列表、踢人、禁言与自动群审核；撤回支持入站原生消息 ID，频道消息支持表情回应。好友 / 群列表、合并转发、戳一戳、点赞、公告、精华、头衔、退群等官方无接口的能力明确标注为不支持。
+- Updated dependencies [6345a38]
+- Updated dependencies [ff3efe7]
+- Updated dependencies [c58c589]
+  - @zhin.js/adapter@1.1.25
+  - @zhin.js/client@1.1.21
+  - @zhin.js/core@1.1.53
+  - @zhin.js/im-contract@1.1.9
+  - @zhin.js/tool@1.1.12
+
+## 1.1.17
+
+### Patch Changes
+
+- Updated dependencies [f67883e]
+- Updated dependencies [e23cabc]
+- Updated dependencies [4d728c0]
+- Updated dependencies [eb8feeb]
+- Updated dependencies [24a2b71]
+- Updated dependencies [d0e1fac]
+- Updated dependencies [1ca669a]
+- Updated dependencies [3771f7a]
+- Updated dependencies [4f96ad5]
+  - @zhin.js/core@1.1.52
+  - @zhin.js/adapter@1.1.24
+  - @zhin.js/tool@1.1.11
+  - @zhin.js/host-http@1.1.11
+  - @zhin.js/im-contract@1.1.8
+
 ## 1.1.16
 
 ### Patch Changes

package/README.md

@@ -11,6 +11,9 @@ Zhin.js QQ 官方机器人适配器（Plugin Runtime），默认通过 **WebSock
 - Webhook / middleware 模式已实现（经 `httpHostToken` 注册 POST 路由）
 - AI `@` 触发标注：群消息（GROUP_AT_MESSAGE_CREATE 仅 @ 时下发）与频道 `mentions[].bot` 会在入站 metadata 标 `mentioned: true`（新 Plugin Runtime 纯文本 content 经 metadata 传递 @）
 - 群事件：机器人进群/退群、群成员加入/退出、入群申请（支持 `$approve()` / `$reject()`）
+- 群管理（官方 v2 群接口）：成员列表 / 详情、移出（可拉黑）、禁言（≤30 天）、入群申请审批、黑名单查询；Endpoint 管理端口与自动群审核（`inspectGroupMember` / `moderateGroupMember`）可直接使用
+- 撤回：自己的消息，以及机器人为群管理员时普通成员 2 分钟内的消息（入站原生消息 ID 也可撤回）
+- 频道子频道消息表情回应（`reaction` 操作，Unicode emoji 或 `type:id`）
 - 完整 SDK 业务 API：通过 `qqClient.get(context, endpoint).api` 使用群管理、禁言、自动审批策略、自定义菜单、指令面板等 `qq-official-bot` 能力
 
 ## 安装
@@ -132,11 +135,31 @@ master 可执行；未配置则放行（首个扫码绑定者会写入该 endpoi
 
 ## AI 工具（Skill）
 
-| 类别 | 路径 |
-|------|------|
-| Permit 词汇 | `PERMITS.md` |
-| 平台工具 | `tools/`（频道、角色等） |
-| 技能说明 | `agents/qq/skills/qq/SKILL.md` |
+| 技能 | 工具 | 场景 |
+|------|------|------|
+| `qq-conversation` | `conversation_info` | 当前会话、机器人实时群角色（`bot_state`）、可用操作与官方限制 |
+| `qq-messages` | `quote_reply`、`recall_own_message` | 私聊 / 群 / 频道 |
+| `qq-group-directory` | `group_info`、`group_members`、`group_member_info` | 当前群 |
+| `qq-group-admin` | `group_kick`、`set_mute`、`recall_member_message`、`handle_join_request` | 当前群（撤回也支持频道） |
+| `qq-group-state` | `list_muted`、`list_join_requests`、`group_blacklist` | 当前群 |
+| `qq-directory` | `list_guilds` | 任意 |
+| `qq` | `list_channels`、`channel_info`、`list_roles`、`create_role`、`add_role`、`remove_role`、`member_detail`、`guild_mute_member`、`guild_kick_member` | 频道 |
+
+群工具只作用于当前会话的群（`group_openid`），成员用 `member_openid` 标识；写操作前实时核验机器人角色。
+`group_kick` / `handle_join_request` / `guild_kick_member` 每次人工审批，禁言类每次审批。Permit 词汇见 `PERMITS.md`。
+
+### 与 ICQQ 的对齐情况
+
+| ICQQ 能力 | QQ 官方 | 说明 |
+|-----------|---------|------|
+| `group_member_info`、`conversation_info`、`quote_reply`、`recall_own_message`、`recall_member_message`、`group_kick`、`set_mute`、`list_muted` | ✅ 对齐 | 官方 v2 群接口；成员 / 移出类为白名单能力（11253） |
+| 入群申请审批、Console 成员列表 / 踢人 / 禁言、自动群审核 | ✅ 对齐 | `EndpointManagement` 端口 |
+| 表情回应 | ⚠️ 部分 | 仅频道子频道消息；官方无群 / 单聊表情回应 |
+| `friend_list`、`group_list`、`user_info` | ❌ 官方不支持 | 无机器人好友 / 群列表、任意用户资料接口 |
+| `forward_messages` | ❌ 官方不支持 | 无合并转发发送接口 |
+| `poke`、`send_user_like`、`group_sign` | ❌ 官方不支持 | |
+| `announce`、`essence`、`set_title`、`set_anonymous`、`group_files`、`group_invite`、`group_leave` | ❌ 官方不支持 | 群公告 / 精华 / 头衔 / 匿名 / 群文件 / 邀请 / 退群均无接口 |
+| 设管理员、删好友（Console） | ❌ 官方不支持 | |
 
 ## 平台 Client 与 QQ API
 
@@ -196,6 +219,34 @@ QQ 开放平台按有没有带上用户消息的 `msg_id`（或事件的 `event_
 公域机器人在群里只能收到 @ 它的消息，所以群聊旁听（`ai.trigger.ambient`）只对拥有全量
 消息权限的私域机器人有意义。
 
+## Console 页面
+
+启动后打开 Console 的「QQ」页（地址 `/qq`），可以：
+
+- 查看运行中的连接、点「测试连接」做连通性诊断；
+- 查看 / 删除 `plugins.qq.endpoints`（凭据写入 `.env`，配置里只保留 `${ENV}` 引用）；新增走扫码绑定；
+- 「平台操作」里扫码绑定新机器人：扫码 → 选择公域 / 私域 → 写入配置；原来的 `qq endpoint add` 仍然保留。
+
+读取需要 `qq:read`，写操作需要 `qq:write`；管理员 full token 不受限。页面里的「扫码绑定新机器人」等价于原来的 `qq endpoint add`。
+
+## 掉线通知
+
+QQ 官方机器人掉线 / 启动失败时，可以配置 `notify` 让另一个适配器实例通知 master：
+
+```yaml
+icqq:
+  # ... 已配置好的 ICQQ 实例
+qq:
+  master: "${QQ_MASTER_OPENID}"
+  notify:
+    adapter: icqq
+    endpoint: "123456"
+    kind: private
+    id: "123456"   # master 的 QQ 号
+```
+
+通知里会提示恢复方式：在 QQ 回复 `qq endpoint add` 重新扫码绑定（或打开 Console 的 QQ 页面）。`notify.id` 同时作为 endpoint 管理命令的 master 身份，方便从通知会话直接完成绑定。未配置 `notify` 时只在日志和 Console 的 QQ 页面显示连接状态。
+
 ## 故障排查
 
 | 现象 | 排查 |

package/adapters/qq/index.js

@@ -2,7 +2,8 @@
 /**
  * Convention entry: discover `adapters/qq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
+import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
+import { outboundHostToken } from 'zhin.js';
 import { httpHostToken } from '@zhin.js/host-http';
 import { QqHttpEndpoint, QqWebsocketEndpoint } from "../../lib/endpoint.js";
 import { resolveQqConfig, } from "../../lib/protocol.js";
@@ -10,7 +11,7 @@ import { qqRuntimeStateToken } from "../../lib/qq-runtime-state.js";
 export { QqHttpEndpoint, QqWebsocketEndpoint, } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    operations: ['recall'],
+    operations: ['recall', 'reaction'],
     // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
     // markdown/keyboard 原生按钮承载交互段。
     segments: {
@@ -29,15 +30,19 @@ export default defineAdapter({
         });
         // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
         // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
+        const outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
+        const notifier = createAdapterOutageNotifier(outbound, config.notify);
         const endpoint = config.mode === 'websocket'
             ? new QqWebsocketEndpoint({
                 id: context.id,
                 config,
+                notifier,
             })
             : new QqHttpEndpoint({
                 id: context.id,
                 http: context.use(httpHostToken),
                 config,
+                notifier,
             });
         // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq endpoint list 仍显示运行中。
         const stopEndpoint = endpoint.stop.bind(endpoint);

package/adapters/qq/index.ts

@@ -1,7 +1,8 @@
 /**
  * Convention entry: discover `adapters/qq/index.ts` → defineAdapter.
  */
-import { defineAdapter } from 'zhin.js/adapter';
+import { createAdapterOutageNotifier, defineAdapter } from 'zhin.js/adapter';
+import { outboundHostToken } from 'zhin.js';
 import { httpHostToken } from '@zhin.js/host-http';
 import { QqHttpEndpoint, QqWebsocketEndpoint } from '../../src/endpoint.js';
 import {
@@ -31,7 +32,7 @@ declare module '@zhin.js/core' {
 
 export default defineAdapter<QqEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
-  operations: ['recall'],
+  operations: ['recall', 'reaction'],
   // 媒体 url 直发，base64/path 由 SDK formatMediaData 物化走 /files 上传；
   // markdown/keyboard 原生按钮承载交互段。
   segments: {
@@ -50,15 +51,19 @@ export default defineAdapter<QqEndpointConfig>({
     });
     // 正向判 websocket：TS 对 `mode === 'webhook' || mode === 'middleware'` 的
     // 否定分支不做联合消减（多字面量判别式），反向写会让 config 窄化失败。
+    const outbound = context.has?.(outboundHostToken) ? context.use(outboundHostToken) : undefined;
+    const notifier = createAdapterOutageNotifier(outbound, config.notify);
     const endpoint = config.mode === 'websocket'
       ? new QqWebsocketEndpoint({
         id: context.id,
         config,
+        notifier,
       })
       : new QqHttpEndpoint({
         id: context.id,
         http: context.use(httpHostToken),
         config,
+        notifier,
       });
     // 运行状态表只增不减：stop 时同步摘除，避免 stop 后 qq endpoint list 仍显示运行中。
     const stopEndpoint = endpoint.stop.bind(endpoint);

package/agents/qq/boundaries.md

@@ -1,3 +1,5 @@
 # Boundaries
 
 Operate only on the active qq endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.
+
+QQ official bots only expose the documented Bot API. Group members are `member_openid` values scoped to this bot and group. There is no group list, friend list, user profile, poke, like, merged forward, leave group, announcement, essence, title, anonymous, group file or sign-in API; say so instead of simulating them. Many group management APIs are invite-only (error 11253).

package/agents/qq/conversation.js

@@ -0,0 +1,92 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { outboundMessageToken } from '@zhin.js/core/runtime';
+import { parseCompoundMessageId, qqOutboundKind } from "../../lib/protocol.js";
+// Shared with EndpointManagement so Console, auto-moderation and Agent tools enforce the same official limits.
+export { kickQqGroupMember, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS } from "../../lib/group-admin.js";
+import { messages as t } from './messages.js';
+/** The trusted turn owns the endpoint and address; model input cannot select another one. */
+export function currentConversation(context) {
+    const { origin } = context;
+    if (origin.kind !== 'im' || origin.platform !== 'qq' || !origin.conversation) {
+        throw new Error(t(context.locale, 'conversationRequired'));
+    }
+    context.signal.throwIfAborted();
+    return origin.conversation;
+}
+/** Current QQ group_openid. */
+export function currentGroup(context) {
+    const conversation = currentConversation(context);
+    if (conversation.kind !== 'group')
+        throw new Error(t(context.locale, 'groupRequired'));
+    return conversation.id;
+}
+/** Current guild child channel and its guild. */
+export function currentGuildChannel(context) {
+    const conversation = currentConversation(context);
+    const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : '';
+    if (conversation.kind !== 'channel' || !guildId)
+        throw new Error(t(context.locale, 'channelRequired'));
+    return { guildId, channelId: conversation.id };
+}
+/**
+ * Resolve a message ID inside the current conversation. Outbound receipts are `kind-target:msgId`
+ * and must match the current conversation; anything else is a native inbound ID of this conversation.
+ */
+export function resolveMessageTarget(context, id) {
+    const conversation = currentConversation(context);
+    const kind = qqOutboundKind(conversation);
+    const value = id.trim();
+    if (!value)
+        throw new Error(t(context.locale, 'messageOutsideConversation'));
+    let compound;
+    try {
+        compound = parseCompoundMessageId(value);
+    }
+    catch {
+        compound = undefined;
+    }
+    if (compound) {
+        if (compound.kind !== kind || compound.channelId !== conversation.id || !compound.qqMsgId) {
+            throw new Error(t(context.locale, 'messageOutsideConversation'));
+        }
+        return { kind, targetId: conversation.id, messageId: compound.qqMsgId, ownOutbound: true };
+    }
+    return { kind, targetId: conversation.id, messageId: value, ownOutbound: false };
+}
+export async function recallTarget(context, target) {
+    context.signal.throwIfAborted();
+    const client = context.$client;
+    const recall = {
+        private: client.recallPrivateMessage, group: client.recallGroupMessage,
+        channel: client.recallGuildMessage, direct: client.recallDirectMessage,
+    }[target.kind];
+    if (!recall)
+        return { success: false, message: t(context.locale, 'recallUnconfirmed') };
+    try {
+        const result = await recall.call(client, target.targetId, target.messageId);
+        const success = result !== false;
+        return { success, message: t(context.locale, success ? 'messageRecalled' : 'recallUnconfirmed') };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: t(context.locale, 'recallUnconfirmed'),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function sendToConversation(context, content) {
+    const conversation = currentConversation(context);
+    const receipt = await context.use(outboundMessageToken).send({
+        requester: context.owner.id,
+        conversation,
+        content,
+    });
+    return { success: receipt.status === 'sent', receipt };
+}
+/** Live check: the bot must be owner/admin of the current group. */
+export async function requireGroupManager(context, groupId) {
+    const state = await context.$client.api.groupService.getBotState(groupId);
+    context.signal.throwIfAborted();
+    return state.member_role === 'owner' || state.member_role === 'admin' ? state : undefined;
+}

package/agents/qq/conversation.ts

@@ -0,0 +1,99 @@
+import { outboundMessageToken, type SendContent } from '@zhin.js/core/runtime';
+import type { ToolExecutionContext } from '@zhin.js/tool';
+import { parseCompoundMessageId, qqOutboundKind, type QqChannelKind } from '../../src/protocol.js';
+// Shared with EndpointManagement so Console, auto-moderation and Agent tools enforce the same official limits.
+export { kickQqGroupMember, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS } from '../../src/group-admin.js';
+import { messages as t } from './messages.js';
+
+export type QqToolContext = ToolExecutionContext<unknown, 'qq'>;
+
+/** The trusted turn owns the endpoint and address; model input cannot select another one. */
+export function currentConversation(context: QqToolContext) {
+  const { origin } = context;
+  if (origin.kind !== 'im' || origin.platform !== 'qq' || !origin.conversation) {
+    throw new Error(t(context.locale, 'conversationRequired'));
+  }
+  context.signal.throwIfAborted();
+  return origin.conversation;
+}
+
+/** Current QQ group_openid. */
+export function currentGroup(context: QqToolContext): string {
+  const conversation = currentConversation(context);
+  if (conversation.kind !== 'group') throw new Error(t(context.locale, 'groupRequired'));
+  return conversation.id;
+}
+
+/** Current guild child channel and its guild. */
+export function currentGuildChannel(context: QqToolContext): { guildId: string; channelId: string } {
+  const conversation = currentConversation(context);
+  const guildId = conversation.parent?.kind === 'channel' ? conversation.parent.id : '';
+  if (conversation.kind !== 'channel' || !guildId) throw new Error(t(context.locale, 'channelRequired'));
+  return { guildId, channelId: conversation.id };
+}
+
+export interface QqMessageTarget {
+  readonly kind: QqChannelKind;
+  readonly targetId: string;
+  readonly messageId: string;
+  /** `send()` receipt IDs are compound; only those are known to be the bot's own messages. */
+  readonly ownOutbound: boolean;
+}
+
+/**
+ * Resolve a message ID inside the current conversation. Outbound receipts are `kind-target:msgId`
+ * and must match the current conversation; anything else is a native inbound ID of this conversation.
+ */
+export function resolveMessageTarget(context: QqToolContext, id: string): QqMessageTarget {
+  const conversation = currentConversation(context);
+  const kind = qqOutboundKind(conversation);
+  const value = id.trim();
+  if (!value) throw new Error(t(context.locale, 'messageOutsideConversation'));
+  let compound: ReturnType<typeof parseCompoundMessageId> | undefined;
+  try { compound = parseCompoundMessageId(value); } catch { compound = undefined; }
+  if (compound) {
+    if (compound.kind !== kind || compound.channelId !== conversation.id || !compound.qqMsgId) {
+      throw new Error(t(context.locale, 'messageOutsideConversation'));
+    }
+    return { kind, targetId: conversation.id, messageId: compound.qqMsgId, ownOutbound: true };
+  }
+  return { kind, targetId: conversation.id, messageId: value, ownOutbound: false };
+}
+
+export async function recallTarget(context: QqToolContext, target: QqMessageTarget) {
+  context.signal.throwIfAborted();
+  const client = context.$client;
+  const recall = {
+    private: client.recallPrivateMessage, group: client.recallGroupMessage,
+    channel: client.recallGuildMessage, direct: client.recallDirectMessage,
+  }[target.kind];
+  if (!recall) return { success: false, message: t(context.locale, 'recallUnconfirmed') };
+  try {
+    const result = await recall.call(client, target.targetId, target.messageId);
+    const success = result !== false;
+    return { success, message: t(context.locale, success ? 'messageRecalled' : 'recallUnconfirmed') };
+  } catch (error) {
+    return {
+      success: false,
+      message: t(context.locale, 'recallUnconfirmed'),
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function sendToConversation(context: QqToolContext, content: SendContent) {
+  const conversation = currentConversation(context);
+  const receipt = await context.use(outboundMessageToken).send({
+    requester: context.owner.id,
+    conversation,
+    content,
+  });
+  return { success: receipt.status === 'sent', receipt };
+}
+
+/** Live check: the bot must be owner/admin of the current group. */
+export async function requireGroupManager(context: QqToolContext, groupId: string) {
+  const state = await context.$client.api.groupService.getBotState(groupId);
+  context.signal.throwIfAborted();
+  return state.member_role === 'owner' || state.member_role === 'admin' ? state : undefined;
+}

package/agents/qq/messages.js

@@ -20,5 +20,65 @@ export const messages = createMessages({
     "roleRemoved": {
         "zh-CN": "已移除成员的角色",
         "en": "Role removed from the member"
+    },
+    "conversationRequired": {
+        "zh-CN": "此操作需要当前 QQ 官方机器人会话",
+        "en": "This operation requires the current QQ official bot conversation"
+    },
+    "groupRequired": {
+        "zh-CN": "此操作仅支持当前 QQ 群",
+        "en": "This operation requires the current QQ group"
+    },
+    "channelRequired": {
+        "zh-CN": "此操作仅支持当前 QQ 频道子频道",
+        "en": "This operation requires the current QQ guild channel"
+    },
+    "messageOutsideConversation": {
+        "zh-CN": "该消息 ID 不属于当前会话，请勿猜测消息 ID",
+        "en": "The message ID does not belong to this conversation; do not guess message IDs"
+    },
+    "ownMessageRequired": {
+        "zh-CN": "该工具只能撤回机器人自己发送的消息（发送回执里的消息 ID）",
+        "en": "This tool can only recall messages the bot sent (the ID from its send receipt)"
+    },
+    "botNotManager": {
+        "zh-CN": "机器人当前不是本群群主或管理员，平台不允许此操作",
+        "en": "The bot is not an owner or admin of this group, so the platform does not allow this"
+    },
+    "targetNotMember": {
+        "zh-CN": "目标必须是本群的普通成员（官方不允许处置群主、管理员或机器人）",
+        "en": "The target must be an ordinary member of this group (owners, admins and bots cannot be targeted)"
+    },
+    "messageRecalled": {
+        "zh-CN": "平台已确认撤回消息",
+        "en": "The platform confirmed the message was recalled"
+    },
+    "recallUnconfirmed": {
+        "zh-CN": "平台未确认撤回成功（官方只允许撤回 2 分钟内的消息），请勿自动重试",
+        "en": "Recall was not confirmed (QQ only allows recalling messages younger than 2 minutes); do not retry automatically"
+    },
+    "memberKicked": {
+        "zh-CN": "已将成员 {p0} 移出本群",
+        "en": "Removed member {p0} from this group"
+    },
+    "blacklistFailed": {
+        "zh-CN": "成员已移出，但加入黑名单失败",
+        "en": "The member was removed, but adding them to the blacklist failed"
+    },
+    "muted": {
+        "zh-CN": "已禁言 {user} {seconds} 秒",
+        "en": "Muted {user} for {seconds} seconds"
+    },
+    "unmuted": {
+        "zh-CN": "已解除 {user} 的禁言",
+        "en": "Unmuted {user}"
+    },
+    "joinApproved": {
+        "zh-CN": "已通过 {user} 的入群申请",
+        "en": "Approved the join request from {user}"
+    },
+    "joinDeclined": {
+        "zh-CN": "已拒绝 {user} 的入群申请",
+        "en": "Declined the join request from {user}"
     }
 });

package/agents/qq/messages.ts

@@ -20,5 +20,65 @@ export const messages = createMessages({
   "roleRemoved": {
     "zh-CN": "已移除成员的角色",
     "en": "Role removed from the member"
+  },
+  "conversationRequired": {
+    "zh-CN": "此操作需要当前 QQ 官方机器人会话",
+    "en": "This operation requires the current QQ official bot conversation"
+  },
+  "groupRequired": {
+    "zh-CN": "此操作仅支持当前 QQ 群",
+    "en": "This operation requires the current QQ group"
+  },
+  "channelRequired": {
+    "zh-CN": "此操作仅支持当前 QQ 频道子频道",
+    "en": "This operation requires the current QQ guild channel"
+  },
+  "messageOutsideConversation": {
+    "zh-CN": "该消息 ID 不属于当前会话，请勿猜测消息 ID",
+    "en": "The message ID does not belong to this conversation; do not guess message IDs"
+  },
+  "ownMessageRequired": {
+    "zh-CN": "该工具只能撤回机器人自己发送的消息（发送回执里的消息 ID）",
+    "en": "This tool can only recall messages the bot sent (the ID from its send receipt)"
+  },
+  "botNotManager": {
+    "zh-CN": "机器人当前不是本群群主或管理员，平台不允许此操作",
+    "en": "The bot is not an owner or admin of this group, so the platform does not allow this"
+  },
+  "targetNotMember": {
+    "zh-CN": "目标必须是本群的普通成员（官方不允许处置群主、管理员或机器人）",
+    "en": "The target must be an ordinary member of this group (owners, admins and bots cannot be targeted)"
+  },
+  "messageRecalled": {
+    "zh-CN": "平台已确认撤回消息",
+    "en": "The platform confirmed the message was recalled"
+  },
+  "recallUnconfirmed": {
+    "zh-CN": "平台未确认撤回成功（官方只允许撤回 2 分钟内的消息），请勿自动重试",
+    "en": "Recall was not confirmed (QQ only allows recalling messages younger than 2 minutes); do not retry automatically"
+  },
+  "memberKicked": {
+    "zh-CN": "已将成员 {p0} 移出本群",
+    "en": "Removed member {p0} from this group"
+  },
+  "blacklistFailed": {
+    "zh-CN": "成员已移出，但加入黑名单失败",
+    "en": "The member was removed, but adding them to the blacklist failed"
+  },
+  "muted": {
+    "zh-CN": "已禁言 {user} {seconds} 秒",
+    "en": "Muted {user} for {seconds} seconds"
+  },
+  "unmuted": {
+    "zh-CN": "已解除 {user} 的禁言",
+    "en": "Unmuted {user}"
+  },
+  "joinApproved": {
+    "zh-CN": "已通过 {user} 的入群申请",
+    "en": "Approved the join request from {user}"
+  },
+  "joinDeclined": {
+    "zh-CN": "已拒绝 {user} 的入群申请",
+    "en": "Declined the join request from {user}"
   }
 });

package/agents/qq/skills/qq/SKILL.md

@@ -2,13 +2,15 @@
 name: qq
 platforms:
   - qq
-description: QQ 官方机器人频道、角色和成员详情管理。
+description: QQ 官方机器人频道、角色、成员详情与成员禁言／移出管理。
 keywords:
   - qq
   - guild
   - channel
   - role
   - member
+  - 频道禁言
+  - 频道踢人
 tags:
   - adapter
   - community
@@ -20,9 +22,13 @@ tools:
   - remove_role
   - channel_info
   - member_detail
+  - guild_mute_member
+  - guild_kick_member
 scopes:
   - channel
 ---
 # QQ 频道
 
-确认频道和成员 ID 后查询详情或维护角色；权限与审批由各 Tool 执行。可访问频道列表使用 qq-directory。
+确认频道和成员 ID 后查询详情、维护角色或处置成员；权限与审批由各 Tool 执行。可访问频道列表使用 qq-directory。
+
+`guild_mute_member` 作用于当前频道（0 秒 = 解除），`guild_kick_member` 每次人工审批，可选拉黑和撤回近 N 天消息；机器人需具备频道管理权限，平台拒绝时不要自动重试。

package/agents/qq/skills/qq/tools/guild_kick_member/index.js

@@ -0,0 +1,30 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+import { currentGuildChannel } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+export default defineAgentTool({
+    description: '把成员移出当前 QQ 频道，可选拉黑与撤回其近期消息；每次人工审批',
+    adapter: 'qq',
+    scopes: ['channel'],
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'guild_admin')],
+    requiresApproval: 'human',
+    risk: 'dangerous',
+    riskCategory: 'member',
+    inputSchema: z.object({
+        user_id: z.string().min(1).describe('要移出的成员用户 ID'),
+        reason: z.string().min(1).describe('本次移出的具体原因，供人工确认'),
+        blacklist: z.boolean().default(false).describe('是否同时拉黑'),
+        delete_history_days: z.union([z.literal(-1), z.literal(0), z.literal(3), z.literal(7), z.literal(15), z.literal(30)])
+            .default(0).describe('撤回该成员近 N 天消息：0 不撤回，-1 全部'),
+    }),
+    async execute({ user_id, blacklist, delete_history_days }, context) {
+        const { guildId } = currentGuildChannel(context);
+        const ok = await context.$client.api.memberService.kickMember(guildId, user_id, delete_history_days ?? 0, blacklist === true);
+        if (ok === false)
+            return { success: false, message: t(context.locale, 'operationFailed') };
+        return { success: true, message: t(context.locale, 'memberKicked', { p0: user_id }) };
+    },
+});

package/agents/qq/skills/qq/tools/guild_kick_member/index.ts

@@ -0,0 +1,29 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+import { currentGuildChannel } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '把成员移出当前 QQ 频道，可选拉黑与撤回其近期消息；每次人工审批',
+  adapter: 'qq',
+  scopes: ['channel'],
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'guild_admin')],
+  requiresApproval: 'human',
+  risk: 'dangerous',
+  riskCategory: 'member',
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('要移出的成员用户 ID'),
+    reason: z.string().min(1).describe('本次移出的具体原因，供人工确认'),
+    blacklist: z.boolean().default(false).describe('是否同时拉黑'),
+    delete_history_days: z.union([z.literal(-1), z.literal(0), z.literal(3), z.literal(7), z.literal(15), z.literal(30)])
+      .default(0).describe('撤回该成员近 N 天消息：0 不撤回，-1 全部'),
+  }),
+  async execute({ user_id, blacklist, delete_history_days }, context) {
+    const { guildId } = currentGuildChannel(context);
+    const ok = await context.$client.api.memberService.kickMember(guildId, user_id, delete_history_days ?? 0, blacklist === true);
+    if (ok === false) return { success: false, message: t(context.locale, 'operationFailed') };
+    return { success: true, message: t(context.locale, 'memberKicked', { p0: user_id }) };
+  },
+});