建立命令列介面
設計命令列介面(語法與行為),以人為本,並支援腳本化操作。
先讀這個
- 閱讀
agent-scripts/skills/create-cli/references/cli-guidelines.md並將其作為預設評分標準。 - 完整指南(上游):https://clig.dev/ (建議修改請至:https://github.com/cli-guidelines/cli-guidelines)
- 僅提出鎖定介面所需的最少澄清問題。
快速釐清
提問後,若使用者不確定則以最佳預設值繼續:
- 命令名稱 + 一句話目的。
- 主要使用者:人類、腳本、或兩者兼顧。
- 輸入來源:引數 vs 標準輸入;檔案 vs URL;機密(絕不能透過旗標傳遞)。
- 輸出合約:人類可讀文字、
--json、--plain、結束碼。 - 互動性:允許提示嗎?需要
--no-input嗎?破壞性操作需要確認嗎? - 設定模型:旗標/環境變數/設定檔;優先順序;XDG 規範 vs 儲存庫本地設定。
- 平台/執行時期限制:macOS/Linux/Windows;單一二進位檔 vs 執行時期。
交付物(要輸出什麼)
設計 CLI 時,產出一份使用者可實作的簡潔規格:
- 命令樹 + USAGE 範例語法。
- 引數/旗標表格(型別、預設值、必填/選填、範例)。
- 子命令語意(每個子命令的作用;是否冪等;狀態變更)。
- 輸出規則:標準輸出 vs 標準錯誤;TTY 偵測;
--json/--plain;--quiet/--verbose。 - 錯誤與結束碼對應表(主要失敗模式)。
- 安全規則:
--dry-run、確認、--force、--no-input。 - 設定與環境變數規則 + 優先順序(旗標 > 環境變數 > 專案設定 > 使用者設定 > 系統設定)。
- Shell 自動補全說明(如果相關):安裝與可發現性;生成命令或內建腳本。
- 5–10 個範例呼叫(常見流程;包含管線/標準輸入範例)。
預設慣例(除非使用者另有指定)
-h/--help總是顯示說明,並忽略其他引數。--version將版本號輸出到標準輸出。- 主要資料輸出到標準輸出;診斷/錯誤輸出到標準錯誤。
- 加入
--json用於機器輸出;考慮加入--plain用於穩定的逐行文字。 - 僅在標準輸入為 TTY 時才顯示提示;
--no-input停用提示。 - 破壞性操作:互動模式需要確認;非互動模式需要
--force或明確的--confirm=...。 - 尊重
NO_COLOR與TERM=dumb;提供--no-color。 - 處理 Ctrl-C:快速退出;有限度的清理;儘可能採用崩潰安全模式。
模板(複製到你的回答中)
CLI 規格骨架
填入以下內容,刪除不相關的部分:
- 名稱:
mycmd - 一句話說明:
... - 使用方式:
mycmd [全域旗標] <子命令> [引數]
- 子命令:
mycmd init ...mycmd run ...
- 全域旗標:
-h, --help--version-q, --quiet/-v, --verbose(明確定義)--json/--plain(如果適用)
- 輸入/輸出合約:
- 標準輸出:
- 標準錯誤:
- 結束碼:
0成功1一般失敗2無效使用(解析/驗證錯誤)- (僅在確實有用時才加入命令專用碼)
- 環境變數/設定:
- 環境變數:
- 設定檔路徑 + 優先順序:
- 範例:
- …
備註
- 僅在使用者要求時才推薦特定語言的解析函式庫;否則此技能應保持語言無關。
- 若要求是「設計參數」,請勿偏離到實作細節。