viz-deck: 讲演级可视化 · 五模产出 + 六项增强

为客户演示、投资人路演、团队 keynote、客户原型评审、对外宣传视频、可编辑 PPT 交付提供五种产出，共享一套视觉语言。v2 通过 huashu-design 获得 HTML→MP4/PPTX 导出、20 哲学、5 维评审；v3 新增 ppt-master 桥接（真正可编辑 native DrawingML PPTX、母版继承、TTS 旁白）。v4 取长补短自 26 个开源 PPT skill：Speaker Mode（html-ppt-skill）/ Show-Don't-Tell 三变体（frontend-slides）/ Doc→Deck（odin-slides + colloquium）/ Academic Talk（academic-pptx-skill）/ Bento Grid（apple-bento-grid）/ Reflective Loop（PPTAgent）。

五种产出模式

v1 / v2 用户：原 4 个模式完全保持不变。v3 只是在并列位置新增模式 5，独立 JSON 输入，独立产出可编辑 PPTX，对其他模式零影响。

模式 3 vs 模式 5 选哪个？

与 biz-html-viz 的边界

同一项目可两个 skill 各出一份：决策版用 biz-html-viz 打印归档，讲演版用 viz-deck 上台展示。

工作流程

Step 1 — 强制读 design-system-deck

references/design-system-deck.md 定义了所有模板共享的 CSS 变量、组件库、动画规则、视觉禁令。未读直接写 = 视觉不一致。

Step 2 — 识别用户意图，选模式

按上表关键词判断走哪个模式。含混不清时主动确认（"这是要 60 分钟讲演稿还是分页 PPT 还是动画视频？"），不要默认。

Step 3 — 询问哲学方向（v2 / v2.1 升级）

情况 A：用户明确指定哲学（"用 Kenya Hara 风" / "用 18"）→ 直接读 references/design-philosophies.md 对应条目。

情况 B：用户上传参考图 / brand URL → 进顾问模式（同 v2）。

情况 C（v2.1 新增）：用户含混表达（"高级一点"、"专业一点"、"做个 keynote 给 board 看"）→ 跑 Show-Don't-Tell 三变体预览：

node ~/.claude/skills/viz-deck/scripts/preview-shotgun.mjs \
  --topic "项目主题" \
  --scene "investor-pitch" \   # 或 product-launch / tech-deepdive / academic / default
  --output ./previews/
# 浏览器打开 ./previews/preview-board.html → 用户点 PICK 按钮选向 → 拿到 slug 写进生成参数

灵感来自 frontend-slides（17.5k Star）的 "show, don't tell" — 用户描述不清楚自己想要的视觉风格，但看到 3 张缩略图却能一眼分辨。

情况 D：用户没说也没上传 → 用 viz-deck 默认深空风。不要为了用而用 20 哲学。

Step 4 — 按模式执行

模式 1（keynote-report）

Competitive-Landscape 必须先调研——读 references/research-playbook.md，严禁仅凭训练数据写竞品对比。

学术模式必读：references/academic-mode.md。强制 action title（"市场翻倍" 而非"市场分析"）+ 引用规范 + Q&A 页 + Limitations。灵感来自 academic-pptx-skill。

模式 2（prototype）

读 references/prototype-mode.md → 复制 templates/prototype-shell.html → 选设备外壳（iOS / Android / macOS / browser）→ 填 AppPhone 状态 → 真实素材（Wikimedia / Met / Unsplash）→ Playwright 点击测试。

模式 3（slide-deck）+ v4 Speaker Mode

读 references/slide-mode.md → 复制 templates/slide-deck.html → 章节 3-5 / 总页 12-25 / 单页 ≤ 60 字 → 写 Speaker Notes → 用 scripts/export-pptx.sh 出可编辑 PPTX。

v4 Speaker Mode（灵感来自 html-ppt-skill）：

• slide-deck.html 旁边自动放 speaker-window.html
• 按 S 弹出独立演讲者窗口，4 张磁吸卡片（CURRENT / NEXT / SPEAKER NOTES / TIMER）
• BroadcastChannel 双窗同步翻页
• 三档 LAYOUT 预设：GRID（2×2）/ PROMPTER（提词器占 70%）/ DUO（双屏对比）
• TIMER 有 elapsed / countdown 双模式，> 90% 黄色警告
• URL 加 ?present=true 自动开演讲者窗口

模式 4（motion-stage）

读 references/motion-mode.md → 复制 templates/motion-stage.html → 8s 内完成完整运动叙事 → 用 scripts/export-mp4.sh 出 25fps+60fps+GIF 三件套 → 可选 BGM/voiceover。

模式 5（pptx-deck · v3 真正可编辑 PPTX）

读 references/pptx-master-bridge.md → 复制 templates/pptx-deck-spec.example.json → 改字段（每页 layout + 数据）→ 跑 scripts/export-editable-pptx.sh deck.json --theme deep-space --anim fade --trans fade。

支持 9 个布局（v4 新增 bento-grid）：title-cover、agenda、section-divider、title-bullets、two-column、kpi-grid、pullquote、bento-grid、closing。

主题 3 选 1：deep-space（viz-deck 默认）、terminal（给 biz-decision-stack 用）、deck-light（公司模板友好）。

v4 新增前置工具：Doc→Deck

如果用户已经写好了一份长报告（.md/.docx/.pdf），不需要手写 JSON：

# .md 直接转
node ~/.claude/skills/viz-deck/scripts/doc-to-spec.mjs \
  --input report.md --output deck.json \
  --theme deep-space --max-slides 25 --target-min 30

# .docx 先 pandoc
pandoc report.docx -o report.md --wrap=none
node ~/.claude/skills/viz-deck/scripts/doc-to-spec.mjs --input report.md --output deck.json

详细见 references/doc-to-deck.md。灵感来自 odin-slides + colloquium。

要旁白？加 --with-notes 让脚本写 speaker_notes/，再跑 scripts/embed-narration.sh ./<build_dir> --voice zh-CN-XiaoxiaoNeural → 生成 *_narrated.pptx。在 PowerPoint 里走 File → Export → Create a Video 出 MP4，画面+动画+旁白自动对齐。

要继承公司模板？读 references/master-templates.md，跑 register_template.py 提取后再生成。

与模式 3 的边界：模式 3 是 HTML 优先（演讲者自己讲），模式 5 是交付给别人在 PowerPoint 里改。两者不互相替代。

Step 5 — 填充内容

复制选定模板 → 替换所有 {{占位符}} → 输出到用户指定目录或 output/。

文件名格式：

• 模式 1：{YYYY-MM-DD}-{type}-{slug}-deck.html
• 模式 2：{YYYY-MM-DD}-{slug}-prototype.html
• 模式 3：{YYYY-MM-DD}-{slug}-slides.html（+ .pptx / .pdf）
• 模式 4：{YYYY-MM-DD}-{slug}-motion.html（+ .mp4 / -60fps.mp4 / .gif）
• 模式 5：{YYYY-MM-DD}-{slug}-deck.json → {slug}_pptx_build/exports/{slug}.pptx（+ {slug}_narrated.pptx）

Step 6 — 一致性检查

Step 7 —（v2 / v4 可选）5 维评审 + 反思循环

手动 5 维评审（v2）：读 references/critique-5dim.md → 写 scores.json → 跑 scripts/review-5dim.mjs 生成 HTML 评审报告（含雷达图）：

node scripts/review-5dim.mjs --input scores.json --output critique.html

触发场景：用户问"好不好看"、"再优化"、"做对了吗"、"评一下"。

v4 自动反思循环（Reflective Loop）（灵感来自 PPTAgent 4.4k Star）：对模式 5 生成的 spec 自动跑页面级客观评分：

node ~/.claude/skills/viz-deck/scripts/reflect-and-redo.mjs \
  --spec deck.json --output ./reflect-report.html --threshold 7.0 \
  --redo-prompts ./redo.txt

每页评 5 维（D2 视觉层级 / D3 细节执行 / D4 功能性 客观打分；D1 哲学一致性 / D5 创新性 默认 7.0 中性，需 LLM 人工审）。低于 threshold 的页 → 列入 redo-prompts.txt，对用户提议重做。

触发场景：模式 5 生成完后默认跑一次；用户问"质量怎么样"、"还能再优化"。

桥接到 huashu-design（v2 模式 2/3/4 必要）

模式 2-4 都依赖 ~/.claude/skills/huashu-design/。检测：

HUASHU="$HOME/.claude/skills/huashu-design"
test -f "$HUASHU/scripts/render-video.js" || echo "huashu-design not installed"

如果未安装，告诉用户（不要 silent fallback）：

git clone --depth=1 https://github.com/alchaincyf/huashu-design.git ~/.claude/skills/huashu-design
cd ~/.claude/skills/huashu-design && npm install && npx playwright install chromium

详细桥接协议见 references/huashu-bridge.md。

桥接到 ppt-master（v3 模式 5 必要）

模式 5 依赖 ~/.claude/skills/ppt-master/。检测：

PPTM="$HOME/.claude/skills/ppt-master"
test -f "$PPTM/.venv/Scripts/python.exe" -o -f "$PPTM/.venv/bin/python" || echo "ppt-master not installed"

如果未安装，告诉用户（不要 silent fallback）：

git clone --depth=1 https://github.com/hugohe3/ppt-master.git ~/.claude/skills/ppt-master
cd ~/.claude/skills/ppt-master && python -m venv .venv
.venv/Scripts/pip install python-pptx edge-tts svglib reportlab Pillow numpy

详细桥接协议见 references/pptx-master-bridge.md、references/editable-pptx.md、references/master-templates.md、references/narration-pptx.md。

内容质量规则

• 每章 lead 一句话定调——讲演节奏感来源
• 主视觉一份报告只一个——orbit / canvas / SVG knowledge graph 选一种
• 章节数控制 5-8 章（模式 1）/ 总页 12-25（模式 3）——少了没分量，多了观众累
• 每章 250-600 字（模式 1）——讲演不是论文
• 所有数字用真值——估值标 [ESTIMATED]，缺失标 [N/A]，严禁编造
• 竞品评价用对方的话——不要用本项目术语去框对方

文件结构（v4）

viz-deck/
├── SKILL.md                          这份
├── references/
│   ├── design-system-deck.md         视觉规范（必读）
│   ├── research-playbook.md          竞品调研三档协议
│   ├── academic-mode.md              v4 · 学术报告 action title + 引用规范
│   ├── doc-to-deck.md                v4 · 长文档转 deck 协议
│   ├── huashu-bridge.md              v2 · 桥接 huashu-design 的协议
│   ├── design-philosophies.md        v2 · 20 哲学的 viz-deck 适配
│   ├── critique-5dim.md              v2 · 5 维评审协议
│   ├── prototype-mode.md             v2 · 高保真原型协议
│   ├── slide-mode.md                 v2 · 幻灯片 + PPTX 导出协议
│   ├── motion-mode.md                v2 · 动画 + MP4 导出协议
│   ├── pptx-master-bridge.md         v3 · 桥接 ppt-master 的协议
│   ├── editable-pptx.md              v3 · PPTX 里哪些能点哪些不能
│   ├── master-templates.md           v3 · 母版/模板继承工作流
│   └── narration-pptx.md             v3 · TTS 旁白 + MP4 导出
├── templates/
│   ├── stage-report.html             阶段报告（v1）
│   ├── architecture-deep.html        架构深研（v1）
│   ├── competitive-landscape.html    竞品对比（v1）
│   ├── academic-talk.html            v4 · 学术报告（action title + 引用 + Q&A）
│   ├── bento-layout.html             v4 · Apple bento 卡片单页
│   ├── prototype-shell.html          v2 · 高保真原型骨架
│   ├── slide-deck.html               v2 · 幻灯片骨架（v4 加 Speaker Mode）
│   ├── speaker-window.html           v4 · 演讲者窗口（4 张磁吸卡片）
│   ├── motion-stage.html             v2 · 动画 stage 骨架
│   ├── preview-board.example.html    v4 · Show-Don't-Tell 三变体预览样板
│   └── pptx-deck-spec.example.json   v3 · 可编辑 PPTX 的 JSON spec 范例（v4 加 bento-grid）
└── scripts/
    ├── export-mp4.sh                 v2 · MP4 / 60fps / GIF 导出
    ├── export-pptx.sh                v2 · HTML→快速 PPTX
    ├── review-5dim.mjs               v2 · 5 维评审 HTML 生成器
    ├── make-pptx-deck.mjs            v3 · JSON→SVG→ppt-master 编排（v4 加 bento-grid）
    ├── export-editable-pptx.sh       v3 · 模式 5 入口
    ├── embed-narration.sh            v3 · TTS 旁白嵌入 + 重建 PPTX
    ├── preview-shotgun.mjs           v4 · Show-Don't-Tell 三变体预览
    ├── doc-to-spec.mjs               v4 · Markdown/Word/PDF → pptx-deck spec
    └── reflect-and-redo.mjs          v4 · 页面级反思循环（PPTAgent 派）

反模式

• ❌ 跳过 design-system-deck.md 直接写
• ❌ 4 个模式视觉风格漂移
• ❌ Competitive 模板没做 web_search 就写
• ❌ 章节缺 eyebrow / kicker-num / lead 任一（模式 1）
• ❌ 一份报告塞两种主视觉
• ❌ 用 biz-html-viz 的黑黄配色（那是另一个 skill）
• ❌ 未提供 prefers-reduced-motion 降级
• ❌ 留下未替换的 {{占位符}}
• ❌ 模式 2 不带设备外壳就交付
• ❌ 模式 3 字号 < 20px（投影看不清）
• ❌ 模式 4 录制画布 ≠ 1920×1080 或 一镜超过 12s 无变化
• ❌ 5 维评审任意一项给 10 分（10 留给真"惊艳"产出）
• ❌ 把 huashu 的资源复制进 viz-deck（违反桥接协议）
• ❌ 同一份 deck 混合 2 个哲学（哲学一致性必扣分）

反 AI slop 硬闸 · zima-design 联动

交付前除本 skill 自身规范与反模式清单外，再过一遍下面六条硬闸——蒸馏自 nutlope/hallmark（MIT · Anti-AI-slop design skill， 已收编为本仓库 zima-design 的 anti-slop 引擎）的六大纪律，任何 HTML / deck / 图表产出都适用：

1. 交付前六轴自评 — Philosophy / Hierarchy / Execution / Specificity / Restraint / Variety 各打 1–5 分，任一 < 3 先返工再交付；把分数以注释盖在产物头部 （<!-- zima-design pre-emit critique: P5 H4 E5 S4 R5 V5 -->）。
2. 诚实文案 — 用户没给的指标一律不编：禁止 "+47% conversion"、"50,000+ teams"、 编造的 testimonial / logo 墙 / 案例数；缺数据用 — + 「待确认」灰块占位，或换一种版式。
3. 令牌锁定 — 主题选定后，色值与 font-family 只许引用 :root 令牌 （var(--color-accent) / var(--font-display)）；禁止内联 hex / OKLCH / 裸字体名， 需要新值先入令牌块再引用。
4. 禁手绘假 chrome — 不画假浏览器栏（红黄绿点 + URL 胶囊）、假手机壳、 假代码窗标题栏、假 IDE 窗口；要么真截图包 <figure>（至多发丝描边），要么让内容裸站。
5. 响应式硬底线 — 320 / 375 / 414 / 768px 四档无横向滚动（根上 overflow-x: clip， 不用 hidden）；带图网格轨道用 minmax(0,1fr) 不用裸 1fr；可点击文本（按钮 / 导航 / CTA）不许折成两行；超长词标题加 overflow-wrap: anywhere; min-width: 0。
6. 标题禁斜体 — 标题与 display 字一律 roman（font-style: normal）； 强调用字重 / 强调色 / 下划线承载，斜体只留正文强调。

结构多样性：同一会话连续产出多份同类交付物时，轮换章节节奏与版式骨架—— 两份产出不允许共享同一套「hero → 三卡 → CTA」式模板节奏。

若本机装有 zima-design skill（~/.claude/skills/zima-design/、项目 .claude/skills/zima-design/ 或 .codex/skills/zima-design/），交付前加载其 engines/anti-slop/references/slop-test.md 跑 universal 子集 （视觉 / 排版 / 文案 / 对比度 / a11y / 微交互关卡；报告与 deck 类产出跳过整页宏结构轮换与 .hallmark/log.json 项目记忆关卡）。口味档位与选材 / 文案细则见姊妹层 taste-engine （references/anti-slop-preflight.md）。