CLI Creator 是做什麼的？
用於建構與審查生產級 Python CLI 工具及 CLI 相關技能/模板的路由。可用來決定 CLI 形狀、保持命令面精簡、維持可安裝性，並強制輸出審查結果。此技能保持輕量：僅讀取您需要的參考文件。
使用時機
- 建立新的 Python CLI 或命令樹。
- CLI 重構、簡化或套件整理。
- CLI 審查/稽核，包括 UX、設定、錯誤處理、快取與發佈流程。
- 行為類似 CLI 套件的代理技能、腳手架或模板。
- 驗證安裝、wheel 或 console-script 行為。
CLI 類型選擇
| 類型 | 偏好 |
|---|---|
| 命令優先的工具 | 精簡路由、嚴格的結束碼、JSON/純文字輸出。 |
| 設定驅動的工具 | 設定發現、優先級、重現性。 |
| 互動式助手 | 流程/狀態機、提示、復原。 |
| 混合類型 CLI | 小型命令樹加上可重複使用的編排。 |
| 高效能 CLI | 延遲匯入、有限的 I/O、快取/進度條。 |
| 外掛/可擴展 CLI | 穩定的擴展合約與註冊表。 |
不要將助手架構強加於命令優先的工具。不要將單一腳本形狀強加於成長中的產品。
核心規則
- 偏好能夠解決使用者工作的最小 CLI。
- 使用最小 CLI/YAGNI 路徑：如果工具只有一兩個指令、無持久狀態、無網路、無外掛、無憑證，請保持微小；除非能解決立即問題，否則不要加入 Rich、Pydantic、platformdirs、快取層、
doctor或外掛註冊表。 - 保持名稱、旗標、結束碼、設定鍵與輸出模式穩定。
- 讓預設值有用且安全。
- 分離路由、領域邏輯、I/O、設定、持久化、渲染與整合。
- 使用 JSON 或純文字模式使機器輸出可腳本化。
- 驗證 README 中的命令即為已安裝的 console script。
參考檔案載入規則
僅讀取任務所需的參考檔案：
- 建立或重構：
references/creation-playbook.md。 - 審查或稽核：
references/review-rubric.md與references/pitfalls-and-solutions.md。 - 實作細節、套件打包、安全性、跨平台行為、Rich 輸出、快取或 LLM 提供者：
references/technical-best-practices.md。 - 若涉及技能/套件維護，查閱工作區根目錄的治理資料夾
skill-ir/、evals/、scripts/、reports/與registry/（若存在）。這些是維護者端的路由輔助工具，不應捆綁在已安裝的技能副本內。
請勿在此處複製那些參考檔案的內容。僅在當前任務需要時才載入它們。
建立新 CLI 或技能流程
- 確定產品形狀：誰執行它、承受什麼壓力、哪些必須快取、記住或忘記。
- 設計命令面，包含少數穩定命令與實際範例。
- 選擇最適合的最小技術棧。
- 大部分 CLI 使用 Typer 或 Click。
- 僅對小型偏好 stdlib 的工具使用 argparse。
- 選擇能撐過接下來兩個版本的最小架構。
- 實作產品循環：輸入、驗證、執行、渲染、持久化、結束碼、復原提示。
- 發佈前進行驗證。
命令面範例
my-cli run
my-cli init
my-cli config show
my-cli doctor
my-cli cache clear
my-cli check PATH
my-cli fetch QUERY --json
my-cli export ID --output result.md
規則：
- 使用引數（arguments）表示必要的領域物件。
- 使用選項（options）表示修飾符、輸出模式與可選行為。
- 提供
--json或--format json以便自動化。 - 一致地提供
--quiet、--verbose與--debug。 - 避免在看似唯讀的命令中進行意外的網路操作或修改。
驗證期望
當命令面、安裝路徑與 wheel 路徑重要時，務必驗證：
- 根命令與每個頂層命令的
--help。 - 在新環境中進行乾淨安裝。
- 當工具含有設定時，處理遺失設定或首次執行路徑。
- 當工具驗證輸入時，處理無效設定或錯誤路徑。
- 成功路徑加上支援時的 JSON/可腳本模式。
- 當工具含有快取時，處理快取重新整理與快取清除。
- 套件中繼資料與 console script。
- 當您需要安裝信心時，從儲存庫外部安裝 wheel。
適用時使用此緊湊組合：
uv venv /tmp/cli-audit
. /tmp/cli-audit/bin/activate
uv pip install -e .
cli-creator-skill --help
cli-creator-skill install
uv build
uv pip install dist/*.whl
python -m pytest
審查工作流程
在稽核現有 CLI 或 CLI 相關技能/模板時：
審查前閱讀：
references/review-rubric.mdreferences/pitfalls-and-solutions.md
當稽核觸及實作細節、套件打包、安全性、跨平台行為、Rich 輸出、快取或 LLM 提供者時，閱讀 references/technical-best-practices.md。
然後：
- 檢查儲存庫結構：套件佈局、命令入口點、設定檔案、測試、文件、CI。
- 執行 help：根命令
--help與命令層級的 help。 - 追蹤一個從回呼到領域服務再到渲染器的成功命令路徑。
- 追蹤一個失敗路徑並檢查錯誤品質。
- 檢查設定優先級：旗標、環境變數、專案設定、使用者設定、預設值。
- 檢查安全性：機密、Shell 執行、路徑處理、不安全的設定/外掛、遙測、子程序逾時、依賴供應鏈。
- 檢查效能：啟動匯入、網路逾時、快取行為、檔案發現。
- 檢查自動化：結束碼、JSON 輸出、stdin/stdout/stderr 分離、非 TTY 行為。
- 檢查套件打包：Python 版本、相依性、腳本、wheel、README 命令。
- 使用
references/review-rubric.md為每個評分領域打分。 - 先回報發現，然後是優先順序的修復建議。
必要稽核輸出
稽核輸出必須包含以下章節，按此順序：
**發現事項**
**評分**
| 領域 | 分數 | 備註 |
|---|---:|---|
**修復順序**
**測試缺口**
**驗證命令**
維護注意事項
- 保持此技能作為路由器；將實作細節放在四個參考檔案中。
- 使命令範例、稽核標題與驗證組合與套件發佈保持同步。
- 對於維護者端的治理，使用工作區根目錄的
skill-ir/、evals/、scripts/、reports/與registry/資料夾（若存在）；不要假裝它們是已安裝技能的一部分。
此技能可協助的事項
- 從頭設計新的 Python CLI。
- 審查現有 CLI 的 UX、套件打包、錯誤處理、模型設定、快取與可維護性。
- 建構 Typer、Click、argparse 或混合型應用程式。
- 建構自然的多輪 CLI 流程，而不讓使用者感覺像在填表單。
- 在真正需要時加入診斷、快取、記憶體分析與首次執行設定流程。
- 審查 CLI 相關技能與模板的觸發清晰度、參考完整性、命令模板、輸出合約與維護策略。
設計基礎
此技能提煉了維護者經驗以及 Python 套件打包、Typer、Click、Rich、uv、Ruff、Pydantic 與 LLM 提供者整合的官方文件模式。它不會從非官方的第三方儲存庫引入程式碼或指示。