tzst

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tzst

Use this skill for the

tzst

command-line interface. Default to execution when the user clearly wants a real archive action and the required paths or archive names are already known.

This skill is CLI-only. If the user is asking about Python code such as

from tzst import ...

, treat that as a general Python library or API documentation task instead of using this skill as the main guide.

本技能适用于

tzst

命令行界面。当用户明确需要执行实际的压缩包操作，且所需路径或压缩包名称已知时，默认直接执行操作。

本技能仅适用于CLI场景。如果用户询问的是

from tzst import ...

这类Python代码相关问题，请将其视为通用Python库或API文档任务，不要以本技能作为主要参考。

When to Use

适用场景

Use this skill when the user:

mentions
```
.tzst
```
or
```
.tar.zst
```
archives
wants to create, extract, flatten, list, or test a
```
tzst
```
archive
needs help installing
```
tzst
```
or choosing CLI flags
wants machine-readable
```
tzst
```
output for scripting or automation
needs safe conflict handling or extraction filter guidance

Do not use this skill for generic

tar

zip

, or Python API questions unless

tzst

is actually part of the request.

当用户满足以下条件时使用本技能：

提到
```
.tzst
```
或
```
.tar.zst
```
格式压缩包
需要创建、提取、扁平化、列出或测试
```
tzst
```
压缩包
需要安装
```
tzst
```
或选择CLI参数的相关帮助
需要用于脚本编写或自动化的机器可读
```
tzst
```
输出
需要安全冲突处理或提取过滤器的使用指南

不要将本技能用于通用

tar

、

zip

或Python API相关问题，除非请求中明确包含

tzst

。

Preflight

前置检查

Check whether
```
tzst
```
is available with
```
tzst --version
```
or
```
tzst --help
```
.
If it is missing, prefer one of these installation paths:
- ```
uv tool install tzst
```
- ```
pip install tzst
```
- a standalone release binary from https://github.com/xixu-me/tzst/releases/latest when the user does not want a Python installation
Re-run
```
tzst --version
```
or
```
tzst --help
```
before doing real work.

通过
```
tzst --version
```
或
```
tzst --help
```
检查
```
tzst
```
是否可用。
如果缺少该工具，优先选择以下安装路径：
- ```
uv tool install tzst
```
- ```
pip install tzst
```
- 当用户不想安装Python环境时，可从https://github.com/xixu-me/tzst/releases/latest下载独立发布的二进制文件
在执行实际操作前重新运行
```
tzst --version
```
或
```
tzst --help
```
确认可用。

Workflow

工作流程

Decide whether the request is execution or guidance. Requests like "archive these files", "extract this backup", "list what is inside", "test this archive", or "install tzst" are execution intent.
Choose the command that matches the request:
- ```
a
```
  ,
```
add
```
  ,
```
create
```
  for archive creation
- ```
x
```
  ,
```
extract
```
  for normal extraction with directory structure preserved
- ```
e
```
  ,
```
extract-flat
```
  only when the user explicitly wants flattened output
- ```
l
```
  ,
```
list
```
  for archive inspection
- ```
t
```
  ,
```
test
```
  for integrity checks
If the user wants to extract only a few members and the member names are uncertain, list first.
Load
```
references/cli-reference.md
```
when you need the command matrix, exact flag names, or copy-paste examples.

判断用户请求是需要执行操作还是获取指南。类似“压缩这些文件”、“解压这个备份”、“列出压缩包内容”、“测试这个压缩包”或“安装tzst”这类请求都属于执行意图。
选择符合请求的命令：
- ```
a
```
  、
```
add
```
  、
```
create
```
  用于创建压缩包
- ```
x
```
  、
```
extract
```
  用于普通提取，保留目录结构
- 仅当用户明确要求扁平化输出时使用
```
e
```
  、
```
extract-flat
```
- ```
l
```
  、
```
list
```
  用于查看压缩包内容
- ```
t
```
  、
```
test
```
  用于完整性校验
如果用户只需要提取部分文件且文件名不确定，先执行列出操作。
当你需要命令矩阵、准确的参数名称或可直接复制的示例时，加载
```
references/cli-reference.md
```
。

Safe Defaults

安全默认配置

Prefer
```
x
```
over
```
e
```
unless flattening is explicitly requested.
Keep
```
--filter data
```
as the default extraction mode.
Use
```
--filter tar
```
only when the user needs standard tar-style compatibility.
Use
```
--filter fully_trusted
```
only when the user explicitly says the archive source is completely trusted.
Keep atomic archive creation enabled. Only reach for
```
--no-atomic
```
when the user explicitly wants it.
Prefer
```
--streaming
```
for large archives or memory-constrained environments.
For automation or pipelines, prefer
```
tzst --json --no-banner ...
```
.
For automated extraction, require an explicit non-interactive
```
--conflict-resolution
```
choice such as
```
replace_all
```
,
```
skip_all
```
, or
```
auto_rename_all
```
.
Do not combine
```
--json
```
with interactive conflict prompting.

除非用户明确要求扁平化，否则优先使用
```
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
```
与交互式冲突提示结合使用。

Scripting Notes

脚本编写注意事项

Put global flags before the subcommand in examples, such as
```
tzst --json --no-banner l archive.tzst
```
.
Use exit codes in scripts:
```
0
```
for success,
```
1
```
for operation errors,
```
2
```
for argument parsing errors, and
```
130
```
for interruption.
When archive naming matters, tell the user that
```
tzst
```
may normalize a creation target to
```
.tzst
```
or
```
.tar.zst
```
.

示例中全局参数需放在子命令之前，例如
```
tzst --json --no-banner l archive.tzst
```
。
脚本中可使用退出码：
```
0
```
表示成功，
```
1
```
表示操作错误，
```
2
```
表示参数解析错误，
```
130
```
表示操作被中断。
当压缩包命名有要求时，告知用户
```
tzst
```
可能会将创建的目标文件名标准化为
```
.tzst
```
或
```
.tar.zst
```
后缀。

Common Mistakes

常见错误

Using
```
e
```
when the user expected the original directory structure to be preserved
Recommending
```
fully_trusted
```
for archives from an unknown or untrusted source
Forgetting an explicit conflict strategy for non-interactive extraction
Treating a Python API question as a CLI question
Guessing flags from
```
tar
```
habits instead of checking the bundled reference or the installed CLI help

用户期望保留原始目录结构时使用了
```
e
```
命令
对来源未知或不可信的压缩包推荐使用
```
fully_trusted
```
参数
非交互式提取时忘记明确指定冲突处理策略
将Python API相关问题视为CLI问题处理
按照
```
tar
```
的使用习惯猜测参数，而没有查询附带的参考文档或已安装CLI的帮助信息