操作演示 GIF 技能
生成一个独立的 Node.js 项目，用于录制浏览器操作演示并导出 MP4 和 GIF。
何时使用此技能 vs. claude-in-chrome gif_creator
对于用户实时浏览器会话中的快速一次性捕获（使用其个人配置文件、已打开标签页、已登录状态），claude-in-chrome 的 gif_creator 工具要简单得多——无需项目搭建，无需 API 密钥。当用户需要 gif_creator 无法提供的内容时，请使用此技能：可重新运行/可版本化的脚本（每次 UI 更改后重新录制）、MP4 输出、高质量的 gifski GIF、干净的配置文件录制（画面中不出现个人书签/扩展）或 CI 可重复性。
架构
自然语言描述
↓
Claude 生成 TypeScript 脚本
↓
Stagehand v3（AI 浏览器控制）—— 通过 CDP 连接的 Playwright
↓
Playwright 录制上下文捕获视频 (.webm)
↓
ffmpeg 转换 → .mp4
gifski 转换帧 → .gif
↓
输出：walkthrough.mp4 + walkthrough.gif + walkthrough.md
工作流程
步骤 1：收集需求
前提条件——LLM API 密钥： Stagehand 每次 AI 操作都需要调用 LLM。用户需要准备好 ANTHROPIC_API_KEY（或与已配置模型匹配的提供商密钥，例如 OPENAI_API_KEY）用于 .env 文件。请预先确认——没有它，生成的脚本无法运行。
在生成任何代码之前，请确认：
- 目标 URL — 操作演示从哪里开始？（例如
https://app.example.com/login） - 流程描述 — 应演示哪些步骤？（自然语言即可）
- 认证情况 — 页面是公开的，还是需要登录？如果需要登录：他们将在
.env中硬编码凭据、使用预认证的会话/cookie 导出，还是从已登录状态开始？ - 输出格式 — 仅 GIF、仅 MP4，还是两者都要？（默认：两者）
- 时长/节奏 — 快速演示还是谨慎的逐步操作？（步骤之间默认暂停约 1-2 秒）
- 视口 — 默认 1280×800。移动风格演示可更窄。
如果用户提供了丰富的描述，请推断出你能理解的部分，并仅询问缺失的细节。
步骤 2：生成项目
在 ./walkthrough-[name]/ 输出一个完整的、可运行的项目：
walkthrough-[name]/
├── package.json
├── tsconfig.json
├── .env.example
├── src/
│ └── walkthrough.ts ← 主脚本
└── scripts/
└── convert.sh ← ffmpeg + gifski 转换
阅读 references/stagehand-patterns.md 以了解 Stagehand API 和步骤转换模式。
阅读 references/output-pipeline.md 以了解 ffmpeg/gifski 转换命令和 GIF 调优。
步骤 3：转换步骤
将用户的自然语言转换为 stagehand.act() 调用（v3：act() 位于 stagehand 实例上，接受纯字符串，带可选的 variables 和 page 选项）。参见 references/stagehand-patterns.md 了解模式和注意事项。
关键转换规则：
- 每个逻辑 UI 操作 = 一个
stagehand.act("...", { page })调用，带有清晰的英文指令 - 输入文本通过
variables（%name%占位符）传递——切勿将密钥内联在指令字符串中 - 在主要步骤之间添加
page.waitForTimeout(1500)以控制节奏（对观看者可见） - 导航后添加
page.waitForLoadState('networkidle') - 永远不要硬编码选择器——Stagehand 会根据自然语言指令自行识别
- 对于需要认证的流程：使用
.env文件存放凭据，切勿硬编码
步骤 4：录制策略
始终使用 Playwright 视频录制作为主要捕获方法：
- Stagehand v3 没有内置录制功能——通过
chromium.connectOverCDP({ wsEndpoint: stagehand.connectURL() })将 Playwright 连接到 Stagehand 的浏览器，创建一个带有recordVideo选项的上下文，并驱动该上下文的页面（参见references/stagehand-patterns.md） - 通过该录制上下文将整个会话录制为
.webm文件 - 不要尝试直接将单个截图拼合为 GIF——视频→帧→GIF 质量更高
- 脚本完成后，运行
convert.sh生成 MP4 和 GIF
切勿将 GIF 作为主要输出。 始终先生成 MP4。GIF 从 MP4 衍生而来。对于超过 15 秒的内容，GIF 文件体积大且质量低——请警告用户并建议将操作演示控制在 60 秒以内。
步骤 5：点击/光标叠加（可选但推荐）
在操作演示开始前，通过 page.addInitScript() 注入点击高亮叠加层。参见 references/stagehand-patterns.md → “点击叠加”部分以获取代码片段。
这会在每个点击点添加微妙的涟漪动画——使操作演示更易读，无需后期处理。
步骤 6：输出
生成之后，提供：
- 项目目录（所有文件）
- 对话中的简短设置清单：
## 设置
npm install
npx playwright install chromium
cp .env.example .env # 填写 ANTHROPIC_API_KEY 及任何凭据
## 运行
npx tsx src/walkthrough.ts
## 转换为 GIF + MP4
bash scripts/convert.sh
同时告知用户预期内容：大致时长、视口大小、输出文件名。
主动提出运行： 如果用户同意（他们仍需提供 .env 值），Claude Code 可以自行执行整个流程——npm install、npx playwright install chromium、运行操作演示脚本，然后 bash scripts/convert.sh。当你自己运行时，请在声明成功之前验证输出：使用 ffprobe 检查 MP4 的时长是否合理，并确认 GIF/MP4 文件大小不为零（convert.sh 会在其验证尾部打印这些信息）。
警告/中止条件
如果以下任何条件适用，请提前告知用户：
| 条件 | 指导建议 |
|---|---|
| 页面需要 MFA/SSO 登录 | 脚本无法自动处理——用户必须从已登录的浏览器会话中导出 cookie |
| 目标页面上有 CAPTCHA | Playwright 将挂起——请改用演示/沙箱环境 |
| 大量动画/无限滚动 | 录制会捕获它们，但 GIF 转换后体积会很大——建议裁剪 |
| 流程超过 90 秒 | 建议仅生成 MP4；GIF 将大得无法使用 |
| 页面内容是随机/动态的 | Stagehand 可处理视觉定位，但需警告重新运行可能看起来不同 |
输出命名约定
walkthrough-[slug]/
output/
walkthrough.webm ← Playwright 原始录制文件
walkthrough.mp4 ← 转换后文件（H.264，适合 Web）
walkthrough.gif ← gifski 输出，最大宽度 800px
walkthrough.md ← 逐步注释（自动生成）
.md 文件将每个 act() 调用列为带时间戳的编号步骤——适合作为字幕嵌入到 GIF 旁边。
参考文件
references/stagehand-patterns.md— Stagehand API、步骤转换、点击叠加代码片段、认证模式references/output-pipeline.md— ffmpeg 命令、gifski 标志、GIF 优化、故障排除