image-gen

工具：image_gen(prompt, reference?, size?, quality?, background?, model?)，三宿主同名（Pi / OpenCode v2 / DSH）。凭据与默认值在 ~/.local/share/agent-skills/image-gen.json。

本 skill 只说明工具能力与行为。画什么、用什么风格、要不要画，由调用方（项目自己的规范或用户 prompt）决定。

1. 能做什么

不能做：

• 只出位图，不是可编辑矢量/SVG；需要精确文字、公式、真实数据或二次编辑时，位图不合适
• 一次调用一张图（内部固定 n: 1）；要几张就调几次
• 不保证图中文字正确 —— 生成模型自身的限制，调 quality 或 size 都不改变这一点

2. 文生图

{ "prompt": "what the picture must show, in English" }

prompt 一律用英文写，包括要出现在图上的文字：这些 gpt-image 模型对英文的理解明显好过中文，中文 prompt 更容易出错字、笔画畸形和中英混杂。

• 图上的标注默认也用英文（text "Data Ingestion" in the top box）
• 用户明确要中文标注时才在 prompt 里写中文字面量，并接受更高的出错率
• 只有传给模型的 prompt 是英文；给用户看的回复、落盘文件名解释仍是中文
• prompt 里写清：主体、布局、必须出现的文字（用引号给原文）、风格与配色；不要把聊天内容整段粘进去

3. 参考图编辑

{ "prompt": "what to keep and exactly what to change", "reference": ["/abs/path/a.png", "/abs/path/b.png"] }

多张参考图一起传；不给 reference 就是文生图。编辑的 prompt 同样一律用英文。编辑结果可能与原图有未要求的差异，原图请自行保留。

4. 参数

5. 返回与落盘

返回三项：落盘路径、一行 模型 · 尺寸 · 画质 · 格式 · 体积 摘要、图片本身（宿主是否把它交给模型见第 6 节）。

• 目录：output_dir，默认项目 cwd 下的 images/，不存在则创建
• 文件名：ISO 时间戳 + prompt 前 40 字，扩展名取渠道返回的 output_format
• 单图几百 KB，会进会话历史

6. 宿主差异

模型看不到图时，把路径交给用户自己打开，不要说"图在下面"。

7. 失败怎么读

工具不自动重试，失败即抛错，需要重试就自己再调一次。

8. 配置

~/.local/share/agent-skills/image-gen.json（0600，IMAGE_GEN_CONFIG 可改路径）：

{
  "base_url": "https://api.example.com/v1",
  "api_key": "...",
  "model": "gpt-image-2.5-flare",
  "edit_model": "gpt-image-2.5-sunburst",
  "output_dir": "images",
  "size": "1024x1024",
  "quality": "medium"
}

• 文件不存在时，从 ~/.pi/agent/models.json 里挑第一个 api 以 openai 开头、凭据和 baseUrl 都填好的 provider 自动写入；挑不到就写空模板并报错
• pi-setup.sh / opencode-setup.sh 会补齐缺字段，已有的 base_url / api_key 一律保留
• 无人值守可用 PI_IMAGE_GEN_API_KEY 预填
• 参数优先级：单次调用参数 > image-gen.json > 内置默认值