getlarge/themoltnet

產品示範錄影

將架構、隱私、敘事和編碼輸出視為各自獨立的發布檢查關卡。 一個成功的產品執行並不表示錄影是安全、可讀或構圖清晰的。

如需了解原生 macOS 或瀏覽器捕捉機制，請閱讀 參考資料/capture-macos.md。 如需了解具有輪詢或重試循環的瀏覽器工作流程建置器，請閱讀 參考資料/browser-workflows.md。 如需了解標題卡、下三分之一、圖表、標註和結束卡，請閱讀 參考資料/infographic-style.md。

先建立交付畫面規格

在錄製前：

1. 在撰寫鏡頭列表之前，先選擇敘事類型：
   • 概覽 介紹產品樣貌：展示最小代表性的節點或畫面序列，使用通用文案，並省略情境特定的說明。
   • 情境示範 回答一個具體問題：說明案例，展示真實的執行階段，並以驗證後的結果作結。
   • 當兩者都有用時，優先使用分開的短片。除非使用者明確想要一個綜合的逐步解說，否則不要混合通用產品說明和特定領域案例。
2. 建立視覺參考：
   • 如果存在先前的錄影，從頭到尾檢查它。在有用時提取聯絡表，並記下其節奏、構圖、註解和最有力的解釋時刻。
   • 如果沒有先前的錄影，依序使用 @themoltnet/design-system 函式庫、鄰近的文件媒體和整合產品的原生 UI，在錄製前建立一個標題卡靜態圖、一個最密集的標註 UI 靜態圖和一個結束卡靜態圖。這些經核准的靜態圖將成為系列中後續影片的基準。
3. 閱讀影片將出現的頁面。寫一個簡短的鏡頭列表，說明使用者結果、所需設定、主要互動、等待或重試行為以及成功結果。
4. 在安排應用程式之前，選擇最終的畫面比例和解析度。偏好傳統的 16:9 畫面，例如 1440x810 或 1920x1080。
5. 安排應用程式，使完整的預期內容區域能容納該畫面。必要時隱藏應用程式內部的可選側邊欄；不要移除一半的側邊欄或控制項，然後用任意的事後裁切來處理。
6. 決定瀏覽器 chrome 是否為構圖的一部分。偏好乾淨的瀏覽器視口捕捉。如果無法做到，則保持完整的瀏覽器視窗，或將其放置在一個有意的框架內。完整的視窗比裁切過的標籤頁、邊緣或應用程式內容更為乾淨。
7. 以實際顯示尺寸審查三個代表性的樣式畫面。不要在疊加系統、安全區域或資訊層級結構仍在發明時，就錄製完整的逐步解說。

使用安全的捕捉邊界

• 捕捉一個應用程式視窗或一個瀏覽器視口，絕不要捕捉一個桌面矩形，以避免其他應用程式進入。
• 在錄製前解析並鎖定確切的視窗識別碼。在導航、彈出視窗或應用程式重新啟動後重新檢查。
• 關閉通知並使用專用的示範資料，但不要依賴這些預防措施作為隱私邊界。
• 將憑證、令牌、個人識別碼、私人 URL 和不相關的帳戶資料保持在捕捉畫面之外。密碼遮罩是必要的，但不要因此讓輸入憑證的片段變得可取。
• 讓指針有目的性。在閱讀靜態結果時，將指針遠離文字停放。

為理解而錄製

• 每個鏡頭使用一個想法。將重要的配置和結果保持足夠長的時間，以便在正常播放速度下閱讀。
• 僅在幫助觀看者重現結果時才顯示設定。對於整合示範，這通常意味著安裝、在不洩露密碼的情況下驗證、匯入工作流程、執行它，並檢查終端結果。
• 偏好使用原生應用程式縮放和佈局更改，而不是後續放大裁切過的點陣圖。
• 捕捉真實的成功執行。重建的標題卡和註解可能可以解釋它，但絕不能暗示一個未被觀察到的動作或結果。
• 一個以狀態為主導的編輯，可以在動畫本身不具教學意義時，使用從一次真實執行中捕捉的乾淨靜態圖。按觀察到的順序保留狀態，保留可見的任務證據，並僅使用轉場來傳達進度。
• 在錄製片段之外完成憑證建立和連線測試。從一個安全的已驗證狀態開始敘事，除非憑證設定本身就是文件化的主題。
• 當流程具有穩定的階段時，錄製短小、可獨立使用的片段。這可以限制重新錄製，並使隱私審查更精確。
• 對於長時間的輪詢或重試循環，保留真實的有序狀態，但加速或修剪重複的空閒部分。以可讀的速度保持初始動作、終端工作流程狀態和接受的結果。

編輯時不隱藏產品

• 保留每個預期的應用程式邊緣。縮小並填充到交付畫面，而不是裁切內容以強制達到某個畫面比例。
• 僅在改善方向性或下一步驟時使用標題卡和結束卡。
• 將下三分之一保持在預先規劃的安全區域內。它們不得遮蓋理解流程所需的控制項、狀態、輸出、錯誤或識別碼。
• 對於情境示範，讓註解隨著執行過程前進。用一行簡短的文字命名當前階段並解釋其後果，例如： 意圖 — 提取地點和時間範圍 接著 意圖完成 — 獲取預報。使用產品的實際階段名稱和可觀察的狀態；不要敘述隱藏的推理。
• 讓概覽影片在視覺上比其配套的情境示範更安靜。當節點標籤和原生狀態指示器已經足夠時，應讓它們承擔解釋工作。
• 在替換現有影片時，符合已建立的文件視覺語言。不要讓替換影片感覺比它所取代的資產更隨意。
• 為了廣泛的瀏覽器相容性，預設使用 H.264 High、yuv420p、固定 30 fps、無音訊（除非有意添加旁白），以及 MP4 fast-start。
• 在此 macOS 工具鏈上，在實際可行時，偏好對最終渲染使用單執行緒的 libx264。在提取精確時間戳的 QA 畫面時，使用捆綁的輔助工具，而不是快速的輸入搜尋。
• 如果某個畫面在成品預覽中看起來損壞，請重新開啟校驗和穩定的成品，並在本機播放器中檢查影片。預覽路徑偶爾會以不同方式渲染相同的圖片字節；除非缺陷可以獨立重現，否則不要修改影片。
• 如果某個畫面在正常播放和重複提取後仍然損壞，請從乾淨的來源替換受影響的片段，並使用 -threads 1 重新編碼最終母版。

僅在音訊有其價值時才添加

• 對於嵌入的文件影片，保持無聲播放為預設。當音訊能實質解釋視覺簡潔的標註無法說明的時機、因果關係或背景時，才添加旁白。
• 針對鎖定的畫面撰寫並計時旁白。字幕或文字稿必須保留相同的資訊，且影片在靜音時必須仍能被理解。
• 僅在獲得該人員明確授權的情況下，才能使用基於可識別人物建模的克隆或合成語音。在周圍頁面或致謝中揭露該語音是合成的；不要將其呈現為真實的現場錄音。
• 除非使用者明確選擇發布，否則將語音樣本、模型檔案和生成的中間檔案保留在儲存庫之外。將建立一個有旁白示範的授權視為僅限於該交付物，而不是未來語音生成的常設同意。
• 在混合音訊後重新執行交付品質檢查。驗證可理解性、音量、同步、字幕、聲道佈局，以及最終容器仍符合影片交付規格。

審查解碼後的交付品

針對最終檔案（而非中間檔案）執行捆綁的輔助工具：

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  path/to/final.mp4 /private/tmp/demo-video-qa --interval 2 4 5 6

該輔助工具會將串流元資料、一個順序解碼的聯絡表，以及開始/中間/結束和請求的時間戳畫面寫入為 JPEG 檔案。使用一個全新的輸出目錄。

然後執行所有這些檢查：

1. 以正常速度觀看整個最終影片。
2. 檢查聯絡表中應用程式、模式、鏡頭、註解和結果狀態的每一次變化。
3. 檢查每個編輯邊界之前、當時和之後的準確畫面。始終在審查回饋中命名添加的時間戳；不要推斷相鄰畫面具有代表性。
4. 確認沒有其他應用程式、桌面區域、通知、憑證、私人資料、裁切邊緣、部分瀏覽器 chrome、奇怪的黑色邊框或受阻的控制項。
5. 確認文字可讀、指針位置平靜、轉場乾淨，且可見結果與周圍文件相符。
6. 根據交付規格驗證編解碼器、像素格式、尺寸、幀率、時長、音訊選擇和 fast-start 要求。

在對將要提交的準確檔案執行這些檢查之前，請勿將錄影描述為已審查。

有目的地發佈並保留

• 僅暫存最終資產和有意義的文件變更。不要添加原始錄影、憑證、瀏覽器設定檔或 QA 匯出。
• 保留原始錄影，直到最終檔案經過審查並安全提交或上傳。然後遵循操作者的保留選擇；明確刪除敏感的臨時捕捉，而不是使用廣泛的刪除模式。
• 在交接時，說明顯示了什麼、最終的技術屬性、檢查了哪些時間戳，以及最終資產的位置。