SunPack 是一个 Windows-first 的智能归档处理与损坏压缩包尽力恢复工具。它不只是批量调用 7-Zip 解压，而是围绕真实文件状态建立一条可循环的 pipeline：

detection -> analysis -> extraction -> verification -> repair -> extraction -> verification

项目的目标是：在复杂下载目录、游戏/程序目录、伪装载体、分卷包、嵌套包和损坏包里，尽量找出真正应该处理的归档；解压失败时尽量恢复可用文件；恢复出多个候选时用 verification 比较完整度，保留更好的结果。

当前项目的 CLI 已支持中文，默认配置文件是 sunpack_config.json。源码入口是 python sunpack.py；Windows 打包后入口是 sunpack.exe。

• 智能候选识别：结合扩展名、magic bytes、ZIP/7z/RAR/TAR 结构事实、embedded payload、PE overlay、目录场景和 7z.dll probe/test 判断文件是否值得解压。
• 场景保护：识别游戏、程序、资源目录，降低把 .dll、模型权重、Office 容器、资源包等误当普通压缩包处理的概率。
• 分卷与虚拟输入：识别标准分卷、编号卷、RAR/7z 分卷和 SFX companion；analysis 可产出 file_range、concat_ranges 等虚拟输入供 worker 解压。
• 真实 worker 解压：最终解压由 sunpack_sevenzip_worker.exe 调用 7z.dll 完成，不走 7z.exe x 文本封装。
• verification 驱动结果判断：不只看 worker 成功/失败，而是检查输出目录、manifest、归档条目、CRC、样本可读性、文件完整度和部分恢复进度。
• 模型驱动 repair 图搜索：内置 diagnosis HGT 判断可操作根因，repair policy transformer 对 module/undo/stop 动作评分；每个候选仍必须重新进入 extraction 和 verification，模型不直接宣称修复成功。
• 损坏包尽力恢复：ZIP repair 使用原子化模块（boundary/pointer/ZIP64/rebuild/descriptor/quarantine/partial/conflict 分别暴露为独立 action）；TAR checksum/trailing/PAX/GNU longname/sparse 修复；gzip/bzip2/xz/zstd 截断和尾部垃圾处理；7z start/next header/边界/CRC/solid block salvage；RAR block/end/carrier/file quarantine 修复。
• 嵌套与载体恢复：可从损坏外壳或 carrier 中扫描内层 ZIP/7z/RAR/TAR/gzip 等载荷，并把内层包送回 pipeline。
• Native-first 热路径：Rust 承接目录扫描、二进制视图、signature prepass、结构 probe、carrier scan、repair I/O、CRC/readability、候选匹配索引和密码 fast verifier；C++ 承接 7z.dll ABI 与 worker。
• 适合右键菜单和 watch：提供 Windows 右键菜单脚本，也支持 watch 目录监控，文件稳定后自动处理。

SunPack 更像一个“归档恢复协调器”而不是普通解压器：

• 对干净压缩包：批量、递归、密码、分卷、清理和扁平化。
• 对可疑文件：通过 detection/analysis 尽量避免误判。
• 对损坏压缩包：先提取可用部分，再让 repair 生成候选，最后由 verification 比较产物质量。
• 对大批量任务：通过 scheduler profile、resource guard、analysis cache、worker 复用和 Rust 热路径控制性能。

准备开发环境：

.\scripts\setup_windows_dev.ps1

包含打包依赖：

.\scripts\setup_windows_dev.ps1 -IncludeBuildDeps

确认 native 组件可用：

python -c "import sunpack_native as n; print(n.native_available(), n.scanner_version())"
python -c "from sunpack.support.sevenzip_bridge import NativePasswordTester; print(NativePasswordTester().available())"
python sunpack.py models status --load

常用命令：

python sunpack.py scan D:\Downloads
python sunpack.py inspect D:\Downloads -v
python sunpack.py extract D:\Downloads
python sunpack.py watch D:\Downloads --out-dir D:\Unpacked
python sunpack.py extract D:\Archives -p 123456 --pw-file .\passwords.txt
python sunpack.py config validate

打包后的程序使用同一套命令：

.\dist\\sunpack\sunpack.exe extract D:\Downloads

详细参数见 CLI 参数说明。

主配置文件是 sunpack_config.json。修改后建议执行：

python sunpack.py config validate

常用配置：

• filesystem.scan_filters_enabled / filesystem.scan_filters：过滤器总开关、目录剪枝、黑名单、最小检测大小。
• detection.enabled / detection.rule_pipeline：detection 层总开关、候选识别、场景保护、结构打分和确认层。
• embedded_payload_identity.embedded_payload_scan_level：嵌入载荷扫描档位，默认 balanced；可改为 light 降低成本，或 deep 提高伪装压缩包召回。
• extract --direct-file <file>：明确指定文件，跳过初始扫描和 detection，直接进入 analysis 及后续解压/校验/修复/后处理。
• analysis：结构分析、signature prepass、fuzzy binary profile、批量 analysis cache。
• verification：输出存在性、manifest、归档 CRC、可读性抽样、部分恢复阈值。
• repair：统一最大修复模式、安全策略、module limits、beam、模块开关和资源上限。
• performance：scheduler profile、worker 超时、profile calibration、resource guard。
• recursive_extract：递归解压策略，* 无限递归，正整数为轮数，? 每轮询问。
• post_extract.archive_cleanup_mode：成功后 d 删除、r 回收站、k 保留。

完整说明见 配置文件说明。

app/config
  -> coordinator
     filesystem->relations-> detection -> analysis -> extraction -> verification
                        ^                            |
                        |                            v
                        +----------- repair ------------+
     -> postprocess

重要边界：

• detection 只判断候选是否应处理。
• analysis 只描述结构、边界、损坏标志和可用输入视图。
• extraction 只执行 worker 解压。
• verification 只评价结果质量和下一步建议。
• repair 统一拥有候选生成、搜索图、模型资产和推理，不直接宣称成功。
• repair.model 不依赖训练代码；repair.search 不依赖具体模型实现。
• coordinator 负责循环、比较、资源限制、summary 和最终归档处理。

详细约束见 开发边界说明 和 修复模型与训练边界。

项目是 Python + Rust + C++ 三层协作：

• sunpack/：配置、CLI、调度、规则、verification/repair 决策编排。
• sunpack/repair/model/：发布时使用的模型结构、张量化、推理、资产清单和统一运行时。
• sunpack/repair/search/：修复搜索图、恢复度评估、运行特征和模块提案。
• repair_training/：数据构建、训练和评估工具；允许依赖 sunpack.repair.model，运行时禁止反向依赖训练目录。
• models/：随源码和发行包分发的模型资产，入口为 models/manifest.json。
• native/sunpack_native/：Rust/PyO3 热路径，包括目录扫描、二进制结构分析、repair I/O、CRC/readability、candidate matching、deep repair native 实现等。
• native/sevenzip_bridge/：C++/CMake 7z.dll bridge，提供 probe/test、密码数组尝试、manifest 和 worker 解压。

运行时必须有：

tools\7z.exe
tools\7z.dll
tools\sunpack_sevenzip.dll
tools\sunpack_sevenzip_worker.exe

7z.exe 主要保留给开发 fixture、手工诊断和 7-Zip 文件来源；正式解压后端是 sunpack_sevenzip_worker.exe + 7z.dll。

模型运行时是正式产品代码，不是训练脚本的兼容层：

• models/manifest.json 声明格式、角色、语义、算法、资产目录和 model.pt SHA-256。
• ModelAssetRegistry 在源码目录和打包目录中定位同一份清单，并在加载前验证哈希。
• DiagnosisHGTProvider 和 RepairPolicyTransformerProvider 由程序内置创建，不支持外部 provider_package。
• 当前内置模型支持 ZIP diagnosis 与 repair policy；不支持的格式会明确返回 unavailable。

检查模型：

python sunpack.py models status --load --json

安装测试依赖并运行默认测试：

python -m pip install -e ".[test]"
python -m pytest

验收测试：

.\run_acceptance_tests.ps1

本地 CI 风格检查：

.\scripts\run_ci_tests.ps1

慢速真实归档/性能测试默认不跑，可显式打开：

pytest --run-slow-real-archives
pytest --run-large-archive-performance -s

开发环境和构建说明见 development_setup.md。

注册当前用户右键菜单：

.\scripts\register_context_menu.ps1

默认菜单项会执行：

sunpack extract <目标目录> --ask-pw --pause

取消注册：

.\scripts\unregister_context_menu.ps1

Windows 打包：

.\scripts\build_windows.ps1

常用参数：

.\scripts\build_windows.ps1 -SkipTests
.\scripts\build_windows.ps1 -Clean
.\scripts\build_windows.ps1 -Version 1.2.3

构建脚本会准备 .venv-build，从 pyproject.toml 安装 build extra，构建 Rust wheel 和 C++ bridge/worker，用 PyInstaller 生成 sunpack.exe，复制配置、模型资产、工具和 license，并执行 packaged smoke 与模型加载检查。发行包输出到 release\sunpack-windows-<arch>-<version>.zip。

构建脚本支持 -Arch x64|arm64。x64 是默认值；ARM64 最终可执行文件需要在 ARM64 Windows + ARM64 Python 环境中构建，脚本会静态校验包内所有关键 PE 文件的 machine 架构。已有包可用 .\scripts\verify_windows_package_arch.ps1 -PackageRoot <dist目录> -Arch arm64 在任意 Windows 机器上做静态检查。