html-slideshow 是做什么的？
一个响应式幻灯片，打包成一个自包含、最小化的 .html。
用 HTML 编写幻灯片；引擎（assets/base.css + base.js）以及 Bun 构建
生成最终文件。需要 Bun。
工作流程
- 检查运行时 —
bun --version（如果缺失，从 bun.sh 安装；已验证版本 1.4.0）。 - 复制模板 — 将
assets/base.html、assets/base.css和assets/base.js复制到用户工作区的一个幻灯片文件夹中（并列放置）。.html文件可以自由重命名（例如my-deck.html）；base.css和base.js由.html通过相对路径引用，因此重命名它们需要更新这些引用。 - 设置标题 — 在
.html中，编辑<title>。默认情况下幻灯片渲染为深色主题；打印时会自动切换到强制浅色调色板。 - 添加幻灯片 — 在
<main id="deck">中，每个幻灯片使用一个<section class="slide">：<section class="slide"> <h2>季度业绩</h2> <ul><li>收入增长 24%</li></ul> </section> - 自定义 CSS/JS — 仅链接文件，绝不内联。 请不要在
.html中添加<style>或<script>块——它只包含页面骨架和幻灯片内容；构建过程会将链接的文件内联到最终的自包含文件中，从而保持源文件可编辑且引擎单源。自定义代码有两个合法位置：直接编辑base.css/base.js，或者——为了从引擎中隔离幻灯片特定的样式/行为——添加<link rel="stylesheet" href="extra.css">/<script src="extra.js" defer></script>（构建过程会将它们内联；尽可能保持base.*不变——请参阅references/bundling-assets.md）。（references/slide-patterns.md中的配方遵循此原则。） - 使用容器单位进行尺寸设置——永远不要用
px。 每个幻灯片都是一个 CSS 查询容器，因此请使用cqw/cqh/cqmin和clamp()，内容会适应任何屏幕。px/pt会破坏响应式——不要使用它们（外部框架使用svh）。这是智能体最容易犯的一个规则；完整指南见references/responsive-units.md。 竖屏视口已为你处理：幻灯片以其横屏画布渲染并缩放以适应，因此宽表格/网格永远不会溢出手机屏幕（:root上的--slide-w/--slide-h，默认为16/9）。 - 构建 — 运行技能的构建脚本：
bun scripts/build.js my-deck.html（内部调用bun build --compile --target=browser --minify my-deck.html --outdir dist；在 Bun 支持的任何操作系统上运行）→dist/my-deck.html：一个单一、最小化、自包含的文件，其中内联了 CSS、JS 以及任何引用的资源。这是你要分发的文件。 - 验证构建后的文件 在浏览器工具中（使用
file://URL 打开dist/my-deck.html）。通过标准：控件正常渲染；右箭头键将计数器前进到 "2 / N" 并设置location.hash为#2；一个约 400×800 的视口仍然显示一个完全可见的、带信箱效果的幻灯片；O键切换概览；打印媒体模拟生成每页一张幻灯片。信号详细说明见references/using-the-deck.md。如果无法使用浏览器工具，说明已跳过视觉验证。 - 清理 — 除了构建输出外，不会创建任何其他文件；保留
my-deck.html、base.css和base.js（可编辑的源文件）与dist/my-deck.html（您分发的文件）并列。如果用户只想要单个文件，请将dist/my-deck.html移动到他们期望幻灯片所在的位置，并保留幻灯片文件夹作为其源文件。
参考索引
按需加载——不要一次性全部加载：
references/using-the-deck.md— 设置、幻灯片契约、完整导航、深层链接（#5打开第 5 张幻灯片；#some-id打开持有该 id 的幻灯片；用于引用→来源）、构建和打印。references/slide-patterns.md— 现成的幻灯片配方 + 编写指南。references/responsive-units.md— 无px的流式尺寸指南。references/bundling-assets.md— 内联 SVG / data-URI 资源（构建过程也会内联相对引用）。references/engine-anatomy.md— 引擎（base.html/base.css/base.js）的地图，用于修改它。examples/quickstart.html— 一个填充了内容的幻灯片（源文件；构建它得到自包含文件）。examples/README.md— 示例幻灯片的两种形式（可读源文件 vs 构建后的独立文件）以及如何编辑后重新构建独立文件。
使用时机
当输出应该一次全屏显示一页时：演讲、课程、演示、状态更新或推介。不适用于滚动显示的散文或文档。