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——不要依赖记忆。

# Check what props are available
antd info Button --format json

# Get a working demo as starting point
antd demo Button basic --format json

# Check semantic classNames/styles for custom styling
antd semantic Button --format json

# Check component-level design tokens for theming
antd token Button --format json

# Get the overall design language (design.md): colors, typography, spacing, radius + principles
antd design.md --format json

工作流：antd info → 了解 props → antd demo → 获取可用示例 → 编写代码。

2. 查询完整文档

需要全面的组件文档（而不只是 props）时：

antd doc Table --format json        # full markdown docs for Table
antd doc Table --lang zh            # Chinese docs

3. 调试 antd 问题

代码未按预期运行，或用户报告了 antd 错误时：

# Collect full environment snapshot (system, deps, browsers, build tools)
antd env --format json

# Check if the prop exists for the user's antd version
antd info Select --version 5.12.0 --format json

# Check if the prop is deprecated
antd lint ./src/components/MyForm.tsx --format json

# Diagnose project-level configuration issues
antd doctor --format json

工作流：antd env → 收集完整环境信息 → antd doctor → 检查配置 → antd info --version X → 根据用户使用的确切版本验证 API → antd lint → 查找已弃用或不正确的用法。

4. 在不同版本之间迁移

用户希望升级 antd 时（例如 v3 → v4 或 v4 → v5）：

# Get full migration checklist
antd migrate 3 4 --format json    # v3 → v4
antd migrate 4 5 --format json    # v4 → v5

# Check migration for a specific component
antd migrate 4 5 --component Select --format json

# Generate agent-friendly auto-migration prompt (does not modify files)
antd migrate 4 5 --apply ./src --format json

# See what changed between two versions
antd changelog 4.24.0 5.0.0 --format json

# See changes for a specific component
antd changelog 4.24.0 5.0.0 Select --format json

工作流：antd migrate → 获取完整检查清单 → antd changelog <v1> <v2> → 了解破坏性变更 → 应用修复 → antd lint → 确认不再存在已弃用的用法。

5. 分析项目中的 antd 用法

用户希望了解项目中 antd 的使用情况时：

# Scan component usage statistics
antd usage ./src --format json

# Filter to a specific component
antd usage ./src --filter Form --format json

# Lint for best practice violations
antd lint ./src --format json

# Check only specific rule categories
antd lint ./src --only deprecated --format json
antd lint ./src --only a11y --format json
antd lint ./src --only performance --format json

6. 查看变更日志和版本历史

用户询问某个版本有哪些变更时：

# Specific version changelog
antd changelog 5.22.0 --format json

# Version range (both ends inclusive)
antd changelog 5.21.0..5.24.0 --format json

7. 浏览可用组件

用户正在选择要使用的组件时：

# List all components with categories
antd list --format json

# List components for a specific antd version
antd list --version 5.0.0 --format json

8. 收集环境信息

需要了解项目的 antd 配置，或为错误报告准备信息时：

# Full environment snapshot (text — paste into GitHub Issues)
antd env

# Structured JSON for programmatic use
antd env --format json

# Scan a specific project directory
antd env ./my-project --format json

收集内容：操作系统、Node、包管理器（npm/pnpm/yarn/bun/utoo）、npm 注册表、浏览器、核心依赖（antd/react/dayjs）、所有 @ant-design/* 和 rc-* 包，以及构建工具（umi/vite/webpack/typescript 等）。

9. 报告 antd 错误

用户要求你报告 antd 错误时：

# Step 0: Collect environment info for reference (optional — antd bug already embeds basic env)
# Use the output to cross-check versions or attach extra details to the bug report
antd env --format json

# Step 1: Preview for user review
antd bug --title "DatePicker crashes when selecting date" \
  --reproduction "https://codesandbox.io/s/xxx" \
  --steps "1. Open DatePicker 2. Click a date" \
  --expected "Date is selected" \
  --actual "Component crashes with error" \
  --format json

# Step 2: Show to user, ask for confirmation

# Step 3: Submit after user confirms
antd bug --title "DatePicker crashes when selecting date" \
  --reproduction "https://codesandbox.io/s/xxx" \
  --steps "1. Open DatePicker 2. Click a date" \
  --expected "Date is selected" \
  --actual "Component crashes with error" \
  --submit

10. 报告 CLI 问题

用户要求你报告 CLI 错误，或明确请求协助提交问题时：

# Preview the bug report for the user
antd bug-cli --title "antd info Button returns wrong props for v5.12.0" \
  --description "When querying Button props for version 5.12.0, the output includes props that don't exist in that version" \
  --steps "1. Run: antd info Button --version 5.12.0 --format json" \
  --expected "Props matching antd 5.12.0 Button API" \
  --actual "Props include 'classNames' which was added in 5.16.0" \
  --format json

将报告展示给用户，并在提交前征得确认：

antd bug-cli --title "antd info Button returns wrong props for 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”提示时：

# Upgrade to the latest version (auto-detects package manager)
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（Agent 应优先使用 json）
--version <v>	指定目标 antd 版本（例如 5.20.0）
--lang zh	中文输出（默认：en）
--detail	包含额外字段（description、since、deprecated、FAQ）
-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 帮助其提交报告。务必先预览并征得用户确认，然后再提交。