dedicated-file-manager（专用文件管理器）

文件管理技能 (file-manager)

模块化的文件管理规则集，用于指导 Agent 执行各类文件和文件夹的整理、分类、命名、归档操作。

设计原则

止观：规则够用即可，不过度设计。优先执行，不制造负担。

安全优先：

• 废弃文件只移入废弃目录，绝不自动删除
• 遇到不确定情况时，保留文件并报告给用户
• 执行破坏性操作前必须列出计划并获取确认

场景驱动：根据文件所在环境自动选择合适的处理方式，不强制统一规则。

主动维护：不等待用户提醒，定期整理并保持清单更新。

专属文件夹机制

核心理念

为 Agent 创建专属工作区，让它拥有自己的"领地"来主动管理文件，而不是被动等待用户要求整理。

文件夹结构

专属文件夹/
├── 📥 inbox/           # 收件箱：新文件统一入口
├── 📁 projects/        # 项目工作区（按项目分子目录）
├── 📚 references/      # 参考资料、文档
├── 📦 archives/       # 归档区
├── 🔧 scratch/        # 草稿、临时工作
├── 📋 manifest.md     # 文件清单（自动维护）
└── ⚙️ config.json     # 配置文件

核心机制

设置流程

当用户说"设置专属文件夹"或"这是我的工作区"时：

1. 询问用户文件夹路径（或使用默认路径）
2. 创建标准目录结构
3. 生成初始 manifest.md
4. 配置每周自动整理任务
5. 记录到配置文件中

自动化流程

用户设置专属文件夹
        ↓
创建标准目录结构 + manifest.md
        ↓
配置每周自动整理（Automation）
        ↓
┌─────────────────────────────────┐
│  每周自动执行：                  │
│  1. 扫描 inbox                   │
│  2. 按规则分类到对应目录          │
│  3. 清理过期临时文件              │
│  4. 更新 manifest.md             │
│  5. 生成整理报告                  │
└─────────────────────────────────┘

模块清单

核心模块（自动加载）

专属文件夹模块（M9-M11）

扩展模块（按需加载）

核心模块详解

M1: 扫描与感知

目的：进场第一步，摸清当前文件状态。

执行步骤：

1. 列出目标目录下的所有文件和文件夹
2. 识别文件类型分布（文档/代码/素材/数据等）
3. 识别命名问题（乱码、空格、过长、无后缀等）
4. 识别目录结构问题（层级过深、根目录堆文件等）
5. 输出扫描报告，包含发现的问题列表

输出格式：

📁 扫描结果：[目录路径]

文件统计：
- 总文件数：X
- 总文件夹数：X
- 文件类型分布：...

发现的问题：
1. [问题1描述]
2. [问题2描述]
...

建议操作：
- [操作建议1]
- [操作建议2]

M2: 分类判断引擎

目的：为每个文件打标签，确定其分类归属。

分类维度：

1. 按文件类型

- 文档类：.md, .docx, .pdf, .txt, .xlsx - 代码类：.cs, .py, .js, .cpp, .shader - 素材类：.png, .jpg, .mp3, .wav, .mp4, .fbx - 配置类：.json, .yaml, .xml, .ini - 数据类：.db, .csv, .log - 临时类：_temp, ~, .tmp

1. 按文件状态

- 进行中：正在编辑、近期修改 - 待处理：等待用户决策、需要外部输入 - 已完成：不再修改、已达成目标 - 归档：项目结束、历史版本

1. 按归属

- 项目文件：属于特定项目 - 个人文件：通用工具、个人资料 - 共享文件：需要保留给其他人或跨项目使用

执行流程：

1. 对每个文件分析三个维度
2. 综合判断确定最佳归属位置
3. 如有冲突，优先考虑文件类型，其次是状态，最后是归属

M3: 命名处理器

目的：标准化文件命名，解决命名混乱问题。

命名规则：

1. 代码/技术类项目（自动识别）

- 使用英文 - 格式：kebab-case 或 snake_case - 示例：player-controller.cs, game_config.json - 禁止：空格、中文、特殊符号（除 - 和 _）

1. 文档/素材/个人类项目（自动识别）

- 可用中文 - 格式：语义描述_版本或日期.后缀 - 示例：游戏设计文档_v2_20260414.md - 禁止：空格（用 _ 或 - 代替）、纯数字、过长文件名

1. 通用规则

- 日期格式：YYYYMMDD（如 20260414） - 版本格式：v1, v2 或 _draft, _final（后者更明确状态） - 序号格式：01, 02（保持两位数） - 关键词分隔：+ 或 -

重命名流程：

1. 分析原文件名，提取核心语义
2. 根据文件类型和所在项目选择命名规则
3. 生成新文件名
4. 检查是否与同目录其他文件冲突
5. 执行重命名

M4: 目录结构生成器

目的：按需创建合理的文件夹骨架。

标准模板（可选）：

项目根目录/
├── 00_文档/          # 所有文档类文件
├── 01_代码/          # 代码文件
├── 02_素材/          # 原始素材
├── 03_产出/          # 生成物、最终版本
├── 04_配置/          # 配置文件
├── _archive/         # 归档（旧版本、废弃文件）
├── _temp/            # 临时文件
└── README.md         # 项目说明

层级原则：

• 不超过 3 层（根目录 → 一级 → 二级）
• 超过 3 层时建议拆分项目或增加分类标签
• 同级文件夹数量建议不超过 10 个

生成流程：

1. 询问或推断项目类型（代码项目/内容项目/混合项目）
2. 选择合适的目录结构模板，或根据需求自定义
3. 创建目录（不覆盖已有目录）
4. 可选：生成 README.md 说明各目录用途

M5: 废弃文件处理

目的：安全地管理废弃文件，不丢失数据。

废弃目录：

• 默认位置：archives/ 或 废弃/
• 可配置：用户可指定其他废弃目录路径
• 结构：archives/[原始目录名]/[原文件名_移入日期]

判定废弃的标准：

• 文件超过 30 天未被访问
• 文件已明确被新版本替代（如 v1 被 v2 替代）
• 用户明确要求归档
• 文件属于已结束的项目

执行规则：

1. 只移入废弃目录，绝不删除
2. 移动时保留原始目录结构信息
3. 在废弃目录中按日期组织，便于追溯
4. 定期向用户报告废弃目录中的文件，由用户决定是否彻底删除

M6: 临时文件处理

目的：识别和管理临时文件，防止堆积。

识别标准：

• 文件名包含 _temp, temp, ~, tmp, backup
• 文件扩展名为 .tmp, .bak, .cache
• 在 _temp 目录中的文件
• 最近 7 天内创建但未被修改的文件

处理流程：

1. 识别临时文件，列出清单
2. 根据文件年龄分类：

- 7 天内：标记为"近期临时"，提醒用户确认 - 7-30 天：建议移入废弃目录 - 30 天以上：自动移入废弃目录（不删除）

1. 生成清理报告

注意事项：

• 区分"临时文件"和"草稿文件"：草稿是故意保留的，临时是无意遗留的
• 代码项目中的 *.tmp 文件可能是 IDE 生成的，谨慎处理

M7: 冲突与重复处理

目的：安全处理文件命名冲突和疑似重复。

命名冲突处理：

1. 发现同名文件时，不覆盖
2. 分析两个文件的内容和时间戳
3. 保留较新或内容更完整的版本
4. 另一个文件移入废弃目录并标注原因

内容重复处理：

1. 检测同名或高度相似的文件名（如 xxx_副本, xxx_copy）
2. 对比文件大小和修改时间
3. 如确认是重复，保留一个，另一个归档
4. 不确定时保留两个并报告给用户

执行原则：

• 永远不自动删除，只归档
• 无法判断时，报告给用户等待指令

M8: 归档处理

目的：项目结束后的整体归档整理。

归档流程：

1. 扫描项目目录，生成完整文件清单
2. 按分类判断引擎标记每个文件的状态
3. 将"已完成"和"历史版本"文件移入归档目录
4. 清理临时文件
5. 生成归档报告，包含：

- 项目名称和归档日期 - 文件统计 - 文件清单（按类型和状态分类） - 废弃文件清单（未彻底删除）

归档目录结构：

archives/
└── [项目名]_[归档日期]/
    ├── 文件清单.md
    ├── 产出物/
    ├── 源代码/
    ├── 素材/
    └── 文档/

专属文件夹模块详解

M9: 专属文件夹初始化

目的：为 Agent 创建专属工作区，设置标准目录结构。

触发条件：

• 用户说"设置专属文件夹"、"初始化工作区"、"这是我的工作区"
• 用户提供文件夹路径

执行流程：

1. 确认或创建专属文件夹路径
2. 创建标准目录结构：

   [根目录]/
   ├── inbox/           # 收件箱
   ├── projects/       # 项目工作区
   ├── references/      # 参考资料
   ├── archives/       # 归档
   ├── scratch/        # 临时工作
   ├── manifest.md     # 文件清单
   └── config.json     # 配置文件

1. 生成初始 manifest.md
2. 更新配置文件记录路径
3. 询问是否需要配置每周自动整理
4. 如果需要，创建 Automation 任务

配置项：

{
  "root_path": "[专属文件夹路径]",
  "inbox_name": "inbox",
  "auto_organize": true,
  "clean_days": 30,
  "last_organize": null
}

M10: 定期整理执行

目的：自动整理 inbox，保持文件有序。

自动执行时机：

• 每周 Automation 触发
• 用户手动说"整理"、"整理 inbox"

执行流程：

1. 扫描 inbox 目录
2. 对每个文件识别类型
3. 根据规则分类：

- 文档类 → references/ - 代码类 → projects/ - 素材类 → scratch/（待用户进一步分类） - 临时文件 → 检查年龄，决定归档或保留

1. 处理命名冲突
2. 更新 manifest.md
3. 生成整理报告
4. 如有过期临时文件，移入 archives/

文件分类规则：

M11: 新项目交接

目的：接收新项目，快速建立文件清单。

触发条件：

• 用户说"新项目"、"交接项目"、"扫描项目"
• 用户提供一个项目文件夹路径

执行流程：

1. 扫描项目目录（深度 3 层）
2. 识别文件类型分布
3. 识别命名问题
4. 生成项目报告：

- 文件统计 - 类型分布 - 建议的目录结构 - 需要关注的问题

1. 询问用户确认分类方式
2. 根据用户确认，执行分类和整理
3. 在 projects/ 下创建项目子目录
4. 更新 manifest.md

扩展模块详解

E1: 版本管理辅助

目的：帮助识别和整理文件的版本关系。

版本识别规则：

• 文件名中包含 v1, v2, _draft, _final, _old, _new
• 文件名以序号结尾，如 xxx_01, xxx_02
• 同一目录下存在多个类似文件名

版本关系映射：

1. 识别同一文件的不同版本
2. 按时间顺序排列
3. 标记最新版本和最终版本
4. 其他版本归档处理

版本命名建议：

• 使用 v1, v2 表示版本号（简洁）
• 使用 _draft, _final 表示状态（更直观）
• 避免混用两种格式

E2: 素材库专项

目的：针对图片、音频、视频等素材的专业分类。

素材分类结构：

素材库/
├── 图片/
│   ├── 原始素材/      # 未加工的原始文件
│   ├── 处理后/        # 经过处理但非最终版
│   └── 最终使用/      # 已在项目中使用的
├── 音频/
│   ├── 音效/
│   ├── 音乐/
│   └── 语音/
├── 视频/
│   ├── 原始素材/
│   └── 剪辑版/
└── 3D资源/
    ├── 模型/
    ├── 贴图/
    └── 动画/

素材命名规则：

• 格式：[类型]_[项目]_[描述]_[日期]
• 示例：角色_主角待机动画_20260414.fbx
• 禁止：中文+特殊符号混用

E3: 批量重命名

目的：对多个文件按统一规则重命名。

使用场景：

• 统一文件名前缀或后缀
• 批量添加日期或序号
• 去除文件名中的乱码或多余字符

执行流程：

1. 列出需要重命名的文件清单
2. 说明重命名规则
3. 预览前 10 个文件的新旧名称对比
4. 确认后执行
5. 报告执行结果

常见规则：

• 添加前缀：[前缀]_[原名]
• 添加后缀：[原名]_[后缀]
• 序号重排：[原名]_01, [原名]_02
• 日期前缀：[日期]_[原名]
• 全局替换：替换文件名中的特定字符串

E4: 关系映射

目的：识别和记录文件之间的关联关系。

关联类型：

• 项目关联：同一项目下的所有文件
• 依赖关联：一个文件被其他文件引用（如代码中的 import）
• 版本关联：同一文件的不同版本
• 素材关联：源素材与处理后的副本

映射输出：

📊 文件关系图

项目：游戏设计
├── 核心文件
│   ├── 设计文档.md
│   └── 角色设定.md
├── 素材文件
│   ├── 角色图.png
│   └── 场景图.jpg
└── 版本记录
    └── 设计文档.md
        ├── v1_20260401
        └── v2_20260410

E5: 报告生成

目的：在文件整理任务完成后输出清晰的报告。

报告内容：

1. 任务概述（时间、目录、文件数量）
2. 执行的操作清单
3. 新创建的文件/目录列表
4. 移动/重命名的文件清单
5. 废弃文件清单
6. 发现但未处理的问题
7. 建议的后续操作

报告格式：

# 文件整理报告

**时间**：2026-04-14 18:00
**目录**：/path/to/directory
**操作人**：Agent

## 统计
- 处理文件数：X
- 新建目录：X
- 重命名：X
- 移动：X

## 操作详情
[详细列表...]

## 发现的问题
[如有]

## 建议
[后续建议...]

执行决策规则

何时可以直接执行

以下情况 Agent 可以直接执行，无需询问：

• 在已有目录中创建新子目录
• 将文件移入专属文件夹的对应目录（按规则）
• 重命名不涉及内容变更（如去除空格、修正乱码）
• 创建目录结构（不影响已有文件）
• 整理 inbox 中的文件（按预设规则）

何时必须暂停并询问

以下情况必须列计划并等待用户确认：

• 删除任何文件（即使在废弃目录中）
• 移动可能影响项目结构的文件
• 重命名可能影响引用的文件（如代码中的引用）
• 处理不确定是否为重复的文件
• 批量重命名超过 20 个文件
• 用户明确要求保留在当前位置的文件

错误恢复

如果操作失败：

1. 记录错误信息
2. 尝试恢复到操作前状态
3. 报告错误和已恢复的状态
4. 等待用户下一步指示

脚本工具

scan_directory.py

扫描目录并生成结构化 JSON 报告。

python scripts/scan_directory.py <path> [--max-depth 3] [--output report.json] [--analyze]

update_manifest.py

扫描目录并更新 manifest.md 文件清单。

python scripts/update_manifest.py <path> [--output manifest.md]

organize_inbox.py

整理 inbox 目录，自动分流文件。

python scripts/organize_inbox.py <root> [--inbox inbox] [--clean-days 30] [--dry-run] [--report report.md]

配置项

用户可配置的选项：

扩展能力

如需更多功能，可以扩展以下内容：

• 与版本控制系统（Git）集成
• 与云存储服务集成
• 自动备份逻辑
• 定时清理任务
• 自定义分类规则

如需这些扩展，请在技能说明中注明。