@finedesign/cli 0.1.0 → 0.2.0-rc.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 +10 -0
- package/README.md +42 -30
- package/data/1.25.0/catalog.json +1 -0
- package/data/1.25.0/manifest.json +17 -0
- package/data/index.json +5 -1
- package/package.json +1 -1
- package/skills/fine-design/SKILL.md +3 -3
- package/skills/fine-design/references/browser-runtime-legacy.json +71 -0
- package/skills/fine-design/references/component-guide.md +1 -0
- package/skills/fine-design/references/docs-slug-map.md +12 -0
- package/skills/fine-design/references/imports-and-setup.md +19 -16
- package/skills/fine-design/references/theme-and-dark-mode.md +1 -0
- package/src/cli.mjs +137 -13
- package/src/core/catalog.mjs +63 -8
- package/src/core/contracts.mjs +12 -2
- package/src/core/data.mjs +7 -1
- package/src/core/version.mjs +11 -1
- package/src/mcp.mjs +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# 更新日志
|
|
2
2
|
|
|
3
|
+
## 0.2.0-rc.0
|
|
4
|
+
|
|
5
|
+
2026-11-03
|
|
6
|
+
|
|
7
|
+
- 新增 `fine-design doctor` 只读环境自检命令,查看当前识别的组件版本、内置离线目录版本及内置 Skill 路径。
|
|
8
|
+
- `doc` 命令新增 `--toc` / `--summary`(MCP `get_component_doc` 新增可选 `summary: true`),支持先读取章节目录与示例列表再按需读取正文;`--section` 支持大小写不敏感匹配与相近章节提示。
|
|
9
|
+
- `example` / `get_component_example` 默认对超过 16 KB 的非入口 JSON 数据夹具返回截断预览与哈希元信息,通过 `--include-assets` / `includeAssets: true` 获取完整内容。
|
|
10
|
+
- 支持在 `@fx-ui/fine-design` 组件库源码仓库内直接识别工作区版本,并为 MCP 服务增加进程内目录缓存。
|
|
11
|
+
- 导出器与离线资料新增 `Combo.Check`(`combo-check`)独立文档及全部内置图标别名检索,收录 Fine Design `1.25.0`(保留 `1.24.9`)并同步最新 Fine Design Skill。
|
|
12
|
+
|
|
3
13
|
## 0.1.0
|
|
4
14
|
|
|
5
15
|
2026-11-02
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
为开发者和 AI 编码助手提供版本化的 Fine Design 组件文档与示例。同一个包支持命令行查询和 MCP 服务,资料随包分发,安装后可离线使用。
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/@finedesign/cli) [](./LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/@finedesign/cli) [](https://www.npmjs.com/package/@finedesign/cli?activeTab=versions) [](./LICENSE)
|
|
6
6
|
|
|
7
7
|
- **按版本查询**:读取项目实际安装的组件版本,或显式指定精确版本。
|
|
8
8
|
- **完整示例**:返回入口代码、相对依赖文件和资源信息。
|
|
@@ -11,26 +11,30 @@
|
|
|
11
11
|
|
|
12
12
|
## 安装
|
|
13
13
|
|
|
14
|
-
需要 Node.js 20
|
|
14
|
+
需要 Node.js 20 或更高版本。本说明对应预发布版 `0.2.0-rc.0`,使用 `next` 渠道,内置 Fine Design `1.24.9` 与 `1.25.0` 的中文资料;稳定版 `latest` 仍为 `0.1.0`,只收录 `1.24.9`。
|
|
15
|
+
|
|
16
|
+
`doctor`、`--toc` / `--summary`、MCP `summary`、子组件与图标别名检索要求 `0.2.0-rc.0` 或更新版本。已验证 macOS arm64 上的 Node.js 20 和 22;其他平台尚未完成验收。
|
|
15
17
|
|
|
16
18
|
```sh
|
|
17
|
-
npm install -g @finedesign/cli@
|
|
19
|
+
npm install -g @finedesign/cli@next
|
|
18
20
|
fine-design --version
|
|
19
21
|
```
|
|
20
22
|
|
|
21
23
|
也可以安装到项目:
|
|
22
24
|
|
|
23
25
|
```sh
|
|
24
|
-
npm install -D @finedesign/cli@
|
|
26
|
+
npm install -D @finedesign/cli@next
|
|
25
27
|
npm exec -- fine-design --version
|
|
26
28
|
```
|
|
27
29
|
|
|
28
30
|
无需安装即可试用:
|
|
29
31
|
|
|
30
32
|
```sh
|
|
31
|
-
npx -y @finedesign/cli@
|
|
33
|
+
npx -y @finedesign/cli@next --help
|
|
32
34
|
```
|
|
33
35
|
|
|
36
|
+
需要固定本次版本时使用 `@finedesign/cli@0.2.0-rc.0`;需要稳定版时使用 `@finedesign/cli@latest`,并按 `1.24.9` 查询资料。
|
|
37
|
+
|
|
34
38
|
### 组件库安装与排查
|
|
35
39
|
|
|
36
40
|
公开 CLI 不需要公司私有源认证。页面工程安装 `@fx-ui/fine-design` 时,需要有权访问对应的组件源;只查询离线资料时,直接指定 `--fd-version 1.24.9` 即可。
|
|
@@ -70,20 +74,24 @@ npm install @fx-ui/fine-design@1.24.9 --userconfig=/absolute/path/to/.npmrc
|
|
|
70
74
|
## 快速开始
|
|
71
75
|
|
|
72
76
|
```sh
|
|
73
|
-
#
|
|
74
|
-
fine-design
|
|
77
|
+
# 检查识别到的组件版本、内置离线版本与内置 Skill 路径
|
|
78
|
+
fine-design doctor
|
|
75
79
|
|
|
76
|
-
#
|
|
77
|
-
fine-design
|
|
80
|
+
# 查找组件、子组件(如 Combo.Check)或内置图标
|
|
81
|
+
fine-design search 表格 --fd-version 1.25.0
|
|
82
|
+
fine-design search Combo.Check --fd-version 1.25.0
|
|
83
|
+
|
|
84
|
+
# 先查看章节目录与示例 ID(节省上下文 Token)
|
|
85
|
+
fine-design doc NextTable --toc --fd-version 1.25.0
|
|
78
86
|
|
|
79
87
|
# 读取一个 API 章节
|
|
80
|
-
fine-design doc NextTable --section 'Table 属性' --fd-version 1.
|
|
88
|
+
fine-design doc NextTable --section 'Table 属性' --fd-version 1.25.0
|
|
81
89
|
|
|
82
90
|
# 获取示例代码和依赖文件
|
|
83
|
-
fine-design example NextTable basic --fd-version 1.
|
|
91
|
+
fine-design example NextTable basic --fd-version 1.25.0 --format json
|
|
84
92
|
```
|
|
85
93
|
|
|
86
|
-
在已安装 `@fx-ui/fine-design`
|
|
94
|
+
在已安装 `@fx-ui/fine-design` 的项目(或 `@fx-ui/fine-design` 源码仓库)中,可以省略 `--fd-version`。CLI 从当前目录及父目录的 `node_modules`(或源码仓库根 `package.json`)读取真实精确版本,不根据依赖范围猜测版本,也不会回退到其他资料版本。
|
|
87
95
|
|
|
88
96
|
项目级安装时,在上述命令前加 `npm exec --`。跨目录查询时使用 `--project /path/to/project`。
|
|
89
97
|
|
|
@@ -91,36 +99,38 @@ fine-design example NextTable basic --fd-version 1.24.9 --format json
|
|
|
91
99
|
|
|
92
100
|
| 命令 | 说明 |
|
|
93
101
|
| --- | --- |
|
|
94
|
-
| `fine-design search [query]` |
|
|
95
|
-
| `fine-design doc <component>` |
|
|
102
|
+
| `fine-design search [query]` | 搜索组件、子组件与内置图标;不传关键词时分页浏览 |
|
|
103
|
+
| `fine-design doc <component>` | 读取文档;加 `--toc` / `--summary` 仅输出章节目录和示例 ID |
|
|
96
104
|
| `fine-design example <component> <id>` | 获取示例文件、外部依赖和未解析引用 |
|
|
105
|
+
| `fine-design doctor` | 只读检查当前识别的组件版本、已收录版本与内置 Skill 路径 |
|
|
97
106
|
| `fine-design mcp` | 启动 stdio MCP 服务 |
|
|
98
107
|
| `fine-design --version` | 查看工具版本 |
|
|
99
108
|
| `fine-design --help` | 查看帮助 |
|
|
100
109
|
|
|
101
110
|
### 输出格式
|
|
102
111
|
|
|
103
|
-
默认输出便于人工阅读的文本。Agent 和脚本使用 `--format json
|
|
112
|
+
默认输出便于人工阅读的文本。Agent 和脚本使用 `--format json`;`doc` 命令还支持 `--format markdown`(直接输出干净 Markdown)。
|
|
104
113
|
|
|
105
114
|
```sh
|
|
106
|
-
fine-design search 表格 --fd-version 1.
|
|
107
|
-
fine-design doc NextTable --section '
|
|
115
|
+
fine-design search 表格 --fd-version 1.25.0 --format json
|
|
116
|
+
fine-design doc NextTable --section 'Table 属性' --fd-version 1.25.0 --format markdown
|
|
108
117
|
```
|
|
109
118
|
|
|
110
119
|
`search` 每页返回 20 条,下一页使用结果中的 `nextOffset`:
|
|
111
120
|
|
|
112
121
|
```sh
|
|
113
|
-
fine-design search --offset 20 --fd-version 1.
|
|
122
|
+
fine-design search --offset 20 --fd-version 1.25.0 --format json
|
|
114
123
|
```
|
|
115
124
|
|
|
116
125
|
### 示例与资源
|
|
117
126
|
|
|
118
|
-
示例结果包含 `entry`、`files`、`dependencies` 和 `unresolved
|
|
127
|
+
示例结果包含 `entry`、`files`、`dependencies` 和 `unresolved`。常规源码文件返回完整内容;二进制文件以及超过 16 KB 的非入口 JSON 数据夹具默认返回路径、编码、字节数、SHA-256(大 JSON 额外提供前 512 字符 `preview` 与 `truncated: true`),以减少上下文占用。
|
|
119
128
|
|
|
120
|
-
|
|
129
|
+
需要完整二进制或超大 JSON 夹具内容时:
|
|
121
130
|
|
|
122
131
|
```sh
|
|
123
|
-
fine-design example Avatar image --include-assets --fd-version 1.
|
|
132
|
+
fine-design example Avatar image --include-assets --fd-version 1.25.0 --format json
|
|
133
|
+
fine-design example MCascader default --include-assets --fd-version 1.25.0 --format json
|
|
124
134
|
```
|
|
125
135
|
|
|
126
136
|
按 `encoding` 解码各文件,并根据 `dependencies` 补齐项目依赖。页面运行仍需匹配版本的 Fine Design、React 和样式;获取文件集合后,应执行消费工程的类型、构建和交互检查。
|
|
@@ -134,42 +144,44 @@ fine-design example Avatar image --include-assets --fd-version 1.24.9 --format j
|
|
|
134
144
|
"mcpServers": {
|
|
135
145
|
"fine-design": {
|
|
136
146
|
"command": "npx",
|
|
137
|
-
"args": ["-y", "@finedesign/cli@
|
|
147
|
+
"args": ["-y", "@finedesign/cli@next", "mcp"]
|
|
138
148
|
}
|
|
139
149
|
}
|
|
140
150
|
}
|
|
141
151
|
```
|
|
142
152
|
|
|
143
|
-
|
|
153
|
+
该配置启动 `next` 预发布版。需要固定版本时将包名改为 `@finedesign/cli@0.2.0-rc.0`。其他客户端使用各自的配置格式,保持相同的启动命令和参数。首次使用公开包需要从 npm 安装。
|
|
144
154
|
|
|
145
155
|
| 工具 | 输入 | 用途 |
|
|
146
156
|
| --- | --- | --- |
|
|
147
|
-
| `search_components` | `version`、`query`,可选 `offset` |
|
|
148
|
-
| `get_component_doc` | `version`、`component`,可选 `section` |
|
|
149
|
-
| `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` |
|
|
157
|
+
| `search_components` | `version`、`query`,可选 `offset` | 搜索组件、子组件与内置图标 |
|
|
158
|
+
| `get_component_doc` | `version`、`component`,可选 `section` 或 `summary` | 阅读文档或仅读取章节目录与示例列表 |
|
|
159
|
+
| `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` | 获取示例及依赖文件 |
|
|
150
160
|
|
|
151
161
|
每次 MCP 调用都必须传入精确的组件 `version`。例如调用 `get_component_doc`:
|
|
152
162
|
|
|
153
163
|
```json
|
|
154
|
-
{ "version": "1.
|
|
164
|
+
{ "version": "1.25.0", "component": "NextTable", "summary": true }
|
|
155
165
|
```
|
|
156
166
|
|
|
167
|
+
如果使用稳定版 `0.1.0`,请传入已收录的 `1.24.9`,并省略 `summary` 等新增参数。
|
|
168
|
+
|
|
157
169
|
CLI JSON 与相同参数的 MCP 查询结果一致。MCP 工具为只读,不修改业务工程文件。
|
|
158
170
|
|
|
159
171
|
## Agent 使用
|
|
160
172
|
|
|
161
173
|
建议按以下顺序获取实现所需信息:
|
|
162
174
|
|
|
163
|
-
1.
|
|
175
|
+
1. 运行 `doctor` 或检查工程安装包,确认项目实际的组件版本。
|
|
164
176
|
2. 使用 `search` 定位组件。
|
|
165
|
-
3. 使用 `doc`
|
|
177
|
+
3. 使用 `doc --toc`(或 MCP `summary: true`)查看章节与示例 ID,再按 `--section` 阅读所需章节。
|
|
166
178
|
4. 使用 `example` 获取代码及依赖,再在项目中实现和验证。
|
|
167
179
|
|
|
168
180
|
包内提供 [Fine Design Skill](./skills/fine-design/SKILL.md)。项目级安装后,文件位于 `node_modules/@finedesign/cli/skills/fine-design/`,可按客户端的 Skill 安装方式加载。npm 安装本身不会自动注册 Skill。
|
|
169
181
|
|
|
170
182
|
## 版本与错误
|
|
171
183
|
|
|
172
|
-
工具版本与组件版本分别管理:`--version` 显示 CLI 版本,`--fd-version` 指定 Fine Design
|
|
184
|
+
工具版本与组件版本分别管理:`--version` 显示 CLI 版本,`--fd-version` 指定 Fine Design 版本。`0.2.0-rc.0` 收录组件版本 `1.24.9` 与 `1.25.0`(可通过 `fine-design doctor` 查看),稳定版 `0.1.0` 只收录 `1.24.9`;未收录版本返回 `VERSION_NOT_SUPPORTED`。
|
|
173
185
|
|
|
174
186
|
| 情况 | 处理方式 |
|
|
175
187
|
| --- | --- |
|