tzst

tzst skill 概覽

tzst skill 能幫你做什麼

tzst skill 是一份實用指南，專門協助你使用 tzst 命令列工具來建立、檢視、測試，以及解壓 .tzst 與 .tar.zst 封存檔。它特別適合你已經知道要處理哪些檔案路徑，只是想更快拿到正確指令、旗標與安全選項，而不是從泛用提示裡慢慢猜。

誰適合使用 tzst

這個 tzst skill 很適合需要穩定封存流程的開發者、維運人員，以及自動化流程建置者，無論是處理本機檔案、撰寫腳本、跑 CI 工作，或是臨時支援任務都很適用。尤其當你在意可機器讀取的輸出、可控的解壓行為，或是不想踩雷的安裝路徑時，這個 skill 會更有價值。

真正要解決的工作需求

多數使用者並不是想看整個 repo 導覽，而是想快速回答這些問題：tzst 要怎麼安裝？哪個指令是建立、哪個是解壓？怎麼避免覆寫既有檔案？怎麼只解壓特定內容？在 tzst for File Automation 的情境下，又該怎麼取得對 JSON 友善、旗標行為可預期的輸出？

主要差異化優勢

和一般提示相比，tzst 的範圍更聚焦，因此也更能直接落地。它專注在 CLI，而不是 Python API；會優先帶出較安全的預設做法；並且直接指向具體指令模式，例如用 a 建立封存、x 保留路徑結構解壓、e 平鋪解壓、l 列出內容，以及用 t 測試封存完整性。

安裝前最該先確認的事

實際導入時，最大的阻礙通常很單純：你的系統上是否已經有 tzst、你偏好 Python 型安裝還是獨立執行檔，以及你的需求到底是不是 tzst，而不是泛用的 tar 或 zip。如果你要的是 CLI 封存處理，這個 skill 很適合；但如果你需要的是 from tzst import ...，那它就不是主要參考指南。

如何使用 tzst skill

先做安裝與前置檢查

在請模型幫你做任何實際操作前，先確認你的環境裡真的有 tzst：

tzst --version
tzst --help

如果找不到，repo 提供的安裝路徑如下：

uv tool install tzst
pip install tzst

如果你不想走 Python 安裝，可直接使用 https://github.com/xixu-me/tzst/releases/latest 提供的獨立 release binaries。

什麼情況下該啟用 tzst skill

當需求涉及以下任一情境時，就很適合使用 tzst usage 指引：

• 建立 .tzst 封存檔
• 解壓 .tzst 或 .tar.zst
• 將解壓內容平鋪輸出
• 列出封存內容
• 測試封存完整性
• 選擇壓縮等級
• 使用串流模式
• 篩選要解壓的路徑
• 指定衝突處理方式
• 產出適合腳本使用的輸出

如果是無關的封存格式，或是在問 Python library 的用法，就不該優先用這個 skill。

核心指令對照表

想快速把 tzst 用對，最有效的方法就是先把需求對到正確的子命令：

• tzst a archive.tzst files...：建立封存
• tzst x archive.tzst：解壓並保留路徑結構
• tzst e archive.tzst：平鋪解壓
• tzst l archive.tzst：列出內容
• tzst t archive.tzst：測試封存

這一點很重要，因為很多錯誤都來自選了 e，但其實你真正要的是 x；或是在沒想清楚衝突處理與輸出位置前就直接解壓。

優先使用保留結構的解壓，而不是平鋪解壓

在一般工作流程裡，tzst x 通常是更安全的預設，因為它會保留目錄結構。只有在你明確想把內容平鋪時，才建議使用 tzst e。這個差異在 tzst for File Automation 特別重要，因為平鋪輸出可能造成檔名衝突，也會讓後續檔案比對更難做。

tzst skill 需要你提供哪些資訊

要產出高品質、可直接執行的指令，這個 skill 需要具體的操作資訊：

• 封存檔路徑，或想建立的輸出封存檔名稱
• 來源檔案或目錄
• 解壓目的地目錄
• 是否需要平鋪輸出
• 是否允許覆寫
• 是否有路徑篩選條件
• 輸出是否需要適合腳本解析
• 你偏好 Python 安裝還是獨立執行檔

如果少了這些資訊，模型仍然可以給你語法範例，但很難提供低風險、可直接落地的指令。

把模糊需求改寫成有效的 tzst prompt

較弱的 prompt：

Help me use tzst.

較強的 prompt：

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.

為什麼這樣更好：它一次就交代了封存檔、目的地、解壓模式、衝突預期，以及篩選範圍。

建立封存時可直接套用的 prompt 範本

要建立封存時，可以用這種 prompt：

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.

這樣 skill 就能正確選用 tzst a，帶出 -l 或 --level，並說明什麼情況下預設值通常已足夠、什麼情況下額外壓縮會增加時間成本。

給腳本與自動化用的 tzst prompt 範本

如果你是在 shell script 或 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.

這會讓 skill 更傾向提供支援 JSON 或適合腳本解析的輸出路徑，並優先採用穩定、可重現的命令順序，而不是互動式建議。

實務任務建議工作流程

一套可靠的流程通常是：

1. 用 tzst --version 確認已安裝
2. 用 tzst --help 確認可用性
3. 依照實際目標選對子命令
4. 明確指定目的地、篩選條件與衝突策略
5. 若風險較高，先 list 或 test 再進行可能有破壞性的解壓
6. 執行最終指令
7. 確認沒問題後，再寫進自動化流程

這個順序能有效減少可避免的解壓錯誤，也更容易排查問題。

採用前值得優先閱讀的 repository 檔案

如果你想先驗證這個 skill 是否適合導入，建議從這兩個檔案開始：

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

SKILL.md 會告訴你這個 skill 應該在什麼情況下觸發；references/cli-reference.md 則是最快查安裝指令、命令對照與旗標選擇的檔案。

會直接影響結果的實用旗標

有幾個選項會明顯改變結果：

• -l 或 --level：建立封存時調整壓縮等級
• -o：控制解壓目的地
• --streaming：對大型檔案或 pipeline 型流程特別重要
• --filter：限制實際要解壓的路徑
• --conflict-resolution：協助避免不小心覆寫檔案
• --no-atomic：改變建立封存時的寫入行為

這些不是裝飾性旗標，而是會直接決定安全性、效能與腳本行為的關鍵選項。

tzst 安裝與使用時最常見的誤踩點

最常見的錯誤其實很固定：

• 把這個 skill 用在 Python import，而不是 CLI 任務
• 略過前置檢查，等到流程都排好了才發現根本沒安裝 tzst
• 原本想保留路徑結構，卻用了平鋪解壓
• 在已有檔案的目錄中解壓時，沒有先指定衝突處理方式
• 只要求「給我一條指令」，卻沒有提供路徑、篩選條件或輸出需求

tzst skill 常見問題

tzst skill 適合新手嗎

適合，但前提是你的需求要夠具體。對新手來說，只要你已經知道手上的封存檔是什麼、想得到什麼結果，tzst guide 會很好上手；但如果只是模糊地想「學會封存」，幫助就相對有限。

tzst 和一般 AI prompt 有什麼差別

一般 prompt 很可能給出看似合理、但其實沒有對齊 tzst 子命令或旗標的封存建議。tzst skill 則是把模型收斂到真實的 CLI 流程、安裝選擇，以及使用者真正需要執行的指令語彙上。

什麼情況下不該使用 tzst

以下情況不適合把 tzst 當作主要指南：

• 純粹在問泛用 zip 或 tar 問題，完全沒有 tzst
• Python API 用法，例如 from tzst import ...
• 其實真正需求是其他已安裝工具的封存工作

這個 skill 本來就是刻意設計成 CLI 專用。

tzst 適合自動化嗎

適合，而且這正是它最有優勢的場景之一。這個 skill 明確涵蓋列出內容、測試封存、路徑篩選、衝突控制，以及機器可讀輸出的考量，這些都是 shell script 和 CI 很在意的事。

最推薦的 tzst 安裝方式是什麼

對很多使用者來說，uv tool install tzst 是最乾淨俐落的安裝方式。如果你的環境本來就適合安裝 Python 套件，pip install tzst 也沒問題。若你希望依賴更少、部署更單純，獨立 binary release 會是更好的路徑。

我需要先把整個 repository 都看完嗎

不用。若你現在是在做安裝決策，通常只要先看 SKILL.md 和 references/cli-reference.md 就夠了。這樣已足以判斷它是否符合你的需求、命令覆蓋是否完整，以及它能不能真的減少你在使用情境中的猜測成本。

如何改善 tzst skill 的使用效果

先把完整任務背景交給 tzst

想讓 tzst 產出更好的結果，最快的方法就是一開始就提供操作細節。請包含封存檔名稱、來源路徑、目標目錄、覆寫政策、是否要平鋪，以及指令是否必須適合腳本使用。輸入越完整，產出的指令就越能直接執行。

明確說出你的風險容忍度

如果任務會碰到重要檔案，請明確告訴 skill 你希望它優先考慮安全，而不是精簡。這會讓它更傾向先列出內容、先測試、使用保留路徑的解壓方式，並明確設定衝突處理，而不是只給最短的指令。

要求提供指令，也要附上理由

一個很好用的 prompt 格式是：

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.

這種細節能幫助 skill 正確判斷該用哪種解壓模式與篩選行為。

及早攔截常見失敗模式

在最終確認指令前，可以要求 skill 先檢查以下幾點：

• 是否缺少 tzst 安裝
• 是否選錯子命令
• 是否會不小心把路徑平鋪
• 是否存在封存覆寫或解壓衝突
• 是否對輸出格式做了不受支援的假設

這正是 tzst skill 相比一般單行 CLI 回答真正能補位的地方。

用穩定流程提升 tzst for File Automation 的效果

在 tzst for File Automation 場景中，請要求一整段流程，而不是單一指令：前置檢查、列出或測試、執行、驗證。穩定的自動化通常來自可預測的步驟，而不是最短的語法。

對照 reference 檔案做驗證

如果某條指令看起來不太確定，請拿它和 references/cli-reference.md 對照。這個檔案是最快確認子命令、安裝方式，以及最可能影響正確性的旗標的地方。

把可改進之處回饋給 skill

如果你發現某些地方反覆出現歧義，可以考慮補強 skill，加入更多偏向決策支援的範例，例如：

• x 與 e 的選擇差異
• 安全的 conflict-resolution 預設值
• 使用真實路徑的篩選範例
• 偏向自動化的輸出模式
• Python 安裝與 standalone binary 的選擇指引

這些補充會讓 tzst skill 在做安裝與採用決策時更有幫助，而不只是執行階段才派上用場。