antd

Ant Design CLI

你可以使用 @ant-design/cli——一个本地 CLI 工具，内置了 v4/v5/v6 的 antd 元数据（以及 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 bug 时：

# 收集完整环境快照（系统、依赖、浏览器、构建工具）
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 设置，或准备 bug 报告信息时：

# 完整环境快照（文本——粘贴到 GitHub Issues）
antd env

# 结构化 JSON 用于程序化使用
antd env --format json

# 扫描特定项目目录
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 bug

当用户要求你报告 antd bug 时：

# 步骤 0：收集环境信息供参考（可选——antd bug 已嵌入基本环境）
# 使用输出来交叉检查版本或向 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 bug，或明确请求帮助提交时：

# 预览 bug 报告给用户
antd bug-cli --title "antd info Button 返回 v5.12.0 的错误属性" \
  --description "查询版本 5.12.0 的 Button 属性时，输出包含该版本中不存在的属性" \
  --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，则完全跳过所有 bug 报告建议——除非用户直接要求，否则不要建议 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 bug——当用户要求报告 antd bug 时，使用 antd bug。始终先预览，获得用户确认，然后提交。
7. 报告 CLI 问题——当用户询问 CLI 问题时，使用 antd bug-cli 帮助他们提交报告。始终先预览，获得用户确认，然后提交。