antd

Ant Design CLI

你擁有 @ant-design/cli 的存取權限 — 這是一個本機 CLI 工具，內含 antd v4/v5/v6 的捆綁中繼資料（以及 v3→v4、v4→v5、v5→v6 的遷移指南）。可用於查詢元件知識、分析專案及引導遷移。所有資料皆為離線，無需網路。

設定

首次使用前，請檢查 CLI 是否已安裝。若未安裝，請自動安裝：

which antd || npm install -g @ant-design/cli

執行任何指令後，若輸出包含「Update available」通知，請先執行 antd upgrade 更新後再繼續。

一律使用 --format json 以取得結構化輸出，方便程式解析。

情境

1. 撰寫 antd 元件程式碼

在撰寫任何 antd 元件程式碼之前，請先查閱其 API — 不要依賴記憶。

# 查看有哪些屬性可用
antd info Button --format json

# 取得可運作的範例作為起點
antd demo Button basic --format json

# 檢查語意化 classNames/styles 以進行自訂樣式
antd semantic Button --format json

# 檢查元件層級的設計權杖以進行主題設定
antd token Button --format json

# 取得整體設計語言 (design.md)：色彩、排版、間距、圓角 + 原則
antd design.md --format json

工作流程： antd info → 了解屬性 → antd demo → 取得可運作範例 → 撰寫程式碼。

2. 查閱完整文件

當你需要完整的元件文件（不僅是屬性）時：

antd doc Table --format json        # Table 的完整 Markdown 文件
antd doc Table --lang zh            # 中文文件

3. 除錯 antd 問題

當程式碼不如預期運作，或使用者回報 antd 錯誤時：

# 收集完整環境快照（系統、相依套件、瀏覽器、建置工具）
antd env --format json

# 檢查該屬性在使用者的 antd 版本中是否存在
antd info Select --version 5.12.0 --format json

# 檢查屬性是否已棄用
antd lint ./src/components/MyForm.tsx --format json

# 診斷專案層級的設定問題
antd doctor --format json

工作流程： antd env → 擷取完整環境 → antd doctor → 檢查設定 → antd info --version X → 比對 API 與使用者確切版本 → antd lint → 找出已棄用或不正確的使用方式。

4. 版本間遷移

當使用者想要升級 antd（例如 v3→v4 或 v4→v5）時：

# 取得完整遷移檢查清單
antd migrate 3 4 --format json    # v3→v4
antd migrate 4 5 --format json    # v4→v5

# 檢查特定元件的遷移
antd migrate 4 5 --component Select --format json

# 產生適合代理程式的自動遷移提示（不會修改檔案）
antd migrate 4 5 --apply ./src --format json

# 查看兩個版本之間的變更
antd changelog 4.24.0 5.0.0 --format json

# 查看特定元件的變更
antd changelog 4.24.0 5.0.0 Select --format json

工作流程： antd migrate → 取得完整檢查清單 → antd changelog <v1> <v2> → 了解重大變更 → 套用修正 → antd lint → 確認無殘留的棄用用法。

5. 分析專案中的 antd 使用情況

當使用者想了解專案中 antd 的使用方式時：

# 掃描元件使用統計
antd usage ./src --format json

# 篩選特定元件
antd usage ./src --filter Form --format json

# 檢查最佳實務違規
antd lint ./src --format json

# 僅檢查特定規則類別
antd lint ./src --only deprecated --format json
antd lint ./src --only a11y --format json
antd lint ./src --only performance --format json

6. 檢查更新日誌與版本歷史

當使用者詢問某個版本的變更時：

# 特定版本的更新日誌
antd changelog 5.22.0 --format json

# 版本範圍（兩端包含）
antd changelog 5.21.0..5.24.0 --format json

7. 探索可用元件

當使用者正在選擇要使用的元件時：

# 列出所有元件及其分類
antd list --format json

# 列出特定 antd 版本的元件
antd list --version 5.0.0 --format json

8. 收集環境資訊

當你需要了解專案的 antd 設定，或準備錯誤回報的資訊時：

# 完整環境快照（文字 — 貼到 GitHub Issues）
antd env

# 結構化 JSON 供程式使用
antd env --format json

# 掃描特定專案目錄
antd env ./my-project --format json

收集內容：作業系統、Node、套件管理器 (npm/pnpm/yarn/bun/utoo)、npm registry、瀏覽器、核心相依套件 (antd/react/dayjs)、所有 @ant-design/* 和 rc-* 套件，以及建置工具 (umi/vite/webpack/typescript 等)。

9. 回報 antd 錯誤

當使用者要求你回報 antd 錯誤時：

# 步驟 0：收集環境資訊供參考（選用 — antd bug 已內嵌基本環境）
# 使用輸出交叉比對版本，或將額外細節附加到錯誤回報中
antd env --format json

# 步驟 1：預覽供使用者審閱
antd bug --title "DatePicker 選取日期時崩潰" \
  --reproduction "https://codesandbox.io/s/xxx" \
  --steps "1. 開啟 DatePicker 2. 點選日期" \
  --expected "日期被選取" \
  --actual "元件崩潰並顯示錯誤" \
  --format json

# 步驟 2：顯示給使用者，請求確認

# 步驟 3：使用者確認後提交
antd bug --title "DatePicker 選取日期時崩潰" \
  --reproduction "https://codesandbox.io/s/xxx" \
  --steps "1. 開啟 DatePicker 2. 點選日期" \
  --expected "日期被選取" \
  --actual "元件崩潰並顯示錯誤" \
  --submit

10. 回報 CLI 問題

當使用者要求你回報 CLI 錯誤，或明確請求協助提交問題時：

# 預覽錯誤回報供使用者查看
antd bug-cli --title "antd info Button 對 v5.12.0 回傳錯誤的屬性" \
  --description "查詢 Button 在版本 5.12.0 的屬性時，輸出包含該版本不存在的屬性" \
  --steps "1. 執行：antd info Button --version 5.12.0 --format json" \
  --expected "符合 antd 5.12.0 Button API 的屬性" \
  --actual "屬性包含 'classNames'，該屬性在 5.16.0 才加入" \
  --format json

將回報顯示給使用者，並在提交前確認：

antd bug-cli --title "antd info Button 對 v5.12.0 回傳錯誤的屬性" \
  --description "..." \
  --steps "..." \
  --expected "..." \
  --actual "..." \
  --submit

選擇退出： 若環境變數 ANTD_NO_AUTO_REPORT=1 已設定，則完全跳過所有錯誤回報建議 — 除非使用者直接要求，否則不要建議 antd bug 或 antd bug-cli。

11. 升級 CLI

當使用者想要將 @ant-design/cli 更新至最新版本，或出現「Update available」通知時：

# 升級至最新版本（自動偵測套件管理器）
antd upgrade

此指令會偵測安裝 CLI 的套件管理器（npm、yarn、pnpm、bun、cnpm、utoo），並執行對應的升級指令。若偵測失敗，則會建議手動指令。

12. 作為 MCP 伺服器使用

若在支援 MCP 的 IDE（Claude Desktop、Cursor 等）中工作，CLI 也可作為 MCP 伺服器執行，直接暴露所有知識查詢工具：

{
  "mcpServers": {
    "antd": {
      "command": "antd",
      "args": ["mcp", "--version", "5.20.0"]
    }
  }
}

這會透過 MCP 協定提供 8 個工具（antd_list、antd_info、antd_doc、antd_demo、antd_token、antd_design_md、antd_semantic、antd_changelog）和 2 個提示（antd-expert、antd-page-generator）。

全域旗標

旗標	用途
--format <format>	輸出格式：json、text 或 markdown（代理程式應偏好 json）
--version <v>	指定目標 antd 版本（例如 5.20.0）
--lang zh	中文輸出（預設：en）
--detail	包含額外欄位（說明、引入版本、棄用資訊、常見問題）
-V, --cli-version	顯示 CLI 版本並退出

關鍵規則

1. 查詢後再撰寫 — 不要憑記憶猜測 antd API。先執行 antd info。
2. 符合使用者版本 — 知識查詢（list/info/doc/demo/token/semantic/changelog）支援 antd v4 以上。若專案使用 antd 4.x/5.x/6.x，請傳入 --version 4.24.0 / 5.24.0 / 6.x。對於 antd v3 專案，請先使用 antd migrate 3 4。
3. 使用 --format json — 每個指令都支援此選項。解析 JSON 輸出，而非使用正規表示式比對文字輸出。
4. 建議遷移前先檢查 — 在建議版本升級前，先執行 antd changelog <v1> <v2> 和 antd migrate。
5. 修改後進行 lint — 在撰寫或修改 antd 程式碼後，對變更的檔案執行 antd lint，以找出已棄用或有問題的用法。
6. 回報 antd 錯誤 — 當使用者要求回報 antd 錯誤時，使用 antd bug。務必先預覽、取得使用者確認，再提交。
7. 回報 CLI 問題 — 當使用者詢問 CLI 問題時，使用 antd bug-cli 協助他們提交回報。務必先預覽、取得使用者確認，再提交。