@zhin.js/adapter-qq 1.1.17 → 1.1.19

package/agents/qq/skills/qq-group-admin/tools/group_kick/index.ts

@@ -0,0 +1,38 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup, kickQqGroupMember, requireGroupManager } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '把当前 QQ 群中的普通成员移出群，可选同时拉黑；每次人工审批，官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'human',
+  risk: 'dangerous',
+  riskCategory: 'member',
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('要移出的成员 member_openid'),
+    reason: z.string().min(1).describe('本次移出的具体原因，随目标成员一起供人工确认'),
+    blacklist: z.boolean().default(false).describe('是否同时加入群黑名单'),
+  }),
+  async execute({ user_id, blacklist }, context) {
+    const group = currentGroup(context);
+    const client = context.$client;
+    const [self, member] = await Promise.all([
+      requireGroupManager(context, group),
+      client.groupService.getMemberInfo(group, user_id),
+    ]);
+    if (!self) return { success: false, message: t(context.locale, 'botNotManager') };
+    if (member.member_openid !== user_id || member.member_role !== 'member' || member.bot || user_id === self.member_openid) {
+      return { success: false, message: t(context.locale, 'targetNotMember') };
+    }
+    context.signal.throwIfAborted();
+    const { blacklistFailed } = await kickQqGroupMember(client, { groupId: group, userId: user_id, addToBlacklist: blacklist === true });
+    return {
+      success: true,
+      message: t(context.locale, 'memberKicked', { p0: member.username || user_id }),
+      ...(blacklistFailed ? { warning: t(context.locale, 'blacklistFailed') } : {}),
+    };
+  },
+});

package/agents/qq/skills/qq-group-admin/tools/handle_join_request/index.js

@@ -0,0 +1,33 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup, requireGroupManager } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+export default defineAgentTool({
+    description: '通过或拒绝当前 QQ 群的一条入群申请；每次人工审批，需机器人为群管理员，官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'human',
+    risk: 'dangerous',
+    riskCategory: 'member',
+    inputSchema: z.object({
+        user_id: z.string().min(1).describe('申请人 member_openid（来自 list_join_requests 或入群申请事件）'),
+        join_request_id: z.string().min(1).optional().describe('申请 ID（list_join_requests 返回的 join_request_id）'),
+        approve: z.boolean().describe('true 通过，false 拒绝'),
+        reason: z.string().optional().describe('拒绝理由（仅拒绝时发送）'),
+        blacklist: z.boolean().default(false).describe('拒绝时是否同时拉黑'),
+    }),
+    async execute({ user_id, join_request_id, approve, reason, blacklist }, context) {
+        const group = currentGroup(context);
+        if (!await requireGroupManager(context, group))
+            return { success: false, message: t(context.locale, 'botNotManager') };
+        await context.$client.groupService.approveJoinRequest(group, user_id, {
+            op: approve ? 'approve' : 'decline',
+            ...(join_request_id ? { join_request_id } : {}),
+            ...(!approve && reason ? { reject_reason: reason } : {}),
+            ...(!approve && blacklist ? { add_to_member_blacklist: true } : {}),
+        });
+        return { success: true, message: t(context.locale, approve ? 'joinApproved' : 'joinDeclined', { user: user_id }) };
+    },
+});

package/agents/qq/skills/qq-group-admin/tools/handle_join_request/index.ts

@@ -0,0 +1,32 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup, requireGroupManager } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '通过或拒绝当前 QQ 群的一条入群申请；每次人工审批，需机器人为群管理员，官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'human',
+  risk: 'dangerous',
+  riskCategory: 'member',
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('申请人 member_openid（来自 list_join_requests 或入群申请事件）'),
+    join_request_id: z.string().min(1).optional().describe('申请 ID（list_join_requests 返回的 join_request_id）'),
+    approve: z.boolean().describe('true 通过，false 拒绝'),
+    reason: z.string().optional().describe('拒绝理由（仅拒绝时发送）'),
+    blacklist: z.boolean().default(false).describe('拒绝时是否同时拉黑'),
+  }),
+  async execute({ user_id, join_request_id, approve, reason, blacklist }, context) {
+    const group = currentGroup(context);
+    if (!await requireGroupManager(context, group)) return { success: false, message: t(context.locale, 'botNotManager') };
+    await context.$client.groupService.approveJoinRequest(group, user_id, {
+      op: approve ? 'approve' : 'decline',
+      ...(join_request_id ? { join_request_id } : {}),
+      ...(!approve && reason ? { reject_reason: reason } : {}),
+      ...(!approve && blacklist ? { add_to_member_blacklist: true } : {}),
+    });
+    return { success: true, message: t(context.locale, approve ? 'joinApproved' : 'joinDeclined', { user: user_id }) };
+  },
+});

package/agents/qq/skills/qq-group-admin/tools/recall_member_message/index.js

@@ -0,0 +1,25 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentConversation, recallTarget, requireGroupManager, resolveMessageTarget } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+export default defineAgentTool({
+    description: '撤回当前 QQ 群或频道子频道内他人的真实消息；需调用方具备群管发起权限，机器人须为管理员，官方只允许 2 分钟内',
+    adapter: 'qq',
+    scopes: ['group', 'channel'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    inputSchema: z.object({
+        message_id: z.string().min(1).describe('当前会话中要撤回的真实消息 ID，或消息头里的 m<n> 别名'),
+        reason: z.string().min(1).describe('撤回的具体原因，自动处理必须依据已确认的群规'),
+    }),
+    async execute({ message_id }, context) {
+        const conversation = currentConversation(context);
+        const target = resolveMessageTarget(context, message_id);
+        // 自己的消息不依赖管理员身份。群里再实时核验机器人角色；目标角色（只能撤回普通成员）由平台执行。
+        if (!target.ownOutbound && conversation.kind === 'group' && !await requireGroupManager(context, conversation.id)) {
+            return { success: false, message: t(context.locale, 'botNotManager') };
+        }
+        return recallTarget(context, target);
+    },
+});

package/agents/qq/skills/qq-group-admin/tools/recall_member_message/index.ts

@@ -0,0 +1,25 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentConversation, recallTarget, requireGroupManager, resolveMessageTarget } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '撤回当前 QQ 群或频道子频道内他人的真实消息；需调用方具备群管发起权限，机器人须为管理员，官方只允许 2 分钟内',
+  adapter: 'qq',
+  scopes: ['group', 'channel'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  inputSchema: z.object({
+    message_id: z.string().min(1).describe('当前会话中要撤回的真实消息 ID，或消息头里的 m<n> 别名'),
+    reason: z.string().min(1).describe('撤回的具体原因，自动处理必须依据已确认的群规'),
+  }),
+  async execute({ message_id }, context) {
+    const conversation = currentConversation(context);
+    const target = resolveMessageTarget(context, message_id);
+    // 自己的消息不依赖管理员身份。群里再实时核验机器人角色；目标角色（只能撤回普通成员）由平台执行。
+    if (!target.ownOutbound && conversation.kind === 'group' && !await requireGroupManager(context, conversation.id)) {
+      return { success: false, message: t(context.locale, 'botNotManager') };
+    }
+    return recallTarget(context, target);
+  },
+});

package/agents/qq/skills/qq-group-admin/tools/set_mute/index.js

@@ -0,0 +1,37 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS, requireGroupManager } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+export default defineAgentTool({
+    description: '禁言 / 解除禁言当前 QQ 群中的普通成员（最长 30 天）；需机器人为群管理员',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'always',
+    risk: 'dangerous',
+    riskCategory: 'member',
+    inputSchema: z.object({
+        user_id: z.string().min(1).describe('目标成员 member_openid'),
+        duration: z.number().int().min(0).max(QQ_GROUP_MUTE_MAX_SECONDS).default(0).describe('禁言秒数，0 = 解除禁言，最长 2592000（30 天）'),
+    }),
+    async execute({ user_id, duration }, context) {
+        const group = currentGroup(context);
+        const client = context.$client;
+        const seconds = duration ?? 0;
+        const [self, member] = await Promise.all([
+            requireGroupManager(context, group),
+            client.groupService.getMemberInfo(group, user_id),
+        ]);
+        if (!self)
+            return { success: false, message: t(context.locale, 'botNotManager') };
+        // 官方：新增 / 更新禁言只能作用于普通成员；解除不限制。
+        if (member.member_openid !== user_id || (seconds > 0 && (member.member_role !== 'member' || member.bot))) {
+            return { success: false, message: t(context.locale, 'targetNotMember') };
+        }
+        context.signal.throwIfAborted();
+        await muteQqGroupMember(client, { groupId: group, userId: user_id, durationSeconds: seconds });
+        const user = member.username || user_id;
+        return { success: true, message: seconds === 0 ? t(context.locale, 'unmuted', { user }) : t(context.locale, 'muted', { user, seconds }) };
+    },
+});

package/agents/qq/skills/qq-group-admin/tools/set_mute/index.ts

@@ -0,0 +1,36 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS, requireGroupManager } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '禁言 / 解除禁言当前 QQ 群中的普通成员（最长 30 天）；需机器人为群管理员',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'always',
+  risk: 'dangerous',
+  riskCategory: 'member',
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('目标成员 member_openid'),
+    duration: z.number().int().min(0).max(QQ_GROUP_MUTE_MAX_SECONDS).default(0).describe('禁言秒数，0 = 解除禁言，最长 2592000（30 天）'),
+  }),
+  async execute({ user_id, duration }, context) {
+    const group = currentGroup(context);
+    const client = context.$client;
+    const seconds = duration ?? 0;
+    const [self, member] = await Promise.all([
+      requireGroupManager(context, group),
+      client.groupService.getMemberInfo(group, user_id),
+    ]);
+    if (!self) return { success: false, message: t(context.locale, 'botNotManager') };
+    // 官方：新增 / 更新禁言只能作用于普通成员；解除不限制。
+    if (member.member_openid !== user_id || (seconds > 0 && (member.member_role !== 'member' || member.bot))) {
+      return { success: false, message: t(context.locale, 'targetNotMember') };
+    }
+    context.signal.throwIfAborted();
+    await muteQqGroupMember(client, { groupId: group, userId: user_id, durationSeconds: seconds });
+    const user = member.username || user_id;
+    return { success: true, message: seconds === 0 ? t(context.locale, 'unmuted', { user }) : t(context.locale, 'muted', { user, seconds }) };
+  },
+});

package/agents/qq/skills/qq-group-directory/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: qq-group-directory
+platforms:
+  - qq
+description: 当前 QQ 群的群信息、成员列表与成员详情（官方白名单能力）。
+keywords:
+  - 群信息
+  - 群成员
+  - 成员列表
+  - member_openid
+tools:
+  - group_info
+  - group_members
+  - group_member_info
+scopes:
+  - group
+---
+# qq-group-directory
+
+All lookups target the current group only. Members are identified by `member_openid`, which is scoped to this bot and group; never derive it from a nickname or reuse it in another group.
+
+Member list and member detail are invite-only official capabilities. Error 11253 means the bot has no access; report that instead of guessing. `group_members` is paged (≤30 per page, 60 QPM): request further pages only when needed.
+
+There is no official API for the bot's group list, friend list or arbitrary user profiles, so `group_list`, `friend_list` and `user_info` do not exist on QQ official bots.

package/agents/qq/skills/qq-group-directory/tools/group_info/index.js

@@ -0,0 +1,16 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '获取当前 QQ 群的基本信息（群名、简介、分类、标签、人数）',
+    adapter: 'qq',
+    scopes: ['group'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({}),
+    async execute(_input, context) {
+        const info = await context.$client.groupService.getInfo(currentGroup(context));
+        return { success: true, group: info };
+    },
+});

package/agents/qq/skills/qq-group-directory/tools/group_info/index.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '获取当前 QQ 群的基本信息（群名、简介、分类、标签、人数）',
+  adapter: 'qq',
+  scopes: ['group'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({}),
+  async execute(_input, context) {
+    const info = await context.$client.groupService.getInfo(currentGroup(context));
+    return { success: true, group: info };
+  },
+});

package/agents/qq/skills/qq-group-directory/tools/group_member_info/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '获取当前 QQ 群中指定成员的信息（昵称、角色、是否机器人、入群时间）；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        user_id: z.string().min(1).describe('目标成员的 member_openid（来自消息发送者或成员列表，不要猜测）'),
+    }),
+    async execute({ user_id }, context) {
+        const member = await context.$client.groupService.getMemberInfo(currentGroup(context), user_id);
+        return { success: true, member };
+    },
+});

package/agents/qq/skills/qq-group-directory/tools/group_member_info/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '获取当前 QQ 群中指定成员的信息（昵称、角色、是否机器人、入群时间）；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('目标成员的 member_openid（来自消息发送者或成员列表，不要猜测）'),
+  }),
+  async execute({ user_id }, context) {
+    const member = await context.$client.groupService.getMemberInfo(currentGroup(context), user_id);
+    return { success: true, member };
+  },
+});

package/agents/qq/skills/qq-group-directory/tools/group_members/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '分页列出当前 QQ 群成员（每页最多 30 人，含 member_openid、昵称、角色）；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+    }),
+    async execute({ cursor }, context) {
+        const page = await context.$client.groupService.getMembersPage(currentGroup(context), cursor ? { cursor } : {});
+        return { success: true, members: page.members ?? [], count: page.members?.length ?? 0, next_cursor: page.next_cursor || undefined };
+    },
+});

package/agents/qq/skills/qq-group-directory/tools/group_members/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '分页列出当前 QQ 群成员（每页最多 30 人，含 member_openid、昵称、角色）；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+  }),
+  async execute({ cursor }, context) {
+    const page = await context.$client.groupService.getMembersPage(currentGroup(context), cursor ? { cursor } : {});
+    return { success: true, members: page.members ?? [], count: page.members?.length ?? 0, next_cursor: page.next_cursor || undefined };
+  },
+});

package/agents/qq/skills/qq-group-state/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: qq-group-state
+platforms:
+  - qq
+description: 当前 QQ 群的禁言状态、待处理入群申请与黑名单查询。
+keywords:
+  - 禁言列表
+  - 入群申请
+  - 黑名单
+tools:
+  - list_muted
+  - list_join_requests
+  - group_blacklist
+scopes:
+  - group
+---
+# qq-group-state
+
+Read-only views of the current group. `list_muted` returns the global mute rule and members whose mute has not expired. `list_join_requests` and `group_blacklist` are paged invite-only APIs; error 11253 means the bot has no access.
+
+Act on a join request with `qq-group-admin` → `handle_join_request`, after confirming the applicant. Group files are not exposed by the official API.

package/agents/qq/skills/qq-group-state/tools/group_blacklist/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '分页查询当前 QQ 群的成员黑名单；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+    }),
+    async execute({ cursor }, context) {
+        const page = await context.$client.groupService.getMemberBlacklist(currentGroup(context), cursor ? { cursor } : {});
+        return { users: page.users ?? [], count: page.users?.length ?? 0, next_cursor: page.next_cursor || undefined };
+    },
+});

package/agents/qq/skills/qq-group-state/tools/group_blacklist/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '分页查询当前 QQ 群的成员黑名单；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+  }),
+  async execute({ cursor }, context) {
+    const page = await context.$client.groupService.getMemberBlacklist(currentGroup(context), cursor ? { cursor } : {});
+    return { users: page.users ?? [], count: page.users?.length ?? 0, next_cursor: page.next_cursor || undefined };
+  },
+});

package/agents/qq/skills/qq-group-state/tools/list_join_requests/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '分页列出当前 QQ 群待处理的入群申请（含验证信息、风险提示）；官方白名单能力',
+    adapter: 'qq',
+    scopes: ['group'],
+    permissions: ['role(master,admin,trusted,owner)'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({
+        cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+    }),
+    async execute({ cursor }, context) {
+        const page = await context.$client.groupService.getJoinRequests(currentGroup(context), cursor ? { cursor } : {});
+        return { requests: page.list ?? [], count: page.list?.length ?? 0, next_cursor: page.next_cursor || undefined };
+    },
+});

package/agents/qq/skills/qq-group-state/tools/list_join_requests/index.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '分页列出当前 QQ 群待处理的入群申请（含验证信息、风险提示）；官方白名单能力',
+  adapter: 'qq',
+  scopes: ['group'],
+  permissions: ['role(master,admin,trusted,owner)'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({
+    cursor: z.string().optional().describe('上一页返回的 next_cursor；首次不传'),
+  }),
+  async execute({ cursor }, context) {
+    const page = await context.$client.groupService.getJoinRequests(currentGroup(context), cursor ? { cursor } : {});
+    return { requests: page.list ?? [], count: page.list?.length ?? 0, next_cursor: page.next_cursor || undefined };
+  },
+});

package/agents/qq/skills/qq-group-state/tools/list_muted/index.js

@@ -0,0 +1,21 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '查询当前 QQ 群的禁言状态：全员禁言规则与被禁言成员列表',
+    adapter: 'qq',
+    scopes: ['group'],
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({}),
+    async execute(_input, context) {
+        const setting = await context.$client.groupService.getMuteSetting(currentGroup(context));
+        const now = Date.now();
+        const muted = (setting.members ?? []).filter((m) => {
+            const until = Date.parse(m.mute_expire_at);
+            return !Number.isFinite(until) || until > now;
+        });
+        return { global_rule: setting.global_rule, muted_members: muted, count: muted.length };
+    },
+});

package/agents/qq/skills/qq-group-state/tools/list_muted/index.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentGroup } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '查询当前 QQ 群的禁言状态：全员禁言规则与被禁言成员列表',
+  adapter: 'qq',
+  scopes: ['group'],
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({}),
+  async execute(_input, context) {
+    const setting = await context.$client.groupService.getMuteSetting(currentGroup(context));
+    const now = Date.now();
+    const muted = (setting.members ?? []).filter((m) => {
+      const until = Date.parse(m.mute_expire_at);
+      return !Number.isFinite(until) || until > now;
+    });
+    return { global_rule: setting.global_rule, muted_members: muted, count: muted.length };
+  },
+});

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

@@ -0,0 +1,27 @@
+---
+name: qq-messages
+platforms:
+  - qq
+description: QQ 官方机器人当前会话的引用回复，以及撤回机器人自己的发言。
+keywords:
+  - 引用
+  - 回复原消息
+  - 撤回
+  - 自己的消息
+tools:
+  - quote_reply
+  - recall_own_message
+scopes:
+  - private
+  - group
+  - channel
+---
+# qq-messages
+
+Only use real message IDs from the current conversation. Do not invent IDs or source authors. Both tools stay inside the current conversation; cross-conversation forwarding does not exist on the official API.
+
+`quote_reply` sends a text reply that references one original (passive reply `msg_id` / guild `message_reference`) through the unified outbound pipeline. Use `inspect_conversation_reference` to read an incoming quote when available; it does not send messages.
+
+`recall_own_message` accepts only the bot's own send receipt ID and needs no management role or approval. QQ only recalls messages younger than 2 minutes; never promise success before confirmation or retry an unconfirmed result. To recall another member's message, load `qq-group-admin`.
+
+Merged forward (`forward_messages`) is not available: the official API cannot send merged-forward records.

package/agents/qq/skills/qq-messages/tools/quote_reply/index.js

@@ -0,0 +1,21 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { resolveMessageTarget, sendToConversation } from '../../../../conversation.js';
+export default defineAgentTool({
+    description: '引用当前 QQ 会话中的真实消息并回复文字（引用即被动回复的 msg_id / message_reference）；发送走统一链路',
+    adapter: 'qq',
+    scopes: ['private', 'group', 'channel'],
+    requiresApproval: 'never',
+    inputSchema: z.object({
+        message_id: z.string().min(1).describe('当前会话中真实的原消息 ID，或消息头里的 m<n> 别名'),
+        text: z.string().min(1).describe('本次回复的文字'),
+    }),
+    async execute({ message_id, text }, context) {
+        const target = resolveMessageTarget(context, message_id);
+        return sendToConversation(context, [
+            { type: 'reply', data: { message_id: target.messageId } },
+            { type: 'text', data: { text } },
+        ]);
+    },
+});

package/agents/qq/skills/qq-messages/tools/quote_reply/index.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { resolveMessageTarget, sendToConversation } from '../../../../conversation.js';
+
+export default defineAgentTool({
+  description: '引用当前 QQ 会话中的真实消息并回复文字（引用即被动回复的 msg_id / message_reference）；发送走统一链路',
+  adapter: 'qq',
+  scopes: ['private', 'group', 'channel'],
+  requiresApproval: 'never',
+  inputSchema: z.object({
+    message_id: z.string().min(1).describe('当前会话中真实的原消息 ID，或消息头里的 m<n> 别名'),
+    text: z.string().min(1).describe('本次回复的文字'),
+  }),
+  async execute({ message_id, text }, context) {
+    const target = resolveMessageTarget(context, message_id);
+    return sendToConversation(context, [
+      { type: 'reply', data: { message_id: target.messageId } },
+      { type: 'text', data: { text } },
+    ]);
+  },
+});

package/agents/qq/skills/qq-messages/tools/recall_own_message/index.js

@@ -0,0 +1,18 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { recallTarget, resolveMessageTarget } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+export default defineAgentTool({
+    description: '撤回机器人在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
+    adapter: 'qq',
+    scopes: ['private', 'group', 'channel'],
+    requiresApproval: 'never',
+    inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的消息 ID（发送回执），或消息头里的 m<n> 别名') }),
+    async execute({ message_id }, context) {
+        const target = resolveMessageTarget(context, message_id);
+        if (!target.ownOutbound)
+            return { success: false, message: t(context.locale, 'ownMessageRequired') };
+        return recallTarget(context, target);
+    },
+});

package/agents/qq/skills/qq-messages/tools/recall_own_message/index.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { recallTarget, resolveMessageTarget } from '../../../../conversation.js';
+import { messages as t } from '../../../../messages.js';
+
+export default defineAgentTool({
+  description: '撤回机器人在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
+  adapter: 'qq',
+  scopes: ['private', 'group', 'channel'],
+  requiresApproval: 'never',
+  inputSchema: z.object({ message_id: z.string().min(1).describe('机器人在当前会话中发送的消息 ID（发送回执），或消息头里的 m<n> 别名') }),
+  async execute({ message_id }, context) {
+    const target = resolveMessageTarget(context, message_id);
+    if (!target.ownOutbound) return { success: false, message: t(context.locale, 'ownMessageRequired') };
+    return recallTarget(context, target);
+  },
+});