@ganziliang/zhizh-pi-ai2image
extensionImage generation and editing for Pi Agent through the Zhizhengroup LLM Gateway (generate_image tool)
by — · v0.1.1 · published 1w ago
$ pi install npm:@ganziliang/zhizh-pi-ai2imageSignals
Download trend
No downloads in the last 12 weeks.
README
Zhizh Pi AI2Image
给 Pi Agent 加一个生图 / 改图工具。装上之后直接对 Pi 说「画一张小红书封面……」就会调用公司生图网关出图，不需要 Python，不需要额外配密钥，也不需要单独的 skill。
- 工具名：
generate_image - 命令：
/imagegen（看配置）、/imagegen open [路径]（看图器打开）、/imagegen reveal [路径]（资源管理器定位） - 能力：文生图、图生图、局部改图、多参考图、批量变体
- 执行方式：扩展内部直接
fetch调 OpenAI-compatible 图片接口，不启动任何子进程
安装
pi install npm:@ganziliang/zhizh-pi-ai2image
装完 /reload 或重启 Pi。
如果已经装了团队引导器，也可以走菜单：
/pi-setup
选择 Zhizh AI2Image（或「全部推荐插件和主题」）。引导器需要另行安装：
pi install npm:@ganziliang/zhizh-pi-plugin-setup
配置来源
扩展按下面的优先级取「网关地址 + 密钥」，前一层能拿到就用它：
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 环境变量 IMAGEGEN_BASE_URL + IMAGEGEN_API_KEY | 显式覆盖，两者都设才生效 |
| 2 | Pi 自己的 provider 凭据（默认 company-gpt） | 默认走这条，直接复用 ~/.pi/agent/models.json 里的网关和 key |
| 3 | .env | 当前目录及其所有上级目录，或用 IMAGEGEN_ENV_FILE 指定具体文件 |
所以只要 Pi 已经配好公司网关（/model-setup 做过），装完就能用，不用配任何东西。
改动配置后可以随时确认当前生效的是哪一层：
/imagegen
输出示例：
配置来源 : pi provider «company-gpt»（configured API key）
Base URL : https://llm-gateway.zhizhengroup.com/openai/v1
Responses : (复用 base URL)
主模型 : gpt-image-2
备用模型 : (已关闭)
API key : 已配置（cr_78db…，长度 67）
额外 header: (无)
.env 兜底文件: (无)
可选的调整项
| 环境变量 | 默认 | 说明 |
|---|---|---|
PI_IMAGEGEN_PROVIDER | company-gpt | 换一个 Pi provider 取网关凭据 |
IMAGEGEN_MODEL | gpt-image-2 | 生图模型 |
IMAGEGEN_FALLBACK_MODELS | 空（关闭） | 备用模型，逗号分隔；主模型失败时按序降级 |
IMAGEGEN_RESPONSES_URL | 复用 base URL | 仅 gemini-* 模型走 /responses 时需要 |
IMAGEGEN_ENV_FILE | — | 指定一份 .env，优先级高于目录扫描 |
IMAGEGEN_AUTO_OPEN | first | 出图后自动弹看图器：first（只弹第一张）/ all / off |
怎么用
核心：直接说需求就行，不需要任何斜杠命令。 模型会自己把需求翻译成工具参数。
文生图
画一张小红书封面，1080x1440 竖版，一只穿奶油黄洞洞鞋的胖橘猫在打太极拳，暖色调
控制尺寸和质量
出一张小红书封面，先来个 normal 质量试稿：一只猫在看书的插画，暖色调
口语里的尺寸/质量会被映射成参数：pageType: "xhs"、quality: "normal"。
尺寸预设：
| pageType | 输出尺寸 | 用途 |
|---|---|---|
portrait（默认） | 1024×1536 | 通用竖版 |
landscape | 1536×1024 | 横版 |
square | 1024×1024 | 方图 / 图标 |
xhs | 1080×1440 | 小红书 3:4 |
xhs-cover | 1080×1080 | 小红书封面 1:1 |
xhs-wide | 1080×720 | 小红书横版 3:2 |
也可以直接给 size 显式宽高（会按网关限制自动归一化），或给 auto 交给模型决定。
质量档位：normal（快速预览）/ high（正式出图）/ 2k（高分辨率）。
改图 / 图生图
必须写清「只改什么、保住什么」，否则主体容易漂：
把 C:\path\to\product.png 的背景换成暖色影棚，
只改背景，产品的形状、边缘、颜色、机位全部保持不变
也可以直接对刚生成的图做迭代，不用自己记路径：
背景再暗一点，其他不动
多参考图
逐张说明角色，别只说「参考这几张」：
用第二张图的版式、第三张图的风格，重做一张 UI 首页：
- 图1 layout_reference：保留布局比例和信息层级
- 图2 style_reference：只借配色、质感、装饰风格
- 不要保留图2里的 logo 和水印
一次出多张变体
出 3 个不同配色的版本让我挑
会存成 xxx_1.png / xxx_2.png / xxx_3.png。
工具参数
| 参数 | 必填 | 说明 |
|---|---|---|
prompt | 是 | 生成提示词或改图指令 |
out | 否 | 输出路径（相对当前工作目录）。默认 outputs/imagegen/<slug>-<时间戳>.png |
ref | 否 | 参考图 / 待改图路径，可多张 |
size | 否 | 显式 宽x高（自动归一化）或 auto |
pageType | 否 | 见上方尺寸预设表 |
quality | 否 | normal / high / 2k |
model | 否 | 覆盖生图模型 |
n | 否 | 文生图变体数量，默认 1 |
结果里可以直接点开图片
生成成功后，工具结果里每个文件都会带两个可单击链接，并自动用系统看图器打开图片：
✓ 已生成 1 张图（文生图，gpt-image-2，1536x1024）
🖼 打开图片 📁 打开所在文件夹
D:\IDEAProject\ai_work\outputs\imagegen\flying-winged-orange-cat.png (1953 KB)
提示：Ctrl + 单击链接即可打开；也可用 /imagegen open（看图器）、/imagegen reveal（资源管理器定位）
| 入口 | 作用 |
|---|---|
🖼 打开图片 | 单击 → 系统默认看图器打开该图 |
📁 打开所在文件夹 | 单击 → 资源管理器打开所在目录 |
/imagegen open [路径] | 看图器打开；不给路径则打开本会话最近生成的那张 |
/imagegen reveal [路径] | 在资源管理器里定位并选中该文件（Windows explorer /select,） |
/imagegen <路径> | 等价于 open |
自动弹看图器由 IMAGEGEN_AUTO_OPEN 控制：first（默认，只弹第一张）/ all / off。
点击方式随终端不同：
| 终端 | 打开链接 |
|---|---|
| Windows Terminal | Ctrl + 单击（单击是选中文本） |
| WezTerm | 单击（无需修饰键） |
| iTerm2 | Cmd + 单击 |
为什么不靠终端内联显示
- Windows Terminal：Pi 判定其不支持图片协议（
images: null），不会内联显示 —— 链接 + 自动弹窗就是 Windows 下的正解。 - WezTerm（Windows）：kitty 图形协议会被 ConPTY 丢弃（wezterm#1673、#5757）；iTerm2 协议能画出来，但 pi-tui 的
moveUp没有重置光标列，图片会被放到窗口最右列、只剩一条细缝。 - Kitty / Ghostty / iTerm2（macOS / Linux）：可正常内联显示。
所以 Windows 下建议保持 IMAGEGEN_AUTO_OPEN=first，靠弹窗看原图。
行为约定
生成的图会回灌给模型。 工具返回里除了文件路径，还带一份图片内容，所以模型能自己看见成图并做像素级验收（它会主动报告颜色、留白比例、甚至算形状重合度），也能据此直接做下一轮改图。这是它相比「跑脚本拿路径」最大的差别。
永不覆盖已有文件。 目标路径已存在时自动改写成 _v2、_v3，所以反复重出和改图都安全，原图永远在。
错误的模型会快速失败。 网关返回「无可用渠道 / model_not_found / 不是图像模型」这类错误时不会退避重试，而是直接跳到备用模型；只有限流、超时、上游账号抖动才重试（指数退避 3s 起，最多 6 次）。
一张图大约 45~90 秒（high 更慢），期间不要打断。
出图提示词建议
结构化 prompt 比一句话稳得多：
Use case: <小红书封面 / 产品主图 / App mockup / 信息图>
Primary request: <一句话说清要画什么>
Subject: <主体>
Scene/backdrop: <背景环境，或纯色>
Style/medium: <照片 / 插画 / 3D / UI mockup / 矢量图标>
Composition/framing: <构图、视角、留白、比例>
Lighting/mood: <光线和情绪>
Color/materials: <主色、材质、质感>
Text (verbatim): "<必须逐字出现的文字；没有就写 none>"
Constraints: <尺寸、必须保留、品牌限制>
Avoid: <logo / watermark / 错字 / 多余道具 / 低清晰度>
三条实战经验：
- 一次只解决一个问题。 第一版不满意，用「只改 XX，其余保持」做单点迭代。
- 内容改动和质感提质分两轮做。 实测把「改姿势」和「提升细节」塞进同一个 prompt 时，提质会被稀释掉。
- 别让模型渲染长中文。 文字图一定要检查拼写，字多的建议后期用设计工具叠字。
排障
| 现象 | 处理 |
|---|---|
| 报「缺少生图网关配置」 | 跑 /imagegen 看来源；确认 company-gpt 还在 models.json 里，或设 IMAGEGEN_BASE_URL + IMAGEGEN_API_KEY |
| 报「所有模型都失败」 | 错误信息里会列出整条模型链各自的失败原因 |
| 报「No available OpenAI Images account found」 | 网关上游账号池抖动，扩展会自动退避重试，通常能自愈。持续报就等几分钟或找网关维护 |
报 HTTP 502: Error 502: Bad gateway | 网关到上游链路故障（与账号池抖动同源），等几分钟再试 |
报 HTTP 400: … safety system | 内容策略拦截，重试无用，改 prompt |
| 图看不出是刚生成的那版 | 检查目录里的 _v2 / _v3，同名不会被覆盖 |
| 想让 Pi 优先走别的生图方式 | 提示词里明确说用哪个工具/技能 |
已知限制
gemini-*模型走/responses+modalities协议，公司当前网关不支持（会返回Unsupported parameter: modalities），这条分支仅为兼容其他网关保留。- 公司网关目前只有
gpt-image-2可用：gpt-image-1无可用渠道，gemini-*不被 images 端点接受。所以备用模型默认关闭。 - 实际输出尺寸会和请求值有偏差（例如请求 1080×1440 实际返回 1086×1448），比例会保持。工具会在返回里报告实际尺寸。
- 工具结果里的图会占上下文，连续生成十几张会明显吃 token（超过 2000×2000 会自动缩放）。批量出图建议分开会话。
与 Python 方案的关系
本扩展是一套自包含实现，不调用任何外部脚本。如果团队里还有基于 Python 的 ai-image-gen skill，两者互不影响，但同一句需求可能被路由到其中任意一条；本扩展通过工具说明让模型优先直调 generate_image。
开发
# 本地调试：不安装、只用这一次
pi -e ./zhizh-pi-ai2image
# 从源码目录直接加载扩展文件
pi --no-extensions -e ./extensions/imagegen.ts
源码单文件：extensions/imagegen.ts。
发布：
npm version patch
npm publish --access public
License
MIT