html-deck-pipeline-skill

name	html-deck-pipeline-skill
description	端到端 HTML 讲稿流水线技能，适用于”上下文过长””分镜拆分””并行生成””风格控制”等超过 10 页的 HTML 演示任务。采用网站骨架输出模式（CSS 三层架构 + hash 路由 + 自适应缩放），支持一键导出 HTML 和 PPTX。强调分镜先行、风格契约、舞台比例可配置（16:9/4:3/16:10/adaptive）、版本递增与样式多样性。

目录结构

html-deck-pipeline-skill/
├─ SKILL.md
├─ README.md
├─ examples/
│  └─ <style-id>/
│     ├─ style-contract-<style-id>.md
│     └─ style-showcase-<style-id>.html
├─ references/                 # 流程规范与参考文档（详见目录内）
├─ templates/
│  ├─ init_topic/
│  ├─ stage-b/
│  │  └─ B-framework-vXX.md
├─ internal-skill/
│  ├─ scrapling-web-fetch/       # 网页抓取与分析（内置）
│  ├─ html-deck-to-pptx/         # PPTX 导出保底方案（Playwright 截图）
│  ├─ web-style-extraction/      # 网页风格提取辅助技能
│  └─ measure-utilization/       # 页面空间利用率检测
├─ container/
│  ├─ index.html
│  ├─ slides-config.json
│  ├─ serve.py
│  ├─ js/
│  │  └─ deck.js
│  └─ css/
│     ├─ config.yaml                # 主题与字号配置
│     ├─ common/                    # 共享 base.css + components.css
│     ├─ fontsize/                  # 字号配置（standard/high-contrast/large）
│     └─ theme/                     # 主题 tokens（dark-theme/dark-theme-2/light-theme/qclaw-theme）
├─ scripts/

当前阶段聚焦创建与优化，不包含安装、测试、打包或发布。

说明：凡由 scripts/ 覆盖的任务均为必须脚本执行项；除非脚本报错，不读取脚本源码。

流水线概览

六阶段流水线，不可越级、不可跳过、每阶段独立门禁：

阶段	名称	核心产出
A：问	需求问询与对齐	目标、受众、页数范围、风格资产、冻结快照
B：架	结构规划与版本初始化	总分总结构、版本号、框架文档、目录就绪
C：镜	分镜与风格应用	全部页面分镜稿（含完整文案、Emoji、样式标注）
D：页	HTML 页面生成与预览	分页 HTML、网站骨架构建、本地预览、自查改进
E：验	验收与发布	导出单文件 HTML/PPTX、用户验收、版本冻结
F：归	归档与经验总结	版本归档、改动清单、经验沉淀

何时启用

触发条件与典型场景请使用：references/09-trigger-matrix.md。

强制约束

工具名兼容说明：本技能中所有 ask_questions 均指代 Claude Code 中的 AskUserQuestion 工具。若目标执行平台的用户交互工具名称不同，请自动映射为平台实际可用的工具名。

• 必须严格按阶段顺序执行：A → B → C → D → E → F；禁止跳过、越级或先做后补。
• 必须先做分镜，再生成 HTML；禁止跳过分镜直接批量写最终页。”先写分镜再补问询””先生成 HTML 再补分镜”均属于失败信号。
• 所有版本必须递增管理（如 v-01、v-02），禁止覆盖旧版。分镜稿、HTML 页面、网站骨架必须使用同一版本号。
• 用户提出修改意见后，必须先更新下一版分镜，再生成下一版 HTML；禁止只改 HTML 不改分镜。
• HTML 修改后必须同步回写分镜稿的”页面完整文案”；分镜文案与 HTML 观众可见文案必须严格一致。分镜稿中的演讲备注、元标注不得进入 HTML。详见 references/03-storyboard-spec.md §2.2.0。
• 分镜稿命名：{part_no:02d}-{part_name}-分镜稿.md。HTML 页面存放：slides/<part_id>/<NN-description>.html，页面清单由 slides-config.json 定义。
• 任一阶段若出现”门禁未过但继续推进”，判定为流程失败，回退到上一个已通过阶段。

风格契约创建模式（按需）

默认流程优先复用已有 style-id，不进入”新建风格契约”流程。

仅当用户显式要求”新建/重写风格契约”时，才加载：

• references/08-style-contract-creation-mode.md
• references/06-style-contract-authoring-guide.md
• references/01-template-pages-standard.md（style-showcase 模板页规范）

若用户要求”参考某个网站的风格”或”从网页中提取设计元素”，同时加载：

• internal-skill/web-style-extraction/SKILL.md（网页风格提取辅助技能）
• internal-skill/scrapling-web-fetch/SKILL.md（网页抓取）

样式多样性要求

样式多样性门槛与页面模式清单详见：references/10-style-diversity-rules.md。

全局交互约定

以下约定适用于所有阶段，各阶段不再逐条重复：

• 🗂️ 交互落盘：每轮结构化交互必须落盘到 {work_dir}/00-input/comms/。文件名格式：{stage_letter}-round{round_no:02d}-{yyyymmdd}.md（单文件包含本轮交互上下文与 AI 结构化总结）。禁止保留 YYYYMMDD 占位文件名。
• ⏸️ 门禁停顿：每阶段完成后，必须使用 ask_questions 暂停，等待用户确认后方可进入下一阶段。未确认前禁止推进。
• 🔁 阶段收口：各阶段收口统一使用 ask_questions 确认进入下一阶段；交互记录按上述规则落盘。

标准流程（分阶段编号）

阶段 A：需求问询与对齐（强制交互）

⚠️ 阶段 A 注意事项（强制）

• 🧭 三个动作 问询 + 确认 + 冻结 缺一不可；未完成阶段 A，不得进入阶段 B/C/D。
• 📐 必须冻结 ratio_mode（默认 16:9，可选 4:3 / 16:10 / adaptive），后续阶段不得中途切换。
• 🎨 必须完成风格资产决策：默认选用已有 style-id；仅当用户显式要求时进入风格契约创建模式（见 references/08-style-contract-creation-mode.md）。
• 🚫 阶段 A 未完成前，禁止初始化目录、写分镜、写 HTML。

🧩 A.0.1 冻结清单（最小必填）

• 阶段 A 冻结快照至少必须包含：目标、受众、页数范围、ratio_mode、风格资产来源、交付格式、时间约束。
• 任一字段缺失时，不得判定阶段 A 完成。

🧭 A.0.2 冲突处理优先级（强制）

• 当新需求与已冻结项冲突时，必须按顺序执行：
  1. 标记冲突项（注明冲突字段与冲突原因）；
  2. 输出影响评估（影响页范围、版本影响、返工成本）；
  3. 使用 ask_questions 获取用户确认后，才允许修改冻结项。
• 未完成上述三步前，禁止隐式改写冻结项。

🧪 A.0.3 缺失信息默认策略

• 对非核心缺失项可采用默认值推进，但必须在“结构化理解总结”中单列“默认采用项清单”。
• 默认采用项必须可追溯（字段名、默认值、采用原因）；用户若否决，必须回退并重冻。

✅ A.0.4 阶段 A DoD（完成定义）

• 同时满足以下条件才可判定阶段 A 完成：
  1. 冻结清单字段完整；
  2. 交互记录已落盘且文件名为真实日期；
  3. 用户明确确认“可进入阶段 B”。

A.1 结构化问询

• 进入 A.1 前，必须先读取：references/04-stage-a-question-card.md。
• 需求收集阶段应尽可能使用 ask_questions 与用户交互，而不是一次性自由提问。
• 首轮问询目标：一次拿到范围、风格、结构、交付边界、工作目录、舞台比例策略（ratio_mode）与并行策略偏好七类信息。
• 首轮问询必须显式确认是否启用 sub-agent 并行加速；默认选项为“不启用”（原因：sub-agent 需要重新加载大量上下文，实际效率未必高于单线程）。
• 首轮问询必须采集“屏幕分辨率（考虑系统缩放后）”信息；至少拿到物理分辨率 + 缩放比例，或浏览器/投屏后的实际可视区尺寸。
• 首轮问询必须显式确认“中间章节组织模式”：总分总（导航-主体-总结/行动） 或 总分（导航-主体）；默认 总分总。
• 固定 checklist 与二轮追问条件详见 references/04-stage-a-question-card.md。

A.1.1 屏幕一致性建议

屏幕适配的三条具体建议详见 references/05-interaction-accessibility-baseline.md §屏幕适配。

A.2 输出理解并等待用户确认（强制附加交互）

• 每轮问询结束后，必须输出“我对需求的结构化理解总结”。
• 总结至少覆盖：目标、范围、结构、风格资产、版本策略、工作目录、边界条件。
• 总结中必须单列“中间章节组织模式（总分总 / 总分）”结论。
• 必须要求用户进行二次确认或补充；未确认前不进入下一步。

A.3 分析并判断是否仍有未明确项

• 对当前反馈做归类：已明确 / 部分明确 / 未明确。
• 满足任一条件即判定“仍有未明确项”：
  • 核心输入缺失（主题、受众、范围、版本号）
  • 工作目录未明确（既无用户指定，也未同意按标准创建）
  • 结构未冻结（总分总中的“分”不清楚）
  • 约束冲突（如页数要求与内容深度冲突）
  • 验收标准不可执行（只有方向，没有检查口径）
  • 风格资产不可执行（未确定选用或新建）

A.4 分支执行：二轮询问或初始化并冻结

• 编号与目录结构详见 references/02-numbering-rules.md。

• 若有未明确项：发起第二轮问询（仅追问未明确项），然后回到 A.2 再次“总结 + 确认”。

• 若无未明确项且用户明确同意进入下一阶段：执行以下收尾动作并冻结需求：

  • 初始化目录必须执行脚本（除非脚本报错，不得手工替代）：

python scripts/init_topic_folder.py \
  --workspace-root "<workspace_root>" \
  --topic-folder "<topic_folder>" \
  --topic-code "<topic_code>" \
  --topic-title "<topic_title>" \
  --version "v-XX" \
  --style-id "<style_id>" \
  --scheme-name "<scheme_name>" \
  --record-date "YYYYMMDD"

• 初始化工作目录（目录结构与编号规则详见 references/02-numbering-rules.md）
  • {work_dir}/00-input/
  • {work_dir}/10-storyboards/v-XX/
  • {work_dir}/20-html/v-XX/
  • {work_dir}/90-tests/
• 落盘沟通记录：按全局交互约定格式，每轮一个 {stage_letter}-round{round_no:02d}-{yyyymmdd}.md。
• 输出并冻结“本轮执行输入快照”（含风格资产路径、工作目录路径、结构冻结结果、ratio_mode）
• 阶段 A 未完成上述收尾，不进入阶段 B。

A.5 阶段收口确认（强制）

按全局交互约定执行，确认”可进入阶段 B”。未确认前只能继续补充 A 阶段材料，不得开始 B 阶段工作。

阶段 B：结构规划与版本初始化

⚠️ 阶段 B 注意事项（强制）

• 📐 阶段 B 必须冻结版本号、总分总结构和章节拆分方案，冻结后不得跨阶段修改。

🧾 B.0.1 版本号与命名规则（强制）

• 阶段 B 必须冻结当前版本号（如 v-01）。
• 分镜稿、HTML 页面、网站骨架必须使用同一版本号；若跨文件出现版本号不一致，判定 B 门禁失败。
• 命名必须遵循编号规则：分镜 {part_no:02d}-{part_name}-分镜稿.md、HTML 页面 slides/<part_id>/<NN-description>.html、网站骨架目录 v-XX/。

📁 B.0.2 目录初始化完成清单（强制）

• 阶段 B 进入分镜前，必须确认以下目录/文件已就绪：
  • {work_dir}/00-input/（含阶段交互记录）
  • {work_dir}/10-storyboards/v-XX/
  • {work_dir}/20-html/v-XX/
  • {work_dir}/90-tests/
  • B-framework-v-XX.md（由模板复制并填充）
• 缺任一项时，不得进入阶段 C。

B.1 总分总框架硬约束

• 大章节拆分补充规则与规模经验值详见 references/11-scope-sizing-and-splitting.md。
• 演示总体结构必须采用”总分总”。
• 开头章节与结尾章节是必需项，且必须独立存在。
• 中间章节的组织方式（例如按模块、按阶段、按问题域）必须在阶段 A 沟通并冻结。
• 若中间章节组织方式未明确，不得进入分镜生成。
• 参考实践：11-组内分享/docs/4.01主题开发 已采用该思路。

B.2 拆分方案产出与确认（含大章节补充规则）

• 必须先产出拆分方案与页数估算，并使用 ask_questions 与用户确认。
• 在 ask_questions 之前，必须先输出”细化到页码级别的规划大纲”（至少包含：页码、所属章节、页面类型、该页核心信息），确保用户有足够信息做决策。
• 用户不认可时必须重拆并再次确认。
• 大章节拆分补充规则、规模经验值与提问模板详见：references/11-scope-sizing-and-splitting.md。

B.3 框架文档落盘（强制）

• 在 B.2 获得用户确认后，必须通过“复制模板 → 编辑填充 → 落盘”完成框架文档。
• 模板路径（固定）：templates/stage-b/B-framework-vXX.md
• 建议路径：{work_dir}/10-storyboards/v-XX/B-framework-v-XX.md。
• 框架文档最低包含：
  • 总分总章节清单
  • 章节边界与页数估算
  • 页码级规划大纲（按章节列出）
  • 并行策略与页面组织顺序
  • 用户确认记录摘要（本轮确认结论）
• 复制模板后必须按本轮实际参数替换占位符（主题、版本、style-id、part 映射等）。
• 不允许跳过模板直接手写框架文档。
• 阶段 B 的交互记录必须落盘为 B-raw... / B-summary...，并作为阶段 C 输入资产。
• 未完成框架文档落盘，不得进入阶段 C。

B.4 版本初始化

• 明确当前版本号，例如 v-01。
• 确保后续分镜、HTML、风格文件使用同一版本号。

B.5 阶段收口确认（强制）

按全局交互约定执行，确认"可进入阶段 C"。

阶段 C：分镜编写

阶段 C 聚焦于内容和结构，不负责视觉风格决策——视觉由主题 CSS 自动渲染。分镜稿描述”页面上有什么、以什么结构组织”。

⚠️ 阶段 C 注意事项（强制）

• 📄 阶段 C 产出分镜稿（内容 + 结构），不产出 HTML。
• 🎨 视觉风格由主题 CSS 自动处理，分镜稿无需描述颜色、字体、阴影等 CSS 细节。

C.1 读取风格资产

• 进入 C.1 前，必须先读取：references/03-storyboard-spec.md 与 references/07-quality-gate-patterns.md。
• 阶段 C 应参考风格描述文件（style-contract-<style-id>.md）和风格展示文件（style-showcase-<style-id>.html），了解可用组件类名与布局模式。
• 阶段 C 不负责新建或修改风格契约。

C.2 分镜编写

• 分镜稿结构与字段规范详见 references/03-storyboard-spec.md。
• 分镜至少包含：页面目标、页面完整文案、演讲备注。
• 页面完整文案必须达到”可直接转成 HTML”的密度，禁止只写 1~2 行口号式占位。
• 每页分镜需标注”页面模式类型”（导航页/对比页/流程页/矩阵页/行动页），用于样式多样性校验。
• 分镜需描述”界面元素布局”：明确表格/卡片/流程/提示框等模块的组织关系和信息分工。
• 对比页至少给出 3~4 组对比项；方法页/流程页至少包含结论标题 + 结构化内容块 + 提示框。
• 行动页至少包含：触发条件、关键动作、验收信号。
• 章节导航页与章节总结页均应保留，每页建议 2~4 个信息块。
• Emoji/符号美化在分镜稿中直接写入并冻结，不在 HTML 阶段再补。
• 分镜稿不需要描述：CSS 颜色值、字体大小 rem 值、阴影参数、圆角像素、渐变方向——这些由主题 CSS 自动处理。
• 分镜稿应标注所使用的 style-id。

C.3 分镜质量门禁

• 执行分镜质量门禁检查，详见 references/07-quality-gate-patterns.md §1。
• 执行样式多样性检查，详见 references/10-style-diversity-rules.md。
• 分镜门禁校验必须执行脚本：

python scripts/validate_storyboards_generic.py \
  --storyboards-dir “<storyboards_dir>” \
  --version “v-XX”

• source-coverage-strike.md 由 AI 生成，并输出覆盖率自评估（默认门禁阈值 70%）。
• 人工审核确认通过后，才允许进入阶段 D。

C.4 阶段收口确认（强制）

按全局交互约定执行，总结分镜状态，确认"可进入阶段 D"。

阶段 D：HTML 页面生成

阶段 D 将分镜稿转化为实际的 HTML 页面，构建网站骨架并启动本地预览，确保 AI 和用户能即时查看渲染效果。

⚠️ 阶段 D 注意事项（强制）

• 📄 一页一文件：每个 HTML 文件只包含一个 <section class=”slide”>。
• 📁 按章节存放：slides/<part_id>/<NN-description>.html。
• 🎨 CSS 由主题自动处理，页面 HTML 不嵌入 <style> 块。

D.1 生成 HTML 页面

• 进入 D.1 前，必须先读取：references/19-website-skeleton-spec.md §8（slide 模板格式）。
• 按分镜逐页生成 HTML 文件，输出到 slides/<part_id>/<NN-description>.html。模板格式见 templates/init_topic/slide_section.html。
• 每个文件只包含一个 <section class=”slide”> 根元素，不含 <html>/<body>/<style>。
• 页面使用 components.css 中已有的组件 class（.panel、.card、.chip、table、.quote-box 等）。
• 页面内容仅保留观众可见信息，演讲备注不进入 HTML。
• 每生成一页 HTML，同步更新 slides-config.json 的 slides 数组（config 中每项含 part、file、title；parts 和 partOrder 在阶段 B 已冻结，D 阶段不修改）。模板格式见 templates/init_topic/slides-config.json。
• 禁止在 HTML 中出现以下标签文本：页面模式类型、背景呈现策略、界面元素布局、示例锚点、执行约束、中间章节组织模式、演讲备注、过渡句。
• 禁止在 HTML 中保留仅供生产流程使用的元属性（如 data-layout）；最终页面仅保留播放必需属性（如 data-index）。
• 若使用 sub-agent 并行生成，派发指令中必须包含并要求优先读取：
  • style-contract-<style-id>.md
  • style-showcase-<style-id>.html
• sub-agent 产出前必须先回传”已读取文件清单”，未回传不得进入构建环节。
• 可使用 sub-agent 并行生成 HTML 页面，但建议一轮最多启用 3 个 sub-agent。
• 并行作业提示词与失败回退流程详见：references/12-parallel-html-generation-playbook.md。
• 键盘/触屏交互与无障碍基线详见 references/05-interaction-accessibility-baseline.md。

D.2 构建网站骨架并本地预览（强制）

• 所有页面 HTML 生成完成后，启动预览以便 AI 和用户查看渲染效果：
  1. 确认 slides/ 就绪：所有页面 HTML 已按 slides/<part>/<NN-desc>.html 放好。
  2. 确认 slides-config.json 完整：title、parts 映射、partOrder、slides 清单均已填入。
  3. 运行启动脚本：python container/serve.py <target_dir> --theme <theme_name>，脚本从 container/ 直接提供骨架文件，同时将 slides-config.json 和 slides/ 路由到目标目录——无需复制任何文件。
• 构建完成后必须执行以下验证：
  • 浏览器打开后首张 slide 正常加载；
  • 键盘导航（ArrowKeys）可正常翻页；
  • 章节导航按钮可正确跳转；
  • Hash 路由正常（#ch0X/XX-slug）；
  • applyAutoScale() 正常触发，无纵向滚动条；
  • “导出 HTML” 和 “导出 PPTX” 按钮可见且可点击；
  • 主题下拉切换正常。
• 验证失败必须回退修正，不得带病进入 D.3。

D.3 自查与改进环节（强制）

• 在 D.2 骨架预览正常运行后，必须执行一次”页面自查回路”。
• D.3 自查重点至少包含：
  • 样式是否美观（视觉层次、对齐、留白、可读性）；
  • 信息密度是否合理（避免”信息过薄”或”单页过载”）；
  • 空白区域是否超标——运行利用率检测脚本量化评估（详见 internal-skill/measure-utilization/SKILL.md）：

    python scripts/measure_utilization.py http://localhost:8080 [--threshold 30]
    

    脚本通过 Playwright 对每页 slide 执行 40×40 网格采样，检测有效内容（文本/背景/边框/图片等）的占比；利用率低于阈值（默认 30%）的页面将被标记为稀疏（sparse），需调整字号/密度/卡片排布。结果同时支持 --json 输出落盘到 90-tests/<version>/。
  • 布局多样性是否达标（避免连续同骨架、主导骨架占比过高）；
  • 背景样式是否统一（全稿背景样式类型不超过 3 种，且章节内保持一致）。
• slide 片段不含 <style>/<script> 标签；components.css 仅含跨章节共享规则。
• 自查必须输出”问题清单（按优先级排序）+ 拟修改方案”。
• 查出问题后，在修改前必须使用 ask_questions 获取用户确认（确认是否修改、先改哪些项、接受的取舍边界）。
• 未获得用户确认前，不得开始修改页面。
• 用户确认后，按确认范围执行修改并复查。
• 自查回路至少执行 1 轮，最多 3 轮；超过 3 轮仍失败，必须暂停并向用户报告阻塞点与备选方案。
• 自查结果建议落盘到 90-tests/<version>/。
• CSS 布局问题排查时，务必检查 inherited display 属性（尤其是 display: grid 对文本宽度的约束），详见 references/21-css-layout-pitfalls.md。
• CSS 修改后需硬刷新浏览器（Ctrl+Shift+R）或用带时间戳的 URL 验证，避免缓存干扰。

D.4 用户反馈与修改

• 自查通过后，使用 ask_questions 提示用户在浏览器中查看完整 deck 效果，收集修改意见。
• 用户在 D.4 可直接提出对页面 HTML 的修改要求；AI 必须先更新对应页面 HTML，再进入下一步确认。
• 当用户提出”增加信息密度”时，允许并建议从原稿中提取相关信息补入 HTML，但必须保持与主题边界和风格约束一致。
• 如果用户反馈涉及某章节需要主题 CSS 之外的额外样式，按需在 v-XX/style/<part_id>.css 中添加章节样式（使用 .part-<part_id> 命名空间，优先使用已有组件和 token 变量）。模板格式见 templates/init_topic/style_part.css。
• D.4 提问建议优先复用：references/18-d4-review-question-card.md。
• HTML 修改后必须同步回写对应分镜稿的文案（同版本、同页面编号），确保”分镜-HTML”一致。

D.5 阶段收口确认（强制）

按全局交互约定执行，确认”可进入阶段 E”。收口仅做确认，不在此环节进行额外修改。

阶段 E：构建验收与发布

阶段 E 聚焦于导出静态文件、用户最终验收与版本冻结。网站骨架已在阶段 D.2 构建并启动，阶段 E 不再重复构建。

⚠️ 阶段 E 注意事项（强制）

• 📦 阶段 E 每次执行即代表一次定版，必须同时产出 HTML 和 PPTX 两个文件。

E.1 导出与定版（强制）

• 网站骨架已在阶段 D.2 构建并验证，E.1 每次执行即代表一次定版，必须同时产出 HTML 和 PPTX 两个文件。
• 导出 HTML（单文件静态）：
  • 点击”导出 HTML”按钮或调用 exportToSingleHTML() 函数；
  • 生成的文件包含：所有 slide 内联、所有 CSS 内联（tokens + base + components）、最小化键盘导航 JS；
  • 导出文件可脱离服务器直接用 file:// 协议打开且功能正常（翻页、进度条、自适应缩放均可用）；
  • 导出文件名格式：{主题}-{版本}.html，落盘到 20-html/v-XX/。
• 导出 PPTX：
  • 优先使用浏览器端导出：点击”导出 PPTX”按钮或调用 exportToPPTX() 函数；
  • 保底方案：若浏览器端导出失败（如跨域限制、内存不足），使用内置 internal-skill/html-deck-to-pptx/ 的 Playwright 截图方案——逐页截图后组装 PPTX，详见该子技能的 SKILL.md。
  • 导出文件名格式：{主题}-{版本}.pptx，落盘到 20-html/v-XX/。
• 导出后必须实际打开 HTML 和 PPTX 文件，验证：
  • 所有页面可正常显示；
  • 键盘翻页正常（HTML）；
  • 无缺失样式或 404 资源请求；
  • 文件体积合理（HTML 通常 < 200KB）。
• 验证失败必须回退到阶段 D 修正，不得跳过。
• 定版后回灌分镜稿（强制）：HTML 和 PPTX 导出验证通过后，必须以本轮 HTML 的实际最终文案为准，一次性批量回写 10-storyboards/v-XX/ 下的对应分镜稿，确保分镜稿文案与定版 HTML 严格一致。

E.2 Preview → Formal 发布（强制）

• E.1 门禁通过后，产物位于 20-html/v-XX/ 目录（含 HTML、PPTX 及全部 slides 源文件）。
• 将导出的 HTML 和 PPTX 文件提供给用户进行最终验收。
• 用户验收通过后，将 20-html/v-XX/ 目录整体作为正式版本冻结。
• 正式版本冻结后，建议至少快检 100% / 125% / 150% 三种缩放下的首屏与章节页。

版本升级（定版后新需求）：定版冻结后若用户提出新想法或修改需求，视为新版本启动：

1. 确定新版本号（如 v-03 → v-04）。
2. 复制 20-html/v-{旧版本}/ 全部内容到 20-html/v-{新版本}/。
3. 复制 10-storyboards/v-{旧版本}/ 全部内容到 10-storyboards/v-{新版本}/。
4. 启动新版本骨架预览：python container/serve.py <新版本target_dir> --theme <theme_name>。
5. 回到阶段 D.4（用户反馈与修改）开始新版本迭代——无需重新执行 D.1~D.3（HTML 已从旧版本复制、骨架已验证、自查已通过）。

E.3 阶段收口确认（强制）

按全局交互约定执行，确认”本轮收口”或”进入阶段 F 归档总结”。未确认前不得私自启动重构或风格重写。

阶段 F：归档与经验总结

F.1 版本归档与经验总结（唯一子步骤）

• F.1 必须完成：
  • 版本资产归档（分镜、HTML、测试报告、关键沟通记录）；
  • 本轮总结（改动清单、验证结果、遗留风险、后续建议）；
  • 经验教训总结（可复用做法 / 失误模式 / 下轮规避建议）；
  • 关键文件路径清单与可追溯记录。
• F.1 完成后，必须使用 ask_questions 询问用户“是否将经验教训回传到技能目录（SKILL.md / references/）”。

执行与验收附录

• 执行清单：references/13-run-checklist.md
• 失败信号与纠偏：references/14-failure-signals-and-recovery.md
• 成功判据：references/15-acceptance-criteria.md
• 交付原则：references/16-delivery-principles.md
• 样式命名规范：references/17-style-namespacing-rules.md
• 网站骨架规范：references/19-website-skeleton-spec.md
• CSS 布局陷阱与调试经验：references/21-css-layout-pitfalls.md