nex_squid/README.md

280 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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`](docs/DESKTOP.md)。
## 快速开始
### 桌面端开发
环境要求:
- Node.js 20+ 与 pnpm
- Rust stable
- macOS:Xcode Command Line Tools
- Windows:MSVC Build Tools 与 WebView2 Runtime
```bash
pnpm install
pnpm desktop:dev
```
仅运行 Vite 页面时无法调用 Tauri 命令;需要验证扫描、删除、系统数据或更新流程时请使用 `pnpm desktop:dev`。
### CLI / TUI
```bash
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`。
## 架构
```text
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/ 架构、设计、桌面与发布规范
```
核心依赖方向:
```text
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`](docs/ARCHITECTURE.md);Nex 系列统一颜色、字体和组件常量见 [`docs/DESIGN.md`](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 共用配置和历史,因此任一端产生的清理记录都能在另一端查看。
常用配置:
```toml
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 控制台字符宽度与排版 |
## 开发与验证
前端:
```bash
pnpm check
pnpm build
```
Rust workspace:
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```
Tauri:
```bash
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 控制台另有“抓帧、复放、量框”验证:
```bash
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`
构建安装包:
```bash
scripts/build-macos-release.sh
scripts/build-windows-release.sh
```
产物:
```text
artifacts/Squid-<version>-macOS-universal.dmg
artifacts/Squid-Setup-<version>-win-x64.exe
artifacts/SHA256SUMS.txt
```
发布到更新通道:
```bash
scripts/publish-release.sh --notes /path/to/release-notes.md
```
发布脚本会重建 `releases` 分支,写入 `squid-update.json`、两个安装包和可选的 `squid-update.sig`。清单包含精确大小与 SHA256,客户端下载后再次校验。
完整发布流程、签名和清单格式见 [`docs/RELEASE.md`](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`](LICENSE)。