mioku-plugin-admin 2.0.0 → 2.2.0

package/commands/group.ts

@@ -41,6 +41,8 @@ export function registerGroupAdminCommands(ctx: MiokiContext) {
       "/改群名片",
       "/改群昵称",
       "/改群头像",
+      "/撤回",
+      "撤回",
     ].some((prefix) => text.startsWith(prefix));
 
     try {
@@ -479,6 +481,40 @@ export function registerGroupAdminCommands(ctx: MiokiContext) {
         }
         return;
       }
+
+      // 撤回 — 引用一条消息后，bot 撤回该消息
+      if (text === "/撤回" || text === "撤回") {
+        if (!isGroup || !groupId) {
+          return event.reply("这个要在群里用哦～", true);
+        }
+        if (!(await ensureAdminPermission())) return;
+
+        const quotedId = event.quote_id;
+        if (!quotedId) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户希望撤回一条消息，但命令中没有引用具体消息，请提醒用户引用要撤回的消息后输入 /撤回",
+            fallbackMessage: "要撤回哪条消息呀～先引用一下～",
+          });
+          return;
+        }
+
+        try {
+          await bot.api("delete_msg", { message_id: quotedId });
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `撤回消息执行失败：${String(err)}。失败原因通常是Bot没有该消息的撤回权限（需要Bot为群主或管理员，且消息发出不超过2分钟），管理员无法撤回管理员的消息或群主的消息。`,
+            fallbackMessage: `撤回失败啦～可能是没权限或消息超过2分钟了：${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
     } catch (err) {
       ctx.logger.error(`[admin group] 未捕获异常: ${String(err)}`);
       if (!isGroupAdminCommand) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-admin",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "管理插件，提供事件通知与群管/个人管理指令",
   "main": "index.ts",
   "type": "module",
@@ -24,6 +24,96 @@
       "config",
       "ai"
     ],
+    "accessHooks": [
+      {
+        "id": "/改头像",
+        "match": "/^\\/改头像/"
+      },
+      {
+        "id": "/改昵称",
+        "match": "/^\\/改昵称/"
+      },
+      {
+        "id": "/改签名",
+        "match": "/^\\/改签名/"
+      },
+      {
+        "id": "/改性别",
+        "match": "/^\\/改性别/"
+      },
+      {
+        "id": "/改群名片",
+        "match": "/^\\/改群名片/"
+      },
+      {
+        "id": "/改群昵称",
+        "match": "/^\\/改群昵称/"
+      },
+      {
+        "id": "/改群头像",
+        "match": "/^\\/改群头像/"
+      },
+      {
+        "id": "/撤回",
+        "match": "/^(\\/撤回|撤回)/"
+      },
+      {
+        "id": "/改头衔",
+        "match": "/^\\/改头衔/"
+      },
+      {
+        "id": "我要头衔",
+        "match": "/^我要头衔/"
+      },
+      {
+        "id": "/踢",
+        "match": "/^\\/踢/"
+      },
+      {
+        "id": "/禁言",
+        "match": "/^\\/禁言/"
+      },
+      {
+        "id": "/解禁",
+        "match": "/^\\/解禁/"
+      },
+      {
+        "id": "/设管理",
+        "match": "/^\\/设管理/"
+      },
+      {
+        "id": "/全体禁言",
+        "match": "/^\\/全体禁言/"
+      },
+      {
+        "id": "/全体解禁",
+        "match": "/^\\/全体解禁/"
+      },
+      {
+        "id": "/删好友",
+        "match": "/^\\/删好友/"
+      },
+      {
+        "id": "/退群",
+        "match": "/^\\/退群/"
+      },
+      {
+        "id": "/发好友",
+        "match": "/^\\/发好友/"
+      },
+      {
+        "id": "/发群聊",
+        "match": "/^\\/发群聊/"
+      },
+      {
+        "id": "/全部好友",
+        "match": "/^\\/全部好友/"
+      },
+      {
+        "id": "/全部群聊",
+        "match": "/^\\/全部群聊/"
+      }
+    ],
     "help": {
       "title": "管理",
       "description": "Bot管理插件，提供事件通知与管理指令",
@@ -63,6 +153,12 @@
           "desc": "修改群头像",
           "role": "admin"
         },
+        {
+          "cmd": "/撤回",
+          "desc": "撤回别人的消息",
+          "usage": "引用一条消息后输入 /撤回",
+          "role": "admin"
+        },
         {
           "cmd": "/改头衔",
           "desc": "设置群成员专属头衔",

package/skills/group.ts

@@ -56,348 +56,283 @@ async function checkDangerousTargetPermission(
 const groupAdminSkill: AISkill = {
   name: "admin_group",
   description:
-    "群管理工具，提供踢人、禁言、解禁、设管理、全体禁言、改群名、改群头像、设头衔等群管操作",
+    "群管理统一入口。action 决定具体行为：管理成员（踢/禁言/解禁/设管理/设头衔）或管理群（全体禁言/改群名/改Bot群名片/改群头像/撤回消息）。",
   permission: "admin",
   tools: [
     {
-      name: "kick_member",
-      description: "将群成员踢出群聊",
+      name: "manage_member",
+      description:
+        "管理群成员：踢人(kick)、禁言(mute)、解除禁言(unmute)、设为管理员(set_admin)、取消管理员(unset_admin)、设置某成员头衔(set_title)、设置自己头衔(set_self_title)。",
       parameters: {
         type: "object",
         properties: {
-          user_id: { type: "number", description: "要踢出的成员QQ号" },
-        },
-        required: ["user_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        const permissionError = await checkDangerousTargetPermission(
-          runtime,
-          args.user_id,
-        );
-        if (permissionError) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_group.kick_member",
-            permissionError,
-          );
-          return { error: permissionError };
-        }
-        try {
-          await bot.api("set_group_kick", {
-            group_id: groupId,
-            user_id: args.user_id,
-          });
-          return {
-            success: true,
-            message: `已将 ${args.user_id} 移出当前群`,
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.kick_member", err);
-          return { error: `踢人失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "mute_member",
-      description: "禁言群成员，不指定时长时默认10分钟",
-      parameters: {
-        type: "object",
-        properties: {
-          user_id: { type: "number", description: "要禁言的成员QQ号" },
+          action: {
+            type: "string",
+            description: "要执行的动作",
+            enum: [
+              "kick",
+              "mute",
+              "unmute",
+              "set_admin",
+              "unset_admin",
+              "set_title",
+              "set_self_title",
+            ],
+          },
+          user_id: {
+            type: "number",
+            description:
+              "目标成员QQ号。set_self_title 不需要；其他动作必填。",
+          },
           duration: {
             type: "number",
-            description: "禁言时长（秒），不提供或小于等于0时默认600秒",
+            description: "禁言时长（秒），仅 mute 生效；不提供或<=0时默认600秒",
           },
-        },
-        required: ["user_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        const duration =
-          Number(args.duration) > 0 ? Number(args.duration) : 10 * 60;
-        const permissionError = await checkDangerousTargetPermission(
-          runtime,
-          args.user_id,
-        );
-        if (permissionError) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_group.mute_member",
-            permissionError,
-          );
-          return { error: permissionError };
-        }
-        try {
-          await bot.setGroupBan(groupId, args.user_id, duration);
-          return {
-            success: true,
-            message: `已禁言 ${args.user_id} ${duration}秒`,
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.mute_member", err);
-          return { error: `禁言失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "unmute_member",
-      description: "解除群成员禁言",
-      parameters: {
-        type: "object",
-        properties: {
-          user_id: { type: "number", description: "要解禁的成员QQ号" },
-        },
-        required: ["user_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        try {
-          await bot.setGroupBan(groupId, args.user_id, 0);
-          return { success: true, message: `已解除 ${args.user_id} 的禁言` };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.unmute_member", err);
-          return { error: `解禁失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_group_admin",
-      description: "设置或取消群管理员",
-      parameters: {
-        type: "object",
-        properties: {
-          user_id: { type: "number", description: "要设为管理的QQ号" },
-          enable: {
-            type: "boolean",
-            description: "true设为管理，false取消管理",
+          title: {
+            type: "string",
+            description: "头衔内容，仅 set_title / set_self_title 需要",
           },
         },
-        required: ["user_id", "enable"],
+        required: ["action"],
       },
       handler: async (args: any, runtimeCtx?: any) => {
         const runtime = await resolveGroupRuntime(runtimeCtx);
         if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
+        const { bot, selfId, groupId, event } = runtime;
+        const action = String(args?.action || "");
+
         try {
-          await bot.api("set_group_admin", {
-            group_id: groupId,
-            user_id: args.user_id,
-            enable: args.enable,
-          });
-          return {
-            success: true,
-            message: args.enable
-              ? `已将 ${args.user_id} 设为当前群的管理员`
-              : `已取消 ${args.user_id} 在当前群的管理员`,
-          };
+          switch (action) {
+            case "kick": {
+              const userId = Number(args?.user_id);
+              if (!userId) return { error: "kick 需要提供 user_id" };
+              const permErr = await checkDangerousTargetPermission(
+                runtime,
+                userId,
+              );
+              if (permErr) return { error: permErr };
+              await bot.api("set_group_kick", {
+                group_id: groupId,
+                user_id: userId,
+              });
+              return { success: true, message: `已将 ${userId} 移出当前群` };
+            }
+            case "mute": {
+              const userId = Number(args?.user_id);
+              if (!userId) return { error: "mute 需要提供 user_id" };
+              const permErr = await checkDangerousTargetPermission(
+                runtime,
+                userId,
+              );
+              if (permErr) return { error: permErr };
+              const duration =
+                Number(args?.duration) > 0 ? Number(args.duration) : 10 * 60;
+              await bot.setGroupBan(groupId, userId, duration);
+              return {
+                success: true,
+                message: `已禁言 ${userId} ${duration}秒`,
+              };
+            }
+            case "unmute": {
+              const userId = Number(args?.user_id);
+              if (!userId) return { error: "unmute 需要提供 user_id" };
+              await bot.setGroupBan(groupId, userId, 0);
+              return { success: true, message: `已解除 ${userId} 的禁言` };
+            }
+            case "set_admin": {
+              const userId = Number(args?.user_id);
+              if (!userId) return { error: "set_admin 需要提供 user_id" };
+              await bot.api("set_group_admin", {
+                group_id: groupId,
+                user_id: userId,
+                enable: true,
+              });
+              return {
+                success: true,
+                message: `已将 ${userId} 设为当前群的管理员`,
+              };
+            }
+            case "unset_admin": {
+              const userId = Number(args?.user_id);
+              if (!userId) return { error: "unset_admin 需要提供 user_id" };
+              await bot.api("set_group_admin", {
+                group_id: groupId,
+                user_id: userId,
+                enable: false,
+              });
+              return {
+                success: true,
+                message: `已取消 ${userId} 在当前群的管理员`,
+              };
+            }
+            case "set_title": {
+              const userId = Number(args?.user_id);
+              const title = String(args?.title || "").trim();
+              if (!userId || !title) {
+                return { error: "set_title 需要提供 user_id 和 title" };
+              }
+              await (bot as any).setGroupSpecialTitle(groupId, userId, title);
+              return {
+                success: true,
+                message: `已将 ${userId} 的头衔设为 "${title}"`,
+              };
+            }
+            case "set_self_title": {
+              const userId = Number(event?.user_id);
+              if (!userId) return { error: "无法获取当前用户ID" };
+              const title = String(args?.title || "").trim();
+              if (!title) return { error: "set_self_title 需要提供 title" };
+              await (bot as any).setGroupSpecialTitle(groupId, userId, title);
+              return {
+                success: true,
+                message: `已将你的头衔设为 "${title}"`,
+              };
+            }
+            default:
+              return { error: `未知的 action: ${action}` };
+          }
         } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.set_group_admin", err);
-          return { error: `设管理失败: ${err}` };
+          logAdminSkillError(runtimeCtx, `admin_group.manage_member.${action}`, err);
+          return { error: `执行 ${action} 失败: ${err}` };
         }
       },
     },
     {
-      name: "set_group_whole_ban",
-      description: "开启或关闭全体禁言",
+      name: "manage_group",
+      description:
+        "管理群本身或批量撤回消息：开启/关闭全体禁言(set_whole_ban/unset_whole_ban)、改群名(set_group_name)、改Bot在群里的名片(set_self_card)、改群头像(set_group_avatar)、撤回一条或多条消息(recall_messages，需要 message_ids 数组)。",
       parameters: {
         type: "object",
         properties: {
-          enable: {
-            type: "boolean",
-            description: "true开启全体禁言，false关闭",
+          action: {
+            type: "string",
+            description: "要执行的动作",
+            enum: [
+              "set_whole_ban",
+              "unset_whole_ban",
+              "set_group_name",
+              "set_self_card",
+              "set_group_avatar",
+              "recall_messages",
+            ],
+          },
+          group_name: {
+            type: "string",
+            description: "新群名，仅 set_group_name 需要",
+          },
+          card: {
+            type: "string",
+            description: "新的Bot群名片，仅 set_self_card 需要",
           },
-        },
-        required: ["enable"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        try {
-          await bot.api("set_group_whole_ban", {
-            group_id: groupId,
-            enable: args.enable,
-          });
-          return {
-            success: true,
-            message: args.enable
-              ? "当前群已开启全体禁言"
-              : "当前群已关闭全体禁言",
-          };
-        } catch (err) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_group.set_group_whole_ban",
-            err,
-          );
-          return { error: `全体禁言操作失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_group_name",
-      description: "修改群聊名称",
-      parameters: {
-        type: "object",
-        properties: {
-          group_name: { type: "string", description: "新群名" },
-        },
-        required: ["group_name"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        try {
-          await bot.api("set_group_name", {
-            group_id: groupId,
-            group_name: args.group_name,
-          });
-          return {
-            success: true,
-            message: `当前群名称已修改为 ${args.group_name}`,
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.set_group_name", err);
-          return { error: `修改群名失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_group_card",
-      description: "修改Bot在当前群内的群名片",
-      parameters: {
-        type: "object",
-        properties: {
-          card: { type: "string", description: "新的群名片" },
-        },
-        required: ["card"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, selfId, groupId } = runtime;
-        const card = String(args?.card || "").trim();
-        if (!card) return { error: "card 不能为空" };
-        try {
-          await bot.setGroupCard(groupId, selfId, card);
-          return {
-            success: true,
-            message: `Bot在当前群的群名片已修改为 ${card}`,
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.set_group_card", err);
-          return { error: `修改群名片失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_group_avatar",
-      description: "修改群头像",
-      parameters: {
-        type: "object",
-        properties: {
           message_id: {
             type: "number",
-            description: "包含图片的消息 message_id",
+            description:
+              "包含图片的消息 message_id，仅 set_group_avatar 需要",
+          },
+          message_ids: {
+            type: "array",
+            items: { type: "number" },
+            description:
+              "要撤回的消息 message_id 数组，仅 recall_messages 需要。一次调用可批量撤回。",
           },
         },
-        required: ["message_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        const messageId = Number(args?.message_id);
-        if (!Number.isFinite(messageId) || messageId <= 0) {
-          return { error: "请提供有效的 message_id" };
-        }
-        const imageUrl = await getImageUrlByMessageId(bot, messageId);
-        if (!imageUrl) {
-          return { error: "指定 message_id 中未找到图片" };
-        }
-        try {
-          await bot.api("set_group_portrait", {
-            group_id: groupId,
-            file: imageUrl,
-          });
-          return { success: true, message: "当前群头像已修改" };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.set_group_avatar", err);
-          return { error: `修改群头像失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_group_title",
-      description: "设置群成员专属头衔",
-      parameters: {
-        type: "object",
-        properties: {
-          user_id: { type: "number", description: "成员QQ号" },
-          title: { type: "string", description: "新头衔" },
-        },
-        required: ["user_id", "title"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const runtime = await resolveGroupRuntime(runtimeCtx);
-        if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        try {
-          await (bot as any).setGroupSpecialTitle(
-            groupId,
-            args.user_id,
-            args.title,
-          );
-          return {
-            success: true,
-            message: `已将 ${args.user_id} 的头衔设为 "${args.title}"`,
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_group.set_group_title", err);
-          return { error: `设置头衔失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_self_group_title",
-      description: "给当前发起用户设置自己的群专属头衔，不能指定或修改别人",
-      parameters: {
-        type: "object",
-        properties: {
-          title: { type: "string", description: "新头衔" },
-        },
-        required: ["title"],
+        required: ["action"],
       },
       handler: async (args: any, runtimeCtx?: any) => {
         const runtime = await resolveGroupRuntime(runtimeCtx);
         if ("error" in runtime) return { error: runtime.error };
-        const { bot, groupId } = runtime;
-        const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
-        const userId = event?.user_id;
-        if (!userId) return { error: "无法获取当前用户ID" };
-        const title = String(args?.title || "").trim();
-        if (!title) return { error: "title 不能为空" };
+        const { bot, selfId, groupId } = runtime;
+        const action = String(args?.action || "");
+
         try {
-          await (bot as any).setGroupSpecialTitle(groupId, userId, title);
-          return {
-            success: true,
-            message: `已将你的头衔设为 "${title}"`,
-          };
+          switch (action) {
+            case "set_whole_ban":
+              await bot.api("set_group_whole_ban", {
+                group_id: groupId,
+                enable: true,
+              });
+              return { success: true, message: "当前群已开启全体禁言" };
+            case "unset_whole_ban":
+              await bot.api("set_group_whole_ban", {
+                group_id: groupId,
+                enable: false,
+              });
+              return { success: true, message: "当前群已关闭全体禁言" };
+            case "set_group_name": {
+              const groupName = String(args?.group_name || "").trim();
+              if (!groupName) return { error: "set_group_name 需要提供 group_name" };
+              await bot.api("set_group_name", {
+                group_id: groupId,
+                group_name: groupName,
+              });
+              return {
+                success: true,
+                message: `当前群名称已修改为 ${groupName}`,
+              };
+            }
+            case "set_self_card": {
+              const card = String(args?.card || "").trim();
+              if (!card) return { error: "set_self_card 需要提供 card" };
+              await bot.setGroupCard(groupId, selfId, card);
+              return {
+                success: true,
+                message: `Bot在当前群的群名片已修改为 ${card}`,
+              };
+            }
+            case "set_group_avatar": {
+              const messageId = Number(args?.message_id);
+              if (!Number.isFinite(messageId) || messageId <= 0) {
+                return { error: "set_group_avatar 需要提供有效的 message_id" };
+              }
+              const imageUrl = await getImageUrlByMessageId(bot, messageId);
+              if (!imageUrl) {
+                return { error: "指定 message_id 中未找到图片" };
+              }
+              await bot.api("set_group_portrait", {
+                group_id: groupId,
+                file: imageUrl,
+              });
+              return { success: true, message: "当前群头像已修改" };
+            }
+            case "recall_messages": {
+              const ids = Array.isArray(args?.message_ids)
+                ? args.message_ids
+                    .map((v: any) => Number(v))
+                    .filter((n: number) => Number.isFinite(n) && n > 0)
+                : [];
+              if (ids.length === 0) {
+                return { error: "recall_messages 需要提供至少一个 message_id" };
+              }
+              const results: Array<{
+                message_id: number;
+                success: boolean;
+                error?: string;
+              }> = [];
+              for (const id of ids) {
+                try {
+                  await bot.api("delete_msg", { message_id: id });
+                  results.push({ message_id: id, success: true });
+                } catch (err) {
+                  results.push({
+                    message_id: id,
+                    success: false,
+                    error: String(err),
+                  });
+                }
+              }
+              const ok = results.filter((r) => r.success).length;
+              return {
+                success: ok === results.length,
+                message: `共尝试撤回 ${results.length} 条消息，成功 ${ok} 条，失败 ${results.length - ok} 条`,
+                results,
+              };
+            }
+            default:
+              return { error: `未知的 action: ${action}` };
+          }
         } catch (err) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_group.set_self_group_title",
-            err,
-          );
-          return { error: `设置头衔失败: ${err}` };
+          logAdminSkillError(runtimeCtx, `admin_group.manage_group.${action}`, err);
+          return { error: `执行 ${action} 失败: ${err}` };
         }
       },
     },

package/skills/personal.ts

@@ -21,352 +21,202 @@ function logAdminSkillError(runtimeCtx: any, toolName: string, err: unknown) {
 const personalSkill: AISkill = {
   name: "admin_personal",
   description:
-    "个人账号管理工具，提供修改自己头像、昵称、个性签名、性别、发送消息、查看好友/群列表等操作",
+    "Bot个人账号与消息管理统一入口。action 决定行为：修改Bot资料(set_avatar/set_nickname/set_signature/set_gender)、发送消息(send_private/send_group)、获取列表(list_friends/list_groups)、管理关系(delete_friend/leave_group)。",
   permission: "owner",
   tools: [
     {
-      name: "set_bot_avatar",
-      description: "修改Bot头像",
+      name: "manage_personal",
+      description:
+        "Bot个人账号管理：修改头像/昵称/签名/性别、给指定用户或群发消息、查看好友/群列表、删除好友、退群。所有功能通过 action 字段区分。",
       parameters: {
         type: "object",
         properties: {
+          action: {
+            type: "string",
+            description: "要执行的动作",
+            enum: [
+              "set_avatar",
+              "set_nickname",
+              "set_signature",
+              "set_gender",
+              "send_private",
+              "send_group",
+              "list_friends",
+              "list_groups",
+              "delete_friend",
+              "leave_group",
+            ],
+          },
           message_id: {
             type: "number",
-            description: "包含图片的消息 message_id",
+            description: "包含图片的消息 message_id，仅 set_avatar 需要",
+          },
+          nickname: {
+            type: "string",
+            description: "新昵称，仅 set_nickname 需要",
+          },
+          personal_note: {
+            type: "string",
+            description: "新个性签名，仅 set_signature 需要",
           },
-        },
-        required: ["message_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        const messageId = Number(args?.message_id);
-        if (!Number.isFinite(messageId) || messageId <= 0) {
-          return { error: "请提供有效的 message_id" };
-        }
-        const imageUrl = await getImageUrlByMessageId(bot, messageId);
-        if (!imageUrl) {
-          return { error: "指定 message_id 中未找到图片" };
-        }
-        try {
-          await bot.api("set_qq_avatar", { file: imageUrl });
-          return { success: true, message: "Bot头像已修改" };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_personal.set_bot_avatar", err);
-          return { error: `修改头像失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_bot_nickname",
-      description: "修改Bot昵称",
-      parameters: {
-        type: "object",
-        properties: { nickname: { type: "string", description: "新昵称" } },
-        required: ["nickname"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          await bot.api("set_qq_profile", {
-            nickname: String(args.nickname || "").trim(),
-          });
-          return {
-            success: true,
-            message: `Bot昵称已修改为: ${args.nickname}`,
-          };
-        } catch (err) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_personal.set_bot_nickname",
-            err,
-          );
-          return { error: `修改昵称失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_bot_signature",
-      description: "修改Bot个性签名",
-      parameters: {
-        type: "object",
-        properties: {
-          personal_note: { type: "string", description: "新个性签名" },
-        },
-        required: ["personal_note"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        const personalNote = String(args?.personal_note || "").trim();
-        if (!personalNote) return { error: "personal_note 不能为空" };
-        try {
-          await bot.api("set_qq_profile", { personal_note: personalNote });
-          return { success: true, message: "Bot个性签名已修改" };
-        } catch (err) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_personal.set_bot_signature",
-            err,
-          );
-          return { error: `修改个性签名失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "set_bot_gender",
-      description: "修改Bot性别",
-      parameters: {
-        type: "object",
-        properties: {
           gender: {
             type: "string",
-            description: "性别：男/女/无 或 male/female/unknown",
-            enum: [
-              "male",
-              "female",
-              "unknown",
-              "男",
-              "女",
-              "无",
-              "0",
-              "1",
-              "2",
-            ],
+            description:
+              "性别：男/女/无 或 male/female/unknown 或 1/2/0，仅 set_gender 需要",
+          },
+          user_id: {
+            type: "number",
+            description:
+              "目标QQ号。send_private / delete_friend 需要。",
+          },
+          group_id: {
+            type: "number",
+            description: "目标群号。send_group / leave_group 需要。",
+          },
+          content: {
+            type: "string",
+            description: "消息内容。send_private / send_group 需要。",
           },
         },
-        required: ["gender"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          const sex = parseProfileSex(args.gender);
-          await bot.api("set_qq_profile", { sex });
-          const genderMap: Record<number, string> = {
-            0: "无",
-            1: "男",
-            2: "女",
-          };
-          return {
-            success: true,
-            message: `Bot性别已修改为: ${genderMap[sex]}`,
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_personal.set_bot_gender", err);
-          return { error: `修改性别失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "send_private_message",
-      description: "给指定QQ号发送私聊消息",
-      parameters: {
-        type: "object",
-        properties: {
-          user_id: { type: "number", description: "目标QQ号" },
-          content: { type: "string", description: "消息内容" },
-        },
-        required: ["user_id", "content"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          await bot.sendPrivateMsg(args.user_id, [
-            ctx.segment.text(args.content),
-          ]);
-          return { success: true, message: `已发送私聊消息给 ${args.user_id}` };
-        } catch (err) {
-          logAdminSkillError(
-            runtimeCtx,
-            "admin_personal.send_private_message",
-            err,
-          );
-          return { error: `发送私聊失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "send_group_message",
-      description: "给指定群发送消息",
-      parameters: {
-        type: "object",
-        properties: {
-          group_id: { type: "number", description: "目标群号" },
-          content: { type: "string", description: "消息内容" },
-        },
-        required: ["group_id", "content"],
+        required: ["action"],
       },
       handler: async (args: any, runtimeCtx?: any) => {
         const ctx = runtimeCtx?.ctx;
         if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
+        const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
+        const selfId = event?.self_id;
         if (!selfId) return { error: "无法获取Bot ID" };
         const bot = ctx.pickBot(selfId);
         if (!bot) return { error: "Bot不可用" };
+        const action = String(args?.action || "");
+
         try {
-          await bot.sendGroupMsg(args.group_id, [
-            ctx.segment.text(args.content),
-          ]);
-          return { success: true, message: `已发送群消息到 ${args.group_id}` };
+          switch (action) {
+            case "set_avatar": {
+              const messageId = Number(args?.message_id);
+              if (!Number.isFinite(messageId) || messageId <= 0) {
+                return { error: "set_avatar 需要提供有效的 message_id" };
+              }
+              const imageUrl = await getImageUrlByMessageId(bot, messageId);
+              if (!imageUrl) {
+                return { error: "指定 message_id 中未找到图片" };
+              }
+              await bot.api("set_qq_avatar", { file: imageUrl });
+              return { success: true, message: "Bot头像已修改" };
+            }
+            case "set_nickname": {
+              const nickname = String(args?.nickname || "").trim();
+              if (!nickname) {
+                return { error: "set_nickname 需要提供 nickname" };
+              }
+              await bot.api("set_qq_profile", { nickname });
+              return {
+                success: true,
+                message: `Bot昵称已修改为: ${nickname}`,
+              };
+            }
+            case "set_signature": {
+              const personalNote = String(args?.personal_note || "").trim();
+              if (!personalNote) {
+                return { error: "set_signature 需要提供 personal_note" };
+              }
+              await bot.api("set_qq_profile", { personal_note: personalNote });
+              return { success: true, message: "Bot个性签名已修改" };
+            }
+            case "set_gender": {
+              const sex = parseProfileSex(args?.gender);
+              await bot.api("set_qq_profile", { sex });
+              const genderMap: Record<number, string> = {
+                0: "无",
+                1: "男",
+                2: "女",
+              };
+              return {
+                success: true,
+                message: `Bot性别已修改为: ${genderMap[sex]}`,
+              };
+            }
+            case "send_private": {
+              const userId = Number(args?.user_id);
+              const content = String(args?.content || "");
+              if (!userId || !content) {
+                return { error: "send_private 需要提供 user_id 和 content" };
+              }
+              await bot.sendPrivateMsg(userId, [ctx.segment.text(content)]);
+              return {
+                success: true,
+                message: `已发送私聊消息给 ${userId}`,
+              };
+            }
+            case "send_group": {
+              const groupId = Number(args?.group_id);
+              const content = String(args?.content || "");
+              if (!groupId || !content) {
+                return { error: "send_group 需要提供 group_id 和 content" };
+              }
+              await bot.sendGroupMsg(groupId, [ctx.segment.text(content)]);
+              return {
+                success: true,
+                message: `已发送群消息到 ${groupId}`,
+              };
+            }
+            case "list_friends": {
+              if (event?.message_type === "group") {
+                return { error: "在私聊使用试试看吧～" };
+              }
+              const friendList: any[] = await bot.api("get_friend_list");
+              if (!Array.isArray(friendList)) return { friends: [] };
+              return {
+                friends: friendList.map((f) => ({
+                  user_id: f.user_id,
+                  nickname: f.nickname,
+                  remark: f.remark,
+                })),
+              };
+            }
+            case "list_groups": {
+              if (event?.message_type === "group") {
+                return { error: "在私聊使用试试看吧～" };
+              }
+              const groupList: any[] = await bot.api("get_group_list");
+              if (!Array.isArray(groupList)) return { groups: [] };
+              return {
+                groups: groupList.map((g) => ({
+                  group_id: g.group_id,
+                  group_name: g.group_name,
+                  member_count: g.member_count,
+                })),
+              };
+            }
+            case "delete_friend": {
+              const userId = Number(args?.user_id);
+              if (!userId) {
+                return { error: "delete_friend 需要提供 user_id" };
+              }
+              await bot.api("delete_friend", { user_id: userId });
+              return { success: true, message: `已删除好友 ${userId}` };
+            }
+            case "leave_group": {
+              const groupId = Number(args?.group_id);
+              if (!groupId) {
+                return { error: "leave_group 需要提供 group_id" };
+              }
+              await bot.api("set_group_leave", {
+                group_id: groupId,
+                is_dismiss: false,
+              });
+              return { success: true, message: `已退出群 ${groupId}` };
+            }
+            default:
+              return { error: `未知的 action: ${action}` };
+          }
         } catch (err) {
           logAdminSkillError(
             runtimeCtx,
-            "admin_personal.send_group_message",
+            `admin_personal.manage_personal.${action}`,
             err,
           );
-          return { error: `发送群消息失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "get_friend_list",
-      description:
-        "获取Bot的全部好友列表，对应/全部好友命令，仅适合在私聊场景调用",
-      parameters: { type: "object", properties: {}, required: [] },
-      handler: async (_args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
-        if (event?.message_type === "group") {
-          return { error: "在私聊使用试试看吧～" };
-        }
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          const friendList: any[] = await bot.api("get_friend_list");
-          if (!Array.isArray(friendList)) return { friends: [] };
-          return {
-            friends: friendList.map((f) => ({
-              user_id: f.user_id,
-              nickname: f.nickname,
-              remark: f.remark,
-            })),
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_personal.get_friend_list", err);
-          return { error: `获取好友列表失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "get_group_list",
-      description:
-        "获取Bot的全部群聊列表，对应/全部群聊命令，仅适合在私聊场景调用",
-      parameters: { type: "object", properties: {}, required: [] },
-      handler: async (_args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const event = runtimeCtx?.event || runtimeCtx?.rawEvent;
-        if (event?.message_type === "group") {
-          return { error: "在私聊使用试试看吧～" };
-        }
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          const groupList: any[] = await bot.api("get_group_list");
-          if (!Array.isArray(groupList)) return { groups: [] };
-          return {
-            groups: groupList.map((g) => ({
-              group_id: g.group_id,
-              group_name: g.group_name,
-              member_count: g.member_count,
-            })),
-          };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_personal.get_group_list", err);
-          return { error: `获取群聊列表失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "delete_friend",
-      description: "删除好友",
-      parameters: {
-        type: "object",
-        properties: {
-          user_id: { type: "number", description: "要删除的好友QQ号" },
-        },
-        required: ["user_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          await bot.api("delete_friend", { user_id: args.user_id });
-          return { success: true, message: `已删除好友 ${args.user_id}` };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_personal.delete_friend", err);
-          return { error: `删除好友失败: ${err}` };
-        }
-      },
-    },
-    {
-      name: "leave_group",
-      description: "退出群聊",
-      parameters: {
-        type: "object",
-        properties: {
-          group_id: { type: "number", description: "要退出的群号" },
-        },
-        required: ["group_id"],
-      },
-      handler: async (args: any, runtimeCtx?: any) => {
-        const ctx = runtimeCtx?.ctx;
-        if (!ctx) return { error: "无法获取上下文" };
-        const selfId =
-          runtimeCtx?.event?.self_id || runtimeCtx?.rawEvent?.self_id;
-        if (!selfId) return { error: "无法获取Bot ID" };
-        const bot = ctx.pickBot(selfId);
-        if (!bot) return { error: "Bot不可用" };
-        try {
-          await bot.api("set_group_leave", {
-            group_id: args.group_id,
-            is_dismiss: false,
-          });
-          return { success: true, message: `已退出群 ${args.group_id}` };
-        } catch (err) {
-          logAdminSkillError(runtimeCtx, "admin_personal.leave_group", err);
-          return { error: `退群失败: ${err}` };
+          return { error: `执行 ${action} 失败: ${err}` };
         }
       },
     },