dedicated-file-manager

Manage, organize, classify, rename, archive, and clean files and folders with dedicated workspace setup, automated sorting, and conflict handling.

Security Scan

The skill's code, docs, and runtime instructions are coherent with a local file-management purpose; it performs only filesystem scanning/moving and manifest generation and does not request credentials or network access, though it implies automated scheduled runs without providing a concrete scheduler/setup step.

Purpose & Capability

Name/description match the included Python scripts and reference docs: scanning directories, categorizing, renaming, archiving, and keeping a manifest. Nothing requires unrelated credentials or binaries. Minor mismatch: SKILL.md promises configuring weekly automatic tasks, but there is no install/spec that registers a scheduler (cron/systemd) or an agent-side installer to implement that automation.

Instruction Scope

Instructions focus on file-management actions (scan, classify, move to archive, update manifest) which aligns with purpose. They also encourage proactive/periodic maintenance and creating an Agent 'dedicated workspace' (including creating directories and config/manifest files in user paths). This grants the agent implicit permission to traverse and modify the filesystem under the chosen root — acceptable for this skill but worth confirming the exact root path before use.

Install Mechanism

No external install or downloads are declared. All code is bundled (three Python scripts and reference docs). There is no remote URL, package install, or archive extraction — low install risk.

Credentials

The skill requests no environment variables, credentials, or config paths. The scripts operate on filesystem paths supplied at runtime; this is proportionate to a file-manager skill. The only implicit path mentioned in docs (~/.workbuddy/...) is a reasonable default for saving templates but should be confirmed with the user.

Persistence & Privilege

Metadata does not force permanent inclusion (always:false). However, SKILL.md repeatedly describes periodic autonomous behavior (weekly automatic整理) and '主动维护' which implies scheduling recurring tasks. The bundle does not implement a concrete scheduler; if the agent is instructed to configure system schedulers (cron/systemd) to call these scripts, that would create persistent background behavior. Ask the user before enabling any scheduled/autonomous runs.

Assessment

This skill appears to do what it says: local scanning, categorization, moving files to archive (it does not auto-delete), and manifest updates. Before installing/using it: (1) Confirm the exact 'root' or dedicated workspace path you want the agent to manage — avoid giving it '/' or broad home directories. (2) Run the scripts in dry-run mode first (they support --dry-run) to see proposed moves. (3) The docs suggest weekly automatic runs but the package doesn't set up a scheduler; only enable any cron/systemd jobs if you trust the skill and know which commands will run. (4) Review the bundled scripts yourself (they are included) if you have concerns — they do not make network calls or read secrets. (5) Require explicit user confirmation for any destructive actions (the SKILL.md advocates this), and ensure the agent is configured to ask you before making changes you haven't approved.

文件管理技能 (file-manager)

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

---

设计原则

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

安全优先：

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

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

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

---

专属文件夹机制

核心理念

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

文件夹结构

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

核心机制

机制	说明
inbox 入口	所有新文件先入 inbox，避免散落各处
manifest 自维护	自动记录每个文件的状态和位置
定期整理	inbox 里的文件每周自动归位一次
新项目交接	扫描项目文件，自动建立清单
主动巡查	发现乱放文件时主动提醒用户

设置流程

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

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

自动化流程

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

---

模块清单

核心模块（自动加载）

模块	触发关键词
M1: 扫描与感知	"扫描"、"现状"、"有哪些文件"
M2: 分类判断引擎	"分类"、"整理"、"类型"
M3: 命名处理器	"重命名"、"命名规范"、"改名字"
M4: 目录结构生成器	"创建目录"、"文件夹结构"、"建文件夹"
M5: 废弃文件处理	"归档"、"废弃"、"删除"
M6: 临时文件处理	"临时文件"、"清理临时"、"_temp"
M7: 冲突与重复处理	"重复"、"冲突"、"同名"
M8: 归档处理	"项目归档"、"结束整理"、"收尾"

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

模块	触发关键词
M9: 专属文件夹初始化	"设置专属文件夹"、"初始化工作区"、"这是我的工作区"
M10: 定期整理执行	"整理"、"整理 inbox"、"自动整理"
M11: 新项目交接	"新项目"、"交接项目"、"扫描项目"

扩展模块（按需加载）

模块	触发关键词
E1: 版本管理辅助	"版本"、"v1"、"v2"、"draft"
E2: 素材库专项	"素材"、"图片整理"、"音频整理"、"视频整理"
E3: 批量重命名	"批量重命名"、"批量改名"
E4: 关系映射	"关联文件"、"项目关系"、"关联"
E5: 报告生成	"生成报告"、"操作日志"、"整理报告"

---

核心模块详解

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

2. 按文件状态

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

3. 按归属

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

执行流程：

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

---

M3: 命名处理器

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

命名规则：

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

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

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

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

3. 通用规则

   • 日期格式：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 天以上：自动移入废弃目录（不删除）
3. 生成清理报告

注意事项：

• 区分"临时文件"和"草稿文件"：草稿是故意保留的，临时是无意遗留的
• 代码项目中的 *.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     # 配置文件
   

3. 生成初始 manifest.md
4. 更新配置文件记录路径
5. 询问是否需要配置每周自动整理
6. 如果需要，创建 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/（待用户进一步分类）
   • 临时文件 → 检查年龄，决定归档或保留
4. 处理命名冲突
5. 更新 manifest.md
6. 生成整理报告
7. 如有过期临时文件，移入 archives/

文件分类规则：

类型	扩展名	目标目录
文档	.md, .docx, .pdf, .txt, .xlsx 等	references/
代码	.py, .js, .cs, .json, .yaml 等	projects/
素材	.png, .jpg, .mp3, .mp4 等	scratch/
Unity	.unity, .prefab, .shader 等	projects/unity/

---

M11: 新项目交接

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

触发条件：

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

执行流程：

1. 扫描项目目录（深度 3 层）
2. 识别文件类型分布
3. 识别命名问题
4. 生成项目报告：
   • 文件统计
   • 类型分布
   • 建议的目录结构
   • 需要关注的问题
5. 询问用户确认分类方式
6. 根据用户确认，执行分类和整理
7. 在 projects/ 下创建项目子目录
8. 更新 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]

---

配置项

用户可配置的选项：

配置项	默认值	说明
专属文件夹路径	未设置	Agent 工作区的根目录
inbox 目录名	inbox	收件箱目录名
归档目录名	archives	废弃文件存放的目录名
临时目录名	scratch	临时文件目录名
临时文件保留期	30天	超过此天数的临时文件建议归档
自动整理周期	每周	定期整理的频率
默认命名语言	跟随项目类型	代码类用英文，文档类用中文
层级深度限制	3	建议的最大目录深度

---

扩展能力

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

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

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