v0.5.0 · MIT · Rust

压缩包就是文件树。别再为了看一眼内容而全部解压。

面向 AI Agent 与人类的统一压缩文件访问层。先检视、按需流式读取压缩包内容,再决定是否解压。

12 个格式族 · schema_version "1" · macOS + Linux CI

~/datasets — zsh

$ arcthis inspect dataset.zip archive: dataset.zip format: zip compression: mixed entries: 7 compressed size: 201315 uncompressed size: 200124 random access: true $ arcthis tree dataset.zip dataset.zip └── dataset ├── README.md ├── docs │ └── notes.md └── train ├── data.csv └── labels.csv $ arcthis read dataset.zip dataset/train/labels.csv id,label 1,cat 2,dog 3,bird

01 — 快速开始

三条命令, 从克隆到第一次检视。

v0.5 仅以源码形式发布 —— 尚未上架 crates.io,也没有预编译二进制。RAR 支持会静态链接 libarchive,平台依赖见下载页。

install — zsh

$ git clone https://github.com/mkynyd/arcthis.git $ cd arcthis $ cargo build --release --locked $ ./target/release/arcthis --version arcthis 0.5.0

02 — 标志性指令

一套语法。全部格式。默认零解压。

统一的 arcthis <command> <archive> [entry] 语法覆盖 ZIP、7z、RAR、TAR 与单流编码格式。以下所有会话都是 arcthis 0.5.0 的真实输出。

move / 01

不解码,先查条目

find 把 glob 过滤作用于规范化后的 entry 元数据,完全不读取内容 —— 即使在数 GB 的压缩包上,路径发现也依然便宜。

find

$ arcthis find dataset.zip --glob '**/*.csv' dataset/train/labels.csv dataset/train/data.csv

move / 02

原地搜索内容

grep 以 entry 大小、行、匹配数和二进制探测为界,流式扫描普通文件 —— 搜索过程不写入任何磁盘。

grep

$ arcthis grep dataset.zip TODO --glob '**/*.md' dataset/docs/notes.md:1:TODO: fill in preprocessing notes dataset/README.md:3:Sample training bundle. TODO: document the schema.

move / 03

流式完整性校验

hash 把单个 entry 流式送入 SHA-256 或 SHA-512;verify 用一次全流式通过校验结构与每一个可读 entry。

hash · verify

$ arcthis hash dataset.zip dataset/train/data.csv 3307d48518fd5bc59980caee9f4833a1aef4a3ae7f16ef4102a132b719d947c2 dataset/train/data.csv $ arcthis verify dataset.zip verified 7 entries (200124 bytes)

move / 04

写入是计划好的事务

pack、extract 和 convert 都能输出类型化的 --dry-run 计划;先写入同级暂存位置,验证通过后才提交。

pack --dry-run

$ arcthis pack ./dataset --output dataset.tar.zst --dry-run dry-run pack plan source: ~/demo/dataset destination: dataset.tar.zst format: tar_zstd entries: 7 estimated bytes: 200124 collision: false will skip: false delete source after success: false

move / 05

压缩包里的压缩包

可重复的 --within 沿内层压缩包逐层深入,以有界内存 source 实现,最多 8 层 —— 绝不创建具名临时文件。

tree --within

$ arcthis tree backup.zip --within project.tar.gz backup.zip::project.tar.gz └── dataset ├── README.md ├── docs │ └── notes.md └── train ├── data.csv └── labels.csv

move / 06

默认为 Agent 结构化

每个查询命令都通过 --json 输出 schema 版本化的 JSON:字段稳定、错误类型化写入 stderr、退出码确定。

stat --json

$ arcthis stat dataset.zip dataset/train/labels.csv --json {"schema_version":"1","archive":{"path":"dataset.zip","path_lossy":false,"format":"zip"},"entry":{"archive_index":5,"path":"dataset/train/labels.csv","path_encoding":"utf8","kind":"file","size":28,"compressed_size":28,"modified_time":"2026-08-30T01:05:30","encrypted":false,"executable":false,"symlink_target":null,"crc32":"9e6ad3e5","mime_guess":"text/csv"}}

03 — 格式

十二个格式族, 统一的 archive 模型。

检测以内容优先:误导性扩展名不会覆盖有效签名。格式差异由 backend 吸收,命令看到的是带能力标记的统一模型。

格式	访问 / 解压	创建	访问模型
zip	Stored/Deflate,含 ZipCrypto/AES 解密	Deflate,不加密	随机 entry 访问
7z	支持,含 AES 解密	LZMA2,不加密	取决于 block/solid 结构
rar / rar5	经 libarchive 读取/解压	只读	顺序访问
tar	支持	支持	顺序访问
tar.gz / tgz	支持	支持	顺序解压
tar.bz2 / tbz2	支持	支持	顺序解压
tar.xz / txz	支持	支持	顺序解压
tar.zst / tzst	支持	支持	顺序解压
gzip	单个隐式 entry	支持	顺序访问
bzip2	单个隐式 entry	支持	顺序访问
xz	单个隐式 entry	支持	顺序访问
zstd	单个隐式 entry	支持	顺序访问

04 — Agent 接口

JSON 是契约, 不是包装。

真实结构化输出。每个成功响应都是一份带 schema_version: "1" 的完整 JSON 文档,字段名与类型是公开的版本化接口。
严格的流分离。结果走 stdout;诊断、警告与错误走 stderr。read 输出原始 entry 字节并拒绝 --json。
类型化失败。机器可读错误是带稳定 code 的 JSON,映射到确定的进程退出码。
诚实的成本。inspect 报告 random_access、solid 等能力,Agent 可以在执行前推算操作成本。

响应信封 — schema_version "1"

{
  "schema_version": "1",
  "archive": {
    "path": "dataset.zip",
    "path_lossy": false,
    "format": "zip"
  }
}

unsupported_format invalid_archive corrupted_archive entry_not_found unsafe_path resource_limit password_required wrong_password collision verification_failed partial_failure io_error

05 — 安全模型

默认安全优先于方便。

不可信压缩包是敌意输入。每一条写入路径都保守、可验证、事务化 —— 方便性选项存在,但必须显式声明。

路径

统一路径消毒器

解压拒绝 ..、绝对路径、Windows 盘符/UNC 前缀、NUL 字节,以及可能越界的链接。

写入

先暂存,再提交

输出先写入同级暂存位置,全部 entry 成功后才提交;失败不会留下伪装成成功的半成品。

冲突

默认拒绝

已存在的目标默认拒绝;--overwrite、--skip-existing、--rename 三选一且必须显式指定。

删除

最后才删源文件

--delete-source 只在 perform → finalize → verify → commit 完成后执行;任何错误、中断或验证失败都保留源文件。

06 — MCP

同样的语义, 直接接入你的 Agent 运行时。

有界 stdio server。可选的 feature-gated MCP 前端,协议固定 2025-06-18,stdout 严格纯净。
九个只读工具:inspect、list、tree、stat、read、find、grep、hash、verify —— 在显式 --allow-root 下始终可用。
六个变更工具(extract/pack/convert 的 plan + execute)只在声明 --allow-output-root 策略后出现。
过期计划拒绝执行。source 或 destination 状态变化会使 SHA-256 plan digest 失效。

mcp — zsh

$ cargo build --release --locked --features mcp $ arcthis mcp --allow-root ./archives # read-only tools only $ arcthis mcp --allow-root ./archives --allow-output-root ./outputs # plan/execute mutation tools become visible

先访问,再解压。先流式,再物化。

从源码构建 v0.5.0,一分钟内完成第一次检视。

$ cargo install --path . --locked

下载阅读文档