mioku-plugin-admin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mioku Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# Admin Plugin
+
+Mioku 的管理插件，提供事件通知与 Bot 管理指令。
+
+## 功能
+
+- **事件通知**：好友消息、好友申请、群邀请、Bot 被禁言时自动通知主人
+- **个人管理**：修改 Bot 头像、昵称、个性签名、性别，发送消息，查看好友/群列表等
+- **群管理**：踢人、禁言、解禁、设管理、全体禁言、改头衔等群管操作
+- **AI 技能**：支持 AI 调用个人管理工具（owner 权限）和群管理工具（admin 权限）
+- **WebUI 配置**：可视化配置通知开关
+
+## 安装
+
+将 `admin` 文件夹放入 Mioku 的 `plugins/` 目录即可
+
+## 配置
+
+配置文件位于 `config/admin/base.json`，也可通过 WebUI 管理。
+
+| 配置项                   | 类型       | 默认值  | 说明                 |
+|-----------------------|----------|------|--------------------|
+| `notifyTarget`        | number[] | []   | 通知目标 QQ 号，空则通知全部主人 |
+| `notifyFriendMsg`     | boolean  | true | 好友私聊消息通知           |
+| `notifyFriendRequest` | boolean  | true | 好友申请通知             |
+| `notifyGroupInvite`   | boolean  | true | 群邀请通知              |
+| `notifyGroupBan`      | boolean  | true | Bot 被禁言通知          |
+| `notifyGroupUnban`    | boolean  | true | Bot 被解除禁言通知        |
+| `notifyGroupKick`     | boolean  | true | Bot 被踢出群聊通知        |
+
+## 事件通知
+
+当配置开启后，以下事件会通过私聊通知主人：
+
+- **好友消息**：`[好友消息] 昵称(QQ号): 内容`
+- **好友申请**：`[好友申请] QQ号 验证消息: xxx`，回复「通过」即可同意
+- **群邀请**：`[群邀请] 群号 邀请人QQ号`，回复「通过」即可同意
+- **Bot 被禁言**：`[Bot被禁言] 群号 操作人 时长`
+- **Bot 被踢**：`[Bot被踢] 群号 操作者QQ 类型`
+
+通知由触发事件的 Bot 发送，多 Bot 实例时不会重复通知。
+
+## 指令
+
+除特别说明外，管理指令需要使用 `/` 前缀。
+
+### 主人指令
+
+| 指令    | 用法            | 说明                     |
+|-------|---------------|------------------------|
+| /改头像  | `/改头像 [图片]`   | 修改 Bot 头像，发送图片或引用图片    |
+| /改昵称  | `/改昵称 昵称`     | 修改 Bot 昵称              |
+| /改签名  | `/改签名 签名内容`   | 修改 Bot 个性签名            |
+| /改性别  | `/改性别 男/女/无`  | 修改 Bot 性别              |
+| 改群名片  | `/改群名片 名片`    | 修改 Bot 群名片（群聊中使用）      |
+| /改群昵称 | `/改群昵称 昵称`    | 同改群名片                  |
+| /改群头像 | `/改群头像 [图片]`  | 修改群头像（群聊中使用）           |
+| /删好友  | `/删好友 QQ号`    | 删除好友                   |
+| /退群   | `/退群 群号`      | 退出指定群聊                 |
+| /发好友  | `/发好友 QQ号 内容` | 给好友发送私聊消息              |
+| /发群聊  | `/发群聊 群号 内容`  | 给群聊发送消息                |
+| /全部好友 | `/全部好友`       | 获取全部好友列表（仅私聊，转发消息，含头像） |
+| /全部群聊 | `/全部群聊`       | 获取全部群聊列表（仅私聊，转发消息，含头像） |
+
+### 群管指令
+
+以下指令在群聊中使用，需要发送者为群主、群管理或主人。
+
+| 指令    | 用法            | 说明                     |
+|-------|---------------|------------------------|
+| 改头衔   | `/改头衔 @人 头衔`  | 设置群成员头衔（需 Bot 为群主）     |
+| 我要头衔  | `我要头衔 头衔`     | 普通群员给自己设置头衔（需 Bot 为群主） |
+| 踢     | `/踢 @人`       | 踢出群成员                  |
+| 禁言    | `/禁言 @人 10分钟` | 禁言成员，支持分钟/小时/天         |
+| 解禁    | `/解禁 @人`      | 解除禁言                   |
+| 设管理   | `/设管理 @人`     | 设置群管理员（需 Bot 为群主）      |
+| /全体禁言 | `/全体禁言`       | 开启全体禁言                 |
+| /全体解禁 | `/全体解禁`       | 关闭全体禁言                 |

package/commands/group.ts

@@ -0,0 +1,457 @@
+import type { MiokiContext } from "mioki";
+import {
+  extractImageUrl,
+  getAtUserId,
+  getMemberRole,
+  parseDuration,
+} from "../config";
+import { replyAdminErrorNotice } from "./notice";
+
+function formatGroupRole(role: string): string {
+  if (role === "owner") return "群主";
+  if (role === "admin") return "管理员";
+  return "群成员";
+}
+
+export function registerGroupAdminCommands(ctx: MiokiContext) {
+  ctx.handle("message", async (event: any) => {
+    const text = ctx.text(event)?.trim();
+    if (!text) return;
+    if (event.user_id === event.self_id) return;
+
+    const isGroupAdminCommand = [
+      "改头衔",
+      "/改头衔",
+      "我要头衔",
+      "踢",
+      "/踢",
+      "禁言",
+      "/禁言",
+      "解禁",
+      "/解禁",
+      "设管理",
+      "/设管理",
+      "/全体禁言",
+      "/全体解禁",
+      "改群名片",
+      "/改群名片",
+      "/改群昵称",
+      "/改群头像",
+    ].some((prefix) => text.startsWith(prefix));
+
+    try {
+      const selfId = event.self_id;
+      const bot = ctx.pickBot(selfId);
+      if (!bot) return;
+
+      const isGroup = event.message_type === "group";
+      const groupId: number | undefined = isGroup ? event.group_id : undefined;
+      if (!isGroup || !groupId) return;
+
+      const isMaster = ctx.isOwner?.(event) ?? false;
+      const senderRole = await getMemberRole(bot, groupId, event.user_id);
+      const hasAdminPermission =
+        isMaster || senderRole === "owner" || senderRole === "admin";
+
+      const replyDone = async () => {
+        await event.reply("done");
+      };
+      const ensureAdminPermission = async (instruction?: string) => {
+        if (hasAdminPermission) return true;
+        await replyAdminErrorNotice({
+          ctx,
+          event,
+          instruction:
+            instruction ||
+            "用户想让你执行群管操作但用户不是群主或管理员，无权限让操作",
+          fallbackMessage: "你得是群主或管理员才行哦～",
+        });
+        return false;
+      };
+      const ensureDangerousTargetPermission = async (
+        targetUserId: number,
+        actionName: string,
+      ) => {
+        const targetRole = await getMemberRole(bot, groupId, targetUserId);
+        if (senderRole !== targetRole) return true;
+
+        await replyAdminErrorNotice({
+          ctx,
+          event,
+          instruction: `用户想${actionName}目标成员，但操作人与被操作人群身份相同，均为${formatGroupRole(senderRole)}，群管危险操作无权操作同等级成员。请明确告诉用户无权操作同级成员。`,
+          fallbackMessage: "无权操作同级成员哦～",
+        });
+        return false;
+      };
+
+      // 普通群员只能给自己设置头衔。
+      if (text.startsWith("我要头衔")) {
+        const atUser = getAtUserId(event.message);
+        if (atUser && atUser !== event.user_id) {
+          await event.reply("管好自己呗～", true);
+          return;
+        }
+
+        const title = text.replace(/^我要头衔\s*/, "").trim();
+        if (!title) {
+          await event.reply("想要什么头衔呀～", true);
+          return;
+        }
+
+        try {
+          await (bot as any).setGroupSpecialTitle(
+            groupId,
+            event.user_id,
+            title,
+          );
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `为用户设置个人头衔执行失败：${String(err)}，请简要说明失败并建议稍后重试`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      // 改头衔
+      if (text.startsWith("改头衔") || text.startsWith("/改头衔")) {
+        if (!(await ensureAdminPermission())) return;
+
+        const rest = text.replace(/^\/?改头衔\s*/, "").trim();
+        const atUser = getAtUserId(event.message);
+        let targetUser: number | undefined = atUser;
+        let title: string;
+
+        if (atUser) {
+          title = rest.replace(/@\d+\s*/, "").trim();
+        } else {
+          const parts = rest.split(/\s+/);
+          if (parts.length < 2) {
+            await replyAdminErrorNotice({
+              ctx,
+              event,
+              instruction:
+                "用户在让你修改别人的头衔时缺少参数，请提示用户命令后需要加qq号或@人",
+              fallbackMessage: "想改谁的头衔呀～",
+            });
+            return;
+          }
+          targetUser = parseInt(parts[0], 10);
+          title = parts.slice(1).join(" ");
+        }
+
+        if (!targetUser || !title) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户触发改头衔时参数无效，请提示用户命令后需要加qq号或@人",
+            fallbackMessage: "想改谁的头衔呀～",
+          });
+          return;
+        }
+
+        try {
+          await (bot as any).setGroupSpecialTitle(groupId, targetUser, title);
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `改头衔执行失败： ${String(err)}，请简要说明失败并建议稍后重试`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      // 踢
+      if (text.startsWith("踢") || text.startsWith("/踢")) {
+        if (!(await ensureAdminPermission())) return;
+        const atUser = getAtUserId(event.message);
+        if (!atUser) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户希望从群聊中踢出一个人，请提醒要在命令后@要踢出的人",
+            fallbackMessage: "你想踢掉谁呀～",
+          });
+          return;
+        }
+        if (!(await ensureDangerousTargetPermission(atUser, "踢出"))) return;
+        try {
+          await bot.api("set_group_kick", {
+            group_id: groupId,
+            user_id: atUser,
+          });
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `踢执行失败${String(err)}，请简要说明失败`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (
+        text.startsWith("禁言") ||
+        text.startsWith("/禁言") ||
+        text.startsWith("/禁") ||
+        text.startsWith("禁")
+      ) {
+        if (!(await ensureAdminPermission())) return;
+        const atUser = getAtUserId(event.message);
+        if (!atUser) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户希望禁言一个人，但是没有目标，请提醒要在命令后@要禁言的人",
+            fallbackMessage: "想把谁关小黑屋呀～",
+          });
+          return;
+        }
+        if (!(await ensureDangerousTargetPermission(atUser, "禁言"))) return;
+        const rest = text.replace(/^\/?禁言\s*/, "").trim();
+        const durationStr = rest.replace(/@\d+\s*/, "").trim();
+        const durationSec = parseDuration(durationStr) || 10 * 60;
+        try {
+          await bot.setGroupBan(groupId, atUser, durationSec);
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `禁言执行失败：${String(err)}，请简要说明失败并建议稍后重试`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (
+        text.startsWith("解禁") ||
+        text.startsWith("/解禁") ||
+        text.startsWith("/解") ||
+        text.startsWith("解")
+      ) {
+        if (!(await ensureAdminPermission())) return;
+        const atUser = getAtUserId(event.message);
+        if (!atUser) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户想让你解除一个人的禁言，请提醒要在命令后@要解禁的人",
+            fallbackMessage: "你想拉谁出来呀～",
+          });
+          return;
+        }
+        try {
+          await bot.setGroupBan(groupId, atUser, 0);
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `解禁执行失败：${String(err)}，请简要说明失败`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (text.startsWith("设管理") || text.startsWith("/设管理")) {
+        if (!(await ensureAdminPermission())) return;
+        const atUser = getAtUserId(event.message);
+        if (!atUser) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户希望你把一个人设置成群管理员，但是没有目标，请提醒要在命令后@要设为管理的人",
+            fallbackMessage: "你想给谁管理呀～",
+          });
+          return;
+        }
+        try {
+          await bot.api("set_group_admin", {
+            group_id: groupId,
+            user_id: atUser,
+            enable: true,
+          });
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `设管理执行失败：${String(err)}，请简要说明失败`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (text === "/全体禁言") {
+        if (!(await ensureAdminPermission())) return;
+        try {
+          await bot.api("set_group_whole_ban", {
+            group_id: groupId,
+            enable: true,
+          });
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `全体禁言执行失败：${String(err)}，请简要说明失败`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (text === "/全体解禁") {
+        if (!(await ensureAdminPermission())) return;
+        try {
+          await bot.api("set_group_whole_ban", {
+            group_id: groupId,
+            enable: false,
+          });
+          await replyDone();
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `全体解禁执行失败：${String(err)}，请简要说明失败`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (text.startsWith("改群名片") || text.startsWith("/改群名片")) {
+        if (!isGroup || !groupId) {
+          return event.reply("这个要在群里用哦～", true);
+        }
+        if (!(await ensureAdminPermission())) return;
+        const card = text.replace(/^\/?改群名片\s*/, "").trim();
+        if (!card) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: "用户希望修改你在群里的昵称，但是没有指定名称。",
+            fallbackMessage: "名片内容呢～",
+          });
+          return;
+        }
+        try {
+          await bot.setGroupCard(groupId, selfId, card);
+          await event.reply("done");
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `改群名片执行失败，${String(err)}`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (text.startsWith("/改群昵称")) {
+        if (!isGroup || !groupId) {
+          return event.reply("这个要在群里用哦～", true);
+        }
+        if (!(await ensureAdminPermission())) return;
+        const groupName = text.replace(/^\/改群昵称\s*/, "").trim();
+        if (!groupName) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户希望修改群聊的名称，但是没有告诉你新的名称是啥，请提醒输入群聊名称",
+            fallbackMessage: "群名想改成什么呀～",
+          });
+          return;
+        }
+        try {
+          await bot.api("set_group_name", {
+            group_id: groupId,
+            group_name: groupName,
+          });
+          await event.reply("done");
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `改群昵称执行失败${String(err)}`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+
+      if (text.startsWith("/改群头像")) {
+        if (!isGroup || !groupId) {
+          return event.reply("这个要在群里用哦～", true);
+        }
+        if (!(await ensureAdminPermission())) return;
+        const imageUrl = extractImageUrl(event.message);
+        if (!imageUrl) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户希望修改群聊的群头像，但是没有发你图片，请提醒附带图片或引用图片。",
+            fallbackMessage: "图片呢图片呢～",
+          });
+          return;
+        }
+        try {
+          await bot.api("set_group_portrait", {
+            group_id: groupId,
+            file: imageUrl,
+          });
+          await event.reply("done");
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `改群头像执行失败 ${String(err)}`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+    } catch (err) {
+      ctx.logger.error(`[admin group] 未捕获异常: ${String(err)}`);
+      if (!isGroupAdminCommand) return;
+      await replyAdminErrorNotice({
+        ctx,
+        event,
+        instruction: `群管理指令执行时发生未捕获异常：${String(err)}，请简要说明失败并建议稍后重试`,
+        fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+        error: err,
+      });
+    }
+  });
+}

package/commands/notice.ts

@@ -0,0 +1,60 @@
+import type { AIService } from "../../../src/services/ai/types";
+import type { MiokiContext } from "mioki";
+
+function normalizeErrorMessage(error: unknown): string {
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+export async function replyAdminErrorNotice(options: {
+  ctx: MiokiContext;
+  event: any;
+  instruction: string;
+  fallbackMessage: string;
+  error?: unknown;
+}): Promise<void> {
+  if (options.error != null) {
+    options.ctx.logger.error(
+      `[admin] ${options.instruction}\n执行错误: ${normalizeErrorMessage(options.error)}`,
+    );
+  }
+
+  const aiService = options.ctx.services?.ai as AIService | undefined;
+  const chatRuntime = aiService?.getChatRuntime();
+  if (chatRuntime) {
+    try {
+      const instructionLines = [options.instruction];
+      if (options.error != null) {
+        instructionLines.push(
+          `执行错误: ${normalizeErrorMessage(options.error)}`,
+        );
+      }
+      await chatRuntime.generateNotice({
+        event: options.event,
+        instruction: instructionLines.join("\n"),
+        send: true,
+        promptInjections: [
+            {
+              title: "Admin Plugin Notice",
+              content:
+                "An admin-related action was triggered. Judge whether the user likely intended this action or triggered it accidentally. If it looks accidental or like a casual mention, weave a natural reply into the conversation without mentioning the plugin, tools, or commands. If the user seems to want this feature, respond helpfully.",
+            },
+          ],
+      });
+      return;
+    } catch (noticeError) {
+      options.ctx.logger.error(`admin error notice failed: ${noticeError}`);
+    }
+  }
+
+  await options.event.reply(options.fallbackMessage, true);
+}