tutorial-video

教學影片

將「教人們怎麼用這個」轉變為一組準備好的 MP4 檔案。Claude 身兼導演、編劇、操作員和剪輯師。使用者只需批准計畫、批准腳本，然後觀看結果。

運作方式（以及為何這樣設計）

理解工具 → 訪談 → 腳本（批准）→ 無錄製排演
   → 校準畫面 → 錄製每個影片 → tut prepare → tut plan/stills → tut render → delivery/

有三個問題定義了此架構。理解它們，因為這解釋了下方幾乎所有的規則：

1. 擴充功能的點擊不會移動系統滑鼠。 螢幕錄製會沒有游標。因此一個注入頁面的 recorder.js 會記錄每個點擊、按鍵和導航發生的位置和時間，而游標、點擊波紋、縮放和標註則在後期編輯時繪製。由於編輯器知道未來發生的事，游標會在點擊之前平滑移到按鈕上，且鏡頭會在動作發生前縮放。
2. 同步影片和事件。 在每個 take 的開始和結束，__tut.flash() 會將頁面變成洋紅色半秒鐘。剪輯器在影片中找到這個閃爍，並藉此找出頁面時鐘與影片時間的對應關係，以及頁面在螢幕上的確切矩形位置，無需計算 Retina 或多螢幕座標。
3. Claude 在兩個動作之間反應較慢。 原始影片中有很長的停頓。剪輯器會剪掉這些停頓（因為影格完全相同，所以剪輯看不出來），加速有移動的等待過程，並在最後凍結結果畫面足夠長的時間以便閱讀字幕。因此，錄製時不要趕時間。趕時間只會導致錯誤。

此處使用的路徑：

• SKILL_DIR：此技能所在的資料夾。
• TUT="$SKILL_DIR/scripts/tut"，REC="$SKILL_DIR/scripts/rec.sh"，WIN="$SKILL_DIR/scripts/chrome-window.sh"。
• SERIE：系列資料夾，預設為當前目錄下的 ./tutoriais/<series-slug>/（如果使用者偏好其他位置請詢問）。

每個 tut 指令最後都會輸出一行 RESULT {json}。請讀取這行來決定下一步。

階段 0：先決條件（每次工作階段執行一次）

1. 執行 $TUT doctor。首次執行會安裝引擎（Remotion），首次渲染時會下載無頭 Chrome（約 140 MB）。
2. 在一次 ToolSearch 呼叫中載入 Claude in Chrome 的工具：select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__javascript_tool,mcp__claude-in-chrome__find,mcp__claude-in-chrome__read_page。如果擴充功能未連接，請要求使用者執行 /chrome。沒有它就無法錄製。
3. 向使用者說明一次接下來會在他的電腦上發生什麼事：macOS 會要求終端機應用程式的螢幕錄製權限，以及 Chrome 的自動化權限（用於定位視窗）。錄製期間應開啟請勿打擾模式，並且不要移動滑鼠或切換視窗。

階段 1：理解工具

在問任何問題之前，先研究要教授的內容。好的問題取決於此。

• 如果有本機專案（儲存庫）：閱讀 README 和文件、路由與頁面、導航選單、表單和引導流程。從最終使用者的角度列出功能（例如「建立職缺」、「邀請同事」），而非從程式碼角度。
• 如果是 URL：使用 Claude in Chrome 瀏覽，在主要畫面上使用 read_page 搭配 filter: "interactive" 並展開選單。

結果：一個簡短的工作對應表，列出受眾能夠完成的任務，以及每個任務的起始畫面。詳細內容請見 references/roteiro.md。

階段 2：訪談與系列計畫

使用 AskUserQuestion。每個問題應提供從階段 1 對應表中得出的具體選項，以及一個建議。使用者不應憑空想出答案。與使用者一同決定：

• 受眾與程度（誰在看，他們已經知道什麼）。
• 系列目標（入門引導、減少支援、銷售展示、內部培訓）。
• 要教什麼：從對應表中複選任務。
• 影片數量。由你提議：一部影片 = 一個結果（例如「如何發布職缺」），長度 30 秒到 3 分鐘，3 到 8 個步驟。
• 視覺：預設樣式 aurora（深色）、grafite 或 claro，品牌色和標誌。
• 錄製環境：URL、已在 Chrome 上登入的示範帳號、虛構資料、絕對不能出現的內容。

接著展示系列計畫（表格：編號、標題、結果、預計長度）並等待批准。

階段 3：腳本（批准關卡）

依照 references/roteiro.md 中的結構和文字規則，撰寫 SERIE/serie.json 以及每個影片的 SERIE/videos/<NN-slug>/roteiro.json。最重要的幾點：

• 每個步驟有一個簡短的命令式 titulo（在畫面上大字顯示）、一個可選的 texto（說明位置或原因）、要執行的 acoes 以及 resultado_esperado。
• 完全按照畫面上顯示的名稱書寫介面名稱。觀看者正在尋找那段文字。

執行 $TUT validate SERIE 並向使用者展示每個腳本的易讀表格。在獲得批准之前不要錄製任何東西。 重錄的成本遠高於重寫。

階段 4：排演（不錄製）

針對每個影片，在不錄製的情況下在 Chrome 中執行步驟。這樣你可以找出有效的選擇器和引用、意外的彈出視窗、載入緩慢的部分，以及需要事先準備好的內容（資料、登入）。之後：

• 將系統恢復到初始狀態（如果使用者同意，刪除排演中建立的內容）。
• 如果需要登入，請要求使用者手動登入。絕對不要輸入密碼，也絕對不要錄製登入畫面。
• 如果腳本有任何不符，請調整腳本（並通知使用者更改了什麼）。

階段 5：準備視窗與校準（每個系列一次，或當視窗改變時）

請遵循 references/gravacao.md 中的「視窗與校準」章節。簡而言之：

1. 注入 recorder.js。
2. 執行 __tut.windowPlan(1280, 720)。根據它回傳的標記和邊界，執行 $WIN <marker> <bounds...>。
3. 以全螢幕錄製幾秒鐘並加上閃爍：$REC start SERIE/.tut/calibracao --full → __tut.flash() → $REC stop ...。
4. 執行 $TUT calibrate SERIE 並查看產生的 viewport.png。

它必須只顯示頁面內容，沒有瀏覽器列、沒有其他視窗、沒有邊框或擴充功能的警告。如果出現邊框，請在 captura.json 中設定 insets。

階段 6：錄製每個影片

完整協定請見 references/gravacao.md。一個 take 的骨架如下：

$REC start SERIE/videos/<id>/take-1          # 只錄製頁面區域（來自校準的裁切）
javascript_tool: __tut.flash()                # 初始閃爍（同步用）
for each step:
  javascript_tool: __tut.mark('start:<step>')
  執行動作 (computer: left_click / hover / key; 使用 __tut.type 輸入)
  標註重要元素：__tut.callout('text or selector', 'short label')
  等待結果出現在畫面上
  javascript_tool: __tut.mark('end:<step>')
javascript_tool: __tut.flash()                # 最終閃爍（修正時間偏差）
javascript_tool: __tut.dump()  →  $TUT save-events SERIE/videos/<id>/take-1   (透過 stdin 傳入 JSON)
$REC stop SERIE/videos/<id>/take-1
$TUT prepare SERIE/videos/<id>/take-1

避免重錄的規則：

• 在任何完整的頁面載入之後，重新注入 recorder。 先前的事件會保存在分頁的工作階段中。在離開到其他網域之前，請執行 dump 和 save-events。
• 如果某個步驟在中間出錯，使用 __tut.mark('abort:<step>')，回到先前的狀態，然後用 start:<step> 重新開始。系統會採用最後一個完整的嘗試。不要因此停止錄製。
• 對於輸入文字，優先使用 __tut.type('text') 在點擊欄位後進行（文字會逐字出現）。computer type 會一次讓所有文字出現。
• 對於滾動，優先使用 __tut.scrollTo('text or selector')（平滑滾動）。停頓是免費的，因為剪輯器會剪掉它們。不要趕時間。
• 不要觸發 alert / confirm：它們會卡住擴充功能。如果某個步驟需要「刪除」，請先通知使用者。

階段 7：編輯與審查

$TUT prepare SERIE/videos/<id>/take-N    # 剪輯、同步、測量移動 → take.json
$TUT stills  SERIE <id>                  # 布局 + 靜止圖格，產出至 videos/<id>/qc/stills.jpg

查看靜止圖格（以 Read 檢視圖片）再進行渲染。確認：

• 游標和點擊波紋正確落在元素上；
• 標註圍繞著元素；
• 字幕與螢幕上的內容相符；
• 縮放區域不是空的；
• 沒有出現敏感資料。

修正腳本（文字）或僅重新錄製有問題的步驟為 take-2。計畫會使用最新且包含完整步驟的 take。接著：

$TUT render SERIE <id>                   # → SERIE/entrega/<id>.mp4 + chapters + contact sheet

開啟 contact sheet (entrega/<id>.sheet.jpg) 做最後檢查。視覺調整（主題、縮放、音樂、片頭與片尾）等資訊在 references/edicao.md 中。

階段 8：交付

1. 執行 $TUT deliver SERIE。它會產生 entrega/LEIAME.md，包含可以直接貼到 YouTube 的標題、時長和章節。
2. 向使用者展示 entrega/ 資料夾和摘要（影片、時長、涵蓋範圍）。
3. 如果可以傳送檔案，請寄送第一支 MP4。
4. 在執行 $TUT clean SERIE 之前先詢問，這會刪除原始錄製檔 raw.mkv 以釋放空間。

原則

• 腳本說了算；錄製要服從。 如果實際介面與腳本不符，暫停並與使用者調整腳本。不要在錄製時即興發揮。
• 一個步驟 = 畫面上的一個想法。 如果字幕需要兩個句子，很可能這是兩個步驟。
• 展示，而非告知。 使用標註來指向元素。字幕僅命名動作。
• 預設保護隱私。 只錄製頁面區域，使用包含虛構資料的示範帳號，不要在網址列顯示查詢字串。在錄製前，關閉不應該出現的內容。
• 用眼睛檢查結果。 靜止圖格和 contact sheet 的存在就是為了讓你查看。未經查看，不要告訴使用者影片沒問題。

參考資料

• references/roteiro.md：工具探索、系列設計、訪談問題、serie.json 和 roteiro.json 的結構、文字規則、範例。
• references/gravacao.md：視窗、校準、逐步錄製 take、__tut API、錯誤恢復以及 Claude in Chrome 和 macOS 的注意事項。
• references/edicao.md：剪輯器如何決定剪輯、縮放和游標，主題和音訊選項，品管檢查清單以及問題排除。