# Extractly **Repository Path**: iLester/extractly ## Basic Information - **Project Name**: Extractly - **Description**: macOS 原生可视化解压工具。纯 Swift/SwiftUI + 进程内 libarchive,零外部二进制、免完整 Xcode。自动判定文件名编码(GBK/Big5…)不乱码;按白名单放行 ZIP/TAR/RAR/RAR5/7z/CPIO,拦下 iso/cab/lha/xar。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-10 - **Last Updated**: 2026-11-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: macOS, 解压, 不乱码 ## README # Extractly > macOS 原生**可视化解压工具**:拖进去就解开,中文名不乱码,危险包先拦下。Swift/SwiftUI + **进程内 libarchive** 架构,**无需 Xcode 即可构建**。 --- ## 为什么做这个 macOS 自带的「归档实用工具」有两个长期痛点: 1. **中文名乱码** —— 包内文件名按本地代码页(GBK、Big5等)存储时,`Archive Utility` 直接按 UTF-8 解释,解出来是乱码。 2. **不设闸门** —— 双击 `../` 越界条目、加密包、非压缩文件,要么静默失败,要么行为不可预期。 Extractly 针对这两点:**自动判定文件名编码并还原**,同时把**格式支持度**做成显式的分层闸门(支持 / 支持但有注意事项 / 不支持)。 ## 特性 - **文件名编码自动判定**:可解码性(硬门槛)+ 往返一致性 + **常用字集命中加成**。 单靠「能解码」不够 —— GBK 字节按 Big5 也能解出合法但生僻的字(`笢恅聆彸恅璃`);必须用常用字集拉开分差。 - **路径三态安全**:`./` 这类归一化后为空的静默跳过;`../` 越界计入 `unsafeRejected`;绝对路径收敛为相对路径。 - **分层格式闸门**: - `reason`=**阻塞** —— 红横幅 + 禁用解压 + `仍要尝试` 越权开关(CLI:exit 3 且不落盘) - `caution`=**非阻塞** —— 琥珀横幅说明已知边界,解压照做 - **Finder 右键集成**:选中压缩包 → 右键「快速操作/服务」→「用 Extractly 解压」,自动解到同名文件夹。 - **重名冲突策略**:`rename` 生成 `中文测试文件 (1).txt`,不覆盖用户已有文件。 ### 格式支持矩阵 | 格式 | 判定 | 实测 | |---|---|---| | ZIP(store/deflate) | ✅ 支持 | ✅ | | TAR 系(ustar/pax/gnu,含 .tar.gz/.bz2/.xz/.zst) | ✅ 支持 | ✅ | | **RAR / RAR5** | ✅ 支持 | ✅ | | **7-Zip (.7z)** | ✅ **支持 · 有注意事项** | ✅ **LZMA2 / copy / BCJ(x86) 三类已测试;⚠️ BCJ2 / PPMd / 分卷 / AES 加密未验证 | | CPIO | ✅ 支持 | ⚠️ 未测试 | | 单文件压缩流(裸 .gz/.bz2/.xz/.zst,内容非 tar) | ✅ 支持 | ✅ | | 普通未压缩文件 / iso / cab / lha / xar / 无法识别 | ⛔️ 跳过 | ✅ | ## 仓库结构 按大厂开源项目惯例组织(2026-11-17 重构): ``` . ├─ Sources/ 源码 │ ├─ App/ SwiftUI 界面 + Finder 右键服务 │ ├─ ArchiveKit/ 纯 Swift 领域层(可单测):格式闸门 / 编码打分 / 路径安全 / 两遍法读写 │ ├─ CArchive/ la_shim.{h,c} 薄垫片:唯一与 libarchive 交互的出口,格式显式白名单注册 │ └─ CLI/ unarchiver-cli:无 GUI 验证器(probe / list / extract) ├─ Resources/ Info.plist、图标生成器 make_icon.py 与图标产物 ├─ scripts/ build.sh / selftest.sh / install.sh ├─ tests/ │ ├─ fixtures/ 回归样本(生成器可一键重建) │ ├─ generators/ 样本生成器(zip/rar4/7z) │ └─ probes/ 调研验证期探针脚本(历史证据,不再演进) ├─ docs/ 调研 / 方案 / 验证记录 / 实现详解 / 项目梳理(决策证据链完整保留) ├─ Makefile 统一工程入口 ├─ CHANGELOG.md 版本变更记录 └─ CONTRIBUTING.md 开发方法论(分支模型 / 提交规范 / 发布流程) ``` ## 构建与运行 ```bash make build # 或 bash scripts/build.sh → Extractly.app(根目录便捷副本)+ .build/unarchiver-cli make test # 集成自测(46 项断言 / 11 组场景,视可选样本 40–46 项) make install # 可选:装到 /Applications + ad-hoc 签名 + 注册右键服务 open Extractly.app ./.build/unarchiver-cli list tests/fixtures/sample-gbk.zip ./.build/unarchiver-cli extract foo.iso /tmp/out # → 被闸门拦下,exit 3 ./.build/unarchiver-cli extract foo.iso /tmp/out --force # → 越权尝试 ``` ### 环境要求 - macOS 14.0+(`LA_MIN` 可覆盖) - Xcode **命令行工具**(`swiftc` / `cc` / `iconutil` / `codesign`)—— **不需要完整 Xcode** - 系统自带 `/usr/lib/libarchive.2.dylib`(dyld 共享缓存提供,3.7.4) 可用环境变量覆盖:`LA_SDK`(默认 `…/MacOSX15.5.sdk`)、`LA_MIN`、`LA_ARCH`。 ## 已知边界 - 7z:**BCJ2**(不是 BCJ)/**PPMd**/**分卷**/**AES 加密** 未验证(本机暂无样本); 加密包能**识别并告警**,但 **v1 未做口令输入**。 - 未做:内容转码(编码修正只覆盖**文件名**)、分卷归档、Finder Sync 扩展(须正式签名)、代码公证、沙箱版打包。 - 右键服务只出现在「**快捷操作 / 服务**」**子菜单**,不是顶层菜单项 —— 顶层需要 Finder Sync 扩展。 macOS 10.14+ 对第三方 App 的服务**默认置为「关闭」**,本 App 每次启动自检并自行启用(详见 `docs/implementation.md`)。 ## 开发流程 - **分支模型**:`main` 为稳定发布线,`dev` 为日常集成线;发布=dev 自测绿 → 合并 main → 打 tag。 - **提交规范**:Conventional Commits(`feat:` / `fix:` / `docs:` / `refactor:` / `test:` / `build:` / `chore:`)。 - **质量门槛**:合入前 `make test` 全绿;新功能必须同步新增自测断言。 - 详见 [`CONTRIBUTING.md`](CONTRIBUTING.md),版本历史见 [`CHANGELOG.md`](CHANGELOG.md)。 ## 许可 未声明开源许可,**保留所有权利**。 --- 更详细的实现要点、踩坑记录与验证证据见 [`docs/implementation.md`](docs/implementation.md)、 [`docs/verification/验证记录.md`](docs/verification/验证记录.md) 与 [`docs/design/macOS可视化解压工具-细化方案.md`](docs/design/macOS可视化解压工具-细化方案.md)。 项目全景速览见 [`docs/PROJECT.md`](docs/PROJECT.md)。