nex_squid/README.md

10 KiB
Raw Blame History

Squid

给你的电脑洗个澡。

Squid 是面向 macOS 与 Windows 的本地系统维护工具:清理可重建的缓存与系统垃圾、卸载应用并处理残留、清理项目构建产物、分析磁盘占用,以及实时查看系统状态。

桌面端、命令行与 TUI 共用同一套 Rust 扫描和删除引擎。清理规则、安全边界、删除账本与配置只维护一份,不依赖云端服务,也不需要 root。

产品组成

入口 技术栈 二进制
桌面应用 Tauri 2 + React 19 + TypeScript + Vite 6 squid-desktop
命令行 Rust + clap squid
终端界面 Rust + ratatui + crossterm squid state

桌面端支持 macOS 12+ 与 Windows 10/11 x64;CLI/TUI 使用同一个 Rust workspace。

功能

功能 说明
电脑概览 磁盘健康、常用操作入口与 CPU、内存、存储摘要
日常清理 macOS 38 条 / Windows 30 条内置规则,覆盖应用与浏览器缓存、日志、崩溃报告、开发缓存与废纸篓等
应用卸载 按名称定位应用,把应用本体与偏好、缓存、容器或 AppData 残留组成同一个卸载计划
深度清理 查找 node_modules 等可重建构建产物、磁盘镜像、安装包和陈旧下载,并保护近期仍在使用的项目
存储空间 逐层测量目录、查看最大子项与最大文件
实时监控 每两秒采样 CPU、内存、网络、磁盘、电池、卷和高占用进程,可确认后结束进程
历史与撤销 每次真实删除写入本地账本;仍在废纸篓或回收站中的内容可以还原
系统更新 从发布分支检查、校验、下载并安装新版本

界面支持中文和英文,跟随 Squid 的语言设置与系统语言。

桌面应用

左侧菜单

  • 维护:电脑概览、日常清理、应用卸载、深度清理
  • 洞察:存储空间、实时监控
  • 底部:历史记录、设置

⌘1–⌘8(macOS)或 Ctrl+1–Ctrl+8(Windows)可以直接切换页面。

常驻托盘

关闭主窗口只会隐藏窗口,Squid 进程继续运行。托盘菜单提供:

  • 打开 Squid
  • 日常清理
  • 应用卸载
  • 深度清理
  • 退出 Squid

再次打开应用、双击应用图标或通过单实例唤起时,会恢复并聚焦主窗口。只有选择“退出 Squid”才会结束进程。

软件更新

  • 设置中的系统信息面板始终显示当前系统版本、架构与 Squid 版本。
  • 只有检测到更高版本时,才显示版本变化和更新说明;已经是最新版本时不显示额外提示。
  • 自动检查默认开启,每天最多检查一次。
  • 安装包必须通过 SHA256 与文件大小校验;带发布公钥的构建还会校验清单的 Ed25519 签名。

权限与隐私

  • 首次启动会显示一次可选的全盘访问检查,不会强制弹出 macOS 权限窗口,也不会阻止应用启动。
  • “设置 → 系统权限”提供权限状态检查和打开“系统设置 → 隐私与安全性 → 全盘访问”的入口。
  • 没有全盘访问时,受 TCC 保护的位置会被跳过,其余功能仍然可用。
  • 存储分析与深度清理只在用户选择或配置目录后读取;文件内容不会上传。
  • 除更新检查和安装包下载外,应用不发起网络请求。

完整说明见 docs/DESKTOP.md。

快速开始

桌面端开发

环境要求:

  • Node.js 20+ 与 pnpm
  • Rust stable
  • macOS:Xcode Command Line Tools
  • Windows:MSVC Build Tools 与 WebView2 Runtime
pnpm install
pnpm desktop:dev

仅运行 Vite 页面时无法调用 Tauri 命令;需要验证扫描、删除、系统数据或更新流程时请使用 pnpm desktop:dev。

CLI / TUI

cargo install --path crates/squid-cli
# 或
cargo build --release -p squid-cli

squid state                       # TUI
squid status                      # 系统快照
squid clean --dry-run             # 预览可清理内容
squid uninstall --list            # 已安装应用
squid purge ~/code                # 深度清理项目构建产物
squid analyze ~/Library/Caches    # 存储分析
squid history                     # 历史账本
squid undo                        # 还原最近一次废纸篓会话

常用命令:

命令 作用
clean 按规则清理缓存、日志、浏览器与开发者垃圾、崩溃报告和废纸篓
uninstall [NAME] 定位应用并生成“本体 + 残留”卸载计划
purge [PATHS…] 清理项目构建目录、磁盘镜像、安装包与陈旧下载
state 打开包含清理、卸载、深度清理、存储、系统和历史面板的 TUI
status 输出 CPU、内存、网络、磁盘、电池与进程快照
analyze [PATH] 输出目录体积树与最大文件
history / undo [ID] 查看历史或还原废纸篓会话
whitelist add|list|remove 维护永不选中的保护路径
rules 列出当前生效的规则
doctor 检查权限、配置、历史文件和生效路径

所有删除命令都支持 --dry-run;非交互环境必须使用 -y/--yes。完整参数请运行 squid <command> --help。

架构

crates/
├── squid-core       模型、路径、安全策略、设置、删除账本、进度与取消
├── squid-platform   macOS / Linux / Windows 平台适配:应用、残留、卷、回收站、进程
├── squid-rules      TOML 规则引擎:模式展开、锚点、保护、年龄与风险标记
├── squid-stats      sysinfo 采样、趋势、电池、网络与磁盘活动
├── squid-engine     clean / uninstall / purge / analyze 与唯一删除通道
├── squid-tui        ratatui 终端界面
└── squid-cli        clap 命令行入口

src/                 React 桌面界面
src-tauri/           Tauri 壳、命令适配、托盘、权限检查与更新器
scripts/             开发、验证与双平台发布脚本
docs/                架构、设计、桌面与发布规范

核心依赖方向:

squid-core → squid-platform → squid-rules → squid-stats → squid-engine → squid-tui → squid-cli

src-tauri 独立于根 Cargo workspace,但直接依赖 squid-core、squid-platform、squid-stats 与 squid-engine,桌面端不维护第二套清理实现。

更多设计见 docs/ARCHITECTURE.md;Nex 系列统一颜色、字体和组件常量见 docs/DESIGN.md。

安全模型

  1. 索引式删除:桌面界面只能提交扫描结果中的索引,不能提交任意待删除路径。
  2. 执行前复验:Rust 层重新构造扫描条目,并检查路径所有权、安全锚点、保护列表、白名单与锁定状态。
  3. 默认进废纸篓:删除模式默认是 trash;只有显式选择永久删除才直接移除。
  4. 硬性禁区:系统根目录、/usr、/System、/Applications 等位置不能被递归删除;符号链接不会被跟随。
  5. 规则刹车:规则支持 protect、min_age_days、skip_if_running 与 risky 标记。
  6. 账本与撤销:真实删除记录到本地 JSON 账本,仍在废纸篓中的文件可以还原。
  7. 进程保护:结束进程前重新采样并核对名称,拒绝 Squid 自身、系统首进程和关键系统进程。

GUI 和 CLI 使用同一个 squid-engine::delete 通道,因此行为、锁定和审计结果一致。

数据与配置

用途 macOS Windows
配置与规则 ~/Library/Application Support/squid/ %APPDATA%\squid\
历史账本 ~/Library/Application Support/squid/history/ %APPDATA%\squid\history\
删除去向 ~/.Trash 或永久删除 回收站或永久删除

Linux 使用 XDG 目录。桌面端与 CLI/TUI 共用配置和历史,因此任一端产生的清理记录都能在另一端查看。

常用配置:

delete_mode = "trash"
history_keep = 60
purge_min_age_days = 7
purge_max_entries = 200000
show_allocated = true
language = "zh"                      # en | zh
whitelist = ["~/Library/Caches/ImportantApp"]
disabled_rules = ["user-trash"]
purge_roots = ["~/code", "~/Projects", "~/Desktop"]

主要环境变量:

变量 作用
SQUID_CONFIG_DIR 覆盖配置目录
SQUID_STATE_DIR 覆盖状态与历史目录
SQUID_LANG 强制 zh 或 en
SQUID_UPDATE_URL 覆盖桌面端更新清单地址,适合测试发布通道
SQUID_TRUECOLOR / NO_COLOR 控制 TUI 颜色
SQUID_SYMBOL_CELLS / SQUID_CONSOLE_TRACE 排查 Windows 控制台字符宽度与排版

开发与验证

前端:

pnpm check
pnpm build

Rust workspace:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Tauri:

cargo fmt --manifest-path src-tauri/Cargo.toml -- --check
cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path src-tauri/Cargo.toml --lib

TUI 使用真实 pty 冒烟测试;Windows 控制台另有“抓帧、复放、量框”验证:

python3 -m pip install --user pyte
python3 scripts/tui_smoke.py
python3 scripts/tui-frame-check.py --selftest

CI 同时执行 workspace 测试、MSVC 目标交叉检查、桌面前端构建和 Tauri Rust 检查。

打包与发布

版本必须同时写入以下四处:

  • Cargo.toml workspace 版本
  • src-tauri/Cargo.toml
  • src-tauri/tauri.conf.json
  • package.json

构建安装包:

scripts/build-macos-release.sh
scripts/build-windows-release.sh

产物:

artifacts/Squid-<version>-macOS-universal.dmg
artifacts/Squid-Setup-<version>-win-x64.exe
artifacts/SHA256SUMS.txt

发布到更新通道:

scripts/publish-release.sh --notes /path/to/release-notes.md

发布脚本会重建 releases 分支,写入 squid-update.json、两个安装包和可选的 squid-update.sig。清单包含精确大小与 SHA256,客户端下载后再次校验。

完整发布流程、签名和清单格式见 docs/RELEASE.md。

平台状态

平台 状态
macOS 桌面端与 CLI/TUI 完整支持,发布通用 DMG
Windows x64 桌面端与 CLI/TUI 支持,发布 NSIS 安装包
Linux 平台层与 CLI/TUI 基础实现;尚未提供内置 Linux 规则和桌面安装包

许可证

Squid 使用 GNU General Public License v3.0 only(GPL-3.0-only)。完整条款见 LICENSE。