@zhin.js/adapter-qq 1.1.16 → 1.1.18

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

@@ -0,0 +1,31 @@
+// 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: 'always',
+    risk: 'dangerous',
+    riskCategory: 'member',
+    inputSchema: z.object({
+        user_id: z.string().min(1).describe('目标成员用户 ID'),
+        duration: z.number().int().min(0).default(0).describe('禁言秒数，0 = 解除禁言'),
+    }),
+    async execute({ user_id, duration }, context) {
+        const { guildId } = currentGuildChannel(context);
+        const members = context.$client.api.memberService;
+        const seconds = duration ?? 0;
+        const ok = seconds === 0
+            ? await members.unmuteGuildMember(guildId, user_id)
+            : await members.muteGuildMember(guildId, user_id, seconds);
+        if (ok === false)
+            return { success: false, message: t(context.locale, 'operationFailed') };
+        return { success: true, message: seconds === 0 ? t(context.locale, 'unmuted', { user: user_id }) : t(context.locale, 'muted', { user: user_id, seconds }) };
+    },
+});

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

@@ -0,0 +1,30 @@
+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: 'always',
+  risk: 'dangerous',
+  riskCategory: 'member',
+  inputSchema: z.object({
+    user_id: z.string().min(1).describe('目标成员用户 ID'),
+    duration: z.number().int().min(0).default(0).describe('禁言秒数，0 = 解除禁言'),
+  }),
+  async execute({ user_id, duration }, context) {
+    const { guildId } = currentGuildChannel(context);
+    const members = context.$client.api.memberService;
+    const seconds = duration ?? 0;
+    const ok = seconds === 0
+      ? await members.unmuteGuildMember(guildId, user_id)
+      : await members.muteGuildMember(guildId, user_id, seconds);
+    if (ok === false) return { success: false, message: t(context.locale, 'operationFailed') };
+    return { success: true, message: seconds === 0 ? t(context.locale, 'unmuted', { user: user_id }) : t(context.locale, 'muted', { user: user_id, seconds }) };
+  },
+});

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

@@ -0,0 +1,24 @@
+---
+name: qq-conversation
+platforms:
+  - qq
+description: 查询当前 QQ 群或频道信息、机器人自身身份（群主／管理员／成员）以及当前会话支持的操作和官方限制。
+keywords:
+  - 当前群
+  - 当前频道
+  - 你是管理员吗
+  - 群主
+  - 机器人权限
+  - 身份
+tools:
+  - conversation_info
+---
+# qq-conversation
+
+Use `conversation_info` before claiming the bot's role or available platform permissions. Group roles come live from the official `bot_state` API for the current endpoint, not from the sender's role. A failed lookup is not evidence that the bot is an ordinary member.
+
+Caller roles authorize a request; bot platform roles determine whether QQ can execute it. They are independent, and a successful inspection does not replace the live check each management tool performs.
+
+In guilds the bot role is read from its guild member record (4 owner, 2 admin, 5 child-channel admin). A `channel_admin` record does not say which child channels it governs, so it cannot authorize an operation in the current channel.
+
+The official QQ Bot API has no merged forward, poke, profile like, leave group, group announcement, essence, special title, anonymous, group files or group sign-in. Do not promise or simulate them.

package/agents/qq/skills/qq-conversation/tools/conversation_info/index.js

@@ -0,0 +1,78 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentConversation } from '../../../../conversation.js';
+/** Guild built-in role ids: 4 = owner, 2 = super admin, 5 = child-channel admin. */
+function guildRole(roles) {
+    const ids = (roles ?? []).map(String);
+    if (ids.includes('4'))
+        return 'owner';
+    if (ids.includes('2'))
+        return 'admin';
+    if (ids.includes('5'))
+        return 'channel_admin';
+    return ids.length ? 'member' : 'unknown';
+}
+export default defineAgentTool({
+    description: '读取当前 QQ 官方机器人会话及机器人自己的群／频道身份；区分调用者权限、机器人平台权限和官方不支持的操作',
+    adapter: 'qq',
+    requiresApproval: 'never',
+    readOnly: true,
+    inputSchema: z.object({}),
+    async execute(_input, context) {
+        const conversation = currentConversation(context);
+        const roles = context.principal.roles;
+        const common = {
+            conversation,
+            requester: {
+                roles,
+                canRequestGroupModeration: roles.some(role => ['master', 'admin', 'trusted', 'owner'].includes(role)),
+            },
+            operations: {
+                quoteReply: true,
+                recallOwnMessage: true,
+                recallMemberMessage: conversation.kind === 'group' || conversation.kind === 'channel',
+                reaction: conversation.kind === 'channel',
+                // 官方 API 不提供：合并转发、戳一戳、点赞、退群、群公告、精华、头衔、匿名、群文件、群签到。
+                forwardMessages: false,
+                leaveGroup: false,
+            },
+        };
+        const api = context.$client.api;
+        if (conversation.kind === 'group') {
+            const [state, info] = await Promise.all([
+                api.groupService.getBotState(conversation.id),
+                api.groupService.getInfo(conversation.id).catch(() => undefined),
+            ]);
+            context.signal.throwIfAborted();
+            const role = state.member_role;
+            return {
+                ...common,
+                group: { id: conversation.id, name: info?.group_name, memberCount: info?.group_member_num },
+                bot: {
+                    id: state.member_openid,
+                    role,
+                    canModerateMembers: role === 'owner' || role === 'admin',
+                    allowProactiveMessage: state.allow_proactive_msg,
+                    receiveSetting: state.recv_msg_setting,
+                    joinedAt: state.joined_at,
+                },
+            };
+        }
+        if (conversation.kind === 'channel' && conversation.parent?.kind === 'channel') {
+            const guildId = conversation.parent.id;
+            const self = await api.botService.getSelfInfo();
+            const member = self?.id
+                ? await api.memberService.getGuildMemberInfo(guildId, String(self.id)).catch(() => undefined)
+                : undefined;
+            context.signal.throwIfAborted();
+            return {
+                ...common,
+                guild: { id: guildId },
+                channel: { id: conversation.id },
+                bot: { id: self?.id, role: guildRole(member?.roles), channelAdminScope: 'unknown' },
+            };
+        }
+        return { ...common, bot: { role: 'not_applicable' } };
+    },
+});

package/agents/qq/skills/qq-conversation/tools/conversation_info/index.ts

@@ -0,0 +1,76 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { currentConversation } from '../../../../conversation.js';
+
+/** Guild built-in role ids: 4 = owner, 2 = super admin, 5 = child-channel admin. */
+function guildRole(roles: readonly unknown[] | undefined): string {
+  const ids = (roles ?? []).map(String);
+  if (ids.includes('4')) return 'owner';
+  if (ids.includes('2')) return 'admin';
+  if (ids.includes('5')) return 'channel_admin';
+  return ids.length ? 'member' : 'unknown';
+}
+
+export default defineAgentTool({
+  description: '读取当前 QQ 官方机器人会话及机器人自己的群／频道身份；区分调用者权限、机器人平台权限和官方不支持的操作',
+  adapter: 'qq',
+  requiresApproval: 'never',
+  readOnly: true,
+  inputSchema: z.object({}),
+  async execute(_input, context) {
+    const conversation = currentConversation(context);
+    const roles = context.principal.roles;
+    const common = {
+      conversation,
+      requester: {
+        roles,
+        canRequestGroupModeration: roles.some(role => ['master', 'admin', 'trusted', 'owner'].includes(role)),
+      },
+      operations: {
+        quoteReply: true,
+        recallOwnMessage: true,
+        recallMemberMessage: conversation.kind === 'group' || conversation.kind === 'channel',
+        reaction: conversation.kind === 'channel',
+        // 官方 API 不提供：合并转发、戳一戳、点赞、退群、群公告、精华、头衔、匿名、群文件、群签到。
+        forwardMessages: false,
+        leaveGroup: false,
+      },
+    };
+    const api = context.$client.api;
+    if (conversation.kind === 'group') {
+      const [state, info] = await Promise.all([
+        api.groupService.getBotState(conversation.id),
+        api.groupService.getInfo(conversation.id).catch(() => undefined),
+      ]);
+      context.signal.throwIfAborted();
+      const role = state.member_role;
+      return {
+        ...common,
+        group: { id: conversation.id, name: info?.group_name, memberCount: info?.group_member_num },
+        bot: {
+          id: state.member_openid,
+          role,
+          canModerateMembers: role === 'owner' || role === 'admin',
+          allowProactiveMessage: state.allow_proactive_msg,
+          receiveSetting: state.recv_msg_setting,
+          joinedAt: state.joined_at,
+        },
+      };
+    }
+    if (conversation.kind === 'channel' && conversation.parent?.kind === 'channel') {
+      const guildId = conversation.parent.id;
+      const self = await api.botService.getSelfInfo();
+      const member = self?.id
+        ? await api.memberService.getGuildMemberInfo(guildId, String(self.id)).catch(() => undefined)
+        : undefined;
+      context.signal.throwIfAborted();
+      return {
+        ...common,
+        guild: { id: guildId },
+        channel: { id: conversation.id },
+        bot: { id: self?.id, role: guildRole(member?.roles), channelAdminScope: 'unknown' },
+      };
+    }
+    return { ...common, bot: { role: 'not_applicable' } };
+  },
+});

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

@@ -0,0 +1,34 @@
+---
+name: qq-group-admin
+platforms:
+  - qq
+description: QQ 官方机器人群管理：移出成员、禁言、撤回他人消息、处理入群申请；工具分别声明权限与审批要求。
+keywords:
+  - 群管理
+  - 禁言
+  - 踢人
+  - 移出
+  - 入群申请
+  - 撤回他人消息
+tools:
+  - group_kick
+  - set_mute
+  - recall_member_message
+  - handle_join_request
+scopes:
+  - group
+  - channel
+---
+# qq-group-admin
+
+Load only when the current group and target member are explicit. Every tool targets the current conversation; the model cannot choose another group. Each tool re-checks the bot's live role (`bot_state`) before acting.
+
+Official limits (enforced by QQ, not by this skill): the bot must be group owner/admin; only ordinary members (not owner, admins or bots) can be removed or muted; mute is at most 30 days; recall works only within 2 minutes; member removal and join-request APIs are invite-only (11253 = no access).
+
+`group_kick` and `handle_join_request` need a fresh human approval each time; show the target member and the reason. A previous approval never authorizes the next action. `set_mute` always needs approval.
+
+Automatic moderation needs a confirmed rule and target group; never invent trigger conditions from permissions alone.
+
+`recall_member_message` keeps the master/admin/trusted/owner requester permission without per-call approval and also works in guild channels (platform-enforced admin rights). To recall the bot's own message, use `qq-messages`.
+
+Not available on official bots: invite to group, leave group, special title, anonymous, announcement, essence, poke and group sign-in.

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

@@ -0,0 +1,39 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+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.api.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.api, group, user_id, 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/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.api.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.api, group, user_id, 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.api.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.api.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.api.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.api, group, user_id, 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.api.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.api, group, user_id, 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.api.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.api.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.api.groupService.getMemberInfo(currentGroup(context), user_id);
+        return { success: true, member };
+    },
+});