V1.1.11

Release Notes v1.1.11 / 发布说明 v1.1.11

🎉 What's New / 新功能

Output Path Normalization / 输出路径规范化

Extracted output now flattens meaningless leading folders (typically numeric/symbol-only wrapper directories) while preserving meaningful structure.

提取输出现在会扁平化“无意义的前置文件夹”（通常为纯数字/符号的包裹目录），同时保留有意义的目录结构。

Examples / 示例：

• 1/aaa.jpg → aaa.jpg
• 1/5555+/222.jpg → 222.jpg

Auto-group Contained Multipart Sets / 自动分组容器内分卷集合

When a container archive extracts a multipart set into the output folder (e.g., .7z.001, .part1.rar, spanned .zip/.z01), the tool now auto-creates a multipart group so it can be extracted in the same run.

当容器档案在输出目录中解出分卷集合（例如 .7z.001、.part1.rar、跨卷 .zip/.z01）时，工具现在会自动创建分卷组，以便同一次运行中继续提取。

🐛 Bug Fixes / 错误修复

Prevent Source Multipart Deletion on Failure / 提取失败时不再删除源分卷

Multipart extraction failures (missing volumes, wrong password, etc.) no longer risk deleting the original multipart parts. The tool cleans up only tool-created temporary folders and keeps the source volumes for safe retry.

分卷提取失败（缺少分卷、密码错误等）时，不再有误删源分卷的风险。工具仅清理其创建的临时目录，并保留源分卷，便于安全重试。

Log / 日志：

• Retained source multipart parts due to extraction failure 提取失败，保留源分卷

Cloaked Rename Collision Handling / 伪装文件重命名冲突处理

If cloaked normalization would rename two different files to the same target name, the tool now resolves the collision by renaming the duplicate to a unique __duplicate_<token> name (multipart-aware), preventing extraction failures and preserving sets.

如果“伪装文件规范化”会将两个不同文件重命名为同一个目标名，工具现在会将重复项改名为唯一的 __duplicate_<token>（兼容分卷后缀），从而避免提取失败并保留完整集合。

🔧 Improvements / 改进

Better Nested Multipart Robustness / 更稳健的嵌套分卷处理

• During nested extraction, multipart continuation parts are tracked as candidates.

• If a nested multipart primary fails (non-password failure), the tool attempts to locate/move matching continuation parts next to the primary and retries once.

• If it still fails, the tool preserves the primary and gathered parts as outputs for later manual retry.

• 嵌套提取过程中，会将续卷分卷记录为候选。

• 若嵌套分卷主卷提取失败（非密码失败），工具会尝试查找/移动对应续卷到主卷旁边并重试一次。

• 若仍失败，会保留主卷及已收集分卷到输出中，便于后续手动重试。

✅ Test Coverage / 测试覆盖

New/Updated Tests / 新增/更新测试

• Output path normalization rules (flatten only meaningless leading folders)

• Multipart retention guardrails on failure

• Contained multipart discovery and grouping behavior

• Cloaked rename collision scenarios

• 输出路径规范化规则（仅扁平化“前置无意义”目录）

• 分卷失败保留的保护逻辑

• 容器内分卷发现与分组行为

• 伪装重命名冲突场景

🚀 Migration Notes / 迁移说明

For Users / 用户须知

• No breaking changes.

• Output folder layout may be flatter if the archive contains meaningless wrapper directories.

• Multipart failures are now safer: source parts are retained for retry.

• 无破坏性更改。

• 若档案包含无意义包裹目录，输出目录结构可能更扁平。

• 分卷失败更安全：源分卷会被保留以便重试。

What's Changed

• V1.1.11 bug fixes by @rozx in #14

Full Changelog: v1.1.10...v1.1.11

v1.1.10

Release Notes v1.1.10 / 发布说明 v1.1.10

🎉 What's New / 新功能

Enhanced Retry Extraction with User Passwords / 增强的重试提取与用户密码支持

The tool now supports a comprehensive retry extraction mechanism that can handle user-provided passwords and intelligently manage extraction results.

工具现在支持全面的重试提取机制，可以处理用户提供的密码并智能管理提取结果。

Highlights / 亮点：

• User-provided passwords are now supported during retry extraction attempts.

• Extracted files from retry operations are automatically moved to the output folder with progress tracking.

• Original archives are preserved when extraction fails due to password issues.

• Temporary folders are cleaned up after extraction attempts.

• 重试提取期间现在支持用户提供的密码。

• 重试操作的提取文件会自动移动到输出文件夹，并带有进度跟踪。

• 当由于密码问题导致提取失败时，原始档案会被保留。

• 提取尝试后临时文件夹会被清理。

Improved Nested Archive Preservation / 改进的嵌套档案保留

When nested archive extraction fails due to password issues, the tool now intelligently preserves the original nested archives instead of deleting them, allowing users to retry with correct passwords later.

当嵌套档案提取由于密码问题失败时，工具现在会智能地保留原始嵌套档案而不是删除它们，允许用户稍后使用正确的密码重试。

🐛 Bug Fixes / 错误修复

1. Fixed Incomplete Error Reporting / 修复不完整的错误报告

Issue / 问题: Error summaries were limited to showing only the first few errors, making it difficult to diagnose issues when multiple archives failed.

错误摘要仅显示前几个错误，使得在多个档案失败时难以诊断问题。

Fix / 修复: Updated error reporting functions to display all encountered errors without limiting the output, providing complete diagnostic information.

更新了错误报告函数，显示所有遇到的错误而不限制输出，提供完整的诊断信息。

Affected functions / 受影响的函数:

• print_final_completion() - Now shows all completion errors
• print_error_summary() - Now displays all error details

2. Enhanced Archive Deletion Logic / 增强的档案删除逻辑

Issue / 问题: Original archives were sometimes deleted even when extraction failed due to password issues, making it impossible to retry.

即使由于密码问题导致提取失败，原始档案有时也会被删除，使得无法重试。

Fix / 修复: Added intelligent logic to determine whether original archives should be deleted based on extraction results. Archives are now preserved when extraction fails due to password authentication issues.

添加了智能逻辑，根据提取结果确定是否应删除原始档案。当由于密码身份验证问题导致提取失败时，档案现在会被保留。

🔧 Improvements / 改进

Comprehensive Password Handling / 全面的密码处理

• Passwords from both destination folder and tool root directory are now combined automatically.

• User-provided passwords during retry extraction are properly tracked and used.

• Better error messages when password authentication fails.

• 目标文件夹和工具根目录的密码现在会自动合并。

• 重试提取期间的用户提供的密码会被正确跟踪和使用。

• 密码身份验证失败时提供更好的错误消息。

Enhanced Error Diagnostics / 增强的错误诊断

• Archive extraction functions now consider both stdout and stderr for comprehensive error detection.

• More detailed error information helps users understand why extraction failed.

• 档案提取函数现在考虑 stdout 和 stderr 以进行全面的错误检测。

• 更详细的错误信息帮助用户理解提取失败的原因。

Improved Cleanup Process / 改进的清理过程

• Temporary folders created during extraction are now cleaned up more reliably.

• Files from retry operations are properly moved to the output folder with progress feedback.

• 提取期间创建的临时文件夹现在更可靠地被清理。

• 重试操作的文件会正确移动到输出文件夹，并带有进度反馈。

📝 Documentation Updates / 文档更新

README.md Enhancements / README.md 增强内容

• Expanded password file handling section with multiple search locations.

• Clarified how passwords from different locations are combined.

• Updated examples to reflect the new password handling capabilities.

• 扩展了密码文件处理部分，包含多个搜索位置。

• 阐明了不同位置的密码如何合并。

• 更新了示例以反映新的密码处理功能。

Key additions / 主要新增内容:

• Passwords can now be placed in both destination folder and tool root directory.

• All found password files are combined automatically.

• Clear examples showing password file placement.

• 密码现在可以放在目标文件夹和工具根目录中。

• 所有找到的密码文件会自动合并。

• 清晰的示例显示密码文件的放置位置。

✅ Test Coverage / 测试覆盖

New Tests / 新增测试

• Added tests for retry extraction with user-provided passwords.

• Tests for archive preservation logic when extraction fails.

• Enhanced error reporting tests to verify all errors are displayed.

• Tests for temporary folder cleanup after extraction attempts.

• 添加了使用用户提供的密码进行重试提取的测试。

• 提取失败时档案保留逻辑的测试。

• 增强的错误报告测试，验证显示所有错误。

• 提取尝试后临时文件夹清理的测试。

Validation / 验证

• ✅ All existing tests continue to pass

• ✅ New retry extraction functionality tested with various password scenarios

• ✅ Error reporting verified to show all encountered errors

• ✅ Archive preservation logic tested with password failures

• ✅ 所有现有测试继续通过

• ✅ 新的重试提取功能在各种密码场景下进行了测试

• ✅ 错误报告经验证显示所有遇到的错误

• ✅ 档案保留逻辑在密码失败情况下进行了测试

⚙️ Technical Details / 技术细节

Modified Files / 修改的文件

complex_unzip_tool_v2/main.py

• Added retry extraction logic with user password support (189 lines added)

• Implemented file movement from retry results to output folder

• Added intelligent archive deletion logic based on extraction results

• Enhanced error handling for nested archive extraction

• Added temporary folder cleanup after extraction attempts

• 添加了带有用户密码支持的重试提取逻辑（新增 189 行）

• 实现了从重试结果到输出文件夹的文件移动

• 添加了基于提取结果的智能档案删除逻辑

• 增强了嵌套档案提取的错误处理

• 添加了提取尝试后的临时文件夹清理

complex_unzip_tool_v2/modules/archive_utils.py

• Enhanced error handling to consider both stdout and stderr

• Improved diagnostic information for archive extraction failures

• Better support for password-related error detection

• 增强了错误处理，考虑 stdout 和 stderr

• 改进了档案提取失败的诊断信息

• 更好地支持密码相关错误检测

complex_unzip_tool_v2/modules/rich_utils.py

• Updated print_final_completion() to show all errors

• Updated print_error_summary() to display complete error information

• Removed conditional messages that limited error display

• 更新了 print_final_completion() 以显示所有错误

• 更新了 print_error_summary() 以显示完整的错误信息

• 删除了限制错误显示的条件消息

README.md

• Expanded password management section with multiple location support

• Added clear examples for password file placement

• Updated usage examples to reflect new capabilities

• 扩展了密码管理部分，支持多个位置

• 添加了密码文件放置的清晰示例

• 更新了使用示例以反映新功能

Test Files / 测试文件

• tests/test_archive_utils.py - Added 43 lines of new tests
• tests/test_main.py - Added 15 lines of new tests

Code Statistics / 代码统计

• Total changes / 总更改: 403 insertions(+), 93 deletions(-)
• Files modified / 修改的文件: 9 files
• Test additions / 测试新增: 58 lines of new tests

🚀 Migration Notes / 迁移说明

For Users / 用户须知

No breaking changes. All existing functionality is preserved and enhanced.

无破坏性更改。 所有现有功能都被保留和增强。

New benefits / 新优势:

• More reliable extraction when password issues occur

• Complete error information for better troubleshooting

• Automatic cleanup of temporary files

• Better handling of nested archives with password protection

• 当出现密码问题时提取更可靠

• 完整的错误信息以便更好地排除故障

• 自动清理临时文件

• 更好地处理受密码保护的嵌套档案

For Developers / 开发者须知

API Changes / API 更改:

• Error reporting functions now display all errors by default (no longer limited)

• Archive extraction error handling now considers both stdout and stderr

• New helper function added for determining archive deletion logic

• 错误报告函数现在默认显示所有错误（不再受限）

• 档案提取错误处理现在考虑 stdout 和 stderr

• 添加了用于确定档案删除逻辑的新辅助函数

If you maintain custom code / 如果您维护自定义代码:

• Review error handling logic if you relied on limited error display

• Update any custom extraction flows to handle the new retry mechanism

• Consider the new archive preservation behavior in your workflows

• 如果您依赖受限的错误显示，请审查错误处理逻辑

• 更新任何自定义提取流程以处理新的重试机制

• 在您的工作流程中考虑新的档案保留行为

🎯 Performance Impact / 性能影响

• Retry extraction / 重试提取: Minimal overhead, only triggered when needed

• Error reporting / 错误报告: Slightly increased output for comprehensive diagnostics

• Cleanup operations / 清理操作: Improved efficiency with better temporary folder management

• 重试提取： 最小开销，仅在需要时触发

• 错误报告： 输出略微增加，以提供全面的诊断

• 清理操作： 通过更好的临时文件夹管理提高了效率

🙏 Acknowledgments / 致谢

Special thanks to all users who provided feedback on password handling and error reporting!

特别感谢所有就密码处理和错误报告提供反馈的用户！

---

Full Changelog: v1.1.8...v1.1.10

完整变更日志： v1.1.8...v1.1.10

What's Changed

• V1.1.10 bug fixes by @rozx in #13

Full Changelog: v1.1.8...v1.1.10

v1.1.8

Release Notes v1.1.8 / 发布说明 v1.1.8

🎉 What's New / 新功能

Continuation Parts Relocation from Nested Containers / 从嵌套容器中重定位分卷续档

When an outer archive contains parts of a multipart set (e.g., a .zip holding MySet.7z.002), the tool now relocates those continuation parts next to their multipart set before attempting the multipart extraction. This guarantees the set is complete when extraction begins.

当外层档案包含多部分档案的续档（例如 .zip 内含 MySet.7z.002）时，工具会在尝试多部分提取前，将这些续档移动到对应的多部分集旁边，确保在开始提取时分卷齐全。

Highlights / 亮点：

• Continuation parts found during nested extraction are no longer lost with temp cleanup—they are moved to the correct group (if possible).

• Primary parts are still the only ones considered for recursive nested extraction.

• A safety-net reconciliation pass scans the output folder to relocate any remaining parts before multipart extraction.

• 在嵌套提取过程中发现的续档不再随临时清理丢失——若可能，将移动到正确的分组目录。

• 递归嵌套提取仍仅针对主分卷执行。

• 在多部分提取前，会对输出目录执行一次兜底扫描，将尚未移动到位的续档重定位。

🐛 Bug Fixes / 错误修复

Fix: Multipart extraction failing when a part was inside another container / 修复：当分卷在其他容器中时多部分提取失败

Issue / 问题： If one of the multipart volumes existed inside another archive, the tool didn’t place it next to the set before attempting extraction, causing missing-volume errors.

如果某个分卷存在于另一个档案内，工具在开始提取前没有将它放到多部分集旁边，导致缺失分卷错误。

Fix / 修复： Added a relocation callback to nested extraction that moves continuation parts into the correct multipart group directory immediately. Also added a reconciliation pass after single-archive extraction to relocate any parts that landed in the output folder.

在嵌套提取中新增重定位回调，立即将续档移动到对应的多部分组目录；并在单一档案提取结束后新增一次对输出目录的兜底扫描，重定位落在输出目录中的续档。

🔧 Improvements / 改进

• Optional group_relocator callback in nested extraction to handle continuation parts discovered inside containers.

• Output-folder reconciliation step ensures multipart sets are complete before extraction begins.

• Clearer CLI messages (English/Chinese) showing when continuation parts are relocated.

• 在嵌套提取中新增可选 group_relocator 回调，用于处理在容器中发现的续档。

• 新增输出目录的兜底扫描步骤，确保开始多部分提取前分卷齐全。

• 更清晰的 CLI 提示（中英文），在续档被移动时给出明确反馈。

📝 Documentation Updates / 文档更新

• Updated AGENTS.md with the new nested multipart relocation behavior and the reconciliation pass.

• Documented how continuation parts are identified and handled across formats (7z, RAR, ZIP, TAR.*).

• 更新了 AGENTS.md，说明新增的嵌套续档重定位行为与兜底扫描步骤。

• 文档化了不同格式（7z、RAR、ZIP、TAR.*）的续档识别与处理方式。

✅ Test Coverage / 测试覆盖

• Added unit tests ensuring continuation parts found during nested extraction are relocated via the callback (or skipped) and do not leak into final_files.

• Full test suite passes locally.

• 新增单元测试，确保嵌套提取中发现的续档会通过回调被重定位（或被跳过），且不会泄漏到 final_files。

• 本地完整测试套件全部通过。

⚙️ Technical Details / 技术细节

Modified Files / 修改的文件

• complex_unzip_tool_v2/modules/archive_utils.py
  • Added optional group_relocator to extract_nested_archives() and used it when encountering continuation parts during nested scanning.
• complex_unzip_tool_v2/main.py
  • Wired group_relocator to reuse file_utils.add_file_to_groups and added a reconciliation step after single-archive extraction.
• complex_unzip_tool_v2/modules/file_utils.py
  • Added relocate_multipart_parts_from_directory(source_root, groups) to scan output folder and relocate parts into their group directories.
  • Kept strict base-name matching semantics to avoid cross-group misclassification.
• tests/test_archive_utils.py
  • Added tests: continuation parts are relocated via callback and not included in final_files; skipped when not relocated.
• AGENTS.md
  • Documented the new relocation and reconciliation behavior.

Validation / 验证

• ✅ CLI verified on a sample real-world directory (e.g., E:\testDir - Copy).

• ✅ 102 unit tests passing locally.

• ✅ 在真实目录（例如 E:\\testDir - Copy）中验证。

• ✅ 本地 102 个单元测试全部通过。

🚀 Migration Notes / 迁移说明

For Users / 用户须知

No breaking changes. The tool will more reliably extract multipart archives when some parts are inside containers.

无破坏性变化。当部分分卷位于容器内时，工具将更可靠地完成多部分提取。

For Developers / 开发者须知

• extract_nested_archives() now accepts an optional group_relocator parameter. Existing calls continue to work (parameter is optional).

• If you maintain custom extraction flows, consider wiring a relocator to ensure continuation parts found in nested contexts are handled immediately.

• extract_nested_archives() 现已支持可选参数 group_relocator。现有调用无需修改（该参数是可选的）。

• 若维护自定义提取流程，建议接入重定位逻辑，以便及时处理嵌套环境中发现的续档。

---

Full Changelog: v1.1.7...v1.1.8

完整变更日志： v1.1.7...v1.1.8

v1.1.7

Release Notes v1.1.7 / 发布说明 v1.1.7

🎉 What's New / 新功能

Nested Multipart Archive Handling / 嵌套多部分档案处理

When extracting archives that contain multipart archives (e.g., a .7z file containing another multipart set), the tool now intelligently filters continuation parts to prevent them from cluttering your output directory.

当提取包含多部分档案的档案时（例如，一个包含另一个多部分集的 .7z 文件），工具现在会智能地过滤续档部分，以防止它们污染输出目录。

Example / 示例:

• Input: outer.7z contains archive.7z.001, archive.7z.002, archive.7z.003

• Previous behavior: All parts moved to output folder

• New behavior: Only extracts archive.7z.001, continuation parts are cleaned up automatically

• 输入：outer.7z 包含 archive.7z.001、archive.7z.002、archive.7z.003

• 之前的行为：所有部分移动到输出文件夹

• 新行为：仅提取 archive.7z.001，续档部分自动清理

🐛 Bug Fixes / 错误修复

1. Fixed Incorrect Renaming of Proper Archive Names / 修复了正确档案名称的错误重命名

Issue / 问题: Files with already-correct multipart extensions (like .7z.001, .r00, .z01) were being renamed incorrectly.

已经具有正确多部分扩展名的文件（如 .7z.001、.r00、.z01）被错误地重命名。

Fix / 修复: Added safety guards to the uncloaking system to skip files that already have proper archive extensions.

在揭示系统中添加了安全防护，跳过已经具有正确档案扩展名的文件。

Protected formats / 受保护的格式:

• Multipart: .7z.001, .7z.002, .r00, .r01, .z01, .z02, .part1.rar, .part2.rar, .tar.gz.001, etc.
• Single: .7z, .rar, .zip, .tar, .tgz, .tbz2, .gz, .bz2, .xz, .iso, etc.

2. Fixed Password Loading from Target Directory / 修复了从目标目录加载密码的问题

Issue / 问题: Passwords in passwords.txt were not being loaded correctly, especially when containing Chinese characters.

passwords.txt 中的密码未正确加载，尤其是包含中文字符时。

Fix / 修复: Enhanced password file reading with multi-encoding support and proper BOM handling.

增强了密码文件读取功能，支持多种编码和正确的 BOM 处理。

Supported encodings / 支持的编码:

• UTF-8 (with/without BOM)
• GBK, GB2312, Big5
• UTF-16 (LE/BE)

Password sources / 密码来源:

1. Target directory: passwords.txt in the extraction directory

2. Tool root: passwords.txt at the repository root

3. 目标目录：提取目录中的 passwords.txt

4. 工具根目录：存储库根目录中的 passwords.txt

3. Fixed False "Corrupted Archive" Errors for Regular Files / 修复了常规文件的虚假"损坏档案"错误

Issue / 问题: Non-archive files (e.g., .mp4, .txt) encountered during nested extraction were incorrectly reported as corrupted archives.

在嵌套提取过程中遇到的非档案文件（例如 .mp4、.txt）被错误地报告为损坏的档案。

Fix / 修复: Improved 7-Zip error message mapping to correctly distinguish between corrupted archives and non-archive files.

改进了 7-Zip 错误消息映射，以正确区分损坏的档案和非档案文件。

Behavior / 行为:

• Files are still probed with 7-Zip (no pre-filtering)

• "Can not open file as archive" → Treated as non-archive (skipped silently)

• "Data error" / "CRC failed" → Treated as corrupted archive (error reported)

• 文件仍然使用 7-Zip 探测（无预过滤）

• "Can not open file as archive" → 视为非档案（静默跳过）

• "Data error" / "CRC failed" → 视为损坏的档案（报告错误）

🔧 Improvements / 改进

Enhanced Multipart Detection / 增强的多部分检测

The tool now recognizes and properly handles these multipart formats during nested extraction:

工具现在可以在嵌套提取期间识别并正确处理这些多部分格式：

• 7-Zip volumes / 7-Zip 卷: .7z.001 (primary), .7z.002+ (continuations)
• RAR volumes / RAR 卷: .rar or .part1.rar (primary), .r00, .r01+, .part2+.rar (continuations)
• ZIP spanned / ZIP 分卷: .zip (primary), .z01, .z02+ (continuations)
• TAR multipart / TAR 多部分: .tar.gz.001, .tar.bz2.001, .tar.xz.001 (primary), .002+ (continuations)

Robust Password Handling / 健壮的密码处理

• Automatic encoding detection for international characters

• BOM (Byte Order Mark) stripping

• Empty line and whitespace handling

• UTF-8 output for saved passwords

• 国际字符的自动编码检测

• BOM（字节顺序标记）剥离

• 空行和空白处理

• 保存密码的 UTF-8 输出

📝 Documentation Updates / 文档更新

AGENTS.md Additions / AGENTS.md 新增内容

• Passwords handling section with encoding details

• Renaming/Uncloaking rules with safety guards

• Nested multipart handling behavior

• Non-archive handling during nested scan

• 密码处理部分，包含编码详细信息

• 重命名/揭示规则，包含安全防护

• 嵌套多部分处理行为

• 嵌套扫描期间的非档案处理

Test Coverage / 测试覆盖

Added comprehensive unit tests for:

• Multipart continuation filtering
• Password encoding robustness
• Non-archive error mapping
• Proper archive name protection

为以下内容添加了全面的单元测试：

• 多部分续档过滤
• 密码编码鲁棒性
• 非档案错误映射
• 正确的档案名称保护

⚙️ Technical Details / 技术细节

Modified Files / 修改的文件

• complex_unzip_tool_v2/modules/archive_utils.py

  • Enhanced _raise_for_7z_error() for non-archive detection
  • Added continuation part filtering in extract_nested_archives()
  • Improved _parse7zListOutput() robustness

• complex_unzip_tool_v2/modules/cloaked_file_detector.py

  • Added safety guards in detect_cloaked_file()
  • Skip renaming for proper multipart and single archive extensions

• complex_unzip_tool_v2/classes/PasswordBook.py

  • Multi-encoding support in load_passwords()
  • UTF-8 encoding in save_passwords()

• complex_unzip_tool_v2/modules/password_util.py

  • Variable naming cleanup (avoid shadowing)

• tests/test_archive_utils.py

  • New tests for non-archive handling
  • New tests for error message mapping

• tests/test_cloaked_file_detector.py

  • Tests for safety guard behavior

Validation / 验证

• ✅ All 100 unit tests passing

• ✅ CLI smoke tests successful

• ✅ Real-world directory testing (E:\testDir, E:\testDir2 - Copy)

• ✅ Chinese password handling verified

• ✅ 所有 100 个单元测试通过

• ✅ CLI 冒烟测试成功

• ✅ 真实世界目录测试（E:\testDir、E:\testDir2 - Copy）

• ✅ 中文密码处理已验证

🚀 Migration Notes / 迁移说明

For Users / 用户须知

No action required. All changes are backward compatible and improve existing functionality.

无需操作。所有更改都向后兼容并改进了现有功能。

For Developers / 开发者须知

If you have custom code that:

• Relies on specific error types from archive operations, review the new ArchiveUnsupportedError usage for non-archives
• Manipulates archive filenames, check the new safety guards in uncloaking rules

如果您有自定义代码：

• 依赖于档案操作的特定错误类型，请查看非档案的新 ArchiveUnsupportedError 使用情况
• 操作档案文件名，请检查揭示规则中的新安全防护

🙏 Acknowledgments / 致谢

Special thanks to all users who reported issues and helped test these fixes!

特别感谢所有报告问题并帮助测试这些修复的用户！

---

Full Changelog: v1.1.6...v1.1.7

完整变更日志： v1.1.6...v1.1.7

v1.1.6

Release Notes - v1.1.6 | 版本说明 - v1.1.6

Nested Archive Handling Fix | 嵌套档案处理修复

Summary | 概述

Fixed a critical issue where multiple nested archives extracted from a single parent archive would collide and overwrite each other's contents when extracted to the same destination directory.

修复了一个关键问题：从单个父档案中提取多个嵌套档案时，所有内容会提取到同一目标目录中发生冲突并相互覆盖。

Problem | 问题描述

When processing self-extracting archives (e.g., .exe files) or archives containing multiple nested archives, all nested content was extracted into the same parent directory. This caused:

处理自解压档案（例如 .exe 文件）或包含多个嵌套档案的档案时，所有嵌套内容都会提取到同一父目录中。这导致：

• File collisions and data loss when nested archives contained files with identical names | 当嵌套档案包含同名文件时发生文件冲突和数据丢失
• Extraction failures due to concurrent write conflicts | 由于并发写入冲突导致提取失败
• Incorrect file counts and missing content in the final output | 最终输出中文件计数不正确和内容缺失

Solution | 解决方案

Each nested archive is now extracted into its own uniquely-named subfolder:

现在每个嵌套档案都会提取到其自己的唯一命名子文件夹中：

• Subfolder names are derived from the archive filename with extensions stripped | 子文件夹名称源自去除扩展名的档案文件名
• Automatic deduplication handles multiple archives with similar names (appends _2, _3, etc.) | 自动去重处理具有相似名称的多个档案（附加 _2、_3 等）
• Directory structure is preserved throughout the extraction chain | 在整个提取链中保留目录结构

Example | 示例

Before | 之前：

temp.archive/
  ├── file1.txt (from archive1.zip)
  ├── file1.txt (from archive2.zip) ← COLLISION! 冲突！
  └── file2.txt

After | 之后：

temp.archive/
  ├── archive1/
  │   ├── file1.txt
  │   └── data.bin
  └── archive2/
      ├── file1.txt
      └── file2.txt

Additional Improvements | 其他改进

• Graceful handling of already-processed archives | 优雅处理已处理的档案: Prevents false errors when a nested archive appears at multiple recursion levels | 防止嵌套档案在多个递归级别出现时产生错误
• Missing file tolerance | 缺失文件容错: Skips already-cleaned-up nested archives without raising errors | 跳过已清理的嵌套档案而不引发错误
• Better logging | 更好的日志记录: Clear messages when nested archives are skipped or processed in subfolders | 当嵌套档案被跳过或在子文件夹中处理时提供清晰的消息

Testing | 测试

• ✅ All 95 existing tests pass | 所有 95 个现有测试通过
• ✅ Validated with real-world test case: brlslyflds.exe containing 2 nested ZIP archives | 使用真实测试用例验证：包含 2 个嵌套 ZIP 档案的 brlslyflds.exe
• ✅ Correctly extracts 85 total files into separate subfolders without collisions | 正确提取 85 个文件到独立子文件夹中，无冲突

Files Changed | 文件更改

• complex_unzip_tool_v2/modules/archive_utils.py
  • Updated extract_nested_archives() → _extractRecursively() logic | 更新了 extract_nested_archives() → _extractRecursively() 逻辑
  • Added subfolder derivation and uniqueness checks | 添加了子文件夹派生和唯一性检查
  • Enhanced error handling for missing/duplicate nested archives | 增强了缺失/重复嵌套档案的错误处理

Compatibility | 兼容性

• No breaking changes to public API | 公共 API 无破坏性更改
• No changes to command-line interface | 命令行界面无更改
• Existing password handling and multi-part archive support unchanged | 现有密码处理和多部分档案支持不变

---

Version | 版本: 1.1.6
Branch | 分支: v1.1.6-nested-archive-fix
Date | 日期: October 1, 2025 | 2025年10月1日

What's Changed

• V1.1.6- nested archive fix by @rozx in #10

Full Changelog: v1.1.5...v1.1.6

v1.1.5

v1.1.5 / 发布说明 v1.1.5

Release Date / 发布日期: September 29, 2025

🆕 New Features / 新功能

Enhanced Cloaked File Detection / 增强的隐藏文件检测

English: Added support for files with digit-suffix extensions like .001删除, .002删除. Files such as missedyou.7z.001删除 are now automatically renamed to missedyou.7z.001 for proper multi-part archive handling.

中文: 支持数字后缀扩展名文件如 .001删除、.002删除。像 missedyou.7z.001删除 这样的文件现在会自动重命名为 missedyou.7z.001，以便正确处理多部分压缩包。

Examples / 示例

missedyou.7z.001删除 → missedyou.7z.001
archive.rar.002删除 → archive.rar.002  
backup.zip.003移除  → backup.zip.003

🔧 Technical Details / 技术详情

English: New rule cloaked_multipart_ext_digits_with_suffix with priority 96. Matches filename pattern ^(.+)\.(7z|rar|zip)$ and extension pattern ^(\d{2,3}).+$ to detect and normalize cloaked multi-part archives.

中文: 新规则 cloaked_multipart_ext_digits_with_suffix，优先级为 96。匹配文件名模式 ^(.+)\.(7z|rar|zip)$ 和扩展名模式 ^(\d{2,3}).+$ 来检测和规范化隐藏的多部分压缩包。

✅ Quality Assurance / 质量保证

English: 95 tests passed (100% success rate). Full backward compatibility maintained. No performance impact.

中文: 95个测试通过（100%成功率）。保持完全向后兼容。无性能影响。

---

GitHub Repository: Complex-unzip-tool-v2
Branch: v1.1.5-new-rules

What's Changed

• v1.1.5 - added new clocked file detecting rule by @rozx in #9

Full Changelog: v1.1.4...v1.1.5

v1.1.4

Release Notes v1.1.4 - Bug Fixes 发布说明 v1.1.4 - 错误修复

🐛 Critical Fix 关键修复

Issue 问题: Archive files were deleted when password extraction failed.
档案文件在密码提取失败时被删除。

Fix 修复: Original archives are now preserved when extraction fails due to password issues.
当由于密码问题导致提取失败时，原始档案现在会被保留。

Files Changed 修改的文件:

• complex_unzip_tool_v2/modules/archive_utils.py: Updated success logic
• tests/test_archive_utils.py: Added regression test

✅ Quality Assurance 质量保证

• All tests pass (93/93) 所有测试通过
• No breaking changes 无破坏性更改
• Backward compatible 向后兼容

Recommended Action 建议操作: Update immediately to prevent data loss.
立即更新以防止数据丢失。

What's Changed

• v1.1.4 by @rozx in #8

Full Changelog: v1.1.3...v1.1.4

v1.1.3

Release Summary v1.1.3 / 发布摘要 v1.1.3

🔒 Safer Multipart Grouping / 更安全的多分卷归组

Fixed: Cross-folder part mixing that caused extraction failures / 修复： 跨文件夹分卷混合导致的提取失败

What Changed / 变更内容

• Multipart archives now group only within the same directory tree / 多分卷档案现仅在同一目录树内归组
• Removed fuzzy matching to prevent accidental cross-group moves / 移除模糊匹配以防意外跨组移动
• Added strict base-name validation for part grouping / 为分卷归组添加严格的基础名验证

Problem Solved / 解决的问题

When extracting parent directories with multiple subfolders containing same-named archives (e.g., 10435.7z.001, 10423.7z.001), parts could be incorrectly moved between folders, causing "File is not a valid archive" errors.

当提取包含多个子文件夹且含有同名档案的父目录时（如 10435.7z.001、10423.7z.001），分卷可能被错误地在文件夹间移动，导致"不是有效档案"错误。

Impact / 影响

• ✅ No more cross-folder part contamination / 不再出现跨文件夹分卷污染
• ✅ Predictable extraction behavior for organized archives / 有组织档案的可预测提取行为
• ✅ Zero breaking changes to CLI / CLI 零破坏性变更

Quick Test / 快速测试

poetry run pytest -q  # All tests pass / 所有测试通过

What's Changed

• v1.1.3 by @rozx in #7

Full Changelog: v1.1.2...v1.1.3

v1.1.2

Complex Unzip Tool v1.1.2 | 复杂解压工具 v1.1.2

🚀 Release Summary | 版本摘要

Release Date: September 6, 2025 | 发布日期: 2025年9月6日
Version: 1.1.2 | 版本: 1.1.2
Type: Bug Fix Release | 类型: 错误修复版本

📋 What's New | 更新内容

🔧 Archive Processing Improvements | 档案处理改进

• Enhanced archive validation and alternative handling | 增强档案验证与备用处理
• Streamlined extraction process with better error recovery | 简化提取流程，改进错误恢复

📦 Multipart Archive Enhancements | 多部分档案增强

• Improved multipart file grouping logic | 改进多部分文件分组逻辑
• Better handling of split archive files | 更好地处理分割档案文件

🛡️ Validation & Error Handling | 验证与错误处理

• Enhanced directory structure validation | 增强目录结构验证
• Better retry mechanisms for failed extractions | 改进提取失败的重试机制

🧹 Code Cleanup | 代码清理

• Removed unnecessary debug validation file | 删除不必要的调试验证文件
• Optimized codebase for better maintainability | 优化代码库以提高可维护性

🎯 Key Benefits | 主要优势

• 🔒 More Reliable | 更可靠: Better error handling and recovery
• ⚡ Faster Processing | 更快处理: Optimized multipart archive handling
• 🧹 Cleaner Code | 更整洁代码: Removed redundant files
• 🛡️ Robust Validation | 强大验证: Enhanced archive and directory checks

📊 Technical Details | 技术详情

• Python Support: 3.11+ | Python 支持: 3.11+
• Platform: Windows | 平台: Windows
• Branch: v1.1.2-bug-fixes | 分支: v1.1.2-bug-fixes

---

This is a maintenance release focusing on bug fixes and code improvements.
这是一个专注于错误修复和代码改进的维护版本。

What's Changed

• V1.1.2 bug fixes by @rozx in #6

Full Changelog: 1.1.1...v1.1.2

v1.1.1

v1.1.1 Changes Summary | v1.1.1 更新摘要

🔧 Major Archive Utils Refactoring | 主要档案工具重构

• Comprehensive refactoring of archive_utils.py for improved readability and maintainability
  全面重构 archive_utils.py 以提高可读性和可维护性
• Added new exception classes (ArchiveExceptions.py) for better error handling
  添加新的异常类 (ArchiveExceptions.py) 以更好地处理错误
• Added archive type definitions (ArchiveTypes.py) for better organization
  添加档案类型定义 (ArchiveTypes.py) 以更好地组织代码
• Improved exception chaining and error reporting
  改进异常链接和错误报告

🧪 New Testing Infrastructure | 新的测试基础设施

• Added unit tests for archive_utils, cloaked_file_detector, and file_utils modules
  为 archive_utils、cloaked_file_detector 和 file_utils 模块添加单元测试
• Enhanced test coverage for core functionality
  增强核心功能的测试覆盖率

🔍 Cloaked File Detection Improvements | 隐藏文件检测改进

• Updated error messages for missing patterns in CloakedFileRule
  更新 CloakedFileRule 中缺失模式的错误消息
• Improved JSON formatting consistency in configuration files
  改进配置文件中 JSON 格式的一致性
• Enhanced validation logic for rule patterns
  增强规则模式的验证逻辑

✨ Code Quality Enhancements | 代码质量提升

• Added .flake8 configuration for code linting
  添加 .flake8 配置用于代码检查
• Improved import statements and code organization
  改进导入语句和代码组织
• Better separation of concerns across modules
  更好地分离各模块的关注点

📦 Version Management | 版本管理

• Updated version to 1.1.1 in both __init__.py and pyproject.toml
  在 __init__.py 和 pyproject.toml 中更新版本至 1.1.1
• Cleaned up temporary refactoring documentation
  清理临时重构文档

🛠️ Enhanced Constants and Utilities | 增强常量和工具函数

• Added new constants in const.py for better configuration management
  在 const.py 中添加新常量以更好地管理配置
• Improved utility functions across various modules
  改进各个模块中的工具函

What's Changed

• V1.1.1 by @rozx in #5

Full Changelog: 1.1.0...1.1.1