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，反例：Windows\System32
• 🔴 建议卸载 — 大应用/重复安装，正例：不再用的 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%\Desktop\storage-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（项目依赖，删了项目跑不了）、AppData\Roaming\Microsoft（Office 设置不可再生）、微信聊天记录（用户数据）
• 必填 trash_paths[]、commands[{label,cmd}]、kill_processes[]。
• ⚠️ trash_paths 不能为空，漏了按钮就不出现。

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

• ✅ 正例：WeChat Files（聊天记录含重要数据）、Downloads 文件夹（可能有重要文件未整理）、WPS 模板（含自定义）、VMware 虚拟机镜像（大小巨大但可能还在用）
• ❌ 反例：C:\Windows\Installer 不能手删（用 DISM 清理）、C:\Windows\WinSxS 不能手删（系统组件仓库）、C:\Windows\System32 不能手删
• 必填 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 中路径含 字符串浏览器提前关闭 → <\/script，\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

测试验证：

v2.2 — 一键清理绿色项（确认面板 + 串行删除 + 进度反馈） (2026-06-05)

在交互式网页中增加"一键清理"功能：确认面板让用户勾选要清理的绿色项，确认后逐项串行删除并实时显示进度，失败项跳过继续，最后显示结果摘要。

交互流程：

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

改动清单：

关键设计决策：

1. 串行而非并行删除：避免并发请求导致文件锁冲突或服务端过载
2. 失败跳过而非中止：某项权限不足时跳过继续，最后汇总失败列表
3. 默认只显示"移到废纸篓"：安全可逆；"直接删除"需额外勾选才可见
4. 确认面板可取消勾选：用户可以精确选择要清理哪些项，而非全有或全无

v2.2.1 — 修复 SHFileOperationW 类型错误 (2026-06-05)

修复"一键清理"全部失败的 bug。根因：_to_wide_null_terminated() 返回 bytes（encode("utf-16-le")），但 SHFILEOPSTRUCTW.pFrom 声明为 wintypes.LPCWSTR，ctypes 期望 str 而非 bytes，导致每次移到废纸篓都报错 unicode string or integer address expected instead of bytes instance。

修复：

• _to_wide_null_terminated() 返回 str 而非 bytes
• 注释同步更新：说明 ctypes 会自动将 Python str 转为 UTF-16
• 移除冗余的 import ctypes 语句（该函数不再需要 ctypes）
• move_to_trash() 增加错误码 120/124 回退逻辑：系统保护目录（如 C:\Windows\SoftwareDistribution\Download）或含被占用文件的目录无法移到回收站时，自动回退到 hard_delete()，避免清理失败
• ALLOWED_ROOTS 新增 C:\Program Files 和 C:\Program Files (x86)：修复 🔴 项"在资源管理器打开"时 L7 root boundary 拦截（如 C:\Program Files\Autodesk）
• report_template.html 修复 onclick 属性中 Windows 路径反斜杠丢失：esc(p).replace(/'/g,"\\'") 增加 .replace(/\\/g,'\\\\')，防止 JS 字符串中 \P 被当作无效转义序列吞掉反斜杠（如 C:\ProgramData\Autodesk 变成 C:ProgramDataAutodesk）

v2.3 — 设计级修复：JSON 解析方式 + 服务进程分离 (2026-06-05)

修复交互式网页始终显示为"静态模式"（DELETE = null）的根因问题，涉及两个独立 bug。

Bug 1：内联 JSON 赋值导致 JS 解析崩溃