@enderhorror/koishi-plugin-media-luna

基于 media-luna（koishi-plugin-media-luna）的增强分支。

中间件驱动的多媒体生成插件，支持多种 AI 图像/音视频连接器与 WebUI 管理。

安装

npm install @enderhorror/[email protected] \
  --registry https://registry.npmjs.org/ \
  --legacy-peer-deps

若仍有 peer 冲突，--legacy-peer-deps 必须保留（与 ChatLuna 1.3/1.4 混用有关，与本插件无关）。

安装后在 Koishi 配置中引用该包。内部服务名仍为 mediaLuna，请勿与原版 media-luna 同时启用以免冲突。

相比原项目修改了什么

原项目：koishi-plugin-media-luna（上游 ziyi233/media-luna）

本包：@enderhorror/[email protected]

1. 连接器错误码映射（errorMappings）

• 每个连接器配置表可配置错误映射：
  • matchType：serviceCode / httpStatus / keyword
  • matchValue：错误码、HTTP 状态或关键词
  • message：对用户显示的中文说明
  • suggestion：处理建议（仅配置侧；默认不对用户聊天/WebUI 展示）
  • retryable：是否允许自动重试
• 匹配范围：错误对象、cause 链、响应正文/片段
• 优先级：服务错误码 → HTTP 状态 → 关键词 → 内置分类 → 安全兜底

2. 全局重试策略

• 新增配置项 retryAttempts（默认 1，含首次请求）
• 仅在以下情况重试：
  • 网络错误 / 限流 / 超时（未映射时的默认行为）
  • 映射命中且 retryable=true（强制可重试）
  • 映射命中且 retryable=false（强制不重试）
• 连接器抛错时尽量保留 { cause }，避免映射/重试信息丢失

3. 用户侧错误展示（更安全、更短）

• 聊天与 WebUI 不再默认展示 API 地址、原始英文堆栈、失败原因/处理建议等技术细节
• 展示：错误类型（分类标签）+ 尝试次数（如 2/3）+ 任务 ID / 耗时等元信息
• 完整诊断写入服务端日志与任务记录

4. 批量生成 -n 1..5

• 渠道指令支持 -n <数量>（1–5，默认 1）
• 按顺序逐次完整生成（非并发）
• 每一次独立：预扣费提示 → 进度提示 → 结果投递 → 任务记录
• 示例：bnn 一只可爱的猫咪 -n 3

5. 进度消息撤回策略

• 生成结束：立即撤回进度提示
• 若任务超过 90 秒仍未结束：到点自动撤回（适配平台撤回时限）
• 避免进度气泡长期残留

6. 引用消息 / 媒体提取增强

• QQ / OneBot / Red 等平台引用消息：仍收集引用中的图片
• 不会把被引用消息发送者的头像误当参考图
• 当前消息正文中显式 @用户 仍会收集头像

7. 包与发布

| 项 | 原项目 | 本增强版 | |----|--------|----------| | npm 包名 | koishi-plugin-media-luna | @enderhorror/koishi-plugin-media-luna | | 内部服务 | mediaLuna | mediaLuna（保持） | | 数据/目录语义 | media-luna | media-luna（保持） |

功能特性（继承自原项目）

• 多连接器：DALL-E、SD WebUI、Flux、Chat API、Gemini、ChatLuna、ComfyUI、豆包、Suno、Runway 等
• 预设系统：提示词模板与远程同步
• 中间件管道：计费、缓存、翻译等可插拔流程
• WebUI：Koishi Console 可视化配置
• 任务记录：生成历史与统计

快速开始

首次使用必读：请按顺序配置，确保每一步正确。

第一步：配置缓存存储（重要）

进入设置 → 插件 → cache。

必须正确配置 publicBaseUrl（或 S3/WebDAV 的公开访问地址），否则预设图与生成结果无法正常显示/发送。

推荐 MinIO（S3 兼容）：

请使用 RELEASE.2025-04-22T22-12-26Z 或更早版本。
Bucket Access Policy 需为 public。

docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -e MINIO_ROOT_USER=admin \
  -e MINIO_ROOT_PASSWORD=your-password \
  -v /data/minio:/data \
  quay.io/minio/minio:RELEASE.2025-04-22T22-12-26Z \
  server /data --console-address ":9001"

cache 插件示例：

• backend: s3
• s3Endpoint: http://your-server:9000
• s3AccessKeyId / s3SecretAccessKey
• s3Bucket: media-luna
• s3PublicBaseUrl: http://your-server:9000/media-luna
• s3ForcePathStyle: true

也可使用本地存储 / WebDAV；服务器部署务必配置外网可访问的 publicBaseUrl。

第二步：启用预设同步

设置 → 插件 → preset：确认 apiUrl，开启 autoSync，点击「同步预设」。

第三步：创建渠道

渠道页：名称（即指令触发词）→ 连接器 → API Key / 模型 → 标签。

第四步：使用

bnn 一只可爱的猫咪
bnn 一只可爱的猫咪 -n 3

或通过 WebUI「生成」页直接生成。

指令说明

查询

| 指令 | 说明 | |------|------| | models | 可用模型 | | presets | 预设列表 | | preset <名> | 预设详情 | | loras | 已挑选 LoRA | | mytasks | 我的任务 | | taskinfo <id> | 任务详情 |

生成格式

渠道名 [预设名] 文字 [图片...] [-n 数量]

1. 完整指定：渠道名 预设名 文字 【图1】【图2】（≥2 张图直接触发）
2. 省略预设：渠道名 文字 【图1】【图2】
3. 收集模式：图片不足时进入收集，发送「开始」触发
4. 引用消息：引用与当前消息合并处理（见上方增强说明）

其它能力

• @用户：替换为对应用户头像
• LoRA：qwen image / z-image 等可用 #xx/xxxx#
• 润色：提示词含「润色」时优化提示词（部分模型）
• 分辨率：1024x1024、9:16、横屏、竖屏 等（视模型支持）
• 批量：-n 1..5，顺序逐次完整生成

配置说明

全局配置

| 配置项 | 说明 | 默认值 | |--------|------|--------| | logLevel | 日志级别 | info | | retryAttempts | 连接器总尝试次数（含首次） | 1 |

错误码映射（渠道连接器）

| 列 | 说明 | 示例 | |----|------|------| | matchType | serviceCode / httpStatus / keyword | httpStatus | | matchValue | 匹配值 | 429 | | message | 用户可见说明 | 当前请求过多，请稍后再试 | | suggestion | 处理建议（配置用，默认不对用户展示） | 等待一分钟后重试 | | retryable | 是否自动重试 | true |

计费插件 (billing)

| 配置项 | 说明 | 默认 | 可渠道覆盖 | |--------|------|------|------------| | tableName | 表名 | monetary | 否 | | userIdField | 用户字段 | uid | 否 | | balanceField | 余额字段 | value | 否 | | currencyField | 货币类型字段 | currency | 否 | | currencyLabel | 显示名 | 积分 | 否 | | refundOnFail | 失败退款 | true | 否 | | cost | 单次费用 | 0 | 是 | | currencyValue | 货币类型值 | default | 是 |

模板变量：{cost} {balance} {label} {error}

缓存插件 (cache)

| 后端 | 说明 | |------|------| | local | 本地文件 | | s3 | S3 / MinIO / OSS | | webdav | WebDAV | | none | 禁用 |

本地关键项：cacheDir、publicPath、publicBaseUrl、maxCacheSize、maxFileSize、expireDays。

预设 / 任务 / 指令

| 插件 | 关键项要点 | |------|----------| | preset | enabled、defaultPreset、apiUrl、autoSync、syncInterval、deleteRemoved | | task | enabled、autoCleanup、retentionDays | | koishi-commands | enabled、collectTimeout、directTriggerImageCount |

连接器（摘录）

| 连接器 | 主要参数 | |--------|----------| | DALL-E | apiUrl, apiKey, model | | SD WebUI | apiUrl | | Flux | apiUrl, apiKey | | Chat API | apiUrl, apiKey, model | | Gemini | apiUrl, apiKey, model | | ChatLuna | model（需 chatluna） | | Midjourney | apiUrl, apiKey | | Stability | apiKey, model | | ComfyUI | apiUrl | | 豆包 | apiUrl, apiKey, model | | Suno | apiUrl, apiKey | | Runway | apiUrl, apiKey, model |

以上连接器均可配置 errorMappings。

WebUI

| 页面 | 功能 | |------|------| | 生成 | 浏览器内生成 | | 渠道 | 渠道与连接器配置（含错误映射） | | 预设 | 预设模板 | | 任务 | 历史与统计 | | 设置 | 全局与插件配置 |

与原版关系

• 本仓库基于上游 media-luna 二次修改，不是官方维护包。
• 问题可在本增强维护方反馈；通用能力也可对照上游 issues。
• 更多架构说明见 docs/。

License

MIT（与上游一致）