smart-folder-organizer

Smart Folder Organizer 是一个用于整理杂乱目录的技能，提供结构化的工作流程，在整理文件的同时确保数据安全。

用途

该技能用于自动整理混乱的文件夹：对文件进行分类、识别重复文件，并根据发票、收据等 PDF 文档的内容对其进行重命名。

安全第一：绝不删除任何文件。将打算删除的文件移动到 to_remove/ 下的特定子文件夹（例如 to_remove/duplicates/ 或 to_remove/empty_folders/）。
严格范围：仅在当前目录及其子目录内操作。绝不移动或访问父目录（..）中的文件。
保留原则：如果文件类别不明确，将其移动到 Needs_Review/ 文件夹，而不是错误猜测。
大文件：对于任何大于 20MB 的文件，跳过深度内容分析（例如读取 PDF 文本）以防止内存问题。将这些未分析的大文件移动到专用的 Needs_Review/LargeFiles/ 目录。
文件夹处理：递归处理当前目录及其子目录中的所有文件。移动文件时，将其放入目标目录根级别的分类文件夹中（不要在每个子文件夹内复制分类结构）。发现或遗留的任何空子目录必须移动到 to_remove/empty_folders/。

在处理单个文件之前，运行 scripts/detect_smart_folders.py <target_dir> 来识别已经组织良好的子目录（例如 git 仓库、软件项目、macOS 应用包）。

操作：将每个检测到的文件夹整体移动到 Others/ —— 不要进入或重新组织其内容。
逻辑：该脚本检查项目标记（.git/、package.json、Cargo.toml、Makefile 等）和应用包（.app），返回带有原因的 JSON 匹配列表。
跳过：所有后续步骤应忽略 Others/ 目录。

运行 find_duplicates.py 脚本以识别相同的文件。

按扩展名和常见模式组织文件：

对于 PDF 文件，读取前几页以确定文档类型并提取元数据以进行重命名。

关键：不要生成动态 Python 脚本来读取 PDF。而是执行本技能提供的 scripts/extract_pdf_metadata.py 脚本，以确定性地提取文本并分析文档。该脚本使用 pypdf，采用采样策略（前 3 页 + 最后一页）进行快速高效的分类。
重要：使用通用语义推理进行文档分类。现代 AI 模型可以理解数十种语言（英语、中文、西班牙语等）；优先考虑文档的意图（例如“请求付款”），而不是特定的英语关键词如“Invoice”。参考 references/classification.md 获取语义指南。
多语言命名：对于非英语文档，以其原始文字提取命名细节（如 [Vendor] 或 [Provider]）（例如中文字符）。标准日期格式 yyyy-mm-dd 保持不变。
发票：重命名为 yyyy-mm-dd-[Vendor]-[Inv#-][Amount].pdf 并移动到 Documents/Invoices/。
账单：重命名为 yyyy-mm-dd-[Provider]-[Service]-[Account#].pdf 并移动到 Documents/Bills/。
收据：重命名为 yyyy-mm-dd-[Store]-[TotalAmount].pdf 并移动到 Documents/Receipts/。
旅行：重命名为 yyyy-mm-dd-[Transport/Hotel]-[Confirmation#].pdf 并移动到 Documents/Travel/。

scripts/find_duplicates.py：一个 Python 脚本，确定性地查找相同文件。它使用 SHA-256 哈希比较文件内容，而不是依赖文件名或大小，返回重复文件的 JSON 列表。
scripts/extract_pdf_metadata.py：一个 Python 辅助脚本，使用 pypdf 库从 PDF 中提取文本。使用此脚本而不是自行编写。它采用采样策略（前 3 页和最后一页）为文档分类提供高效的文本提取，在 JSON 包装器中返回文本。
scripts/detect_smart_folders.py：一个 Python 脚本，扫描目标文件夹的直接子目录以查找项目标记（.git/、package.json、Cargo.toml、Makefile 等）和应用包（.app）。返回检测到的“智能”文件夹的 JSON 列表，这些文件夹应移动到 Others/ 而不被拆散。
references/classification.md：包含 PDF 和其他文档类型的详细关键词列表和命名约定。

适用于需要整理杂乱文件夹、对文件进行分类、识别重复文件以及根据内容重命名 PDF 文档（如发票、收据）的场景。