minimal-agent 0.8.2 → 0.10.0

package/workflows/word.yaml

@@ -0,0 +1,710 @@
+name: word
+description: >
+  生成 Word 长文（素材驱动版，word）：统一摄取用户给的 Word/PPT/PDF/Excel/图片等素材
+  （可已有配图，也可纯文字）+ 一句要求 → 抽取文字与客户图 → 逐图识图 → 合并成
+  material.md/material.json → 总结、重组、扩写成知乎深度文章风格 → 规划图文混排
+  （客户图必须使用，必要时图生图增强；章节需要解释性视觉时积极文生图）→
+  Markdown-first 写 article.md → 使用 minimal-agent 自带 docx skill 转成 Word →
+  OPC 校验后交付 docx。Word 是阅读型长文，不走 PPT 的 Web 页面设计、HTML deck、
+  构图门、三层 hybrid 导出或固定画布视觉修复。
+version: "0.1"
+
+artifacts:
+  - "./out/article.docx"
+
+self_heal:
+  max_retries: 2
+  retry_delay_ms: 20000
+
+inputs:
+  - name: topic
+    type: string
+    required: true
+    greedy: true
+    description: "Word 长文主题 / 完整需求（中文自然语言即可：总结、扩写、改写、知乎长文、受众、语气、素材使用方式等）。"
+  - name: source
+    type: string
+    default: ""
+    description: "【素材文档·可选 --input】已有配图 Word、纯文字 Word、PPT、PDF、Excel、图片或混合素材路径。留空时解析 topic 中的文件线索，仍无明确素材则扫描当前目录支持格式。"
+  - name: out
+    type: string
+    default: "./out/article.docx"
+    description: "【高级·可选 --input】输出 Word 文件路径。"
+  - name: image_intensity
+    type: enum
+    values: ["minimal", "balanced", "rich"]
+    default: "balanced"
+    description: "【高级·可选 --input】配图积极性：minimal=只用客户图和少量必要解释图；balanced=客户图全用 + 关键章节配图；rich=客户图全用 + 所有适合视觉解释的章节积极文生图。"
+  - name: quality
+    type: enum
+    values: ["fast", "best"]
+    default: "fast"
+    description: "【高级·可选 --input】质量模式：fast=确定性硬门 + 一次导出；best=更严格正文/配图复核，可在后续版本扩展更多修订轮。"
+  - name: debug_keep_build
+    type: enum
+    values: ["true", "false"]
+    default: "true"
+    description: "【调试·可选 --input】是否保留 ./build 中间产物。默认 true，便于检查 article.md、material.json、img_plan.json 和报告。"
+
+steps:
+  - id: stage0_analyze
+    title: "阶段1/13·需求分析与写作策略"
+    agent: |
+      你要为用户做一篇 Word 长文。**本步只做需求分析和写作策略，不写文件、不生成 Word、不调用导出工具。**
+
+      用户原始要求：${inputs.topic}
+      素材路径：${inputs.source}
+      配图积极性：${inputs.image_intensity}
+
+      请输出简洁结论，供后续步骤引用：
+      - 文章目标：总结 / 扩写 / 改写 / 深度解读 / 报告化整理分别占多大比重。
+      - 受众和阅读场景：知乎深度文章、公众号长文、内部报告或客户材料复盘等。
+      - 内容深度：观点密度、解释粒度、是否需要补充背景常识。
+      - 写作风格：知乎深度文章，要求有观点、有论证、有转折、有小标题、有结论，不是 PPT 文案，也不是资料堆砌。
+      - 图文策略：
+        - 有客户图：所有客户图必须使用，原图或图生图增强后进入最终 Word。
+        - 无客户图：进入**纯 topic 创作模式**，必须基于用户要求自行总结扩写，并按章节观点生成文生图，不能交付纯文字 Word。
+        - 所有生图提示词必须结合上下文和章节观点，禁止空泛的“现代科技风”“知乎配图”“抽象背景”。
+      - 关键默认假设。
+    capture: writing_strategy
+    goal_supplement: true
+    onError: continue
+    maxTurns: 8
+
+  - id: stage_extract
+    title: "阶段2/13·摄取素材：抽取文字与客户图"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        mkdir -p ./build ./out
+        rm -f \
+          ./build/article.md \
+          ./build/article_outline.md \
+          ./build/build_complete \
+          ./build/export-summary.md \
+          ./build/img_plan.json \
+          ./build/image_map.json \
+          ./build/material.md \
+          ./build/material.json \
+          ./build/source_resolution.json \
+          ./build/source_assets.json \
+          ./build/source.md \
+          ./build/source_stats.json \
+          ./build/user_request.md \
+          ./build/word_topic_image_gate.json \
+          ./build/word_topic_image_gate.md \
+          ./build/word_customer_image_usage.json \
+          ./build/word_customer_image_usage.md
+        rm -rf ./build/assets ./build/vision ./build/generated-image-reviews
+        mkdir -p ./build/assets ./build/vision
+
+        RESOLVE="skills/ui-design/scripts/resolve_source_input.py"
+        EXTRACT="skills/ui-design/scripts/extract_source_assets.py"
+        STATS="skills/image-stats/scripts/image_stats.py"
+        RAW_TOPIC="$(cat <<'EOF_TOPIC'
+        ${inputs.topic}
+        EOF_TOPIC
+        )"
+        RAW_SOURCE="$(cat <<'EOF_SOURCE'
+        ${inputs.source}
+        EOF_SOURCE
+        )"
+        python3 "$RESOLVE" \
+          --source "$RAW_SOURCE" \
+          --topic "$RAW_TOPIC" \
+          --cwd . \
+          --out ./build/source_resolution.json
+        SOURCE="$(python3 -c 'import json; data=json.load(open("./build/source_resolution.json", encoding="utf-8")); print(data.get("resolved_path") or "")')"
+        if [ -n "$SOURCE" ]; then
+          python3 "$EXTRACT" "$SOURCE" --out ./build -v
+        else
+          python3 "$EXTRACT" . --scan --out ./build -v
+        fi
+        python3 -c 'import json,sys; r=json.load(open("./build/source_resolution.json", encoding="utf-8")); a=json.load(open("./build/source_assets.json", encoding="utf-8")); ok=not (r.get("requires_source") and not a.get("has_source")); print("WORD_SOURCE_REQUIRED_BUT_EMPTY: 用户明确要求使用素材文件，但抽取结果为空。", file=sys.stderr) if not ok else None; print(json.dumps(r, ensure_ascii=False, indent=2), file=sys.stderr) if not ok else None; sys.exit(0 if ok else 3)'
+        python3 "$STATS" ./build/assets --scan --json > ./build/source_stats.json
+        cat > ./build/user_request.md <<'EOF'
+        # 用户原始输入与目标
+
+        - 主题/指令：${inputs.topic}
+        - 素材路径：${inputs.source}
+        - 输出文件：${inputs.out}
+        - 配图积极性：${inputs.image_intensity}
+        - 质量模式：${inputs.quality}
+
+        ## 阶段1写作策略
+
+        ${writing_strategy}
+
+        ## 执行优先级
+
+        1. 用户原始输入和素材最高权重，后续写作、配图、导出都必须回看本文件。
+        2. Word 是阅读型长文：正文主导、深度论证、图文混排，绝不按 PPT 固定画布思路写。
+        3. 客户提供的图片必须全部使用：原图使用或图生图增强后使用，不能无故丢弃。
+        4. 文生图只服务章节理解，不做无上下文装饰图。
+        EOF
+        echo "WORD_SOURCE_EXTRACT_READY"
+        test -f ./build/source_assets.json
+    onError: halt
+
+  - id: stage_vision_loop
+    title: "阶段3/13·逐图识图：客户图内容与文章落点"
+    when: "fileExists('./build/source_assets.json')"
+    type: loop
+    over: "${asArray(readJson('./build/source_assets.json', 'images'))}"
+    as: img
+    fresh_context: true
+    do:
+      - id: vision_one
+        title: "阶段3/13·识图 ${img.file}"
+        llm: |
+          你在为 Word 长文识别客户图片。下方已附上客户图片 `${img.file}`（朝向 ${img.orient}，来自素材章节「${img.section}」）。
+          只输出合法 JSON 对象，不要 Markdown、不要代码围栏。字符串内部不要使用未转义英文双引号。
+
+          JSON 字段：
+          - `description`：图片内容，包含主体、场景、图表/截图/照片类型、可读文字或关键信息。
+          - `key_elements`：关键元素数组。
+          - `content_type`：photo|screenshot_slide|screenshot_ui|chart|diagram|document_scan|poster|other。
+          - `information_density`：low|medium|high。图表、截图、文档扫描通常 high。
+          - `suggested_article_section`：这张图最适合放入文章的哪类章节，结合素材上下文判断。
+          - `caption_hint`：适合 Word 图注的一句话，必须和文章观点/证据有关。
+          - `enhance_recommended`：true/false。低清、比例不适合、背景杂乱、风格不统一时 true；信息密集图/截图/图表若增强会损失文字则 false。
+          - `enhance_prompt`：如果需要图生图增强，写英文提示词；必须保留原始主体、信息语义和构图重点，只改善清晰度、比例、光线、背景整洁度和 Word 文章配图质感。
+          - `use_rule`：必须写明“所有客户图必须使用，原图或增强后进入最终 Word”。
+        images: ["./build/assets/${img.file}"]
+        image_detail: high
+        capture:
+          text: vision_json
+        onError: continue
+        maxTurns: 3
+
+      - id: write_vision_json
+        title: "阶段3/13·写入识图 JSON ${img.file}"
+        when: "length(vision_json) > 0"
+        tool: Write
+        args:
+          file_path: "./build/vision/${img.file}.json"
+          content: "${vision_json}"
+        onError: continue
+
+      - id: sanitize_vision_json
+        title: "阶段3/13·校验识图 JSON ${img.file}"
+        when: "fileExists('./build/vision/${img.file}.json')"
+        tool: Bash
+        args:
+          command: |
+            python3 - "./build/vision/${img.file}.json" <<'PYEOF'
+            import json, sys, os
+            path = sys.argv[1]
+            try:
+                data = json.load(open(path, encoding="utf-8"))
+                if not isinstance(data, dict):
+                    raise ValueError("root must be object")
+                json.dump(data, open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=2)
+            except Exception as e:
+                print(f"WORD_VISION_JSON_INVALID {path}: {e}", file=sys.stderr)
+                try:
+                    os.remove(path)
+                except FileNotFoundError:
+                    pass
+            PYEOF
+        onError: continue
+
+  - id: stage_assemble_material
+    title: "阶段4/13·合并统一材料 material.md/json"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        python3 - <<'PYEOF'
+        import json, os
+        from pathlib import Path
+
+        build = Path("./build")
+        assets = build / "assets"
+        vision_dir = build / "vision"
+
+        def read_json(path, default):
+            try:
+                return json.loads(Path(path).read_text(encoding="utf-8-sig"))
+            except Exception:
+                return default
+
+        source_assets = read_json(build / "source_assets.json", {})
+        source_stats = read_json(build / "source_stats.json", {})
+        source_text = (build / "source.md").read_text(encoding="utf-8") if (build / "source.md").exists() else ""
+        images = []
+        for img in source_assets.get("images") or []:
+            item = dict(img)
+            vf = vision_dir / f"{img.get('file')}.json"
+            item["vision"] = read_json(vf, {}) if vf.exists() else {}
+            images.append(item)
+
+        material = {
+            "user_request": {
+                "topic": """${inputs.topic}""",
+                "source": """${inputs.source}""",
+                "out": """${inputs.out}""",
+                "image_intensity": """${inputs.image_intensity}""",
+                "writing_strategy": """${writing_strategy}""",
+            },
+            "source_assets": source_assets,
+            "source_stats": source_stats,
+            "source_text": source_text,
+            "images": images,
+            "rules": {
+                "article_style": "知乎深度文章",
+                "customer_images": "所有客户图必须使用，原图或图生图增强后进入最终 Word。",
+                "new_images": "章节需要视觉解释时积极文生图，提示词必须结合上下文和章节观点。",
+                "not_ppt": "不做网页式固定画布设计、页面 JSON 设计稿、构图门或 PPTX 三层导出。",
+            },
+        }
+        (build / "material.json").write_text(json.dumps(material, ensure_ascii=False, indent=2), encoding="utf-8")
+
+        md = []
+        md.append("# Word 长文统一材料\n")
+        md.append("## 用户目标\n")
+        md.append(f"- 主题/指令：{material['user_request']['topic']}\n")
+        md.append(f"- 素材路径：{material['user_request']['source']}\n")
+        md.append(f"- 配图积极性：{material['user_request']['image_intensity']}\n")
+        md.append("\n## 写作策略\n\n")
+        md.append(material["user_request"]["writing_strategy"].strip() + "\n\n")
+        md.append("## 抽取文字\n\n")
+        md.append(source_text.strip() or "（未抽取到文字素材）")
+        md.append("\n\n## 客户图清单（必须全部使用）\n\n")
+        for i, img in enumerate(images, 1):
+            v = img.get("vision") or {}
+            md.append(f"### 图 {i}: {img.get('file')}\n")
+            md.append(f"- 章节来源：{img.get('section', '')}\n")
+            md.append(f"- 朝向：{img.get('orient', '')}\n")
+            md.append(f"- 内容类型：{v.get('content_type', '')}\n")
+            md.append(f"- 内容描述：{v.get('description', '')}\n")
+            md.append(f"- 建议文章章节：{v.get('suggested_article_section', '')}\n")
+            md.append(f"- 建议图注：{v.get('caption_hint', '')}\n")
+            md.append(f"- 是否建议增强：{v.get('enhance_recommended', '')}\n\n")
+        (build / "material.md").write_text("".join(md), encoding="utf-8")
+        print(f"WORD_MATERIAL_READY images={len(images)} chars={len(source_text)}")
+        PYEOF
+        test -f ./build/material.md
+        test -f ./build/material.json
+    onError: halt
+
+  - id: stage_outline
+    title: "阶段5/13·总结扩写大纲：知乎深度长文结构"
+    agent: |
+      基于以下材料写一份 Word 长文大纲，落盘到 `./build/article_outline.md`：
+      - `./build/user_request.md`
+      - `./build/material.md`
+      - `./build/material.json`
+
+      要求：
+      - 文章定位为**知乎深度文章**：有观点、有论证、有转折、有解释、有结论。
+      - 根据素材做总结、重组和扩写；不能只摘抄素材，也不能脱离素材编故事。
+      - 大纲必须包含：标题候选、导语角度、核心观点、章节结构、每章论点、证据/案例位置、结尾观点。
+      - 明确图文混排思路：每张客户图应该进入哪个章节；哪些章节需要额外文生图；为什么需要图。
+      - 对客户图写明：**所有客户图必须使用**，原图或图生图增强后使用。
+      - 需要文生图的章节，先写中文视觉意图和上下文，不要只写空泛风格词。
+      - 若 `material.json.images` 为空，说明没有客户图，必须进入**无客户图 / 纯 topic 创作模式**：
+        - 大纲必须规划至少 3 个解释型/场景型/概念型配图点。
+        - 每个配图点必须说明服务哪个章节观点和读者理解，不允许装饰图。
+        - 默认 `image_intensity=balanced` 至少 3 张；`rich` 至少 5 张；`minimal` 至少 1 张封面或核心概念图。
+
+      写完后简短汇报。
+    done_when: "fileExists('./build/article_outline.md')"
+    onError: halt
+    maxTurns: 18
+
+  - id: stage_write_article
+    title: "阶段6/13·写作 article.md：知乎深度长文正文"
+    agent: |
+      基于 `./build/article_outline.md`、`./build/material.md`、`./build/material.json` 写正文，落盘到 `./build/article.md`。
+
+      写作要求：
+      - 风格是**知乎深度文章**，不是 PPT 文案，不是资料堆砌。
+      - 要有清晰标题、导语、多个二级/三级标题、论证段、解释段、案例段、结论。
+      - 允许总结扩写，但必须结合素材上下文和用户目标；不要一知半解地泛泛发挥。
+      - 先用 Markdown 占位标记图片，例如：
+        `<!-- image: src_1.png | purpose: 证明某观点 | caption: ... -->`
+      - 每张客户图必须至少有一个占位。
+      - **无客户图 / 纯 topic 创作模式**也必须保留文生图占位，不能交付纯文字 Word：
+        - `minimal` 至少 1 个封面/核心概念图占位。
+        - `balanced` 至少 3 个图片占位。
+        - `rich` 至少 5 个图片占位。
+        - 每个占位必须贴近对应章节观点，写清 purpose 和 caption。
+      - 图片附近必须有上下文解释，不能把图片孤零零塞进去。
+      - 文章中避免出现“作为 AI”“根据材料可知”这类过程话。
+    done_when: "fileExists('./build/article.md')"
+    onError: halt
+    maxTurns: 25
+
+  - id: stage_img_plan
+    title: "阶段7/13·图文混排计划 img_plan/image_map"
+    agent: |
+      基于 `./build/article.md`、`./build/material.json`、`./build/material.md` 生成两个文件：
+      1. `./build/img_plan.json`
+      2. `./build/image_map.json`
+
+      `img_plan.json` 是给 GenerateImage 工具使用的数组，只放需要实际生成/增强的图：
+      - 文生图：`{"file":"word_img_1.png","mode":"text-to-image","aspect":"16:9","prompt":"..."}`
+      - 图生图：`{"file":"enhanced_src_1.png","mode":"image-to-image","source_file":"src_1.png","aspect":"4:3","prompt":"..."}`
+      - prompt 必须是英文，但必须来自文章上下文、章节观点和 material.md，不允许空泛的“现代科技风”“知乎配图”“抽象背景”。
+
+      `image_map.json` 记录所有最终要进入 Word 的图片，数组字段至少包含：
+      - `source_file`：客户图原文件；文生图可为空字符串。
+      - `final_file`：最终插入 article.md 的图片文件名。客户图原图可直接是 `src_K.png`；增强图是 `enhanced_src_K.png`；文生图是 `word_img_K.png`。
+      - `article_section`：插入章节。
+      - `caption`：Word 图注。
+      - `alt`：图片 alt 文本。
+      - `usage`：source-original|source-enhanced|text-to-image。
+      - `context_reason`：为什么这张图服务该章节论点。
+
+      硬性规则：
+      - `material.json` 的 `images` 里所有客户图都必须出现在 `image_map.json`，所有客户图必须使用。
+      - 信息密集图、截图、图表类默认 source-original 或轻增强后完整展示；不要图生图导致文字/信息丢失。
+      - 低清、比例不合适、背景杂乱、风格不统一的客户图可 source-enhanced，但必须保留原图主体和语义。
+      - 无客户图 / 纯 topic 创作模式时，`img_plan.json` 不得为空，必须全部是 `text-to-image` 文生图条目，并按 `${inputs.image_intensity}` 控制最低数量：
+        - `minimal`：至少 1 张。
+        - `balanced`：至少 3 张。
+        - `rich`：至少 5 张。
+      - 纯 topic 模式每条文生图必须包含 `file`、`mode`、`aspect`、`prompt`，其中 `mode` 必须是 `text-to-image`。
+      - 纯 topic 模式每条 prompt 必须结合 `article.md` 的章节观点、上下文、场景和图注意图，不允许只写风格词。
+      - 有客户图时也可以按 `${inputs.image_intensity}` 给关键章节补充文生图，但不能替代客户图使用。
+
+      写完两个 JSON 后简短汇报。
+    done_when: "fileExists('./build/img_plan.json') && fileExists('./build/image_map.json')"
+    onError: halt
+    maxTurns: 18
+
+  - id: stage_sanitize_img_plan
+    title: "阶段7/13·校验配图计划 JSON"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        python3 - <<'PYEOF'
+        import json, sys
+        from pathlib import Path
+        build = Path("./build")
+        for name, expect_array in [("img_plan.json", True), ("image_map.json", True)]:
+            path = build / name
+            data = json.loads(path.read_text(encoding="utf-8-sig"))
+            if expect_array and not isinstance(data, list):
+                raise SystemExit(f"{name} root must be array")
+            path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+        print("WORD_IMAGE_PLAN_JSON_OK")
+        PYEOF
+    onError: halt
+
+  - id: stage_gen_images
+    title: "阶段8/13·客户图增强与章节配图生成"
+    when: "fileExists('./build/img_plan.json')"
+    tool: GenerateImage
+    args:
+      plan: ./build/img_plan.json
+      assets: ./build/assets
+      size: 2k
+      timeout_ms: 300000
+      wall_budget_ms: 3600000
+      concurrency: 2
+    onError: continue
+    max_retries: 1
+
+  - id: stage_image_quality_gate
+    title: "阶段8/13·补生成降级配图"
+    when: "fileExists('./build/image_generation_report.json')"
+    tool: GenerateImage
+    args:
+      plan: ./build/img_plan.json
+      assets: ./build/assets
+      size: 2k
+      timeout_ms: 300000
+      wall_budget_ms: 3600000
+      retry_degraded_report: ./build/image_generation_report.json
+      max_rounds: 1
+      concurrency: 2
+    onError: continue
+    max_retries: 1
+
+  - id: stage_generated_image_gate
+    title: "阶段8/13·配图成品硬闸门"
+    when: "fileExists('./build/image_generation_report.json')"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        python3 - <<'PYEOF'
+        import json
+        from pathlib import Path
+
+        build = Path("./build")
+        report = json.loads((build / "image_generation_report.json").read_text(encoding="utf-8"))
+        plan = json.loads((build / "img_plan.json").read_text(encoding="utf-8"))
+        assets = build / "assets"
+        errors = []
+        if report.get("qualityOk") is not True:
+            errors.append("image generation report is degraded or incomplete")
+        for item in plan:
+            name = str(item.get("file") or "")
+            path = assets / name
+            if not name or not path.is_file():
+                errors.append(f"missing generated image: {name or '<unnamed>'}")
+            elif path.stat().st_size < 8192:
+                errors.append(f"generated image is implausibly small: {name} ({path.stat().st_size} bytes)")
+        if errors:
+            raise SystemExit("WORD_GENERATED_IMAGE_GATE_FAILED: " + "; ".join(errors))
+        print("WORD_GENERATED_IMAGE_GATE_OK")
+        PYEOF
+    onError: halt
+
+  - id: stage_finalize_markdown
+    title: "阶段9/13·Markdown 图文混排收口"
+    agent: |
+      更新 `./build/article.md`，把 `./build/image_map.json` 中的图片按章节插入最终位置。
+
+      要求：
+      - 图片路径统一使用 `./build/assets/<final_file>`。
+      - 每张图必须有 Markdown 图片语法和紧随其后的图注，例如：
+        `![alt](./build/assets/final.png)`
+        `*图：caption*`
+      - 删除临时 `<!-- image: ... -->` 占位。
+      - 保持知乎深度文章风格：图片前后要有解释段，说明它支持了哪个观点或案例。
+      - 统一标题层级、段落节奏、引用块、表格、结论。
+      - 不要加入 PPT 术语，不要提网页 deck、页面 JSON 设计稿、构图门或 fixed canvas。
+    done_when: "fileExists('./build/article.md')"
+    onError: halt
+    maxTurns: 18
+
+  - id: stage_topic_image_gate
+    title: "阶段10/13·纯 topic 文生图闸门"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        python3 - <<'PYEOF'
+        import json, sys
+        from pathlib import Path
+
+        build = Path("./build")
+        material = json.loads((build / "material.json").read_text(encoding="utf-8"))
+        customer = [img.get("file") for img in material.get("images", []) if img.get("file")]
+        if customer:
+            print("WORD_TOPIC_IMAGE_GATE_SKIP: 有客户图，交给客户图用尽闸门")
+            raise SystemExit(0)
+
+        intensity = "${inputs.image_intensity}"
+        required = {"minimal": 1, "balanced": 3, "rich": 5}.get(intensity, 3)
+        img_plan = json.loads((build / "img_plan.json").read_text(encoding="utf-8"))
+        image_map = json.loads((build / "image_map.json").read_text(encoding="utf-8"))
+        article = (build / "article.md").read_text(encoding="utf-8")
+
+        errors = []
+        if not isinstance(img_plan, list):
+            errors.append("img_plan.json root must be array")
+            img_plan = []
+        if not isinstance(image_map, list):
+            errors.append("image_map.json root must be array")
+            image_map = []
+
+        text_to_image = []
+        for i, item in enumerate(img_plan):
+            if not isinstance(item, dict):
+                errors.append(f"img_plan[{i}] must be object")
+                continue
+            if item.get("mode") != "text-to-image":
+                errors.append(f"img_plan[{i}].mode must be text-to-image in pure topic mode")
+            for key in ("file", "mode", "aspect", "prompt"):
+                if not str(item.get(key) or "").strip():
+                    errors.append(f"img_plan[{i}].{key} required")
+            if item.get("mode") == "text-to-image":
+                text_to_image.append(item)
+
+        if len(text_to_image) < required:
+            errors.append(
+                f"pure topic mode requires at least {required} text-to-image items for image_intensity={intensity}, got {len(text_to_image)}"
+            )
+
+        mapped_text_images = [m for m in image_map if isinstance(m, dict) and m.get("usage") == "text-to-image"]
+        if len(mapped_text_images) < required:
+            errors.append(f"image_map requires at least {required} text-to-image entries, got {len(mapped_text_images)}")
+        for i, item in enumerate(mapped_text_images):
+            for key in ("final_file", "article_section", "caption", "alt", "context_reason"):
+                if not str(item.get(key) or "").strip():
+                    errors.append(f"image_map text-to-image entry {i}.{key} required")
+            final_file = str(item.get("final_file") or "")
+            if final_file and final_file not in article:
+                errors.append(f"article.md does not reference text-to-image final_file: {final_file}")
+
+        report = {
+            "ok": not errors,
+            "mode": "pure-topic",
+            "image_intensity": intensity,
+            "required_text_to_image": required,
+            "img_plan_text_to_image": len(text_to_image),
+            "image_map_text_to_image": len(mapped_text_images),
+            "errors": errors,
+        }
+        (build / "word_topic_image_gate.json").write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+        md = ["# Word 纯 topic 文生图闸门\n\n", f"- 模式：无客户图 / 纯 topic\n", f"- 配图强度：{intensity}\n", f"- 最低文生图数量：{required}\n", f"- 结果：{'通过' if not errors else '失败'}\n"]
+        for e in errors:
+            md.append(f"- {e}\n")
+        (build / "word_topic_image_gate.md").write_text("".join(md), encoding="utf-8")
+        if errors:
+            print(json.dumps(report, ensure_ascii=False, indent=2), file=sys.stderr)
+            raise SystemExit("WORD_TOPIC_IMAGE_GATE_FAILED: 纯 topic 模式必须生成足量文生图并完成 article.md 引用")
+        print("WORD_TOPIC_IMAGE_GATE_OK")
+        PYEOF
+    onError: halt
+
+  - id: stage_customer_image_gate
+    title: "阶段10/13·客户图用尽闸门"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        python3 - <<'PYEOF'
+        import json, re, sys
+        from pathlib import Path
+
+        build = Path("./build")
+        material = json.loads((build / "material.json").read_text(encoding="utf-8"))
+        image_map = json.loads((build / "image_map.json").read_text(encoding="utf-8"))
+        article = (build / "article.md").read_text(encoding="utf-8")
+        customer = [img.get("file") for img in material.get("images", []) if img.get("file")]
+        mapped = {m.get("source_file") for m in image_map if m.get("source_file")}
+        text = article
+        missing = []
+        for src in customer:
+            finals = [m.get("final_file") for m in image_map if m.get("source_file") == src]
+            if src not in mapped:
+                missing.append({"source_file": src, "reason": "not in image_map.source_file"})
+                continue
+            if not any(f and f in text for f in finals):
+                missing.append({"source_file": src, "reason": "mapped but final_file not referenced in article.md", "final_files": finals})
+        report = {"ok": not missing, "customer_count": len(customer), "missing": missing}
+        (build / "word_customer_image_usage.json").write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+        md = ["# Word 客户图用尽闸门\n\n", f"- 客户图数量：{len(customer)}\n", f"- 结果：{'通过' if not missing else '失败'}\n"]
+        for item in missing:
+            md.append(f"- 缺失：{item}\n")
+        (build / "word_customer_image_usage.md").write_text("".join(md), encoding="utf-8")
+        if missing:
+            print(json.dumps(report, ensure_ascii=False, indent=2), file=sys.stderr)
+            raise SystemExit("WORD_CUSTOMER_IMAGE_USAGE_FAILED: 所有客户图必须使用，缺失项见 build/word_customer_image_usage.md")
+        print("WORD_CUSTOMER_IMAGE_USAGE_OK")
+        PYEOF
+    onError: halt
+
+  - id: stage_export_docx
+    title: "阶段11/13·使用 docx skill 导出 Word"
+    skill: docx
+    input: |
+      本步骤是 `skill: docx` 必要节点。
+      请严格按当前 minimal-agent 自带 `skills/docx/SKILL.md` 的指引，把 `./build/article.md` 转换为 Word 文件 `${inputs.out}`。
+
+      硬性要求：
+      - 优先使用 Markdown-first 路线：pandoc `./build/article.md -f markdown-implicit_figures -t docx -o ${inputs.out} --wrap=preserve --standalone`。
+      - 必须关闭 pandoc implicit_figures，避免 Markdown 图片 alt 文本被渲染成额外可见图注；最终只保留 article.md 中显式的 `*图：...*` 图注。
+      - 如果 pandoc 不可用或图片/表格转换失败，按 docx skill 指引回退到 python-docx 或 docx-js。
+      - 若使用 docx-js，必须用 Node 运行脚本，不要用 Bun。
+      - 保留 Markdown 标题层级、列表、表格、引用块、图片、图注和正文段落。
+      - 图片来自 `./build/assets/<final_file>`，不要丢图。
+      - 最终必须生成 `${inputs.out}`。
+    onError: halt
+    maxTurns: 25
+
+  - id: stage_verify_docx
+    title: "阶段12/13·DOCX OPC 校验"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        OUT="${inputs.out}"
+        test -f "$OUT"
+        python3 - "$OUT" <<'PYEOF'
+        import shutil, sys, tempfile, zipfile
+        from pathlib import Path
+        from xml.etree import ElementTree as ET
+
+        path = Path(sys.argv[1])
+        ns = "http://schemas.openxmlformats.org/package/2006/content-types"
+        ET.register_namespace("", ns)
+
+        with zipfile.ZipFile(path, "r") as zin:
+            names = zin.namelist()
+            has_png = any(n.startswith("word/media/") and n.lower().endswith(".png") for n in names)
+            content_types = zin.read("[Content_Types].xml")
+
+        if has_png:
+            root = ET.fromstring(content_types)
+            has_default = any(
+                child.tag == f"{{{ns}}}Default"
+                and child.attrib.get("Extension", "").lower() == "png"
+                for child in root
+            )
+            if not has_default:
+                ET.SubElement(root, f"{{{ns}}}Default", {"Extension": "png", "ContentType": "image/png"})
+                updated = ET.tostring(root, encoding="utf-8", xml_declaration=True)
+                with tempfile.NamedTemporaryFile(delete=False, suffix=".docx") as tmp:
+                    tmp_path = Path(tmp.name)
+                with zipfile.ZipFile(path, "r") as zin, zipfile.ZipFile(tmp_path, "w", zipfile.ZIP_DEFLATED) as zout:
+                    for item in zin.infolist():
+                        if item.filename == "[Content_Types].xml":
+                            zout.writestr(item, updated)
+                        else:
+                            zout.writestr(item, zin.read(item.filename))
+                shutil.move(tmp_path, path)
+                print("WORD_DOCX_PNG_CONTENT_TYPE_ADDED")
+        PYEOF
+        python3 skills/docx/scripts/opc_check.py "$OUT" || (
+          python3 skills/docx/scripts/opc_check.py "$OUT" --repack "$OUT.tmp.docx" &&
+          mv -f "$OUT.tmp.docx" "$OUT" &&
+          python3 skills/docx/scripts/opc_check.py "$OUT"
+        )
+        python3 skills/docx/scripts/office/validate.py "$OUT" || true
+        python3 - <<'PYEOF'
+        import json, os
+        from pathlib import Path
+        build = Path("./build")
+        article = build / "article.md"
+        image_map = json.loads((build / "image_map.json").read_text(encoding="utf-8")) if (build / "image_map.json").exists() else []
+        usage = json.loads((build / "word_customer_image_usage.json").read_text(encoding="utf-8")) if (build / "word_customer_image_usage.json").exists() else {}
+        summary = [
+            "# Word 导出摘要\n\n",
+            f"- 输出文件：${inputs.out}\n",
+            f"- Markdown：./build/article.md\n",
+            f"- 文章字符数：{len(article.read_text(encoding='utf-8')) if article.exists() else 0}\n",
+            f"- 图片映射数量：{len(image_map)}\n",
+            f"- 客户图数量：{usage.get('customer_count', 0)}\n",
+            "- OPC 校验：通过\n",
+        ]
+        (build / "export-summary.md").write_text("".join(summary), encoding="utf-8")
+        print("WORD_DOCX_VERIFY_OK")
+        PYEOF
+        touch ./build/build_complete
+    onError: halt
+
+  - id: cleanup_intermediates
+    title: "阶段13/13·处理中间产物"
+    when: "inputs.debug_keep_build == 'false'"
+    tool: Bash
+    args:
+      command: |
+        set -e
+        mkdir -p ./out
+        cp ./build/export-summary.md ./out/word-export-summary.md 2>/dev/null || true
+        rm -rf ./build
+        echo "WORD_BUILD_CLEANED"
+    onError: continue
+
+  - id: final_report
+    title: "阶段13/13·完成报告"
+    type: echo
+    message: |
+      Word 长文已生成。
+
+      - 输出 Word：${inputs.out}
+      - Markdown 草稿：./build/article.md
+      - 统一材料：./build/material.md / ./build/material.json
+      - 配图计划：./build/img_plan.json / ./build/image_map.json
+      - 导出摘要：./build/export-summary.md
+
+      流程：素材摄取 → 逐图识图 → 统一 material → 知乎深度文章大纲 → article.md 正文 → 图文混排计划 → 客户图增强/章节配图 → 客户图用尽闸门 → docx skill 导出 → OPC 校验。