Macos Disk Triage

磁盘清道夫

Diagnose macOS storage pressure from the outside in. Lead with measured capacity and evidence, then separate reclaimable caches from personal or system data.

Safety contract

• Default to read-only commands. Never delete, move, truncate, empty Trash, uninstall, prune, rebuild an index, remove a snapshot, kill a process, restart, or change settings without explicit authorization for that action.
• Treat “不要删除任何东西” as a hard constraint for the entire investigation. Do not present a modifying command as if it were diagnostic.
• Never request or accept an administrator password. When root visibility is necessary, give the user an exact read-only sudo command to run in Terminal and ask them to paste the output.
• State before each diagnostic batch that it is read-only. Keep the user updated if a du scan runs longer than 60 seconds.
• Preserve the distinction between diagnosis, recommendation, and execution.
• Never bypass a platform or agent deletion safeguard with another language or tool. Do not use force-kill as a routine cache-cleaning step.
• Resolve every candidate to an exact path before proposing a mutation. Do not execute destructive commands against unresolved variables, wildcards, symlinks, or a whole application container merely because one child is cache-like.

Workflow

1. Establish physical and APFS capacity

Run the bundled collector in quick mode:

zsh scripts/collect-readonly.sh quick

Interpret all of these separately:

• Physical disk size and partitions from diskutil list physical
• Shared APFS container capacity from diskutil apfs list
• Per-volume consumption for System, Data, VM, Preboot, and Recovery
• Data-volume free space from df -h /System/Volumes/Data

Do not add df rows together; APFS volumes share one container.

2. Attribute ordinary files

Run:

zsh scripts/collect-readonly.sh home

Start with ~/Library, ~/Documents, /Applications, /Library, /private, /opt, and other users. Drill into only the largest directories. Use du -x to avoid crossing mounted filesystems.

Classify findings:

• Personal data: documents, photos, chat attachments, video, databases
• Application state: profiles, extensions, containers, offline web data
• Regenerable cache: package caches, browser cache, migration downloads
• System-managed data: Spotlight, VM/swap, snapshots, Preboot, Recovery

Avoid double counting a parent and its child when estimating reclaimable space.

3. Inventory known cache candidates

When the user asks what can be cleaned, run the cache inventory:

zsh scripts/collect-readonly.sh caches

Read references/cache-map.md before assigning a safety grade. Treat the map as decision support, never as authorization. Use three grades:

• Low risk: reproducible cache with a native cleanup mechanism and no account or document state
• Caution: cache adjacent to offline data, sessions, profiles, messages, containers, or active project state
• Do not touch: credentials, databases, settings, user-created content, or an unknown path

For paths absent from the map, identify the owning application and verify the directory semantics from authoritative documentation or source. If uncertainty remains, report it as unknown and do not propose deletion.

4. Reconcile unexplained space

Compare APFS Data volume usage with the top-level du total. If the gap is material, check in this order:

1. Local snapshots: tmutil listlocalsnapshots / and diskutil apfs listSnapshots diskXsY
2. Deleted-but-open files: lsof +L1
3. VM/swap and current pressure: memory_pressure -Q, sysctl vm.swapusage, and /System/Volumes/VM
4. Protected root-owned directories

For a root-visible top-level total, ask the user to run:

sudo du -x -h -d 1 /System/Volumes/Data 2>/dev/null | sort -h | tail -n 30

This command is read-only. Explain that Full Disk Access does not replace Unix root privileges.

5. Investigate Spotlight when large or slow

Run:

zsh scripts/collect-readonly.sh spotlight

If .Spotlight-V100 needs root visibility, ask the user to run the read-only commands in references/interpretation.md. Diagnose duplication, shard accumulation, cache/journal growth, status inconsistency, and the collector's timed exact-name query responsiveness.

Strong evidence of an unhealthy index includes several signals together: index size disproportionate to indexed data, hundreds of accumulated shards, large postings/positions tables, mdutil state inconsistent with its configuration, and exact-name searches taking many seconds.

Do not manually remove .Spotlight-V100. If rebuilding is appropriate, explain that it replaces Spotlight metadata rather than personal files, list temporary effects, and wait for explicit authorization. Prefer Apple’s Spotlight Privacy add/remove workflow.

After the user triggers a rebuild, verify:

• Free space rises when the old index is retired
• mdutil -s changes from disabled to enabled after the disk is removed from Privacy
• mdsync, mds, mds_stores, and mdworker activity indicates rebuilding
• High CPU and incomplete search results are expected temporarily

6. Interpret swap without mislabeling it as junk

Explain that swap is SSD-backed virtual memory created when RAM pressure rises. Judge it with memory pressure and workload, not its existence alone. Do not delete swapfiles manually.

On a 16 GB Mac, sustained multi-gigabyte swap plus many browser, agent, and Electron processes can consume substantial disk. Closing workload or restarting may reclaim it, but both are actions requiring user authorization.

7. Report and propose next steps

Lead with a compact accounting table or list:

• Actual usable container capacity
• Data, VM, System, Preboot, Recovery, and free space
• Largest confirmed directories
• Unexplained gap, if any
• Safely reclaimable estimate versus personal-data choices

Label inferences explicitly. For each proposed action state expected recovery, risk, reversibility, prerequisites such as quitting an app, and whether it touches personal data. Ask for separate confirmation before executing any modification.

If the user explicitly authorizes cleanup:

1. Restate the exact selected paths, measured sizes, consequences, and expected recovery.
2. Ask the user to save work and quit the owning application; do not force-kill it unless the user separately authorizes that escalation.
3. Prefer the application’s storage manager or official cache command. For user-owned cache paths, prefer a recoverable move to Trash when practical.
4. Re-resolve and validate each target immediately before acting. Stop on path mismatch, symlink ambiguity, ownership uncertainty, or unexpected contents.
5. Re-measure the exact target and Data-volume free space. Report actual recovery and regeneration cost.

Authorization to clean one path does not authorize adjacent directories, all items in the same grade, or a broader cleanup pass.

Detailed interpretation

Read references/interpretation.md when diagnosing APFS accounting gaps, Spotlight internals, swap pressure, or choosing thresholds and remediation language.

Read references/cache-map.md only when evaluating or planning cache cleanup.