README.md

C Drive Cache Helper

一个保守、安全、可解释的 Windows C 盘缓存清理助手。

只清理缓存，不卸载软件，不删除聊天记录、接收文件、项目文件和个人文档。
默认只扫描；只有通过安全测试并完成扫描后，界面才允许执行清理。

功能亮点 · 安全边界 · 快速开始 · Release 包 · 迁移到其他电脑 · 测试

重要说明： 本工具定位是“缓存清理助手”，不是系统瘦身器，也不是软件卸载器。虚拟内存只做占用报告，不自动修改 pagefile、swapfile 或 hiberfil。

---

Features / 功能亮点

• 扫描优先 — 默认只统计可清理缓存，不删除任何文件。
• 三步 UI — 1 安全测试 → 2 扫描缓存 → 3 清理缓存，清理按钮默认禁用。
• 保守白名单 — 只处理明确属于缓存的目录，例如临时目录、崩溃转储、显卡缓存、浏览器缓存、部分应用 Web 缓存。
• 聊天软件保护 — 微信、QQ、飞书只识别保守缓存目录；聊天记录、数据库、接收文件、图片、视频、语音、附件目录受保护。
• 报告留档 — 每次扫描/清理都会生成报告，方便回看本次做了什么。
• 虚拟内存报告 — 可查看 pagefile / swapfile / hiberfil 的占用情况，但不会自动修改。
• 可迁移 — 不依赖固定 D 盘路径，复制到其他 Windows 电脑也能使用。
• 可测试 — 内置安全测试和 UI 静态测试，修改清理范围前可以先跑测试。

---

Safety Model / 安全边界

这个工具采用“允许清理的少量缓存目录 + 明确禁止的保护目录”两层保护。

永远不会主动清理

• C:\Program Files
• C:\Program Files (x86)
• C:\Windows\WinSxS
• C:\Windows\System32\DriverStore
• C:\Windows\Installer
• 桌面、文档、下载、图片、视频
• 项目文件夹
• Codex 记忆文件
• 微信 / QQ / 飞书聊天记录
• 微信 / QQ / 飞书接收文件、图片、视频、语音、附件

清理前置条件

flowchart LR
    A["打开工具"] --> B["1 安全测试"]
    B --> C["2 扫描缓存"]
    C --> D{"确认报告"}
    D -->|确认无误| E["3 清理缓存"]
    D -->|不确定| F["关闭工具，不清理"]

    style B fill:#E8F5E9,stroke:#2E7D32,color:#111
    style C fill:#E3F2FD,stroke:#1565C0,color:#111
    style E fill:#FFF3E0,stroke:#EF6C00,color:#111
    style F fill:#F5F5F5,stroke:#777,color:#111

Loading

---

Quick Start / 快速开始

方式 A：图形界面

下载 Release 包并解压后，双击：

Start-UI.bat

中文别名：

启动UI.bat

使用顺序：

1. 点 1 安全测试。
2. 点 2 扫描缓存。
3. 看界面输出，必要时点 打开报告。
4. 确认只命中缓存后，再点 3 清理缓存。

方式 B：命令行

只扫描，不删除：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\clean.ps1"

清理缓存：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\clean.ps1" -Execute

扫描浏览器和开发工具缓存：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\clean.ps1" -IncludeBrowserCaches -IncludeDevCaches

查看虚拟内存报告：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\clean.ps1" -IncludeVirtualMemoryReport

---

Release Package / 发布包

Release 资产：

文件	说明
c-drive-cache-helper-v0.1.0.zip	可直接解压运行的工具包

压缩包包含：

C Drive Cache Helper
├── Start-UI.bat
├── 启动UI.bat
├── start-ui.ps1
├── clean.ps1
├── C盘清理助手-UI.ps1
├── c盘清理助手.ps1
├── tests
├── reports
├── README.md
└── AGENTS.md

压缩包不包含本机扫描报告、Git 历史和临时文件。

---

Migration / 迁移到其他电脑

可以迁移。推荐流程：

1. 从 GitHub Releases 下载 c-drive-cache-helper-v0.1.0.zip。
2. 解压到任意目录，例如桌面、D 盘工具目录或移动硬盘。
3. 先运行安全测试：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\tests\safety-test.ps1"

4. 安全测试通过后，再双击 Start-UI.bat。

不要求放在 D:\project，脚本会根据自身所在目录寻找后端和测试文件。

---

Project Structure / 项目结构

c-drive-cache-helper
├── AGENTS.md                 # Codex 协作边界：只清缓存，不碰软件和资料
├── README.md                 # 项目说明
├── Start-UI.bat              # 推荐启动入口
├── 启动UI.bat                # 中文启动别名
├── start-ui.ps1              # UI 启动器
├── C盘清理助手-UI.ps1        # WinForms 图形界面
├── clean.ps1                 # ASCII 后端桥接入口
├── c盘清理助手.ps1           # 清理核心逻辑
├── tests
│   ├── safety-test.ps1       # ASCII 安全测试入口
│   ├── 安全测试.ps1          # 安全测试主体
│   └── UI静态测试.ps1        # UI 安全逻辑检查
└── reports
    └── .gitkeep              # 运行后报告会保存在这里

---

Tests / 测试

安全测试：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\tests\safety-test.ps1"

UI 静态测试：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\tests\UI静态测试.ps1"

启动器自检：

powershell -NoProfile -ExecutionPolicy Bypass -STA -File ".\start-ui.ps1" -SelfTest

测试覆盖重点：

• 默认模式必须是扫描，不删除。
• 清理必须显式传入 -Execute。
• Program Files 必须受保护。
• 微信/QQ/飞书聊天记录和接收文件路径必须受保护。
• 虚拟内存必须只报告，不修改。
• UI 清理按钮必须默认禁用。
• UI 必须要求安全测试和扫描都完成后才允许清理。

---

FAQ / 常见问题

会删除软件吗？

不会。软件安装目录在保护列表里。

会删除微信、QQ、飞书聊天记录吗？

不会。聊天记录、数据库、接收文件、图片、视频、语音、附件目录都受保护。

为什么有些文件清理失败？

通常是文件正在被软件占用。关闭对应软件后重新扫描/清理即可。

虚拟内存能不能一键清？

本工具不做这件事。虚拟内存属于系统设置，只显示报告，不自动修改。

GitHub 上为什么没有 reports 里的报告？

报告可能包含本机用户名和路径，所以默认不上传。仓库只保留 reports/.gitkeep。