# KMC 双图像引擎功能规划 — Ideogram4（设计供体）× Z-Image（i2i 加工）两步链

> 架构设计批（arch 司机）。背景事实全部为 operator 0908-0909 实测定谳，**直接采用勿重新推导**。发现与事实冲突时：以实测为准，在交付文档逐条列出并合法自纠偏。

## 任务性质

**架构设计类，非修码批**。产出 = 设计文档（docs/*.md）+ 最小探针验证代码（不接线）。**禁止把两步链直接接进 phases 生产代码**——接线属后续实施批，归 flash/GLM 司机，本批只做设计+探针。

## 背景事实（全部实测，直接采用）

### 1. 两步链能力定谳（2026-09-09 会话，产物在 /home/kai/shared/2026-09-09/）

- **链路定义**：臂A（Ideogram4）纯 t2i 出「精华底图」（文字渲染/构图/质感是它的最强形态）→ 臂B（Z-Image Turbo）i2i 高 denoise 做「内容替换/人物注入」，继承臂A 的风格与构图。
- **工作点**：Z i2i **d0.75 = 甜点**。corr(i2i, init)=0.481（风格穿透显著，无关基线 0.212）；d0.85 时 corr 降到 0.322（先验洗掉供体）；d≤0.6 内容换不动（昨日人物入景探针已证）。**现有 engine_adapters/zimage.py 的 `_DEFAULT_DENOISE_I2I = 0.65` 是「保场景改细节」档，与本链的「换内容保风格」档（0.75）是两个不同工作点**——设计时必须把 denoise 提升为 per-call 可配参数。
- **风格穿透实证**：Ideogram S1 供体（暖琥珀+胶片颗粒）→ Z i2i 换成唐人街夜市，输出明显继承供体色温/颗粒/饱和度，纯 t2i 对照臂为冷蓝糖果色。判定页 `/home/kai/shared/2026-09-09/ideogram_blind4/style_transfer_showcase.html`。
- **跨域验证（kais-validation 素材矩阵，产物 /home/kai/shared/2026-09-09/validation_2step/）**：3 case × [素材 init + 人物 prompt d0.75] vs [纯 t2i 对照]，真实系室外（corr 0.803）/ 真实系室内（0.559）/ 动漫竖屏（0.648），人物注入 3/3 成功（古装双人 / 拥抱双人 / 老农+羊+猪）。**弱点**：家具级细节在 d0.75 会被 Z 先验重写（书桌→沙发、羊圈围栏重组）。判定页 `validation_2step_showcase.html`。
- **招牌/中文文字**：Z i2i d0.35-0.75 全档保住「龙轩咖啡」招牌（OCR 1.00/0.98/1.00）；Ideogram4 中文招牌能力实锤（4 字招牌笔画全对）。两步链天然适合「带招牌/店招的场景设计」。

### 2. 引擎能力边界（定谳，勿推翻）

| 引擎 | 强项 | 禁区 |
|---|---|---|
| Ideogram4 int8_convrot + Realism V5 LoRA@0.8 | 中文/英文文字渲染、构图设计感、写实质感；t2i 唯一强项位 | **本地无真·多图参考**（三轮生态查重钉死：无 reference_latents 通道、无 adapter 权重）；i2i 仅单图 d≥0.6 且 d0.3-0.5 有油画笔触区；裸模 87% 安全叠字（LoRA@0.8 压制，18/18 OCR 干净）；20步/cfg7/28-32s 慢 |
| Z-Image Turbo bf16 | i2i 高 denoise 内容替换+构图锚定（本链核心能力）；中文渲染（盲测 R1 第一）；9步/cfg1/10-25s 快；实验台 :8190 与生产 :8188 双实例可用 | 多图参考需等 diffusers ZImageOmniPipeline 成熟（ComfyUI 未封装）；t2i 默认先验偏「冷蓝糖果色」，当设计供体不如 Ideogram |

### 3. KMC 管线既有接线锚点（真源 = kais-hermes-skills 仓 pipeline/）

- **engine 配置单点**：`runner.py` `_DEFAULT_GENERATION_CONFIG`（~L2484）资产类型级 `engine` 键，值域 `"dreamina"`（缺省）| `"zimage"`；解析优先级 扁平>子资产；消费方 `p04._resolve_image_engine`。**目前只有 P04 消费 engine 键**。
- **engine_adapters/**：现有 `zimage.py`（t2i+i2i，含 GPU 显存守卫/EngineBusy 语义/测试 seam）。**无 ideogram adapter**——Ideogram4 目前只有裸 ComfyUI 工作流 JSON（`/tmp/ideo_realism_graph.json` history 回捞件）+ skill 记录（~/.hermes/skills/ideogram4-local-workflow/SKILL.md，含完整拓扑与参数）。
- **图像消费 phase 全景**：P04（角色 bible/turnaround/costume_swap）、P07（scene_image/multiview）、P09c（storyboard sheet）。P07 现走 dreamina_manager 批量通道。
- **治理先例**：textguard-m2「配置默认关、detect 先行、A/B 后翻默认」；vdn-8「只加档不切默认」。新臂接入必须沿用此治理形态。

## 设计任务

### D1. 两步链在 KMC 的功能定位矩阵（设计核心）

产出「场景类型 → 推荐链路」决策表，至少覆盖：

| 场景类型 | 推荐链路 | 理由锚点 |
|---|---|---|
| 带中文招牌/文字的店铺场景（龙轩咖啡类） | Ideogram t2i 设计 → Z i2i 注入人物 | 两引擎文字+招牌能力叠加，OCR 预筛 |
| 带人物的场景首帧/关键帧（P11 iframe 前置） | 素材/设计图 → Z i2i d0.75 人物注入 | validation 矩阵 3/3 实证 |
| 无文字纯氛围场景 | 单臂 Z t2i 直出（跳过两步链） | 两步链成本不必要 |
| 角色 turnaround / bible | **不进本链**（维持 P04 现状） | turnaround 是白底多视图，非本链适用域 |
| 服化道换装 | 维持现有 engine 键机制（zimage 已接） | 已有实现，零改动 |

矩阵须给出「何时值得多花 ~30s 走两步链」的成本判据（臂A 28-32s + 臂B 10-25s vs 单臂 Z 10-20s）。

### D2. 架构设计

1. **Ideogram4Engine adapter**（engine_adapters/ideogram.py）：镜像 zimage.py 的类结构（EngineBusy/EngineUnavailable/ExecutionError 三异常、GPU 守卫、测试 seam、/prompt→/history→/view 生命周期）。拓扑参数从 skill 记录取（20步/cfg7/双模型CFG/ModelSamplingAuraFlow shift5/RL V5 LoRA@0.8/int8_convrot 底模）。设计文档给类接口签名与 workflow 构建伪码即可，**不要求真机联调**。
2. **两步链编排器**（建议 pipeline/engine_adapters/two_step.py 或作为 phase 侧 helper，司机按既有代码风格定）：接口形如 `two_step_generate(design_prompt, refine_prompt, init_image=None, denoise=0.75, ...)`；臂A 失败降级单臂 Z t2i；**denoise 必须可配**（默认 0.75，与 zimage.py 的 0.65 缺省区分语义并注释）。产物 manifest 记录两臂引擎/prompt/seed/denoise/耗时（对齐 prompt_ledger 溯源纪律）。
3. **generation_config 扩展设计**（只写设计不实现）：`engine: "two_step"` 新档位语义 + 资产类型级配置样例（如 `{p07_scene: {scene_image: {engine: "two_step", two_step: {denoise: 0.75, design_engine: "ideogram"}}}}`）；降级链 two_step→zimage→dreamina；声明**默认值不动**（dreamina），A/B 验证后再翻（textguard/vdn-8 治理先例）。
4. **适用 phase 建议**：P07 scene_image 为主战场；P09c storyboard sheet 为候补；P11 iframe 链路（条件帧生产）作为远期位——只写建议与理由，不做实现设计。

### D3. 最小探针（验证设计假设，非生产代码）

- scripts/ 下交付 `two_step_probe.py`：两步链单次调用 demo（Ideogram t2i → Z i2i d0.75），ComfyUI API 直调形态参照 /home/kai/shared/2026-09-09/validation_2step/val2step_probe.py 的 post/get 轮询骨架。
- **红线**：探针不做真机渲染（GPU 渲染归 operator 冒烟）；用 mock seam（zimage.py 的 _http/_run 模式）写单测证明编排逻辑/降级链正确。
- Ideogram4 workflow 构建逻辑照 skill 记录的拓扑写，节点名以 /tmp/ideo_realism_graph.json 为真值参照（该文件若已失，按 skill 的拓扑描述构建并注明「待 object_info 复核」）。

## 交付物

1. `docs/two-step-image-chain-design.md` — D1 矩阵 + D2 架构 + D4 风险与 open questions（单测覆盖面、d0.65/0.75 双工作点共存语义、manifest 溯源字段清单、后续实施批的验收锚点建议）
2. `pipeline/engine_adapters/ideogram.py` — adapter 骨架（含单测，mock seam）
3. `pipeline/engine_adapters/two_step.py`（或 phase 侧 helper，司机定夺并说明理由）— 编排器 + 降级链 + 单测
4. `scripts/two_step_probe.py` — 探针 demo（mock 形态可跑，真机冒烟命令写注释留给 operator）
5. 全部单测 mock 形态可跑（无 GPU 依赖，同 zimage.py 测试 seam 先例）

## 红线

1. **禁改 phases/ 生产接线**——runner.py / p04 / p07 / p09c 一律零改动；generation_config 扩展只写设计文档
2. 禁 GPU 渲染任务（真机冒烟归 operator）
3. 提交只进你的 worktree 分支；禁 push
4. kais-hermes-skills 为多会话共享仓：发车前 `git log --oneline -3` 认环境，基线以工单所写为准，若 HEAD 已前进以「与设计相关的锚点文件内容」为准

## 基线与 worktree

- 真源仓：/data/workspace/kais-hermes-skills（pipeline/ 在 skills/kais-movie-pipeline/pipeline/）
- 基线：当前活跃分支 HEAD（先 git log 认环境）
- worktree：`git worktree add -b wt/two-step-image-chain /data/workspace/kais-hermes-skills-wt/two-step <基线>`
- 验证命令（发车前已实测布局：测试在 `<worktree>/skills/kais-movie-pipeline/tests/`）：
  - `cd <worktree>/skills/kais-movie-pipeline && python3 -m pytest tests/ -q -k "ideogram or two_step"`
  - `python3 -m py_compile pipeline/engine_adapters/ideogram.py pipeline/engine_adapters/two_step.py scripts/two_step_probe.py`（pipeline/ 相对 skills/kais-movie-pipeline/）

## 验收锚点（operator 验收用，司机交付文档须逐条回应）

1. D1 矩阵覆盖 5 类场景且每行有实测数据锚点引用
2. denoise 0.65 vs 0.75 双工作点语义在代码与文档中都有显式区分
3. 降级链 two_step→zimage→dreamina 有单测证明
4. 红线第 1 条零越界（git diff 审）
5. 全部单测在本机 mock 形态跑绿（operator 独立复跑，不采信自报）