@finedesign/cli 0.1.0-rc.0 → 0.1.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,16 +1,20 @@
1
- # Changelog
1
+ # 更新日志
2
2
 
3
- 工具版本独立于组件资料版本。每次修改工具运行代码、内置资料或 Skill,均需更新工具版本与本文件;仅修改开发文档时无需发版。
3
+ ## 0.1.0
4
+
5
+ 2026-11-02
6
+
7
+ - 发布首个正式版本,提供组件搜索、文档与示例查询,以及三个只读 MCP 工具。
8
+ - 改善组件未安装时的排查提示,支持在未安装组件库的工程中显式指定版本查询离线资料。
9
+ - 补充组件库安装、私有源认证和独立 HTML 预览说明,区分公开 CLI 与组件库的安装要求。
10
+ - 内置 Fine Design 1.24.9 中文资料及更新后的 Fine Design Skill。
4
11
 
5
12
  ## 0.1.0-rc.0
6
13
 
7
- 状态:准备首个 RC;本次仅向 npmjs 发布 `@finedesign/cli`,使用 `next` 标签,私有渠道暂缓。
14
+ 2026-11-02
8
15
 
9
- - 提供统一 `fine-design` CLI 和 stdio MCP,支持组件搜索、文档和完整示例查询。
10
- - 收录 Fine Design 1.24.9 仓库资料及官方 Skill 快照;来源提交和脏状态记录在资料 manifest,尚未核对已发布组件包契约。
11
- - 提供资料显式同步、独立构建与测试、双源产物准备及安装验收。
12
- - 提供发布预检、registry 安装验证、版本一致性检查和独立 Git tag 约定。
13
- - RC 允许先发布已验收的工作区快照,保留真实来源与 dirty 状态;稳定版仍要求干净来源及对应 Git tag。
14
- - 工具目录统一为 `tools/fine-design-cli`,本地与私有 npm 包名统一为 `@fx-ui/fine-design-cli`。
15
- - 补齐 Message、Notification、Toast、SvgIcon 公开导出;父章节查询包含子章节内容。
16
- - 示例默认返回文本代码与二进制资产元信息,通过 CLI `--include-assets` 或 MCP `includeAssets: true` 获取完整二进制内容。
16
+ - 提供 `fine-design` 命令,支持组件搜索、文档章节和示例查询。
17
+ - 提供 stdio MCP 服务,包含三个只读工具,与 CLI 使用相同的查询结果和错误契约。
18
+ - 内置 Fine Design 1.24.9 中文资料和 Fine Design Skill。
19
+ - 支持完整示例文件及相对依赖读取;二进制资源默认返回元信息,可按需获取完整内容。
20
+ - 支持从项目实际安装包识别组件版本;未收录版本明确报错。
package/README.md CHANGED
@@ -1,118 +1,186 @@
1
- # Fine Design CLI / MCP(开发中)
1
+ # Fine Design CLI
2
2
 
3
- 只读查询工具,使用 Node.js 20+。本工程尚未正式发布;整体目标和后续阶段见 [DESIGN.md](./DESIGN.md)。本地包名为 `@fx-ui/fine-design-cli`,唯一命令为 `fine-design`。
3
+ 为开发者和 AI 编码助手提供版本化的 Fine Design 组件文档与示例。同一个包支持命令行查询和 MCP 服务,资料随包分发,安装后可离线使用。
4
4
 
5
- 本次首发仅使用 npmjs 的 `@finedesign/cli@0.1.0-rc.0`,发布到 `next`;公司私有渠道暂缓,无需登录或发布私有源。现有双渠道打包能力保留。
5
+ [![npm](https://img.shields.io/npm/v/@finedesign/cli)](https://www.npmjs.com/package/@finedesign/cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
6
6
 
7
- ## 本地开发
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;其他平台尚未完成验收。
8
15
 
9
16
  ```sh
10
- cd tools/fine-design-cli
11
- npm ci
12
- npm run build
13
- npm test
14
- npm run pack:all
15
- npm run test:package
17
+ npm install -g @finedesign/cli@0.1.0
18
+ fine-design --version
16
19
  ```
17
20
 
18
- 构建校验本工程的包/锁版本、CHANGELOG、版本索引、资料哈希、示例结构、运行入口与 Skill 引用,不访问上层组件源码或根依赖。`npm test` 不依赖已生成的 tgz;产物验收前先执行 `npm run pack:all`。开发依赖由本目录的锁文件管理,不需要 workspace 或转译构建。
21
+ 也可以安装到项目:
19
22
 
20
- ## 更新资料
23
+ ```sh
24
+ npm install -D @finedesign/cli@0.1.0
25
+ npm exec -- fine-design --version
26
+ ```
21
27
 
22
- 在组件仓库根目录显式执行:
28
+ 无需安装即可试用:
23
29
 
24
30
  ```sh
25
- npm run export:ai-docs
26
- npm run test:ai-docs
27
- npm --prefix tools/fine-design-cli run sync:data -- --from ../../artifacts/ai-docs/1.24.9
31
+ npx -y @finedesign/cli@0.1.0 --help
28
32
  ```
29
33
 
30
- 导出器读取真实公开导出、中文文档、示例的相对依赖与二进制资源,生成 `artifacts/ai-docs/<组件版本>/`,不直接改工具快照。导出包包含 `catalog.json`、`manifest.json` 和 `skills/fine-design/`;manifest 记录来源提交、脏状态以及资料和 Skill 文件哈希。
34
+ ### 组件库安装与排查
31
35
 
32
- `--from` 的相对路径始终以工具工程目录为基准。同步先验证并暂存完整输入,再替换数据和 Skill,失败时恢复原数据;包名、依赖和锁文件不会被同步操作改动。`data/index.json` 的 `skillVersion` 指向当前内置 Skill 的来源版本,其他已收录组件版本仍保留。Skill 唯一作者源是根目录 `skills/fine-design`,不要直接编辑本目录的快照。
36
+ 公开 CLI 不需要公司私有源认证。页面工程安装 `@fx-ui/fine-design` 时,需要有权访问对应的组件源;只查询离线资料时,直接指定 `--fd-version 1.24.9` 即可。
33
37
 
34
- ## 版本管理
38
+ 在页面工程目录检查实际生效的配置:
39
+
40
+ ```sh
41
+ npm config get @fx-ui:registry
42
+ npm config get registry
43
+ npm config get userconfig
44
+ ```
35
45
 
36
- 工具使用独立 SemVer,不随组件库根包同步升版。兼容修复及资料/Skill 修订使用 patch,新增兼容功能或增加支持版本使用 minor;1.0 前的不兼容修改使用 minor,1.0 起使用 major,并在 CHANGELOG 中说明迁移方式。移除已收录的组件版本属于不兼容修改。仅修改开发文档时无需发版。
46
+ 没有项目 `.npmrc` 不代表没有配置:npm 也读取用户、全局配置和环境变量。项目配置只作用于当前工程,全局安装或临时目录不会自动继承另一工程的配置。
37
47
 
38
- 在本工程升级工具版本,例如:
48
+ 已有可用配置时,通过路径复用,不复制其中的凭据:
39
49
 
40
50
  ```sh
41
- npm version 0.2.0-rc.0 --no-git-tag-version
51
+ npm install @fx-ui/fine-design@1.24.9 --userconfig=/absolute/path/to/.npmrc
42
52
  ```
43
53
 
44
- 该命令更新本目录的 `package.json` 和 `package-lock.json`。随后在 `CHANGELOG.md` 增加精确的 `## 0.2.0-rc.0` 条目,记录功能、资料版本和 Skill 变更;build/pack 会拒绝版本不一致或缺少条目的输入。示例命令不会自动提交或创建 tag。
54
+ 新工程需要公司源时,在项目 `.npmrc` 中合并以下非敏感配置,保留原有设置;其他 scope 仅在实际依赖需要时添加:
45
55
 
46
- 稳定版发版前,维护者需评审并提交选定输入,在同一仓库创建 `fine-design-cli/v<工具版本>` tag,指向用于打包的工具提交。发布记录保存该 tag 和提交;稳定版上传要求来源干净、可追溯且 tag 指向正确提交。预发布允许先上传已验收的工作区快照,再同步 Git;真实提交、dirty 状态、缺失的 tag 和运行文件/资料/tgz 哈希仍保留在记录中,来源提交不可缺失。工具的导入、构建、测试和打包均不自动提交、打 tag 或推送。
56
+ ```ini
57
+ @fx-ui:registry=https://npm.jdydevelop.com/
58
+ ```
47
59
 
48
- 首次稳定版发布时,先提交 CLI 工程、资料导出脚本、Skill 和相关根配置,并确认工作区干净;再按“更新资料”导出并同步快照,使 `sourceRevision` 指向这次干净提交、`sourceDirty` 为 `false`。随后提交新快照,在该提交上创建工具 tag,再打包验收。不要手工改写来源字段;资料来源提交与最终工具提交可以不同。本次 RC 按维护者决定先发 npmjs,Git 后续同步。
60
+ 需要认证时运行 `npm login --scope=@fx-ui --registry=https://npm.jdydevelop.com/`。不要将 Token 写入示例、共享文档或提交到仓库。npm 配置规则见 [npmrc](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc/)。
49
61
 
50
- 预发布版本如 `0.2.0-rc.0` 自动发布到 `next`,稳定版本发布到 `latest`,两个渠道使用同一规则。已发布的同名同版本不可覆盖;修复需要新版本。需要恢复推荐版本时,将对应 registry 的 dist-tag 指回已验证版本;已固定版本的消费者仍需升级或调整依赖。
62
+ | 安装错误 | 排查方向 |
63
+ | --- | --- |
64
+ | `E401` / `E403` | 配置是否生效、登录是否过期,以及账号是否有包的读取权限 |
65
+ | `E404` | scope 是否指向正确源、版本是否存在;私有源也可能隐藏无权限的包 |
66
+ | 连接失败或超时 | 网络、VPN、代理和 registry 地址 |
51
67
 
52
- ## 准备、发布和验证 npm 产物
68
+ 仅需独立 HTML 预览时,可使用 [Standalone HTML](./skills/fine-design/references/imports-and-setup.md#standalone-html) 的公开 Runtime。它不替代 React 工程的依赖安装;未版本化 CDN 资源也不保证与指定 npm 版本一致。
53
69
 
54
- 在本工程执行:
70
+ ## 快速开始
55
71
 
56
72
  ```sh
57
- npm run pack:all
58
- npm run test:package
59
- npm run publish:public -- --dry-run
73
+ # 查找组件
74
+ fine-design search 表格 --fd-version 1.24.9
75
+
76
+ # 阅读组件文档及可用章节
77
+ fine-design doc NextTable --fd-version 1.24.9
78
+
79
+ # 读取一个 API 章节
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
60
84
  ```
61
85
 
62
- `pack:all` 先校验和测试,再冻结白名单内的运行文件,从同一份输入生成私有 `@fx-ui/fine-design-cli` 和公开 `@finedesign/cli` 两份 tgz。公开名称只在暂存区转换;本地元信息和锁文件保持不变。包中只包含运行代码、资料、Skill、README、CHANGELOG、LICENSE 与 npm 元信息;移除引用开发文件的 lifecycle。
86
+ 在已安装 `@fx-ui/fine-design` 的项目中,可以省略 `--fd-version`。CLI 从当前目录及父目录的 `node_modules` 读取真实安装版本,不根据依赖范围猜测版本,也不会回退到其他资料版本。
87
+
88
+ 项目级安装时,在上述命令前加 `npm exec --`。跨目录查询时使用 `--project /path/to/project`。
89
+
90
+ ## 命令
63
91
 
64
- 产物和 `release-manifest.json` 保存在 `artifacts/releases/<工具版本>/`,不进入官网目录或 Git。已有版本目录不会被覆盖;要重新准备时先保存或明确移除旧目录。所有子工程 `node_modules`、tgz、同步临时目录和产物目录均忽略提交。
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` | 查看帮助 |
65
100
 
66
- `test:package` 读取上述原始 tgz,核对文件清单、元信息和 integrity,在两个干净消费者工程中真实安装依赖,通过 `npm exec --offline -- fine-design ...` 验证 CLI/MCP,再记录 `validated` 状态与 Node/平台信息;不会隐式重新打包。测试需要 npm 官方源访问权限和发布机的 `tar`,用户运行 CLI/MCP 不需要 `tar`。
101
+ ### 输出格式
67
102
 
68
- 本次只需 npmjs 认证。`randost` 账号的 `finedesign` 组织 owner 权限已核实;本次 RC 使用如实记录来源的工作区快照,上传前仍须完成原始 tgz 安装验收。执行:
103
+ 默认输出便于人工阅读的文本。Agent 和脚本使用 `--format json`;文档查询还支持 `--format markdown`。
69
104
 
70
105
  ```sh
71
- npm run publish:public
72
- npm run verify:public
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
73
108
  ```
74
109
 
75
- 发布只上传验收过的原始 tgz,使用 manifest 固定的 registry、scope、access 和 dist-tag。上传前查询同版本 integrity:内容相同则复用,内容冲突则拒绝;失败或超时保留已确认状态。上传成功只记录 `published`。
110
+ `search` 每页返回 20 条,下一页使用结果中的 `nextOffset`:
76
111
 
77
- `verify:*` 核对目标 registry 的 integrity,再用新缓存、干净消费者工程安装精确版本,检查实际安装的 integrity、运行文件哈希及 CLI/MCP,成功后记录 `verified`、验证时间和运行环境。它复用本地 tgz 安装测试的检查逻辑;失败不提升发布状态。本次 npm 试发以公开渠道达到 `verified` 为完成条件,不要求私有渠道上传或验收。以后启用私有渠道时,再单独执行 `publish:private` / `verify:private`。
112
+ ```sh
113
+ fine-design search --offset 20 --fd-version 1.24.9 --format json
114
+ ```
115
+
116
+ ### 示例与资源
78
117
 
79
- RC 发布并验收后,可在消费工程试用:
118
+ 示例结果包含 `entry`、`files`、`dependencies` 和 `unresolved`。文本文件返回完整内容;二进制文件默认只返回路径、编码、字节数和 SHA-256,以减少上下文占用。
119
+
120
+ 需要完整二进制内容时:
80
121
 
81
122
  ```sh
82
- npx --registry=https://registry.npmjs.org/ --@finedesign:registry=https://registry.npmjs.org/ -y @finedesign/cli@0.1.0-rc.0 --version
83
- npx --registry=https://registry.npmjs.org/ --@finedesign:registry=https://registry.npmjs.org/ -y @finedesign/cli@0.1.0-rc.0 search 表格 --fd-version 1.24.9 --format json
84
- npx --registry=https://registry.npmjs.org/ --@finedesign:registry=https://registry.npmjs.org/ -y @finedesign/cli@0.1.0-rc.0 mcp
123
+ fine-design example Avatar image --include-assets --fd-version 1.24.9 --format json
85
124
  ```
86
125
 
87
- npm 正式发布和版本管理均属于本次建设计划。当前仍未正式发布;既有本地验证不等于 registry 或账号权限已经验证。
126
+ 按 `encoding` 解码各文件,并根据 `dependencies` 补齐项目依赖。页面运行仍需匹配版本的 Fine Design、React 和样式;获取文件集合后,应执行消费工程的类型、构建和交互检查。
88
127
 
89
- ## 仓库管理
128
+ ## MCP 接入
90
129
 
91
- 首版保留当前仓库中的独立子工程,使用独立版本、CHANGELOG 和 Git tag。npm 发布不要求单独创建 GitHub 仓库;有公开源码、社区协作或独立维护需求时再拆仓。公开 npm 包会公开其中的代码、示例、资料和 Skill,需确认这些内容可以公开分发。
130
+ 在使用 `mcpServers` 字段的客户端中配置:
92
131
 
93
- ## 查询与 MCP
132
+ ```json
133
+ {
134
+ "mcpServers": {
135
+ "fine-design": {
136
+ "command": "npx",
137
+ "args": ["-y", "@finedesign/cli@0.1.0", "mcp"]
138
+ }
139
+ }
140
+ }
141
+ ```
94
142
 
95
- 在本工程中可直接运行:
143
+ 其他客户端使用各自的配置格式,保持相同的启动命令和参数。首次运行需要从 npm 安装包。
96
144
 
97
- ```sh
98
- node bin/fine-design.mjs --help
99
- node bin/fine-design.mjs search 表格 --fd-version 1.24.9 --format json
100
- node bin/fine-design.mjs doc NextTable --section 'Table 属性' --fd-version 1.24.9 --format markdown
101
- node bin/fine-design.mjs example NextTable basic --fd-version 1.24.9 --format json
102
- node bin/fine-design.mjs example Avatar image --include-assets --fd-version 1.24.9 --format json
103
- node bin/fine-design.mjs mcp
145
+ | 工具 | 输入 | 用途 |
146
+ | --- | --- | --- |
147
+ | `search_components` | `version`、`query`,可选 `offset` | 搜索组件 |
148
+ | `get_component_doc` | `version`、`component`,可选 `section` | 阅读文档 |
149
+ | `get_component_example` | `version`、`component`、`exampleId`,可选 `includeAssets` | 获取示例 |
150
+
151
+ 每次 MCP 调用都必须传入精确的组件 `version`。例如调用 `get_component_doc`:
152
+
153
+ ```json
154
+ { "version": "1.24.9", "component": "NextTable" }
104
155
  ```
105
156
 
106
- 查询支持 `--project <目录>` 从该目录及父级的 `node_modules` 读取已安装的组件版本;也可以用 `--fd-version` 显式指定。不会根据依赖版本范围猜测版本,也不会回退到其他快照。`search` 支持 `--offset` 分页;`doc` 支持精确章节名;默认输出为文本,也支持 `json` 和 `markdown`。JSON 结果在 stdout,错误在 stderr,退出码为 2(参数)、3(版本)、4(未找到)或 1(其他错误)。
157
+ CLI JSON 与相同参数的 MCP 查询结果一致。MCP 工具为只读,不修改业务工程文件。
158
+
159
+ ## Agent 使用
160
+
161
+ 建议按以下顺序获取实现所需信息:
162
+
163
+ 1. 确认项目实际安装的组件版本。
164
+ 2. 使用 `search` 定位组件。
165
+ 3. 使用 `doc` 阅读相关章节并选择示例 ID。
166
+ 4. 使用 `example` 获取代码及依赖,再在项目中实现和验证。
167
+
168
+ 包内提供 [Fine Design Skill](./skills/fine-design/SKILL.md)。项目级安装后,文件位于 `node_modules/@finedesign/cli/skills/fine-design/`,可按客户端的 Skill 安装方式加载。npm 安装本身不会自动注册 Skill。
107
169
 
108
- `doc --section` 返回整个章节,包含其子章节。例如 NextTable 的“组件 API”包含“Table 属性”等表格。Message、Notification、Toast、SvgIcon 均可查询;Message 没有独立文档,返回 `docsAvailable: false`,其消息使用示例可查询 Toast 和 Notification。
170
+ ## 版本与错误
109
171
 
110
- `example` 默认返回完整文本文件内容,以及二进制资产的 `path`、`encoding`、`size`(解码后的字节数)和 `sha256`,省略二进制 `content`,避免图片 base64 占用 Agent 上下文。需要保存完整文件集时使用 `--include-assets`,按各文件的 `encoding` 解码;工具本身不自动写文件。数据快照始终保留完整资产内容。
172
+ 工具版本与组件版本分别管理:`--version` 显示 CLI 版本,`--fd-version` 指定 Fine Design 版本。当前仅收录组件版本 `1.24.9`;未收录版本返回 `VERSION_NOT_SUPPORTED`。
111
173
 
112
- MCP 客户端通过 `node /绝对路径/bin/fine-design.mjs mcp` 启动本地服务;三个工具分别为 `search_components`、`get_component_doc`、`get_component_example`,每次调用须传入精确 `version`。旧的 `server.mjs` 和无参数启动方式已由该入口替代,试点配置需同步调整。
174
+ | 情况 | 处理方式 |
175
+ | --- | --- |
176
+ | `VERSION_NOT_DETECTED` | 在已安装组件库的项目中运行,或使用 `--project` / `--fd-version` |
177
+ | `VERSION_NOT_SUPPORTED` | 使用已收录的精确版本 |
178
+ | `COMPONENT_NOT_FOUND` | 先通过 `search` 确认组件导出名 |
179
+ | `SECTION_NOT_FOUND` / `EXAMPLE_NOT_FOUND` | 使用 `doc` 返回的章节名或示例 ID |
180
+ | `docsAvailable: false` | 当前组件没有独立文档,按已安装包的公开声明核对用法 |
113
181
 
114
- MCP `get_component_example` 使用相同的默认轻量结果;按需传入 `includeAssets: true` 获取二进制 `content`。CLI JSON 与相同参数的 MCP 内容 JSON 保持一致。
182
+ 成功结果写入 stdout,错误写入 stderr。退出码:`0` 成功、`2` 参数错误、`3` 版本错误、`4` 资料不存在、`1` 其他运行错误。
115
183
 
116
- 内置 `1.24.9` 资料来自仓库快照;实际 `sourceRevision` 和 `sourceDirty` 以 `data/1.24.9/manifest.json` 为准,`sourceDirty: true` 的快照仅用于预发布,不作为稳定版来源。仓库快照不代表与已发布 npm 包一致。示例含文件、编码、依赖和未解析项,使用前需检查适配要求;文件集合完整不代表已经完成示例编译、交互或外部服务验收。不要手工改版本号来伪造历史资料。
184
+ ## 许可证
117
185
 
118
- 2026-10-30 已在 macOS / Node 22 验证:源码导出检查、工具构建与测试、脱离组件仓库的独立安装/构建/测试/打包、两份原始 tgz 的干净安装与 CLI/MCP、两个渠道的发布 dry-run。升级至 Zod 4.6.7 后 `npm audit --omit=dev` 为 0 告警。Node 20、Windows、Linux、Codex/WorkBuddy 实际客户端,以及官网 Markdown 和平台安装包属于后续验收范围。
186
+ [MIT](./LICENSE) · [更新日志](./CHANGELOG.md)