@zhin.js/adapter-qq 1.1.17 → 1.1.19

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/add_role/index.js

@@ -17,7 +17,8 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id, channel_id, user_id, role_id }, context) {
         const client = context.$client;
-        const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
+        await client.memberService.addMemberRole(guild_id, channel_id, user_id, role_id);
+        const success = true;
         return { success, message: success ? t(context.locale, 'roleAdded') : t(context.locale, 'operationFailed') };
     },
 });

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

@@ -17,7 +17,8 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
   permissions: [platformPermission('qq', '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);
+    await client.memberService.addMemberRole(guild_id, channel_id, user_id, role_id);
+    const success = true;
     return { success, message: success ? t(context.locale, 'roleAdded') : t(context.locale, 'operationFailed') };
   },
 });

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

@@ -13,6 +13,6 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ channel_id }, context) {
         const client = context.$client;
-        return client.getChannelInfo(channel_id);
+        return client.channelService.getInfo(channel_id);
     },
 });

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

@@ -13,6 +13,6 @@ export default defineAgentTool<{ channel_id: string }>({
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ channel_id  }: { channel_id: string }, context) {
     const client = context.$client;
-    return client.getChannelInfo(channel_id);
+    return client.channelService.getInfo(channel_id);
   },
 });

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

@@ -16,7 +16,7 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'guild_owner')],
     async execute({ guild_id, name, color }, context) {
         const client = context.$client;
-        const role = await client.createGuildRole(guild_id, name, color);
+        const role = await client.guildService.createRole(guild_id, { name, color: color || 0, hoist: 0 });
         return { success: !!role, role, message: role ? t(context.locale, 'namedRoleCreated', { p0: name }) : t(context.locale, 'createFailed') };
     },
 });

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

@@ -16,7 +16,7 @@ export default defineAgentTool<{ guild_id: string; name: string; color?: number
   permissions: [platformPermission('qq', '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);
+    const role = await client.guildService.createRole(guild_id, { name, color: color || 0, hoist: 0 });
     return { success: !!role, role, message: role ? t(context.locale, 'namedRoleCreated', { p0: name }) : t(context.locale, 'createFailed') };
   },
 });

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.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.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_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.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.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/list_channels/index.js

@@ -13,7 +13,7 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_channels')],
     async execute({ guild_id }, context) {
         const client = context.$client;
-        const channels = await client.getChannels(guild_id);
+        const channels = await client.channelService.getList(guild_id);
         return { channels, count: channels.length };
     },
 });

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

@@ -13,7 +13,7 @@ export default defineAgentTool<{ guild_id: string }>({
   permissions: [platformPermission('qq', 'manage_channels')],
   async execute({ guild_id  }: { guild_id: string }, context) {
     const client = context.$client;
-    const channels = await client.getChannels(guild_id);
+    const channels = await client.channelService.getList(guild_id);
     return { channels, count: channels.length };
   },
 });

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

@@ -13,7 +13,7 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id }, context) {
         const client = context.$client;
-        const roles = await client.getGuildRoles(guild_id);
+        const roles = await client.guildService.getRoles(guild_id);
         return { roles, count: roles.length };
     },
 });

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

@@ -13,7 +13,7 @@ export default defineAgentTool<{ guild_id: string }>({
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id  }: { guild_id: string }, context) {
     const client = context.$client;
-    const roles = await client.getGuildRoles(guild_id);
+    const roles = await client.guildService.getRoles(guild_id);
     return { roles, count: roles.length };
   },
 });

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

@@ -14,6 +14,6 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ guild_id, user_id }, context) {
         const client = context.$client;
-        return client.getGuildMember(guild_id, user_id);
+        return client.memberService.getGuildMemberInfo(guild_id, user_id);
     },
 });

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

@@ -14,6 +14,6 @@ export default defineAgentTool<{ guild_id: string; user_id: string }>({
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ guild_id, user_id  }: { guild_id: string; user_id: string }, context) {
     const client = context.$client;
-    return client.getGuildMember(guild_id, user_id);
+    return client.memberService.getGuildMemberInfo(guild_id, user_id);
   },
 });

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

@@ -17,7 +17,8 @@ export default defineAgentTool({
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id, channel_id, user_id, role_id }, context) {
         const client = context.$client;
-        const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
+        await client.memberService.removeMemberRole(guild_id, channel_id, user_id, role_id);
+        const success = true;
         return { success, message: success ? t(context.locale, 'roleRemoved') : t(context.locale, 'operationFailed') };
     },
 });

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

@@ -17,7 +17,8 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
   permissions: [platformPermission('qq', '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.removeMemberRole(guild_id, channel_id, user_id, role_id);
+    await client.memberService.removeMemberRole(guild_id, channel_id, user_id, role_id);
+    const success = true;
     return { success, message: success ? t(context.locale, 'roleRemoved') : t(context.locale, 'operationFailed') };
   },
 });

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;
+        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;
+    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-directory/tools/list_guilds/index.js

@@ -8,7 +8,7 @@ export default defineAgentTool({
     tags: ['qq'],
     async execute(_input, context) {
         const client = context.$client;
-        const guilds = await client.getGuilds();
+        const guilds = await client.guildService.getList();
         return { guilds, count: guilds.length };
     },
 });

package/agents/qq/skills/qq-directory/tools/list_guilds/index.ts

@@ -8,7 +8,7 @@ export default defineAgentTool<Record<string, never>>({
   tags: ['qq'],
   async execute(_input, context) {
     const client = context.$client;
-    const guilds = await client.getGuilds();
+    const guilds = await client.guildService.getList();
     return { guilds, count: guilds.length };
   },
 });

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.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') } : {}),
+        };
+    },
+});