系統差異 是做什麼的？
系統差異展示了變更對執行中系統的影響：新增、移除或修改的元件與流程、事物現在可以經歷的狀態、改變的事實，以及新的故障方式。行級差異是證據；系統差異是審查者需要的故事。
你將變更建模為規格，指令稿則將規格渲染成影片，包含多個節拍：標題、每個圖表的前後對比、故障、結束。以下，<script> 是此技能資料夾中 scripts/system-diff.mjs 的絕對路徑。
1. 檢查設定
執行 node <script> doctor。如果機器設定完成，它會以 Ready. 結束。
若以其他訊息結束，或找不到 node，請停止並要求用戶執行 /setup-system-diff，此指令會安裝此技能所需的一切。
2. 收集變更
變更指一個拉取請求、一個分支或一個提交範圍。未指定時，採用目前分支相對於其基礎分支：若有拉取請求，則取該請求的基礎分支；否則取儲存庫的預設分支。當兩者都不明確時，詢問用戶。
請在變更的頭部所在的檢出目錄中工作，因為步驟 4 會根據磁碟上的檔案檢查你的證據。
- 讀取完整的差異（
gh pr diff <number>或git diff <base>...<head>），以及拉取請求的描述（若有的話），或提交訊息（若無拉取請求）。 - 對於每個觸及呼叫、查詢、排程、配置值、綱要（schema）或權限的程式碼區塊，在基礎版本和頭部版本中讀取足夠的周圍程式碼，以了解執行時期誰呼叫誰。
完成時，你應該能夠針對基礎版本和頭部版本說明：哪些程式在執行、每個程式與誰溝通、儲存了什麼，以及當其依賴的每個項目當機時會發生什麼。
3. 建模系統變更
將變更列為宣稱（claims），每個宣稱附帶顯示該變更的 path:line。這些宣稱將成為步驟 4 中的規格，並在步驟 6 中呈現給用戶。
- 元件：執行或儲存資料的事物，例如服務、工作、佇列、表格或外部 API。包含觀看者理解流程所需而未改變的元件。
- 流程：一個元件呼叫、讀取或寫入另一個元件。
- 狀態與轉換：一個事物經歷的階段，例如訂單、工作、工作階段或連線，以及將其從一個階段移到下一個階段的事件。
- 事實：系統中具有前後值的一個屬性，例如配置值、限制、綱要、誰可以執行什麼，或某操作耗時多久。
- 故障模式：最重要的新故障方式。通常是新元件或新依賴項目停止運作；也可能是現有元件故障的成本更高，或事物卡在某個狀態。說明接下來會發生什麼：每個其他元件做什麼，或事物最終卡在哪裡。
每個宣稱必須引用顯示它的行號。沒有行號可引用的宣稱即為猜測，應排除在影片之外。
某些變更不會改變系統：重構、格式化、測試、註解、僅程式碼內部可見的重新命名。對於這類變更，告知用戶該變更沒有系統差異，並說明其變更類型，然後在不產生影片的情況下結束。重新命名系統執行時可見的事物（如路由、表格、佇列或配置金鑰）則屬於系統變更。
宣稱決定影片繪製哪種圖表：
- 元件視圖，當接線（wiring）變更時：新增或移除元件或流程，或流程傳遞不同的內容。
- 狀態圖，當生命週期變更時：狀態新增或移除某個值，出現重試或取消步驟，或事件現在導向其他地方。
- 接線和生命週期不變但值改變的情況（例如更長的逾時），視為事實，顯示在提供上下文的圖表下方。
- 兩者皆繪製，當兩者都變更，且每個圖表能展示另一個圖表無法顯示的資訊時。每個圖表增加兩個節拍，因此一個圖表能完整說明的變更只需一個圖表。
完成時，差異中的每個區塊都應被宣稱覆蓋，或歸類為不改變系統的部分，並且你已選定要繪製的圖表。
4. 撰寫規格
將宣稱轉換為規格，遵循 SPEC.md 中的說明，該文件定義了所有欄位、佈局規則以及如何撰寫標題與旁白。將規格儲存為儲存庫外部的暫存資料夾中的 system-diff.json。
執行 node <script> check <spec> --repo <repository root>。
完成時，它應僅輸出 The spec is valid.，且無任何警告。check 指令會確認每個引用的行號確實存在；但該行是否真的顯示該宣稱則由你自行確認。
5. 建置並檢查樣張
執行 node <script> build <spec> --repo <repository root> --out <scratch folder>。它會輸出影片路徑、警告、聯繫表（一張包含每個節拍一個影格的圖片）以及一個 stills 資料夾，其中包含相同影格的全尺寸圖片。
閱讀聯繫表以了解整體畫面，並檢視各影格以檢查小字：
- 每個標籤、數值和標題都完整且可讀；
- 每條流程線都清晰繞過不相連的方塊和標籤；
- 每個「之前」影格只顯示變更前存在的內容，而每個「之後」影格顯示變更新增的所有內容；
- 狀態圖的起點位於事物起始的狀態上；
- 故障影格標記正確的元件或狀態，且每個註解位於其描述對象的底部邊緣；
- 每個標題說明其影格顯示的內容。
修正規格並重新建置，直到建置輸出 No warnings. 且樣張通過所有檢查。多數影格問題可透過縮短文字或將方塊移到另一個儲存格來解決。若仍有問題，請在交接時特別說明。
6. 交接
提供用戶影片路徑、一句話說明影片內容、帶有證據的宣稱，以及你遺漏或不確定的部分。將影片發布到任何地方是用戶的決定。