Recursive Unzip Tool

一个面向桌面的递归解压工具。选择目标目录后，先扫描目录中的压缩包，再勾选需要处理的文件并执行解压。

功能

• PySide6 图形界面，采用类似 FreeFileSync 的两阶段工作流。
• 递归扫描目标目录和子目录。
• 支持 .zip、.7z、.tar、.tar.gz、.tgz、.tar.bz2、.tbz2、.tar.xz、.txz。
• 扫描完成后以树形视图显示文件，压缩包默认勾选。
• 文件列表显示压缩包大小和预计解压后大小。
• 主界面可直接选择扫描格式：ZIP、7Z、TAR 系列。
• 不同压缩格式使用不同颜色显示。
• 右键文件可打开、打开文件位置或查看详细属性。
• 可选显示所有文件；普通文件只用于浏览，不会被执行。
• 可配置扫描深度、执行线程数、是否删除源压缩包。
• 执行阶段支持多线程、进度条、取消、强制中断和失败重试。
• 日志会记录扫描、执行、失败原因和建议。
• 默认不会删除源压缩包；只有开启设置并解压成功后才删除。

安装

推荐使用 uv：

uv sync --group dev

uv 默认使用项目目录下的 .venv。如果当前 PowerShell 激活的是其他环境，例如 rut1，uv 仍会优先同步 .venv。

或使用 pip：

python -m pip install -e .

运行

uv run python main.py

也可以直接使用 uv 创建的解释器：

.\.venv\Scripts\python.exe main.py

安装为可编辑包后，也可以运行：

uv run recursive-unzip-tool

使用

1. 点击“浏览”选择目标目录。
2. 在主界面勾选需要扫描的格式：ZIP、7Z、TAR 系列。
3. 点击“设置”按需调整扫描深度、是否显示所有文件、执行线程数和删除源文件选项。
4. 点击“扫描”，等待树形列表生成。
5. 在“执行”列查看 √，点击该列可切换是否执行。
6. 点击“执行”。
7. 如果执行完成后存在失败项，点击“重试失败”只重新处理失败文件。

取消与强制中断

• 取消：请求任务自然停止。已经开始处理的压缩包会尽量完成，未开始的任务会跳过。
• 强制中断：立即终止当前扫描或执行子进程。正在写出的解压内容可能不完整，请检查目标目录后再重试。

右键列表中的文件可以：

• 打开：使用系统默认程序打开文件。
• 打开文件位置：在文件浏览器中定位该文件。
• 属性：查看路径、格式、压缩包大小、解压后大小、修改时间、状态和错误建议。

错误处理

程序会保留原始错误信息，并根据常见异常给出建议：

• 权限问题：检查文件和目录权限，关闭占用文件的程序。
• 文件缺失：重新扫描目录。
• 文件损坏或 CRC 校验失败：重新下载或复制压缩包后重试。
• 不安全路径：程序会阻止解压写出目标目录。
• 不支持格式：当前版本不支持 RAR，请转换为 ZIP、7Z 或 TAR 系列。

技术说明：树状视图

当前文件列表使用 PySide6 的 QTreeWidget 实现，不引入额外的树结构库。

Qt 的树形展开箭头和层级缩进只作用在第 0 列，因此项目把 名称 放在第 0 列，把 执行 放在第 1 列。这样目录和文件名会按真实父子关系自然显示阶梯缩进，例如：

目录1
  文件1.zip
  子目录2
    文件2-3.7z
    文件2-4.tar.gz
  文件3.zip
目录2
  文件4.zip
文件0.zip

实现要点：

• 列顺序固定为：名称、执行、相对路径、格式、压缩包大小、解压后大小、状态、错误/建议。
• recursive_unzip_tool/gui.py 中使用 COL_NAME = 0 和 COL_EXECUTE = 1 等列索引常量，避免后续维护时把树列改错。
• 扫描结果按 ArchiveItem.relative_path.parts 拆分路径；中间目录会创建为 QTreeWidgetItem 目录节点，文件节点挂到对应目录节点下面。
• 目录节点只显示真实目录名，不额外添加 [目录] 前缀。
• 文件节点的 名称 列显示文件名，执行 列显示 √ 或空白。
• 点击逻辑只响应 执行 列；点击 名称 列只选中行，不切换是否执行。
• 右键菜单和属性窗口通过 COL_NAME 列保存的 UserRole 路径读取目标文件或目录。
• tree.setIndentation(32) 用来加大层级缩进，使多层目录更容易辨认。

本轮暂不使用 treelib。原因是当前需求主要是 GUI 展示层缩进问题，QTreeWidget 已经能表达父子层级；后续如果需要搜索、复杂过滤、批量折叠、虚拟列表或更复杂的树数据操作，再考虑增加专门的数据层或第三方库。

开发与测试

uv sync --group dev
uv run pytest

如果默认临时目录有权限问题，可以指定测试临时目录：

uv run pytest --basetemp C:\tmp\recursive-unzip-tool-pytest -o cache_dir=C:\tmp\recursive-unzip-tool-pytest-cache