300 行 Python 文件分类脚本：GUI / 右键 / 热键 / 定时，一行交互代码都没写

脚本清单：main.py 共 307 行，配套 bm-scripts-box-rc.toml 配置文件 57 行，仅此两份。

它的能力看起来和代码体量很不匹配：

• 友好的GUI交互窗口
• 快捷键执行文件整理
• 右键菜单快速执行文件整理
• 支持定时执行文件整理

按照传统开发思路，单单交互界面就要几百行；右键菜单需要操作注册表；全局热键要调用 Win32 API；定时任务要对接系统计划任务或者维护常驻后台进程。四项功能从头手写，保守估算两千行起步。

但这四项，我一行业务代码都没有写。

我只聚焦一件核心逻辑：接收文件夹路径，按照预设规则对文件分组、移动。这部分核心代码大约 130 行。
界面、右键、热键、定时调度，全部由不忙脚本盒子读取 TOML 配置自动生成。下面拆解整套实现思路，以及这次选择不自己开发外壳的原因。

脚本本身只负责：文件分类逻辑

先说明：外围能力由盒子提供，但分类规则全部是自研实现。一共 7 种分类模式：

• 按后缀名：.jpg、.pdf 等后缀各自独立建文件夹
• 按文件类型：归集为文档、视频、音频、图像、压缩包、执行脚本、代码、设计文件、其他，共 9 大类（日常最常用）
• 按关键词：仅匹配带指定关键词的文件，其余文件保持不动
• 按创建时间 / 修改时间：自动生成 2026年/03月 两级时间目录
• 按文件大小：分为 4 档：＜10MB、10MB~100MB、100MB~1GB、＞1GB
• 按文件数量：每 N 个文件拆分一个目录，适合大批量图片分片归档

配图：整理前后目录对比截图，左侧是四百多个杂乱文件，右侧自动分成 9 个类型文件夹

使用方式

脚本不是独立 EXE，交互入口、触发方式都依托不忙脚本盒子：

1. 访问 bm-box.cn 下载安装（Windows10 及以上 64 位）
2. 打开盒子，进入脚本市场，搜索「文件分类」安装
3. 打开脚本卡片，选择目标文件夹、选定分类规则，点击执行

Python 运行环境由盒子托管；脚本仅使用 Python 标准库，版本要求≥3.8，无需额外 pip 安装依赖。
右键菜单、全局快捷键、定时任务这三种启动方式，同样在盒子内配置开启。

四项能力，靠一份 TOML 配置声明实现

脚本和交互层完全解耦。所有界面控件、触发入口，都写在配置文件里，盒子读取配置自动生成能力。

1. 参数弹窗面板

没有手动绘制任何 UI 控件。在 TOML 中声明输入项、参数、联动显隐规则即可：

[[bmscriptsbox.inputs]]
name = "target_dir_path"
label = "目标文件夹（可多选）"
type = "list"
pick = "folders"

[[bmscriptsbox.params]]
name = "mode"
label = "分类方式"
type = "str"
default = "extension"
choices = ["extension", "type", "keywords", "creation_time",
           "modification_time", "size", "quantity"]
choice_labels = { extension = "按后缀名", type = "按文件类型", keywords = "按关键词" }

[[bmscriptsbox.params]]
name = "keywords"
label = "关键词"
type = "str"
when = { field = "mode", eq = "keywords" }

• pick = "folders"：直接渲染文件夹多选器，不用手动实现文件选择弹窗
• when 条件联动：选中「按关键词」才展示关键词输入框；选中「按数量」，才出现每组文件数量输入框

如果自己开发，文件夹多选、表单校验、选项联动显隐、状态保存，每一块都要写大量前端 / UI 代码。

2. 资源管理器右键菜单

[bmscriptsbox.triggers.context_menu]
enabled = true
targets = ['background', 'directory']

• background：文件夹空白处右键
• directory：选中文件夹后右键

菜单项由盒子自动写入、管理。点击菜单时，盒子自动把选中目录路径传给脚本。
不用操作注册表，不用处理路径空格、管理员权限不足、卸载残留清理等一堆坑。

3. 全局快捷键

[bmscriptsbox.triggers.shortcut]
enabled = true
input_type = "active"

热键在盒子内自定义绑定（例如 Ctrl+Alt+F）。
input_type = "active"：按下快捷键时，自动读取当前资源管理器激活窗口的文件夹路径。切到下载文件夹按快捷键，就整理下载；切到桌面，就整理桌面。
脚本完全无感，只接收路径入参，不需要编写热键注册、消息循环逻辑。

4. 定时自动任务

[bmscriptsbox.schedule]
enabled = true

调度能力由盒子内置调度器负责，到点自动拉起脚本。我配置的是每天 19:00 自动整理下载文件夹。

亮点：定时任务复用同一套参数表单。目标目录、分类规则和手动执行配置完全一致，不需要单独开发一套自动执行参数、增加 --auto 命令分支。之前自研定时版本，就是因为两套参数逻辑，代码越维护越混乱。

脚本与盒子的通信规则

盒子启动脚本时，向命令行传入一个 JSON 文件路径。脚本读取 JSON 拿到上下文，执行完成直接退出。无 SDK、无基类依赖，脚本单独拷贝出来也可以独立运行。

JSON 示例：

{
  "environment": { "invoke_mode": "scheduled" },
  "data":       { "target_dir_path": ["C:/Users/me/Downloads"] },
  "params":     { "mode": "extension", "keywords": "", "per_folder": 100 }
}

• data：目标文件夹列表
• params：分类配置参数
• environment.invoke_mode：调用来源标识：manual（手动点击 / 右键 / 快捷键）、scheduled（定时）、node（被其他脚本联动调用）

脚本里只有一段简短判断适配不同调用场景：

if (env or {}).get("invoke_mode") in ("scheduled", "node"):
    print("已退出", flush=True)
    sys.exit(0)

手动执行时，结尾有 5 秒倒计时等待用户查看日志；无人值守的定时 / 联动调用，直接退出，避免阻塞调度队列。
这个边界场景很容易被忽略，如果全套自研，需要自己设计上下文参数、保证所有调用链路都正确传递标识。

如果全部从零手写，工作量对比

表格

四项叠加，很容易从「一个周末完工」变成拖两周。

不是写不出来。前两版我就是自己写的：第一版纯命令行，输路径很麻烦；第二版上了 Tkinter 界面，但每次改交互需求都要调整 UI 布局，打包之后还要应对杀毒软件误报。两次迭代都消耗大量精力在和业务无关的外壳代码上。

这次换思路：核心分类逻辑自研，通用桌面交互外壳交给盒子。写完即可交付分享给其他人使用。

安全设计原则

文件整理工具一旦出错，代价是用户文件，所以做了大量保守限制：

• 仅执行移动 shutil.move，代码内没有任何删除逻辑
• 重名自动后缀递增，永远不覆盖原有文件
• 关键词模式：不匹配关键词的文件完全不改动
• 只处理当前一级文件，不递归遍历子文件夹，防止误操作根目录造成大范围改动
• 单个文件移动失败不中断整体流程，单独记录失败文件与原因
• 先一次性读取全部待处理文件列表，再执行移动，避免遍历过程中目录结构变化导致漏处理

常见疑问

Q：脚本会删除文件吗？
A：不会，只有移动操作，没有删除代码。

Q：支持 Win11 吗？Mac 呢？
A：Win10 / Win11（64 位）可用；暂不支持 Mac。

Q：需要手动安装 Python 环境吗？
A：盒子自带环境，开箱即用；单独运行源码需要 Python3.8+。

Q：定时任务需要额外配置吗？
A：参数表单和手动执行一致，配置一次保存即可。

Q：怎么获取这个脚本？
A：安装不忙脚本盒子，在脚本市场搜索「文件分类」，当前版本 v1.4.0。

收尾

回到最开始的问题：307 行代码到底都写了什么？
130 行分类核心逻辑，其余是参数解析、日志、异常处理和注释。GUI、右键、热键、定时，全部没有手写。

这套体验，来自 不忙脚本盒子。
它提供了一套面向 Windows 脚本的声明式底座：只需一份 TOML 配置，自动生成可视化表单、右键菜单、全局快捷键、定时任务，同时托管 Python 运行环境，简化脚本分发与分享。

不用再重复造桌面交互轮子，开发者聚焦业务逻辑即可。普通用户也无需接触命令行和依赖，开箱即用。
如果你也想低成本开发、分享 Windows 自动化脚本，可以试试不忙脚本盒子。

盒子GitHub仓库：/bm-qihengzhi/bmscriptsbox