清洁器
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 通用
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 中等消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows · Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第二阶段:报到并停在门口
报告观察到的值而不是推断的属性。使用`references/report_templates.md`作为长格式布局,并为每个建议的操作包含以下字段: 字段 · 必需的内容 当前状态 · 时间戳、目标身份、磁盘已用/空闲/容量和子系统状态 证据 · 命令和观察值;说明该数字是逻辑数字还是物理数字 确切的命令 · 将更改状态的命令,具有确切的目标或对象 ID
第三阶段:执行已确认的计划
紧接第一个状态更改命令之前:重新确认目标身份和当前磁盘状态。重新查询对象或子系统状态;当实时状态发生变化时,清理计划就会过期。重新检查受保护服务的运行状况。将批准的命令与即将运行的命令进行比较。任何差异都需要新的批准。
第四阶段:验证和观察
验证必须涵盖已批准计划的所有条款:重读`df -k`和`df -h`;根据读数之前/之后计算回收的空间,而不是根据删除工具的声明。重新查询已清理子系统的激活、配置和物理使用情况。重新解析每个受保护服务的 PID、侦听器、启动机制和运行状况探测。健康的磁盘并不能证明服务幸存下来。
# macOS Cleaner
Diagnose the actual source of disk pressure, reclaim only approved space, and prove that the cleanup did not damage user data or co-resident services.
## Entry router
Choose the narrowest path that can answer the request:
| User signal | Route |
|---|---|
| Apple Content Caching, `AssetCacheManagerUtil`, `CacheUsed`, `ActualCacheUsed`, iCloud cache, or “Caching needs more space” | Read `references/apple_content_caching.md` completely before probing or proposing commands |
| Docker, OrbStack, images, containers, or volumes | Read `references/docker_analysis.md`; inspect every object and never use prune-family commands |
| Docker build cache | Measure with `docker builder du`; this skill reports it but does not delete it because Docker exposes category-wide prune controls rather than per-record intent |
| A named cache, directory, application, or service is already the suspect | Inspect that target first and read the matching semantics in `references/cleanup_targets.md`; do not start a home-directory or whole-disk scan |
| The source is genuinely unknown | Use the general analysis workflow below; Mole is optional, not the universal first step |
User-provided scope exclusions override every generic scan suggestion. Do not inspect personal directories, credentials, databases, application state, or unrelated services when the user excludes them.
## Safety and authorization contract
1. **Separate observation from mutation.** Complete a read-only diagnosis first. Do not delete, stop a service, edit settings, install or upgrade tools, or run a cleanup preview that may mutate state during that phase.
2. **Confirm the exact target.** On a remote Mac, record the current host identity before any other work. Never infer the machine from an IP, old PID, directory name, or prior report.
3. **Plan before asking.** Before any state change, list every command, what it changes, expected physical space reclaimed, impact, recoverability, and postconditions. Then stop if the user requested a plan-only phase.
4. **Require explicit approval.** If the user supplies an exact confirmation phrase, require that phrase. Otherwise ask for unmistakable approval of the listed commands and targets. Approval for one plan does not authorize a fallback or a wider cleanup.
5. **Use precise supported controls.** Prefer an application's supported cache-management command or an exact object ID. If no supported control exists, an exact application-owned cache directory may be removed only after verifying its owner, confirming the application is stopped or the directory is otherwise inactive, explaining rebuild/redownload impact, and receiving approval. Never target a broad cache root or active application state.
6. **Never use Docker prune-family commands.** This includes image, container, volume, system, builder, and buildx prune. Category-wide deletion cannot express per-object user intent.
7. **Avoid broad destructive shell forms.** Do not recommend or execute broad `rm -rf` or glob deletion. For exact approved ordinary files, prefer Finder Trash. The bundled legacy helper permanently deletes and has only the limited guards documented below; never treat it as equivalent to Trash.
8. **Preserve valuable state.** Never target user documents, credentials, SSH material, active databases, application configuration, or running-service state merely to increase the reported savings. Read `references/safety_rules.md` before any file deletion.
9. **Execution follows the user's authorization.** If the user asks only for analysis or wants to run commands personally, hand off the commands. If the user asks the agent to fix the machine and explicitly confirms the scoped plan, execute the exact approved commands and verify them. Unattended recurring deletion logic needs separate approval before it is written or enabled.
10. **Fail fast.** A non-zero command, a mismatched postcondition, an unexpected target, or a changed dependency stops the cleanup. Report the partial state; do not improvise a fallback.
## Phase contract
Use this state machine for every cleanup:
1. **Observe — read-only.** Capture identity, disk baseline, the suspected subsystem's status and configuration, physical allocation, and critical-service health.
1b. **Authorize stateful inspection when unavoidable.** If deeper evidence requires creating a temporary container, pulling an image, mounting a volume, or writing a snapshot, first finish the metadata-only observation, list the exact inspection commands and their side effects, and obtain separate approval. Inspection approval is not cleanup approval.
2. **Plan — no mutation.** Explain findings, commands, impact, recovery, expected release, and success criteria. Stop at the confirmation gate.
3. **Execute — approved scope only.** Re-read live state immediately before acting, then run each approved command separately and check its exit status and postcondition.
4. **Verify — independent readback.** Measure disk space and subsystem state again, recheck protected services, and observe long enough to detect immediate refill.
Do not compress phases 2 and 3 into one message. A plan printed beside a cleanup command is not a confirmation gate.
## Phase 1: read-only diagnosis
### Establish the baseline
At minimum, capture:
```bash
/bin/date "+%F %T %Z %z"
/usr/sbin/scutil --get ComputerName
/usr/sbin/scutil --get LocalHostName
/usr/bin/sw_vers
/bin/df -k /System/Volumes/Data
/bin/df -h /System/Volumes/Data
```
Use `df -k` for calculations and `df -h` for the human-readable report. Treat an extension, label, or old report as a hint until the live command confirms it.
Establish the success target before an unknown-source scan. Copy a user-supplied free-space or capacity target exactly. If the user supplied none, report the current values and ask for a target in GiB, capacity percentage, or both; do not invent one. A named-suspect diagnosis may continue without a cleanup target, but the ordered unknown-source scan cannot claim a stop condition until the target is explicit.
Keep this first phase read-only. Do not run `scripts/cleanup_report.py` yet: it creates a local state directory and snapshot file. Preserve the command output in the report instead. On a remote target, always run the direct `df` commands on that host; the local helper must not measure the controller Mac by mistake.
### Follow the named suspect before broad scans
- Query the subsystem's own status and settings.
- Measure physical allocation with a bounded `du` on the exact data path only when permissions and user scope allow it.
- Distinguish logical content size, sparse-file apparent size, purgeable space, and physically allocated bytes.
- For a suspected growing log, record exact file sizes at two or more timestamps. One large file or one recent mtime does not prove sustained growth.
- Capture the current process, listeners, launch mechanism, and supported health probe of any co-resident service the user marks as critical. Re-resolve PIDs at each checkpoint.
If the known suspect alone can meet the user's free-space target, do not scan unrelated personal or development directories “just in case.”
### General analysis when the source is unknown
Run the smallest ordered sequence that can identify enough physical space to meet the target. Stop only when candidates with supported exact actions and defensible expected physical release can meet it. Raw allocation totals, logical cache sizes, shared Docker layers, Trash moves, and unverified “potential savings” do not satisfy the stop condition.
| Order / signal | Read-only action | Stop or continue |
|---|---|---|
| 1. Always | Capture identity and `df -k/-h`; inventory user exclusions | Stop on target mismatch |
| 2. Cache/log pressure, and `~/Library/Caches` plus `~/Library/Logs` are approved read scopes | `uv run scripts/analyze_caches.py --user-only` | Stop when measured candidates can meet the target |
| 3. Developer tools are present and the script's fixed scope is approved | `uv run scripts/analyze_dev_env.py` reads Docker/package managers plus existing `~/Projects`, `~/workspace`, `~/dev`, `~/src`, and `~/code` roots | Route Docker/OrbStack findings to their dedicated reference; skip this helper when any fixed root is out of scope |
| 4. Uninstalled-app residue is plausible and its fixed roots are approved | `uv run scripts/find_app_remnants.py` reads `/Applications`, `~/Applications`, and four documented `~/Library` application-state roots | Treat every result as a candidate, never proof of abandonment; skip when that scope is not approved |
| 5. A content-bearing path is explicitly approved | `uv run scripts/analyze_large_files.py --threshold 100MB --path "<approved-path>"` | Do not substitute `~`, Downloads, Documents, or the data-volume root when no path was approved |
| 6. Still unknown after bounded checks, and the user explicitly approves Mole's fixed broad scan roots | Read `references/mole_integration.md` and use `mo analyze` through a TTY | Mole cannot accept an arbitrary path scope; skip it when approval is narrower than its documented roots |
An `<approved-path>` is an exact path the user named or explicitly accepted after its scope was described. If none exists, skip large-file and duplicate-content scanning, state that this evidence branch was not authorized, and continue with non-content-bearing evidence. Do not install or upgrade Mole during a read-only phase unless the user separately authorizes that change.
Mole's analyzer scans a fixed set that includes the home directory, application data, system libraries, applications, and volumes. Navigation inside the results does not make the underlying scan path-scoped. If that broad read scope is not approved, do not run Mole; stop with the bounded evidence already collected or ask for the missing scan authorization in the plan.
For an explicitly approved duplicate-file investigation, read the “Optional duplicate files” section in `references/cleanup_targets.md`. It is read-only and never uses an automatic-delete option.
### Docker and OrbStack
Read `references/docker_analysis.md` before reporting Docker savings. List every image, container, and volume individually; inspect references and database-like contents; use actual sparse-file allocation rather than apparent size. A resource reported as dangling is not proof that its data is worthless. Build-cache measurement is supported, but build-cache deletion is deliberately out of scope because the available Docker controls are prune-family operations.
## Phase 2: report and stop at the gate
Report observed values rather than inferred properties. Use `references/report_templates.md` for the long-form layout and include these fields for every proposed action:
| Field | Required content |
|---|---|
| Current state | Timestamp, target identity, disk used/free/capacity, and subsystem status |
| Evidence | The command and observed value; state whether the number is logical or physical |
| Exact command | The command that would change state, with the exact target or object ID |
| Change | What the command modifies or removes |
| Recoverability | Reversible command, Trash recovery, backup restore, or redownload-only |
| Expected release | Physical-space estimate with unit and assumptions |
| Service impact | User-visible effects and protected-service invariants |
| Postconditions | Values that must be true before the action is called successful |
Classify findings by consequence, not by how tempting the number is:
- **Rebuildable cache:** deletion loses only a local copy, but state the redownload or rebuild cost.
- **User decision required:** value depends on the user's workflow or ownership knowledge.
- **Preserve:** user data, credentials, database state, active configuration, or anything whose role is uncertain.
Do not call a cache “absolutely safe” merely because software can regenerate it. Regeneration time, bandwidth, authentication, and offline availability are real costs.
## Phase 3: execute the confirmed plan
Immediately before the first state-changing command:
1. Reconfirm the target identity and current disk state.
2. Re-query the objects or subsystem status; cleanup plans expire when live state changes.
3. Recheck protected-service health.
4. Compare the approved commands with the commands about to run. Any difference requires new approval.
If the approved plan includes creation of a local before/after report artifact, capture the before snapshot now, after approval and before the first cleanup command:
```bash
uv run scripts/cleanup_report.py --snapshot before
```
This writes under `~/.macos-cleaner`, so list it in the plan. It is optional and local-target only; direct `df -k/-h` readings remain the source of truth. Never run it on the controller Mac as a substitute for measuring a remote target.
Run one state-changing command at a time. Read the result before sending the next command. After each command, run the postcondition that can distinguish success from partial success.
For an exact ordinary file that is not user data, application state, a database, or a protected path, prefer a recoverable Finder Trash move after the user confirms the exact path:
```bash
/usr/bin/osascript \
-e 'on run argv' \
-e 'tell application "Finder" to delete (POSIX file (item 1 of argv))' \
-e 'end run' -- "<exact-path>"
```
Moving to Trash usually releases no physical space until Trash is emptied; state that in the plan. `scripts/safe_delete.py` is a legacy permanent-deletion helper with an interactive prompt and a limited system/credential denylist. It does not move to Trash, check every user-data root, detect open files, or independently prove reclaimed bytes. Use it only when the exact non-user-data target and irreversible deletion were explicitly approved:
```bash
uv run scripts/safe_delete.py <exact-path> [<exact-path> ...]
```
Do not use this helper for user documents, application-managed caches such as Apple Content Caching, databases, credentials, or any target whose role is uncertain.
Two narrow Finder-Trash branches remain available without weakening those exclusions:
- For an exact inactive application cache with no verified supported management control, follow the named-cache discovery/in-use protocol in `references/cleanup_targets.md`, explain the rebuild cost, and obtain explicit approval for that exact cache path.
- For duplicate files inside an exact approved user-data root, first show each duplicate set's size/hash and every path. The user must name the copy to keep and each copy to remove. Move only those confirmed files to Finder Trash; never use the permanent helper, an automatic duplicate-selection flag, `all`, a glob, or a directory-level target. Verify the source paths moved to Trash, and state that physical space is not released until Trash is separately reviewed and emptied.
## Phase 4: verify and observe
Verification must cover all clauses of the approved plan:
- Re-read `df -k` and `df -h`; calculate reclaimed space from before/after readings rather than from the deletion tool's claim.
- Re-query the cleaned subsystem's activation, configuration, and physical usage.
- Re-resolve each protected service's PID, listeners, launch mechanism, and health probe. A healthy disk does not prove the service survived.
- Observe at bounded intervals when APFS accounting can lag or the source may refill. Record each timestamp and value.
- If the free-space target is missed, stop all deletion. Begin a second read-only analysis and rank remaining sources by measured physical allocation.
Never report “fixed” when only the command exit code is known. A successful cleanup requires both the intended state and the protected invariants.
For a local target whose before snapshot was captured by the helper, generate the comparison with:
```bash
uv run scripts/cleanup_report.py --snapshot after --compare
```
## Resources
Load only the branch relevant to the current task:
- `references/apple_content_caching.md` — Apple Content Caching diagnosis, unit interpretation, supported remote controls, confirmation plan, and post-cleanup verification.
- `references/cleanup_targets.md` — cache, log, application, developer, large-file, and Time Machine target semantics.
- `references/docker_analysis.md` — per-object Docker and OrbStack analysis, database-volume safeguards, and refill root-cause diagnosis.
- `references/mole_integration.md` — TTY workflow for interactive Mole analysis and preview.
- `references/report_templates.md` — long-form general and Docker report templates.
- `references/safety_rules.md` — blocked paths, confirmation, recovery, and file-deletion safety checks.
- `scripts/analyze_caches.py` — bounded cache inventory.
- `scripts/find_app_remnants.py` — application-remnant candidates; reads its fixed Applications and `~/Library` roots, so require that scope first.
- `scripts/analyze_large_files.py` — large-file discovery inside an approved path.
- `scripts/analyze_dev_env.py` — Docker/package-manager inventory plus fixed common-project-root `.git` sizing; require that full read scope first.
- `scripts/safe_delete.py` — legacy guarded permanent deletion for exact approved non-user-data targets; it is not a Trash or recovery tool.
- `scripts/cleanup_report.py` — local-target before/after reporting for `/System/Volumes/Data` by default, with an explicit `--volume` override.
## Do not use this skill when
- The target is Windows or Linux.
- The requested action requires disabling SIP or bypassing macOS protections.
- The user asks for silent or automatic deletion without an auditable scope and confirmation gate.
- The task is only to tune application behavior and has no disk-space diagnosis or recovery goal.
章节与文件索引
按说明文件中的顺序排列。
入口路由器
安全和授权合同
阶段合约
建立基线
在广泛扫描之前追踪指定嫌疑人
文件/命令 -> AssetCacheManagerUtil · CacheUsed · ActualCacheUsed · references/apple_content_caching.md · references/docker_analysis.md · docker builder du · references/cleanup_targets.md · rm -rf
内容校验值 -> e999a4689ffe
当前原文的自动摘译,尚未人工审校。
入口路由器
选择可以响应请求的最窄路径:用户信号 · 路由 Apple 内容缓存、
AssetCacheManagerUtil、CacheUsed、ActualCacheUsed、iCloud 缓存或“缓存需要更多空间” · 在探测或提出命令 Docker、OrbStack、图像、容器或卷之前完整阅读references/apple_content_caching.md· 阅读references/docker_analysis.md;检查每个对象并且永远不要使用 prune-family 命令安全和授权合同
将观察与突变分开。首先完成只读诊断。请勿删除、停止服务、编辑设置、安装或升级工具或运行可能会在此阶段改变状态的清理预览。确认具体目标。在远程 Mac 上,在进行任何其他工作之前记录当前主机身份。切勿从 IP、旧 PID、目录名称或之前的报告推断计算机。询问之前先做好计划。在任何状态更改之前,列出每个命令、它更改的内容、回收的预期物理空间、影响、可恢复性和后置条件。如果用户请求仅计划阶段,则停止。
阶段合约
每次清理都使用此状态机:观察 - 只读。捕获身份、磁盘基线、可疑子系统的状态和配置、物理分配以及关键服务运行状况。 1b.不可避免时授权状态检查。如果更深入的证据需要创建临时容器、拉取映像、挂载卷或写入快照,请首先完成仅元数据观察,列出确切的检查命令及其副作用,并获得单独的批准。检查批准不是清理批准。
建立基线
至少,捕获:使用
df -k进行计算,使用df -h进行人类可读的报告。将扩展名、标签或旧报告视为提示,直到实时命令确认为止。在未知来源扫描之前建立成功目标。准确复制用户提供的可用空间或容量目标。如果用户未提供任何值,则报告当前值并询问以 GiB 为单位的目标、容量百分比或两者;不要发明一个。指定嫌疑人诊断可能会在没有清理目标的情况下继续进行,但有序的未知源扫描在目标明确之前无法声明停止条件。在广泛扫描之前追踪指定嫌疑人
查询子系统自身的状态和设置。仅当权限和用户范围允许时,才在确切的数据路径上使用有界的
du测量物理分配。区分逻辑内容大小、稀疏文件表观大小、可清除空间和物理分配的字节。对于可疑增长的日志,记录两个或多个时间戳处的确切文件大小。一份大文件或一份最近的 mtime 并不能证明持续增长。