merge-datalisted

# Data Merge 此 Skill 用於將多份資料檔整合成單一檔案的情境，例如先後產出的兩份資料、主機匯出的補充資料需要與既有資料合併。它不是 ETL pipeline，也不負責資料庫 migration 或例行資料同步；若整合邏輯需要長期重複執行，改以正式的資料處理程式承載。 ## 啟動條件 符合任一條件時套用： - 使用者要求將兩份以上的資料檔合併、整合或補資料成一份。 - 一份資料發現闕漏，需與另一份補充資料合併。 - 需要對多份資料去重或對齊欄位後輸出單一檔案。 ## 能力邊界 一次性的資料整合無法「可證明正確」。整合腳本若有邏輯錯誤，它產出的 dry-run 數字也會跟著錯。本流程的作用是把錯誤從破壞性寫檔之後提前到寫檔之前，並產出可供審查的證據。最終正確性由使用者拿已知事實核對樣本後定案，不得對外宣稱本流程已「保證整合正確」。 ## 整合流程 1. **盤點來源**：列出每份來源檔的格式、筆數與欄位結構。讀不到筆數或結構不明時，先回報，不進入後續步驟。 2. **確立合併語意**：與使用者確認下列三項，不自行假設： - 比對鍵（key）：以哪個欄位判定「同一筆」。 - 合併模式：補欄位（同一筆補齊缺漏欄位）、加列（不同筆合併）、或去重。 - 衝突規則：同一筆在不同來源有不同值時，以哪一份為準。 3. **確立獨立預期**：在撰寫腳本前，先用來源筆數推導整合結果的應有筆數公式（例如 `結果筆數 = A 筆數 + B 新增筆數`）。此公式必須獨立推導，不得從整合腳本反推，否則失去驗證意義。 4. **撰寫整合腳本**：讀來源、寫新檔，不原地覆寫輸入檔（依全域規範「腳本改寫安全」）。來源檔保持不動，即為天然還原依據。腳本必須支援 dry-run 模式。 5. **dry-run**：先以「只報告、不寫檔」模式執行，輸出預計比對到、新增與衝突的筆數。對照步驟 3 的公式，數字不符即停下檢查腳本邏輯，不得寫出整合檔。 6. **正式產出**：dry-run 數字與預期相符後才執行寫檔。整合結果輸出為新檔，存放於使用者預期的專案位置。需要跨階段交接的資料放入 `<work-root>/.local/ai-sessions/handoff/`，人員閱讀的整合報告放入 `<work-root>/.local/ai-sessions/report/`，不將交付資料放入 `.local/ai-sessions/`。 7. **對筆數**：整合檔的實際筆數與步驟 3 的公式再核對一次。不符代表有資料被默默增刪。 8. **抽樣比對**：從每份來源各挑數筆已知資料，確認在整合檔中正確出現、欄位無錯置；有衝突的筆至少抽一筆，確認取捨符合步驟 2 的衝突規則。 9. **整合報告**：輸出差異摘要供使用者審查。 ## 檢查未通過時 - 任一檢查（dry-run、對筆數、抽樣比對）不通過時停止，不重複盲試。 - 保留來源檔與已產出的整合檔（整合檔加註待查標記，不覆寫、不刪除）。 - 回報不符的具體數字或筆、推測的腳本問題、尚需使用者確認的合併語意。 - 修正前須講出明確假設（問題在 X，因為 Y，所以改 Z）。同一問題最多嘗試修正 3 次，仍失敗即停止並回報。 ## 整合報告格式 完成後用精簡格式回報： ```text 資料整合： - 來源檔： - 合併模式 / 比對鍵： - 預期筆數 / 實際筆數： - 新增 / 補欄位 / 衝突筆數： - 抽樣比對結果： - 待確認項目： ``` 若有檢查未通過或待確認的合併