koishi-plugin-ai-image-agnes

项目介绍 (Project Introduction)

中文

一款为 Koishi 聊天机器人框架开发的 AI 绘图插件，深度集成 Agnes ，提供高质量的文生图、图生图及多图合成能力。
针对高信息密度图像和复杂构图进行了深度优化，能够更好地还原复杂场景、丰富细节和视觉层次。

内置多 API 负载均衡、图片压缩、Base64 自动转换、预置提示词、主/副模型分离、调试日志、上传等待与清理机制，配置灵活、开箱即用、稳定可靠。
图生图支持同时发送多张参考图片，并可自定义最大图片数量。
生成完成后自动清理临时上传的参考图片，避免存储堆积。

English

An AI image generation plugin for the Koishi chatbot framework, **deeply integrated with Agnes **, providing high-quality text-to-image, image-to-image, and multi-image composition.
Optimized for high-information-density images and complex compositions, ensuring rich details and accurate semantic alignment.

Built‑in multi‑API load balancing, image compression, automatic Base64 conversion, preset prompts, primary/secondary model separation, debug logging, upload wait and cleanup mechanism.
Image‑to‑image supports multiple reference images with configurable maximum count.
Temporary uploaded reference images are automatically cleaned up after generation.

核心指令 (Core Commands)

| 指令 (Command) | 说明 (Description) | 示例 (Example) | |----------------|--------------------|----------------| | draw <提示词> | 进入收集模式：可发送文字/图片，输入「开始」生成，「取消」退出。支持 -p <预设> 直接应用预置提示词模板。 (Enter collection mode: send text/images, then "start" to generate. Use -p <preset> to apply a preset prompt template.) | draw 一只猫 -p 动漫风格 | | draw2 <提示词> | 使用副模型进入收集模式，操作同 draw。 (Same as draw but using the secondary model.) | draw2 一只猫 | | redraw | 重绘上一次的文生图结果。 (Redraw the last text-to-image result.) | redraw |

配置项说明 (Configuration)

基本设置 (Basic Settings)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | debug | boolean | false | 调试模式，输出完整请求/响应日志 (Debug mode, logs full request/response) | | timeout | number | 300000 | API 请求超时时间（毫秒） (Request timeout in ms) | | rateLimit | number | 200 | 每小时调用次数上限 (Hourly call limit) | | collectTimeout | number | 120 | 收集模式等待用户输入的超时秒数 (Collection mode wait timeout in seconds) | | defaultImageSize | string | 2K | 全局默认图片尺寸档位（如 1K, 2K, 3K, 4K） (Global default image size level, e.g., 1K, 2K, 3K, 4K) | | maxImages | number | 5 | 图生图最大支持图片数量 (Max reference images) | | imageSendMode | string | image | 图片发送方式：image（仅图片） / url（仅链接） / both（图片+链接） (Send mode: image, url, both) | | enableForward | boolean | true | 多图结果是否使用合并转发 (Use forward message for multiple images) | | enableTxt2Img | boolean | true | 启用文生图功能 (Enable txt2img) | | enableImg2Img | boolean | true | 启用图生图功能 (Enable img2img) | | defaultResponseImageFormat | string | url | 全局默认图片数据格式：url（直链） / pure_base64（Base64） (Global default image format: url, pure_base64) | | imageUploadWaitTime | number | 10 | 图生图上传图片后等待时间（秒），最小为 0，仅整数 (Wait time after uploading reference images in seconds, min 0, integer only) |

扩展功能 (Extended Features)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | imageCompression.enable | boolean | false | 启用图片压缩（需安装 sharp 模块） (Enable image compression, requires sharp) | | imageCompression.maxWidth | number | 1024 | 压缩后最大宽度 (Max width after compression) | | imageCompression.maxHeight | number | 1024 | 压缩后最大高度 (Max height after compression) | | imageCompression.quality | number | 80 | JPEG 压缩质量 0-100 (JPEG quality 0-100) | | imageInputAsBase64 | boolean | false | 图生图时将参考图片转为 Base64 发送 (Convert reference images to Base64 for img2img) | | presetPrompts | array | [] | 预置提示词列表，每项包含 name（名称）、keywords（触发关键词数组）、template（提示词模板，支持 {prompt} {keyword} 变量） (List of preset prompts: name, keywords array, template with {prompt} and {keyword} variables) |

主模型设置 (Primary Model)

主模型始终使用自定义 API 列表，支持多个端点与负载均衡。
The primary model always uses a custom API list with multiple endpoints and load balancing.

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | apiStrategy | string | roundrobin | 主模型调度策略：sequence（顺序） / roundrobin（轮询） (Load balancing strategy for primary model) | | primaryApiList | array | [] | 主模型 API 条目列表，每个条目包含以下配置 (List of primary API entries, each with the following fields) |

API 条目公共配置 (API Entry Common Fields)（主模型与副模型通用）

注意： 该插件已深度集成 Agnes API，无需配置 adapterType 或 bodyTemplate。

| 字段 (Field) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |--------------|-------------|-------------------|---------------------| | enable | boolean | true | 是否启用此 API (Enable this API) | | endpoint | string | https://apihub.agnes-ai.com/v1/images/generations | API 端点 (Endpoint) | | apiKey | string | (空) | API 密钥 (API key) | | model | string | agnes-image-2.1-flash | 模型名称 (Model name) | | img2imgModel | string | (空) | 图生图专用模型，留空使用主模型 (Img2img model, falls back to primary) | | imageSize | string | (空) | 图片尺寸档位（如 1K, 2K, 3K, 4K），留空使用全局默认 (Image size level, falls back to global default) | | responseImageFormat | string | (空) | 图片数据格式：url / pure_base64，留空跟随全局 (Image format, falls back to global) | | txt2imgPrompt | string | (空) | 文生图提示词模板，支持 {prompt} (Prompt template for txt2img) | | img2imgPrompt | string | (空) | 图生图提示词模板，支持 {prompt} (Prompt template for img2img) | | customHeaders | string | 预设 (Preset) | 自定义请求头 JSON，支持 {apiKey} 变量 (Custom headers JSON) |

副模型设置 (Secondary Model)

副模型通过 draw2 指令调用，其 API 列表完全独立于主模型；若副模型列表为空，则自动回退到主模型的 primaryApiList。
The secondary model is invoked via the draw2 command. Its API list is completely independent; if empty, it falls back to the primary primaryApiList.

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | secondaryApi.enable | boolean | false | 启用副模型功能 (Enable secondary model) | | secondaryApi.strategy | string | roundrobin | 副模型调度策略：sequence / roundrobin (Load balancing strategy for secondary model) | | secondaryApi.list | array | [] | 副模型 API 条目列表，结构与主模型条目完全相同（留空则使用主模型列表） (Secondary API entry list, same structure as primary entries; if empty, uses primary list) |

副模型列表的每个条目配置项与主模型 API 条目完全一致，详见上方 API 条目公共配置 表格。
Each entry in the secondary list has the same fields as a primary API entry; see the API Entry Common Fields table above.

代理设置 (Proxy Settings)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | proxyEnabled | boolean | false | 启用 HTTP/HTTPS 代理 (Enable proxy) | | proxyProtocol | string | http | 代理协议：http / https (Proxy protocol) | | proxyHost | string | (空) | 代理地址 (Proxy host) | | proxyPort | number | 8080 | 代理端口 (Proxy port) | | proxyAuth | boolean | false | 代理是否需要认证 (Proxy requires auth) | | proxyUsername | string | (空) | 代理用户名 (Proxy username) | | proxyPassword | string | (空) | 代理密码 (Proxy password) |

消息文本 (Messages)

| 配置项 (Config) | 类型 (Type) | 默认值 (Default) | 说明 (Description) | |----------------|-------------|-------------------|---------------------| | messages.* | object | 见配置页 (See schema) | 所有提示文案均可自定义，支持模板变量 (All messages customizable, supports template variables) |

依赖 (Dependencies)

• 图生图 (img2img)：需要 assets 服务及正确的 selfUrl 配置。 (Requires assets service and correct selfUrl)
• 图片压缩 (optional)：需要安装 sharp 模块。 (Optional: sharp module for compression)

项目贡献者 (Contributors)

| 贡献者 (Contributor) | 贡献内容 (Contribution) | | --- | --- | | Minecraft-1314 | 插件完整开发 (Complete plugin development) | | （欢迎提交 PR / Issues 加入贡献者列表） | | (Welcome to join the contributor list via PR or Issues) |

许可协议 (License)

本项目采用 MIT 许可证，详情参见 LICENSE 文件。

This project is licensed under the MIT License, see the LICENSE file for details.

支持我们 (Support Us)

如果这个项目对您有帮助，欢迎点亮右上角的 Star 支持我们，这将是对所有贡献者最大的鼓励！

If this project is helpful to you, please feel free to star it in the upper right corner to support us, which will be the greatest encouragement to all contributors!

问题反馈 (Feedback)

如有问题或建议，可通过 Issues 提交反馈。

If you have any questions or suggestions, please submit feedback via Issues.