tzst

tzst skill 概览

tzst skill 能帮你做什么

tzst skill 是一份面向 tzst 命令行工具的实用指南，帮助你创建、查看、测试以及解压 .tzst 和 .tar.zst 压缩归档。它尤其适合这样一种场景：你已经知道要处理哪些文件路径，只需要尽快拿到正确的命令、参数和更稳妥的操作方式，而不是从通用提示里慢慢试错。

谁适合使用 tzst

这个 tzst skill 适合开发者、运维用户以及自动化流程构建者：如果你需要为本地文件、脚本、CI 任务或一次性支持工作建立可靠的归档处理流程，它会很合适。特别是当你在意机器可读输出、可控的解压行为，或希望选择一条尽量少踩坑的安装路径时，tzst 的价值会更明显。

它真正解决的工作问题

大多数用户并不是想看一遍仓库导览，他们真正想解决的问题通常是：怎么安装 tzst？哪个命令用于创建，哪个用于解压？怎样避免覆盖已有文件？如何只解压特定路径？在 File Automation 场景里，怎样使用 tzst 获得对 JSON 友好、参数行为可预测的输出？

关键差异点

和普通提示相比，tzst 更聚焦，因此也更能直接落地。它专注 CLI，而不是 Python API；会优先给出更安全的默认做法；并且会把用户引导到明确的命令模式上，比如用 a 创建、用 x 按路径结构解压、用 e 平铺解压、用 l 列出内容、用 t 测试归档。

安装前最值得先确认的事

是否采用 tzst，最常见的阻碍往往很直接：你的系统里是否已经可用 tzst，你更想用 Python 方式安装还是独立二进制，以及你的需求到底是不是 tzst，而不是通用的 tar 或 zip。如果你的核心需求是通过 CLI 处理归档，这个 skill 很匹配；但如果你需要的是 from tzst import ... 这类 Python 用法，它就不是首选指南。

如何使用 tzst skill

先做安装与预检

在让模型执行任何实质性任务前，先确认你的环境里确实有 tzst：

tzst --version
tzst --help

如果缺失，仓库给出的安装路径包括：

uv tool install tzst
pip install tzst

如果你不想走 Python 安装方式，可以直接使用 https://github.com/xixu-me/tzst/releases/latest 中提供的独立发布二进制。

什么时候该调用 tzst skill

当请求涉及以下任一需求时，优先使用 tzst usage 指南：

• 创建 .tzst 归档
• 解压 .tzst 或 .tar.zst
• 将解压结果平铺输出
• 列出归档条目
• 测试归档完整性
• 选择压缩级别
• 使用流式模式
• 过滤要解压的路径
• 选择冲突处理行为
• 生成适合脚本使用的输出

如果问题与这些无关，例如其他归档格式，或 Python 库调用问题，就不应优先使用这个 skill。

核心命令对应关系

想高效用好 tzst，最快的方法就是把目标任务映射到正确的子命令：

• tzst a archive.tzst files... 用于创建
• tzst x archive.tzst 用于按原始路径结构解压
• tzst e archive.tzst 用于平铺解压
• tzst l archive.tzst 用于列出内容
• tzst t archive.tzst 用于测试归档

这一点非常关键，因为很多问题都来自选错子命令：本来想保留目录结构，却用了 e；或者在没有考虑冲突和输出位置的情况下直接解压。

优先使用保留路径结构的解压，而不是平铺解压

在大多数正常工作流里，tzst x 是更安全的默认选择，因为它会保留目录结构。只有在你明确需要“平铺输出”时，才应该使用 tzst e。对于 tzst for File Automation 场景，这个区别尤其重要：平铺解压更容易造成重名冲突，也会让后续文件匹配变得更难。

这个 skill 需要你提供哪些输入

想让 tzst 生成高质量命令，你需要提供尽可能具体的操作信息：

• 归档路径，或希望生成的归档文件名
• 源文件或目录
• 解压目标目录
• 是否需要平铺解压
• 是否允许覆盖
• 是否需要路径过滤
• 输出是否要适合脚本处理
• 你偏好 Python 安装还是独立二进制

如果这些信息缺失，模型仍然可以给出大致语法，但很难提供一条真正低风险、可直接执行的命令。

把模糊需求变成高质量的 tzst 提示

较弱的提示：

Help me use tzst.

更强的提示：

I need a tzst command to extract archive.tzst into ./out, preserve paths, avoid overwriting existing files, and only extract files under docs/. Assume tzst is already installed.

为什么后者更好：它一次性提供了归档文件、目标目录、解压模式、冲突预期和过滤范围，tzst skill 才能直接生成可执行、风险更低的命令。

创建归档时的提示模板

如果你的目标是创建归档，可以这样提问：

Give me a tzst create command for backup.tzst from ./src and ./docs, use a higher compression level, and explain any safety or performance tradeoffs.

这样 tzst 就能正确选择 tzst a，同时补充 -l 或 --level 的用法，并说明什么时候默认值已经足够，什么时候提高压缩率会带来额外耗时。

面向脚本和自动化的提示模板

如果你是在 shell 脚本或 CI 中使用 tzst usage，应明确要求机器可读、可解析的输出：

I need tzst for File Automation in a CI job. Show commands to test an archive, list contents, and return output that is easy to parse in a script.

这会引导 tzst skill 优先给出支持 JSON 导向或脚本安全输出的路径，并倾向于稳定、可复用的命令序列，而不是交互式建议。

适合真实任务的推荐工作流

一个更稳妥的流程通常是：

1. 用 tzst --version 确认已安装
2. 用 tzst --help 确认可用
3. 根据真实目标选择子命令
4. 明确目标目录、过滤条件和冲突策略
5. 如果风险较高，先执行 test 或 list，再做可能有破坏性的解压
6. 运行最终命令
7. 确认无误后，再把它写进自动化流程

这个顺序能显著减少本可避免的解压失误，也更利于排查问题。

值得优先阅读的仓库文件

如果你想在采用前快速判断这个 skill 是否合适，建议先看：

• skills/tzst/SKILL.md
• skills/tzst/references/cli-reference.md

SKILL.md 说明这个 skill 在什么情况下应该被触发；references/cli-reference.md 则是最快获取安装命令、命令映射和参数选择信息的文件。

真正会影响结果的实用参数

以下几个选项会实质性改变结果：

• -l 或 --level：创建时调整压缩级别
• -o：控制解压目标目录
• --streaming：对大文件或管道式工作流很关键
• --filter：限制解压范围
• --conflict-resolution：帮助避免误覆盖已有文件
• --no-atomic：改变创建时的写入行为

这些不是“可有可无”的装饰性参数，它们会直接影响安全性、性能和脚本行为。

tzst 安装与使用中的常见误区

这类错误往往很有规律：

• 把这个 skill 用在 Python import 问题上，而不是 CLI 任务
• 跳过预检，直到工作流都搭好了才发现根本没安装 tzst
• 本来需要保留路径结构，却误用了平铺解压
• 在已有文件的目录中解压时，没有明确指定冲突处理策略
• 只说“给我一个命令”，却不提供路径、过滤条件或输出要求

tzst skill 常见问题

tzst skill 适合新手吗

适合，前提是你的任务足够具体。对于已经知道自己手上是什么归档、想得到什么结果的用户来说，tzst guide 对新手也很友好；但如果你的需求只是“教我归档基础知识”，它的帮助就没那么大。

tzst 和通用 AI 提示有什么区别

通用提示可能会给出“看起来合理”的归档建议，但不一定真正对应 tzst 的子命令和参数。tzst skill 会把模型收束到真实的 CLI 工作流、安装选择以及用户实际需要执行的命令体系上。

什么情况下不该使用 tzst

以下情况不建议把 tzst 当作主指南：

• 与 tzst 无关的通用 zip 或 tar 问题
• Python API 用法，例如 from tzst import ...
• 实际需求更适合其他已安装工具的归档任务

这个 skill 是刻意按 CLI 专用场景设计的。

tzst 适合自动化使用吗

适合，而且这是使用它的一个强理由。这个 skill 明确覆盖了 shell 脚本和 CI 中很关键的内容：列表查看、归档测试、路径过滤、冲突控制，以及机器可读输出的考虑。

最佳的 tzst 安装方式是什么

对很多用户来说，uv tool install tzst 是最干净的安装方式。如果你的环境本来就接受 Python 包安装，那么 pip install tzst 也没问题。如果你想尽量减少依赖负担，独立二进制发布通常是更合适的选择。

我需要先把整个仓库都看完吗

不需要。仅从安装决策角度看，通常只要阅读 SKILL.md 和 references/cli-reference.md 就够了。这已经足够帮助你判断它是否匹配你的场景、命令覆盖是否完整，以及它能否减少你的猜测成本。

如何改进 tzst skill

给 tzst 提供完整的任务上下文

想让 tzst 输出更好，最快的方法就是一开始就把操作细节说完整。包括归档名、源路径、目标目录、覆盖策略、是否平铺，以及命令是否必须适合脚本执行。输入越具体，生成的命令就越接近“拿来即用”。

明确表达你的风险偏好

如果任务涉及重要文件，务必告诉 tzst skill：你更看重安全，而不是简短。这样它会更倾向于推荐先列出或测试、保留路径结构的解压方式，以及显式的冲突设置，而不是只给最短命令。

要求“命令 + 原因说明”

一种很好用的提问格式是：

Give me the exact tzst command, explain each important flag briefly, and mention any safer alternative if the destination already contains files.

这样能提升可验证性，也更容易在实际执行前发现错误假设。

第一条命令出来后继续迭代

tzst guide 的最佳用法通常是迭代式的。拿到第一版结果后，再结合你的环境细节继续细化：

Now adapt that command for a standalone binary install and a CI environment where the output must be easy to parse.

这种做法通常比从头重问更高效。

提供文件样例和路径示例

如果过滤或平铺行为很关键，最好给出有代表性的路径样例。例如：

Archive contains docs/api/index.md, docs/user/intro.md, and src/main.py. I only want docs/ extracted into ./site-content.

这种细节足以帮助 tzst skill 选择更合适的解压模式和过滤策略。

提前排查常见失败点

在最终定稿命令前，可以要求这个 skill 重点检查以下问题：

• 是否缺少 tzst 安装
• 是否为当前任务选错了子命令
• 是否发生了意外的路径平铺
• 是否存在归档覆盖或解压冲突
• 是否对输出格式做了不受支持的假设

这正是 tzst skill 相比普通单行 CLI 回答更有价值的地方。

用稳定工作流提升 tzst for File Automation 的效果

在 tzst for File Automation 场景中，尽量要求它给出一整套步骤，而不是单条命令：预检、列出或测试、执行、验证。稳定的自动化通常来自可预测的步骤，而不是最短语法。

用参考文件做交叉验证

如果某条命令看起来不太确定，可以对照 references/cli-reference.md。这个文件是核对子命令、安装方式和关键参数的最快参考来源，尤其适合确认那些最容易影响正确性的选项。

把改进建议反馈回 skill

如果你发现某些地方经常让人产生歧义，可以通过补充更多“决策导向”的示例来改进这个 skill，例如：

• x 与 e 的选择
• 更安全的 conflict-resolution 默认建议
• 带真实路径的过滤示例
• 面向自动化的输出模式示例
• Python 安装与独立二进制之间的选择建议

这些补充会让 tzst skill 不只是“会执行命令”，而是在安装和使用决策阶段就更有帮助。