tzst

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

此技能仅适用于 CLI。如果用户询问的是 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 获取独立发布二进制文件
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 帮助