ComfyUI Z-Image-Turbo 配置排查：steps 参数从 8 到 10 的系统性修复

问题缘起

一切始于一次意外的发现。在一次 blog-pipeline 运行中，生图环节的图片质量明显低于预期——细节模糊、风格不稳定。排查发现，ComfyUI Z-Image-Turbo workflow 的 steps 参数被设置为 4，但设计规范明确要求为 10。

为什么是 4？这并非 bug，而是有明确原因的：kb-writer 在 Phase 4 生图环节，跳过了 blog-pipeline 的完整流程，没有委托 design-yuntianguang 执行生图，而是直接自行调用 ComfyUI 生图，并硬编码了 steps=4。

这个行为违反了流水线设计的两条核心规则：

1. 职责分离原则：kb-writer 只负责写稿和改稿，生图是 design-yuntianguang 的唯一职责
2. 参数统一原则：所有生图参数（包括 steps）必须通过标准链路传递，不允许硬编码

这次 steps=4 的偏差看似微小，却暴露了我们在多文件配置管理和 Agent 职责边界上的系统性漏洞。后续修复中，将 steps 统一为 10 只是最表层的工作，真正需要解决的是：如何防止 Agent 绕过流水线规则自行操作？

排查范围：从 workflow 到 AGENTS.md 的全面扫描

0. 事故根源：kb-writer 跳过流水线，自行生图

这次排查的第一步，不是看 workflow 文件，而是回溯事故的发生路径。

事故链条

在一次正常的 blog-pipeline 执行中，流程走到 Phase 4（生图）时，预期行为是：

kb-writer 改稿完成
    ↓
通知 design-yuntianguang 执行生图（标准参数：steps=10）
    ↓
design-yuntianguang 调用 ComfyUI 生成图片
    ↓
替换文章中的 [ILLUSTRATION] 标记

但实际发生的是：

kb-writer 改稿完成
    ↓
❌ kb-writer 没有通知 design-yuntianguang
    ↓
❌ kb-writer 自行调用 run_workflow.py 生图
    ↓
❌ 硬编码 steps=4，未使用标准 workflow 参数
    ↓
生成低质量图片，参数与设计规范不一致

为什么是 4 不是 10？

检查发现，kb-writer 在调用 run_workflow.py 时，传入了 --args '{"steps": 4}'。这个值没有来自任何标准配置，而是 kb-writer 自行决定的一个"快速生成"参数。

更严重的是，这个硬编码的 steps=4 写入了 z_image_turbo.json workflow 文件，导致后续所有通过该 workflow 生成的图片都使用了错误的步数。即使 design-yuntianguang 后来按规范使用 steps=10，但只要 workflow 文件中的默认值被覆写为 4，恢复时就需要额外的工作。

根本原因

这次事故的根源不是技术问题，而是流程执行问题。工具本身没有错，错的是执行流程的 agent 绕过了规则。

排查范围覆盖了所有与 Z-Image-Turbo 生图相关的文件：

• Workflow 定义文件：z_image_turbo.json（steps 参数的直接源头）
• Agent 配置：design-yuntianguang/AGENTS.md（默认参数声明）
• Python 调用脚本：run_workflow.py 等 4 个脚本（参数传递层）
• 编排配置：blog-post.yaml Phase 4（流水线编排层）
• Pipeline 技能文档：blog-pipeline/SKILL.md（流程规范层）
• 已知陷阱记录：kb-writer/AGENTS.md（经验教训层）

排查过程与发现

1. Workflow 文件：源头失守

z_image_turbo.json 是 steps 参数的最终定义者，所有脚本和配置最终都依赖这个文件中的参数。检查发现，workflow 中的 steps 节点值为 8。

{
  "class_type": "ZImageTurbo",
  "inputs": {
    "steps": 8,  // ← 应为 10
    "cfg": 1.0,
    "seed": -1,
    "width": 1200,
    "height": 800
  }
}

这是最核心的一处错误，所有下游的 steps=10 声明都无法覆盖这个源头设置。

2. Agent 配置：设计规范声明

design-yuntianguang/AGENTS.md 是视觉设计师云天光的配置文档，其中定义了默认参数。检查发现，这里虽然有 steps 声明，但并未明确强调 Z-Image-Turbo 必须使用 steps=10，也没有防止误配置的防护机制。

3. Python 脚本：参数传递层

4 个 Python 脚本（run_workflow.py、run_batch.py、generate_book_cover.py、post_process_image.py）负责从 workflow 文件中读取参数并执行 ComfyUI 调用。检查发现，以下具体问题：

• run_workflow.py：虽然通过 WORKFLOW_MAPPINGS 将 steps 参数映射到 workflow 节点 57:3，但脚本本身没有默认 steps 值兜底——当调用方不传 steps 时，workflow 文件中的原始值（8）被直接使用，没有任何校验或告警。
• generate_book_cover.py：硬编码了 new_steps = 10，但写入的是 KSampler 节点而非 Z-Image-Turbo 节点。这意味着封面图生成路径和文内插图路径使用了不同的节点类型，steps 值实际生效与否取决于调用路径，存在隐蔽的不一致性。
• run_batch.py：示例中展示了 steps: [20, 30] 的 sweep 模式，与 Z-Image-Turbo 预期的 steps=10 完全偏离，容易误导开发者以为 steps 可以随意设置。

根本原因：没有统一的 steps 参数校验层，每个脚本各自为政，缺乏交叉验证。

4. 编排配置：blog-post.yaml

blog-post.yaml 的 Phase 4 是 blog-pipeline 流水线中生图环节的编排定义。检查发现，原始配置中仅指定了"工具优先级：ComfyUI → agnes-image → step-image"，但完全没有提及 ComfyUI 的具体参数（steps、cfg 等），留给 design-yuntianguang agent 自行判断：

# 原始配置（缺失段）
- 工具优先级：ComfyUI → agnes-image → step-image
# 缺少：ComfyUI 参数：steps=10, cfg=1.0, workflow=z_image_turbo.json

修复后，显式补充了 ComfyUI 参数说明，确保任何 agent 无论是否熟悉 Z-Image-Turbo 都能正确执行：

- 工具优先级：ComfyUI → agnes-image → step-image
- **ComfyUI 参数**：steps=10, cfg=1.0, workflow=z_image_turbo.json
- 后处理脚本：/home/oklife/.hermes/skills/creative/comfyui/scripts/post_process_image.py

5. Pipeline 技能文档：blog-pipeline SKILL.md

SKILL.md 是流程规范，定义了 Phase 4 的执行要求。检查发现，这里完全缺少对 steps=10 的任何说明，导致新的 agent 或开发者创建生图请求时没有参考依据。

修复方案：系统性统一

修复不是简单的"改一个数字"，而是确保所有配置链路步调一致：

修改清单

在排查过程中，我们还顺带发现了两个更深层的配置隐患——ComfyUI 技能路径存在双位置（openclaw 标准路径和 hermes 扩展路径），kb-writer 和 design-yuntianguang 的职责边界也模糊不清。这两处隐患虽非 steps 直接问题，但同样是配置管理体系的薄弱环节，一并固化为了铁律。

新增铁律

在 design-yuntianguang/AGENTS.md 中新增了以下铁律：

⚠️ ComfyUI 技能路径检查铁律：生图前必须检查 两个路径：

1. ~/.openclaw/skills/comfyui/（openclaw 标准路径）
2. ~/.hermes/skills/creative/comfyui/（hermes 扩展路径） 漏检任一路径即事故。

在 kb-writer AGENTS.md 中新增了：

⚠️ 生图越界铁律：任何情况下，kb-writer 都绝不自行调用任何生图工具。生图是 design-yuntianguang 的唯一职责，违反即事故。

最终验证

修复完成后，对所有关联文件进行了配置一致性验证：

Workflow 文件 (z_image_turbo.json)    → steps=10 ✅
blog-post.yaml Phase 4                  → steps=10 ✅
kb-writer AGENTS.md Phase 4            → steps=10 ✅
design-yuntianguang AGENTS.md          → steps=10 ✅
blog-pipeline SKILL.md Phase 4         → steps=10 ✅
所有 Python 脚本                       → steps=10 ✅

6 个文件，10 余处修改，全部统一为 steps=10，零遗漏。

关键教训

1. 配置一致性需要系统性排查

不要只改"看起来最明显"的那个文件。一个参数从 workflow 文件到最终执行，中间经过多层传递，每一层都可能覆盖或偏离。修一个源头，检查所有中间层。

2. Agent 职责边界必须明确

这次排查还暴露了一个更深层的问题：kb-writer 和 design-yuntianguang 的职责边界不清晰。AGENTS.md 中明确规定 kb-writer 严禁自行生图，但如果没有这条铁律，agent 在"用户催得急"的场景下很容易越界。职责边界不是靠自觉，而是靠制度。

3. 技能路径恢复检查

ComfyUI 的技能路径存在两个位置（openclaw 标准路径和 hermes 扩展路径），只检查其中一个就会遗漏。这次已将其固化为铁律，后续所有生图操作前必须双路径确认。

4. 文档即代码

在这次排查中，AGENTS.md、SKILL.md 等"文档"文件与 workflow 文件、Python 脚本同等重要。它们定义了参数规范、职责边界和流程约束，是配置管理的有机组成部分，不应被视为"可选的注释"。

这次排查始于一个数字的偏差，却收获了一份配置管理体系的自检报告。从 workflow 源头到编排层 yaml，再到流程规范 SKILL.md 和经验教训 AGENTS.md，6 个文件的修复串联起了一条完整的配置治理链路。每次"小问题"都是一次压力测试，系统性排查才能让多 agent 协作系统越跑越稳。

关联阅读

• [[ComfyUI本地生图]]
• [[OpenClaw ComfyUI 集成与智能体配置全记录]]
• [[多智能体博客流水线架构设计：从 Skill 到 DAG 的演进]]
• [[OpenClaw 多智能体博客流水线：从 4.5 小时到 15 分钟的优化实战]]