tzst

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

此技能仅适用于 CLI。如果用户询问的是 from tzst import ... 之类的 Python 代码，请将其视为常规 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 中的独立发行版二进制文件
3. 执行实际操作前，重新运行 tzst --version 或 tzst --help。

工作流

1. 判断请求是要执行操作还是获取指导。 “归档这些文件”“解压此备份”“列出其中的内容”“测试此归档”或“安装 tzst”之类的请求，都属于执行意图。
2. 选择与请求相符的命令：
   • 创建归档：a、add、create
   • 常规解压并保留目录结构：x、extract
   • 仅在用户明确要求展平输出时使用：e、extract-flat
   • 检查归档：l、list
   • 完整性检查：t、test
3. 如果用户只想提取少数几个成员，且成员名称不确定，请先列出内容。
4. 需要命令对照表、准确的标志名称或可直接复制粘贴的示例时，请加载 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 的帮助信息