walkthrough-record

用途

walkthrough-record 用于为 Web 应用录制精致的演示视频。它把一份场景 YAML 作为输入，输出电影感的 webm 母版，并附带 mp4（H.264、faststart）和 gif（两遍调色板）导出文件。它针对的是手动录屏的常见失败：光标抖动、节奏错失、无法复现的拍摄、文字模糊，以及动辄 20 MB 的 GIF。

主要能力

运行内置的 Playwright 录制器，驱动真实 Chromium。
注入覆盖层引擎：缓动贝塞尔光标、点击涟漪、聚光灯环、隐私遮罩、说明卡片、镜头缩放。
通过 Playwright 的 page.screencast 以清晰的 2 倍分辨率捕获。
可选加框处理：将捕获画面嵌入壁纸画布，带圆角、柔和阴影，以及可选的 macOS 窗口标题栏。
输出 webm 母版（始终全出血，不烘焙边框）、mp4（H.264 CRF 18、yuv420p、faststart、按 output.fps 恒定帧率）、gif（palettegen/paletteuse 两遍）。
每个文件原子写入，不会截断；同名输出会被覆盖。
加框运行会额外保留 <name>.frame-plate.png（画布尺寸：壁纸、阴影、边缘、标题栏）和 <name>.frame-mask.png（圆角 alpha），作为重新导出的输入。

使用方式

每台机器一次性安装：运行 bash "${CLAUDE_SKILL_DIR}/scripts/setup.sh"。它会检查 Node ≥ 20 和 ffmpeg，在脚本旁安装固定版本依赖（playwright 1.61.1、yaml 2.8.0），并安装 Chromium。若缺少前置条件会以非零退出并给出确切信息，应原样呈现，不要自行发挥安装。
获取场景：使用用户提供的场景，或先用姊妹技能制作故事板。若没有场景且只想看效果，可录制内置演示 "${CLAUDE_SKILL_DIR}/assets/demo/orbit-tour.yaml"。
录制：

node "${CLAUDE_SKILL_DIR}/scripts/record.mjs" scenario.yaml --out ./walkthrough-out

可用标志：--validate-only（仅做模式校验，保证不打开浏览器）、--webm-only（迭代时跳过导出）、--headed（实时观看）、--out DIR。录制器会在打开浏览器之前校验场景，若失败则退出码 1 并列出所有模式违规，应原样转述；修 YAML，不要改校验器。对于需要认证的目标，storageState 场景会用真实会话执行真实点击——录制任何生产环境内容前，先与用户确认来源是预发布/测试账号。

声明成功前先验证：检查日志中的 mp4 check 行（宽、高、帧数 | 秒数），然后抽取 3–4 个抽查帧查看：

ffmpeg -y -i out/<name>.mp4 -vf "select='not(mod(n\,400))'" -vsync vfr /tmp/frame%d.png

确认：光标可见且平滑、卡片可读且在画面内、缩放居中于目标、没有遮罩内容泄漏。

加框（可选，除非场景要求否则关闭）：output.frame 将捕获画面嵌入壁纸画布。它在导出时运行——webm 母版保持全出血，因此可通过重新导出添加、改样式或去掉边框。

output:
  frame:
    background: auto      # auto | studio | midnight | spotlight | paper | 任意 CSS 颜色/渐变
    chrome: false         # macOS 窗口标题栏（12 pt 灯、28 pt 栏）——默认关闭
    title: "Orbit"        # 标题栏文字，仅 chrome 开启时
    pad: 0.062            # 画布内边距，占画布宽度的比例
    radius: 13            # 圆角半径，CSS px（10 = 真实 macOS，chrome 开启时的默认值）

output.frame: true 采用全部默认值。background: auto 会采样所录应用的品牌色和明暗，推导匹配的壁纸——在事先不了解应用时是正确选择。当视频必须匹配已知品牌时，选择具名背景。

针对平台目标（README、YouTube、社交平台）调整导出：预算和配方见 references/export-profiles.md。GIF 太大？先裁剪到一个节拍（gif: {start, duration}），再收窄宽度，再降低帧率——从现有 webm 重新导出，不要重新录制（加框运行会把 *.frame-plate.png / *.frame-mask.png 保留在输出旁，正是为了让重新导出仍可用；配方在 references/export-profiles.md）。
失败处理（找不到选择器、缩放区域错误、空白视频、粘性头部伪影）：用 references/troubleshooting.md 诊断。绝不要为了绕过某个应用而修改 scripts/；修场景或记录限制。

适用场景

为 Web 应用制作演示、导览或走查视频。
需要可复现、脚本化、带平滑光标和镜头运动的录制。
需要从同一母版导出多平台格式（webm/mp4/gif）。
需要隐私遮罩、说明卡片、品牌化加框等呈现效果。

限制

不适用于：编写或打磨场景 YAML 本身（节拍、卡片文案、缩放位置、主题）——那是 walkthrough-storyboard 的职责；对任意桌面应用或现场演示做操作系统级录屏；Playwright 测试编写、截图或通用 ffmpeg 转换。
镜头缩放是对 <body> 的 CSS transform（有意为之，GPU 平滑缓动）。固定/粘性 chrome 或在缩放期间读取视口矩形的 JS 可能表现异常；修复在场景侧（无缩放节拍或换目标），见 troubleshooting。合成器侧缩放仍在路线图中，尚未发布——不要承诺。
2 倍清晰度使用 html {zoom} 加双倍视口，因此媒体查询看到的是基础宽度×2。桌面优先应用渲染一致；中间有 max-width 断点的应用需要 output: {scale: 1}。
遮罩不透明且失败即关闭：实心覆盖（不是模糊——模糊会泄漏形状/长度），每帧重新解析；匹配不到任何元素的遮罩选择器会中止运行；导航期间会绘制幕布直到遮罩重新应用。不要通过删除遮罩来“修复”中止——找到正确的选择器。遮罩无法触及跨域 iframe 内部。
wait: {until: networkidle} 在带持久 websocket 的应用上会挂起——优先用 wait: {for: selector}。
导出会覆盖同名输出（迭代渲染是常态）；用不同的 --out 目录保留不同拍摄。
录制是实时的：捕获期间保持机器低负载；若输出看起来卡顿，用 troubleshooting 中的 ffprobe 命令验证节奏。
加框会消耗应用线性分辨率约 20%（默认内边距下 2560 → 2054 px）。母版是 2 倍栅格，因此应用仍落在 1.6 倍，文字保持清晰——但不要把加框叠加在 output: {scale: 1} 上。
background: auto 只在首次注入覆盖层时采样一次。若导览中途把应用切到深色模式，壁纸保持起始时的样子；边缘和阴影仍会分隔窗口。若在意，固定一个具名背景。
加框 GIF 会把调色板默认值改为 256 色 + sierra2_4a：渐变壁纸在未加框的 128 色 bayer 默认下会明显色带。128 色下的扩散既更丑也更大——不要“优化”回去。

文件

scripts/record.mjs — 录制器 CLI（校验、录制、导出；任何失败退出码 ≠ 0）
scripts/overlay.js — 注入的覆盖层引擎（光标/卡片/环/遮罩/镜头）
scripts/frame.mjs — 导出时加框（壁纸/阴影/圆角/macOS 标题栏）；node frame.mjs --self-test
scripts/setup.sh — 一次性依赖安装，scripts/themes/ — 主题预设
assets/demo/ — 内置演示应用（orbit.html）+ 演示场景（orbit-tour.yaml）
references/export-profiles.md — 各目的地（README、YouTube、Vimeo、应用内）的 mp4/gif 预算
references/troubleshooting.md — 失败→修复表、缩放兼容性说明、节奏审计命令

技能介绍

用途

主要能力

使用方式

适用场景

限制

文件