CloudyWing/merge-data

Data Merge

此 Skill 用於將多份資料檔整合成單一檔案的情境，例如先後產出的兩份資料、主機匯出的補充資料需要與既有資料合併。它不是 ETL pipeline，也不負責資料庫 migration 或例行資料同步；若整合邏輯需要長期重複執行，改以正式的資料處理程式承載。

啟動條件

符合任一條件時套用：

• 使用者要求將兩份以上的資料檔合併、整合或補資料成一份。
• 一份資料發現闕漏，需與另一份補充資料合併。
• 需要對多份資料去重或對齊欄位後輸出單一檔案。

能力邊界

一次性的資料整合無法「可證明正確」。整合腳本若有邏輯錯誤，它產出的 dry-run 數字也會跟著錯。本流程的作用是把錯誤從破壞性寫檔之後提前到寫檔之前，並產出可供審查的證據。最終正確性由使用者拿已知事實核對樣本後定案，不得對外宣稱本流程已「保證整合正確」。

整合流程

1. 盤點來源：列出每份來源檔的格式、筆數與欄位結構。讀不到筆數或結構不明時，先回報，不進入後續步驟。
2. 確立合併語意：與使用者確認下列三項，不自行假設：
   • 比對鍵（key）：以哪個欄位判定「同一筆」。
   • 合併模式：補欄位（同一筆補齊缺漏欄位）、加列（不同筆合併）、或去重。
   • 衝突規則：同一筆在不同來源有不同值時，以哪一份為準。
3. 確立獨立預期：在撰寫腳本前，先用來源筆數推導整合結果的應有筆數公式（例如 結果筆數 = A 筆數 + B 新增筆數）。此公式必須獨立推導，不得從整合腳本反推，否則失去驗證意義。
4. 撰寫整合腳本：讀來源、寫新檔，不原地覆寫輸入檔（依全域規範「腳本改寫安全」）。來源檔保持不動，即為天然還原依據。腳本必須支援 dry-run 模式。
5. dry-run：先以「只報告、不寫檔」模式執行，輸出預計比對到、新增與衝突的筆數。對照步驟 3 的公式，數字不符即停下檢查腳本邏輯，不得寫出整合檔。
6. 正式產出：dry-run 數字與預期相符後才執行寫檔。整合結果輸出為新檔，存放於使用者預期的專案位置，不放入 .local/ai-sessions/。
7. 對筆數：整合檔的實際筆數與步驟 3 的公式再核對一次。不符代表有資料被默默增刪。
8. 抽樣比對：從每份來源各挑數筆已知資料，確認在整合檔中正確出現、欄位無錯置；有衝突的筆至少抽一筆，確認取捨符合步驟 2 的衝突規則。
9. 整合報告：輸出差異摘要供使用者審查。

檢查未通過時

• 任一檢查（dry-run、對筆數、抽樣比對）不通過時停止，不重複盲試。
• 保留來源檔與已產出的整合檔（整合檔加註待查標記，不覆寫、不刪除）。
• 回報不符的具體數字或筆、推測的腳本問題、尚需使用者確認的合併語意。
• 修正前須講出明確假設（問題在 X，因為 Y，所以改 Z）。同一問題最多嘗試修正 3 次，仍失敗即停止並回報。

整合報告格式

完成後用精簡格式回報：

資料整合：
- 來源檔：
- 合併模式 / 比對鍵：
- 預期筆數 / 實際筆數：
- 新增 / 補欄位 / 衝突筆數：
- 抽樣比對結果：
- 待確認項目：

若有檢查未通過或待確認的合併語意，必須在 待確認項目 明列，不得在語意未確認的情況下逕行產出整合檔。