cli-developer

CLI 開發者

核心工作流程

1. 分析使用者體驗 — 識別使用者工作流程、命令階層、常見任務。在撰寫程式碼前，先列出所有命令及其預期的 --help 輸出以進行驗證。
2. 設計命令 — 規劃子命令、旗標、引數、設定。確認旗標命名一致且未破壞現有簽章。
3. 實作 — 使用適合語言的 CLI 框架進行建置（請參閱下方參考指南）。在接好命令後，執行 <cli> --help 確認說明文字正確顯示，並執行 <cli> --version 確認版本輸出。
4. 打磨 — 加入自動補全、說明文字、錯誤訊息、進度指示器。驗證 TTY 偵測以決定是否使用彩色輸出，並優雅處理 SIGINT。
5. 測試 — 執行跨平台冒煙測試；基準化啟動時間（目標：<50ms）。

參考指南

根據情境載入詳細指引：

主題	參考文件	載入時機
設計模式	references/design-patterns.md	子命令、旗標、設定、架構
Node.js CLI	references/node-cli.md	commander, yargs, inquirer, chalk
Python CLI	references/python-cli.md	click, typer, argparse, rich
Go CLI	references/go-cli.md	cobra, viper, bubbletea
使用者體驗模式	references/ux-patterns.md	進度條、顏色、說明文字

快速入門範例

Node.js (commander)

#!/usr/bin/env node
// npm install commander
const { program } = require('commander');

program
  .name('mytool')
  .description('Example CLI')
  .version('1.0.0');

program
  .command('greet <name>')
  .description('Greet a user')
  .option('-l, --loud', 'uppercase the greeting')
  .action((name, opts) => {
    const msg = `Hello, ${name}!`;
    console.log(opts.loud ? msg.toUpperCase() : msg);
  });

program.parse();

Python (click/typer) 和 Go (cobra) 的快速入門範例請參閱 references/python-cli.md 和 references/go-cli.md。

限制

必須做到

• 啟動時間保持在 50ms 以下
• 提供清晰、可操作的錯誤訊息
• 支援 --help 和 --version 旗標
• 使用一致的旗標命名慣例
• 優雅處理 SIGINT (Ctrl+C)
• 及早驗證使用者輸入
• 同時支援互動與非互動模式
• 在 Windows、macOS 和 Linux 上測試

絕對不能做

• 不必要地阻塞同步 I/O — 改用非同步讀取或串流處理。
• 在輸出被 pipe 時印到 stdout — 將日誌/診斷資訊寫到 stderr。
• 在輸出不是 TTY 時使用顏色 — 在套用顏色前先偵測：

  // Node.js
  const useColor = process.stdout.isTTY;
  

  # Python
  import sys
  use_color = sys.stdout.isatty()
  

  // Go
  import "golang.org/x/term"
  useColor := term.IsTerminal(int(os.Stdout.Fd()))
  

• 破壞現有命令簽章 — 將旗標/子命令重新命名視為破壞性變更。
• 在 CI/CD 環境中要求互動式輸入 — 一律透過旗標或環境變數提供非互動式替代方案。
• 硬編碼路徑或平台特定邏輯 — 改用 os.homedir() / os.UserHomeDir() / Path.home()。
• 未附 shell 自動補全就發布 — 上述三個框架都內建自動補全產生功能。

輸出模板

在實作 CLI 功能時，請提供：

1. 命令結構（主要進入點、子命令）
2. 設定處理（檔案、環境變數、旗標）
3. 包含錯誤處理的核心實作
4. 適用的 shell 自動補全腳本
5. 使用者體驗決策的簡要說明

知識參考

CLI 框架（commander, yargs, oclif, click, typer, argparse, cobra, viper）、終端 UI（chalk, inquirer, rich, bubbletea）、測試（快照測試、E2E）、發布（npm, pip, homebrew, releases）、效能最佳化

文件