System Cleaner(跨平台系统清理)
Overview
安全地扫描并清理 Windows / macOS / Ubuntu 系统上的缓存、临时文件、日志、
浏览器缓存、回收站、包管理器缓存等可安全重建的内容,释放磁盘空间。
本 skill 的核心设计原则:
- 扫描只读 —
scan.py只做统计报告,绝不修改任何文件。 - 回收站而非删除 —
clean.py将所有项目移入系统回收站/废纸篓,
可恢复,绝不永久删除。 - 确认先行 — 展示完整路径清单并获得用户确认后,才执行清理。
- 高危拦截 — 系统级目标(需管理员权限的)默认拒绝,除非用户明确批准。
- 不碰个人文件 — 桌面、文档、下载、图片、视频等用户文件目录在任何
情况下都不在清理范围内。
触发场景
用户提出以下意图时使用本 skill:
- "清理系统垃圾 / 清理缓存 / 释放磁盘空间"
- "C盘满了 / 磁盘空间不足 / 帮我看看空间被什么占了"
- "清理浏览器缓存 / 临时文件 / 日志 / 回收站 / Xcode 缓存 / Homebrew 缓存"
- "电脑变慢了,帮我清理一下"
用户给出模糊的、未指定目标目录/类型的清理请求(如"清理一下我的电脑")
时,必须先用扫描报告帮助定位问题,再让用户选择具体清理项,不可直接猜测执行。
工作流程
Step 1: 识别平台并扫描(只读)
用当前平台的 Python 运行扫描脚本。绝不允许手动 find / du / rm 替代:
python3 scripts/scan.py --json /tmp/cleanup-report.json
必要时可限定单个目标:python3 scripts/scan.py --target browser_cache --json /tmp/cleanup-report.json
查看全部可用目标:python3 scripts/scan.py --list-targets
扫描会输出:每个目标的大小、文件数、具体路径、风险等级,以及总计可清理空间。
> 平台识别:sys.platform 的 win32 → windows,darwin → macOS,
> linux → Ubuntu/Linux。脚本自动匹配,无需手动指定。
Step 2: 向用户展示报告并解释
把报告翻译成用户易懂的中文摘要:
- 可清理总空间、分项列出(每项:名称、大小、风险)。
- 解释每一项删除后的影响(如"浏览器缓存删除后会自动重建")。
- 标注哪些是高危项(系统临时文件/系统日志/Windows Update 缓存等),
并说明默认不清理。
Step 3: 获得明确确认
在运行任何清理前,必须获得用户明确同意,确认方式可以是:
- 用户直接回复"清理"或指定目标(如"清理浏览器缓存和临时文件");
- 或对列出的目标逐项确认。
同时向用户说明:清理会将文件移入回收站/废纸篓,可随时恢复。
如果用户请求模糊(未指定清理内容),基于报告给出建议,并询问用户选择哪些项。
Step 4: 执行清理(仅移入回收站)
python3 scripts/clean.py /tmp/cleanup-report.json --targets browser_cache,user_temp --yes
--targets只清理用户确认过的目标;高风险目标必须加--allow-high,
且仅当用户明确批准该目标时才能使用。- 不加
--yes时脚本会交互式确认;agent 场景中,获得用户确认后用--yes
跳过脚本内二次确认(避免卡住)。 - 若用户担心误删,可加
--backup-dir <目录>先备份再清理。 - 脚本按每批最多 10 项执行,每批验证;个别被占用/无权限的项会跳过并
明确报告,不会中断整个清理。 - macOS 目录类目标(如
~/Library/Logs):脚本会自动展开为逐子项清理,
不会整体移动目录(整体移动会被系统安全服务拦截,报 FSMoveObjectToTrashSync
-5000,且可能产生部分移动的冗余副本)。目录本身保留,仅清空内容。
Step 5: 报告结果
清理完成后告知用户:
- 清理了多少项、释放了多大空间(脚本输出)。
- 已移入回收站,若想恢复可从回收站还原。
- 如果用户想彻底释放回收站空间,再引导用户自行清空回收站
(清空回收站属于永久删除,必须由用户本人操作,agent 不代劳)。
平台注意点
- Windows:高危项(
C:\Windows\Temp、C:\Windows\Logs、
SoftwareDistribution\Download)需要管理员权限,默认跳过。
可提示用户:可用系统自带"磁盘清理"(cleanmgr)处理系统级清理。 - macOS:
~/Library/Logs属于用户日志可以清理;系统日志
(/var/log) 不在范围内。Xcode 用户可建议xcrun simctl delete unavailable。 - Ubuntu:需要 root 的系统清理(
apt clean、journalctl --vacuum-time)由
脚本报告但默认不执行;agent 可向用户给出命令建议,让用户自行以 sudo 执行,
agent 不代跑 sudo 命令。
详细的各平台目标清单见 references/cleanup-targets.md。
边界与红线(不可逾越)
- 绝不永久删除文件:任何清理操作都只能移入回收站。需要"彻底删除"时,
只引导用户自己清空回收站。 - 绝不清理用户个人文件:桌面、文档、下载、图片、音乐、视频、以及任何
用户未确认路径,全部排除。 - 绝不递归清理整盘:禁止对磁盘根目录、
C:\、/、/Users、/home做
批量清理。 - 高危目标必须显式批准:用户只是笼统说"都清理"不构成对高危项的批准,
需要逐项点名确认。 - 绝不代替用户执行 sudo/管理员操作:给出命令建议,由用户自行执行。
Resources
scripts/scan.py— 只读扫描,生成文本+JSON 报告(安全流程第一步)。scripts/clean.py— 安全清理执行器:仅移入回收站、批量小步执行、逐目标
确认、高危拦截、可选备份。scripts/recycle.py— 跨平台回收站实现(Windows PowerShell / macOS Finder /
Linux gio|trash-put|XDG Trash),被 clean.py 调用,禁止永久删除。references/cleanup-targets.md— 各平台清理目标、路径、风险等级、系统自带
工具对照表。
