Screencast Demo
从 Playwright 驱动的演练中生成带有字幕、光标覆盖的产品演示视频。核心见解：Playwright 的无头录制没有真正的光标。在最终视频中看到的可视光标 + 点击涟漪 + 字幕是从结构化事件日志中组成的 ffmpeg 覆盖，而不是真正的鼠标事件。这种解耦使得录制脚本保持声明式（“点击此，讲述那”），而生产质量的视觉效果（光滑的光标插值、涟漪闪烁、字幕计时）从后处理器中免费获得。
何时使用
当用户请求以下任何内容时激活：
网页应用程序的精致产品演示视频
README 或发布公告的 OSS 功能演示
带有讲述步骤的 bug repro Screencast
教程/入门视频，展示如何在基于浏览器的 UI 中执行某些操作
用户说“录 demo / 录视频 / screencast / walkthrough video / 演示视频”时
何时不激活
用户想要记录非浏览器内容（使用 OBS / 本机屏幕录制器）
单个屏幕截图或静态图像就足够了
用户想要记录真正的鼠标运动（此技能绘制合成光标）
目标 UI 仅为移动设备（Playwright 支持移动模拟，但光标 + 涟漪视觉效果针对桌面视口进行了调整）
管道概述
gen-cursor + gen-ripple → cursor.png, ripple.png（一次性）
login → storageState.json + 页面摘要
record → raw.webm + events.json
postprocess → final.mp4 + subs.srt
deploy → output/screencast-{stamp}.mp4
review → review/{flow,visual,coverage}/*.png
clean → 删除临时文件
npm run ship 运行 record → postprocess → deploy → review → clean 作为一个命令。
初始化新项目
当用户说他们想为某个网页应用程序记录演示时，执行以下操作：
向用户询问（简要，理想情况下在一轮中）：
目标 URL（基础 — 本地 http://localhost:3000 或远程）
如果不是 /login 的登录路径
演示项目的工作目录（例如 D:\AI\my-demo 或 ~/projects/my-demo）
是否需要部署目录（默认为 ./output/）
如果不是 1440x900 的视口大小
将模板复制到工作目录：
templates/record.js → <工作目录>/record.js
templates/postprocess.js → <工作目录>/postprocess.js
templates/review.js → <工作目录>/review.js
templates/login.js → <工作目录>/login.js
templates/gen-cursor.js → <工作目录>/gen-cursor.js
templates/gen-ripple.js → <工作目录>/gen-ripple.js
templates/deploy.js → <工作目录>/deploy.js
templates/clean.js → <工作目录>/clean.js
templates/package.json → <工作目录>/package.json
然后在工作目录中：
npm install
npx playwright install chromium
模板已经接受这些环境变量（无需代码编辑）：
SCREENCAST_BASE — 目标 URL
SCREENCAST_LOGIN_PATH — 默认为 /login
SCREENCAST_VIEWPORT_W / SCREENCAST_VIEWPORT_H — 默认 1440/900
DEPLOY_DIR — 默认为 ./output/
DEPLOY_PREFIX — 默认为 screencast
SUBTITLE_FONT — 覆盖平台检测的 CJK 字体
对于一次性操作，直接编辑 record.js 第 22-26 行。
npm run setup # 生成 cursor.png 和 ripple.png
npm run login # 打开真正的浏览器；用户手动登录
如果目标页面是公共的（无需身份验证），则跳过 npm run login。record.js 将在没有 storageState.json 文件的情况下运行 — 演示将不会有任何登录会话。
npm run login 步骤专门用于应用程序后面的登录屏幕。
在使用 npm run login 后，post-login-summary.json 将包含可见的导航/标题/按钮文本。在编写阶段流之前，请阅读此文件 — 它告诉您在不与实时 UI 交互的情况下可用的选择器。
编辑 record.js 中 try { ... } 块的主体（搜索 STAGE FLOW）。使用 references/helpers-api.md 中记录的帮助程序。
有关更完整的模式指南，请参阅 examples/walkthrough-flow.md。
npm run ship
这运行了完整的管道（record → postprocess → deploy → review → clean）。
对于 2 分钟的演示，预计：
record：~2-3 分钟（实时播放加上停留时间）
postprocess：~30-60 秒（ffmpeg 合成）
review：~30-60 秒（n × ffmpeg seek+frame extraction；无进度指示器，只是静默等待 — 这是正常的）
完成后，阅读审查截图以验证演示实际上看起来是正确的 — 参阅 references/known-pitfalls.md 以了解需要注意什么。
编写帮助程序（快速参考）
在 record.js 的 try { ... } 块中：
帮助程序 做什么
await sub('字幕文本') 添加字幕事件 + 持有页面的 CJK 感知持续时间
await click(locator, '操作描述') 光标移动到目标，停留，点击，停留（完整的仪式）
by