Z-image Local image generation with OpenVINO (no API key)

技能：Z-Image 基于 OpenVINO 的本地图像生成（无需 API 密钥）

版本：1.0.3

分块：1/3

模型：snake7gun/Z-Image-Turbo-int4-ov（ModelScope INT4）

技能版本：v1.0.3

网络使用：安装时从 github.com 下载 pip 依赖（部分锁定为 git+https 提交），并从 modelscope.cn 下载模型（约 10 GB，支持断点续传）。

推理完全离线——安装完成后不再需要网络调用。

首次使用？ 第一次使用本技能前，请在终端中分别运行以下两个脚本：

python setup.py          # 创建虚拟环境，安装依赖（约5分钟）
python download_model.py # 下载模型（约10 GB，可续传）

两个脚本均位于本 SKILL.md 所在技能目录中。

目录结构（全部自动创建）

{USERNAME}_openvino\
├── venv\                          ← 共享虚拟环境（由 setup.py 创建）
└── imagegen\
    ├── state.json                 ← 由 setup.py 写入
    ├── generate_image.py          ← 由 setup.py 部署（带版本号）
    ├── Z-Image-Turbo-int4-ov\    ← 由 download_model.py 下载（约10 GB）
    └── outputs\YYYYMMDD_HHMMSS_topic.png

智能体指令

1. 仅限 Windows / PowerShell。 切勿使用 Linux 命令（ls、rm、cat）。切勿使用 && 或 call。
2. **每一步都自行读取 state.json** —— 不要在步骤间手动传递路径。
3. **所有推理和包导入调用均使用 state.json 中的 VENV_PY** —— 切勿使用系统 Python 进行推理或执行步骤 2 的 DEP_CHECK。例外：setup.py、check_env.py、download_model.py 以及步骤 2 中编写脚本的命令有意使用系统 Python 运行（这些脚本仅使用标准库或创建/验证虚拟环境，因此不能依赖虚拟环境）。
4. **关键 —— 切勿手动修改 generate_image.py。** 它由 setup.py 部署并管理版本。如果它失败或丢失，请重新运行 setup.py。
5. 目标：生成图像并将预览发送到对话中。

自动恢复策略 —— 先尝试，再询问用户：

* 如果 STATE=MISSING、VENV_PY=BROKEN、PACKAGES_MISSING 或 SCRIPTS_STALE：自动运行 setup.py（最多尝试 3 次）。仅在所有 3 次尝试均失败时才询问用户。

* 如果 MODEL_STATUS=MISSING：自动运行 download_model.py（最多尝试 3 次）。如果单次尝试超过 20 分钟则停止 —— 下载支持断点续传，不会丢失已下载的部分进度。

* 每次尝试前始终提示：[INFO] Auto-installing environment (attempt N/3)…

[警告] 网络/代理处理 —— 运行 setup.py 或 download_model.py 时：

1. 检查代理：读取 $env:HTTPS_PROXY / $env:HTTP_PROXY；如果未设置，运行 netsh winhttp show proxy。
2. 如果检测到代理：自动应用并继续。
3. 如果没有代理且下载/设置失败：告知用户，建议配置代理，然后重试。

许多网络（企业网络 / 中国大陆 / 校园网络）需要代理。下载支持断点续传 —— 修复网络后可安全重试。

流程 —— 严格按照以下顺序执行，不可跳过：

步骤 0：扩展提示词          → EXPANDED_PROMPT, TOPIC
步骤 1：验证环境          → VENV_PY, IMAGE_GEN_DIR 确认就绪
         ↳ 如果 STATE=MISSING 或 VENV_BROKEN 或 PACKAGES_MISSING：自动运行 setup.py（3次尝试）
         ↳ 如果 MODEL_STATUS=MISSING：自动运行 download_model.py（3次尝试）
步骤 2：验证依赖          → DEP_CHECK=PASS
步骤 3：生成并发送       → [SUCCESS] + 图像预览

预检：验证运行时要求（首次使用必需）

预检：检查 Python 和 git...

检查 Python 版本

python --version

解释：

如果输出包含“未找到请运行...”，则 Windows 商店应用执行别名正在遮挡真正的 Python。不要要求用户更改设置，也不要编写辅助脚本。运行以下命令找到真正的 Python：

where.exe python 2>$null | Where-Object { $_ -notlike "*WindowsApps*" } | Select-Object -First 1

* 若输出一个路径 → **将此字符串原文记录为 SYSTEM_PYTHON**（系统级 Python，仅用于 setup.py、check_env.py、download_model.py）。对于所有标记为 [SYSTEM PYTHON] 的命令，将 python 替换为完整的文字路径。切勿将此路径用于推理 —— 推理必须始终使用 VENV_PY。不要在工具调用间使用 $variable —— 每次调用都是新 shell，请始终直接嵌入文字路径。

* 若未输出任何内容 → Python 未安装 —— 请安装（见下文）。

如果 Python 缺失或版本过旧，在 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 自动将 Python 添加到 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

git --version

解释：

如果 git 缺失，在 PowerShell 中运行以下单命令静默安装程序：

Skill Contract (Input / Output)

接受的输入

1. 文本描述（必需）— 描述要生成的图像的英文或中文提示。
2. 可选参数：

* steps：推理步数，默认为 9（越高细节越多）

* size：512×512 | 768×768 | 1024×1024，默认为 512×512

* seed：整数（默认 42）或 -1 表示随机

* output：PNG 文件的自定义绝对输出路径

成功时的输出

在 stdout 中返回 PNG 文件路径，格式为 [SUCCESS] <path>，并通过 message 工具发送预览。

{
    "image_path": "C:\\...\\outputs\\20260412_153000_panda_bamboo.png",
    "topic": "panda_bamboo",
    "prompt": "A giant panda sitting in a lush bamboo forest...",
    "steps": 9,
    "size": "512x512",
    "seed": 42,
    "device": "GPU.0"
}

失败时的输出

{
    "error": "人类可读描述",
    "stage": "environment | model | inference",
    "recoverable": true
}

步骤 0：扩展提示（仅 LLM — 不使用工具）

同时执行两项操作：① 扩展提示 和 ② 提取主题标识（英文 snake_case，用于文件名）。

扩展结构：[subject] [action/pose] [environment] [lighting/mood] [style] [quality tags]

提示可以是英文或中文 — 无需翻译。主题标识必须始终是英文，以避免路径编码问题。

质量标签：photorealistic，8K resolution，cinematic lighting，masterpiece

在继续之前显示结果：

Input:    {user description}
   Expanded: {full prompt}
   Topic:    {topic_slug}

步骤 1：验证环境与模型

步骤 1/3：检查环境与模型…

# [SYSTEM PYTHON] check_env.py 验证虚拟环境 — 不得使用虚拟环境的 Python
python "<skill_dir>\check_env.py"

输出解释：

成功时：从 stdout 中记录 VENV_PY 和 IMAGE_GEN_DIR，然后继续执行步骤 2。

如果 SCRIPTS_STALE 与 MODEL_STATUS=READY 同时出现，则在步骤 2 之前自动运行 setup.py（见下方）。

如果出现 SCRIPTS_STALE 或 STATE=MISSING 或 VENV_PY=BROKEN 或 PACKAGES_MISSING → 自动运行 setup.py

SCRIPTS_STALE 表示虚拟环境和模型均正常，但 IMAGE_GEN_DIR 中的 generate_image.py 是旧版本。setup.py 是幂等的 — 如果虚拟环境/包已经健康，它会跳过，只重新部署脚本。

PACKAGES_MISSING 表示虚拟环境存在，但缺少必需的包（openvino，torch，optimum.intel）。重新运行 setup.py 仅重新安装缺失的包。

通知并运行（最多尝试 3 次）：

[INFO] 环境未初始化 — 自动安装中（尝试 1/3）…

# [SYSTEM PYTHON] setup.py 创建虚拟环境 — 不得使用虚拟环境的 Python
python "<skill_dir>\setup.py"

每次尝试后重新运行 python "<skill_dir>\check_env.py"。如果所有 3 次都失败，则显示下面的手动降级方案。

如果 MODEL_STATUS=MISSING → 自动运行 download_model.py

通知用户并询问如何处理：

未找到模型 — 需要下载（约 10 GB）
   预计时间：
   • 100 Mbps → 约 15 分钟
   •  50 Mbps → 约 30 分钟
   •  10 Mbps → 约 2 小时
   下载支持断点续传 — 可安全中断并重试。

   [Y] 开始自动下载
   [N] 我将手动下载 — 给我链接

自动下载（最多尝试 3 次，单次尝试超过 20 分钟则停止）：

# [SYSTEM PYTHON] download_model.py 仅使用标准库 — 不得使用虚拟环境的 Python
python "<skill_dir>\download_model.py"

每次尝试后重新运行 python "<skill_dir>\check_env.py"。

手动下载降级方案：

ModelScope 页面：https://modelscope.cn/models/snake7gun/Z-Image-Turbo-int4-ov/files

将所有文件放置到 <IMAGE_GEN_DIR>\Z-Image-Turbo-int4-ov\ 下。必要的子目录：

Z-Image-Turbo-int4-ov\
├── transformer\
├── vae_decoder\
└── text_encoder\

然后重新运行 python "<skill_dir>\check_env.py" 进行验证。

手动降级方案（仅当所有 3 次自动设置尝试均失败时）

向用户显示：

[WARN] 自动安装失败。请手动在终端中运行：

1) 安装环境：

python "<skill_dir>\setup.py"

大约需要 5 分钟，全自动完成。

2) 下载模型（约 10 GB）：

python "<skill_dir>\download_model.py"

支持断点续传——可以安全中断并重试。

完成后返回此处。

步骤 2：验证依赖

步骤 2/3：正在验证依赖…

验证依赖（通过 VENV_PY 运行）：

$env:PYTHONUTF8 = "1"
& "<VENV_PY>" -c "
import json, site
from pathlib import Path

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))

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

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 = '[OK]' if status == 'OK' else ('[WARN]' if status == 'WRONG' else '[MISSING]')
    print(f'  {icon} {k}: {detail}')
print('DEP_CHECK=PASS' if all_ok else 'DEP_CHECK=FAIL')
"

步骤 3：生成图像并发送预览

步骤 3/3：正在运行推理…

分别执行以下两条命令：

$env:PYTHONUTF8 = "1"

& "<VENV_PY>" "<IMAGE_GEN_DIR>\generate_image.py" --prompt "EXPANDED_PROMPT" --topic "TOPIC" --steps 9 --seed 42

通过条件：标准输出包含 [SUCCESS]。从该行记录 OUTPUT_PATH。

通过 message 工具发送预览：

action: "send"  filePath: "OUTPUT_PATH"  message: "[OK] TOPIC"

最终宣告：

[OK] 完成！路径：<OUTPUT_PATH>
提示：{expanded prompt}
steps=9, 512×512, seed=42 | 设备：{CPU/GPU}

参数

guidance_scale 固定为 0.0，不暴露为参数。

故障排除