draw-thing

Draw Thing

通过 draw-things-cli 在本地生成 AI 图像和媒体。使用当前 Draw Things 命令接口：generate、models list、models ensure、models import 和 train lora。

范围： 本地 Draw Things 图像生成、图像编辑、模型设置、模型清单、导入和短时本地媒体生成。不适用于 UI 实现（设计）、广告创意策略（ad-creative）、云端图像 API 或常规 AI 模型市场调研。

---

规范词汇

术语	含义	不代表
txt2img	文本生成图像：输入提示词，输出图像文件	img2img
img2img	图像生成图像：输入图像和提示词	txt2img
media	使用 --frames 生成视频或音视频，并输出视频	UI 动画
model id	Draw Things 模型文件名或 --model 接受的模型引用	猜测的显示名称
recommended pack	当前针对设备配置批准的模型集	所有已安装的模型
legacy model	为兼容性保留的旧模型，默认不推荐	删除目标
cfg	当前 CLI 指导参数：--cfg	旧版 --guidance-scale
strength	Img2img 的修改幅度：数值越低越能保留原图，数值越高重绘越多	输出比例
seed	用于复现相同提示词和设置的值	模型选择
config file	使用 --config-file 传入、用于设置应用高级选项的 JSON 文件	直接 CLI 参数

---

分派

$ARGUMENTS	模式	操作
generate <prompt> / create <prompt>	生成	使用当前最佳图像默认设置进行 txt2img
自然语言图像描述	自动：生成	判断提示词意图并选择模型
edit <path> <prompt> / transform <path>	编辑	使用 --image 和 --strength 进行 img2img
图像路径 + 修改意图	自动：编辑	保留原图，写入新的输出文件
video <prompt> / media <prompt> / animate <prompt>	媒体	使用 --frames 生成短时本地媒体
setup / download models / best models	设置	检查设备配置并确保安装推荐模型集
inventory / models / model status	清单	运行模型清单辅助工具并汇总缺失项
import <path-or-url>	导入	使用 draw-things-cli models import
model <name>	模型信息	显示当前用途、设置和状态
batch <prompt> / variations <prompt>	批量生成	使用包含多个种子和输出的 shell 循环
refine / iterate	优化	锁定种子并更改一个参数后重新运行
upscale <path> / controlnet ... / lora ...	高级	运行前确认 config-file 工作流
(空)	帮助	确认 CLI，展示模式和示例

自动检测启发规则

1. 提示词要求安装、下载、配置或选择最佳模型 → 设置。
2. 提示词要求查看模型列表、当前下载内容或缺少的模型 → 库存。
3. 提示词提及视频、动态、mp4、mov、帧或动画 → 媒体。
4. 提供现有文件路径，并要求编辑、重设风格、更改或转换 → 编辑。
5. 提供现有文件路径，并要求放大、控制、lora 或修复 → 高级，然后在运行前确认当前 CLI/配置是否支持。
6. 提供描述性文本，但没有文件路径 → 生成。
7. 意图不明确 → 询问要使用哪种模式，并说明取舍。

---

前置条件流程

在任何生成或模型变更前运行：

1. 检查 CLI：command -v draw-things-cli。
2. 如果缺少，显示安装命令并停止：

   brew install drawthingsai/draw-things/draw-things-cli
   

3. 验证已安装命令的功能：draw-things-cli generate --help。
4. 对于设置/库存，优先使用：

   uv run python skills/draw-thing/scripts/model_inventory.py --format json
   

5. 始终传入 --output；如果不传，当前 CLI 在受支持的终端中可能只会预览，而不会写入文件。

---

当前最佳模型策略

截至 2026-05-15，这台 Mac 配备 Apple M1 Pro、arm64、macOS 26.5 和 32 GiB 统一内存。使用当前针对 Draw Things 优化的检查点；除非用户明确要求兼容性，否则不要推荐旧版 SDXL/SD1.5/FLUX.1 系列。

用途	模型 id	状态	默认用途
快速图像默认模型	z_image_turbo_1.0_q8p.ckpt	推荐	快速草稿，8 步，--cfg 0
最佳文本/布局/真实感	qwen_image_2512_q8p.ckpt	推荐	海报、排版、精美图像
创意基础模型	z_image_1.0_q8p.ckpt	推荐	通用创意探索
高端 FLUX/参考/编辑	flux_2_dev_q6p.ckpt	推荐	32 GiB 上的 FLUX.2 工作流
指令式图像编辑	qwen_image_edit_2511_q8p.ckpt	推荐	Img2img/编辑提示词
艺术/提示词遵循替代模型	hidream_i1_full_q5p.ckpt	推荐下载	最高质量的艺术创作替代模型
快速本地媒体	ltx_2.3_22b_distilled_q6p.ckpt	推荐下载	短文本/视频生成
适配设备的 Wan 媒体	wan_v2.2_5b_ti2v_q8p.ckpt	推荐下载	32 GiB 上当前的 Wan 视频生成

未经批准，不得将已下载的旧版/冗余模型列为删除目标：flux_1_schnell_q8p.ckpt、flux_1_fill_dev_q8p.ckpt 和 flux_2_klein_4b_q6p.ckpt。

辅助文本/VLM 文件和未完成的部分文件不是推荐的生成模型。例如，llama_3.1_8b_instruct_q8p.ckpt.part 是一个不完整的陈旧辅助文件，并非 2026 年 5 月中旬最佳模型包中的模型。

Qwen Layered 仍是当前可选工作流的目标，但不能保证在这台设备上安装为最佳模型包：qwen_image_layered_1.0_bf16_q6p.ckpt 校验失败，原因是校验和不匹配；qwen_image_layered_1.0_bf16_q8p.ckpt 则在 CLI 下载期间反复停滞。除非用户明确要求继续重试 Layered，否则应使用 qwen_image_edit_2511_q8p.ckpt 进行可靠的本地编辑。

如需查看确切的安装命令、当前与旧版的区别以及量化规则，请加载 references/model-catalog.md。

---

核心生成协议

每种模式都遵循以下流程：

1. 验证：CLI 存在，输入文件存在，模型已下载，或有意使用 --download-missing。
2. 选择默认值：除非用户提供了 --model，否则按角色选择当前模型。
3. 构建命令：仅使用 draw-things-cli generate --help 中显示的标志，或使用 --config-file 设置高级应用选项。
4. 显示命令：运行前显示完整命令。
5. 执行：通过 Bash 运行并捕获输出。
6. 报告：输出路径、种子、模型 ID、尺寸、步数和 cfg。

模式：生成

快速草稿默认值：

draw-things-cli generate \
  --model z_image_turbo_1.0_q8p.ckpt \
  --prompt "<prompt>" \
  --steps 8 \
  --cfg 0 \
  --width 1024 \
  --height 1024 \
  --seed <seed> \
  --output <output.png>

质量／文本默认值：

draw-things-cli generate \
  --model qwen_image_2512_q8p.ckpt \
  --prompt "<prompt>" \
  --steps 40 \
  --cfg 4 \
  --width 1328 \
  --height 1328 \
  --seed <seed> \
  --output <output.png>

模式：编辑

draw-things-cli generate \
  --model qwen_image_edit_2511_q8p.ckpt \
  --image <input.png> \
  --prompt "<edit instruction>" \
  --strength 0.55 \
  --steps 30 \
  --cfg 4 \
  --seed <seed> \
  --output <output.png>

细微编辑使用 --strength 0.25-0.4，明显编辑使用 0.5-0.65，大幅重绘使用 0.75+。

模式：媒体

draw-things-cli generate \
  --model ltx_2.3_22b_distilled_q6p.ckpt \
  --prompt "<motion prompt>" \
  --frames 49 \
  --width 768 \
  --height 512 \
  --seed <seed> \
  --output <output.mov>

此设备优先使用 LTX distilled。宽度／高度须能被 32 整除，帧数须为 8 的倍数加 1。

模式：设置

先运行清单检查：

uv run python skills/draw-thing/scripts/model_inventory.py --recommended-pack all --format json

然后，向用户展示缺失的 ensure_command 条目，再运行这些命令。除非用户另行批准清理操作，否则不要删除旧版模型。

模式：清单

uv run python skills/draw-thing/scripts/model_inventory.py --format json

汇总已安装模型、缺失的推荐模型和冗余的旧版下载。 分别报告 incomplete_downloads 和 auxiliary_or_dependency_files，以免将辅助文件或过期的 .part 文件误认为当前最佳模型。

模式：批量

当前 CLI 不提供 --batch-count。请使用 shell 循环和明确的输出名称：

for seed in 1201 1202 1203 1204; do
  draw-things-cli generate \
    --model z_image_turbo_1.0_q8p.ckpt \
    --prompt "<prompt>" \
    --steps 8 \
    --cfg 0 \
    --width 1024 \
    --height 1024 \
    --seed "$seed" \
    --output "$HOME/Pictures/draw-thing/run-$seed.png"
done

模式：高级

当前的 generate --help 不提供旧版直接标志，例如 --controls、--loras、--mask、--upscaler、--batch-count、--sampler 或 --guidance-scale。对于 ControlNet、LoRA、局部重绘、放大、平铺及其他应用级设置：

1. 重新检查 draw-things-cli generate --help。
2. 仅在确认架构后使用 Draw Things 应用管理的设置或 --config-json / --config-file。
3. 切勿根据旧示例臆造直接标志。

---

提示词速查表

模型系列	风格	负面提示词
Z Image Turbo/Base	直接使用自然语言指令；简洁描述构图细节	支持使用；有用时再用，并保持简短
Qwen Image 2512	明确描述布局、排版、准确文本和编辑风格语言	支持使用；保持针对性
Qwen Edit/Layered	使用祈使式编辑指令和保留约束	仅用于说明应避免更改的内容
FLUX.2	使用自然语言描述参考／编辑细节和精确的场景意图	按模型确认；不要假设适用 FLUX.1 规则
HiDream I1 Full	丰富地描述艺术指导、风格、媒介、光照和构图	如需使用，请提供简短且有针对性的负面提示词
LTX/Wan media	描述随时间变化的运动、摄像机移动和时间连贯性	避免只适用于静态图像的标签列表

如需模板和故障排除指南，请加载 references/prompt-patterns.md。

扩展策略

请求规模	策略
单张图像	使用 z_image_turbo_1.0_q8p.ckpt，除非质量或文本需求需要 Qwen 2512
文本／布局至关重要	使用 qwen_image_2512_q8p.ckpt，并提供明确的文本／布局提示词
编辑现有图像	先使用较保守的强度，搭配 qwen_image_edit_2511_q8p.ckpt
图层／可编辑性工作流	仅当已安装 Qwen Layered 时使用；否则说明之前安装失败的情况，并在重试前征求同意
高质量艺术效果	尝试 hidream_i1_full_q5p.ckpt；如果出现内存压力，则改用其他模型
短视频	优先使用 LTX distilled q6p；尺寸保持适中
多种变化方案	使用 shell 循环、固定输出路径和适量的种子批次

---

输出处理

• 技能默认输出目录：~/Pictures/draw-thing/。
• 生成前创建该目录：mkdir -p "$HOME/Pictures/draw-thing"。
• 始终传入 --output <file>；不要依赖隐式输出行为。
• 切勿覆盖源图像；请使用描述性的新文件名。
• 始终报告输出文件、种子、模型、步数、cfg、尺寸，以及此次运行是否下载了模型。

---

错误恢复

错误	可能原因	操作
unknown flag	旧版说明或 CLI 不匹配	运行 draw-things-cli generate --help；移除过时的直接标记
找不到模型	id 错误或尚未下载	运行 draw-things-cli models list；使用 models ensure --model <id>
没有输出文件	缺少 --output 或终端处于仅预览模式	使用明确的文件路径重新运行
进程被终止／OOM	模型过大或尺寸过高	降低尺寸，使用 q6p/q5p，或切换到更快的模型
文本效果差	用于排版的模型／提示词不合适	使用 Qwen Image 2512，并提供准确的引号内文本
视频生成失败	模型缺失或内存压力	确保有 LTX q6p，降低尺寸／帧数

---

参考文件

每次只加载一个参考文件。

文件	内容	加载时机
references/cli-reference.md	当前命令接口、标记、models 子命令及配置注意事项	构建较复杂的命令
references/model-catalog.md	截至 2026-05-15 当前最佳模型包、准确的 ensure 命令及旧版说明	选择／下载模型
references/prompt-patterns.md	Qwen、Z Image、FLUX.2、HiDream、LTX/Wan 的提示词模式	复杂提示词或质量问题
references/controlnet-guide.md	高级控制／导入／配置指南，以及过时标记警告	ControlNet、LoRA、局部重绘、放大
references/workflow-recipes.md	使用已公开标记和 shell 循环的当前配方	多步骤创意工作流

---

验证约定

在声明更改完成之前，从此技能目录运行：

python scripts/check.py
python scripts/model_inventory.py --format json

完成标准：

1. scripts/check.py 以状态码 0 退出。
2. 模型清单注明是否属于推荐套装。
3. 命令示例中不包含当前 generate --help 不支持的过时直接标志。
4. 此技能目录下不存在违反便携式 CLI 规范的内容。

---

关键规则

1. 在生成内容或更改模型之前，始终检查 command -v draw-things-cli。
2. 始终以 draw-things-cli generate --help 作为直接标志的权威来源。
3. 始终传入 --output；仅生成预览输出不足以满足 Agent 工作流的要求。
4. 使用 --cfg，不要使用过时的 --guidance-scale。
5. 除非当前帮助信息或配置架构证明支持，否则不要使用过时的直接标志：--sampler、--batch-count、--upscaler、--mask、--controls 或 --loras。
6. 优先使用推荐的 2026 配置套装，而不是旧版 SDXL、SD1.5、SD2.x、SVD、FLUX.1、Qwen 1.0、Qwen Edit 2509、Wan 2.1 或旧版社区检查点。
7. 未获得用户单独明确批准，绝不删除或清理模型。
8. 运行命令前，先展示完整命令。
9. 保留源图像；将新文件写入输出路径。
10. 报告 seed、模型 ID、输出路径、尺寸、步数和 cfg。
11. 对于视频，保持适中的尺寸，并确保帧数除以 8 后余 1。
12. 对于高级 ControlNet/LoRA/修复/放大工作流，执行前验证 --config-json 或 --config-file 的架构。
13. 不要将辅助文本/VLM 文件、附属文件或未完成的 .part 下载视为推荐的生成/媒体模型。