# 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`

## 安装

开发目录中：

```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              # 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 无法自动识别时）：

```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
gpt-image-2 [生图、编辑] [名称推测]
custom-model [未知] [无法判断]
```

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

## 文生图

用户可以直接说：

```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 可能要求不同字段名。
