What's New 短片 是做什麼的?
What's New 短片 告訴人們一個版本在短暫的滑動時間內改變了什麼:一張開場卡,每次發布時都問同一個問題並顯示版本號;每個變更一個場景,在正式版本上拍攝並附上說明文字;以及一張結束卡,指出如何取得。文字先確定,而且是核准者自己的用語。你從一個可重複的預設狀態開始拍攝,用一個指令渲染,在任何人看到之前先觀看你自己的渲染靜態畫面。規格文件保留在版本庫中,所以下一個版本可以從這個版本開始,而不是從空白的編輯工作階段開始。
專案事實存放在使用者版本庫的 docs/agents/whats-new-clip.md:發行說明的位置、如何建構與預設發行版本、如何捕捉這個畫面、外觀、格式、短片存放位置,以及核准者是誰。如果該檔案遺失,請先遵循 SETUP.md。
工具是 scripts/clip.py。以 uv run <此技能的資料夾>/scripts/clip.py <指令> 執行;任何指令加上 --help 會列出其旗標。它需要在 PATH 上有 ffmpeg 和 ffprobe;uv 會攜帶 Pillow。如果沒有 uv,請在版本庫外部建立虛擬環境(python3 -m venv <dir> && <dir>/bin/pip install pillow),然後用 <dir>/bin/python 執行工具。規格的格式以及 check 適用的每個規則都在 SPEC.md 中。
1. 找出人們會注意到的東西
讀取專案檔案中指定的版本發行說明。列出使用者會看到、聽到或感受到的每個變更,並將每個變更連結到其發行說明中的行號。省略沒有人注意到的修正和幕後工作。
如果清單上沒有任何項目是使用者會注意到的,請詢問核准者這個版本是否要製作短片,除非他們回答「是」,否則就停止。
完成條件: 清單上的每個項目都指向發行說明中的一行,或者核准者已表示此版本沒有短片。
2. 確定文字
為每個變更提出一個說明文字,按照顯示順序排列,最引人注目的放在最前面。一個場景只講一個變更。說明文字是用簡單詞彙表達的使用者好處,要夠短,能在場景播放期間讀兩次(大約六個詞)。如果核准者已經為某個變更提供了文字(在發行說明、訊息或應用程式內的 What's New 中),請原封不動地使用它們:保持他們的拼字、文法和大寫。
一次詢問核准者,附上完整清單和每行的建議,讓他們可以用一個字回答。在文字確定之前不要拍攝任何東西:重新措辭的說明文字通常需要不同的鏡頭。
當核准者重新措辭產品中也顯示的說明文字(例如應用程式內的 What's New 畫面、商店發行說明)時,請詢問該文字是否也應更改,以便版本用統一的聲音說話。
完成條件: 核准者已同意每個說明文字,並且你持有每個文字,與同意的內容完全一致。
3. 撰寫規格
如果設定時已經寫了此版本的規格,請填寫該檔案。否則,從上一個版本的規格開始,以便外觀、開場白和結束卡能夠延續:
clip.py init <版本> --out <規格資料夾> --from <規格資料夾>/<上一個版本>.json
對於第一個短片,請使用 --product "<名稱>" 而不是 --from。填寫每個場景的 caption(從步驟 2 逐字複製)、words_by(提供文字的人),以及計劃的 in 和 out 時間,要夠長以便閱讀其說明文字。沒有畫面可看的變更,場景長度應盡可能縮短,只需足以顯示說明文字即可。然後執行 clip.py check <spec> --words。
完成條件: check --words 輸出 check: ok。
4. 拍攝每個場景
按照 FILMING.md 中的規則,使用專案檔案中的建構、預設和捕捉指令來拍攝每個場景。只顯示此版本包含的內容:不要顯示它在出貨時關閉的功能開關後的東西,也不要顯示下一個版本的東西。
如果無法透過產品自己的 UI 的真實輸入到達某個變更,請停止並告知使用者:這是個錯誤,繞過它拍攝的短片會承諾人們無法做到的事情。
專案捕捉無法拍攝的變更(例如相機畫面、第二個裝置)應從保存的影片中展示:請參閱 FILMING.md 中的「捕捉無法拍攝的內容」。
將影片放在此版本的短片資料夾中,在版本庫外部。根據每一步執行的時間戳記設定每個場景的 source、in 和 out,並在信賴標記之前先觀察:
clip.py peek <影片> --from <秒數> --to <秒數> --out <一個全新的暫存資料夾> --sheet <暫存資料夾>/peek.png
它會顯示影片在兩個秒數之間的畫面,如同 render 將讀取的那樣。切勿使用你自己的搜尋來拉取那個靜態畫面:螢幕錄影僅在畫面改變的位置保留一個影格,所以搜尋會落在下一個改變的位置,這可能是在幾秒鐘之後。
然後執行 clip.py check <spec> --media <影片資料夾>。
完成條件: check 在 --media 指向影片時輸出 check: ok。
5. 渲染
clip.py render <spec> --media <影片資料夾> --out <短片資料夾>/<產品, 用連字號連接>-<版本>-9x16.mp4
使用 --size 渲染專案檔案中指定的每個其他格式,例如 --size 1920x1080。當 render 說某個螢幕在該尺寸下太小而無法閱讀時(例如寬畫面中的手機螢幕),該格式需要自己的規格:請參閱 SPEC.md 中的「另一種格式」。聲音是可選的,且永遠不承載訊息:大多數人會靜音觀看,因此僅靠說明文字就必須講述故事。
完成條件: render 為專案檔案中指定的每個格式都輸出了 Wrote ...。
6. 審查者檢查
將靜態畫面拉取到一個新資料夾中:clip.py stills <短片> --spec <規格> --every 1 --safe --out <暫存資料夾> --sheet <暫存資料夾>/sheet.png。它會從每張卡片和每個場景的中間寫入一個靜態畫面,每秒一個,以及它們的組合圖,並將饋送覆蓋的邊緣著色。根據 REVIEW.md 檢查每個靜態畫面,針對每種格式。
如果你的工具可以啟動子代理,請將此檢查交給一個以全新上下文啟動的子代理,它只持有 REVIEW.md、規格、靜態畫面和組合圖:它看到的是螢幕上的內容,而不是你打算拍攝的內容。
按照 REVIEW.md 的表格修復每個發現的問題,然後重新渲染並再次拉取靜態畫面。永遠不要在交接過程中用解釋來淡化錯誤的畫面。
完成條件: 每個靜態畫面都通過 REVIEW.md 中的每個項目,並且沒有待處理的修復。
7. 交接
將 REVIEW.md 的「交接」列表中提到的內容,按照專案檔案指定的方式發送給核准者,並請求批准或告知需要修改的地方。在他們說「可以」之前,短片不會被發布,也不會附加到版本上。發布由專案檔案中指定的人負責。
如果收到「不行」,將他們的修改要求帶回步驟 2(文字)或步驟 4(畫面),並且只重新拍攝那些有變更的場景。如果「不行」沒有說明原因:一次詢問他們不喜歡什麼,然後再進行同樣的拍攝。
完成條件: 核准者已說「可以」,或者他們的修改要求已回到步驟 2 或步驟 4。
8. 為下一個版本保留
規格文件與版本的其他變更一起保留在版本庫中。將影片與已核准的短片一起放在短片資料夾中。將這個短片教訓中學到的每個經驗,作為一行添加到專案檔案中的 Lessons 下方。
完成條件: 規格文件在版本庫中,影片與已核准的短片並排放置,並且每個新經驗都已成為 docs/agents/whats-new-clip.md 中的一行。