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 說明