Preface¶

Troubleshooting disk space on macOS typically involves opening a new Terminal and typing du -sh *, find ~ -size +500M, then pairing it with a third-party cleanup tool. The problem is that the former only shows numbers, making it hard to see proportional relationships between directories; the latter often performs one-click sweeps where you don’t actually review what is being deleted or if it can be restored.

dsh-disk-ops is a local disk space plugin for DeepSeek Harness (DSH) Desktop. It uses a panel to answer three questions: Where did the space go? What can be cleaned? Is it safe? It connects visualization (treemap), rule-based suggestions, and the “Plan → Confirm → Move to Trash” cleanup workflow into a single dataset, with command-line and agent tools serving as auxiliary entry points.

Below, the introduction follows the order of positioning, features, installation, usage, and notes. All commands and fields are sourced from the repository README.

What is this¶

• Plugin Name: dsh-disk-ops
• Repository: https://github.com/aiml-kiki/dsh-disk-ops
• Community Directory Page: https://www.skillhub.cn/plugins/aiml-kiki/dsh-disk-ops
• Maintainer: aiml-kiki
• Category: Client (Client / Bundle)
• License: MIT
• Runtime Environment: darwin exclusive; engines requires node >=22 and dsh >=0.2.1-rc.2

It is positioned as a Client Bundle: injected into the Host via cordis.patch.yml, and into the sidebar and panel via @deepseek-ai/dsh-client-ui-slots, while providing a dsh-disk command-line entry.

Core Features¶

1. Treemap for visualization and drill-down

Enter the full-width main panel from the “Disk Space” icon in the left sidebar; the fallback entry is Settings → Disk Space. In the treemap, the area of the color block represents usage: hover to see the path, size, and percentage of the current level; click to drill down one level; double-click to display in Finder using open -R; use breadcrumbs or Esc to return. Below the treemap is the Top 10 Big Files list, and the right-side list follows the current directory, listing directories and files of the current level.

2. Rule-driven cleanup suggestions

Items in the right-side list are only tagged as “Safe/Prudent” if they match entries in rules.json. Rules are composed of kind (prefix/children/ext), path, safety (safe | probably | risky | irreversible), and action (trash | report | trash-empty), with additional ignore and neverDelete fields for protection.

3. Cleanup follows a plan and confirmation process, not immediate deletion

After checking any item and clicking “Clean”, only a plan card is generated (item count, total size, valid for 10 minutes); files are not deleted. Only clicking “Confirm” performs inode/size/mtime checks one by one and moves them to the Trash. Deletion defaults to using osascript to trigger Finder’s Trash, falling back to mv ~/.Trash on failure, and is generally recoverable. Permanent deletion only exists via the trash-empty path, and the current number of Trash items must be entered.

4. Three areas share the same dataset

Suggestions, Treemap, and Big Files are not three independent lists: hovering a suggestion line will highlight its corresponding color block in the current level; the “×” in the top-right corner of a color block initiates a manual deletion plan for that block; the “↗” in a suggestion line jumps to the item’s parent directory and highlights it; “Locate” in Big Files also jumps to the parent directory. When switching levels, suggestions and Big Files automatically return to the current level.

5. Cache-first, no blank screen waiting for du

When the panel opens, it first displays the cached layer from the last 24 hours; expired data is refreshed in the background. When scanning the current level, the old image dims and prompts, avoiding the interface from getting stuck on scanning.

6. Minimal permissions

It does not request Full Disk Access (FDA) or ever use sudo; ~/Library/Containers, Group Containers, Mail, Safari, and other TCC directories show size but are not expanded, so no system authorization popups appear. It audits writes to audit.ndjson (append-only, 5MB rotation ×3), recording timestamp, original path, size, action, destination, and batch.

Installation and Enablement¶

The repository provides three installation methods, all installing the bundle via DSH’s plugin manager, not dsh plugin add.

Local Source Build (build first, then install directory):

cd disk-ops
node scripts/build-client.mjs      # Optional: rebuild client only
node scripts/install.mjs --dist    # Generates dist/<hash>/ and cordis.patch.yml

plugin_manager install_bundle target="$PWD"

If the same version is already installed, run remove_bundle before install_bundle; Client changes require a page refresh (Host changes require reinstalling the bundle due to ESM cache; install.mjs generates dist/<rev>/ using content hash to avoid old module caching).

GitHub Release (marked as “Currently Available” in README, version 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"

It is worth noting that the dist-tags.latest on the npm registry is currently 0.1.2 (published on 2026-11-05, maintainer account pasonwang); the exact version syntax @0.2.0 in the README follows the latest release in the repo. It is recommended to confirm that the version exists on the registry before installing.

The plugin discovery entry is the community directory / plugin market index: add the HTTPS address of market/index.json to Settings → Plugin Market to search and install; the common practice is to submit a YAML file to the awesome-dsh-plugin repository (both dsh-market and dshmarket.com generate from it). The directory page itself is a third-party community site with no official affiliation with DeepSeek or Inference Power.

Typical Usage¶

After installation, use commands with the /disk prefix directly in a DSH session:

/disk scan [path] [--refresh]      # One directory level + suggestions
/disk big [--min 100MB]            # Top big files
/disk status                        # Capacity and data directories
/disk rules                         # Rules table
/disk clean                         # Generate cleanup plan (no deletion)
/disk clean --confirm <token>       # Execute plan (move to trash)
/disk trash-empty --confirm <count> # Permanently empty Trash, requires current item count
dsh-disk <same as above>             # CLI without DSH

There are two tools on the agent side: disk_scan (read-only) and disk_clean (two-stage plan → commit, commit prompts for user confirmation). This means when called by an agent, deletion still requires one round of human confirmation.

Rules are optional configuration, placed in $DSH_HOME/disk-ops/rules.json. The example provided in the repo:

{
  "ignore": ["~/Library/Caches/keep-me"],
  "neverDelete": ["~/Development/precious"],
  "rules": [
    {
      "id": "my-builds",
      "category": "自建产物",
      "kind": "prefix",
      "path": "~/src/build",
      "safety": "probably",
      "action": "trash"
    }
  ]
}

The ext type in kind matches by file extension, used with dirs / exts / minAgeDays, suitable for rules like “log files older than 30 days”. When rules.json is not written, items can still be manually checked for cleanup in the panel, but those items won’t have a safety tag and will proceed as manual plans with a clear prompt “Not in rules”.

Corresponding directory structure:

$DSH_HOME/disk-ops/
├── rules.json      # Optional: rules / ignore / neverDelete
├── audit.ndjson    # Append-only, 5MB rotation ×3
└── cache/          # Per-layer scan cache, 24h; expired are shown first, then refreshed in background

Suitable Scenarios and Notes¶

Suitable scenarios: macOS users using DSH Desktop daily who want to view home directory usage, cache, and cleanable items together in the work interface, without giving third-party tools Full Disk Access permissions. Also suitable for users who want agents to have controlled disk cleaning capabilities but require human confirmation for deletion actions in automation workflows.

Things to note:

1. The plugin runs with the permissions of the current DSH process; deletion scope is limited to the home directory, rules hits, and non-protected paths; paths are normalized before realpath, and out-of-bounds requests are rejected. Read the source code and license yourself before installing any third-party plugin (this project is MIT), especially to ensure paths in rules.json don’t accidentally harm working directories outside neverDelete.
2. The community directory currently shows 0 stars; it is a very new project. It is safer to read DESIGN.md to understand design trade-offs before daily use.
3. Volume is calculated based on actual disk usage blocks by du. APFS clones sharing blocks are counted multiple times; clone de-duplication is not performed.
4. Without Full Disk Access, some directories inside ~/Library are unreadable, and reports will be marked “Partial Results”.
5. First scan of deeply uncached directories may take several seconds (budget 8s, timeout marks partial); osascript may trigger a “Control Finder” automation authorization for the first time, falling back to mv if rejected.
6. trash-empty is the only permanent deletion path; you must enter the current number of Trash items before execution. This is an intentional double confirmation and should not be treated as a regular cleanup method.

Conclusion¶

The value of dsh-disk-ops lies not in having another cleaner, but in putting “viewing usage” and “deleting things” on the same auditable path: first see the space distribution, then generate a plan based on your own rules, and finally move to Trash after human confirmation, leaving a trace for every operation. Commands, agent tools, and panels share the same current directory data, usable for both daily troubleshooting and automation.

Project URL: GitHub, Community Directory Page: skillhub.cn.