# @finedesign/cli 中文文档

规范地址：https://npmcn.com/package/%40finedesign/cli/

版本：0\.9\.0
npm 元数据更新时间：2026-11-12T09:49:19.373Z
中文译文更新时间：2026-11-14T19:06:58.139Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40finedesign/cli
原文对照：https://npmcn.com/package/%40finedesign/cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.5 MB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：3 个
- 首次发布：2026-11-02T03:21:13.492Z
- 最新版本发布：2026-11-12T09:49:18.880Z
- 近 30 天下载量：3002（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

版本精细设计文件、编码检查和编码代理设置

## 安装

```sh
npm install @finedesign/cli
```

也可以使用：`pnpm add @finedesign/cli`、`yarn add @finedesign/cli`、`bun add @finedesign/cli`

## README

# Fine Design CLI

按项目版本查询 Fine Design 组件资料，供终端和 AI 编码助手使用。

[![npm](https://img.shields.io/npm/v/@finedesign/cli)](https://www.npmjs.com/package/@finedesign/cli) [![License](https://img.shields.io/npm/l/@finedesign/cli)](https://unpkg.com/@finedesign/cli@latest/LICENSE)

[使用指南](https://docs.fanruan.design/docs/react/skills-cn) · [在线体验](https://fine-design-runtime.pages.dev/) · [更新日志](https://unpkg.com/@finedesign/cli@latest/CHANGELOG.md)

## 特性

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

## 安装

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

```sh
npm install -g @finedesign/cli
```

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

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

## 快速开始

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

```sh
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 助手的工作目录初始化：

```sh
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 的客户端中添加：

```json
{
  "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`。

### 组件资料

| 命令 | 用途 |
| --- | --- |
| `list` | 浏览组件及导出项 |
| `search [query]` | 搜索组件、中文别名、子组件与图标 |
| `info <component>` | 查看组件概览与 API |
| `doc <component>` | 阅读文档；`--toc` 查看目录，`--section` 选择章节 |
| `token [component] [query]` | 查询与筛选全局或组件 Token |
| `example <component> [id]` | 列出示例 ID 和标题，或按 ID 读取源码及资源信息 |

### 工程检查

| 命令 | 用途 |
| --- | --- |
| `doctor` | 检查组件版本、资料来源、可用资料及 Skill 路径 |
| `lint [files-or-dirs...]` | 扫描常见 API 陷阱与非法导入 |
| `diff [fromVer] [toVer]` | 对比版本间的文档和示例，提供通用迁移建议，支持 `--component <name>` |

### 集成与代码落地

| 命令 | 用途 |
| --- | --- |
| `init` | 一键初始化 Agent 规则与配置（`--agent cursor/claude/codex/all`） |
| `add <component> [id]` | 提取组件示例代码及附属文件到项目目录（支持 `--output` 与 `--force`） |
| `figma <resolve|list|scan>` | 反查 Fine Design 库节点的离线 Code Connect 映射、浏览已连接模板，或扫描代码输出物料清单 (BOM) |
| `mcp` | 启动 stdio MCP 服务 |
| `runtime [list]` | 查询在线运行时或生成完整 HTML 页面 |

`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 运行时，浏览器无需安装组件包。

```sh
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](https://fine-design-runtime.pages.dev/)。生成的 HTML 固定资源版本并附带 SRI 校验；在线托管仅保留当前版本，长期归档请保存对应资源。

## 更多资料

-   [完整接入指南](https://docs.fanruan.design/docs/react/skills-cn)：Agent 配置、组件使用与 Figma 配合。
-   [组件安装与样式配置](https://docs.fanruan.design/docs/react/getstart-cn)：私有组件源、按需加载与样式前缀。
-   [更新日志](https://unpkg.com/@finedesign/cli@latest/CHANGELOG.md) · [MIT License](https://unpkg.com/@finedesign/cli@latest/LICENSE)

## 常见问题

### @finedesign/cli 是什么？

版本精细设计文件、编码检查和编码代理设置

### 如何安装 @finedesign/cli？

在项目目录运行 npm install @finedesign/cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 fine-design，可以用 npx fine-design 直接运行。

### @finedesign/cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/finedesign\_\_cli 是否存在。

### @finedesign/cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @finedesign/cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @finedesign/cli 可以商用吗？

@finedesign/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @finedesign/cli 的下载量有多少？

根据 npm 官方下载统计，@finedesign/cli 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,002 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @finedesign/cli 还在维护吗？

最新版本 0\.9\.0 发布于 2026/11/12（2 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/11/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。