How-it-works 网站
生成一个无依赖的幻灯片，放在 site/ 目录下，该幻灯片从为什么这个角度出发，一直深入到代码层面，解释代码库的运作原理，并包含反映项目真实逻辑的交互式演示，同时提供一个 CI 任务来发布该网站。参考实现：https://mveplus.github.io/onair-led-sign-firmware/ （19 张幻灯片，4 个模拟；源代码位于 https://github.com/mveplus/onair-led-sign-firmware/tree/main/site）。
本技能 templates/ 目录中的模板：
| 文件 | 复制到 | 用途 |
|---|---|---|
index.html | site/index.html | 页面框架 + 可克隆的幻灯片模式 |
deck.css | site/deck.css | 主题令牌、布局、组件 |
deck.js | site/deck.js | 导航、概览、哈希路由、帧循环、步进器辅助 |
app.js | site/app.js | 项目演示的启动器（步进器接线、帧钩子） |
github-pages.yml | .github/workflows/pages.yml | GitHub Pages 部署 |
gitlab-ci.yml | 合并到 .gitlab-ci.yml | GitLab Pages 部署 |
项目特定的演示代码放在 site/app.js 中（样式放在可选的 site/app.css 中）；保持 deck.js 和 deck.css 的通用性。
流程
1. 构建前先询问（一次 AskUserQuestion 调用）
首先运行 git remote -v 以便托管问题能反映实际情况。如果远程是 GitHub 而用户说 GitLab（或相反），请询问用户。最多问四个问题：
- 托管： GitHub Pages、GitLab Pages 或两者都选。
- 受众/深度： 混合型（先讲想法，再深入探讨；默认选项）、开发者或非开发者。
- 交互式演示： 提供 3-4 个针对此项目的候选方案，通过快速浏览找到（状态机、时序/阈值逻辑、请求流、数学或公式、配置构建器）。多选。
- 可选：如果仓库有建议，可以询问语言或品牌限制。
2. 正确读取代码
读取入口点、主要模块、README/文档和 CI 文件。对于幻灯片将要做的每一个声明（超时、阈值、默认值、主题、端点、重置清除的内容），都要从代码中获取，而不是从 README 中获取。保留一份文档与代码的差异以及死胡同（例如，某个 CI 任务的使用者不存在）的列表。在幻灯片上展示代码的真实行为，并在最后向用户报告该列表。不要悄悄地“修正”幻灯片以使其与文档匹配。
3. 大纲（约 12-20 张幻灯片），按章节分组
典型流程：标题（带有一个有趣的交互元素）→ 想法/问题 → 全局图景（可点击的架构）→ 请求/数据流（动画步进器）→ 每个主要组件一张幻灯片 → 弹性/故障处理 → 安全/秘密 → 构建、CI、交付 → 设计原则回顾（带链接）。每张幻灯片都需要一个 data-chapter 和一个 data-title。
4. 构建
- 复制模板并在
index.html中克隆幻灯片模式（英雄、两列带卡片、步进器、信息网格）。 - 模拟复用项目实际算法：移植该函数（整数数学、阈值、排序）并在幻灯片上引用其名称。只有看起来正确的模拟是一个 bug。
- 使用
Deck.onFrame(slideId, fn)进行动画，这样只有可见的幻灯片才会动画化。使用Deck.stepper(...)进行点击浏览序列。 - 图表：使用 CSS 令牌的内联 SVG；不依赖外部内容。没有 CDN，也没有需要获取的字体，这样网站可以离线运行，也能在锁定严格的 Pages 上工作。
- 图片：将它们复制到
site/img/中，调整大小并删除元数据（使用 ImageMagick：magick in -auto-orient -strip -resize 1200x -quality 80 out.jpg）。检查仓库原始图片的 GPS EXIF（例如identify -format '%[EXIF:GPSLatitude]'或exiftool -gps:all），如果发现，则警告用户。手机照片通常携带拍摄地点的位置信息。一旦推送，它们就会进入 git 历史记录，因此删除它们需要进行历史重写，这由用户决定。
5. 发布接线
- GitHub：复制
github-pages.yml。必须启用 Pages，并将源设置为 Actions（设置 → Pages），或者使用下面的命令。将用户要复制的命令放在代码块中，后面不跟任何内容。一个句子的句点如果一起被复制，就会成为参数的一部分 (build_type=workflow.)，导致 API 拒绝：
它只从默认分支部署。gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow - GitLab：将
pages任务合并到任何现有的.gitlab-ci.yml中；不要覆盖它。Pages 会自动启用；URL 显示在“部署”→ “Pages”下。 - 在 README 的概述/“How it works”部分添加一个简短的链接段落。
6. 报告前验证
node --check site/*.js- 使用
python3 -m http.server 8765 --bind 127.0.0.1 --directory site（在后台）提供服务。如果浏览器自动化工具可用（例如 Claude 在 Chrome 中），打开网站，截取每个章节的屏幕截图，并通过在页面中运行 JavaScript（.click()、分发的 PointerEvents）来驱动每个演示，而不是通过点击坐标：屏幕截图通常相对于 CSS 像素进行缩放，因此坐标点击会错过目标。如果窗口无法调整大小，可以通过在 380 像素的 iframe 中加载网站并查找getBoundingClientRect().right > 381的元素来检查手机宽度。 - 如果没有浏览器工具，则告诉用户需要手动检查哪些页面和演示。不要将网站报告为已测试。
- 关闭您打开的任何标签页，之后停止服务器。
7. 交付
在提交或推送前先询问。然后，在一个分支上：为网站创建一个提交，为用户要求的任何代码修复创建单独的提交。报告：已构建的内容、如何启用 Pages、差异列表以及任何未测试的内容（例如硬件）。
样式规则
- 默认为深色主题（令牌在
deck.css中），带有一个红色强调色，您可以通过--accent为每个项目重新着色。 - 平实、具体的文案。解释为什么存在某个设计选择，而不仅仅是它做什么。
- 代码摘录简短且真实（从源代码中裁剪，并带有命名文件的注释）。
- 键盘：←/→/Space/PageUp/PageDown/Home/End，
O用于概览，Esc用于关闭。触摸滑动。每张幻灯片都有自己的 URL（#/slide-id）。