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 中的 scripts、README、dist/ 資料夾）。然後選擇一種方式：
- 如果應用程式已在執行，或者您可以自行啟動：設定
"url"。 - 如果是靜態網站或已建置的資料夾：設定
"serve": "./dist"，Clickreel 會提供服務。 - 如果您希望建置過程日後可重複執行：設定
"start": "npm run dev"搭配"url"，Clickreel 會啟動它並等待。
步驟是透過使用者看得見的文字來定位元素：按鈕文字、欄位的標籤或佔位文字、aria-label。請閱讀您所選流程的元件，並精確複製這些標籤。猜測會浪費一次往返。
示範應該從一個值得觀看的狀態開始。空白的第一個畫面或登入畫面是薄弱開場。如果應用程式需要資料或已登入的會話，請在第一個停點（stop）之前設定好：使用應用程式的種子腳本、一個寫入 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" }
]
}
每個步驟會變成一個停點（stop）（訪客需要執行的操作）或什麼都沒有：
| 步驟 | 在示範中的呈現 |
|---|---|
{ "click": "新增專案" } | 在元素上顯示一個熱區。訪客點擊它後會看到真實結果。 |
{ "type": "hello", "into": "Email" } | 在欄位上顯示一個熱區。點擊它會播放文字輸入的過程。省略 into 則在當前聚焦的欄位中輸入。 |
{ "press": "Enter" } | 顯示可按的按鍵圖示，或訪客按下真實按鍵。"Mod+K" 在 macOS 上是 Cmd，在其他系統上是 Ctrl。 |
{ "hover": "圖表" } | 一個對懸停或手機點擊有反應的熱區。 |
{ "select": "Pro", "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 檔案，可以從磁碟和任何網頁主機運作，並且不從網路載入任何內容。回報 Clickreel 印出的任何注意事項（頁面錯誤、被遮蓋的元素、檔案過大）。如果某個步驟無法運作而您移除了它，請說明原因。
GitHub README 無法執行 HTML 檔案。對於 README，請連結到示範的託管位置（GitHub Pages 很適合提供 docs/ 的服務），或使用來自 Demoreel 的 GIF。
簡而言之，如何寫出好的示範
- 六到十二個停點。 每個停點都是訪客必須進行的一次點擊。減少設定步驟，或使用
eval在第一個停點之前完成它們。 - 標題就是新聞標題。 七個字或更少，重點是效益（「邊做邊打勾」），而不是動作（「現在點擊核取方塊」）。提示已經告訴他們要點擊什麼。一場示範使用三到五個標題。
- 輸入真實內容。 「網站發布」，而不是「測試」或「asdf」。輸入的文字本身就是推銷的一部分。
- 開頭與結尾要精彩。 為開始卡片設定
demo.title和一行demo.intro。以應用程式最好的狀態結束，並設定demo.cta指向訪客下一步應該去的地方。 - 根據放置位置選擇尺寸。 預設的
desktop視口適合登陸頁面。對於行動網頁應用程式，使用"viewport": "phone"。較小的視口會讓應用程式在較小的嵌入區中看起來更大。
更多關於結構、注意事項、自動播放和監聽示範事件的資訊：references/writing.md。
隱私與誠實
- 一切都在此機器上執行。Clickreel 不會自行開啟任何網路連線；瀏覽器只載入您指定的應用程式。最終檔案不發送任何請求，也不追蹤任何資訊。
- 示範由頁面上畫面的圖片組成，並且旨在發布。請使用測試帳號和虛構資料。未經使用者同意，不要擷取真實客戶資料、真實電子郵件地址或內部 URL。
- 如實展示應用程式。不要使用
eval來偽造功能、隱藏真實錯誤，或讓東西看起來比實際更快。填充資料和隱藏開發者疊加層是可以的；但捏造行為則不行。
它不能做什麼
僅限網頁應用程式。畫面是圖片，因此訪客無法在停點內捲動、選取文字或偏離您選擇的路徑。drag 步驟在其熱區被點擊時播放。它無法跟隨開啟新分頁的連結、無法進入 iframe 內部，也無法上傳檔案。原生的 alert() 和 confirm() 對話框會被自動接受而不會出現。如果流程依賴於這些功能，請說明情況並建置可行的部分。
當某些問題以錯誤訊息無法解釋的方式失敗時，請參閱 references/troubleshooting.md。