轻量、零外部依赖的现代原生 GUI 本地文件与多媒体批处理瑞士军刀
A lightweight, zero-dependency modern native GUI toolkit for batch media & file management.
-indigo.svg?style=flat-square){kind=icon}
在管理庞大的本地媒体库（如 NAS 共享目录、视频归档库、电子书库、影视刮削元数据）时，传统工具往往存在各种痛点：
- 传统脚本：没有图形界面，每次使用都要修改代码配置路径，稍有不慎改错文件名无法挽回；
- 大型工具软件：动辄几百 MB 的 Electron 臃肿框架，启动缓慢、消耗大量内存，且在网络驱动器权限下频频报错；
- 普通 Tkinter 工具：界面宛如 90 年代 Windows 95，在大分辨率屏幕上字小如蚁、布局挤迫。
MediaForge 为此而生：它采用纯 Python 标准库打造，兼具极简现代审美、安全预演与一键撤销机制与极佳的 2K/4K 大屏适配，拉下代码即开即用！
| 杀手级特性 | 详细描述 |
|---|---|
| 🛡️ 安全第一 (Safety First) | 标配 【🔍 预览 Dry-Run】，正式操作前清晰掌控匹配清单与冲突预警，绝不误伤文件；采用两阶段改名机制，彻底杜绝文件相互覆盖。 |
| ↩ 持久化撤销 (Persistent Undo) | 每次批量操作流水自动落盘到本地 JSON。即使关闭软件或重启电脑，再次打开依然支持一键无损原路回退！ |
| ⚡ 零外部依赖 (Zero Dependency) | 纯基于 Python 标准库开发，无需安装任何第三方依赖包，拉下代码直接运行，绿色无污染。 |
| 🔒 uv 精确锁定 | 项目使用现代 Python 包管理器 uv 进行环境与 Python 3.12.14 版本锁定（uv.lock）。 |
| 🎨 现代原生 UI (Modern Aesthetics) | 摆脱传统 Tkinter 复古灰底粗边框，采用 Tailwind / Linear 级纯白卡片、动态悬浮反馈与深色 VSCode 风格控制台。 |
| 🖥️ 2K / 4K 高分屏优化 | 默认以 1800 × 1200 宽阔视野启动，适配高分屏字体与舒适留白，大屏操作舒展从容。 |
| 🧩 模块化扁平架构 | 摒弃多层无用嵌套，业务算法（core）与 UI 视图彻底解耦，轻松在 3 步内扩展新工具。 |
┌─────────────────────────────────────────────────────────────────────────────┐
│ ⚡ MediaForge Studio │
├─────────────────┬───────────────────────────────────────────────────────────┤
│ 🎬 MP4 批量编号 │ 遍历所选父目录下的每个子文件夹，各自独立从 V001 开始按序重命名 │
│ 📦 视频提取命名 │ 将分散在各子文件夹内的视频改名为“文件夹名.mp4”并提取至父目录下 │
│ 📝 NFO 文本替换 │ 批量查找替换 NFO/文本中的分类标签、网址等，支持 Shift_JIS/UTF-8 │
│ 📚 电子书提取 │ 扫描二级书籍目录(L2)，将深层嵌套(L3+)的 .epub 一键提取扁平化到 L2 │
│ 🧹 空目录清理 │ 递归自底向上智能探测并清理空文件夹，支持识别 Thumbs.db 残留与撤销 │
│ 🌳 目录树生成 │ 生成 ASCII 视觉树（tree /f）或平铺清单，支持深度/后缀过滤与导出 │
│ 🗜️ 子文件夹打包 │ 纯原生零依赖，将父目录下各子文件夹独立打包为同名 zip 归档包 │
└─────────────────┴───────────────────────────────────────────────────────────┘
各工具详细配置与实战案例请参见 👉 内置工具使用指南。
git clone https://github.com/esverde/media-forge.git
cd media-forge本项目锁定了 Python 3.12.14，推荐使用 uv 运行，也支持系统 Python 直接启动：
# 方式 A：使用 uv (推荐，自动遵循 uv.lock 与 3.12.14 环境)
uv run main.py
# 方式 B：使用系统 Python 3.12 直接运行
python main.py也可以作为标准 Python 模块启动：
python -m media_forge或者本地安装后直接作为全局命令调用：
uv pip install -e .
media-forge如果您希望直接打开某一个独立工具窗口，可使用命令行参数：
python main.py --tool mp4 # 直接打开 MP4 批量编号独立窗口
python main.py --tool move # 直接打开 视频提取重命名独立窗口
python main.py --tool nfo # 直接打开 NFO 文本替换独立窗口
python main.py --tool epub # 直接打开 电子书提取扁平化独立窗口
python main.py --tool empty # 直接打开 空文件夹智能清理独立窗口
python main.py --tool tree # 直接打开 目录树生成导出独立窗口
python main.py --tool zip # 直接打开 子文件夹独立打包独立窗口采用清晰直观的扁平包结构（避免多余目录嵌套）：
media-forge/
├── .gitignore # Git 规范忽略配置
├── .python-version # Python 版本锁定 (3.12.14)
├── uv.lock # uv 依赖与环境锁定文件
├── LICENSE # MIT 开源许可证
├── pyproject.toml # PEP 517 / PEP 621 构建配置
├── README.md # 主文档
├── main.py # 快速启动入口
├── docs/ # 详细工程文档
│ ├── architecture.md # 架构分层与设计规范
│ ├── tools_guide.md # 4大工具深度使用手册
│ └── extension_guide.md # 二次开发扩展指南
└── media_forge/ # 核心 Python 模块包
├── __init__.py # 包导出与元数据
├── __main__.py # python -m 入口
├── core/ # 纯业务逻辑算法层（无 UI 依赖）
│ ├── history.py # 通用历史记录与持久化管理器
│ ├── utils.py # 自然排序、后缀解析、编码尝试
│ ├── mp4_renamer.py # MP4 批量编号引擎
│ ├── video_extractor.py # 视频提取引擎
│ ├── nfo_replacer.py # 文本/NFO 查找替换引擎
│ └── epub_extractor.py # 电子书扁平化提取引擎
└── ui/ # 展现层
├── theme.py # 现代色彩系统与设计令牌
├── components.py # 纯原生扁平化现代组件库
├── app.py # 主工作台窗口（侧边栏集成）
└── views/ # 各工具视图
├── base_view.py # 视图通用抽象基类
├── mp4_rename_view.py # MP4 重命名视图
├── video_extract_view.py # 视频提取视图
├── nfo_replace_view.py # NFO 替换视图
└── epub_flatten_view.py # 电子书提取视图
MediaForge 拥有清晰的扩展体系。如果您想新增一个功能（例如：图片压缩 或 字幕重命名），只需 3 步：
- 在
media_forge/core/中编写纯业务逻辑（扫描、执行、回退）； - 在
media_forge/ui/views/中继承BaseView编写现代卡片表单； - 在
media_forge/ui/app.py中注册菜单项与视图。
详细示例代码与说明请参阅 👉 二次开发与扩展指南。
- 🖼️ 图片批处理模块：批量无损压缩、格式转换（WebP/AVIF）、EXIF 拍摄日期重命名；
- 🎬 字幕与音频对齐：视频与字幕文件（.srt/.ass）自动模糊匹配并对齐命名；
- 🔍 重复文件查重工具：基于快速哈希（xxHash/MD5）查重与清理；
- 📦 压缩包批量解压与整理：自动识别分卷、清理残留并扁平化归类。
MediaForge is a modern, lightweight, zero-dependency desktop toolkit for batch file and media management built purely with Python 3.12.14 standard library.
- Zero Dependencies: Pure Python standard library (
tkinter), no third-party packages required. - Reproducible Environment: Python version locked to
3.12.14viauv(uv.lock+.python-version). - Safety First: Full Dry-Run simulation before making changes; two-phase renaming prevents file overwrite conflicts.
- Persistent Undo: Actions are logged to JSON; revert previous operations with one click anytime, even after app restart.
- Modern Native Aesthetics: Card-based flat UI, hover response, dark VSCode-like terminal, and optimized for 2K/4K large displays (
1800x1200). - Clean Architecture: Decoupled core business logic from UI views with zero unnecessary nesting.
本项目基于 MIT 许可证 开源。欢迎提交 Issue 与 Pull Request！