Back to Details

files-buddy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Files Buddy

Files Buddy

Mac storage command center for safe filesystem organization, duplicate review, cache analysis, cloud offload planning, and cleanup execution. It delegates to free/OSS CLI tools and treats iCloud Drive, Google Drive, developer caches, AI/model caches, containers, VMs, backups, and app-managed libraries as first-class storage surfaces.
Scope: macOS file management, storage audits, cleanup/offload plans, exact and similar duplicate review, progress dashboards, manifest-backed execution, and undo. NOT for shell scripts (shell-scripter), CI/CD (devops-engineer), database work (database-architect), or Linux/Windows cleanup.
Mac存储管理中心，用于安全的文件系统整理、重复文件审核、缓存分析、云卸载规划和清理执行。它基于免费/开源CLI工具构建，将iCloud Drive、Google Drive、开发者缓存、AI/模型缓存、容器、虚拟机（VM）、备份和应用管理的库视为一等存储对象。
适用范围： macOS文件管理、存储审计、清理/卸载规划、精确与相似重复文件审核、进度仪表盘、基于清单的执行与撤销功能。不适用于Shell脚本（shell-scripter）、CI/CD（devops-engineer）、数据库工作（database-architect）或Linux/Windows系统清理。

Canonical Vocabulary

标准术语

Canonical terms: use these terms exactly in plans, reports, manifests, and dashboard labels.
TermDefinition
all-localWhole-Mac audit scope: home folders, cloud roots, 
/Volumes/*
, caches, dev/AI stores, containers, VMs, and report-only app libraries
dry-runTool-native preview or read-only simulation before any mutation
approved planUser-confirmed plan naming exact operation classes, paths, savings, risks, and restore path
manifestJSON operation log under 
~/.files-buddy/manifests/
used for undo and verification
progress snapshotLive JSON at 
~/.files-buddy/runs/{run-id}/progress.json
blast radiusFile count, local bytes, cloud bytes, directories, and operation classes affected
protected pathHard-blocked or escalated-confirmation path from 
references/protected-paths.md
offload candidateFile or directory that can free local bytes while preserving recoverability elsewhere
repercussionConcrete consequence: re-download, rebuild, re-index, app breakage, sync delete, quota impact, or lost snapshot
dependency evidenceGit refs, process refs, app library ownership, package/cache ownership, cloud state, or model/runtime references
exact duplicateSame content hash and distinct inode/link identity
similar-media groupPerceptual image/video/audio candidates; never auto-trash
cloud-safeNo automatic synced deletion; materialize only with approval; verify provider sync state
dashboardStatic report plus optional live-refresh progress view built from the shadcn/ui + Tailwind v4 + Recharts source contract
标准术语： 在规划、报告、清单和仪表盘标签中必须严格使用以下术语。
术语定义
all-local全Mac审计范围：主文件夹、云盘根目录、
/Volumes/*
、缓存、开发/AI存储、容器、虚拟机以及仅报告的应用库
dry-run任何变更操作前的工具原生预览或只读模拟
approved plan用户确认的规划，明确包含操作类别、路径、存储空间节省量、风险和恢复路径
manifest存储在
~/.files-buddy/manifests/
下的JSON操作日志，用于撤销操作和验证
progress snapshot实时JSON文件，路径为
~/.files-buddy/runs/{run-id}/progress.json
blast radius受影响的文件数量、本地字节数、云字节数、目录数和操作类别
protected path来自
references/protected-paths.md
的硬阻止或需确认路径
offload candidate可释放本地存储空间同时保留其他位置可恢复性的文件或目录
repercussion具体后果：重新下载、重建、重新索引、应用崩溃、同步删除、配额影响或快照丢失
dependency evidenceGit引用、进程引用、应用库归属、包/缓存归属、云状态或模型/运行时引用
exact duplicate内容哈希相同但inode/链接标识不同的文件
similar-media group感知相似的图片/视频/音频候选文件；绝不会自动删除
cloud-safe不会自动同步删除；仅在获得批准后才会具体化；验证提供商同步状态
dashboard静态报告加上可选的实时刷新进度视图，基于shadcn/ui + Tailwind v4 + Recharts源协议构建

Dispatch

命令调度

$ARGUMENTS
ModeDestructive?Primary reference
storage-audit all-local
Whole-Mac storage auditNo
macos-storage-map.md
storage-audit <path>
/ 
audit <path>
Scoped storage auditNo
scan-performance.md
cleanup-plan <path-or-all-local>
/ 
clean <path>
Ranked cleanup planNo
dependency-impact.md
offload-plan <path-or-all-local> --to <icloud-or-gdrive-or-rclone-remote>
Local-byte offload planNo
offload-recommendations.md
dedupe <path> --exact
Exact duplicate planNo
duplicate-detection.md
dedupe <path> --similar-media
Similar image/video/audio reviewNo
duplicate-detection.md
`cache-audit [all-localdevaicontainers
organize <path>
Organize plan/executionYes after approval
organization-strategies.md
rename <path> <pattern>
Batch rename plan/executionYes after approval
rename-patterns.md
archive <path>
Archive plan/executionYes after approval
dependency-impact.md
sanitize <path>
Filename cleanup plan/executionYes after approval
tool-integrations.md
find <path> <query>
Read-only searchNo
tool-integrations.md
watch <path> [rules]
Auto-organize watcherYes after approval
organization-strategies.md
progress <run-id-or-progress-json>
Show run progressNo
progress-reporting.md
dashboard <progress-or-report-json>
Render dashboardNo writes report
dashboard-app.md
execute <approved-plan>
Execute previously approved planYes
safety-workflow.md
undo <manifest>
Reverse manifest operationsYes restores
safety-workflow.md
Empty or unrecognizedGallery and mode menuNo—
$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-localdevaicontainers
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
空或无法识别功能列表与模式菜单否—

Auto-Detection Heuristic

自动检测规则

  1. "free space", "storage", "what can I delete", "whole Mac" -> storage-audit or 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 or progress
  7. "sort", "organize", "rename", "archive", "sanitize", "find", "watch", "undo" -> matching mode
  8. Ambiguous mutation request -> produce read-only plan and ask for explicit approval before execution
  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. 模糊的变更请求 → 生成只读规划，并在执行前请求明确批准

Execution Ladder

执行流程

Every storage-saving workflow follows this order:
  1. Read-only inventory — detect volumes, cloud roots, protected paths, symlinks, app-managed stores, tools, and scope.
  2. Dry-run or report — run only non-mutating commands, native dry-runs, or report-only CLI modes.
  3. Dependency impact — explain references, repercussions, regeneration cost, restore path, and confidence for each recommendation.
  4. Ranked plan — group actions into safe trash, exact duplicates, similar media review, archives, offloads, cache prunes, app-managed report-only, and protected skips.
  5. Approval gate — require explicit approval of the specific plan before any move, rename, trash, prune, archive, evict, dedupe, or watcher.
  6. Manifest execution — create manifest, execute in batches, write progress snapshots, verify outputs, and preserve undo.
  7. Final report — local bytes saved, cloud bytes affected, skipped items, failures, manifest, restore commands, and verification evidence.
每个节省存储空间的工作流遵循以下顺序：
  1. 只读清单 — 检测卷、云盘根目录、受保护路径、符号链接、应用管理存储、工具和范围。
  2. 预演或报告 — 仅运行非变更命令、原生预演或仅报告的CLI模式。
  3. 依赖影响分析 — 解释每个建议的引用关系、后果、再生成本、恢复路径和可信度。
  4. 分级规划 — 将操作分为安全删除、精确重复文件、相似媒体审核、归档、卸载、缓存清理、仅报告的应用管理存储和跳过受保护项。
  5. 批准闸门 — 在执行任何移动、重命名、删除、清理、归档、驱逐、去重或监控操作前，需要对具体规划进行明确批准。
  6. 清单执行 — 创建清单，分批执行，写入进度快照，验证输出，并保留撤销功能。
  7. 最终报告 — 本地节省字节数、云字节影响、跳过项、失败项、清单、恢复命令和验证证据。

State Management

状态管理

Persistent run state lives under 
~/.files-buddy/runs/{run-id}/
and includes progress snapshots, checkpoints, reports, and links to manifests. Destructive operations are resumable only from manifest records; read-only scans can resume from checkpoints when path, size, mtime, and inode summaries still match.
持久化运行状态存储在
~/.files-buddy/runs/{run-id}/
下，包括进度快照、检查点、报告和清单链接。破坏性操作仅能从清单记录恢复；只读扫描在路径、大小、修改时间和inode摘要仍匹配时可从检查点恢复。

Progressive Disclosure

渐进式披露

Keep the main response focused on ranked recommendations and approval gates. Load only the single reference needed for the active mode, write detailed scan/progress/dashboard data to files, and summarize large result sets with top-N tables plus report paths instead of dumping raw inventories into chat.
保持主响应聚焦于分级建议和批准闸门。仅加载当前模式所需的单个参考文档，将详细的扫描/进度/仪表盘数据写入文件，对大型结果集使用前N项表格加报告路径进行汇总，而非将原始清单直接输出到对话中。

Structural Constraints

结构约束

  1. macOS-only: refuse Linux/Windows cleanup except to explain scope.
  2. Operation whitelist: move, rename, copy, trash, mkdir, archive, cloud-offload, cache-prune. NEVER use 
    rm
    , 
    chmod
    , 
    chown
    , or force deletion.
  3. Scope pinning: default boundary is the user-referenced path. 
    all-local
    is allowed only for read-only inventory until an approved plan narrows execution.
  4. Protected paths: reject hard-blocked paths; escalate secrets, dot-configs, app libraries, and cloud roots.
  5. Symlink safety: resolve real paths, detect cycles, and never follow links outside scope.
  6. Cloud-safe: never auto-delete synced files; never materialize or evict placeholders without dry-run proof and approval.
  7. App-managed stores: Photos, Music, TV, Mail, Messages, Time Machine snapshots, and VM snapshots are report-only unless the user selects the app-native cleanup path.
  8. Similar media: never auto-trash perceptual matches; create review queues only.
  9. Caches: distinguish disposable, regenerable, expensive-to-regenerate, and app-owned caches before recommending cleanup.
  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. 缓存： 在建议清理前，区分一次性缓存、可再生缓存、再生成本高的缓存和应用归属缓存。

Pre-Flight Checks

预检查

Run before every mode:
  1. Resolve paths, reject hard-blocked paths, and identify escalated-confirmation paths.
  2. Detect cloud roots: 
    ~/Library/Mobile Documents/com~apple~CloudDocs
    , 
    ~/Library/CloudStorage/*
    , and configured 
    rclone
    remotes.
  3. Detect volumes: 
    /Volumes/*
    , local snapshots, APFS case sensitivity, free space, and filesystem type.
  4. Inventory symlinks, 
    .git/
    , 
    .gitignore
    , tracked files, package manifests, lockfiles, and app library markers.
  5. Check tools: 
    fd fclones rmlint czkawka_cli f2 dust erd gomi ouch zstd b3sum detox convmv rclone pueue bat watchexec organize docker tmutil brctl fileproviderctl
    .
  6. For scans above 10k files, load 
    references/scan-performance.md
    and use checkpoints, bounded memory, and per-volume concurrency limits.
  7. For dashboards, load 
    references/progress-reporting.md
    and 
    references/dashboard-app.md
    .
在每种模式运行前执行：
  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. 对于超过10k文件的扫描，加载
    references/scan-performance.md
    并使用检查点、内存限制和每卷并发限制。
  7. 对于仪表盘，加载
    references/progress-reporting.md
    和
    references/dashboard-app.md
    。

Recommendation Contract

建议规范

Each cleanup/offload recommendation must include:
FieldRequirement
Action
trash
, 
offload
, 
archive
, 
dedupe
, 
cache-prune
, 
review
, or 
skip
Local bytesEstimated bytes freed on this Mac
Cloud bytesEstimated cloud quota impact or 
0
ConfidenceHigh/medium/low with evidence
Dependency evidenceRepos, package managers, running processes, app owners, cloud state, or model references
RepercussionsWhat breaks, rebuilds, redownloads, re-syncs, or becomes slower
Restore pathUndo command, app-native restore, cloud restore, or reinstall command
Dry-run proofCommand output or report that proves no mutation occurred
Approval tierLow, Medium, High, or Critical
每个清理/卸载建议必须包含：
字段要求
操作
trash
、
offload
、
archive
、
dedupe
、
cache-prune
、
review
或
skip
本地字节数预计在该Mac上释放的字节数
云字节数预计对云配额的影响或
0
可信度高/中/低并附证据
依赖证据代码库、包管理器、运行进程、应用所有者、云状态或模型引用
后果哪些内容会损坏、需要重建、重新下载、重新同步或变慢
恢复路径撤销命令、应用原生恢复、云恢复或重新安装命令
预演证明证明无变更发生的命令输出或报告
批准等级低、中、高或关键

Dashboard Requirements

仪表盘要求

Dashboard mode renders a static report and can refresh from 
progress.json
during long runs.
  1. Source contract: React + shadcn/ui component patterns + Tailwind CSS v4 tokens + Recharts visualizations. Read 
    references/dashboard-app.md
    .
  2. Packaged fallback: 
    templates/dashboard.html
    must stay self-contained and must not require a CDN or network.
  3. Required panels: run status hero, savings funnel, reclaimable-by-category chart, risk matrix, treemap, duplicate clusters, recommendation cards, cache impact, cloud offload board, progress timeline, manifest explorer.
  4. Accessibility: semantic headings, keyboard-friendly tables, chart text fallbacks, high contrast, reduced-motion compatibility.
  5. Data compatibility: support legacy keys (
    files
    , 
    duplicates
    , 
    directories
    , 
    operations
    , 
    cloud
    , 
    summary
    ) and v1.1 keys from 
    progress-reporting.md
    .
仪表盘模式渲染静态报告，并可在长时间运行期间从
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键。

Scaling Strategy

扩展策略

ScopeStrategy
<100 filesFull preview and direct read-only report
100-1,000 filesFull inventory, grouped recommendations, simple progress
1,000-10,000 filesCheckpoints, sampled preview, top-N memory caps, pueue batches
10,000+ filesPer-volume phases, size-first pruning, partial-hash then full-hash, resumable progress snapshots
Cloud rootsHalf local parallelism, avoid placeholder materialization unless approved, verify sync state
范围策略
<100个文件完整预览和直接只读报告
100-1,000个文件完整清单、分组建议、简单进度
1,000-10,000个文件检查点、抽样预览、前N项内存限制、pueue分批处理
10,000+个文件按卷分阶段、按大小优先修剪、部分哈希后全哈希、可恢复进度快照
云盘根目录本地并行度减半，除非获得批准否则避免具体化占位符，验证同步状态

Reference Files

参考文件

Load ONE reference at a time. Do not preload all references into context.
FileContentRead When
references/macos-storage-map.md
Whole-Mac storage surfaces, dev/AI caches, app-managed stores, backups, scan commands, action class, repercussions
storage-audit all-local
, 
cache-audit
references/dependency-impact.md
Dependency evidence, repercussions, regeneration cost, restore path, confidence, do-not-proceed checks
cleanup-plan
, 
archive
, 
execute
references/offload-recommendations.md
iCloud, Google Drive Stream/Mirror, rclone offload scoring and verification
offload-plan
references/scan-performance.md
Large-scan phases, pruning, NUL-safe paths, checkpoints, concurrency, cloud limitsAny large scan
references/progress-reporting.md
progress.json
schema, phase events, savings model, live refresh contract
progress
, 
dashboard
, long execution
references/dashboard-app.md
shadcn/ui + Tailwind v4 + Recharts dashboard architecture and component contract
dashboard
references/tool-integrations.md
Free/OSS CLI matrix, install commands, dry-run flags, output parsingPre-flight tools
references/cloud-drives.md
macOS cloud roots, iCloud/File Provider commands, Google Drive/rclone gotchasCloud detection and offload
references/organization-strategies.md
organize-tool YAML templates, project detection, collision handlingOrganize/watch
references/protected-paths.md
Hard-blocked and escalated paths, validation algorithm, 
.git/
exclusion		Pre-flight safety
references/duplicate-detection.md
fclones/rmlint/czkawka/rclone/dupeGuru/imagededup policies, keeper rules, media reviewDeduplication
references/rename-patterns.md
f2 patterns, EXIF/ID3/hash variables, CSV batch, conflicts, undoRename
references/safety-workflow.md
Manifest schema, atomic writes, trash hierarchy, TOCTOU, undo, cloud safetyExecution and undo
ScriptWhen to Run
scripts/manifest-manager.py
Create, list, search, validate, append, close, and undo manifests
scripts/dashboard-renderer.py
Inject report/progress JSON into dashboard template and optionally open browser
TemplateWhen to Render
templates/dashboard.html
Self-contained dashboard artifact for report and progress visualization
每次仅加载一个参考文件。不要预加载所有参考文件到上下文。
文件内容加载时机
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
schema、阶段事件、节省模型、实时刷新协议
progress
、
dashboard
、长时间执行
references/dashboard-app.md
shadcn/ui + Tailwind v4 + Recharts仪表盘架构和组件协议
dashboard
references/tool-integrations.md
免费/开源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
清单schema、原子写入、删除层级、TOCTOU、撤销、云安全执行和撤销
脚本运行时机
scripts/manifest-manager.py
创建、列出、搜索、验证、追加、关闭和撤销清单
scripts/dashboard-renderer.py
将报告/进度JSON注入仪表盘模板并可选打开浏览器
模板渲染时机
templates/dashboard.html
用于报告和进度可视化的自包含仪表盘工件

Validation Contract

验证规范

Run from this skill directory before declaring changes complete:
bash
python scripts/check.py
python -m py_compile scripts/*.py
python scripts/dashboard-renderer.py --data <sample.json> --output <tmp.html>
Completion criteria:
  1. scripts/check.py
    exits 0.
  2. Dashboard smoke writes HTML; invalid JSON returns a JSON error.
  3. No portable-CLI violations remain under this skill directory.
在声明变更完成前，从该技能目录运行：
bash
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. 仪表盘可生成HTML；无效JSON返回JSON错误。
  3. 该技能目录下无便携CLI违规。

Critical Rules

关键规则

  1. Never delete, trash, prune, evict, move, archive, rename, or dedupe without explicit approval of a specific dry-run plan.
  2. Never use 
    rm
    or pipe finder output into deletion commands.
  3. Never operate outside the approved scope pin.
  4. Never modify hard-blocked paths.
  5. Never follow symlinks outside scope.
  6. Always show blast radius and repercussions before destructive operations.
  7. Always create a manifest before the first approved operation.
  8. Always record progress snapshots for long-running scans/executions.
  9. Always separate exact duplicates from similar-media groups.
  10. Always treat cloud synced deletion as Critical because it can sync loss to every device.
  11. Always materialize cloud placeholders only after explaining local-space impact and receiving approval.
  12. Always label Photos/Music/TV/Mail/Messages/Time Machine/VM snapshot recommendations as app-native or report-only unless explicitly approved.
  13. Always include restore path and regeneration cost for cache cleanup recommendations.
  14. Always verify BLAKE3 hashes, size, 
    st_mode
    , and 
    st_ino
    for finalized file operations when possible.
  15. Always validate manifests stay under 
    ~/.files-buddy/manifests/
    .
  16. Always preserve 
    .git/
    and warn before touching tracked files.
  17. Always load only the reference needed for the active mode.
  18. Always report missing tools with free/OSS install commands and safe fallbacks.
  19. Always use bounded-memory, checkpointed scans for huge trees.
  20. Always run the validation contract before claiming the skill is complete.
  1. 未经明确批准具体的预演规划，绝不能删除、清理、驱逐、移动、归档、重命名或去重文件。
  2. 绝不能使用
    rm
    或将finder输出管道到删除命令。
  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. 在声称技能完成前，必须运行验证规范。