ant-design

Ant Design

S - 范围

• 目标：antd@^6 + React 18-19；需要时使用 ant-design-pro@^5 / @ant-design/pro-components 和 @ant-design/x@^2。
• 工具：使用 @ant-design/cli 离线查询组件元数据、演示、变更日志、迁移、代码检查、doctor 检查和用法分析。
• 重点：仅提供决策指导；不提供面向终端用户的教程。
• 来源政策：仅使用官方文档；不使用未记录的 API，也不耦合内部 .ant-*。

默认假设

• 语言：TypeScript。
• 样式：优先使用 tokens，然后使用 classNames/styles；避免全局覆盖。
• Provider：除非需要严格隔离，否则使用一个根级 ConfigProvider。

强制规则

• 编写或修改 antd 组件代码前，先使用 antd info <Component> --format json 查询组件 API。如果 CLI 可以离线提供答案，就不要依赖记忆。
• 使用 antd CLI 命令时，始终添加 --format json。
• 如果项目版本很重要，请使用 --version <x.y.z> 匹配版本，或让 CLI 从本地 node_modules 自动检测。
• 修改 antd 代码后，运行 antd lint <changed-path> --format json。
• 如果 antd CLI 命令崩溃、返回错误数据或违反其记录的行为，请准备 antd bug-cli 预览并让用户确认，不要悄悄采用变通方案。
• 对于组件相关问题，先将组件名称映射到官方路由 slug {components}（小写 kebab-case，例如 TreeSelect -> tree-select、Button -> button），然后按以下顺序请求文档（优先中文，英文作为回退）：
  1. https://ant.design/components/{components}-cn
  2. https://ant.design/components/{components}
  • 示例：tree-select-cn -> tree-select、button-cn -> button。
• 仅使用有文档记录的 antd/Pro/X API。
• 不要编造 props、事件或组件名称。
• 不要依赖内部 DOM 或 .ant-* 选择器。
• 主题优先级：全局 tokens -> 组件 tokens -> 别名 tokens。

P - 流程

1）分类

• 确定所属层：核心 antd、Pro 或 X。
• 确认版本、渲染模式（CSR/SSR/streaming）、数据规模，以及是否应将 @ant-design/cli 作为首选查询途径。

2）查询权威来源

• 优先使用本地 @ant-design/cli 进行结构化查询：
  • antd info 查询 props/API
  • antd demo 获取可运行的基准示例
  • antd doc 查询完整文档
  • antd token / antd semantic 查询主题和样式钩子
  • 在调试或升级时使用 antd doctor、antd lint、antd usage、antd migrate、antd changelog
• 需要叙述性文档或交叉核对时，再请求官方组件文档（优先 -cn，英文作为回退）。

3）决策

• Provider 基准方案：CSR -> ConfigProvider；SSR -> ConfigProvider + StyleProvider。
• 主题基准方案：全局 tokens -> 组件 tokens -> classNames/styles。
• 给出建议、风险和验证要点（SSR/a11y/perf）；如使用 CLI，引用其查询结果。

O - 输出

• 提供简短的决策理由（1-3 句）。
• 包含精简的 provider/主题策略。
• 包含具体的 SSR/a11y/perf 检查项。
• 对于 Pro：说明路由/菜单/访问控制和 CRUD schema 方向。
• 对于 X：说明消息/工具 schema 和流式状态方向。

参考资料

文件	使用场景
references/antd-cli.md	需要查询 API、演示、代码检查、doctor 检查、迁移、变更日志审查、用法分析或 bug 报告的精确离线 CLI 流程时。

回归检查清单

• 一个根级 ConfigProvider；已验证 SSR 样式顺序和水合。
• 优先使用令牌；不进行宽泛的全局 .ant-* 覆盖。
• 表格具有稳定的 rowKey；排序、筛选和分页入口统一。
• Select 远程模式使用远程搜索时，会禁用本地筛选。
• 明确 Upload 的受控/非受控模式，并提供失败/重试路径。
• Pro 路由/菜单/访问权限与后端强制执行保持一致。
• X 流式传输支持停止/重试和确定性的工具渲染。
• 如果使用了 antd CLI，命令需带 --format json 运行，并通过 antd bug-cli 预览升级任何 CLI 缺陷。