figma-cache-toolchain 2.0.3 → 2.0.5

package/figma-cache/docs/p0-ui-preflight-handoff.md

@@ -0,0 +1,207 @@
+# P0 执行交接文档：UI Preflight 门禁落地
+
+> 目标：先落地 **P0**，让 UI 生成前有机器门禁，减少“生成后返工”。
+> 
+> 本文档给下一个 Agent 直接执行，按顺序完成即可。
+
+---
+
+## 1. 背景与目标
+
+当前项目已有：
+
+- `figma-cache validate`：索引/证据完整性门禁
+- `figma:cache:contract:check`：token/state 映射门禁
+- `figma:ui:gate`：聚合门禁（当前无 preflight）
+
+缺口：
+
+- 缺少“面向 UI 任务”的结构化 preflight 产物与阻断策略。
+- 当前 gate 偏通用校验，无法直观看到“为何当前 cacheKey 不适合开工写组件”。
+
+P0 目标：
+
+1. 新增 `figma:ui:preflight` 命令（脚本 `scripts/ui-preflight.js`）。
+2. 生成结构化报告（默认输出到 `figma-cache/reports/ui-preflight-report.json`）。
+3. 存在阻断项时返回非零退出码（建议 `2`）。
+4. 将 preflight 接到 `figma:ui:gate` 前置步骤。
+5. 增加 smoke 覆盖与文档说明。
+
+---
+
+## 2. 设计约束（必须遵守）
+
+- 不修改 Core 语义边界：`figma-cache/figma-cache.js` 继续保持“缓存/索引/校验入口”。
+- P0 先做“门禁与可观测性”，不做 1:1 评分器（那是 P1）。
+- 新脚本必须支持 PowerShell 与 CI（Linux）执行。
+- 输出报告必须机器可读 JSON，便于后续接 CI 与二次分析。
+- 默认尽量零配置可跑；参数可选。
+
+---
+
+## 3. 需要改动的文件（最小集）
+
+### 3.1 新增
+
+- `scripts/ui-preflight.js`
+
+### 3.2 修改
+
+- `package.json`
+  - 新增 script：`figma:ui:preflight`
+  - 调整 script：`figma:ui:gate` 前置执行 preflight
+- `tests/smoke.js`
+  - 增加 preflight 正向/负向用例
+- `README.md`
+  - 增加 preflight 与 gate 新流程
+- `figma-cache/docs/README.md`
+  - 增加 preflight 命令、参数、报告字段
+
+> 若有必要，可补一个文档：`figma-cache/docs/ui-preflight-spec.md`（可选）
+
+---
+
+## 4. `scripts/ui-preflight.js` 规格（执行标准）
+
+## 4.1 CLI 参数
+
+建议支持：
+
+- `--cacheKey=<fileKey#nodeId>`（可选；不传则扫描全部 items）
+- `--contract=<path>`（可选；默认 `figma-cache/adapters/ui-adapter.contract.json`）
+- `--report=<path>`（可选；默认 `figma-cache/reports/ui-preflight-report.json`）
+- `--allow-warn`（可选；仅对 warning 放行，blocking 仍失败）
+
+## 4.2 输入源
+
+- 读取 `FIGMA_CACHE_DIR/index.json`
+- 读取 contract JSON
+- 对每个命中 item 读取：
+  - `paths.meta`
+  - `paths.spec`
+  - `paths.stateMap`
+  - `paths.raw`
+  - 若 source=figma-mcp，则读取 `mcp-raw/mcp-raw-manifest.json`
+
+## 4.3 报告结构（建议）
+
+```json
+{
+  "ok": false,
+  "generatedAt": "ISO",
+  "summary": {
+    "checkedItems": 1,
+    "blockingCount": 2,
+    "warningCount": 1
+  },
+  "items": [
+    {
+      "cacheKey": "xxx#yyy",
+      "source": "manual|figma-mcp",
+      "blocking": ["..."],
+      "warnings": ["..."],
+      "checks": {
+        "cacheItemExists": true,
+        "entryFilesExist": true,
+        "coverageEvidenceReady": false,
+        "contractExists": true,
+        "tokenMappingReady": true,
+        "stateMappingReady": false,
+        "mcpRawReady": true
+      }
+    }
+  ]
+}
+```
+
+## 4.4 阻断规则（P0）
+
+任一命中即 blocking：
+
+- 指定 cacheKey 不存在
+- item 缺失关键文件路径或文件不存在
+- `raw.coverageSummary.evidence` 缺失/维度为空（按 item.completeness）
+- contract 文件不存在或 JSON 非法
+- `tokenMappings` 或 `stateMappings` 为空
+- source=figma-mcp 时缺失 mcp-raw manifest（或 files 映射缺失）
+
+warning（不阻断，可积累）：
+
+- spec/state-map 中仍存在 TODO 占位
+- contract 存在但 mapping 命中率低（可输出统计）
+
+## 4.5 退出码
+
+- `0`: 无 blocking
+- `2`: 存在 blocking 或参数错误
+
+---
+
+## 5. gate 接入策略
+
+调整 `package.json`：
+
+- 新增：
+  - `"figma:ui:preflight": "node scripts/ui-preflight.js"`
+- 调整：
+  - `"figma:ui:gate": "npm run figma:ui:preflight && npm run figma:cache:validate && npm run cursor:shadow:check && npm test"`
+
+> 说明：P0 不强制在 gate 中跑 `figma:cache:contract:check`，避免对旧项目立即破坏性升级。可在 P0.5 再接入。
+
+---
+
+## 6. 测试用例（必须）
+
+在 `tests/smoke.js` 至少补以下：
+
+1. **negative**：指定不存在 cacheKey，preflight 返回 `status=2`
+2. **negative**：构造 raw evidence 缺失，preflight 返回 `status=2`
+3. **positive**：构造最小完整 item + contract，preflight 返回 0，且报告 `ok=true`
+4. **assert 报告文件存在**：默认 report 路径成功写出
+
+---
+
+## 7. 验收命令（交付前必须全部通过）
+
+按顺序执行：
+
+1. `npm run cursor:shadow:sync`
+2. `npm run cursor:shadow:check`
+3. `npm test`
+4. `npm run figma:ui:preflight`（至少跑一次）
+5. `npm run figma:ui:gate`
+
+---
+
+## 8. 风险与注意事项
+
+- `package.json` 当前格式被 PowerShell 写成“宽缩进 + 转义字符形式”，属于可接受状态；若后续要美化，单独做格式提交，不要混在 P0 逻辑提交里。
+- `figma-cache/files/*` 可能有历史样例数据，不要把“样例缺陷”误当脚本 bug。
+- 在 Windows PowerShell 5.1 中链式命令不要用 `&&`；优先 `;`。
+
+---
+
+## 9. 建议提交信息（给下一个 Agent）
+
+```text
+feat(gate): 新增 figma ui preflight 结构化门禁并接入 figma:ui:gate
+
+- 新增 scripts/ui-preflight.js，输出 ui-preflight-report.json 并对阻断项返回 exit code 2。
+- 在 package.json 增加 figma:ui:preflight，且将 figma:ui:gate 前置 preflight 执行。
+- 扩展 smoke 覆盖 preflight 的正负场景与报告落盘断言。
+- 同步 README 与 figma-cache/docs/README.md，补充 preflight 使用说明与报告字段。
+```
+
+---
+
+## 11. 全量优化路线图（P1/P2/P3）
+
+- 总体路线图文档：`figma-cache/docs/ui-1to1-optimization-roadmap.md`
+- 建议：先完成本文件 P0，再按路线图推进 P1 -> P2 -> P3。
+
+---
+## 10. 当前上下文状态（切换 Agent 前说明）
+
+- 最新提交：`8f27b82`
+- 当前工作区：干净
+- 本文档已落地，下一位 Agent 直接按本文执行 P0 即可

package/figma-cache/docs/ui-1to1-optimization-roadmap.md

@@ -0,0 +1,182 @@
+# UI 1:1 还原优化路线图（P0-P3）
+
+> 目标：让 Agent 生成的组件/页面尽可能一次性 1:1 还原，显著降低返工轮次。
+
+---
+
+## 0. 北极星目标与衡量指标
+
+## 0.1 北极星目标
+
+- **一次性交付可用率**：目标从当前基线提升到 `>=85%`（P2 结束）并冲刺 `>=95%`（P3）
+- **平均返工轮次**：降到 `<=1.0`（P2）
+- **关键页面首轮通过率**：`>=90%`（P3）
+
+## 0.2 指标定义（统一口径）
+
+- `firstPassAccepted`: 首轮无需视觉/交互修改即可验收
+- `reworkRounds`: 从首次生成到验收的修改轮次
+- `score.layout/text/token/state/interaction`: 五维质量得分（0-100）
+- `blockingRate`: preflight 阻断率（要区分“真实阻断”与“误报阻断”）
+
+---
+
+## 1. P0（当前）：开工前门禁与可观测性
+
+## 1.1 目标
+
+- 新增 `figma:ui:preflight`，先判断“是否具备开工条件”，减少无效生成。
+- 在 `figma:ui:gate` 中前置 preflight。
+
+## 1.2 交付物
+
+- `scripts/ui-preflight.js`
+- `figma-cache/reports/ui-preflight-report.json`
+- `package.json`：`figma:ui:preflight` + 更新 `figma:ui:gate`
+- `tests/smoke.js`：preflight 正负样例
+
+## 1.3 完成判定
+
+- preflight 对缺失证据/缺失 contract/覆盖证据空维度能稳定阻断（exit 2）
+- gate 能在 preflight blocking 时提前失败
+
+---
+
+## 2. P1：结果可度量（从“过程正确”到“结果可验”）
+
+## 2.1 目标
+
+- 建立统一评分与差异报告，明确“还差多少才 1:1”。
+
+## 2.2 交付物（建议）
+
+1. **质量审计脚本**
+   - 新增：`scripts/ui-1to1-audit.js`
+   - 输入：`cacheKey`、目标组件路径、可选 contract
+   - 输出：`figma-cache/reports/ui-1to1-report.json`
+
+2. **报告规范（schema）**
+   - 新增：`figma-cache/docs/ui-1to1-report.schema.json`
+   - 字段至少包含：
+     - `score.total`
+     - `score.layout/text/token/state/interaction`
+     - `diffs[]`（事实差异项）
+     - `blocking[]`、`warnings[]`
+
+3. **gate 接入阈值**
+   - 新增 script：`figma:ui:audit`
+   - 更新 gate：加入审计阈值（如 `score.total >= 85` 才放行）
+
+## 2.3 技术策略
+
+- 先做“事实对事实”比对（cache 事实 vs 代码事实），避免一上来就纯像素比对。
+- 文本、token、状态覆盖优先，布局分阶段细化（先主轴、后细节）。
+
+## 2.4 完成判定
+
+- 每次生成后都可产出结构化评分报告
+- 失败有明确差异清单，不再依赖人工口头描述
+
+---
+
+## 3. P2：生成准确性强化（减少二次修改）
+
+## 3.1 目标
+
+- 将“映射与规则”从提示词级别，提升为可执行资产，降低 Agent 自由发挥空间。
+
+## 3.2 交付物（建议）
+
+1. **设计事实标准化层**
+   - 新增：`figma-cache/js/ui-facts-normalizer.js`
+   - 职责：把 `spec/raw/state-map/mcp-raw` 统一成稳定事实模型（dimensions/states/tokens/interactions）
+
+2. **组件生成配方（recipe）机制**
+   - 新增目录：`figma-cache/adapters/recipes/`
+   - 每类组件（select/input/modal/table）定义：
+     - 结构模板
+     - 状态机模板
+     - token 映射优先级
+     - 常见陷阱修正
+
+3. **contract 增强（从静态映射到约束映射）**
+   - 扩展 `ui-adapter.contract.json`：
+     - `layoutRules`
+     - `typographyRules`
+     - `interactionRules`
+   - 并增强 `contract-check`：新增规则级校验（非仅 token/state）
+
+4. **节点级 override 正规化**
+   - 规范 `ui-override.json` 字段与优先级
+   - 增加冲突检测（global contract vs node override）
+
+## 3.3 完成判定
+
+- 常见组件类型（前 10 类）首轮通过率显著提升
+- 同一组件跨页面表现一致（规则资产复用）
+
+---
+
+## 4. P3：体系化与规模化（团队长期稳定）
+
+## 4.1 目标
+
+- 让流程可治理、可追踪、可持续优化。
+
+## 4.2 交付物（建议）
+
+1. **模式分层（降低认知负担）**
+   - 引入 `FIGMA_UI_PROFILE=fast|standard|strict`
+   - profile 映射到：preflight 严格度、审计阈值、是否强制预检文档
+
+2. **报告汇总与趋势分析**
+   - 新增：`scripts/ui-report-aggregate.js`
+   - 汇总 `ui-preflight-report.json` + `ui-1to1-report.json`，输出周报/趋势
+
+3. **CI 质量门禁矩阵**
+   - PR 最低门槛：preflight 必过
+   - 主干门槛：audit 分数阈值
+   - 关键路径页面：视觉基线对比（可选）
+
+4. **最佳实践模板化**
+   - 在 `cursor-bootstrap` 增加短版/严格版执行模板
+   - 把高频问题沉淀为“自动检查而非口头提醒”
+
+## 4.3 完成判定
+
+- 指标长期稳定（首轮通过率、返工轮次）
+- 新成员可按模板快速落地，不依赖专家经验
+
+---
+
+## 5. 建议实施顺序（现实可执行）
+
+1. **先做 P0（当前）**：先拦截无效开工
+2. **紧接 P1**：先拿到评分与差异报告
+3. **再做 P2**：把高频返工点产品化（recipe + contract 增强）
+4. **最后 P3**：标准化与团队化治理
+
+---
+
+## 6. 每阶段建议工期（参考）
+
+- P0：1~2 天
+- P1：3~5 天
+- P2：1~2 周（按组件类型分批）
+- P3：持续迭代（每周治理）
+
+---
+
+## 7. 与现有文档关系
+
+- P0 详细执行：`figma-cache/docs/p0-ui-preflight-handoff.md`
+- 本文档：总路线图（P0-P3）
+
+---
+
+## 8. 当前实现进度（2026-04）
+
+- P0：已完成（preflight + gate 前置 + smoke + 文档）
+- P1：已完成（audit + schema + gate 阈值）
+- P2：已完成第一批（facts normalizer、recipes、contract 规则增强、override 冲突检测）
+- P3：已完成第一批（profile 分层、报告聚合、PR/main 门禁矩阵、执行模板）

package/figma-cache/docs/ui-1to1-report.schema.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "UI 1to1 Audit Report",
+  "type": "object",
+  "required": [
+    "ok",
+    "generatedAt",
+    "summary",
+    "blocking",
+    "warnings",
+    "diffs",
+    "items"
+  ],
+  "properties": {
+    "ok": {
+      "type": "boolean"
+    },
+    "generatedAt": {
+      "type": "string"
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "checkedItems",
+        "score",
+        "blockingCount",
+        "warningCount",
+        "diffCount",
+        "minScore"
+      ],
+      "properties": {
+        "checkedItems": { "type": "integer" },
+        "blockingCount": { "type": "integer" },
+        "warningCount": { "type": "integer" },
+        "diffCount": { "type": "integer" },
+        "minScore": { "type": "number" },
+        "recipesTotal": { "type": "integer" },
+        "recipesMatchedItems": { "type": "integer" },
+        "score": {
+          "type": "object",
+          "required": ["total", "layout", "text", "token", "state", "interaction"],
+          "properties": {
+            "total": { "type": "number" },
+            "layout": { "type": "number" },
+            "text": { "type": "number" },
+            "token": { "type": "number" },
+            "state": { "type": "number" },
+            "interaction": { "type": "number" }
+          }
+        }
+      }
+    },
+    "blocking": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "diffs": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["cacheKey", "score", "blocking", "warnings", "diffs"],
+        "properties": {
+          "cacheKey": { "type": "string" },
+          "score": {
+            "type": "object",
+            "required": ["total", "layout", "text", "token", "state", "interaction"],
+            "properties": {
+              "total": { "type": "number" },
+              "layout": { "type": "number" },
+              "text": { "type": "number" },
+              "token": { "type": "number" },
+              "state": { "type": "number" },
+              "interaction": { "type": "number" }
+            }
+          },
+          "blocking": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "warnings": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "diffs": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "matchedRecipes": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}