figma-cache-toolchain 1.4.4 → 2.0.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.
Files changed (15) hide show
  1. package/README.md +156 -142
  2. package/bin/figma-cache.js +1 -1
  3. package/cursor-bootstrap/AGENT-SETUP-PROMPT.md +7 -1
  4. package/cursor-bootstrap/rules/00-output-token-budget.mdc +26 -0
  5. package/cursor-bootstrap/rules/01-figma-cache-core.mdc +41 -29
  6. package/cursor-bootstrap/skills/figma-mcp-local-cache/SKILL.md +22 -15
  7. package/figma-cache/docs/README.md +23 -21
  8. package/figma-cache/docs/colleague-guide-zh.md +199 -207
  9. package/figma-cache/docs/quick-start-zh.md +42 -0
  10. package/figma-cache/figma-cache.js +11 -9
  11. package/figma-cache/js/cursor-bootstrap-cli.js +12 -4
  12. package/figma-cache/js/entry-files.js +219 -0
  13. package/figma-cache/js/project-config.js +2 -0
  14. package/figma-cache/js/validate-cli.js +52 -0
  15. package/package.json +1 -1
package/README.md CHANGED
@@ -1,142 +1,156 @@
1
- # figma-cache-toolchain
2
-
3
- 面向业务项目的 Figma 本地缓存工具链：提供链接标准化、索引管理、缓存读写、校验与流程维护能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
4
-
5
- - npm 包：`figma-cache-toolchain`
6
- - Git 仓库：<https://github.com/907086379/figma-cache-toolchain.git>
7
-
8
- ---
9
-
10
- ## 这份 README 面向谁
11
-
12
- - npm 用户：把工具链接入业务项目并日常使用
13
- - git 用户：在仓库内开发、测试、提交改动
14
-
15
- > npm 发布由仓库维护者负责；普通用户和贡献者无需执行 `npm publish`。
16
-
17
- ---
18
-
19
- ## npm 用户快速开始
20
-
21
- ### 1) 安装
22
-
23
- ```bash
24
- npm i -D figma-cache-toolchain
25
- ```
26
-
27
- ### 2) 初始化 Cursor 模板与任务书
28
-
29
- ```bash
30
- npx figma-cache cursor init
31
- ```
32
-
33
- 该命令会：
34
-
35
- - 写入或跳过（已存在且未使用 `--force`）`.cursor/rules/`、`.cursor/skills/`
36
- - 确保根目录存在 `figma-cache.config.js`
37
- - 刷新根目录 `AGENT-SETUP-PROMPT.md`
38
- - 同步刷新 `figma-cache/docs/colleague-guide-zh.md`
39
-
40
- ### 3) 初始化本地缓存索引
41
-
42
- ```bash
43
- npm run figma:cache:init
44
- ```
45
-
46
- 若项目还没配置 scripts，可临时使用：
47
-
48
- ```bash
49
- npx figma-cache init
50
- ```
51
-
52
- ### 4) 执行校验
53
-
54
- ```bash
55
- npm run figma:cache:validate
56
- ```
57
-
58
- ---
59
-
60
- ## 默认 completeness 与 token 开销
61
-
62
- 默认 completeness：`layout,text,tokens,interactions,states,accessibility`（默认不含 `flow/assets`）。
63
-
64
- - `flow` 默认关闭，避免常规场景冗余
65
- - 自动追加 `flow` 仅命中白名单时触发：
66
- - 关系关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
67
- - 同轮或断续出现多个 Figma 链接，且明确存在先后/串联意图（如 A->B）
68
- - 以下场景不自动追加 `flow`：单链接且无关系意图、仅视觉微调/文案修改、仅资产导出
69
- - `assets` 仍按需开启，避免资产留档体积膨胀
70
- - token 开销通常在启用 `flow` 且节点复杂时上升更明显
71
- - 触发自动补 `flow` 时，建议在执行日志/回复中记录触发原因（关键词命中或多链接串联意图），便于审计
72
-
73
- 按需覆盖示例：
74
-
75
- ```bash
76
- # 常规场景
77
- npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
78
-
79
- # 关联节点/同轮或断续多链接串联场景（自动或显式）
80
- npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow
81
-
82
- # 同时需要资产留档
83
- npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow,assets
84
- ```
85
-
86
- ---
87
-
88
- ## 常用命令
89
-
90
- ```bash
91
- npm run figma:cache:init
92
- npm run figma:cache:config
93
- npm run figma:cache:get -- "<figma-url>"
94
- npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility
95
- npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
96
- npm run figma:cache:validate
97
- npm run figma:cache:budget
98
- npm run figma:cache:stale
99
- npm run figma:cache:backfill
100
- ```
101
-
102
- 严格证据模式（默认开启）：
103
-
104
- - 当 `source=figma-mcp` 时，`upsert/ensure` 会先校验 `mcp-raw` 证据映射
105
- - 仅在你明确需要先落索引骨架时，才使用 `--allow-skeleton-with-figma-mcp`
106
- - `validate` 会校验 `coverageSummary.evidence`，缺失或 TODO 占位会失败
107
-
108
- ---
109
-
110
- ## git 用户（仓库开发）
111
-
112
- ### 1) 克隆并安装依赖
113
-
114
- ```bash
115
- git clone https://github.com/907086379/figma-cache-toolchain.git
116
- cd figma-cache-toolchain
117
- npm ci
118
- ```
119
-
120
- ### 2) 本地自检
121
-
122
- ```bash
123
- npm run docs:encoding:check
124
- npm test
125
- ```
126
-
127
- ### 3) 提交前建议
128
-
129
- - 确认 `README.md`、`figma-cache/docs/*.md` 编码为 UTF-8 无 BOM
130
- - 变更 CLI 行为后，同步更新文档与示例命令
131
- - 只提交与本次任务相关文件
132
-
133
- ---
134
-
135
- ## 文档入口
136
-
137
- - `figma-cache/docs/README.md`：完整脚本、环境变量、回填与维护说明
138
- - `figma-cache/docs/colleague-guide-zh.md`：团队协作指南与提示词模板
139
- - `figma-cache/docs/link-normalization-spec.md`：链接标准化规范
140
- - `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
141
- - `AGENT-SETUP-PROMPT.md`：项目接入任务书（`cursor init` 会刷新）
142
- - `docs/mobile-native-adapter-template.md`：iOS/Android 双端适配模板与最小转换脚本说明
1
+ # figma-cache-toolchain
2
+
3
+ 面向业务项目的 Figma 本地缓存工具链：默认采用“本地缓存优先 + 按需 MCP + 最小调用集 + 严格证据校验 + validate 闭环”，提供链接标准化、索引与流程关系维护、缓存读写、校验与预算分析能力。该工具链聚焦“Figma -> 本地通用缓存”数据层，不直接绑定具体 UI 框架。
4
+
5
+ - npm 包：`figma-cache-toolchain`
6
+ - Git 仓库：<https://github.com/907086379/figma-cache-toolchain.git>
7
+
8
+ ---
9
+
10
+ ## 这份 README 面向谁
11
+
12
+ - npm 用户：把工具链接入业务项目并日常使用
13
+ - git 用户：在仓库内开发、测试、提交改动
14
+
15
+ > npm 发布由仓库维护者负责；普通用户和贡献者无需执行 `npm publish`。
16
+
17
+ ---
18
+
19
+ ## npm 用户快速开始
20
+
21
+ ### 1) 安装
22
+
23
+ ```bash
24
+ npm i -D figma-cache-toolchain
25
+ ```
26
+
27
+ ### 2) 初始化 Cursor 模板与任务书
28
+
29
+ ```bash
30
+ npx figma-cache cursor init
31
+ ```
32
+
33
+ 该命令会：
34
+
35
+ - 默认覆盖写入最新 `.cursor/rules/`、`.cursor/skills/` 模板
36
+ - 新增通用规则：`.cursor/rules/00-output-token-budget.mdc`（全任务低 token 输出基线）
37
+ - 若需保留已存在模板，可使用 `npx figma-cache cursor init --force`（跳过同名覆盖）
38
+ - 确保根目录存在 `figma-cache.config.js`
39
+ - 刷新根目录 `AGENT-SETUP-PROMPT.md`
40
+ - 同步刷新 `figma-cache/docs/colleague-guide-zh.md`
41
+
42
+ ### 3) 初始化本地缓存索引
43
+
44
+ ```bash
45
+ npm run figma:cache:init
46
+ ```
47
+
48
+ 若项目还没配置 scripts，可临时使用：
49
+
50
+ ```bash
51
+ npx figma-cache init
52
+ ```
53
+
54
+ ### 4) 执行校验
55
+
56
+ ```bash
57
+ npm run figma:cache:validate
58
+ ```
59
+
60
+ ---
61
+
62
+ ## 团队协作建议（来自同事指南精简版）
63
+
64
+ - 默认执行链：**先查缓存** -> 按需 MCP -> 原始回包写 `mcp-raw/` -> `upsert/ensure` -> `validate`
65
+ - 当 `source=figma-mcp` 时，`mcp-raw` 证据不完整会被门禁拦截，不能只写骨架宣称成功
66
+ - 默认 completeness：`layout,text,tokens,interactions,states,accessibility`
67
+ - `flow` 仅在关系关键词命中或多链接明确串联意图时自动追加
68
+ - 回报建议包含：缓存状态、来源（Local/MCP）、MCP 调用次数、输出文件清单
69
+ - 团队可直接复用 `figma-cache/docs/colleague-guide-zh.md` 中的主提示词模板
70
+
71
+ ---
72
+
73
+ ## 默认 completeness 与 token 开销
74
+
75
+ 默认 completeness：`layout,text,tokens,interactions,states,accessibility`（默认不含 `flow/assets`）。
76
+
77
+ - `flow` 默认关闭，避免常规场景冗余
78
+ - 自动追加 `flow` 仅命中白名单时触发：
79
+ - 关系关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
80
+ - 同轮或断续出现多个 Figma 链接，且明确存在先后/串联意图（如 A->B）
81
+ - 以下场景不自动追加 `flow`：单链接且无关系意图、仅视觉微调/文案修改、仅资产导出
82
+ - `assets` 仍按需开启，避免资产留档体积膨胀
83
+ - token 开销通常在启用 `flow` 且节点复杂时上升更明显
84
+ - 触发自动补 `flow` 时，建议在执行日志/回复中记录触发原因（关键词命中或多链接串联意图），便于审计
85
+
86
+ 按需覆盖示例：
87
+
88
+ ```bash
89
+ # 常规场景
90
+ npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
91
+
92
+ # 关联节点/同轮或断续多链接串联场景（自动或显式）
93
+ npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow
94
+
95
+ # 同时需要资产留档
96
+ npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility,flow,assets
97
+ ```
98
+
99
+ ---
100
+
101
+ ## 常用命令
102
+
103
+ ```bash
104
+ npm run figma:cache:init
105
+ npm run figma:cache:config
106
+ npm run figma:cache:get -- "<figma-url>"
107
+ npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility
108
+ npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility
109
+ npm run figma:cache:validate
110
+ npm run figma:cache:budget
111
+ npm run figma:cache:stale
112
+ npm run figma:cache:backfill
113
+ ```
114
+
115
+ 严格证据模式（默认开启）：
116
+
117
+ - 当 `source=figma-mcp` 时，`upsert/ensure` 会先校验 `mcp-raw` 证据映射
118
+ - 仅在你明确需要先落索引骨架时，才使用 `--allow-skeleton-with-figma-mcp`
119
+ - `validate` 会校验 `coverageSummary.evidence`，缺失或 TODO 占位会失败
120
+
121
+ ---
122
+
123
+ ## git 用户（仓库开发）
124
+
125
+ ### 1) 克隆并安装依赖
126
+
127
+ ```bash
128
+ git clone https://github.com/907086379/figma-cache-toolchain.git
129
+ cd figma-cache-toolchain
130
+ npm ci
131
+ ```
132
+
133
+ ### 2) 本地自检
134
+
135
+ ```bash
136
+ npm run docs:encoding:check
137
+ npm test
138
+ ```
139
+
140
+ ### 3) 提交前建议
141
+
142
+ - 确认 `README.md`、`figma-cache/docs/*.md` 编码为 UTF-8 无 BOM
143
+ - 变更 CLI 行为后，同步更新文档与示例命令
144
+ - 只提交与本次任务相关文件
145
+
146
+ ---
147
+
148
+ ## 文档入口
149
+
150
+ - `figma-cache/docs/README.md`：完整脚本、环境变量、回填与维护说明
151
+ - `figma-cache/docs/colleague-guide-zh.md`：团队协作指南与提示词模板
152
+ - `figma-cache/docs/quick-start-zh.md`：一页式同事速查卡（3 分钟上手）
153
+ - `figma-cache/docs/link-normalization-spec.md`：链接标准化规范
154
+ - `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
155
+ - `AGENT-SETUP-PROMPT.md`：项目接入任务书（`cursor init` 会刷新）
156
+ - `docs/mobile-native-adapter-template.md`：iOS/Android 双端适配模板与最小转换脚本说明
package/bin/figma-cache.js CHANGED
@@ -1,2 +1,2 @@
1
- #!/usr/bin/env node
1
+ #!/usr/bin/env node
2
2
  require("../figma-cache/figma-cache.js");
package/cursor-bootstrap/AGENT-SETUP-PROMPT.md CHANGED
@@ -2,6 +2,7 @@
2
2
 
3
3
  > **给 Cursor Agent 的指令**：你正在操作的是**用户业务项目**的根目录。以下文件应已存在（由 `npx figma-cache cursor init` 从 npm 包 **`{{NPM_PACKAGE_NAME}}`** 复制到当前仓库根）：
4
4
  > - `.cursor/rules/01-figma-cache-core.mdc`
5
+ > - `.cursor/rules/00-output-token-budget.mdc`（通用低 token 输出基线）
5
6
  > - `.cursor/rules/02-figma-stack-adapter.mdc`（**占位**，任务完成后需删除）
6
7
  > - `.cursor/rules/figma-local-cache-first.mdc`（可选保留）
7
8
  > - `.cursor/skills/figma-mcp-local-cache/SKILL.md`
@@ -37,6 +38,11 @@
37
38
  - 说明：后续 Figma 相关对话将主要由 **01 Core + 新 Adapter + Skill** 驱动。
38
39
  - **可选**：若项目已通过 `cursor init` 同步 `figma-cache/docs/colleague-guide-zh.md`，提示团队默认只使用 **§5.1「最推荐主提示词」**，只有特殊诉求再追加 **§5.2** 的一句附加要求。
39
40
 
41
+ ## 输出与 token 约束（强制）
42
+ - 默认“只要结果”：不输出思考过程，不粘贴 MCP 长回包。
43
+ - 执行 Figma MCP 后，用户可见回复只保留：缓存状态、调用次数、产物路径、校验结论、失败修复动作。
44
+ - 除非用户明确要求，禁止在 chat 中贴出 `get_design_context` 全文；原始内容仅保存到 `mcp-raw/*`。
45
+
40
46
  ## 硬约束（违反则视为未完成）
41
47
 
42
48
  - **不要**修改 `node_modules/{{NPM_PACKAGE_NAME}}/` 下已发布包内文件（应无此必要）。
@@ -51,4 +57,4 @@
51
57
 
52
58
  ---
53
59
 
54
- **开始执行：**读完本文件后立刻按上述顺序操作仓库文件，直至全部完成。
60
+ **开始执行：**读完本文件后立刻按上述顺序操作仓库文件，直至全部完成。
package/cursor-bootstrap/rules/00-output-token-budget.mdc ADDED
@@ -0,0 +1,26 @@
1
+ ---
2
+ description: 通用低 token 输出基线（结果优先，最小回显）
3
+ alwaysApply: true
4
+ ---
5
+
6
+ # Output Token Budget（通用）
7
+
8
+ 适用于所有任务（不仅限 Figma）。目标：减少对话 token 消耗，只输出结果与可执行结论。
9
+
10
+ ## 默认输出策略（强制）
11
+ - 结果优先：不输出思考过程，不做长篇背景铺垫。
12
+ - 最小必要：只输出结论、关键变更、验证结果、下一步动作。
13
+ - 工具原文最小化：禁止在回复中粘贴大段工具原始回包/日志，除非用户明确要求查看原文。
14
+ - 文件优先：大内容落到文件，再汇报路径；回复仅给摘要与定位。
15
+
16
+ ## 任务分级（强制）
17
+ - UI/组件实现：默认读取并使用完整设计证据，不反复讨论“是否需要读取”；完成后仅汇报最终差异与验证。
18
+ - 逻辑/流程/校验类任务：优先读取摘要产物（如 `raw.json`、`spec.md`、`manifest`），避免无关大文件。
19
+
20
+ ## 交互与进度（强制）
21
+ - 仅在必要阻塞时提问；可自行推断时不追问。
22
+ - 中间进度最多 1 条（长任务可 2 条），其余一次性收敛到最终结果。
23
+ - 失败反馈固定三段：失败原因、定位信息、修复动作。
24
+
25
+ ## 例外
26
+ - 用户明确要求“展示完整输出/完整日志/原文”时，才突破上述限制。
package/cursor-bootstrap/rules/01-figma-cache-core.mdc CHANGED
@@ -42,10 +42,10 @@ alwaysApply: true
42
42
  - `interactions` / `flow` / `states` → `get_design_context` + `state-map.md`/`flows` 回写
43
43
  - `accessibility`（若任务声明）→ 优先 `get_design_context` 的语义线索，不足时标注缺口
44
44
  - `assets`（若任务声明）→ `get_design_context` 中资产 URL；仅当用户要求截图留档再调 `get_screenshot`
45
- - **flow 自动追加白名单（强制）**：默认 completeness 基线为 `layout,text,tokens,interactions,states,accessibility`（不含 `flow`）；仅在命中白名单时自动追加 `flow`：
46
- - 用户明确表达关系/流程意图，且语义命中关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
47
- - 同轮或断续出现多个 Figma 链接，且存在明确先后或串联意图（如 A->B）
48
- - 单链接且无关系意图、仅视觉微调、仅资产导出时，禁止自动追加 `flow`
45
+ - **flow 自动追加白名单（强制）**：默认 completeness 基线为 `layout,text,tokens,interactions,states,accessibility`（不含 `flow`）；仅在命中白名单时自动追加 `flow`：
46
+ - 用户明确表达关系/流程意图，且语义命中关键词：`关联`、`流程`、`跳转`、`前后页`、`上一步`、`下一步`、`分支`、`链路`、`路径`、`from/to`、`next`、`branch`
47
+ - 同轮或断续出现多个 Figma 链接，且存在明确先后或串联意图（如 A->B）
48
+ - 单链接且无关系意图、仅视觉微调、仅资产导出时，禁止自动追加 `flow`
49
49
  9. **两阶段拉取**：先按最小必要工具取数并检查字段缺口；仅在缺口存在时进入第二阶段补调工具。
50
50
  10. **写入一致性门禁（强制）**：当 `source=figma-mcp` 或输出来源标注 MCP 时，节点目录必须存在 `mcp-raw/` 与对应原始文件；若缺失则视为未完成，必须停止并报告，不得宣称“更新成功”。
51
51
  11. **严格证据门禁（强制）**：当 `source=figma-mcp` 且未显式传入 `--allow-skeleton-with-figma-mcp` 时，`upsert/ensure` 必须在写入前校验 `mcp-raw` 证据：
@@ -56,7 +56,9 @@ alwaysApply: true
56
56
  12. **严格 validate（强制）**：`validate` 不仅校验索引字段，还校验证据完整性：
57
57
  - `completeness` 声明的维度必须在 `raw.json.coverageSummary.evidence` 中提供非空证据
58
58
  - 对 `source=figma-mcp` 且声明 `interactions/states/accessibility` 的节点，禁止保留 TODO 占位内容
59
- 13. **大文件读取策略（强制）**：仅在 UI 还原/像素对齐/组件实现任务中读取 `mcp-raw-get-design-context.txt` 全文；非 UI 任务（命中检查、预算统计、校验、流程维护）默认仅读取 `raw.json` / `spec.md` / `mcp-raw-manifest.json`。
59
+ 13. **大文件读取策略（强制）**：
60
+ - **UI 还原/像素对齐/组件实现任务**：默认必须读取 `mcp-raw-get-design-context.txt` 全文，不反复讨论是否需要读取。
61
+ - **非 UI 任务**（命中检查、预算统计、校验、流程维护）：默认仅读取 `raw.json` / `spec.md` / `mcp-raw-manifest.json`。
60
62
  14. **闭环校验（强制）**：每次 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`** 成功结束后，**自动静默**执行 `npm run figma:cache:validate`。
61
63
  15. validate 失败 → **自行修复并重复 validate 直至通过**，不得宣称缓存已就绪。
62
64
  16. **不写前端**：本阶段禁止输出业务组件实现；若用户要求写 UI，在缓存就绪后转由 **栈专属 Adapter 规则**（如 `02-figma-stack-adapter.mdc` 占位，或项目内 `02-figma-<栈>-adapter.mdc`）接管。
@@ -68,8 +70,15 @@ alwaysApply: true
68
70
 
69
71
  （语义与 `index.json` 中 `nodeId` / `__FILE__` 约定同前；Blockquote 后再写结论。）
70
72
 
71
- - 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
72
-
73
+ - 若本轮自动追加了 `flow`，必须在回复中显式写明触发原因：`关键词命中` 或 `多链接串联意图`（二选一或同时命中）。
74
+
75
+ ## 低 Token 输出模式（强制）
76
+ - 默认采用“结果优先”输出：仅保留最终结论与必要审计字段，不输出思考过程。
77
+ - MCP 工具回包（尤其 `get_design_context`）禁止在用户可见回复中粘贴全文或大段复述；仅报告调用计数、来源、文件路径与校验结果。
78
+ - 除非用户明确要求查看原文，`mcp-raw` 内容仅落盘到文件，不在 chat 回显。
79
+ - 进度反馈最小化：缓存任务默认 0-1 条简短进度更新；完成后一次性给出结果。
80
+ - 失败场景也保持精简：仅输出失败原因、定位文件、下一步修复动作。
81
+
73
82
  ## 配置与钩子
74
83
  - `npm run figma:cache:config` 可查看是否加载 `hooks.postEnsure`。
75
84
  - `ensure` 在写入通用骨架后会调用 `hooks.postEnsure`；钩子异常**不得**阻断 ensure 成功退出（由 Core 捕获）。
@@ -79,30 +88,33 @@ alwaysApply: true
79
88
  - 缓存目录、环境变量、`flows`、陈旧策略、提交前校验等与原「Local Cache First」一致，参见 `figma-cache/` 内文档及 `npm run figma:cache:*`。
80
89
  - 对同一节点写缓存时，优先复用本轮已拿到的 MCP 响应做落盘，避免“仅为生成原始文件而重复调同一工具”。
81
90
  - 若保存原始数据，统一写入节点目录下 `mcp-raw/` 子目录（如 `mcp-raw/mcp-raw-get-design-context.txt`），与加工缓存文件分层。
91
+ - `mcp-raw` 原始文件**禁止**写入任何摘要/截断标记（如 `omitted for brevity`、`...response omitted...`、`省略`、`截断`）；必须直存完整 MCP 回包。
92
+ - `mcp-raw/mcp-raw-manifest.json` 必须记录每个工具原始文件的 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数）；`validate` 会逐项比对，不一致即失败。
93
+ - **落盘后即时反精简检查（强制）**：每次写入 `mcp-raw` 后，必须立刻检查是否出现摘要/截断标记与 hash/size 不一致；检查结果必须在用户回复中显式输出为 `mcp-raw anti-truncation: pass|fail`（失败时附修复动作）。
82
94
  - 默认不写 `whoami` 原始文件；仅在鉴权排障或用户显式要求账号态审计时才写入。
83
95
  - 单节点 MCP 调用预算默认不超过 3 次；超过时必须在输出中说明缺口字段与补调原因。
84
96
  - 仅对超时/5xx做指数退避重试；对参数错误/权限错误不重试，直接报告并等待用户指令。
85
97
  - 不在未校验时假定 Figma 为最新；用户显式要求实时读取时须遵守。
86
- ## Encoding, Shell 兼容与安全写入（强制）
87
- - 仓库内 README / mdc / SKILL / json / js 等文本文件默认使用 **UTF-8 无 BOM**。
88
- - Node 写文件必须显式指定 utf8（如 writeFileSync(path, text, "utf8")）。
89
- - 在 Windows PowerShell 下，**禁止**把 Set-Content / Out-File -Encoding utf8 作为 js/mdc/md/json 的默认写入方式（可能写出 BOM）。
90
- - 若必须用 PowerShell 写文本文件，使用无 BOM 写法：
91
- - `$enc = New-Object System.Text.UTF8Encoding($false)`
92
- - `[System.IO.File]::WriteAllText($path, $text, $enc)`
93
-
94
- ## Shell 语法兼容（PowerShell 强制）
95
- - 当前终端为 PowerShell 时，**禁止**使用 bash heredoc（如 `<<'EOF'`、`<<'PY'`）。
96
- - 当前终端为 PowerShell 时，命令串联默认使用 `;`（或拆成多次调用），**禁止**使用 `&&`。
97
- - 多行文本注入优先使用 PowerShell here-string（`@' ... '@` 或 `@" ... "@`）。
98
- - 文本替换时，禁止把字面量 `\n` / `` `n `` 当作真实换行依赖；必须写入真实换行并回读确认。
99
-
100
- ## 写后必检（强制）
101
- - 每次脚本化写入后，必须立刻回读目标文件，确认无字面量 `\n`、`` `n ``、乱码、截断。
102
- - 对 shebang 文件（如 `#!/usr/bin/env node`），必须确认文件首字节无 BOM。
103
- - 修改 README / rules / skills 后，必须执行 `npm run docs:encoding:check`（或等价编码检查）并确认通过。
104
-
105
- ## 故障恢复（强制）
106
- - 一旦出现 BOM、乱码、PowerShell 语法不兼容、转义换行误写，立即停止增量替换。
107
- - 先回读定位受影响文件，再用 UTF-8 无 BOM 方式整段重写，最后重新执行验证命令。
98
+ ## Encoding, Shell 兼容与安全写入（强制）
99
+ - 仓库内 README / mdc / SKILL / json / js 等文本文件默认使用 **UTF-8 无 BOM**。
100
+ - Node 写文件必须显式指定 utf8（如 writeFileSync(path, text, "utf8")）。
101
+ - 在 Windows PowerShell 下，**禁止**把 Set-Content / Out-File -Encoding utf8 作为 js/mdc/md/json 的默认写入方式（可能写出 BOM）。
102
+ - 若必须用 PowerShell 写文本文件，使用无 BOM 写法：
103
+ - `$enc = New-Object System.Text.UTF8Encoding($false)`
104
+ - `[System.IO.File]::WriteAllText($path, $text, $enc)`
105
+
106
+ ## Shell 语法兼容（PowerShell 强制）
107
+ - 当前终端为 PowerShell 时，**禁止**使用 bash heredoc（如 `<<'EOF'`、`<<'PY'`）。
108
+ - 当前终端为 PowerShell 时，命令串联默认使用 `;`（或拆成多次调用），**禁止**使用 `&&`。
109
+ - 多行文本注入优先使用 PowerShell here-string（`@' ... '@` 或 `@" ... "@`）。
110
+ - 文本替换时，禁止把字面量 `\n` / `` `n `` 当作真实换行依赖；必须写入真实换行并回读确认。
111
+
112
+ ## 写后必检（强制）
113
+ - 每次脚本化写入后，必须立刻回读目标文件，确认无字面量 `\n`、`` `n ``、乱码、截断。
114
+ - 对 shebang 文件（如 `#!/usr/bin/env node`），必须确认文件首字节无 BOM。
115
+ - 修改 README / rules / skills 后，必须执行 `npm run docs:encoding:check`（或等价编码检查）并确认通过。
116
+
117
+ ## 故障恢复（强制）
118
+ - 一旦出现 BOM、乱码、PowerShell 语法不兼容、转义换行误写，立即停止增量替换。
119
+ - 先回读定位受影响文件，再用 UTF-8 无 BOM 方式整段重写，最后重新执行验证命令。
108
120
 
package/cursor-bootstrap/skills/figma-mcp-local-cache/SKILL.md CHANGED
@@ -47,9 +47,9 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
47
47
 
48
48
  ## 流程关系（Flow）
49
49
  - `figma-cache/index.json` 中的 `flows` 用于维护业务/交互流程的节点集合与边关系。
50
- - 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
51
- - 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
52
- - flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
50
+ - 当用户描述「下一步/分支/同一流程」时，应同步更新对应 `flow` 的 `nodes/edges`。
51
+ - 默认 completeness 不含 `flow`；仅命中 flow 白名单时自动追加。
52
+ - flow 白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确串联意图。
53
53
  - 不触发：单链接且无关系意图、仅视觉微调、仅资产导出。
54
54
 
55
55
  ## 标准流程
@@ -77,16 +77,21 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
77
77
  7. **两阶段拉取**：先最小必要调用并检查字段缺口；仅在缺口存在时补调。
78
78
  8. 同一参数的 MCP 工具在单轮内不得重复调用；若需落盘原始数据，必须优先复用首次响应。
79
79
  9. **原始大文本直存策略**：当需保存 `mcp-raw-get-design-context.txt` 时，优先直接写入 `mcp-raw/` 子目录（不改写、不摘要、不二次解释），避免把整段文本再次喂给模型。
80
- 10. **本地分析优先**：若本地已存在可用 `mcp-raw-*` 与缓存加工文件，且用户未要求刷新/强制最新，后续分析默认只读本地文件，不再调用 Figma MCP。
81
- 11. 发生 MCP 拉取或本地补齐时，写入/更新 `meta.json`、`spec.md`、必要补充文件，并更新索引。
82
- 12. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅补齐索引与骨架文件，不能替代 MCP 拉取；不得把“执行了 ensure”当成“完成了 figma-mcp 调用”。
83
- 13. **MCP 证据门禁（强制）**：当输出来源声明为 `figma-mcp` 时，节点目录必须存在 `mcp-raw/` 及最小调用集原始回包（按 completeness 裁剪）；若缺失，立即停止并报告“未完成”，不得宣称更新成功。
84
- 14. **调用预算**：单节点默认 MCP 调用不超过 3 次；超过时必须在回复中说明缺口字段与补调理由。
85
- 15. **重试策略**：仅对超时/5xx进行指数退避重试；参数错误/权限错误不重试并直接报告。
86
- 16. **大文件读取策略（强制）**：仅在“UI 还原/像素对齐/组件实现”任务时读取 `mcp-raw-get-design-context.txt` 全文；非 UI 实现任务（如命中检查、预算统计、校验、流程维护）默认只读 `raw.json`/`spec.md`/`mcp-raw-manifest.json`，避免无意义 token 消耗。
87
- 17. **闭环校验（强制）**：凡本轮执行了 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`**（任意参数组合），在命令成功结束后，Agent **必须**在同一仓库根目录**自动、静默**执行 `npm run figma:cache:validate`。
88
- 18. **校验失败**：根据脚本输出修复索引、`paths`、缺失文件、JSON 结构等，**循环执行 validate 直至退出码为 0**；不得在 validate 未通过时结束本轮「写缓存」任务。
89
- 19. 对用户反馈时除 Blockquote 外可补充：`source: local-cache` / `source: figma-mcp` 与简要文件列表（不必粘贴完整终端日志）。
80
+ 10. **反截断约束（强制）**：`mcp-raw` 文件中禁止出现摘要/截断标记（如 `omitted for brevity`、`...response omitted...`、`省略`、`截断`）；一旦出现，必须视为无效证据并重新落盘完整回包。
81
+ 11. **完整性签名（强制）**：`mcp-raw-manifest.json` 必须提供 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数）；任一工具文件不匹配即视为证据损坏。
82
+ 12. **落盘后即时反精简检查（强制）**：每次写入 `mcp-raw` 后，必须立即执行反精简检查（截断标记 + hash/size）；并在用户回复中显式输出 `mcp-raw anti-truncation: pass|fail`。
83
+ 13. **本地分析优先**：若本地已存在可用 `mcp-raw-*` 与缓存加工文件，且用户未要求刷新/强制最新，后续分析默认只读本地文件，不再调用 Figma MCP。
84
+ 14. 发生 MCP 拉取或本地补齐时，写入/更新 `meta.json`、`spec.md`、必要补充文件，并更新索引。
85
+ 15. **`ensure` 语义边界（强制）**：`figma:cache:ensure` 仅补齐索引与骨架文件，不能替代 MCP 拉取；不得把“执行了 ensure”当成“完成了 figma-mcp 调用”。
86
+ 16. **MCP 证据门禁（强制）**：当输出来源声明为 `figma-mcp` 时，节点目录必须存在 `mcp-raw/` 及最小调用集原始回包（按 completeness 裁剪）；若缺失，立即停止并报告“未完成”，不得宣称更新成功。
87
+ 17. **调用预算**：单节点默认 MCP 调用不超过 3 次；超过时必须在回复中说明缺口字段与补调理由。
88
+ 18. **重试策略**：仅对超时/5xx进行指数退避重试；参数错误/权限错误不重试并直接报告。
89
+ 19. **大文件读取策略（强制）**：
90
+ - UI 还原/像素对齐/组件实现任务：默认必须读取 `mcp-raw-get-design-context.txt` 全文，不反复拉扯“是否需要读全文”。
91
+ - 非 UI 任务（命中检查、预算统计、校验、流程维护）：默认只读 `raw.json`/`spec.md`/`mcp-raw-manifest.json`。
92
+ 20. **闭环校验（强制）**：凡本轮执行了 **`npm run figma:cache:upsert`** 或 **`npm run figma:cache:ensure`**（任意参数组合），在命令成功结束后，Agent **必须**在同一仓库根目录**自动、静默**执行 `npm run figma:cache:validate`。
93
+ 21. **校验失败**：根据脚本输出修复索引、`paths`、缺失文件、JSON 结构等，**循环执行 validate 直至退出码为 0**；不得在 validate 未通过时结束本轮「写缓存」任务。
94
+ 22. 对用户反馈时除 Blockquote 外可补充：`source: local-cache` / `source: figma-mcp`、`mcp-raw anti-truncation: pass|fail` 与简要文件列表（不必粘贴完整终端日志）。
90
95
 
91
96
  ## Agent 最终输出格式（强制）
92
97
  - 触发 `<Trigger Conditions>` 且本轮触碰缓存读写的回复，**第一段**必须为单行 Blockquote：
@@ -165,14 +170,16 @@ description: 将 Figma 链接信息沉淀到项目本地缓存并执行缓存优
165
170
  - **必须先**输出规定的缓存状态 Blockquote，再给出设计结论或实现说明。
166
171
  - 若跳过 MCP，Blockquote 中来源为 Local，状态多为「命中」。
167
172
  - 若调用 MCP，Blockquote 中来源为 MCP，状态多为「缺失→更新」或「更新」，并在后文简述触发原因（未命中/信息不足/用户强刷）。
173
+ - 默认采用低 token 输出：不回显 MCP 原始正文，仅输出调用统计、文件落盘与校验结果。
174
+ - 用户若明确要求“查看原文/贴出回包”时，才输出必要片段；默认引导用户查看 `mcp-raw/*` 本地文件。
168
175
 
169
176
  ## 推荐命令（v2 流程）
170
177
  - `npm run figma:cache:init`：初始化空索引（用于纯净移植）
171
178
  - `npm run figma:cache:config`：查看当前生效配置
172
179
  - `npm run figma:cache:get -- "<figma-url>"`：检查命中情况
173
180
  - 先执行 MCP 最小调用集并写入 `mcp-raw/`，再执行：`npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility`
174
- - `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility`：自动补齐缓存骨架文件（非 MCP 拉取）
175
- - 若命中 flow 白名单场景，自动或显式追加：`--completeness=layout,text,tokens,interactions,states,accessibility,flow`
181
+ - `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility`：自动补齐缓存骨架文件（非 MCP 拉取）
182
+ - 若命中 flow 白名单场景，自动或显式追加：`--completeness=layout,text,tokens,interactions,states,accessibility,flow`
176
183
  - 一旦自动追加了 `flow`，对用户回复必须附带触发原因：`关键词命中` 或 `多链接串联意图`。
177
184
  - MCP 默认最小调用集：`get_design_context(excludeScreenshot=true)` + `get_metadata` + `get_variable_defs`
178
185
  - `npm run figma:cache:validate`：**每次 upsert/ensure 成功后必须自动执行**；失败则修至通过
package/figma-cache/docs/README.md CHANGED
@@ -13,7 +13,7 @@
13
13
 
14
14
  说明：**`cursor init`** 与 **`figma-cache init`** 是两件事；后者才是本地缓存数据目录与空索引。仓库根 **`README.md`**（npm 包首页文档）中有与上述一致的「四步」说明。
15
15
 
16
- 团队向长文（可转发同事）：**`colleague-guide-zh.md`**。
16
+ 团队向长文（可转发同事）：**`colleague-guide-zh.md`**。`quick-start-zh.md` 可作新人一页式速查入口。
17
17
 
18
18
  ## 使用方式（重要）
19
19
 
@@ -28,6 +28,7 @@
28
28
  - `figma-cache/files/...`：节点缓存内容
29
29
  - **`figma-cache/docs/README.md`**：接入、scripts、环境变量、人工校验与回填（本文件，随包分发的主文档）
30
30
  - **`figma-cache/docs/colleague-guide-zh.md`**：团队向说明与提示词模板；**`npx figma-cache cursor init` 会写入/刷新**（与 `FIGMA_CACHE_DIR` 下路径一致），便于纳入版本库、不必从 `node_modules` 手抄
31
+ - `figma-cache/docs/quick-start-zh.md`：一页式同事速查卡（建议新人先读）
31
32
  - `figma-cache/docs/link-normalization-spec.md`：链接标准化规则（Core / Skill 会引用）
32
33
  - `figma-cache/docs/flow-edge-taxonomy.md`：流程边类型约定
33
34
 
@@ -52,22 +53,22 @@ $env:FIGMA_DEFAULT_FLOW="sip-calling-phase1"
52
53
  npm run figma:cache:config
53
54
  ```
54
55
 
55
- ## 常用命令（通常由 agent 自动执行）
56
-
57
- - `npm run figma:cache:init`
58
- - `npm run figma:cache:get -- "<figma-url>"`
59
- - `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility`
60
- - `npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility`
61
- - `npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
62
- - `npm run figma:cache:ensure -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
63
- - 若不传 `--completeness`，CLI 默认即使用：`layout,text,tokens,interactions,states,accessibility`
64
- - 自动追加 `flow` 仅限白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确先后/串联意图
65
- - 单链接且无关系意图、仅视觉微调、仅资产导出时，不自动追加 `flow`
66
- - 若自动追加了 `flow`，Agent 输出中必须记录触发原因：`关键词命中` 或 `多链接串联意图`
67
- - `npm run figma:cache:validate`
68
- - `npm run figma:cache:budget`（默认 `--mcp-only`）
69
- - `npm run figma:cache:stale`
70
- - `npm run figma:cache:backfill`
56
+ ## 常用命令（通常由 agent 自动执行）
57
+
58
+ - `npm run figma:cache:init`
59
+ - `npm run figma:cache:get -- "<figma-url>"`
60
+ - `npm run figma:cache:ensure -- "<figma-url>" --source=manual --completeness=layout,text,tokens,interactions,states,accessibility`
61
+ - `npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens,interactions,states,accessibility`
62
+ - `npm run figma:cache:upsert -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
63
+ - `npm run figma:cache:ensure -- "<figma-url>" --source=figma-mcp --completeness=layout,text,tokens --allow-skeleton-with-figma-mcp`（仅写骨架，后续仍需 `validate` 通过）
64
+ - 若不传 `--completeness`，CLI 默认即使用：`layout,text,tokens,interactions,states,accessibility`
65
+ - 自动追加 `flow` 仅限白名单：关系关键词（关联/流程/跳转/前后页/上一步/下一步/分支/链路/路径/from/to/next/branch），或同轮/断续多链接且明确先后/串联意图
66
+ - 单链接且无关系意图、仅视觉微调、仅资产导出时，不自动追加 `flow`
67
+ - 若自动追加了 `flow`，Agent 输出中必须记录触发原因：`关键词命中` 或 `多链接串联意图`
68
+ - `npm run figma:cache:validate`
69
+ - `npm run figma:cache:budget`（默认 `--mcp-only`）
70
+ - `npm run figma:cache:stale`
71
+ - `npm run figma:cache:backfill`
71
72
  > 注意：`ensure` 默认职责是“写索引 + 生成骨架文件”，不是 MCP 拉取器。
72
73
  > 当 `upsert/ensure` 传 `--source=figma-mcp` 且未显式允许骨架模式时，CLI 会先执行 MCP 原始证据门禁（缺失即失败，退出码 2）。
73
74
  > 正确流程是先由 Agent/Figma MCP 获取最小调用集并写入 `mcp-raw/`，再执行 `upsert/ensure` 与 `validate`。
@@ -76,6 +77,7 @@ npm run figma:cache:config
76
77
 
77
78
  - `validate` 会检查 `raw.json.coverageSummary.evidence` 与 `completeness` 是否一致。
78
79
  - 当 `source=figma-mcp` 且声明 `interactions/states/accessibility` 时，不允许保留 TODO 占位说明。
80
+ - `validate` 会检查 `mcp-raw-manifest.json` 的 `fileHashes`（sha256）与 `fileSizes`（utf8 字节数），并逐项比对原始文件；缺失或不一致会直接失败。
79
81
  - 若你仅想先落骨架，可使用 `--allow-skeleton-with-figma-mcp`（仅放行 upsert/ensure 写入，不放行 validate）；后续必须补齐证据并通过 `validate`。
80
82
 
81
83
  ### 预算统计（token/调用）
@@ -132,7 +134,7 @@ npm run figma:cache:init
132
134
  - **项目根**仍需：`figma-cache.config.js`、`.cursor/` 规则与 Skill、`AGENT-SETUP-PROMPT.md`（或由等价流程生成）。
133
135
  - Vue2+Vuetify2 参考 Adapter：`cursor-bootstrap/examples/vue2-vuetify2-adapter.reference.mdc`（npm 安装时在 `node_modules/.../cursor-bootstrap/examples/`）。
134
136
 
135
- 说明：Cursor **不会**在 `npm install` 时写入 `.cursor/`；`npx figma-cache cursor init` 负责从包内复制模板。已存在模板时 `cursor init` 默认**跳过**（`--force` 覆盖）；**`AGENT-SETUP-PROMPT.md` 每次 `cursor init` 均刷新**。
137
+ 说明：Cursor **不会**在 `npm install` 时写入 `.cursor/`；`npx figma-cache cursor init` 负责从包内复制模板。`cursor init` 默认**覆盖**同名模板为最新版本（`--force` 可改为保留已有模板并跳过覆盖）；并会下发通用低 token 规则 `00-output-token-budget.mdc`；**`AGENT-SETUP-PROMPT.md` 每次 `cursor init` 均刷新**。
136
138
 
137
139
  ## package.json scripts 示例
138
140
 
@@ -178,9 +180,9 @@ npm run figma:cache:init
178
180
  | `FIGMA_CACHE_STALE_DAYS` | 陈旧阈值（天） |
179
181
  | `FIGMA_DEFAULT_FLOW` | 默认 `flowId`（大迭代推荐设置） |
180
182
  | `FIGMA_CACHE_ADAPTER_DOC` | 覆盖 adapter 提示文档基础名（默认 `figma-cache-adapter-hint.md`） |
181
- | `FIGMA_CACHE_ADAPTER_DOC_MODE` | adapter 提示写入模式：`cache-root`（默认，目录级单文件）/ `node`（按节点）/ `off`（关闭） |
182
- | `FIGMA_CACHE_ADAPTER_DOC_CACHE` | `cache-root` 模式下 adapter 提示文档路径（相对项目根，默认 `figma-cache/docs/figma-cache-adapter-hint.md`） |
183
- | `FIGMA_CACHE_ADAPTER_DOC_WRITE_POLICY` | adapter 提示写入策略：`if-missing`（默认）/ `always` |
183
+ | `FIGMA_CACHE_ADAPTER_DOC_MODE` | adapter 提示写入模式：`cache-root`（默认，目录级单文件）/ `node`（按节点）/ `off`（关闭） |
184
+ | `FIGMA_CACHE_ADAPTER_DOC_CACHE` | `cache-root` 模式下 adapter 提示文档路径（相对项目根，默认 `figma-cache/docs/figma-cache-adapter-hint.md`） |
185
+ | `FIGMA_CACHE_ADAPTER_DOC_WRITE_POLICY` | adapter 提示写入策略：`if-missing`（默认）/ `always` |
184
186
  | `FIGMA_CACHE_FLOW_README` | **仅包内示例钩子**：人类可读的「流程 / 需求总览」Markdown 相对路径，默认 **`docs/figma-flow-readme.md`**；每次 `ensure` 对**新 cacheKey** 幂等追加一节 |
185
187
 
186
188
  ## 人工校验清单（对照 `validate`）