mioku-plugin-meme 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jerry
+
+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,29 @@
+# Meme Plugin
+
+Mioku 的 `meme` 插件，用来接入 `meme-generator` API，在聊天中搜索、查看和生成表情包。
+
+## 功能
+
+- 支持 `meme` 菜单、搜索、详情、更新
+- 支持直接用表情关键词生成表情
+- 支持 AI 调用 `search_memes` 和 `send_meme`
+- 支持 WebUI 配置页
+- 支持黑名单关键词拦截
+- 支持用户头像或指定消息图片作为生成来源
+
+## 使用
+
+这个插件依赖一个单独运行的 `meme-generator` API 服务
+
+默认 API 地址：
+
+```text
+http://127.0.0.1:2233
+```
+
+你可以在 WebUI 或配置文件里修改
+
+## 搭建 Meme API
+
+- GitHub: https://github.com/MeetWq/meme-generator
+- Docker Hub: https://hub.docker.com/r/meetwq/meme-generator

package/config.md

@@ -0,0 +1,103 @@
+---
+title: Meme 插件配置
+description: 在这里调整表情包插件的配置
+fields:
+  - key: base.api.baseUrl
+    label: Meme API 地址
+    type: text
+    description: meme-generator 服务地址,可自行搭建
+    placeholder: http://127.0.0.1:2233
+
+  - key: base.api.timeoutMs
+    label: 请求超时毫秒
+    type: number
+    description: 访问 meme API 的超时时间
+    placeholder: 15000
+
+  - key: base.trigger.requirePrefix
+    label: 命令是否要求前缀
+    type: switch
+    description: 开启后，菜单/搜索/更新等命令必须带前缀
+
+  - key: base.trigger.prefixes
+    label: 命令前缀列表
+    type: json
+    description: 命令识别前缀数组。默认是 [\"/\", \"#\"]。
+
+  - key: base.trigger.directKeywordNeedPrefix
+    label: 关键词是否要前缀
+    type: switch
+    description: 控制 `<表情关键词> [文本][#参数]` 这种是否必须带前缀
+
+  - key: base.behavior.quoteReply
+    label: 生成结果是否引用
+    type: switch
+    description: 发送生成图片时是否附带引用回复段
+
+  - key: base.behavior.useSenderAvatarFallback
+    label: 使用发送着头像
+    type: switch
+    description: 在自动取图模式下，如果消息和引用里都没有图，是否自动使用发送者头像进行制作
+
+  - key: base.behavior.includePreviewInDetail
+    label: 详情页附带预览图
+    type: switch
+    description: 执行“meme 详情 关键词”时是否再拉取一张预览图
+
+  - key: base.behavior.maxSearchResults
+    label: 搜索结果上限
+    type: number
+    description: 单次搜索返回的关键词最大条数
+    placeholder: 20
+
+  - key: base.cache.refreshOnStartup
+    label: 启动自动刷新缓存
+    type: switch
+    description: 开启后插件每次启动都会重新拉取关键词和菜单图,关闭则优先使用本地缓存
+
+  - key: base.permissions.ownerOnlyUpdate
+    label: 更新是否仅主人可用
+    type: switch
+    description: 控制“meme 更新”命令的权限。开启后只有 owner 能手动刷新缓存
+
+  - key: filters.enabled
+    label: 是否启用黑名单
+    type: switch
+    description: 开启后命中黑名单关键词会阻止生成
+
+  - key: filters.blockedKeywords
+    label: 黑名单关键词列表
+    type: json
+    description: 关键词数组,命中任意一项即视为黑名单触发
+
+  - key: filters.replyOnBlocked
+    label: 黑名单命中时是否回复
+    type: switch
+    description: 关闭则静默拦截不回消息
+---
+
+```mioku-fields
+keys:
+  - base.api.baseU
+  - base.api.timeoutMs
+  - base.trigger.requirePrefix
+  - base.trigger.prefixes
+  - base.trigger.directKeywordNeedPrefix
+```
+
+```mioku-fields
+keys:
+  - base.behavior.quoteReply
+  - base.behavior.useSenderAvatarFallback
+  - base.behavior.includePreviewInDetail
+  - base.behavior.maxSearchResults
+  - base.cache.refreshOnStartup
+  - base.permissions.ownerOnlyUpdate
+```
+
+```mioku-fields
+keys:
+  - filters.enabled
+  - filters.blockedKeywords
+  - filters.replyOnBlocked
+```

package/configs/base.ts

@@ -0,0 +1,25 @@
+import type { MemeBaseConfig } from "../types";
+
+export const MEME_BASE_CONFIG: MemeBaseConfig = {
+  api: {
+    baseUrl: "http://127.0.0.1:2233",
+    timeoutMs: 15000,
+  },
+  trigger: {
+    requirePrefix: true,
+    prefixes: ["/", "#"],
+    directKeywordNeedPrefix: false,
+  },
+  behavior: {
+    quoteReply: false,
+    useSenderAvatarFallback: true,
+    includePreviewInDetail: true,
+    maxSearchResults: 20,
+  },
+  cache: {
+    refreshOnStartup: false,
+  },
+  permissions: {
+    ownerOnlyUpdate: true,
+  },
+};

package/configs/filters.ts

@@ -0,0 +1,26 @@
+import type { MemeFilterConfig } from "../types";
+
+export const MEME_FILTER_CONFIG: MemeFilterConfig = {
+  enabled: true,
+  blockedKeywords: [
+    "撅",
+    "砍",
+    "射",
+    "🐍",
+    "看看你的",
+    "换位思考",
+    "打胶",
+    "飞机杯",
+    "鞭",
+    "导",
+    "打飞机",
+    "口",
+    "火柴撸",
+    "求",
+    "啃",
+    "对称",
+    "sm",
+    "斩",
+  ],
+  replyOnBlocked: true,
+};

package/index.ts

@@ -0,0 +1,374 @@
+import type { AIService } from "../../src/services/ai/types";
+import type { ConfigService } from "../../src/services/config/tpyes";
+import { definePlugin, type MiokiContext } from "mioki";
+import { MEME_BASE_CONFIG } from "./configs/base";
+import { MEME_FILTER_CONFIG } from "./configs/filters";
+import { MemePluginRuntime, replyWithParts } from "./shared";
+import { resetMemeRuntimeState, setMemeRuntimeState } from "./runtime";
+import type { MemeBaseConfig, MemeFilterConfig } from "./types";
+
+function cloneConfig<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+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);
+  }
+}
+
+function stripCommandPrefix(
+  text: string,
+  prefixes: string[],
+): { value: string; hasPrefix: boolean } {
+  const trimmed = String(text || "").trim();
+  for (const prefix of prefixes) {
+    if (trimmed.startsWith(prefix)) {
+      return {
+        value: trimmed.slice(prefix.length).trim(),
+        hasPrefix: true,
+      };
+    }
+  }
+  return { value: trimmed, hasPrefix: false };
+}
+
+const memePlugin = definePlugin({
+  name: "meme",
+  version: "1.0.0",
+  description: "基于 meme-generator API 的表情包制作插件",
+
+  async setup(ctx: MiokiContext) {
+    const configService = ctx.services?.config as ConfigService | undefined;
+    const aiService = ctx.services?.ai as AIService | undefined;
+
+    let baseConfig = cloneConfig(MEME_BASE_CONFIG);
+    let filterConfig = cloneConfig(MEME_FILTER_CONFIG);
+
+    if (configService) {
+      await configService.registerConfig("meme", "base", baseConfig);
+      await configService.registerConfig("meme", "filters", filterConfig);
+
+      const nextBase = await configService.getConfig("meme", "base");
+      const nextFilters = await configService.getConfig("meme", "filters");
+      if (nextBase) {
+        baseConfig = nextBase as MemeBaseConfig;
+      }
+      if (nextFilters) {
+        filterConfig = nextFilters as MemeFilterConfig;
+      }
+    } else {
+      ctx.logger.warn("config-service 未加载，meme 插件将使用内置默认配置");
+    }
+
+    const notifyByAIRuntime = async (
+      event: any,
+      instruction: string,
+      fallbackMessage?: string,
+      error?: unknown,
+    ) => {
+      if (error != null) {
+        ctx.logger.error(
+          `[meme] ${instruction}\n执行错误: ${normalizeErrorMessage(error)}`,
+        );
+      }
+      const chatRuntime = aiService?.getChatRuntime();
+      if (chatRuntime) {
+        try {
+          await chatRuntime.generateNotice({
+            event,
+            instruction,
+            send: true,
+            promptInjections: [
+              {
+                title: "Meme Plugin Notice",
+                content:
+                  "A meme-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. Keep it brief and natural.",
+              },
+            ],
+          });
+          return;
+        } catch (noticeError) {
+          ctx.logger.error(`meme notice 发送失败 ${noticeError}`);
+        }
+      }
+
+      await replyWithParts({
+        ctx,
+        event,
+        parts: [fallbackMessage || "请求处理失败，请稍后重试"],
+        quoteReply: baseConfig.behavior.quoteReply,
+      });
+    };
+
+    const runtime = new MemePluginRuntime({
+      logger: ctx.logger,
+      baseConfig,
+      filterConfig,
+    });
+
+    try {
+      await runtime.initialize();
+    } catch (error) {
+      ctx.logger.warn(
+        `meme 插件初始化缓存失败，首次使用时会再尝试拉取: ${error}`,
+      );
+    }
+
+    setMemeRuntimeState({ runtime });
+
+    const disposers: Array<() => void> = [];
+    if (configService) {
+      disposers.push(
+        configService.onConfigChange("meme", "base", (next) => {
+          baseConfig = next as MemeBaseConfig;
+          runtime.updateBaseConfig(baseConfig);
+        }),
+      );
+      disposers.push(
+        configService.onConfigChange("meme", "filters", (next) => {
+          filterConfig = next as MemeFilterConfig;
+          runtime.updateFilterConfig(filterConfig);
+        }),
+      );
+    }
+
+    ctx.handle("message", async (event: any) => {
+      const rawText = ctx.text(event)?.trim();
+      if (!rawText) {
+        return;
+      }
+
+      const stripResult = stripCommandPrefix(
+        rawText,
+        baseConfig.trigger.prefixes,
+      );
+      const prefixedText = stripResult.value;
+      const commandText =
+        stripResult.hasPrefix || !baseConfig.trigger.requirePrefix
+          ? prefixedText
+          : "";
+      const directText = stripResult.hasPrefix
+        ? prefixedText
+        : baseConfig.trigger.directKeywordNeedPrefix
+          ? ""
+          : rawText;
+
+      try {
+        if (
+          commandText &&
+          (/^(?:表情|meme)包?(?:菜单|展示|制作(?:列表)?)$/i.test(commandText) ||
+            /^meme\s+(?:菜单|列表|展示)$/i.test(commandText))
+        ) {
+          await runtime.sendMenu(ctx, event);
+          return;
+        }
+
+        if (commandText && /^随机(?:表情|meme)(?:包)?$/i.test(commandText)) {
+          await runtime.sendRandom(ctx, event);
+          return;
+        }
+
+        if (
+          commandText &&
+          (/^(?:(?:头像|文字)?(?:表情|meme)包?(?:制作(?:菜单|教程)?|帮助|说明|指令|使用说明)|(?:头像|文字)(?:表情|meme)包?)$/i.test(
+            commandText,
+          ) ||
+            /^meme\s+帮助$/i.test(commandText))
+        ) {
+          await runtime.sendHelp(ctx, event);
+          return;
+        }
+
+        const searchMatch = commandText.match(
+          /^(?:表情|meme)包?(?:搜索|检索)\s*(.*)$/i,
+        );
+        if (searchMatch) {
+          const query = (searchMatch[1] || "").trim();
+          if (!query) {
+            await notifyByAIRuntime(
+              event,
+              "用户发起了 meme 搜索但没有给关键词。请自然提醒他补一个搜索词",
+              "你想搜什么？",
+            );
+            return;
+          }
+          await runtime.sendSearch(ctx, event, query);
+          return;
+        }
+
+        const detailCommandMatch =
+          commandText.match(/^meme包?\s+详情\s+(.+)$/i);
+        if (detailCommandMatch) {
+          const keyword = detailCommandMatch[1].trim();
+          if (!runtime.getDetail(keyword)) {
+            await notifyByAIRuntime(
+              event,
+              `用户查询了不存在的表情详情关键词 "${keyword}"。请自然提醒先搜索可用关键词`,
+              `未找到表情关键词：${keyword}`,
+            );
+            return;
+          }
+          await runtime.sendDetail(ctx, event, keyword);
+          return;
+        }
+
+        if (
+          commandText &&
+          (/^(?:表情|meme)包?更新$/i.test(commandText) ||
+            /^meme\s+更新$/i.test(commandText))
+        ) {
+          if (baseConfig.permissions.ownerOnlyUpdate && !ctx.isOwner(event)) {
+            await notifyByAIRuntime(
+              event,
+              "用户尝试刷新 meme 缓存，但权限不足。请自然提醒该操作仅主人可用",
+              "不支持小男娘使用喵",
+            );
+            return;
+          }
+
+          await replyWithParts({
+            ctx,
+            event,
+            parts: ["开始刷新 meme 缓存，请稍等..."],
+            quoteReply: baseConfig.behavior.quoteReply,
+          });
+
+          try {
+            await runtime.refreshCache();
+            await runtime.sendMenu(ctx, event);
+          } catch (error) {
+            await notifyByAIRuntime(
+              event,
+              `meme 缓存刷新失败，错误信息：${error}。请自然告知用户稍后重试或让管理员检查 meme API 服务状态。`,
+              `刷新 meme 缓存失败：${error}`,
+              error,
+            );
+          }
+          return;
+        }
+
+        const genericGenerateMatch = commandText.match(
+          /^meme包?\s+(?:生成|制作)\s+(.+)$/i,
+        );
+        if (genericGenerateMatch) {
+          const result = await runtime.generateFromInput(
+            ctx,
+            event,
+            genericGenerateMatch[1],
+            {
+              send: true,
+            },
+          );
+          if (!result.ok && result.shouldNotice) {
+            await notifyByAIRuntime(
+              event,
+              result.noticeInstruction || `meme 生成失败：${result.message}`,
+              result.message,
+            );
+          }
+          return;
+        }
+
+        const genericPassThroughMatch = commandText.match(/^meme包?\s+(.+)$/i);
+        if (genericPassThroughMatch) {
+          const passThrough = genericPassThroughMatch[1].trim();
+          if (!passThrough) {
+            return;
+          }
+
+          if (/(详情|帮助|成分)$/.test(passThrough)) {
+            const keyword = passThrough.replace(/(详情|帮助|成分)$/, "").trim();
+            if (!runtime.getDetail(keyword)) {
+              await notifyByAIRuntime(
+                event,
+                `用户查询了不存在的表情详情关键词 "${keyword}"。请自然提醒先搜索可用关键词`,
+                `未找到表情关键词：${keyword}`,
+              );
+              return;
+            }
+            await runtime.sendDetail(ctx, event, keyword);
+            return;
+          }
+
+          const result = await runtime.generateFromInput(
+            ctx,
+            event,
+            passThrough,
+            {
+              send: true,
+            },
+          );
+          if (!result.ok && result.shouldNotice) {
+            await notifyByAIRuntime(
+              event,
+              result.noticeInstruction || `meme 生成失败：${result.message}`,
+              result.message,
+            );
+          }
+          return;
+        }
+
+        if (!directText) {
+          return;
+        }
+
+        const directMatch = runtime.findMatch(directText);
+        if (!directMatch) {
+          return;
+        }
+
+        if (/(详情|帮助|成分)$/.test(directMatch.rest)) {
+          if (!runtime.getDetail(directMatch.keyword)) {
+            await notifyByAIRuntime(
+              event,
+              `用户查询了不存在的表情详情关键词 "${directMatch.keyword}"。请自然提醒先搜索可用关键词`,
+              `未找到表情关键词：${directMatch.keyword}`,
+            );
+            return;
+          }
+          await runtime.sendDetail(ctx, event, directMatch.keyword);
+          return;
+        }
+
+        const directResult = await runtime.generateFromInput(
+          ctx,
+          event,
+          directText,
+          {
+            send: true,
+          },
+        );
+        if (!directResult.ok && directResult.shouldNotice) {
+          await notifyByAIRuntime(
+            event,
+            directResult.noticeInstruction ||
+              `meme 生成失败：${directResult.message}`,
+            directResult.message,
+          );
+        }
+      } catch (error) {
+        await notifyByAIRuntime(
+          event,
+          `meme 插件执行失败，错误信息：${error}。请自然告诉用户当前处理失败并建议稍后重试`,
+          `meme 插件执行失败：${error}`,
+          error,
+        );
+      }
+    });
+
+    return () => {
+      for (const dispose of disposers) {
+        dispose();
+      }
+      resetMemeRuntimeState();
+      ctx.logger.info("meme 插件已卸载");
+    };
+  },
+});
+
+export default memePlugin;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "mioku-plugin-meme",
+  "version": "1.0.0",
+  "description": "基于 meme-generator API 的表情包制作插件",
+  "main": "index.ts",
+  "keywords": [
+    "mioku"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mioku-lab/mioku-plugin-meme.git"
+  },
+  "mioku": {
+    "services": [
+      "config",
+      "ai"
+    ],
+    "help": {
+      "title": "Meme 表情包",
+      "description": "接入 meme-generator API 的表情包制作插件",
+      "commands": [
+        {
+          "cmd": "/meme 菜单",
+          "desc": "查看已同步的表情菜单",
+          "usage": "/meme 菜单",
+          "role": "member"
+        },
+        {
+          "cmd": "/meme 搜索 <关键词>",
+          "desc": "搜索相关表情关键词",
+          "usage": "/meme 搜索 摸",
+          "role": "member"
+        },
+        {
+          "cmd": "/meme 详情 <关键词>",
+          "desc": "查看表情参数和预览",
+          "usage": "/meme 详情 摸头",
+          "role": "member"
+        },
+        {
+          "cmd": "/随机表情",
+          "desc": "随机生成一个头像类表情",
+          "usage": "/随机表情",
+          "role": "member"
+        },
+        {
+          "cmd": "<表情关键词> [文本1/文本2][#参数]",
+          "desc": "直接按关键词生成表情",
+          "usage": "摸头 小明#圆",
+          "role": "member"
+        },
+        {
+          "cmd": "/meme 更新",
+          "desc": "刷新远端表情缓存",
+          "usage": "/meme 更新",
+          "role": "owner"
+        }
+      ]
+    }
+  }
+}

package/runtime.ts

@@ -0,0 +1,26 @@
+import type { MemePluginRuntime } from "./shared";
+import {
+  getPluginRuntimeState,
+  resetPluginRuntimeState,
+  setPluginRuntimeState,
+} from "../../src";
+
+export interface MemeRuntimeState {
+  runtime?: MemePluginRuntime;
+}
+
+const MEME_PLUGIN_NAME = "meme";
+
+export function setMemeRuntimeState(
+  nextState: MemeRuntimeState,
+): MemeRuntimeState {
+  return setPluginRuntimeState<MemeRuntimeState>(MEME_PLUGIN_NAME, nextState);
+}
+
+export function getMemeRuntimeState(): MemeRuntimeState {
+  return getPluginRuntimeState<MemeRuntimeState>(MEME_PLUGIN_NAME);
+}
+
+export function resetMemeRuntimeState(): void {
+  resetPluginRuntimeState(MEME_PLUGIN_NAME);
+}