@finedesign/cli 0.2.0 → 0.3.1

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 CHANGED
@@ -1,8 +1,25 @@
1
1
  # 更新日志
2
2
 
3
+ ## 0.3.1
4
+
5
+ 2026-11-05
6
+
7
+ - 重整 npm README,固定功能、安装、快速开始、Agent 集成与命令索引等章节,精简接入说明并使用动态版本徽章。
8
+ - 增加 README 维护约定和构建校验,普通发版无需改写正文;CLI 命令、组件资料和依赖保持不变。
9
+
10
+ ## 0.3.0
11
+
12
+ 2026-11-05
13
+
14
+ - 新增 `list`、`info`、`token`、`lint`、`diff` 命令,支持组件列表、API 概览、设计变量查询、代码检查和跨版本资料对比;搜索新增 `--limit`。
15
+ - 优化搜索排序,补充中文、子组件及图标别名和拼写建议;完善资料简介、Token 表格及可复用示例。
16
+ - `lint` 使用语法树区分代码、注释和字符串,修正 Button 类型与建议,支持解构重命名,并区分类型导出和运行时值。
17
+ - 从对应历史提交补齐 Fine Design `1.24.9` 的组件 Token 资料;文本 `diff` 增加被移除组件列表。
18
+ - 补齐 `1.24.9` 内置图标导出,修复 `lint` 对组件重命名及局部同名绑定的误判,并使 Token 查询的 Markdown 输出遵循筛选条件。
19
+
3
20
  ## 0.2.0
4
21
 
5
- 2026-11-04(待发布)
22
+ 2026-11-04
6
23
 
7
24
  - CLI/MCP 增加在线 UMD 查询,按精确组件版本返回版本化 URL、SRI 和加载标签;仅托管当前最新文件,旧版本缺失时明确报错。
8
25
  - `runtime --format html` 生成完整可运行页面,固定托管资源的版本化 URL、SRI 和 CORS 属性;失败时显示具体资源地址。默认入口统一为已验收的 Cloudflare production。
package/README.md CHANGED
@@ -1,86 +1,125 @@
1
- # Fine Design CLI / MCP
1
+ <div align="center">
2
2
 
3
- 公开包为 `@finedesign/cli`,命令为 `fine-design`。当前准备正式版 `0.2.0`,尚未发布;内置 Fine Design `1.24.9` 与 `1.25.0` 的中文资料。Node.js 20+。工具版本、组件版本与在线 UMD 版本分别管理。
3
+ # Fine Design CLI
4
4
 
5
- 发布后可固定安装:
5
+ 按项目版本查询 Fine Design 组件资料,供终端和 AI 编码助手使用。
6
+
7
+ [![npm](https://img.shields.io/npm/v/@finedesign/cli)](https://www.npmjs.com/package/@finedesign/cli)
8
+ [![License](https://img.shields.io/npm/l/@finedesign/cli)](https://unpkg.com/@finedesign/cli@latest/LICENSE)
9
+
10
+ [使用指南](https://docs.fanruan.design/docs/react/skills-cn) · [在线体验](https://fine-design-runtime.pages.dev/) · [更新日志](https://unpkg.com/@finedesign/cli@latest/CHANGELOG.md)
11
+
12
+ </div>
13
+
14
+ ## 特性
15
+
16
+ - **离线资料**:组件 API、Design Token 和真实示例随包分发。
17
+ - **精确版本**:识别工程实际安装的组件版本,不自动替换为其他版本的资料。
18
+ - **Agent 接入**:内置 Fine Design Skill,支持 JSON 输出与 stdio MCP。
19
+ - **代码检查**:只读扫描常见 API 误用和非法导入,不修改源文件。
20
+
21
+ ## 安装
22
+
23
+ 需要 Node.js 20+。在项目中安装:
6
24
 
7
25
  ```sh
8
- npm install -g @finedesign/cli@0.2.0
9
- fine-design doctor
26
+ npm install -D @finedesign/cli
10
27
  ```
11
28
 
12
- 当前工作区通过 `node tools/fine-design/cli/bin/fine-design.mjs` 运行。公开 CLI 及离线查询不需要公司私有源;安装私有组件包是独立操作。
29
+ 也可通过 `npx -y @finedesign/cli` 直接运行。CLI 安装和离线查询无需公司私有 npm 源;组件包安装是独立操作。
13
30
 
14
- | 命令 | 用途 |
15
- | --- | --- |
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 服务 |
31
+ ## 快速开始
32
+
33
+ 在使用 Fine Design 的工程目录运行:
23
34
 
24
35
  ```sh
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
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/ # 检查代码
32
40
  ```
33
41
 
34
- 显式 `--fd-version` 优先,否则从 `--project` 或当前目录向上查找实际安装包/组件源码仓库的版本。不会从依赖范围或锁文件自动猜测,不回退其他版本。`--format json` 适合 Agent;Markdown 格式仅用于 `doc`;`runtime --format html` 输出可直接打开的完整示例,用 shell 重定向保存文件。
42
+ 尚未安装组件时,先用 `doctor` 查看可用资料版本,再通过 `--fd-version <组件版本>` 指定目标版本。
35
43
 
36
- 离线资料可保留多个版本,在线 UMD 仅保留最新一份:`manifest.json` 直接包含当前精确版本和资源元数据。资源路径使用 `fine-design/<组件版本>/...` 和 `van-analysis/<图表版本>/...`,无 hash 目录、历史索引或 `--release-id`。升级后旧版本 URL 不保证可用;长期使用的独立页面应自行保存资源。SRI 仍用于校验字节,不能用版本号代替它。
44
+ ## Agent 集成
37
45
 
38
- 默认运行时入口为 `https://fine-design-runtime.pages.dev/`,已部署 production 并通过资源及浏览器交互验收。可打开 [在线示例](https://fine-design-runtime.pages.dev/);`--runtime-url` 用于明确选择的其他托管地址,HTTP 仅允许本机回环测试。独立浏览器已验证生成的 HTML;内置文件预览的网络或沙箱行为需单独验证,资源加载失败时页面会显示具体 URL。
46
+ ### Skill
39
47
 
40
- `runtime` 结果的 `docsAvailable` 描述当前 CLI 是否收录该组件版本,网络资源可用性独立。CSS → React → ReactDOM → Fine Design 顺序加载,用 `window.FineDesign` 访问控件;图表场景额外加载 `vanAnalysisCss` / `vanAnalysis`。返回的 `tags` 包含精确 URL、`integrity` 和 `crossorigin="anonymous"`,宿主需提供 CORS。
48
+ CLI 内置 `skills/fine-design/SKILL.md`。将以下指令发给 AI 编码助手,或写入项目的 `AGENTS.md` / `CLAUDE.md`:
41
49
 
42
- ## MCP
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
+ ```
43
56
 
44
- 发布后按客户端配置语法使用:
57
+ ### MCP
58
+
59
+ 在支持 stdio MCP 的客户端中添加:
45
60
 
46
61
  ```json
47
62
  {
48
63
  "mcpServers": {
49
64
  "fine-design": {
50
65
  "command": "npx",
51
- "args": ["-y", "@finedesign/cli@0.2.0", "mcp"]
66
+ "args": ["-y", "@finedesign/cli", "mcp"]
52
67
  }
53
68
  }
54
69
  }
55
70
  ```
56
71
 
57
- | 工具 | 输入 |
72
+ MCP 提供组件搜索、文档、示例和浏览器运行时查询;工具输入结构由客户端自动发现。组件查询需传入精确的 `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
+ | 命令 | 用途 |
58
92
  | --- | --- |
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` |
93
+ | `doctor` | 检查组件版本、可用资料及 Skill 路径 |
94
+ | `lint [files-or-dirs...]` | 扫描常见 API 陷阱与非法导入 |
95
+ | `diff [fromVer] [toVer]` | 对比版本间的资料与迁移建议 |
64
96
 
65
- CLI JSON 与相同参数的 MCP 返回一致。所有工具只读;前三个使用离线资料,两个浏览器工具要求联网。除列举版本外必须传精确组件版本。
97
+ ### 集成与预览
66
98
 
67
- ## 安装配置与错误
99
+ | 命令 | 用途 |
100
+ | --- | --- |
101
+ | `mcp` | 启动 stdio MCP 服务 |
102
+ | `runtime [list]` | 查询在线运行时或生成完整 HTML 页面 |
103
+
104
+ ## 版本与输出
68
105
 
69
- 缺少项目 `.npmrc` 不代表没有私有源配置,先检查实际生效的设置:
106
+ - **组件版本**:`--fd-version` 优先;否则从当前工程或 `--project <目录>` 检测实际安装版本。未收录的版本明确报错,不降级或猜测。
107
+ - **输出格式**:默认文本;`--format json` 适合 Agent。`doc`、`info`、`token` 支持 Markdown;`runtime` 支持 HTML。
108
+ - **结果与错误**:结果写入 stdout,错误写入 stderr。退出码 `0` 表示成功,`1` 表示检查未通过或运行错误,`2` 为参数问题,`3` 为版本问题,`4` 为资料未找到。
109
+
110
+ ## 浏览器预览
111
+
112
+ 独立 HTML 和原型可使用公开 UMD 运行时,无需安装组件包或配置构建工具。
70
113
 
71
114
  ```sh
72
- npm config get @fx-ui:registry
73
- npm config get registry
74
- npm config get userconfig
115
+ npx -y @finedesign/cli runtime list
116
+ npx -y @finedesign/cli runtime --format html > demo.html
75
117
  ```
76
118
 
77
- 需要安装私有组件时复用授权配置路径,例如 `npm install @fx-ui/fine-design@<精确版本> --userconfig=/absolute/path/to/.npmrc`;不复制或输出 token。`E401` / `E403` 检查权限,`E404` 检查源和版本,连接失败检查网络。
119
+ [打开 Fine Design Playground](https://fine-design-runtime.pages.dev/)。生成的 HTML 固定资源版本并附带 SRI 校验;在线托管仅保留当前版本,长期归档请保存对应资源。
78
120
 
79
- | 错误 | 含义 |
80
- | --- | --- |
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 已不在当前托管目录,不回退 |
121
+ ## 更多资料
85
122
 
86
- 成功写 stdout,错误写 stderr;退出码:`0` 成功、`2` 参数、`3` 版本、`4` 资料不存在、`1` 其他错误。版本更新见 [CHANGELOG](CHANGELOG.md)。
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)