Storage Analyzer

Linux / macOS / Windows 磁盘分析清理 Skill for Claude Code

扫描 → 分级 → 交互报告 → 一键清理

---

这是什么

一个 Claude Code Skill。对你说一句"磁盘满了"或"清理空间"，它会：

1. 只读扫描整机磁盘占用（du / os.scandir，零写操作）
2. 智能分级为 🟢 可自动清理 / 🟡 需人工判断 / 🔴 谨慎清理
3. 生成交互式 HTML 报告，命令一键复制、可折叠卡片
4. 起本地服务，网页上直接点按钮移回收站或删除

适合场景：磁盘空间不够、不知道什么吃硬盘、想清理但不知道哪些能删。

注意：这是"存储空间"分析（disk storage），不是"运行内存"分析（RAM）。想知道哪个进程吃内存请用 top / htop。

截图

报告页面包含：

• 磁盘总览卡片（容量进度条 + 三色分段 + 系统信息）
• 占用排行 Top 5 表格
• 执行建议（优先级清单）
• 🟢🟡🔴 三级可折叠卡片（含清理命令、一键删除按钮）
• 长期优化建议

安装

方式一：Claude Code Skill 目录（推荐）

# 克隆到你的 skills 目录
git clone https://github.com/Autsunset/storage-analyzer.git ~/.claude/skills/storage-analyzer

装好后，在 Claude Code 对话里直接说"分析磁盘"或"清理空间"即可触发。

方式二：手动复制

把本项目放到 ~/.claude/skills/storage-analyzer/ 目录下，保持目录结构不变：

storage-analyzer/
├── SKILL.md                    # Skill 定义（触发词 + 执行流程）
├── scripts/
│   ├── scan.py                 # 只读扫描器（三平台自适应）
│   ├── server.py               # 一键删除本地服务
│   └── build_report.py         # 静态 HTML 报告生成
├── assets/
│   └── report_template.html    # 交互报告模板
└── references/
    ├── linux.md                # Linux 数据布局参考
    ├── macos.md                # macOS 数据布局参考
    └── windows.md              # Windows 数据布局参考

使用

在 Claude Code 里：

> 磁盘满了，帮我看看什么占空间
> 清理一下存储
> storage analysis
> 看下哪些东西吃硬盘

Claude 会自动执行：扫描 → 分析 → 生成报告 → 给你链接。

打开链接后：

• 🟢 绿色项：点「移到回收站」(可恢复) 或「直接删除」(立即释放)
• 🟡 黄色项：点「在文件管理器打开」跳过去自己审查
• 所有清理命令也可一键复制到终端手动执行

平台支持

平台	扫描	报告	一键删除	回收站机制
Linux	✅	✅	✅	gio trash → trash-put → FreeDesktop 规范
macOS	✅	✅	✅	osascript (Finder Trash)
Windows	✅	✅	✅	SHFileOperationW (Recycle Bin)

Linux 扫描覆盖

• 用户目录：~/.cache、~/.local/share、~/.config、~/Downloads、回收站
• 系统目录：/var/cache、/var/log、/var/lib、/usr/lib、/usr/share、/opt
• 开发缓存：pip / uv / npm / pnpm / cargo / gradle / m2 / conda / go / docker / snapd / flatpak
• 包管理器缓存：apt / dnf / pacman / zypper
• 多挂载点：自动解析 /proc/mounts，列出所有真实文件系统

安全模型

这个 Skill 的设计原则是 扫描只读、删除受控：

层级	机制
扫描阶段	绝对只读，只跑 du / df / ls / 读取元数据
删除服务	绑定 0.0.0.0 但需要随机 token + Host 校验
路径白名单	三套白名单从严到宽：rm(仅绿灯) < trash(绿+橙) < open(全部)
路径越界检查	所有操作路径必须 realpath 命中白名单 + 在 $HOME 内
橙灯保护	永远不能 rm，只能移回收站（可恢复）
红灯保护	不给删除按钮，只引导用户走正规卸载流程
浏览器确认	每次操作前 confirm() 弹窗二次确认
空闲关闭	30 分钟无请求自动停止服务

技术细节

• 零依赖：全部脚本基于 Python 3 标准库，不需要 pip install 任何东西
• Agent 驱动：不是双击即用的 App，扫描数据由 Claude 做智能分级分析
• 多设备查看：报告服务同时输出本机 URL 和局域网 URL，手机/平板也能访问

依赖

• Python 3（Linux / macOS 通常自带；Windows 需手动安装）
• Linux 回收站（可选）：gio（GNOME 自带）或 trash-cli（apt install trash-cli）

致谢

本项目基于 KKKKhazix/khazix-skills 的 storage-analyzer Skill 改编，原项目支持 macOS 和 Windows。本项目新增了完整的 Linux 适配：

• 新增 scan_linux() — 覆盖 Linux 用户目录、系统目录、开发缓存、包管理器缓存
• 新增 /proc/mounts 多挂载点检测 + /etc/os-release 发行版识别
• 新增 gio trash → trash-put → FreeDesktop.org Trash 规范三层回收站回退
• 新增 xdg-open 文件管理器集成
• 新增局域网访问支持（0.0.0.0 绑定 + 多 IP Host 校验）
• 新增 30 分钟空闲自动关闭
• 新增 references/linux.md — Linux 数据布局与分级参考

感谢 linux.do 社区提供的交流平台和技术讨论氛围。

License

MIT