@finedesign/cli 0.6.1 → 0.8.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,5 +1,22 @@
1
1
  # 更新日志
2
2
 
3
+ ## 0.8.0
4
+
5
+ 2026-11-11
6
+
7
+ - 新增离线 Figma 组件反查。CLI 提供 `fine-design figma resolve` 与 `figma list`,stdio MCP 提供 `resolve_figma_component` 与 `list_figma_components`。收录 70 个 Code Connect 模板及导入语句,并按模板提供适用的业务参数和静态包装函数签名。
8
+ - Figma 映射随资料同步生成。仓库构建检查快照与模板来源的一致性,独立构建检查快照完整性。
9
+
10
+ ## 0.7.0
11
+
12
+ 2026-11-10
13
+
14
+ - JSX 与 React.createElement 共用 API 检查,补齐 Select、Combo、NextTable、PopConfirm、Pagination、Dialog、Tag 和主题前缀检查,支持 React 工厂导入及展开属性的保守判断。
15
+ - 新增 `runtime --output <新目录>`,下载并校验四份必需资源,导出本地 HTML、任务列表组合示例及来源记录;支持 dry-run,拒绝覆盖已有目录,失败时不安装半成品。
16
+ - 随包提供筛选、分页、草稿编辑和确认删除的独立页面参考,补充业务语义、真实操作结果、键盘入口及验证边界要求。
17
+ - 初始化规则与内置 Skill 明确 Fine Design 任务的主动查询、自检和结果报告要求,支持全局 CLI,并复用同一会话的版本诊断及 API 资料。
18
+ - 更新站点和 Agent 接入提示词,补充已有项目规则的合并与更新方式;按需查询组件和示例,避免默认读取全部资料。
19
+
3
20
  ## 0.6.1
4
21
 
5
22
  2026-11-10
package/README.md CHANGED
@@ -17,26 +17,29 @@
17
17
  - **精确版本**:识别工程实际安装的组件版本,不自动替换为其他版本的资料。
18
18
  - **Agent 接入**:内置 Fine Design Skill,支持 JSON 输出与 stdio MCP。
19
19
  - **代码检查**:只读扫描常见 API 误用和非法导入,不修改源文件。
20
+ - **离线预览**:导出校验过的浏览器资源和可运行示例,便于本地预览与归档。
20
21
 
21
22
  ## 安装
22
23
 
23
- 需要 Node.js 20+。在项目中安装:
24
+ 需要 Node.js 20+。推荐全局安装,一台机器只需安装一次,无需已有项目:
24
25
 
25
26
  ```sh
26
- npm install -D @finedesign/cli
27
+ npm install -g @finedesign/cli
27
28
  ```
28
29
 
29
30
  也可通过 `npx -y @finedesign/cli` 直接运行。CLI 安装和离线查询无需公司私有 npm 源;组件包安装是独立操作。
30
31
 
32
+ 团队需要通过锁文件固定版本时,可在已有项目中用 `npm install -D @finedesign/cli` 安装,之后用 `npx fine-design` 调用。
33
+
31
34
  ## 快速开始
32
35
 
33
36
  在使用 Fine Design 的工程目录运行:
34
37
 
35
38
  ```sh
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/ # 检查代码
39
+ fine-design doctor # 检查组件版本与内置 Skill 路径
40
+ fine-design info Button --format json # 查询组件 API
41
+ fine-design example Button basic # 读取真实示例源码
42
+ fine-design lint src/ # 检查代码
40
43
  ```
41
44
 
42
45
  尚未安装组件时,先用 `doctor` 查看可用资料版本,再通过 `--fd-version <组件版本>` 指定目标版本。
@@ -45,17 +48,17 @@ npx -y @finedesign/cli lint src/ # 检查代码
45
48
 
46
49
  ### Skill
47
50
 
48
- 安装 CLI 后,在项目根目录初始化:
51
+ 安装 CLI 后,在准备使用 AI 助手的工作目录初始化:
49
52
 
50
53
  ```sh
51
- npx fine-design init
54
+ fine-design init
52
55
  ```
53
56
 
54
- `init` 默认配置 Cursor、Claude Code 和 Codex,写入项目规则,并为 Claude Code、Codex 安装内置 Skill;已有配置默认保留。完成后直接描述业务需求,Agent 会使用 `npx fine-design` 查询组件与检查代码。
57
+ 空目录也可初始化,无需现有 React 项目或 `package.json`。`init` 默认配置 Cursor、Claude Code 和 Codex,写入主动调用 CLI 的项目规则,并为 Claude Code、Codex 安装内置 Skill;已有配置默认保留。换一个工作目录时,再执行一次 `fine-design init`。后续直接描述业务需求,助手会在 Fine Design 任务中核对目标版本 API、按需读取示例,并在改动后运行 lint 和项目检查;同一会话已查资料可复用。
55
58
 
56
59
  也可让 AI 编码助手完成接入:
57
60
 
58
- > 使用项目现有包管理器安装开发依赖 `@finedesign/cli`(已安装则复用),然后运行 `npx fine-design init`。只完成安装和初始化,后续 Fine Design 任务使用该 CLI。
61
+ > 全局安装 `@finedesign/cli`(已安装则复用),在当前工作目录运行 `fine-design init`,空目录也可。确认当前助手的项目规则包含:涉及 Fine Design 的任务主动用 CLI 核对目标版本 API,改动后运行 lint 和项目检查。保留已有规则,本次只完成接入。
59
62
 
60
63
  ### MCP
61
64
 
@@ -72,11 +75,11 @@ npx fine-design init
72
75
  }
73
76
  ```
74
77
 
75
- MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检查和浏览器运行时查询。客户端可自动发现工具参数。组件资料查询可省略 `version`:默认从 MCP 进程工作目录检测组件版本,检测不到时使用内置 Skill 对应的资料版本;已检测但未收录的版本仍会报错。代码检查从扫描目标检测版本。`get_browser_runtime` 省略版本时使用当前托管版本,运行时查询需要联网。
78
+ MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检查、浏览器运行时查询以及 Figma 节点与 Code Connect 映射解析(`resolve_figma_component` / `list_figma_components`)。客户端可自动发现工具参数。组件资料查询可省略 `version`:默认从 MCP 进程工作目录检测组件版本,检测不到时使用内置 Skill 对应的资料版本;已检测但未收录的版本仍会报错。代码检查从扫描目标检测版本。`get_browser_runtime` 省略版本时使用当前托管版本,运行时查询需要联网。
76
79
 
77
80
  ## 命令
78
81
 
79
- 以下命令均使用 `npx -y @finedesign/cli` 前缀,完整参数见 `npx -y @finedesign/cli --help`。
82
+ 以下命令均使用 `fine-design` 前缀,完整参数见 `fine-design --help`。
80
83
 
81
84
  ### 组件资料
82
85
 
@@ -103,6 +106,7 @@ MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检
103
106
  | --- | --- |
104
107
  | `init` | 一键初始化 Agent 规则与配置(`--agent cursor/claude/codex/all`) |
105
108
  | `add <component> [id]` | 提取组件示例代码及附属文件到项目目录(支持 `--output` 与 `--force`) |
109
+ | `figma <resolve\|list>` | 反查 Fine Design 库节点的离线 Code Connect 映射,或浏览已连接模板 |
106
110
  | `mcp` | 启动 stdio MCP 服务 |
107
111
  | `runtime [list]` | 查询在线运行时或生成完整 HTML 页面 |
108
112
 
@@ -111,7 +115,7 @@ MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检
111
115
  ## 版本与输出
112
116
 
113
117
  - **组件版本**:`--fd-version` 优先,其次使用 `--project <目录>` 指定的工程。未指定时,`lint` 从扫描目标检测版本,其他组件查询从当前工程检测。未收录的版本会报错。
114
- - **输出格式**:默认文本;`--format json` 适合 Agent。`doc`、`info`、`token` 支持 Markdown;`runtime` 支持 HTML。
118
+ - **输出格式**:默认文本;`--format json` 适合 Agent。`doc`、`info`、`token`、`figma` 支持 Markdown;`runtime` 支持 HTML。
115
119
  - **结果与错误**:结果写入 stdout,错误写入 stderr。退出码 `0` 表示成功,`1` 表示检查未通过或运行错误,`2` 为参数问题,`3` 为版本问题,`4` 为资料未找到。
116
120
 
117
121
  ## 浏览器预览
@@ -119,10 +123,13 @@ MCP 提供组件搜索、API、Design Token、示例、版本对比、代码检
119
123
  已有构建流程的 React 应用使用私有组件包 `@fx-ui/fine-design`。独立 HTML、无构建嵌入页和原型可使用公开 UMD 运行时,浏览器无需安装组件包。
120
124
 
121
125
  ```sh
122
- npx -y @finedesign/cli runtime list --format json
123
- npx -y @finedesign/cli runtime --fd-version '<versions 中的版本>' --format html > demo.html
126
+ fine-design runtime list --format json
127
+ fine-design runtime --fd-version '<versions 中的版本>' --format html > demo.html
128
+ fine-design runtime --fd-version '<versions 中的版本>' --output ./offline-demo
124
129
  ```
125
130
 
131
+ `--output` 将运行时示例、任务列表组合示例、资源和来源记录写入新目录,并保留 SRI。可加 `--dry-run --format json` 预览文件列表。首次导出需要联网,生成的页面仅引用本地资源。宿主须允许页面脚本和样式。
132
+
126
133
  [打开 Fine Design Playground](https://fine-design-runtime.pages.dev/)。生成的 HTML 固定资源版本并附带 SRI 校验;在线托管仅保留当前版本,长期归档请保存对应资源。
127
134
 
128
135
  ## 更多资料