前言

作为打工人/程序员/学生党，你是否也曾面对这样的场景：下载文件夹里堆满了各种格式的文件，项目目录里散落着文档、代码、截图，找个文件要翻半天；手动整理又耗时耗力，分类逻辑还总不统一？

最近开发了一款「智能文件夹整理Agent」工具，基于DeepSeek大模型驱动，既能自动分析文件特征生成整理方案，也支持自定义规则，还能可视化预览、拖拽调整，彻底告别文件夹杂乱的烦恼。

代码已经开源在github：https://github.com/ChenAI-TGF/FolderFox
如果觉得有用的话欢迎点一个宝贵的Star！谢谢！！！

核心功能：不止是“按类型分类”

市面上很多文件整理工具只能简单按后缀名归类，但实际使用中我们的需求远不止于此——比如按项目维度、按时间前缀、按业务场景整理，甚至要区分大文件/近期文件避免误操作。这款工具的核心亮点在于：

1. 多模式智能整理，适配不同场景

智能模式（默认）：基于DeepSeek大模型分析文件名、类型、内容特征，生成贴合日常使用习惯的分类方案（比如“2024Q4项目报告”会归到“项目文档/2024Q4”，而不是单纯的“文档”文件夹）；
按类型模式：经典的后缀名分类，自动创建“图片”“代码”“视频”等文件夹，适合通用整理；
按文件名前缀模式：针对有命名规范的文件（如“20240512_会议记录.md”“20240512_截图.png”），自动按前缀分组，适合归档类文件。

2. 可视化预览+交互式调整

左侧展示「整理前的文件结构」，右侧展示AI生成的「整理后预览」，所有文件分类一目了然；
支持拖拽调整：觉得AI分类不对？直接拖拽文件/文件夹到目标目录，实时修改整理方案；
右键菜单：可新建子文件夹、移除不想整理的文件，完全自定义整理逻辑。

3. 高风险文件防护，避免误操作

自动标记「大文件（>100MB）」和「近期文件（7天内）」，可单独筛选查看，防止重要文件被误移动；
执行整理前需二次确认，支持一键撤销上次整理操作，不怕整理错了回不来。

4. 多语言+个性化定制

界面支持中文/英文切换，分类文件夹名称也可选择对应语言；
支持自定义“不整理的文件类型”（比如保留所有.pdf文件不动）；
可输入个性化需求（如“所有Python代码文件放到code目录下，按模块细分”），AI会按你的要求生成方案。

核心技术原理：文件整理专用Agent的设计与实现

很多朋友会问：市面上有很多按后缀分类的整理脚本，这个工具和它们有什么区别？为什么要叫「Agent」？

答案很简单：传统整理脚本只能执行预设的固定规则，而这个工具是一个面向文件整理场景的轻量闭环Agent，它具备了智能体的核心四要素：环境感知、自主决策、工具执行、反馈迭代，能基于环境信息和用户需求动态生成方案，还能通过人机反馈持续优化，而非死板执行固定逻辑。

下面我拆解这个Agent的完整架构设计，每一部分都对应代码里的核心实现：

1. 环境感知层：Agent的「眼睛」，精准捕捉文件系统特征

Agent的所有决策，都基于对当前环境的完整感知。这一层对应代码里的_collect_files_info方法，核心是完成文件系统的结构化信息采集与特征工程，为后续决策提供完整、低噪的输入。

它的核心工作流程：

递归扫描目标文件夹的全量文件，过滤掉用户指定跳过的文件类型，避免无效信息输入；
提取文件的核心元特征：文件名、后缀名、文件大小、修改时间、相对路径，构建结构化的文件信息对象；
对文本类文件（代码、Markdown、日志、配置文件等）做轻量内容采样（读取前800字符），让AI能基于文件内容做更精准的分类，而非仅靠文件名；
预标记高风险特征：基于阈值判定「大文件」「近期文件」，为后续的风险提示和筛选提供依据，避免AI决策带来的误操作风险。

和传统脚本只读取后缀名不同，这个感知层会给AI提供多维度的特征，让决策更贴合用户的真实使用习惯，比如同样是.md文件，AI能通过内容采样区分是「项目文档」还是「个人笔记」，从而分到不同的目录。

2. 决策规划层：Agent的「大脑」，基于大模型的动态分类决策

这是Agent的核心，对应代码里的_deepseek_worker方法和DeepSeekClient客户端，核心是把文件整理任务转化为大模型可理解、可稳定输出的结构化任务，基于感知到的文件信息和用户需求，生成可执行、可校验的整理方案。

我针对文件整理场景，做了深度的Prompt工程和输出约束，解决了大模型通用输出的不稳定性问题，核心设计包括：

多模式任务拆解：不同的整理模式，对应不同的System Prompt指令，精准控制AI的决策逻辑：
- 智能模式：让AI基于文件的全量特征，模拟用户日常的文件管理习惯，做语义化、场景化的分类，同时严格遵守用户输入的个性化自然语言需求；
- 按类型模式：给AI预设固定的文件类型-分类目录映射，优先按后缀名做标准化分类，兼顾AI的灵活性和规则的确定性；
- 按文件名前缀模式：强制AI优先匹配文件名的公共前缀，按前缀做分组归档，适配有规范命名的归档场景。
严格的输出格式约束：强制大模型输出JSON数组格式，每个文件对应固定的字段（name/suggested_subfolder/reason），保证输出结果可被代码稳定解析，杜绝大模型的自由文本输出带来的解析失败问题；
Token与成本优化：只给模型输入必要的结构化特征，而非全量文件内容，文本采样限制在800字符以内，既保证了分类的准确性，又大幅降低了Token消耗和响应延迟，让整个分析过程能在几秒内完成。

和传统脚本的固定规则最大的区别是：这个决策层能理解自然语言需求，比如用户输入“所有和项目A相关的文件都放到项目A文件夹，按文档、代码、素材细分”，AI能自动识别相关文件，生成多级目录结构，而无需用户提前写好正则规则或分类脚本。

3. 执行工具层：Agent的「手」，安全可控的文件系统操作

决策生成后，Agent需要可靠地执行方案，这一层对应代码里的_execute_organize_worker和_undo_organize_worker方法，核心是把AI生成的分类方案，转化为安全、可追溯、可回滚的文件系统操作，解决了通用Agent直接操作文件系统的安全风险问题。

核心的安全设计：

前置冲突校验：执行移动前，先校验目标路径是否已存在同名文件，优先判断是否为同一文件、是否内容重复，避免无效移动；若存在冲突，自动生成有序后缀（_1/_2），绝不覆盖用户的已有文件；
事务性操作记录：每一次成功的文件移动，都会生成一条MoveRecord记录，完整保存源路径和目标路径，形成完整的操作事务日志，为后续的撤销功能提供基础；
原子化执行：单文件的移动操作独立处理，单个文件移动失败不会影响整个整理流程，执行完成后统一反馈成功/失败结果，保证流程的稳定性；
权限隔离：所有操作都严格限制在用户选择的目标文件夹内，禁止AI生成的目录路径跳出目标文件夹，杜绝路径注入带来的安全风险。

4. 反馈迭代层：Agent的「闭环」，人机协同的持续优化

这是这个Agent最核心的差异化设计，也是它能真正贴合用户需求的关键——它不是一个“一次性执行”的黑盒工具，而是支持人机协同的反馈迭代闭环，对应代码里的拖拽交互、右键菜单、预览刷新等所有UI交互逻辑。

反馈闭环分为两个核心链路：

执行前的人工校验与反馈：AI生成整理方案后，不会直接执行，而是先在右侧面板做可视化预览。用户可以通过拖拽文件/文件夹修改分类、右键新建目录、移除不需要整理的文件，每一次修改都会实时更新Agent的整理方案，相当于用户给AI的决策做了人工修正，AI会基于用户的修改重新渲染预览，形成「AI生成方案→人工校验修正→方案迭代优化」的闭环；
执行后的结果反馈与回滚：整理执行完成后，Agent会统计执行结果，反馈成功/失败的文件数量；同时基于之前的事务性记录，支持一键撤销整次整理操作，把所有文件移回原位置，形成「执行→结果反馈→回滚修正」的安全闭环。

和传统工具“生成即执行”的模式不同，这个Agent把决策权的最终控制权交给了用户，AI负责做繁琐的分类规划，用户负责做最终的审核和调整，既节省了手动分类的时间，又避免了AI分类不符合预期的问题，真正实现了人机协同的智能整理。

轻量化工程实现

工具基于Python+Tkinter开发，轻量化无依赖，无需安装复杂环境，开箱即用：

UI设计采用浅色简约风格，卡片式布局+蓝色轻点缀，兼顾美观与易用性；
全流程多线程处理：扫描文件、生成整理方案、执行移动操作均在后台线程完成，界面全程无卡顿；
全局语言适配：界面文案与分类目录语言独立控制，支持中英文无缝切换，适配不同用户的使用习惯。

适用场景

个人电脑：整理下载文件夹、桌面、项目目录，告别杂乱；
办公场景：归档会议文件、项目资料，按业务维度分类；
开发场景：整理代码仓库，按模块/功能归类代码文件、配置文件、测试数据。

使用流程（超简单）

选择需要整理的文件夹；
选择整理模式（智能/按类型/按前缀），可补充个性化需求；
点击「分析并生成整理方案」，等待AI生成预览；
调整预览中的分类（拖拽/右键操作）；
确认无误后点击「执行整理」，完成后可随时撤销。

后续规划

目前工具已满足核心整理需求，后续计划围绕Agent能力与使用体验做持续升级：

增加Agent的长期记忆功能，学习用户的分类习惯，下次整理自动复用，越用越贴合你的需求；
新增重复文件检测与清理能力，补充文件去重的专用工具链；
支持自定义分类模板，可保存常用整理规则，一键复用；
优化多智能体协作架构，拆分感知、决策、执行、校验为独立子Agent，进一步提升稳定性与准确性；
支持网络路径/云盘目录整理，覆盖更多使用场景。

写在最后

这款工具的初衷是解决我自己的文件夹杂乱问题——作为程序员，每天要处理大量代码、文档、截图，手动整理太浪费时间，而AI能精准捕捉我的分类习惯，比手动整理更高效。

如果你也饱受文件夹杂乱的困扰，不妨试试这款工具，把整理文件的时间省下来做更重要的事。后续我会开放源码（或打包成可执行文件），感兴趣的朋友可以持续关注～

（附：工具界面截图👇）

左侧为整理前结构，右侧为AI生成的整理预览，高风险文件标注⚠️，支持拖拽调整，界面简洁易操作。