工具箱 (ToolBox)

离线 · 高效 · 美观 的桌面工具集合

功能特色 · 截图预览 · 快速开始 · 使用指南 · 插件开发 · 用户手册 · 架构图

简体中文 | English

---

功能特色

图标	工具	说明
🗜️	图片压缩	批量压缩 JPG/PNG/WebP，可调质量，支持格式互转
🔁	图片格式转换	批量转换 JPEG/PNG/WebP/BMP/TIFF/GIF 六种格式
🧩	图片拼接	多张图片横向或纵向拼成一张，支持对齐设置
🖨️	图片转PDF	多张图片合并为一个 PDF，或每张图片生成独立 PDF；可设置页面大小、压缩与 JPEG 质量
🔍	图片缩放	批量调整尺寸，支持按比例/宽度/高度缩放
📚	PDF合并	多个 PDF 合并为一个，支持上移/下移调整顺序
✂️	PDF拆分	拆分 PDF 为图片或单页 PDF，支持自定义页数
🧹	文件去重	按文件大小预筛选 + 内容 Hash 查找重复文件，支持规则排序预览
🗑️	空文件夹清理	递归查找并删除完全为空的文件夹，支持多层空目录

通用特性

• 🌙 深色/浅色主题 — 一键切换，自动记忆偏好
• 🌐 中英双语界面 — 按系统语言自动选择，可随时在设置页切换
• 🖱️ 拖拽支持 — 多数工具支持直接拖拽文件到列表
• 📊 文件列表 — 统一的交互体验，支持添加/移除/排序/清空
• 📈 进度显示 — 实时显示处理进度和状态
• 🔌 完全离线 — 所有处理在本地完成，不上传任何数据
• 🧩 插件扩展 — 放入 plugins/ 目录并登记到 config.py 的 PLUGIN_MODULES 即可自动加载
• ↔️ 侧边栏折叠 — 点击折叠按钮或 Ctrl+B 快捷键收起/展开侧边栏
• 🧭 导航栏管理 — 在设置页拖拽调整工具顺序、勾选隐藏，侧边栏与首页卡片即时同步
• ↩️ 恢复默认设置 — 一键将语言、主题、窗口布局等恢复为默认值

---

截图预览

功能	截图
首页
图片压缩
图片格式转换
图片拼接
图片转PDF
图片缩放
PDF合并
PDF拆分
文件去重
空文件夹清理
设置

---

快速开始

1. 安装依赖

pip install -r requirements.txt

依赖包说明：

包	用途
PyQt6	GUI 框架
Pillow (PIL)	图片处理
img2pdf	PDF 转换
PyMuPDF (fitz)	PDF 转换
send2trash	删除文件到系统回收站（文件去重使用）
pyinstaller	打包为可执行文件（见「打包发布」）

2. 运行程序

python main.py

3. 打包为 EXE（Windows）

# 推荐使用 spec 文件打包（已包含所有必要模块）
pyinstaller toolbox.spec

# 使用 UPX 压缩减小体积
pyinstaller --upx-dir=/path/to/upx toolbox.spec

⚠️ 注意：必须使用 toolbox.spec 进行打包，直接运行 pyinstaller main.py 会导致动态加载的插件模块缺失。

---

使用指南

图片压缩

1. 点击左侧「图片压缩」
2. 添加图片（支持多选和拖拽）
3. 选择输出格式（保持原格式 / JPG / PNG / WebP）
4. 调整压缩质量滑块（建议 70~85%）
5. 点击「开始压缩」

图片格式转换

1. 点击左侧「图片格式转换」
2. 添加图片，选择目标格式（JPEG / PNG / WebP / BMP / TIFF / GIF）
3. 选择输出目录（默认保存到原图目录）
4. 点击「开始转换」

图片拼接

1. 点击左侧「图片拼接」
2. 添加图片（至少 2 张），调整顺序
3. 选择拼接方向：横向 / 纵向
4. 选择对齐方式（顶部/左侧、居中、底部/右侧、智能缩放）与背景颜色
5. 选择输出文件路径
6. 点击「开始拼接」

图片转PDF

1. 点击左侧「图片转PDF」
2. 添加图片（列表顺序即 PDF 顺序，可用上移/下移或排序按钮调整）
3. 选择页面大小（自动适应 / A4 / A3 / 原图尺寸 / 智能缩放）
4. 勾选「启用压缩」并调整 JPEG 质量（1–100%）
5. 设置「是否合并」：勾选时多图合并为一个 PDF（需选择输出文件）；不勾选时为每张图片生成独立 PDF（输出路径作为目录）
6. 选择输出路径
7. 点击「开始转换」

图片缩放

1. 点击左侧「图片缩放」
2. 添加图片，选择缩放方式（百分比 / 宽度 / 高度）
3. 设置缩放参数，勾选「保持宽高比」
4. 点击「开始缩放」

PDF合并

1. 点击左侧「PDF合并」
2. 添加 PDF 文件（列表顺序即合并顺序，可用上移/下移或排序按钮调整）
3. 选择输出文件路径
4. 点击「开始合并」

PDF拆分

1. 点击左侧「PDF拆分」
2. 添加一个 PDF 文件
3. 选择输出格式（单页 PDF / 图片）
4. 设置拆分页数（单页 PDF 模式）或图片格式与清晰度滑块（图片模式）
5. 点击「开始拆分」

文件去重

1. 点击左侧「文件去重」
2. 点击「浏览」选择要扫描的文件夹（或将文件夹拖入输入框），自动开始扫描（三级过滤：文件大小→快速Hash→完整Hash，大幅提速）
3. 选择去重规则，点击「按规则排序」预览保留/删除标记
4. 确认无误后勾选要删除的分组（可选：勾选「删除到回收站」，被删文件进入系统回收站，便于恢复）
5. 点击「删除重复文件」并确认

空文件夹清理

1. 点击左侧「空文件夹清理」
2. 选择要清理的根目录（或将文件夹拖入输入框）
3. 点击「开始扫描」，递归查找完全为空的文件夹（只含空子目录的目录树也算空）
4. 在结果列表中勾选要删除的目录（支持「全选」/「取消全选」）
5. 点击「删除选中目录」并确认

💡 扫描根目录始终保留，删除只使用 os.rmdir，绝不会删除文件；符号链接/junction 会被跳过。

---

插件开发

工具箱支持插件扩展。将 Python 文件放入 plugins/ 目录后，还需在 config.py 的 PLUGIN_MODULES 中登记，启动时通过 importlib 自动导入并注册（仅放入目录、未登记不会被加载）。

创建插件

新建 plugins/my_tool.py：

# -*- encoding: utf-8 -*-
"""
我的工具插件
"""
from toolbox import ToolPlugin, Card, AnimatedButton, Theme
from PyQt6.QtWidgets import QWidget, QVBoxLayout, QLabel

class MyTool(ToolPlugin):
    name = "我的工具"
    description = "工具描述"
    icon = "🔧"

    def create_ui(self) -> QWidget:
        """创建工具界面"""
        widget = QWidget()
        layout = QVBoxLayout(widget)
        layout.addWidget(QLabel("Hello, World!"))
        return widget

    def update_theme(self, theme):
        """响应主题切换（基类已有空实现；插件有自定义样式时必须覆写）"""
        pass

插件配置

在 config.py 的 PLUGIN_MODULES 列表中添加配置：

PLUGIN_MODULES = [
    # ... 其他插件 ...
    {
        "id": "my_tool",
        "name": "我的工具",
        "icon": "🔧",
        "description": "工具描述",
        "order": 30,  # 排序权重，越小越靠前
        "module": "plugins.my_tool",
        "class": "MyTool",
    },
]

现有插件

文件	类名	功能
plugins/image_compressor.py	ImageCompressor	图片压缩
plugins/image_format_converter.py	FormatConverter	图片格式转换
plugins/image_stitcher.py	ImageStitcher	图片拼接
plugins/image_to_pdf.py	ImageToPDF	图片转 PDF
plugins/image_scaler.py	ImageScaler	图片缩放
plugins/pdf_merger.py	PDFMerger	PDF 合并
plugins/pdf_splitter.py	PDFSplitter	PDF 拆分
plugins/file_deduplicator.py	FileDeduplicator	文件去重
plugins/empty_folder_cleaner.py	EmptyFolderCleaner	空文件夹清理

---

配置系统

源码中的静态配置集中在 config.py 文件中：

配置项	说明
APP_NAME, APP_VERSION	应用名称和版本号
APP_DESCRIPTION, APP_COPYRIGHT	应用描述和版权信息
APP_WEBSITE_URL, APP_UPDATE_URL, APP_ISSUE_URL	官网、检查更新与问题反馈链接
PLUGIN_MODULES	插件列表（id、图标、描述、排序、模块与类名）
UI_CONFIG	窗口最小/最大尺寸、侧边栏宽度、圆角等 UI 设置
SPACING_SMALL, SPACING_MEDIUM	通用间距常量
FONT_SIZE_*, FONT_WEIGHT_*, TITLE_STYLES	字体大小、粗细与标题样式

界面显示文本（窗口标题、插件名称/描述、状态消息等）位于 i18n/zh_CN.json 与 i18n/en.json，由 t() 在运行时读取；修改 PLUGIN_MODULES 中的 name/description 不会改变已翻译的显示文本，需同步编辑 i18n 词典。

修改 config.py 可调整版本号、插件图标与排序、加载配置、窗口尺寸等；界面文案则需同步修改 i18n/*.json。

运行时配置（config.ini）

应用运行时还会读写 config.ini 保存用户设置：

项目	说明
默认位置	Windows：%LOCALAPPDATA%\Toolbox\config.ini；macOS：~/Library/Application Support/Toolbox/config.ini
便携模式	程序（源码运行时为项目根目录）下存在可写的 portable.flag 时，配置存放在同目录的 config.ini
保存内容	[setting] 界面语言与主题、[setting.window] 窗口几何与状态、[setting.nav] 导航顺序与工具可见性、[plugin.<id>] 各插件的设置项（压缩质量、缩放方式、页面大小等）、[setting.meta] 配置版本
首次启动	文件不存在时自动生成并写入默认值；界面语言按系统语言初始化（中文 → zh_CN，其余 → en），首次自动设置后会弹窗提示，之后以用户在设置页的选择为准
旧版迁移	从旧版 QSettings 注册表导入主题与窗口几何/状态，仅在 INI 尚无对应值时导入，且不删除注册表数据
写入安全	保存前备份为 config.ini.bak，通过临时文件 + 原子替换写入；文件缺失或损坏时回退默认值并打印错误；配置目录不可写时设置仅在本次运行生效

该文件由 common/app_settings.py 中的 AppSettings 统一管理，通常无需手动编辑。

---

打包发布

环境要求

• Python 3.10+（PyQt6/PyMuPDF 依赖要求）
• Windows 系统（其他平台可修改 spec 后尝试，macOS 可用 build_macos.py）

打包步骤

# 1. 生成版本信息文件
python generate_version_info.py

# 2. 验证打包依赖
python verify_packaging.py

# 3. 打包为 EXE
pyinstaller toolbox.spec

打包后的 EXE 文件位于 dist/ 目录下。

---

TODO

已完成 ✅

• 图片压缩（批量，可调质量）
• 图片格式转换（JPEG/PNG/WebP/BMP/TIFF/GIF）
• 图片拼接（横向/纵向）
• 图片转 PDF（合并或每图独立）
• 图片缩放（百分比/宽度/高度）
• PDF 合并（多文件合并）
• PDF 拆分（拆成图片或单页 PDF）
• 文件去重（按内容 Hash）
• 空文件夹清理（递归删除空目录）
• 深色/浅色主题切换
• 中英双语界面
• 导航栏排序与隐藏
• 恢复默认设置
• 插件自动导入与注册（需登记到 PLUGIN_MODULES）

计划中 🔨

• 图片批量水印（文字或图片水印）
• 图片批量旋转/翻转
• 图片批量裁剪
• 文件批量重命名（正则、序号、日期规则）

待优化功能

暂无

---

欢迎提交 PR 贡献新插件或功能！

---

许可证

本项目为开源项目，使用MIT协议，欢迎自由使用和贡献。

Star History

Visitors

---

工具箱 — 让文件处理更简单 🚀