特性

• 离线资料：组件 API、Design Token 和真实示例随包分发。
• 精确版本：识别工程实际安装的组件版本，不自动替换为其他版本的资料。
• Agent 接入：内置 Fine Design Skill，支持 JSON 输出与 stdio MCP。
• 代码检查：只读扫描常见 API 误用和非法导入，不修改源文件。
• 离线预览：导出校验过的浏览器资源和可运行示例，便于本地预览与归档。

安装

需要 Node.js 20+。推荐全局安装，一台机器只需安装一次，无需已有项目：

npm install -g @finedesign/cli

也可通过 npx -y @finedesign/cli 直接运行。CLI 安装和离线查询无需公司私有 npm 源；组件包安装是独立操作。

团队需要通过锁文件固定版本时，可在已有项目中用 npm install -D @finedesign/cli 安装，之后用 npx fine-design 调用。

快速开始

在使用 Fine Design 的工程目录运行：

fine-design doctor                    # 检查组件版本与内置 Skill 路径
fine-design info Button --format json  # 查询组件 API
fine-design example Button basic      # 读取真实示例源码
fine-design lint src/                 # 检查代码

尚未安装组件时，先用 doctor 查看可用资料版本，再通过 --fd-version <组件版本> 指定目标版本。

Agent 集成

Skill

安装 CLI 后，在准备使用 AI 助手的工作目录初始化：

fine-design init

空目录也可初始化，无需现有 React 项目或 package.json。init 默认配置 Cursor、Claude Code 和 Codex，写入主动调用 CLI 的项目规则，并为 Claude Code、Codex 安装内置 Skill；已有配置默认保留。换一个工作目录时，再执行一次 fine-design init。后续直接描述业务需求，助手会在 Fine Design 任务中核对目标版本 API、按需读取示例，并在改动后运行 lint 和项目检查；同一会话已查资料可复用。

也可让 AI 编码助手完成接入：

全局安装 @finedesign/cli（已安装则复用），在当前工作目录运行 fine-design init，空目录也可。确认当前助手的项目规则包含：涉及 Fine Design 的任务主动用 CLI 核对目标版本 API，改动后运行 lint 和项目检查。保留已有规则，本次只完成接入。

MCP

在支持 stdio MCP 的客户端中添加：

{
  "mcpServers": {
    "fine-design": {
      "command": "npx",
      "args": ["-y", "@finedesign/cli", "mcp"]
    }
  }
}

MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检查、浏览器运行时查询以及 Figma 节点映射与代码物料清单扫描（resolve_figma_component / list_figma_components / scan_figma_components）。客户端可自动发现工具参数。组件资料查询可省略 version：默认从 MCP 进程工作目录检测组件版本，检测不到时使用内置 Skill 对应的资料版本；已检测但未收录的版本仍会报错。代码检查从扫描目标检测版本。get_browser_runtime 省略版本时使用当前托管版本，运行时查询需要联网。

命令

以下命令均使用 fine-design 前缀，完整参数见 fine-design --help。

组件资料

工程检查

集成与代码落地

init 默认保留已有 Skill，更新需指定 --force；共享规则文件中只更新带标记的 Fine Design 内容，旧版无标记规则需手动处理。add 保留示例文件之间的相对目录关系，跨目录资源会生成相应子目录；已有文件冲突时在写入前报错，覆盖需指定 --force。两个命令均支持 --dry-run 预览文件变更。

版本与输出

• 组件版本：--fd-version 优先，其次使用 --project <目录> 指定的工程。未指定时，lint 从扫描目标检测版本，其他组件查询从当前工程检测。未收录的版本会报错。
• 输出格式：默认文本；--format json 适合 Agent。doc、info、token、figma 支持 Markdown；runtime 支持 HTML。
• 结果与错误：结果写入 stdout，错误写入 stderr。退出码 0 表示成功，1 表示检查未通过或运行错误，2 为参数问题，3 为版本问题，4 为资料未找到。

浏览器预览

已有构建流程的 React 应用使用私有组件包 @fx-ui/fine-design。独立 HTML、无构建嵌入页和原型可使用公开 UMD 运行时，浏览器无需安装组件包。

fine-design runtime list --format json
fine-design runtime --fd-version '<versions 中的版本>' --format html > demo.html
fine-design runtime --fd-version '<versions 中的版本>' --output ./offline-demo

--output 将运行时示例、资源和来源记录写入新目录，并保留 SRI。可加 --dry-run --format json 预览文件列表。首次导出需要联网，生成的页面仅引用本地资源。宿主须允许页面脚本和样式。

打开 Fine Design Playground。生成的 HTML 固定资源版本并附带 SRI 校验；在线托管仅保留当前版本，长期归档请保存对应资源。

更多资料

• 完整接入指南：Agent 配置、组件使用与 Figma 配合。
• 组件安装与样式配置：私有组件源、按需加载与样式前缀。
• 更新日志 · MIT License