@finedesign/cli 0.1.0-rc.0 → 0.1.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 -11
- package/README.md +130 -62
- package/data/1.24.9/catalog.json +1 -1
- package/data/1.24.9/manifest.json +6 -6
- package/package.json +1 -1
- package/skills/fine-design/SKILL.md +1 -1
- package/skills/fine-design/references/imports-and-setup.md +28 -0
- package/src/core/version.mjs +6 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,16 +1,20 @@
|
|
|
1
|
-
#
|
|
1
|
+
# 更新日志
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
2026-11-02
|
|
6
|
+
|
|
7
|
+
- 发布首个正式版本,提供组件搜索、文档与示例查询,以及三个只读 MCP 工具。
|
|
8
|
+
- 改善组件未安装时的排查提示,支持在未安装组件库的工程中显式指定版本查询离线资料。
|
|
9
|
+
- 补充组件库安装、私有源认证和独立 HTML 预览说明,区分公开 CLI 与组件库的安装要求。
|
|
10
|
+
- 内置 Fine Design 1.24.9 中文资料及更新后的 Fine Design Skill。
|
|
4
11
|
|
|
5
12
|
## 0.1.0-rc.0
|
|
6
13
|
|
|
7
|
-
|
|
14
|
+
2026-11-02
|
|
8
15
|
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
- 工具目录统一为 `tools/fine-design-cli`,本地与私有 npm 包名统一为 `@fx-ui/fine-design-cli`。
|
|
15
|
-
- 补齐 Message、Notification、Toast、SvgIcon 公开导出;父章节查询包含子章节内容。
|
|
16
|
-
- 示例默认返回文本代码与二进制资产元信息,通过 CLI `--include-assets` 或 MCP `includeAssets: true` 获取完整二进制内容。
|
|
16
|
+
- 提供 `fine-design` 命令,支持组件搜索、文档章节和示例查询。
|
|
17
|
+
- 提供 stdio MCP 服务,包含三个只读工具,与 CLI 使用相同的查询结果和错误契约。
|
|
18
|
+
- 内置 Fine Design 1.24.9 中文资料和 Fine Design Skill。
|
|
19
|
+
- 支持完整示例文件及相对依赖读取;二进制资源默认返回元信息,可按需获取完整内容。
|
|
20
|
+
- 支持从项目实际安装包识别组件版本;未收录版本明确报错。
|
package/README.md
CHANGED
|
@@ -1,118 +1,186 @@
|
|
|
1
|
-
# Fine Design CLI
|
|
1
|
+
# Fine Design CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
为开发者和 AI 编码助手提供版本化的 Fine Design 组件文档与示例。同一个包支持命令行查询和 MCP 服务,资料随包分发,安装后可离线使用。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/@finedesign/cli) [](./LICENSE)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- **按版本查询**:读取项目实际安装的组件版本,或显式指定精确版本。
|
|
8
|
+
- **完整示例**:返回入口代码、相对依赖文件和资源信息。
|
|
9
|
+
- **适合 Agent**:支持 JSON 输出、结构化错误和只读 MCP 工具。
|
|
10
|
+
- **离线资料**:查询不需要 API Key 或远程文档服务。
|
|
11
|
+
|
|
12
|
+
## 安装
|
|
13
|
+
|
|
14
|
+
需要 Node.js 20 或更高版本。当前版本为 `0.1.0`,内置 Fine Design `1.24.9` 的中文资料。已验证 macOS arm64 上的 Node.js 20 和 22;其他平台尚未完成验收。
|
|
8
15
|
|
|
9
16
|
```sh
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
npm run build
|
|
13
|
-
npm test
|
|
14
|
-
npm run pack:all
|
|
15
|
-
npm run test:package
|
|
17
|
+
npm install -g @finedesign/cli@0.1.0
|
|
18
|
+
fine-design --version
|
|
16
19
|
```
|
|
17
20
|
|
|
18
|
-
|
|
21
|
+
也可以安装到项目:
|
|
19
22
|
|
|
20
|
-
|
|
23
|
+
```sh
|
|
24
|
+
npm install -D @finedesign/cli@0.1.0
|
|
25
|
+
npm exec -- fine-design --version
|
|
26
|
+
```
|
|
21
27
|
|
|
22
|
-
|
|
28
|
+
无需安装即可试用:
|
|
23
29
|
|
|
24
30
|
```sh
|
|
25
|
-
|
|
26
|
-
npm run test:ai-docs
|
|
27
|
-
npm --prefix tools/fine-design-cli run sync:data -- --from ../../artifacts/ai-docs/1.24.9
|
|
31
|
+
npx -y @finedesign/cli@0.1.0 --help
|
|
28
32
|
```
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
### 组件库安装与排查
|
|
31
35
|
|
|
32
|
-
|
|
36
|
+
公开 CLI 不需要公司私有源认证。页面工程安装 `@fx-ui/fine-design` 时,需要有权访问对应的组件源;只查询离线资料时,直接指定 `--fd-version 1.24.9` 即可。
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
在页面工程目录检查实际生效的配置:
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
npm config get @fx-ui:registry
|
|
42
|
+
npm config get registry
|
|
43
|
+
npm config get userconfig
|
|
44
|
+
```
|
|
35
45
|
|
|
36
|
-
|
|
46
|
+
没有项目 `.npmrc` 不代表没有配置:npm 也读取用户、全局配置和环境变量。项目配置只作用于当前工程,全局安装或临时目录不会自动继承另一工程的配置。
|
|
37
47
|
|
|
38
|
-
|
|
48
|
+
已有可用配置时,通过路径复用,不复制其中的凭据:
|
|
39
49
|
|
|
40
50
|
```sh
|
|
41
|
-
npm
|
|
51
|
+
npm install @fx-ui/fine-design@1.24.9 --userconfig=/absolute/path/to/.npmrc
|
|
42
52
|
```
|
|
43
53
|
|
|
44
|
-
|
|
54
|
+
新工程需要公司源时,在项目 `.npmrc` 中合并以下非敏感配置,保留原有设置;其他 scope 仅在实际依赖需要时添加:
|
|
45
55
|
|
|
46
|
-
|
|
56
|
+
```ini
|
|
57
|
+
@fx-ui:registry=https://npm.jdydevelop.com/
|
|
58
|
+
```
|
|
47
59
|
|
|
48
|
-
|
|
60
|
+
需要认证时运行 `npm login --scope=@fx-ui --registry=https://npm.jdydevelop.com/`。不要将 Token 写入示例、共享文档或提交到仓库。npm 配置规则见 [npmrc](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc/)。
|
|
49
61
|
|
|
50
|
-
|
|
62
|
+
| 安装错误 | 排查方向 |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| `E401` / `E403` | 配置是否生效、登录是否过期,以及账号是否有包的读取权限 |
|
|
65
|
+
| `E404` | scope 是否指向正确源、版本是否存在;私有源也可能隐藏无权限的包 |
|
|
66
|
+
| 连接失败或超时 | 网络、VPN、代理和 registry 地址 |
|
|
51
67
|
|
|
52
|
-
|
|
68
|
+
仅需独立 HTML 预览时,可使用 [Standalone HTML](./skills/fine-design/references/imports-and-setup.md#standalone-html) 的公开 Runtime。它不替代 React 工程的依赖安装;未版本化 CDN 资源也不保证与指定 npm 版本一致。
|
|
53
69
|
|
|
54
|
-
|
|
70
|
+
## 快速开始
|
|
55
71
|
|
|
56
72
|
```sh
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
73
|
+
# 查找组件
|
|
74
|
+
fine-design search 表格 --fd-version 1.24.9
|
|
75
|
+
|
|
76
|
+
# 阅读组件文档及可用章节
|
|
77
|
+
fine-design doc NextTable --fd-version 1.24.9
|
|
78
|
+
|
|
79
|
+
# 读取一个 API 章节
|
|
80
|
+
fine-design doc NextTable --section 'Table 属性' --fd-version 1.24.9
|
|
81
|
+
|
|
82
|
+
# 获取示例代码和依赖文件
|
|
83
|
+
fine-design example NextTable basic --fd-version 1.24.9 --format json
|
|
60
84
|
```
|
|
61
85
|
|
|
62
|
-
|
|
86
|
+
在已安装 `@fx-ui/fine-design` 的项目中,可以省略 `--fd-version`。CLI 从当前目录及父目录的 `node_modules` 读取真实安装版本,不根据依赖范围猜测版本,也不会回退到其他资料版本。
|
|
87
|
+
|
|
88
|
+
项目级安装时,在上述命令前加 `npm exec --`。跨目录查询时使用 `--project /path/to/project`。
|
|
89
|
+
|
|
90
|
+
## 命令
|
|
63
91
|
|
|
64
|
-
|
|
92
|
+
| 命令 | 说明 |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| `fine-design search [query]` | 搜索组件;不传关键词时分页浏览 |
|
|
95
|
+
| `fine-design doc <component>` | 读取文档,查看章节名和示例 ID |
|
|
96
|
+
| `fine-design example <component> <id>` | 获取示例文件、外部依赖和未解析引用 |
|
|
97
|
+
| `fine-design mcp` | 启动 stdio MCP 服务 |
|
|
98
|
+
| `fine-design --version` | 查看工具版本 |
|
|
99
|
+
| `fine-design --help` | 查看帮助 |
|
|
65
100
|
|
|
66
|
-
|
|
101
|
+
### 输出格式
|
|
67
102
|
|
|
68
|
-
|
|
103
|
+
默认输出便于人工阅读的文本。Agent 和脚本使用 `--format json`;文档查询还支持 `--format markdown`。
|
|
69
104
|
|
|
70
105
|
```sh
|
|
71
|
-
|
|
72
|
-
|
|
106
|
+
fine-design search 表格 --fd-version 1.24.9 --format json
|
|
107
|
+
fine-design doc NextTable --section '组件 API' --fd-version 1.24.9 --format markdown
|
|
73
108
|
```
|
|
74
109
|
|
|
75
|
-
|
|
110
|
+
`search` 每页返回 20 条,下一页使用结果中的 `nextOffset`:
|
|
76
111
|
|
|
77
|
-
|
|
112
|
+
```sh
|
|
113
|
+
fine-design search --offset 20 --fd-version 1.24.9 --format json
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### 示例与资源
|
|
78
117
|
|
|
79
|
-
|
|
118
|
+
示例结果包含 `entry`、`files`、`dependencies` 和 `unresolved`。文本文件返回完整内容;二进制文件默认只返回路径、编码、字节数和 SHA-256,以减少上下文占用。
|
|
119
|
+
|
|
120
|
+
需要完整二进制内容时:
|
|
80
121
|
|
|
81
122
|
```sh
|
|
82
|
-
|
|
83
|
-
npx --registry=https://registry.npmjs.org/ --@finedesign:registry=https://registry.npmjs.org/ -y @finedesign/cli@0.1.0-rc.0 search 表格 --fd-version 1.24.9 --format json
|
|
84
|
-
npx --registry=https://registry.npmjs.org/ --@finedesign:registry=https://registry.npmjs.org/ -y @finedesign/cli@0.1.0-rc.0 mcp
|
|
123
|
+
fine-design example Avatar image --include-assets --fd-version 1.24.9 --format json
|
|
85
124
|
```
|
|
86
125
|
|
|
87
|
-
|
|
126
|
+
按 `encoding` 解码各文件,并根据 `dependencies` 补齐项目依赖。页面运行仍需匹配版本的 Fine Design、React 和样式;获取文件集合后,应执行消费工程的类型、构建和交互检查。
|
|
88
127
|
|
|
89
|
-
##
|
|
128
|
+
## MCP 接入
|
|
90
129
|
|
|
91
|
-
|
|
130
|
+
在使用 `mcpServers` 字段的客户端中配置:
|
|
92
131
|
|
|
93
|
-
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"mcpServers": {
|
|
135
|
+
"fine-design": {
|
|
136
|
+
"command": "npx",
|
|
137
|
+
"args": ["-y", "@finedesign/cli@0.1.0", "mcp"]
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
```
|
|
94
142
|
|
|
95
|
-
|
|
143
|
+
其他客户端使用各自的配置格式,保持相同的启动命令和参数。首次运行需要从 npm 安装包。
|
|
96
144
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
145
|
+
| 工具 | 输入 | 用途 |
|
|
146
|
+
| --- | --- | --- |
|
|
147
|
+
| `search_components` | `version`、`query`,可选 `offset` | 搜索组件 |
|
|
148
|
+
| `get_component_doc` | `version`、`component`,可选 `section` | 阅读文档 |
|
|
149
|
+
| `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` | 获取示例 |
|
|
150
|
+
|
|
151
|
+
每次 MCP 调用都必须传入精确的组件 `version`。例如调用 `get_component_doc`:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{ "version": "1.24.9", "component": "NextTable" }
|
|
104
155
|
```
|
|
105
156
|
|
|
106
|
-
|
|
157
|
+
CLI JSON 与相同参数的 MCP 查询结果一致。MCP 工具为只读,不修改业务工程文件。
|
|
158
|
+
|
|
159
|
+
## Agent 使用
|
|
160
|
+
|
|
161
|
+
建议按以下顺序获取实现所需信息:
|
|
162
|
+
|
|
163
|
+
1. 确认项目实际安装的组件版本。
|
|
164
|
+
2. 使用 `search` 定位组件。
|
|
165
|
+
3. 使用 `doc` 阅读相关章节并选择示例 ID。
|
|
166
|
+
4. 使用 `example` 获取代码及依赖,再在项目中实现和验证。
|
|
167
|
+
|
|
168
|
+
包内提供 [Fine Design Skill](./skills/fine-design/SKILL.md)。项目级安装后,文件位于 `node_modules/@finedesign/cli/skills/fine-design/`,可按客户端的 Skill 安装方式加载。npm 安装本身不会自动注册 Skill。
|
|
107
169
|
|
|
108
|
-
|
|
170
|
+
## 版本与错误
|
|
109
171
|
|
|
110
|
-
`
|
|
172
|
+
工具版本与组件版本分别管理:`--version` 显示 CLI 版本,`--fd-version` 指定 Fine Design 版本。当前仅收录组件版本 `1.24.9`;未收录版本返回 `VERSION_NOT_SUPPORTED`。
|
|
111
173
|
|
|
112
|
-
|
|
174
|
+
| 情况 | 处理方式 |
|
|
175
|
+
| --- | --- |
|
|
176
|
+
| `VERSION_NOT_DETECTED` | 在已安装组件库的项目中运行,或使用 `--project` / `--fd-version` |
|
|
177
|
+
| `VERSION_NOT_SUPPORTED` | 使用已收录的精确版本 |
|
|
178
|
+
| `COMPONENT_NOT_FOUND` | 先通过 `search` 确认组件导出名 |
|
|
179
|
+
| `SECTION_NOT_FOUND` / `EXAMPLE_NOT_FOUND` | 使用 `doc` 返回的章节名或示例 ID |
|
|
180
|
+
| `docsAvailable: false` | 当前组件没有独立文档,按已安装包的公开声明核对用法 |
|
|
113
181
|
|
|
114
|
-
|
|
182
|
+
成功结果写入 stdout,错误写入 stderr。退出码:`0` 成功、`2` 参数错误、`3` 版本错误、`4` 资料不存在、`1` 其他运行错误。
|
|
115
183
|
|
|
116
|
-
|
|
184
|
+
## 许可证
|
|
117
185
|
|
|
118
|
-
|
|
186
|
+
[MIT](./LICENSE) · [更新日志](./CHANGELOG.md)
|