[codex] Document guizang material QA workflow

README.md

@@ -122,6 +122,8 @@ out/
 
 Humanize PPT 当前重点是稳定“资料 → AST生产契约 → 风格预览/完整deck → presenter/export → QA”的工作流。更多renderer自动化、视频生成、部署平台集成和团队包上传会放到后续版本，不塞进这次目录整理。
 
+V0.6.1 补充了 guizang downstream 工作流经验：Humanize PPT 先产出 AST 契约，guizang 负责中文稳定渲染，素材生产和视觉 QA 作为独立 pass 记录。文字精确的信息图优先用 SVG/HTML 等确定性素材；Remotion 用作短流程视频素材，不替代 PPT 页面本体。
+
 ## 在线预览
 
 - 首页：https://learnprompt.github.io/humanize-ppt/
@@ -135,6 +137,7 @@ Humanize PPT 当前重点是稳定“资料 → AST生产契约 → 风格预览
 - [OPC工作流](docs/OPC-workflow.md)
 - [Agent Teams](docs/agent-teams.md)
 - [Smoke Test](docs/smoke-test.md)
+- [Guizang material QA](references/guizang-material-qa.md)
 - [版本历史](docs/versions/)
 - [发版前审查清单](docs/plans/2026-05-25-release-readiness-checklist.md)
 

SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: humanize-ppt
 description: AST-based outline director and router for human-centered AI presentation workflows. Use before generating PPT/HTML slides from raw material, or as the single entrypoint that routes to downstream PPT Skills.
-version: 0.6.0
+version: 0.6.1
 author: LearnPrompt
 license: MIT
 metadata:
@@ -101,19 +101,23 @@ C — Complete / Control
 10. When `beautiful-html-templates` is the preview-first route, do not stop at a planned command file. A connected path must produce real `outputs/beautiful/previews/index.html`, three candidate title-slide previews, `preview_manifest.json`, a render report, and a QA-visible route status. Treat this as V0.3+ capability, because it changes the user-facing workflow from routing advice to visible style selection.
 11. When the user chooses a Beautiful candidate, run V0.4+ `--selected-template <slug>` and produce a real full deck at `outputs/beautiful/selected/index.html` plus `selected_manifest.json`. Do not call this complete if only the preview gallery exists.
 12. In V0.5, presenter/export are post-processing adapters. They require a rendered final deck (`outputs/<renderer>/index.html` or `outputs/beautiful/selected/index.html`), not just a preview gallery.
+13. When routing to `guizang-ppt-skill`, treat guizang as the stable Chinese production renderer, then run a separate visual/material QA pass before presenter or deploy. Check that template class names actually exist in the copied template CSS; do not trust layout docs blindly. If an SVG, GPT image, screenshot, or Remotion clip is inserted, it must support the page instead of repeating the page title, and all internal text must fit within its own safe area.
+14. For Swiss-style guizang decks, use Remotion as a material producer for short process clips and deterministic SVG/HTML diagrams for text-heavy Chinese information graphics. Prefer GPT image generation for non-textual photos, mood images, or visual concepts; use deterministic SVG/HTML when exact Chinese labels, grid alignment, or validation-friendly text is required.
 
 ## Operational references
 
 - `references/agent-teams-public-preview.md` — Agent Teams architecture, specialist-agent command protocol, public preview release loop, and README split convention.
 - `references/humanize-ppt-public-writing.md` — Public-facing positioning and article/script patterns: Humanize PPT as adaptable outline/director layer, not a fixed 4-Skill bundle.
 - `references/workbuddy-team-packaging-and-video-materials.md` — WorkBuddy/CodeBuddy team upload zip structure, validation script, scenario rules shape, and the Remotion/HyperFrames-as-material-producers pitfall.
+- `references/guizang-material-qa.md` — Guizang downstream workflow, material production rules, Swiss visual QA checklist, and failure patterns learned from a full Humanize PPT → guizang deck pass.
 - `references/beautiful-preview-first-adapter.md` — Durable adapter pattern for connecting `beautiful-html-templates`: version boundary, template selection, real title-slide previews, manifests, QA, and pitfalls.
 - `references/selected-template-full-deck-adapter.md` — Durable adapter pattern for V0.4 selected-template full deck generation: required artifacts, routing, QA, and TDD coverage.
 - `references/presenter-export-adapter.md` — Durable adapter pattern for adding V0.5-style presenter shell and export package after a final deck exists.
 - `docs/versions/v0.2-router-edition.md` — V0.2 Router Edition notes kept for history.
 - `docs/versions/v0.3-preview-first.md` — V0.3 Preview-First implementation notes: real `beautiful-html-templates` preview gallery, template selection, manifests, and version boundary.
 - `docs/versions/v0.4-selected-template-full-deck.md` — V0.4 Selected Template Full Deck notes: `--selected-template`, selected deck output, manifests, QA, and current boundaries.
 - `docs/versions/v0.5-presenter-export-adapter.md` — V0.5 Presenter / Export Adapter notes: `--presenter-adapter`, `--export-adapter`, output artifacts, and boundaries.
+- `docs/versions/v0.6.1-guizang-material-qa.md` — V0.6.1 Guizang material QA notes: downstream artifact recording, Remotion-as-material, SVG-safe Chinese diagrams, and visual review rules.
 - `docs/smoke-test.md` — No-dependency smoke check for validating the stable entrypoint on machines without pytest.
 - `docs/plans/2026-05-25-release-readiness-checklist.md` — V0.6 release-readiness checklist and release-note draft.
 

docs/versions/v0.6.1-guizang-material-qa.md

@@ -0,0 +1,32 @@
+# V0.6.1 Guizang Material QA
+
+V0.6.1 is a workflow-note release. It records lessons from a full Humanize PPT → guizang-ppt-skill pass that included Swiss HTML rendering, deterministic diagram materials, a Remotion process clip, and visual QA iterations.
+
+## What Changed
+
+- Bumped public skill metadata to `0.6.1`.
+- Added `references/guizang-material-qa.md`.
+- Clarified that guizang completion needs a visual/material QA pass after the first HTML deck exists.
+- Clarified that Remotion is a PPT material producer, not a replacement for slide content.
+- Clarified that deterministic SVG/HTML is preferred for Chinese text-heavy diagrams, while GPT image generation is better for non-textual visual support.
+
+## Lessons Captured
+
+1. Humanize PPT must record downstream artifacts explicitly.
+   A guizang deck, inserted materials, and Remotion source/output should be visible in manifests instead of living as informal side files.
+
+2. Layout documentation is not enough.
+   A class mentioned in a reference document may not exist in the current copied template. Agents must verify class names against the actual template CSS before relying on them.
+
+3. Materials should not repeat page titles.
+   The slide owns the title and narrative frame. SVG diagrams and Remotion clips should carry the proof, process, or system relationship.
+
+4. SVG text needs a local safe area.
+   Chinese labels can clip or overlap once scaled into deck frames. Increase card height, reduce label size, and keep connectors clear of labels.
+
+5. Statement pages may need structural anchors.
+   Swiss whitespace works when it is intentional. If a statement page feels unfinished, add a compact stack, comparison, or supporting evidence rather than filling space randomly.
+
+## Boundaries
+
+This release does not add a new automatic guizang material generator. It documents the workflow and QA rules so a future adapter can implement them without re-learning these failure modes.

references/guizang-material-qa.md

@@ -0,0 +1,98 @@
+# Guizang Material QA
+
+Use this reference when Humanize PPT routes a deck to `guizang-ppt-skill`, especially for Chinese Swiss-style decks that need inserted diagrams, screenshots, generated images, or Remotion clips.
+
+## Position
+
+Humanize PPT remains the outline director and route owner. Guizang is the downstream renderer for stable Chinese HTML PPT production. Material generation is a separate pass after the first guizang deck exists.
+
+Recommended route:
+
+```text
+raw material
+→ Humanize PPT AST contract
+→ guizang-ppt-skill HTML deck
+→ material production pass
+→ visual QA pass
+→ presenter/export/deploy
+```
+
+Do not describe a guizang deck as complete just because `index.html` exists. A produced deck needs visual QA after materials are inserted.
+
+## Material Selection
+
+Choose materials by page need:
+
+- If a page feels empty, first decide what is missing: proof, process, system relationship, comparison, screenshot evidence, or emotional anchor.
+- Use Remotion for short timed process clips, transition fragments, before/after motion, or explanatory sequences.
+- Use deterministic SVG/HTML diagrams for Chinese text-heavy information graphics, exact labels, Swiss grid alignment, and content that must be inspectable.
+- Use GPT image generation for non-textual photos, mood images, visual metaphors, or concept art where exact text is not critical.
+- Use screenshot framing when preserving a real UI or source image matters more than redesigning it.
+
+Remotion, GPT images, and SVG diagrams are materials inside PPT pages. They should not replace the page with an empty embedded player or duplicate the page title.
+
+## Guizang Swiss QA Checklist
+
+Before reporting completion, check:
+
+1. `guizang-ppt-skill` validator passes for Swiss decks.
+2. Every slide has a registered `data-layout`.
+3. Referenced class names exist in the copied template CSS. Do not trust layout docs alone; verify the actual template.
+4. No page has unresolved placeholders such as `[必填]`.
+5. Text inside inserted SVG/image/video frames has its own safe area and does not clip, overlap, or hug the edge.
+6. Inserted materials do not repeat the outer PPT title. The page owns the title; the material should carry the diagram, process, proof, or evidence.
+7. Long Chinese labels are either shortened, split into lines, or moved into HTML text outside the image.
+8. Video slots have a purpose, duration, source path, and fallback explanation in the manifest.
+9. The final `material_manifest.json` records all generated or inserted assets.
+10. The downstream route is reflected in `router_plan.json` / `run_manifest.json` when the workflow is being packaged as a Humanize PPT run.
+
+## Failure Patterns
+
+### Undefined layout classes
+
+If a page uses a class from a reference document but the copied template CSS does not define it, the page may collapse into plain vertical text. Fix by switching to classes verified in the actual template, such as `grid-6`, `card-fill`, `card-accent`, `sub-card`, or the registered Sxx skeleton.
+
+### Text clipped inside SVG
+
+SVG text can look correct in isolation but clip once scaled into a deck frame. Increase the containing rectangle, reduce text size, move baselines inward, and keep connector lines away from labels.
+
+### Material repeats the slide title
+
+If the outer slide title says the concept, the inserted SVG or Remotion clip should not repeat the same large title. Keep only metadata, process nodes, diagrams, or proof inside the material.
+
+### Over-empty statement pages
+
+Swiss whitespace is useful, but a statement page can look unfinished when it carries only one sentence and no structural anchor. Add a compact right-side stack, comparison, or supporting proof when the slide needs to be taught rather than merely declared.
+
+### Image generation with Chinese text
+
+GPT image generation can be useful for visual concepts, but exact Chinese labels are fragile. Prefer SVG/HTML for Chinese system diagrams, flow charts, and QA-sensitive labels. Use GPT images for non-textual visual support unless the user explicitly accepts text risk.
+
+## Manifest Pattern
+
+For materialized guizang runs, write a small manifest:
+
+```json
+{
+  "source_workflow": "Humanize PPT AST contract -> guizang-ppt-skill deck -> material production pass",
+  "style": "Swiss Internationalism / IKB",
+  "assets": [
+    {
+      "slide": 3,
+      "file": "ppt/videos/03-entry-loop.mp4",
+      "type": "remotion-process-video",
+      "slot": "remotion-entry-loop-16x9",
+      "purpose": "Explain the entry loop without repeating the slide title"
+    },
+    {
+      "slide": 6,
+      "file": "ppt/images/06-context-system.svg",
+      "type": "deterministic-svg-diagram",
+      "slot": "s14-context-21x9",
+      "purpose": "Show how project/task/personal context enters Hermes"
+    }
+  ]
+}
+```
+
+Keep generated run artifacts out of the public repo unless they are curated demo assets.

registry/renderer_registry.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.0",
+  "version": "0.6.1",
   "renderers": [
     {
       "id": "guizang",

scripts/humanize_ppt_v2.py

@@ -11,7 +11,7 @@
 
 SKILL_ROOT = Path(__file__).resolve().parents[1]
 REGISTRY_PATH = SKILL_ROOT / "registry" / "renderer_registry.json"
-VERSION = "0.6.0"
+VERSION = "0.6.1"
 BEAUTIFUL_REPO_URL = "https://github.com/zarazhangrui/beautiful-html-templates.git"
 
 ROLE_ARC = [

tests/test_version_metadata.py

@@ -4,14 +4,14 @@
 
 
 ROOT = Path(__file__).resolve().parents[1]
-EXPECTED_VERSION = "0.6.0"
+EXPECTED_VERSION = "0.6.1"
 
 
 def test_release_version_metadata_is_consistent():
     skill = (ROOT / "SKILL.md").read_text(encoding="utf-8")
     script = (ROOT / "scripts" / "humanize_ppt_v2.py").read_text(encoding="utf-8")
     registry = json.loads((ROOT / "registry" / "renderer_registry.json").read_text(encoding="utf-8"))
 
-    assert re.search(r"^version: 0\.6\.0$", skill, re.MULTILINE)
+    assert re.search(r"^version: 0\.6\.1$", skill, re.MULTILINE)
     assert f'VERSION = "{EXPECTED_VERSION}"' in script
     assert registry["version"] == EXPECTED_VERSION