文档 · v0.6.0 · schema_version "2"
CLI 用法说明, 以已实现的为准。
本页对应 0.6.0（schema 2）；0.5.1 使用 schema 1，升级前请核对接口迁移。还在规划中的功能会标记 planned。完整长篇指南是仓库里的 START.zh-CN.md。
命令语法
一套与格式无关的语法。没有 ZIP 专属或 TAR 专属的一级命令。
arcthis <command> <archive> [entry] [options]
默认工作流是先访问,再解压:inspect → tree/list → stat/read → 只 extract 真正需要的内容。完整解压始终是显式操作。
输出规则
两种输出严格分开,让脚本和 AI Agent 可以安全地调用 Arcthis。
- stdout 只承载结果数据;stderr 承载诊断、警告与进度。
--json让支持的命令输出给程序读取的 JSON;read始终输出原始文件内容,并且拒绝--json。- JSON 输出和不接终端时的输出都不含颜色等终端装饰。在终端里可以用
--no-color或NO_COLOR关闭颜色。 - 管道另一端的程序提前退出(比如
| head)不算错误 ——arcthis read a.zip big.bin | head的退出码为 0。 - 非 UTF-8 的文件名会通过
path_encoding字段如实标出;默认抽取拒绝未解码名字，可显式 --encoding 严格解码后再检查。
全局选项
放在子命令之前,出自 arcthis --help。
| 选项 | 默认值 | 含义 |
|---|---|---|
| --json | 关 | 在支持的命令上输出稳定的机器可读 JSON |
| --no-sync | 默认逐文件 fsync | extract/extract-all/convert 跳过逐文件 fsync；保留暂存与回滚，降低掉电耐久性 |
| --entry-index <N> | — | 精确选择 stat/read/hash/extract 的实例，仅作用于 within 最终层 |
| --encoding <name> | — | 严格 utf8/cp437/gbk/shift-jis 解码，继续检查路径与冲突 |
| --stdin-name <name> | stdin | 只读标准输入源 - 的虚拟文件名 |
| --max-stdin-bytes <bytes> | 64 MiB | 限制实际缓冲的 stdin 压缩字节 |
| --no-color | 关 | 禁用终端颜色装饰 |
| --within <entry> | — | 进入压缩包内的某个压缩包;可重复使用以逐层深入(最多 8 层) |
| --max-nested-entry-size <bytes> | 268435456 | 嵌套压缩包中单个文件允许占用的最大内存(字节) |
| --password-file <path> | — | 从文件读取压缩包密码(自动去掉行尾换行);密码绝不直接写在命令行里 |
| --volume <path> | — | 添加一个分卷压缩包文件;需按分卷顺序逐个添加 |
| --index-directory <path> | 平台缓存目录 | 更改索引文件的存放位置(默认用系统缓存目录) |
命令
命令签名来自实际 CLI,说明来自 arcthis --help。
展示压缩包的基本信息、能力和风险提示:文件数量、大小、压缩率,以及 random_access(能否随机读取)、solid(是否整体压缩)、encrypted(是否加密)等能力标记 —— 足以让 Agent 在执行前估算一次操作要付出的代价。
保留归档顺序与全部重名实例，包括 ZIP。命名访问遇到歧义返回 collision；--entry-index 按 archive_index 选择实例。
以文件树展示压缩包内容。JSON 输出为嵌套的 tree 数组。每条路径最多 4096 字节、256 层,超限返回 resource_limit。
展示条目元数据；--verbose 增加原始名、CRC、时间与编码信息。可按 --entry-index 选择；只有一个普通文件时可省略 entry。未知元数据为 null。
默认直接流式输出原始字节；CRC 失败前可能已有部分输出，必须检查退出码。--verify-first 先在匿名临时文件中完整校验，再写 stdout，实际大小默认最多 4 GiB。read --json 在读取源或密码前返回 invalid_argument/2。
按通配符查找路径匹配的文件。只对完整路径做匹配,完全不读取文件内容。
直接搜索文件中的文字。默认单个文件最多 16 MiB、10,000 条匹配、单行保留 1 MiB。--max-result-bytes 限制跨文件的结果总量,默认 16 MiB;省略的匹配会标记 matches_truncated。默认跳过二进制文件,可用 --binary 开启。 ZIP/TAR/7z/RAR 复用一次内容遍历与有界结果预算。
计算单个文件的校验值,默认 SHA-256,也支持 SHA-512。结果是小写十六进制。
有效缓存自动用于查询，archive.index_used 显示命中。--list 列出缓存；--prune 清理失效或过期索引，可配 --dry-run 和 --max-age-seconds（默认 30 天）。只操作索引目录内哈希命名的 JSON；Unix 额外核验 ctime/dev/inode。
安全地解压全部内容或指定的单个文件。先完整检查一遍文件清单;解压结果先写到旁边的临时位置,全部成功后才正式保存。相关选项:--dry-run、--delete-source,以及 --overwrite / --skip-existing / --rename 三选一。 安全规范化 ./；同名与规范化后冲突仍拒绝。--no-sync 可显式降低 fsync 开销，成功删除源文件会有回执。
有界并行处理，结果排序固定。--continue-on-error 隔离坏档、规划错误与路径冲突，继续执行独立好档；部分失败返回 12，JSON 保留逐档结果。dry-run 也会报告错误清单。
把文件或目录打包成压缩包并验证。先在旁边生成临时文件,再重新打开逐个校验内容,全部通过后才保存为正式结果。输出路径位于被压缩的目录内部、或与源是同一个文件,都会被拒绝。 --strip-root 只打包目录内容；输出权限遵循 umask，Gzip 写入 FNAME/mtime。
从头到尾完整读一遍,校验压缩包结构和每个可读文件的数据。JSON 输出会附带含 verified、entries_checked、bytes_checked 的 verification 对象。
把压缩包转换成另一种格式:先安全地解压到临时位置,再打包并校验。文件路径保持不变;写入磁盘前先完成资源与路径安全检查;新压缩包验证通过并正式保存后,--delete-source 才可能删除原文件。
提供本地 MCP 服务,协议版本 2025-06-18。授权输入目录后可用九个只读工具;授权输出目录后增加 extract、pack、convert 的六个计划与执行工具。删除源文件需服务配置和请求同时允许。 schema 2 与 CLI 共享只读结构和错误信封。只读请求可传授权根内的 password_file（最多 4096 字节），不接受明文 password；支持 entry_index。干净 EOF 退出 0；mcp --json 返回参数错误。
--max-concurrent-requests 默认 4,允许 1–64;--max-response-bytes 默认 16 MiB,计算工具结果中的 JSON 和文本副本。单次请求另有上限:--max-entries 100,000、--max-decoded-bytes 1 GiB、--max-results 10,000 条 find/grep 结果、--max-read-window 1 MiB(单次 archive_read 窗口)。超限返回 resource_limit。客户端无法提高服务端限额,MCP grep 的结果上限还受响应大小约束。
JSON 与错误
每个成功的结构化响应都是一份 JSON 文档加一个换行。各命令特有的字段会加在共享的基本结构上。
{
"schema_version": "2",
"archive": {
"path": "/data/dataset.zip",
"path_lossy": false,
"index_used": false,
"format": "zip"
},
"entry": {
"archive_index": 42,
"path": "train/data.csv",
"path_encoding": "utf8",
"path_raw_hex": "747261696e2f646174612e637376",
"kind": "file",
"size": 1048576,
"compressed_size": 182341,
"modified_time": null,
"modified_time_local": "2026-08-27T12:00:00",
"encrypted": false,
"executable": false,
"symlink_target": null,
"crc32": "c0ffee00",
"mime_guess": "text/csv"
}
}
使用 --json 时,命令错误以 JSON 写入 stderr,stdout 保持为空:
{ "schema_version": "2", "error": { "code": "entry_not_found", "message": "archive entry was not found", "details": { "entry": "README.md" } } }
稳定错误类别:
schema 2 将 executable 改为可空，modified_time_local 与绝对 RFC3339 时间分开，path_raw_hex 保留 adapter 暴露的名字字节。solid 7z 的共享压缩大小为 null，比例限制按块计算。CLI/MCP 共用只读结构；文件源引用是绝对路径，stdin/nested 保留虚拟引用。 ADR 0002
退出码
每种错误类别对应一个固定的退出码。
| 退出码 | 类别 |
|---|---|
| 0 | 成功,包括 BrokenPipe 消费方停止 |
| 1 | 一般 I/O 错误 |
| 2 | 命令行语法 / invalid_argument |
| 3 | unsupported_format / not_an_archive |
| 4 | invalid_archive 或 corrupted_archive |
| 5 | entry_not_found |
| 6 | permission_denied |
| 7 | unsafe_path |
| 8 | resource_limit |
| 9 | collision |
| 10 | unsupported_operation、密码类错误 |
| 11 | verification_failed |
| 12 | partial_failure |
资源限制
解压时检查实际输出字节,查询与 MCP 另有调用和结果限制。
| 选项 | 默认值 |
|---|---|
| --max-entries | 100,000 |
| --max-total-size | 16 GiB |
| --max-entry-size | 4 GiB |
| --max-compression-ratio | 未指定则不启用 |
| --max-entry-duration-seconds | 未指定则不启用 |
| grep --max-result-bytes | 16 MiB |
| mcp --max-entries | 100,000 |
| mcp --max-decoded-bytes | 1 GiB |
| mcp --max-results | 10,000 |
| mcp --max-read-window | 1 MiB |
| mcp --max-concurrent-requests | 4 |
| mcp --max-response-bytes | 16 MiB |
安全默认值
简短版;精确保证与已知限制见 docs/SECURITY.md。
- 路径检查。统一的检查会拒绝
..、绝对路径、Windows 盘符/UNC 前缀、NUL 字节,以及可能跳出目标目录的链接。 - 不自动恢复链接和特殊文件。符号链接、硬链接和特殊文件默认不恢复。
- 写入要么完整生效,要么不生效。先写临时文件再正式保存;pack 会重新打开新压缩包逐个验证,通过后才放到你指定的位置。
- 重叠检查。所有写入都拒绝源和目标相同或互相包含;批处理同时检查不同压缩包之间的路径冲突。
- 最后才删源文件。
--delete-source只在新文件写入、验证并正式保存之后才运行;错误、中断和验证失败都会保留源文件。dry-run 不写入也不删除。 - 密码不出现在命令行参数里。密码只能来自
--password-file指定的文件,在调试输出中也会被隐藏。
Planned
以下功能仍在规划中。详见 ROADMAP.md。