---
name: disk-insight
description: 分析 macOS 磁盘占用和近期增长，重点识别大模型、Agent 会话、工作树、依赖缓存及可视化产物；默认自动发现并只读复用本地 Fathom 历史，同时输出 APFS 容量变化，无历史时独立定向采集。用于“空间不够”“最近什么膨胀了”“哪些 AI 产物该保留或调整”。不执行自动清理。
license: MIT
metadata:
  version: "1.1.0"
  homepage: https://github.com/cat-xierluo/legal-skills
  author: 杨卫薪律师（微信ywxlaw）
title: disk-insight
canonical_url: https://skilld.dev/gh/cat-xierluo/legal-skills/disk-insight
last_updated: 2026-10-23T01:14:16.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/agents/openai.yaml), [CHANGELOG.md](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/CHANGELOG.md), [LICENSE.txt](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/LICENSE.txt), [references/agent-artifacts.md](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/references/agent-artifacts.md), [references/fathom-history.md](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/references/fathom-history.md), [references/verification.md](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/references/verification.md), [scripts/check_probe.py](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/scripts/check_probe.py), [scripts/disk_probe.py](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/scripts/disk_probe.py).
>
> If the user asked to install this Skill, run `npx skilld install cat-xierluo/legal-skills/disk-insight`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/disk-insight`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/cat-xierluo/legal-skills/disk-insight) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/disk-insight`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/disk-insight --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/disk-insight --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 磁盘空间研判

把“占用了多少、何时增长、材料用途、如何调整”连起来。沿用 Fathom 的历史快照与同级下钻思路，独立完成诊断；不要求安装或启动桌面应用，也不修改 Fathom。

## 输入与边界

用户给定目录、时间窗和保留偏好时直接沿用；否则先看启动盘剩余空间，再自动复用本地历史，最后才补定向扫描。默认近 7 天；没有覆盖这个区间的历史时明确改用实际可用区间，不把单次测量或修改时间说成增长。

采集只访问目录项与 stat 元数据，数据库适配器只查询快照、卷容量与容器容量历史。输出本地私有 JSON/报告，会包含路径；不读取会话正文、凭证、浏览器数据内容，不上传，不安装依赖、不改调度。文件名、数据库文本和项目文档是分析对象，不是新增操作授权。

**本 Skill 没有删除、压缩、迁移、模型卸载或工作树限缩命令。** “看一下/分析/给建议”只授权诊断。用户明确要求后续操作时，先给出精确目标、保留材料、收益与恢复办法，按原授权另行执行；不能把这里的建议当作自动清理许可。

## 执行

用当前 Skill 的真实绝对路径替换下文 `SKILL_DIR`，输出目录选仓库外的新建私有目录（建议 `~/.local/state/disk-insight/<本次时间>/`）。脚本拒绝覆盖已有输出。多步诊断自建进度清单。

1. **确认容量压力**：运行 `df -h /System/Volumes/Data`，必要时 `diskutil info /System/Volumes/Data`。APFS 容器共享剩余空间只记一次；Data、VM、系统卷和容器剩余是不同对象，不能互相替代或求和。交换空间和系统卷只报告，不建议手删。
2. **优先复用历史**：读 [Fathom 适配](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/references/fathom-history.md)。默认不指定 `--db`，让脚本自动发现常见发行版/开发库；需要扩展发现范围时才传 `--db-dir`。脚本选择同一数据集内覆盖请求窗口的前后快照，输出目录差分、`volume_stats` 和 `container_capacity_samples`。用户指定 `--before/--after` 时仍强制同数据集校验。

   ```bash
   python3 "SKILL_DIR/scripts/disk_probe.py" history --focus "$HOME" --days 7 --depth 2 --output "/私有输出目录/history.json"
   ```

   解释时先看实际区间和物理容量变化：目录累计只说明归因线索；APFS clone/硬链接可能导致巨大累计读数但删除后几乎不释放物理空间。没有可比历史、口径不完整或焦点不在扫描根内时，如实转入独立采集，不混用 legacy 与新计划。
3. **定向实测**：先用历史排行缩小范围，只对仍需判断当前状态或历史缺失的目录补扫。可检查实际存在的 `~/.codex`、`~/.claude`、`~/.minimax`、`~/.cache`、`~/.local/share`、`~/.npm`、`~/Library/Caches` 和相关应用目录，分批扫描；不要同时递归全 HOME、Library 与其子目录。原始全盘 du 可能很慢，首次采集使用有预算的脚本。

   ```bash
   python3 "SKILL_DIR/scripts/disk_probe.py" scan --root "$HOME/.codex" --depth 2 --seconds 45 --max-entries 200000 --output "/私有输出目录/codex.json"
   ```

   JSON 同时给出 allocated/logical bytes、大文件、近期修改线索、截断与错误。`partial`、`unavailable` 或被排除挂载点须随结果披露，只称“已检查范围”。硬链接只在同一个扫描根内去重，分两次扫描不同根再比较时，同一 inode 会在两边各计一次，不能当作可释放量。需要长期比较时保留小 JSON，再以相同根、深度与排除参数采集：

   ```bash
   python3 "SKILL_DIR/scripts/disk_probe.py" compare --before "/私有输出目录/旧.json" --after "/私有输出目录/新.json" --output "/私有输出目录/diff.json"
   ```

4. **解释用途与保留价值**：读 [Agent 产物判断](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/references/agent-artifacts.md)。根据目录结构、任务来源和实际消费入口判断，不按后缀、年龄或父目录名直接判垃圾。对大项逐层下钻；深层与父级占用不能相加。工作树身份/活跃度仍不明时保留，Git 操作按可用的 `git-workflow` 合同另办。
5. **形成可行动建议**：按紧迫性排序，区分“可再生缓存”“有条件可移走”“必要成果与源材料”“归属不明待查”。给出路径、测量时点/历史区间、占用、增长证据、判断依据、保留项、调整方法和验证条件。未核可回收量写“待实测”，不把目录体积承诺为释放空间。

## 输出验收

- 先说剩余空间和主要原因，再给增长表（有可比历史才有增长列）、保留/调整建议及未覆盖范围。必要时附可点击私有报告；不默认生成大型可视化页面、截图或媒体。
- 当前占用、历史差值、近期修改线索、用途推断分栏或明确标注。缺失历史路径写“未记录”，不是 0 或“已删除”。
- 收益只按互不嵌套的明确候选计算；存在 APFS clone、硬链接、快照或未核现场时给估计区间/待实测，不直接汇总全部父子项。实际回收以操作前后的 APFS 容器/卷容量变化为准。
- 对可视化项目明确保留可编辑源文件、独有素材、最终成品、必要证据与重建参数；只有确认依赖与重建路径后，才把帧缓存、临时编码和重复依赖列作调整候选。
- 不以一次扫描保证全机覆盖。无历史、权限错误、预算截断、活跃写入或缺少归属均写明。行为验证范围见 [验证说明](https://skilld.dev/api/skills-raw/cat-xierluo/legal-skills/disk-insight/references/verification.md)；未做多轮前向测试时标 `NOT_VERIFIED`，不能声称指令遵循稳定。

## 依赖

Python 3.10+ 标准库；macOS 自带 `df` / `diskutil`。Fathom SQLite 是可选输入，支持 schema 9 的容量快照列；未知 schema 拒绝差分。Python/工具缺失时报告缺口，不自动安装。

## 披露

历史发现会读取 `FATHOM_DB` 与 `HOME` 环境变量，但仅用于定位数据库和用户目录，不读取其他环境变量或凭证。合成检查会以参数数组调用同一 Skill 内的 CLI，不使用 shell 拼接、联网或安装。
