NodeKit Present
將經驗證的開發產物轉化為活生生的簡報。將簡報視為變更記錄的投影，而非獨立的主張來源。
在創建或更新簡報產物之前，請閱讀變更故事合約。
工作流程
- 分類變更層級。 跳過無關緊要工作的簡報；對於狹義的修復使用變更卡，對於主要功能使用 3-5 張幻燈片的迷你簡報，對於發行版本或黑客松則使用完整簡報加附錄。
- 創建或更新
changes/<change-id>/change.yaml。 記錄目標受眾、問題、先前狀態、決策、替代方案、受影響的系統、使用者工作流程、證據需求、限制條件以及簡報層級。 - 在工作進行時捕獲證據： 基準和之後的螢幕截圖、確切的提交記錄、部署身份、測試、基準測試、追蹤、產物、匯出以及已知失敗。保留原始收據。
- 建立證據索引。 為每個具體的主張賦予狀態和證據 ID。清楚區分已規劃、推斷、使用者聲稱和已測量的主張。
- 在渲染前規劃每張幻燈片。 說明其任務、目標受眾問題、核心要點、敘事角色、主要視覺元素、證據 ID、密度預算和演講者筆記目標。
- 按此順序使用已安裝的 NodeSlide 傳輸： 儲存庫原生適配器、NodeSlide CLI、NodeSlide MCP 或套件 API。首先檢查能力，絕不假設託管寫入、匯出或核准可用。
- 針對已固定的簡報版本提出簡報變更。 透過主機政策進行驗證、比較和套用；請勿為了方便而繞過 NodeSlide 治理。
- 針對當前提交或部署驗證每個具體的主張。 重新整理過時的螢幕截圖和指標。保持限制條件可見。
- 匯出請求的可編輯格式並重新開啟。 驗證渲染後的簡報、演講者筆記、原始碼綁定以及任何 PPTX 的往返一致性。
- 從相同的變更故事和證據索引衍生出示範腳本、README 章節、發行說明和投稿文案。
展示剪輯是渲染的引導式操作，絕非螢幕錄影
此章節的存在源於一次有紀錄的失敗。一次生產環境部署在 11/11 透過一個錄製剪輯進行驗證，但該剪輯只是原始的 Playwright 擷取：沒有焦點畫面、沒有字幕、沒有可見的串流或工具呼叫、沒有幻燈片。針對上述每一項的工具當時都已存在，而這個技能卻沒有提到任何一個，因此最終以拙劣的方式手工製作，而不是良好地驅動它們。
FeatureClipStudio (feature-walkthrough-gif/) 是從擷取到渲染的管線，它涵蓋了原始擷取永遠不具備的四件事：
| 原始擷取缺乏的內容 | 管線提供的內容 |
|---|---|
| 聚焦在重要事物上 | 縮放至重點的相機、動畫游標滑動至每次點擊並附帶漣漪效果 |
| 解說 | 每個狀態的步驟字幕 |
| 工作過程的可見性 | 即時載入和串流顯示已擷取的內容——旋轉圖示旋轉、結果送達 |
| 當主張依賴於內部機制時，其內部運作 | 原始 JSON/狀態證據面板 |
npm run capture # Playwright 驅動即時流程並記錄每個 UI 狀態
npm run studio # 分鏡板展示擷取的狀態
npm run render # Remotion 渲染引導式操作影片
npm run judge # Gemini 觀看渲染結果並評分
judge-video.mjs 是關卡，並且是在宣告剪輯完成前必須執行的那一個。它根據反英雄鏡頭評分標準觀看渲染後的 MP4 檔案，並返回帶有時間戳的 P0/P1/P2 缺陷——其中 P0 會阻止發布。其自身的標題說明了重點：最終剪輯不再只是人類眼睛檢查的階段。評斷 MP4 而不是 GIF；GIF 並非支援的影片 MIME 類型。
對於評分已經通過的 P2 缺陷，請不要進入重新渲染的打磨循環。
兩個軸線，而第二個軸線正是經常失敗的那個
judge-video.mjs 分別評分 CRAFT——游標真實性、節奏、易讀性、動態——以及 COMPREHENSION，即觀看者必須實際理解的十件事：
人物角色 · 目的 · 使用案例 · 功能清晰度 · 完整互動
回應性 · 流程 · 結果 · 非專業人士理解度 · 知識轉移
它們是正交的，一段剪輯可以製作精良但難以理解。在一個真實渲染結果上的測量：工藝以 publish 的判決通過，而理解度在全部十項上只得到 1 分——沒有缺失，沒有明確，一切都只是暗示——評分者指出 0:06 是讓非專業人士迷失的時刻（「層級架構概念和終端日誌輸出」）。
non_expert_sense 是媽媽測試，它會獨自阻止發布，無論總分如何。一個通過了其自身評分者認為「圈外人無法理解」的影片的關卡，不是一個有效的關卡。所有十項的均一分數會被標記而不是取平均，因為「全部 1 分」意味著全部暗示而無一陳述，這是一個發現，而不是一個及格邊緣的通過。
循環是預設值，而非最終檢查： 渲染、評分、閱讀它所說缺失的內容、重新剪輯、再次評分。對同一部影片進行三次剪輯，將其從 10/20 提升到 13/20，並且更有用的是，告訴創作者這個故事是圍繞著錯誤的時刻構建的——這是任何數量的自我審查都無法發現的。當理解度通過且剩餘缺陷僅為 P2 時停止。
NodeSlide 用於簡報，NodeVideo 用於畫面層級的證據——一個作為運作中的產品呈現的畫面，必須綁定到它來自的部署，而 presentedAs 正是使這可被檢查的機制。
參考影片來源
Mobbin 適用於 UI，因為它是一個你觀察和引用的語料庫，絕不複製。影片需要同樣的紀律，並分為兩種，它們不可互換：
流程參考——真實產品實際上是如何一步一步運作的。 Page Flows 是直接的類比：記錄的使用者旅程而非螢幕截圖，超過 20,000 個應用程式，按任務組織——註冊、升級、取消——包括同意對話框、欄位驗證、空狀態和成功畫面。它自身的框架是從另一面陳述的反英雄鏡頭規則：Mobbin 向你展示目的地，Page Flows 向你展示旅程。ScreensDesign 涵蓋了入職流程和付費牆，並附帶收入信號。使用這些來回答「此類型的真實流程包含哪些狀態，而我正在跳過哪些？」
工藝參考——發布影片是如何構建的。從 YouTube 開始。 評分者可以直接讀取 YouTube URL——已驗證：Gemini 僅從 URL 觀看了一個並描述了其開場秒數和運行時長，無需下載。因此，參考是被引用的，絕不複製，這完全解決了授權問題，並使定位器成為 URL 加上時間戳：
代理會建立自己的語料庫，而不是等待被給予一個。yt-dlp 搜尋 YouTube 並讀取元數據；不下載任何內容，而 Gemini 觀看 URL：
node find-references.mjs "Raycast product demo" "Linear product demo" # 搜尋、篩選、觀察
node judge-video.mjs out/demo.mp4 # 自動使用語料庫
node judge-video.mjs out/demo.mp4 --no-reference # 選擇退出
find-references.mjs 在花費 token 之前進行篩選：任何超過 180 秒的內容預設都會被拒絕，因為對於短暫的引導式操作來說，這是錯誤的形狀和錯誤的成本，並會列印原因。在一次真實運行中測量——一個 39 秒的第一方示範花費了 3.9k 的提示 token，而一個 18 分鐘的花費了 102k。然後它會寫入 references/video/<id>.json：帶有時間戳的原子事實（0:07 motion — keycaps turn green on keypress）、hookSeconds、statesShown、whatToSteal 和 whatNotToSteal，以及一個它無法確定的 notRun 列表。事實，絕非形容詞——一個事實可以為一個候選項目評分，一個形容詞則不能。
判決會增加一個 reference 區塊——singleMoment、statePacing、motionPurpose、whatToSteal 和 whatNotToSteal——每個關於參考的宣稱都需要一個時間戳。每個值得研究的產品發布影片都在 YouTube 上，並且是主要來源；下面策展的庫是它之上的發現層，對於尋找候選項目很有用，而不是用來觀看它們。
成本是真實的：一個 18 分鐘的參考測量到 102k 的提示 token。偏好 30-90 秒的剪輯，並且最多傳遞兩到三個參考。
FlowJam 是手工策展的 SaaS 和產品發布影片； Tella 的庫 和 Vidico 的拆解 發布帶有推理說明的範例。使用這些來了解節奏、單一時刻，以及動態在哪裡起作用，哪裡只是裝飾。
請不要將任何一種直接貼到評分標準中作為文字。像記錄 Mobbin 觀察結果一樣記錄它們：一個原子事實，帶有一個 locatorDescription，對於影片來說是一個時間戳，引用到來源 URL。宣稱是「在 0:12 時，載入狀態持續了 1.4 秒才顯示結果」，而不是「他們的節奏很好」。從帶有時間戳的觀察結果中得出的規則可以被評分；形容詞則不能。
許可：觀察和歸屬，永遠不要重新託管。觀察模式中的 licenceMode 故意是一個枚舉的單一值——將其擴展到一個新的來源類別是一次許可審查和一次刻意的模式編輯，而不是一個鍵入的字串。
發布影片是被導演，然後被渲染的——發布影片合約
以上所有內容都是評斷一個已存在的剪輯。一部發布影片在更早的時候就會失敗：它建立在錯誤的時刻，或者在發布之後才交付，而沒有評分循環可以挽回任一種情況。在 Motion Studio 現場研究（針對 YC 級別新創公司的發布影片）：他們的流程是 導演 → 初稿 → 修改 → 交付，並且「人類導演做出每一個品味決定」。那個順序就是產品本身。nodekit launch-video 將其作為一個可以拒絕的合約來執行，所以驅動的編碼代理會逐步執行這些階段，而不是跳躍到 npm run render：
nodekit launch-video declare --application <slug> --out launch-video.json
# 1 BRIEF 填寫產品、故事（利益相關者的話）、目標受眾、發布日期、頻道
# 2 DIRECTION 單一時刻、有序的節拍、透過 find-references.mjs 獲得的參考（帶時間戳的事實，絕非形容詞）、durationTargetSeconds ≤ 180——然後由**人類**核准
# 3 DRAFTS capture → studio → render (FeatureClipStudio 或 NodeVideo)，對 MP4 執行 judge-video.mjs，記錄循環：剪輯、評分分數、humanNotes、處理方式
# 4 DELIVERY 最終剪輯 + judgeReceipt + 人類核准，deliveredAt 在 launchDate 之前
nodekit launch-video check --contract launch-video.json # 在每個階段退出時拒絕
檢查會拒絕什麼，以及每個拒絕存在的原因：
- 在核准的方向之前有草稿——第一個剪輯是在方向上達成一致，而不是發現一個；在方向返回之前製作的渲染是修改帳單。
- 沒有時間戳的參考宣稱——「他們的節奏很好」無法評分；「在 0:12 時載入狀態持續了 1.4 秒」則可以。
- 最終循環未通過
non_expert_sense——媽媽測試獨自阻止交付，規則與上述評分循環相同；合約使其成為階段退出而不是建議。 deliveredAt晚於launchDate——在發布之後交付的發布影片是一部回顧。- 沒有人類核准的交付——評分者是提供建議的；品味決定是人做出的。
評分循環仍然是階段 3 的內部循環，完全如上所述。合約增加了循環本身從未持有的東西：按順序排列的階段、在兩個品味關卡的人類，以及日期。
平行軌道
對於一個大型實作，將簡報工作作為一個主要用於讀取的軌道，與建置和 QA 並行運行。早期起草問題和架構；僅在後續關卡使用經過驗證的證據來取代佔位符。僅針對不支援的主張、缺少所需證明、證據過時或匯出失敗的情況，才阻止發行。
完成狀態用語
- 當幻燈片計劃存在時，說
drafted（已起草）。 - 當每個具體的主張都指向當前的證據時，說
evidence-bound（證據已綁定）。 - 僅在請求的輸出成功重新開啟後，說
export-verified（匯出已驗證）。 - 僅當應用程式證明和簡報證明都通過時，說
release-ready（準備好發布）。
不要將通過的單元測試變成生產環境的主張，不要將 HTTP 200 變成瀏覽器證明，也不要將建議性的模型判斷變成權威性的裁決。