koishi-plugin-aka-ai-image-generator

自用 AI 图像生成插件 V2（image-only）。当前 0.6.3 版本采用供应商凭证 + 模型路由配置界面，支持在每条模型映射中显式选择供应商、运行时协议与积分单价，并使用积分制计费、用户数据 v2 和精简后的账户命令体系。

范围：仅图像生成。视频生成、ChatLuna 桥接和 Console WebUI 不在当前运行时范围内；0.6.x 聚焦积分制计费、账本、充值审计和用户数据 v2。

当前版本状态

• 当前包版本：0.6.3。
• 当前稳定能力：供应商凭证分区、模型映射显式 supplier + protocol 路由、模型级积分单价、OpenAI-compatible 图像站点、OpenAI 官方 GPT、Gemini 官方、openai 协议、gemini 协议、基础图像命令、通用合成图、动态 styles / styleGroups 快捷命令、配置重载后动态命令刷新、styles 默认模式 / 默认模型、紧凑控制台表格列名、设置页顶部命令速查、紧凑命令帮助、紧凑图像参数帮助、simple / detail 日志级别、最终失败显式聊天提示、统一聊天输出文案、显式 -n、受限模型权限拦截、用户自助查询、用户自助账单、管理员查询、用量排行榜、管理员充值与余额修正、积分账单、用户数据 v2、积分流水账本、充值审计、积分制限流和豁免能力。
• 当前活跃计划：0.6.x 积分制计费 + 用户数据 v2 已进入 release preparation；后续仅根据远端验证日志做 patch 修复。
• 当前插件路线图：见 ROADMAP.md。
• 手动发布入口：从仓库根目录执行 ./push.sh aka-ai-image-generator。

支持的供应商入口 / 模型路由

控制台顶层只暴露三类供应商凭证入口，供应商只负责 API 凭证，不直接配置模型：

• 第三方：OpenAI-compatible 第三方站点。填写 apiBase + apiKey，可选额外请求头。
• OpenAI：OpenAI 官方 GPT。只填写 API key，固定使用 OpenAI 官方 base。
• Gemini：Gemini 官方。只填写 API key，固定使用 Google Gemini 官方 base。

模型统一在模型映射表中配置。每条模型映射都是一条模型路由：

• suffix：命令参数和 styles 预设引用的模型后缀。
• modelId：真实上游模型 ID。
• supplier：该模型使用哪个供应商凭证入口。
• protocol：该模型使用哪个运行时协议 / 通道。
• restricted：是否仅允许管理员或模型白名单用户使用。
• creditCostPerImage：该模型每张图片消耗的积分，支持小数；为空时使用全局默认单价。

当前运行时协议：

• openai：OpenAI API，调用 /v1/images/generations 与 /v1/images/edits。
• gemini：Gemini generateContent 协议，调用 /v1beta/models/{model}:generateContent。

推荐组合：

• OpenAI 官方 GPT：供应商选 OpenAI，协议选 openai。
• 第三方 GPT Images：供应商选第三方，协议选 openai。
• 第三方 Gemini generateContent（如云雾）：供应商选第三方，协议选 gemini。
• Gemini 官方：供应商选 Gemini，协议选 gemini。

配置页里的次数、窗口、超时等数值字段使用数字输入，不使用滑竿。低频设置使用 Koishi Schema 的嵌套 .collapse() 模式默认收起。配置页顶部提供只读“使用说明 / 命令速查”，用纯文本分区展示首次配置顺序、普通用户命令、管理员命令、常用参数和权限规则。配置页文案采用分层策略：下拉选项和表格列名保持极简，字段描述适度说明用途、单位和权限影响；表格列名优先使用短标签，减少控制台多行换行。日志级别使用 simple / detail：simple 记录关键流程，detail 额外记录脱敏请求诊断。

命令（v0.6.3）

命令统一采用无前缀直呼格式，不使用 aig. 前缀。

| 命令 | 别名 | 说明 | | --- | --- | --- | | 文生图 [prompt] | t2i | 纯文字描述生成图片 | | 图生图 [img] [prompt] | i2i | 单张图片 + 修改描述 | | 合成图 [-n 数量] | compose-image | 命令后收集多张图片，收到 prompt 文字后开始合成 | | 图像查询 [@用户] | - | 无 @ 时查询自己的积分余额和生成统计；管理员可 @用户 查询他人 | | 图像账单 [@用户] [-n 数量] | - | 无 @ 时查询自己的最近流水；管理员可 @用户 查询他人 | | 图像账单 --all [-n 数量] | - | 管理员查看全局最近积分流水 | | 图像充值 @用户 积分 [原因] | - | 管理员给用户充值；积分为负数时作为余额修正 | | 图像排行榜 [-n 数量] | - | 管理员查看用户生成 / 消耗排行，默认按历史消耗排序 | | 图像指令 | - | 查看核心生成命令和当前快捷命令 | | 图像参数 | - | 查看通用参数、尺寸、比例和受限模型后缀 | | styles / styleGroups 动态命令 | - | 配置页维护的 prompt 预设，可选择文生图 / 图生图 / 合成图模式与默认模型后缀；重载配置后会重新注册 |

当前基础修饰符：

• -n <数量>：一次生成图片数量，范围 1-4；未填写时使用 defaultNumImages。
• -1k / -2k / -4k：预设分辨率。
• -1024x1024：自定义分辨率。
• -1:1 / -4:3 / -16:9 / -9:16 / -3:2 / -2:3：画幅比例。
• -add <补充要求>：追加生成要求。
• -模型后缀：切换到配置中的模型映射。

模型映射权限：

• restricted = false 的模型后缀正常调用。
• restricted = true 的模型后缀仅管理员和模型白名单用户可用。
• 永久会员只跳过额度和限流，不自动获得受限模型权限。

styles 与 styleGroups 预设支持 mode 与 modelSuffix：mode 决定默认走文生图、图生图或合成图链路；modelSuffix 引用模型映射后缀。用户在命令中显式填写模型后缀时，优先级高于 style 默认模型。配置重载时，动态快捷命令会先注销旧命令再按最新配置重新注册。图像指令 展示核心生成命令、当前快捷命令、账户命令和管理员命令入口；图像参数 独立展示参数、尺寸、比例、积分规则和受限模型后缀。

积分计费：

• 默认每张图片消耗 defaultCreditCostPerImage 积分；模型映射可用 creditCostPerImage 覆盖；积分支持最多两位小数。
• 生成前按请求张数预检，生成后按成功发送到聊天窗口的图片数扣费。
• 当部分图片生成或发送成功时，只按成功发送图片数扣费。
• 管理员、永久会员和 unlimitedPlatforms 平台跳过积分扣费和限流，但仍记录生成统计。
• 模型白名单只允许调用 restricted 模型，不代表免费。
• 用户数据保存为 users.v2.json；流水保存为 credit-ledger.v2.jsonl；充值审计保存为 recharge-records.v2.jsonl。

版本进度

• v0.1.x：架构骨架（Provider Registry + Tagged Union Schema + 多 Provider 验证）。
• v0.2.x：MVP（Service + 简化版 Orchestrator + 文生图 / 图生图 / 额度查询命令）。
• v0.3.0：OpenAI 兼容图像端点验证 MVP（无前缀命令 + 图像协议选择）。
• v0.4.0：协议优先配置重写（控制台改为图像协议通道，移除历史供应商顶层选项与注册别名）。
• v0.5.0：供应商语义 UI 重写（控制台顶层仅保留 openai-compatible / openai-official / gemini-official，OpenAI 兼容入口内部选择图像协议；数值配置改为数字输入）。
• v0.5.1：尝试修复 OpenAI 兼容入口选择后配置项未展开的问题；后续确认该 Tagged Union 结构在控制台中仍不稳定。
• v0.5.2：修复供应商设置整体消失问题，改为稳定对象分组结构，并修复模型映射跨运行时 Provider 时的凭证来源错误。
• v0.5.3：清理当前阶段不应暴露的 ChatLuna 集成配置、未实现命令族常量和后续阶段运行时代码残留；当前阶段只保留 文生图、图生图、图像额度。
• v0.5.4：增强 OpenAI / OpenAI-compatible 调用链路脱敏诊断日志和错误归一化上下文，便于远端排查 base URL、模型、HTTP 状态、网络错误与超时问题。
• v0.5.5：将 OpenAI 兼容、OpenAI 官方、Gemini 官方三类供应商详细配置合并到默认收起抽屉中，保留稳定对象分组，避免重新引入 tagged union 渲染不稳定问题。
• v0.5.6：新增 图像指令、参数指令，给 文生图 / 图生图 显式注册 -n <num:number>，并在命令入口拦截 restricted 模型后缀。
• v0.5.7：将供应商详细设置改为顶层供应商分组内的嵌套折叠对象，并在服务层兼容读取旧版 flat 配置字段。
• v0.5.8：新增 合成图、图像查询 @用户、图像排行榜 [-n 数量]、动态 styles 命令分发、styles 默认模式 / 默认模型，并优化配置页分组顺序。
• v0.5.9：供应商与模型分离，供应商仅保存凭证，模型映射统一保存模型 ID 与协议。
• v0.5.10：修复模型映射无法显式选择供应商的问题，新增 supplier + protocol 模型路由，并让 gpt-official 凭证可被模型映射使用。
• v0.5.11：精简 Koishi Console 配置页文案，模型路由、供应商凭证、Prompt 预设、权限、配额、安全和通用设置均改为短标签。
• v0.5.12：修复上游失败后图像任务锁可能残留的问题，任务锁新增 requestId 与 TTL 兜底清理。
• v0.5.13：协议名称收敛为 openai / gemini，移除不使用的聊天补全图像通道。
• v0.5.14：精简控制台供应商显示名，模型路由中只显示第三方 / OpenAI / Gemini。
• v0.5.15：修复配置重载后 styles / styleGroups 新增快捷命令不生效的问题，并让 图像指令 展示动态快捷命令。
• v0.5.16：调整 Koishi Console 配置说明文案，字段描述补充用途、单位和权限影响，选项文本保持极简。
• v0.5.17：新增配置页顶部只读初始化说明，引导首次配置顺序和关键概念。
• v0.5.18：重写 图像指令 与 参数指令 输出，核心命令、快捷命令和参数可选项改为紧凑分区格式。
• v0.5.19：统一润色聊天可见输出，额度、查询、排行榜、输入引导、生成状态、失败和权限提示改为短标题与一行式条目格式。
• v0.5.20：将参数帮助命令从 参数指令 改名为 图像参数，让两个帮助入口统一以 图像 开头。
• v0.5.21：将日志级别显示改为 simple / detail，并让 detail 通过插件配置显式控制脱敏请求诊断日志。
• v0.5.22：精简模型映射与 Prompt 预设表格列名，降低 Koishi Console 表头换行。
• v0.5.23：最终生成失败、未返回图片和内容安全拦截提示改为显式发送到聊天窗口，降低长耗时命令依赖 action 返回值自动回复的风险。
• v0.6.0：引入积分制计费、用户数据 v2、积分流水账本、充值审计、模型级积分单价、管理员充值 / 扣除 / 查账命令和积分化聊天输出。
• v0.6.1：移除模型映射中的上游成本 / 定价备注配置，仅保留用户侧积分单价；积分配置改为支持小数。
• v0.6.2：修复管理员扣除 0 或不足额时的聊天反馈，并让豁免用户首次统计记录使用当前配置初始化积分快照。
• v0.6.3：删除 图像额度 和 图像扣除 固定命令；图像查询 接管用户自助查询；图像账单 支持用户自助流水和管理员全局流水；图像充值 支持负数余额修正；设置页顶部扩展为命令速查。

后续计划

• 0.6.x：根据目标 Koishi 环境远端验证日志修复计费、账本、配置兼容或上游返回差异问题。
• 后续大功能：Console WebUI、ChatLuna bridge 和迁移工具仍保持 deferred，不进入当前运行时范围。

远端验证建议

用户发布并在目标 Koishi 环境升级后，建议优先验证：

1. 配置页顶部显示 📌 使用说明 / 命令速查 只读引导，并按首次配置、普通用户、管理员、常用参数、权限说明分区展示；供应商凭证、模型映射、Prompt 预设 / 快捷命令、管理员与运营、用户豁免与白名单、积分计费与限流、安全策略、通用设置分组显示；低频权限、计费与安全策略默认折叠。
2. 模型映射每行可显式设置供应商、接口格式、受限状态和每张积分；每张积分支持小数；供应商显示为第三方 / OpenAI / Gemini，并能区分 OpenAI 官方 GPT、OpenAI-compatible GPT、OpenAI-compatible Gemini、Gemini 官方。
3. styles 每行可设置生成模式和生成模型，模型映射分组位于 Prompt 预设分组上方；在 styleGroups 中新增如 手游化 的快捷命令后点击重载配置，无需外部重启即可直接调用。
4. OpenAI-compatible + openai 可完成 文生图 一只猫；OpenAI-compatible + gemini 可调用云雾等第三方 Gemini generateContent 端点。
5. 文生图 -n 2 一只猫 按 2 张图进行积分预检；若模型单价为 1，则预计消耗 2 积分。
6. 将某个模型映射的 creditCostPerImage 改为 3 后，使用对应模型后缀生成 2 张图时应按 6 积分预检，并按成功发送图片数扣费。
7. 普通用户余额不足时，聊天窗口返回 积分不足，并显示需要积分、今日免费、已购余额和合计可用。
8. 生成成功后，普通用户执行 图像查询 返回 图像查询 标题与用户、今日免费、已购余额、合计可用、已生成、历史消耗等条目。
9. 当部分图片生成或发送成功时，只按成功发送到聊天窗口的图片数扣费；最终完成提示里的本次消耗应与实际发送图片数一致。
10. 管理员执行 图像充值 @用户 20 测试充值 后，用户已购余额增加，聊天输出包含本次充值、已购余额、合计可用和流水号。
11. 管理员执行 图像充值 @用户 -5 测试修正 后，从用户已购余额中安全修正，并写入积分流水；如果已购余额不足，应显示部分调整或调整失败，而不是普通充值完成。
12. 普通用户执行 图像账单 -n 10 返回自己的最近流水；管理员执行 图像账单 @用户 -n 10 返回指定用户最近流水；管理员执行 图像账单 --all -n 10 返回全局最近流水。
13. 管理员执行 图像查询 @用户 返回 图像查询 标题与用户、今日免费、已购余额、合计可用、已生成、历史消耗等积分化条目；查询不存在的历史用户不会创建数据。
14. 管理员执行 图像排行榜 -n 10 返回 图像排行榜 标题，并按历史消耗优先、生成图片数次之排序。
15. 管理员、永久会员和 unlimitedPlatforms 平台可跳过积分扣费和限流，但仍记录生成统计；首次创建豁免用户数据时应按当前 dailyFreeCredits 初始化积分快照；模型白名单用户只获得 restricted 模型调用权限，不自动免费。
16. 非白名单用户调用 restricted 模型后缀会被 模型受限 分区提示拒绝，管理员和模型白名单用户可用。
17. 图像指令 展示核心生成命令、当前 styles / styleGroups 快捷命令、账户命令和管理员命令入口；图像参数 展示通用参数、尺寸、比例、积分规则和受限模型后缀。
18. 文生图 -16:9 -2k 一座城市 能带入画幅与分辨率；文生图 -add 暖色灯光 一间书房 能带入追加要求。
19. 图生图 <图片> 改成赛博朋克风格 能收集图片并发起编辑；合成图 -n 2 后连续发送多张图片，最后发送 prompt 文字后才开始执行。
20. 插件数据目录中会生成或更新 users.v2.json、users.v2.json.backup、credit-ledger.v2.jsonl、recharge-records.v2.jsonl；流水 JSONL 中不应包含 API key。
21. 输入引导、生成开始、生成完成、积分不足、内容安全拦截和上游失败提示均保持短标题与一行式条目格式，日志不泄露 API key。
22. 模拟或等待一次最终上游失败时，聊天窗口能收到 生成失败 或 内容安全拦截 提示；中间 fallback / retry 警告仍只写入日志且不扣费。
23. 日志级别为 simple 时仅记录关键流程；切换到 detail 后会额外输出请求 URL、模型路由、脱敏 headers、请求体摘要、超时、尺寸、比例和扣费诊断信息。

发布边界

本仓库默认由助手准备代码、文档、版本号、CHANGELOG 和远端验证步骤；发布由用户手动执行。

从仓库根目录发布本插件：

./push.sh aka-ai-image-generator

除非用户明确要求，助手不自动运行依赖安装、本地 typecheck、build、test、push.sh、pnpm publish 或 npm publish。