Clickreel 是做什么的？
你正在制作用户真实应用的交互式演示。访客在落地页或通过链接打开它，点击高亮区域，应用的下一个真实屏幕就会出现。他们会在不到一分钟内决定该应用是否值得尝试。一个成功的演示应以 6 到 12 次点击为路径，展示该应用最好的一项功能。
你负责编写分镜脚本并评估结果。Clickreel 负责其余工作：它在无头浏览器中打开应用，真实执行每一步，在操作前后对页面拍照，并将屏幕和播放器打包成一个 HTML 文件。
命令
所有操作都通过一个脚本完成。它只需要机器上已安装的 Node 和一个基于 Chromium 的浏览器。
node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs <command>
如果上面的 ${CLAUDE_SKILL_DIR} 是作为文字出现的，说明你的代理没有填写它：请使用包含此 SKILL.md 的文件夹。
| 命令 | 作用 |
|---|---|
build <storyboard> | 执行步骤，并在分镜脚本旁边写入 <name>.html（演示文件）和 <name>.stops.png（联系表）。需要 10 到 30 秒。 |
check <storyboard> | 执行步骤，但仅将联系表写入临时文件夹。用于在不影响项目的情况下测试分镜脚本。 |
doctor | 检查此机器能否构建演示。如果任何操作无法启动，请先运行此命令。 |
init [file] | 写入一个启动分镜脚本。 |
有用的标志：--out <dir>、--json、--headed（观察浏览器工作）、--force。
工作方式
1. 确定演示内容
一个演示，一个流程。问问自己这个应用最令人信服的功能是什么，并围绕它构建演示。如果用户提到了某个功能或流程，那就是主题。如果他们只说“做个演示”，你自己挑选核心流程（即 README 第一句话所承诺的内容），并说明你选择了哪个。除非应用有多个不相关的产品，否则不要询问用户的选择。
2. 让应用运行起来，并了解其真实标签
找到应用的启动方式（package.json 中的脚本、README、dist/ 文件夹）。然后选择一个：
- 已经运行或你可以自己启动：设置
"url"。 - 静态站点或已构建的文件夹：设置
"serve": "./dist"，Clickreel 会提供它。 - 你想让构建在以后可重复：配合
"url"设置"start": "npm run dev"，Clickreel 会启动它并等待。
步骤通过用户看到的文本来定位元素：按钮文本、字段的标签或占位符、aria-label。阅读你选择的流程所涉及的组件，并精确复制标签。猜测会浪费一次往返。
演示应在值得一看的状态下打开。空的首次运行屏幕或登录墙是糟糕的开端。如果应用需要数据或登录会话，请在第一个停止点之前设置好：使用应用的种子脚本、写入 localStorage 的 eval 步骤，或者在开始时使用测试账户登录。将密码和令牌放在环境变量中，并在分镜脚本中引用为 ${env:NAME}；切勿将真实密钥写入分镜脚本。
3. 编写分镜脚本
将其保存为项目根目录下的 demo.click.json，除非用户要求放在其他地方。如果项目已有 Demoreel 分镜脚本（*.reel.json），你可以直接基于该文件构建。
{
"url": "http://localhost:5173",
"displayUrl": "acme.app",
"demo": {
"title": "Acme",
"intro": "看看一个项目如何从构思变为完成。",
"cta": { "label": "免费试用", "url": "https://acme.app/signup" }
},
"steps": [
{ "say": "几秒内启动一个项目" },
{ "click": "新建项目" },
{ "type": "网站发布", "into": "项目名称" },
{ "click": "创建项目" },
{ "say": "像打字一样快速添加任务" },
{ "type": "撰写公告帖", "into": "添加任务" },
{ "press": "Enter" }
]
}
每个步骤都会成为一个停止点（访客需要执行的操作）或什么都不生成：
| 步骤 | 在演示中 |
|---|---|
{ "click": "新建项目" } | 元素上的一个热点。访客点击它，看到真实结果。 |
{ "type": "hello", "into": "邮箱" } | 字段上的一个热点。点击它会播放正在输入的文本。省略 into 以保持输入在已聚焦的字段中。 |
{ "press": "Enter" } | 可点击的键帽，或者访客按下真实按键。"Mod+K" 在 macOS 上是 Cmd，在其他系统上是 Ctrl。 |
{ "hover": "图表" } | 对悬停做出反应的热点，或在手机上对点击做出反应。 |
{ "select": "专业版", "in": "计划" } | 原生下拉菜单上的热点。 |
{ "say": "一句简短的话" } | 在其后的停止点期间显示的说明文字。它会一直显示，直到下一个 say。后面没有停止点的 say 会变成一张带有“下一步”按钮的卡片。 |
{ "zoom": "总计" } | 一个标注：元素被点亮，页面其余部分变暗，一张卡片显示说明文字和“下一步”按钮。 |
{ "scroll": 600 }、{ "goto": "/settings" }、{ "wait": 800 }、{ "waitFor": "报告就绪" }、{ "eval": "..." } | 没有停止点。演示会自动通过它们。用于设置和到达正确位置。 |
每个热点旁边的文字是为你自动生成的：点击“新建项目”、输入“网站发布”、按下 键帽。在步骤中添加 "hint": "打开设置" 可以用你自己的方式说明。当步骤使用没有可读名称的选择器时（默认会显示“点击这里”），请使用此选项。
目标根据可见名称进行匹配，精确匹配优先。当名称有歧义时，添加 "nth": 2，或使用选择器："css=.sidebar button"、"#save"、"testid=submit"。对可能没有可操作目标的步骤（例如关闭 Cookie 横幅）添加 "optional": true。
完整的步骤、选项、样式和框架列表在 references/storyboard.md 中。在使用这里未显示的内容之前，请先阅读它。
4. 构建
node ${CLAUDE_SKILL_DIR}/scripts/clickreel.mjs build demo.click.json
无法执行的步骤会停止构建，并准确告诉你问题所在：
第 4 步（点击“Creat 项目”）失败：找不到可点击的“Creat 项目”。
您是否指的是：“创建项目”？
当前屏幕上有：“取消”、“创建项目”、“项目名称”
当时页面的截图：/tmp/clickreel/demo-123/step-04-failed.jpg
修复该步骤并重新构建。如果项目已存在一个 Clickreel 未写入的 <name>.html 文件，构建将拒绝替换它：请在分镜脚本中设置 "name" 或传递 --out <dir>。
成功的构建仍然可能会打印提示信息。请阅读它们。提示：第 4 步 (...) 在页面上没有可见变化 意味着该步骤找到了要操作的对象，但页面之后看起来一样：它几乎总是找到了错误的元素，因此它在演示中的停止点毫无作用。修复目标（更精确的名称、nth 或选择器）并重新构建。
5. 在报告结果之前，先检查一下结果
build 会写入一个联系表 <name>.stops.png：每个停止点一张图片，上面绘制了热点，下方标明了步骤和说明文字，最后才是最后一个屏幕。打开它并查看每一张图片。这是你检查自己演示的方式。
检查每张图片：
- 热点。 框是否在你想要的元素上，并且该元素是否在视口中？框指向了错误的东西意味着名称匹配了其他内容：使用
nth或选择器。 - 真实性。 图片是否显示了应用正在正常工作？寻找错误消息、空状态、从未完成的旋转器、占位符文本。每张图片显示的是访客在点击之前看到的内容，因此它后面的图片显示的是他们的点击所实现的效果。
- 说明文字。 图片下方的说明文字是否描述了图片中正在发生的事情？
- 最后一张图片。 它位于结束卡片后面。它应该是应用最美的状态。
修复分镜脚本并重新构建。两到三轮是正常的。当联系表看起来正确时就停止。
6. 交付
告诉用户文件的位置、大小、包含的停止点数量以及它展示的流程。提供 build 打印出的嵌入代码：
<iframe src="demo.html" title="Acme：交互式演示" loading="lazy" allowfullscreen style="width:100%;aspect-ratio:1372/889;border:0;border-radius:12px"></iframe>
简明扼要地说明文件是什么：一个包含其应用截图的 HTML 文件，可从磁盘和任何 Web 主机工作，并且不从网络加载任何内容。报告 Clickreel 打印的任何提示信息（页面错误、被覆盖的元素、大文件）。如果你无法让某个步骤工作并已将其移除，请说明。
GitHub README 不能运行 HTML 文件。对于 README，请链接到托管演示的地方（GitHub Pages 很好地支持 docs/），或使用 Demoreel 的 GIF。
编写好演示的要点
- 六到十二个停止点。 每个停止点都是访客必须执行的一次点击。剪掉设置步骤，或在第一个停止点之前通过
eval完成。 - 说明文字是标题。 七个字或更少，关于收益（"边走边完成事项"），而不是关于操作（"现在点击复选框"）。提示已经说明了要点击什么。一个演示中有三到五条说明文字。
- 输入真实内容。 输入“网站发布”，而不是“测试”或“asdf”。输入的文本是宣传的一部分。
- 开头和结尾要精彩。 为开始卡片设置
demo.title和一行demo.intro。在应用的最佳状态结束，并设置demo.cta为访客下一步应该去的地方。 - 根据演示的放置位置选择尺寸。 默认的
desktop视口适合落地页。对于移动 Web 应用，使用"viewport": "phone"。较小的视口会让应用在小嵌入中看起来更大。
更多关于结构、笔记、自动播放和监听演示事件的内容：references/writing.md。
隐私与诚实
- 所有操作都在此机器上运行。Clickreel 本身不打开任何网络连接；浏览器只加载你指向的应用。完成的文件不发出任何请求，也不跟踪任何内容。
- 演示由页面上显示的任何内容的截图组成，并且是准备公开的。请使用测试账户和模拟数据。未经用户许可，不要捕获真实的客户数据、真实的电子邮件地址或内部 URL。
- 展示应用的真实面貌。不要使用
eval伪造功能、隐藏真实错误或让某些东西看起来比实际更快。填充数据和隐藏开发者覆盖层是可以的；但编造行为是不可以的。
功能限制
仅限 Web 应用。屏幕是图片，因此访客不能在停止点内滚动、选择文本或偏离你选择的路径。drag 步骤在点击其热点时执行。它不跟踪打开新页签的链接，不能进入 iframe 内部，也不能上传文件。原生的 alert() 和 confirm() 对话框会被自动接受且不显示。如果流程依赖这些功能之一，请说明并构建能正常工作的部分。
当某些事情以错误消息无法解释的方式失败时，请参阅 references/troubleshooting.md。