disk-insight v1.1.0A

Immutable. This exact content never changes and is served at /api/v1/blob/66e375ecea85803b.

---
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）
---

# 磁盘空间研判

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

## 输出验收

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

## 依赖

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

## 披露

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