# 两步链实施批：generation_config two_step 档 + P07 消费接线 — 架构司机批次

## 背景事实（operator 已实证，直接采用勿重新推导）

1. **设计已定稿**：`skills/kais-movie-pipeline/docs/two-step-image-chain-design.md`（§2.3 是本批蓝图）。
   编排器/双 adapter/探针/26 单测已合入主线（35f6846d + 416f58aa）。
2. **拓扑已复核定谳**（2026-09-10，commit 416f58aa）：ideogram.py = 真值拓扑
   （DualModelGuider/CLIPTextEncode/Ideogram4Scheduler/qwen3vl_8b TE），TOPOLOGY_STATUS=verified-2026-09-09。
3. **真机冒烟已通过**（2026-09-10 龙轩咖啡试金石）：臂A Ideogram t2i OCR「龙轩咖啡」conf 0.984 →
   臂B Z i2i d0.75 人物注入 OCR 0.998，全链 degraded=null，manifest 全字段。链真机可用。
4. **既有锚点**（p04 先例，P07 照抄镜像）：
   - `runner._DEFAULT_GENERATION_CONFIG`（runner.py ~L2471）：资产类型级 engine 键，值域 dreamina|zimage。
   - `p04._resolve_image_engine(episode_config, asset_type)`（p04 ~L563）：扁平 > 子资产 > 缺省 dreamina。
   - p04 消费形态（~L990）：`if _resolve_image_engine(...) == "zimage": return _run_costume_swap_zimage(...)`。
5. **两步链编排器接口**（pipeline/engine_adapters/two_step.py）：
   `two_step_generate(design_prompt, refine_prompt, *, width, height, seed, denoise=0.75,
   init_image=None, negative_prompt="", output_dir, filename_prefix, design_engine=None,
   refine_engine=None, final_fallback=None) -> TwoStepResult`（.path/.degraded/.arms/.manifest_path/.chain）。
   降级链 two_step→zimage→dreamina 由 `resolve_fallback_chain` 单点定义；`TwoStepChainError.chain` 可供 phase 判定。
6. **P07 现状**：scene_image 走 dreamina_manager 批量通道；p07 文件 ~1300 行，消费锚在图像生成区
   （grep `dreamina_manager` / `_gen_scene` 找）。`p07_scene.scene_image.text_guard` 挂点已有（textguard-m2 先例）。

## 任务（本批范围 = 设计文档 §2.3 的实现，默认值零变化）

### C1. runner._DEFAULT_GENERATION_CONFIG 增 p07_scene 注释性锚（不改行为）
   在 p07_scene 相关键处（若现无该 phase 键则新增仅注释示例，**不新增 two_step 默认档**）写清：
   `engine` 值域扩展说明（"dreamina"|"zimage"|"two_step"）、two_step 子键样例
   （denoise/design_engine/双 base_url）、**禁止翻默认**的治理注释（textguard-m2/vdn-8 先例引用）。
   若 runner 里 p07_scene 无既有键 → 在 p07 消费侧 resolver 的 docstring 里承载同样的说明即可（二选一，说清理由）。

### C2. p07 新增 `_resolve_image_engine` 镜像函数 + `_resolve_two_step_cfg`
   - `_resolve_image_engine(episode_config, asset_type)`：语义镜像 p04（扁平 > 子资产 > 缺省 "dreamina"）。
   - `_resolve_two_step_cfg(episode_config, asset_type) -> dict`：读 `two_step` 子键
     {denoise, design_engine, ideogram_base_url, z_base_url}，各键带缺省（0.75/"ideogram"/:8188/:8188），
     垃圾值回落缺省（denoise 越界(0,1] 回落 0.75；非数值回落）。

### C3. p07 scene_image 消费分支（engine=="two_step" 时走编排器）
   - 位置：scene_image 生成路径入口（与 p04 L990 形态一致：`if engine == "two_step": return _run_scene_two_step(...)`）。
   - `_run_scene_two_step()`：逐场景串行调 `two_step_generate`（批内过滤粒度：仅对含文字载体
     （scene 有 text_spec/招牌需求）或人物首帧需求的场景开链，纯氛围场景仍走 dreamina 单臂——§1.2 判据）。
     design_prompt/refine_prompt 从场景语义拼（design=场景+招牌设计描述；refine=完整终稿含人物）。
   - **产物落盘与既有 scene_image 消费面完全对齐**（同 output 目录/命名，下游 P08 选择/画布同步零感知）；
     manifest 写到场景资产旁；TwoStepChainError 捕获 → 记 warning + 该场景走 dreamina 兜底（WARN-AND-SKIP，
     不炸 phase，对齐 p07 既有引擎失败语义）。
   - **GPU 纪律**：编排器内部两臂同卡串行（:8188），臂间无需 /free（探针实测双臂 21G 峰值间歇即可，
     若遇到 EngineBusy 由编排器降级链自然接管，不加跨臂 sleep hack）。

### C4. 测试（pytest，全 mock 零 GPU，参照 test_two_step_image_chain.py 的 fake 形状）
   - resolver 三层优先级/垃圾值回落。
   - two_step 分支触发条件（engine=="two_step" 才走；dreamina 缺省零行为变化断言）。
   - 批内过滤（无文字无人物的场景不开链）。
   - 链耗尽 WARN-AND-SKIP（mock TwoStepChainError → 场景标 engine_error，phase 不炸）。
   - 产物路径/manifest 字段对齐。

### C5. 交付文档 `docs/two-step-p07-integration.md`
   - 实探结论（p07 消费锚行号锚点）+ 改动锚点 + requirement.json 开启样例（显式 two_step 档）+
     验证命令 + 回滚（git revert 单 commit）。**无部署面**（管线 Python 侧随进程生效）。

## 验证命令（operator 验收独立复跑）
1. `cd <worktree>/skills/kais-movie-pipeline && python3 -m pytest tests/ -q --no-header -k "two_step or ideogram or p07" 2>&1 | tail -3` 全绿
2. `python3 -m py_compile pipeline/phases/p07_scene_generation.py pipeline/runner.py`
3. `git diff <baseline>..HEAD --stat`：范围 = p07_scene_generation.py / runner.py / 新测试 / 新 docs，**零越界**

## 基线与红线

- 仓：/data/workspace/kais-hermes-skills（当前 HEAD = 416f58aa，分支 feat/kmc-h3-blockcache）。
- worktree：`git worktree add -b wt/two-step-p07 /data/workspace/kais-hermes-skills-wt/two-step-p07 416f58aa`
  （发车前自行 `git log --oneline -1` 认环境，若 HEAD 已前进以内容为准）。
- 红线：①**禁止改 _DEFAULT_GENERATION_CONFIG 的任何默认值**（two_step 只进文档/注释/测试，不进默认档）；
  ②禁止改 p04/zimage.py/ideogram.py/two_step.py（已定稿件零改动）；③禁 push；提交只进你的 worktree 分支；
  ④禁 GPU 渲染任务（测试全 mock）；⑤单 commit 交付。