cardbuddy 0.15.0 → 0.17.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 (107) hide show
  1. package/dist/init.js +0 -2
  2. package/dist/preview-editor/assets/index-CXDf5tVg.css +1 -0
  3. package/dist/preview-editor/assets/{index-CIIfMlwI.js → index-DLQkCPLT.js} +113 -86
  4. package/dist/preview-editor/index.html +2 -2
  5. package/dist/vendored/card-editor/runtime/adapter.js +2 -2
  6. package/dist/vendored/mcp/client.mjs +1 -1
  7. package/dist/vendored/server/core/ai-chat.js +251 -80
  8. package/dist/vendored/server/core/browser.js +17 -0
  9. package/dist/vendored/server/core/cardFiles.js +49 -1
  10. package/dist/vendored/server/core/cardImage.js +103 -2
  11. package/dist/vendored/server/core/cardValidate.js +16 -5
  12. package/dist/vendored/server/core/screenshot.js +94 -0
  13. package/dist/vendored/skills/card-skill-trainer/SKILL.md +68 -13
  14. package/dist/vendored/skills/card-skill-trainer/scripts/diagnose_case.mjs +14 -82
  15. package/dist/vendored/skills/card-skill-trainer/scripts/lib/diagnosis.mjs +207 -0
  16. package/dist/vendored/skills/card-skill-trainer/scripts/lib/layout-correction-sim.mjs +62 -0
  17. package/dist/vendored/skills/card-skill-trainer/scripts/lib/paradigm-router.mjs +76 -0
  18. package/dist/vendored/skills/card-skill-trainer/scripts/lib/pixel-worker-runner.mjs +31 -0
  19. package/dist/vendored/skills/card-skill-trainer/scripts/lib/pixel-worker.mjs +138 -0
  20. package/dist/vendored/skills/card-skill-trainer/scripts/lib/scoring.mjs +24 -20
  21. package/dist/vendored/skills/card-skill-trainer/scripts/lib/telemetry.mjs +46 -0
  22. package/dist/vendored/skills/card-skill-trainer/scripts/plan_next_round.mjs +5 -2
  23. package/dist/vendored/skills/card-skill-trainer/scripts/run_round.mjs +286 -92
  24. package/dist/vendored/skills/card-skill-trainer/scripts/score_round.mjs +74 -2
  25. package/dist/vendored/skills/card-skill-trainer/scripts/sink_rules.mjs +127 -0
  26. package/dist/vendored/skills/dsl-card-generator/SKILL.md +93 -27
  27. package/dist/vendored/skills/dsl-card-generator/references/component_rules.md +14 -0
  28. package/dist/vendored/skills/dsl-card-generator/references/dsl_structure.md +1 -15
  29. package/dist/vendored/skills/dsl-card-generator/references/expression_engine.md +11 -20
  30. package/dist/vendored/skills/dsl-card-generator/references/generation_pitfalls.md +217 -44
  31. package/dist/vendored/skills/dsl-card-generator/references/ir-format.md +87 -3
  32. package/dist/vendored/skills/dsl-card-generator/references/iteration_protocol.md +35 -6
  33. package/dist/vendored/skills/dsl-card-generator/references/previewer_contract.md +21 -0
  34. package/dist/vendored/skills/dsl-card-generator/references/quickref.md +28 -27
  35. package/dist/vendored/skills/dsl-card-generator/references/recipes.md +30 -8
  36. package/dist/vendored/skills/dsl-card-generator/references/rules.md +3 -2
  37. package/dist/vendored/skills/dsl-card-generator/references/scripts_reference.md +5 -2
  38. package/dist/vendored/skills/dsl-card-generator/references/slices_convention.md +2 -3
  39. package/dist/vendored/skills/dsl-card-generator/references/spec_to_schema_patterns.md +1 -4
  40. package/dist/vendored/skills/dsl-card-generator/scripts/add_component.mjs +5 -14
  41. package/dist/vendored/skills/dsl-card-generator/scripts/autofix_schema.py +88 -0
  42. package/dist/vendored/skills/dsl-card-generator/scripts/check_fidelity.mjs +143 -42
  43. package/dist/vendored/skills/dsl-card-generator/scripts/check_topology.py +0 -35
  44. package/dist/vendored/skills/dsl-card-generator/scripts/expand_ir.mjs +99 -53
  45. package/dist/vendored/skills/dsl-card-generator/scripts/gate.mjs +5 -2
  46. package/dist/vendored/skills/dsl-card-generator/scripts/iterate.mjs +388 -29
  47. package/dist/vendored/skills/dsl-card-generator/scripts/lib/component_contract.mjs +315 -0
  48. package/dist/vendored/skills/dsl-card-generator/scripts/lib/layout-tokens.mjs +1 -1
  49. package/dist/vendored/skills/dsl-card-generator/scripts/lib/paths.mjs +23 -0
  50. package/dist/vendored/skills/dsl-card-generator/scripts/lib/paths.py +0 -37
  51. package/dist/vendored/skills/dsl-card-generator/scripts/lib/python.mjs +99 -0
  52. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/adaptive-width.mjs +105 -0
  53. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/bindings.mjs +260 -0
  54. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/expr.mjs +52 -0
  55. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/image.mjs +96 -0
  56. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/registry.mjs +166 -0
  57. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/structure.mjs +127 -0
  58. package/dist/vendored/skills/dsl-card-generator/scripts/lib/rules/walk.mjs +61 -0
  59. package/dist/vendored/skills/dsl-card-generator/scripts/lib/scaffold.mjs +48 -1
  60. package/dist/vendored/skills/dsl-card-generator/scripts/lib/scope_alias.mjs +125 -0
  61. package/dist/vendored/skills/dsl-card-generator/scripts/lib/v3_assemble.mjs +366 -45
  62. package/dist/vendored/skills/dsl-card-generator/scripts/lib/v3_extract.mjs +169 -12
  63. package/dist/vendored/skills/dsl-card-generator/scripts/lib/v3_shared.mjs +17 -9
  64. package/dist/vendored/skills/dsl-card-generator/scripts/lint_card.mjs +119 -78
  65. package/dist/vendored/skills/dsl-card-generator/scripts/preflight.mjs +48 -50
  66. package/dist/vendored/skills/dsl-card-generator/scripts/readiness.mjs +634 -0
  67. package/dist/vendored/skills/dsl-card-generator/scripts/register_card_template.mjs +5 -8
  68. package/dist/vendored/skills/dsl-card-generator/scripts/route_input.mjs +5 -10
  69. package/dist/vendored/skills/dsl-card-generator/scripts/spec_audit.mjs +122 -8
  70. package/dist/vendored/skills/dsl-card-generator/scripts/v3_regression.mjs +11 -2
  71. package/dist/vendored/skills/dsl-card-generator/scripts/validate_schema.py +23 -15
  72. package/dist/vendored/skills/finmall-card-sync/scripts/api_batch_sync.mjs +46 -2
  73. package/dist/vendored/skills/mbank-design-gen/SKILL.md +76 -0
  74. package/dist/vendored/skills/mbank-design-gen/assets/icons/icon-apps.png +0 -0
  75. package/dist/vendored/skills/mbank-design-gen/assets/icons/icon-arrow-right-blue.png +0 -0
  76. package/dist/vendored/skills/mbank-design-gen/assets/icons/icon-check.png +0 -0
  77. package/dist/vendored/skills/mbank-design-gen/assets/icons/icon-settings.png +0 -0
  78. package/dist/vendored/skills/mbank-design-gen/assets/icons/icon-sound.png +0 -0
  79. package/dist/vendored/skills/mbank-design-gen/assets/icons/icon-voice-switch.png +0 -0
  80. package/dist/vendored/skills/mbank-design-gen/assets/icons/progress-thumb.png +0 -0
  81. package/dist/vendored/skills/mbank-design-gen/assets/icons/tag-bg.png +0 -0
  82. package/dist/vendored/skills/mbank-design-gen/assets/icons/vs-badge.png +0 -0
  83. package/dist/vendored/skills/mbank-design-gen/assets/ref/ref-chat-options.png +0 -0
  84. package/dist/vendored/skills/mbank-design-gen/assets/ref/ref-home-scene.png +0 -0
  85. package/dist/vendored/skills/mbank-design-gen/assets/ref/ref-product-detail.png +0 -0
  86. package/dist/vendored/skills/mbank-design-gen/assets/ref/ref-rate-table.png +0 -0
  87. package/dist/vendored/skills/mbank-design-gen/assets/robot.png +0 -0
  88. package/dist/vendored/skills/mbank-design-gen/references/component-library.md +127 -0
  89. package/dist/vendored/skills/mbank-design-gen/references/design-spec.md +261 -0
  90. package/dist/vendored/skills/mbank-design-gen/templates/mockup-template.html +138 -0
  91. package/dist/vendored/skills/mbank-design-gen/tools/screenshot.mjs +34 -0
  92. package/dist/vendored/skills/shared/exit-codes.md +79 -0
  93. package/dist/vendored/skills/shared/spec-contract.md +127 -0
  94. package/dist/vendored/skills/sketch-spec-to-card/SKILL.md +27 -10
  95. package/dist/vendored/skills/sketch-spec-to-card/references/spec-schema.md +3 -3
  96. package/dist/vendored/skills/sketch-spec-to-card/scripts/build_prompt.py +0 -8
  97. package/dist/vendored/skills/sketch-spec-to-card/scripts/cluster_states.py +14 -25
  98. package/dist/vendored/skills/sketch-spec-to-card/scripts/parse_meaxure.py +121 -47
  99. package/dist/vendored/skills/sketch-spec-to-card/scripts/png_utils.py +0 -5
  100. package/dist/vendored/skills/sketch-spec-to-card/scripts/test_text_only_artboard.py +98 -16
  101. package/dist/vendored/skills/sketch-spec-to-card/scripts/vision.py +55 -37
  102. package/dist/vendored/templates/helloCard/schema.json +62 -1
  103. package/dist/vendored/tools/finmall-env.mjs +1 -18
  104. package/package.json +1 -1
  105. package/dist/preview-editor/assets/index-DQn0zQBP.css +0 -1
  106. package/dist/vendored/skills/card-skill-trainer/scripts/test_missing_slice.py +0 -122
  107. package/dist/vendored/skills/dsl-card-generator/scripts/analyze_component_usage.mjs +0 -153
@@ -0,0 +1,127 @@
1
+ # spec.json 契约(sketch-spec-to-card ↔ dsl-card-generator)
2
+
3
+ > **单一权威**:本文件是 `UI/<画板>/spec.json` 的唯一契约定义。`references/spec-schema.md`(上游)只描述字段来源与判定逻辑,**字段的增删改以本文件为准**。
4
+ >
5
+ > - **生产者**:`skills/sketch-spec-to-card`(唯一写出方 = `scripts/parse_meaxure.py`;视觉判定出自 `vision.py`,列表/意图出自 `build_prompt.py`)
6
+ > - **消费者**:`skills/dsl-card-generator`(生产建卡路径)、`skills/card-skill-trainer`(训练/回归)、`skills/card-doctor`
7
+ > - **机械校验**:`tools/tests/spec-contract.test.mjs` —— 从 `UI/**/spec.json` 聚合实际字段路径,未在本文件登记的路径会让测试失败。**改产物字段必须同步改本文件**。
8
+
9
+ ## 状态口径
10
+
11
+ | 状态 | 含义 | 改动要求 |
12
+ |---|---|---|
13
+ | `active` | 两端或多端在用,**是接口** | 破坏性变更需同步改所有消费者 |
14
+ | `upstream-only` | 只有上游(sketch skill)自用;下游 0 读点 | 下游可无视;改动不通知下游 |
15
+ | `write-only` | **全仓无读点**(只写不读) | 删除候选。删之前先按 §「消重纪律」跑一轮全量确认无外部消费(如训练脚本、外部接入方) |
16
+ | `removed` | 上游已停写(2026-09-24 起) | **禁止在新代码读它**。存量旧产物仍带此字段(无害,不必重跑);登记行保留是为了门禁对存量产物放行 |
17
+
18
+ ## 顶层字段
19
+
20
+ | 字段路径 | 类型 | 生产者 | 消费者 | 状态 | 缺失 / 为 null 时的口径 |
21
+ |---|---|---|---|---|---|
22
+ | `canvas` | string | parse_meaxure | build_prompt、generate_cards、v3_assemble、build_dataset | active | 画板标识,同时是 `UI/<canvas>/` 目录名;同名画板第 2 个起追加 `-2`/`-3`(见 `spec_tree.mjs` 展示名取 `spec.canvas`);不可为空 |
23
+ | `schemaVersion` | string | parse_meaxure | **无** | removed | **已删(2026-09-24 统计定案)**:spec 产物恒 `"1.0"` 零信息量、静态读点 0 + 金标全链路运行时访问 0 → 上游已停写。存量旧产物仍带此字段,无害,不必重跑。注意 manifest.json 的 schemaVersion 是另一处(manifest 自描述),保留 |
24
+ | `size` | {width,height} | parse_meaxure | v3_extract、v3_assemble、spec_tree、iterate | active | 下游回落 `{width:375,height:812}` 并告警 |
25
+ | `cards` | array | vision.detect_cards → parse_meaxure | v3_extract、spec_tree、generate_cards、trainer | active | `[]` = 本画板无卡(`text_only` / 全弹层);下游必须跳过而非报错 |
26
+ | `rejectedCards` | array | vision.detect_cards | build_dataset(训练集构造) | upstream-only | 缺失 = 无拒绝记录;训练侧据此做负样本分析 |
27
+ | `conversationFlow` | object\|null | vision.detect_conversation_flow | **无** | write-only | **保留(2026-09-24 统计)**:96.6% 写入且 10 种真实值(inputDock 几何/bubbleCount/stackedBubblePairs,非对话卡 null)——上游花算力提取的结构化信息,值有信息量;会话流判定当前由 `artboardType=text_only` + `rejectedCards` 承载,此字段是未来对话卡生成的原料。勿与 text_only 判定混谈 |
28
+ | `focusSkipReason` | string | parse_meaxure | build_dataset | upstream-only | 非空 = **跳过了常规候选检测**(含原因)。⚠ **不是「0 卡」的同义词**:`bottom_sheet_geometry` 与 `cards` 非空可同时成立(底部抽屉由面板几何直取,不走候选检测) |
29
+ | `elements` | array | parse_meaxure | v3_extract、spec_tree、trainer | active | **必需**;全画板展平图层(含系统区/背景) |
30
+ | `styleSummary` | object | parse_meaxure | build_prompt | upstream-only | 下游不读:**样式以 `elements[].style` 为准**,禁止从摘要反推单元素样式 |
31
+ | `styleSummary.*` | {colors,gradients,fonts,borderRadius,shadows} | parse_meaxure | build_prompt | upstream-only | 五个子键均为聚合摘要,不进下游 |
32
+ | `artboardType` | string | parse_meaxure.classify_artboard | generate_cards、v3_extract、spec_tree、iterate | active | 取值 `card`/`overlay_dialog`/`subcard`/`text_only`;缺失回落 `card` |
33
+ | `interaction` | string | parse_meaxure | build_prompt、cluster_states | upstream-only | `card` 时为空串 |
34
+ | `jsapiInteractions` | array | parse_meaxure | build_prompt、cluster_states | upstream-only | 缺失 = `[]` |
35
+ | `annotationDefects` | array | parse_meaxure | card-skill-trainer(diagnose_case / plan_next_round / scoring) | active(训练侧) | 缺失 = 视为无标注缺陷 |
36
+ | `slices` | array&lt;string&gt; | parse_meaxure | v3_assemble、v3_extract | active | 本画板 `slices/` 下的相对路径(posix);空数组 = 无切图 |
37
+ | `skippedReason` | string | parse_meaxure | build_prompt | upstream-only | 仅 `cards=[]` 时存在 |
38
+
39
+ ## `cards` 空 / 非空的合法性(按 `artboardType` 分流)
40
+
41
+ `cards` 空与非空**都不代表对错** —— 上游按 `artboardType` 收口,每类的产出与建卡路径如下。下游遇到空 `cards` 时按类型分流,**不要**判成「上游自相矛盾」,也不要在下游补卡:
42
+
43
+ | artboardType | 含义 | `cards[]` | `card-N.png` | 建卡路径(Workflow A.5 口径) | 证据 |
44
+ |---|---|---|---|---|---|
45
+ | text_only | 纯文本画板(对话 / 问答 / 提示),整板无卡 | `[]` | 不产 | **不建卡**(上游按类型收口,勿人工绕过) | `classify_artboard`;`test_text_only_artboard.py` 用例 1 |
46
+ | overlay_dialog | 系统弹框 | `[]` | 视觉 scrim 判定类不产;名称兜底判定类产 fallback `card-1.png` | **不建卡** —— 由父卡 alertDialog 调用承载 | 用例 5 |
47
+ | subcard | 视觉 bottom-sheet 子卡(底部抽屉) | **1 张**(面板几何直取,**不走候选检测**) | 产 `card-1.png`(面板 rect + 顶圆角遮罩) | **建独立 Dialog 卡** —— 与普通卡同构:`rect` / `mask.radius` / 卡内 `elements` / `segments` 齐备 | `detect_artboard_cards` sheet 分支;`vision._bottom_sheet_rect`;用例 4 |
48
+ | card | 0 卡 · 结构丰富:候选被读成控件条 / 无候选(整卡单切图已由兜底提升为 1 张卡,见下注) | `[]` | 产 fallback `card-1.png`(去系统 chrome) | 建卡:以该兜底图 + `elements[]` 为准(**有图无坐标**) | `parse_meaxure.py:645`;`board_tag`(`:1768`);用例 2/6 |
49
+
50
+ > 注:本表首列**刻意不加反引号** —— `spec-contract.test.mjs` 以「首列反引号 + 整行 6 列」识别字段契约表,加反引号会让本表被误当成字段登记。
51
+
52
+ > **`subcard` 产卡(2026-09-24 修)**:此前 `bottom_sheet` 只写 `focusSkipReason` 不产 `cards`,导致 `cluster_states` 承认它是独立逻辑卡(`pageId=card-N`、`isDialog=true`)而 spec 层给不出任何卡级数据。现由 `detect_artboard_cards` 的 sheet 分支把面板几何(`vision._bottom_sheet_rect` 早已算出 rect + 顶圆角)落成 1 张卡;`focusSkipReason` **保持不变**(`classify_artboard` 靠它判 `subcard`,改动会连带打翻 `is_text_only_artboard` / `board_verdict` / trainer 的 `is_popup_case`)。**旧版存量 spec 仍可能是 `subcard` + `cards=[]` → 重跑上游,不要在下游补卡。**
53
+
54
+ > **整卡单切图兜底(2026-09-28)**:设计稿把卡片整体导成一张大切图时(图层树只剩「编组 N」大图),`detect_artboard_cards` 在**常规候选 0 卡**时把该切图提升为 1 张真卡。纯几何判据:宽 ≥ 55%W、高 ≥ 12%H、纵向落在 10%..95%H、区域归属元素只有切图本身(混入任何文本/其他切图标注不兜底)。此前这类画板 `cards=[]` → manifest `trainingEligible=false` → 数据集构建整板跳过,「对话 + 内嵌卡」形态永远进不了训练。兜底后 `cards[0].rect` = 切图几何、卡内 elements 只有该 slice,下游按普通 Image 卡建卡。仅 0 卡时触发,已有卡的画板行为不变。
55
+ >
56
+ > `readiness.mjs` 门 **F**:`cards=[]` 的三类(text_only / overlay_dialog / card)只在 `checks.spec.notes` 记说明,**均不进 `blockers`**;`cards` 非空时只校验 `rect` / `mask` 是否缺失(产卡与否由 Workflow A.5 决定,不是契约缺失)。
57
+ > 门 F 真正拦的只有:`cards` 非空时 `cards[i].rect` / `cards[i].mask` 缺失(旧版产物)、`--card` 序号越界、spec 解析失败。
58
+
59
+ ## `cards[]`
60
+
61
+ | 字段路径 | 类型 | 生产者 | 消费者 | 状态 | 缺失 / 为 null 时的口径 |
62
+ |---|---|---|---|---|---|
63
+ | `cards[].index` | int | parse_meaxure | v3_extract(定位 `card-N.png`)、trainer | active | **1 起**;与 `card-N.png` 的 N 严格同源 |
64
+ | `cards[].rect` | {x,y,width,height} | vision.detect_cards | v3_extract、v3_assemble、spec_tree | active | **`cards` 非空时必需**;画板坐标系设计 px |
65
+ | `cards[].image` | string | parse_meaxure | v3_assemble、render_card、迭代对比 | active | 裁切失败可缺失 → 下游按 `cards[].index` 自行拼 `card-N.png` 并容忍不存在 |
66
+ | `cards[].cardFill` | string\|null | parse_meaxure | v3_extract、v3_assemble | active | `null`(无纯色填充,如渐变/图片底)→ 下游用组件默认底色,**不得从截图像素反推** |
67
+ | `cards[].mask` | object | parse_meaxure(`:584`,**无条件产出**) | spec_tree、v3_extract | active | **必需**。存量 spec 缺失 `mask` 是**旧版产物**(在 `focusMetrics`/`mask`/`cardFill` 批次字段引入前生成)→ 重跑上游 `parse_meaxure.py --build` 即补全;`readiness.mjs` 的 spec 契约检查会拦 |
68
+ | `cards[].mask.type` | `"geometry"` | parse_meaxure | spec_tree(诊断打印) | upstream-only | 固定值;遮罩完全来自图层几何(rect + borderRadius),**不依赖背景颜色** |
69
+ | `cards[].mask.radius` | [tl,tr,br,bl]\|null | parse_meaxure `_card_mask_info` | **v3_extract → v3_assemble** | active | **`null` = 上游没找到带圆角的卡壳**(`_card_mask_info` 返回 `(None, fill)`)。下游 `v3_assemble.mjs:366` 取 `T.radius('card')` 默认圆角 —— **这是契约规定的兜底,不是 bug**。取用时用 `??` 而非 `\|\|`,否则 `radius[0]==0`(真·直角卡)会被误判成"无圆角" |
70
+ | `cards[].mask.shapeCount` | int | parse_meaxure | **无** | write-only | **保留(2026-09-24 统计)**:92% 写入、3 种值(1/2/4,mask 复杂度有变化)。无代码读点,但删除收益为零、有校验价值 |
71
+ | `cards[].focusMetrics` | object | vision.card_focus_metrics | card-skill-trainer | upstream-only | 缺失 = 该卡未参与焦点评分 |
72
+ | `cards[].focusMetrics.*` | {areaRatio,aspectRatio,heightRatio,textCount,richComponentCount,sliceCount,symbolCount,shapeCount} | vision.card_focus_metrics | card-skill-trainer | upstream-only | 训练侧打分用 |
73
+ | `cards[].segments` | array | parse_meaxure.detect_segments | **v3_assemble(真消费)**、build_prompt | active | 空数组 = 未分段;**下游不得自算几何兜底**(上游已是权威,重复判定会给出两个答案) |
74
+ | `cards[].segments[].y` | float | parse_meaxure | v3_assemble | active | 卡内相对坐标 |
75
+ | `cards[].segments[].height` | float | parse_meaxure | v3_assemble | active | 卡内相对坐标 |
76
+ | `cards[].segments[].hint` | string | parse_meaxure | build_prompt | upstream-only | 分段语义提示 |
77
+ | `cards[].segments[].items` | array | parse_meaxure | build_prompt | upstream-only | 段内元素引用 |
78
+ | `cards[].segments[].gap_top` | float | parse_meaxure | **无** | removed | **已删(2026-09-24 定案)**:纯冗余推导值——首段 `gap_top === y` 完全重复,后续段 = 相邻 `y/height` 之差,可无损推导;读点 0 + 金标运行时访问 0 → 上游已停写。间距看 `segments[].y`。存量旧产物仍带此字段,无害。(勘误:初版统计「0/609 写入」是扫描脚本 path 漏 `cards[]` 前缀的误报,真实为 48% 写入) |
79
+ | `cards[].detectedList` | object\|absent | build_prompt | build_prompt | upstream-only | 仅用于生成 prompt 文本,**不进 spec 下游链路**;v3 自行重判列表 |
80
+ | `cards[].flexLayout` | object\|absent | vision.infer_flex_layout | build_prompt、spec_tree(诊断打印) | upstream-only | **不进生成**:flex 方向由 AI 视觉主判 / IR 层决定 |
81
+ | `cards[].cardFillSampled` | string | parse_meaxure | **无** | write-only | **保留(2026-09-24 统计)**:92.3% 写入、4 种色值——是 `cardFillConflict` 的对照基线,删了 conflict 标记就失去参照 |
82
+ | `cards[].cardFillConflict` | true | parse_meaxure | **读 spec 的人/模型**(代码无读点;写入同时打 stderr) | write-only | **保留(2026-09-24 定案)**:30.8% 卡写(恒 true,仅在冲突时写)。它的消费者是**读 spec 的智能体**而非代码——警示「fill 标注不可信,按视觉裁决」;删掉会让冲突静默 |
83
+ | `cards[].trainingEligible` | bool | parse_meaxure | build_dataset、spec_tree、run_round | upstream-only | `false` = 不进训练集 |
84
+ | `cards[].elements` | array | parse_meaxure | v3_extract | active | 归属该卡的图层;结构与顶层 `elements[]` 同构 |
85
+
86
+ ## `elements[]`
87
+
88
+ | 字段路径 | 类型 | 生产者 | 消费者 | 状态 | 缺失 / 为 null 时的口径 |
89
+ |---|---|---|---|---|---|
90
+ | `elements[].name` | string | parse_meaxure | spec_tree、v3_extract | active | 原始 Sketch 层名;仅附属信息,**不参与保留/剔除判定** |
91
+ | `elements[].type` | string | parse_meaxure | v3_extract、spec_tree | active | `symbol`/`shape`/`group`/`slice`/`text` |
92
+ | `elements[].rect` | {x,y,width,height} | parse_meaxure | v3_extract、v3_assemble、spec_tree | active | 画板坐标系设计 px |
93
+ | `elements[].style` | object | parse_meaxure | v3_extract、v3_assemble | active | 平台对齐样式参考(`fill`/`border`/`radius`/`shadow`/`opacity`/`gradient`…),**样式值只从这里读** |
94
+ | `elements[].text` | string\|null | parse_meaxure | build_prompt、v3_extract | active | 仅 text 层;附属记录,不参与判定 |
95
+ | `elements[].textStyle` | object\|null | parse_meaxure | v3_extract | active | 仅 text 层(`fontSize`/`fontFace`/`color`/`textAlign`/`lineHeight`);非 text 层为 `null` |
96
+ | `elements[].slices` | string\|null | parse_meaxure | v3_assemble | active | 仅 slice 层:原始层名(切图匹配溯源);非 slice 层为 `null` |
97
+ | `elements[].annotationDefect` | object\|absent | parse_meaxure(`:1200` / `:1264`) | v3_extract、v3_assemble、v3_shared、card-skill-trainer | active | **仅当该元素的标注有缺陷时才存在**。下游据此决定切图补偿方式;**缺失 ≠ 有缺陷,而是「标注完整」**,所以判定必须用 `el.annotationDefect?.type` 而非存在性反推 |
98
+ | `elements[].annotationDefect.*` | {type,name,reason,approximateSolidColor,resolution,cropSlice} | parse_meaxure | 同上 | active | `type`(如 `missing-slice`)是判定键;`cropSlice` 是「从画板裁切补图」的产物路径 —— 为 `null` 时 `v3_shared.mjs:381` 判定无法补偿,切图会悬空 |
99
+
100
+ ## 消重纪律(v3 与上游的判定边界)
101
+
102
+ 上游已经算过的事,下游**不得自算第二遍**(同一张卡出现两个答案时无裁决机制)。当前已知的越界自算(清理中,需先埋点统计 fallback 触发率,< 5% 才删):
103
+
104
+ | 能力 | 权威(上游) | 下游越界自算 |
105
+ |---|---|---|
106
+ | 分段 segments | `parse_meaxure.detect_segments`(`:294`) | `v3_extract.mjs:277-356, 2000-2068` 几何兜底 |
107
+ | 列表检测 | `build_prompt.detect_list_in_card` → `cards[].detectedList` | `v3_extract.mjs:838-856, 2403-2472` 自行重判(且不读 `detectedList`) |
108
+ | 卡底颜色 | `cards[].cardFill` | `v3_assemble.mjs:5303-5314` 对设计稿二次像素校验 |
109
+ | 圆角 | `cards[].mask.radius` | 自算 `radiusMax`(`v3_shared.mjs:276`) |
110
+
111
+ **已正确划界(下游只消费不重做)**:keyboard / overlay_dialog / 聊天气泡 / 系统 chrome / `annotationDefects` / `artboardType`。
112
+
113
+ ## 存量产物漂移
114
+
115
+ `UI/` 下的 spec.json 是历史产物,与当前代码产出的字段集**可能不一致**:
116
+
117
+ - 缺 `mask` / `focusMetrics` / `cardFill` / `cardFillSampled` / `trainingEligible` 的 = **旧版产物**(上述批次字段引入前生成)。
118
+ - 判定口径:字段出现次数 < `cards[]` 总数即存在旧产物。
119
+ - 处置:**重跑上游**(`parse_meaxure.py --src <导出> --draft <稿名> --build`)而非手工补字段。
120
+ - 不要为了兼容旧产物在下游写 `if (!card.mask)` 分支 —— 契约规定 `mask` 必需,兼容分支会让"上游漏产"永远不被发现。
121
+
122
+ ---
123
+ ### upstream-structural-focus-image-card(r264 训练回灌)
124
+ > lesson: `r264-l01` status: `promoted`
125
+
126
+ 整卡单切图形态(设计稿把卡片整体导出成一张大切图,图层树只剩该图、卡内无任何文本/按钮标注)此前在解析器永远 0 卡:_candidate_visuals 跳过 is_slice → 候选全被低结构门拒绝 → spec.cards=[] → manifest trainingEligible=false → 数据集构建整板跳过,而 is_text_only_artboard 又承认这种板「有卡」(has_card_like_visual),两处口径互相矛盾。修复三件套:① detect_artboard_cards 在常规候选 0 卡时把合格大切图兜底提升为 1 张真卡(判据纯几何:宽≥55%W、高≥12%H、纵向 10%..95%H、区域归属元素仅切图本身,混入任何其他标注不兜底);② card_focus_metrics 把切片当内容而非壳——面积≥55%卡区的壳层排除规则只适用 shape/symbol,切片无条件计数并新增 sliceAreaRatio 字段;③ 训练器上游结构聚焦门新增图像卡通道 sliceAreaRatio≥0.6。生成器对该形态的忠实还原 = 把切片绑为卡背景图(R31 消毒空格→连字符),像素/结构/色彩门按同图对比正常评分。
127
+
@@ -18,7 +18,7 @@ description: 读取 Sketch MeaXure 标注导出(index.html + preview/ + assets
18
18
  3. 一句纯文本提问(「请回复要处理的画板序号,或回复 `全部`」)后**停止输出、结束本轮等回复**;
19
19
  4. 拿到回复才继续:**照抄清单行尾的 `--pick`**(板号 1 起、卡号 1 起:用户说「8.1」就 `--pick 8.1`;多张逗号分隔 `--pick 8.1,9.2`;同板连卡 `--pick 8.1~8.2`;连板 `--pick 7~9`)。等价的 0 起老写法是 `--indices <k-1>`,**不要去换算它**——实测换算错一位,建了错的画板后重跑一整次(34s + 一步 LLM)。`全部` → `--scope-all`(UI 产物全量跑;产卡时视为显式批量授权)。
20
20
 
21
- **「生成产物 / 前处理 / 跑管线」这类请求同样适用本门禁**——「UI 产物允许全量生成」的含义是**用户可以回答 `全部`**,**不是** Agent 可以默认全量。脚本层有机械卡点:`parse_meaxure.py` 不带 `--pick/--only/--indices/--sample/--scope-all` 的生成运行会打印 1..n+全部 清单并 **exit 4**(无人值守训练 `card-skill-trainer` 属显式批量例外,直接带 `--scope-all`)。详见 `dsl-card-generator/references/rules.md §十三` 与本文件 §2 步骤 2。
21
+ **「生成产物 / 前处理 / 跑管线」这类请求同样适用本门禁**——「UI 产物允许全量生成」的含义是**用户可以回答 `全部`**,**不是** Agent 可以默认全量。脚本层有机械卡点:`parse_meaxure.py` 不带 `--pick/--only/--indices/--sample/--scope-all` 的生成运行会打印 1..n+全部 清单并 **exit 4**(退出码语义 `kind=needs-user`,即「**等用户选**」而非脚本报错,见 `skills/shared/exit-codes.md`;无人值守训练 `card-skill-trainer` 属显式批量例外,直接带 `--scope-all`)。详见 `dsl-card-generator/references/rules.md §十三` 与本文件 §2 步骤 2。
22
22
 
23
23
  ## -1. 视觉优先原则(最高优先级)
24
24
 
@@ -51,7 +51,9 @@ Sketch MeaXure 导出的目录,结构形如:
51
51
  UI/
52
52
  manifest.json # 全部画板清单:order / name / status(generated|skipped) / artboardType
53
53
  # / trainingEligible(普通卡=true,子卡/弹框/纯文本板=false)
54
- <画布名>/ # 如「01转账_未登录」,目录名直接用画板原始中文名;若 parse 时传 --draft <稿名>,则整体落在 UI/<draft>/ 下(按稿分片)
54
+ # / name 已唯一化(同名板追加 -2/-3,见下方「同名画板消歧」)
55
+ # / nameOriginal 仅消歧板有(Sketch 里的原始名)
56
+ <画布名>/ # 如「01转账_未登录」,目录名 = 画板名(消歧后);若 parse 时传 --draft <稿名>,则整体落在 UI/<draft>/ 下(按稿分片)
55
57
  artboard.png # 整图截图(来自 preview/,已降采样至最长边≤640,仅作整体参考;卡片细节以 card-N.png 为准)
56
58
  card-N.png # 聚焦裁切图(每张卡片局部,@2x,RGBA;圆角/不规则外区域透明,非原始整稿)
57
59
  spec.json # 视觉要素标注:cards/elements/styleSummary/artboardType/jsapiInteractions + cards[].segments(几何视觉分段)
@@ -73,6 +75,8 @@ UI/
73
75
 
74
76
  > **纯文本板过滤(用户 2026-09-20)**:整板只有对话/问答/提示文字、查不到任何可建卡结构的画板,判 `artboardType=text_only`(`status=skipped`、`trainingEligible=false`)——**没有生成卡片的必要**,不进选板清单的可建卡池。这类画板**不产 `card-N.png`(连以前的整屏兜底裁切也不产,否则 `spec_tree.mjs` 会拿它当预览降级)**,`prompt.md` 只写「本画板不要生成卡片」+ 判定依据,不写建卡要素。规则与回归见 §5 / §6。
75
77
 
78
+ > **同名画板消歧(2026-09-24)**:Sketch 允许两个画板**完全同名**(实测「地址管理」稿 25 板里两个「11…_失败_再次修改」,375×1232/129 层 vs 375×1252/130 层,是两个不同设计)。目录名直接用画板名时,后跑的会**整板覆盖**先跑的——`artboard.png` / `card-N.png` / `spec.json` / `slices/` 静默丢失,且 manifest 两条 entry 指向同一目录;下游按名定位(`generate_cards.mjs`:`uiDir/<name>/spec.json`)也会读错同一份。故 `manifest.canvases[].name` 对**第 2 个及以后**的同名板追加 `-2` / `-3` 后缀(`nameOriginal` 留 Sketch 原始名便于回溯),**目录名、选板清单、下游定位键三者一律用唯一名**——下游零改动即正确。分类判定(`classify_artboard`)与预览图兜底探测仍用原始名,后缀不参与语义。回归见 `test_text_only_artboard.py`「同名画板消歧」。
79
+
76
80
  ## 2. 工作流
77
81
  1. **解析**:`scripts/parse_meaxure.py` 从 `index.html` 提取 `let data={...}` JSON(括号配平后 `json.loads`),遍历全部画板,视觉驱动检测卡片区域 → 裁切聚焦图 → 序列化要素,生成 `manifest.json` + 各画板 `spec.json`/`card-*.png`/`slices/`;同时检测 JSAPI 交互控件(密码/验证码/toast/二次确认)与 Flex 布局。系统 chrome 由 `vision.py` 几何阈值排除(见 §4)。
78
82
  2. **选画板(硬门禁,先于解析/生成)**:先 `parse_meaxure.py --src <导出目录> --list` **机械列出全量画板**,按 **`1..n` 编号(1 起)+ 末尾 `全部`** 交给用户,**停止输出等回复**后才跑管线。**「UI 产物允许全量生成」= 用户可以回答 `全部`(此时加 `--scope-all` 整份导出全跑,素材可复用),不是 Agent 可以默认全量**——用户消息里没指定画板时,**包括「生成产物 / 前处理」在内的任何请求都必须先过本门禁**;**禁止**自行挑画板、**禁止**替用户选「全部」、**禁止**批量产卡、**禁止**「先建一张看看」。下游卡片生成仍以用户指定的单个画板 / 单个 UI 产物为单位(铁律见 `dsl-card-generator/references/rules.md §十三`,机械卡点见门禁 0)。
@@ -110,9 +114,6 @@ python skills/sketch-spec-to-card/scripts/parse_meaxure.py --src <导出目录>
110
114
  # 一步式:解析并直接生成 prompt.md/spec.md(省一次 build_prompt 命令,提速)
111
115
  python skills/sketch-spec-to-card/scripts/parse_meaxure.py --src <导出目录> --sample 5 --build
112
116
 
113
- # 新业务域微调意图推导:传 {关键字: 意图模板} JSON(覆盖/追加默认规则)
114
- python skills/sketch-spec-to-card/scripts/parse_meaxure.py --src <导出目录> --sample 5 --intent-map intent-map.json
115
-
116
117
  # 生成 prompt.md / spec.md(处理 manifest 中全部 generated 画板;也可由 --build 自动触发)
117
118
  python skills/sketch-spec-to-card/scripts/build_prompt.py
118
119
  python skills/sketch-spec-to-card/scripts/build_prompt.py --only "未登录"
@@ -158,7 +159,7 @@ python skills/sketch-spec-to-card/scripts/cluster_states.py --out <UI目录> --a
158
159
 
159
160
  1. 每个候选必须是一个**完整业务卡边界**:有独立容器、标题/内容主体和业务语义,不是对话气泡、单个按钮、图标、状态条或背景装饰。
160
161
  2. 一张画板的多个卡片必须分别落成 `card-1.png`、`card-2.png`;不允许把多张业务卡合成一张截图。
161
- 3. 识别不到完整卡片,或画板只是弹窗、toast、底部抽屉等交互态,输出 `trainingEligible=false` 并记录跳过原因,不进入普通卡训练。
162
+ 3. 识别不到完整卡片,或画板只是弹窗、toast、底部抽屉等交互态,输出 `trainingEligible=false` 并记录跳过原因,不进入普通卡训练。**例外(整卡单切图,2026-09-28)**:设计稿把卡片整体导成一张大切图(图层树只剩该图、卡内无文本/按钮标注)时,`detect_artboard_cards` 在常规候选 0 卡后把合格大切图兜底提升为 1 张真卡(纯几何判据:宽≥55%W、高≥12%H、纵向 10%..95%H、区域归属元素仅切图本身;混入任何其他标注不兜底)——`trainingEligible=true`,下游按图像卡(切片绑背景图)建卡。
162
163
  4. 低置信度候选宁可拒绝并进入 `rejectedCards`,不得为了提高召回把按钮或气泡当卡片。
163
164
  5. `focus-audit` 必须保留 `acceptedCards/rejectedCards/skippedNoCards` 证据,后续训练只消费通过该门的普通卡。
164
165
 
@@ -197,24 +198,26 @@ python skills/sketch-spec-to-card/scripts/cluster_states.py --out <UI目录> --a
197
198
  - **切图自包含 + 同名取最高倍率**。每个画板 `slices/` 仅含该画板引用的切图(按画板内 `slice` 层名匹配 `assets/` 文件名,剥 `@Nx` 与 `_icon` 后缀、取路径末段)。**同名多尺寸去重**:同一图标若存在 `@3x`/`@2x`/`@1x`/原始 多版本,只保留最高倍率(`@3x`>`@2x`>`@1x`>无后缀),每图标仅 1 个文件。候选排序必须先交叉验证目录语义段,再按位图格式、最高倍率和路径简洁度择优;`8、icon` 与 `8.icon` 这类目录分隔差异不能阻断匹配。零匹配时回退拷贝整个 `assets/` 池,保证不缺素材。**保留导出原名**(作为来源证据,不在本 skill 改名):语义化重命名与**跨画板内容去重**(同内容只存一份、按 sha256 判定)在下游落 `src/slices/` 时做,见 `dsl-card-generator/references/slices_convention.md §1.1 / §3.1`(lint `r59` / `r60` 兜底)。
198
199
  - **标注提取**。text 层含 `content/color(hex)/fontSize/fontFace/textAlign/lineHeight`;其余层取 `rect/fills/borders/opacity`。group 层递归展平,保留 `depth` 与 `parent`。
199
200
  - **双主题 / 预览区独立性**:本 skill 不动编辑器主题;切图按原样拷贝,颜色以标注 hex 为准。
200
- - **文本气泡误识别剔除**(`parse_meaxure.py::_is_pure_text_card`):`detect_cards` 会把 AI 应答文本气泡(纯文本气泡 / 大段应答多行文本)误识别为卡片。判定规则(纯结构/几何,不读名称/文案):①存在「大层」(rect 宽≥80%cw 且高≥50%ch 的元素 = 卡面/蒙版/top-bg 等背景装饰);②剥去所有大层与组(包装)后,剩余「真实内容」= slice + 小 symbol(图标) + 带填充小 shape(图标/按钮) + text;③若无 slice/图标/带填充小形状 且 text 段数≤2 → 文本气泡,剔除。剔除后删除对应 `card-N.png` 并对保留卡片重新 1..N 编号。无大层 → 保守保留(透明卡不杀)。真卡(空态/列表/结果卡,含图标或多段 label-value 文本)不受影响。
201
+ - **文本气泡误识别剔除**(2026-09-20 起并入「拒绝理由体系」,旧函数已删):`detect_cards` 偶把 AI 应答文本气泡识别为卡片。现由 `vision.detect_cards` 对每个候选区域逐条给出**拒绝理由**——文本气泡类 = `conversation_bubble_region`(单气泡)/ `stacked_conversation_bubbles_region`(堆叠气泡)/ `prose_paragraph_region`(段落)/ `empty_region`(空区域),见 `vision.py` 顺序否决链;画板级再由 `parse_meaxure.is_text_only_artboard` 按「所有拒绝理由都落在纯文本类集合」收口为 `text_only`(下一条)。剔除后删除对应 `card-N.png` 并对保留卡片重新 1..N 编号。**注意:旧实现 `_is_pure_text_card` / `_filter_pure_text_cards` 已于 2026-09-20 重构中删除**(被上述理由体系取代),任何仍引用它们的文档段落均为过期信息。
201
202
  - **纯文本画板过滤**(`parse_meaxure.py::is_text_only_artboard`,用户 2026-09-20):整板就是对话/问答/提示文字的画板**没有生成卡片的必要**,不该继续占产卡池与训练集。判据(`classify_artboard` 在视觉弹层判定之后、名称兜底之前调用;`focus_artboard` 复用同一入口 `detect_artboard_cards`,两处判定不漂移):①`cards` 非空 → 不是纯文本;②`focusSkipReason` 属 overlay/底部抽屉 → 归弹层类,不走这条;③板上有**卡片级大盘切图**(中段、宽≥55%W、高≥12%H 的 slice,即卡片被整体导成一张图,`vision.has_card_like_visual`)→ 保留;④其余凡「至少有一个候选被拒」且**所有拒绝理由都落在纯文本类集合**(`text_only_or_low_structure_region` / `prose_paragraph_region` / `conversation_bubble_region` / `stacked_conversation_bubbles_region` / `conversation_inputDock_region` / `conversation_keyboard_region` / `empty_region`)→ `text_only`。**白名单式判定**是关键:理由只要沾上 `single_button_or_bar_region`(读起来像卡、规则没认的窄卡)或 `repeated_control_bar_region` 就一律保留——汇率牌价这类宽扁卡靠这条保住;0 候选的普通文字页同样保守保留。落地:`status=skipped` + `trainingEligible=false` + 不产 `card-N.png`(连兜底图也不产)+ `prompt.md` 只写「不要建卡」的判定依据;`--list` / 门禁清单把它归到「已过滤」段。
202
203
  - 详细 spec.json 字段见 `references/spec-schema.md`。
203
204
 
204
205
  ## 6. 已沉淀问题 / 优化(维护记录)
206
+ - **同名画板整板覆盖(2026-09-24)**:重跑「地址管理」稿时发现 25 个画板只落 24 个目录 —— 源导出里 `11信用卡地址管理_…_失败_再次修改` 出现**两次**(idx=10 为 375×1232/129 层,idx=11 为 375×1252/130 层,`imagePath` 分别是 `…-2-11…png` 与 `…-1-11…png`,是两个不同设计而非重复导出)。`cdir = base / name` 直接用画板名 → 后跑的整板覆盖先跑的(`artboard.png` / `card-N.png` / `spec.json` / `slices/` 静默丢失),manifest 两条 entry 还都指向同一目录;下游 `generate_cards.mjs`(`uiDir/<name>/spec.json`)与选板清单同样按 name 走,两行同名用户也无法指定。修复:新增 `unique_canvas_names`,第 2 个及以后追加 `-2` / `-3` 并**同步写入 `name` 与 `slug`**(`nameOriginal` 留原始名)——下游只认 name,故零改动即正确;清单展示同用唯一名,保证「用户看到的行 = 落盘目录 = 下游定位键」三者一致。`classify_artboard` 与预览图兜底 glob 仍传原始名(后缀不参与语义判定)。**已知残留**:同名板且 `imagePath` 也缺失时,兜底 glob 仍可能取到同一张预览图(双缺失场景,已在代码注释标注)。回归:自检新增「同名画板消歧」断言(`["A_首页","A_首页","B_备用","A_首页"]` → `["A_首页","A_首页-2","B_备用","A_首页-3"]`)+ 真实稿 25 板 → 25 目录、两板元素数 129/130 各自独立。
207
+ - **`subcard` 产卡(2026-09-24)**:`bottom_sheet` 此前只写 `focusSkipReason=bottom_sheet_geometry` 而**不产 `cards`**,于是 `cluster_states` 承认它是独立逻辑卡(`pageId=card-N`、`isDialog=true`)而 spec 层给不出任何卡级数据 —— 下游只能读整图自定边界。现由 `detect_artboard_cards` 的 sheet 分支把面板几何(`vision._bottom_sheet_rect` 早已算出 rect + 顶圆角)落成 1 张卡:`cards[0]` 含 `rect` / `mask.radius` / 卡内 `elements` / `segments` / `detectedList`,并实产 `card-1.png`。**`focusSkipReason` 保持不变** —— `classify_artboard`(`:1667`)靠它判 `artboardType=subcard`,改它会连带打翻 `is_text_only_artboard`(`:1643`) / `board_verdict` / trainer 的 `is_popup_case`(`build_dataset.py:188`);该字段语义是「跳过自动候选检测」,不是「0 卡」。元素归属抽 `vision.elements_in_rect(elements, rect, min_cover)` 作**唯一口径**:普通卡走默认(中心在内 or 覆盖 >30%,与 `detect_cards` 原实现等价),抽屉卡走 `min_cover=0.7`(面板上沿会切过相邻气泡与其文字层 —— 其大头刚过沿就会被默认口径收进来;真实稿 04/05/06 实测阈值 0.65~0.90 元素集合完全一致,不敏感)。回归:自检 6 例(含 `subcard` → `cards=1`)+ 抽屉元素归属 + `focus_artboard` 端到端(card-1.png / mask.radius 实产)+ 真实稿三张实证元素归属 0 异常;trainer 不受影响(`POPUP_TYPES` 已整体跳过 subcard)。**注意全量统计会变**:原先 `subcard=82` 全部是 0 卡,重跑后每张 +1 卡。
205
208
  - **纯文本画板过滤(2026-09-20)**:用户反馈「纯文本对话的设计稿,里面都是文本,没有任何生成卡片的必要」。新增 `vision.has_card_like_visual`(卡片级大盘切图保险)+ `parse_meaxure.is_text_only_artboard`(纯文本拒绝理由白名单收口)+ `detect_artboard_cards` 统一检出入口(`focus_artboard` 与清单 `board_verdict` 同源,判定不漂移),并停掉纯文本板的兜底 `card-1.png`、给这类板单独产「不要建卡」prompt。**全量回归(24 稿 675 画板)**:`card=530 / subcard=82 / overlay_dialog=43 / text_only=20`;被过滤的 20 张全是各稿「无权限 / 知识问答 / 无返现记录 / 额度不够 / 交易超时」这类纯文本对话页;人工复核房贷 14 张、汇率 02、理财 06/25、我的账户 01 均为真卡或「对话 + 真卡」,零误伤。单测 `scripts/test_text_only_artboard.py`(6 例:纯文本对话页→text_only、对话+内嵌矢量卡→card、对话+卡片切图→card、底部抽屉→subcard、遮罩弹框→overlay_dialog、0 候选普通文字页→card)。
206
209
  - **`_is_repeated_control_bar` 误杀业务卡(2026-09-06)**:01基金_基金推荐 主卡(标题 + 3 编号选项 + 底部 3 列收益子卡)被控件条启发式误判——底部 3 个同构子卡恰好满足「3+ 横向等距重复块」全部数值条件(宽比 0.28/高比 0.32/等间距),导致主卡 0 检出、下游被迫手工补框。根因:规则只识别「横排重复」的几何形态,未区分「整卡=控件条」与「业务卡底部恰好有同构子卡行」。修复:加入**支配性守卫**——簇的纵向并集须覆盖卡高 ≥50% 才判控件条(真评分/开关组整卡只有一条横排);收益卡行只占卡高 32% → 不再误杀。回归:24 画板零崩溃,存量 UI 无其他画板曾被该规则拒绝(零回归面),主卡恢复 1 卡检出且自动裁切与人工标注框逐字节一致。
207
210
 
208
211
  > 详细回归与优化记录见 `references/regression-notes.md`。本 skill 经过「收支分析 → 信用卡查询与还款 / 转账」两稿回归,已从「单一稿写死」重构为「通用可配置」:
209
212
 
210
- - **意图推导不再写死业务域**:原 `derive_intent` 硬编码「收支分析」各分支,对其它稿会产出张冠李戴的意图(如转账未登录 → "引导登录后查看收支分析")。现改为「通用状态规则 + 可选 `--intent-map` 覆盖」,`spec.json.intent` 对任何稿都给出合理中性意图。
213
+ - **意图推导(机制已整体移除,勿复用)**:`derive_intent` / `spec.json.intent` / `--intent-map` 均已删除(曾硬编码「收支分析」分支,跨稿张冠李戴);意图现由下游 AI 读图 + 语义裁决主判(`dsl-card-generator/references/semantic_adjudication.md`)。
211
214
  - **关键标注自动排除系统 chrome**:原 `prompt.md` 把状态栏 `9:41`、对话标题、AI 输入框、`欢迎向米宝提问` 等系统 chrome 文案一并 dump 进「关键文案」,与 §0 边界自相矛盾,既增噪又拖慢生成。现由 `vision.py` 几何阈值在聚焦裁切时排除顶/底系统区与全屏背景(设计稿文本多为示意,名称/文本不参与保留/剔除判定),`build_prompt.py` 仅聚焦卡片主体区域,切图也区分主体/系统(见 §4 与 `references/boundary.json`)。
212
215
  - **抽样更具代表性**:原 `PRIORITY_KEYWORDS` 全是收支分析词,对新稿退化为取前 N。现关键字泛化为通用业务状态,并新增「业务流去重」——优先每个主屏(画板名首个 `_` 前段)各取一个代表,保证覆盖不同流程。
213
216
  - **一步式提速**:新增 `--build`,解析后直接生成 `prompt.md/spec.md`,省去单独跑 `build_prompt.py` 的一次命令/上下文切换。
214
217
  - **配置外置(去金融写死)**:参考存量卡(`alertDialog`/`alertCard`)外置为 `references/card_refs.json`,`cluster_states.py` 默认读取,`--card-refs`/`--auto-refs` 覆盖,`--auto-refs` 可从 `src/cards` 动态探测存量卡用法。
215
218
  - **维度判定去业务词(2026-08-14 强化)**:维度检测改为 100% 纯结构(指纹 Jaccard 相似度 + qualifier 语法角色),彻底删除 `KNOWN_ENUMS`/`PAIR_PATTERNS`/`FORM_PATTERNS`/`STATUS_PATTERNS`/`SCENARIO_VERBS`/`EMPTY_ERROR_MARKS`/`TRANSITION_HINT` 等金融业务词集与 `enum_map.json`,移除 `--enum-map` 参数。过渡态判定改纯结构(qualifier 命中其他 cardKey)。`classify_artboard` 改视觉信号优先(scrim/bottom-sheet)、名称仅兜底,并从 `SUBCARD_NAME_PATTERNS` 删除「选择账号/选择银行卡」业务实体名。换业务域零调整即可生效。
216
219
  - **已知限制**:AI 应答卡常被建模在 `用户问-单行备份` 组内,纯用户问话泡(非备份)才判为 chrome;若某稿把卡片主体放在非 `-备份` 的 `用户问` 组,主体文案可能被误标——此时以 `artboard.png` 截图为准(generator 多模态读图不会丢)。已在 §0 与 `regression-notes.md` 标注。
217
- - **文本气泡误识别剔除(2026-08-14)**:信用卡稿回归发现 `detect_cards` 把 AI 应答文本气泡(含纯文本气泡「请选择要查询...」与大段应答气泡「好的,为您查询信用卡(3568)账单...」)误识别为卡片。新增 `_is_pure_text_card`(见 §5):剥去大背景层与组后若仅剩 ≤2 段文本且无图标/切图 → 剔除并重编号。v1 用「无填充色」失败(气泡白底 `#FFFFFF` 与真卡卡面同色),v2 改为「剥去最大填充背景后剩仅文本」只覆盖纯文本气泡,v3 终版改为「剥去所有大层(含 top-bg/蒙版装饰) 后剩仅少量文本」同时覆盖纯文本 + 大段应答气泡。信用卡稿 41 画板剔除 9 张应答气泡,真卡(空态/列表/结果卡)全保留,逻辑卡仍 6 张。
220
+ - **文本气泡误识别剔除(2026-08-14 提出,2026-09-20 重构收口)**:曾以 `_is_pure_text_card` 启发式剔除误识别的应答气泡(信用卡稿 41 画板剔 9 张,真卡零误伤);该函数已删,判定并入 §5「拒绝理由体系 + `is_text_only_artboard`」,现行机制以 §5 为准。
218
221
  - **业务硬编码彻查(2026-08-15)**:按 `禁止业务性硬编码` 铁律做全量 grep 审计(`转账|还款|收款|银行卡|借记卡|信用卡|转出|余额|账单|payee|outAccount|cardNo|balance`)。结论:**本 skill 合规,无业务性硬编码进入活跃逻辑**——业务词仅出现在文档/注释/可覆盖配置三类:
219
222
  - `parse_meaxure.py` 弹层识别纯几何+视觉信号(scrim/bottom-sheet),名称仅兜底且 `DIALOG/SUBCARD_NAME_PATTERNS` 仅含通用 UI 容器类型词(弹框/弹窗/子卡/浮层卡/弹层卡…),并已删除「选择账号/银行卡选择」等业务实体名。
220
223
  - `cluster_states.py` 维度/状态识别 100% 纯结构(指纹 Jaccard 相似度 + qualifier 语法角色),无任何业务词集。
@@ -308,7 +311,7 @@ python skills/sketch-spec-to-card/scripts/cluster_states.py --out <UI目录> --a
308
311
 
309
312
  - **弹窗/对话框**(alertDialog):覆盖在卡片上的浮层,有半透明遮罩 + 居中弹窗
310
313
  - **底部弹出抽屉**(bottom-sheet):从底部滑出的交互层
311
- - **聊天气泡**:AI 应答的纯文本气泡(已有 `_is_pure_text_card` 识别,但多模态验证可进一步确认)
314
+ - **聊天气泡**:AI 应答的纯文本气泡(已由 `detect_cards` 的 `conversation_bubble_region` / `stacked_conversation_bubbles_region` 拒绝理由 + `is_text_only_artboard` 收口,但多模态验证可进一步确认)
312
315
  - **纯按钮区域**:单独的一个按钮不应作为独立卡片
313
316
 
314
317
  判定信号(不看业务词,纯结构/视觉):半透明遮罩层存在、底部圆角向上无延伸、无卡片外壳 shape、面积占比 <30% 画板。
@@ -333,3 +336,17 @@ python skills/sketch-spec-to-card/scripts/cluster_states.py --out <UI目录> --a
333
336
  - **矢量 logo 组按裁切处理**:设计稿里品牌 logo / 图标常是「纯矢量编组」——MeaXure 不会给它导出切图,标注里只有一个 `group` 节点。判据(`parse_meaxure.py::is_vector_logo_group` + group 分支):紧凑媒体尺寸(宽高各 12–220pt 且面积 ≤ 卡面积 20%)、无同名导出切图、矩形内**无文本叠加**、组内含 ≥1 个 shape 子件 → 记 `annotationDefect(missing-slice)` 并从原画板按标注矩形裁切成 `cropSlice`,下游 `spec_to_schema_v3.mjs` 把 `annotationDefect.cropSlice` 提权进 slices 池由 Image 承载。不裁切就整块丢失(组件分 + 像素分双掉)。
334
337
  - **自动命名图层只认精确同名匹配**:`编组 N` / `组 N` / `矩形 N` / `椭圆 N` / `直线 N` / `多边形 N` / `Group N` / `Rectangle N` / `Shape|Path|Oval|Line|Star|Polygon N` 这类 Sketch 自动命名(`AUTO_LAYER_NAME_RE`)在切图池里高度重名,`collect_slice_files` 的「去尾数字宽松匹配」会把 `编组 2` 错配到 `编组 4.png`(拿到别人的像素)。规则:图层名命中该正则时**跳过宽松匹配**,只用精确同名文件;宁可判为缺素材走裁切,也不要静默换图。
335
338
  - 两条都在 `spec.json` 留证据(`annotationDefects[].resolution=artboard-crop` / 缺素材记录),便于训练侧归因是上游解析还是下游生成。
339
+
340
+ ---
341
+ ### popup/subcard artboards are not ordinary whole-card training(r002 训练回灌)
342
+ > lesson: `LESSON-20260824-003` status: `promoted`
343
+
344
+ sketch-spec-to-card 在 manifest 中输出 trainingEligible=false;普通卡训练集只消费普通卡,弹框/子卡走专项交互训练。
345
+
346
+
347
+ ---
348
+ ### card focus needs visual, annotation and agent semantic cross(r039n 训练回灌)
349
+ > lesson: `LESSON-20260826-047` status: `promoted`
350
+
351
+ 卡片候选由截图视觉、标注几何和 Agent 语义三方交叉验证;完整业务容器才可接受,对话气泡、单按钮、弹窗、toast 和底部抽屉必须拒绝或跳过。规则只使用通用结构信号,禁止业务词硬编码。
352
+
@@ -24,7 +24,7 @@
24
24
  由 `vision.detect_cards()` 视觉检测得到的 1..N 张卡片区域。每项字段:
25
25
  | 字段 | 类型 | 说明 |
26
26
  |------|------|------|
27
- | `index` | int | 卡片序号(1 起)。剔除纯文本误识别后会重新编号(见 `_filter_pure_text_cards`) |
27
+ | `index` | int | 卡片序号(1 起)。剔除纯文本误识别后重新编号(由 `detect_cards` 拒绝理由体系 + `is_text_only_artboard` 收口) |
28
28
  | `rect` | {x,y,width,height} | 相对画板的卡片区域几何(设计坐标) |
29
29
  | `image` | string | 该卡片聚焦裁切图文件名(如 `card-1.png`,@2x);裁切失败可能缺失 |
30
30
  | `cardFill` | string\|null | 卡片容器自身纯色填充(`#RRGGBB`),供下游生成卡片 Root 背景;**不是画布背景**。背景非均匀/非固定时本字段仍来自卡片容器 fill,绝不从截图像素反推 |
@@ -32,7 +32,7 @@
32
32
  | `elements` | array | 归属该卡片的图层(同 elements[] 结构) |
33
33
  | `flexLayout` | object\|undefined | 容器 flex 布局推断(仅当子元素 ≥2):`{direction, justifyContent, alignItems, childCount}` |
34
34
 
35
- > **纯文本气泡误识别剔除**:`detect_cards` 偶把 AI 应答文本气泡识别为卡片。`_is_pure_text_card` 判定(纯结构/几何):剥去所有大层(宽≥80%cw 且高≥50%ch)与 group 包装后,若剩余仅 text 段且 ≤2 段、无 slice/带填充小shape/小symbol → 视为文本气泡剔除并删除 PNG、重新 1..N 编号。真卡(空态/列表/结果卡,含图标或多段 label-value 文本)不受影响。
35
+ > **纯文本气泡误识别剔除**(2026-09-20 起并入「拒绝理由体系」,旧函数已删):`detect_cards` 偶把 AI 应答文本气泡识别为卡片。现由 `vision.detect_cards` 逐候选给出拒绝理由(文本气泡类 = `conversation_bubble_region` / `stacked_conversation_bubbles_region` / `prose_paragraph_region` / `empty_region`),画板级再由 `parse_meaxure.is_text_only_artboard` 按「所有拒绝理由都落在纯文本类集合」收口为 `text_only`。剔除后删除对应 PNG 并重新 1..N 编号。真卡(空态/列表/结果卡,含图标或多段 label-value 文本)不受影响。**旧实现 `_is_pure_text_card` / `_filter_pure_text_cards` 已删除**,引用它们的文档即过期信息。
36
36
 
37
37
  ## elements[]
38
38
  全画板展平图层(`vision._flatten_raw` + `serialize_element`),含系统区/背景(不在 `cards[]` 内的元素)。每项字段:
@@ -99,5 +99,5 @@ MeaXure 的 `color` 对象含 `rgb/hsl/color-hex/argb-hex/rgba-hex/css-rgba/css-
99
99
 
100
100
  ## 历史变更(与本文档相关)
101
101
  - **2026-08-14 重构**:删除 `layers[]` / `chrome` 字段 / `summary.chromeCount` / `summary.cardBodyCount` / `CHROME_NAME_PATTERNS` / `CHROME_CONTAINER_PATTERNS` 名称标记机制;系统 chrome 改由 `vision.py` 几何阈值在卡片检测阶段直接剔除(不出现在 `cards[]` 内)。新增 `elements[]` 平铺结构、`cards[]` 区域结构、`styleSummary` 聚合样式。
102
- - **意图推导下线**:旧版 `derive_intent` / `DEFAULT_INTENT_RULES` / `spec.json.intent` 字段已删除;意图推导改由 `build_prompt.py` 在生成 prompt 时基于画板名 + 可选 `--intent-map` 在 prompt 文本层产出,不进 spec.json 结构。
102
+ - **意图推导下线**:旧版 `derive_intent` / `DEFAULT_INTENT_RULES` / `spec.json.intent` 字段已删除;现由 `build_prompt._detect_spec_intents` 从 spec 结构信号识别布局意图(`single_column_flow` / `list_with_sections` / `amount_header` / `form_rows` 等)并写入 prompt 文本层,不进 spec.json 结构。**无 `--intent-map` 覆盖入口** —— 该参数从未在 `build_prompt.py` / `parse_meaxure.py` 的 argparse 中实现过(argparse 实为 `--out / --only / --all`)。
103
103
  - **2026-08-15**:补齐文档与代码同步(前版本描述了已不存在的 chrome 标记字段)。
@@ -420,14 +420,6 @@ def build_handcrafted_hints(spec):
420
420
 
421
421
 
422
422
  # ---------- 列表检测(视觉:卡片内重复行结构) ----------
423
- def _rect_center_in(a, b):
424
- """a 的中心点是否落在 b 矩形内。"""
425
- ax, ay, aw, ah = a
426
- bx, by, bw, bh = b
427
- cx, cy = ax + aw / 2.0, ay + ah / 2.0
428
- return bx <= cx <= bx + bw and by <= cy <= by + bh
429
-
430
-
431
423
  def _axis_overlap_ratio(a, b, pos_i, main_i):
432
424
  """a 与 b 在主轴投影上的重叠占较短主尺寸的比例(0..1)。"""
433
425
  a0, a1 = a[pos_i], a[pos_i] + a[main_i]
@@ -60,10 +60,22 @@ _AUTH_HINT = re.compile(r"(登录|授权|登入)", re.I)
60
60
 
61
61
 
62
62
  def _resolve_src_cards(explicit):
63
+ """定位 --auto-refs 的扫描目录(宿主工程根/src/cards)。
64
+
65
+ 锚点契约与下游 `dsl-card-generator/scripts/lib/paths.py` 一致:
66
+ 显式 --src-cards > 环境变量 DSL_CARD_PROJECT_ROOT > 按脚本位置回溯。
67
+
68
+ 回溯必须退**三级**:本文件位于 `<repo>/skills/sketch-spec-to-card/scripts/`。
69
+ 历史 bug:只退两级 → 得到 `<repo>/skills`,拼出 `skills/src/cards` 恒不存在
70
+ → 返回 None → `load_card_refs` 静默回退写死的金融卡参考
71
+ (`card_refs.BUILTIN_CARD_REFS`)—— 整条「跨业务域自动探测参考卡」从未生效。
72
+ """
63
73
  if explicit:
64
74
  return explicit
65
- repo_root = os.path.dirname(os.path.dirname(SCRIPT_DIR))
66
- cand = os.path.join(repo_root, "src", "cards")
75
+ root = os.environ.get("DSL_CARD_PROJECT_ROOT")
76
+ if not root:
77
+ root = os.path.dirname(os.path.dirname(os.path.dirname(SCRIPT_DIR)))
78
+ cand = os.path.join(root, "src", "cards")
67
79
  return cand if os.path.isdir(cand) else None
68
80
 
69
81
 
@@ -162,13 +174,6 @@ def diff_fingerprint(base, other):
162
174
  # ----------------------------------------------------------------------------
163
175
  # 4. 维度提取(tab / conditional / form / sequential)—— 纯结构,无业务词
164
176
  # ----------------------------------------------------------------------------
165
- def _fp_sim(a, b):
166
- """两状态指纹平均相似度(文本 Jaccard + 块 Jaccard)/2。"""
167
- jt = jaccard(set(a["fp"]["texts"]), set(b["fp"]["texts"]))
168
- jb = jaccard(set(a["fp"]["blocks"]), set(b["fp"]["blocks"]))
169
- return (jt + jb) / 2
170
-
171
-
172
177
  def is_empty_or_error(qs, fp=None):
173
178
  """空/错误态判定:qualifier 含否定语法前缀 或 指纹内容极稀疏。"""
174
179
  joined = "_".join(qs)
@@ -345,22 +350,6 @@ def detect_forms(cluster_states):
345
350
  return out
346
351
 
347
352
 
348
- # 兼容旧调用名(build_cluster 仍引用)
349
- def detect_enums(cluster_states):
350
- return [d for d in detect_positional_tabs(cluster_states) if d["type"] == "tab"]
351
-
352
-
353
- def detect_pairs(cluster_states):
354
- return [d for d in detect_positional_tabs(cluster_states) if d["type"] == "conditional"]
355
-
356
-
357
- def detect_sequential(cluster_states):
358
- seqs = [d for d in detect_positional_tabs(cluster_states) if d["type"] == "sequential"]
359
- # 保持旧输出结构(phases + 单变量)
360
- return [{"type": "sequential", "phases": s["values"], "boundVar": s["boundVar"],
361
- "note": s.get("note", "")} for s in seqs]
362
-
363
-
364
353
  # ----------------------------------------------------------------------------
365
354
  # 5. 主流程:聚类 + 产物聚合
366
355
  # ----------------------------------------------------------------------------