@finedesign/cli 0.2.0-rc.0 → 0.3.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 +68 -155
- 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 +7 -8
- package/package.json +2 -1
- package/skills/fine-design/SKILL.md +2 -2
- package/skills/fine-design/references/component-guide.md +1 -1
- package/skills/fine-design/references/imports-and-setup.md +8 -8
- package/src/cli.mjs +165 -10
- package/src/core/catalog.mjs +300 -19
- package/src/core/contracts.mjs +8 -1
- package/src/core/html.cjs +152 -0
- package/src/core/lint.mjs +302 -0
- package/src/core/runtime.mjs +62 -0
- package/src/mcp.mjs +7 -3
- package/skills/fine-design/references/browser-runtime-legacy.json +0 -71
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# 更新日志
|
|
2
2
|
|
|
3
|
+
## 0.3.0
|
|
4
|
+
|
|
5
|
+
2026-11-05
|
|
6
|
+
|
|
7
|
+
- 新增 `list`、`info`、`token`、`lint`、`diff` 命令,支持组件列表、API 概览、设计变量查询、代码检查和跨版本资料对比;搜索新增 `--limit`。
|
|
8
|
+
- 优化搜索排序,补充中文、子组件及图标别名和拼写建议;完善资料简介、Token 表格及可复用示例。
|
|
9
|
+
- `lint` 使用语法树区分代码、注释和字符串,修正 Button 类型与建议,支持解构重命名,并区分类型导出和运行时值。
|
|
10
|
+
- 从对应历史提交补齐 Fine Design `1.24.9` 的组件 Token 资料;文本 `diff` 增加被移除组件列表。
|
|
11
|
+
- 补齐 `1.24.9` 内置图标导出,修复 `lint` 对组件重命名及局部同名绑定的误判,并使 Token 查询的 Markdown 输出遵循筛选条件。
|
|
12
|
+
|
|
13
|
+
## 0.2.0
|
|
14
|
+
|
|
15
|
+
2026-11-04
|
|
16
|
+
|
|
17
|
+
- CLI/MCP 增加在线 UMD 查询,按精确组件版本返回版本化 URL、SRI 和加载标签;仅托管当前最新文件,旧版本缺失时明确报错。
|
|
18
|
+
- `runtime --format html` 生成完整可运行页面,固定托管资源的版本化 URL、SRI 和 CORS 属性;失败时显示具体资源地址。默认入口统一为已验收的 Cloudflare production。
|
|
19
|
+
- 保留离线文档的多版本能力,与在线 UMD 可用性分别报告。
|
|
20
|
+
- 发布工具、托管、文档导出和 Skill 作者源统一至 `tools/fine-design`,提供完整本地构建、浏览器与打包安装验收。
|
|
21
|
+
- CLI 上传前持久化意图,上传中断保留原 tgz,仅继续查询和验收。
|
|
22
|
+
|
|
3
23
|
## 0.2.0-rc.0
|
|
4
24
|
|
|
5
25
|
2026-11-03
|
package/README.md
CHANGED
|
@@ -1,198 +1,111 @@
|
|
|
1
|
-
# Fine Design CLI
|
|
1
|
+
# Fine Design CLI / MCP (`@finedesign/cli`)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Fine Design CLI(`@finedesign/cli`)提供按工程组件版本查询的离线文档、Design Token、Demo 源码、代码检查与 AI Skill(`skills/fine-design/SKILL.md`),支持命令行和 MCP 接入。当前版本为 `0.3.0`,命令为 `fine-design`,要求 Node.js 20+。CLI 安装及离线查询不需要公司私有 npm 源。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 快速接入 Agent
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
- **完整示例**:返回入口代码、相对依赖文件和资源信息。
|
|
9
|
-
- **适合 Agent**:支持 JSON 输出、结构化错误和只读 MCP 工具。
|
|
10
|
-
- **离线资料**:查询不需要 API Key 或远程文档服务。
|
|
7
|
+
### 1. 复制指令直接接入 Agent
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
将以下提示词复制给 **Claude Code / Cursor / Codex / Windsurf**,或写入项目 `AGENTS.md` / `CLAUDE.md`:
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
```sh
|
|
26
|
-
npm install -D @finedesign/cli@next
|
|
27
|
-
npm exec -- fine-design --version
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
无需安装即可试用:
|
|
31
|
-
|
|
32
|
-
```sh
|
|
33
|
-
npx -y @finedesign/cli@next --help
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
需要固定本次版本时使用 `@finedesign/cli@0.2.0-rc.0`;需要稳定版时使用 `@finedesign/cli@latest`,并按 `1.24.9` 查询资料。
|
|
37
|
-
|
|
38
|
-
### 组件库安装与排查
|
|
39
|
-
|
|
40
|
-
公开 CLI 不需要公司私有源认证。页面工程安装 `@fx-ui/fine-design` 时,需要有权访问对应的组件源;只查询离线资料时,直接指定 `--fd-version 1.24.9` 即可。
|
|
41
|
-
|
|
42
|
-
在页面工程目录检查实际生效的配置:
|
|
43
|
-
|
|
44
|
-
```sh
|
|
45
|
-
npm config get @fx-ui:registry
|
|
46
|
-
npm config get registry
|
|
47
|
-
npm config get userconfig
|
|
11
|
+
```text
|
|
12
|
+
在当前工程开发、修复或评审 Fine Design (@fx-ui/fine-design) 界面时,请使用 @finedesign/cli:
|
|
13
|
+
1. 先执行 `npx -y @finedesign/cli@0.3.0 doctor` 识别工程当前安装的 Fine Design 版本,并读取输出的 Bundled Skill (`SKILL.md`) 路径。
|
|
14
|
+
2. 按需通过 CLI 查询精确版本资料(优先加 `--format json`):
|
|
15
|
+
- 组件概览与 API 表:`npx -y @finedesign/cli@0.3.0 info <Component>`
|
|
16
|
+
- 搜索组件、子组件或内置图标:`npx -y @finedesign/cli@0.3.0 search <关键词>`
|
|
17
|
+
- 文档章节目录与示例列表:`npx -y @finedesign/cli@0.3.0 doc <Component> --toc`
|
|
18
|
+
- 全局或组件 Design Token:`npx -y @finedesign/cli@0.3.0 token [Component]`
|
|
19
|
+
- 读取真实示例源码:`npx -y @finedesign/cli@0.3.0 example <Component> <exampleId>`
|
|
20
|
+
3. 完成代码修改后,执行 `npx -y @finedesign/cli@0.3.0 lint <文件或目录>` 扫描高频 API 陷阱与非法导入。
|
|
48
21
|
```
|
|
49
22
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
已有可用配置时,通过路径复用,不复制其中的凭据:
|
|
23
|
+
高频使用时可安装到工程开发依赖或全局:
|
|
53
24
|
|
|
54
25
|
```sh
|
|
55
|
-
npm install @
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
新工程需要公司源时,在项目 `.npmrc` 中合并以下非敏感配置,保留原有设置;其他 scope 仅在实际依赖需要时添加:
|
|
59
|
-
|
|
60
|
-
```ini
|
|
61
|
-
@fx-ui:registry=https://npm.jdydevelop.com/
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
需要认证时运行 `npm login --scope=@fx-ui --registry=https://npm.jdydevelop.com/`。不要将 Token 写入示例、共享文档或提交到仓库。npm 配置规则见 [npmrc](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc/)。
|
|
65
|
-
|
|
66
|
-
| 安装错误 | 排查方向 |
|
|
67
|
-
| --- | --- |
|
|
68
|
-
| `E401` / `E403` | 配置是否生效、登录是否过期,以及账号是否有包的读取权限 |
|
|
69
|
-
| `E404` | scope 是否指向正确源、版本是否存在;私有源也可能隐藏无权限的包 |
|
|
70
|
-
| 连接失败或超时 | 网络、VPN、代理和 registry 地址 |
|
|
71
|
-
|
|
72
|
-
仅需独立 HTML 预览时,可使用 [Standalone HTML](./skills/fine-design/references/imports-and-setup.md#standalone-html) 的公开 Runtime。它不替代 React 工程的依赖安装;未版本化 CDN 资源也不保证与指定 npm 版本一致。
|
|
73
|
-
|
|
74
|
-
## 快速开始
|
|
75
|
-
|
|
76
|
-
```sh
|
|
77
|
-
# 检查识别到的组件版本、内置离线版本与内置 Skill 路径
|
|
78
|
-
fine-design doctor
|
|
79
|
-
|
|
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
|
|
86
|
-
|
|
87
|
-
# 读取一个 API 章节
|
|
88
|
-
fine-design doc NextTable --section 'Table 属性' --fd-version 1.25.0
|
|
89
|
-
|
|
90
|
-
# 获取示例代码和依赖文件
|
|
91
|
-
fine-design example NextTable basic --fd-version 1.25.0 --format json
|
|
26
|
+
npm install -D @finedesign/cli@0.3.0
|
|
27
|
+
npx fine-design doctor
|
|
92
28
|
```
|
|
93
29
|
|
|
94
|
-
|
|
30
|
+
### 2. 命令速查
|
|
95
31
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
## 命令
|
|
99
|
-
|
|
100
|
-
| 命令 | 说明 |
|
|
32
|
+
| 命令 | 用途 |
|
|
101
33
|
| --- | --- |
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
34
|
+
| `doctor` | 检查工程组件版本、已收录资料和内置 Skill 路径 |
|
|
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 服务 |
|
|
113
45
|
|
|
114
46
|
```sh
|
|
47
|
+
fine-design list --fd-version 1.25.0
|
|
115
48
|
fine-design search 表格 --fd-version 1.25.0 --format json
|
|
49
|
+
fine-design info Select --fd-version 1.25.0 --format markdown
|
|
50
|
+
fine-design doc NextTable --toc --fd-version 1.25.0
|
|
116
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
|
|
117
57
|
```
|
|
118
58
|
|
|
119
|
-
`
|
|
120
|
-
|
|
121
|
-
```sh
|
|
122
|
-
fine-design search --offset 20 --fd-version 1.25.0 --format json
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
### 示例与资源
|
|
59
|
+
显式 `--fd-version` 优先,否则从 `--project` 或当前目录向上查找实际安装包/组件源码仓库的版本。不会从依赖范围或锁文件自动猜测,不回退其他版本。`--format json` 适合 Agent;Markdown 格式支持 `doc`、`info`、`token`;`runtime --format html` 输出可直接打开的完整示例,用 shell 重定向保存文件。
|
|
126
60
|
|
|
127
|
-
|
|
61
|
+
在线 UMD 托管提供当前版本的资源,`manifest.json` 包含精确版本和资源元数据。资源路径使用 `fine-design/<组件版本>/...` 和 `van-analysis/<图表版本>/...`,通过 SRI 校验资源字节。长期使用的独立页面应自行保存对应资源。
|
|
128
62
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
```sh
|
|
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
|
|
134
|
-
```
|
|
63
|
+
默认运行时入口为 [在线示例](https://fine-design-runtime.pages.dev/);`--runtime-url` 可指定其他托管地址,HTTP 仅允许本机回环测试。资源加载失败时,生成的页面会显示具体 URL。
|
|
135
64
|
|
|
136
|
-
|
|
65
|
+
`runtime` 结果的 `docsAvailable` 描述当前 CLI 是否收录该组件版本,网络资源可用性独立。CSS → React → ReactDOM → Fine Design 顺序加载,用 `window.FineDesign` 访问控件;图表场景额外加载 `vanAnalysisCss` / `vanAnalysis`。返回的 `tags` 包含精确 URL、`integrity` 和 `crossorigin="anonymous"`,宿主需提供 CORS。
|
|
137
66
|
|
|
138
|
-
## MCP
|
|
67
|
+
## MCP
|
|
139
68
|
|
|
140
|
-
|
|
69
|
+
按客户端配置语法使用:
|
|
141
70
|
|
|
142
71
|
```json
|
|
143
72
|
{
|
|
144
73
|
"mcpServers": {
|
|
145
74
|
"fine-design": {
|
|
146
75
|
"command": "npx",
|
|
147
|
-
"args": ["-y", "@finedesign/cli@
|
|
76
|
+
"args": ["-y", "@finedesign/cli@0.3.0", "mcp"]
|
|
148
77
|
}
|
|
149
78
|
}
|
|
150
79
|
}
|
|
151
80
|
```
|
|
152
81
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
|
156
|
-
|
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
159
|
-
| `
|
|
160
|
-
|
|
161
|
-
每次 MCP 调用都必须传入精确的组件 `version`。例如调用 `get_component_doc`:
|
|
162
|
-
|
|
163
|
-
```json
|
|
164
|
-
{ "version": "1.25.0", "component": "NextTable", "summary": true }
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
如果使用稳定版 `0.1.0`,请传入已收录的 `1.24.9`,并省略 `summary` 等新增参数。
|
|
168
|
-
|
|
169
|
-
CLI JSON 与相同参数的 MCP 查询结果一致。MCP 工具为只读,不修改业务工程文件。
|
|
170
|
-
|
|
171
|
-
## Agent 使用
|
|
82
|
+
| 工具 | 输入 |
|
|
83
|
+
| --- | --- |
|
|
84
|
+
| `search_components` | `version`、`query`,可选 `offset` / `limit` |
|
|
85
|
+
| `get_component_doc` | `version`、`component`,可选 `section` / `summary` |
|
|
86
|
+
| `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` |
|
|
87
|
+
| `list_browser_runtimes` | 可选 `runtimeURL` |
|
|
88
|
+
| `get_browser_runtime` | `version`,可选 `runtimeURL` |
|
|
172
89
|
|
|
173
|
-
|
|
90
|
+
CLI JSON 与相同参数的 MCP 返回一致。所有工具只读;前三个使用离线资料,两个浏览器工具要求联网。除列举版本外必须传精确组件版本。
|
|
174
91
|
|
|
175
|
-
|
|
176
|
-
2. 使用 `search` 定位组件。
|
|
177
|
-
3. 使用 `doc --toc`(或 MCP `summary: true`)查看章节与示例 ID,再按 `--section` 阅读所需章节。
|
|
178
|
-
4. 使用 `example` 获取代码及依赖,再在项目中实现和验证。
|
|
92
|
+
## 安装配置与错误
|
|
179
93
|
|
|
180
|
-
|
|
94
|
+
缺少项目 `.npmrc` 不代表没有私有源配置,先检查实际生效的设置:
|
|
181
95
|
|
|
182
|
-
|
|
96
|
+
```sh
|
|
97
|
+
npm config get @fx-ui:registry
|
|
98
|
+
npm config get registry
|
|
99
|
+
npm config get userconfig
|
|
100
|
+
```
|
|
183
101
|
|
|
184
|
-
|
|
102
|
+
需要安装私有组件时复用授权配置路径,例如 `npm install @fx-ui/fine-design@<精确版本> --userconfig=/absolute/path/to/.npmrc`;不复制或输出 token。`E401` / `E403` 检查权限,`E404` 检查源和版本,连接失败检查网络。
|
|
185
103
|
|
|
186
|
-
|
|
|
104
|
+
| 错误 | 含义 |
|
|
187
105
|
| --- | --- |
|
|
188
|
-
| `VERSION_NOT_DETECTED`
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `docsAvailable: false` | 当前组件没有独立文档,按已安装包的公开声明核对用法 |
|
|
193
|
-
|
|
194
|
-
成功结果写入 stdout,错误写入 stderr。退出码:`0` 成功、`2` 参数错误、`3` 版本错误、`4` 资料不存在、`1` 其他运行错误。
|
|
195
|
-
|
|
196
|
-
## 许可证
|
|
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 已不在当前托管目录,不回退 |
|
|
197
110
|
|
|
198
|
-
|
|
111
|
+
成功写 stdout,错误写 stderr;退出码:`0` 成功、`2` 参数、`3` 版本、`4` 资料不存在、`1` 其他错误。版本更新见 [CHANGELOG](CHANGELOG.md)。
|