file-organizer

文件整理器

一款由 LLM 驱动的文件整理器，可读取文件内容、提出合理的文件夹结构并重命名文件，然后分批执行移动操作——在进行任何文件系统更改之前，必须先获得用户确认。

概述

灵感来自 LlamaFS，但专为 Hermes 设计： 脚本负责文件系统 I/O（扫描、读取片段、执行移动）。默认情况下，由 Agent 自带的 LLM 进行推理。可选的 propose 子命令可调用成本更低的外部 LLM（deepseek、openrouter、ollama），适用于注重成本的大型目录整理。仅使用标准库进行 HTTP 通信（urllib），无需 requests/openai SDK。

适用场景

• 用户说“整理我的 Downloads” /“整理我的 Desktop” /“清理这个文件夹”
• 用户的目录杂乱，希望将文件归入不同类别
• 用户希望根据文件内容重命名文件（而不仅仅是移动文件）
• 用户希望整理本地磁盘、网络挂载或远程文件系统中的文件

不适用于：

• 批量删除文件（此技能只移动和重命名文件，绝不删除）
• 去重（请使用专用的去重工具）
• 搜索文件内容（请改用 search_files）

工作流

步骤 1 — 扫描

运行扫描脚本，获取文件元数据和内容片段：

python3 scripts/organize.py scan --path <directory> [--depth N] [--max-snippet-chars 500]

输出为 JSON 数组。每个文件条目包含：

• path：完整文件路径
• relative_path：相对于已扫描目录的路径
• name：当前文件名
• size：字节数
• mtime：ISO 时间戳
• type：text、image、audio、pdf、office、archive、other
• mime：检测到的 MIME 类型
• snippet：内容的前 N 个字符（text/pdf）或元数据（image/audio）

标志：--depth N（最大目录深度）、--max-snippet-chars N（每个文件的片段长度上限，默认为 500）、--include-hidden（包含默认跳过的点文件）。

步骤 2 — 提出整理方案（Agent LLM — 默认）

根据扫描结果，分析以下内容：

• 根据文件内容和类型确定自然分类
• 设计清晰的文件夹层级（不要太深，最多 2-3 层）
• 使用能体现文件内容的描述性文件名（而非将 IMG_3847.jpg 改为 Hawaii-Beach-Sunset.jpg）
• 在适当时按时间分组（例如 2024-Taxes/、2023-Receipts/）

构建一个计划 JSON：

{
  "source_dir": "<scanned dir>",
  "moves": [
    {"source": "<full path>", "destination": "<full path>"}
  ],
  "folders_to_create": ["<full path>", ...]
}

节省成本的选项： 展示计划时（步骤 3），告知用户：

"本次使用了 Agent 自带的模型。对于较大的目录，我可以通过成本更低的 LLM 进行推理，以节省费用。可选方案："

提供商	模型	费用	说明
deepseek	deepseek-chat	输入约 $0.14/M，输出约 $0.28/M	最便宜的云端方案
openrouter	deepseek/deepseek-chat	按用量付费	多模型路由
ollama	llama3.2:3b	免费（本地 CPU）	速度较慢，但零成本

只需说“使用 deepseek”或“使用 ollama”，我就会通过成本更低的模型重新运行。

仅当扫描结果包含 20 个或更多文件时才提供此选项（对于很小的目录不值得）。

使用成本更低的模型（选择启用）： 如果用户要求使用成本更低的模型，或目录非常大（100 个或更多文件），请改用 propose 子命令：

python3 scripts/organize.py propose --scan /tmp/scan.json --source-dir <dir> \
  --provider deepseek [--model <model-id>]

提供商优先级：--provider 标志 > DEEPSEEK_API_KEY 环境变量 > OPENAI_API_KEY 环境变量

OPENROUTER_API_KEY 环境变量 > OLLAMA_HOST 环境变量 > 报错

如果 propose 失败（网络、身份验证或解析错误），则改为手动进行 Agent 推理。

步骤 3 — 向用户展示计划（强制确认关卡）

此步骤不可省略。 将计划整理成格式化表格展示：

#	当前名称	→	新位置	类型	片段预览

请用户：

• 按当前方案确认
• 调整具体的移动操作（重命名、重新分类、跳过）
• 完全取消

未经用户明确确认，绝不要继续执行。

第 4 步 — 分批执行

用户确认后，将计划写入临时文件并执行：

python3 scripts/organize.py execute --plan /tmp/plan.json --chunk-size 10

脚本会：

• 先创建目标文件夹
• 每批移动 10 个文件（可配置）
• 每批完成后打印进度：[chunk 2/5] moved 10, failed 0
• 跳过冲突（目标文件已存在）——绝不覆盖
• 记录每个文件的错误，但不会中止整个批次

第 5 步 — 汇报结果

向用户展示最终摘要：

• 成功移动的文件
• 跳过的文件（冲突）
• 失败的文件（错误）
• 建议后续操作（例如：“要我再整理另一个目录吗？”）

跨文件系统支持

整理工具适用于主机可访问的任何路径：

目标	路径格式	备注
本地磁盘	任意本地路径	直接访问文件系统
网络挂载	NFS、SMB/CIFS、SSHFS 挂载	网络延迟较高时使用较小的批次大小
远程文件系统	Python shutil.move 可处理的任意路径	SSHFS、FUSE 等

关键防护措施

1. 绝不删除 — 只移动和重命名。如果用户需要删除文件，应将其作为单独任务处理，并进行单独的确认流程。
2. 绝不覆盖 — 如果目标文件已存在，则跳过并记录。
3. 始终先确认 — 执行前向用户展示计划。不得静默移动。
4. 分批执行 — 每批处理 10 个文件，以便妥善处理失败。
5. 默认使用 Agent 的 LLM，可选择使用低成本 LLM — scan 和 execute 仅执行文件系统 I/O。默认由 Agent 自己的 LLM 进行推理。对于大型目录，可选择使用 propose 子命令调用成本较低的外部模型。

常见问题

1. 目录过大 — 扫描 10,000 个以上的文件会产生大量输出。先使用 --depth 1 查看概况，再深入子目录。也可以按文件类型分别扫描。

2. 没有文本片段的二进制文件 — 图片、音频和办公文档仅会返回元数据。LLM 必须根据文件名、大小和修改时间推断分类。

3. 路径包含空格 — 始终在计划 JSON 中为路径加引号。脚本通过 Python pathlib 正确处理这类路径。

4. 网络文件系统延迟 — 由于网络往返通信，在 SSHFS/NFS/SMB 挂载上整理文件会比较慢。对于远程目标，请使用较小的批次大小（5）。

5. 权限错误 — 某些文件可能无法读取。扫描脚本会妥善处理这类情况（返回包含 snippet: null 的元数据）。

验证清单

• 扫描已完成并返回 JSON 输出
• 计划包含 source_dir、moves 和 folders_to_create
• 计划以表格形式展示给用户，并清晰列出调整前 → 调整后的映射
• 用户已明确确认计划
• 计划已写入临时 JSON 文件
• 执行已完成，并输出分批进度
• 已汇报最终摘要（移动／失败／跳过的数量）
• 没有文件被删除或覆盖

一步完成的操作示例

整理 Downloads 文件夹

# 1. Scan
python3 scripts/organize.py scan --path ~/Downloads --depth 2 > /tmp/scan.json

# 2. Agent reasons over scan JSON, builds plan (default — uses agent's own LLM)
#    OR for large directories, use cheap LLM:
#    python3 scripts/organize.py propose --scan /tmp/scan.json --source-dir ~/Downloads --provider deepseek > /tmp/plan.json

# 3. Agent presents plan to user (with cost-saving offer if 20+ files)

# 4. After confirmation:
python3 scripts/organize.py execute --plan /tmp/plan.json --chunk-size 10

整理网络挂载的目录

# 1. Scan
python3 scripts/organize.py scan --path /mnt/remote/Desktop --depth 2 > /tmp/scan.json

# 2. Agent reasons over scan JSON, builds plan (default)
#    OR: python3 scripts/organize.py propose --scan /tmp/scan.json --source-dir /mnt/remote/Desktop --provider deepseek > /tmp/plan.json

# 3. Agent presents plan to user

# 4. After confirmation (smaller chunks for network latency):
python3 scripts/organize.py execute --plan /tmp/plan.json --chunk-size 5

试运行（仅预览）

python3 scripts/organize.py execute --plan /tmp/plan.json --dry-run

使用低成本 LLM（大型目录可选）

# Scan → Propose via deepseek → Execute
python3 scripts/organize.py scan --path ~/Downloads > /tmp/scan.json
python3 scripts/organize.py propose --scan /tmp/scan.json --source-dir ~/Downloads --provider deepseek > /tmp/plan.json
# Agent reviews plan, presents to user, then:
python3 scripts/organize.py execute --plan /tmp/plan.json --chunk-size 10

运行自检

python3 scripts/organize.py --self-test

脚本参考

命令	用途
scan --path <dir> [--depth N] [--max-snippet-chars N] [--include-hidden]	扫描目录，输出包含文件元数据和文本片段的 JSON
propose --scan <json> --source-dir <dir> [--provider <p>] [--model <m>]	可选：调用成本较低的外部 LLM 生成计划 JSON
execute --plan <json> [--chunk-size N] [--dry-run]	分批执行移动计划，并逐批打印进度
--self-test	运行内置测试套件（19 项测试，在临时目录中独立运行）

可选 Python 依赖（缺失时会自动降级处理）：

• Pillow — 图片尺寸和 EXIF 日期
• mutagen — 音频时长和 ID3 标签
• PyMuPDF (fitz) — 提取 PDF 首页文本