操作示範 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 檔案中。請事先確認這點 — 沒有金鑰，產生的腳本就無法執行。
在產生任何程式碼之前，請先確認：
- 目標網址 — 操作示範從哪裡開始？（例如
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 是從中衍生出來的。超過 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，網頁安全）
walkthrough.gif ← gifski 輸出，最大寬度 800px
walkthrough.md ← 逐步註解（自動產生）
.md 檔案會將每個 act() 呼叫列為帶有時間戳的編號步驟 — 非常適合嵌入作為 GIF 的圖說。
參考檔案
references/stagehand-patterns.md— Stagehand API、步驟翻譯、點擊疊加片段、驗證模式references/output-pipeline.md— ffmpeg 指令、gifski 旗標、GIF 最佳化、疑難排解