file-organization

文件整理

此技能可帮助 AI Agent 整理杂乱的目录。给定目标路径后，Agent 会扫描所有文件，使用可配置的规则集对文件进行分类，并将其移入结构清晰的目录树。它支持按文件类型、修改日期、项目关联或优先级整理。高级功能包括通过内容哈希检测重复文件、统一命名规范、预览模拟运行，以及自动归档长期未使用的文件。

工作流

1. 扫描目标目录 递归枚举指定目录中的所有文件。收集每个文件的元数据：名称、扩展名、大小、创建日期、修改日期和内容哈希（仅在检测重复文件时按需计算 SHA-256）。默认跳过隐藏文件和系统文件（例如 .DS_Store、Thumbs.db），但允许用户通过配置将其纳入。

2. 根据规则集对文件分类 应用当前整理策略，为每个文件分配目标文件夹。默认策略使用内置扩展名映射，按文件类型分组（例如，.pdf → documents/、.png → images/、.mp3 → audio/）。其他策略包括：按修改日期分组（2025/01/、2025/02/）、根据路径前缀或文件名标签推断项目名称后分组，或按文件名中包含的优先级标签分组（例如，URGENT-report.pdf → priority-high/）。用户可以提供 YAML 或 JSON 格式的自定义规则文件，以覆盖或扩展任何策略。

3. 检测并处理重复文件 比较所有已扫描文件的内容哈希。发现重复文件时，将最近修改的副本保留在目标位置，并将较旧的副本移至 _duplicates/ 暂存文件夹。向用户汇总重复文件，供其在永久删除前审核。也可以选择将重复文件替换为指向规范副本的符号链接，以节省磁盘空间，同时保留路径引用。

4. 应用命名规范 根据配置的规范统一文件名。选项包括：kebab-case（quarterly-report-2025.pdf）、snake_case（quarterly_report_2025.pdf）或日期前缀（2025-01-15_quarterly-report.pdf）。去除特殊字符、合并多余空白，并在需要时将 Unicode 转写为 ASCII。保留原始扩展名。记录每次重命名，以便撤销操作。

5. 执行移动计划（或模拟运行） 移动任何文件之前，生成完整的移动计划，显示每个文件的源路径和目标路径。模拟运行模式（首次调用时的默认模式）下，显示计划并请求确认。确认后，按需创建目标目录，并以原子方式移动文件。在目标目录根目录下写入清单文件（_organization-log.json），记录执行的所有操作，以便完整撤销。

6. 归档长期未使用的文件 可选择识别在可配置的时间阈值内（默认：12 个月）未访问或修改的文件。将这些文件移至 _archive/ 目录，同时保留整理后的子文件夹结构。如果需要，可将归档文件夹压缩为 .tar.gz 或 .zip。通知用户回收的总空间。

用法

指定一个目录并为 Agent 指定整理策略。如果未指定策略，Agent 默认按文件类型整理。

"Organize my ~/Downloads folder by file type."

"Sort the files in /data/raw-exports by modification date, using YYYY/MM subfolders."

"Organize ~/Projects/acme-app using this config file: .file-org-rules.yaml"

自定义规则文件如下所示：

# .file-org-rules.yaml
strategy: type
naming: kebab-case
date_prefix: true
archive_after_days: 365
type_map:
  documents: [pdf, docx, txt, md, csv]
  images: [jpg, jpeg, png, gif, svg, webp]
  audio: [mp3, wav, flac, aac]
  video: [mp4, mov, avi, mkv]
  archives: [zip, tar, gz, rar, 7z]
  code: [py, js, ts, go, rs, java, c, cpp, h]
  data: [json, xml, yaml, yml, toml, sql]
ignore:
  - node_modules
  - .git
  - __pycache__

示例

示例 1 — 整理杂乱的下载文件夹

整理前：

~/Downloads/
├── IMG_4012.jpg
├── IMG_4012 (1).jpg       ← duplicate
├── Q3 Financial Report.pdf
├── meeting-notes.txt
├── setup_installer.exe
├── song.mp3
├── profile photo.PNG
├── data_export.csv
├── slides_final_v2.pptx
├── backup.zip
└── vacation vid.mp4

用户输入：

"Organize ~/Downloads by file type. Use kebab-case naming. Detect duplicates."

Agent 输出（模拟运行预览）：

Scan complete: 11 files found, 1 duplicate detected.

Duplicate: IMG_4012 (1).jpg is identical to IMG_4012.jpg (SHA-256 match)
  → Moving IMG_4012 (1).jpg to _duplicates/

Move plan:
  IMG_4012.jpg                → images/img-4012.jpg
  profile photo.PNG           → images/profile-photo.png
  Q3 Financial Report.pdf     → documents/q3-financial-report.pdf
  meeting-notes.txt           → documents/meeting-notes.txt
  data_export.csv             → documents/data-export.csv
  slides_final_v2.pptx       → presentations/slides-final-v2.pptx
  song.mp3                    → audio/song.mp3
  vacation vid.mp4            → video/vacation-vid.mp4
  setup_installer.exe         → applications/setup-installer.exe
  backup.zip                  → archives/backup.zip

Confirm? (yes / no / edit plan)

整理后（确认后）：

~/Downloads/
├── _duplicates/
│   └── img-4012-1.jpg
├── _organization-log.json
├── applications/
│   └── setup-installer.exe
├── archives/
│   └── backup.zip
├── audio/
│   └── song.mp3
├── documents/
│   ├── data-export.csv
│   ├── meeting-notes.txt
│   └── q3-financial-report.pdf
├── images/
│   ├── img-4012.jpg
│   └── profile-photo.png
├── presentations/
│   └── slides-final-v2.pptx
└── video/
    └── vacation-vid.mp4

示例 2 — 按标准结构整理项目仓库

用户输入：

"Reorganize ~/code/my-api into a standard Go project layout. Move source files, tests, configs, and docs into conventional locations."

Agent 输出（模拟运行预览）：

Detected project type: Go (found go.mod)

Proposed structure:
  cmd/my-api/main.go         ← entry point (moved from ./main.go)
  internal/handlers/          ← HTTP handlers (moved from ./handlers/)
  internal/models/            ← data models (moved from ./models/)
  internal/service/           ← business logic (moved from ./service/)
  pkg/                        ← exported library code (empty — populate later)
  configs/config.yaml         ← moved from ./config.yaml
  docs/api-spec.md            ← moved from ./API.md
  scripts/migrate.sh          ← moved from ./migrate.sh
  test/integration/           ← moved from ./integration_tests/
  go.mod                      ← unchanged
  go.sum                      ← unchanged
  README.md                   ← unchanged

7 files moved, 3 directories created, 2 files unchanged.
Import paths in Go files updated automatically.

Confirm? (yes / no / edit plan)

最佳实践

• 始终先进行试运行。 在向用户展示完整计划之前，绝不要移动文件。意外重组正在使用的项目目录可能会导致构建和工具无法正常工作。
• 保留清单日志。 将每项操作（移动、重命名、删除）写入目标目录根目录下的 JSON 日志文件。这样可以完全撤销操作。
• 遵循版本控制规则。 如果目标目录位于 Git 仓库中，请使用 git mv，而非直接移动文件，以保留历史记录。如果存在未提交的更改，请提醒用户。
• 处理文件名冲突。 如果两个不同文件将映射到同一目标路径，请在文件名后添加数字后缀（例如，report.pdf 和 report-1.pdf），而不是直接覆盖。
• 默认跳过已知依赖目录。 默认排除 node_modules/、.git/、__pycache__/、vendor/ 及类似的工具管理目录。重组这些目录会导致包管理器无法正常工作。
• 移动后验证完整性。 执行完成后，将每个已移动文件的 SHA-256 哈希与扫描期间记录的原始哈希进行比较，以确认数据未损坏。

边缘情况

• 留下空目录。 将文件移出文件夹后，检查源文件夹是否已变空。可询问用户是否要删除空目录，以保持目录树整洁。
• 符号链接和硬链接。 扫描时不要跟随符号链接——将其记录为链接，并询问用户如何处理（移动链接、解析到目标，或跳过）。
• 没有扩展名的文件。 默认将无扩展名文件归类到 other/。如果文件包含 shebang 行（例如，#!/usr/bin/env python3），则根据解释器推断文件类型。
• 非常大的目录（>10,000 个文件）。 分批处理文件，并提供进度指示。避免一次性将完整文件列表加载到内存中。
• 权限错误。 如果因文件系统权限而无法读取或移动某个文件，请记录该文件、跳过它，并继续处理其余文件。最后汇总并列出跳过的文件。
• 网络驱动器或外部驱动器。 提醒用户，在网络共享或外部驱动器上重组文件可能会慢很多，而且操作中断可能导致文件状态不一致。建议先在本地副本上操作。