用途
soil-html-deck 用于创建 YAML 驱动的 SOIL 交互式 HTML 演示文稿，把演示内容输出为可移植的单文件网页。它是 SOIL Image Deck 的交互超集，沿用相同的 SOIL 教学流程、页面架构、设计系统、受控布局路由、图像简报与 YAML 核心，但用 HTML/CSS/JS 渲染实时文字与交互，而不是生成图片幻灯片。
输出契约
- 生成一个可在浏览器打开的 .html 文件，样式与脚本全部内联。
- 接受的图片以 data:image/...;base64,... 形式嵌入，保证最终文件可便携。
- 标题、段落、标签、卡片、表格、公式、图表、决策节点与控件保持为实时 HTML、SVG、Canvas 或数学标记。
- 仅允许在封面、章节分隔或结尾主图上使用烤制文字。
- 使用内置图像生成能力制作 AI 视觉素材，不用程序化占位符替代请求的 AI 视觉。
- 保留键盘、鼠标与触控导航；包含减少动效行为与无交互降级方案。
共享 SOIL 核心
从 references/soil-deck-core.md 中的渲染器中立字段开始，再用 assets/interactive-spec-template.yaml 中的 HTML 交互与无障碍字段扩展。配置轴包括：
- planning_mode：quick 或 yaml_spec，默认 yaml_spec。
- visual_mode：native、asset、plate 或 hero-only baked。
- interaction_level：none、guided 或 exploratory，默认 guided。
- portability：single_file 或 linked，默认 single_file。
- style_lock：none 或 golden_trio，默认 golden_trio。
使用方式（工作流）
- 概念与流程：确定一个核心大想法、受众目标、常见误解，以及「引起动机 → 维持注意 → 唤起行动」。
- 页面架构：为每页分配一个教学任务、核心要点、学习任务、语义结构、受控布局与简短可见文案。
- YAML 契约：基于 assets/interactive-spec-template.yaml 创建 spec.yaml，在编写 HTML 前锁定设计、响应式、交互、无障碍与验证规则。
- 交互路由：根据语义选择交互，而非装饰；参考 references/interaction-router.md。
- 黄金三页：在构建完整演示前，先确认封面、标准内容页与一个代表性交互页。
- 素材制作：只生成所需图片；实时 HTML 页面优先选择无文字底板与辅助素材。
- HTML 制作：使用 references/html-patterns.md 中的组件与导航模式；保持选定主题，不强制固定暗色科技风。
- 验证：校验 YAML、嵌入素材、运行独立验证器、在浏览器中检查每一页，并测试桌面与窄视口表现。
若已有经过验证的 SOIL Image Deck YAML，可迁移其渲染器中立字段，而不必重新规划；随后补充 learning_task、speaker_only、interaction、accessibility 与响应式布局行为，再验证升级后的规格。
交互策略
- 仅在能澄清比较、顺序、分类、因果、层级、数据、决策、练习或探索时使用交互。
- 8–12 页演示默认安排 2–4 个有意义的交互；仅当学习设计需要时可更多。
- 每页保留一个主要交互。
- 每个交互都需要明确的学习目标、初始状态、键盘/触控控制与静态降级方案。
- 不要把关键教学内容藏在仅悬停可见的行为后面。
- 不把动效当装饰；支持 prefers-reduced-motion。
排版与视觉规则
使用 YAML 设计系统。默认中文展示字体保持粗体、圆润、友好、低棱角。本地可用时优先 jf open 粉圓 2.1、GenSenRounded TW 或 GenJyuuGothic；便携 HTML 可使用声明的圆体网页字体或有记录的系统回退。保持固定外壳与受控变化：标题锚点、色板、材质语言、重复母题、安全区域与进度元素保持一致，同时布局与交互响应内容变化。
命令
校验交互式 YAML：
python .\scripts\validate_interactive_spec.py --spec .\spec.yaml
将生成的素材嵌入最终 HTML 文件：
python .\scripts\embed_assets.py --template .\slides.template.html --output .\slides.html --asset COVER=.\assets\cover.png
验证最终独立演示：
python .\scripts\verify_html.py --html .\slides.html --spec .\spec.yaml --strict-offline
参考文档
- 迁移或编写 YAML 前阅读 references/soil-deck-core.md。
- 分配交互前阅读 references/interaction-router.md。
- 实现 HTML 前阅读 references/html-patterns.md。
- 交付前阅读 references/validation.md。
适用场景与限制
适用于交互式教学演示、课程讲义、产品讲解、需要对比或流程展示的网页演示；要求最终产物为单文件、可离线打开。限制包括：依赖 YAML 规格与配套脚本、需要浏览器端测试；字体本地可用性影响中文圆体效果，不保证所有环境一致；图片需预先接受并内嵌，体积受嵌入素材影响。具体收费、价格与平台支持信息暂未提供。