@finedesign/cli 0.0.0-stage → 0.1.0-rc.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 +16 -0
- package/LICENSE +22 -0
- package/README.md +117 -2
- package/bin/fine-design.mjs +3 -0
- package/data/1.24.9/catalog.json +1 -0
- package/data/1.24.9/manifest.json +16 -0
- package/data/index.json +10 -0
- package/package.json +33 -5
- package/skills/fine-design/SKILL.md +31 -0
- package/skills/fine-design/references/component-guide.md +67 -0
- package/skills/fine-design/references/docs-slug-map.md +79 -0
- package/skills/fine-design/references/imports-and-setup.md +44 -0
- package/skills/fine-design/references/theme-and-dark-mode.md +49 -0
- package/src/cli.mjs +59 -0
- package/src/core/catalog.mjs +113 -0
- package/src/core/contracts.mjs +18 -0
- package/src/core/data.mjs +99 -0
- package/src/core/errors.mjs +17 -0
- package/src/core/version.mjs +23 -0
- package/src/mcp.mjs +33 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
工具版本独立于组件资料版本。每次修改工具运行代码、内置资料或 Skill,均需更新工具版本与本文件;仅修改开发文档时无需发版。
|
|
4
|
+
|
|
5
|
+
## 0.1.0-rc.0
|
|
6
|
+
|
|
7
|
+
状态:准备首个 RC;本次仅向 npmjs 发布 `@finedesign/cli`,使用 `next` 标签,私有渠道暂缓。
|
|
8
|
+
|
|
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` 获取完整二进制内容。
|
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT LICENSE
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2018-present JDY DESIGN, https://jdy.design/
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
6
|
+
a copy of this software and associated documentation files (the
|
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
|
11
|
+
the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be
|
|
14
|
+
included in all copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,118 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Fine Design CLI / MCP(开发中)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
只读查询工具,使用 Node.js 20+。本工程尚未正式发布;整体目标和后续阶段见 [DESIGN.md](./DESIGN.md)。本地包名为 `@fx-ui/fine-design-cli`,唯一命令为 `fine-design`。
|
|
4
|
+
|
|
5
|
+
本次首发仅使用 npmjs 的 `@finedesign/cli@0.1.0-rc.0`,发布到 `next`;公司私有渠道暂缓,无需登录或发布私有源。现有双渠道打包能力保留。
|
|
6
|
+
|
|
7
|
+
## 本地开发
|
|
8
|
+
|
|
9
|
+
```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
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
构建校验本工程的包/锁版本、CHANGELOG、版本索引、资料哈希、示例结构、运行入口与 Skill 引用,不访问上层组件源码或根依赖。`npm test` 不依赖已生成的 tgz;产物验收前先执行 `npm run pack:all`。开发依赖由本目录的锁文件管理,不需要 workspace 或转译构建。
|
|
19
|
+
|
|
20
|
+
## 更新资料
|
|
21
|
+
|
|
22
|
+
在组件仓库根目录显式执行:
|
|
23
|
+
|
|
24
|
+
```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
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
导出器读取真实公开导出、中文文档、示例的相对依赖与二进制资源,生成 `artifacts/ai-docs/<组件版本>/`,不直接改工具快照。导出包包含 `catalog.json`、`manifest.json` 和 `skills/fine-design/`;manifest 记录来源提交、脏状态以及资料和 Skill 文件哈希。
|
|
31
|
+
|
|
32
|
+
`--from` 的相对路径始终以工具工程目录为基准。同步先验证并暂存完整输入,再替换数据和 Skill,失败时恢复原数据;包名、依赖和锁文件不会被同步操作改动。`data/index.json` 的 `skillVersion` 指向当前内置 Skill 的来源版本,其他已收录组件版本仍保留。Skill 唯一作者源是根目录 `skills/fine-design`,不要直接编辑本目录的快照。
|
|
33
|
+
|
|
34
|
+
## 版本管理
|
|
35
|
+
|
|
36
|
+
工具使用独立 SemVer,不随组件库根包同步升版。兼容修复及资料/Skill 修订使用 patch,新增兼容功能或增加支持版本使用 minor;1.0 前的不兼容修改使用 minor,1.0 起使用 major,并在 CHANGELOG 中说明迁移方式。移除已收录的组件版本属于不兼容修改。仅修改开发文档时无需发版。
|
|
37
|
+
|
|
38
|
+
在本工程升级工具版本,例如:
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
npm version 0.2.0-rc.0 --no-git-tag-version
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
该命令更新本目录的 `package.json` 和 `package-lock.json`。随后在 `CHANGELOG.md` 增加精确的 `## 0.2.0-rc.0` 条目,记录功能、资料版本和 Skill 变更;build/pack 会拒绝版本不一致或缺少条目的输入。示例命令不会自动提交或创建 tag。
|
|
45
|
+
|
|
46
|
+
稳定版发版前,维护者需评审并提交选定输入,在同一仓库创建 `fine-design-cli/v<工具版本>` tag,指向用于打包的工具提交。发布记录保存该 tag 和提交;稳定版上传要求来源干净、可追溯且 tag 指向正确提交。预发布允许先上传已验收的工作区快照,再同步 Git;真实提交、dirty 状态、缺失的 tag 和运行文件/资料/tgz 哈希仍保留在记录中,来源提交不可缺失。工具的导入、构建、测试和打包均不自动提交、打 tag 或推送。
|
|
47
|
+
|
|
48
|
+
首次稳定版发布时,先提交 CLI 工程、资料导出脚本、Skill 和相关根配置,并确认工作区干净;再按“更新资料”导出并同步快照,使 `sourceRevision` 指向这次干净提交、`sourceDirty` 为 `false`。随后提交新快照,在该提交上创建工具 tag,再打包验收。不要手工改写来源字段;资料来源提交与最终工具提交可以不同。本次 RC 按维护者决定先发 npmjs,Git 后续同步。
|
|
49
|
+
|
|
50
|
+
预发布版本如 `0.2.0-rc.0` 自动发布到 `next`,稳定版本发布到 `latest`,两个渠道使用同一规则。已发布的同名同版本不可覆盖;修复需要新版本。需要恢复推荐版本时,将对应 registry 的 dist-tag 指回已验证版本;已固定版本的消费者仍需升级或调整依赖。
|
|
51
|
+
|
|
52
|
+
## 准备、发布和验证 npm 产物
|
|
53
|
+
|
|
54
|
+
在本工程执行:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
npm run pack:all
|
|
58
|
+
npm run test:package
|
|
59
|
+
npm run publish:public -- --dry-run
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`pack:all` 先校验和测试,再冻结白名单内的运行文件,从同一份输入生成私有 `@fx-ui/fine-design-cli` 和公开 `@finedesign/cli` 两份 tgz。公开名称只在暂存区转换;本地元信息和锁文件保持不变。包中只包含运行代码、资料、Skill、README、CHANGELOG、LICENSE 与 npm 元信息;移除引用开发文件的 lifecycle。
|
|
63
|
+
|
|
64
|
+
产物和 `release-manifest.json` 保存在 `artifacts/releases/<工具版本>/`,不进入官网目录或 Git。已有版本目录不会被覆盖;要重新准备时先保存或明确移除旧目录。所有子工程 `node_modules`、tgz、同步临时目录和产物目录均忽略提交。
|
|
65
|
+
|
|
66
|
+
`test:package` 读取上述原始 tgz,核对文件清单、元信息和 integrity,在两个干净消费者工程中真实安装依赖,通过 `npm exec --offline -- fine-design ...` 验证 CLI/MCP,再记录 `validated` 状态与 Node/平台信息;不会隐式重新打包。测试需要 npm 官方源访问权限和发布机的 `tar`,用户运行 CLI/MCP 不需要 `tar`。
|
|
67
|
+
|
|
68
|
+
本次只需 npmjs 认证。`randost` 账号的 `finedesign` 组织 owner 权限已核实;本次 RC 使用如实记录来源的工作区快照,上传前仍须完成原始 tgz 安装验收。执行:
|
|
69
|
+
|
|
70
|
+
```sh
|
|
71
|
+
npm run publish:public
|
|
72
|
+
npm run verify:public
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
发布只上传验收过的原始 tgz,使用 manifest 固定的 registry、scope、access 和 dist-tag。上传前查询同版本 integrity:内容相同则复用,内容冲突则拒绝;失败或超时保留已确认状态。上传成功只记录 `published`。
|
|
76
|
+
|
|
77
|
+
`verify:*` 核对目标 registry 的 integrity,再用新缓存、干净消费者工程安装精确版本,检查实际安装的 integrity、运行文件哈希及 CLI/MCP,成功后记录 `verified`、验证时间和运行环境。它复用本地 tgz 安装测试的检查逻辑;失败不提升发布状态。本次 npm 试发以公开渠道达到 `verified` 为完成条件,不要求私有渠道上传或验收。以后启用私有渠道时,再单独执行 `publish:private` / `verify:private`。
|
|
78
|
+
|
|
79
|
+
RC 发布并验收后,可在消费工程试用:
|
|
80
|
+
|
|
81
|
+
```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
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
npm 正式发布和版本管理均属于本次建设计划。当前仍未正式发布;既有本地验证不等于 registry 或账号权限已经验证。
|
|
88
|
+
|
|
89
|
+
## 仓库管理
|
|
90
|
+
|
|
91
|
+
首版保留当前仓库中的独立子工程,使用独立版本、CHANGELOG 和 Git tag。npm 发布不要求单独创建 GitHub 仓库;有公开源码、社区协作或独立维护需求时再拆仓。公开 npm 包会公开其中的代码、示例、资料和 Skill,需确认这些内容可以公开分发。
|
|
92
|
+
|
|
93
|
+
## 查询与 MCP
|
|
94
|
+
|
|
95
|
+
在本工程中可直接运行:
|
|
96
|
+
|
|
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
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
查询支持 `--project <目录>` 从该目录及父级的 `node_modules` 读取已安装的组件版本;也可以用 `--fd-version` 显式指定。不会根据依赖版本范围猜测版本,也不会回退到其他快照。`search` 支持 `--offset` 分页;`doc` 支持精确章节名;默认输出为文本,也支持 `json` 和 `markdown`。JSON 结果在 stdout,错误在 stderr,退出码为 2(参数)、3(版本)、4(未找到)或 1(其他错误)。
|
|
107
|
+
|
|
108
|
+
`doc --section` 返回整个章节,包含其子章节。例如 NextTable 的“组件 API”包含“Table 属性”等表格。Message、Notification、Toast、SvgIcon 均可查询;Message 没有独立文档,返回 `docsAvailable: false`,其消息使用示例可查询 Toast 和 Notification。
|
|
109
|
+
|
|
110
|
+
`example` 默认返回完整文本文件内容,以及二进制资产的 `path`、`encoding`、`size`(解码后的字节数)和 `sha256`,省略二进制 `content`,避免图片 base64 占用 Agent 上下文。需要保存完整文件集时使用 `--include-assets`,按各文件的 `encoding` 解码;工具本身不自动写文件。数据快照始终保留完整资产内容。
|
|
111
|
+
|
|
112
|
+
MCP 客户端通过 `node /绝对路径/bin/fine-design.mjs mcp` 启动本地服务;三个工具分别为 `search_components`、`get_component_doc`、`get_component_example`,每次调用须传入精确 `version`。旧的 `server.mjs` 和无参数启动方式已由该入口替代,试点配置需同步调整。
|
|
113
|
+
|
|
114
|
+
MCP `get_component_example` 使用相同的默认轻量结果;按需传入 `includeAssets: true` 获取二进制 `content`。CLI JSON 与相同参数的 MCP 内容 JSON 保持一致。
|
|
115
|
+
|
|
116
|
+
内置 `1.24.9` 资料来自仓库快照;实际 `sourceRevision` 和 `sourceDirty` 以 `data/1.24.9/manifest.json` 为准,`sourceDirty: true` 的快照仅用于预发布,不作为稳定版来源。仓库快照不代表与已发布 npm 包一致。示例含文件、编码、依赖和未解析项,使用前需检查适配要求;文件集合完整不代表已经完成示例编译、交互或外部服务验收。不要手工改版本号来伪造历史资料。
|
|
117
|
+
|
|
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 和平台安装包属于后续验收范围。
|