wizz-method 1.0.2 → 1.1.0

package/src/skills-lib/huashu-design/references/workflow.md

@@ -0,0 +1,216 @@
+# Workflow：从接到任务到交付
+
+你是用户的junior designer。用户是manager。按这个流程工作，能产出好设计的概率会显著提升。
+
+## 问问题的艺术
+
+大多数情况下，开工前要问至少10个问题。不是走过场，是真的要把需求摸清。
+
+**什么时候必须问**：新任务、模糊任务、没有design context、用户只说了一句模糊的要求。
+
+**什么时候可以不问**：小修小补、follow-up任务、用户已经给了明确PRD+截图+上下文。
+
+**怎么问**：大部分 agent 环境没有结构化问题 UI，在对话里用 markdown 清单问即可。**一次性把问题列完让用户批量答**，不要一来一回一个个问——那会浪费用户时间、打断用户思路。
+
+## 必问清单
+
+每个设计任务都必须问清这5类问题：
+
+### 1. Design Context（最重要）
+
+- 有没有现成的design system、UI kit、组件库？在哪？
+- 有没有品牌指南、色彩规范、字体规范？
+- 有没有可以参考的现有产品/页面截图？
+- 有没有codebase可以读？
+
+**如果用户说"没有"**：
+- 帮他找——翻项目目录、看有没有参考品牌
+- 还没有？明确说："我会基于通用直觉做，但这通常做不出符合你品牌的作品。你考虑下是否先提供一些参考？"
+- 实在要做，就按`references/design-context.md`的fallback策略办
+
+### 2. Variations维度
+
+- 想要几种variations？（推荐3+）
+- 在哪些维度上变？视觉/交互/色彩/布局/文案/动画？
+- 希望variations都"接近预期"还是"一张地图，从保守到疯狂"？
+
+### 3. Fidelity和Scope
+
+- 多高保真？线框图 / 半成品 / 真实data的full hi-fi？
+- 覆盖多少flow？一屏 / 一个flow / 整个产品？
+- 有没有具体的「必须包含」元素？
+
+### 4. Tweaks
+
+- 希望能实时调整哪些参数？（颜色/字号/间距/layout/文案/feature flag）
+- 用户自己要不要在做完后继续调？
+
+### 5. 问题专属（至少4个）
+
+针对具体任务问4+个细节。例如：
+
+**做landing page**：
+- 目标转化动作是什么？
+- 主要受众？
+- 竞品参考？
+- 文案谁提供？
+
+**做iOS App onboarding**：
+- 几步？
+- 需要用户做什么？
+- 跳过路径？
+- 目标留存率？
+
+**做动画**：
+- 时长？
+- 最终用途（视频素材/官网/社交）？
+- 节奏（快/慢/分段）？
+- 必须出现的关键帧？
+
+## 问题模板示例
+
+遇到新任务时，可以抄这个结构在对话里问：
+
+```markdown
+开始前想跟你对齐几个问题，一次列齐你批量回答就行：
+
+**Design Context**
+1. 有设计系统/UI kit/品牌规范吗？如果有在哪？
+2. 有可以参考的现有产品或竞品截图吗？
+3. 项目里有codebase可以读吗？
+
+**Variations**
+4. 想要几种variations？在哪些维度上变（视觉/交互/色彩/...）？
+5. 希望都是"接近答案"还是从保守到疯狂的一张地图？
+
+**Fidelity**
+6. 保真度：线框 / 半成品 / 带真数据full hi-fi？
+7. Scope：一屏 / 一整个flow / 整个产品？
+
+**Tweaks**
+8. 希望做完后能实时调哪些参数？
+
+**具体任务**
+9. [任务专属问题1]
+10. [任务专属问题2]
+...
+```
+
+## Junior Designer模式
+
+这是整个workflow最重要的环节。**不要接到任务就闷头冲**。步骤：
+
+### Pass 1：Assumptions + Placeholders（5-15分钟）
+
+HTML文件头部先写你的**assumptions+reasoning comments**，像junior给manager汇报：
+
+```html
+<!--
+我的假设：
+- 这是给XX受众看的
+- 整体tone我理解为XX（基于用户说的"专业但不严肃"）
+- 主要flow是A→B→C
+- 色彩我想用品牌蓝+暖灰，不确定你想不想要accent色
+
+未解的问题：
+- 第3步的数据从哪里来？先用placeholder
+- 背景图用抽象几何还是真照片？先占位
+
+如果你看到这里觉得方向不对，现在是成本最低的时候改。
+-->
+
+<!-- 然后是带placeholder的结构 -->
+<section class="hero">
+  <h1>[主标题位 - 等用户提供]</h1>
+  <p>[副标题位]</p>
+  <div class="cta-placeholder">[CTA按钮]</div>
+</section>
+```
+
+**保存 → show用户 → 等反馈再走下一步**。
+
+### Pass 2：真实组件+Variations（主力工作量）
+
+用户批准方向后，开始填充。这时：
+- 写React组件替换placeholder
+- 做variations（用design_canvas或Tweaks）
+- 如果是幻灯片/动画，用starter components起手
+
+**做到一半再show一次**——不要等全做完。设计方向错了，晚show等于白做。
+
+### Pass 3：细节打磨
+
+用户满意整体后，打磨：
+- 字号/间距/对比度微调
+- 动画timing
+- 边界case
+- Tweaks面板完善
+
+### Pass 4：验证+交付
+
+- 用Playwright截图（见`references/verification.md`）
+- 打开浏览器肉眼确认
+- 总结**极简**：只说caveats和next steps
+
+## Variations的深度逻辑
+
+给variations不是给用户制造选择困难，是**探索可能性空间**。让用户mix and match出最终版本。
+
+### 好的variations长什么样
+
+- **维度明确**：每个variation在不同维度上变（A vs B只换配色，C vs D只换layout）
+- **有梯度**：从「by-the-book保守版」到「大胆novel版」逐级递进
+- **有记号**：每个variation有短label说明它在探索什么
+
+### 实现方式
+
+**纯视觉对比**（静态）：
+→ 用`assets/design_canvas.jsx`，网格布局并排展示。每个cell带label。
+
+**多选项/交互差异**：
+→ 做完整原型，用Tweaks切换。例如做登录页，"布局"是tweak的一个选项：
+- 左文案右表单
+- 顶部logo+中央表单
+- 背景全屏图+浮层表单
+
+用户开关Tweaks就能切换，不需要打开多个HTML文件。
+
+### 探索矩阵思考
+
+每次设计，脑内过一遍这些维度，挑2-3个来给variations：
+
+- 视觉：minimal / editorial / brutalist / organic / futuristic / retro
+- 色彩：monochrome / dual-tone / vibrant / pastel / high-contrast
+- 字型：sans-only / sans+serif对比 / 全衬线 / 等宽
+- Layout：对称 / 非对称 / 不规则grid / full-bleed / 窄栏
+- Density：稀疏呼吸 / 中等 / 信息密集
+- 交互：极简hover / 丰富micro-interaction / 夸张大动画
+- 材质：flat / 有阴影层次 / 纹理 / noise / 渐变
+
+## 遇到不确定的情况
+
+- **不知道怎么做**：坦白说你不确定，问用户，或先做个placeholder继续。**不要编**。
+- **用户的描述矛盾**：指出矛盾，让用户选一个方向。
+- **任务太大一次吃不下**：拆成steps，先做第一步让用户看，再推进。
+- **用户要求的效果技术上很难**：说清技术边界，提供替代方案。
+
+## 总结规则
+
+交付时，summary **极短**：
+
+```markdown
+✅ 幻灯片已完成（10张），带Tweaks可切换"夜/日模式"。
+
+注意：
+- 第4页的数据是假的，等你提供真数据我替换
+- 动画用了CSS transition，不需要JS
+
+下一步建议：先你浏览器打开看一遍，有问题告诉我哪页哪处。
+```
+
+不要：
+- 罗列每一页的内容
+- 重复讲你用了什么技术
+- 夸自己设计多好
+
+Caveats + next steps，结束。

package/src/skills-lib/huashu-design/scripts/add-music.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# Mix a BGM track into an MP4 video.
+#
+# Usage:
+#   bash add-music.sh <input.mp4> [--mood=<name>] [--music=<path>] [--out=<path>]
+#
+# Mood library (in ../assets/, matching bgm-<mood>.mp3):
+#   tech              — Apple Silicon / product keynote vibe, minimal synth+piano (default)
+#   ad                — upbeat modern, clear build + drop, social-media ad energy
+#   educational       — warm, patient, inviting learning tone
+#   educational-alt   — alternate take of educational
+#   tutorial          — lo-fi background, stays out of voiceover's way
+#   tutorial-alt      — alternate take of tutorial
+#
+# Flags (all optional):
+#   --mood=<name>     pick a preset from the library (default: tech)
+#   --music=<path>    override with your own audio file (wins over --mood)
+#   --out=<path>      output path (default: <input-basename>-bgm.mp4)
+#
+# Legacy positional form still works: bash add-music.sh in.mp4 music.mp3 out.mp4
+#
+# Behavior:
+#   - Music is trimmed to match video duration
+#   - 0.3s fade in, 1.0s fade out (avoids hard cuts)
+#   - Video stream copied (no re-encode), audio AAC 192k
+#
+# Examples:
+#   bash add-music.sh my.mp4                              # default: tech mood
+#   bash add-music.sh my.mp4 --mood=ad                    # switch mood
+#   bash add-music.sh my.mp4 --mood=educational --out=final.mp4
+#   bash add-music.sh my.mp4 --music=~/Downloads/song.mp3 # bring your own
+#
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ASSETS_DIR="$SCRIPT_DIR/../assets"
+
+# ── Parse args ───────────────────────────────────────────────────────
+INPUT=""
+MOOD="tech"
+CUSTOM_MUSIC=""
+OUTPUT=""
+POSITIONAL=()
+
+for arg in "$@"; do
+  case "$arg" in
+    --mood=*)  MOOD="${arg#*=}" ;;
+    --music=*) CUSTOM_MUSIC="${arg#*=}" ;;
+    --out=*)   OUTPUT="${arg#*=}" ;;
+    *)         POSITIONAL+=("$arg") ;;
+  esac
+done
+
+# Legacy positional: <input> [music] [output]
+INPUT="${POSITIONAL[0]}"
+[ -z "$CUSTOM_MUSIC" ] && [ -n "${POSITIONAL[1]}" ] && CUSTOM_MUSIC="${POSITIONAL[1]}"
+[ -z "$OUTPUT" ]       && [ -n "${POSITIONAL[2]}" ] && OUTPUT="${POSITIONAL[2]}"
+
+if [ -z "$INPUT" ] || [ ! -f "$INPUT" ]; then
+  echo "Usage: bash add-music.sh <input.mp4> [--mood=<name>] [--music=<path>] [--out=<path>]" >&2
+  echo "Moods available: $(ls "$ASSETS_DIR" | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2
+  exit 1
+fi
+
+# ── Resolve music source: --music wins, else --mood ─────────────────
+if [ -n "$CUSTOM_MUSIC" ]; then
+  MUSIC="$CUSTOM_MUSIC"
+  SOURCE_LABEL="custom: $MUSIC"
+else
+  MUSIC="$ASSETS_DIR/bgm-${MOOD}.mp3"
+  SOURCE_LABEL="mood: $MOOD"
+fi
+
+if [ ! -f "$MUSIC" ]; then
+  echo "✗ Music not found: $MUSIC" >&2
+  echo "  Available moods: $(ls "$ASSETS_DIR" | grep -E '^bgm-.*\.mp3$' | sed 's/^bgm-//;s/\.mp3$//' | tr '\n' ' ')" >&2
+  exit 1
+fi
+
+# ── Resolve output path ─────────────────────────────────────────────
+INPUT_DIR="$(cd "$(dirname "$INPUT")" && pwd)"
+INPUT_NAME="$(basename "$INPUT" .mp4)"
+[ -z "$OUTPUT" ] && OUTPUT="$INPUT_DIR/$INPUT_NAME-bgm.mp4"
+
+# ── Measure video duration, compute fade-out start ──────────────────
+DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "$INPUT")
+if [ -z "$DURATION" ]; then
+  echo "✗ Could not read video duration" >&2
+  exit 1
+fi
+FADE_OUT_START=$(awk "BEGIN { d = $DURATION - 1; if (d < 0) d = 0; print d }")
+
+echo "▸ Mixing BGM into video"
+echo "  input:    $INPUT"
+echo "  music:    $SOURCE_LABEL"
+echo "  duration: ${DURATION}s"
+echo "  output:   $OUTPUT"
+
+ffmpeg -y -loglevel error \
+  -i "$INPUT" \
+  -i "$MUSIC" \
+  -filter_complex "[1:a]atrim=0:${DURATION},asetpts=PTS-STARTPTS,afade=t=in:st=0:d=0.3,afade=t=out:st=${FADE_OUT_START}:d=1[a]" \
+  -map 0:v -map "[a]" \
+  -c:v copy -c:a aac -b:a 192k -shortest \
+  "$OUTPUT"
+
+SIZE=$(du -h "$OUTPUT" | cut -f1)
+echo "✓ Done: $OUTPUT ($SIZE)"

package/src/skills-lib/huashu-design/scripts/convert-formats.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Convert MP4 animations to 60fps MP4 and optimized GIF.
+#
+# Usage:
+#   ./convert-formats.sh input.mp4 [gif_width] [--minterpolate]
+#
+# Produces next to the input:
+#   <name>-60fps.mp4   (1920x1080, 60fps, frame-duplicated by default)
+#   <name>.gif         (scaled width, 15fps, palette-optimized)
+#
+# Flags:
+#   --minterpolate     Enable motion-compensated interpolation (high quality
+#                      but elementary stream has known QuickTime/Safari
+#                      compat issues — only use if your player handles it).
+#
+# Default 60fps mode: simple `fps=60` filter (frame duplication). Wide
+# compatibility, plays in QuickTime / Safari / Chrome / VLC. The 60fps
+# label is for upload-platform optics; perceived smoothness is identical
+# to the source 25fps for most CSS-driven motion.
+#
+# When to enable --minterpolate: heavy translate/scale motion where you
+# want true 60fps interpolation. WARN: macOS QuickTime sometimes refuses
+# to open minterpolate output. Test before delivering.
+#
+# GIF uses two-pass palette:
+#   pass 1: palettegen with stats_mode=diff (per-video optimal palette)
+#   pass 2: paletteuse with bayer dither + rectangle diff
+# This keeps 30s/1080p animations GIF under ~4MB with good color fidelity.
+
+set -e
+
+INPUT=""
+GIF_WIDTH="960"
+USE_MINTERPOLATE=0
+for arg in "$@"; do
+  case "$arg" in
+    --minterpolate) USE_MINTERPOLATE=1 ;;
+    --*) echo "Unknown flag: $arg" >&2; exit 1 ;;
+    *)
+      if [ -z "$INPUT" ]; then INPUT="$arg"
+      else GIF_WIDTH="$arg"
+      fi
+      ;;
+  esac
+done
+[ -z "$INPUT" ] && { echo "Usage: $0 input.mp4 [gif_width] [--minterpolate]" >&2; exit 1; }
+
+DIR=$(dirname "$INPUT")
+BASE=$(basename "$INPUT" .mp4)
+OUT60="$DIR/$BASE-60fps.mp4"
+OUTGIF="$DIR/$BASE.gif"
+PAL="$DIR/.palette-$BASE.png"
+
+if [ "$USE_MINTERPOLATE" = "1" ]; then
+  echo "▸ 60fps interpolate (minterpolate, high quality): $OUT60"
+  VFILTER="minterpolate=fps=60:mi_mode=mci:mc_mode=aobmc:me_mode=bidir:vsbmc=1"
+else
+  echo "▸ 60fps frame-duplicate (compat mode): $OUT60"
+  VFILTER="fps=60"
+fi
+
+# -profile:v high -level 4.0 → broad H.264 compatibility (QuickTime, Safari, mobile)
+# -movflags +faststart        → moov atom upfront, streamable / instant-play
+ffmpeg -y -loglevel error -i "$INPUT" \
+  -vf "$VFILTER" \
+  -c:v libx264 -pix_fmt yuv420p -profile:v high -level 4.0 \
+  -crf 18 -preset medium -movflags +faststart \
+  "$OUT60"
+MP4_SIZE=$(du -h "$OUT60" | cut -f1)
+echo "  ✓ $MP4_SIZE"
+
+echo "▸ GIF (${GIF_WIDTH}w, 15fps, palette-optimized): $OUTGIF"
+# Pass 1: generate palette tailored to this video
+ffmpeg -y -loglevel error -i "$INPUT" \
+  -vf "fps=15,scale=${GIF_WIDTH}:-1:flags=lanczos,palettegen=stats_mode=diff" \
+  "$PAL"
+# Pass 2: apply palette with dithering
+ffmpeg -y -loglevel error -i "$INPUT" -i "$PAL" \
+  -lavfi "fps=15,scale=${GIF_WIDTH}:-1:flags=lanczos[x];[x][1:v]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle" \
+  "$OUTGIF"
+rm -f "$PAL"
+GIF_SIZE=$(du -h "$OUTGIF" | cut -f1)
+echo "  ✓ $GIF_SIZE"

package/src/skills-lib/huashu-design/scripts/export_deck_pdf.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * export_deck_pdf.mjs — 把多文件 slide deck 导出为单个矢量 PDF
+ *
+ * 用法：
+ *   node export_deck_pdf.mjs --slides <dir> --out <file.pdf> [--width 1920] [--height 1080]
+ *
+ * 特点：
+ *   - 文字保留矢量（可复制、可搜索）
+ *   - 背景/图形 1:1 保真（Playwright 内嵌 Chromium 渲染）
+ *   - 不需要对 HTML 做任何改造
+ *   - 视觉损失 = 0（PDF 就是浏览器打印出来的）
+ *
+ * trade-off：
+ *   - PDF 不可再编辑文字（要改回到 HTML 改）
+ *
+ * 依赖：playwright pdf-lib
+ *   npm install playwright pdf-lib
+ *
+ * 会按文件名排序（01-xxx.html → 02-xxx.html → ...）
+ */
+
+import { chromium } from 'playwright';
+import { PDFDocument } from 'pdf-lib';
+import fs from 'fs/promises';
+import path from 'path';
+
+function parseArgs() {
+  const args = { width: 1920, height: 1080 };
+  const a = process.argv.slice(2);
+  for (let i = 0; i < a.length; i += 2) {
+    const k = a[i].replace(/^--/, '');
+    args[k] = a[i + 1];
+  }
+  if (!args.slides || !args.out) {
+    console.error('用法: node export_deck_pdf.mjs --slides <dir> --out <file.pdf> [--width 1920] [--height 1080]');
+    process.exit(1);
+  }
+  args.width = parseInt(args.width);
+  args.height = parseInt(args.height);
+  return args;
+}
+
+async function main() {
+  const { slides, out, width, height } = parseArgs();
+  const slidesDir = path.resolve(slides);
+  const outFile = path.resolve(out);
+
+  const files = (await fs.readdir(slidesDir))
+    .filter(f => f.endsWith('.html'))
+    .sort();
+  if (!files.length) {
+    console.error(`No .html files found in ${slidesDir}`);
+    process.exit(1);
+  }
+  console.log(`Found ${files.length} slides in ${slidesDir}`);
+
+  const browser = await chromium.launch();
+  const ctx = await browser.newContext({ viewport: { width, height } });
+
+  // 1) Render each HTML to its own PDF buffer
+  const pageBuffers = [];
+  for (const f of files) {
+    const page = await ctx.newPage();
+    const url = 'file://' + path.join(slidesDir, f);
+    await page.goto(url, { waitUntil: 'networkidle' }).catch(() => page.goto(url));
+    await page.waitForTimeout(1200);  // web-font paint
+    // emulate "screen" so CSS colors/backgrounds render the same as browser
+    await page.emulateMedia({ media: 'screen' });
+    const buf = await page.pdf({
+      width: `${width}px`,
+      height: `${height}px`,
+      printBackground: true,
+      margin: { top: 0, right: 0, bottom: 0, left: 0 },
+      preferCSSPageSize: false,
+    });
+    pageBuffers.push(buf);
+    await page.close();
+    console.log(`  [${pageBuffers.length}/${files.length}] ${f}`);
+  }
+
+  await browser.close();
+
+  // 2) Merge into a single PDF
+  const merged = await PDFDocument.create();
+  for (const buf of pageBuffers) {
+    const src = await PDFDocument.load(buf);
+    const copied = await merged.copyPages(src, src.getPageIndices());
+    copied.forEach(p => merged.addPage(p));
+  }
+  const bytes = await merged.save();
+  await fs.writeFile(outFile, bytes);
+
+  const kb = (bytes.byteLength / 1024).toFixed(0);
+  console.log(`\n✓ Wrote ${outFile}  (${kb} KB, ${files.length} pages, vector)`);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/src/skills-lib/huashu-design/scripts/export_deck_pptx.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * export_deck_pptx.mjs — 把多文件 slide deck 导出为可编辑 PPTX
+ *
+ * 用法：
+ *   node export_deck_pptx.mjs --slides <dir> --out <file.pptx>
+ *
+ * 行为：
+ *   - 调用 scripts/html2pptx.js 把 HTML DOM 逐元素翻译成 PowerPoint 原生对象
+ *   - 文字是真文本框，PPT 里直接双击能编辑
+ *   - body 尺寸 960pt × 540pt（LAYOUT_WIDE，13.333″ × 7.5″）
+ *
+ * ⚠️ HTML 必须符合 4 条硬约束（见 references/editable-pptx.md）：
+ *   1. 文字包在 <p>/<h1>-<h6> 里（div 不能直接放文字）
+ *   2. 不用 CSS 渐变
+ *   3. <p>/<h*> 不能有 background/border/shadow（放外层 div）
+ *   4. div 不能 background-image（用 <img>）
+ *
+ * 视觉驱动的 HTML 几乎无法 pass —— 必须从写 HTML 的第一行就按约束写。
+ * 视觉自由度优先的场景（动画、web component、CSS 渐变、复杂 SVG）
+ * 应改用 export_deck_pdf.mjs / export_deck_stage_pdf.mjs 导出 PDF。
+ *
+ * 依赖：npm install playwright pptxgenjs sharp
+ *
+ * 按文件名排序（01-xxx.html → 02-xxx.html → ...）。
+ */
+
+import pptxgen from 'pptxgenjs';
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function parseArgs() {
+  const args = {};
+  const a = process.argv.slice(2);
+  for (let i = 0; i < a.length; i += 2) {
+    const k = a[i].replace(/^--/, '');
+    args[k] = a[i + 1];
+  }
+  if (!args.slides || !args.out) {
+    console.error('用法: node export_deck_pptx.mjs --slides <dir> --out <file.pptx>');
+    console.error('');
+    console.error('⚠️ HTML 必须符合 4 条硬约束（见 references/editable-pptx.md）。');
+    console.error('   视觉自由度优先的场景请改用 export_deck_pdf.mjs 导出 PDF。');
+    process.exit(1);
+  }
+  return args;
+}
+
+async function main() {
+  const { slides, out } = parseArgs();
+  const slidesDir = path.resolve(slides);
+  const outFile = path.resolve(out);
+
+  const files = (await fs.readdir(slidesDir))
+    .filter(f => f.endsWith('.html'))
+    .sort();
+  if (!files.length) {
+    console.error(`No .html files found in ${slidesDir}`);
+    process.exit(1);
+  }
+
+  console.log(`Converting ${files.length} slides via html2pptx...`);
+
+  const { createRequire } = await import('module');
+  const require = createRequire(import.meta.url);
+  let html2pptx;
+  try {
+    html2pptx = require(path.join(__dirname, 'html2pptx.js'));
+  } catch (e) {
+    console.error(`✗ 加载 html2pptx.js 失败：${e.message}`);
+    console.error(`  依赖缺失时请跑：npm install playwright pptxgenjs sharp`);
+    process.exit(1);
+  }
+
+  const pres = new pptxgen();
+  pres.layout = 'LAYOUT_WIDE';  // 13.333 × 7.5 inch，对应 HTML body 960 × 540 pt
+
+  const errors = [];
+  for (let i = 0; i < files.length; i++) {
+    const f = files[i];
+    const fullPath = path.join(slidesDir, f);
+    try {
+      await html2pptx(fullPath, pres);
+      console.log(`  [${i + 1}/${files.length}] ${f} ✓`);
+    } catch (e) {
+      console.error(`  [${i + 1}/${files.length}] ${f} ✗  ${e.message}`);
+      errors.push({ file: f, error: e.message });
+    }
+  }
+
+  if (errors.length) {
+    console.error(`\n⚠️ ${errors.length} 张 slide 转换失败。常见原因：HTML 不符合 4 条硬约束。`);
+    console.error(`  详见 references/editable-pptx.md 的「常见错误速查」。`);
+    if (errors.length === files.length) {
+      console.error(`✗ 全部失败，不生成 PPTX。`);
+      process.exit(1);
+    }
+  }
+
+  await pres.writeFile({ fileName: outFile });
+  console.log(`\n✓ Wrote ${outFile}  (${files.length - errors.length}/${files.length} slides, 可编辑 PPTX)`);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });