koishi-plugin-aka-ai-image-generator 0.2.0

package/README.md

@@ -0,0 +1,37 @@
+# koishi-plugin-aka-ai-image-generator
+
+[![npm](https://img.shields.io/npm/v/koishi-plugin-aka-ai-image-generator?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-aka-ai-image-generator)
+
+自用 AI 图像生成插件 V2（image-only）。
+
+> 范围：仅图像生成。视频生成不在本插件范围内。
+
+## 支持的供应商
+
+- 云雾（自适应：Gemini / OpenAI 协议）
+- GPT God
+- Google Gemini 官方
+- Grok（xAI，可经云雾中转）
+- OpenAI 兼容（任意符合 OpenAI Images API 的端点）
+- OpenAI 官方 GPT Image
+
+## 命令（v0.2.0 MVP）
+
+| 命令 | 别名 | 说明 |
+| --- | --- | --- |
+| `aig.文生图 <prompt>` | `aig.t2i` | 纯文字描述生成图片 |
+| `aig.图生图 [img] <prompt>` | `aig.i2i` | 单张图片 + 修改描述 |
+| `aig.图像额度` | `aig.quota` | 查询当前用户额度 |
+
+支持的修饰符（紧跟在命令后）：
+
+- `--n <数量>` 一次生成图片数量
+- `--model <模型>` 覆盖默认模型
+- `--ar <宽高比>` 例如 `1:1`、`16:9`
+- `--res <分辨率>` 例如 `1024x1024`
+
+## 状态
+
+- v0.1.x：架构骨架（Provider Registry + Tagged Union Schema + 6 个图像 Provider）
+- v0.2.0：MVP（Service + 简化版 Orchestrator + 文生图 / 图生图 / 额度查询命令）
+- v0.3.x（计划，Phase 5）：完整命令族（合成图 / 风格迁移 / 改姿势 / 修改设计 / 变像素 / 充值 / 参数指令）+ ChatLuna 桥接 + 用户数据迁移工具

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+import * as koishi from 'koishi';
+import { Context, Schema } from 'koishi';
+
+/**
+ * 图像生成参数
+ *
+ * 与 v1 的 ImageGenerationOptions 兼容，但移除了对 ProviderConfig 的依赖。
+ * 配置通过构造函数注入而非选项字段传递，保持本结构精简。
+ */
+interface ImageGenerationOptions {
+    /** 分辨率预设：'1k' / '2k' / '4k' 或自定义 'WIDTHxHEIGHT'（如 '1024x1536'） */
+    resolution?: '1k' | '2k' | '4k' | `${number}x${number}`;
+    /** 宽高比预设；当未指定 resolution 时由各 Provider 映射到具体尺寸 */
+    aspectRatio?: '1:1' | '4:3' | '16:9' | '9:16' | '3:2' | '2:3';
+}
+/**
+ * 流式回调：每生成一张图片就触发一次。
+ *
+ * - imageUrl 可能是远程 URL，也可能是 data:image/...;base64,... 的内嵌格式
+ * - index 从 0 开始
+ * - total 是请求的总张数（不一定等于最终成功生成数）
+ */
+type ImageGeneratedCallback = (imageUrl: string, index: number, total: number) => void | Promise<void>;
+/**
+ * 图像供应商（统一接口）
+ *
+ * v2 相比 v1 的变化：
+ * - 移除 ProviderConfig 字段（由具体子类构造函数管理）
+ * - 错误统一抛出 ProviderError 子类（见 ./errors.ts）
+ * - 通过基类 BaseImageProvider 共享 timeout / retry / 错误处理逻辑
+ */
+interface ImageProvider$1 {
+    /** Provider 标识，例如 'openai-images' / 'gemini' / 'gptgod' */
+    readonly name: string;
+    /**
+     * 生成图像
+     *
+     * @param prompt 提示词
+     * @param imageUrls 输入图片：空数组/空字符串表示文生图；否则为图生图（编辑）
+     * @param numImages 期望生成数量
+     * @param options 生成参数（分辨率/宽高比）
+     * @param onImageGenerated 流式回调（每张生成完即调用）
+     */
+    generateImages(prompt: string, imageUrls: string | string[], numImages: number, options?: ImageGenerationOptions, onImageGenerated?: ImageGeneratedCallback): Promise<string[]>;
+}
+/**
+ * Provider 工厂函数签名（registry 使用）
+ *
+ * @param ctx Koishi 上下文
+ * @param config 通过 Schema 验证后的 Provider 凭证 + 模型字段
+ */
+type ProviderFactory = (ctx: Context, config: Record<string, unknown>) => ImageProvider$1;
+
+/**
+ * Provider 注册表（7.11.4 节）
+ *
+ * 设计要点：
+ * - 注册表实例是无状态的（只持有工厂引用）
+ * - 实际 ImageProvider 实例通过 createProvider 即时构造，由调用方决定缓存策略
+ * - 名字大小写不敏感
+ *
+ * 使用示例：
+ * ```ts
+ * const registry = new ProviderRegistry()
+ * registry.register('openai-images', (ctx, cfg) => new OpenAIImagesProvider({ ctx, ...cfg }))
+ * const provider = registry.createProvider('openai-images', ctx, cfg)
+ * ```
+ */
+declare class ProviderRegistry {
+    private readonly factories;
+    /**
+     * 注册一个 Provider 工厂。重复注册会覆盖前一次。
+     */
+    register(name: string, factory: ProviderFactory): void;
+    /**
+     * 注销一个 Provider。
+     */
+    unregister(name: string): boolean;
+    /** 列出所有已注册 Provider 名（按注册顺序） */
+    list(): string[];
+    /** 是否已注册 */
+    has(name: string): boolean;
+    /**
+     * 创建一个 Provider 实例。
+     *
+     * @throws 当 name 未注册时抛出
+     */
+    createProvider(name: string, ctx: Context, config: Record<string, unknown>): ImageProvider$1;
+}
+
+/**
+ * 配置选项中的「供应商」枚举（Schema 用于 Tagged Union 标签字段）。
+ *
+ * 与 ProviderType 的差异：这是**用户配置层**的标签，背后映射到一个或多个
+ * ProviderRegistry 中的实际 provider 名（例如 'yunwu' 标签 → 'yunwu-adaptive' provider）。
+ */
+type ImageProvider = 'yunwu' | 'gptgod' | 'gemini' | 'grok' | 'openai' | 'gpt-official';
+/** 云雾 Provider 的协议格式选择 */
+type ApiFormat = 'gemini' | 'openai';
+interface ModelMappingConfig {
+    suffix: string;
+    modelId: string;
+    provider?: ImageProvider;
+    apiFormat?: ApiFormat;
+    /** 是否为受限模型，仅模型白名单内的用户可调用 */
+    restricted?: boolean;
+}
+interface StyleConfig {
+    commandName: string;
+    description?: string;
+    prompt: string;
+    aliases?: string[];
+    keywords?: string[];
+    examples?: string[];
+    category?: string;
+    whenToUse?: string;
+}
+interface StyleGroupConfig {
+    prompts: StyleConfig[];
+}
+
+/**
+ * V2 配置 Schema —— Phase 3 Batch D 终稿（image-only）。
+ *
+ * 设计要点：
+ * - **Tagged Union**：`Schema.intersect([base, Schema.union([...])])`，每个分支只声明自己用到的字段，
+ *   不再使用 v1 的 `.hidden()` 反模式。
+ * - **范围**：仅图像生成。所有视频相关字段 / Schema 已移除。
+ * - **运行期类型**：`Config` interface 与 Schema 保持一致；可被 v1 的 cherry-pick 文件
+ *   （UserManager / prompt-timeout）继续使用。
+ *
+ * 顶层布局（按用户视觉优先级排序）：
+ *   ① 图像供应商（Tagged Union 主体）
+ *   ② 图像生成（风格预设 styles + styleGroups + 基础显示设置）
+ *   ③ 模型映射
+ *   ④ 限流与配额
+ *   ⑤ 安全策略
+ *   ⑥ 管理员设置
+ *   ⑦ ChatLuna 集成
+ */
+
+interface Config$1 {
+    provider: ImageProvider;
+    yunwuApiKey?: string;
+    yunwuModelId?: string;
+    yunwuApiFormat?: ApiFormat;
+    yunwuApiBase?: string;
+    gptgodApiKey?: string;
+    gptgodModelId?: string;
+    geminiApiKey?: string;
+    geminiModelId?: string;
+    geminiApiBase?: string;
+    grokApiKey?: string;
+    grokModelId?: string;
+    grokApiBase?: string;
+    openaiApiKey?: string;
+    openaiModelId?: string;
+    openaiApiBase?: string;
+    gptOfficialApiKey?: string;
+    gptOfficialModelId?: string;
+    gptOfficialApiBase?: string;
+    styles: StyleConfig[];
+    styleGroups?: Record<string, StyleGroupConfig>;
+    showQuotaInImageCommands: boolean;
+    defaultNumImages: number;
+    modelMappings?: ModelMappingConfig[];
+    dailyFreeLimit: number;
+    unlimitedPlatforms: string[];
+    rateLimitWindow: number;
+    rateLimitMax: number;
+    securityBlockWindow: number;
+    securityBlockWarningThreshold: number;
+    adminUsers: string[];
+    permanentMembers: string[];
+    modelWhitelistUsers: string[];
+    logLevel: 'info' | 'debug';
+    chatlunaEnabled: boolean;
+    chatlunaContextInjectionEnabled: boolean;
+    chatlunaContextHistorySize: number;
+    chatlunaContextTtlSeconds: number;
+    apiTimeout: number;
+}
+declare const Config$1: Schema<Config$1>;
+
+/**
+ * V2 插件入口（aka-ai-image-generator） —— 仅图像生成。
+ *
+ * Phase 4 MVP 接线：
+ *   - ProviderRegistry：模块级单例，注册 6 个 image-only Provider 工厂
+ *   - UserManager：用户配额 / 限流 / 安全计数（cherry-pick 自 v1）
+ *   - AiImageGeneratorService：核心服务（Provider 实例化 + 配额 + 用量 + 图像记忆）
+ *   - ImageGenerationOrchestrator：MVP 编排（文生图 + 图生图，命令级超时）
+ *   - 命令族：aig.文生图 / aig.图生图 / aig.图像额度
+ *
+ * 配置热重载：通过 ctx.scope.update 风格的 acceptor 处理；本入口在变更时同步
+ * 更新闭包内的 currentConfig，并调用 `service.updateConfig(next)`。
+ *
+ * Phase 5 计划：
+ *   - 迁移工具 + 文档（v1 → v2 用户数据迁移）
+ *   - ChatLuna 桥接（manager/runtime/context-injection/tools）
+ *   - 完整命令族：合成图、风格迁移、改姿势、修改设计、变像素、充值、参数指令
+ *   - 发布到 npm
+ *
+ * 注：本插件**不包含视频生成**功能，相关代码 / 配置 / 文档全部不在 v2 范围内。
+ */
+declare const name = "aka-ai-image-generator";
+type Config = Config$1;
+declare const Config: koishi.Schema<Config$1>;
+/**
+ * 暴露给同插件其它模块（如未来的 ChatLuna bridge）的注册表入口。
+ * 不通过 ctx.set() 暴露，避免污染全局服务命名空间。
+ */
+declare function getProviderRegistry(): ProviderRegistry;
+declare function apply(ctx: Context, config: Config): void;
+
+export { Config, apply, getProviderRegistry, name };