img-cli 0.1.0__tar.gz

img_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    name: Build package and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/img-cli
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publishing (OIDC)
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history and tags for hatch-vcs dynamic versioning
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Run tests
+        run: |
+          uv run pytest -v
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true

img_cli-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+src/img_cli/_version.py
+
+# Virtual Environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing and coverage
+.cache
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# IDE & Editor files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Operating System files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

img_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8DE4732A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

img_cli-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: img-cli
+Version: 0.1.0
+Summary: CLI tool for OpenAI-compatible Image Generation and Editing
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.7
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.50.0
+Requires-Dist: pillow>=10.2.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=13.7.0
+Description-Content-Type: text/markdown
+
+# img-cli
+
+命令行图片生成与编辑工具，基于 Python + uv 开发，封装 OpenAI 兼容的 Images API（文生图 `generate` 与图生图编辑 `edit`）。
+
+<p align="center">
+  <img src="assets/poster.png" alt="img-cli Poster" width="600" />
+</p>
+
+---
+
+## 特性
+
+- 🚀 **简单易用**：一行命令完成图片生成和图片编辑。
+- 🔑 **灵活认证**：支持 `~/.img_gen/auth.json` 配置文件及环境变量。
+- 📝 **审计日志**：自动在 `~/.img_gen/img.log` 记录每次请求详情（JSON Lines 格式）。
+- 🖼️ **格式与尺寸自适应**：支持 PNG / JPEG / WEBP，自动进行 RGBA 蒙版和格式转换。
+- 🌐 **网络与本地图片支持**：编辑模式下原图和蒙版均支持本地路径（含 `~`）及 HTTP/HTTPS URL。
+- 🤖 **Agent 友好**：清晰的标准输出与结构化错误码，便于自动化工作流接入。
+
+---
+
+## 安装与环境准备
+
+### 通过 PyPI 安装
+
+```bash
+# 使用 uv 工具安装（推荐）
+uv tool install img-cli
+
+# 或通过 pip 安装
+pip install img-cli
+```
+
+### 本地开发与运行
+
+```bash
+# 1. 运行测试 / 调试
+uv run img-cli --help
+
+# 2. 从源码安装 CLI
+uv tool install .
+```
+
+---
+
+## 认证配置
+
+首次使用前，请创建配置文件 `~/.img_gen/auth.json`：
+
+```bash
+mkdir -p ~/.img_gen
+echo '{"api_key":"sk-xxx","api_base":"https://api.openai.com/v1"}' > ~/.img_gen/auth.json
+```
+
+也可通过环境变量传入：
+- `OPENAI_API_KEY`（或 `IMG_GEN_API_KEY`）
+- `OPENAI_BASE_URL`（或 `OPENAI_API_BASE` / `IMG_GEN_API_BASE`）
+
+---
+
+## 快速使用
+
+### 1. 文生图 (generate)
+
+```bash
+# 基础生成（默认模型 gpt-image-2，保存至当前目录）
+img-cli generate "一只戴墨镜的猫坐在沙滩上"
+
+# 指定模型、尺寸与输出目录
+img-cli generate "a futuristic city at sunset" -m dall-e-3 -s 1792x1024 -q hd -o ~/Desktop
+
+# 指定输出格式为 JPEG
+img-cli generate "产品白底宣传图，极简风格" -m gpt-image-1 -q high --format jpeg -o ./output
+```
+
+### 2. 图片编辑 (edit)
+
+```bash
+# 本地图片全图编辑
+img-cli edit "给猫戴上一顶红色圣诞帽" --image ./cat.png -o ./output
+
+# 网络图片直接编辑
+img-cli edit "替换背景为星空" --image https://example.com/photo.jpg -o ./output
+
+# 带蒙版的局部编辑（蒙版透明区域为待修改区域）
+img-cli edit "用一朵玫瑰替换这里" --image ./photo.png --mask ./mask.png -o ./output
+```
+
+---
+
+## 命令参数参考
+
+### `img-cli generate <prompt>`
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 提示词（支持中文与英文） |
+| `-m`, `--model` | `gpt-image-2` | 模型名称（如 `gpt-image-2`, `dall-e-3`, `gpt-image-1`） |
+| `-s`, `--size` | `1024x1024` | 尺寸（如 `1024x1024`, `1536x1024`, `1024x1536`, `auto`） |
+| `-q`, `--quality` | 无 | 质量（`low` / `medium` / `high` / `auto` / `standard` / `hd`） |
+| `-n`, `--n` | `1` | 生成张数 |
+| `-o`, `--output` | `.` | 图片输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |
+
+### `img-cli edit <prompt>`
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 修改描述 |
+| `-i`, `--image` | 必填 | 原图：本地路径或 HTTP/HTTPS URL |
+| `--mask` | 无 | 蒙版：本地路径或 URL（PNG 透明区域待修改） |
+| `-m`, `--model` | `gpt-image-2` | 模型名称 |
+| `-s`, `--size` | `auto` | 尺寸 |
+| `-q`, `--quality` | `auto` | 质量 |
+| `-n`, `--n` | `1` | 生成张数 |
+| `-o`, `--output` | `.` | 图片输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |
+
+---
+
+## 运行测试
+
+```bash
+uv run pytest -v
+```

img_cli-0.1.0/README.md

@@ -0,0 +1,125 @@
+# img-cli
+
+命令行图片生成与编辑工具，基于 Python + uv 开发，封装 OpenAI 兼容的 Images API（文生图 `generate` 与图生图编辑 `edit`）。
+
+<p align="center">
+  <img src="assets/poster.png" alt="img-cli Poster" width="600" />
+</p>
+
+---
+
+## 特性
+
+- 🚀 **简单易用**：一行命令完成图片生成和图片编辑。
+- 🔑 **灵活认证**：支持 `~/.img_gen/auth.json` 配置文件及环境变量。
+- 📝 **审计日志**：自动在 `~/.img_gen/img.log` 记录每次请求详情（JSON Lines 格式）。
+- 🖼️ **格式与尺寸自适应**：支持 PNG / JPEG / WEBP，自动进行 RGBA 蒙版和格式转换。
+- 🌐 **网络与本地图片支持**：编辑模式下原图和蒙版均支持本地路径（含 `~`）及 HTTP/HTTPS URL。
+- 🤖 **Agent 友好**：清晰的标准输出与结构化错误码，便于自动化工作流接入。
+
+---
+
+## 安装与环境准备
+
+### 通过 PyPI 安装
+
+```bash
+# 使用 uv 工具安装（推荐）
+uv tool install img-cli
+
+# 或通过 pip 安装
+pip install img-cli
+```
+
+### 本地开发与运行
+
+```bash
+# 1. 运行测试 / 调试
+uv run img-cli --help
+
+# 2. 从源码安装 CLI
+uv tool install .
+```
+
+---
+
+## 认证配置
+
+首次使用前，请创建配置文件 `~/.img_gen/auth.json`：
+
+```bash
+mkdir -p ~/.img_gen
+echo '{"api_key":"sk-xxx","api_base":"https://api.openai.com/v1"}' > ~/.img_gen/auth.json
+```
+
+也可通过环境变量传入：
+- `OPENAI_API_KEY`（或 `IMG_GEN_API_KEY`）
+- `OPENAI_BASE_URL`（或 `OPENAI_API_BASE` / `IMG_GEN_API_BASE`）
+
+---
+
+## 快速使用
+
+### 1. 文生图 (generate)
+
+```bash
+# 基础生成（默认模型 gpt-image-2，保存至当前目录）
+img-cli generate "一只戴墨镜的猫坐在沙滩上"
+
+# 指定模型、尺寸与输出目录
+img-cli generate "a futuristic city at sunset" -m dall-e-3 -s 1792x1024 -q hd -o ~/Desktop
+
+# 指定输出格式为 JPEG
+img-cli generate "产品白底宣传图，极简风格" -m gpt-image-1 -q high --format jpeg -o ./output
+```
+
+### 2. 图片编辑 (edit)
+
+```bash
+# 本地图片全图编辑
+img-cli edit "给猫戴上一顶红色圣诞帽" --image ./cat.png -o ./output
+
+# 网络图片直接编辑
+img-cli edit "替换背景为星空" --image https://example.com/photo.jpg -o ./output
+
+# 带蒙版的局部编辑（蒙版透明区域为待修改区域）
+img-cli edit "用一朵玫瑰替换这里" --image ./photo.png --mask ./mask.png -o ./output
+```
+
+---
+
+## 命令参数参考
+
+### `img-cli generate <prompt>`
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 提示词（支持中文与英文） |
+| `-m`, `--model` | `gpt-image-2` | 模型名称（如 `gpt-image-2`, `dall-e-3`, `gpt-image-1`） |
+| `-s`, `--size` | `1024x1024` | 尺寸（如 `1024x1024`, `1536x1024`, `1024x1536`, `auto`） |
+| `-q`, `--quality` | 无 | 质量（`low` / `medium` / `high` / `auto` / `standard` / `hd`） |
+| `-n`, `--n` | `1` | 生成张数 |
+| `-o`, `--output` | `.` | 图片输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |
+
+### `img-cli edit <prompt>`
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 修改描述 |
+| `-i`, `--image` | 必填 | 原图：本地路径或 HTTP/HTTPS URL |
+| `--mask` | 无 | 蒙版：本地路径或 URL（PNG 透明区域待修改） |
+| `-m`, `--model` | `gpt-image-2` | 模型名称 |
+| `-s`, `--size` | `auto` | 尺寸 |
+| `-q`, `--quality` | `auto` | 质量 |
+| `-n`, `--n` | `1` | 生成张数 |
+| `-o`, `--output` | `.` | 图片输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp` |
+
+---
+
+## 运行测试
+
+```bash
+uv run pytest -v
+```

img_cli-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "img-cli"
+dynamic = ["version"]
+description = "CLI tool for OpenAI-compatible Image Generation and Editing"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.1.7",
+    "httpx>=0.27.0",
+    "openai>=1.50.0",
+    "pillow>=10.2.0",
+    "rich>=13.7.0",
+    "pydantic>=2.6.0",
+]
+
+[project.scripts]
+img-cli = "img_cli.cli:main"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/img_cli/_version.py"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-mock>=3.14.0",
+    "respx>=0.21.0",
+    "ruff>=0.9.0",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "RUF", # ruff-specific rules
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+    "B008",  # do not perform function calls in argument defaults (click options)
+    "RUF001", # ambiguous unicode characters in Chinese strings
+    "RUF002", # ambiguous unicode characters in docstrings
+    "RUF003", # ambiguous unicode characters in comments
+]

img_cli-0.1.0/skills/img-cli/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: img-cli
+description: 当用户需要生成图片、创建图片、用文字描述画图、修改图片、编辑图片、给图片加元素、替换图片背景时使用本技能，包括"生成图片"、"画一张"、"文生图"、"改图"、"编辑图片"、"img-cli"、"image generation"、"image edit"等请求。
+allowed-tools:
+  - Bash(img-cli generate *)
+  - Bash(img-cli edit *)
+---
+
+# 图片生成与编辑（img-cli）
+
+通过 `img-cli` 调用 OpenAI Images API 生成或编辑图片。
+
+## 安装说明
+
+使用 `uv`（推荐）或 `pip` 进行安装：
+
+```bash
+# 使用 uv 工具安装（推荐）
+uv tool install img-cli
+
+# 或通过 pip 安装
+pip install img-cli
+```
+
+> **认证说明：** 所有命令需要 `~/.img_gen/auth.json` 中配置 `api_key` 和 `api_base`。
+> 若报错"未找到认证文件"，请创建该文件：
+> ```bash
+> mkdir -p ~/.img_gen
+> echo '{"api_key":"sk-xxx","api_base":"https://api.openai.com/v1"}' > ~/.img_gen/auth.json
+> ```
+
+---
+
+## 命令总览
+
+| 命令 | 说明 |
+|---|---|
+| `img-cli generate <prompt>` | 文字描述生成图片 |
+| `img-cli edit <prompt>` | 根据描述修改已有图片 |
+
+---
+
+## 命令参考
+
+### `img-cli generate`
+
+根据文字描述生成图片。
+
+```bash
+img-cli generate <prompt> [OPTIONS]
+```
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 图片描述，支持中文和英文 |
+| `--model` / `-m` | `gpt-image-2` | 模型（目前仅支持 `gpt-image-2`） |
+| `--size` / `-s` | `1024x1024` | 尺寸，见下方支持列表 |
+| `--quality` / `-q` | 无 | 质量，见下方支持列表 |
+| `--n` / `-n` | `1` | 生成数量（`dall-e-3` 固定为 1） |
+| `--output` / `-o` | `.`（当前目录） | 输出目录 |
+| `--format` | `png` | 输出格式：`png` / `jpeg` / `webp`（仅 `gpt-image-1` 有效） |
+
+**gpt-image-2 支持的尺寸：** `1024x1024` / `1536x1024` / `1024x1536` / `auto`
+
+**gpt-image-2 支持的 quality：** `low` / `medium` / `high` / `auto`
+
+**示例：**
+
+```bash
+# 使用默认模型（dall-e-3）生成
+img-cli generate "一只戴墨镜的猫坐在沙滩上" --output ~/Desktop
+
+# 生成横版高清图
+img-cli generate "a futuristic city at sunset" -m dall-e-3 -s 1792x1024 -q hd -o ~/Desktop
+
+# 使用 gpt-image-1 生成高质量图片
+img-cli generate "产品白底宣传图，简洁风格" -m gpt-image-1 -q high -o ~/Desktop
+```
+
+---
+
+### `img-cli edit`
+
+根据文字描述修改已有图片。支持本地文件路径和网络图片 URL。
+
+```bash
+img-cli edit <prompt> --image <路径或URL> [OPTIONS]
+```
+
+| 参数 | 默认值 | 说明 |
+|---|---|---|
+| `prompt` | 必填 | 修改描述 |
+| `--image` / `-i` | 必填 | 原图：本地文件路径或 HTTP URL |
+| `--mask` | 无 | 蒙版图（PNG，透明区域为待编辑区域）：本地路径或 URL |
+| `--model` / `-m` | `gpt-image-2` | 模型（目前仅支持 `gpt-image-2`） |
+| `--size` / `-s` | `auto` | 尺寸 |
+| `--quality` / `-q` | `auto` | 质量（仅 `gpt-image-1`） |
+| `--n` / `-n` | `1` | 生成数量 |
+| `--output` / `-o` | `.`（当前目录） | 输出目录 |
+| `--format` | `png` | 输出格式（仅 `gpt-image-1`） |
+
+**关于蒙版（mask）：**
+- 蒙版为 PNG 格式，尺寸必须与原图相同
+- **透明区域（alpha=0）** = 需要编辑的区域
+- **不透明区域** = 保持原样的区域
+- 不传 mask 时，模型自动判断需要修改的区域
+
+**示例：**
+
+```bash
+# 修改本地图片（全图编辑）
+img-cli edit "给猫戴上一顶帽子" --image ~/Desktop/cat.png --output ~/Desktop
+
+# 修改网络图片
+img-cli edit "替换背景为星空" --image https://example.com/photo.jpg -o ~/Desktop
+
+# 带蒙版的精确编辑（只修改透明区域）
+img-cli edit "用一朵玫瑰替换这里" --image ~/photo.png --mask ~/mask.png -o ~/Desktop
+
+# 使用 dall-e-2 编辑（低成本场景）
+img-cli edit "remove the background" --image ~/item.png -m dall-e-2 -o ~/Desktop
+```
+
+---
+
+## 标准使用流程
+
+### 场景一：文字生成图片
+
+```bash
+# 1. 直接生成，保存到当前目录
+img-cli generate "一只在雪地里奔跑的柴犬，卡通风格"
+
+# 2. 指定输出目录和更高质量
+img-cli generate "一只在雪地里奔跑的柴犬，卡通风格" -q hd -o ~/Desktop/output
+```
+
+### 场景二：修改已有图片
+
+```bash
+# 1. 先确认图片路径可访问
+ls ~/Desktop/photo.png   # 本地文件
+
+# 2. 执行编辑
+img-cli edit "将背景替换为办公室环境" --image ~/Desktop/photo.png -o ~/Desktop/output
+```
+
+### 场景三：网络图片直接编辑
+
+```bash
+# 直接传入图片 URL，无需手动下载
+img-cli edit "添加一个太阳" --image https://example.com/landscape.jpg -o ~/Desktop
+```
+
+---
+
+## 输出说明
+
+- 生成的图片保存到 `--output` 指定目录，文件名格式为 `img_<时间戳>_<序号>.<格式>`
+- 每次调用在 `~/.img_gen/img.log` 写入审计记录（JSON Lines 格式）
+- `dall-e-3` 会输出 **修订后的 prompt**（模型对原始描述的优化版本）
+- 输出耗时可能较长比如3-4分钟
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方式 |
+|---|---|---|
+| "未找到认证文件" | `~/.img_gen/auth.json` 不存在 | 按提示创建配置文件 |
+| `dall-e-3` 只能生成 1 张 | API 限制，`n` 固定为 1 | 多次执行命令 |
+| 图片 URL 下载超时 | 网络问题或 URL 失效 | 先手动下载为本地文件再使用 |
+| "invalid size" 错误 | 尺寸与模型不匹配 | 参考上方模型能力对比表 |

img_cli-0.1.0/src/img_cli/__init__.py

@@ -0,0 +1,13 @@
+"""img-cli: CLI tool for OpenAI-compatible Image Generation and Editing."""
+
+try:
+    from img_cli._version import __version__, __version_tuple__
+except ImportError:
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("img-cli")
+        __version_tuple__ = (0, 0, 0)
+    except Exception:
+        __version__ = "0.0.0.dev0"
+        __version_tuple__ = (0, 0, 0, "dev0")

img_cli-0.1.0/src/img_cli/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None