2026-10-25 · 项目地址 · https://github.com/wyfirstname/qwenimage-comic
本功能后续会以系列形式更新和发布，期待和大家一起交流
独立开发AI 绘图游戏美术工程化
先说结论： 你现在只需要输入一句话，比如「云巅剑域------东方仙气藏于云海，修者御剑御空芒，灵兽伴行标状」------系统会自动策划出角色、宠物、分级武器、建筑、野怪的完整设定，然后把场景（春夏秋冬 ×4 季变体）、角色、宠物、武器（普通/史诗分等级）、建筑、野怪共 16~35 张风格统一的素材图，分类独立生成、独立重试、全程状态透明地跑完。
这篇文章记录这个「游戏素材工坊」从 v1 到 v4 的完整迭代过程，以及切到真实模型（Qwen-Image 2.1）后踩过的三个深坑。
一、整体架构：站在四层架构上的一个 App
项目底层是「团子衣橱」的四层架构：shared/（配置与存储）→ engine/（引擎封装，mock/comfy 双模式）→ apps/（各业务应用）→ portal/（门户，靠 manifest.json 自动发现新应用）。游戏素材工坊就是 apps/gameassets，独立端口 8107，写完往 manifest.json 一挂，门户自动收录。
最核心的难题只有一个：一致性。一整套素材要像一个美术团队画的，而不是 16 个陌生人的作品集。我们用了三层机制：
| 层级 | 机制 | 做法 |
|---|---|---|
| 提示词层 | 风格基因 + 时间背景 | 6 种美术风格（吉卜力水彩/像素复古/赛博霓虹...）× 6 种时间背景（清晨/黄昏/夜晚...），所有提示词拼接同一段风格描述 |
| 图像层 | 基准图融合锚定 | 先出一张场景基准图（master），后续所有素材都以它为参考图做 image-to-image 融合（CFG=1），风格和色调从源头锚死 |
| 后验层 | 色调评分 | 每张图出完后用 Pillow 提取 6 色板，与基准图算平均色距，超阈值标「✗ 色调偏离」，一眼看出跑色的素材 |
二、从「逐个添加」到「一句话流水线」：四轮迭代
这个应用不是一次设计出来的，而是被真实使用反馈逼着长出来的：
v1：逐个添加模式
最初只是「选场景 → 加角色 → 加道具」的手动模式，顺带实现了上面那套三层一致性。用户试完只说了一句：「要的是一键流水线，不是逐个添加。」
v2：一键流水线
加了后台流水线：基准图 → 场景 → 角色 → 道具，串行排队保显存（6GB 的 2060 跑不起并发），逐步写库，单步失败不断链。
v3：自动策划
用户的第二次反馈：*「要系统自己完善设定。」*于是加了 LLM 策划器------用户只给一句话，系统自动产出角色/宠物/武器（分普通、精良、史诗、传说四级）/建筑/野怪的完整设定；LLM 不可用时规则兜底。场景自动扩展春夏秋冬四季变体。
v4：分类独立 + 异常透明
第三次反馈最扎心：*「程序要把各类分开生成，也要加入异常回复功能。目前系统卡住或内部异常，页面依然进行中，误导空等。」*这轮重构是工程上最重要的一步：
- 流水线拆成 8 个独立阶段（策划/基准图/场景/角色/宠物/武器/建筑/野怪），各自状态机、各自条目表、互不拖累；
- 单 worker FIFO 串行队列保显存，「全部生成」是编排不是硬循环；
recover_interrupted()启动时清理服务被杀留下的假 running 状态；- 前端断线检测（轮询失败 ≥3 次红横幅）+ alive 对账（页面显示执行中但服务端无任务 → 提示已中断，点生成续做）；
- 所有异常落库：阶段 error 字段 + 200 条滚动操作日志。
v4 主界面：8 张阶段卡（全绿 = 完成）、操作日志实时滚动、LLM 策划方案直接可审
注意左下角「策划方案」面板------这就是那句「云巅剑域」被系统自动完善的设定：仙山浮于云海、角色 2、宠物 1、武器 2、建筑 1、野怪 2。上面每张卡都能单独「重新生成」，一类失败不影响其他类。
三、真实出图：切到 Qwen-Image 2.1 后的三个深坑
开发全程在 6GB 显存的 2060 上用 mock 模式验证逻辑，出真图时切 ComfyUI + Qwen-Image 2.1（Q3_K_S 量化版，2.54GB）。然后连续踩了三个坑，每一个都不是一眼能看出来的：
坑一：txt2img 出图必黑
基准图出来几乎全黑。原因是代码里无参考图的 txt2img 分支还在走 1.0 时代的老路径------CLIPTextEncode + cfg=4.0。而 2.1 是 CFG=1 的蒸馏模型 ，喂 4.0 的引导系数等于把采样推进崩溃。素材生成走的参考图融合路径本来就是 CFG=1 所以没事，唯独基准图中招。修复：改走 2.1 官方的 TextEncodeQwenImage21 节点 + CFG=1。
坑二：夜晚预设是「崩溃咒语」
修完坑一还是黑。这次做了 14 组对照实验（控制变量：步数/尺寸/负面词/提示词分段），最后二分定位到夜晚预设里的一组措辞：
text
deep blue moonlight, cool desaturated shadows,
strong chiaroscuro, ... vast cold darkness这组「强明暗对比 + 广袤冷暗」的美术术语把 8 步蒸馏模型直接推进了采样崩溃，整图烧成近纯黑（亮度 RGB 0,5,44）。换成温和夜色措辞后同 seed 立刻正常。教训：给蒸馏模型写提示词，极端的对比类描述是高危词。
坑三：中文括号被画成图上的乱码文字
黑图修完，新问题来了：画面上出现整排乱码文字。原因很有意思------Qwen-Image 2.1 的卖点之一是文字渲染能力强，而我们的提示词里有「起点村庄（蒸汽朋克世界风格）」这种中文括号注记，模型把括号里的内容当成了「要画到图上的文字」，认认真真地渲染了出去。修复：提示词组装时统一剥掉括号注记，风格描述全部走英文。
这三个坑全部是用「同 seed 对照实验」在 ComfyUI 上二分定位的------别猜，跑实验。
四、最终效果
「云巅剑域」项目，一句话输入，lite 档 17 步：基准图 1 张 + 场景 2 个 × 4 季 + 角色 2 + 宠物 1 + 武器 2（普通/史诗）+ 建筑 1 + 野怪 2，共 16 张全部完成。
场景 × 四季：同一场景在春夏秋冬下的变体，每张卡片下方带色调一致性徽章（✓ 一致 / ✗ 偏离 + 色距分数）
角色（寒星剑子 / 赤焰道人）与宠物（玄影豹）------全部锚定同一张基准图的色调与画风
武器分等级（霜魄剑·普通 / 朱霄刃·史诗，描述里带材质与光效分级）、建筑（剑心阁）、野怪（蚀魂蛛 / 雷鳞蛟）
五、工程上值得复用的几个模式
- store.mutate 原子写 ：所有状态变更走
store.mutate(sid, lambda t: ...)统一出口，JSON 原子落盘，读盘归一化绝不碰运行态（否则并发轮询会把真任务翻成 failed）。 - 串行队列保显存：单 worker FIFO，显存小的消费级显卡也能稳定跑长任务。
- manifest 自动发现：新应用写个 manifest.json，门户零改动收录，独立端口可单独起。
- 异常透明 > 静默退化：宁可页面红横幅，不让用户对着「生成中」空等三小时。
- 中断恢复语义：「全部生成」必须是续做（跳过 done 阶段）而不是重跑，否则中断恢复的承诺就是谎言。
单张出图速度（2060 6GB + Q3_K_S 量化）：融合路径约 2~4 分钟/张，基准图首张含模型加载约 7~13 分钟。一套 lite 包 16 张，一小时内跑完。
结语
这个项目最有意思的地方不是「能出图」，而是把「AI 出图」当成一个工程问题来解：一致性靠三层机制叠加，可靠性靠状态机 + 恢复语义 + 异常落库，模型行为靠对照实验定位。四轮迭代，每一轮都来自真实使用的反馈------好用的工具从来不是设计出来的，是磨出来的。