mioku-plugin-admin 2.2.2 → 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

@@ -39,6 +39,113 @@ fields:
     type: switch
     description: Bot被踢出群聊时通知主人
 
+  - key: base.welcome.enabled
+    label: 启用新人入群欢迎
+    type: switch
+    description: 新人（非机器人）入群时发送欢迎消息
+
+  - key: base.welcome.mode
+    label: 欢迎模式
+    type: select
+    options:
+      - value: ai
+        label: 使用AI生成
+      - value: text
+        label: 固定文本
+    description: AI 模式由 chat-runtime 模型生成；text 模式直接套用固定欢迎模板
+
+  - key: base.welcome.text
+    label: 固定欢迎文本
+    type: textarea
+    description: 欢迎模板，支持 {user} 和 {group} 占位符
+    placeholder: 欢迎新人～
+
+  - key: base.welcome.aiPrompt
+    label: AI欢迎额外提示词
+    type: textarea
+    description: 作为额外要求传给模型，默认留空即可
+    placeholder: 例如：提醒新成员查看群公告
+
+  - key: base.welcome.batchWindowMs
+    label: AI 欢迎聚合窗口 (毫秒)
+    type: number
+    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
@@ -50,4 +157,21 @@ keys:
   - base.notifyGroupBan
   - base.notifyGroupUnban
   - base.notifyGroupKick
+  - base.welcome.enabled
+  - base.welcome.mode
+  - 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

@@ -8,6 +8,13 @@ export interface AdminConfig {
   notifyGroupBan: boolean;
   notifyGroupUnban: boolean;
   notifyGroupKick: boolean;
+  welcome: {
+    enabled: boolean;
+    mode: "ai" | "text";
+    text: string;
+    aiPrompt: string;
+    batchWindowMs: number;
+  };
 }
 
 export const DEFAULT_CONFIG: AdminConfig = {
@@ -18,6 +25,13 @@ export const DEFAULT_CONFIG: AdminConfig = {
   notifyGroupBan: true,
   notifyGroupUnban: true,
   notifyGroupKick: true,
+  welcome: {
+    enabled: true,
+    mode: "ai",
+    text: "欢迎新人～",
+    aiPrompt: "",
+    batchWindowMs: 20000,
+  },
 };
 
 export function normalizeConfig(raw: any): AdminConfig {
@@ -33,9 +47,30 @@ export function normalizeConfig(raw: any): AdminConfig {
     notifyGroupBan: raw?.notifyGroupBan ?? DEFAULT_CONFIG.notifyGroupBan,
     notifyGroupUnban: raw?.notifyGroupUnban ?? DEFAULT_CONFIG.notifyGroupUnban,
     notifyGroupKick: raw?.notifyGroupKick ?? DEFAULT_CONFIG.notifyGroupKick,
+    welcome: {
+      enabled: raw?.welcome?.enabled ?? DEFAULT_CONFIG.welcome.enabled,
+      mode: raw?.welcome?.mode === "text" ? "text" : "ai",
+      text:
+        typeof raw?.welcome?.text === "string"
+          ? raw.welcome.text
+          : DEFAULT_CONFIG.welcome.text,
+      aiPrompt:
+        typeof raw?.welcome?.aiPrompt === "string"
+          ? raw.welcome.aiPrompt
+          : DEFAULT_CONFIG.welcome.aiPrompt,
+      batchWindowMs: normalizeBatchWindowMs(raw?.welcome?.batchWindowMs),
+    },
   };
 }
 
+function normalizeBatchWindowMs(value: unknown): number {
+  const num = Number(value);
+  if (!Number.isFinite(num) || num < 0) {
+    return DEFAULT_CONFIG.welcome.batchWindowMs;
+  }
+  return Math.floor(num);
+}
+
 // 格式化秒数为可读时长
 export function formatDuration(seconds: number): string {
   if (seconds <= 0) return "0秒";

package/index.ts

@@ -1,11 +1,18 @@
 import { definePlugin, type MiokiContext } from "mioki";
-import type { ConfigService } from "mioku";
+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;
@@ -15,12 +22,14 @@ interface RuntimeState {
 export default definePlugin({
   name: "admin",
   version: "1.0.0",
-  description: "管理插件，提供事件通知与管理指令",
+  description: "管理插件，提供事件通知与群管/个人管理指令",
 
   async setup(ctx: MiokiContext) {
     const configService = ctx.services?.config as ConfigService | undefined;
+    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);
@@ -29,15 +38,59 @@ 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);
 
+    // 注册新人入群欢迎（开启验证的群由 verify 接管，验证通过后再欢迎）
+    const disposeWelcome = registerWelcomeHandler(
+      ctx,
+      aiService,
+      getConfig,
+      (info) => verifyController.handleMemberJoin(info),
+    );
+
+    // 注册入群验证指令
+    registerVerifyCommands({
+      ctx,
+      getVerifyConfig,
+      setVerifyConfig,
+      verifyController,
+    });
+
     // 注册指令
     registerPersonalCommands(ctx);
     registerGroupAdminCommands(ctx);
@@ -45,6 +98,8 @@ export default definePlugin({
     ctx.logger.info("管理插件加载成功");
 
     return () => {
+      disposeWelcome();
+      verifyController.dispose();
       resetPluginRuntimeState("admin");
       ctx.logger.info("管理插件已卸载");
     };