nex_squid/docs/ARCHITECTURE.md

31 KiB
Raw Permalink Blame History

squid 架构

本文描述 squid 的模块划分、数据流、安全不变量与跨平台方案。阅读顺序建议:先读「两条铁律」,再看 crate 图,最后按需查各引擎。

设计目标

  1. 一台机器可以只有 245 GB,但用户的文件必须是无价的。 所有设计里优先级最高的一条。
  2. 单二进制、零常驻。 没有 daemon、没有 launch agent、没有后台上传;squid 退出后不留痕迹。
  3. CLI 与 TUI 共用同一套引擎。 终端界面不是玩具前端,squid clean 与 TUI 里的「清理」面板调用的是同一个函数。
  4. 可脚本化。 任何命令都能 --json、--dry-run、--quiet,退出码稳定。

非目标:不做实时文件系统监听、不做定时任务、不做 GUI(AppKit/SwiftUI)、不做云同步。

两条铁律(不变量)

铁律一:扫描不删除。 每个引擎都遵循 Scan → Approve → Delete 契约。scan() 只产出 ScanReport(一组 CleanupItem),幂等、无副作用,可以随时中断,可以对着 1 TB 的目录跑十次。

铁律二:只有 squid_engine::delete::execute 能删东西。 squid-engine 内部禁止直接调用 std::fs::remove_*。删除必须经过这一个函数,因此「安全校验 + 账本 + 废纸篓可还原」在架构上无法被绕过——新增引擎时想跳过检查,就只能显式地写出一条很难看代码评审的语句。

execute 做的事:丢弃嵌套重复项(父目录先删会让子项 ENOENT、体积重复计数)→ 对每个条目重新执行 Engine::block_reason()(锁、白名单、SafetyPolicy)→ 预先计算废纸篓目标路径 → 删除 → 写 ledger 会话。之所以要"重新校验",是因为一次扫描可能跑了几分钟,磁盘早就不一样了。

crate 依赖图

层 crate 依赖
0 squid-core —(不知道任何其它 crate 的存在)
1 squid-platform core
1 squid-rules core, platform
1 squid-stats core, platform
1 squid-guard core, platform
2 squid-engine core, platform, rules, stats
3 squid-tui core, platform, rules, stats, engine
4 squid-cli 以上全部(含 guard)
— src-tauri core, platform, guard, engine, stats

squid-guard 与 squid-engine 在第 1 / 第 2 层并列,而不是叠在一起:清理引擎的一切 前提都是「这东西可再生,删了没事」,而隔离的全部难度恰恰在于「这是用户自己的文件, 必须能原样放回去」。所以 guard 只依赖 core 与 platform,复用 Progress、 CancelToken 与 paths,但不碰删除路径。

squid-core

模块 关键类型 职责
model CleanupItem, Category, ItemKind, DeleteMode, LockReason, CleanSummary, ScanReport 唯一的数据货币。CleanupItem{path, kind, size, category, label, rule_id, selected, allocated, lock, note, anchors}
bytes Bytes, format_thousands 逻辑大小 vs 实际占盘大小(st_blocks * 512)两套口径
paths expand, home_dir, pretty, label_for ~ 展开、~/… 显示、中文安全的路径缩短
fs measure, measure_all, kind_of, remove_item_with, trash_path, trash_target_for, empty_trash 体积测量(walkdir + rayon 并行,忽略符号链接)、安全删除、跨卷回收站
safety SafetyPolicy 见「安全模型」
settings Settings, locale() config.toml、白名单、规则开关、SQUID_CONFIG_DIR/SQUID_STATE_DIR
ledger Session, LedgerEntry, write_session, load_sessions, restore 删除账本与 undo
progress Progress, Event, CancelToken 引擎与 UI 之间唯一的沟通渠道;跨线程通道,取消是协作式的

squid-platform

Platform trait 把「这个操作系统上 App 装在哪、残留放在哪、卷怎么枚举、删除前要不要先停服务」抽象出来:

fn app_sources(&self) -> Vec<AppSource>;
fn list_apps(&self, cancel: &CancelToken, size_apps: bool) -> Result<Vec<AppInfo>>;
fn leftover_roots(&self) -> Vec<LeftoverRoot>;
fn prepare_uninstall(&self, app: &AppInfo) -> LifecycleReport;   // 停 launchd / 注销 Launch Services
fn finish_uninstall(&self, app: &AppInfo, removed: &[PathBuf]) -> LifecycleReport;
fn volumes(&self) -> Result<Vec<Volume>>;
fn protected_prefixes(&self) -> Vec<PathBuf>;
fn running_executables(&self) -> Vec<String>;                    // 供 skip_if_running 使用

LeftoverRoot { dir, naming, deep, category } 描述一个残留目录以及它的命名方式(BundleId / AppName / Either / GroupContainer)。deep 默认 false —— Application Support 这种目录只匹配直接子项,绝不递归。

leftovers::match_name 负责把 Xmind.app 与 com.xmind.win_zen.bundle、Xmind-state、Xmind Saved Application State 之类关联起来。这里有两个曾经踩过的坑,回归测试已经锁住:

  • 匹配前大小写要归一化(Xmind vs xmind);
  • KNOWN_SUFFIXES 带点而文件名切分后不带点,两侧必须用同一种归一化形式比较(has_known_suffix)。另外 .pdf/.png/.mp3 这类文档后缀绝不能出现在「按名称匹配」的后缀表里,否则 Xmind-notes.pdf 会被当成残留删掉。

console 不在 Platform trait 里,但它回答的是同一类问题——「这台机器上的现实是什么」:控制台自称的窗口尺寸、它背后那块屏幕缓冲区的尺寸、它最大允许多大的窗口,以及一个「按 Unicode 只有 1 列宽」的字符在这里到底占几格。legacy conhost 在这两件事上都会给出错答案:进备用屏换掉的只是「正在显示的那块缓冲区」,进程的 stdout 句柄仍指着没人看的那一块,于是窗口比真正存在的格子更宽,写出一行的格子就落到下一行开头;cp936 码页又把 ─│·…↑↓✓ 这批 East Asian Ambiguous 字符收两格,而 ratatui 按一格排版。两者最后都表现为同一种花屏——屏上同时留着好几帧。所以 TUI 每一拍重新量一次尺寸(缓冲区被滚走、窗口被人拖大都算变化,只有真的变了才擦屏重画)。字形的价格归 currency:Exchange 按码位存一张兑换表,只在控制台确实多收钱时建,afford 在单格终端上原样返回。价是谁问的要分开说——console::prices 逐字符把答案量回来给界面,squid_tui::glyphs 因此只剩 ratatui 那一半:witnesses 从界面源码和 widget 里收集本界面会画的所有歧义字符,Carry 走一遍成品帧把付不起的字符换成 ASCII;console::prices_unasked 只取码页隐含的悲观答案给命令行,因为测量要往控制台上正显示的东西写一个字符再擦掉,而命令行是那台屏幕上的客人,它不该买这个答案,代价是在单格终端被码页误伤的机器上少一个 █、多一个 #。两边各有一条测试钉住「画的字符」与「问过的字符」是同一份:界面是 every_glyph_this_interface_draws_has_a_price 和 the_probe_asks_the_price_of_everything_that_ends_up_on_the_screen,命令行是 no_line_of_chrome_escapes_the_counter,它扫描 main.rs,要求除 JSON 和空行之外每个 print 都过 priced。SQUID_SYMBOL_CELLS 供人强制指定,SQUID_CONSOLE_TRACE 把控制台自己的几个数字写进文件留证。

process 也只回答一个「这台机器上怎么停掉一个进程」的问题,而它值一个模块的理由是「为什么没停掉」必须由操作系统来回答。force_stop(pid) 在 unix 上发 SIGKILL,在 Windows 上 OpenProcess(PROCESS_TERMINATE) + TerminateProcess,两边是同一个承诺:立刻停,不保存任何东西——所以界面在三套系统上都写「强制结束」,而不是它并没做过的「退出」。sysinfo 的 Process::kill() 也能办成这件事,但它只回一个 false,而 EPERM(你不是那个用户 → 换个提权的终端)和 ESRCH(它自己早走了 → 什么都不用做)要求的动作恰恰相反,把两种结果压成同一句报错,等于教用户从此不再信报错。规则也放在这里,因为操作系统并不拦下一切:非提权进程本来就碰不到 macOS 的 WindowServer,但提权后的 squid 在 Windows 上是真的能打开 csrss.exe 的,一次按错的回车换来一次不带询问的重启,六个名字的表换这个结果是划算的(svchost 故意不在表里:它承载的服务用户确实可能要重启,且少一个也不至于起不来)。pid_refusal 与 refusal 拆成两个问题,因为它们被问的时刻不同:前者问的是界面手里那个数字,后者要等真正读到进程的名字。这个模块只对着 pid 说话——「此刻的 pid 还是不是用户读到的那个进程」是关于 sample 的问题,问在 sample 待着的地方。

squid-rules

规则是 TOML,内置于 crates/squid-rules/rules/macos.toml(39 条),通过 include_str! 编译进二进制;用户规则从 <config_dir>/rules/*.toml 合并,同 id 覆盖内置。

[[rule]]
id = "xcode-derived-data"
category = "developer"
patterns = ["~/Library/Developer/Xcode/DerivedData/*"]
mode = "path"          # path = 删除条目本身;contents = 只清空目录内容
os = ["macos"]
protect = ["SomeKeep", "SomeKeep/*"]
min_age_days = 3
select_by_default = true
needs_admin = false
skip_if_running = ["Docker Desktop", "com.docker.backend"]
risky = true
note = "Xcode 会重新生成。"

核心是 expand_pattern(pattern) -> Vec<Match{path, anchor}>:

  • * 不跨越路径分隔符(globset 语义),所以 ~/Library/Caches/* 只会命中一层;
  • 每条匹配都携带 anchor(锚点) —— 模式的最长字面量前缀。锚点是删除时的权限边界:SafetyPolicy 只允许在锚点之下删除,且拒绝锚点自身。这条设计使得「一条规则写错」的最坏后果被限制在该规则自己的目录里;
  • 不含通配符的字面模式(如 ~/.cargo/.package-cache)匹配的是这个文件本身、锚点取其父目录。曾经有个 bug 是把锚点当成了匹配结果,等于提出删除整个 ~/.cargo——已有回归测试 wildcard_free_patterns_match_the_file_not_the_parent。

risky 与 skip_if_running 是给「体积巨大但语义危险」的规则准备的刹车,典型是 container-images:Docker 的 VM 磁盘可能有 1 TB,一旦正在运行还去删就是数据事故,所以它既不默认勾选、又在检测到 Docker/OrbStack 进程时直接锁定。

squid-stats

Sampler::{new, prime, refresh} 基于 sysinfo,两次采样之间才有 CPU%/网速,因此 prime() 是必须的预热步骤。产出 SystemSnapshot{cpu, memory, network, disk, uptime_secs, top_processes, volumes, battery, host} 与 TrendStore(滚动历史,给 TUI 的迷你折线/柱状图)。battery.rs、human_uptime() 提供 iStat 式细节。

界面既然能列出谁在跑,就会被要求停掉谁,Sampler::stop(sample) 是这件事唯一的入口。它先按 pid 挡掉 squid 自己、机器的第一个进程和 Windows 的 System,再用 sample_of(pid) 重读一次:读不到就是「已经不在了」,读到的名字对不上也算「已经不在了」(用户指着的那个进程确实没了,无论 pid 朝哪个方向移动),只有名字仍然相符,才轮到 squid_platform::process::force_stop。名字之所以能当这个凭据,靠的是 top_processes、applications 与 sample_of 共用同一个 shown_name——三处各自截一次尾段,凭据就有三份写法。sample_of 是公开的:它给的正是界面此刻会为这个 pid 画出来的那一行,测试拿它造一条诚实的行,界面将来只重画一行也用得上。键位是 x:它在文件面板上一直是「删除」,系统状态面板上没有可删的东西、只有进程,同样的手指落到同样的动词上。规则当场命中的那些(自己、第一个进程、Windows 的引导进程)直接 toast 原因、不弹确认框:为一个规则注定会拒绝的动作去要许可,是把确认框变成戏剧。

squid-engine

引擎 做法
clean 遍历规则 → expand_pattern → protect/年龄/白名单/运行中过滤 → measure_all 并行测体积 → sort_for_display 按分组排序。--orphans 会额外调用平台残留匹配,寻找已消失 App 的孤儿目录
uninstall scan_apps 建立 App 清单(名称、bundle id、体积、是否运行中、Homebrew cask)→ find 模糊定位 → build_plan 生成「本体 + 按 bundle id/名称匹配的残留」→ 用户确认 → remove_plan(含平台 prepare_uninstall/finish_uninstall 钩子)。共享给同厂商多个安装的残留会被 LockReason::SharedWithOtherInstall 锁住
purge 遍历 purge_roots(或用户给定路径,默认深度 6、最多 30 万目录),把 ALWAYS(node_modules、target、DerivedData、.venv…)识别为可再生;AMBIGUOUS(dist、build、out、venv…)只有当同目录存在 package.json/Cargo.toml/go.mod 等 PROJECT_MARKERS、或用户显式 --all 时才提出。DO_NOT_DESCEND 阻止进入 .git、Library、挂载点等。附带 APFS 本地快照(com.apple.TimeMachine*)与旧 iOS 备份、磁盘镜像等非目录项
analyze DaisyDisk 式体积树:explore/expand 逐层展开、largest_files、buckets 分类聚合。总量在遍历超限时标记为下限而非真值

squid-tui

ratatui + crossterm。六个面板 Cleanup / Uninstall / Purge / Storage / Stats / History,App 是唯一状态机,键盘事件 → Action → 重绘。

  • 绝不阻塞 UI:每个引擎调用都通过 job::spawn 跑到独立线程,返回 JobHandle<T>;Progress 事件与最终结果走两条 crossbeam 通道,事件循环 poll() 非阻塞取结果。取消是协作式的 CancelToken。
  • 每个 job 自己 Engine::new(),避免跨线程借用,代价是每次扫描重读一遍小 TOML。
  • theme::Strings::t(en, zh) 集中管理双语文案,Palette/card() 复刻 CleanMyMac 的暗色卡片观感(背景 Rgb(16,18,23)、强调色 Rgb(86,182,246)、圆角卡片)。 调色板只写 RGB,输出一律经 Palette::resolve:SQUID_TRUECOLOR → COLORTERM → TERM_PROGRAM → TERM 依次探测真彩色能力,不支持时映射到 xterm-256(灰阶走 24 级灰条)。Terminal.app 只认 256 色, 少了这一步它会把 48;2;… 当文字打出来,暗色主题直接变成白底黑字。
  • 选中状态不能只靠颜色:Palette::selected_for(truecolor) 在真彩色下是强调色条,降级终端里是 REVERSED | BOLD(反白由终端自身的前景色/背景色完成,灰度终端同样成立);勾选状态另有加粗 ● 与细体 ○ 两条冗余通道。close_gaps 负责让高亮行成为连续的一整条:列分隔用的是无样式 Span::raw(" "),反白时会在行里留下一道道暗缝,所以只在「整行非空白 span 样式一致」时把空白也染上; 路径列只截断不补齐,因此 item_row 末尾还会按显示宽度补一段同色空格,让高亮条一直顶到卡片右边框。
  • 一个 widget 只有一套下标:ListState::selected 是 ratatui 用来定位滚动窗口的行号,高亮却由每一行自己画,两者必须数同一批行。卸载列表把「大小/名称/版本」表头(筛选时还多一行 filter chip)和条目一起塞进同一个 List,selected 就此比样式多算了一两行:第一屏看不出来,列表一超过一页,窗口按「光标上面那一行」定位,高亮行被挤出可视区,用户看到的是「下翻之后没有高亮了」——Mac 与 Windows 同因,因为它跟终端无关。清理面板从不出现这个现象,ScanPanel::lines 里只有条目,标题挂在 card 的 block 上。现在的写法把表头和 filter chip 当作 chrome 单独走一段 Layout:Paragraph 拿上面,List 只拿条目。the_app_under_the_cursor_is_the_row_that_is_on_screen 遍历每一个光标位置(含筛选态)断言「光标那一行就是屏幕上那一行、且带着强调色与加粗」,因为它无法靠猜某个卡片高度通过。

squid-guard

恶意软件扫描、检测规则与可逆隔离。它是唯一一个会移动用户文件的新 crate,所以它的 设计重心不是「能找到什么」,而是「在没有 Developer ID 与 Authenticode 的发布方式下, 怎样做到不伤人」。

模块 职责
scan 扫描编排:ScanTarget::{Quick,Full,Paths} → 采集 → 判定 → ScanReport。Guard 装配规则、哈希表、缓存与排除项
rules YARA-X Detector、HashIndex,以及决定「这个文件值不值得打开」的门(plausible_by_name_in / worth_scanning_in / layout_of)
heuristics 无签名 / 世界可写 / 登录项 / 伪装名称,产 Evidence;CEILING = Suspicious,永远到不了 Confirmed
findings Confidence::{Advisory,Suspicious,Confirmed}、Evidence(带 key() 与 summary())、Finding
coverage 每个 root 的结果:walked / denied / absent。读不到不等于干净,二者在报告里是不同的值
quarantine 账本 + 惰性对象 + 字节一致恢复
intel 规则包格式、验签、安装与回退
store 判定缓存(按文件身份)+ 上一次扫描 + 最近活动,落 <state>/security/

squid-guard 刻意不依赖 squid-engine:清理引擎的一切前提都是「这东西可再生,删了 没事」,而隔离的全部难度恰恰在于「这是用户自己的文件,必须能原样放回去」。它复用 Progress、CancelToken 与 paths,但不复用删除路径。

三条不变量,都有测试钉住:

  1. 扫描不删除任何东西。 唯一会移动文件的是隔离,而隔离只接受后端发出的 finding id。 界面永远不能提交一个路径来要求隔离:security_quarantine(finding_id) 查的是后端自己 存下的那份扫描,再核对哈希、大小与文件身份;扫描之后被换过的文件会被拒绝,而不是按 一行过期记录搬走。
  2. 只有 confirmed 可能被自动隔离,且默认关闭(security.auto_quarantine = false)。 suspicious 只报告。级别由两处分别决定后取最大值:已发布探测器(哈希 / YARA)按自己的 等级说话,启发式则要求两个信号互相印证——单个「无签名」是提示,「无签名 + 开机启动」 才是可疑。这一条是实测逼出来的:一台干净的 Mac 按旧规则会报出 975 条可疑,其中 951 条 只是「带执行位的文本文件」,而这么长的列表最终的下场是被人整个忽略掉。
  3. 不上传。 这个 crate 里没有任何函数接收本地路径再发出网络请求。规则包只下载。

xprotect update 永不被调用:这台机器要不要向 Apple 的服务器取定义,不是第三方 App 能 替用户决定的事。squid-platform::protection 只读 status / version / spctl,读不到 就报 known = false,界面据此显示「无法确认」而不是绿色。

门(gate)比规则更决定可用性。 一次快速扫描会路过约 105 万个文件,其中 34 万个是没有 扩展名的数据文件。判定顺序按代价排列:名字(免费,遍历时已经在手)→ stat(大小、执行位) → 目录形状(bundle 内部只看主可执行文件与 Info.plist,否则光是 /Applications 就吃掉 十 GB)→ 只有浏览器下载目录才去读头八个字节。用户自己指名的目录是例外:那里按内容判定, 因为 eicar.com 的后缀和它的身份本来就互相矛盾。最终约 1,900 个文件 / 6.2 GB,冷启动 26 秒、命中缓存 9 秒。

一处性能教训值得留在这里:判定缓存与候选去重原本都是 Vec 加 paths::same_path 线性 查找,而 same_path 每次比较都要重建一条路径的组件向量。15,000 个文件下这就是几十亿次 字符串分配——快速扫描跑十分钟、CPU 满核,看着像磁盘慢,其实是纯 CPU。现在两处都按 paths::canonical_key 建索引,并且有测试断言 canonical_key 与 same_path 判定一致: 键和判定不一致,就等于把一份缓存结论用到了另一个文件身上。

隔离区不是废纸篓。对象被放进 Squid 自己的状态目录、清掉执行位、权限收紧到仅属主,账本与 对象放在一起,所以「隔离了一个登录项」意味着它下次开机真的不会起来。恢复按原始路径、模式 与时间戳放回,且恢复前要确认。

规则包与安装包用不同的密钥签名:轮换发布密钥不应该顺手改变谁能推规则,泄漏了安装包 密钥也不应该变成一条规则注入路径。包格式把 manifest 与 source 存在同一个文件里,读到什么 就一起验什么,避免「新包配旧 manifest」这种两半漂移。任何一次更新失败都保留上一版可用 规则,并且会清空判定缓存——旧规则给出的结论不是新规则给的结论。

squid-cli

clap derive。约定:

  • --json 时 stdout 只允许是数据。所有人类可读输出经 DIAG_STDERR 改道 stderr,squid clean --json | jq 永远干净;
  • stdin 不是 TTY 且没有 -y/--yes 时,拒绝执行真实删除;
  • 输出宽度按 terminal_width() 自适应,列宽用显示宽度(CJK 占两列)对齐,clip 截断 + fit 补空格。

安全模型(分层)

层 位置 拦截什么
规则自我约束 squid-rules protect、min_age_days、select_by_default=false、risky、skip_if_running、os
锚点边界 CleanupItem::anchors + SafetyPolicy::check 只允许在规则声明的锚点之下删除,且永不删除锚点自身
硬性禁区 safety::HARD_DENY /、/usr、/System、/Library、/Applications、/private/var/folders、/Volumes… 无论什么规则都拒绝
危险目录 safety::DENY_EXACT ~/Library、~/Documents、~/.ssh、~/.aws、~/Library/Application Support/MobileSync… 允许删子项、禁止整目录递归删
深度 / 家目录 / 符号链接 SafetyPolicy{min_depth, allow_system_paths, follow_symlinks} 非 root 时拒绝家目录之外的路径(OUTSIDE_HOME_OK 例外);递归删除必须有最小深度;永不跟随符号链接
卷 forbidden_mounts 由 platform.volumes() 注入,不删别的卷
用户白名单 Engine::is_whitelisted glob 命中即永不选中
运行时状态 LockReason App 正在运行、被其它安装共享、权限不属于当前用户
兜底 默认 Trash + --dry-run + 账本 + undo 前面全漏了还能还原

Engine::new() 会根据是否 root 选择 SafetyPolicy::system() 或 user_only(),后者拒绝家目录之外的路径, 例外只有 OUTSIDE_HOME_OK = ["/Applications"]:管理员组的普通用户在 Finder 里把 App 拖进废纸篓不需要密码, 卸载器必须做同一件事。例外只覆盖 /Applications 里的条目(目录本身仍在 HARD_DENY), 且 root 拥有的 App 早在 build_plan 就被 writable_by_us 锁住了。

事故记录:卸载「成功」了,App 还在

一次用户反馈「选中 Chatbox → d → 确认 → 毫无反应」,最后挖出四层独立原因,每一层都足以让事故静默:

  1. pending_plan 从未被赋值(见下一节);
  2. 任务运行期间所有变更键被 if self.busy() { return } 静默吞掉,confirm_delete() 还会顺手清空 confirm + pending——用户的「是」被吃掉了。现在统一走 App::busy_refusal(),明确提示「上一个任务 还在进行,或按 c 取消」,并且保留审批;
  3. App 本体的锚点不存在:.app 条目过去复用 default_anchors(),而那份锚点表里根本没有 /Applications——它是「squid 被允许进去打扫的文件夹」清单,应用程序目录不是。于是每个卸载计划都是 批准 6 项、删除 5 项,.app 带着「outside every declared cleanup anchor」被跳过。现在 bundle_anchors() 取 bundle 的父目录作为锚点,既最小又不越权;
  4. 非 root 走不到 /Applications:user_only() 的家目录规则把系统 App 一律拒绝。见上面的 OUTSIDE_HOME_OK。

同一次排查还修了 Plan 视图的一个隐性错位:它用 index == 0 认定第一行是「应用本体」,而 build_plan 是按体积降序排序的——一旦某个容器比 App 大,就有一项残留被藏进表头、下面每行都错一位。 现在按 rule_id == "uninstall-bundle" 识别,行与光标严格一一对应。

教训写进断言里:the_bundle_itself_passes_the_safety_policy、 a_plain_user_can_still_uninstall_into_applications、a_busy_app_answers_instead_of_ignoring_you、 the_plan_view_shows_the_bundle_and_every_leftover(后者读回测试缓冲区:三项计划必须画出三个勾选行、 表头文案不得占据其中任何一行、加粗的那一行永远是 .app、光标落在哪一行就高亮哪一行)。 删除路径的测试必须把沙盒建在真实形态的位置上:早先的卸载测试把假 App 放在 ~/Library/Caches/… 下, 正好落在锚点里,所以这个 bug 一路绿灯。

数据流

config.toml ─┐
             ├─► Engine{platform, settings, rules, safety, whitelist}
rules/*.toml ┘                         │
                                       ├── scan() ─► Vec<CleanupItem> ─► CLI 表格 / TUI 面板
                                       │                                       │ 用户勾选
                                       │                                       ▼
                                       └── delete::execute(DeleteJob) ─► SafetyPolicy 复检
                                                  │                       fs::remove_item_with
                                                  │                       ledger::write_session
                                                  ▼
              ~/Library/Application Support/squid/history/<session>.json
                                                  │
                                          squid undo ─► ledger::restore ─► rename 回原路径

性能

体积测量是这类工具唯一的重活。做法:walkdir(contents_first(false)、max_open(64)、跳过符号链接)单目录内顺序遍历,measure_all 在条目之间用 rayon 并行(线程数 clamp(4,16)),每完成一个条目就发一次进度事件,所以 UI 的进度条是真实进度而不是假动画。purge 用 max_entries 限制单项目文件数、MAX_DIRS 限制总目录数,超限时明确标注结果是下限。实测 clean --dry-run 在 18 万条目 / 30 GB 量级上约 5 秒。

跨平台移植指南

新增一个平台 = 实现 Platform + 提供规则文件,引擎与 UI 一行都不用改。

  1. 新建 squid-platform/src/<os>.rs,实现 Platform;在 lib.rs::current() 里返回它。
  2. 决定 app_sources() 与 leftover_roots():命名方式(bundle id / 名称 / 容器)决定残留匹配器怎么配。
  3. 补 safety::HARD_DENY / DENY_EXACT 里该系统的禁区(Windows:C:\Windows、C:\Program Files;Linux:/snap、/nix、/var/lib)。
  4. 新增 crates/squid-rules/rules/<os>.toml,并在 RuleSet::builtins() 里 include_str!。规则里的 os = [...] 字段决定它在哪个平台生效。
  5. 回收站语义:fs::trash_target_for 需要该系统的回收站位置与命名规则(macOS 是 ~/.Trash 与卷根 .Trashes/<uid>;Linux 是 XDG ~/.local/share/Trash/files;Windows 需要 $Recycle.Bin 或 Shell API)。
  6. 提权:macOS/Linux 用 sudo 重跑(needs_admin 的规则在非 root 时只报告不执行);Windows 需要 UAC。

现状:macOS 完整;Linux 有 .desktop/Flatpak/Snap 与 XDG 残留实现,缺规则文件与真机验证;Windows 平台层已实现并在真机跑通(注册表卸载表、AppData 残留、卷枚举、IFileOperation 回收站、console 的尺寸与字形探测),缺 UAC 提权与长路径 manifest。

测试策略

166 个测试(cargo test --workspace)。三类:

  • 纯逻辑:字节格式化、glob 与锚点、规则解析、名称匹配、安全策略拒绝表 —— 这些是最有价值的,因为它们把「曾经出过的事故」变成断言。
  • 引擎级:在临时目录 / ~/Library/Caches/squid-delete-test-* 里搭沙盒,跑真实 scan + delete。
  • 状态隔离:删除类测试必须调用 isolate_state(),用 SQUID_STATE_DIR 把账本重定向到临时目录,否则测试会话会污染用户真实的 squid history。

约定:CI 门禁是 cargo clippy --workspace --all-targets -- -D warnings + cargo test --workspace --no-fail-fast。任何删除相关改动必须同时提供 Trash 往返(delete → undo → 字节一致)测试。

确认框背后的不变量:Approval 枚举

TUI 的「按 d → 确认 → 执行」曾经出过一次典型的静默失败:App 上有两个平行字段 pending: Option<Vec<CleanupItem>> 与 pending_plan: Option<UninstallPlan>,卸载流程只写了 后者对应的读逻辑,pending_plan 从来没被赋成 Some,于是 confirm_delete() 里 let Some(plan) = self.pending_plan.take() else { return } 直接返回——用户按了回车,什么也没发生, 什么也没说。

修复方式不是补一行赋值,而是让非法状态无法表达:两个字段合并成 pending: Option<Approval>,Approval 是 Items { items, purge } | Plan(UninstallPlan) | UndoSession(String) | StopProcess(ProcessSample) 四个变体。多出来的那个是系统状态面板的「强制结束进程」,它同样必须先构造出自己才问得出确认框;它带的是 sample 而不是 pid,因为 pid 是重复发放的座位号、不是人:用户读到的是名字,会被杀掉的是号码,把两者分开的唯一办法是把它们一起带到执行处(复核在 squid_stats::Sampler::stop)。ask_delete() 与 ask_stop_process() 都必须构造其中一个才问得出确认框;确认框能打开, 就必然有可执行的内容。confirm_delete() 对 None 的情况显式 toast「没有待确认的内容,请重新按 d」, 把「静默」变成「可见」。app.rs 里那三个回归测试直接驱动 ask_delete() → confirm_delete() → poll() 到任务结束,断言 outcome.summary.removed == N,覆盖卸载、清理/深度清理、以及空确认框三条路径。

许可证

squid 以 GPL-3.0-only 发布,全文见仓库根目录的 LICENSE。七个 crate 通过 [workspace.package] license 继承同一份许可,scripts/release.sh 把 LICENSE 与 README.md 一起打进发布包,packaging/homebrew/squid.rb 声明同一 SPDX 标识符。