@finedesign/cli 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +15 -0
- package/README.md +84 -70
- package/data/1.24.9/catalog.json +1 -1
- package/data/1.24.9/manifest.json +2 -2
- package/data/1.25.0/catalog.json +1 -1
- package/data/1.25.0/manifest.json +3 -3
- package/package.json +1 -1
- package/src/cli.mjs +7 -4
- package/src/core/contracts.mjs +21 -1
- package/src/core/lint.mjs +16 -11
- package/src/core/version.mjs +16 -0
- package/src/mcp.mjs +39 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,20 @@
|
|
|
1
1
|
# 更新日志
|
|
2
2
|
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
2026-11-05
|
|
6
|
+
|
|
7
|
+
- MCP 新增组件概览、Design Token、版本对比和代码检查,支持省略可选的工具参数。
|
|
8
|
+
- CLI 和 MCP 按扫描目标检测 Fine Design 版本,仅在执行 `lint` 时加载语法解析器。代码检查支持传统装饰器和 SVG 图标类型导入。
|
|
9
|
+
- 补齐 `1.24.9` 的 `Combo.Check`、图标示例和组件别名,更新 `1.25.0` 示例中的 Dialog 回调与图标导入。日期示例导出时移除站点专用样式前缀。
|
|
10
|
+
|
|
11
|
+
## 0.3.1
|
|
12
|
+
|
|
13
|
+
2026-11-05
|
|
14
|
+
|
|
15
|
+
- 重整 npm README,固定功能、安装、快速开始、Agent 集成与命令索引等章节,精简接入说明并使用动态版本徽章。
|
|
16
|
+
- 增加 README 维护约定和构建校验,普通发版无需改写正文;CLI 命令、组件资料和依赖保持不变。
|
|
17
|
+
|
|
3
18
|
## 0.3.0
|
|
4
19
|
|
|
5
20
|
2026-11-05
|
package/README.md
CHANGED
|
@@ -1,111 +1,125 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
Fine Design CLI
|
|
3
|
+
# Fine Design CLI
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
按项目版本查询 Fine Design 组件资料,供终端和 AI 编码助手使用。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
[](https://www.npmjs.com/package/@finedesign/cli)
|
|
8
|
+
[](https://unpkg.com/@finedesign/cli@latest/LICENSE)
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
[使用指南](https://docs.fanruan.design/docs/react/skills-cn) · [在线体验](https://fine-design-runtime.pages.dev/) · [更新日志](https://unpkg.com/@finedesign/cli@latest/CHANGELOG.md)
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
- 读取真实示例源码:`npx -y @finedesign/cli@0.3.0 example <Component> <exampleId>`
|
|
20
|
-
3. 完成代码修改后,执行 `npx -y @finedesign/cli@0.3.0 lint <文件或目录>` 扫描高频 API 陷阱与非法导入。
|
|
21
|
-
```
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
## 特性
|
|
15
|
+
|
|
16
|
+
- **离线资料**:组件 API、Design Token 和真实示例随包分发。
|
|
17
|
+
- **精确版本**:识别工程实际安装的组件版本,不自动替换为其他版本的资料。
|
|
18
|
+
- **Agent 接入**:内置 Fine Design Skill,支持 JSON 输出与 stdio MCP。
|
|
19
|
+
- **代码检查**:只读扫描常见 API 误用和非法导入,不修改源文件。
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
## 安装
|
|
22
|
+
|
|
23
|
+
需要 Node.js 20+。在项目中安装:
|
|
24
24
|
|
|
25
25
|
```sh
|
|
26
|
-
npm install -D @finedesign/cli
|
|
27
|
-
npx fine-design doctor
|
|
26
|
+
npm install -D @finedesign/cli
|
|
28
27
|
```
|
|
29
28
|
|
|
30
|
-
|
|
29
|
+
也可通过 `npx -y @finedesign/cli` 直接运行。CLI 安装和离线查询无需公司私有 npm 源;组件包安装是独立操作。
|
|
31
30
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
| `list` | 列出目标版本下的全部组件、导出项与简介 |
|
|
36
|
-
| `search [query]` | 搜索组件、子组件、中文别名、内置图标;支持 `--limit`、`--offset` 分页 |
|
|
37
|
-
| `info <component>` | 直接查看组件概览与 API / Props 属性章节;支持 `--format markdown` |
|
|
38
|
-
| `doc <component>` | 读取组件文档;`--toc` / `--summary` 读取目录,`--section` 读取章节 |
|
|
39
|
-
| `token [component] [query]` | 查询全局 Design Token 或指定组件的专属 Token;支持 `--format markdown` |
|
|
40
|
-
| `example <component> <id>` | 读取示例源码、依赖和资源;`--include-assets` 获取完整大资源 |
|
|
41
|
-
| `lint [files-or-dirs...]` | 扫描代码中的高频 API 陷阱、废弃组件与非法导入 |
|
|
42
|
-
| `diff [fromVer] [toVer]` | 对比两个版本间的新增组件、章节变更与迁移建议 |
|
|
43
|
-
| `runtime [list]` | 联网读取当前托管的 UMD 组件版本,或解析精确版本的 URL、SRI 与 HTML 页面 |
|
|
44
|
-
| `mcp` | 启动 stdio MCP 服务 |
|
|
31
|
+
## 快速开始
|
|
32
|
+
|
|
33
|
+
在使用 Fine Design 的工程目录运行:
|
|
45
34
|
|
|
46
35
|
```sh
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
fine-design doc NextTable --section 'Table 属性' --fd-version 1.25.0 --format markdown
|
|
52
|
-
fine-design token Button --fd-version 1.25.0
|
|
53
|
-
fine-design example NextTable basic --fd-version 1.25.0 --format json
|
|
54
|
-
fine-design lint src/ --fd-version 1.25.0
|
|
55
|
-
fine-design runtime list --format json
|
|
56
|
-
fine-design runtime --fd-version 1.25.0 --format html > demo.html
|
|
36
|
+
npx -y @finedesign/cli doctor # 检查组件版本与内置 Skill 路径
|
|
37
|
+
npx -y @finedesign/cli info Button --format json # 查询组件 API
|
|
38
|
+
npx -y @finedesign/cli example Button basic # 读取真实示例源码
|
|
39
|
+
npx -y @finedesign/cli lint src/ # 检查代码
|
|
57
40
|
```
|
|
58
41
|
|
|
59
|
-
|
|
42
|
+
尚未安装组件时,先用 `doctor` 查看可用资料版本,再通过 `--fd-version <组件版本>` 指定目标版本。
|
|
60
43
|
|
|
61
|
-
|
|
44
|
+
## Agent 集成
|
|
62
45
|
|
|
63
|
-
|
|
46
|
+
### Skill
|
|
64
47
|
|
|
65
|
-
|
|
48
|
+
CLI 内置 `skills/fine-design/SKILL.md`。将以下指令发给 AI 编码助手,或写入项目的 `AGENTS.md` / `CLAUDE.md`:
|
|
66
49
|
|
|
67
|
-
|
|
50
|
+
```text
|
|
51
|
+
开发、修复或评审 Fine Design 页面时:
|
|
52
|
+
1. 运行 npx -y @finedesign/cli doctor,读取输出路径中的 SKILL.md。
|
|
53
|
+
2. 按检测到的组件版本,通过 info、doc、token、example 查询 API 和真实示例;结构化结果使用 --format json。
|
|
54
|
+
3. 完成后运行 npx -y @finedesign/cli lint <文件或目录>,并执行项目现有构建、测试和关键交互验证。
|
|
55
|
+
```
|
|
68
56
|
|
|
69
|
-
|
|
57
|
+
### MCP
|
|
58
|
+
|
|
59
|
+
在支持 stdio MCP 的客户端中添加:
|
|
70
60
|
|
|
71
61
|
```json
|
|
72
62
|
{
|
|
73
63
|
"mcpServers": {
|
|
74
64
|
"fine-design": {
|
|
75
65
|
"command": "npx",
|
|
76
|
-
"args": ["-y", "@finedesign/cli
|
|
66
|
+
"args": ["-y", "@finedesign/cli", "mcp"]
|
|
77
67
|
}
|
|
78
68
|
}
|
|
79
69
|
}
|
|
80
70
|
```
|
|
81
71
|
|
|
82
|
-
|
|
72
|
+
MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检查和浏览器运行时查询。客户端可自动发现工具参数。组件查询需传入精确的 `version`,代码检查可以从目标工程检测版本,运行时查询需要联网。
|
|
73
|
+
|
|
74
|
+
## 命令
|
|
75
|
+
|
|
76
|
+
以下命令均使用 `npx -y @finedesign/cli` 前缀,完整参数见 `npx -y @finedesign/cli --help`。
|
|
77
|
+
|
|
78
|
+
### 组件资料
|
|
79
|
+
|
|
80
|
+
| 命令 | 用途 |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| `list` | 浏览组件及导出项 |
|
|
83
|
+
| `search [query]` | 搜索组件、中文别名、子组件与图标 |
|
|
84
|
+
| `info <component>` | 查看组件概览与 API |
|
|
85
|
+
| `doc <component>` | 阅读文档;`--toc` 查看目录,`--section` 选择章节 |
|
|
86
|
+
| `token [component] [query]` | 查询与筛选全局或组件 Token |
|
|
87
|
+
| `example <component> <id>` | 读取示例源码及资源信息 |
|
|
88
|
+
|
|
89
|
+
### 工程检查
|
|
90
|
+
|
|
91
|
+
| 命令 | 用途 |
|
|
83
92
|
| --- | --- |
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `list_browser_runtimes` | 可选 `runtimeURL` |
|
|
88
|
-
| `get_browser_runtime` | `version`,可选 `runtimeURL` |
|
|
93
|
+
| `doctor` | 检查组件版本、可用资料及 Skill 路径 |
|
|
94
|
+
| `lint [files-or-dirs...]` | 扫描常见 API 陷阱与非法导入 |
|
|
95
|
+
| `diff [fromVer] [toVer]` | 对比版本间的资料与迁移建议 |
|
|
89
96
|
|
|
90
|
-
|
|
97
|
+
### 集成与预览
|
|
91
98
|
|
|
92
|
-
|
|
99
|
+
| 命令 | 用途 |
|
|
100
|
+
| --- | --- |
|
|
101
|
+
| `mcp` | 启动 stdio MCP 服务 |
|
|
102
|
+
| `runtime [list]` | 查询在线运行时或生成完整 HTML 页面 |
|
|
103
|
+
|
|
104
|
+
## 版本与输出
|
|
93
105
|
|
|
94
|
-
|
|
106
|
+
- **组件版本**:`--fd-version` 优先,其次使用 `--project <目录>` 指定的工程。未指定时,`lint` 从扫描目标检测版本,其他组件查询从当前工程检测。未收录的版本会报错。
|
|
107
|
+
- **输出格式**:默认文本;`--format json` 适合 Agent。`doc`、`info`、`token` 支持 Markdown;`runtime` 支持 HTML。
|
|
108
|
+
- **结果与错误**:结果写入 stdout,错误写入 stderr。退出码 `0` 表示成功,`1` 表示检查未通过或运行错误,`2` 为参数问题,`3` 为版本问题,`4` 为资料未找到。
|
|
109
|
+
|
|
110
|
+
## 浏览器预览
|
|
111
|
+
|
|
112
|
+
独立 HTML 和原型可使用公开 UMD 运行时,无需安装组件包或配置构建工具。
|
|
95
113
|
|
|
96
114
|
```sh
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
npm config get userconfig
|
|
115
|
+
npx -y @finedesign/cli runtime list
|
|
116
|
+
npx -y @finedesign/cli runtime --format html > demo.html
|
|
100
117
|
```
|
|
101
118
|
|
|
102
|
-
|
|
119
|
+
[打开 Fine Design Playground](https://fine-design-runtime.pages.dev/)。生成的 HTML 固定资源版本并附带 SRI 校验;在线托管仅保留当前版本,长期归档请保存对应资源。
|
|
103
120
|
|
|
104
|
-
|
|
105
|
-
| --- | --- |
|
|
106
|
-
| `VERSION_NOT_DETECTED` / `VERSION_NOT_SUPPORTED` | 未识别组件版本/CLI 未收录该精确版本 |
|
|
107
|
-
| `COMPONENT_NOT_FOUND` / `SECTION_NOT_FOUND` / `EXAMPLE_NOT_FOUND` | 使用搜索和文档目录核对名称 |
|
|
108
|
-
| `RUNTIME_UNAVAILABLE` / `RUNTIME_INVALID` | 托管不可用或清单不符合契约 |
|
|
109
|
-
| `RUNTIME_VERSION_NOT_FOUND` | 请求的 UMD 已不在当前托管目录,不回退 |
|
|
121
|
+
## 更多资料
|
|
110
122
|
|
|
111
|
-
|
|
123
|
+
- [完整接入指南](https://docs.fanruan.design/docs/react/skills-cn):Agent 配置、组件使用与 Figma 配合。
|
|
124
|
+
- [组件安装与样式配置](https://docs.fanruan.design/docs/react/getstart-cn):私有组件源、按需加载与样式前缀。
|
|
125
|
+
- [更新日志](https://unpkg.com/@finedesign/cli@latest/CHANGELOG.md) · [MIT License](https://unpkg.com/@finedesign/cli@latest/LICENSE)
|