carveragents/show-n-tell

show-n-tell 是做什麼的？

你是指揮者，負責編排一條完整的生產線：將任何網站、一個 Logo 以及一些意圖引導，轉化為一支 5 分鐘、含旁白且有品牌風格的示範影片。scripts/ 中的腳本是單純的管道，真正的編排由你來執行。

本資料夾中的參考文件：docs/SCHEMAS.md（YAML + 動作語法）、docs/GOTCHAS.md（已知問題與解決方案）、docs/CONTEXT.md（「什麼樣的輸出才算好」）、examples/halyard-spme/（完整的標準範例）。請視需要閱讀，無需預先載入。

何時使用此技能

• 使用者想要一支有旁白的網站示範影片（線上站、本機開發站或靜態站皆可）。
• 使用者至少提供了輕量的意圖引導（「展示 X、Y、Z」/「示範儀表板流程」）。
• 使用者擁有 Logo 或字標。

若使用者未提供意圖說明也未提供 Logo，則拒絕執行。 缺乏引導且使用預設品牌的通用示範影片品質不佳。請要求使用者提供指引，而非直接產出品質低落的影片。

環境偵測（開始前請先閱讀）

在開始任何動作之前，請先確認 Claude 運行的環境：

• Cowork：工具列表中可找到 mcp__cowork__list_artifacts 與 mcp__computer-use__screenshot。
• Claude Code CLI：上述工具不存在。

這點很重要，因為多個階段在兩種環境下的行為不同。快速參考：

階段	Claude Code CLI	Cowork
工作目錄（階段 5）	~/demo-videos/<slug>/	request_cowork_directory 輸出路徑
公開網站探索（階段 2b）	Playwright MCP 工具	Chrome MCP 工具或 explore_page.py 無頭模式
認證擷取 OAuth（階段 2a）	透過 Bash 執行 capture_auth.py	使用者在本機執行 capture_auth.py
長時間命令（階段 7–9）	同步執行	nohup + 輪詢（45 秒 Bash 超時）
交接（階段 11）	回報 mp4 路徑	mp4 路徑 + computer:// 連結

---

階段 1 — 訪談（收集輸入）

每次只問一兩個問題，不要一次全問。必要項目：

1. 目標網址 — 確認可連線。
2. 示範意圖說明 — 要講述什麼故事？哪些功能重要？
3. 受眾與語氣 — 內部/外部/投資人；說明型/銷售型/技術型/輕鬆型。
4. 長度目標 — 預設 5 分鐘。
5. Logo — URL 或路徑。若僅有純文字，請標註限制但接受。
6. 品牌色 — 主色（文字）＋ 強調色。若未指定，透過 PIL 從 Logo 推斷。
7. 需要登入？ — 網站是否需要登入？
   • 不需要 → 繼續。
   • 需要，表單登入（網站有你可控制的電子郵件/密碼欄位）→ 在 demo_config.yaml 中使用 session.pre_session。收集憑證的環境變數名稱（不要實際值）以及登入 URL/選擇器。告訴使用者將實際憑證自行放入 <working_dir>/.env 中，不要在對話中提供。請參閱 examples/login-flow/。
   • 需要，OAuth / SSO / 魔法連結 / 通行金鑰（Google、Microsoft、Okta 等）→ 使用 session.storage_state。使用者無需執行任何命令。由你在階段 2a 為他們啟動 helpers/capture_auth.py，他們只需在開啟的瀏覽器視窗中互動登入。擷取的 auth.json 同時用於階段 2b 的探索與階段 8 的錄製。請參閱 examples/oauth-storage-state/。

階段 2a — 認證擷取（僅限 OAuth）

若階段 1 問題 7 確定為「無需認證」或「表單登入」，則完全跳過此階段。對於 OAuth / SSO / 魔法連結 / 通行金鑰，請在網站探索「之前」擷取已認證的工作階段 — 階段 2b 需要它來檢視已認證頁面。

mkdir -p ~/demo-videos/<demo-slug>/
uv run helpers/capture_auth.py <login_or_start_url> \
  --out ~/demo-videos/<demo-slug>/auth.json \
  --viewport <recording.viewport from demo_config.yaml; default 1440x900>

透過 Bash 工具執行此命令，設定 timeout: 600000（10 分鐘 — 最大值）。腳本會開啟一個有介面的 Chromium 視窗。以淺顯的文字告訴使用者：

「我正在為你開啟一個瀏覽器視窗，請登入。完成登入流程（Google、Microsoft 等，處理雙因子驗證），導航到你希望錄製開始的頁面，然後關閉瀏覽器視窗。我將儲存工作階段並自動繼續。」

腳本會以原子寫入方式將 auth.json 寫入，權限設為 0600。若使用者花費超過 10 分鐘（較少見，但可能發生在使用手機雙因子驗證時），Bash 超時會觸發 — 只需重新執行相同命令即可。

--viewport 必須與 demo_config.yaml 中的 recording.viewport 相符。某些網站會指紋辨識視窗大小；不相符可能導致在錄製或探索時，已擷取的工作階段失效。

若尚未安裝 Playwright 的 Chromium（剛複製技能時），腳本會顯示可操作的錯誤訊息。請執行 uv run --with playwright playwright install chromium 一次。

若在 Claude Code CLI 中執行： 依照上述方式透過 Bash 執行 capture_auth.py。

若在 Cowork 中執行： Claude 直接透過 computer-use 與 Chrome 工具處理 — 使用者僅需在瀏覽器開啟時登入。步驟如下：

1. 確保已知工作目錄路徑。 若階段 5 尚未執行，請立即呼叫 mcp__cowork__request_cowork_directory 以取得輸出路徑，並將 <working_dir> 設為 <outputs_path>/<demo-slug>/。

2. 在使用者的桌面上開啟 Chrome：

   mcp__computer-use__open_application  →  "Google Chrome"  (或 "Chrome")
   

3. 導航到登入 URL。 若已連線，優先使用 Chrome MCP：

   • Chrome 擴充功能已連線：使用 mcp__Claude_in_Chrome__navigate 導航至 <login_or_start_url>
   • Chrome 擴充功能未連線：使用 mcp__computer-use__* 工具點選網址列並輸入 URL

4. 告訴使用者登入 — 以淺顯文字說：

   「Chrome 已開啟至登入頁面。請登入（處理任何雙因子驗證、SSO 等），然後導航到要開始錄製的頁面。完成後請告訴我。」

5. 等待並觀察。 約每 15 秒使用 mcp__computer-use__screenshot 輪詢。當 URL 不再是登入/認證頁面，而是顯示儀表板或應用程式頁面時，繼續下一步。

6. 透過 JavaScript 提取工作階段狀態。 使用 mcp__Claude_in_Chrome__javascript_tool 執行以下程式碼片段：

   (() => {
     const cookies = document.cookie.split(';').map(c => {
       const [name, ...rest] = c.trim().split('=');
       return { name: name.trim(), value: rest.join('='), domain: location.hostname,
                path: '/', expires: -1, httpOnly: false, secure: location.protocol === 'https:',
                sameSite: 'Lax' };
     }).filter(c => c.name);
     const ls = {};
     for (let i = 0; i < localStorage.length; i++) {
       const k = localStorage.key(i);
       ls[k] = localStorage.getItem(k);
     }
     const ss = {};
     for (let i = 0; i < sessionStorage.length; i++) {
       const k = sessionStorage.key(i);
       ss[k] = sessionStorage.getItem(k);
     }
     return JSON.stringify({
       cookies,
       origins: [{ origin: location.origin,
                   localStorage: Object.entries(ls).map(([n,v]) => ({name:n,value:v})),
                   sessionStorage: Object.entries(ss).map(([n,v]) => ({name:n,value:v})) }]
     }, null, 2);
   })()
   

7. 使用 Write 工具將結果寫入 <working_dir>/auth.json。這是有效的 Playwright storage_state 格式 — helpers/explore_page.py 與 record_demo.py 都會透過 browser.new_context(storage_state=...) 使用它。

8. HttpOnly Cookie 注意事項： JavaScript 無法讀取 HttpOnly Cookie — 它們對 document.cookie 來說是不可見的。若網站的工作階段 token 僅設定為 HttpOnly（常見於舊版 Rails/Django 工作階段 Cookie），則提取的狀態將缺少該 token。請告訴使用者：

   「請注意：標記為 HttpOnly 的工作階段 Cookie 無法從 JavaScript 存取，因此我可能未擷取到所有認證 token。錄製時會嘗試使用已擷取的資料 — 如果在階段 8 遇到登入牆，我們可以退回使用本機的 capture_auth.py。」 然後繼續 — 許多現代網站（Google、Microsoft、Okta）會在非 HttpOnly Cookie 或 localStorage 中保留足夠的狀態，讓 Playwright 能夠運作。

階段 2b — 網站探索

若階段 2a 已執行（存在 auth.json），請使用 helpers/explore_page.py 檢視已認證頁面 — Playwright MCP 無法載入 storage_state，只會看到登入牆。對於無需認證的示範，Playwright MCP 就足夠且更具互動性，請如同以往使用。

對於已認證頁面：

mkdir -p ~/demo-videos/<demo-slug>/_explore/
uv run helpers/explore_page.py https://target.example.com/dashboard \
  --storage-state ~/demo-videos/<demo-slug>/auth.json \
  --out-dir ~/demo-videos/<demo-slug>/_explore/

每個頁面會在 _explore/ 中寫出三個檔案：<slug>.png（螢幕截圖）、<slug>.dom.html（用於選取器的 DOM）、<slug>.meta.json（{url_requested, final_url, title, status}）。使用 Read 工具檢視 PNG 以查看頁面；使用 grep 搜尋 DOM 以尋找選擇器。若 meta.json 中的 final_url 指向登入頁面，表示工作階段已過期 — 請重新執行階段 2a。

對於公開頁面（任何示範的著陸頁、行銷頁面；無需認證的示範中的所有頁面）— 請如同以往使用 Playwright MCP 工具（mcp__plugin_playwright_playwright__*）：

• 使用 browser_navigate 導航至目標 URL，然後導航至使用者意圖提到的 2–5 個頁面。
• 使用 browser_snapshot 或 browser_take_screenshot 檢視每個頁面的佈局。
• 使用 browser_evaluate 讀取 DOM 以取得穩定的選擇器（優先使用語義選擇器而非 nth-of-type）。

若在 Claude Code CLI 中執行： 依照上述方式使用 mcp__plugin_playwright_playwright__* 工具。

若在 Cowork 中執行： 首先請確認已安裝 Chromium。