file-singlify(文件單副本化)
這個 skill 做什麼
掃描某個磁碟 / 目錄 / 掛載路徑,找出因多次複製、備份、同步、遷移產生的重複檔案和重複目錄,生成「單副本化」方案:每組保留一份 canonical copy,其餘映射為引用 / 待刪除 / 連結建議,估算可節省空間。
核心原則:預設唯讀、只做 dry-run。絕不直接刪除、移動、覆蓋、改寫、建立硬/軟連結。任何破壞性操作都必須先出報告、再等使用者明確確認。 腳本本身永遠唯讀 —— --action-mode 只改報告裡 suggested_action 的標籤,不執行任何動作。
何時使用
- 使用者要掃某個盤/目錄/一批資料夾,找「一模一樣的檔案」「重複目錄」「冗餘備份」「多重複製」
- 使用者想保留一份原始檔案、生成引用映射、刪除建議、硬/軟連結建議、去重報告、節省空間估算
- 關鍵詞:去重 / 單副本化 / 重複目錄摺疊 / dedup / canonical copy / storage cleanup
不適用: 使用者要的是檔案內容分析、壓縮、或與重複檢測無關的整理。
預設工作流程
- 路徑與權限檢查 — 確認當前環境能否存取
root_path。能存取就執行腳本;不能存取則要求使用者提供目錄清單 / 目錄樹 / 壓縮檔 / 可存取掛載路徑。絕不虛構掃描結果。 - 執行腳本(directory-first) — 先按目錄一致性找冗餘,再用 hash 確認檔案。整個目錄被重複複製是最大空間浪費來源,優先展示目錄級結果。
- 讀腳本輸出,整理給使用者 — 優先講重複目錄組,再講重複檔案組、canonical 映射、節省空間、風險項。對腳本標為
uncertain/manual_review的項,向使用者提問澄清,不要替他決定。 - 給出 top-4 後續命令 — 腳本會按當前 OS/shell 生成 top-4 推薦命令(安全優先:verify → quarantine → hardlink → delete),見報告第 10 節 / JSON 的
recommended_commands。把它們呈現給使用者,並按使用者真實的 OS 與 shell 調整語法;腳本預設自動探測,必要時用--target-os/--target-shell覆蓋。只給命令,不執行。 命令裡用的是代表性樣本路徑,需逐行套用到映射表。 - destructive 操作前再確認 — 使用者要真正刪除 / 換連結時,先複述計畫並要求明確確認;腳本不會執行,需使用者自行執行或另行授權。
何時執行腳本
環境可直接讀到 root_path 就執行;只拿到清單/樹時,按同樣的判定邏輯(目錄結構一致 → 檔案大小一致 → 內容 hash 確認)人工分析並明確說明「未做 hash 確認」。
python3 scripts/scan_file_singlify.py <root_path> \
--scan-mode directory-first \ # 或 file-only
--hash-algorithm md5 \ # md5 | sha256 | both(嚴格用 both)
--output-format markdown \ # markdown | json | csv
--action-mode report-only \ # report-only|link-plan|delete-plan|hardlink-plan|symlink-plan
--exclude-patterns ".git,node_modules,cache,temp" \
--include-patterns "*.jpg,*.mp4" \
--min-file-size 1024 \
--prefer "/Volumes/Primary" \ # 優先保留此路徑作 canonical
--target-os auto \ # auto|macos|linux|windows(生成 top-4 命令用)
--target-shell auto # auto|bash|zsh|fish|powershell|cmd
完整參數與判定細節見腳本 --help、references/matching-rules.md 與 references/safety-rules.md。
輸出格式
腳本產出結構化報告,含:掃描範圍、參數、總檔案/目錄/容量、重複目錄組、疑似重複目錄、重複檔案組(hash 確認)、節省空間估算、canonical 映射表、top-4 推薦命令(按 OS/shell 生成)、風險與不確定項、下一步建議。markdown 給人看,json 給程式消費(含 recommended_commands),csv 是 duplicate→canonical 映射表。
每個映射行帶 confidence(confirmed / uncertain)和 suggested_action(keep / delete_duplicate / replace_with_hardlink / replace_with_symlink / create_manifest_reference / manual_review)。
安全邊界
- 預設絕不刪除檔案、絕不自動建硬/軟連結。 腳本唯讀。
- 只憑檔案名稱 / 大小 / mtime 不能判定相同 —— 只作候選篩選;最終結論必須 hash 確認(相同大小 + 相同 hash)。
- 對系統目錄、隱藏目錄、應用目錄、Git 倉庫、資料庫、照片圖庫、雲同步目錄格外謹慎。
- 符號連結不跟隨、不遞迴;遇到目錄循環停止遞迴並報告。
- 權限不足 / 零位元組 / 特殊檔案 / 已硬連結檔案 → 標記並跳過,進入「跳過 / 不確定」分類,不當作確定重複。
- canonical 無法判定時,列候選並要求使用者確認,不自行拍板。
常見錯誤
| 錯誤 | 糾正 |
|---|---|
| 沒確認能否存取路徑就「假裝掃描」 | 先確認;不能存取就要清單,絕不虛構結果 |
| 僅憑檔案名稱/大小/時間就判定重複 | 只作候選;必須 hash 確認 |
| 一上來就對所有檔案做 hash | 先目錄一致性篩選,再對候選 hash |
| 報告還沒出就建議刪除/換連結 | 先出報告、等明確確認;腳本不執行破壞性動作 |
替使用者決定 uncertain 項 | 把不確定項作為問題拋回給使用者 |