File-SorterAgent：基于强化学习的智能文件自动整理系统

一个结合深度强化学习与规则引擎的文件自动分类工具，支持预览模式、冲突检测、重复文件识别和可撤销操作，为本地文件管理提供智能化解决方案。

• 原作者/维护者：kai9987kai
• 来源平台：github
• 原始标题：File-SorterAgent
• 原始链接：https://github.com/kai9987kai/File-SorterAgent
• 来源发布时间/更新时间：2026-06-07T10:15:43Z

原作者与来源

• 原作者/维护者：kai9987kai
• 来源平台：github
• 原始标题：File-SorterAgent
• 原始链接：https://github.com/kai9987kai/File-SorterAgent
• 来源发布时间/更新时间：2026-06-07T10:15:43Z 原作者与来源\n\n- 原作者/维护者：kai9987kai\n- 来源平台：GitHub\n- 原始标题：File-SorterAgent\n- 原始链接：https://github.com/kai9987kai/File-SorterAgent\n- 发布时间：2026年6月7日\n\n---\n\n项目概述\n\nFile-SorterAgent 是一个跨平台的智能文件整理工具，支持 Windows、macOS 和 Linux 系统。该项目最初采用 TensorFlow 实现了一个基于 Dueling DQN 的强化学习原型（保留在 beta.py 中），但在实际生产版本中转向了一种更可靠的混合方案：结合神经网络分类能力与确定性规则引擎，既保留了智能化的文件识别能力，又确保了操作的可预测性和安全性。\n\n这个项目的核心设计理念是"安全优先"——所有文件移动操作默认处于预览模式，只有在用户明确确认后才会执行，并且每一次操作都可以被完整撤销。\n\n---\n\n核心功能与技术实现\n\n双重架构设计\n\n项目包含两个主要组件：\n\n1. 生产版本（Main.py）：基于规则引擎的确定性分类器，使用文件名扩展名、内容关键词匹配和可配置的分类规则，确保每次运行结果一致且可预测。\n\n2. 研究原型（beta.py）：使用 Dueling DQN 深度强化学习网络，通过奖励机制学习文件分类策略。该版本需要 NumPy、TensorFlow 和 python-docx 依赖，目前仅建议用于实验环境。\n\n生产版本之所以取代纯强化学习方案，是因为未训练的神经网络会做出随机的文件放置决策，这在实际文件管理场景中是不可接受的。\n\n内置分类体系\n\n系统预定义了十个文件类别，覆盖常见的文档、媒体、代码和数据类型：\n\n- 文档类：PDF、Word、TXT 等办公文档\n- 图片类：JPG、PNG、GIF、WebP 等图像格式\n- 音频类：MP3、WAV、FLAC 等音乐文件\n- 视频类：MP4、AVI、MKV 等视频格式\n- 代码类：Python、JavaScript、HTML 等源代码文件\n- 数据类：CSV、JSON、XML 等结构化数据\n- 应用程序：EXE、DMG、AppImage 等可执行文件\n- 设计文件：PSD、AI、Sketch 等设计源文件\n- 字体文件：TTF、OTF、WOFF 等字体资源\n- 压缩包：ZIP、RAR、7Z 等归档文件\n\n智能内容识别\n\n系统不仅依赖文件扩展名，还可以深入分析文件内容：\n\n- 文本文件扫描：读取文本和 DOCX 文件内容，识别工作相关关键词（如"发票"、"合同"、"预算"）或个人内容特征\n- 关键词规则优先：内容匹配的规则优先级高于扩展名规则，确保重要文档被正确归类\n- 可配置规则引擎：用户可通过 JSON 配置文件自定义分类规则和关键词匹配策略\n\n安全机制与数据保护\n\n预览模式\n默认运行模式下，系统仅生成整理计划而不实际移动文件。用户可以在执行前完整审查所有拟议操作：\n\nbash\npython Main.py \"$HOME/Downloads\" 预览模式\npython Main.py \"$HOME/Downloads\" --execute 实际执行\n\n\n冲突处理与重复检测\n\n- 智能重命名：当目标位置存在同名文件时，自动采用 filename (1).ext 格式重命名\n- SHA-256 重复检测：计算文件哈希值识别真正重复的内容，支持跳过、重命名或单独存放三种处理策略\n- 防覆盖保护：撤销操作永远不会覆盖现有文件，如果原始路径已被占用，则报告错误并保持现状\n\n操作历史与撤销\n\n每次执行的整理操作都会被记录到 history.jsonl 文件中，用户可以：\n\n- 查看历史操作记录：--history\n- 撤销最近一次操作：--undo\n- 撤销指定操作：--undo <run-id>\n\n高级功能\n\n时间分组\n支持按年份或年月对整理后的文件进行二级分组，便于按时间轴管理大型文件库：\n\nbash\npython Main.py \"$HOME/Downloads\" --group-by month --execute\n\n\n递归整理与目标目录\n可以递归处理子目录中的文件，并支持将整理结果输出到独立的目录结构，保持源目录原貌：\n\nbash\npython Main.py \"D:/Inbox\" --destination \"D:/Organized\" --recursive --execute\n\n\n文件年龄过滤\n支持设置最小文件年龄（秒），避免处理正在下载或近期可能仍在使用的文件：\n\nbash\npython Main.py \"$HOME/Downloads\" --min-age 300 --execute 跳过5分钟内修改的文件\n\n\nJSON 输出与机器可读\n支持生成结构化的 JSON 输出，便于与其他自动化工具集成：\n\nbash\npython Main.py \"$HOME/Downloads\" --json\n\n\n---\n\n配置与扩展\n\n自定义配置文件\n\n用户可以生成完整的可编辑配置文件：\n\nbash\npython Main.py --init-config sorter-config.json\n\n\n配置示例：\n\njson\n{\n \"categories\": {\n \"Design\": [\".fig\", \".sketch\", \".xd\"],\n \"Books\": [\".epub\", \".mobi\"]\n },\n \"keyword_rules\": {\n \"Finance\": [\"invoice\", \"statement\", \"budget\"]\n },\n \"ignore_patterns\": [\"*.tmp\", \"keep/**\"],\n \"content_read_limit\": 256000\n}\n\n\n配置值与内置规则合并，重用类别名称会替换该分类的值。类别名称不能包含路径分隔符，关键词规则优先级高于扩展名规则。\n\n---\n\n技术亮点与工程实践\n\n确定性优先的设计哲学\n\n在 AI/ML 项目普遍追求"智能化"的潮流中，File-SorterAgent 展现了务实的工程思维：当任务涉及用户数据安全和可预测性时，确定性规则比概率性模型更可靠。生产版本完全移除了对 TensorFlow 的依赖，仅使用 Python 标准库，降低了部署复杂度和运行时开销。\n\n防御性编程\n\n代码体现了多层防御性设计：\n\n- 输入验证：路径和配置参数的严格校验\n- 异常隔离：单个文件处理失败不会中断整个批处理流程\n- 原子性操作：历史记录先于文件操作写入，确保即使程序崩溃也能安全恢复\n- 边界情况处理：特殊字符文件名、符号链接、权限问题等都有专门处理\n\n跨平台兼容\n\n通过使用 pathlib 和抽象的路径操作，代码在 Windows、macOS 和 Linux 上保持一致行为，正确处理各平台的文件命名规则和路径分隔符。\n\n---\n\n应用场景与实用价值\n\n个人数字资产管理\n\n对于长期积累大量下载文件、文档、照片的用户，File-SorterAgent 提供了一种低风险的整理方案。预览模式允许在真正改动文件系统前充分评估整理效果，撤销机制则为误操作提供了安全网。\n\n自动化工作流集成\n\nJSON 输出模式和命令行界面使其易于集成到更大的自动化流程中，例如：\n\n- 定期清理下载文件夹的定时任务\n- 邮件附件自动分类\n- 云同步前的本地预处理\n- 数据归档流水线\n\n企业文档管理\n\n通过自定义关键词规则和类别配置，可以适配企业特定的文档分类需求，如按项目、部门或文档类型进行自动化归档。\n\n---\n\n项目现状与使用建议\n\nFile-SorterAgent 目前处于活跃开发状态，代码结构清晰，测试覆盖完整（python -m unittest discover -s tests -v）。项目遵循良好的开源实践，包含完整的 README、LICENSE 和 .gitignore 配置。\n\n对于希望尝试的用户，建议：\n\n1. 从预览模式开始：始终先不带 --execute 运行，审查整理计划\n2. 在测试目录验证：首次使用先在副本数据上测试\n3. 利用配置定制：根据实际需求调整分类规则和关键词\n4. 保留历史记录：定期备份 .file-sorter/history.jsonl 以便必要时恢复\n\n---\n\n总结\n\nFile-SorterAgent 是一个兼具技术深度和实用价值的开源项目。它展示了如何将机器学习概念与实际工程需求相结合——不是盲目追求技术先进性，而是在理解任务本质后选择最合适的实现方案。对于希望构建类似自动化工具的开发者和希望改善文件管理效率的用户，该项目都提供了有价值的参考和可直接使用的解决方案。