前言¶
在 macOS 上排查磁盤空間，常見做法是新開 Terminal 敲 du -sh *、find ~ -size +500M，再配一個第三方清理工具。問題是前者只有數字，看不到目錄之間的比例關係；後者往往一鍵清掃，刪的是什麼、能不能放回，自己並沒有真正過一遍。
dsh-disk-ops 是給 DeepSeek Harness（DSH）Desktop 寫的本機磁盤空間插件，用一個面板回答三個問題：空間去哪了、能清什麼、清了安全嗎。它把佔用可視化（treemap）、規則化建議和「計劃 → 確認 → 移入廢紙簍」的清理流程連成一份數據，命令與 agent 工具是輔助入口。
下面按定位、功能、安裝、用法、注意事項的順序介紹，所有命令與字段均來自倉庫 README。
這是什麼¶
- 插件名稱：
dsh-disk-ops - 倉庫：https://github.com/aiml-kiki/dsh-disk-ops
- 社區目錄頁：https://www.skillhub.cn/plugins/aiml-kiki/dsh-disk-ops
- 維護者：aiml-kiki
- 分類：客戶端（Client / Bundle）
- 許可證：MIT
- 運行環境：
darwin專屬；engines要求node >=22、dsh >=0.2.1-rc.2
它定位爲客戶端 bundle：通過 cordis.patch.yml 注入 Host，通過 @deepseek-ai/dsh-client-ui-slots 注入側欄與面板，同時提供 dsh-disk 命令行入口。
核心功能¶
1、treemap 看佔用並下鑽
左側欄「磁盤空間」圖標進入全寬主面板，兜底入口是設置 → 磁盤空間。treemap 中色塊面積即佔用：懸浮看路徑、大小、佔本層比例；單擊下鑽一層；雙擊用 open -R 在 Finder 中顯示；麪包屑或 Esc 返回。樹圖下方接大文件 Top 10，右側列表跟隨當前目錄，列出本層的目錄與文件。
2、規則驅動的清理建議
右側列表命中 rules.json 的項纔打「安全/謹慎」tag。規則由 kind（prefix / children / ext）、path、safety（safe | probably | risky | irreversible）與 action（trash | report | trash-empty）組合，另有 ignore 與 neverDelete 兩欄做保護。
3、清理走計劃與確認，不直接刪
勾選任意項後點「清理」只生成計劃卡片（條目數、總大小、10 分鐘有效），不會刪文件；點「確認」才逐條複覈 inode/size/mtime 並移入廢紙簍。刪除默認用 osascript 調 Finder 走廢紙簍，失敗回退 mv ~/.Trash，默認可放回。永久刪除只有 trash-empty 一條路徑，且必須輸入當前廢紙簍條目數。
4、三個區域共享同一份數據
建議、treemap、大文件不是三個互不相干的列表：懸浮建議行會高亮它在當前層的所屬色塊；色塊右上角「×」對當前色塊發起手動刪除計劃；建議行「↗」跳到該項父目錄並高亮；大文件的「定位」同樣跳到父目錄。切層時建議與大文件自動回到當前層。
5、緩存優先，不空屏等 du
打開面板先展示 24 小時內的緩存層，過期數據在後臺刷新；掃描當前層時舊圖變暗並提示，避免界面卡在掃描上。
6、權限最小化
不申請全盤訪問（FDA）、永不 sudo；~/Library/Containers、Group Containers、Mail、Safari 等 TCC 目錄顯示體積但不展開，不會彈系統授權框。審計寫入 audit.ndjson（追加寫，5MB 輪轉 ×3），記錄時間、原路徑、大小、動作、落點與批次。
安裝與啓用¶
倉庫提供三種安裝方式，都是通過 DSH 的插件管理器安裝 bundle，不是 dsh plugin add。
本地源碼構建（先構建，再裝目錄）：
cd disk-ops
node scripts/build-client.mjs # 可選：只重建 client
node scripts/install.mjs --dist # 生成 dist/<hash>/ 與 cordis.patch.yml
plugin_manager install_bundle target="$PWD"
已安裝同版本時先 remove_bundle 再 install_bundle；Client 改動需要刷新一次頁面（Host 改動需重裝 bundle，因爲 ESM 緩存；install.mjs 用內容哈希生成 dist/<rev>/ 正是爲了避免舊模塊被緩存）。
GitHub Release（README 標註「當前可用」，版本 v0.1.2）：
plugin_manager install_bundle target="https://github.com/aiml-kiki/dsh-disk-ops/releases/download/v0.1.2/dsh-disk-ops-0.1.2.tgz"
npm registry：
plugin_manager install_bundle target="dsh-disk-ops"
plugin_manager install_bundle target="dsh-disk-ops@0.2.0" registry="https://registry.npmjs.org"
需要說明的是，npm registry 的 dist-tags.latest 當前是 0.1.2（發佈於 2026-11-05，維護賬號 pasonwang）；README 中的 @0.2.0 精確版本寫法以倉庫最新發布爲準，安裝前建議先確認該版本在 registry 上確實存在。
插件發現入口是社區目錄 / 插件市場索引：把 market/index.json 的 HTTPS 地址加到 Settings → Plugin Market 即可搜索安裝；常見做法是向 awesome-dsh-plugin 倉庫提交一個 YAML（dsh-market 與 dshmarket.com 都從它生成）。目錄頁本身是第三方社區站點，與 DeepSeek / 幻方無官方從屬關係。
典型用法¶
安裝後在 DSH 會話中直接用 /disk 前綴的命令：
/disk scan [path] [--refresh] # 一層目錄 + 建議
/disk big [--min 100MB] # 大文件 Top
/disk status # 容量與數據目錄
/disk rules # 規則表
/disk clean # 生成清理計劃（不刪除）
/disk clean --confirm <token> # 執行該計劃（移入廢紙簍）
/disk trash-empty --confirm <count> # 永久清空廢紙簍，需輸入當前條目數
dsh-disk <同上> # 不帶 DSH 的 CLI
agent 側有兩個工具：disk_scan（只讀）與 disk_clean（plan → commit 兩段式，commit 會彈用戶確認）。也就是說給 agent 調用時，刪除仍然要過一次人工確認。
規則是可選配置，放在 $DSH_HOME/disk-ops/rules.json。倉庫給出的示例：
{
"ignore": ["~/Library/Caches/keep-me"],
"neverDelete": ["~/Development/precious"],
"rules": [
{
"id": "my-builds",
"category": "自建產物",
"kind": "prefix",
"path": "~/src/build",
"safety": "probably",
"action": "trash"
}
]
}
kind 中 ext 類型按擴展名匹配，配合 dirs / exts / minAgeDays 使用，適合做「超過 30 天的日誌文件」這類規則。不寫 rules.json 時，面板裏仍可手工勾選任意項清理，只是那些項不帶安全 tag，走手動計劃並明確提示「不在規則內」。
配套目錄結構：
$DSH_HOME/disk-ops/
├── rules.json # 可選：rules / ignore / neverDelete
├── audit.ndjson # 追加寫，5MB 輪轉 ×3
└── cache/ # 每層掃描緩存，24h；過期也先展示，再後臺刷新
適用場景與注意¶
適合的場景：日常用 DSH Desktop 的 macOS 用戶，想把家目錄的佔用、緩存與可清理項放進工作界面一起看，同時不想給第三方工具全盤訪問權限；也適合想讓 agent 有受控的磁盤清理能力、但刪除動作必須經人確認的自動化流程。
需要注意：
1、插件以當前 DSH 進程的權限運行，刪除範圍限制在家目錄內、規則命中、非保護路徑；路徑先規範化再 realpath，越界即拒。安裝任何第三方插件前都應自己讀一遍源碼與許可證（本項目爲 MIT），尤其是要確認 rules.json 裏的路徑不會誤傷 neverDelete 之外的工作目錄。
2、社區目錄當前記錄星標爲 0，屬於很新的項目，先讀 DESIGN.md 理解設計取捨再投入日常使用更穩妥。
3、體積按 du 的實際佔用塊計算，APFS 克隆共享塊會重複計，不做克隆去重。
4、沒有全盤訪問時，~/Library 內部分目錄不可讀，報告會標「部分結果」。
5、首次掃描未緩存的深層目錄可能花數秒（預算 8s，超時標 partial）；osascript 首次使用可能觸發「控制 Finder」的自動化授權，拒絕後自動回退 mv。
6、trash-empty 是唯一的永久刪除路徑，執行前需要輸入廢紙簍當前條目數，屬於有意的二次確認，不要把它當常規清理手段。
結尾¶
dsh-disk-ops 的價值不在又多了一個清理器，而在於把「看佔用」和「刪東西」放在同一條可審計的路徑上：先看到空間分佈，再按自己的規則生成計劃，最後人工確認後走廢紙簍，每次操作留痕。命令、agent 工具與面板共享同一份當前目錄數據，日常排查和自動化都能用上。
項目地址：GitHub，社區目錄頁：skillhub.cn。
