Arcthis
EN 下载

v0.6.0 · MIT · Rust

压缩包就是文件树。不必全部解压。

查看、读取、搜索、创建和转换压缩文件。支持命令行、JSON 输出和本地 AI Agent。

下载 文档

12 种格式 · JSON 输出稳定 · macOS + Linux 自动化测试

~/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.6.0 已通过 Cargo、Homebrew、npm 与 pnpm 发布,所有安装方式默认都包含 MCP。其他安装方法与编译成品见下载页。

install — zsh
$ brew install mkynyd/tap/arcthis
02 — 招牌功能

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

使用 arcthis <command> <archive> [entry] 查看、读取和管理 ZIP、7z、RAR、TAR 及单文件压缩格式。

move / 01

不解压,先查文件

find 按通配符匹配文件清单中的路径。顺序压缩格式需要先扫描清单,查询结果不会写出文件。

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

原地搜索内容

grep 逐行搜索压缩包内的文本,限制文件大小、行长度、匹配数量和结果总量。默认跳过二进制文件。

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 计算单个文件的 SHA-256 或 SHA-512 校验值;verify 从头到尾读一遍,一次性校验压缩包结构和每个可读文件。

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 可以重复使用,逐层进入压缩包里的压缩包,全程在内存中完成,最多 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 都会输出带版本号的 JSON:字段保持稳定,错误有固定类型并写入 stderr,退出码也是确定的。

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

十二种格式, 同一套使用方式。

识别格式看内容,不看扩展名:改错的扩展名骗不过它。不同格式的差异在底层各自处理,你面对的是统一的行为和诚实的能力说明。

格式访问 / 解压创建读取方式
zipStored/Deflate,含 ZipCrypto/AES 解密Deflate,不加密可直接读取任意文件
7z支持,含 AES 解密LZMA2,不加密取决于压缩结构
rar / rar5支持(经 libarchive)只读需从头读到尾
tar支持支持需从头读到尾
tar.gz / tgz支持支持需从头解压
tar.bz2 / tbz2支持支持需从头解压
tar.xz / txz支持支持需从头解压
tar.zst / tzst支持支持需从头解压
gzip单个文件支持需从头读到尾
bzip2单个文件支持需从头读到尾
xz单个文件支持需从头读到尾
zstd单个文件支持需从头读到尾
04 — Agent 接口

JSON 输出, 字段稳定、版本明确。

  • 真实结构化输出。每个成功响应都是一份带 schema_version: "2" 的完整 JSON 文档,字段名与类型是公开的版本化接口。
  • 输出严格分流。结果走 stdout;诊断、警告和错误走 stderr。read 输出原始文件内容,并且拒绝 --json。
  • 错误有固定类型。给程序读取的错误是带固定代码的 JSON,对应确定的退出码。
  • 诚实的成本。inspect 报告 random_access、solid 等能力,Agent 可以在执行前推算操作成本。
响应结构 — schema_version "2" 
{
  "schema_version": "2",
  "archive": {
    "path": "/data/dataset.zip",
    "path_lossy": false,
    "index_used": 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 字节,以及可能跳出目标目录的链接。

写入

先写临时文件,再正式保存

输出先写到旁边的临时位置,全部文件成功后才正式保存;失败不会留下看似完整的半成品。

冲突

默认拒绝

目标已存在时需明确选择覆盖、跳过或改名。源和目标互相包含时拒绝写入;批处理也会检查不同压缩包之间的路径冲突。

删除

最后才删源文件

--delete-source 只在新文件写入、验证并正式保存之后才执行;任何错误、中断或验证失败都会保留源文件。

06 — MCP

同样的能力, 直接接入你的 AI Agent。

  • 内置 MCP 服务。通过本地标准输入输出与 AI Agent 连接,所有安装方式均包含。
  • 九个只读工具:inspect、list、tree、stat、read、find、grep、hash、verify —— 用 --allow-root 明确授权目录后始终可用。
  • 六个修改类工具(extract/pack/convert,先出计划再执行)只有用 --allow-output-root 明确授权输出目录后才会出现。
  • 计划后再执行。源文件或目标位置改变时拒绝旧计划。客户端只能收紧服务端的文件数和解码上限。
  • 可配置的调用限制。默认同时处理 4 个调用,每次工具响应最多 16 MiB。grep 默认最多保留 16 MiB 匹配结果。
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.6.0,开始查看和管理压缩文件。

$ brew install mkynyd/tap/arcthis
下载 阅读文档