故障排查
Cleanr 已打开，但没有扫描
这是正常行为。启动只会设置扫描根目录。按 s、运行 /scan，或按 u
执行用量扫描。
命令面板里没有 /review 或 /clean
依赖扫描结果的命令会在扫描完成前隐藏。请先运行 /scan。如果扫描仍在进行，
等待完成，或按 Esc / x 取消。
扫描没有找到候选项
请检查：
- 对应规则包是否在
cleanup.enabled_rule_packs中； - 目标是否被
ignore_dirs或ignore_patterns排除； - 条目是否满足规则的大小、时间、名称或路径条件；
- 条目是否达到本次生效的
[recommendations].preselect_after_days修改时间年龄门槛。cleanr analyze会保留未达到门槛的证据；若其中已有规则命中，可修改设置，或有意地 使用/scan --inactive-days <天数>重新扫描； - 扫描的是包含候选项的目录，而不是把候选目录本身作为根目录。扫描根目录本身 永远不会成为清理候选项。
使用 /rules 查看已加载规则，使用 /plugins 确认自定义 bundle 是否被发现。
/scan --global 提示没有发现清理位置
当前平台没有返回所选全局分类对应的已知用户级系统清理位置。仍然可以显式指定路径：
/scan /home/me/.cargo /home/me/.npm
请使用当前操作系统真实存在的绝对路径。TUI 中输入的路径不会展开 ~ 或
环境变量。
Cleanr 报告配置解析错误
打印默认配置路径：
cleanr config path
如果使用自定义文件，排查时要带上相同的 --config。重点检查未知键、拼错的
枚举值、重复 ID 和无效 TOML。
在不覆盖原文件的情况下生成一份新默认配置用于对比：
cleanr --config /tmp/cleanr-default.toml config init
终端显示异常
-
确认终端支持 Unicode 和彩色显示。
-
Cleanr 默认使用便携的 ANSI 基础色。如果颜色仍变成整片红/绿块， 请重置终端配置，或换一个终端应用验证。
-
如果只是背景明暗不对，再设置显式主题：
cleanr config set ui.theme dark -
放大过小的终端窗口。
-
如果程序被强制中断，在 Shell 中运行
reset恢复终端状态。
已选条目在清理时被跳过
Cleanr 会在执行前重新校验每个目标。如果条目在扫描后变化、变成符号链接、 移出扫描根目录或与受保护路径重叠，就会被跳过。请重新扫描并审阅新状态，不要 强制执行旧计划。
恢复失败
常见原因包括：
- 系统回收站已清空；
- 条目被手动移出回收站；
- 原路径已经存在；
- 回收站元数据发生变化或不可用；
- 当前平台不支持程序化恢复。
Cleanr 不会覆盖当前路径。排查期间请手动检查系统回收站，并保留 Cleanr 状态 目录和清单。
关闭更新检查
Cleanr 最多每 24 小时检查一次新版本。可以关闭这个非阻塞启动检查：
Cleanr 0.16.0 及后续版本使用后台线程检查更新，HTTP 请求超时为 10 秒。首屏不等待网络； 发现新版本后在首页单独提示，不覆盖任务错误。
cleanr --no-update-check
或：
export CLEANR_NO_UPDATE_CHECK=true
全局扫描很慢或看似卡住
可以选择启用配置中的扫描预算，限制保留条目、耗时、估算分配或保留 诊断。启用预算时使用单个遍历 worker；命中预算后返回只读部分证据。耗时上限采用协作 检查：它会在扫描阶段和文件系统操作之间检查，但无法中断已经阻塞在操作系统内核中的 元数据读取或目录读取。若内核调用最终返回，可以取消扫描；如果反复阻塞，应检查对应的 文件系统、挂载点或网络共享。
安装、升级或卸载问题
快速开始提供系统/CPU 资产选择，以及升级、回退和卸载命令。版本没有
变化时，macOS/Linux 使用 command -v cleanr，PowerShell 使用 Get-Command cleanr
检查实际可执行文件。混用安装方式可能让 PATH 中存在多个版本。
清理总量没有变成可用空间
移入系统回收站通常仍占用磁盘。候选大小或已移动字节数不是可用空间测量。回收站条目 与本地记录还在时，Cleanr 才可能恢复；清空回收站是另一个决定，也会移除恢复来源。
获取更多帮助
如果问题可以稳定复现，请在 GitHub 提交 issue，并附上：
- Cleanr 版本（
cleanr --version）； - 操作系统和终端；
- 安装方式；
- 完整命令或按键步骤；
- 去除密钥和个人路径后的完整错误信息。