- name
>
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add KKKKhazix/khazix-skills --skill storage-analyzer -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add KKKKhazix/khazix-skills --skill storage-analyzer -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add KKKKhazix/khazix-skills --skill storage-analyzer -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add KKKKhazix/khazix-skills --skill storage-analyzer -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/KKKKhazix/khazix-skills/tree/HEAD/storage-analyzerFrom the publisher
对 macOS / Windows / Linux 做一次只读存储分析,产出交互式 HTML 报告。流程:扫描 → 分析分级 → 生成网页 → 打开。
从宿主当前加载的 Skill 位置取得实际绝对目录并设为 STORAGE_SKILL_DIR;每个新 shell 都要重新赋值。输出写入当前任务的工作目录,脚本使用带引号的绝对路径:
python3 "$STORAGE_SKILL_DIR/scripts/scan.py" > storage_scan.json
scan.py 自动识别系统(sys.platform):
du -x 算大小(不跨卷)。挂载点会被跳过并写进 warnings,例如 Xcode 的 ~/Library/Developer/CoreDevice/DeviceFS:它是模拟器/设备文件系统的虚拟挂载,显示几十 GB 但不占本盘空间,不要当成清理项。二次深入查看时同样用 du -x。os.scandir 算大小;system.disks 含所有盘符。.cache、.local/share、downloads、/var、/tmp、dev_caches(pip/uv/cargo/npm/go/docker/snap 等),用 du 算大小,不跳过挂载点(ZFS 数据集、btrfs 子卷和本盘同池);system.disks 来自 GNU df,按 ZFS 池或设备合并,主盘是装着 / 的那个(解析失败时降级为根分区信息)。输出 JSON:system(系统/磁盘信息,含 disk_name 主盘名 + disks 全部盘)+ groups(各组子目录大小,已降序、过滤 50MB 以下)。Windows 同次扫描复用子目录统计,避免重复遍历。顶层分组存在父子包含关系,不能直接相加;可释放空间还受硬链接、压缩和回收站保留影响。读取 warnings,把其中没读全的路径写进分析结果的 denied(报告只渲染 denied,不渲染 warnings);被跳过的挂载点在 summary.overview 或对话摘要里说明。读不到的目录标 denied,需在报告里列出并提示遗漏体量。
Windows 使用 py -3 或 python;在 PowerShell 用 py -3 "$STORAGE_SKILL_DIR/scripts/scan.py" | Out-File -Encoding utf8 storage_scan.json,后续 JSON 读取支持 UTF-8 BOM。PowerShell 同样先设置 $STORAGE_SKILL_DIR 为实际绝对目录。
先看 system.os 判断系统,读对应的数据布局参考:macOS 读 references/macos.md,Windows 读 references/windows.md,Linux 读 references/linux.md(讲该系统东西存哪、怎么辨认、归哪一级)。然后读 storage_scan.json 做这几件事:
ls/du 深入一层看清楚,但仍只读。.Downloads 目录、旧备份目录),给它 trash_paths → 网页出现「移到废纸篓」按钮。橙灯只准移废纸篓(可逆),绝不给"直接删除"。App 托管又无安全子路径的(Chrome/微信)只给打开按钮、不给 trash_paths。open_note 字段做客观说明(会显示在注意事项里)。口吻要中性、像产品说明:直接描述"这里是什么结构、为什么不好手动删、想精细操作该去哪",不要写成"我发现/提醒注意/看着像没视频"这种暴露排查过程的话。indirect_release 写具体卸载步骤(自带卸载器 / 启动台长按 / 右键移废纸篓 / AppCleaner 清残留 / App Store 可重装等,要可照做不是空话)。app_paths(真实 .app 绝对路径数组)→ 网页出现「在文件管理器打开(去卸载)」按钮,定位到 App 让用户自己正规卸载。summary.long_term 长期建议。不要把项目、git worktree(包括 .git 指针文件)、项目依赖或整个开发工具目录当作缓存。Windows 二次查看大小也要排除 junction/symlink,不能只看体积或目录名判断可删。pnpm store 优先 pnpm store prune,Go 模块缓存优先 go clean -modcache;不提供整个 store、global 或工具安装根目录的删除按钮。硬链接不因删除另一条链接就失效,但也不能把逻辑大小当作一定可释放的空间。
每个 🟢 项要给:预估释放空间、清理前需关闭的进程、可一键复制的清理命令(用移到废纸篓或 App 自身清理入口的安全方式,谨慎用 rm;如用 rm 必须是明确的缓存子目录)。
大小字段写干净:size / size_estimate 用"约 14 GB""合计约 8.6 GB"即可——"约"已表示估算,不要再加"(估算)",重复且不专业(模板也会自动去掉这种冗余括号)。可再生属性已由分级标题和按钮说明覆盖,别塞进大小字段。
把分析结果以 UTF-8 写成 analysis JSON(schema 见 scripts/build_report.py 顶部注释)。其中 system 把扫描结果里的 system 对象原样照抄,不删字段:磁盘总览和多盘列表靠里面的 disk_name 和 disks 渲染,删了多盘就显示不出来。Windows PowerShell 不用默认 ANSI 写文件,用 Set-Content -Encoding utf8 或 Python 的 encoding="utf-8";已有中文变成问号的 JSON 必须从原内容重生成,换字体无法恢复丢失字符。
🟢 项必须带 trash_paths(具体可删的绝对路径数组,区别于人类可读的 path 展示字段)——这是网页删除按钮的前提,漏了按钮就不出现。
被符号链接引用的目录加 clear_contents: true:清理目标被别的路径以符号链接指着时(如 ~/.cache → ~/.dev-cache/cache),给该项加 "clear_contents": true,服务端只清空目录里的内容、保留目录本身,链接不会悬空;配套命令也只清内容(如 find <dir> -mindepth 1 -delete),不给整目录删除或移废纸篓。判断方法:ls -ld <路径> 看是不是 symlink,或 realpath <路径> 与展示路径不一致。
默认用一键删除模式(server.py)打开报告,因为这个 skill 的核心价值就是网页上能直接清理:
python3 "$STORAGE_SKILL_DIR/scripts/server.py" storage_analysis.json # 自动开浏览器,Ctrl+C 停,闲置 30 分钟自动退出
server.py 起在 127.0.0.1 + 随机端口 + 随机 token。🟢 项给「移到废纸篓」(可逆) +「直接删除」(不可逆,实际释放量以磁盘统计为准);🟡 项给「在访达打开」+(有安全子路径时)「移到废纸篓」。安全模型——三套白名单,权限从严到宽:rm 只允许绿灯 trash_paths;trash 允许绿灯+橙灯 trash_paths(橙灯永远不能 rm);open(在文件管理器打开,非破坏性)允许上述全部 + 橙灯真实 path。删除请求校验整个批次,限制在用户目录内,拒绝主目录、数据根目录、链接和项目/worktree;应用安装目录仅允许打开。所有请求 Host 校验,操作请求还校验 token,每次点击浏览器先 confirm。osascript/SHFileOperationW 入废纸篓,macOS 首次弹访达自动化授权点允许即可。
仅当用户明确只想要一份可分享/留存的只读文件时,才用静态模式(无删除按钮,因为 file:// 打开的页面碰不到文件系统):
python3 "$STORAGE_SKILL_DIR/scripts/build_report.py" storage_analysis.json storage-report.html
排障:网页上没有删除/移废纸篓按钮 = 要么开的是静态报告(改用 server.py),要么 🟢 项漏了 trash_paths(补上重启服务)。
报告阅读流(固定顺序):磁盘总览卡片(容量 + 进度条 + 三色容量 pills + 系统信息,纯数据)→ 占用排行 Top5 → 执行建议 → 🟢🟡🔴 三级可折叠卡片(命令一键复制)→ 长期优化建议。即"现状 → 诊断 → 处方 → 操作 → 预防"。
注意 summary.overview 要写成一句话洞察(直接说最大占用是什么、能释放多少),不要重复总/已用/可用数字——那些已在卡片大数字里显示。overview 渲染在"执行建议"小节开头作引子(普通文字),紧接着是 summary.priority 优先级清单。
磁盘进度条把"已用"拆成分段:绿(可自动清)+橙(需手动)+红(已识别的不建议动项)+蓝(系统及其他,自动取 已用−绿−橙−红 的余量),余下为可用(灰底)。summary.tier_stats 的 green / yellow / red 三个值都要以可解析的 GB 数字开头(如 "约 27.8 GB"),脚本从中取数算分段;蓝色段和"系统及其他"pill 由模板自动算余量。
pills 只渲染解析出的纯数字(如"约 5.5 GB"),不显示数据里的附注,所以 tier_stats 三个值写干净的数字即可,别加"仅已识别项/系统未计"这类道歉式说明——系统文件本来就归在蓝色段,红色只放你能量化的 🔴 项(重复应用、可卸载大应用等),量不准的系统文件/快照自然落到蓝色。
宿主的沙箱不允许绑定本地端口时,先按宿主的流程申请;申请不到就改用静态模式出报告,并告诉用户这次为什么没有删除按钮。
使用可终止的托管执行会话启动服务,记录进程和地址;工具等待超时不代表服务失败,先核实已有进程,不重复启动。任务结束时停止本次服务并核实端口释放;只有用户要继续使用页面才保留并说明 30 分钟空闲退出。
报告生成后,在对话里用一段话给结论先行的摘要:总可释放估算、最该先清的 2-3 项、风险最高的一项。细节让用户看网页。
python3 --version。du、diskutil、osascript 由系统提供。python 或 py -3(不是 python3)。本 skill 命令示例写的是 python3,在 Windows 上自动改用 python / py -3。du;磁盘信息用 GNU df(BusyBox/Alpine 的 df 不支持时降级为根分区信息);移废纸篓需 gio(GNOME 自带)或 trash-cli,打开文件夹需 xdg-open。scan.py 的 scan_windows、server.py 的 _trash_windows 走 SHFileOperationW),包含社区 Windows 真机反馈对应的修复;自动化验证见仓库 CI,回收站桌面交互仍需按当前机器核实。首次在 Windows 跑要核对:目标目录路径、os.scandir 大小、回收站删除是否正常。多盘符已支持(主盘分段条 + 其他盘列表)。scan_linux + gio trash / xdg-open)。仅在 Ubuntu 26.04.1 LTS + GNOME + ZFS 单机实测(扫描 / 报告 / 服务模式 / POST → gio trash → 回收站 链路验证过);依赖 GNU coreutils、GIO 或 trash-cli、xdg-open。扫描目标含 Debian 系路径(~/snap 等,无 snap 的发行版自动跳过);references/linux.md 的清理示例已标注 Debian/Ubuntu 与 Fedora/Arch 的写法差异;KDE/XFCE、无桌面、Fedora/Arch/Alpine、非 ZFS 文件系统均未实机测过;磁盘汇总对 ext4、btrfs、ZFS 和外接盘的 df 输出有回归测试。brew cleanup、Xcode DerivedData、浏览器缓存sudo apt autoremove && sudo apt clean(Fedora:dnf clean all;Arch:pacman -Sc)、journalctl --vacuum-size=200M、清 snap 旧版本、清 ~/.cache© 2026 Skills Rack.
---name: storage-analyzerdescription: >---# storage-analyzer/SKILL.mdFAQ
Download storage-analyzer/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/KKKKhazix/khazix-skills.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.