smart-file-organizer

智能文件整理器

读取实际文件内容，以还原损坏的文件名、从头生成有意义的名称，并可选择将文件重新整理到分类文件夹中——所有操作都配有安全回滚映射。

分析目标目录（包括所有子目录）中的文件内容，根据内容重命名文件，并可选择将文件重新整理为逻辑清晰的文件夹结构。

模式

• rename-only（默认）：根据内容分析结果在原位置重命名文件。
• full-organize：重命名文件，并将其重新整理到分类文件夹结构中（创建、重命名、合并文件夹）。
• collect：扫描多个目录中的文件，并将符合用户指定用途的文件复制到单个输出文件夹中。不重命名或移动原始文件。

流程

步骤 1：收集参数

询问用户：

1. 目标目录——要扫描的绝对路径（必填）。
2. 模式——rename-only、full-organize 或 collect（默认：rename-only）。
   • 如果是 collect：还要询问收集查询——要收集哪类文件（例如：“简历相关文件”、“数据集文件”、“可丢弃文件”）。
3. 允许使用的语言——文件名应使用哪些语言（默认：与原文件相同或使用英语）。

   Which languages should be used in file names?
     Allowed: (e.g., Korean, English)
     Others:  auto-translate to an allowed language (e.g., Japanese → English)
   

   • 当文件内容使用不允许的语言时，将生成的名称翻译为用户首选的允许语言。
   • 首字母缩略词和专有名词无需翻译（如 IITP、YOLOv8 等）。
4. 文件筛选条件——要包含或排除的特定扩展名（默认：所有文件）。
5. 最大深度——递归进入子目录的深度（默认：不限制）。
6. 重命名严格程度——重命名文件的激进程度（默认：recovery）。

   How strictly should files be renamed?
     [R] Recovery  — only fix broken/meaningless names, keep already-descriptive names as-is
     [U] Uniform   — rename ALL files to a standardized format based on content
   

   • recovery：跳过当前名称已能合理描述文件内容的文件（即使格式与命名规范不完全一致）。
   • uniform：将所有原名称视为不可靠，并从头重新生成——当前行为。

如果用户提供目录但未指定其他选项，则使用默认值并继续。

步骤 2：扫描并建立清单

1. 递归列出目标目录中的所有文件。
2. 跳过隐藏文件和目录（以 . 开头）以及常见忽略模式（node_modules、.git、__pycache__ 等）。
3. 默认跳过源代码文件——重命名会破坏导入路径、包含指令和构建系统。排除的扩展名：.py、.cpp、.c、.h、.hpp、.js、.ts、.jsx、.tsx、.java、.go、.rs、.rb、.cs、.swift、.kt、.scala、.sh、.bat、.ps1，以及 CI/CD 配置文件（Jenkinsfile*、Makefile、Dockerfile、*.cmake）。用户可以使用显式的 --include-code 标志或通过请求来覆盖此设置。
4. 跳过可执行文件和安装程序文件——保留 .exe、.msi、.appimage、.dmg 文件的原名称。
5. 检测疑似数据集目录——处理前识别可能包含大批量数据集的目录。符合以下任一条件时，该目录即为疑似目录：
   • 包含100 个或以上扩展名相同的文件。
   • 文件采用连续编号或基于哈希值的命名模式（例如 img_0001.jpg…img_9999.jpg、a3f8c2.png）。
   • 名称匹配常见数据集模式（不区分大小写）：train、val、valid、validation、test、dataset、datasets、images、labels、annotations、samples、corpus、raw、processed。
   • 除批量数据外，还包含标注或清单文件（例如：*.json/*.csv 标注文件以及 50 个或以上图像/文本文件）。 对于每个疑似目录，请先征求用户意见，再决定如何处理：

   ⚠ The following directories are suspected to be datasets:
     📁 train/       — 1,523 .jpg files, sequential naming pattern
     📁 annotations/ — 1,523 .json files + manifest.csv
   
   For each directory, choose:
     [S] Skip  — treat as dataset, do not rename
     [I] Include — treat as normal folder, process files
   

   • 用户确认属于数据集的目录将被完全排除，并记录为“数据集目录（用户已确认）”。
   • 用户确认不属于数据集的目录将继续正常处理。
6. 创建清单，包含：当前路径、文件大小、扩展名、最后修改日期。
7. 扫描目录名称——识别名称异常或无意义的目录（乱码、New Folder、Untitled、仅含数字的名称，如 1、2、3）。这些目录将与文件一同纳入重命名映射。目录重命名适用于所有模式（包括 rename-only），并在所有文件重命名完成后执行，以避免路径失效。
   • 文件/目录名称编码恢复——对于包含乱码字节（mojibake）的名称，应使用原始字节依次尝试 EUC-KR、CP949、Shift_JIS、GB2312 和 Latin-1 解码。如果恢复出可读名称，则以此作为重命名依据。
8. 向用户报告清单摘要：
   • 文件总数
   • 按扩展名分类的数量
   • 总大小

如果文件超过 100 个，请先征求用户确认再继续，或建议使用筛选条件缩小范围。

批量处理——避免上下文溢出和工具调用失败：

• 每批最多处理 50 个文件。
• 文件总数超过 50 时，将清单拆分为每批最多 50 个文件。
• 将每批作为独立子 Agent 处理（如果无法使用子 Agent，则按顺序逐批处理）：
  1. 每批接收自己的文件列表，并独立执行步骤 3–4。
  2. 将所有批次的结果合并为统一的重命名映射，再呈现给用户。
• 子 Agent 批次可以并行运行（最多同时运行 4 批）。
• 子 Agent 自动批准——子 Agent 必须执行所有文件读取和分析操作，无需用户确认。只有最终汇总的试运行映射（步骤 4）需要用户批准。调用子 Agent 时，传入 --auto-approve 或等效标志，以便批次中的工具调用自动执行。
• 每批必须以 JSON 格式返回部分重命名映射，以便合并。
• 批次合并去重——合并所有批次结果后，检查建议名称是否冲突：
  1. 按建议名称（不区分大小写）对条目分组。
  2. 对每个冲突，通过添加区分属性（日期、父文件夹名称或数字后缀）来区分。
  3. 在试运行输出中记录已解决的冲突，供用户审核。
• 完成保障——所有批次返回后，确认清单中的每个文件都有对应处理结果（已重命名、因说明的原因跳过，或移至 _unknown/）。如果有文件缺失于批次结果中，则将其重新加入补充批次。最终重命名映射必须涵盖清单中的 100% 文件。

步骤 3：分析文件内容

具体行为取决于步骤 1 中设置的重命名严格程度。

当使用 uniform 模式时：

⚠ 严重警告：所有非代码文件都必须根据其实际内容重命名为规范格式。没有例外。

• 原始文件名不可靠——应将其视为随机字符。
• 必须先读取并分析文件内容，然后再从头生成文件名。
• 对于名称有一定描述性但不符合标准的文件（例如，073_disaster_safety_XR.hwpx、report_v2_final.docx），仍必须在读取内容后重命名。
• 只有当原始名称已完全符合命名规范格式，并且准确描述了具体内容时，才可以保留。

重命名标准（uniform）——只要满足以下任一条件，就必须重命名文件：

• 包含无意义的前缀、序列号或代码（073_、IMG_、DSC_、001_、(3)）。
• 名称含糊、使用缩写，或未体现文档的具体主题。
• 不符合 references/naming-conventions.md 中的 [YYMMDD_]<attr1>_<attr2>[_...<attrN>].<ext> 格式。
• 包含不允许使用的语言字符（参见步骤 1 中的语言设置）。
• 包含通用词（document、file、untitled、report），但没有具体上下文。

当使用 recovery 模式（默认）时：

只重命名名称明显损坏或毫无意义的文件。如果当前名称已经能合理表达文件内容，就原样保留——即使它没有完全遵循命名规范格式。

预筛选（读取内容前）——为了避免不必要地读取数百个文件，首先快速应用名称质量启发式规则：

1. 提取文件主名（不含扩展名）。
2. 如果主名包含至少 2 个有意义的词（非代码或数字），且没有不合格模式，则跳过内容读取（标记为“保留”）。
3. 仅当满足以下任一条件时，才需要读取内容：
   • 主名完全由非字母字符构成（哈希值、UUID、数字序列）。
   • 匹配自动生成的模式：IMG_\d+、DSC\d+、Screen Shot、document\(\d+\)、Untitled、New File。
   • 去除数字和标点后，主名中的字母词项少于 2 个。
   • 包含不允许使用的语言字符（参见步骤 1）。

对于大多数文件名已经比较合适的大型目录，此预筛选可大幅减少内容读取量。

重命名标准（recovery）——仅当满足以下任一条件时才重命名文件：

• 名称完全没有意义（例如，IMG_20240315_142356.jpg、document(3).pdf、a3f8c2.png）。
• 名称主要由代码、哈希值或连续数字组成，且不含描述性词语。
• 名称是单个通用词（untitled、file、new、temp）。
• 包含不允许使用的语言字符（参见步骤 1 中的语言设置）。

名称有一定描述性的文件（例如，quarterly_report.pdf、meeting_notes_march.txt）在 recovery 模式下原样保留。

对于每个文件，读取其内容并确定一个描述性名称：

基于文本的文件

扩展名：.txt、.md、.json、.csv、.html、.xml、.log、.yaml、.yml、.ini、.cfg、.conf、.toml 等。

• 读取文件前 10% 的内容（按行数或字节数计算）。至少 5 行。最多读取 200 行或 4 KB，以先达到者为准。
• 根据实际文本内容确定主要主题、用途或内容。
• 建议的名称必须体现文本的主题，而不是文件格式。

编码检测

如果文件内容显示为乱码或无法读取：

1. 按以下顺序尝试常见编码：utf-8 → cp949（韩语）→ shift_jis（日语）→ gb2312（中文）→ euc-kr → latin-1。
2. 如果可用，使用 file 命令或类似 chardet 的启发式方法检测编码。
3. 获得可读文本后，继续分析内容。
4. 如果所有编码都无法生成可读文本，则将文件标记为无法读取。

文档

扩展名：.pdf、.docx、.xlsx、.pptx、.hwp、.hwpx

• 提取前 10% 页数的文本（至少 1 页，提取的文本最多 8 KB）。
• 阅读提取的文本，识别文档的主题、标题或用途。
• .hwpx 文件是包含 XML 的 ZIP 压缩包——解压并解析 Contents/section*.xml 以提取正文文本。
• .hwp 文件——如果可用，请使用 hwp5txt 或 pyhwp；否则尝试使用 strings 命令并指定韩文编码。
• 如果文本提取失败，则使用元数据（标题、作者、主题）作为备用信息。
• 仅在最后才使用现有名称作为备用，并标记为供用户审核：⚠ content unreadable — name based on metadata/original。

图像

扩展名：.jpg、.png、.gif、.webp、.svg、.jfif

• 如果有 EXIF 数据或嵌入的元数据，请检查。
• 如果 Agent 具备视觉能力，直接分析图像内容并根据图像所示内容命名。
• 否则，按以下顺序尝试进行上下文推断：
  1. 同级文件——检查同一目录中的其他文件，寻找主题或项目线索。
  2. 时间戳——将创建或修改时间与附近文件进行比较，寻找时间上的关联。
  3. 文件名片段——从原始名称中提取有意义的部分（日期、序列号、应用名称）。
  4. 父目录名称——将文件夹名称用作类别提示。
• 如果以上方法都无法得出可靠的名称，则移至 _unknown/。

二进制文件／未知文件

• 仅使用文件元数据和扩展名。
• 不要尝试读取二进制内容。

无法读取的文件

无法分析的文件（已损坏、已加密、格式不受支持、所有编码尝试均失败）：

• 将文件移至 <target-dir>/_unknown/，并保留原始文件名。
• 记录失败原因（例如“编码检测失败”“没有元数据的二进制文件”）。
• 将这些文件包含在试运行预览中，以便用户覆盖处理决定。

语言处理

应用步骤 1 中设置的允许语言：

• 检测文件内容的语言。
• 如果内容语言不在允许列表中，则将建议的名称翻译成用户首选的允许语言。
• 缩写和专有名词保持原样。

命名规则

详细模式请参阅 references/naming-conventions.md。主要规则：

• 属性之间使用 _ 分隔，多词属性内部使用 - 分隔。
• 名称应简洁：最多包含 3–6 个属性。
• 保留原始文件扩展名。
• 如果文件有明确的关联日期，请添加日期前缀（YYMMDD_）。
• 避免使用 document、file、untitled 等通用名称。
• 始终根据内容分析生成新名称——绝不可复制原始文件名。即使原始名称包含相关词语，也要遵循命名规范格式，从头重新构建名称。

第 4 步：生成重命名映射（试运行）

以 JSON 格式构建重命名映射。当文件总数超过 30 个时，优先展示摘要：

📊 Rename Summary
  Rename:  142 files
  Keep:    358 files (name already descriptive)
  Unknown:   5 files → _unknown/

  By extension: .pdf (42) · .hwpx (31) · .jpg (28) · .docx (22) · .txt (19)

  [Show full list]  [Show by folder]  [Show renames only]

当用户请求查看详情（或文件总数 ≤ 30）时，展示完整的重命名映射：

Current Name                    → Proposed Name
────────────────────────────────────────────────
IMG_20240315_142356.jpg         → 240315_sunset_beach-photo.jpg
document(3).pdf                 → 240901_quarterly_sales-report_Q3.pdf
073_disaster_safety_XR.hwpx     → 250530_IITP_disaster-safety_XR-augmentation_proposal.hwpx
notes.txt                       → meeting-notes_product-roadmap.txt

⚠ Unreadable (→ _unknown/):
corrupted-data.bin              → _unknown/corrupted-data.bin (reason: binary, no metadata)

迭代审批流程——重复此流程，直到用户明确批准：

1. 展示完整的重命名映射。
2. 用户可以：
   • 全部批准——继续执行第 5 步。
   • 请求更改——例如：“使用韩语名称”“缩短名称”“仅为照片保留日期前缀”“不要将文件 X 移至 _unknown”。
   • 编辑特定条目——修改单个拟议名称。
   • 排除文件——跳过特定文件。
   • 取消——中止操作。
3. 如果用户请求更改，修改受影响的条目并再次展示更新后的映射。
4. 返回此流程的第 1 步。

在用户明确批准之前，不得继续执行操作。

执行前回滚映射——用户批准后，立即在进行任何文件操作之前保存计划的回滚映射：

bash <skill-path>/scripts/rename-map.sh save <target-dir>

这会创建 <target-dir>/.file-organizer-map.json，确保即使执行过程中断，用户仍可回滚已完成的操作。

第 5 步：执行重命名

保存回滚映射后：

1. 逐个重命名文件。
2. 进度报告——对于大批量文件（50 个及以上），每处理 25 个文件报告一次进度：

   ✅ 25/142 renamed... (17%)
   ✅ 50/142 renamed... (35%)
   

3. 报告任何错误（例如名称冲突、权限问题）。
4. 如果名称冲突，追加数字后缀：report_Q3_2.pdf。
5. 核对回滚映射——所有重命名完成后，根据实际文件系统状态核对映射，并移除未执行操作对应的条目：

   bash <skill-path>/scripts/rename-map.sh reconcile <target-dir>
   

   这样可确保回滚映射仅包含实际执行过的操作。
6. 执行完整性检查——将核对后的映射和跳过列表与原始清单进行比较。如果有任何文件既未重命名也未明确跳过，则将其报告为错误并重试。

第 6 步：重新整理（仅限 full-organize 模式）

如果用户选择了 full-organize，则在重命名后：

1. 分析现有文件夹结构和文件内容类别。

2. 提出新的文件夹结构——可包括：

   • 创建新文件夹，用于存放尚不存在类别的文件。
   • 重命名现有文件夹，使名称更具描述性（例如，misc/ → reports/，New Folder/ → presentations/）。
   • 合并文件夹，合并内容相似的文件夹。
   • 移除空文件夹，在文件移出后清理空文件夹。

   提案示例：

   📁 Folder changes:
     [NEW]    documents/reports/
     [NEW]    images/screenshots/
     [RENAME] misc/ → data/csv/
     [RENAME] New Folder/ → presentations/
     [DELETE] old-stuff/ (empty after move)
   
   📁 Proposed structure:
   <target-dir>/
   ├── documents/
   │   ├── reports/
   │   └── notes/
   ├── images/
   │   ├── photos/
   │   └── screenshots/
   ├── data/
   │   ├── csv/
   │   └── json/
   └── other/
   

3. 文件夹命名遵循与文件命名相同的规范（参见 references/naming-conventions.md），使用描述性名称。

4. 将拟议的文件夹更改和文件移动一并提交给用户审批。

5. 获得批准后，先执行文件夹操作（创建／重命名），再移动文件，最后清理空目录。

6. 所有文件夹重命名／移动操作都会记录在回滚映射中，以便撤销。

第 6b 步：收集（仅限 collect 模式）

如果用户选择了 collect，则跳过第 3 至第 6 步，改为执行以下流程：

1. 使用第 1 步中的收集查询定义搜索条件。
2. 针对清单中的每个文件，通过以下方式判断其相关性：
   • 文件名和路径关键词。
   • 内容抽样（文本读取前 4 KB，文档读取前 8 KB）——与第 3 步使用相同的上限。
   • 元数据（扩展名、父文件夹名称、日期）。
3. 为每个文件的相关性评分，并创建包含置信度级别的收集列表：

   📋 Collect: "resume-related files" → _collected/resume_related/
     ✅ High (12 files):
       documents/resume_john-doe.pdf
       career/portfolio_2025.pptx
       ...
     🔶 Medium (5 files):
       misc/cover-letter_draft.docx
       ...
     ❌ Excluded (283 files): not relevant
   

4. 展示收集列表，并请用户批准、调整阈值或排除特定文件。
5. 获得批准后，将匹配的文件复制（而非移动）到 <target-dir>/_collected/<query-slug>/。
6. 以扁平副本形式保留原始目录结构（发生冲突时，在文件名前添加父文件夹名称）。
7. 在 .file-organizer-changelog.md 中记录收集操作。

步骤 7：总结报告

输出总结：

• 重命名的文件：数量
• 移动的文件：数量（如果是 full-organize）
• 收集的文件：数量和目标位置（如果是 collect）
• 跳过的文件：数量和原因
• 回滚命令：bash <skill-path>/scripts/rename-map.sh rollback <target-dir>

保存更改日志——在 <target-dir>/.file-organizer-changelog.md 写入一个 Markdown 文件，内容如下：

# File Organizer Change Log

- **Date**: YYYY-MM-DD HH:MM
- **Mode**: rename-only | full-organize | collect
- **Target**: <target-dir>

## Changes (N files)

| # | Before | After |
|---|--------|-------|
| 1 | `old-name.pdf` | `new-name.pdf` |
| ... | ... | ... |

## Skipped (M files)

| # | File | Reason |
|---|------|--------|
| 1 | `some-file.py` | Source code (excluded) |
| 2 | `train/` (1523 files) | Dataset directory (user confirmed) |
| ... | ... | ... |

## Moved to _unknown/ (K files)

| # | File | Reason |
|---|------|--------|
| 1 | `hash-image.webp` | Unreadable content |
| ... | ... | ... |

每次运行都会覆盖此文件（不会保留之前的日志）。

回滚

回滚映射（.file-organizer-map.json）会记录每项重命名/移动操作，以便撤销。用户可以使用以下命令管理它：

# Save current rename map (done automatically before execution)
bash <skill-path>/scripts/rename-map.sh save <target-dir>

# Show the current rollback map contents
bash <skill-path>/scripts/rename-map.sh show <target-dir>

# Undo all renames/moves recorded in the map
bash <skill-path>/scripts/rename-map.sh rollback <target-dir>

# Reconcile map after execution (remove entries for operations that didn't happen)
bash <skill-path>/scripts/rename-map.sh reconcile <target-dir>

# Clear the rollback map (after confirming changes are correct)
bash <skill-path>/scripts/rename-map.sh clear <target-dir>

用户也可以直接向 Agent 提出请求：“回滚上一次文件整理”“显示重命名过的内容”或“清除回滚历史记录”。

安全规则

• 绝不覆盖现有文件——务必先检查是否存在冲突。
• 未经用户明确批准，绝不执行 rm -rf 或任何递归删除命令——即使是在子 Agent 中也是如此。只有确认目录为空后，才允许删除空目录（rmdir）。
• 做出任何更改前，务必先保存回滚映射。
• 执行前，务必展示试运行预览并获得用户明确批准。
• 跳过当前已打开或被锁定的文件。
• 重命名/移动时保留文件权限和时间戳。