前言¶
在 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。
