SweepX

SweepX 是一个安全优先的 Rust 磁盘分析项目。 当前仓库包含可运行的开发版 CLI/TUI、显式确认的系统回收站预览，以及 P3 的计划、simulation-only 授权、审计恢复与确定性模拟执行库；它还不是已发布产品，也没有永久删除能力。

[!CAUTION] trash 是当前唯一真实文件变更能力：只接受绝对路径，默认交互确认，提交前重验类型和身份，并且只移到操作系统回收站。它没有 Permanent fallback。仓库仍没有 plan、approve、execute 或永久删除 CLI。

当前实现状态

状态截点：2026-08-29。以下描述来自当前代码与测试，不是发布或跨平台资格声明。

CLI 和 TUI 支持 zh-CN 与 en-US。它们会从 locale 环境自动选择语言，也可以用 --locale zh-CN 或 --locale en-US 显式覆盖；机器输出字段和值保持稳定，不随翻译改变。

安装

发布页会提供一个统一的 sweepx 二进制。安装器下载与当前平台匹配的归档，校验 SHA256SUMS，并拒绝包含额外文件的归档。

Linux / macOS：

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/lejunyang/sweepx/main/install.sh | sh

Windows PowerShell：

irm https://raw.githubusercontent.com/lejunyang/sweepx/main/install.ps1 | iex

也可以从 GitHub Release 下载对应的 .tar.gz / .zip 与 SHA256SUMS 后手工校验。当前构建矩阵包含 Linux x86_64/aarch64、macOS Intel/Apple Silicon 和 Windows x86_64；二进制存在不等于对应平台的扫描能力已合格，具体以 sweepx capabilities 为准。

发布门禁

普通 push/PR 会运行 Rust、schema、站点、安装器和 native CLI CI；main 上的文档会独立部署 GitHub Pages。只有 HEAD commit message 包含字面量 [publish] 时，才会发布二进制和 crates.io 包。GitHub Release 与 Pages 使用仓库自带的 GITHUB_TOKEN；crates.io 需要在受保护的 crates-io environment 中配置 CARGO_REGISTRY_TOKEN。完整步骤见 RELEASING.md。

运行只读能力

需要仓库声明的 Rust toolchain。下列命令只展示当前存在的接口；请始终使用你明确选择的绝对路径。

# 查看当前能力矩阵
cargo run -p sweepx-cli -- --locale zh-CN capabilities

# 执行 development-grade/degraded 的只读扫描；默认直接显示有界终端表格
# Linux 可选择 SQLite journal 目录，macOS 可选择 legacy snapshot 目录；Windows 不要传 --state-dir
cargo run -p sweepx-cli -- scan /absolute/path/to/root

# 不传路径时扫描当前平台文件系统根（可能较慢，并受资源上限约束）
cargo run -p sweepx-cli -- scan

# 不需要后续 status/operation state 时关闭状态写入；也适用于 journal 不支持的文件系统
cargo run -p sweepx-cli -- scan --no-state /absolute/path/to/root

# 扫描后进入文件管理器式 TUI（Enter/Right 进入，d/Delete 移到回收站）
cargo run -p sweepx-cli -- scan --tui /absolute/path/to/root

# 显式将一个绝对路径移到系统回收站；默认询问确认
cargo run -p sweepx-cli -- trash /absolute/path/to/item

# 仅在脚本或集成需要时显式请求 JSON
cargo run -p sweepx-cli -- \
  --format json scan /absolute/path/to/root > /absolute/path/to/scan.json

# Linux 从 journal、macOS 从 legacy state 读取扫描结束时保存的 snapshot
cargo run -p sweepx-cli -- \
  --format json \
  --state-dir /absolute/path/to/sweepx-state \
  status --operation-id <OPERATION_ID>

# 只读 preview cache 诊断；缺失缓存返回 absent 且不创建目录
cargo run -p sweepx-cli -- \
  --format json \
  --state-dir /absolute/path/to/sweepx-state \
  cache status

# 从有界的导入 JSON 生成 report-only 解释
cargo run -p sweepx-cli -- \
  --format json \
  explain --scan-json /absolute/path/to/scan.json

# 读取内置 Cleaner 元数据
cargo run -p sweepx-cli -- --format json cleaner list
cargo run -p sweepx-cli -- --format json cleaner show <CLEANER_REF>

# 实验性 live-only Cargo target 检测；默认 human 输出列出 target、大小与 report-only 原因
cargo run -p sweepx-cli -- cleaner cargo-detect /absolute/path/to/workspace

# 统一垃圾识别入口：首批覆盖常见项目构建产物，结果只报告不删除
cargo run -p sweepx-cli -- junk ~/Projects
# 扫描当前平台经过核验的用户缓存根（只报告）
cargo run -p sweepx-cli -- junk --system

scan 接受相对路径、~、一个或多个绝对根；不传路径时扫描当前平台文件系统根。scan --no-state 跳过 operation snapshot/event journal，适合不需要后续 status/operation state 或 state filesystem 不支持 journal 的显式只读扫描；它不能与 --state-dir 同时使用。默认 human 输出最多显示 40 行，按可回收大小降序，并用自动人类单位；--unit auto|b|kib|mib|gib|tib 与 --sort size|path 可覆盖。>= 表示受边界影响的下限，不是精确值；“可回收”是预计可释放的独占分配空间，不等同逻辑大小，也不作释放保证。json 始终保留精确字节。scan --format ndjson 会在扫描前以 unsupported 拒绝。Linux 已接入 bounded SQLite journal，在单个事务中写入完整事件流与 terminal snapshot；Core 的 status 优先读取 journal。Linux 现支持 sweepx --format ndjson status --operation-id <OPERATION_ID> --watch [--after SXCUR1...] 的 completed-stream replay。TUI 只做 root admission 就进入界面，单根自动进入；当前层先展示，直接子目录大小随后由后台递归聚合回填，后代不作为 TUI 行长期保留。目录 detail rescan 使用 single-flight 后台任务，deadline 为 30 s，导航或退出不会等待非协作 worker。explain 默认最多读取 8 MiB 的导入 JSON。

cache status 是独立的只读 preview cache 诊断表面，输出 kind 为 cache.status.result。Linux 与 macOS 支持 human/json，Windows 当前 disabled；--format ndjson 在创建或读取任何 state 目录之前就以 usage error 拒绝。若默认或显式 state/cache 缺失，命令返回 disposition=absent、exit 0，且不创建 state_dir、preview-cache/、current.json 或其他缓存目录。检查范围只限 preview-cache/current.json、当前 generation 文件、generations/ 与 quarantine/ 的浅层结构、近似字节数、当前指针健康和 stored-generation schema/checksum/provenance 健康；它不会触发 scan、repair、quarantine 或 cache rebuild，也不会暴露 cache entries、display path 或预览内容。available 只表示缓存结构和校验在当前读取范围内可用，不代表 live/current 文件事实。只要存在 warning、error 或 quarantine presence，结果就降为 degraded 并以 exit 4 返回。

库集成方可以调用 sweepx_core::cleaner_cargo_detect_with_cancel 并持有传入的 sweepx_core::CancellationToken。这个 token 的作用域刻意很窄：它只由同步 scan 完成后的 Cargo fixed-input/evidence collection 检查，不拥有也不会中断此前的同步 scan。若收集阶段观察到取消，相关 typed evidence 失败关闭为 unknown(cancelled)，terminal envelope 使用 status=cancelled、exit 10 和 reasonCode=cancelled；已有输出仍只用于 hint/report-only，取消不会授予 candidate、plan、approval、execution 或 mutation authority。

status 与 cancel 的诚实语义

当前扫描是同步命令。Linux 上 status journal-first 读取扫描结束时写入的 terminal snapshot，并支持 sweepx --format ndjson status --operation-id <OPERATION_ID> --watch [--after SXCUR1...] 的 degraded completed-stream replay：它只覆盖已完成且已持久化的 journal stream，先做一次同 snapshot 全量校验，随后按每页最多 1024 条事件续读；unknown 但语法有效的 cursor 返回 stream.reset_required，malformed cursor/usage 返回 usage error。它不等待新事件，不创建后台 operation，也不支持 cancel，因此不是 live progress。macOS 读取 legacy operation snapshot，仍无 replay/watch；Windows durable snapshot state 完全禁用：默认 state_dir=None，不写 terminal snapshot，显式 --state-dir 失败关闭。cancel 不伪装成可用能力：对于缺失或已经结束的 operation，它返回明确 disposition，而 capability matrix 将 cancellation 标记为 disabled。Cargo 检测的 caller-owned post-scan token 是独立的 library cooperative-cancellation seam，并未与该命令或 live operation registry 连接；当前 CLI 也没有 Ctrl-C handler 来触发它。

导入 JSON 永远不是执行依据

explain --scan-json 会接受符合 scan.result 合同的有界 JSON。导入时，路径证据会被标记为 stale preview，coverage 被降级为 incomplete/not revalidated，因此解释只能用于报告。它不会创建可执行候选、计划、授权或 permit。scan --tui 不走导入路径，而是只读浏览本次 live scan 的 typed 结果。

Cleaner 概念

Cleaner 不是任意脚本或“目录名匹配后删除”的别名。一个 Cleaner package 描述版本化 manifest、证据、规则和 Core 兼容范围。当前 CLI 只允许：

• cleaner list：列出内置 package 及兼容性；
• cleaner show：仅在兼容性检查通过后展示 manifest 与规则元数据；
• cleaner cargo-detect：实验性、只读；Cleaner 兼容性先于扫描和规则求值检查。当前实现经由 Scanner 的有界 locator batch reader 收集固定输入；workspace 收集器只读取已 admission 的 Cargo.toml 与 .cargo/config*。两份 workspace config 通过同一个 retained .cargo handle 和单个有界枚举 cursor 观察，ASCII 大小写 alias 与重复项失败关闭；由于目录枚举不能排除 ABA，该观察仍是 non-atomic。workspace 证据在 manifest 合法且绑定成立时可为 known，同时 data.hints[].evidence.cargo.configScope 会输出 cargo.config-scope.v1：顶层字段为 schema、decoderId、workspace、ancestorConfigs、cargoHomeConfig、environment、cli、invocationCwd、precedenceComplete、blockers[]。其中 workspace.pairSnapshot 的状态是 stable_snapshot|not_checked|failed，workspace.config/configToml 的合同枚举是 present|verified_absent|not_checked|failed，但当前生产路径在 pair 非稳定时会把时间点式 absence 降为 not_checked；workspace.selected 是 config|config_toml|none|not_checked，workspace.targetDirDeclaration 是 known|verified_absent|not_checked|unknown。environment 只记录 CARGO_TARGET_DIR、CARGO_BUILD_TARGET_DIR、CARGO_HOME 是否 present_redacted|verified_absent；valueRedacted 字段始终存在，前者为 true、后者为 false，从不序列化变量值。workspace config 的 target-dir 也只在 known 时暴露 source 与 valueRedacted=true，不输出原始相对路径值。只有显式绝对 CARGO_HOME 会在 compatibility gate 通过后被私下捕获并在 scan 后重验；collector 随后只观察 home 根下直属 config / config.toml 的存在性，命中投影为 cargoHomeConfig.state=present_redacted，并且只能对应 cargo_home_config_present_redacted blocker。该观察不提供原子 pair/absence 证明：未命中以及未显式设置、使用默认 home 的情况保持 not_checked，并且只能对应 cargo_home_config_not_checked blocker；失败只对应 cargo_home_config_failed。为验证 presence integrity，scanner 只做有界、no-follow、handle-bound 的 metadata inspection；配置内容不会被读取、解析、使用或序列化，target-dir 值也不会被提取，ledger 不包含环境值或 home/config 路径。SweepX 的 cargo-detect CLI 没有 Cargo passthrough --target-dir 或 --config，因此 cli.targetDir 与 cli.configOverrides 当前是结构性 verified_absent，而不是 not_checked。process cwd 也只在 compatibility gate 通过后私下捕获并记录 capture-time identity；随后只与重验后的 workspace root 比较精确 native path 和 identity。匹配时仅投影 path_matches_revalidated_workspace_root，且因未跨阶段持有 cwd handle 而保留 invocation_cwd_identity_not_bound blocker；cwd path 本身不进入序列化结果。未观察到的 workspace config 成员仍保持 not_checked；没有平台密封的抗 ABA 目录 generation 证明时，不能把联合 presence/absence 提升为稳定选择。Cargo-home presence ledger 不读取、解析、使用或序列化配置内容来闭合 precedence，ancestor configs 与 workspace pair 也仍未解决；因此 precedenceComplete 继续为 false，targetDir 继续是 not_checked(config_scope_not_checked)，而依赖它的 targetShape 继续是 unknown(config_scope_not_checked)。因此 Cargo.toml + target/ 名称目前仍只形成 hint，candidateAllowed、planAllowed、approvalAllowed、executionAllowed 全部为 false；
• Core 另提供 cleaner_cargo_detect_with_cancel，由库调用方持有 cancellation token。该 token 只覆盖 scan 之后的 fixed-input/evidence collection；同步 scan 仍独立拥有自己的 token。收集阶段一旦观察到取消便返回 fail-closed 的 cancelled/report-only 结果，而不是继续补全证据或扩大权限；
• 对不兼容、未知版本或证据不足的内容保持 partial、report-only 或失败关闭。

Cargo Cleaner 现在声明 >=0.1.0, <0.2.0 并与当前 Core 兼容；Chromium Cleaner 仍要求 >=1.0.0, <2.0.0，因此 catalog 仍会诚实报告 partial。Cargo detector 只扫描并输出 report-only 观察，不会调用 cargo clean 或获得删除权限。

安全模型

已经落地的只读边界与未来 mutation 设计共享以下原则，但只有经过实现和相应测试的部分才是当前能力：

1. 普通用户、只读优先。 默认扫描不请求 UAC、sudo、polkit 或其他提权，并保持 no-follow、边界可见和错误可见。唯一例外是用户显式传入 --elevate：它在 Windows 上请求一次 UAC 同意并以提权身份重启进程，用于启用 NTFS 加速扫描路径；不传该参数时永远不会出现提权弹窗。提权只放宽只读加速能力，破坏性操作在提权会话下仍按设计硬拒绝。
2. 观察不等于授权。 Candidate、Explanation、DeletionPlan、ExecutionAuthorization、PreflightPermit、平台结果与审计记录是不同对象。
3. 不确定性不等于零。 unknown、lower_bound、unsupported、not_checked 和 incomplete 不能渲染成已知 0 或“安全”。
4. 导入结果不可执行。 缓存、历史报告、导入 JSON、文件名或年龄都不能成为 mutation authority。
5. 精确计划绑定。 P3 library model 将授权绑定到 canonical plan digest、模式、对象与动作集合、风险、用户、主机、时效和单次使用状态。
6. 审计先于模拟结果。 durable audit model 记录 intent、fence、outcome 与 reconciliation；它目前服务 deterministic simulation，不证明 native adapter 已安全。
7. 没有降级删除。 未来即使实现 Trash，失败、拒绝、取消或结果不明也不得自动转为 Permanent。
8. 硬保护不可绕过。 根目录、系统区域、home/profile 根、SweepX state、受保护 anchor 及其包含关系在未来 mutation model 中必须失败关闭。

P3 executor 是 sealed、serial、deterministic 且 simulation-only：请求只携带 ID，identity/revalidation digest 由 canonical plan 派生，不携带 native path；唯一 adapter 是 fake adapter；所谓 simulated Trash/Permanent 只生成可验证 receipt 和审计状态，不调用操作系统删除接口，也不改变扫描目标。当前 audit/recovery 仍仅支持 Unix；Linux durable event journal 已在单个事务中持久化完整流与 terminal snapshot，并提供 journal-first status 与 degraded completed-stream status --watch replay。该 replay 只重放已完成且已持久化的 stream，先做一次同 snapshot 全量校验，单次请求按每页最多 1024 条事件续读；unknown 但语法有效的 cursor 返回 stream.reset_required，malformed cursor/usage 返回 usage error。由于事件仍在 scan 后批量构造，它不是 live sink，也不等待新事件、不会创建后台 operation，且尚未 runtime-qualified；scan --format ndjson 因此继续 disabled。macOS 仍使用 legacy snapshot；Windows 已可持久化 preview cache 与 operation snapshot（explicit private DACL + owner 校验 + reparse-point 拒绝），但仍无 event journal。因此它既不是 future native mutation 的发布级存储，也不能被写成跨平台或真实执行资格。

P4a.2 又把 mutation 资格拆成五个独立 cell：trash.local.file、trash.local.directory、permanent.local.file、permanent.local.directory 和 permanent.local.link。当前运行平台的两个 Trash cell 以 degraded preview 报告，其余平台与全部 Permanent cell 保持 disabled；preview 不等于发布资格。fixture_conformance_only、fake、stale、incomplete、placeholder 或 mismatched evidence 永远不能把 mutation 标成 qualified；未来也只有 real_os_qualification、validity.status=current 且完整匹配精确 QualificationKey tuple 的 evidence 才可能使对应单元合格。

Agent 权限边界

当前 Agent 可安全协助的范围仅限：

• 查询 capabilities；
• 在用户明确选择的绝对根上发起只读扫描；
• 读取结构化输出并解释边界、错误与不确定性；
• 查看 Cleaner 元数据；
• 打开有界、只读的 TUI 视图。

Agent 不能把聊天中的“可以”变成 HumanApproval，不能构造或消费执行 permit，不能调用未来的 approval UI，也不能调用任何危险删除开关。当前 CLI 根本没有 plan、approve 或 execute 子命令。

未来破坏性接口：仅为提案

下面的命令名只记录路线图方向，当前二进制不接受这些命令：

PROPOSED ONLY — NOT IMPLEMENTED — DO NOT RUN
sweepx plan create ...
sweepx plan show ...
sweepx approve ...
sweepx execute ...
sweepx execute ... --dangerously-delete

若未来实现，它们仍必须遵守 immutable plan、精确授权、live revalidation、durable intent、reconciliation、硬保护和逐平台资格门槛。Permanent 是独立的 R4 能力，不是 Trash 失败后的 fallback，也不是 secure erase。设计状态流是：

scan -> explain -> immutable plan -> explicit authorization -> live revalidation
     -> platform action -> reconcile -> audit

当前已走通只读扫描、TUI 浏览与单对象 path -> Trash preview；scan -> plan -> execute 和 Permanent 路径仍不存在。

平台与发布边界

• Linux scanner 已实现为 development-grade/degraded，只能依据当前测试理解，不能据此宣称生产资格或完整文件系统覆盖。
• macOS scanner 现为 handle-bound degraded live scanner，并通过统一 sweepx scan / scan --tui 接入；这不等于三平台扫描资格完成。
• Windows scanner 现为 development-grade/degraded 的只读 handle-relative live scanner，并通过统一的 scan / scan --tui 接入；这不等于 Windows 或三平台扫描已取得发布资格。
• Windows NTFS 加速扫描路径已接入为预览数据源：资格判定通过时，一次批量元数据读取即产出扫描根的条目数与容量预览（实测 14.5 GB / 36,531 个对象耗时 1.06 s，而完整权威扫描 133 s），但预览标记 authoritative: false 且不携带 reopen recipe，不能据以删除任何对象；可移植的 handle-relative 遍历始终权威，加速资格失败只作为观察事件出现，不影响总计精确性。预览输出与独立目录遍历交叉验证，要求路径集合与字节总和完全一致。实测显示 FSCTL_QUERY_USN_JOURNAL 需要提权下的 GENERIC_READ 卷句柄，低权限句柄即使提权也报告功能不存在，因此未提权时不启用加速是平台属性而非实现缺陷；详见 原生扫描加速验收矩阵。
• P4 的 native Trash beta、P5 的稳定产品和任何 Permanent 能力都仍是未来路线图。
• 已有五目标二进制、校验和、安装器、GitHub Pages 与 crates.io 的发布工作流；尚未实际发布稳定版本，也没有签名、SBOM、provenance 或稳定支持承诺。

文档导航

• 文档站点：中文默认入口与英文镜像内容。
• 总体设计：端到端架构、信任边界与关键决策。
• Cleaner Catalog：生态证据、风险与 report-only 边界。
• MangoDisk 采用决策：规则来源审计、许可证边界与 Linux 策略。
• MangoDisk 未纳入规则：205 条规则的覆盖差距与后续核验批次。
• 原生扫描加速验收矩阵：可先实现项与 Windows/macOS 真机门槛。
• 路线图：当前实现快照、阶段目标、测试矩阵与发布门槛。
• 发布指南：版本、提交消息门禁、token、产物与失败恢复。
• 扫描/缓存架构、安全删除架构与CLI/TUI/Cleaner 架构。

已知缺口

• Linux scan 的性能预算、复杂文件系统语义和故障注入仍需更完整、可复现的验证。
• macOS handle-bound 与 Windows handle-relative 的 degraded live scanner 均已存在，但其资格、覆盖与跨平台一致性仍未完成；Trash preview 的逐平台发布资格、可信本地审批 broker 与完整 preflight/reconciliation 尚未实现。
• Cleaner 签名、更新、撤销、沙箱和外部 query/mutation adapter 尚未达到发布状态。
• P3 plan/simulation authorization、audit/recovery 和 executor 已在 library 层实现；仍没有公共 CLI 合同、可信 HumanApproval broker 或 native adapter。
• 对 sparse、compressed、hard link、clone/reflink、snapshot、dedup、overlay、quota 和共享存储的空间归因不能被概括成“将释放多少空间”。

最重要的当前结论是：SweepX 已有可运行的扫描/TUI 和单对象 Trash preview，但还没有完整计划执行或 Permanent 清理能力。