Local image generator on Intel platform

本地文生图、AI画图、生成图像、画一张图、帮我画、生成图片、创作图像、制作一幅图、 图像生成、文字生成图片、AI绘画、画个XX、我想要一张XX的图、本地生图、离线生图。 generate an image, create a picture, draw something, make an image of, text to image, paint a picture, illustrate, visualize, local image generation, AI art, image synthesis. 使用 Z-Image-Turbo 模型在本机 Windows 离线运行，支持中英双语提示词， 自动优先 Intel iGPU 推理，无需联网，不调用任何云端 API。

# 本地文生图 (Windows · Z-Image-Turbo · OpenVINO)

**模型**：`snake7gun/Z-Image-Turbo-int4-ov`（ModelScope INT4）  
**接口**：`optimum.intel.OVZImagePipeline`  
**技能目录**：`{baseDir}`（含 `SKILL.md` 与 `requirements_imagegen.txt`）  
**SKILL_VERSION**：`v1.0`　← Step 4 用此版本号判断是否覆写脚本

## 目录结构（全部自动生成）

```
<IMAGE_GEN_DIR>\               ← 自动定位或创建（如 D:\image-gen-local）
├── image_gen\                 ← venv（Pre-flight 后 Step 2 自动创建）
├── generate_image.py          ← Step 4 自动写入
├── Z-Image-Turbo-int4-ov\     ← 首次自动从 ModelScope 下载（约 10 GB）
└── outputs\20260318_panda_bamboo.png  ← 文件名：YYYYMMDD_HHMMSS_topic_en.png
```

---

## ⚠️ AI 助手执行须知

1. 每次只执行一个命令，等输出后再决定下一步。
2. 遇错立即停止，对照末尾"错误排查"表处理。
3. 所有路径用双引号包裹。
4. `{baseDir}` 由运行时自动注入为本 SKILL.md 所在目录的绝对路径（例如 `C:\Users\you\skills\local-image-generation`）。若注入失败或命令报路径不存在，请将 `{baseDir}` 手动替换为该目录的实际绝对路径后再执行。`requirements_imagegen.txt` 位于此目录下。
5. **唯一目标**：生成图像并在对话中预览。

**执行流程（不可跳过）**：
```
Pre-flight: 检查 Python ≥3.10 + git  → PYTHON_OK + GIT_OK
Step 0:     扩充提示词 + 提炼主题词   → 展示给用户
Step 1:     定位工作目录              → IMAGE_GEN_DIR
Step 2:     激活 venv，验证依赖       → DEP_CHECK=PASS
Step 3:     检查磁盘空间 + 模型       → MODEL_STATUS=READY 则跳过下载
Step 4:     写入脚本（版本检查）      → SCRIPT_UPDATE=DONE/SKIPPED
Step 5:     生图 + 预览               → 发送图像到对话
```

**进度播报**：每步开始前向用户播报，格式：`🔍 Pre-flight：检查运行环境…`

---

## Pre-flight：检查运行环境（首次使用必做，后续可跳过）

> 🔍 Pre-flight：检查 Python 和 git…

### 检查 Python 版本

```bat
python --version
```

**判断结果**：

| 输出 | 操作 |
|------|------|
| `Python 3.10.x` 或更高 | ✅ `PYTHON_OK`，继续检查 git |
| `Python 3.8 / 3.9` | ⛔ 版本过低，需升级（见下方） |
| `'python' 不是内部或外部命令` | ⛔ Python 未安装，需安装（见下方） |

**Python 未安装或版本过低时**，用 PowerShell 一键下载静默安装（推荐，无需管理员权限）：

```powershell
$f = "$env:TEMP\python-installer.exe"
Invoke-WebRequest "https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe" -OutFile $f
Start-Process $f -ArgumentList "/quiet InstallAllUsers=0 PrependPath=1 Include_pip=1" -Wait
Remove-Item $f
```

> `PrependPath=1` 自动加 PATH；`Include_pip=1` 同时装 pip；`InstallAllUsers=0` 无需管理员权限。

安装完成后**重启终端**，执行 `python --version` 确认输出 `Python 3.12.x`。

若偏好手动安装：直接下载 **https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe**，运行时**务必勾选 "Add python.exe to PATH"**。

### 检查 git

```bat
git --version
```

**判断结果**：

| 输出 | 操作 |
|------|------|
| `git version 2.x.x` | ✅ `GIT_OK`，Pre-flight 通过 |
| `'git' 不是内部或外部命令` | ⛔ git 未安装，需安装（见下方） |

**git 未安装时**，用 PowerShell 一键下载静默安装：

```powershell
$f = "$env:TEMP\git-installer.exe"
Invoke-WebRequest "https://github.com/git-for-windows/git/releases/download/v2.49.0.windows.1/Git-2.49.0-64-bit.exe" -OutFile $f
Start-Process $f -ArgumentList "/VERYSILENT /NORESTART /NOCANCEL /SP- /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS /COMPONENTS=icons,ext\reg\shellhere,assoc,assoc_sh" -Wait
Remove-Item $f
```

安装完成后**重启终端**，执行 `git --version` 确认。

若偏好手动安装：浏览器打开 **https://git-scm.com/download/win**，下载并运行安装程序，全程保持默认选项即可。

> git 是 `requirements_imagegen.txt` 中 `git+https://` 依赖的必要工具，缺少时 `pip install` 会报 `git: command not found`。

**Pre-flight 通过标准**：`python --version` ≥ 3.10 且 `git --version` 有输出。  
播报：`✅ Python 和 git 就绪，开始执行主流程。`

---

## Step 0：扩充提示词（LLM 自身完成，无需工具）

同时完成两件事：**① 扩充提示词** ② **提炼主题词**（用于文件名，**必须为英文 snake_case**）

扩充结构：`[主体] [动作/姿态] [环境/背景] [光线/氛围] [风格] [质量词]`

**支持中英双语**，无需翻译。中文场景优先用中文，英文输入保持英文。  
**主题词统一使用英文**（snake_case，如 `panda_bamboo`），避免中文路径编码问题。

质量词参考：`超写实/photorealistic`、`8K分辨率/8K resolution`、`电影级光照/cinematic lighting`、`杰作/masterpiece`

| 输入 | 主题词（英文） | 扩充后提示词 |
|------|--------|------------|
| 一只熊猫 | `panda_bamboo` | 一只大熊猫坐在翠绿竹林中，阳光透过竹叶洒落，超写实，8K，野生动物摄影 |
| cyberpunk city | `cyberpunk_city` | A futuristic megacity at night, neon signs on rain-slicked streets, cyberpunk, cinematic, 8K |

完成后**必须展示**：
```
📝 原始输入：{用户描述}
   扩充后：{完整提示词}
   主题词：{topic_en}（英文，用于文件命名）
```

---

## Step 1：定位工作目录

> 🔍 Step 1/5：正在定位工作目录…

```python
python -c "
import string, shutil
from pathlib import Path
drives = [f'{d}:\\\\' for d in string.ascii_uppercase if Path(f'{d}:\\\\').exists()]
print(f'[INFO] 检测到磁盘: {drives}')
found = None
for drive in drives:
    candidate = Path(drive) / 'image-gen-local'
    if candidate.exists():
        found = candidate
        break
if not found:
    best = max(drives, key=lambda d: shutil.disk_usage(d).free)
    found = Path(best) / 'image-gen-local'
    found.mkdir(parents=True, exist_ok=True)
    print(f'[INFO] 已创建: {found}')
print(f'IMAGE_GEN_DIR={found}')
"
```

**成功标准**：输出含 `IMAGE_GEN_DIR=` 的行，记录路径，后续替换 `<IMAGE_GEN_DIR>`。

---

## Step 2：激活 venv 并验证依赖

> ⚙️ Step 2/5：验证 Python 环境和依赖…

```bat
call "<IMAGE_GEN_DIR>\image_gen\Scripts\activate.bat"
python -c "import sys; print(sys.executable)"
```

**成功标准**：路径含 `image_gen`。

**若 venv 不存在**（activate.bat 报错），按顺序逐条执行，不可合并：
```bat
python -m ensurepip --upgrade
```
```bat
python -m venv "<IMAGE_GEN_DIR>\image_gen"
```
```bat
call "<IMAGE_GEN_DIR>\image_gen\Scripts\activate.bat"
```
```bat
python -m pip install --upgrade pip
```
```bat
pip install -r "{baseDir}\requirements_imagegen.txt"
```

> ⚠️ **关键**：`pip install` 必须在 `activate.bat` 执行之后运行，否则包会装进系统 Python 而不是 venv，导致 venv 内依赖验证失败。
> 激活成功的标志是命令行前缀出现 `(image_gen)`，如 `(image_gen) C:\image-gen-local>`。

**验证依赖（必须执行）**：

> ⚠️ 执行前确认命令行前缀为 `(image_gen)`，否则先执行 `call "<IMAGE_GEN_DIR>\image_gen\Scripts\activate.bat"`。

```python
python -c "
import json, site
from pathlib import Path

# 期望的 git commit hash（前8位匹配）
EXPECTED_COMMITS = {
    'optimum_intel': '2f62e5ae',
    'diffusers':     'a1f36ee3',
}

def get_git_commit(pkg_name):
    dirs = site.getsitepackages()
    try: dirs += [site.getusersitepackages()]
    except Exception: pass
    for d in dirs:
        for dist in Path(d).glob(f'{pkg_name}*.dist-info'):
            url_file = dist / 'direct_url.json'
            if url_file.exists():
                data = json.loads(url_file.read_text(encoding='utf-8'))
                return data.get('vcs_info', {}).get('commit_id', 'no_vcs_info')
    return 'not_found'

results = {}

# 普通包
for pkg, imp in [('openvino','openvino'),('torch','torch'),('Pillow','PIL'),('modelscope','modelscope')]:
    try:
        ver = getattr(__import__(imp), '__version__', 'OK')
        results[pkg] = ('OK', ver)
    except ImportError as e:
        results[pkg] = ('MISSING', str(e))

# OVZImagePipeline 可用性
try:
    from optimum.intel import OVZImagePipeline
    results['OVZImagePipeline'] = ('OK', 'importable')
except ImportError as e:
    results['OVZImagePipeline'] = ('MISSING', str(e))

# git commit 精确验证
for pkg_name, exp in EXPECTED_COMMITS.items():
    actual = get_git_commit(pkg_name)
    if actual == 'not_found':
        results[f'{pkg_name}@commit'] = ('MISSING', 'not installed via git+https')
    elif actual.startswith(exp):
        results[f'{pkg_name}@commit'] = ('OK', actual[:16])
    else:
        results[f'{pkg_name}@commit'] = ('WRONG', f'got {actual[:16]} want {exp}...')

all_ok = all(v[0] == 'OK' for v in results.values())
for k, (status, detail) in results.items():
    icon = '✅' if status == 'OK' else ('⚠️' if status == 'WRONG' else '❌')
    print(f'  {icon} {k}: {detail}')
print('DEP_CHECK=PASS' if all_ok else 'DEP_CHECK=FAIL')
"
```

| 输出 | 操作 |
|------|------|
| `DEP_CHECK=PASS` | ✅ 进入 Step 3，播报：`✅ 环境就绪。` |
| `DEP_CHECK=FAIL`（MISSING） | ⛔ 执行 `pip install -r "{baseDir}\requirements_imagegen.txt"` 后重新验证 |
| `DEP_CHECK=FAIL`（`@commit` 显示 WRONG） | ⛔ commit 不匹配，执行下方强制重装 |

**commit 不匹配时强制重装**：
```bat
pip uninstall optimum-intel diffusers -y
pip install -r "{baseDir}\requirements_imagegen.txt" --no-cache-dir
```
> `--no-cache-dir` 防止 pip 读取旧缓存导致 commit 未更新。

---

## Step 3：检查磁盘空间 + 模型

> 📦 Step 3/5：检查磁盘空间和模型文件…

**先检查磁盘空间**（模型约 10 GB，venv 约 3 GB，需至少 15 GB 余量）：

```python
python -c "
import shutil
from pathlib import Path
target = Path(r'<IMAGE_GEN_DIR>')
free_gb = shutil.disk_usage(target).free / (1024**3)
print(f'DISK_FREE={free_gb:.1f}GB')
if free_gb < 15:
    print('DISK_STATUS=LOW')
    print(f'[WARN] 可用空间不足 15 GB，模型下载可能中途失败')
else:
    print('DISK_STATUS=OK')
"
```

| 输出 | 操作 |
|------|------|
| `DISK_STATUS=OK` | ✅ 继续检查