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 架构预留。

最新更新（本地开发版）

• 配置摘要默认精简显示 Provider 状态、默认模型和能力统计；详细模型列表请使用 image_models。
• 编辑/变体未配置专用模型时会跟随生图模型，但该模型必须声明支持对应操作。
• 当跟随的生图模型不支持编辑或变体时，错误提示会引导选择专用模型或手动声明能力。

最新发布版（0.1.2）

• 文档修复：上版 README 里「每几十秒只吐 1 字节」被误写为 ASCII 残留「/sql1」，已修正为正常中文。
• 文档修复：去掉 README 中指向 unpkg 直链的 CHANGELOG 链接——unpkg 对 .md 直发 text/markdown 不含 charset 在中文 Windows 下会乱码；改提示「在 npm 包页 Code/Files 选项卡查看 CHANGELOG」。

历史更新（0.1.1）

• 修复：中转站出图慢但已成功返回仍被判“请求超时”的问题 —— 超时改为“stall 续命”（只要持续有字节到达就自动续期），不再用固定 60 秒死闸误杀慢请求。
• 修复：连带报错 Stream ended without finish_reason —— 失败时不再向 pi 主程序抛异常，避免主程序触发流式重试导致的断流。
• 修复：responseFormat=auto 不再硬塞 response_format: "url"，让中转站用它最快的方式回，出图更稳更快。
• 新增：总时长兜底环境变量 IMAGE_TOTAL_TIMEOUT_SECONDS（默认 600 秒）防被「每几十秒只吐 1 字节」的续活死链无限挂起；图片下载独立超时 IMAGE_DOWNLOAD_TIMEOUT_SECONDS（默认 60 秒）。

完整的更新记录见包内 CHANGELOG.md（在 npm 包页「Code」/ Files 选项卡查看，避免 unpkg 直链因无 charset 显示乱码）。

功能

• 通过唯一用户入口 /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

安装

开发目录中：

npm install
npm run build

作为 Pi package 安装时，package.json 已声明：

{
  "pi": {
    "extensions": ["./dist/index.js"]
  }
}

也可以在当前项目直接使用 .pi/extensions/pi-image-gen.ts 开发入口，然后在 Pi 中 /reload。

配置

配置入口

在 Pi 中运行：

/image-config

即可添加 Provider、测试 /models、选择默认生图/编辑/变体模型、设置默认 Provider，以及设置图片响应格式（自动兼容、URL、Base64 JSON）。配置跨项目保存在：

~/.pi/agent/pi-image-gen/providers.json

最小环境变量配置（无全局 Provider 时的兼容 fallback）：

export IMAGE_BASE_URL=https://example.com/v1
export IMAGE_API_KEY=sk-xxxx

Windows PowerShell：

$env:IMAGE_BASE_URL="https://example.com/v1"
$env:IMAGE_API_KEY="sk-xxxx"

可选配置：

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              # stall 超时：只要持续有字节到达就自动续期
export IMAGE_TOTAL_TIMEOUT_SECONDS=600        # 总时长上限（默认 10 分钟），防被续活死链无限挂起
export IMAGE_DOWNLOAD_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 无法自动识别时）：

export IMAGE_MODEL_CAPABILITIES="my-model:image_generation,image_edit;other-model:vision"

API URL

IMAGE_BASE_URL 应指向 API 版本根路径，例如：

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 仍可调用工具：

image_models({ "refresh": true })

每个模型只显示一次，并标注识别到的能力与来源，例如：

gpt-image-2 [生图、编辑] [名称推测]
custom-model [未知] [无法判断]

能力来源按可信程度排序：服务端声明、手动配置、名称推测、无法判断。名称推测不等于实际接口验证。

文生图

用户可以直接说：

生成一张赛博朋克东京街头，16:9。

Agent 应调用：

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 隔离，位于：

~/.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 都在：

/image-config

安全策略

• 不打印完整 API Key
• 不返回 Authorization Header
• 请求有 timeout
• API 响应大小有限制
• 图片下载大小有限制
• 只支持 http/https 图片 URL
• 不执行图片文件
• 不使用 eval
• 不执行用户输入
• 不进行端口扫描或大范围 API 探测

添加 Provider

核心接口在 src/core/types.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 模型

扩展无法确认模型能力。使用：

export IMAGE_MODEL_CAPABILITIES="model-id:image_generation"

开发

npm install
npm run typecheck
npm run build
npm test
npm pack --dry-run

测试使用 mock fetch，不会调用真实付费 API。

npm 发布

发布前检查：

npm pack --dry-run

确认包内没有：

• .env
• API Key
• 本地缓存
• 测试垃圾
• 大文件

发布需手动执行：

npm publish

本项目不会自动发布。

已知限制

• 第一版仅实现 OpenAI-compatible Provider。
• 不会默认发送真实图片生成请求来验证能力，避免潜在付费。
• 不同服务商图片接口参数可能有差异；当前传递 OpenAI 风格常见字段。
• image_edit 使用 multipart/form-data，某些兼容 API 可能要求不同字段名。