@xinizai/pi-image-gen 0.1.0

package/README.md

@@ -0,0 +1,337 @@
+# pi-image-gen
+
+一个通用 Pi Agent 图片生成扩展。用户只配置 `IMAGE_BASE_URL` 和 `IMAGE_API_KEY`，扩展会尽可能自动探测 OpenAI-compatible API、发现模型、识别模型能力，并向 Pi Agent 注册图片生成/编辑/变体工具。
+
+> 第一版重点支持 OpenAI-compatible API：`GET /models`、`POST /images/generations`、`POST /images/edits`、`POST /images/variations`。其它 Provider 通过 Adapter 架构预留。
+
+## 功能
+
+- 通过唯一用户入口 `/image-config` 管理多个跨项目共享的 Provider（环境变量仍可作为兼容 fallback）
+- 有限、安全地探测 `GET /models`
+- 自动识别模型能力：`image_generation`、`image_edit`、`image_variation`、`vision`、`text`、`unknown`
+- 模型发现缓存，默认 10 分钟
+- 自动选择稳定默认图片模型
+- 支持 base64 和 URL 图片响应，统一保存为本地文件
+- 图片保存目录默认：`~/.pi/agent/generated/`
+- 不把 API Key 返回给 Agent 或写入输出
+- 注册 Pi Tools：`image_generate`、`image_edit`、`image_variation`、`image_models`、`image_config`、`image_providers`
+- 唯一面向用户的 Slash Command：`/image-config`
+
+## 安装
+
+开发目录中：
+
+```bash
+npm install
+npm run build
+```
+
+作为 Pi package 安装时，`package.json` 已声明：
+
+```json
+{
+  "pi": {
+    "extensions": ["./dist/index.js"]
+  }
+}
+```
+
+也可以在当前项目直接使用 `.pi/extensions/pi-image-gen.ts` 开发入口，然后在 Pi 中 `/reload`。
+
+## 配置
+
+## 配置入口
+
+在 Pi 中运行：
+
+```text
+/image-config
+```
+
+即可添加 Provider、测试 `/models`、选择默认图片模型、设置默认 Provider，以及设置图片响应格式（自动兼容、URL、Base64 JSON）。配置跨项目保存在：
+
+```text
+~/.pi/agent/pi-image-gen/providers.json
+```
+
+最小环境变量配置（无全局 Provider 时的兼容 fallback）：
+
+```bash
+export IMAGE_BASE_URL=https://example.com/v1
+export IMAGE_API_KEY=sk-xxxx
+```
+
+Windows PowerShell：
+
+```powershell
+$env:IMAGE_BASE_URL="https://example.com/v1"
+$env:IMAGE_API_KEY="sk-xxxx"
+```
+
+可选配置：
+
+```bash
+export IMAGE_MODEL=gpt-image-1                 # fallback 或显式默认文生图模型
+export IMAGE_EDIT_MODEL=gpt-image-1            # 默认编辑模型
+export IMAGE_VARIATION_MODEL=dall-e-2          # 默认变体模型
+export IMAGE_TIMEOUT_SECONDS=60
+export IMAGE_CACHE_TTL_SECONDS=600
+export IMAGE_OUTPUT_DIR=/path/to/generated
+export IMAGE_MAX_RESPONSE_BYTES=8000000
+export IMAGE_MAX_DOWNLOAD_BYTES=25000000
+```
+
+手动声明模型能力（当 API 无法自动识别时）：
+
+```bash
+export IMAGE_MODEL_CAPABILITIES="my-model:image_generation,image_edit;other-model:vision"
+```
+
+## API URL
+
+`IMAGE_BASE_URL` 应指向 API 版本根路径，例如：
+
+```bash
+https://api.example.com/v1
+```
+
+扩展只会针对该 Base URL 进行有限兼容探测：当前仅尝试 `GET /models`。不会扫描端口、不会递归探测大量 URL。
+
+## 自动发现模型
+
+启动后或首次调用工具时：
+
+1. 读取 Base URL 与 API Key
+2. 调用 `GET {IMAGE_BASE_URL}/models`
+3. 解析 `data[]`
+4. 优先使用 API metadata 中的能力字段
+5. 如果没有 metadata，则使用模型 ID 和 metadata 做启发式候选识别
+6. 写入缓存 `~/.pi/agent/image-gen-cache.json`
+
+如果 `/models` 不存在：
+
+- 若设置了 `IMAGE_MODEL`，会把它作为 fallback 模型；
+- 否则明确报错，并提示配置 `IMAGE_MODEL`。
+
+## 模型能力识别
+
+能力类型：
+
+- `text`
+- `vision`
+- `image_generation`
+- `image_edit`
+- `image_variation`
+- `unknown`
+
+识别优先级：
+
+1. 用户手动声明：`IMAGE_MODEL_CAPABILITIES`
+2. API 返回 metadata：`capabilities`、`modalities`、`input_modalities`、`output_modalities` 等
+3. 启发式识别：模型名包含 `image`、`img`、`dall-e`、`gpt-image`、`flux`、`stable-diffusion` 等
+4. 无法确认则标记为 `unknown`
+
+启发式识别只表示候选，不保证 100% 正确。扩展不会默认发送真实付费生图请求来验证能力。
+
+## 查看模型
+
+普通用户请在 Pi 中运行 `/image-config` 后进入 Provider 的“选择默认图片模型”。
+
+Agent 仍可调用工具：
+
+```text
+image_models({ "refresh": true })
+```
+
+输出按能力分组：
+
+```text
+Image Generation:
+- model-a
+- model-b
+
+Vision:
+- model-c
+
+Text:
+- model-d
+
+Unknown:
+- model-e
+```
+
+## 文生图
+
+用户可以直接说：
+
+```text
+生成一张赛博朋克东京街头，16:9。
+```
+
+Agent 应调用：
+
+```text
+image_generate({
+  "prompt": "赛博朋克东京街头",
+  "aspect_ratio": "16:9"
+})
+```
+
+参数：
+
+- `prompt` 必填
+- `model` 可选，默认自动选择
+- `size` 可选，例如 `1024x1024`
+- `aspect_ratio` 可选，例如 `16:9`
+- `quality` 可选
+- `output_format` 可选：`png`、`jpeg`、`jpg`、`webp`
+- `n` 可选
+
+## 图片编辑
+
+工具：`image_edit`
+
+参数：
+
+- `image`：Windows 本地路径、Linux 本地路径、`file://`、`https://`
+- `prompt`
+- `model?`
+- `size?`
+- `output_format?`
+
+支持输入格式：`.png`、`.jpg`、`.jpeg`、`.webp`。
+
+如果没有发现支持 `image_edit` 的模型，会明确报错，而不是伪造成功。
+
+## 图片变体
+
+工具：`image_variation`
+
+参数：
+
+- `image`
+- `model?`
+- `size?`
+- `n?`
+
+需要模型具备 `image_variation` 能力。
+
+## 缓存
+
+模型发现缓存默认有效期 10 分钟。
+
+缓存按 Provider 隔离，位于：
+
+```text
+~/.pi/agent/pi-image-gen/cache/providers/{providerId}.json
+```
+
+缓存包含 Base URL、Provider type、模型、能力和发现时间；不保存 API Key 明文。缓存 key 使用 Provider ID、Provider type、Base URL 与 API Key 指纹，API Key 或 Base URL 变化会自动失效。
+
+刷新模型、浏览模型和管理 Provider 都在：
+
+```text
+/image-config
+```
+
+## 安全策略
+
+- 不打印完整 API Key
+- 不返回 Authorization Header
+- 请求有 timeout
+- API 响应大小有限制
+- 图片下载大小有限制
+- 只支持 http/https 图片 URL
+- 不执行图片文件
+- 不使用 eval
+- 不执行用户输入
+- 不进行端口扫描或大范围 API 探测
+
+## 添加 Provider
+
+核心接口在 `src/core/types.ts`：
+
+```ts
+interface ImageProvider {
+  discoverModels(): Promise<ModelInfo[]>;
+  generate(...): Promise<ImageOperationResult>;
+  edit(...): Promise<ImageOperationResult>;
+  variation(...): Promise<ImageOperationResult>;
+}
+```
+
+新增 Provider：
+
+1. 在 `src/providers/` 新建实现
+2. 实现 `ImageProvider`
+3. 在 `src/core/provider.ts` 中注册 resolver
+4. 添加 mock 测试
+
+## 故障排查
+
+### 401
+
+API Key 错误或过期。检查 `IMAGE_API_KEY`。
+
+### 403
+
+API Key 无权访问模型或图片接口。
+
+### 404 /models
+
+Base URL 可能不包含 `/v1`，或服务商不支持 `/models`。可以设置 `IMAGE_MODEL` fallback。
+
+### 429
+
+限流或额度不足。稍后重试。
+
+### unknown 模型
+
+扩展无法确认模型能力。使用：
+
+```bash
+export IMAGE_MODEL_CAPABILITIES="model-id:image_generation"
+```
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+npm pack --dry-run
+```
+
+测试使用 mock fetch，不会调用真实付费 API。
+
+## npm 发布
+
+发布前检查：
+
+```bash
+npm pack --dry-run
+```
+
+确认包内没有：
+
+- `.env`
+- API Key
+- 本地缓存
+- 测试垃圾
+- 大文件
+
+发布需手动执行：
+
+```bash
+npm publish
+```
+
+本项目不会自动发布。
+
+## 已知限制
+
+- 第一版仅实现 OpenAI-compatible Provider。
+- 不会默认发送真实图片生成请求来验证能力，避免潜在付费。
+- 不同服务商图片接口参数可能有差异；当前传递 OpenAI 风格常见字段。
+- `image_edit` 使用 multipart/form-data，某些兼容 API 可能要求不同字段名。

package/dist/core/cache.d.ts

@@ -0,0 +1,11 @@
+import type { DiscoveryResult, ImageGenConfig } from "./types.js";
+export declare class ModelDiscoveryCache {
+    private readonly cacheDir;
+    constructor(cacheDir?: string);
+    get(config: ImageGenConfig, now?: number): Promise<DiscoveryResult | undefined>;
+    set(config: ImageGenConfig, result: DiscoveryResult): Promise<void>;
+    key(config: ImageGenConfig): string;
+    apiKeyFingerprint(config: ImageGenConfig): string;
+    private fileFor;
+    private read;
+}

package/dist/core/cache.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile, rename, chmod } from "node:fs/promises";
+import { resolve } from "node:path";
+import { GLOBAL_DIR } from "./global-config.js";
+export class ModelDiscoveryCache {
+    cacheDir;
+    constructor(cacheDir = resolve(GLOBAL_DIR, "cache", "providers")) {
+        this.cacheDir = cacheDir;
+    }
+    async get(config, now = Date.now()) {
+        const entry = await this.read(config.providerId).catch(() => undefined);
+        if (!entry)
+            return undefined;
+        if (entry.key !== this.key(config))
+            return undefined;
+        const discovered = Date.parse(entry.result.discoveredAt);
+        if (!Number.isFinite(discovered) || now - discovered > config.cacheTtlMs)
+            return undefined;
+        return entry.result;
+    }
+    async set(config, result) {
+        await mkdir(this.cacheDir, { recursive: true });
+        const file = this.fileFor(config.providerId);
+        const temp = `${file}.${process.pid}.tmp`;
+        await writeFile(temp, JSON.stringify({ key: this.key(config), result: { ...result, apiKeyFingerprint: this.apiKeyFingerprint(config) } }, null, 2), { encoding: "utf8", mode: 0o600 });
+        await chmod(temp, 0o600).catch(() => undefined);
+        await rename(temp, file);
+    }
+    key(config) {
+        return createHash("sha256").update(`${config.providerId}\n${config.providerType}\n${config.baseUrl}\n${config.apiKeyUpdatedAt}\n${this.apiKeyFingerprint(config)}`).digest("hex");
+    }
+    apiKeyFingerprint(config) {
+        return createHash("sha256").update(config.apiKey).digest("hex").slice(0, 12);
+    }
+    fileFor(providerId) {
+        return resolve(this.cacheDir, `${providerId.replace(/[^a-zA-Z0-9._-]/g, "_")}.json`);
+    }
+    async read(providerId) {
+        return JSON.parse(await readFile(this.fileFor(providerId), "utf8"));
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/core/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"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"}

package/dist/core/capabilities.d.ts

@@ -0,0 +1,2 @@
+import type { ModelCapability, ModelInfo } from "./types.js";
+export declare function detectCapabilities(id: string, metadata: Record<string, unknown>, manual?: ModelCapability[]): Pick<ModelInfo, "capabilities" | "capabilitySource" | "inputModalities" | "outputModalities" | "supportsImageInput" | "supportsMultipleImages" | "supportsSize" | "supportsQuality" | "supportsAspectRatio">;

package/dist/core/capabilities.js

@@ -0,0 +1,65 @@
+const imageHints = ["image", "img", "dall-e", "dalle", "gpt-image", "flux", "stable-diffusion", "sdxl", "midjourney", "ideogram", "recraft"];
+const visionHints = ["vision", "vl", "visual", "omni", "gpt-4o", "qwen-vl", "llava"];
+const textHints = ["gpt", "claude", "llama", "mistral", "deepseek", "qwen", "kimi", "mimo"];
+export function detectCapabilities(id, metadata, manual) {
+    if (manual?.length)
+        return base(manual, "manual", metadata);
+    const metaCaps = explicitCapabilities(metadata);
+    if (metaCaps.length)
+        return base(metaCaps, "metadata", metadata);
+    const haystack = `${id} ${JSON.stringify(metadata)}`.toLowerCase();
+    const caps = new Set();
+    if (imageHints.some((h) => haystack.includes(h))) {
+        caps.add("image_generation");
+        if (haystack.includes("edit") || haystack.includes("gpt-image"))
+            caps.add("image_edit");
+        if (haystack.includes("variation") || haystack.includes("dall-e"))
+            caps.add("image_variation");
+    }
+    if (visionHints.some((h) => haystack.includes(h)))
+        caps.add("vision");
+    if (caps.size === 0 && textHints.some((h) => haystack.includes(h)))
+        caps.add("text");
+    if (caps.size === 0)
+        caps.add("unknown");
+    return base([...caps], caps.has("unknown") ? "unknown" : "heuristic", metadata);
+}
+function explicitCapabilities(metadata) {
+    const values = [];
+    for (const key of ["capabilities", "capability", "modalities", "input_modalities", "output_modalities", "supported_generation_methods"]) {
+        const value = metadata[key];
+        if (Array.isArray(value))
+            values.push(...value.filter((v) => typeof v === "string"));
+        else if (typeof value === "string")
+            values.push(value);
+    }
+    const text = values.join(" ").toLowerCase();
+    const caps = new Set();
+    if (/image[_ -]?generation|text-to-image|generate_images|image_out|output:image/.test(text))
+        caps.add("image_generation");
+    if (/image[_ -]?edit|edit_images|inpaint|input:image/.test(text))
+        caps.add("image_edit");
+    if (/image[_ -]?variation|variations/.test(text))
+        caps.add("image_variation");
+    if (/vision|image_input|input:image/.test(text))
+        caps.add("vision");
+    if (/text|chat|completion/.test(text))
+        caps.add("text");
+    return [...caps];
+}
+function base(capabilities, source, metadata) {
+    const lower = JSON.stringify(metadata).toLowerCase();
+    const supportsImageInput = capabilities.includes("image_edit") || capabilities.includes("vision") || lower.includes("input:image") || lower.includes("image_input");
+    return {
+        capabilities,
+        capabilitySource: source,
+        inputModalities: supportsImageInput ? ["text", "image"] : ["text"],
+        outputModalities: capabilities.includes("image_generation") || capabilities.includes("image_edit") || capabilities.includes("image_variation") ? ["image"] : ["text"],
+        supportsImageInput,
+        supportsMultipleImages: lower.includes("multiple") || lower.includes("multi_image"),
+        supportsSize: true,
+        supportsQuality: lower.includes("quality") || capabilities.includes("image_generation"),
+        supportsAspectRatio: lower.includes("aspect") || capabilities.includes("image_generation"),
+    };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/core/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/core/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+export type ImageErrorCode = "missing_config" | "invalid_base_url" | "auth_failed" | "forbidden" | "not_found" | "rate_limited" | "server_error" | "timeout" | "network_error" | "invalid_request" | "invalid_json" | "invalid_image" | "unsupported_format" | "model_unavailable" | "capability_unknown" | "response_too_large" | "request_too_large" | "download_too_large" | "unsupported_provider";
+export declare class ImageGenError extends Error {
+    readonly code: ImageErrorCode;
+    readonly suggestion: string;
+    readonly status?: number | undefined;
+    constructor(code: ImageErrorCode, message: string, suggestion: string, status?: number | undefined);
+    toUserMessage(): string;
+}
+export declare function sanitizeSecret(text: string, apiKey?: string): string;
+export declare function maskApiKey(key: string): string;
+export declare function errorFromStatus(status: number, action: string, detail?: string): ImageGenError;

package/dist/core/errors.js

@@ -0,0 +1,71 @@
+export class ImageGenError extends Error {
+    code;
+    suggestion;
+    status;
+    constructor(code, message, suggestion, status) {
+        super(message);
+        this.code = code;
+        this.suggestion = suggestion;
+        this.status = status;
+        this.name = "ImageGenError";
+    }
+    toUserMessage() {
+        const status = this.status ? `HTTP ${this.status}。` : "";
+        return `${this.message}\n原因：${status}${reasonForCode(this.code)}\n解决办法：${this.suggestion}`;
+    }
+}
+export function sanitizeSecret(text, apiKey) {
+    let out = text;
+    if (apiKey)
+        out = out.split(apiKey).join(maskApiKey(apiKey));
+    out = out.replace(/Bearer\s+[A-Za-z0-9._\-]+/g, "Bearer ****");
+    out = out.replace(/sk-[A-Za-z0-9._\-]{8,}/g, (m) => maskApiKey(m));
+    return out;
+}
+export function maskApiKey(key) {
+    if (!key)
+        return "未配置";
+    if (key.length <= 8)
+        return "****";
+    return `${key.slice(0, 3)}-****${key.slice(-4)}`;
+}
+export function errorFromStatus(status, action, detail) {
+    switch (status) {
+        case 401: return new ImageGenError("auth_failed", `${action}失败：认证失败。`, "检查 IMAGE_API_KEY 是否正确、是否过期。", status);
+        case 403: return new ImageGenError("forbidden", `${action}失败：权限不足。`, "确认 API Key 有访问模型和图片接口的权限。", status);
+        case 404: return new ImageGenError("not_found", `${action}失败：接口不存在。`, "确认 IMAGE_BASE_URL 是否包含正确版本路径，例如 https://host/v1。", status);
+        case 408: return new ImageGenError("timeout", `${action}失败：请求超时。`, "稍后重试，或增大 IMAGE_TIMEOUT_SECONDS。", status);
+        case 409: return new ImageGenError("model_unavailable", `${action}失败：请求冲突或模型不可用。`, "尝试换模型，或检查服务商状态。", status);
+        case 413: return new ImageGenError("request_too_large", `${action}失败：请求体过大。`, "降低图片尺寸、减少 n，或使用更小的输入图片。", status);
+        case 429: return new ImageGenError("rate_limited", `${action}失败：触发限流。`, "稍后重试，或检查额度/并发限制。", status);
+        case 500:
+        case 502:
+        case 503: return new ImageGenError("server_error", `${action}失败：服务端错误。`, "稍后重试；若持续失败请联系 API 服务商。", status);
+        default: return new ImageGenError(status >= 500 ? "server_error" : status >= 400 ? "invalid_request" : "network_error", `${action}失败：HTTP ${status}${detail ? `：${detail}` : "。"}`, status >= 400 && status < 500 ? "检查模型名称、图片尺寸、响应格式和服务商文档。" : "检查网络连接和服务商状态。", status);
+    }
+}
+function reasonForCode(code) {
+    const map = {
+        missing_config: "缺少必要配置。",
+        invalid_base_url: "Base URL 格式不正确或不是 http/https。",
+        auth_failed: "API Key 无效或未授权。",
+        forbidden: "当前凭证没有访问权限。",
+        not_found: "目标 API 路径不存在。",
+        rate_limited: "请求过快或额度不足。",
+        server_error: "API 服务端返回错误。",
+        timeout: "网络请求超过超时时间。",
+        network_error: "网络连接失败或响应异常。",
+        invalid_request: "请求已到达 API，但参数或模型不符合服务商要求。",
+        invalid_json: "API 返回的 JSON 无法解析。",
+        invalid_image: "图片内容为空或不是有效图片。",
+        unsupported_format: "仅支持 png、jpg、jpeg、webp。",
+        model_unavailable: "模型不存在、不可用或不支持该操作。",
+        capability_unknown: "无法自动确认模型能力。",
+        response_too_large: "响应超过安全大小限制。",
+        request_too_large: "请求体超过服务商限制。",
+        download_too_large: "下载图片超过大小限制。",
+        unsupported_provider: "暂不支持该 Provider 类型。",
+    };
+    return map[code];
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/core/global-config.d.ts

@@ -0,0 +1,25 @@
+import type { GlobalImageGenConfig, ImageGenConfig, StoredProviderConfig } from "./types.js";
+export declare const GLOBAL_DIR: string;
+export declare const PROVIDERS_FILE: string;
+export declare class GlobalConfigStore {
+    private readonly filePath;
+    constructor(filePath?: string);
+    read(): Promise<GlobalImageGenConfig>;
+    write(config: GlobalImageGenConfig): Promise<void>;
+    addProvider(input: {
+        id?: string;
+        name: string;
+        baseUrl: string;
+        apiKey: string;
+        defaultModel?: string;
+        responseFormat?: "auto" | "url" | "b64_json";
+        manualCapabilities?: string;
+    }): Promise<StoredProviderConfig>;
+    updateProvider(id: string, patch: Partial<Omit<StoredProviderConfig, "id" | "createdAt">>): Promise<StoredProviderConfig>;
+    deleteProvider(id: string): Promise<void>;
+    setDefaultProvider(id: string): Promise<void>;
+    resolveProvider(idOrName?: string): Promise<StoredProviderConfig | undefined>;
+    toRuntimeConfig(provider: StoredProviderConfig, env?: NodeJS.ProcessEnv): Promise<ImageGenConfig>;
+}
+export declare function envFallbackProvider(env?: NodeJS.ProcessEnv): StoredProviderConfig | undefined;
+export declare function resolveRuntimeConfig(providerId?: string, env?: NodeJS.ProcessEnv, store?: GlobalConfigStore): Promise<ImageGenConfig>;