files-buddy

Files Buddy

用于安全整理文件系统、审查重复项、分析缓存、规划云端卸载和执行清理的 Mac 存储管理中心。它委托免费的开源 CLI 工具处理任务，并将 iCloud Drive、Google Drive、开发者缓存、AI/模型缓存、容器、VM、备份和应用管理的资料库视为一等存储区域。

**范围：**macOS 文件管理、存储审计、清理/卸载计划、精确及相似重复项审查、进度仪表板、基于清单的执行和撤销。不适用于 shell 脚本（shell-scripter）、CI/CD（devops-engineer）、数据库工作（database-architect）或 Linux/Windows 清理。

规范术语

**规范术语：**在计划、报告、清单和仪表板标签中准确使用这些术语。

术语	定义
all-local	整台 Mac 的审计范围：主文件夹、云端根目录、/Volumes/*、缓存、开发/AI 存储、容器、VM，以及仅报告、不做处理的应用资料库
dry-run	在进行任何更改前，由工具原生提供的预览或只读模拟
approved plan	经用户确认的计划，列明确切的操作类别、路径、节省空间、风险和恢复路径
manifest	~/.files-buddy/manifests/ 下用于撤销和验证的 JSON 操作日志
progress snapshot	~/.files-buddy/runs/{run-id}/progress.json 下的实时 JSON
blast radius	受影响的文件数量、本地字节数、云端字节数、目录和操作类别
protected path	references/protected-paths.md 中列出的硬性禁止路径或需要升级确认的路径
offload candidate	可释放本地空间，同时在其他位置保留可恢复性的文件或目录
repercussion	具体后果：重新下载、重新构建、重新索引、应用故障、同步删除、配额影响或快照丢失
dependency evidence	Git refs、进程 refs、应用资料库所有权、包/缓存所有权、云端状态或模型/运行时引用
exact duplicate	内容哈希相同且 inode/链接身份不同的文件
similar-media group	感知层面的图像/视频/音频候选项；绝不自动移至废纸篓
cloud-safe	不自动删除同步内容；仅在获得批准后才将内容下载到本地；验证服务提供商的同步状态
dashboard	静态报告，以及基于 shadcn/ui + Tailwind v4 + Recharts 源契约构建的可选实时刷新进度视图

分派

$ARGUMENTS	模式	是否具有破坏性？	主要参考资料
storage-audit all-local	整台 Mac 存储审计	否	macos-storage-map.md
storage-audit <path> / audit <path>	指定范围的存储审计	否	scan-performance.md
cleanup-plan <path-or-all-local> / clean <path>	排序后的清理计划	否	dependency-impact.md
offload-plan <path-or-all-local> --to <icloud-or-gdrive-or-rclone-remote>	本地字节卸载计划	否	offload-recommendations.md
dedupe <path> --exact	精确重复项计划	否	duplicate-detection.md
dedupe <path> --similar-media	相似图片／视频／音频审查	否	duplicate-detection.md
`cache-audit [all-local	dev	ai	containers
organize <path>	整理计划／执行	经批准后是	organization-strategies.md
rename <path> <pattern>	批量重命名计划／执行	经批准后是	rename-patterns.md
archive <path>	归档计划／执行	经批准后是	dependency-impact.md
sanitize <path>	文件名清理计划／执行	经批准后是	tool-integrations.md
find <path> <query>	只读搜索	否	tool-integrations.md
watch <path> [rules]	自动整理监视器	经批准后是	organization-strategies.md
progress <run-id-or-progress-json>	显示运行进度	否	progress-reporting.md
dashboard <progress-or-report-json>	呈现仪表板	不写入报告	dashboard-app.md
execute <approved-plan>	执行先前已批准的计划	是	safety-workflow.md
undo <manifest>	撤销清单中的操作	是，进行还原	safety-workflow.md
留空或无法识别	功能集与模式菜单	否	—

自动检测启发式规则

1. “free space”“storage”“what can I delete”“whole Mac” -> storage-audit 或 cleanup-plan
2. “offload”“iCloud”“Google Drive”“cloud only”“stream” -> offload-plan
3. “duplicates”“dedupe”“same files” -> dedupe --exact
4. “similar photos”“similar videos”“same music” -> dedupe --similar-media
5. “cache”“Xcode”“Docker”“node_modules”“Hugging Face”“Ollama” -> cache-audit
6. “dashboard”“visualize”“progress”“report” -> dashboard 或 progress
7. “sort”“organize”“rename”“archive”“sanitize”“find”“watch”“undo” -> 对应模式
8. 含糊的更改请求 -> 生成只读计划，并在执行前要求明确批准

执行步骤

所有节省存储空间的工作流都按以下顺序进行：

1. 只读清点 — 检测卷、云端根目录、受保护路径、符号链接、应用管理的存储、工具和范围。
2. 试运行或报告 — 仅运行不会更改内容的命令、原生命令的试运行模式或仅生成报告的 CLI 模式。
3. 依赖影响 — 说明每项建议涉及的引用、后续影响、重新生成成本、还原路径和可信度。
4. 排序后的计划 — 将操作归类为安全移入废纸篓、精确重复项、相似媒体审查、归档、卸载、清理缓存、仅报告的应用管理内容，以及跳过受保护内容。
5. 批准关卡 — 在移动、重命名、移入废纸篓、清理、归档、逐出、去重或启用监视器之前，必须获得对具体计划的明确批准。
6. 清单执行 — 创建清单，分批执行，写入进度快照，验证输出，并保留撤销能力。
7. 最终报告 — 报告节省的本地字节数、受影响的云端字节数、跳过的项目、失败项、清单、还原命令和验证证据。

状态管理

持久运行状态存储在 ~/.files-buddy/runs/{run-id}/ 下，其中包括进度快照、检查点、报告和指向清单的链接。只有依据清单记录才能恢复破坏性操作；如果路径、大小、修改时间和 inode 摘要仍然匹配，只读扫描可以从检查点恢复。

渐进式披露

让主回复聚焦于按优先级排序的建议和审批关卡。仅加载当前模式所需的那一份参考资料，将详细的扫描、进度和仪表板数据写入文件，并使用包含前 N 项的表格和报告路径概述大型结果集，而不是在聊天中倾倒原始清单。

结构约束

1. 仅限 macOS： 拒绝清理 Linux/Windows 系统，除非只是说明适用范围。
2. 操作白名单： 移动、重命名、复制、移至废纸篓、创建目录、归档、卸载到云端、清理缓存。绝不使用 rm、chmod、chown 或强制删除。
3. 范围限定： 默认边界为用户指定的路径。仅在只读清单中允许使用 all-local，直到获批计划缩小执行范围。
4. 受保护路径： 拒绝硬性禁止的路径；对机密信息、点配置文件、应用程序库和云端根目录升级确认级别。
5. 符号链接安全： 解析真实路径、检测循环，绝不跟随链接越出范围。
6. 云端安全： 绝不自动删除已同步的文件；未经演练运行证明和批准，绝不将占位文件实体化或驱逐。
7. 应用管理的存储： Photos、Music、TV、Mail、Messages、Time Machine 快照和 VM 快照仅可报告，除非用户选择应用原生清理路径。
8. 相似媒体： 绝不自动将感知匹配项移至废纸篓；仅创建审核队列。
9. 缓存： 提出清理建议前，区分可丢弃、可再生、重新生成成本高以及应用所有的缓存。

执行前检查

每种模式运行前都要执行：

1. 解析路径、拒绝硬性禁止的路径，并识别需要升级确认的路径。
2. 检测云端根目录：~/Library/Mobile Documents/com~apple~CloudDocs、~/Library/CloudStorage/* 和已配置的 rclone 远程端。
3. 检测卷：/Volumes/*、本地快照、APFS 大小写敏感性、可用空间和文件系统类型。
4. 清点符号链接、.git/、.gitignore、受版本控制的文件、软件包清单、锁文件和应用库标记。
5. 检查工具：fd fclones rmlint czkawka_cli f2 dust erd gomi ouch zstd b3sum detox convmv rclone pueue bat watchexec organize docker tmutil brctl fileproviderctl。
6. 对超过 1 万个文件的扫描，加载 references/scan-performance.md，并使用检查点、受限内存和按卷设置的并发限制。
7. 对仪表板，加载 references/progress-reporting.md 和 references/dashboard-app.md。

建议规范

每项清理/卸载建议都必须包含：

字段	要求
操作	trash、offload、archive、dedupe、cache-prune、review 或 skip
本地字节数	预计可在此 Mac 上释放的字节数
云端字节数	预计对云端配额的影响，或 0
置信度	高/中/低，并附证据
依赖证据	代码仓库、软件包管理器、运行中的进程、应用所有者、云端状态或模型引用
影响	哪些内容会损坏、重建、重新下载、重新同步或变慢
恢复路径	撤销命令、应用原生恢复、云端恢复或重新安装命令
演练运行证明	证明未发生任何更改的命令输出或报告
审批级别	低、中、高或严重

仪表板要求

仪表板模式会呈现静态报告，并可在长时间运行期间从 progress.json 刷新。

1. 源代码约定：React + shadcn/ui 组件模式 + Tailwind CSS v4 令牌 + Recharts 可视化。请阅读 references/dashboard-app.md。
2. 打包的备用方案：templates/dashboard.html 必须保持自包含，不得依赖 CDN 或网络。
3. 必需面板：运行状态主视觉、节省漏斗、按类别划分的可回收空间图表、风险矩阵、树状图、重复项集群、建议卡片、缓存影响、云端卸载面板、进度时间线、清单浏览器。
4. 无障碍性：语义化标题、支持键盘操作的表格、图表文本备用内容、高对比度、兼容减少动态效果设置。
5. 数据兼容性：支持旧版键（files、duplicates、directories、operations、cloud、summary）以及 progress-reporting.md 中的 v1.1 键。

扩展策略

范围	策略
<100 个文件	完整预览并直接读取报告
100-1,000 个文件	完整清单、分组建议、简单进度
1,000-10,000 个文件	检查点、抽样预览、top-N 内存上限、pueue 批次
10,000+ 个文件	按卷分阶段、优先按大小修剪、先部分哈希再完整哈希、可恢复的进度快照
云端根目录	将本地并行度减半，除非获准，否则避免实体化占位文件，并验证同步状态

参考文件

每次只加载 ONE 个参考文件。不要将所有参考文件预先加载到上下文中。

文件	内容	阅读时机
references/macos-storage-map.md	整个 Mac 的存储位置、开发/AI 缓存、应用管理的存储、备份、扫描命令、操作类别、影响	storage-audit all-local、cache-audit
references/dependency-impact.md	依赖证据、影响、重新生成成本、恢复路径、置信度、禁止继续检查项	cleanup-plan、archive、execute
references/offload-recommendations.md	iCloud、Google Drive Stream/Mirror、rclone 卸载评分与验证	offload-plan
references/scan-performance.md	大规模扫描阶段、修剪、NUL 安全路径、检查点、并发、云端限制	任何大规模扫描
references/progress-reporting.md	progress.json 架构、阶段事件、节省模型、实时刷新约定	progress、dashboard、长时间执行
references/dashboard-app.md	shadcn/ui + Tailwind v4 + Recharts 仪表板架构和组件约定	dashboard
references/tool-integrations.md	免费/OSS CLI 矩阵、安装命令、试运行标记、输出解析	工具预检
references/cloud-drives.md	macOS 云端根目录、iCloud/File Provider 命令、Google Drive/rclone 注意事项	云端检测和卸载
references/organization-strategies.md	organize-tool YAML 模板、项目检测、冲突处理	整理/监控
references/protected-paths.md	硬性阻止和升级处理的路径、验证算法、.git/ 排除规则	安全预检
references/duplicate-detection.md	fclones/rmlint/czkawka/rclone/dupeGuru/imagededup 策略、保留规则、媒体审查	去重
references/rename-patterns.md	f2 模式、EXIF/ID3/哈希变量、CSV 批处理、冲突、撤销	重命名
references/safety-workflow.md	清单架构、原子写入、废纸篓层级、TOCTOU、撤销、云端安全	执行和撤销

脚本	运行时机
scripts/manifest-manager.py	创建、列出、搜索、验证、追加、关闭和撤销清单
scripts/dashboard-renderer.py	将报告/进度 JSON 注入仪表板模板，并可选择打开浏览器

模板	渲染时机
templates/dashboard.html	用于报告和进度可视化的自包含仪表板产物

验证契约

在宣布更改完成之前，请从此技能目录运行：

python scripts/check.py
python -m py_compile scripts/*.py
python scripts/dashboard-renderer.py --data <sample.json> --output <tmp.html>

完成标准：

1. scripts/check.py 以退出码 0 结束。
2. Dashboard 冒烟测试会写入 HTML；无效 JSON 会返回 JSON 错误。
3. 此技能目录下不再存在可移植 CLI 违规项。

关键规则

1. 未获得对特定试运行计划的明确批准，绝不删除、丢弃、修剪、逐出、移动、归档、重命名或去重。
2. 绝不使用 rm，也绝不将查找器的输出通过管道传递给删除命令。
3. 绝不在已批准的范围标记之外操作。
4. 绝不修改硬性阻止访问的路径。
5. 绝不跟随超出范围的符号链接。
6. 执行破坏性操作前，始终说明影响范围和后果。
7. 执行首个获批操作前，始终创建清单。
8. 对长时间运行的扫描／执行，始终记录进度快照。
9. 始终将完全重复项与相似媒体组分开处理。
10. 始终将云同步删除视为严重操作，因为它可能将数据丢失同步到所有设备。
11. 只有在说明对本地空间的影响并获得批准后，才始终物化云占位文件。
12. 除非明确获批，否则始终将 Photos／Music／TV／Mail／Messages／Time Machine／VM 快照建议标记为应用原生操作或仅供报告。
13. 对缓存清理建议，始终说明恢复路径和重新生成成本。
14. 在可行时，始终验证最终文件操作的 BLAKE3 哈希、大小、st_mode 和 st_ino。
15. 始终验证清单位于 ~/.files-buddy/manifests/ 下。
16. 始终保留 .git/，并在触及受版本控制的文件前发出警告。
17. 始终只加载当前模式所需的参考资料。
18. 始终报告缺失的工具，并提供免费的开源安装命令和安全替代方案。
19. 对大型目录树，始终使用有界内存、支持检查点的扫描方式。
20. 始终在宣称技能已完成前运行验证契约。