@finedesign/cli 0.1.0 → 0.2.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 +20 -0
- package/README.md +50 -150
- package/data/1.25.0/catalog.json +1 -0
- package/data/1.25.0/manifest.json +16 -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/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 +152 -14
- package/src/core/catalog.mjs +63 -8
- package/src/core/contracts.mjs +14 -2
- package/src/core/data.mjs +7 -1
- package/src/core/html.cjs +32 -0
- package/src/core/runtime.mjs +62 -0
- package/src/core/version.mjs +11 -1
- package/src/mcp.mjs +9 -5
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# 更新日志
|
|
2
2
|
|
|
3
|
+
## 0.2.0
|
|
4
|
+
|
|
5
|
+
2026-11-04(待发布)
|
|
6
|
+
|
|
7
|
+
- CLI/MCP 增加在线 UMD 查询,按精确组件版本返回版本化 URL、SRI 和加载标签;仅托管当前最新文件,旧版本缺失时明确报错。
|
|
8
|
+
- `runtime --format html` 生成完整可运行页面,固定托管资源的版本化 URL、SRI 和 CORS 属性;失败时显示具体资源地址。默认入口统一为已验收的 Cloudflare production。
|
|
9
|
+
- 保留离线文档的多版本能力,与在线 UMD 可用性分别报告。
|
|
10
|
+
- 发布工具、托管、文档导出和 Skill 作者源统一至 `tools/fine-design`,提供完整本地构建、浏览器与打包安装验收。
|
|
11
|
+
- CLI 上传前持久化意图,上传中断保留原 tgz,仅继续查询和验收。
|
|
12
|
+
|
|
13
|
+
## 0.2.0-rc.0
|
|
14
|
+
|
|
15
|
+
2026-11-03
|
|
16
|
+
|
|
17
|
+
- 新增 `fine-design doctor` 只读环境自检命令,查看当前识别的组件版本、内置离线目录版本及内置 Skill 路径。
|
|
18
|
+
- `doc` 命令新增 `--toc` / `--summary`(MCP `get_component_doc` 新增可选 `summary: true`),支持先读取章节目录与示例列表再按需读取正文;`--section` 支持大小写不敏感匹配与相近章节提示。
|
|
19
|
+
- `example` / `get_component_example` 默认对超过 16 KB 的非入口 JSON 数据夹具返回截断预览与哈希元信息,通过 `--include-assets` / `includeAssets: true` 获取完整内容。
|
|
20
|
+
- 支持在 `@fx-ui/fine-design` 组件库源码仓库内直接识别工作区版本,并为 MCP 服务增加进程内目录缓存。
|
|
21
|
+
- 导出器与离线资料新增 `Combo.Check`(`combo-check`)独立文档及全部内置图标别名检索,收录 Fine Design `1.25.0`(保留 `1.24.9`)并同步最新 Fine Design Skill。
|
|
22
|
+
|
|
3
23
|
## 0.1.0
|
|
4
24
|
|
|
5
25
|
2026-11-02
|
package/README.md
CHANGED
|
@@ -1,186 +1,86 @@
|
|
|
1
|
-
# Fine Design CLI
|
|
1
|
+
# Fine Design CLI / MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
公开包为 `@finedesign/cli`,命令为 `fine-design`。当前准备正式版 `0.2.0`,尚未发布;内置 Fine Design `1.24.9` 与 `1.25.0` 的中文资料。Node.js 20+。工具版本、组件版本与在线 UMD 版本分别管理。
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
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;其他平台尚未完成验收。
|
|
5
|
+
发布后可固定安装:
|
|
15
6
|
|
|
16
7
|
```sh
|
|
17
|
-
npm install -g @finedesign/cli@0.
|
|
18
|
-
fine-design
|
|
8
|
+
npm install -g @finedesign/cli@0.2.0
|
|
9
|
+
fine-design doctor
|
|
19
10
|
```
|
|
20
11
|
|
|
21
|
-
|
|
12
|
+
当前工作区通过 `node tools/fine-design/cli/bin/fine-design.mjs` 运行。公开 CLI 及离线查询不需要公司私有源;安装私有组件包是独立操作。
|
|
22
13
|
|
|
23
|
-
|
|
24
|
-
npm install -D @finedesign/cli@0.1.0
|
|
25
|
-
npm exec -- fine-design --version
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
无需安装即可试用:
|
|
29
|
-
|
|
30
|
-
```sh
|
|
31
|
-
npx -y @finedesign/cli@0.1.0 --help
|
|
32
|
-
```
|
|
33
|
-
|
|
34
|
-
### 组件库安装与排查
|
|
35
|
-
|
|
36
|
-
公开 CLI 不需要公司私有源认证。页面工程安装 `@fx-ui/fine-design` 时,需要有权访问对应的组件源;只查询离线资料时,直接指定 `--fd-version 1.24.9` 即可。
|
|
37
|
-
|
|
38
|
-
在页面工程目录检查实际生效的配置:
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
|
-
npm config get @fx-ui:registry
|
|
42
|
-
npm config get registry
|
|
43
|
-
npm config get userconfig
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
没有项目 `.npmrc` 不代表没有配置:npm 也读取用户、全局配置和环境变量。项目配置只作用于当前工程,全局安装或临时目录不会自动继承另一工程的配置。
|
|
47
|
-
|
|
48
|
-
已有可用配置时,通过路径复用,不复制其中的凭据:
|
|
49
|
-
|
|
50
|
-
```sh
|
|
51
|
-
npm install @fx-ui/fine-design@1.24.9 --userconfig=/absolute/path/to/.npmrc
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
新工程需要公司源时,在项目 `.npmrc` 中合并以下非敏感配置,保留原有设置;其他 scope 仅在实际依赖需要时添加:
|
|
55
|
-
|
|
56
|
-
```ini
|
|
57
|
-
@fx-ui:registry=https://npm.jdydevelop.com/
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
需要认证时运行 `npm login --scope=@fx-ui --registry=https://npm.jdydevelop.com/`。不要将 Token 写入示例、共享文档或提交到仓库。npm 配置规则见 [npmrc](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc/)。
|
|
61
|
-
|
|
62
|
-
| 安装错误 | 排查方向 |
|
|
14
|
+
| 命令 | 用途 |
|
|
63
15
|
| --- | --- |
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
16
|
+
| `doctor` | 检查工程组件版本、已收录资料和内置 Skill |
|
|
17
|
+
| `search [query]` | 搜索组件、子组件、内置图标;`--offset` 分页 |
|
|
18
|
+
| `doc <component>` | 文档;`--toc` / `--summary` 读取目录,`--section` 读取章节 |
|
|
19
|
+
| `example <component> <id>` | 示例、依赖和资源;`--include-assets` 获取完整大资源 |
|
|
20
|
+
| `runtime list` | 联网读取当前托管的一个 UMD 组件版本 |
|
|
21
|
+
| `runtime` | 解析精确组件版本的版本化 URL、SRI 和加载标签 |
|
|
22
|
+
| `mcp` | 启动 stdio MCP 服务 |
|
|
71
23
|
|
|
72
24
|
```sh
|
|
73
|
-
|
|
74
|
-
fine-design
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
fine-design
|
|
78
|
-
|
|
79
|
-
|
|
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
|
|
25
|
+
fine-design search 表格 --fd-version 1.25.0 --format json
|
|
26
|
+
fine-design doc NextTable --toc --fd-version 1.25.0
|
|
27
|
+
fine-design doc NextTable --section 'Table 属性' --fd-version 1.25.0 --format markdown
|
|
28
|
+
fine-design example NextTable basic --fd-version 1.25.0 --format json
|
|
29
|
+
fine-design runtime list --format json
|
|
30
|
+
fine-design runtime --fd-version 1.25.0 --format json
|
|
31
|
+
fine-design runtime --fd-version 1.25.0 --format html > demo.html
|
|
84
32
|
```
|
|
85
33
|
|
|
86
|
-
|
|
34
|
+
显式 `--fd-version` 优先,否则从 `--project` 或当前目录向上查找实际安装包/组件源码仓库的版本。不会从依赖范围或锁文件自动猜测,不回退其他版本。`--format json` 适合 Agent;Markdown 格式仅用于 `doc`;`runtime --format html` 输出可直接打开的完整示例,用 shell 重定向保存文件。
|
|
87
35
|
|
|
88
|
-
|
|
36
|
+
离线资料可保留多个版本,在线 UMD 仅保留最新一份:`manifest.json` 直接包含当前精确版本和资源元数据。资源路径使用 `fine-design/<组件版本>/...` 和 `van-analysis/<图表版本>/...`,无 hash 目录、历史索引或 `--release-id`。升级后旧版本 URL 不保证可用;长期使用的独立页面应自行保存资源。SRI 仍用于校验字节,不能用版本号代替它。
|
|
89
37
|
|
|
90
|
-
|
|
38
|
+
默认运行时入口为 `https://fine-design-runtime.pages.dev/`,已部署 production 并通过资源及浏览器交互验收。可打开 [在线示例](https://fine-design-runtime.pages.dev/);`--runtime-url` 用于明确选择的其他托管地址,HTTP 仅允许本机回环测试。独立浏览器已验证生成的 HTML;内置文件预览的网络或沙箱行为需单独验证,资源加载失败时页面会显示具体 URL。
|
|
91
39
|
|
|
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` | 查看帮助 |
|
|
100
|
-
|
|
101
|
-
### 输出格式
|
|
102
|
-
|
|
103
|
-
默认输出便于人工阅读的文本。Agent 和脚本使用 `--format json`;文档查询还支持 `--format markdown`。
|
|
104
|
-
|
|
105
|
-
```sh
|
|
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
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
`search` 每页返回 20 条,下一页使用结果中的 `nextOffset`:
|
|
111
|
-
|
|
112
|
-
```sh
|
|
113
|
-
fine-design search --offset 20 --fd-version 1.24.9 --format json
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
### 示例与资源
|
|
117
|
-
|
|
118
|
-
示例结果包含 `entry`、`files`、`dependencies` 和 `unresolved`。文本文件返回完整内容;二进制文件默认只返回路径、编码、字节数和 SHA-256,以减少上下文占用。
|
|
119
|
-
|
|
120
|
-
需要完整二进制内容时:
|
|
121
|
-
|
|
122
|
-
```sh
|
|
123
|
-
fine-design example Avatar image --include-assets --fd-version 1.24.9 --format json
|
|
124
|
-
```
|
|
40
|
+
`runtime` 结果的 `docsAvailable` 描述当前 CLI 是否收录该组件版本,网络资源可用性独立。CSS → React → ReactDOM → Fine Design 顺序加载,用 `window.FineDesign` 访问控件;图表场景额外加载 `vanAnalysisCss` / `vanAnalysis`。返回的 `tags` 包含精确 URL、`integrity` 和 `crossorigin="anonymous"`,宿主需提供 CORS。
|
|
125
41
|
|
|
126
|
-
|
|
42
|
+
## MCP
|
|
127
43
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
在使用 `mcpServers` 字段的客户端中配置:
|
|
44
|
+
发布后按客户端配置语法使用:
|
|
131
45
|
|
|
132
46
|
```json
|
|
133
47
|
{
|
|
134
48
|
"mcpServers": {
|
|
135
49
|
"fine-design": {
|
|
136
50
|
"command": "npx",
|
|
137
|
-
"args": ["-y", "@finedesign/cli@0.
|
|
51
|
+
"args": ["-y", "@finedesign/cli@0.2.0", "mcp"]
|
|
138
52
|
}
|
|
139
53
|
}
|
|
140
54
|
}
|
|
141
55
|
```
|
|
142
56
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
|
146
|
-
|
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
|
|
151
|
-
每次 MCP 调用都必须传入精确的组件 `version`。例如调用 `get_component_doc`:
|
|
152
|
-
|
|
153
|
-
```json
|
|
154
|
-
{ "version": "1.24.9", "component": "NextTable" }
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
CLI JSON 与相同参数的 MCP 查询结果一致。MCP 工具为只读,不修改业务工程文件。
|
|
158
|
-
|
|
159
|
-
## Agent 使用
|
|
57
|
+
| 工具 | 输入 |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `search_components` | `version`、`query`,可选 `offset` |
|
|
60
|
+
| `get_component_doc` | `version`、`component`,可选 `section` / `summary` |
|
|
61
|
+
| `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` |
|
|
62
|
+
| `list_browser_runtimes` | 可选 `runtimeURL` |
|
|
63
|
+
| `get_browser_runtime` | `version`,可选 `runtimeURL` |
|
|
160
64
|
|
|
161
|
-
|
|
65
|
+
CLI JSON 与相同参数的 MCP 返回一致。所有工具只读;前三个使用离线资料,两个浏览器工具要求联网。除列举版本外必须传精确组件版本。
|
|
162
66
|
|
|
163
|
-
|
|
164
|
-
2. 使用 `search` 定位组件。
|
|
165
|
-
3. 使用 `doc` 阅读相关章节并选择示例 ID。
|
|
166
|
-
4. 使用 `example` 获取代码及依赖,再在项目中实现和验证。
|
|
67
|
+
## 安装配置与错误
|
|
167
68
|
|
|
168
|
-
|
|
69
|
+
缺少项目 `.npmrc` 不代表没有私有源配置,先检查实际生效的设置:
|
|
169
70
|
|
|
170
|
-
|
|
71
|
+
```sh
|
|
72
|
+
npm config get @fx-ui:registry
|
|
73
|
+
npm config get registry
|
|
74
|
+
npm config get userconfig
|
|
75
|
+
```
|
|
171
76
|
|
|
172
|
-
|
|
77
|
+
需要安装私有组件时复用授权配置路径,例如 `npm install @fx-ui/fine-design@<精确版本> --userconfig=/absolute/path/to/.npmrc`;不复制或输出 token。`E401` / `E403` 检查权限,`E404` 检查源和版本,连接失败检查网络。
|
|
173
78
|
|
|
174
|
-
|
|
|
79
|
+
| 错误 | 含义 |
|
|
175
80
|
| --- | --- |
|
|
176
|
-
| `VERSION_NOT_DETECTED`
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `docsAvailable: false` | 当前组件没有独立文档,按已安装包的公开声明核对用法 |
|
|
181
|
-
|
|
182
|
-
成功结果写入 stdout,错误写入 stderr。退出码:`0` 成功、`2` 参数错误、`3` 版本错误、`4` 资料不存在、`1` 其他运行错误。
|
|
183
|
-
|
|
184
|
-
## 许可证
|
|
81
|
+
| `VERSION_NOT_DETECTED` / `VERSION_NOT_SUPPORTED` | 未识别组件版本/CLI 未收录该精确版本 |
|
|
82
|
+
| `COMPONENT_NOT_FOUND` / `SECTION_NOT_FOUND` / `EXAMPLE_NOT_FOUND` | 使用搜索和文档目录核对名称 |
|
|
83
|
+
| `RUNTIME_UNAVAILABLE` / `RUNTIME_INVALID` | 托管不可用或清单不符合契约 |
|
|
84
|
+
| `RUNTIME_VERSION_NOT_FOUND` | 请求的 UMD 已不在当前托管目录,不回退 |
|
|
185
85
|
|
|
186
|
-
|
|
86
|
+
成功写 stdout,错误写 stderr;退出码:`0` 成功、`2` 参数、`3` 版本、`4` 资料不存在、`1` 其他错误。版本更新见 [CHANGELOG](CHANGELOG.md)。
|