LibACG 项目的压缩包处理插件，封装 7-Zip 命令行工具，支持 ZIP / RAR / 7Z 解压、密码处理、文件过滤，跨平台自动安装。

• 多格式解压 — ZIP、RAR、7Z 等 7-Zip 支持的所有格式
• 密码支持 — 加密压缩包解压
• 文件过滤 — include / exclude 模式精确控制
• 自动安装 — 检测并自动下载 7-Zip（Windows 优先 winget）
• 跨平台 — Windows / Linux / macOS，amd64 / arm64
• Pipeline 集成 — 作为 LibACG 插件提供 check_archive 和 extract_archive 两个 Stage

pip install libacg-7zip

要求：Python >= 3.14

from pathlib import Path
from libacg_7zip import SevenZipClient, install_7zip

# 自动定位或安装 7-Zip
exe = install_7zip()
client = SevenZipClient(executable=exe)

# 解压
client.extract(Path("archive.zip"), Path("output"))

# 带密码
client.extract(Path("encrypted.7z"), Path("output"), password="secret")

# 只解压特定文件
client.extract(Path("archive.zip"), Path("output"), include=["*.txt"])

# 查看内容
file_count, folder_count = client.list_contents(Path("archive.zip"))

插件注册了两个 Stage：

Stage	说明
check_archive	检查压缩包内容（文件/文件夹数量）
extract_archive	解压压缩包到指定目录

预构建 Job extract_and_check：先检查再解压。

libacg job run extract_and_check \
  --input archive_path=/path/to/archive.zip \
  --input output_dir=/path/to/output

所有异常继承自 ArchiveError：

异常	说明
ExtractionFailedError	解压失败（含退出码和 stderr）
ToolNotFoundError	7-Zip 未找到且无法自动安装
InstallationFailedError	自动安装失败
ArchiveNotFoundError	压缩包文件不存在
PasswordRequiredError	需要密码但未提供
CorruptArchiveError	压缩包损坏

• 架构说明 — 软件框架与模块设计
• 使用指南 — 完整的用法参考
• AGENTS.md — AI 助手开发规范

MIT License