UCCZip 项目文档

1. 项目基础信息

1.1 核心功能一览

• 多格式归档：ZIP、RAR、7z、TAR、GZIP、Unix .Z 等格式的浏览、压缩、解压、测试
• 加密支持：ZIP 传统 ZipCrypto 与 WinZip AES-256 加密/解密
• 双视图文件管理：文件系统树 + 压缩包内虚拟目录浏览，支持拖放、查找、部分解压
• 智能解压：根据压缩包顶层结构自动选择解压到当前目录或同名子文件夹
• Shell 扩展：UCCZipShell.dll 提供经典右键菜单与 Win11 IExplorerCommand 主菜单
• 自解压包 (SFX)：将文件夹打包为独立 .exe，内置静态链接的 UCCZipSfxStub.exe
• 归档库 (Archive Depot)：基于 SQLite 的压缩包样本入库、检索与管理
• ZIP 密码破解：字典、掩码、字符集暴力、已知明文 (KPA)、CRC32 短明文枚举等
• 系统集成：文件关联、开机自启、系统托盘、单实例、Mark-of-the-Web (MOTW) 标记
• 国际化：中文（默认）/ 英文界面切换

1.2 归档格式支持矩阵

读取（解压 / 列表 / 测试）

创建（压缩）

2. 环境与安装

2.0 依赖环境要求

推荐 Qt 安装路径（本项目开发环境）

C:\Qt515\5.15.2\mingw81_64\     # Qt 库与 qmake
C:\Qt515\Tools\mingw810_64\     # MinGW 工具链

可选外部工具

• 7z.exe — 非常规 .7z 归档兜底（正常使用不需要）
• UnRAR.exe — RAR 兜底（内置 UnRAR 为默认）
• Rar.exe — 创建 RAR 归档时必需
• bkcrack.exe — KPA 攻击可选外部工具（亦内置 bkcrack 静态库）

2.1 本地编译构建

方式 A：Qt Creator（推荐）

1. 用 Qt Creator 打开 UCCZip.pro
2. 选择套件：Desktop Qt 5.15.2 MinGW 64-bit
3. 构建配置选 Release 或 Debug
4. 点击构建 — qmake 会自动串联编译：
   • 应用图标 (tools/generate_app_icon.ps1)
   • Shell 扩展 DLL (shell/UCCZipShell/)
   • SFX 存根 (sfx/UCCZipSfxStub/，始终 Release 静态链接)
   • 主程序 UCCZip.exe

方式 B：命令行

# 设置 PATH
$env:PATH = "C:\Qt515\Tools\mingw810_64\bin;C:\Qt515\5.15.2\mingw81_64\bin;" + $env:PATH

# 创建并进入构建目录
cd d:\Temp2\UCCZip
mkdir build\Desktop_Qt_5_15_2_MinGW_64_bit-release -Force
cd build\Desktop_Qt_5_15_2_MinGW_64_bit-release

# 生成 Makefile 并编译
qmake ..\..\UCCZip.pro -spec win32-g++ "CONFIG+=release"
mingw32-make -j4

构建成功后，Release 产物位于：

build\Desktop_Qt_5_15_2_MinGW_64_bit-release\release\
  ├── UCCZip.exe
  ├── UCCZipShell.dll
  ├── UCCZipSfxStub.exe
  ├── libwinpthread-1.dll
  ├── images\
  ├── Assets\
  ├── AppxManifest.xml
  ├── tools\
  └── plugins\sqldrivers\qsqlite.dll

2.2 部署与安装

一键部署到 C:\UCCRelease

powershell -ExecutionPolicy Bypass -File "d:\Temp2\UCCZip\tools\deploy_uccrelease.ps1" `
  -BuildReleaseDir "d:\Temp2\UCCZip\build\Desktop_Qt_5_15_2_MinGW_64_bit-release\release" `
  -DestDir "C:\UCCRelease"

部署脚本自动完成：

1. 复制核心二进制与资源到目标目录
2. 运行 windeployqt 收集 Qt / MinGW 运行时
3. 复制 SQLite 驱动 (qsqlite.dll)
4. 复制 Win11 稀疏包清单与图标资源
5. 复制 password_list.txt 密码字典（若存在）
6. 执行 UCCZip.exe --shell-register 注册右键菜单与稀疏包

手动安装步骤

1. 将完整发布目录（含上述所有文件）复制到目标位置，例如 C:\UCCRelease
2. 以该目录为工作目录，运行：UCCZip.exe --shell-register
3. （可选）在设置中启用文件关联、开机自启、系统托盘
4. 首次启动会自动尝试注册 Win11 稀疏包；也可手动执行 tools\register_win11_sparse_package.ps1

卸载 Shell 集成

UCCZip.exe --shell-unregister

3. 使用指南

3.1 主界面操作

主窗口 (MainWindow) 提供双模式视图：

• 文件系统视图：浏览本地目录，双击压缩包进入归档视图
• 归档视图：在压缩包内导航子目录，支持地址栏、后退/前进、上级目录

工具栏 / 菜单核心操作

设置项（选项对话框）

• 默认解压位置：压缩包旁 / 同名子文件夹 / 自定义目录
• 压缩默认：格式、压缩级别、AES 加密、覆盖策略
• 智能解压开关、解压后打开文件夹、MOTW 标记模式
• 多线程解压线程数（LZMA2 / .xz，0 = 自动）
• Shell 右键菜单集成、文件关联
• 单实例模式、系统托盘、关闭到托盘、开机自启
• 界面语言：中文 / English

3.2 Shell 右键菜单

通过 UCCZipShell.dll 与注册表/IExplorerCommand 集成到 Windows 资源管理器。支持 Win10 经典菜单与 Win11 一级上下文菜单（稀疏包 AppxManifest.xml）。

可用 Shell 命令（动词）

多选压缩时，资源管理器会为每个选中项启动独立进程；UCCZip 通过 --shell-coalesce 机制合并为一次压缩操作。

3.3 命令行参数

维护参数

UCCZip.exe --shell-register      # 注册 Shell 扩展与稀疏包
UCCZip.exe --shell-unregister    # 卸载 Shell 扩展

Shell 调用格式

UCCZip.exe --shell <verb> ["path1" "path2" ...]
UCCZip.exe --shell compress-quick --shell-coalesce "D:\file1.txt"
UCCZip.exe --shell archive-depot-manager

开发与测试参数

直接打开文件

UCCZip.exe "D:\archive.zip"          # 打开指定压缩包
UCCZip.exe "D:\folder"               # 浏览文件夹

3.4 ZIP 密码破解

通过 工具 → ZIP 密码破解 打开 ZipCrackerDialog。实现参考 ZipCracker 项目，支持 ZipCrypto 与 WinZip AES。

攻击方式（按顺序执行）

1. 伪加密检测与修复（成功则直接解压，无需密码）
2. 短明文 CRC32 枚举（1–6 字节，可选）
3. 常见弱口令 / 密码字典（单文件或目录内全部 .txt）/ 数字字典 / 字符集暴力
4. 掩码攻击（?d 数字、?l 小写、?u 大写、?s 符号等）
5. 已知明文攻击 KPA（仅 ZipCrypto；内置 png/zip/exe 模板）

性能参数

3.5 归档库 (Archive Depot)

归档库用于管理压缩包样本集合，数据存储在 SQLite 数据库中（ArchiveDepotDatabase）。

• 导入：通过右键「导入归档库」或主界面工具菜单，将压缩包复制到库目录并记录元数据
• 管理：打开归档库管理器，按库路径浏览、搜索、编辑备注、删除记录
• 字段：文件名、存储路径、源路径、格式、大小、备注、创建/更新时间

3.6 自解压包 (SFX)

通过 SfxBuilder 将文件夹打包为独立可执行文件：

• 使用 UCCZipSfxStub.exe 作为存根（静态链接 zlib + minizip，无 Qt 依赖）
• 支持设置解压目标（如 %EXEDIR%）、压缩级别、AES 加密、自定义图标
• 可配置解压后运行程序、创建开始菜单快捷方式、解压后打开文件夹
• 构建时自动将 payload 附加到 stub 末尾

4. 技术架构

4.1 代码目录结构

4.2 核心模块说明

4.2.1 归档引擎层

ArchiveRouter 根据 ArchiveFormat 将操作分发到对应引擎，并通过 ArchiveCapabilities 查询各格式的 List/Extract/Test/Compress 能力。

4.2.2 表示层 (MainWindow)

主窗口是整个应用的编排中心：

• 管理双视图切换（文件系统 / 归档内浏览）
• 处理用户操作 → 构建 ArchiveTask / SfxTask → 提交 ArchiveManager
• 处理 Shell 模式（m_shellMode）：无界面或最小化执行右键命令后退出
• 维护导航历史、最近文件、剪贴板操作、拖放、临时解压缓存

4.2.3 Shell 集成层

4.2.4 ZIP 密码破解子系统

• ZipCrackerVerify — 归档分析、快速密码筛选（ZipCrypto 12 字节头校验）
• ZipCrackerWorker — 多线程字典/暴力枚举，专用 QThreadPool
• ZipCrackerMask — 掩码密码生成
• ZipCrackerKpa / ZipKpaEngine — 已知明文攻击（集成 bkcrack 库）
• ZipCryptoFast — ZipCrypto 快速解密校验
• ZipCrackerSession — QSettings 会话持久化

4.2.5 归档库子系统

• ArchiveDepotDatabase — SQLite 本地数据库，管理 ArchiveDepotRecord
• ArchiveDepotService — 导入逻辑：复制文件到库目录 + 写入记录
• ArchiveDepotManager — UI 管理界面

4.2.6 SFX 子系统

• SfxBuilder — 编排 stub + payload 拼接
• SfxPayload — payload 格式与 SFX 检测
• UCCZipSfxStub — 独立 C++ 项目，运行时自解压（静态链接，无 Qt DLL）

4.3 数据流与启动流程

应用启动流程

1. main() 检查测试/冒烟参数 → 否则创建 QApplication
2. 初始化日志、清理 7 天前的临时目录 (%TEMP%/UCCZip)
3. 加载 AppSettings，安装翻译器，配置 SQLite 插件路径
4. 解析 --shell-register/unregister → 注册/卸载后退出
5. ShellContextMenu::syncFromSettings() 同步右键菜单状态
6. SingleInstance 检测：若已有实例则转发命令后退出
7. 解析 --shell <verb>：Shell 模式或普通模式启动 MainWindow

压缩/解压任务流

1. 用户操作 / Shell 命令 → MainWindow 构建 ArchiveTask
2. ArchiveManager::compress/extract/test 在 QThreadPool 中异步执行
3. ArchiveRouter::runTask() 按格式路由到具体 Engine
4. Engine 通过回调报告进度 → ArchiveManager::progress 信号 → ProgressDialog
5. 完成后发射 finished(success, message)

关键数据结构

// archive_types.h
enum class ArchiveFormat { Unknown, Zip, Rar, SevenZip, Tar, GZip, UnixZ, Sfx };
enum class ArchiveOperation { None, Compress, Extract, Test, List };

struct ArchiveEntry {
    QString name, path;
    qint64 compressedSize, uncompressedSize;
    QDateTime modified;
    bool isDirectory, encrypted, usesAes;
    int compressionMethod;
    quint32 crc32;
};

struct ArchiveTask {
    ArchiveOperation operation;
    ArchiveFormat format;
    QString archivePath, destinationPath;
    QStringList sourcePaths;
    QString password;
    int compressionLevel;
    bool useAes, overwrite, includeRoot, extractSelectedOnly;
    QList<ArchiveEntry> prefetchedEntries;
    SmartExtractPolicy smartExtractPolicy;
    CompressArchiveMode compressMode;
};

4.4 第三方依赖

5. 法律声明