figma-cache-toolchain 1.4.2 → 1.4.3
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/README.md +154 -98
- package/package.json +5 -4
package/README.md
CHANGED
|
@@ -1,98 +1,154 @@
|
|
|
1
|
-
# figma-cache-toolchain
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
###
|
|
16
|
-
|
|
17
|
-
```bash
|
|
18
|
-
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
npm run figma:cache:init
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
###
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
###
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
npm
|
|
97
|
-
|
|
98
|
-
|
|
1
|
+
# figma-cache-toolchain
|
|
2
|
+
|
|
3
|
+
面向业务项目的 Figma 本地缓存工具链：提供链接标准化、索引管理、缓存读写、校验与流程维护能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
|
|
4
|
+
|
|
5
|
+
## 快速接入（4 步）
|
|
6
|
+
|
|
7
|
+
以下步骤建议在业务项目根目录执行。
|
|
8
|
+
|
|
9
|
+
### 1) 安装
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm i -D figma-cache-toolchain
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
### 2) 初始化 Cursor 模板与任务书
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx figma-cache cursor init
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
该命令会：
|
|
22
|
+
|
|
23
|
+
- 写入或跳过（已存在且未使用 `--force`）`.cursor/rules/`、`.cursor/skills/`、`figma-cache.config.example.js`
|
|
24
|
+
- 每次刷新根目录 `AGENT-SETUP-PROMPT.md`
|
|
25
|
+
- 同步刷新 `figma-cache/colleague-guide-zh.md`
|
|
26
|
+
|
|
27
|
+
### 3) 交给 Cursor Agent 执行一次项目接入
|
|
28
|
+
|
|
29
|
+
在 Cursor 对话中引用 `@AGENT-SETUP-PROMPT.md`，并让 Agent 按文档执行。
|
|
30
|
+
|
|
31
|
+
通常会完成：
|
|
32
|
+
|
|
33
|
+
- 推断技术栈并生成/合并 Adapter 规则
|
|
34
|
+
- 合并或生成 `figma-cache.config.js`
|
|
35
|
+
- 补全 `figma:cache:*` 相关 scripts
|
|
36
|
+
|
|
37
|
+
### 4) 初始化本地缓存索引
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm run figma:cache:init
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
若项目尚未配置 scripts，可临时使用：
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx figma-cache init
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
随后建议执行一次：
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm run figma:cache:validate
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
> `cursor init` 与 `figma-cache init` 是两件事：
|
|
56
|
+
> - `cursor init` 负责模板与任务书
|
|
57
|
+
> - `figma-cache init` 负责创建本地空索引
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 日常使用方式
|
|
62
|
+
|
|
63
|
+
日常通常只需把 Figma 链接发给 Agent，Agent 会按规则自动执行：
|
|
64
|
+
|
|
65
|
+
1. 查询本地缓存是否命中
|
|
66
|
+
2. 信息不足时调用 MCP 拉取最小必要数据
|
|
67
|
+
3. 回写 `figma-cache/` 缓存文件
|
|
68
|
+
4. 执行 `upsert/ensure` 后自动 `validate`
|
|
69
|
+
|
|
70
|
+
你一般不需要手工跑命令，命令主要用于排障、迁移和验收。
|
|
71
|
+
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
## 升级 npm 包后的推荐流程（业务项目）
|
|
75
|
+
|
|
76
|
+
### 1) 升级依赖
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npm i -D figma-cache-toolchain@latest
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
### 2) 刷新模板与说明文档
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
npx figma-cache cursor init
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### 3) 对齐 `figma-cache.config.js`
|
|
89
|
+
|
|
90
|
+
- 若你的正式配置是 `require` 包内示例：通常只需重新加载即可。
|
|
91
|
+
- 若你的正式配置是历史复制版/自定义版：请与最新 `figma-cache.config.example.js` 做增量合并，避免整文件覆盖导致自定义钩子丢失。
|
|
92
|
+
|
|
93
|
+
### 4) 校验
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
npm run figma:cache:validate
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
并结合 `CHANGELOG.md` 检查是否存在破坏性变更。
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## 常用文档入口
|
|
104
|
+
|
|
105
|
+
- `figma-cache/README.md`：完整脚本、环境变量、回填与维护说明
|
|
106
|
+
- `figma-cache/colleague-guide-zh.md`：团队协作指南与提示词模板
|
|
107
|
+
- `figma-cache/link-normalization-spec.md`：Figma 链接标准化规范
|
|
108
|
+
- `figma-cache/flow-edge-taxonomy.md`：流程边类型约定
|
|
109
|
+
- `AGENT-SETUP-PROMPT.md`：项目接入任务书（由 `cursor init` 每次刷新）
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 常用命令（参考）
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
npm run figma:cache:init
|
|
117
|
+
npm run figma:cache:config
|
|
118
|
+
npm run figma:cache:get -- "<figma-url>"
|
|
119
|
+
npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions
|
|
120
|
+
npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions
|
|
121
|
+
npm run figma:cache:validate
|
|
122
|
+
npm run figma:cache:budget
|
|
123
|
+
npm run figma:cache:stale
|
|
124
|
+
npm run figma:cache:backfill
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
---
|
|
128
|
+
|
|
129
|
+
## 防乱码约定（Windows / PowerShell）
|
|
130
|
+
|
|
131
|
+
为避免中文文档出现乱码，请统一遵循：
|
|
132
|
+
|
|
133
|
+
- 文本文件统一使用 UTF-8 编码（建议与仓库既有风格保持一致）
|
|
134
|
+
- Node 写文件必须显式指定 `utf8`
|
|
135
|
+
- PowerShell 写文件必须显式指定编码，例如：
|
|
136
|
+
|
|
137
|
+
```powershell
|
|
138
|
+
Set-Content -Path .\README.md -Value $text -Encoding utf8
|
|
139
|
+
Out-File -FilePath .\README.md -InputObject $text -Encoding utf8
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
- 不要把终端里已经乱码的内容直接复制回文件再保存
|
|
143
|
+
- 文档改动后，至少回读抽查 20 行，确认中文可读
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 维护者说明
|
|
148
|
+
|
|
149
|
+
维护本工具链源码时，请优先参考：
|
|
150
|
+
|
|
151
|
+
- 根目录 `CHANGELOG.md`
|
|
152
|
+
- `figma-cache/README.md` 的维护说明
|
|
153
|
+
|
|
154
|
+
修改 `cursor-bootstrap/` 模板或 CLI 行为后，请按发布流程更新版本并发布，以便消费方通过 `cursor init` 获取最新模板。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "figma-cache-toolchain",
|
|
3
|
-
"version": "1.4.
|
|
3
|
+
"version": "1.4.3",
|
|
4
4
|
"description": "Figma link normalization, local cache index, validation, and Node CLI (framework-agnostic core).",
|
|
5
5
|
"homepage": "https://www.npmjs.com/package/figma-cache-toolchain",
|
|
6
6
|
"keywords": [
|
|
@@ -28,8 +28,8 @@
|
|
|
28
28
|
"registry": "https://registry.npmjs.org/"
|
|
29
29
|
},
|
|
30
30
|
"scripts": {
|
|
31
|
-
"test": "node tests/smoke.js",
|
|
32
|
-
"prepack": "node bin/figma-cache.js validate",
|
|
31
|
+
"test": "npm run docs:encoding:check && node tests/smoke.js",
|
|
32
|
+
"prepack": "npm run docs:encoding:check && node bin/figma-cache.js validate",
|
|
33
33
|
"figma:cache:normalize": "node bin/figma-cache.js normalize",
|
|
34
34
|
"figma:cache:get": "node bin/figma-cache.js get",
|
|
35
35
|
"figma:cache:upsert": "node bin/figma-cache.js upsert",
|
|
@@ -46,7 +46,8 @@
|
|
|
46
46
|
"figma:cache:flow:chain": "node bin/figma-cache.js flow chain",
|
|
47
47
|
"figma:cache:flow:show": "node bin/figma-cache.js flow show",
|
|
48
48
|
"figma:cache:flow:mermaid": "node bin/figma-cache.js flow mermaid",
|
|
49
|
-
"figma:cache:cursor:init": "node bin/figma-cache.js cursor init"
|
|
49
|
+
"figma:cache:cursor:init": "node bin/figma-cache.js cursor init",
|
|
50
|
+
"docs:encoding:check": "node scripts/check-doc-encoding.js"
|
|
50
51
|
},
|
|
51
52
|
"volta": {
|
|
52
53
|
"node": "16.20.2"
|