koishi-plugin-memes/readme.md

MemeGenerator(RS)表情生成，全功能支持，可自由配置黑名单。

# koishi-plugin-memes

[![npm](https://img.shields.io/npm/v/koishi-plugin-memes?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-memes)

[MemeGenerator](https://github.com/MemeCrafters/meme-generator)([RS](https://github.com/MemeCrafters/meme-generator-rs))表情生成，全功能支持，可自由配置黑名单。

## ✨ 功能特性

- **双后端兼容**: 完美支持 Python (FastAPI) 和 Rust (axum) 版本的后端，插件启动时会自动检测并适配。
- **丰富的指令集**: 提供包括表情制作、列表查看、模板搜索、详情查询、随机表情在内的全套功能。
- **强大的图像工具 (仅限 RsAPI)**: 当使用 `meme-generator-rs` 后端时，可启用一系列高级图像处理功能，如翻转、灰度化、反色、旋转、裁剪、尺寸调整以及 GIF 分解、倒放、合并等。
- **灵活的参数输入**: 支持文本、图片、用户`@`提及作为表情素材，并能自动补充用户头像。
- **智能的参数处理**:
  - 当缺少必要参数时，会提示用户补充，并在时限内等待输入。
  - 可配置自动填充默认文本、忽略多余参数等。
- **关键词与快捷指令触发**: 可配置通过关键词（有/无前缀）快速生成表情，并支持模板自带的快捷指令。
- **高度可定制**:
  - 可自定义模板列表的排序方式、渲染模板和图标显示。
  - 可为新模板添加 "新" 标记。
  - 可在特定群组中禁用指定的表情模板。

## ⚙️ 配置选项

### 基础配置

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `apiUrl` | `string` | `http://127.0.0.1:2233` | 后端 API 服务地址。 |
| `cacheAllInfo` | `boolean` | `true` | 是否在启动时缓存所有模板的详细信息，可加快后续响应速度。 |
| `debug` | `boolean` | `false` | 是否显示调试信息。 |

### 参数配置

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `useUserAvatar` | `boolean` | `true` | 当模板需要图片但未提供时，自动使用发送者的头像进行补充。 |
| `fillDefaultText` | `'disable' \| 'insufficient' \| 'missing'` | `'missing'` | **自动补充默认文本的策略。** `disable`: 关闭； `missing`: 仅当用户未提供任何文本时补充； `insufficient`: 当用户提供的文本数量不足时补充。 |
| `ignoreExcess` | `boolean` | `true` | 是否自动忽略用户提供的多余文本或图片参数。 |

### 其它配置

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `triggerMode` | `'disable' \| 'noprefix' \| 'prefix'` | `'disable'` | **关键词触发模式。** `disable`: 关闭； `noprefix`: 无需前缀直接触发； `prefix`: 需要匹配全局指令前缀触发。 |
| `sendRandomInfo` | `boolean` | `true` | 使用 `memes.random` 命令时，是否额外发送所用模板的名称信息。 |
| `blacklist` | `object[]` | `[]` | **表情禁用规则。** 可配置在指定群组 (`guildId`) 禁用特定模板 (`keyId`)。`guildId` 留空则为全局禁用。 |

### 菜单配置

| 配置项 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `sortListBy` | `string` | *(无)* | **模板列表的排序方式。** 支持按表情名、关键词、拼音、创建/修改时间升序或降序排列。 |
| `listTextTemplate` | `string` | *(无)* | 自定义列表渲染时的文字模板。 |
| `showListIcon` | `boolean` | `false` | 是否在渲染的列表图片中为模板添加分类图标。 |
| `markAsNewDays` | `number` | `0` | 将最近 N 天内更新的模板标记为 "新"。设置为 0 则禁用。 |

## 📖 指令用法

### 核心指令

- **`memes.list`**
  - 功能: 显示所有可用的表情模板列表。
  - 说明: 若安装并配置了 `koishi-plugin-puppeteer`，将以图片形式展示。否则，以文本形式展示。

- **`memes.make <模板名/关键词> [参数...]`**
  - 功能: 根据指定的模板制作表情。
  - 示例:
    - `memes.make 摸 @用户` (使用`@`的用户头像)
    - `memes.make 远离 "远离" "色图"` (使用引号传递带空格的文本)
    - `memes.make some_template --arg=value` (传递选项参数)

- **`memes.info <模板名/关键词>`**
  - 功能: 查询指定模板的详细信息。
  - 说明: 会列出模板的关键词、所需参数、默认文本、可用选项和快捷指令，并附带一张预览图。

- **`memes.search <关键词>`**
  - 功能: 根据关键词或标签搜索相关的表情模板。

- **`memes.random [参数...]`**
  - 功能: 随机选择一个模板并制作表情。

### 图像工具 (仅在使用 `meme-generator-rs` 后端时可用)

- **`memes.img <图片>`**
  - 功能: 对单张图片进行处理。
  - 选项:
    - `-hf`, `--hflip`: 水平翻转
    - `-vf`, `--vflip`: 垂直翻转
    - `-g`, `--grayscale`: 灰度化
    - `-i`, `--invert`: 反色
    - `-r <度数>`, `--rotate <度数>`: 旋转图片
    - `-s <宽|高>`, `--resize <宽|高>`: 调整尺寸 (例如: `-s 200|` 或 `-s |300`)
    - `-c <左|上|右|下>`, `--crop <左|上|右|下>`: 裁剪图片 (例如: `-c 10|10|100|100`)

- **`memes.gif <图片>`**
  - 功能: 对 GIF 动图进行处理。
  - 选项:
    - `-s`, `--split`: 分解 GIF 为多张静态图并合并展示。
    - `-r`, `--reverse`: 倒放 GIF。
    - `-d <秒>`, `--duration <秒>`: 调整 GIF 每帧的间隔时间。

- **`memes.merge <图片...>`**
  - 功能: 合并多张图片。
  - 选项:
    - `-hz`, `--horizontal`: 水平合并。
    - `-vt`, `--vertical`: 垂直合并。
    - `-g [秒]`, `--gif [秒]`: 合并为 GIF，可指定帧间隔 (默认为 0.1s)。

- **`memes.stat <标题> <类型> <数据>`**
  - 功能: 生成数据统计图。
  - 说明: `类型`为 `meme_count` 或 `time_count`，`数据`格式为 `key1:value1,key2:value2...`。

## 💡 使用说明

- **提供图片/用户参数**:
  - **`@用户`**: 在指令中直接`@`某人，插件会自动获取其头像作为图片参数。
  - **发送图片**: 在发送指令的同时附带图片，或回复一条带图片的消息。
  - **自动补充**: 如果模板需要图片但未提供，插件会根据 `useUserAvatar` 配置自动使用发送者的头像。

- **为图片指定名称 (仅限 RsAPI)**:
  - 在图片参数后紧跟 `==名称` 即可为该图片指定一个特定的名字。这个名称可能会被某些需要展示用户名的模板使用。
  - 如果不指定，则默认使用发送者的昵称。
  - **示例**: `memes.make <模板> [图片1] ==张三 [图片2] ==李四`

- **提供文本参数**:
  - 多个文本参数请用**空格**隔开。
  - 如果某段文本自身包含空格，请用**英文双引号** (`"`) 将其括起来。

- **提供选项参数**:
  - 使用格式 `--选项名=值` (例如: `--color=red`)。
  - 对于开关类型的选项 (布尔值)，可直接使用 `--选项名` 来表示 `true`。

### 快捷触发示例

当 `triggerMode` 设置为 `prefix` (需要指令前缀，推荐) 或 `noprefix` (无需前缀) 时，可快速生成表情。

- **prefix 模式**: 若指令前缀为 `/`
  - `/摸 @小明` -> 自动执行 `memes.make 摸 @小明`

- **noprefix 模式**: (可能造成误触发，请谨慎使用)
  - `摸 @小明` -> 自动执行 `memes.make 摸 @小明`