文档 · v0.5.0 · schema_version "1"
CLI 契约, 以已实现为准。
本页描述的都是 Arcthis 0.5.0 已实现、已测试的行为。仍在 roadmap 上的能力会标记 planned。权威长篇指南是仓库里的 START.zh-CN.md。
命令语法
一套与格式无关的语法。没有 ZIP 专属或 TAR 专属的一级命令。
arcthis <command> <archive> [entry] [options]
默认工作流是先访问,再解压:inspect → tree/list → stat/read → 只 extract 真正需要的内容。完整解压始终是显式操作。
输出契约
严格的流分离,让脚本和 Agent 可以安全地驱动 Arcthis。
- stdout 只承载结果数据;stderr 承载诊断、警告与进度。
--json在有结构化结果的命令上选择机器输出;read始终输出原始 entry 字节并拒绝--json。- JSON 与非 TTY 输出不含任何 ANSI 装饰。
--no-color与NO_COLOR可在 TTY 中禁用颜色。 - stdout 的
BrokenPipe被视为消费方正常提前结束 ——arcthis read a.zip big.bin | head退出码为 0。 - 非 UTF-8 的 entry 名通过
path_encoding显式报告;解压拒绝字节转义路径,避免物化出错误的文件名。
全局选项
放在子命令之前,出自 arcthis --help。
| 选项 | 默认值 | 含义 |
|---|---|---|
| --json | 关 | 在支持的命令上输出稳定的机器可读 JSON |
| --no-color | 关 | 禁用终端颜色装饰 |
| --within <entry> | — | 深入指定的压缩包 entry;可重复以逐层下钻(深度上限 8) |
| --max-nested-entry-size <bytes> | 268435456 | 每个嵌套压缩包 entry 允许缓冲的最大解码字节数 |
| --password-file <path> | — | 从文件读取压缩包密码,去除尾部 CR/LF;密码永远不作为命令行参数值 |
| --volume <path> | — | 追加一个字节流压缩包分卷;按精确分卷顺序重复使用 |
| --index-directory <path> | 平台缓存目录 | 覆盖持久索引使用的平台缓存根目录 |
命令
签名来自 CLI 契约,说明来自 arcthis --help。
展示压缩包元数据、能力与风险警告。报告 entry 数、大小、压缩率、稳定结构的警告,以及 random_access、solid、encrypted 等能力布尔值 —— 足以让 Agent 在付出成本之前估算一次操作的代价。
按压缩包内顺序列出 entry,保留重复项。JSON 增加完整 entry 对象的 entries 数组。
以文件树形式展示压缩包条目。JSON 增加递归的 tree 节点数组;隐式目录的 entry 为 null。
展示单个 entry 的元数据:类型、大小、压缩后大小、修改时间、加密、CRC-32,以及基于扩展名的轻量 MIME 猜测。路径不存在返回 entry_not_found;路径重复返回 collision,因为选择有歧义。
把单个普通文件 entry 流式写入 stdout。这是组合原语 —— 压缩包内容可以直接接入你已有的工具:
arcthis read source.zip src/lib.rs | rg unsafe · arcthis read media.zip video.mp4 | ffprobe -i pipe:0
查找路径匹配 glob 的 entry。匹配作用于完整规范化 entry 路径,绝不读取 entry 内容。
不解压直接搜索普通文件内容。字面量(非正则)匹配,流式执行且有界:单 entry 16 MiB、10,000 条匹配、单行保留上限 1 MiB,并以 8 KiB NUL 探测跳过二进制文件,除非指定 --binary。
把单个 entry 流式送入密码学 hash。默认 SHA-256,也实现了 SHA-512。digest 为小写十六进制。
创建、刷新、检查或删除持久 entry 元数据索引。索引被视为不可信缓存输入,按源文件大小与修改时间失效。
安全地解压全部 entry 或单个选定普通文件。先执行完整的元数据预检;写入同级暂存位置,全部成功后才提交。生命周期选项:--dry-run、--delete-source,以及 --overwrite / --skip-existing / --rename 三选一。
安全地解压目录中发现的每一个受支持压缩包。跨独立压缩包的有界并行,结果确定性排序;dry-run 为每个发现的压缩包返回一份类型化计划。
创建并验证受支持的压缩包或单流文件。临时同级压缩包先 finalize,再经由正常 archive 接口重新打开并逐 entry 验证,之后才会提交。输出位于目录源内、或任何源/目标别名,都会被拒绝。
以一次全流式通过校验压缩包结构与可读 entry 数据。JSON 增加含 verified、entries_checked、bytes_checked 的 verification 对象。
经由安全暂存解压与验证打包完成格式转换。保留 entry 路径,任何物化之前先执行解压资源与路径校验;目标先验证再提交,之后才可能有 --delete-source。
通过 stdio 提供有界的本地 Model Context Protocol 前端(feature 构建,协议固定 2025-06-18)。九个只读工具始终可用;六个 extract/pack/convert 计划/执行工具只在显式输出策略下才会出现。删除源文件需要 --allow-source-deletion 与请求中的 delete_source: true 双重授权。
JSON 与错误
每个成功的结构化响应都是一份 JSON 文档加换行。命令专属字段扩展共享信封。
{ "schema_version": "1", "archive": { "path": "dataset.zip", "path_lossy": false, "format": "zip" }, "entry": { "archive_index": 42, // 稳定的源内顺序 "path": "train/data.csv", "path_encoding": "utf8", // 或 "escaped_bytes"(%XX) "kind": "file", "size": 1048576, "compressed_size": 182341, "modified_time": "2026-08-27T12:00:00Z", "encrypted": false, "crc32": "c0ffee00", "mime_guess": "text/csv" // 基于扩展名,绝不读取内容 } }
使用 --json 时,命令错误以 JSON 写入 stderr,stdout 保持为空:
{ "schema_version": "1", "error": { "code": "entry_not_found", "message": "archive entry was not found", "details": { "entry": "README.md" } } }
稳定错误类别:
退出码
错误类别到进程退出状态的确定性映射。
| 退出码 | 类别 |
|---|---|
| 0 | 成功,包括 BrokenPipe 消费方停止 |
| 1 | 一般 I/O 错误 |
| 2 | clap 的 CLI 语法/用法错误 |
| 3 | unsupported_format |
| 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 |
资源限制
限制在真实的写入/解码路径上强制执行 —— 不是只在检视时给出警告。
| 选项 | 默认值 |
|---|---|
| --max-entries | 100,000 |
| --max-total-size | 16 GiB |
| --max-entry-size | 4 GiB |
| --max-compression-ratio | 未指定则不启用 |
| --max-entry-duration-seconds | 未指定则不启用 |
安全默认值
简短版;精确保证与已知限制见 docs/SECURITY.md。
- 路径消毒。统一消毒器拒绝
..、绝对路径、Windows 盘符/UNC 前缀、NUL 字节,以及可能越界的链接。 - 不隐式恢复链接与特殊文件。symlink、hardlink 与特殊文件默认不恢复。
- 事务化写入。暂存加提交;pack 先 finalize、重新打开并验证,之后请求的输出才出现。
- 别名与重叠检查。破坏性生命周期在写入前拒绝源/目标的文件系统别名与祖先/后代重叠。
- 最后才删源文件。
--delete-source只在 perform → finalize → verify → commit 后运行;错误、中断与验证失败都保留源文件。dry-run 不写不删。 - 密码不进 argv。密码只能来自
--password-file,并在 library 调试输出中脱敏。
Planned
v0.5.0 未实现 —— 列在这里是为了让 Agent 不必猜测。每一项都需要配套的 library 支持、JSON schema、测试与文档之后才会成为公开行为。详见 ROADMAP.md。