@finedesign/cli 0.2.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 CHANGED
@@ -1,8 +1,18 @@
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
+
3
13
  ## 0.2.0
4
14
 
5
- 2026-11-04(待发布)
15
+ 2026-11-04
6
16
 
7
17
  - CLI/MCP 增加在线 UMD 查询,按精确组件版本返回版本化 URL、SRI 和加载标签;仅托管当前最新文件,旧版本缺失时明确报错。
8
18
  - `runtime --format html` 生成完整可运行页面,固定托管资源的版本化 URL、SRI 和 CORS 属性;失败时显示具体资源地址。默认入口统一为已验收的 Cloudflare production。
package/README.md CHANGED
@@ -1,54 +1,79 @@
1
- # Fine Design CLI / MCP
1
+ # Fine Design CLI / MCP (`@finedesign/cli`)
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(`@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
+
7
+ ### 1. 复制指令直接接入 Agent
8
+
9
+ 将以下提示词复制给 **Claude Code / Cursor / Codex / Windsurf**,或写入项目 `AGENTS.md` / `CLAUDE.md`:
10
+
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 陷阱与非法导入。
21
+ ```
22
+
23
+ 高频使用时可安装到工程开发依赖或全局:
6
24
 
7
25
  ```sh
8
- npm install -g @finedesign/cli@0.2.0
9
- fine-design doctor
26
+ npm install -D @finedesign/cli@0.3.0
27
+ npx fine-design doctor
10
28
  ```
11
29
 
12
- 当前工作区通过 `node tools/fine-design/cli/bin/fine-design.mjs` 运行。公开 CLI 及离线查询不需要公司私有源;安装私有组件包是独立操作。
30
+ ### 2. 命令速查
13
31
 
14
32
  | 命令 | 用途 |
15
33
  | --- | --- |
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 和加载标签 |
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 页面 |
22
44
  | `mcp` | 启动 stdio MCP 服务 |
23
45
 
24
46
  ```sh
47
+ fine-design list --fd-version 1.25.0
25
48
  fine-design search 表格 --fd-version 1.25.0 --format json
49
+ fine-design info Select --fd-version 1.25.0 --format markdown
26
50
  fine-design doc NextTable --toc --fd-version 1.25.0
27
51
  fine-design doc NextTable --section 'Table 属性' --fd-version 1.25.0 --format markdown
52
+ fine-design token Button --fd-version 1.25.0
28
53
  fine-design example NextTable basic --fd-version 1.25.0 --format json
54
+ fine-design lint src/ --fd-version 1.25.0
29
55
  fine-design runtime list --format json
30
- fine-design runtime --fd-version 1.25.0 --format json
31
56
  fine-design runtime --fd-version 1.25.0 --format html > demo.html
32
57
  ```
33
58
 
34
- 显式 `--fd-version` 优先,否则从 `--project` 或当前目录向上查找实际安装包/组件源码仓库的版本。不会从依赖范围或锁文件自动猜测,不回退其他版本。`--format json` 适合 Agent;Markdown 格式仅用于 `doc`;`runtime --format html` 输出可直接打开的完整示例,用 shell 重定向保存文件。
59
+ 显式 `--fd-version` 优先,否则从 `--project` 或当前目录向上查找实际安装包/组件源码仓库的版本。不会从依赖范围或锁文件自动猜测,不回退其他版本。`--format json` 适合 Agent;Markdown 格式支持 `doc`、`info`、`token`;`runtime --format html` 输出可直接打开的完整示例,用 shell 重定向保存文件。
35
60
 
36
- 离线资料可保留多个版本,在线 UMD 仅保留最新一份:`manifest.json` 直接包含当前精确版本和资源元数据。资源路径使用 `fine-design/<组件版本>/...` 和 `van-analysis/<图表版本>/...`,无 hash 目录、历史索引或 `--release-id`。升级后旧版本 URL 不保证可用;长期使用的独立页面应自行保存资源。SRI 仍用于校验字节,不能用版本号代替它。
61
+ 在线 UMD 托管提供当前版本的资源,`manifest.json` 包含精确版本和资源元数据。资源路径使用 `fine-design/<组件版本>/...` 和 `van-analysis/<图表版本>/...`,通过 SRI 校验资源字节。长期使用的独立页面应自行保存对应资源。
37
62
 
38
- 默认运行时入口为 `https://fine-design-runtime.pages.dev/`,已部署 production 并通过资源及浏览器交互验收。可打开 [在线示例](https://fine-design-runtime.pages.dev/);`--runtime-url` 用于明确选择的其他托管地址,HTTP 仅允许本机回环测试。独立浏览器已验证生成的 HTML;内置文件预览的网络或沙箱行为需单独验证,资源加载失败时页面会显示具体 URL。
63
+ 默认运行时入口为 [在线示例](https://fine-design-runtime.pages.dev/);`--runtime-url` 可指定其他托管地址,HTTP 仅允许本机回环测试。资源加载失败时,生成的页面会显示具体 URL。
39
64
 
40
65
  `runtime` 结果的 `docsAvailable` 描述当前 CLI 是否收录该组件版本,网络资源可用性独立。CSS → React → ReactDOM → Fine Design 顺序加载,用 `window.FineDesign` 访问控件;图表场景额外加载 `vanAnalysisCss` / `vanAnalysis`。返回的 `tags` 包含精确 URL、`integrity` 和 `crossorigin="anonymous"`,宿主需提供 CORS。
41
66
 
42
67
  ## MCP
43
68
 
44
- 发布后按客户端配置语法使用:
69
+ 按客户端配置语法使用:
45
70
 
46
71
  ```json
47
72
  {
48
73
  "mcpServers": {
49
74
  "fine-design": {
50
75
  "command": "npx",
51
- "args": ["-y", "@finedesign/cli@0.2.0", "mcp"]
76
+ "args": ["-y", "@finedesign/cli@0.3.0", "mcp"]
52
77
  }
53
78
  }
54
79
  }
@@ -56,7 +81,7 @@ fine-design runtime --fd-version 1.25.0 --format html > demo.html
56
81
 
57
82
  | 工具 | 输入 |
58
83
  | --- | --- |
59
- | `search_components` | `version`、`query`,可选 `offset` |
84
+ | `search_components` | `version`、`query`,可选 `offset` / `limit` |
60
85
  | `get_component_doc` | `version`、`component`,可选 `section` / `summary` |
61
86
  | `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` |
62
87
  | `list_browser_runtimes` | 可选 `runtimeURL` |