SnowSky1 / universal-imagegen-agent

# Universal ImageGen Agent
**开始验证：** 完整 generate → edit 案例 ·
更新记录 ·
English ·
作者展示页：Agent 与 AI
`v0.1.1` 修复了 Node.js 将 `n=0` 静默变成 `n=1` 的行为，并为
Node.js/Python CLI 加入共享的数量边界用例。未指定数量时仍默认生成一张。
这是一个从 OpenAI Codex `imagegen` skill 改造而来的、面向通用智能体的独立项目。它把 Codex 生图能力中已经沉淀下来的任务决策流程、提示词工程、用例分类、编辑不变量和提示词范例库抽离出来，使任意具备 shell 或 Python 调用能力的智能体，都能直接复用这套成熟方法来生成和编辑图片，而不必依赖 Codex 专有的内置图片工具。
随着 Qwen-Image、Qwen-Image-2.1 等开放图像模型快速发展，智能体已经拥有越来越多可选择的生图后端。本项目不绑定某个模型：既可以连接 OpenAI Images API，也可以连接实现兼容接口的第三方服务；将 Qwen-Image 部署到本地或推理服务后，还可以通过 OpenAI-compatible 网关或新增适配器，把 Qwen 的开放模型能力与本项目继承自 Codex 的提示词库、工作流和质量约束组合起来，让不同智能体获得更稳定、更专业的生图体验。
> 当前内置的是 OpenAI-compatible Images API 适配层。Qwen 本地 Diffusers、ComfyUI 或 SGLang 推理后端尚未直接内置，需要通过兼容网关接入或新增 provider adapter。
项目提供：
- 可由任意具备 shell 能力的智能体调用的 `imagegen-agent` CLI；
- 可通过 npm、pnpm 或 Python 安装；
- 可嵌入其他程序的 Node.js 与 Python 接口；
- 一条命令安装到 Codex 或兼容智能体的 `universal-imagegen` skill；
- `--json` 机器可读输出和稳定的退出码；
- 独立 API 密钥、自定义 `base_url`、模型、请求头和扩展请求参数；
- 生成、编辑、多图输入、遮罩和 JSONL 批处理；
- 非覆盖式输出、dry-run、提示词结构化和敏感配置脱敏；
- 完整保留的上游技能快照，位于 `upstream/imagegen/`。
当前改造日期为 2026-09-24。新配置默认使用
`gpt-image-2.5-sunburst`，但模型不是硬编码限制，任何部署都可以通过
环境变量、TOML 或命令行替换。
## 为什么适合 Qwen-Image 等开放模型
图像模型本身决定画面生成能力，而智能体侧的任务理解、提示词组织、输入图片角色标注、编辑不变量和结果检查同样决定最终质量。这个项目负责后半部分：
- 把用户的自然语言请求转换为结构清晰、面向生产的图片提示词；
- 区分新图生成、参考图生成、局部编辑、多图合成和批量资源等任务；
- 为编辑任务持续锁定人物身份、布局、文字、边缘和背景等不变量；
- 复用 Codex `imagegen` skill 中的 use-case taxonomy 和提示词范例；
- 用统一 CLI、Python API 和 JSON 结果，让不同智能体共享同一套生图能力；
- 通过可配置 provider，将相同工作流用于 OpenAI 模型、Qwen-Image 部署或其他兼容服务。
因此，接入 Qwen-Image 并不意味着每个智能体都要重新设计提示词系统。只要部署端提供兼容 API，智能体就可以继续使用本项目的 `SKILL.md`、提示词库和执行协议；如果部署端接口不同，也只需新增 provider adapter，而不需要重写上层智能体工作流。
## 目录
 [code] 
## 安装
### 安装本次修复版 v0.1.2
`v0.1.2` 已发布到 npm，可固定版本安装：
 [code] 
本版本修复了数量校验和 npm CLI 入口，并通过 GitHub Actions 可信发布。
需要直接下载安装包、Python wheel 或源码包时，可查看
v0.1.2 Release。
### npm
 [code] 
### pnpm
 [code] 
安装后可直接运行：
 [code] 
也可以不进行全局安装：
 [code] 
如果 npm registry 版本尚未发布或需要测试最新的 `main`：
 [code] 
### 安装相应 skill
全局安装 CLI 后：
 [code] 
不全局安装：
 [code] 
默认安装位置为：
 [code] 
未设置 `CODEX_HOME` 时使用：
 [code] 
可通过 `--target` 安装到其他智能体的技能目录：
 [code] 
已有同名 skill 时默认不覆盖；确认替换时添加 `--force`。安装完成后重启或重新加载智能体，使其发现 `$universal-imagegen`。
### Python 开发版
需要 Python 3.11 或更高版本：
 [code] 
## 配置 API
复制环境变量示例：
 [code] 
在本机 `.env` 中填写密钥：
 [code] 
`.env` 已被 Git 忽略。请勿把真实密钥提交到仓库。
如需项目级非敏感配置：
 [code] 
配置优先级从高到低为：
1. 命令行中的模型、URL、输出等非敏感参数；
2. `IMAGEGEN_*` 环境变量及 `.env`；
3. `--config`、`IMAGEGEN_CONFIG` 或当前目录 `.imagegen.toml`；
4. 项目默认值。
为了避免 shell 历史和进程列表泄密，CLI 故意不提供 `--api-key` 参数。
TOML 中只写 `api_key_env`，密钥本身放在环境变量。
### 自定义兼容服务
只要服务实现兼容的 Images API，即可配置：
 [code] 
自定义服务会收到提示词、输入图像及请求头，请只使用可信端点。
## 常用命令
检查配置，输出会自动隐藏密钥：
 [code] 
仅验证请求，不联网：
 [code] 
生成：
 [code] 
编辑：
 [code] 
批处理：
 [code] 
 [code] 
## 智能体调用约定
智能体应优先执行 dry-run，确认提示词、模型与输出路径后再进行真实请求。
真实执行时建议使用 `--json`，其标准输出只包含结果对象，进度和错误写入
标准错误。成功退出码为 `0`，配置或输入错误为 `2`，API/网络/写入失败为
`1`。
完整的行为约束、决策树和提示词分类见 SKILL.md。
## Node.js 接口
 [code] 
## Python 接口
 [code] 
## 验证和使用反馈
从源码目录运行 `node examples/verify-workflow.mjs`，可以实际走通本地
HTT