CSpaceGuard 折腾记录

这不是文档，是流水账。技术细节在 开发手册 里，怎么安装看 部署手册，
这里只记一个人和一个红了的硬盘之间的故事。
时间：2026 年 9 月 5 日深夜开工，6 日中午收尾。

序：那个 89%

先看一张图吧。

250 GB 的 C 盘，用了 221.7 GB。右上那个橙色圆环，是我电脑最近半年的血压计。
每个月我都会打开"此电脑"，看一眼那条蓝色容量条又往前爬了一截，然后叹口气关掉。

想清理，不敢。谁知道 AppData 深处那个几 GB 的文件夹里，有没有藏着我三年的
聊天记录？谁敢保证那个看不懂的 .conda 不是什么重要的东西？

清理工具最大的敌人从来不是垃圾，是误删。 这句话我在项目做完之后才写下来，
但它在按下第一个键之前就已经在了。

一、起因是一个名字很好笑的开源项目

然后在 GitHub 上刷到了 WhoShitsonMyC——"谁在我的 C 盘上拉屎"。
名字笑死我，但认真读完 README 才发现：它根本不清理。它是个侦探，
拍两次快照对比，指着红红绿绿的树告诉你"是它干的"，然后拍拍手走人——
删还得你自己删。

行，那我想要一个既会破案、又敢帮忙收尾、但绝对不会抓错人的。
没有，就造一个。

二、被自己采访的晚上

开工前我先让 AI 采访我，条件只有一个：一次只问一个问题。

七八个问题问下来，产品长什么样就定了：侦破和清理都要；给自己用但可能开源；
手动打开、用完即走（我受够了那些常驻后台"帮你优化"的东西）；界面只要中文；
扫描线程数、主题、白名单都得能自己调。

有一道题我记得最清楚。问到清理范围，我几乎全勾了——系统垃圾、浏览器、
微信 QQ、开发缓存——然后在选项后面手打了一行字：

"但是内容要写具体，聊天软件缓存里有些文件可能比较重要，开发者缓存里有些配置可能很重要。"

就是这句话，后来变成了代码里的三层白名单。你看，**软件的性格，
其实是主人在需求访谈里泄露的**。

软件名字是 AI 替我起的：CSpaceGuard，C盘空间卫士。比 WhoShitsonMyC 文明，
也比"C盘清理大师"有出息。

三、第一晚： bug 像爆米花一样蹦

那晚的 bug 多到值得单独开一章，挑几个印象深的：

import 不到的 pywebview。 装包成功，import pywebview 却报"模块不存在"。
查了半天，它的导入名是 webview。包名和模块名不一致这种历史遗留坑，
每个 Python 玩家都摔过，但没有一次不气。

存不进去的快照。 扫描都跑通了，往磁盘存快照时炸出一个类型错误——
压缩文件流是二进制的，我却往里写文本。改一个字母就好，但它暴露了更要紧的事：
当时根本没有快照读写的测试。后来补测试的时候我给自己立了条规矩，
每修一个 bug 就放一个"再也不会"的测试在那儿守门。

读到一行源码，后背发凉。 为了确认"删进回收站"真的安全，我翻了底层库的
源码，看到几个标志位的瞬间头皮发麻：删除操作被设置成"不弹任何确认框"。
这意味着——单个文件大到塞不进回收站时，Windows 不会问任何人，直接永久删除。
也就是说，我这个号称"绝不直接删除"的工具，遇到一个 60 GB 的模型文件时，
会亲手把它送进永远回不来的地方，还礼貌地在日志里写"已删除"。

那天晚上的处理方式是：删除之前先去系统注册表里查回收站的真实容量上限
（我这台是 49.64 GB，系统挺大方），塞不下的文件在我们这边就主动跳过、
写明原因。宁可漏删一千，不可误删一个——这句话后来被写进了测试的名字里。

四、第一张全家福

折腾到 6 日凌晨，界面终于能见人了。趁热截了几张图：

快照对比——整个项目的灵魂视图。红色是变大的目录（+28.7 MB），
灰色徽章是"部分不可见"（没权限进的地方，诚实标注，不装看得见）。
每行最右边那个黄色小文件夹，是后来加的：点一下直接跳进资源管理器去现场看。
说实话，第一版是没有这个按钮的，直到有天我盯着一行结果想"那这个目录在哪来着"，
才意识到侦探报告上应该附地址。

这张图里的数据是真实的——是我今天上午自己扫的两个快照（间隔六分钟），
所以净增只有 29.2 MB。等我攒几天的增长，红绿树才有好戏看。

空间排行——按大小排的"占用大户榜单"，带比例条，点一行就能钻进去看下一层。
配上"全盘最大文件"榜，谁在吃 C 盘一目了然。

清理中心——全部价值观浓缩在这一页。绿盾牌是 A 档"确定安全"，可以整体勾选；
黄球是 B 档"存疑"，默认一个都不选，必须逐条确认。你看"系统临时文件"那两行
是灰的——因为我现在没提权，软件诚实地说"需要管理员权限，当前不可用"，
而不是假装能清然后偷偷失败。HuggingFace 模型缓存挂着黄色警告：
"重新下载可能耗时数小时"——每个字都是从真实痛苦里长出来的。

页首那条蓝色横幅是全项目最重要的一句话：
清理 = 把文件移入回收站（可撤销），空间在回收站被清空后才真正释放。
早期版本没写清楚，我自己都困惑过"怎么清完没变大"。工具对用户诚实的程度，
决定了它值得被信任的程度。

清理日志——删了什么、多大、去了哪，逐条记录；被白名单拦下的文件也会留痕，
比如图里那个被保护起来的 PDF，和那个"文件被占用"的日志。这页存在的意义是：
哪怕有一天你怀疑它删错了东西，也能翻开账本一条条对。

设置——白名单全部摊开给你看：哪些扩展名永远不碰、哪些名字模式永远不碰，
还能自己往严里加规则（只能加严，不能放宽——防线不许自己拆）。

暗色主题——凌晨写完主题切换代码时截的。深夜的橙色圆环在暗色里像个小小的
警报灯，挺配它的身份。

五、今天中午：给软件拍证件照

写文档要配图，于是今天中午干了一件折腾事：让软件自己跑起来、往界面里灌演示
数据、然后逐个视图自动截图。

第一次尝试差点出事故：截屏方式抓的是"屏幕上那块区域"，结果抓到了我桌面上
开着的其他窗口——既不能用，还泄露隐私。全部销毁重拍，改用按窗口句柄
直接取内容的方式，才算干净。

第二版又全军覆没成 0 KB 的空文件，查了半天发现是临时文件名里的中文在命令行
管道里被搞坏了。改成先存英文名再改名，七张图一次成型。

中间还有个小惊喜：拍"快照对比"时发现，页面里显示的不是我灌的演示数据，
而是今天上午我自己扫的两个真实快照——原来软件早就在后台把活干好了，
连"演示"这个环节都在用真数据说话。（当然，04 那张清理中心里的
"Temp 10.4 GB"之类是我灌的演示数字，图和真相分清楚。）

六、那些没能变成功能的想法

不是每个想法都值得变成代码。两轮自我审查里，有好几条被我自己按住了：

• 给白名单匹配做性能优化——算了，快到根本感觉不到，不值得在安全代码上动刀；
• 快照加载时显示进度条——改动面太大，为了省一两秒的等待冒回归的险，不值；
• "磁盘色块地图"——采访那天就被我自己划掉了，红绿树已经把话说清楚了。

折腾这件事最难的不是加东西，是忍住不加。

尾声

现在的状态：54 个自动化测试全绿，其中十几个是专门看守安全底线的
（受保护的文件就算被硬塞进删除清单也拦得住、塞不进回收站的大文件一律绕行、
回收站里只清除本软件删过且有账可查的那部分）。

C 盘还是 89%。但这次我一点也不慌——

快照在记录它的每一次呼吸，红绿树会指着元凶的名字，
清理中心的每一刀都进回收站，每一笔都有账可查。

工具的克制程度，决定了它的下限；对"误删"的恐惧有多具体，决定了它的上限。

这一夜一天，所有较真，都是同一句话。

CSpaceGuard v0.1.0 · 2026-09-05 深夜 ～ 09-06 午后 · 与 AI 结对，人来把关