本地文件整理虾

本地文件整理虾 — 自动分类、重命名并归档本地文件。 当以下情况时使用此 Skill： (1) 需要自动整理本地目录（下载文件夹、桌面、项目归档等） (2) 需要按文件类型分类（文档/图片/视频/音频/压缩包/代码） (3) 需要检测并清理重复文件 (4) 需要批量重命名文件，统一命名格式 (5) 用户提到"整理...

Security Scan

脚本总体与“本地文件整理”描述相符且未请求任何凭证或网络访问，但文档、说明与实际脚本存在多处不一致（提到外部工具/删除选项/相似度检测等），建议在运行前审阅并先使用 --dry-run 以及备份重要数据。

Purpose & Capability

名称与描述（自动分类、重命名、查重）与脚本功能基本一致：脚本扫描本地目录、按扩展名分类、移动文件、生成报告并可用 MD5 查重。注意：references 文档提到 exiftool、pHash/pillow、以及删除到回收站/直接删除的选项，但脚本并未实现 pHash、exiftool 调用或 --trash/--delete 参数，这表明文档和实现不完全匹配。

Instruction Scope

SKILL.md 指令明确要求在本地以 python3 运行 core 脚本，脚本仅对本地文件系统读/写（移动文件、写入报告 JSON），未包含任何网络调用或环境变量访问。唯一的范围问题是文档里建议使用 `trash` 或图片相似度检测，但脚本并不提供这些功能——说明书暗示的额外行为不会被脚本执行。

Install Mechanism

无安装规格（instruction-only + 内含脚本），不在安装阶段从外部 URL 下载或安装任意二进制，风险较低。需要有 Python3 可用（脚本通过 python3 运行）。

Credentials

不请求任何环境变量、凭证或配置路径。脚本也不读取环境变量或网络凭证，访问仅限于用户指定的源/目标目录，所需权限与功能相称。

Persistence & Privilege

不要求常驻(always)或修改其他技能/系统全局配置。运行时会在目标目录写入报告 JSON 并移动文件（当非 dry-run 时），这些都是该功能的预期行为。

What to consider before installing

该 Skill 的代码与描述大体一致：它在本地扫描并移动/重命名文件、可做 MD5 查重并在目标目录保存报告。待注意的点： - 文档提到的 exiftool、pHash（图片相似度检测）、以及 `--trash`/`--delete` 行为在实际脚本中并未实现；这是文档与实现的不一致，而非隐含的远程行为。 - 在非 dry-run 模式下脚本会移动文件（shutil.move），请先用 `--dry-run` 预览结果并检查生成的 organize-report-*.json 报告；在对重要数据操作前做好备份。 - 对大文件计算 MD5 可能耗时；文档提到的 `--quick` 快速模式也未在脚本中实现（脚本仅有 --find-dups 切换），注意性能影响。 - 虽然脚本默认不删除文件，但会将文件从源位置移动到目标分类文件夹——确认目标路径正确以免混乱。 建议：在可信的测试目录（非生产/重要目录）运行一次完整 dry-run 并人工核对报告与移动计划；如果你需要 exif 或相似度检测、回收站删除等功能，应在本机安装并审查/扩展脚本以确保行为符合预期。

核心脚本：scripts/organize_files.py

快速使用

# 预览整理效果（不实际移动）
python3 scripts/organize_files.py ~/Downloads --dry-run

# 执行整理（移动到同目录下的分类子文件夹）
python3 scripts/organize_files.py ~/Downloads

# 整理到指定目标目录
python3 scripts/organize_files.py ~/Downloads ~/Organized

# 整理 + 检测重复文件
python3 scripts/organize_files.py ~/Downloads --find-dups

# 使用自定义规则
python3 scripts/organize_files.py ~/Downloads --rules my-rules.json

工作流程

1. 理解需求 — 确认源目录、目标目录、整理模式（移动/复制/重命名）
2. 预览 — 先用 --dry-run 展示整理计划，让用户确认
3. 执行 — 用户确认后执行实际整理
4. 汇报 — 展示整理统计（移动了多少文件、发现多少重复）

分类规则

默认按扩展名分类到：Documents / Pictures / Videos / Audio / Archives / Code / Others

自定义规则 JSON 格式：

{
  "设计稿": ["psd", "ai", "sketch", "fig"],
  "文档": ["pdf", "docx", "md"]
}

详细规则参考：references/classification-rules.md

重复文件检测

--find-dups 标志启用 MD5 哈希比对，输出重复文件列表。 用户确认后可手动删除，或使用 trash 命令移到回收站（推荐）。

保留策略详见：references/duplicate-detection.md

命名规范

批量重命名时参考：references/naming-conventions.md

支持变量：{date} {name} {ext} {index} {parent}

安全原则

• 默认不删除文件，只移动/复制
• 删除操作前必须用户二次确认
• 优先使用 trash 而非 rm（可恢复）
• 文件名冲突时自动添加序号（file_1.pdf）

已知限制

• 无法处理正在被占用的文件
• 大文件（>10GB）哈希计算较慢，可先用 --quick 模式
• 不支持网络驱动器（NAS/SMB）的实时监控