1实现原理 · 为什么它能做到
四步流水线：只读扫描 → agent 分级分析 → 生成交互式 HTML 报告 → 在对话里给结论先行摘要；扫描与报告分离，中间产物是一份 JSON。
storage-analyzer/SKILL.md
对 macOS 做一次只读存储分析，产出交互式 HTML 报告。流程：扫描 → 分析分级 → 生成网页 → 打开。
扫描器全部只读：只跑 df/du/diskutil/stat/ls 与 os.scandir，绝不写盘；脚本 docstring 与 SKILL.md 铁律双重声明。
storage-analyzer/scripts/scan.py
STRICTLY READ-ONLY: only sizes/lists/reads metadata. Never creates, moves, or deletes anything.
注：SKILL.md 铁律同步写「只能跑扫描/统计/列目录/读元信息（df、du、diskutil、stat、ls）。绝对禁止 rm、mv、rmdir、清空回收站、改权限等任何写操作」。
扫描器自动识别系统（sys.platform）走两套目标目录：macOS 扫 home/library/caches/containers/app_support/applications/downloads/dev_caches 并用 du 算大小；Windows 扫 user_profile/appdata/temp/downloads/program_files 并用 os.scandir。
storage-analyzer/SKILL.md
- **macOS**：扫 home、library、caches、containers、group_containers、app_support、applications、downloads、dev_caches，用 `du` 算大小。 - **Windows**：扫 user_profile、appdata_local、appdata_roaming、temp、downloads、program_files(_x86)、dev_caches，用 `os.scandir` 算大小；`system.disks` 含所有盘符。
分级是「清理决策清单」而非全盘点：只把存在「要不要动它」决策的项放进三灯，正常在用应用与系统文件落到蓝色「系统及其他」。
storage-analyzer/SKILL.md
**三级分类 = 清理决策清单，不是全盘点。** 只把"存在'要不要动它'这个决策"的项放进三灯；日常在用的正常应用、操作系统本身、海量零碎小文件没有清理决策，不进三灯，它们落在磁盘条的蓝色"系统及其他"里。判定标准：
一键删除靠本地服务：server.py 起 127.0.0.1 + 随机端口 + 每会话随机 token，POST /action 才执行；静态模式（build_report.py）明确不给删除按钮。
storage-analyzer/scripts/server.py
- Bound to 127.0.0.1 only; every POST requires the session token; Host header
注：SKILL.md 同步说明「仅当用户明确只想要一份可分享/留存的只读文件时，才用静态模式（无删除按钮，因为 `file://` 打开的页面碰不到文件系统）」。
安全模型是三套白名单从严到宽：rm 仅绿灯 trash_paths；trash 允许绿灯+橙灯 trash_paths；open 另加橙灯 path 与红灯 app_paths，且全部 realpath 校验 + 必须在 $HOME 内。
storage-analyzer/SKILL.md
**安全模型——三套白名单，权限从严到宽**：`rm` 只允许绿灯 `trash_paths`；`trash` 允许绿灯+橙灯 `trash_paths`（橙灯永远不能 rm）；`open`（在文件管理器打开，非破坏性）允许上述全部 + 橙灯真实 `path`。所有请求 realpath 校验 + 必须在 $HOME 内 + token + Host 校验，每次点击浏览器先 confirm。
删除走系统回收站 API 而非直接 rm：macOS 用 osascript 让 Finder delete（失败回退 ~/.Trash 移动），Windows 用 SHFileOperationW + FOF_ALLOWUNDO。
storage-analyzer/scripts/server.py
script = 'tell application "Finder" to delete (POSIX file %s as alias)' % json.dumps(path)
注：server.py 里 _trash_windows 通过 ctypes 调 shell32.SHFileOperationW 并带 FOF_ALLOWUNDO；hard_delete（shutil.rmtree/os.remove）只对白名单内路径生效。
橙灯只准移废纸篓（可逆），红灯干脆不给删除按钮、只给「在文件管理器打开」——这是对「有决策但不建议手删」的显式分级。
storage-analyzer/SKILL.md
橙灯只准移废纸篓、可逆，绝不给"直接删除"）。App 托管又无安全子路径的（Chrome/微信）只给打开按钮、不给 trash_paths。按钮下方会自动写明注意事项（打开只查看不删、移废纸篓可逆需清空才释放等）；如果某项在文件管理器里是 App 内部格式、不方便手动挑选，给它一个 `open_note` 字段做客观说明（会显示在注意事项里）。**口吻要中性、像产品说明**：直接描述"这里是什么结构、为什么不好手动删、想精细操作该去哪"，不要写成"我发现/提醒注意/看着像没视频"这种暴露开发者踩坑视角的话。 - 🔴 **谨慎清理（有决策但不建议手删）**：你可能想动、但建议别手删的具体项——重复安装的应用、想卸载的大应用、运行中应用的核心数据等。给"为什么不建议手删" + `indirect_release` 写**具体卸载步骤**（自带卸载器 / 启动台长按 / 右键移废纸篓 / AppCleaner 清残留 / App Store 可重装等，要可照做不是空话）。应用项给 `app_paths`（真实 `.app` 绝对路径数组）→ 网页出现「在文件管理器打开（去卸载）」按钮，定位到 App 让用户自己正规卸载。**红灯不给删除/卸载按钮**
注：红灯项要求给 indirect_release（具体卸载步骤）与 app_paths，让用户在访达里自己正规卸载。
报告是固定阅读流的交互式 HTML：磁盘总览（分段进度条）→ Top5 → 执行建议 → 三色可折叠卡片（命令一键复制）→ 长期优化建议，即「现状→诊断→处方→操作→预防」。
storage-analyzer/SKILL.md
报告阅读流（固定顺序）：磁盘总览卡片（容量 + 进度条 + 三色容量 pills + 系统信息，纯数据）→ 占用排行 Top5 → 执行建议 → 🟢🟡🔴 三级可折叠卡片（命令一键复制）→ 长期优化建议。
Windows 支持如实标注未实测，并要求首次跑核对路径、scandir 大小与回收站删除；多盘符已支持。
storage-analyzer/SKILL.md
- **Windows**：代码已写（`scan.py` 的 `scan_windows`、`server.py` 的 `_trash_windows` 走 `SHFileOperationW`），但**未在真实 Windows 上实测**。
零第三方依赖：脚本只用 Python 3 标准库，macOS 自带 python3/du/diskutil/osascript，开箱即用。
storage-analyzer/SKILL.md
- 全部脚本是 **Python 3 标准库**，零第三方依赖（不用 pip install）。
2核心能力
01macOS/Windows 整机磁盘只读扫描（分组目录大小、Top 大户、全部盘符）
02三色分级清理决策（🟢 可自动清 / 🟡 需人工判断 / 🔴 谨慎清理）并给出可照做的处置路径
03识别「神秘大目录」：UUID 命名的 Container、隐藏目录追查到具体 App 与内容
04交互式 HTML 报告（可折叠卡片、命令一键复制、分段磁盘条、pills）
05本地点选式清理：网页上一键移废纸篓（可逆）或直接删除（🟢 项）
06静态只读报告导出（可分享/留存，不带删除能力）
07长期优化建议素材（brew cleanup、DerivedData、可视化工具、外置盘归档与系统储存优化）
08排障指引：网页上没有删除按钮 = 静态报告或绿灯漏 trash_paths
4风险提醒 风险提醒：蓝色 · 知晓即可
风险提醒：蓝色 · 知晓即可
- 绿灯硬删除不可逆，且白名单源自 agent 判断 — rm 直接走 shutil.rmtree/os.remove；若 agent 把含用户数据的目录误判成绿灯写进 trash_paths，用户点一次即永久丢失。建议默认只用「移到废纸篓」，或先跑静态报告人工过一遍分级。
- 报告服务开着=本机多了一个删除接口 — 服务绑 127.0.0.1 且有 token，但若被端口转发/代理暴露或 token 与页面一起泄露，就等同于把白名单内的删除能力交出去；用完应立即 Ctrl+C 停服（skill 也提示按钮随即失效）。
- 删除命令展示需用户自己执行，存在误操作空间 — 绿灯项的命令是「可一键复制的清理命令」，用户自行粘贴执行时若改了路径或环境不同（如 Windows 用 python 而非 python3），可能删错目标；skill 建议谨慎用 rm 且必须指向明确缓存子目录。
- Windows 分支未经实测 — scan_windows 与 _trash_windows 未在真实 Windows 验证；首次使用需自行核对目录路径、os.scandir 大小与回收站删除是否正常。
- 扫描较慢、体量感知依赖系统命令 — du -sk 逐子目录在超大目录上耗时长（SKILL.md 提示「扫描较慢，耐心等」）；读不到的目录标 denied，遗漏体量需在报告里说明，否则用户会误以为已全清。
风险提醒：蓝色，知晓即可。判级对象为本 skill 目录（SKILL.md + scripts×3 + assets/report_template.html + references×2，全部 Python 3 标准库、零依赖）。全部行为在本地：只读扫描 → agent 分级 → 生成报告 → 可选起 127.0.0.1 服务做点选清理；无公网外发、无凭证读取、无第三方包，故落蓝档（并非 green：它自带脚本、会写盘，且在用户点选后执行真实删除）。它把安全边界写得很明确：rm 仅绿灯 trash_paths、trash 允许绿灯+橙灯、open 另含红灯 app_paths，全部 realpath 校验 + 必须在 $HOME 内 + 会话 token + Host 校验 + 浏览器二次 confirm，红灯项不给任何删除按钮。注意点：硬删除不可逆、白名单质量取决于 agent 的分级输出、报告服务开着时等于本机多了一个受 token 保护的删除接口（Ctrl+C 关闭即失效）。
5第二遍独立确认
- [ok] 扫描器确实只读 — scan.py 只用 os.scandir/os.listdir/du/df/diskutil 等读取与统计；无 open(...,"w")、无 shutil.rmtree/os.remove、无 mkdir；docstring 明写 STRICTLY READ-ONLY。
- [ok] 服务侧白名单构造与文档一致 — load() 中：green.trash_paths → rm/trash/open 三集合；yellow.trash_paths 只进 trash+open；yellow.path（存在时）只进 open；red.app_paths（存在时）只进 open——与 SKILL.md「三套白名单，权限从严到宽」逐条对应。
- [ok] 删除请求的多重校验 — do_POST 依次校验：Host ∈ {127.0.0.1, localhost}、token 相等、mode ∈ {rm,trash,open}、每个 path realpath 后必须在对应白名单、且必须在 HOME 或 /Applications 之下（删除类白名单不含 /Applications）。
- [ok] 回收站删除的实现 — macOS: osascript `tell application "Finder" to delete (POSIX file ...)`，失败回退 shutil.move 到 ~/.Trash；Windows: ctypes 调 SHFileOperationW，fFlags 含 FOF_ALLOWUNDO（进回收站）。
- [ok] 无公网请求 — 全目录 URL 扫描仅命中 http://127.0.0.1:%d/（服务自述地址）；无 CDN、无遥测、无第三方 API。
- [ok] 无凭证读取 — API_KEY/token/secret 扫描：唯一 token 变量是 secrets.token_urlsafe(24) 生成的会话 token，非用户凭证；无 env 读取、无 keychain、无配置文件读取。
- [ok] 静态报告确实没有删除能力 — build_report.py 把 __DELETE_CONFIG__ 替换为 "null"；模板里的 fetch(DELETE.endpoint, ...) 只有在服务模式下注入 token/endpoint 才可用（SKILL.md 的排障段落也这么说）。
- [ok] 零第三方依赖 — 三个脚本 import 仅 json/os/secrets/shutil/subprocess/sys/time/webbrowser/http.server/re/ctypes；无 requirements/pip 指令。
6结论
适合：适合 macOS（Windows 可用但需自测）用户做一次全机存储体检：找出占空间大户、分辨哪些是可再生缓存、哪些含用户数据，并拿到一份可点击清理的交互报告。也适合把「磁盘分析 + 分级处置」沉淀成团队/客服话术（它的分级标准与口吻要求可直接复用）。
不适合：不适合 RAM/内存占用问题（description 明确排除，那是活动监视器的领域）；不适合在无人值守环境自动清理（它按设计需要用户点选与确认）；不适合对不可逆删除零容忍的场景——除非只用静态报告或只走废纸篓；Windows 生产环境建议先在测试机验证。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 storage-analyzer.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentb8b3f5bde010e27b…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库KKKKhazix / KKKKhazix/khazix-skills
原始 GitHubKKKKhazix/khazix-skills ↗
Stars20687
最近推送2026-09-13
本 skill commit
48e8ba527f许可MIT（仓库根 LICENSE，Copyright (c) 2026 数字生命卡兹克）
本站信息
收录日期2026-09-06
分类基础工具与工作流
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。