Storage Analyzer Windows

纯 Windows 只读存储分析，交互式 HTML 报告 + 一键清理。

速览：用户说"磁盘满了" → 跑 scan.py --quick(0.3s) 看概况 → 需要详情再跑全量(9s) → 按附录A模板写分析JSON → server.py 启动交互式服务 → 自动用 preview_url 打开 → 给用户一句话摘要。全程只读扫描，交互式网页支持一键清理。

约束规则

铁律

• 全程只读扫描。 只能跑 os.scandir / shutil.disk_usage / 列目录。
• 删除命令只展示，不执行。 报告里的清理命令供用户在终端确认后运行。 即使用户在对话里说"帮我删"，也要先停下确认，不要直接代跑。
• 系统目录保护。 C:Windows 除了 Installer / Temp / SoftwareDistribution 之外不扫描不操作。
• 回收站警告。 清空回收站前必须明确告知空间释放量。
• 长路径处理。 Windows 路径 >260 字符时使用 \? 前缀。

⏸️ 确认门

Step 3 完成后，必须暂停，向用户展示：

1. Top 5 摘要（表格：排名/名称/大小/分级/一句话说明）
2. 三灯汇总（🟢 X 项约 Y GB / 🟡 X 项约 Y GB / 🔴 X 项约 Y GB）
3. 问用户："分级结果如上，是否继续生成报告？还是需要调整？"

用户同意后才进入 Step 4。 如果用户要求调整，只调用户指定的项，不要推翻全部分级。

异常处理

执行流程

Step 1 快速扫描（可选，0.5s 内）

python scripts/scan.py --quick > %TEMP%storage_scan.json

仅扫描一级子目录大小（跳过递归），大文件自动聚合显示。 适用场景：快速判断"有没有大问题"。

Step 2 全量扫描

python scripts/scan.py > %TEMP%storage_scan.json

扫描 12 组目标（详见 references/windows.md），耗时约 9-15s（SSD）。 读不到的目录标 denied。

Step 3 分析与分级

先读 references/windows.md 了解布局规则，再读扫描 JSON。

按 附录A 的 6 条检查清单逐条执行，按 附录B 的模板写出 analysis JSON。

核心决策规则（详见附录A）：

• 🟢 可自动清理 — 纯缓存/临时文件/可再生，正例：pip Cache，反例：node_modules
• 🟡 需人工判断 — 含用户数据或需判断成本，正例：WeChat Files，反例：WindowsSystem32
• 🔴 建议卸载 — 大应用/重复安装，正例：不再用的 MobileAppEngine，反例：C:Windows
• 其他 → 不展示（归蓝色）

Step 4 启动交互式服务并自动打开

使用 PowerShell Start-Process 以独立进程启动（不受 Bash 超时影响）：

Start-Process -FilePath "python" -ArgumentList "scripts/server.py","%TEMP%storage_analysis.json","--no-browser","--port-file","%TEMP%storage_server_url.txt" -WindowStyle Hidden

启动后：

1. 等待 2 秒读取 %TEMP%storage_server_url.txt 获取 URL
2. 健康检查 GET /health 确认服务正常
3. 用 Start-Process 在用户默认浏览器中打开 URL（不要用 preview_url，内嵌浏览器无法正确执行交互式功能）
4. 同时可用 preview_url 在内嵌面板中预览（仅查看，一键清理功能需在真实浏览器中使用）

这是默认模式，交互式网页支持：

• 🟢 一键清理全部 — 确认面板 + 逐项串行删除 + 进度反馈
• 🟢 单项移到废纸篓 / 直接删除
• 🟡 在资源管理器打开 / 安全子路径移废纸篓
• 🔴 在资源管理器打开（去卸载）
• 折叠卡片、锚点导航、命令复制

可选：静态报告模式（仅查看，不能操作删除）：

python scripts/build_report.py %TEMP%storage_analysis.json %USERPROFILE%Desktopstorage-report.html

纯静态只读 HTML 文件，不含删除功能。仅在用户明确要求静态报告时使用。

Step 5 摘要总结

报告打开后，给一段结论先行的摘要：总可释放估算、最该先清的 2-3 项、风险最高的一项。细节让用户看网页。

附录A：分析检查清单

逐条执行，每完成一条在脑中打勾。

• 1. 挑 Top 5：按 size_kb 排序全部 groups 条目，取前 5，判定类型标签。 标签按优先级从高到低匹配，命中即停止，后面的不再考虑：

  优先级	标签	释义	判定依据
  1	系统文件	操作系统运行依赖的核心文件与组件仓库，误删可能导致系统不稳定、功能异常或无法启动	C:Windows 下除 Temp/SoftwareDistribution 外的全部子目录, C:Boot, EFI 分区, pagefile.sys, hiberfil.sys
  2	应用程序文件	应用程序安装目录下的全部文件（含 exe/dll/资源/配置），删除将导致对应应用无法运行	C:Program Files*, C:Program Files (x86)*, %LOCALAPPDATA%Programs* 下的应用目录
  3	虚拟机镜像	虚拟机/模拟器的磁盘镜像文件，删除将导致虚拟机数据完全丢失且不可恢复	EmulatorSdk 镜像, WSL vhdx, Hyper-V 虚拟硬盘, VMware .vmdk, VirtualBox .vdi
  4	应用数据	应用产生的不可再生或具有持久价值的用户个人数据，通常位于 AppData 及其子目录	WPS 模板, 微信聊天记录, 钉钉消息, 邮箱本地数据
  5	应用缓存	面向最终用户的应用产生的可再生临时文件，删除不影响功能、不丢用户数据	浏览器 Cache, 缩略图缓存, 微信/QQ 图片缓存, %TEMP%*, Office 最近文件索引
  6	开发缓存	包管理器/构建工具/IDE 产生的可再生中间文件，删除后可通过重新下载或构建恢复	pip Cache, .npm, .gradle, .m2/repository, Cargo target/, Yarn cache, NuGet packages
  7	用户文件	用户主动创建/编辑/保存的个人文档、工程文件、自建图片等	Desktop, Documents, Pictures, WorkBuddy* 项目目录
  8	媒体内容	从网络下载或应用缓存的消费型音视频文件，常见于 Downloads/Videos/Music 及各 App 离线目录	Downloads 里的 .mp4/.mkv/.avi, App 离线视频缓存, Music
  9	下载内容	Downloads 目录下用户通过浏览器/下载器获取后未整理的文件（安装包、压缩包、文档等）	Downloads*.exe, Downloads*.msi, Downloads*.zip
  10	回收站	Windows 回收站内容	C:$Recycle.Bin, 各盘符 $Recycle.Bin
  11	其他	以上均不匹配的兜底分类	—

  互斥规则：按优先级 1→11 依次匹配，命中即停。例如：Downloads 下的安装包优先匹配 9（下载内容），而非 8（媒体内容）；%TEMP% 下的编译中间文件优先匹配 6（开发缓存），而非 5（应用缓存）。

• 2. 探查神秘大目录：对名称含 UUID/GUID/SSID 的目录、大小 >1GB 的 ProgramData 子目录、不明用途的隐藏目录 → ls 查看内部结构，查出归属。 例：kingsoft/wps_international/addons 实为国际版 WPS 的冗余插件。

• 3. 三灯分类（只分"存在清理决策"的项，正常应用/系统文件归蓝色不展示）：

  🟢 可自动清理 — 纯缓存/临时文件/安装包残留/可再生不丢用户数据

  • ✅ 正例：浏览器 Cache、%TEMP%*、--updater 目录、pip Cache（开发缓存可再生）、IntelliJ IDEA caches
  • ❌ 反例：node_modules（项目依赖，删了项目跑不了）、AppDataRoamingMicrosoft（Office 设置不可再生）、微信聊天记录（用户数据）
  • 必填 trash_paths[]、commands[{label,cmd}]、kill_processes[]。
  • ⚠️ trash_paths 不能为空，漏了按钮就不出现。

  🟡 需人工判断 — 含用户数据或有判断成本

  • ✅ 正例：WeChat Files（聊天记录含重要数据）、Downloads 文件夹（可能有重要文件未整理）、WPS 模板（含自定义）、VMware 虚拟机镜像（大小巨大但可能还在用）
  • ❌ 反例：C:WindowsInstaller 不能手删（用 DISM 清理）、C:WindowsWinSxS 不能手删（系统组件仓库）、C:WindowsSystem32 不能手删
  • 必填 content_profile、why_manual、disposal、risk。
  • 有核实过的安全子路径时 → trash_paths（🟡 只能移废纸篓，永不给 rm）。
  • 目录是 App 内部格式 → open_note 字段说明。
  • ⚠️ 口吻中性如产品说明，不写"我发现/提醒注意"。

  🔴 建议卸载（别手删） — 大应用/重复安装/想卸载的项

  • ✅ 正例：不再用的 MobileAppEngine（7.6GB）、EdrawSoft（1.2GB）、Autodesk（2GB+）
  • ❌ 反例：C:Windows（操作系统本身）、Microsoft Office（如果还在用）、dotnet（系统运行时依赖）、Git（开发必备工具）
  • 必填 why_keep、indirect_release（具体卸载步骤，可照做不是空话）、app_paths[]。
  • 不给删除按钮，只给"在资源管理器打开（去卸载）"。

• 4. 数量检查：green+yellow+red 的总信息量应「一眼能看完」。 如果某级超过 10 项，挑最重要的列，其余合并到 summary。

• 5. 大小字段规范：用"约 14 GB""合计约 8.6 GB"格式。 "约"已表示估算，不要再加"（估算）"。

• 6. 按附录B模板写出完整 analysis JSON。 tier_stats 的 green/yellow/red 必须是可解析的 GB 数字开头（如"约 27.8 GB"）。

附录B：analysis JSON 模板（照此结构写）

{
  "generated_at": "2026-06-03 17:00:00",
  "scan_seconds": 9.3,
  "system": {  /* 从 scan.json 的 system 字段直接复制 */ },
  "top5": [
    {"rank": 1, "tier": "red", "size": "约 7.6 GB", "type": "应用程序文件",
     "name": "MobileAppEngine", "path": "C:\Program Files\MobileAppEngine",
     "note": "华为手机助手模拟器，EmulatorSdk 占 7.4 GB"}
  ],
  "green": [
    {
      "name": "WorkBuddy 桌面端更新缓存",
      "path": "C:\Users\xxx\AppData\Local\@genieworkbuddy-desktop-updater",
      "size_estimate": "约 450 MB",
      "kill_processes": [],
      "trash_paths": ["C:\Users\xxx\AppData\Local\@genieworkbuddy-desktop-updater"],
      "commands": [
        {"label": "PowerShell 移入回收站",
         "cmd": "Remove-Item -Path "$env:LOCALAPPDATA\@genieworkbuddy-desktop-updater" -Recurse -Force"}
      ]
    }
  ],
  "yellow": [
    {
      "name": "WPS 双版本插件/模板",
      "path": "C:\Users\xxx\AppData\Roaming\kingsoft",
      "size": "约 4.4 GB",
      "content_profile": "WPS 中文版+国际版数据。wps/addons 2.2GB，wps_international/addons 1.9GB。",
      "why_manual": "涉及两个版本的共用数据，无法自动判断主要用哪版。",
      "disposal": "只用中文版：wps_international/addons 1.9GB 可安全删除。",
      "risk": "删除 wps_international 后国际版 WPS 启动时会重新下载插件。",
      "trash_paths": ["C:\Users\xxx\AppData\Roaming\kingsoft\wps_international"]
    }
  ],
  "red": [
    {
      "name": "MobileAppEngine（华为手机助手）",
      "path": "C:\Program Files\MobileAppEngine",
      "size": "约 7.6 GB",
      "why_keep": "7.4GB 为 EmulatorSdk Android 模拟器镜像。如果不用华为手机连电脑可卸载。",
      "indirect_release": "设置→应用→已安装的应用→搜索 MobileAppEngine→卸载。释放约 7.6GB。",
      "app_paths": ["C:\Program Files\MobileAppEngine"],
      "auto_reclaim": "否，需手动卸载"
    }
  ],
  "denied": [],
  "summary": {
    "overview": "C 盘仅剩 4.3GB，最大占用是华为手机助手 7.6GB + WPS 数据 4.4GB。可立刻释放约 1.8GB。",
    "tier_stats": {"green": "约 1.8 GB", "yellow": "约 15.0 GB", "red": "约 12.4 GB"},
    "priority": [
      "最优先：清除更新缓存 5 项约 1.8GB，零风险",
      "其次：清理 WPS 国际版插件 1.9GB"
    ],
    "long_term": [
      "启用存储感知：设置→系统→存储→存储感知→开",
      "定期 DISM：DISM /Online /Cleanup-Image /StartComponentCleanup",
      "大文件迁移至 D 盘：D 盘还有 218GB 可用"
    ]
  }
}

注意事项：

• system 字段直接复制 scan.json 的 system，不要改动结构。
• trash_paths 必须是真实存在的绝对路径数组，不能为空数组。
• 🟡 项的 trash_paths 只放核实过安全可移的子路径（如旧备份目录），不是整个 path。
• 🟡 项如果没有安全子路径，trash_paths 留空或不写。
• commands[].cmd 写完整的可执行命令，用户可以直接复制到 PowerShell。

依赖

• Python 3.10+ (纯标准库，零 pip install)
• Windows 10 / 11（Windows 7 未测试）

平台状态

• Windows 10/11：完整实现并实测（扫描/报告/一键删除全验证）。
• 新增覆盖原版盲区：Installer、ProgramData、回收站、WinSxS、Windows Temp。

与原版 storage-analyzer 的差异

长期建议（写入报告 long_term）

• Windows 自带：cleanmgr(磁盘清理)、存储感知(设置→系统→存储)
• DISM 清理：DISM /Online /Cleanup-Image /StartComponentCleanup /ResetBase
• 第三方工具：WizTree（免费）、SpaceSniffer（免费）、TreeSize
• 大文件迁移至 D/E 盘；休眠关闭：powercfg /hibernate off
• 聊天软件缓存：微信/企微/钉钉定期在 App 内清理

更新日志

v2.0 — Windows-Native 重构 (2026-06-03)

基于原版 storage-analyzer (KKKKhazix/khazix-skills) 的完整逆向分析创建纯 Windows 实现。

修改动机：

• 原版 307 行 scan.py 中 ~150 行是 macOS-only 逻辑，Windows 用户无需携带
• 原版扫描盲区 ~65GB：Installer(31.5G) / ProgramData(4.7G) / 回收站(3.6G) / WinSxS(11.6G)
• 3 个 Windows 特有 bug：stdout 缓冲、SHFileOperationW 长路径、后台服务无存活检测

改动清单：

原版 vs Windows 版性能：

v2.1 — HTML 空白页修复 (2026-06-05)

修复报告 HTML 在浏览器中显示空白的致命问题。根因：JSON 数据注入 HTML 时，3 个崩溃点会导致整个 注入 JSON 中路径含 字符串 浏览器提前关闭 → ，u2028 → u2028，u2029 → u2029，彻底消除 JS 解析崩溃 build_report.py 新增 _warnings 注入数据 将结构验证警告传入模板，页面也能显示诊断提示 report_template.html 修复 amber→yellow / green_items→green 兼容 Agent 写 amber 不再导致数据丢失 report_template.html 修复 逐项字段补全 green/yellow/red 每一项缺失的字段自动填安全默认值（如 content_profile → "暂无内容画像"），不再显示 undefined 或空白 report_template.html 新增 mount 函数结构诊断 检测 green/yellow/red 全空、缺少 size_estimate、缺少 content_profile 等问题，页面顶部显示警告横幅 report_template.html 新增 build_report 警告透传 _warnings 数组中的验证警告也会在页面中显示 report_template.html 修复 catch 块增加调试信息 JS 解析失败时不再空白，显示错误详情和原始数据片段 server.py 修复 三重安全转义（同 build_report.py） 服务模式下也不会因 / u2028 崩溃 server.py 修复 amber→yellow 兼容 load() 函数自动将 amber 键重命名为 yellow

测试验证：

点击"一键清理全部 N 项 (约 X GB)" → 弹出确认面板
  → 面板列出所有绿色项（复选框 + 名称 + 路径 + 大小）
  → 用户勾选/取消 → 点击"确认移到废纸篓"或"直接删除"
    → 逐项串行调用 /action API
      → 每完成一项：更新进度条 + 状态标记（✓/✗）
      → 某项失败？跳过继续，记录错误
    → 全部完成：显示结果摘要（成功 N 项 / 失败 M 项 + 失败原因）
  → 用户点"关闭"