@finedesign/cli 0.3.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +84 -70
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,12 @@
1
1
  # 更新日志
2
2
 
3
+ ## 0.3.1
4
+
5
+ 2026-11-05
6
+
7
+ - 重整 npm README,固定功能、安装、快速开始、Agent 集成与命令索引等章节,精简接入说明并使用动态版本徽章。
8
+ - 增加 README 维护约定和构建校验,普通发版无需改写正文;CLI 命令、组件资料和依赖保持不变。
9
+
3
10
  ## 0.3.0
4
11
 
5
12
  2026-11-05
package/README.md CHANGED
@@ -1,111 +1,125 @@
1
- # Fine Design CLI / MCP (`@finedesign/cli`)
1
+ <div align="center">
2
2
 
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 源。
3
+ # Fine Design CLI
4
4
 
5
- ## 快速接入 Agent
5
+ 按项目版本查询 Fine Design 组件资料,供终端和 AI 编码助手使用。
6
6
 
7
- ### 1. 复制指令直接接入 Agent
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)
8
9
 
9
- 将以下提示词复制给 **Claude Code / Cursor / Codex / Windsurf**,或写入项目 `AGENTS.md` / `CLAUDE.md`:
10
+ [使用指南](https://docs.fanruan.design/docs/react/skills-cn) · [在线体验](https://fine-design-runtime.pages.dev/) · [更新日志](https://unpkg.com/@finedesign/cli@latest/CHANGELOG.md)
10
11
 
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
- ```
12
+ </div>
13
+
14
+ ## 特性
15
+
16
+ - **离线资料**:组件 API、Design Token 和真实示例随包分发。
17
+ - **精确版本**:识别工程实际安装的组件版本,不自动替换为其他版本的资料。
18
+ - **Agent 接入**:内置 Fine Design Skill,支持 JSON 输出与 stdio MCP。
19
+ - **代码检查**:只读扫描常见 API 误用和非法导入,不修改源文件。
22
20
 
23
- 高频使用时可安装到工程开发依赖或全局:
21
+ ## 安装
22
+
23
+ 需要 Node.js 20+。在项目中安装:
24
24
 
25
25
  ```sh
26
- npm install -D @finedesign/cli@0.3.0
27
- npx fine-design doctor
26
+ npm install -D @finedesign/cli
28
27
  ```
29
28
 
30
- ### 2. 命令速查
29
+ 也可通过 `npx -y @finedesign/cli` 直接运行。CLI 安装和离线查询无需公司私有 npm 源;组件包安装是独立操作。
31
30
 
32
- | 命令 | 用途 |
33
- | --- | --- |
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 服务 |
31
+ ## 快速开始
32
+
33
+ 在使用 Fine Design 的工程目录运行:
45
34
 
46
35
  ```sh
47
- fine-design list --fd-version 1.25.0
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
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
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/ # 检查代码
57
40
  ```
58
41
 
59
- 显式 `--fd-version` 优先,否则从 `--project` 或当前目录向上查找实际安装包/组件源码仓库的版本。不会从依赖范围或锁文件自动猜测,不回退其他版本。`--format json` 适合 Agent;Markdown 格式支持 `doc`、`info`、`token`;`runtime --format html` 输出可直接打开的完整示例,用 shell 重定向保存文件。
42
+ 尚未安装组件时,先用 `doctor` 查看可用资料版本,再通过 `--fd-version <组件版本>` 指定目标版本。
60
43
 
61
- 在线 UMD 托管提供当前版本的资源,`manifest.json` 包含精确版本和资源元数据。资源路径使用 `fine-design/<组件版本>/...` 和 `van-analysis/<图表版本>/...`,通过 SRI 校验资源字节。长期使用的独立页面应自行保存对应资源。
44
+ ## Agent 集成
62
45
 
63
- 默认运行时入口为 [在线示例](https://fine-design-runtime.pages.dev/);`--runtime-url` 可指定其他托管地址,HTTP 仅允许本机回环测试。资源加载失败时,生成的页面会显示具体 URL。
46
+ ### Skill
64
47
 
65
- `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`:
66
49
 
67
- ## 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
+ ```
68
56
 
69
- 按客户端配置语法使用:
57
+ ### MCP
58
+
59
+ 在支持 stdio MCP 的客户端中添加:
70
60
 
71
61
  ```json
72
62
  {
73
63
  "mcpServers": {
74
64
  "fine-design": {
75
65
  "command": "npx",
76
- "args": ["-y", "@finedesign/cli@0.3.0", "mcp"]
66
+ "args": ["-y", "@finedesign/cli", "mcp"]
77
67
  }
78
68
  }
79
69
  }
80
70
  ```
81
71
 
82
- | 工具 | 输入 |
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
+ | 命令 | 用途 |
83
92
  | --- | --- |
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` |
93
+ | `doctor` | 检查组件版本、可用资料及 Skill 路径 |
94
+ | `lint [files-or-dirs...]` | 扫描常见 API 陷阱与非法导入 |
95
+ | `diff [fromVer] [toVer]` | 对比版本间的资料与迁移建议 |
89
96
 
90
- CLI JSON 与相同参数的 MCP 返回一致。所有工具只读;前三个使用离线资料,两个浏览器工具要求联网。除列举版本外必须传精确组件版本。
97
+ ### 集成与预览
91
98
 
92
- ## 安装配置与错误
99
+ | 命令 | 用途 |
100
+ | --- | --- |
101
+ | `mcp` | 启动 stdio MCP 服务 |
102
+ | `runtime [list]` | 查询在线运行时或生成完整 HTML 页面 |
103
+
104
+ ## 版本与输出
93
105
 
94
- 缺少项目 `.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 运行时,无需安装组件包或配置构建工具。
95
113
 
96
114
  ```sh
97
- npm config get @fx-ui:registry
98
- npm config get registry
99
- npm config get userconfig
115
+ npx -y @finedesign/cli runtime list
116
+ npx -y @finedesign/cli runtime --format html > demo.html
100
117
  ```
101
118
 
102
- 需要安装私有组件时复用授权配置路径,例如 `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 校验;在线托管仅保留当前版本,长期归档请保存对应资源。
103
120
 
104
- | 错误 | 含义 |
105
- | --- | --- |
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 已不在当前托管目录,不回退 |
121
+ ## 更多资料
110
122
 
111
- 成功写 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)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@finedesign/cli",
3
- "version": "0.3.0",
3
+ "version": "0.3.1",
4
4
  "description": "Read-only, versioned Fine Design documentation for coding agents",
5
5
  "license": "MIT",
6
6
  "publishConfig": {