tzst

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

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

此技能仅适用于 CLI。如果用户询问的是 Python 代码，例如 from tzst import ...，则将其视为通用的 Python 库或 API 文档任务，而不是以此技能作为主要指导。

使用时机

当用户出现以下情况时使用此技能：

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

请勿将本技能用于通用的 tar、zip 或 Python API 问题，除非 tzst 确实属于请求的一部分。

前置检查

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 帮助