tzst

name: tzst
description: 当用户需要为 `.tzst` 或 `.tar.zst` 存档创建、提取、展平、列出、测试、安装、编写脚本或排查 `tzst` CLI 工作流时使用，包括压缩级别、流式模式、提取过滤器、冲突解决、JSON 输出或独立二进制设置，即使他们在描述存档任务时没有提及 `tzst`。

使用此技能处理 tzst 命令行界面。当用户明确需要执行真实的归档操作，且所需路径或归档名称已知时，默认执行。

此技能仅限命令行界面。如果用户询问 Python 代码（例如 from tzst import ...），则将其视为一般的 Python 库或 API 文档任务，不要以此技能作为主要指南。

何时使用

在以下情况下使用此技能：

• 用户提到 .tzst 或 .tar.zst 归档
• 用户想要创建、提取、扁平化、列出或测试 tzst 归档
• 用户需要安装 tzst 的帮助或选择 CLI 标志
• 用户需要机器可读的 tzst 输出以用于脚本或自动化
• 用户需要安全冲突处理或提取过滤器指导

除非 tzst 是请求的一部分，否则不要将此技能用于通用的 tar、zip 或 Python API 问题。

前置检查

1. 使用 tzst --version 或 tzst --help 检查 tzst 是否可用。
2. 如果缺失，优先选择以下安装路径之一：

• uv tool install tzst
• pip install tzst
• 当用户不希望进行 Python 安装时，从 <https://github.com/xixu-me/tzst/releases/latest> 下载独立的发布二进制文件

1. 在执行实际操作前，重新运行 tzst --version 或 tzst --help。

工作流程

1. 判断请求是执行还是指导。

诸如“归档这些文件”“提取此备份”“列出内容”“测试此归档”或“安装 tzst”之类的请求属于执行意图。

1. 选择与请求匹配的命令：

• a、add、create 用于创建归档
• x、extract 用于保留目录结构的常规提取
• e、extract-flat 仅当用户明确要求扁平化输出时使用
• l、list 用于检查归档
• t、test 用于完整性检查

1. 如果用户只想提取少数成员且成员名称不确定，先列出内容。
2. 当你需要命令矩阵、确切标志名称或可复制示例时，请参考 references/cli-reference.md。

安全默认值

• 除非明确要求扁平化，否则优先使用 x 而非 e。
• 保持 --filter data 作为默认提取模式。
• 仅当用户需要标准的 tar 风格兼容性时，才使用 --filter tar。
• 仅当用户明确说明归档来源完全可信时，才使用 --filter fully_trusted。
• 保持原子归档创建启用。仅当用户明确要求时，才使用 --no-atomic。
• 对于大型归档或内存受限环境，优先使用 --streaming。
• 对于自动化或管道，优先使用 tzst --json --no-banner ...。
• 对于自动提取，要求显式指定非交互式的 --conflict-resolution 选项，例如 replace_all、skip_all 或 auto_rename_all。
• 不要将 --json 与交互式冲突提示结合使用。

脚本注意事项

• 在示例中，将全局标志放在子命令之前，例如 tzst --json --no-banner l archive.tzst。
• 在脚本中使用退出码：0 表示成功，1 表示操作错误，2 表示参数解析错误，130 表示中断。
• 当归档命名很重要时，告知用户 tzst 可能会将创建目标规范化为 .tzst 或 .tar.zst。

常见错误

• 使用 e 但用户期望保留原始目录结构
• 为未知或不可信来源的归档推荐 fully_trusted
• 忘记为非交互式提取指定显式的冲突策略
• 将 Python API 问题当作 CLI 问题处理
• 根据 tar 习惯猜测标志，而不是检查附带的参考或已安装的 CLI 帮助