mioku-plugin-admin 2.2.2 → 2.2.3

package/config.md

@@ -39,6 +39,39 @@ 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
+
 ---
 
 ```mioku-fields
@@ -50,4 +83,9 @@ keys:
   - base.notifyGroupBan
   - base.notifyGroupUnban
   - base.notifyGroupKick
-```
+  - base.welcome.enabled
+  - base.welcome.mode
+  - base.welcome.text
+  - base.welcome.aiPrompt
+  - base.welcome.batchWindowMs
+```

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,31 @@ 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秒";
@@ -111,4 +147,4 @@ export async function getMemberRole(
   } catch {
     return "member";
   }
-}
+}

package/index.ts

@@ -1,11 +1,12 @@
 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 { registerNotificationHandlers } from "./notify";
 import { registerPersonalCommands } from "./commands/personal";
 import { registerGroupAdminCommands } from "./commands/group";
+import { registerWelcomeHandler } from "./notify/welcome";
 
 interface RuntimeState {
   ctx?: MiokiContext;
@@ -15,10 +16,11 @@ 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 };
 
@@ -38,6 +40,9 @@ export default definePlugin({
     // 注册事件通知
     registerNotificationHandlers(ctx, getConfig);
 
+    // 注册新人入群欢迎
+    registerWelcomeHandler(ctx, aiService, getConfig);
+
     // 注册指令
     registerPersonalCommands(ctx);
     registerGroupAdminCommands(ctx);
@@ -49,4 +54,4 @@ export default definePlugin({
       ctx.logger.info("管理插件已卸载");
     };
   },
-});
+});

package/notify/welcome.ts

@@ -0,0 +1,223 @@
+import { type MiokiContext, wait } from "mioki";
+import { getPluginRuntimeState, type AIService } from "mioku";
+import type { AdminConfig } from "../config";
+
+export async function resolveMemberName(
+  ctx: MiokiContext,
+  groupId: number,
+  userId: number,
+  selfId: number,
+): Promise<string> {
+  try {
+    const member = await ctx
+      .pickBot(selfId)
+      .getGroupMemberInfo(groupId, userId);
+    return (
+      String(member?.card || "").trim() ||
+      String(member?.nickname || "").trim() ||
+      String(userId)
+    );
+  } catch {
+    return String(userId);
+  }
+}
+
+interface PendingMember {
+  userId: number;
+  memberName: string;
+}
+
+interface BatchState {
+  members: PendingMember[];
+  timer: ReturnType<typeof setTimeout> | null;
+  groupName: string;
+}
+
+const RUNTIME_KEY = "welcomeBatch";
+
+function getBatchMap(): Map<string, BatchState> {
+  const state = getPluginRuntimeState("admin");
+  if (!state[RUNTIME_KEY]) {
+    state[RUNTIME_KEY] = new Map<string, BatchState>();
+  }
+  return state[RUNTIME_KEY] as Map<string, BatchState>;
+}
+
+function batchKey(selfId: number, groupId: number): string {
+  return `${selfId}:${groupId}`;
+}
+
+function renderTemplate(
+  template: string,
+  values: Record<string, string>,
+): string {
+  let output = String(template || "");
+  for (const [key, value] of Object.entries(values)) {
+    output = output.split(`{${key}}`).join(value);
+  }
+  return output;
+}
+
+function normalizeGeneratedText(value: string): string {
+  return String(value || "")
+    .replace(/[`"'“”‘’]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+async function flushBatch(options: {
+  ctx: MiokiContext;
+  aiService?: AIService;
+  config: AdminConfig;
+  selfId: number;
+  groupId: number;
+  groupName: string;
+  members: PendingMember[];
+}): Promise<string> {
+  const { ctx, aiService, config, selfId, groupId, groupName, members } = options;
+  if (!members.length) return "";
+
+  const names = members.map((m) => m.memberName || String(m.userId));
+  const userList = names.join("、");
+  const userIdList = members.map((m) => String(m.userId)).join(", ");
+
+  const fallbackText =
+    normalizeGeneratedText(
+      renderTemplate(config.welcome.text, {
+        user: userList,
+        group: groupName,
+      }),
+    ) || `欢迎新人～`;
+
+  if (config.welcome.mode !== "ai") {
+    return fallbackText;
+  }
+
+  const chatRuntime = aiService?.getChatRuntime();
+  if (!chatRuntime) {
+    return fallbackText;
+  }
+
+  try {
+    await chatRuntime.generateNotice({
+      selfId,
+      groupId,
+      send: true,
+      instruction: [
+        `当前有 ${members.length} 位新成员同时入群，请一次性发送一段统一的欢迎语（不要逐个 @ 欢迎、不要重复点名）。`,
+        `新成员昵称：${userList}`,
+        `新成员 QQ：${userIdList}`,
+        `所在群：${groupName}`,
+        `${config.welcome.aiPrompt || ""}`,
+      ].join("\n"),
+    });
+
+    return "";
+  } catch (error) {
+    ctx.logger.error(`admin welcome chat-runtime 生成失败: ${error}`);
+    return fallbackText;
+  }
+}
+
+export function registerWelcomeHandler(
+  ctx: MiokiContext,
+  aiService: AIService | undefined,
+  getConfig: () => AdminConfig,
+): () => void {
+  const batches = getBatchMap();
+
+  const dispose = ctx.handle("notice.group.increase" as any, async (event: any) => {
+    const cfg = getConfig();
+    const selfId = Number(event?.self_id || ctx.self_id);
+    const groupId = Number(event?.group_id || 0);
+    const userId = Number(event?.user_id || 0);
+    if (!groupId || !userId) return;
+    if (userId === selfId) return;
+
+    if (!cfg.welcome.enabled) return;
+
+    const groupName =
+      String(event?.group?.group_name || "").trim() || String(groupId);
+
+    const batchWindowMs = Math.max(0, Number(cfg.welcome.batchWindowMs) || 0);
+
+    if (batchWindowMs === 0) {
+      const memberName = await resolveMemberName(ctx, groupId, userId, selfId);
+      const welcomeMessage = await flushBatch({
+        ctx,
+        aiService,
+        config: cfg,
+        selfId,
+        groupId,
+        groupName,
+        members: [{ userId, memberName }],
+      });
+      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}`);
+      }
+      return;
+    }
+
+    const key = batchKey(selfId, groupId);
+    let state = batches.get(key);
+    if (!state) {
+      state = { members: [], timer: null, groupName };
+      batches.set(key, state);
+    }
+    if (groupName && groupName !== String(groupId)) {
+      state.groupName = groupName;
+    }
+
+    const memberName = await resolveMemberName(ctx, groupId, userId, selfId);
+    if (!state.members.some((m) => m.userId === userId)) {
+      state.members.push({ userId, memberName });
+    }
+
+    if (state.timer) {
+      return;
+    }
+
+    state.timer = setTimeout(async () => {
+      try {
+        const pending = state;
+        batches.delete(key);
+        if (!pending || !pending.members.length) return;
+
+        const currentConfig = getConfig();
+        const welcomeMessage = await flushBatch({
+          ctx,
+          aiService,
+          config: currentConfig,
+          selfId,
+          groupId,
+          groupName: pending.groupName,
+          members: pending.members,
+        });
+        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}`);
+        }
+      } catch (error) {
+        ctx.logger.error(`admin welcome 批次处理失败: ${error}`);
+      }
+    }, batchWindowMs);
+  });
+
+  return () => {
+    for (const state of batches.values()) {
+      if (state.timer) clearTimeout(state.timer);
+    }
+    batches.clear();
+    dispose();
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mioku-plugin-admin",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "管理插件，提供事件通知与群管/个人管理指令",
   "main": "index.ts",
   "type": "module",
@@ -112,6 +112,11 @@
       {
         "id": "/全部群聊",
         "match": "/^\\/全部群聊/"
+      },
+      {
+        "id": "welcome",
+        "event": "notice.group.increase",
+        "description": "新人入群相关功能"
       }
     ],
     "help": {