mioku-plugin-admin 2.2.3 → 2.3.0

package/README.md

@@ -76,3 +76,8 @@ Mioku 的管理插件，提供事件通知与 Bot 管理指令。
 | 设管理   | `/设管理 @人`     | 设置群管理员（需 Bot 为群主）      |
 | /全体禁言 | `/全体禁言`       | 开启全体禁言                 |
 | /全体解禁 | `/全体解禁`       | 关闭全体禁言                 |
+| /开启验证 | `/开启验证` 或 `#开启验证` | 开启本群入群验证（需 Bot 为群主或管理员） |
+| /关闭验证 | `/关闭验证` 或 `#关闭验证` | 关闭本群入群验证               |
+| /切换验证模式 | `/切换验证模式 回应/数字/手性碳` | 切换验证模式，默认回应           |
+| /绕过验证 | `/绕过验证 @新成员` | 跳过该成员验证直接走欢迎流程        |
+| /重新验证 | `/重新验证 @成员` | 让指定成员重新进行入群验证（不能针对群主/管理/主人） |

package/commands/verify.ts

@@ -0,0 +1,253 @@
+import type { MiokiContext } from "mioki";
+import { getAtUserId, getMemberRole } from "../config";
+import {
+  getGroupVerifyConfig,
+  normalizeVerifyMode,
+  upsertGroupVerifyConfig,
+  type VerifyConfig,
+} from "../verify/config";
+import { replyAdminErrorNotice } from "./notice";
+import type { VerifyController } from "../verify/types";
+
+export interface VerifyCommandOptions {
+  ctx: MiokiContext;
+  getVerifyConfig: () => VerifyConfig;
+  setVerifyConfig: (next: VerifyConfig) => Promise<void>;
+  verifyController: VerifyController;
+}
+
+const VERIFY_MODE_LABELS: Record<string, string> = {
+  reaction: "回应",
+  number: "数字",
+  chiral: "手性碳",
+};
+
+export function registerVerifyCommands(options: VerifyCommandOptions) {
+  const { ctx, getVerifyConfig, setVerifyConfig, verifyController } = options;
+
+  ctx.handle("message", async (event: any) => {
+    const text = ctx.text(event)?.trim();
+    if (!text) return;
+    if (event.user_id === event.self_id) return;
+
+    if (event.message_type !== "group") return;
+    const groupId = Number(event.group_id || 0);
+    if (!groupId) return;
+
+    const isVerifyCommand =
+      text === "/开启验证" ||
+      text === "#开启验证" ||
+      text === "/关闭验证" ||
+      text === "#关闭验证" ||
+      text.startsWith("/切换验证模式") ||
+      text.startsWith("#切换验证模式") ||
+      text.startsWith("/绕过验证") ||
+      text.startsWith("#绕过验证") ||
+      text.startsWith("/重新验证") ||
+      text.startsWith("#重新验证");
+
+    try {
+      const selfId = event.self_id;
+      const bot = ctx.pickBot(selfId);
+      if (!bot) return;
+
+      const isMaster = ctx.isOwner?.(event) ?? false;
+      const senderRole = await getMemberRole(bot, groupId, event.user_id);
+      const hasAdminPermission =
+        isMaster || senderRole === "owner" || senderRole === "admin";
+
+      const ensureAdminPermission = async (instruction?: string) => {
+        if (hasAdminPermission) return true;
+        await replyAdminErrorNotice({
+          ctx,
+          event,
+          instruction:
+            instruction ||
+            "用户想使用入群验证相关指令，但不是群主或管理员，无权限。请告诉用户需要管理权限。",
+          fallbackMessage: "你得是群主或管理员才行哦～",
+        });
+        return false;
+      };
+
+      const groupName =
+        String(event?.group?.group_name || "").trim() || String(groupId);
+
+      // /开启验证 | #开启验证
+      if (text === "/开启验证" || text === "#开启验证") {
+        if (!(await ensureAdminPermission())) return;
+
+        const botRole = await getMemberRole(bot, groupId, selfId);
+        if (botRole !== "owner" && botRole !== "admin") {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户想开启入群验证，但Bot在群内不是群主或管理员，无法执行撤回/踢人等验证操作。请告诉用户需要先把Bot设为群主或管理员。",
+            fallbackMessage: "我得是群主或管理员才能开验证哦～",
+          });
+          return;
+        }
+
+        const current = getVerifyConfig();
+        const groupCfg = getGroupVerifyConfig(current, groupId);
+        if (groupCfg.enabled) {
+          await event.reply("本群已经开启验证啦～", true);
+          return;
+        }
+        const next = upsertGroupVerifyConfig(current, groupId, {
+          enabled: true,
+        });
+        await setVerifyConfig(next);
+        await event.reply("已开启入群验证～", true);
+        return;
+      }
+
+      // /关闭验证 | #关闭验证
+      if (text === "/关闭验证" || text === "#关闭验证") {
+        if (!(await ensureAdminPermission())) return;
+
+        const current = getVerifyConfig();
+        const groupCfg = getGroupVerifyConfig(current, groupId);
+        if (!groupCfg.enabled) {
+          await event.reply("本群还没开启验证哦～", true);
+          return;
+        }
+        const next = upsertGroupVerifyConfig(current, groupId, {
+          enabled: false,
+        });
+        await setVerifyConfig(next);
+        await event.reply("已关闭入群验证～", true);
+        return;
+      }
+
+      // /切换验证模式 回应|数字|手性碳
+      if (
+        text.startsWith("/切换验证模式") ||
+        text.startsWith("#切换验证模式")
+      ) {
+        if (!(await ensureAdminPermission())) return;
+
+        const arg = text
+          .replace(/^[/#]切换验证模式\s*/, "")
+          .trim() as string;
+        const mode = normalizeVerifyMode(arg);
+        if (!arg) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户想切换验证模式但没指定模式。请告诉用户可用模式：回应、数字、手性碳，用法：/切换验证模式 回应。",
+            fallbackMessage: "想切换成哪种模式呀～回应/数字/手性碳",
+          });
+          return;
+        }
+
+        const current = getVerifyConfig();
+        const next = upsertGroupVerifyConfig(current, groupId, { mode });
+        await setVerifyConfig(next);
+        await event.reply(
+          `验证模式已切换为：${VERIFY_MODE_LABELS[mode]}～`,
+          true,
+        );
+        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 verifyController.bypassVerification({
+            selfId,
+            groupId,
+            userId: atUser,
+            groupName,
+          });
+          await event.reply("done");
+        } 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;
+        }
+
+        const isTargetMaster = ctx.isOwner?.(atUser) ?? false;
+        const targetRole = await getMemberRole(bot, groupId, atUser);
+        if (isTargetMaster || targetRole === "owner" || targetRole === "admin") {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction:
+              "用户想让一位群主/管理员/主人重新验证，但这些成员无需验证。请告诉用户该成员是管理/群主或主人，不能对其重新验证。",
+            fallbackMessage: "管理/群主或主人可不用验证哦～",
+          });
+          return;
+        }
+
+        try {
+          const started = await verifyController.restartVerification({
+            selfId,
+            groupId,
+            userId: atUser,
+            groupName,
+          });
+          if (!started) {
+            await event.reply("本群还没开启验证哦～", true);
+          }
+        } catch (err) {
+          await replyAdminErrorNotice({
+            ctx,
+            event,
+            instruction: `重新验证执行失败：${String(err)}，请简要说明失败并建议稍后重试。`,
+            fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+            error: err,
+          });
+        }
+        return;
+      }
+    } catch (err) {
+      ctx.logger.error(`[admin verify] 未捕获异常: ${String(err)}`);
+      if (!isVerifyCommand) return;
+      await replyAdminErrorNotice({
+        ctx,
+        event,
+        instruction: `入群验证指令执行时发生未捕获异常：${String(err)}，请简要说明失败并建议稍后重试。`,
+        fallbackMessage: `出错了，笨蛋～ ${String(err)}`,
+        error: err,
+      });
+    }
+  });
+}

package/config.md

@@ -72,6 +72,80 @@ fields:
     description: 短时间内多个新成员入群时，攒齐该时长内的成员后只发一次 AI 欢迎，避免频繁调用模型。设为 0 表示关闭聚合、逐个欢迎。默认 20000。
     placeholder: 20000
 
+  - key: verify.groups
+    label: 各群入群验证配置
+    type: json
+    description: 每个群的验证配置数组，元素形如 {"groupId":123,"enabled":true,"mode":"reaction"}。推荐通过 /开启验证、/关闭验证、/切换验证模式 指令管理，直接编辑需填写合法 JSON 数组。
+    placeholder: '[]'
+
+  - key: verify.reactionEmojiId
+    label: 回应模式表态表情ID
+    type: text
+    description: 回应验证模式下，Bot 给提示消息添加的表态表情 ID，新成员点击该表态即通过验证。默认 424。
+    placeholder: "424"
+
+  - key: verify.reactionDelayMs
+    label: 回应模式延迟 (毫秒)
+    type: number
+    description: 回应模式下新成员入群后，Bot 等待多久再 @新成员发出验证提示并添加表态。默认 3000。重新验证指令不受此延迟影响。
+    placeholder: 3000
+
+  - key: verify.verifyTimeoutMs
+    label: 验证超时 (毫秒)
+    type: number
+    description: 新成员未在此时长内完成验证则视为超时，按下方配置决定是否踢出。默认 120000（2分钟）。
+    placeholder: 120000
+
+  - key: verify.reactionPrompt
+    label: 回应模式提示语
+    type: textarea
+    description: 回应模式下 @新成员 时发送的提示文本。
+    placeholder: 新来的小伙伴请在2分钟内点击下方红色按钮完成验证 不听话会被移出群聊喵~
+
+  - key: verify.numberPrompt
+    label: 数字模式提示语
+    type: textarea
+    description: 数字模式下的提示文本，支持 {question} 占位符替换算术题。
+    placeholder: '新来的小伙伴请在2分钟内回答下面的题目完成验证，不听话移出群聊喵~\n请问：{question}'
+
+  - key: verify.chiralApiUrl
+    label: 手性碳验证 API 地址
+    type: text
+    description: 手性碳模式调用的验证服务地址，默认 https://carbon.crystelf.top。你也可以参照 https://github.com/leafLeaf9/chiral-carbon-captcha 自行部署后填写自己的地址。
+    placeholder: https://carbon.crystelf.top
+
+  - key: verify.chiralDifficulty
+    label: 手性碳验证难度
+    type: select
+    options:
+      - value: simple
+        label: 简单（显示提示）
+      - value: hard
+        label: 困难（不显示提示）
+    description: 简单模式题图带提示标注，困难模式不带提示。
+
+  - key: verify.chiralPrompt
+    label: 手性碳模式提示语
+    type: textarea
+    description: 手性碳模式下随题图发送的提示文本，支持 {count} 占位符替换答案数量。
+    placeholder: '新来的小伙伴请在2分钟内完成下面的手性碳验证：找出图中{count}个手性碳所在的格子，回复格子编号即可，不听话会被移出群聊喵~'
+
+  - key: verify.maxInvalidMessages
+    label: 最大无关消息数
+    type: number
+    description: 未验证成员发送与验证无关的消息达到该次数后踢出群聊。默认 5。
+    placeholder: 5
+
+  - key: verify.kickOnFail
+    label: 达到上限踢出
+    type: switch
+    description: 未验证成员无关消息达到上限时是否踢出群聊
+
+  - key: verify.kickOnTimeout
+    label: 超时踢出
+    type: switch
+    description: 新成员验证超时是否踢出群聊
+
 ---
 
 ```mioku-fields
@@ -88,4 +162,16 @@ keys:
   - base.welcome.text
   - base.welcome.aiPrompt
   - base.welcome.batchWindowMs
-```
+  - verify.groups
+  - verify.reactionEmojiId
+  - verify.reactionDelayMs
+  - verify.verifyTimeoutMs
+  - verify.reactionPrompt
+  - verify.numberPrompt
+  - verify.chiralApiUrl
+  - verify.chiralDifficulty
+  - verify.chiralPrompt
+  - verify.maxInvalidMessages
+  - verify.kickOnFail
+  - verify.kickOnTimeout
+```

package/config.ts

@@ -48,8 +48,7 @@ export function normalizeConfig(raw: any): AdminConfig {
     notifyGroupUnban: raw?.notifyGroupUnban ?? DEFAULT_CONFIG.notifyGroupUnban,
     notifyGroupKick: raw?.notifyGroupKick ?? DEFAULT_CONFIG.notifyGroupKick,
     welcome: {
-      enabled:
-        raw?.welcome?.enabled ?? DEFAULT_CONFIG.welcome.enabled,
+      enabled: raw?.welcome?.enabled ?? DEFAULT_CONFIG.welcome.enabled,
       mode: raw?.welcome?.mode === "text" ? "text" : "ai",
       text:
         typeof raw?.welcome?.text === "string"
@@ -147,4 +146,4 @@ export async function getMemberRole(
   } catch {
     return "member";
   }
-}
+}

package/index.ts

@@ -1,12 +1,18 @@
 import { definePlugin, type MiokiContext } from "mioki";
 import type { AIService, ConfigService } from "mioku";
 import { setPluginRuntimeState, resetPluginRuntimeState } from "mioku";
-import { DEFAULT_CONFIG, normalizeConfig } from "./config";
-import type { AdminConfig } from "./config";
+import { DEFAULT_CONFIG, normalizeConfig, type AdminConfig } from "./config";
+import {
+  DEFAULT_VERIFY_CONFIG,
+  normalizeVerifyConfig,
+  type VerifyConfig,
+} from "./verify/config";
 import { registerNotificationHandlers } from "./notify";
 import { registerPersonalCommands } from "./commands/personal";
 import { registerGroupAdminCommands } from "./commands/group";
+import { registerVerifyCommands } from "./commands/verify";
 import { registerWelcomeHandler } from "./notify/welcome";
+import { createVerifyController } from "./verify";
 
 interface RuntimeState {
   ctx?: MiokiContext;
@@ -23,6 +29,7 @@ export default definePlugin({
     const aiService = ctx.services?.ai as AIService | undefined;
 
     let config: AdminConfig = { ...DEFAULT_CONFIG };
+    let verifyConfig: VerifyConfig = { ...DEFAULT_VERIFY_CONFIG };
 
     if (configService) {
       await configService.registerConfig("admin", "base", DEFAULT_CONFIG);
@@ -31,17 +38,58 @@ export default definePlugin({
       configService.onConfigChange("admin", "base", (next) => {
         config = normalizeConfig(next);
       });
+
+      await configService.registerConfig(
+        "admin",
+        "verify",
+        DEFAULT_VERIFY_CONFIG,
+      );
+      const verifyRaw = await configService.getConfig("admin", "verify");
+      verifyConfig = normalizeVerifyConfig(verifyRaw);
+      configService.onConfigChange("admin", "verify", (next) => {
+        verifyConfig = normalizeVerifyConfig(next);
+      });
     }
 
     setPluginRuntimeState("admin", { ctx });
 
     const getConfig = () => config;
+    const getVerifyConfig = () => verifyConfig;
+    const getWelcomeEnabled = () => config.welcome.enabled;
+    const setVerifyConfig = async (next: VerifyConfig) => {
+      verifyConfig = next;
+      if (configService) {
+        await configService.updateConfig("admin", "verify", next);
+      }
+    };
+
+    const verifyController = createVerifyController({
+      ctx,
+      aiService,
+      getConfig,
+      getVerifyConfig,
+      getWelcomeEnabled,
+      setVerifyConfig,
+    });
 
     // 注册事件通知
     registerNotificationHandlers(ctx, getConfig);
 
-    // 注册新人入群欢迎
-    registerWelcomeHandler(ctx, aiService, getConfig);
+    // 注册新人入群欢迎（开启验证的群由 verify 接管，验证通过后再欢迎）
+    const disposeWelcome = registerWelcomeHandler(
+      ctx,
+      aiService,
+      getConfig,
+      (info) => verifyController.handleMemberJoin(info),
+    );
+
+    // 注册入群验证指令
+    registerVerifyCommands({
+      ctx,
+      getVerifyConfig,
+      setVerifyConfig,
+      verifyController,
+    });
 
     // 注册指令
     registerPersonalCommands(ctx);
@@ -50,8 +98,10 @@ export default definePlugin({
     ctx.logger.info("管理插件加载成功");
 
     return () => {
+      disposeWelcome();
+      verifyController.dispose();
       resetPluginRuntimeState("admin");
       ctx.logger.info("管理插件已卸载");
     };
   },
-});
+});

package/notify/welcome.ts

@@ -73,8 +73,10 @@ async function flushBatch(options: {
   groupId: number;
   groupName: string;
   members: PendingMember[];
+  promptInjections?: { content: string; title?: string }[];
 }): Promise<string> {
-  const { ctx, aiService, config, selfId, groupId, groupName, members } = options;
+  const { ctx, aiService, config, selfId, groupId, groupName, members, promptInjections } =
+    options;
   if (!members.length) return "";
 
   const names = members.map((m) => m.memberName || String(m.userId));
@@ -110,6 +112,7 @@ async function flushBatch(options: {
         `所在群：${groupName}`,
         `${config.welcome.aiPrompt || ""}`,
       ].join("\n"),
+      promptInjections,
     });
 
     return "";
@@ -119,10 +122,90 @@ async function flushBatch(options: {
   }
 }
 
+async function sendSingleWelcome(options: {
+  ctx: MiokiContext;
+  aiService?: AIService;
+  config: AdminConfig;
+  selfId: number;
+  groupId: number;
+  groupName: string;
+  userId: number;
+  memberName: string;
+  promptInjections?: { content: string; title?: string }[];
+}): Promise<void> {
+  const {
+    ctx,
+    aiService,
+    config,
+    selfId,
+    groupId,
+    groupName,
+    userId,
+    memberName,
+    promptInjections,
+  } = options;
+  const welcomeMessage = await flushBatch({
+    ctx,
+    aiService,
+    config,
+    selfId,
+    groupId,
+    groupName,
+    members: [{ userId, memberName }],
+    promptInjections,
+  });
+  if (!welcomeMessage) return;
+  const bot = ctx.pickBot(selfId);
+  if (!bot) return;
+  try {
+    await bot.sendGroupMsg(groupId, [ctx.segment.text(welcomeMessage)]);
+  } catch (error) {
+    ctx.logger.warn(`发送入群欢迎失败: ${error}`);
+  }
+}
+
+export async function triggerSingleWelcome(options: {
+  ctx: MiokiContext;
+  aiService?: AIService;
+  getConfig: () => AdminConfig;
+  selfId: number;
+  groupId: number;
+  groupName: string;
+  userId: number;
+  memberName?: string;
+  promptInjections?: { content: string; title?: string }[];
+}): Promise<void> {
+  const memberName =
+    options.memberName ||
+    (await resolveMemberName(
+      options.ctx,
+      options.groupId,
+      options.userId,
+      options.selfId,
+    ));
+  await sendSingleWelcome({
+    ctx: options.ctx,
+    aiService: options.aiService,
+    config: options.getConfig(),
+    selfId: options.selfId,
+    groupId: options.groupId,
+    groupName: options.groupName,
+    userId: options.userId,
+    memberName,
+    promptInjections: options.promptInjections,
+  });
+}
+
 export function registerWelcomeHandler(
   ctx: MiokiContext,
   aiService: AIService | undefined,
   getConfig: () => AdminConfig,
+  shouldSuppress?: (info: {
+    selfId: number;
+    groupId: number;
+    userId: number;
+    groupName: string;
+  }) => Promise<boolean> | boolean,
 ): () => void {
   const batches = getBatchMap();
 
@@ -134,11 +217,18 @@ export function registerWelcomeHandler(
     if (!groupId || !userId) return;
     if (userId === selfId) return;
 
-    if (!cfg.welcome.enabled) return;
-
     const groupName =
       String(event?.group?.group_name || "").trim() || String(groupId);
 
+    if (
+      shouldSuppress &&
+      (await shouldSuppress({ selfId, groupId, userId, groupName }))
+    ) {
+      return;
+    }
+
+    if (!cfg.welcome.enabled) return;
+
     const batchWindowMs = Math.max(0, Number(cfg.welcome.batchWindowMs) || 0);
 
     if (batchWindowMs === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-admin",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "description": "管理插件，提供事件通知与群管/个人管理指令",
   "main": "index.ts",
   "type": "module",
@@ -117,6 +117,26 @@
         "id": "welcome",
         "event": "notice.group.increase",
         "description": "新人入群相关功能"
+      },
+      {
+        "id": "/开启验证",
+        "match": "/^[/#]开启验证$/"
+      },
+      {
+        "id": "/关闭验证",
+        "match": "/^[/#]关闭验证$/"
+      },
+      {
+        "id": "/切换验证模式",
+        "match": "/^[/#]切换验证模式/"
+      },
+      {
+        "id": "/绕过验证",
+        "match": "/^[/#]绕过验证/"
+      },
+      {
+        "id": "/重新验证",
+        "match": "/^[/#]重新验证/"
       }
     ],
     "help": {
@@ -240,6 +260,34 @@
           "cmd": "/全部群聊",
           "desc": "获取全部群聊列表",
           "role": "master"
+        },
+        {
+          "cmd": "/开启验证",
+          "desc": "开启本群入群验证",
+          "role": "admin"
+        },
+        {
+          "cmd": "/关闭验证",
+          "desc": "关闭本群入群验证",
+          "role": "admin"
+        },
+        {
+          "cmd": "/切换验证模式",
+          "desc": "切换验证模式：回应/数字/手性碳",
+          "usage": "/切换验证模式 回应",
+          "role": "admin"
+        },
+        {
+          "cmd": "/绕过验证",
+          "desc": "绕过指定新成员的验证直接欢迎",
+          "usage": "/绕过验证 @新成员",
+          "role": "admin"
+        },
+        {
+          "cmd": "/重新验证",
+          "desc": "让指定成员重新进行入群验证",
+          "usage": "/重新验证 @成员",
+          "role": "admin"
         }
       ]
     }