cardbuddy 0.11.0 → 0.12.1

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 (313) hide show
  1. package/README.md +46 -5
  2. package/dist/cli.js +51 -1
  3. package/dist/config.js +51 -16
  4. package/dist/core.js +2 -2
  5. package/dist/init.js +425 -0
  6. package/dist/preview-editor/assets/index-CHuGGIR3.js +276 -0
  7. package/dist/preview-editor/assets/{index-B4VZgNSK.css → index-CQScMhyg.css} +1 -1
  8. package/dist/preview-editor/index.html +2 -2
  9. package/dist/standalone.js +8 -0
  10. package/dist/vendored/mcp/client.mjs +537 -0
  11. package/dist/vendored/mcp/tools.mjs +268 -0
  12. package/dist/vendored/preview/assets/default-image.png +0 -0
  13. package/dist/{server-core → vendored/server/core}/ai-chat.js +82 -38
  14. package/dist/{server-core → vendored/server/core}/browser.js +1 -1
  15. package/dist/{server-core → vendored/server/core}/cardSave.js +8 -3
  16. package/dist/{server-core → vendored/server/core}/cardSync.js +6 -14
  17. package/dist/{server-core → vendored/server/core}/cardValidate.js +11 -8
  18. package/dist/{server-core → vendored/server/core}/index.js +5 -3
  19. package/dist/vendored/server/core/skillPaths.js +124 -0
  20. package/dist/{server-core → vendored/server/core}/sliceUpload.js +5 -8
  21. package/dist/vendored/skills/README.md +93 -0
  22. package/dist/vendored/skills/card-doctor/SKILL.md +52 -0
  23. package/dist/vendored/skills/card-skill-trainer/SKILL.md +312 -0
  24. package/dist/vendored/skills/card-skill-trainer/baselines/v3-r038n.json +43 -0
  25. package/dist/vendored/skills/card-skill-trainer/baselines/v3-r039n.json +47 -0
  26. package/dist/vendored/skills/card-skill-trainer/baselines/v3-r050n.json +48 -0
  27. package/dist/vendored/skills/card-skill-trainer/scripts/build_dataset.py +472 -0
  28. package/dist/vendored/skills/card-skill-trainer/scripts/build_sample.mjs +162 -0
  29. package/dist/vendored/skills/card-skill-trainer/scripts/diagnose_case.mjs +241 -0
  30. package/dist/vendored/skills/card-skill-trainer/scripts/lib/scoring.mjs +525 -0
  31. package/dist/vendored/skills/card-skill-trainer/scripts/round_diff.mjs +133 -0
  32. package/dist/vendored/skills/card-skill-trainer/scripts/run_round.mjs +1043 -0
  33. package/dist/vendored/skills/card-skill-trainer/scripts/score_round.mjs +195 -0
  34. package/dist/vendored/skills/card-skill-trainer/scripts/test_missing_slice.py +122 -0
  35. package/dist/vendored/skills/dsl-card-ai/SKILL.md +191 -0
  36. package/dist/vendored/skills/dsl-card-generator/SKILL.md +480 -0
  37. package/dist/vendored/skills/dsl-card-generator/config/render-contract.json +11 -0
  38. package/dist/vendored/skills/dsl-card-generator/references/amount_formatting.md +138 -0
  39. package/dist/vendored/skills/dsl-card-generator/references/card_index.json +1597 -0
  40. package/dist/vendored/skills/dsl-card-generator/references/card_templates.json +384 -0
  41. package/dist/vendored/skills/dsl-card-generator/references/card_to_summary.md +56 -0
  42. package/dist/vendored/skills/dsl-card-generator/references/component_rules.md +76 -0
  43. package/dist/vendored/skills/dsl-card-generator/references/component_specs.md +393 -0
  44. package/dist/vendored/skills/dsl-card-generator/references/dsl_structure.md +208 -0
  45. package/dist/vendored/skills/dsl-card-generator/references/event_patterns.md +287 -0
  46. package/dist/vendored/skills/dsl-card-generator/references/expression_engine.md +121 -0
  47. package/dist/vendored/skills/dsl-card-generator/references/field_name_dict.json +34 -0
  48. package/dist/vendored/skills/dsl-card-generator/references/field_naming.md +101 -0
  49. package/dist/vendored/skills/dsl-card-generator/references/generation_pitfalls.md +928 -0
  50. package/dist/vendored/skills/dsl-card-generator/references/handcrafted/README.md +69 -0
  51. package/dist/vendored/skills/dsl-card-generator/references/handcrafted/examples_index.json +2967 -0
  52. package/dist/vendored/skills/dsl-card-generator/references/handcrafted/patterns.json +2835 -0
  53. package/dist/vendored/skills/dsl-card-generator/references/handcrafted/recipes_v2.json +648 -0
  54. package/dist/vendored/skills/dsl-card-generator/references/handcrafted/recipes_v2_schema.md +295 -0
  55. package/dist/vendored/skills/dsl-card-generator/references/image_diff.md +48 -0
  56. package/dist/vendored/skills/dsl-card-generator/references/image_to_card.md +129 -0
  57. package/dist/vendored/skills/dsl-card-generator/references/ir-format.md +212 -0
  58. package/dist/vendored/skills/dsl-card-generator/references/message-center-pattern.md +149 -0
  59. package/dist/vendored/skills/dsl-card-generator/references/platform_jsapi.md +196 -0
  60. package/dist/vendored/skills/dsl-card-generator/references/previewer_contract.md +54 -0
  61. package/dist/vendored/skills/dsl-card-generator/references/quickref.md +197 -0
  62. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/absolute-badge.json +84 -0
  63. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/accordion-group-toggle.json +18 -0
  64. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/alertCard-pair.json +12 -0
  65. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/alertDialog-call.json +12 -0
  66. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/canvas-countdown.json +15 -0
  67. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/canvas-donut.json +15 -0
  68. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/canvas-gauge-score.json +11 -0
  69. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/canvas-radar.json +10 -0
  70. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/canvas-title-head.json +13 -0
  71. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/globalSet.json +12 -0
  72. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/label-col-modes.json +21 -0
  73. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/list-expand-collapse.json +17 -0
  74. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/money-format.json +11 -0
  75. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/opacity-switch.json +130 -0
  76. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/progress-bar.json +25 -0
  77. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/tab-billMode.json +15 -0
  78. package/dist/vendored/skills/dsl-card-generator/references/recipe_snippets/title-underline-overlay.json +21 -0
  79. package/dist/vendored/skills/dsl-card-generator/references/recipes.md +797 -0
  80. package/dist/vendored/skills/dsl-card-generator/references/rules.md +235 -0
  81. package/dist/vendored/skills/dsl-card-generator/references/slices_convention.md +177 -0
  82. package/dist/vendored/skills/dsl-card-generator/references/spec_to_schema_patterns.md +609 -0
  83. package/dist/vendored/skills/dsl-card-generator/references/ui_fidelity_rules.md +131 -0
  84. package/dist/vendored/skills/dsl-card-generator/scripts/add_component.mjs +118 -0
  85. package/dist/vendored/skills/dsl-card-generator/scripts/analyze_component_usage.mjs +153 -0
  86. package/dist/vendored/skills/dsl-card-generator/scripts/apply_opacity_pattern.mjs +343 -0
  87. package/dist/vendored/skills/dsl-card-generator/scripts/build_card_index.mjs +108 -0
  88. package/dist/vendored/skills/dsl-card-generator/scripts/build_card_templates.mjs +190 -0
  89. package/dist/vendored/skills/dsl-card-generator/scripts/check_fidelity.mjs +257 -0
  90. package/dist/vendored/skills/dsl-card-generator/scripts/check_magic_values.mjs +79 -0
  91. package/dist/vendored/skills/dsl-card-generator/scripts/crop_slices.mjs +98 -0
  92. package/dist/vendored/skills/dsl-card-generator/scripts/describe_card.mjs +265 -0
  93. package/dist/vendored/skills/dsl-card-generator/scripts/diff_bands.mjs +257 -0
  94. package/dist/vendored/skills/dsl-card-generator/scripts/diff_card.mjs +316 -0
  95. package/dist/vendored/skills/dsl-card-generator/scripts/expand_ir.mjs +873 -0
  96. package/dist/vendored/skills/dsl-card-generator/scripts/extract_handcrafted.py +1199 -0
  97. package/dist/vendored/skills/dsl-card-generator/scripts/extract_subtree.mjs +191 -0
  98. package/dist/vendored/skills/dsl-card-generator/scripts/generate_cards.mjs +389 -0
  99. package/dist/vendored/skills/dsl-card-generator/scripts/inventory_schemas.py +160 -0
  100. package/dist/vendored/skills/dsl-card-generator/scripts/iterate.mjs +700 -0
  101. package/dist/vendored/skills/dsl-card-generator/scripts/lib/design_image.mjs +56 -0
  102. package/dist/vendored/skills/dsl-card-generator/scripts/lib/design_sample.mjs +328 -0
  103. package/dist/vendored/skills/dsl-card-generator/scripts/lib/layout-tokens.mjs +79 -0
  104. package/dist/vendored/skills/dsl-card-generator/scripts/lib/paths.mjs +103 -0
  105. package/dist/vendored/skills/dsl-card-generator/scripts/lib/scaffold.mjs +575 -0
  106. package/dist/vendored/skills/dsl-card-generator/scripts/lib/slicePath.mjs +81 -0
  107. package/dist/vendored/skills/dsl-card-generator/scripts/lib/slice_dedupe.mjs +147 -0
  108. package/dist/vendored/skills/dsl-card-generator/scripts/lint_autofix.mjs +363 -0
  109. package/dist/vendored/skills/dsl-card-generator/scripts/lint_card.mjs +1399 -0
  110. package/dist/vendored/skills/dsl-card-generator/scripts/preflight.mjs +249 -0
  111. package/dist/vendored/skills/dsl-card-generator/scripts/register_card_template.mjs +208 -0
  112. package/dist/vendored/skills/dsl-card-generator/scripts/render_baseline.mjs +231 -0
  113. package/dist/vendored/skills/dsl-card-generator/scripts/render_card.mjs +801 -0
  114. package/dist/vendored/skills/dsl-card-generator/scripts/render_diff.mjs +239 -0
  115. package/dist/vendored/skills/dsl-card-generator/scripts/resolve_card_template.mjs +73 -0
  116. package/dist/vendored/skills/dsl-card-generator/scripts/route_input.mjs +447 -0
  117. package/dist/vendored/skills/dsl-card-generator/scripts/scaffold_card.mjs +81 -0
  118. package/dist/vendored/skills/dsl-card-generator/scripts/slices_normalize.mjs +316 -0
  119. package/dist/vendored/skills/dsl-card-generator/scripts/spec_audit.mjs +462 -0
  120. package/dist/vendored/skills/dsl-card-generator/scripts/spec_to_schema_v3.mjs +7735 -0
  121. package/dist/vendored/skills/dsl-card-generator/scripts/spec_tree.mjs +355 -0
  122. package/dist/vendored/skills/dsl-card-generator/scripts/validate_all_schemas.py +71 -0
  123. package/dist/vendored/skills/dsl-card-generator/vendor/preview/assets/default-image-wzZYQ86K.png +0 -0
  124. package/dist/vendored/skills/dsl-card-generator/vendor/preview/assets/standalone-C9k-07y7.css +1 -0
  125. package/dist/vendored/skills/dsl-card-generator/vendor/preview/assets/standalone-oFRM4f4V.js +55 -0
  126. package/dist/vendored/skills/dsl-card-generator/vendor/preview/assets/svg-symbols-B2exBrAr.svg +118 -0
  127. package/dist/vendored/skills/dsl-card-generator/vendor/preview/meta/component-meta.json +2714 -0
  128. package/dist/vendored/skills/dsl-card-generator/vendor/preview/meta/directive-meta.json +40 -0
  129. package/dist/vendored/skills/dsl-card-generator/vendor/preview/meta/style-meta.json +1086 -0
  130. package/dist/vendored/{standalone.html → skills/dsl-card-generator/vendor/preview/standalone.html} +2 -1
  131. package/dist/vendored/skills/finmall-card-sync/SKILL.md +262 -0
  132. package/dist/vendored/skills/finmall-session-navigator/SKILL.md +169 -0
  133. package/dist/vendored/skills/finmall-session-navigator/scripts/finmall_login.mjs +882 -0
  134. package/dist/vendored/skills/finmall-session-navigator/scripts/package-lock.json +59 -0
  135. package/dist/vendored/skills/finmall-session-navigator/scripts/package.json +10 -0
  136. package/dist/vendored/skills/finmall-session-navigator/scripts/session-manager.mjs +96 -0
  137. package/dist/vendored/skills/shared/README.md +55 -0
  138. package/dist/vendored/skills/shared/auth-model.md +79 -0
  139. package/dist/vendored/skills/sketch-spec-to-card/SKILL.md +329 -0
  140. package/dist/vendored/skills/sketch-spec-to-card/references/boundary.json +14 -0
  141. package/dist/vendored/skills/sketch-spec-to-card/references/card_refs.json +13 -0
  142. package/dist/vendored/skills/sketch-spec-to-card/references/spec-schema.md +103 -0
  143. package/dist/vendored/skills/sketch-spec-to-card/scripts/build_prompt.py +797 -0
  144. package/dist/vendored/skills/sketch-spec-to-card/scripts/card_refs.py +94 -0
  145. package/dist/vendored/skills/sketch-spec-to-card/scripts/cluster_states.py +706 -0
  146. package/dist/vendored/skills/sketch-spec-to-card/scripts/parse_meaxure.py +1781 -0
  147. package/dist/vendored/skills/sketch-spec-to-card/scripts/png_utils.py +318 -0
  148. package/dist/vendored/skills/sketch-spec-to-card/scripts/vision.py +1118 -0
  149. package/dist/vendored/templates/helloCard/data.json +10 -0
  150. package/dist/vendored/templates/helloCard/schema.json +238 -0
  151. package/dist/vendored/tools/link-skills.mjs +485 -0
  152. package/package.json +2 -1
  153. package/dist/preview-editor/assets/index-jl4YJzKv.js +0 -180
  154. package/dist/vendored/App.vue +0 -2858
  155. package/dist/vendored/ansi.js +0 -185
  156. package/dist/vendored/assets/apple-touch-icon.png +0 -0
  157. package/dist/vendored/assets/default-image.png +0 -0
  158. package/dist/vendored/assets/favicon-16.png +0 -0
  159. package/dist/vendored/assets/favicon-32.png +0 -0
  160. package/dist/vendored/assets/site-icon.png +0 -0
  161. package/dist/vendored/assets/svgIcons/icons.svg +0 -87
  162. package/dist/vendored/assets/svgIcons/index.js +0 -39
  163. package/dist/vendored/components/AiSettings.vue +0 -392
  164. package/dist/vendored/components/AlertCardInstance.vue +0 -58
  165. package/dist/vendored/components/AlertCardLayer.vue +0 -59
  166. package/dist/vendored/components/ApiCallPanel.vue +0 -127
  167. package/dist/vendored/components/ApiPayloadTree.vue +0 -201
  168. package/dist/vendored/components/AppToast.vue +0 -37
  169. package/dist/vendored/components/CardGallery.vue +0 -291
  170. package/dist/vendored/components/CardPreview.vue +0 -72
  171. package/dist/vendored/components/CardSelect.vue +0 -206
  172. package/dist/vendored/components/ChatComposer.vue +0 -413
  173. package/dist/vendored/components/ChatMessage.vue +0 -383
  174. package/dist/vendored/components/ChatPanel.vue +0 -937
  175. package/dist/vendored/components/ComponentPalette.vue +0 -301
  176. package/dist/vendored/components/ConfirmDialog.vue +0 -54
  177. package/dist/vendored/components/DatePickerOverlay.vue +0 -345
  178. package/dist/vendored/components/DebugPanel.vue +0 -1734
  179. package/dist/vendored/components/DeviceOverlay.vue +0 -70
  180. package/dist/vendored/components/Dropdown.vue +0 -193
  181. package/dist/vendored/components/EventEditor.vue +0 -273
  182. package/dist/vendored/components/HoverGuides.vue +0 -122
  183. package/dist/vendored/components/JsonTree.vue +0 -547
  184. package/dist/vendored/components/LogValue.vue +0 -52
  185. package/dist/vendored/components/MarkdownBody.vue +0 -64
  186. package/dist/vendored/components/NewCardDialog.vue +0 -132
  187. package/dist/vendored/components/NodeInspector.vue +0 -295
  188. package/dist/vendored/components/NumberStepper.vue +0 -125
  189. package/dist/vendored/components/PickerOverlay.vue +0 -131
  190. package/dist/vendored/components/PropControl.vue +0 -245
  191. package/dist/vendored/components/PropTree.vue +0 -128
  192. package/dist/vendored/components/RemotePreview.vue +0 -173
  193. package/dist/vendored/components/SelectionOverlay.vue +0 -105
  194. package/dist/vendored/components/StructureTree.vue +0 -1002
  195. package/dist/vendored/components/Switch.vue +0 -38
  196. package/dist/vendored/components/setters/SetBgPosition.vue +0 -64
  197. package/dist/vendored/components/setters/SetBgSize.vue +0 -90
  198. package/dist/vendored/components/setters/SetCode.vue +0 -198
  199. package/dist/vendored/components/setters/SetColor.vue +0 -244
  200. package/dist/vendored/components/setters/SetCustomSelect.vue +0 -58
  201. package/dist/vendored/components/setters/SetExpr.vue +0 -107
  202. package/dist/vendored/components/setters/SetGradient.vue +0 -125
  203. package/dist/vendored/components/setters/SetGrid9.vue +0 -68
  204. package/dist/vendored/components/setters/SetIconSelect.vue +0 -67
  205. package/dist/vendored/components/setters/SetIfForm.vue +0 -61
  206. package/dist/vendored/components/setters/SetImage.vue +0 -43
  207. package/dist/vendored/components/setters/SetList.vue +0 -139
  208. package/dist/vendored/components/setters/SetNumber.vue +0 -118
  209. package/dist/vendored/components/setters/SetNumberStyle.vue +0 -113
  210. package/dist/vendored/components/setters/SetPadding.vue +0 -77
  211. package/dist/vendored/components/setters/SetSegment.vue +0 -160
  212. package/dist/vendored/components/setters/SetSelect.vue +0 -51
  213. package/dist/vendored/components/setters/SetSwitch.vue +0 -49
  214. package/dist/vendored/components/setters/SetText.vue +0 -52
  215. package/dist/vendored/components/setters/props.js +0 -23
  216. package/dist/vendored/fidelity/baseline-messageOverview.json +0 -87
  217. package/dist/vendored/fidelity/calibration.json +0 -29
  218. package/dist/vendored/fidelity/fidelity-messageOverview-after.html +0 -114
  219. package/dist/vendored/fidelity/fidelity-messageOverview-after.json +0 -272
  220. package/dist/vendored/fidelity/fidelity-messageOverview.html +0 -185
  221. package/dist/vendored/fidelity/fidelity-messageOverview.json +0 -336
  222. package/dist/vendored/fidelity/fidelity-messageOverview_v2.html +0 -262
  223. package/dist/vendored/fidelity/fidelity-messageOverview_v2.json +0 -502
  224. package/dist/vendored/fidelity/fidelity-messageOverview_v3.html +0 -201
  225. package/dist/vendored/fidelity/fidelity-messageOverview_v3.json +0 -417
  226. package/dist/vendored/fidelity/fidelity-messageOverview_visual.html +0 -125
  227. package/dist/vendored/fidelity/fidelity-messageOverview_visual.json +0 -338
  228. package/dist/vendored/index.html +0 -16
  229. package/dist/vendored/main.js +0 -37
  230. package/dist/vendored/runtime/ai-api.js +0 -165
  231. package/dist/vendored/runtime/alert-card.js +0 -125
  232. package/dist/vendored/runtime/app-toast.js +0 -33
  233. package/dist/vendored/runtime/clipboard-node.js +0 -78
  234. package/dist/vendored/runtime/clipboard.js +0 -29
  235. package/dist/vendored/runtime/event-model.js +0 -300
  236. package/dist/vendored/runtime/hoverGuide.js +0 -31
  237. package/dist/vendored/runtime/jsapi-mock.js +0 -256
  238. package/dist/vendored/runtime/markdown.js +0 -140
  239. package/dist/vendored/runtime/node-model.js +0 -217
  240. package/dist/vendored/skills/.manifest.json +0 -1101
  241. package/dist/vendored/standalone-main.js +0 -36
  242. package/dist/vendored/styles/ai-chat.css +0 -1850
  243. package/dist/vendored/styles/app.css +0 -3648
  244. package/dist/vendored/styles/card-gallery.css +0 -285
  245. package/dist/vendored/styles/card-select.css +0 -288
  246. package/dist/vendored/styles/components.css +0 -383
  247. package/dist/vendored/styles/dropdown.css +0 -324
  248. package/dist/vendored/styles/json-tree.css +0 -308
  249. package/dist/vendored/styles/node-inspector.css +0 -800
  250. package/dist/vendored/styles/setters.css +0 -1050
  251. package/dist/vendored/styles/standalone.css +0 -27
  252. package/dist/vendored/styles/structure-tree.css +0 -460
  253. /package/dist/vendored/{api.js → preview/api.js} +0 -0
  254. /package/dist/vendored/{assets → preview/assets}/svg-symbols.svg +0 -0
  255. /package/dist/vendored/{components → preview/components}/AbsoluteLayout.vue +0 -0
  256. /package/dist/vendored/{components → preview/components}/Button.vue +0 -0
  257. /package/dist/vendored/{components → preview/components}/Canvas.vue +0 -0
  258. /package/dist/vendored/{components → preview/components}/CheckGroup.vue +0 -0
  259. /package/dist/vendored/{components → preview/components}/Column.vue +0 -0
  260. /package/dist/vendored/{components → preview/components}/CustomPlaceholder.vue +0 -0
  261. /package/dist/vendored/{components → preview/components}/Divider.vue +0 -0
  262. /package/dist/vendored/{components → preview/components}/GridLayout.vue +0 -0
  263. /package/dist/vendored/{components → preview/components}/Icon.vue +0 -0
  264. /package/dist/vendored/{components → preview/components}/Image.vue +0 -0
  265. /package/dist/vendored/{components → preview/components}/Input.vue +0 -0
  266. /package/dist/vendored/{components → preview/components}/ListLayout.vue +0 -0
  267. /package/dist/vendored/{components → preview/components}/Map.vue +0 -0
  268. /package/dist/vendored/{components → preview/components}/MultiColumn.vue +0 -0
  269. /package/dist/vendored/{components → preview/components}/MultiText.vue +0 -0
  270. /package/dist/vendored/{components → preview/components}/ProgressSlider.vue +0 -0
  271. /package/dist/vendored/{components → preview/components}/RadioButton.vue +0 -0
  272. /package/dist/vendored/{components → preview/components}/RenderTree.vue +0 -0
  273. /package/dist/vendored/{components → preview/components}/Root.vue +0 -0
  274. /package/dist/vendored/{components → preview/components}/Row.vue +0 -0
  275. /package/dist/vendored/{components → preview/components}/SvgCode.vue +0 -0
  276. /package/dist/vendored/{components → preview/components}/SvgSymbols.vue +0 -0
  277. /package/dist/vendored/{components → preview/components}/Text.vue +0 -0
  278. /package/dist/vendored/{components → preview/components}/Video.vue +0 -0
  279. /package/dist/vendored/{components → preview/components}/ViewContainer.vue +0 -0
  280. /package/dist/vendored/{components → preview/components}/base.js +0 -0
  281. /package/dist/vendored/{components → preview/components}/icons.js +0 -0
  282. /package/dist/vendored/{components → preview/components}/index.js +0 -0
  283. /package/dist/vendored/{meta → preview/meta}/component-meta.json +0 -0
  284. /package/dist/vendored/{meta → preview/meta}/directive-meta.json +0 -0
  285. /package/dist/vendored/{meta → preview/meta}/style-meta.json +0 -0
  286. /package/dist/vendored/{runtime → preview/runtime}/StyleParser.js +0 -0
  287. /package/dist/vendored/{runtime → preview/runtime}/adapter.js +0 -0
  288. /package/dist/vendored/{runtime → preview/runtime}/assets.js +0 -0
  289. /package/dist/vendored/{runtime → preview/runtime}/canvas-context.js +0 -0
  290. /package/dist/vendored/{runtime → preview/runtime}/card-runtime.js +0 -0
  291. /package/dist/vendored/{runtime → preview/runtime}/evaluate.js +0 -0
  292. /package/dist/vendored/{runtime → preview/runtime}/property.js +0 -0
  293. /package/dist/vendored/{runtime → preview/runtime}/selectionOverlay.js +0 -0
  294. /package/dist/vendored/{runtime → preview/runtime}/toPreview.js +0 -0
  295. /package/dist/{server-core → vendored/server/core}/assetProxy.js +0 -0
  296. /package/dist/{server-core → vendored/server/core}/bbox.js +0 -0
  297. /package/dist/{server-core → vendored/server/core}/buildDataFromSchema.js +0 -0
  298. /package/dist/{server-core → vendored/server/core}/cardFiles.js +0 -0
  299. /package/dist/{server-core → vendored/server/core}/cardHistory.js +0 -0
  300. /package/dist/{server-core → vendored/server/core}/cardImage.js +0 -0
  301. /package/dist/{server-core → vendored/server/core}/cardImportMeta.js +0 -0
  302. /package/dist/{server-core → vendored/server/core}/cardListCache.js +0 -0
  303. /package/dist/{server-core → vendored/server/core}/cardOpenFolder.js +0 -0
  304. /package/dist/{server-core → vendored/server/core}/cardSidecar.js +0 -0
  305. /package/dist/{server-core → vendored/server/core}/codeBridge.js +0 -0
  306. /package/dist/{server-core → vendored/server/core}/logStream.js +0 -0
  307. /package/dist/{server-core → vendored/server/core}/logger.js +0 -0
  308. /package/dist/{server-core → vendored/server/core}/nodeModels.js +0 -0
  309. /package/dist/{server-core → vendored/server/core}/renderStatus.js +0 -0
  310. /package/dist/{server-core → vendored/server/core}/screenshot.js +0 -0
  311. /package/dist/{server-core → vendored/server/core}/sliceStatic.js +0 -0
  312. /package/dist/vendored/{meta → skills/dsl-card-generator/vendor/preview/meta}/action-meta.json +0 -0
  313. /package/dist/{server-core/_vendor → vendored/tools}/finmall-env.mjs +0 -0
@@ -0,0 +1,928 @@
1
+ # 生成避坑清单(Generation Pitfalls)
2
+
3
+ > 本文件沉淀自一次真实生成任务:**从 Sketch 标注 `UI/30收支分析_提取到收支类型和时间维度_按年` 生成 `src/cards/gen-card-test`**。
4
+ > 这一轮踩过的坑全部已转化为 skill 的**硬校验**或本文档的提醒,避免下次重蹈覆辙。
5
+ >
6
+ > 其他文档只引用本文,不要重复措辞;与本文冲突以本文为准(本文是「生成」专题的唯一权威)。
7
+
8
+ ---
9
+
10
+ ## 0. 一句话总纲
11
+
12
+ - **`itemValueFrom` 不是可选项,是生死线**——漏写它,背景/内边距/gap/对齐在预览里**静默消失**,且旧校验漏报。
13
+ - **`style` 子项的 `itemId` 必须严格对照 `vendor/preview/meta/style-meta.json`**——`flexDirection` 是 `006`,不是 `002`(那是 `alignItems`)。
14
+ - **校验通过 ≠ 画对了**——`validate_schema.py` 只查结构,不查渲染;必须以 `card_screenshot` / Playwright 视觉真相收口。
15
+
16
+ ---
17
+
18
+ ## 1. itemValueFrom 必填(最致命)
19
+
20
+ ### 现象
21
+ 手写 `style` 时若漏掉 `itemValueFrom`(尤其 `style` 子项),卡片在预览里**背景色不上、内边距为零、gap 为零、对齐失效**,但 `validate_schema.py` 全程 0 报错。gen-card-test 第一轮就因此"看起来完全没样式"。
22
+
23
+ ### 根因(确证)
24
+ `vendor/preview/runtime/property.js` 的 `Property.onPreview()`(L199-224):
25
+
26
+ ```js
27
+ if (this.itemVisible && this.itemKey) {
28
+ if (this.itemValueFrom === '0') { /* 写进预览产物 */ }
29
+ else if (this.itemValueFrom === '1') { /* 变量绑定 */ }
30
+ else if (this.itemValueFrom === '2') { /* 图片 */ }
31
+ // 三者都不匹配(undefined / "")→ 整条分支不执行 → 该属性被丢弃
32
+ }
33
+ ```
34
+
35
+ 即:`itemValueFrom` 不是 `'0'/'1'/'2'` 时,这个 style/prop 直接从预览产物里蒸发。**不是"取默认",是"没有"**。
36
+
37
+ ### 规则
38
+ - 每个 `style` 子项、`component.properties[]`、`directives[]` 都必须带 `itemValueFrom`:
39
+ - `"0"` 常量(直接用 `itemValue`);
40
+ - `"1"` 变量/表达式(**必须**额外带 `itemDefaultValue` 兜底);
41
+ - `"2"` 图片/文件值。
42
+ - 不可省略、不可写空串、不可写数字 `0`(运行时是严格字符串比较 `=== '0'`)。
43
+
44
+ ### 现在已被工具链兜底
45
+ - `validate_schema.py`:缺失/空串 `itemValueFrom` 已升级为 **ERROR**(之前因 `""` 在白名单里漏报)。
46
+ - `autofix_schema.py`:会自动把缺失/空串补成 `"0"`(常量,最安全默认),跑一次即清零。
47
+ - 脚手架 `scaffold.mjs` 生成的 `boundProp/constProp/makeStyleChild` 本就带 `"0"`,**只有手写 style 才容易漏**——写完务必跑校验。
48
+
49
+ ---
50
+
51
+ ## 2. style 子项 itemId 以 style-meta.json 为准(flexDirection=006 陷阱)
52
+
53
+ ### 现象
54
+ 凭肌肉记忆把 `flexDirection` 写成 `itemId:"002"`,导致 Column 不堆叠、100% 宽子项换行。`validate` 原实现因 `"002"` 是全局合法 itemId(其实是 `alignItems`)而**漏报**,渲染却炸。
55
+
56
+ ### 根因
57
+ `restoreProperty`(`property.js`)按 `index[itemId] || index[itemKey]` 匹配 meta。`flexDirection` 子项若 `itemId:"002"`,会先匹配到 `alignItems` 的 meta → 值被错填给 alignItems,`flexDirection` 永远取默认 `row`。
58
+
59
+ ### 易错 itemId 速查(以 `vendor/preview/meta/style-meta.json` 为唯一权威)
60
+
61
+ | 样式组 | 子项 | 正确 itemId | 常见误写 |
62
+ |---|---|---|---|
63
+ | flex (100) | **flexDirection** | **006** | 002(那是 alignItems) |
64
+ | flex (100) | justifyContent | 001 | — |
65
+ | flex (100) | alignItems | 002 | — |
66
+ | flex (100) | gap | 003 | — |
67
+ | rect (200) | width | 003 | — |
68
+ | rect (200) | height | 004 | — |
69
+ | background (300) | backgroundType | 001 | — |
70
+ | background (300) | backgroundColor | 002 | — |
71
+ | padding (400) | paddingType | 001 | — |
72
+ | padding (400) | padding | 002 | — |
73
+ | borderRadius (600) | borderRadiusType | 001 | — |
74
+ | borderRadius (600) | borderRadius | 002 | — |
75
+ | font (1100) | color | 001 | — |
76
+ | font (1100) | fontSize | 002 | — |
77
+ | font (1100) | **lineHeight** | **007** | **005(那是 isMaxLine)** |
78
+ | font (1100) | **textAlign** | **003** | **006(那是 maxLine)** |
79
+ | font (1100) | fontWeight | 004 | — |
80
+
81
+ > 完整映射永远以 `style-meta.json` 为准;上面的表只列出最容易想当然写错的那几个。**不必死记**——`validate_schema.py` 现已校验「样式子项 itemId 是否与该组预期一致」,写错直接 ERROR 报出 `flexDirection uses 002 instead of 006`。
82
+
83
+ ---
84
+
85
+ ## 3. 图片 / 背景资源解析规则
86
+
87
+ ### 现象
88
+ 把设计稿切片(如 `gen-card-test.png`)以本地相对路径写进 `backgroundImage`,预览里背景**不显示**(破图/无背景)。
89
+
90
+ ### 规则
91
+ - 预览器(`vendor/preview/runtime/adapter.js`)**无法解析本地相对路径 PNG**;`bare relative local path` 不命中任何资源代理。
92
+ - 三种可行方案,按优先级:
93
+ 1. **远程 `@filestore/...` 别名**:经 `doReplaceUrl` + 8787 资源代理重写,编辑器导出卡均用此;新建卡若无远端资源,不要硬编。
94
+ 2. **纯色背景**:`backgroundType:"01"` + `backgroundColor:"#F6F7F9"`,最稳,gen-card-test 月度项背景即采用此法。
95
+ 3. 确有本地图片需求时,放 `vendor/preview/assets/` 并用约定资源入口(参考现有导出卡的图片引用方式),不要随手写相对路径。
96
+ - 结论:**能用纯色就别引用本地切片**;gen-card-test 因此弃用了 `gen-card-test.png`。
97
+
98
+ ### 3.1 缺素材时用占位图(生成器默认口径)
99
+
100
+ 设计稿出现图标 / 背景图 / 复杂背景效果,但**手头没有对应可用素材**时,先占位、不卡生成:
101
+
102
+ - **Image 组件缺图**:`value` 留空(`""`)即可——`vendor/preview/components/Image.vue` L28 用 `this.value || DEFAULT_IMAGE_URL` 自动兜底到打包内的 `default-image.png` 占位图(renderer-proven,`DEFAULT_IMAGE_URL` 定义在 `vendor/preview/runtime/assets.js`)。这是最稳的占位方式,无需任何路径。
103
+ - **Icon 缺对应字形**:Icon 是矢量字形(来自 `vendor/preview/assets/svg-symbols.svg` sprite),没有对应 glyph 时**不能硬填本地 PNG**。改用 Image 组件占位(空 `value` → 自动显示 `default-image` 占位图)顶在图标位。
104
+ - **背景图 / 复杂背景效果缺素材**:`backgroundImage` **没有**自动兜底,且本地相对 PNG 不解析(见上 §3)。占位二选一:
105
+ 1. 在该层放一个**占位的 Image 组件**(空 `value` → 显示 `default-image` 占位图)作为背景层,后续替换为真图;
106
+ 2. 或先用纯色背景(上 §3 方案 2,最稳)。
107
+ 复杂渐变 / 纹理 / 毛玻璃等效果可先以占位图呈现,不纠结 100% 还原,等真素材到位再替换。
108
+ - 远程真图可用时仍优先 `@filestore/...` 别名(上 §3 方案 1)。
109
+ - **怎么用 backgroundImage 承载复杂背景 / 状态相关视觉(含 itemValueFrom 2 静态整图、itemValueFrom 1 表达式算 URL)**——正向范式见 `references/recipes.md §8`。
110
+
111
+ ---
112
+
113
+ ## 4. 布局陷阱(反复中招)
114
+
115
+ 0. **卡片根节点绝不用画布/页面灰底;外圆角只画在卡片本体上;绝不从截图四角采样背景。**(rules.md §九)
116
+ → 聚焦图 `card-N.png` 是 RGBA,卡片几何(`spec.cards[].mask`,`type:"geometry"`)之外已透明,背景可能是非均匀/非固定色,禁止取四角像素当 Root 背景。纯色卡:Root 背景=`spec.cards[].cardFill`(卡片自身 fill),外圆角放 Root,第一层容器透明且不重复圆角(geo 已按此约束)。分层卡:Root `backgroundType=00` 透明,圆角与背景放内部独立卡容器(v3 的 `whiteCard`)。`cardFill` 为 null 时 Root 必须透明。**禁止**把画布灰底(`#F5F6F8` 等)或 `TOKEN.pageBg/fallbackBg` 写进 Root 背景。
117
+ 1. **根节点(Root)不要在 style 里放 rect 组(width)。**
118
+ → 根节点宽度由顶层 `view.width="375"` 承载,`view.style.properties` 里**不要**加 `rect` 组(含 `width:375`)——冗余且与 view.width 冲突(导出实证:49+ 张卡根 style 均无 rect)。误加时 `check_topology.py` 会报 `Root_style_rect_forbidden`(hard 级)提示删除。铁律见 `rules.md §九`。
119
+ 1. **Column 默认 `width:100%`,同 Row 内两个 100% 宽 Column 会换行。**
120
+ → 给配对 Column 加 `rect.width:"auto"`;或给 Row 内元素明确宽度/auto,再配 `justifyContent:space-between`。
121
+ 2. **空 `Row` + 背景色不渲染。**
122
+ → 进度条/色块别用空 Row 撑高,改用 **`Divider` 叶子组件**(`backgroundColor` + `rect.height` 撑高)。gen-card-test 的橙/黄进度条即两枚 `Divider`(height 4)。**宽度要数据驱动,禁止写死**——见 §8。
123
+ 3. **Icon glyph 必须是 svg-symbols.svg 里存在的 id。**
124
+ → 用 `grep -oE 'id="[^"]*"' vendor/preview/assets/svg-symbols.svg | sort -u` 查可用列表。常用:`angle_right` / `arrow_right` / `caret_right`(右箭头)、`angle_down/up/left`、`times`、`check` 等。**`'right'` 不是有效 id**(常用但缺),渲染空白甚至 server 500。
125
+ 4. **padding 多值必须拆四边(style-meta `padding.padding` 仅接受单值)。**
126
+ → 单值 `'12'` → `paddingType=0` + `padding=12`;多值 `'16 12'` / `'8 16 12 24'` → `paddingType=1` + 拆 `paddingTop/Right/Bottom/Left` 各设。违反时预览器解析失败(文本 width 塌缩/行宽爆数千 px)。多 builder 见 `message-center-pattern.md §4`。
127
+ 5. **列容器的子组件必须放 `slots[0].components`,不是 `components` 字段。**
128
+ → 参照导出卡(account/activityLevel 等):`components: []` + `slots: [{slotKey:'default', slotScope:false, components:[...]}]`。否则 `validate_schema.py` 警告"has no slots",且预览器可能不渲染该子树。
129
+ 6. **每个组件必须带 `componentId`(唯一字符串)+ `slots: []`。**
130
+ → validate 硬要求 componentId,缺失则 ERROR。leaf 节点(Text/Icon/Image/Divider/Button)也带 `slots: []`(空数组)。手工构建时建议全局计数器自动分配(`comp_0001`、`comp_0002`…)。
131
+ 7. **padding 多值按 CSS 语义解析**(构建器常踩):
132
+ - 1 值 `'12'` → 全边 12
133
+ - 2 值 `'16 12'` → 上下 16、左右 12(**CSS 标准**,不是 top/right/bottom/left)
134
+ - 4 值 `'8 16 12 24'` → top right bottom left
135
+ - 反例:把 `'16 12'` 解析成 top=16, right=12, bottom=12, left=12(bottom 错误,应 16)——底部 padding 会偏小。
136
+ 8. **左右对齐的"行内两簇"两种做法**(见 `spec_to_schema_patterns.md §0.2.1`):
137
+ - **方案 A · 左撑满+右固定**:左 `width:100%+shrink:1`,右不设宽度 + `shrink:0`,父 `space-between` —— 适用"左侧文本可能很长"
138
+ - **方案 B · 父 space-between + 两侧都不设宽度**:子节点都按内容尺寸固定 —— 适用"两侧都是固定内容"
139
+ - **绝对禁忌**:用百分比(`width:60%`)写死宽度,无法应对右侧内容变化。
140
+ 9. **列表项右箭头距离右边 16px → 通过父容器 paddingRight=16**(设计标注常见约定):
141
+ - itemTpl 的 padding 形如 `'16 16 16 12'`(top right bottom left),right=16 让箭头距右 16px
142
+ - 不要给 Icon/Image 自己设 marginRight(边距应由父容器统一管控)
143
+ 10. **红点 / 小圆形色块用 Divider + borderRadius=半高 模拟**(Icon 无"纯圆点"字形):
144
+ - Divider `width:N height:N backgroundColor:#xxx borderRadius:N/2` → 圆形
145
+ - 例:10×10 红点 → `divider_node(width=10, height=10, color='#F6434F', radius=5)`
146
+ 11. **箭头 / 方向图标优先用设计稿切片(Image)而非 Icon 矢量字形**(`slices_convention.md` 铁律):
147
+ - 设计稿切片目录有 `slices/8.icon/通用/箭头右@3x.png` 时 → `<Image value="/slices/8.icon_通用_箭头右@3x.png" />`
148
+ - 仅当设计稿没有该图标切片、且 svg-symbols.svg 含对应 glyph 时,才用 Icon glyph(如 `angle_right`)。
149
+ - **反例**:用 `icon glyph='angle_right'` 实现列表底部"查看更多 >"链接——设计稿明确给了对应箭头切片(导出路径见 spec.slices),应该用 Image。
150
+ 3. **多行内容行的 `alignItems`。**
151
+ → 左右两列各含"标签+数值"两行时,`alignItems:center` 会让右列顶部对齐到左列中部;用 `flex-end` 让两列底部对齐更自然(gen-card-test `comp_item` 最终用 `flex-end`)。
152
+ 4. **`space-between` 需要子元素有确定宽度或 auto**,纯默认 100% 会撑满不分布。
153
+
154
+ ---
155
+
156
+ ## 5. 视觉真相验证(Playwright 配方)
157
+
158
+ `validate_schema.py` 只证明"结构合法、绑定可解析、渲染不抛错",**不证明画对了**(`render_status.ok ≠ 画对`)。生成后必须做视觉收口:
159
+
160
+ > **适用范围**:本节的视觉收口只针对 **UI 变更**(新建卡、改 `style.*`、节点增删移动、静态文案、图片资源、v-show 条件)。**非 UI 变更**(`inputParams` / 绑定表达式取值逻辑 / 事件代码 / `data.json`)不做视觉验证,改用单元断言收口——铁律见 `rules.md §七.1`。
161
+
162
+ ```bash
163
+ # 首选:离线独立渲染器(vendor/preview 构建产物 + 系统 Chrome CDP),用完即关,不依赖 npm run dev
164
+ node skills/dsl-card-generator/scripts/render_card.mjs --id <id> --width 375 --out /tmp/<id>.png
165
+ ```
166
+
167
+ 旧 Playwright 配方仍可用于 `getComputedStyle`/`getBoundingClientRect` 逐项断言;但截图收口不要再用 5180:
168
+
169
+ ```js
170
+ // 仅当需要自定义页面交互/逐样式断言且宿主 dev server(5180) 已启动时使用;
171
+ // 本 skill 的离线 render_card.mjs 不提供任意页面交互,复制 skill 到其他项目后该配方按需自建。
172
+ import { chromium } from 'playwright';
173
+ const ts = Date.now();
174
+ const url = `http://localhost:5180/?card=<id>&t=${ts}`;
175
+ const browser = await chromium.launch({ channel: 'chrome', args: ['--no-sandbox'] });
176
+ const page = await browser.newPage({ viewport: { width: 1200, height: 900 }, deviceScaleFactor: 2 });
177
+ await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30000 }); // 不要 networkidle:Vite HMR 永不 idle
178
+ await page.waitForTimeout(2500); // 等 HMR + 首帧
179
+ const el = await page.$('.phone__frame');
180
+ await el.screenshot({ path: '/tmp/<id>.png' }); // 只截设备框,排掉外壳
181
+ await browser.close();
182
+ ```
183
+
184
+ 要点:
185
+ - **必须用系统 Chrome**:`chromium.launch({ channel: 'chrome' })`(缓存的 headless shell 版本常不匹配)。
186
+ - **`waitUntil:'domcontentloaded'` + `waitForTimeout(2500)`**,别用 `networkidle`(Vite HMR 持续连接,永远不 idle → 超时)。
187
+ - 截图 `.phone__frame` 元素,排除编辑器外壳;`@2x` 看清细节。
188
+ - 可用 `page.evaluate(() => getComputedStyle(el))` 直接读 `display/flexDirection/justifyContent/width/backgroundColor` 做**断言式核对**(比肉眼更准),定位"为什么没堆叠/没背景"。
189
+ - 若只是截图/视觉比对,优先 `render_card.mjs` 或 MCP `card_screenshot`(dev server 未启动时自动离线降级),无需先跑 `npm run dev`;只有自定义交互/逐样式断言才需要上面这段 Playwright 配方。
190
+
191
+ ---
192
+
193
+ ## 6. 生成—校验—修复闭环(推荐顺序)
194
+
195
+ 1. `node skills/dsl-card-generator/scripts/scaffold_card.mjs --intent <i> --id <id> --name <名>` 出骨架(零手写样板,自带 `itemValueFrom`)。
196
+ 2. 查 `references/card_index.json` 选近邻导出卡改造,保留 `componentId`。
197
+ 3. 手写 `style` 时**逐个子项带 `itemValueFrom`**,并对照 §2 表核对 `itemId`。
198
+ 4. `python3 skills/dsl-card-generator/scripts/validate_schema.py <schema.json>` → 把 `[ERROR]` 清零。
199
+ - 若报 `Missing/empty itemValueFrom`:`python3 autofix_schema.py <schema.json>` 一键补,再复验。
200
+ - 若报 `Style 'flex.flexDirection' ... 002 instead of 006`:这是 itemId 写错,需人工改(autofix 不动,因为要确认语义)。
201
+ 5. `python3 derive_data_json.py <schema.json> --check`(或 `autofix` 顺带修漂移)。
202
+ 6. **Playwright 截图 / `card_screenshot` 视觉收口**(§5),按七维度(`references/image_diff.md`)逐项核对。
203
+ 7. (可选)`diff_card.mjs` 确认未涉及节点没误删。
204
+
205
+ > 铁律、证据分级、DSL 契约等其他章节见 `references/rules.md`;本文件只管"生成时最容易翻车的具体点"。
206
+
207
+ ---
208
+
209
+ ## 7. 工具链兜底现状(落地确认)
210
+
211
+ 本文 §1、§2 的两个致命点已被工具链双保险拦截,**两处脚本均已生效**:
212
+
213
+ - **`validate_schema.py`**(CI 硬卡点):缺失/空串 `itemValueFrom` → ERROR;style 子项 `itemId` 与该组预期不一致 → ERROR(捕捉 `flexDirection` 002 vs 006)。
214
+ - **`lint_card.mjs`**(健康度体检,检查项 9/10):同源重复校验,方便 `node lint_card.mjs --id <id>` 或 `--all` 时一并发现,报告 `missing-itemValueFrom` / `style-itemId-mismatch`(severity=error)。
215
+ - **`autofix_schema.py`**:缺失/空串 `itemValueFrom` 一键补 `"0"`(常量,最安全默认);`itemId` 错配不动(需人工确认语义)。
216
+
217
+ > 速查版见 `references/quickref.md` §7。
218
+
219
+ ---
220
+
221
+ ## 8. 进度条必须数据驱动(≤1 比率绑定,禁止静态写死)
222
+
223
+ > **这是 UI 功能实现层面的约定,不是新增"进度条组件"**——DSL 里没有进度条组件(编辑器专属的 `ProgressSlider` 预览不渲染)。进度条是用 `Divider` / 带背景的 `Row` **视觉模拟**出来的;本条要管的是:**模拟出来的进度条,其填充宽度必须反映数据,而非写死成装饰条**。
224
+
225
+ ### 规则
226
+ 识别到设计稿里的**进度条 / 占比条 / 完成度条 / 按比率填充的色块**时:
227
+
228
+ 1. **不要**把填充宽度写成静态百分比(如 `43%` / `57%`)——那只是某一刻的快照,数据一变就对不上,且失去"进度"语义,沦为纯装饰。
229
+ 2. 新增一个 **≤1 的比率 inputParams**(如 `incomeRatio`),把每段填充宽度**绑定成表达式**:
230
+ - 收入段:`width` → `itemValueFrom:"1"`、`itemValue:"$incomeRatio * 100 + '%'"`、`itemDefaultValue:"45%"`
231
+ - 支出段:`width` → `itemValueFrom:"1"`、`itemValue:"(1 - $incomeRatio) * 100 + '%'"`、`itemDefaultValue:"55%"`
232
+ 3. `data.json` 同步加 `"incomeRatio": 0.45`(`derive_data_json.py` 会校验一致)。
233
+ 4. **比率数值来自业务侧**(收入 / (收入 + 支出)),由外部系统算好传入;卡片只负责"映射",不负责"算金额"。
234
+
235
+ ### 为什么(确证)
236
+ gen-card-test 第一轮就把收支占比条写成了静态 `43%` / `57%` 的 `Divider`——能看,但数据不可驱动。按本规则修正后:进度条绑定 `incomeRatio`(默认 0.45),橙/黄两段宽度随该比率实时映射,文字(总收入/总支出)与色块比例永远自洽。
237
+
238
+ ### 落地做法(以 gen-card-test 收支占比条为例)
239
+ ```jsonc
240
+ // dictionary.inputParams 新增
241
+ { "key": "incomeRatio", "name": "incomeRatio", "type": "number",
242
+ "defaultValue": 0.45, "desc": "收入占比(0~1),进度条橙色段宽度映射来源" }
243
+
244
+ // comp_bar_income(橙 #FF5C00)width 改为绑定
245
+ { "itemId": "003", "itemKey": "width",
246
+ "itemValueFrom": "1", "itemValue": "$incomeRatio * 100 + '%'", "itemDefaultValue": "45%" }
247
+ // comp_bar_expense(黄 #FCC800)width 改为绑定
248
+ { "itemId": "003", "itemKey": "width",
249
+ "itemValueFrom": "1", "itemValue": "(1 - $incomeRatio) * 100 + '%'", "itemDefaultValue": "55%" }
250
+ ```
251
+
252
+ > 速查版见 `references/quickref.md` §7。
253
+
254
+ ---
255
+
256
+ ## 9. 视觉还原硬规则(2026-08-19 固化)
257
+
258
+ > 以下规则沉淀自 messageOverview_visual 生成全过程的真实错误(用户逐条指出)。
259
+ > **声明:这只是已发现问题的固化,不代表覆盖全部潜在错误——任何新卡生成后仍需按 §5 双门禁人工复核。**
260
+
261
+ ### 自动化覆盖索引(哪些规则已由工具兜底)
262
+
263
+ | 规则 | 工具 | 自动校验内容 |
264
+ |---|---|---|
265
+ | **R1 属性值来源** | `validate_schema.py` | itemValueFrom 缺失/空串 → ERROR |
266
+ | **R5 验收双门禁** | `render_diff.mjs` | 设计稿 vs 渲染并排对比,AI 多模态判断差异(替代旧 fidelity 分数) |
267
+ | **R8 圆角归属** ✅ | `lint_card.mjs` `r8-double-border-radius` | Root 与一级子容器双重圆角 → INFO |
268
+ | **R11 渲染器默认样式** | `validate_schema.py` | style 子项缺 itemValueFrom → ERROR(覆盖隐性根因) |
269
+ | **R17 叶子节点防压缩** ✅ | `lint_card.mjs` `r17-leaf-no-flexshrink` | Text/Icon/Image/MultiText 缺 flexShrink:0 → **ERROR** |
270
+ | **R19 space-between 宽度** ✅ | `lint_card.mjs` `r19-space-between-no-width` | Row space-between 且宽度不确定(未设/auto)又未被父容器拉伸 → WARN |
271
+ | **R22 width:100% 可压缩** ✅ | `lint_card.mjs` `r22-width100-flexshrink0` | width:100% + flexShrink:0 → **ERROR** |
272
+ | **style itemId** | `validate_schema.py` | flexDirection 必须是 006 不是 002 等 → ERROR |
273
+ | **Button/Icon click** | `lint_card.mjs` | Button 缺 click → WARN(祖先带 click 时降为 INFO `button-click-by-ancestor`:`Button.vue` 的 `$emit('click')` 未 `.stop`,原生 click 会冒泡到祖先 handler,按钮实际可点,只是热区被放大);Icon 缺 click → **ERROR**(R-FMT3) |
274
+ | **Canvas onMeasured** | `lint_card.mjs` | Canvas 缺 onMeasured → WARN |
275
+ | **Root background** | `lint_card.mjs` | Root 缺 background → INFO |
276
+ | **R-FMT1 borderRadius 格式** ✅ | `lint_card.mjs` `fmt-border-radius-tuple` | borderRadius 元组 `{...}` → **ERROR** |
277
+ | **R-FMT2 padding/margin 格式** ✅ | `lint_card.mjs` `fmt-padding-tuple` | padding/margin 元组 `{...}` → **ERROR** |
278
+ | **R-FMT4 MultiText 默认值** ✅ | `lint_card.mjs` `multitext-item-no-default` | itemList itemValueFrom:1 缺 itemDefaultValue → **ERROR** |
279
+ | **R9/R10 Root 零间距** ✅ | `lint_card.mjs` `r9-root-nonzero-padding` | view 设非零 padding/margin → **ERROR** |
280
+
281
+ > **用法**:Workflow A 步骤 4 中,`validate_schema.py`(结构合法性)+ `lint_card.mjs`(行为规则)**双门禁全过 0 ERROR** 才能进入步骤 5 渲染。lint 已把渲染相关的关键规则(R17/R22/R-FMT1-4/R9)升级为 **ERROR**,在渲染前拦截——不等到截图比对才发现。
282
+ > 未被工具覆盖的规则(R2/R3/R4/R6/R7/R9/R10/R12-R16/R18/R20/R21)仍需 AI 在生成时遵守,下面逐条说明。
283
+
284
+ ### R1 属性值来源 = spec 标注 + meta,禁止凭记忆、禁止抄存量卡
285
+ - **属性值类**(color/fontSize/lineHeight/radius/shadow/border/背景色)**直接读 spec 标注**(见 R10);组名 / 子项 key / 类型开关 / itemId 读 `vendor/preview/meta/style-meta.json` + `vendor/preview/meta/component-meta.json`。
286
+ - 存量卡只用于确认 meta 的「取值合法性 / 字段语义」,**不作为属性值来源**——抄存量卡 = 把别的卡片的数值错误带入(R10 已踩坑全类)。
287
+ - 已踩坑:`borderRadiusType:'01'`(真值 '0')、`backgroundType:'00'`(透明底,按钮须配文字色否则文字与底融合)、gap 放在不存在的 `flexGap` 组(应在 flex 组)、`paddingType:'0'` 时 paddingTop/Bottom 子项被忽略(必须 '1')、style itemId 留空(渲染器 Property 构造崩)。
288
+ - 验收:`validate_schema.py` **0 error 0 warn**(WARN 也是没对齐 meta 的证据)+ DOM computed style 与 spec 标注一致。
289
+
290
+ ### R2 间距唯一来源 = spec 容器边界,禁止文本 y 差臆测
291
+ - 间距 = 相邻**容器元素**(shape/group/symbol 的 rect)边界之差,不是文本元素 y 差(文本 rect 含字体度量误差)。
292
+ - 已踩坑:用「描述文本底→下项标题顶」算列表项卡间距得 44px,查卡容器边界(shape 矩形)实为 12px——把卡内 padding 也算进去了。
293
+ - 验收:渲染后 Playwright `getBoundingClientRect` 逐区块对照 spec 容器边界,±2px 内。
294
+
295
+ ### R3 切图唯一路径 = slicePath.mjs;源缺失必须显式告警,禁止手写 @Nx
296
+ - 图标一律 `resolveSliceExport(spec.slices, sliceElName)` + `sliceRefPath`(导出路径自带 @3x → **3x 自动优先**);被引用切片必须拷到 `src/slices/<扁平名>`(仅引用才拷,卡片主体外的 chrome 图标不拷)。
297
+ - **`collectSlices` 返回 `missing` 清单**(spec slice 元素 + rect + reason),生成器**显式 WARN 告警**——禁止静默跳过。
298
+ - 源缺失兜底:**从 card-N.png 按 spec slice rect 精确抠图占位**(spec rect 在画布上是精确坐标,注意 card-N.png 通常 @2x 需按画布→图内坐标换算),存 `src/slices/<flatname>.png`;路径含 `#` 必须 `%23` 编码(HTML img src 把 `#` 后当 fragment 截断)。
299
+ - 已踩坑:手写 `@2x`(src/slices 只有 @3x → 404)且违反 3x 优先约定;上游导出遗漏(spec.slices/源目录都缺)时静默降级为 Text "?" 掩盖问题。
300
+ - 验收:Image value 全部 @3x 且可访问(curl /slices/<扁平名> 200);missing 清单为空(Agent/上游修图后)。
301
+
302
+ ### R4 数据驱动:提取出数组必用列表组件,禁止写死
303
+ - 任何提取出的数组数据(列表/明细/枚举)必须用 ListLayout/GridLayout:properties.value 绑 `$var`(itemType var + itemDefaultValue 数组形态)+ slot 设 `slotScope:true` + itemTemplate 内字段用 `$field` 绑定。
304
+ - 已踩坑:提取了 messageList 却写死 3 个 Row(放弃数据驱动)。
305
+ - 验收:改 data.json 数组项数 → 渲染列表项数联动。
306
+
307
+ ### R5 验收双门禁:校验 + DOM 实测,fidelity 分数不算数
308
+
309
+ > 适用范围:**UI 变更**(本条出自「从设计稿生成卡片」语境,天然属 UI)。非 UI 变更免门禁 2,改走单元断言,见 `rules.md §七.1`。
310
+ - 门禁 1:`validate_schema`(0 error 0 warn)→ `derive_data_json --check` → `/__render-status`(ok + bindingErrorCount 0)。
311
+ - 门禁 2:Playwright 读 DOM computed style,逐项核对背景/圆角/颜色/宽高/间距/**对齐**(§5 配方),对照 spec 容器边界。**对齐断言必做**:居中元素中心 x ≈ 容器中心;右对齐元素右缘 ≈ 容器右缘;左对齐元素左缘 ≈ 容器左缘——对齐错误(textAlign 误用 / alignItems 对满宽子元素失效)只能靠 DOM 实测抓出,validate 不报。
312
+ - fidelity 分数只当参考(其按 box 高比文本高,Text 带 padding 会误报 Δh),**不作为验收标准**。
313
+
314
+ ### R6 组件异常先定位根因,禁止绕开标准方案
315
+ - 组件行为异常(如 ListLayout「重复渲染」)→ 先查 value 绑定、slotScope、模板结构、父容器布局,定位真因再修。
316
+ - 已踩坑:遇 ListLayout 异常直接改 3 个写死 Row(真因是 leftNum width 塌陷误导,非 ListLayout 问题)。
317
+
318
+ ### R7 生成器一律复用 lib/,禁止自写
319
+ - slicePath / layout-tokens / scaffold 是唯一工具源;style itemId 必须从 style-meta 权威化;禁止在生成器里重写路径/样式/Token 逻辑。
320
+
321
+
322
+ ### R8 卡片圆角放最外层容器(Root),不放内层白底主体
323
+ - 圆角值**读 spec 卡片容器 `mask.radius` 标注**;放在**最外层容器**(Root);外层背景=`spec.cards[].cardFill`(卡片自身 fill),**绝不读画布/蒙版 fill**——圆角外区域在独立渲染下由宿主透出,不得用画布灰底填充。
324
+ - 内层白底主体(Column)只设背景 + 结构性 padding,**不设圆角**——内层圆角被外层白底填平,视觉上是直角块。
325
+ - 已踩坑:圆角放内层 contentColumn + 外层 Root 白底无圆角 → 圆角被填平不可见;Root 背景抄存量卡(#F6F8FA)或误读画布/蒙版 fill(#F8F8F8)而非 `cardFill`。
326
+ - 验收:Playwright 查 Root `getComputedStyle.borderRadius` = spec `mask.radius`、`backgroundColor` = spec `cardFill`。
327
+ - **完整根样式提取**:除背景+圆角外,卡片根背景 shape 可能还标了 **border / shadow / opacity**——必须一并提取到根容器节点。完整字段映射与查找方法见 **R33**(卡片根节点样式全量提取)。
328
+
329
+ ### R9 元素间距用 margin,不用 padding
330
+ - "元素 X 与相邻元素的间距" → 写 X 的 `marginTop`/`marginBottom`(或相邻元素的 margin),**不用 padding**。
331
+ - padding 表达「盒子内部留白」:box 高 = 内容高 + padding,会污染 box 高(fidelity Δh 误报)、让"下一元素顶 = 内容底 + padding"而非纯内容底。
332
+ - 保留 padding 的场景:**结构性内边距**——容器内边距、卡片内边距、文本缩进(paddingLeft)。
333
+ - 渲染器 margin 支持:`margin` 组 `marginType`('1'=四边自定义)+ `marginLeft/Top/Right/Bottom`(见 vendor/preview/meta/style-meta.json)。
334
+ - 验收:DOM computed style margin 有值;间距实测对齐 spec 容器边界 ±2px(padding↔margin 同值视觉等价,只差 box 高)。
335
+
336
+
337
+ ### R10 标注可信度分层(最高优先级,2026-08-19 用户重申)
338
+ - **可参考标注(属性值类)**:圆角 radius、阴影 shadow、字体 textStyle(fontSize/lineHeight/fontWeight/color/textAlign)、边框 border(isBorder/width/color)、背景 fill/background(Root 背景读 `cards[].cardFill`,**禁止读画布/页面背景色**)—— 这些是设计值,直接读 spec,**不要抄存量卡**。
339
+ - **不可参考标注(几何类)**:rect x/y/w/h 尺寸、元素间距 —— 设计稿标注是**绝对定位**,不遵循节点树尺寸逻辑(矩形带 padding/margin 的盒子实际占位 ≠ 标注坐标差),必须按实图/容器边界(shape/group/symbol rect)分析。
340
+ - 已踩坑(全部是"该读标注却抄存量卡/误读画布背景"):Root 背景抄 v1 #F6F8FA 或误读画布蒙版 #F8F8F8(应读 `cards[].cardFill`);列表项卡 #F8FAFB+radius12(标注 #FAFAFA+radius8);按钮 radius 22(标注 20);链接色文案 #4F6BF2(标注 #1584FF);标题色 #171717(标注 #221715);描述/说明色 #888888(标注 #555555);列表 title weight 400(标注 500)。
341
+ - 验收:DOM computed style 与 spec 标注逐项一致(fontSize/lineHeight/color/fontWeight/backgroundColor/borderRadius/borderColor)。
342
+
343
+ ### R11 渲染器默认样式必须显式覆盖(隐性根因)
344
+ - preview 渲染器对**未显式设置**的 Row/Column/ListLayout 默认注入:`padding: 2px`、`gap: 4px`、`justify-content: center`(Column 内容**垂直居中**!);ListLayout 另有默认 `edge-insets {2,2,2,2}`(内部容器 2px 内边距)。
345
+ - 生成器必须显式指定:容器 `padding 0`(结构性 padding 如卡片 16 保留)、Column 显式 `justifyContent: flex-start`(防 center)、需要间距的容器显式传 `gap`、ListLayout 设 `edge-insets '{0,0,0,0}'`。
346
+ - 已踩坑:不覆盖 → 每层容器叠 2px padding + 4px gap + Column 垂直居中,内容偏移 8px+、列表项缩进错乱、头部整体下移。
347
+ - 验收:DOM computed style 检查 padding/gap/justifyContent 与预期一致(不应是渲染器默认值)。
348
+
349
+ ### R12 运行期数据必须绑定(动态参数提取是强制步骤,不是可选)
350
+ - 生成后通读全部常量文本,金额/余额/日期范围/姓名/卡号/账号/手机号/订单号等**运行期数据**必须提取为 inputParams 绑定 `$var` 并同步 data.json——静态文案(标题/标签/提示)才留常量。
351
+ - 金额字段一律 `type:"number"`(见 `amount_formatting.md` §2 铁律),渲染用表达式还原格式。
352
+ - 已踩坑:头部金额/日期范围直接写死字符串常量(明显运行期数据未绑定)。
353
+ - 验收:schema 中无未绑定的金额/日期类常量文本;data.json 金额字段为 number。
354
+
355
+ ### R13 金额数字铁律 + 表达式还原(含正则转义坑)
356
+ - 金额数据存 `number`,显示格式(千分号/¥/负号)用表达式还原——canonical 表达式库见 `amount_formatting.md` §3(`($n*1).toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ',')`、负数 `($n<0?'-¥':'¥')+Math.abs(...)`、带前缀 `'前缀¥'+...`)。
357
+ - **正则转义坑**:生成器源码里写正则必须 `\\B`/`\\d`(JS 字符串字面量两个反斜杠 = 值一个反斜杠);用脚本(python 等)替换写入会降级成单反斜杠 → JS 把 `\B` 当无效转义吞掉 → 千分号静默失效(`8927.50` 无逗号)。写入后必须查 schema 里表达式原文确认 `\B` 保留。
358
+ - 验收:渲染 DOM 文本含千分号/¥ 且 data.json 金额为 number。
359
+
360
+ ### R14 设计稿分割线必须实现,禁止省略
361
+ - spec 中细长 shape(高 ≤1、宽接近内容区、fill 浅灰如 #F0F0F0)是分割线,必须还原为 Divider(背景色 = 标注 fill)——不得以"浅色在白底上不可见"为由跳过。
362
+ - 列表项间分割线结构:Divider 放 itemTemplate 内,`marginTop` 承载"内容底 → 分割线"间距(spec 实测),剩余项间距由 ListLayout `row-spacing` 承载(两者之和 = 项间距)。
363
+ - 已踩坑:以"视觉差异小"省略列表分割线,用户逐条指出。
364
+ - 验收:DOM 中 Divider 数量 = spec 细长 shape 数量,y 对齐 spec(±1px)。
365
+
366
+ ### R15 flex 对齐心智模型(元素级对齐的唯一正确判断路径,同类问题总根源)
367
+ **先决策再写样式**——写任何元素对齐前,按以下两步判断(textAlign/alignItems/justifyContent 三者职责不同):
368
+
369
+ 1. **Text 盒内文本对齐** → `textAlign`(只对齐文本在 Text 盒内的位置,**不是元素级对齐手段**)。
370
+ 2. **元素级对齐**(元素在父容器内的位置)→ 看**该元素是否在主轴方向撑满父容器**(Row/Column 默认 `width/height: 100%` 撑满):
371
+ - **撑满 → 交叉轴 `alignItems` 对它失效**,只能靠父容器 `justifyContent`(主轴)控制:居中 `center`、靠右/靠下 `flex-end`、靠左/靠上 `flex-start`。
372
+ - **内容宽(width auto)→ 父容器 `alignItems`(交叉轴)生效**:`flex-end` 贴右、`center` 居中。
373
+
374
+ - 典型错误(同源):
375
+ - 给 Text 设 `textAlign: center/right` 以为元素居中/右对齐 → 元素仍停左缘(居中场景)或右缘不对齐(右对齐场景)。
376
+ - 父容器设 `alignItems: flex-end` 以为整行右对齐 → 子 Row 默认 width 100% 撑满,alignItems 失效 → 实际左对齐。
377
+ - 已踩坑:底部操作/链接文字用 textAlign center 不居中;头部右侧提示行(文字 + 图标)父列 alignItems flex-end 不右对齐(必须行内 justifyContent flex-end)。
378
+ - 验收:DOM 实测(门禁 2 对齐断言)——居中元素中心 x ≈ 容器中心;右对齐元素右缘 ≈ 容器右缘;左对齐元素左缘 ≈ 容器左缘。
379
+
380
+
381
+ ### R16 slice 元素必须 Image 组件 + 源缺失禁止降级为文字(最高优先)
382
+ - spec 元素 type=`slice`(设计稿标注的图标)→ 生成器**必须**用 Image 组件(props.value = `/slices/<path>`),**禁止**用 Text 字符/emoji 兜底。
383
+ - 触发:spec 元素标了 `type: 'slice'` 但 `collectSlices` 报告 missing(spec.slices 无匹配/源文件未导出/上游 MeaXure 导出遗漏)。
384
+ - 处理流程:
385
+ 1. `collectSlices` 返回 `missing` 列表(含 name/rect/reason),生成器显式 WARN
386
+ 2. 从 `card-N.png` 按 spec slice rect 精确抠图(card-N.png 通常 @2x,坐标换算 `((rect.x - cardRange.x) * scale, (rect.y - cardRange.y) * scale, (rect.x + rect.width - cardRange.x) * scale, ...)`),存 `src/slices/<flatname>.png`(文件名按 `sliceFlatName` 规则 + 实际像素 `@Nx` 后缀)
387
+ 3. 生成 Image 引用 `/slices/<flatname>.png`,**路径含 `#` 必须 `%23` 编码**
388
+ 4. 视觉尺寸按 spec rect 的 `width/height`(非图源像素)
389
+ - 反例:源缺失时用 `Text('?')` 兜底——掩盖真实问题、用户视觉失效、违反"必须 Image 组件"铁律。
390
+ - 验收:missing 清单为空;Image src 可访问(200);DOM 检查 Image 元素真实加载(非 alt 占位)。
391
+
392
+ ### R17 关键文本防换行(flexShrink:0 铁律,2026-08-20 固化)
393
+ - 渲染器 `.ce_text` 的 CSS 是 `width: fit-content; word-break: break-all`——**任何** Text 节点宽度被压缩时会在字符间断行,尤其是金额、百分比、标签这类关键文本:父容器被压缩到 0 时会出现文本字符垂直堆叠(每个字一行)的视觉塌陷。
394
+ - **根因**:Row 默认 `flexShrink:"1"`(可收缩),父子链上任一层被压缩都会沿断行规则塌陷。`justifyContent:space-between` 让父容器内的子节点收缩到 min-content 再分布。
395
+ - **铁律**:
396
+ 1. **关键文本节点(金额、数字、标签、标题、占比、单位等不允许换行的内容)必须显式设置 `flexShrink:"0"`**(flex 组子项 `itemId:"004"`,`itemValueFrom:"0"`)。这是与 §9-R15 并列、防视觉塌陷的硬约束。
397
+ 2. 包裹这些关键文本的 Row/Column 容器也需要 `flexShrink:"0"`,防止父链传播收缩。
398
+ 3. `justifyContent:space-between` 的两侧子节点各自保护:左侧组与右侧组都设 `flexShrink:"0"`;只有确实希望"被压缩换行"的长文本(如卡片描述)才留默认 `flexShrink:"1"`。
399
+ 4. **但 R17 仅适用于「内容宽 / auto / 未显式设 100%」的节点**——如果节点自身显式设了 `rect.width:"100%"`,请走 R22(必须可压缩),R17 不适用。两者按节点的 `width` 取值分流,互不冲突。
400
+ 5. **R17 仅适用于「单子容器」中的叶子节点**——即父容器只有该叶子一个子节点。多子并列容器(Row/Column 有 2+ 子节点)中的叶子**不强制 R17**——多子容器由 **R35**(至少一个子节点可压缩防溢出)管辖,二者按父容器的子节点数分流,互不冲突。
401
+ - 反例:列表项「左侧标题+右侧金额」用 Row + space-between,标题与金额都没设 shrink → 整行宽度塌陷 → 金额字符竖排堆叠(每字一行)。
402
+ - 验收:Playwright `getBoundingClientRect` 检查关键 Text 节点 `height ≤ 期望行高`(不是单字高度)、`width > 0`;用 `page.evaluate(() => el.getClientRects().length)` 检查文本实际渲染行数符合预期。
403
+
404
+ ### R18 分割线与触发元素配套隐藏(视觉语义铁律,2026-08-20 固化)
405
+ - 设计稿中"按钮上方的细分割线"的视觉语义是**分割按钮与上方内容区**(如列表);当按钮自身用 `v-show` 条件隐藏时,这条分割线**必须一起隐藏**——否则会出现"按钮没了、留一条孤立线"的视觉断层。
406
+ - **铁律**:
407
+ 1. 识别"这条分割线是为什么元素服务的"——分割线视觉上属于谁,就跟谁绑同一个显隐条件。
408
+ 2. 实现方式:把"触发元素(按钮/操作)+ 它的分割线"放进**同一个带 v-show 的容器**(Column 或 Row),让 v-show 条件控制整个组合的显隐;或两者各自绑**同一个 v-show 表达式**。
409
+ 3. 决策信号:分割线水平方向上的两端是否触达"目标元素正下方"?是 → 分割线属于该元素,配套隐藏;否则可能是容器级分割线,独立存在。
410
+ - 反例:「列表 + 分割线 + 查看更多」结构里,查看更多被 v-show 隐藏(列表条数 ≤ 3),但分割线独立没绑条件 → 视觉上留下一条孤线指向虚无。
411
+ - 验收:把触发元素的 v-show 条件强制设为 false(如把对应数据数组改为长度 ≤ 3),DOM 中分割线节点 `display:none` 或不存在;再设回 true 时分割线与按钮同时出现。
412
+
413
+ ### R19 行容器宽度撑满才能 space-between(嵌套 Row 显式 width:100%,2026-08-20 固化)
414
+ - `justifyContent:space-between` 只在**父容器宽度撑满父级**时才生效——根节点级 Row 默认 `width:100%`,但**多层嵌套**的内层 Row 不再默认 100%,会收缩到内容宽(`fit-content`),space-between 失效、子节点堆在左侧。
415
+ - **铁律**:
416
+ 1. 需要 `space-between` 左右分布的 Row,**显式 `rect.width:"100%"`**(`itemValueFrom:"0"`),确保撑满父级主轴。
417
+ 2. 这是 §9-R15 flex 对齐心智模型的补充:R15 讲「元素是否撑满决定 alignItems 生效与否」,本条讲「父容器自身是否撑满决定 space-between 生效与否」——两者都是宽度撑满问题,发生在不同层级。
418
+ 3. 嵌套深时每一层都要检查:中间任意一层 Row 不撑满,最底层的 space-between 就会失效。
419
+ - 反例:Root → Column(padding 16) → Row(space-between) 三层结构,中间 Row 没 width:100% → 收缩到内容宽 → 标题与右侧图标挤在左侧、没左右分布。
420
+ - 验收:Playwright `getBoundingClientRect` 检查 Row 容器 `width ≈ 父级 width`;左右子节点 `right - left` 之和接近容器宽、中间留空区域明显存在。
421
+ - **lint 触发条件(`r19-space-between-no-width` WARN,2026-09-09 收紧去误报)**:只在「宽度**不确定**且父容器**不拉伸**」时报,两种情况不报——
422
+ 1. **自身已给确定宽度**:`rect.width` 为 `100%` 或定宽 px。定宽时容器宽度可定,`space-between` 在该宽度内正常生效(如 `transferPlan` 两个 `width:"100"` 的日期胶囊并排在横向 Row 里,各自把日期文本与日历图标推到 100px 两端)。此时按铁律改成 `100%` 反而会让两个胶囊各占满父级而互相溢出。
423
+ 2. **父容器纵向流且交叉轴 stretch**:`Column`/`Root`/`SingleColumn` 的 CSS 已强制 `flex-direction:column`(见 `preview/styles/components.css` 的 `.ce_column`/`.ce_root`/`.ce_singlecolumn`),`align-items` 缺省即 `stretch`,子 Row 未设宽也会被拉伸到父内容宽,`space-between` 已生效。
424
+ 只有「未设宽/auto 且父容器是横向流(Row/MultiColumn/GridLayout/ListLayout 项等)或父级 `align-items` 非 stretch」才真的收缩到内容宽——这才是本条要拦的缺陷。
425
+ - **⚠️ 别为消 R19 WARN 盲目补 `width:"100%"`**:该节点若同时是 `flexShrink:"0"`,补完立刻撞 **R22 `r22-width100-flexshrink0`(ERROR)**;若其并列子节点又全是 `flexShrink:0`,还会撞 **R35 `r35-multi-child-all-shrink0`(ERROR)**。即「用 1 条 WARN 换 2 条 ERROR」,棘轮(error 只减不增)会直接失败。生成期按铁律显式写 `width:"100%"` 时,必须同时给该节点 `flexShrink:"1"`(R22)并让至少一个子节点可压缩(R35);存量卡若已被父级 stretch 撑满(渲染无缺陷),**不要**为了消 WARN 去补宽度。
426
+
427
+ ### R20 图标优先矢量字形(Icon sprite),切片为辅(2026-08-20 固化,扩展 R3)
428
+ - 设计稿图标出现时,**优先按以下顺序选择承载组件**(与 R3「切片优先」看似冲突,实为互补——R3 管"方向性/品牌性图标用切片保真",本条管"通用语义图标用矢量字形减负"):
429
+ 1. **svg-symbols 字形**:设计稿标注的图标语义能在 `vendor/preview/assets/svg-symbols.svg` sprite 里找到对应字形(如"帮助/问号"对应 `bangzhu`)时,**用 Icon 组件 + 该字形 id**——矢量、主题色可控、零资源请求。
430
+ 2. **设计稿切片**:方向性图标(箭头)、品牌性图标、字形库里没有的图标 → 用 Image + 切片路径(R3 路径,`collectSlices` + `/slices/<path>`)。
431
+ 3. **占位图**:以上两种都没有 → Image 空 value 显示 default-image 占位(§3.1)。
432
+ - **Icon 组件尺寸控制铁律**:Icon 必须带 `style.rect`(`itemId:"003"` width + `itemId:"004"` height,`itemValueFrom:"0"`)——Icon 的 SVG 会跟随 `.ce_icon` 外层尺寸,没有 rect 会按 svg-symbols 默认尺寸渲染(通常 32×32),与设计稿要求尺寸(如 20×20)不一致。
433
+ - 反例:设计稿问号图标语义在 sprite 里有对应字形(`bangzhu`),却去裁切切片 PNG 走 Image 路径——多一次资源请求 + 丢矢量可控性 + 切片真实文件可能不存在导致 404。
434
+ - 决策信号:
435
+ - 图标视觉简洁(单色线条 + 语义明确)→ 优先找 sprite 字形。
436
+ - 图标视觉复杂(多色、阴影、品牌细节)→ 切片优先。
437
+ - sprite 字形清单:`grep -oE 'id="[^"]*"' vendor/preview/assets/svg-symbols.svg | sort -u`。
438
+ - 验收:选择 Icon 时 sprite 字形存在;Icon 节点 style.rect 有 width/height 且等于设计稿尺寸;DOM 中 Icon 元素 `getBoundingClientRect` 与设计稿标注一致。
439
+
440
+ ### R21 程序化构建器陷阱(Python/JS 手写 schema 生成器,2026-08-20 固化)
441
+ - 当卡片需要用脚本批量/半自动构建 schema(如 Python 构建器辅助生成)时,以下三类陷阱反复出现:
442
+ 1. **语言层「falsy 值」与业务语义冲突**:
443
+ - Python `if value:` 对 `0 / "" / None / False` 全部为假;JS `if (value)` 同理。但业务上 `flexShrink:"0"`(防压缩)、`borderRadius:"0"`(直角)都是**有效的显式设置**,不能因为 falsy 跳过写入。
444
+ - **铁律**:构建器函数里判断「是否传入某参数」用 `if param is not None:`(Python)/ `if (param !== undefined)`(JS),**不要用 `if param:` / `if (param)`**。
445
+ - 反例:`Text(value, shrink=0)` 函数里 `if shrink: add_flex_shrink(shrink)` → `shrink=0`(防压缩的本意)被跳过 → 关键文本换行(R17)。
446
+ 2. **表达式识别过宽**:
447
+ - `if '$' in value or '+' in value or '?' in value:` 这类简单字符判断会把合法静态文案误判成表达式(如「A + B 优惠」、「你有 $ 余额」),导致 `itemValueFrom:"1"`(变量绑定)被错误写入、预览空渲染。
448
+ - **铁律**:表达式识别按**最小特征集**——只在出现 `$<变量名>`(`$` 紧跟字母/下划线)或明确的 JS 表达式结构(三元 `? ... :`、`.map(`、`.slice(`、`&&` / `||`、`$index`)时判定为表达式;普通文案中的 `$` / `+` / `?` 不算。
449
+ - 或更稳的做法:构建器接受**显式参数**(如 `is_expr=True`),由调用方决定,不做字符串嗅探。
450
+ 3. **style 组装时 None 元素过滤过头或不够**:
451
+ - `style(*parts): return {"properties": [p for p in parts if p]}` —— 会把所有 falsy 元素都过滤掉,但有时一个合法的空对象(`{}` 表示「该组用默认值」)也会被过滤。
452
+ - **铁律**:过滤条件用 `if p is not None`,不要 `if p`;且组装完成后**立即跑一次 schema 校验**(`validate_schema.py`)确认结构合法,不要等到生成完所有节点再校验(早期错误会传染到下游)。
453
+ - 这是工具实现层的规则,不直接出现在最终 schema 里,但违反会导致生成的 schema 隐患重重且难以排查(症状往往在渲染时才显现)。
454
+
455
+ ### R22 width:100% 节点必须可压缩(flexShrink:1,2026-08-20 固化)
456
+ - **铁律**:节点的 `rect.width` 设为 `"100%"` 时,**必须保持默认的 `flexShrink:"1"`(可压缩),禁止显式设 `flexShrink:"0"`**。
457
+ - **根因**:`width:100%` 在 flex 布局里语义是"我希望占满主轴",但当同级有兄弟节点(尤其固定宽的图标、按钮、金额)时,100% 会先按字面占满整个父容器,再让兄弟被挤出可视区或换行。`flexShrink:"1"` 是 flex 协议的"压缩协商机制"——空间不够时 100% 节点主动让位,兄弟节点保留原始尺寸。一旦 100% 节点同时设 `flexShrink:"0"`(不可压缩),协商机制被锁死,浏览器只能挤走兄弟或触发溢出。
458
+ - **与 R17 的关系**:R17 说「关键 Text 节点要 `flexShrink:"0"` 防压缩换行」,R22 说「100% 宽节点要 `flexShrink:"1"` 让位兄弟」——**两者按 width 取值分流,互不冲突**:
459
+ - 节点 `width:auto` / `fit-content` / 未显式设宽(关键 Text 大多如此)→ R17 适用,`flexShrink:"0"` 保护。
460
+ - 节点 `width:100%`(容器、撑满分布的 Row)→ R22 适用,`flexShrink:"1"` 让位。
461
+ - **禁区的组合**:`width:100%` + `flexShrink:"0"` 同时出现 → 矛盾配置,必然挤走兄弟。
462
+ - **典型场景**:「左侧长文本(100% 撑满)+ 右侧固定宽图标」的行:
463
+ - 正确:左 `width:100%` + `flexShrink:1`(未显式即默认 1),右 `width:auto` + `flexShrink:0`,父 `space-between` → 文本撑满剩余空间、图标固定不被挤。
464
+ - 错误:左 `width:100%` + `flexShrink:0` → 文本硬占 100%、图标被挤出可视区。
465
+ - **与 §4「左右对齐行内两簇」方案 A 的关系**:方案 A「左 `width:100%+shrink:1`,右 `shrink:0`」就是本规则的正向范式实例——本规则把它从范式提炼成铁律。
466
+ - 反例:列表项标题 `width:100%` 且 `flexShrink:0` + 右侧时间戳 `width:auto` 且 `flexShrink:0` → 双方都不让 → 时间戳被挤出右侧可视区,或父容器宽度溢出。
467
+ - 验收:检查 schema 中所有 `rect.width == "100%"` 的节点,**不可**同时出现 `flex.flexShrink == "0"`;Playwright `getBoundingClientRect` 验证 100% 节点的兄弟节点 `right ≤ 父容器 right`(没被挤出)。
468
+
469
+ ### R23 百分比表达式必须 Math.round 防 JS 浮点精度(2026-08-21 固化)
470
+ - **铁律**:任何把 ≤1 的比率变量乘 100 得到百分比的表达式,**必须**用 `Math.round()` 包裹,禁止直接写 `$ratio * 100`。
471
+ - **根因**:JavaScript 使用 IEEE 754 双精度浮点数,`0.28 * 100` 的结果是 `28.000000000000004` 而非 `28`,`0.25 * 100` 结果是 `25`(恰好),`0.1 + 0.2` 结果是 `0.30000000000000004`。这不影响逻辑判断但在**文本展示**和**宽度百分比**场景产生肉眼可见的错误(如 `28.000000000000004%` 或进度条宽度小数溢出)。
472
+ - **正确写法**:
473
+ - 百分比文本:`Math.round($ratio * 100) + '%'`(itemValueFrom:"1" + itemDefaultValue 兜底)
474
+ - 进度条宽度:`Math.round($ratio * 100) + '%'`
475
+ - 多段占比合计校验:先 `Math.round()` 再比较,不直接比浮点和
476
+ - **错误写法**:
477
+ - `$ratio * 100 + '%'` → 可能输出 `28.000000000000004%`
478
+ - `($ratio * 100).toFixed(0) + '%'` → 正确但返回字符串拼接后可能丢精度,不如 `Math.round` 直观
479
+ - **验收**:在 data.json 中设置会产生浮点误差的比率值(如 0.28、0.07、0.55),渲染后检查百分比文本不含小数点后多余数字。
480
+ - 典型场景:资产分析卡的 `p_pct` 文本节点 `Math.round($ratio * 100) + '%'`;进度条填充节点宽度同理。
481
+
482
+ ### R24 auto 宽度 flex 子项紧邻固定宽兄弟时必须可压缩(2026-08-21 固化)
483
+ - **铁律**:未显式设宽(`width:auto` / 无 `rect.width`)的 flex 子项,当同行有固定宽兄弟(Canvas、Image、固定宽 Row 等)时,**必须保持 `flexShrink:"1"`(默认值),禁止设 `flexShrink:"0"`**。
484
+ - **根因**:`flexShrink:"0"` 锁死节点的不可压缩性。当 flex 容器空间不足以容纳所有子项的自然宽度之和时,设了 `flexShrink:"0"` 的节点拒绝收缩,多余空间被挤到其他子项或导致溢出。对于无固定宽的节点(如 ListLayout、Column),其自然宽度可能远超预期(ListLayout 会展开到内容宽度),加上 `flexShrink:"0"` 就会与固定宽兄弟争抢空间、重叠或溢出。
485
+ - **与 R17/R22 的关系**:三条规则按 `width` + `className` 分流:
486
+ - 关键 Text(auto/fit-content,需防换行)→ R17,`flexShrink:"0"` 保护文本完整性。
487
+ - `width:100%` 容器 → R22,`flexShrink:"1"` 让位固定宽兄弟。
488
+ - **auto 宽度容器/列表**(ListLayout、Column、Row 等非 Text 节点)→ 本条,保持默认 `flexShrink:"1"`,尤其紧邻固定宽兄弟时。
489
+ - **唯一例外**:auto 宽度节点本身是关键视觉元素且**无固定宽兄弟**(独占行)时,设 `flexShrink:"0"` 无害但无必要。
490
+ - **典型反例**:Canvas(140×140,`flexShrink:"0"`)+ ListLayout(未设宽,误设 `flexShrink:"0"`)在同一 Row → ListLayout 自然展开到 339px,与 Canvas 重叠。修正:ListLayout 不设 `flexShrink`(默认 `"1"`),收缩到 187px 正确排在 Canvas 右侧。
491
+ - **验收**:检查 schema 中所有 **未设 `rect.width`** 且同行有固定宽兄弟的节点,确认 `flex.flexShrink` 不是 `"0"`;Playwright `getBoundingClientRect` 验证各子项 `right` 不超过父容器 `right`,且子项间无重叠。
492
+
493
+ ### R25 Image 组件 itemValueFrom 三态精确映射(2026-08-21 固化,同日修正收紧)
494
+ - **铁律**:Image 组件的 `value` 属性 `itemTypeRange` 为 `"image,var"`——只有两个合法选项,`itemValueFrom` 必须精确匹配:
495
+ - **静态切片路径**(如 `/slices/icon_xxx.png`)→ `itemValueFrom: "2"`(图片/文件值)。**禁止 `"0"`(常量)**——渲染器只在 `=== "2"` 时走图片渲染逻辑设 background-image,`"0"` 被当文本常量 → 渲染空白。
496
+ - **变量绑定**(如 `$productImage`)→ `itemValueFrom: "1"`(变量/表达式)。
497
+ - **绝不可能用 `"0"`**:Image 的 `itemTypeRange` 没有 `const` 项,`"0"` 不在合法枚举内。
498
+ - **根因**:R25 初版写「`"0"` 或 `"2"` 均可」,但渲染器逻辑为 `if (itemValueFrom === '2') { /* 设置背景图 */ }`——`"0"` 不进入该分支,图片永远空白。已收紧为只允许 `"2"`。
499
+ - **itemValueFrom 全局三态**(`dsl_structure.md`):`"0"`=常量(用于 Text 文案、数字等 `const` 类型字段)、`"1"`=变量/表达式、`"2"`=图片/文件。Image 字段 `itemTypeRange: "image,var"` 对应 `"2"` 和 `"1"`。
500
+ - **验收**:① schema 中所有 `className: "Image"` 节点的 `value` 属性 `itemValueFrom` 为 `"2"`(静态路径)或 `"1"`(变量);② 渲染后 DOM 中 `.ce_image_fill` 的 `background-image` 不为 `none`。
501
+
502
+ ### R26 font lineHeight/textAlign itemId 写错(2026-08-21 固化)
503
+ - **铁律**:font 组的 lineHeight itemId 是 **007**(不是 005),textAlign itemId 是 **003**(不是 006)。005/006 在 font 组里分别是 isMaxLine/maxLine,写错会导致行高/对齐失效甚至属性串位。
504
+ - **根因**:AI 凭连续编号直觉写 lineHeight=005、textAlign=006,但 font 组 itemId 不连续(001=color, 002=fontSize, 007=lineHeight, 003=textAlign, 004=fontWeight),中间有跳号。
505
+ - **验收**:生成后跑 validate_schema.py,确认无 font.lineHeight ... itemId 005 but expects 007 报错。
506
+
507
+ ### R27 左右分布三要素公式(space-between 配方)(2026-08-21 固化)
508
+ - **铁律**:实现 space-between 左右分布时,三要素缺一不可:
509
+ 1. **父容器 Row**:justifyContent space-between + 显式 rect.width 100% + flexShrink 1
510
+ 2. **左元素**:rect.width 100% + flexShrink 1(占满可用空间但可收缩,把右侧推到最右)
511
+ 3. **右元素**:rect.width auto + flexShrink 0(按内容宽度,不可压缩)
512
+ - **根因**:平台渲染器对不设 width 的非 Text 节点会默认撑满 100%,导致两个子元素都变 100% 互相挤压。必须显式写 width auto 才能按内容宽度渲染。
513
+ - **最常见错误**:右元素不设 rect.width(以为不设等于 auto)实际撑满 100%,把左元素压成几像素,标题文字竖排换行。
514
+ - **与 R17/R22/R24 的关系**:本条是 R22 + R17 + R19 的组合配方,专门解决 space-between 场景,三要素必须同时满足。
515
+ - **典型范式**(人力卡实证 messageOverview):Row(100%, shrink:1) 内含 Row(100%, shrink:1) + Row(auto, shrink:0)
516
+ - **验收**:Playwright getBoundingClientRect 检查左元素 width > 0,右元素 right 等于父容器 right。
517
+
518
+ ### R28 平台不存在的组件类型 + 分割线必须用 Divider 组件(2026-08-21 固化,分割线部分同日修正)
519
+ - **铁律**:DSL 平台没有 View 组件。视觉装饰元素按用途分流:
520
+ - **分割线(section divider)→ 用 `Divider` 组件**(平台原生叶子组件,见 component_specs.md §Divider)。设计稿中独立于内容、横向贯穿、高 ≤2px、浅灰 fill 的分割 shape 一律用 `Divider`,**禁止用 Row 模拟**。styleState:`rect.width=100%` / `rect.height=标注高度` / `background.backgroundColor=标注 fill`。间距用 `margin.marginTop` 承载。
521
+ - **纯背景色块 / 色条 / 下划线(贴附文字的装饰条)→ 用 `Row`**(设 rect + background + borderRadius)。
522
+ - **圆角徽章 → 用 `Row` 或 `Column`**。
523
+ - **禁止**:使用 View、div、span 等 HTML 标签名或任何不在 component-meta.json 中的 className;**禁止用 Row 手写 width:100%+height:0.5+背景色 来模拟分割线**——这是 R28 旧版措辞的错误指引,已修正。分割线唯一正确组件是 `Divider`。
524
+ - **根因(含本次修正)**:R28 初版把"分割线"和"色块/背景条"混为一谈全部指向 Row,但平台有专门的 `Divider` 组件(R14、component_specs.md §Divider、spec_to_schema_patterns.md 均指向 Divider),导致 AI 按最新规则 R28 用 Row 模拟,与 R14「必须还原为 Divider」冲突。修正后 R28 明确区分:独立分割线 → Divider;贴附装饰色块 → Row。
525
+ - **验收**:① validate_schema.py 无 Unknown className;② DOM 中所有分割线节点 className 为 `Divider`(而非 Row);③ Divider 节点数量 = spec 细长 shape 数量。
526
+
527
+ ### R29 设计稿元素遗漏检测(生成前清单)(2026-08-21 固化)
528
+ - **铁律**:生成 schema 前必须从 spec.json 的 cards[0].elements[] 提取完整元素清单,逐一确认每个视觉元素都有对应 schema 节点。遗漏信号:type slice 有 rect 需对应 Image,type shape 有 fill.color 需对应 Row,type text 需对应 Text。
529
+ - **检查方法**:生成前用 spec_tree.mjs --compact 打印元素列表,数清 text/slice/shape 数量,生成后逐个核对,特别注意行尾/角落的小元素(badge、标签、图标)最容易遗漏。
530
+ - **验收**:生成 schema 的节点数应大于等于 spec.json 关键元素数(合并文本除外)。
531
+
532
+ ### R30 Icon eventaction 格式(2026-08-21 固化)
533
+ - **铁律**:Icon 的 click eventaction 必须用嵌套格式:顶层有 event(含 eventKey click)和 action(含 actionType customAction)两个对象。禁止用 eventName/actionType 扁平格式。
534
+ - **正确格式**:{ event: { eventName: "点击事件", eventKey: "click" }, action: { actionType: "customAction", properties: [{ itemId: "001", itemKey: "function", itemValueFrom: "0", itemValue: { code: "" } }] } }
535
+ - **根因**:平台 eventaction 是 event + action 分离的嵌套结构,AI 从通用 JSON 经验写成扁平 key。lint 检查的是 ea.event.eventKey === click,扁平格式没有 event 字段。
536
+ - **验收**:lint_card.mjs 无 icon-no-click ERROR。
537
+
538
+ ### R31 切图文件名含空格/特殊字符必须重命名(2026-08-21 固化)
539
+ - **铁律**:复制切图到 `src/slices/` 后,检查文件名是否含**空格、中文括号、特殊符号**(如 `矩形 4.png`、`icon (2).png`)。含则**必须重命名为纯 ASCII 安全名**(如 `矩形 4.png` → `btn_exchange.png`、`icon_arrow@2x.png` → `icon_arrow@2x.png` 保留)。schema 中 Image `value` 引用的路径必须与重命名后的文件名一致。
540
+ - **根因**:渲染器将 `value` 拼接进 CSS `background-image: url(...)` 时,空格导致 URL 断裂(浏览器解析 `url(/slices/矩形` 然后把 `4.png)` 当非法值丢弃)→ `background-image: none` → 图片空白。即使后端 HTTP server 做了 URL decode,前端 CSS url() 拼接时未编码空格。
541
+ - **处理时机**:`cp slices/*.png src/slices/` 后、写 schema 前,逐个检查文件名。安全命名规则:`小写字母_数字.png`,去掉空格和括号。
542
+ - **验收**:schema 中所有 Image `value` 的路径不含空格;渲染后 DOM 中 `.ce_image_fill` 的 `background-image` 不为 `none`。
543
+
544
+ ### R32 Image 组件必须设显式 rect.height(否则被 CSS aspect-ratio:16/9 压缩)(2026-08-21 固化)
545
+ - **铁律**:Image 组件的 `rect` 必须显式设 `height`(从 spec 标注读取),**不可省略**。仅设 `width:100%` 不够——渲染器 CSS 硬编码 `.ce_image { aspect-ratio:16/9 }`,不设高度时浏览器按 16:9 比例自动计算高度(如 width:162px → height:91px,远小于设计稿 110px),导致图片被压扁。
546
+ - **根因**:`.ce_image { aspect-ratio:16/9; display:flex }` 是预览渲染器的内置样式,`width:100%` 时浏览器据此算出 16:9 高度,与设计稿标注的实际高度无关。`aspect-ratio` 会覆盖 flex 拉伸效果。
547
+ - **处理**:每个 Image 节点的 `rect.height` 必须从 spec 的对应 slice/shape 的 `rect.height` 读取并显式写入。
548
+ - **验收**:DOM 中所有 `.ce_image` 的 `getBoundingClientRect().height` == spec 标注高度(±1px)。
549
+
550
+ ### R33 卡片根节点样式必须从 spec 卡片 bg shape 全量提取(背景/圆角/边框/阴影/透明度)(2026-08-21 固化)
551
+ - **铁律**:spec.json 中每个 `cards[]` 都有一个**卡片根背景 shape**——尺寸 == 卡片 `rect`(width/height 完全匹配)、type 为 `shape` 的元素。该元素的 `style` 是卡片容器的**全套视觉样式**,生成 schema 时必须**逐项提取并设置到根容器节点**(Root 或 cardContainer):
552
+ | spec 字段 | style 路径 | 对应 schema style 组 | itemId |
553
+ | --- | --- | --- | --- |
554
+ | `background.color` / `cardFill` | style.background.color | `background(300)`: backgroundType=01 + backgroundColor | 001, 002 |
555
+ | `radius.borderRadius` / `mask.radius` | style.radius.borderRadius | `borderRadius(600)`: borderRadiusType=0 + borderRadius | 001, 002 |
556
+ | `border.isBorder` | style.border.isBorder | `border(700)`: isBorder | 001 |
557
+ | `border.width` | style.border.width | `border(700)`: borderWidth | 002 |
558
+ | `border.style`(默认 solid) | — | `border(700)`: borderStyle | 003 |
559
+ | `border.color` | style.border.color | `border(700)`: borderColor | 004 |
560
+ | `shadow` | style.shadow | `shadow(800)`: (查 style-meta.json §shadow 组) | — |
561
+ | `opacity` | style.opacity | `opacity(900)`: (查 style-meta.json §opacity 组) | — |
562
+ - **查找方法**:遍历 `cards[].elements[]`,找到 `type=="shape"` 且 `rect.width==card.rect.width` 且 `rect.height==card.rect.height` 的元素,即为卡片根背景 shape。若有多层编组(group 包 shape),取最内层 shape(group 的 style 通常为 null,样式挂在子 shape 上)。
563
+ - **根因**:R8 只提了背景(`cardFill`)+ 圆角(`mask.radius`),完全遗漏了 border / shadow / opacity。AI 按 R8 提取了两项就停了,不会主动去找卡片 bg shape 上的其他样式字段。
564
+ - **border 组完整格式**:
565
+ ```
566
+ { "itemId": "700", "itemKey": "border", "itemValue": {}, "itemChildren": { "properties": [
567
+ { "itemId": "001", "itemKey": "isBorder", "itemValueFrom": "0", "itemValue": "1" },
568
+ { "itemId": "002", "itemKey": "borderWidth", "itemValueFrom": "0", "itemValue": "0.5" },
569
+ { "itemId": "003", "itemKey": "borderStyle", "itemValueFrom": "0", "itemValue": "solid" },
570
+ { "itemId": "004", "itemKey": "borderColor", "itemValueFrom": "0", "itemValue": "#FFFFFF" }
571
+ ]}}
572
+ ```
573
+ - **禁止**:① 只提取 background + borderRadius 而漏掉 border/shadow/opacity;② 手动凭感觉设根样式而不读 spec;③ 看到 `border.isBorder: true` 却忽略不设。
574
+ - **验收**:① schema 根容器节点的 style 组数量 == spec 卡片 bg shape 有值的 style 字段数;② DOM 中根容器 `getComputedStyle` 的 `backgroundColor`/`borderRadius`/`borderWidth`/`borderColor` 与 spec 标注逐项一致。
575
+
576
+ ### R34 生成器出口必须做渲染契约归一化(2026-08-24 训练固化)
577
+ - **铁律**:`spec_to_schema_v3.mjs` 的 `generate()` 返回前调用 `normalizeRenderContract()`:`Text` / `Icon` / `Image` / `MultiText` 必须有 `flex.flexShrink=0`;`Icon` 必须有嵌套 `click` eventaction;组件树中禁止出现 `null` 子节点。
578
+ - **根因**:逐段组装时容易漏掉通用契约;尤其是列表箭头 slice 命中但 PNG 未导出时,`imageFromSlice()` 返回 `null` 仍被放入插槽,导致运行期渲染挂起。
579
+ - **处理**:契约归一化放在生成器出口,而不是依赖训练器或人工修复;可选 slice 为空时必须提供可见占位或 Icon 兜底。
580
+ - **验收**:`validate_schema.py` 0 ERROR、`lint_card.mjs` 0 ERROR、递归扫描 schema 无 `null` 子节点,独立 Chrome 渲染能进入 `data-card-ready`。
581
+
582
+ ### R36 语义组件由 Agent 裁决,脚本不得业务硬编码(2026-08-25 固化)
583
+ - **铁律**:脚本只输出几何、标注和渲染证据;`display-value/input/action/list/media` 等组件语义由 Agent 结合截图与层级树裁决。禁止用“还款”“账单”等业务词触发组件选型。
584
+ - **通用信号**:货币符号 + 数值 + 右侧编辑/箭头控件 → 金额输入候选;完整业务容器 + 标题/内容主体 → 卡片候选;遮罩/关闭/toast → 弹层交互,不按普通卡还原。
585
+ - **验收**:同一规则换成新业务文案仍成立;schema 中无非 DSL 语义字段;lessons 记录证据案例。
586
+
587
+ ### R37 源文本单一消费,禁止重影(2026-08-25 固化)
588
+ - **铁律**:每个源文本只能进入一个语义块;按钮、列表标题、主金额、辅助文案建立互斥消费集合。
589
+ - **根因**:按钮壳和按钮文案分别被 action/listTitle 消费时,会出现按钮下方重复文本或标题误判。
590
+ - **验收**:渲染截图无重复文案;schema 中每个字面值/绑定可追溯到唯一 spec 源元素;列表标题不得是按钮文案。
591
+
592
+ ### R38 容器高度由内容撑开(2026-08-25 固化)
593
+ - **铁律**:Root、卡片容器、列表容器和普通 Row/Column 用 `height:auto`;纵向尺寸来自子内容、gap 和标注 padding。
594
+ - **例外**:Input、Image、Icon、Divider、Canvas 等叶子控件可读标注高度;Canvas 绘图控件按绘制直径设置。
595
+ - **验收**:内容行数变化时不裁切;渲染高度与设计稿比例偏差在评分门禁内;禁止为了对齐截图写死整卡高度。
596
+
597
+ ### R39 几何判定必须消费原始标注(2026-08-26 训练固化)
598
+ - **铁律**:`sameRow`、overlap、距离计算只能消费带 `rect` 的源元素,或显式携带 `sourceEl` 的语义投影。禁止把已经展开成 `{x,y,width}` 的投影对象再传给依赖 `rect()` 的函数。
599
+ - **根因**:辅助文本投影丢失 `rect` 后,`rect().y` 全部回退为 0,导致不同 y 的标题、日期和金额标签被合并成同一行。
600
+ - **验收**:同一语义分组内任意两个源元素的 y 差必须满足阈值;探针必须包含“同行标题 + 下方居中标签”的结构。
601
+
602
+ ### R40 顶层语义块按视觉 y 排序(2026-08-26 训练固化)
603
+ - **铁律**:panel、option-group、primary-amount、sub-amount、form、button 等顶层块注册标注 y 后按 y 插入;纵向 padding 由相邻块边界推导。重叠块间距为 0,计算当前块间距时必须排除自身边界。
604
+ - **禁止**:按代码段落顺序直接 append;用固定 section padding 补偿乱序;为了高度相似写死整卡高度。
605
+ - **验收**:schema 顶层子节点 y 单调不递减(重叠容器按标注边界记录);渲染顺序与设计稿一致。
606
+
607
+ ### R41 主金额片段不得复用为组标签(2026-08-26 训练固化)
608
+ - **铁律**:货币符号和数值合成主金额后,该片段从 option-group label 候选中互斥排除;label 必须在主金额矩形外,且不是合成金额文本的组成部分。
609
+ - **根因**:`¥` 被同时消费为主金额前缀和选项组标签,造成金额重影。
610
+ - **验收**:主金额、组标签、选项成员在 schema 中可追溯到不同源元素;渲染文本无重复。
611
+
612
+ ### R42 列表带内分隔线不提升为顶层块(2026-08-26 训练固化)
613
+ - **铁律**:细长分隔线若落在重复媒体行或列表项的纵向带内,由重复项模板或列表容器承载;只有带外通栏分隔线才作为独立 divider 渲染。
614
+ - **根因**:列表项之间的 divider 被提升为顶层块后,把列表项撑散、箭头插错位置,甚至挤掉后续内容。
615
+ - **验收**:重复媒体行/ListLayout 的项间距来自模板;独立 divider 只出现在列表或重复带外。
616
+
617
+ ### R43 重复行控件必须归入模板(2026-08-26 r039n 固化)
618
+ - **铁律**:同一右缘、同尺寸、等距重复的小控件是重复行模板的一部分;ListLayout/重复媒体模板消费后,原始控件不得再进入孤立媒体块。已消费的副金额 label/value 也必须从列表标题候选互斥排除。
619
+ - **根因**:列表模板已复用右缘箭头后,三个源箭头又被兜底成孤立媒体块;副金额值因字号和下方文本数量误判成列表标题,分别造成纵向膨胀和重影。
620
+ - **验收**:ListLayout 渲染 N 行时只出现 N 个模板控件;schema 中同一源元素只映射到一个语义块;按钮后不得出现被面板消费的金额文本。
621
+
622
+ ### R44 语义间距只计一次(2026-08-26 r039n 固化)
623
+ - **铁律**:相邻语义块的标注间距由统一边界表推导,不得在上一块底部和下一块顶部重复添加;列表标题、列表项、查看更多必须注册边界。列表行内边距用“标注行高 - 内容高”推导,ListLayout 行间距显式归零。
624
+ - **根因**:列表语义缺失边界时,按钮误算到卡底的大留白;列表模板默认行距与项内 padding 叠加,导致内容撑出设计稿高度。
625
+ - **验收**:DOM 顶层块顺序与标注 y 一致;内容变化时容器继续 auto 撑开;渲染总高不因固定行距或重复间距超过标注比例门禁。
626
+
627
+ ### R45 分割线必须是原生 Divider(2026-08-26 r050n 固化)
628
+ - **铁律**:独立分割线用 `Divider` 组件承载,逻辑高度固定为 `1px`,颜色优先读标注填充;重叠去重阈值使用 `>=0.4` 的纵向覆盖比例。
629
+ - **根因**:细线被兜底成普通 Image 后按倍率放大或与半像素线重复输出,视觉上变成粗线/重影。
630
+ - **验收**:schema 中带外独立细线只有一个 `Divider`;渲染 DOM 高度为 `1px`;同位置无第二条可见线。
631
+
632
+ ### R46 缺失切图按画板裁切优先(2026-08-26 r050n 固化)
633
+ - **铁律**:缺失导出的媒体优先从原画板按标注矩形裁切为 `cropSlice`;裁切失败或切片视觉与画板局部不一致时才使用 `http://iph.href.lu/{w}x{h}?text=缺切图|切图冲突` 占位图。禁止退化为纯色块冒充图片。
634
+ - **根因**:设计稿可能漏导切图,纯色会丢失图像结构;直接占位又浪费画板中已有的真实视觉证据。
635
+ - **验收**:`spec.json` 缺导出项携带 `annotationDefects.resolution=artboard-crop` 与 `cropSlice`;生成器优先引用裁切文件;小切片用 alpha mask IoU 校验,低于 `0.35` 记录 `slice-visual-mismatch`。
636
+
637
+ ### R47 面板流高裁剪必须有界(2026-08-26 r050n 固化)
638
+ - **铁律**:只有轻微重叠才允许把面板流式高度截到下一个重叠顶边,阈值为 `max(16px, 面板高度 * 25%)`;列表面板和大幅重叠保持完整高度。
639
+ - **根因**:无界裁剪会让头部面板压低主金额;完全不裁剪又会保留跨面板的幽灵留白。
640
+ - **验收**:轻微重叠卡的主金额 y 回到标注范围;列表面板不被压缩;整卡高度继续由内容撑开。
641
+
642
+ ### R48 文本禁止压缩,辅助留白随对齐变化(2026-08-26 r050n 固化)
643
+ - **铁律**:所有 `Text` 节点统一设置 `flexShrink:0`;居中文本的辅助 padding 只加上下,不加左右;右对齐加右侧,左对齐加左侧。
644
+ - **根因**:文本被挤压换行或截断后还原度失真;对称侧向 padding 又会把右值和左标签推出标注列。
645
+ - **验收**:递归 schema 无可压缩 Text;长文案不横向压缩;居中、左对齐和右对齐辅助文本的偏移方向与标注一致。
646
+
647
+ ### R49 列表行 padding 禁止 NaN(2026-08-27 r052 固化)
648
+ - **铁律**:`T.pad('micro')` 等 token 引用必须确认键存在于对应 token 表(`PADDING` 表有 `micro`,`GAP` 表也有 `micro`);消费端用 `parseInt(val, 10) || 0` 防御性兜底。`Math.max(NaN, x)` 恒为 `NaN`,会导致 padding 静默失效。
649
+ - **根因**:`PADDING` 表缺少 `micro` 键,`T.pad('micro')` 返回 `'undefined'`,`Number('undefined')` = `NaN`,使列表行 padding 全部为 `NaN`,行高坍塌。
650
+ - **验收**:所有 `T.pad/T.gap` 调用的键在对应 token 表中存在;`parseInt` 兜底确保非负整数;列表行 padding 不为 `NaN` 或 `undefined`。
651
+
652
+ ### R50 列表项语义边界用实测行高(2026-08-27 r052 固化)
653
+ - **铁律**:列表项的语义边界 bottom 必须用 `item.rowHeight`(相邻项 y 差)或 `item.contentHeight`,禁止硬编码 `56`。最后一项的 `rowHeight` 继承前一项的值(因为无下一个项可算差值)。
654
+ - **根因**:硬编码 `56` 与实际行高(常为 72px)不符,导致列表后续区块(查看更多等)的 `semanticTopGap` 偏移 16px+。
655
+ - **验收**:`semanticBounds` 中列表项的 `bottom - top` 等于实际行高;无硬编码行高值;最后一项不退化为 contentHeight 导致高度偏小。
656
+
657
+ ### R51 垂直节奏优先用 padding 而非 lineHeight(2026-08-27 r052 固化)
658
+ - **铁律**:控制元素垂直位置时,优先通过容器的 `paddingTop/paddingBottom` 调整,不设 `lineHeight`。渲染器文字行高约 `fontSize × 1.4`,设计稿 `rect.height` 比率在 1.27-1.50 间波动;用 padding 补偿比改行高更稳定,不会引起内容重新分布。
659
+ - **根因**:设 `lineHeight` 会导致简单卡片的内容被重新分配到整个卡片高度(flex 重新计算),造成布局坍塌。padding 只影响容器间距,不触发 flex 重新分布。
660
+ - **验收**:schema 中 `Text` 节点不设 `lineHeight`(保持默认);区块间距通过 `paddingTop` 从 `semanticTopGap` 推导;渲染内容带 y 位置与设计稿在 ±4px 内对齐。
661
+
662
+ ### R52 语义边界高度取渲染器行高与设计稿的较大值(2026-08-27 r052 固化)
663
+ - **铁律**:文本类语义边界的 `bottom` 取 `max(rect.height, fontSize × 1.4)`,不单用设计稿 `rect.height`。渲染器行高固定为 `fontSize × 1.4`,设计稿 `rect.height` 比率在 1.27-1.50 间波动;当设计稿比率 < 1.4 时,渲染器实际行高 > 设计稿高度,若语义边界只用 `rect.height`,间距计算会偏小,导致后续区块累积下移。
664
+ - **根因**:`semanticTopGap(y) = y - previousSemanticBottom`,当 `previousSemanticBottom` 用 `rect.height` 算(比渲染器实际行高小),间距偏大,内容带位置逐区块偏移,rowStructure 下降。
665
+ - **验收**:含 10+ 文本区块的卡片,渲染内容带 y 位置与设计稿在 ±4px 内对齐;rowStructure ≥ 0.5;无累积偏移。
666
+
667
+ ### R53 组件计数口径对齐(2026-08-27 r052 固化)
668
+ - **铁律**:`schemaComponents` 和 `expectedComponents` 的媒体计数口径必须一致。容器节点引用了 `backgroundImage` 时计入 media(对齐设计稿中 `slice` 类型);设计稿中 symbol 只是表单行容器壳(含 label+value 文本对,高度 <60px)时,不计入 expected media。
669
+ - **根因**:结果状态卡的"弥散"背景以 CSS `backgroundImage` 引用 PNG 切图,`schemaComponents` 未计入 media;设计稿中 3 个"内容-卡片" symbol 实际是表单行容器壳,`expectedComponents` 误计为 media。双向偏差导致 components fidelity 从 1.0 跌到 0.67。
670
+ - **验收**:结果状态卡(成功/失败/弥散背景)的 components fidelity ≥ 0.89;`backgroundImage` 容器被计为 media;表单行 symbol 容器壳不被计为 expected media。
671
+
672
+ ### R54 同框控件层只允许一次语义消费(2026-08-27 r053 固化)
673
+ - **铁律**:MeaXure 会把同一按钮/面板导出为 symbol、group 和兜底 shape 多层。聚焦产物先按“同类型 + 同框”去重;下游语义块必须按源元素实例互斥消费。
674
+ - **验收**:完全重叠的控件只渲染一次;渲染截图无重影;同一源文本不得同时进入两个语义块。
675
+
676
+ ### R55 状态卡媒体使用邻域占位(2026-08-27 r053 固化)
677
+ - **铁律**:居中孤立媒体若上下都有语义块,媒体保留真实高度;其行容器通过上下 padding 共同承接前后语义块间的几何空隙,不得把媒体自身放大到邻域高度。
678
+ - **验收**:状态卡尺寸保持标注比例;视觉中心媒体比例不变形;后续文案位置与相邻标注边界一致。
679
+
680
+ ### R56 列表标题间距拆分到上下 padding(2026-08-27 r053 固化)
681
+ - **铁律**:列表标题与首行的标注间距按语义边界计算后,先扣除标题上方 padding,再分配给标题下方 padding;标题语义高度取 `max(rect.height, fontSize × 1.4)`。
682
+ - **验收**:标题前后位置由相邻标注边界推导;不再默认叠加 `section` padding;列表卡 rowStructure 不因标题行盒累计偏移下降。
683
+
684
+ ### R57 弥散与不规则纹理必须按位图还原(2026-08-27 r055 固化)
685
+ - **铁律**:弥散、光晕、噪点和不规则纹理不是基础组件可安全近似的 CSS 渐变。标注存在对应 slice 时必须引用切图;缺失切图时先从画板局部裁切,最后才允许占位图。
686
+ - **根因**:把弥散位图误描述为“渐变容器”会诱导生成器退回纯色或规则渐变,边缘光斑丢失且随主题色失效。
687
+ - **验收**:schema 背景为 `backgroundType:"02"` + 切图或裁切图;只有标注明确提供色标和方向的规则渐变才可用 `backgroundGradient`。
688
+
689
+ ### R58 ListLayout 显式属性与模板字号继承(2026-08-27 r055 固化)
690
+ - **铁律**:ListLayout 运行时属性名是 `row-spacing` / `edge-insets`;必须显式写 `0`,不能依赖默认值。列表标题、描述和金额模板继承首项标注的字号、字重和颜色,行内上下 padding 用行壳顶、标题顶、内容行盒和 Divider 高度推导。
691
+ - **根因**:`rowSpacing` 会被组件归一化到默认 12px;模板替换成主题字号后,内容盒和行距同时失真。
692
+ - **验收**:渲染检查中相邻列表项顶距等于行壳 pitch;标题/描述字号与标注一致;容器高度由内容撑开,无整行或整卡写死高度。
693
+
694
+ ### R35 多子容器全叶子 flexShrink:0 溢出风险(2026-08-28 固化)
695
+ - **铁律**:受外宽约束(`rect.width` 非 `auto`)的 Row/Column 容器有 **2 个及以上并列子节点**时,**禁止全部子节点设 `flexShrink:"0"`**——至少一个子节点必须保持 `flexShrink:"1"`(可压缩)。当外容器宽度变化时,全部定宽子节点的宽度累加可能超过 100% 导致溢出;至少一个可压缩子节点能吸收空间变化,保护整体布局。`width:"auto"` 的内容自适应容器以自身内容定宽,其内部固定子元素可以全部 shrink:0。
696
+ - **根因**:R17 无差别要求所有叶子节点(Text/Icon/Image)设 `flexShrink:"0"`,本意是防文本换行/图标变形。但在多子并列容器中,所有子节点都 shrink:0 → 全部刚性 → 无弹性空间 → 外宽缩小时必然溢出。R17 保护的「单子容器中关键文本防换行」与 R35 管的「多子容器防溢出」是两个不同场景。
697
+ - **分流规则**:
698
+ - **单子容器**(parent 只有 1 个子节点)→ R17 适用,叶子设 `flexShrink:"0"` 保护内容不换行。
699
+ - **受外宽约束的多子容器**(parent 有 2+ 并列子节点且 width 非 auto)→ **至少一个子节点 flexShrink:1**;固定尺寸小元素(Icon 32×32、小 Image)可以 shrink:0,但"主内容"子节点(承载文本的 Column/Row/Text)必须可压缩。
700
+ - **内容自适应容器**(parent width 为 auto/未设置)→ 不强制 R35;右侧 `auto+shrink:0` 组内的 Text+Icon 都保持刚性是正确形态。
701
+ - **space-between 对**(R27)天然满足——左侧 shrink:1 + 右侧 shrink:0,有且仅有一个可压缩。
702
+ - **lint 实现**:`lint_card.mjs` 新增 `r35-multi-child-all-shrink0` 检查——遍历所有 Row/Column,统计并列子节点数 ≥2、自身 width 非 auto 且全部 flexShrink:0 → ERROR。同时 R17 检查收窄为仅对单子容器中的叶子生效(多子容器中的叶子由 R34 管,不重复报 R17)。
703
+ - **验收**:① schema 中每个 2+ 子节点的 Row/Column 至少有一个子节点 flexShrink ≠ "0";② lint_card.mjs 0 ERROR。
704
+
705
+ ### R42 标题+装饰条重叠必须用 AbsoluteLayout,禁止负外边距(2026-09-02 固化)
706
+ - **铁律**:当标题文本与下方装饰条(下划线/高亮条)在视觉上紧贴或重叠时,必须用 **AbsoluteLayout + position.top** 实现绝对定位,**禁止用负 marginTop**。
707
+ - **根因**:负 marginTop 在 flex 流式布局中会导致后续兄弟节点位置计算偏差、容器高度塌缩、间距连锁错乱。AbsoluteLayout 的绝对定位让标题和装饰条各自独立定位,互不干扰流式布局。
708
+ - **正确范式**(export-proven:myLoan / loanCompare / pointsDetail / memberLevelNone / integralCouponList):
709
+ ```
710
+ AbsoluteLayout(align:BottomLeft, height=round(fontSize*1.4))
711
+ ├─ Row#underline: position.top=round(fontSize*1.4)+gap, position.left=0
712
+ │ rect.width=$title.length*fontSize, height=8(或标注值)
713
+ │ background=标注色(常见品牌色@20%透明)
714
+ └─ Text#title: position.top=0, position.left=0
715
+ ```
716
+ - `align:BottomLeft` 让后续兄弟节点从标题底部开始排列(不感知装饰条溢出)。
717
+ - **子节点顺序必须是 [装饰条, 标题]**:装饰条先绘制、标题后绘制,保证文字覆盖在下划线上方;顺序颠倒会把标题压住。
718
+ - `height=round(fontSize*1.4)` = 渲染器标题行高(非 rect.height)。
719
+ - 下划线宽度用表达式 `$titleVar.length * fontSize` 随标题文字等宽。
720
+ - 完整 recipe snippet 见 `recipe_snippets/title-underline-overlay.json`。
721
+ - **lint 实现**:`lint_card.mjs` 新增 `r38-negative-margin` 检查——遍历所有节点的 marginTop,值为负数 → ERROR;同时检查标题+装饰条拓扑:缺 `align:"BottomLeft"` 或装饰条排在标题之后 → ERROR,装饰条宽度未绑定标题长度表达式 → WARN。lint 编号 R38 对应 pitfalls R42。
722
+ - **验收**:① schema 中无任何节点 marginTop 为负值;② 标题+装饰条用 `AbsoluteLayout(align:"BottomLeft")` 包裹;③ 子节点顺序为 [装饰条, 标题];④ 装饰条宽度绑定标题长度表达式;⑤ lint_card.mjs 0 ERROR。
723
+
724
+ ### R43 卡片背景不透明铁律(2026-09-02 固化)
725
+ - **铁律**:卡片背景**不存在透明的情况**。Root(view)或首层容器必须有明确的非透明背景色。
726
+ - **根因**:卡片透明时,设计器预览背景(浅灰)与实际运行环境背景不一致,导致文字在某些场景不可读、视觉对比度不足。
727
+ - **取色优先级**:
728
+ 1. **首选**:从设计稿标注 `spec.cards[].cardFill` 获取背景色(写入 Root/首层容器的 `background.backgroundColor` + `backgroundType:"01"`)。
729
+ 2. **兜底**:标注缺失时,从聚焦截图(`card-1.png`)的卡片主体区域**中心采样**取色。
730
+ 3. **禁止**:使用透明(`backgroundType:"00"` 或缺省);禁止用画布灰底;禁止从透明化截图四角/边缘采样(聚焦图几何外已透明,见 rules.md §九)。
731
+ - **lint 实现**:`lint_card.mjs` 新增 `r43-card-transparent-background` 检查——Root 的 background 组缺失、或 backgroundType 为 "00"/空、或有 backgroundType 但缺 backgroundColor → ERROR。
732
+ - **验收**:① lint_card.mjs 对该规则 0 ERROR;② 渲染截图卡片背景为实色(非透明)。
733
+
734
+ ### R44 类型+值成对检查(borderRadius/border/shadow 的类型开关必须配值)(2026-09-02 固化)
735
+ - **铁律**:样式系统中存在「类型开关 + 值」成对出现的样式组——设了值但缺类型开关,渲染器默认类型为空,值被**静默丢弃**。
736
+ | 样式组 | 类型开关 | 值 | 缺类型开关的后果 |
737
+ |---|---|---|---|
738
+ | background(300) | `backgroundType` | `backgroundColor` | 渲染透明(已有 backgroundType 自动补,见 expand_ir) |
739
+ | borderRadius(600) | `borderRadiusType` | `borderRadius` | **无圆角**(值被忽略,渲染直角) |
740
+ | border(700) | `isBorder` | `borderColor`/`borderWidth` | **无边框** |
741
+ | shadow(800) | `isShadow` | `shadowColor` | **无阴影** |
742
+ - **根因**:渲染器 StyleParser 按 `itemType` 分支解析,类型为空时跳过该组所有子项赋值。`expand_ir.mjs` 已对 `background` 和 `borderRadius` 做自动补类型,但存量卡和手写 schema 仍可能遗漏。
743
+ - **lint 实现**:`lint_card.mjs` 新增 `r44-*` 系列——遍历所有节点的 borderRadius/border/shadow 组,有值但缺类型开关 → ERROR。
744
+ - **expand_ir 自动补**:`expand_ir.mjs` 对 `borderRadius.borderRadius` 自动补 `borderRadiusType:"0"`,对 `border.borderColor` 自动补 `isBorder:"1"`,对 `shadow.shadowColor` 自动补 `isShadow:"1"`。
745
+ - **验收**:① lint_card.mjs 对 r44-* 系列 0 ERROR;② 渲染截图圆角/边框/阴影均可见。
746
+
747
+ ### R45 元素宽度必须实测,禁止靠直觉假设默认行为(2026-09-02 固化)
748
+ - **铁律**:容器/控件需要精确尺寸时,**必须从设计稿标注或截图像素扫描获取宽度,禁止靠直觉猜测或依赖渲染器默认值**。
749
+ - **根因**:Row 默认 `width:100%` 是最常见陷阱——需要收窄的按钮/标签/胶囊必须显式设固定宽度,否则撑满整行。`auto` 在某些场景也被渲染器解释为 100%,不等于内容自适应。
750
+ - **取值优先级**:
751
+ 1. **首选**:设计稿标注 `element.rect.width`(精确像素值)。
752
+ 2. **兜底**:标注缺失时,从聚焦截图(`card-1.png`)像素扫描该元素的精确宽度(按颜色边界检测)。
753
+ 3. **禁止**:用 `auto` 或 `100%` 假设会自动收窄;凭直觉写死一个「看起来差不多」的数字。
754
+ - **验收**:渲染截图中每个需要精确宽度的元素与设计稿像素级对齐;lint 无 width:100% + flexShrink:0 冲突(R22)。
755
+
756
+ ### R46 装饰元素尺寸优先表达式化,与文本内容联动(2026-09-02 固化)
757
+ - **铁律**:装饰条/高亮条/下划线等与标题文本**视觉联动**的元素,宽度应**绑定表达式**(如 `$title.length * fontSize`)而非写死固定像素。高度从设计稿截图实测。
758
+ - **根因**:写死固定宽度无法适应标题文字变化(3字 vs 5字标题),导致装饰条与标题不对齐。表达式绑定让装饰条随标题等宽伸缩。
759
+ - **范式**:下划线 width = `$titleVar.length * titleFontSize`(字数 × 字号),height = 标注值或截图实测值。颜色读标注(常见品牌色 20% 透明)。
760
+ - **验收**:标题文字变化时装饰条等宽跟随;渲染截图中装饰条宽度与标题文字宽度对齐。
761
+
762
+ ### R47 视觉迭代必须先像素分析再动手改(2026-09-02 固化)
763
+ - **铁律**:视觉闭环迭代时,**先用像素级扫描确认差异根因(元素 y 坐标偏差、高度差异、颜色采样对比),再针对性修改**。禁止盲目改间距而不先测量。
764
+ - **根因**:不测量就改间距会导致「修了一个偏差引入另一个」——例如修了下划线高度但没调偏移,反而更偏;修了宽度但没查默认 padding,高度反增。
765
+ - **标准流程**:
766
+ 1. 渲染截图 vs 设计稿截图 → 像素级 band diff 分析(哪些 y 区间差异最大)。
767
+ 2. 对关键元素采样颜色(D=设计稿 RGB vs R=渲染 RGB),标注 Δ 差值。
768
+ 3. 检测元素 y 坐标偏移(渐变区域 top 差、按钮 top 差),找出级联偏移根因。
769
+ 4. 针对性修改 → 重渲染 → 再对比,直到 match > 85%。
770
+ - **工具**:`iterate.mjs` 一条龙输出 pixelDiff.match 百分比 + lint.errors 计数;像素分析用 PIL/numpy 扫描。
771
+ - **验收**:每轮迭代有量化指标(match% / Δy / Δcolor),不做盲改。
772
+
773
+ ### R48 根节点核心样式属性默认值(2026-09-02 固化)
774
+ - **铁律**:**根节点(view/Root)** 的 gap、background、padding、borderRadius 这四个核心属性,若不设置,必须填入显式默认值。**子节点不在此次约束范围内**——子节点样式由 IR 按需设置,不自动补默认值。
775
+ - **默认值口径(仅根节点)**:
776
+ | 属性 | 默认值 | 含义 |
777
+ |---|---|---|
778
+ | flex.gap | "0" | 子元素间距为 0 |
779
+ | background | 透明(backgroundType:"00") | 无背景色(R43 会强制要求实际不透明) |
780
+ | padding | 全 0(paddingType:"1" + 四边=0) | 内边距为 0 |
781
+ | borderRadius | 无(borderRadiusType:"0" + borderRadius:"0") | 无圆角 |
782
+ - **expand_ir 实现**:`ensureRootDefaults(schema.view)` 在展开后只对根节点自动补入缺失的核心样式默认值。
783
+ - **验收**:展开后的 schema 中根节点有 background/borderRadius/padding 组。
784
+
785
+ ### R49 inputParams 必填字段完整性(2026-09-02 固化)
786
+ - **铁律**:`dictionary.inputParams[]` 每项必须包含完整 7 个字段:`key`、`name`、`type`、`defaultValue`、`desc`、`rule`、`children`。
787
+ - **模板格式**:
788
+ ```json
789
+ {
790
+ "key": "",
791
+ "name": "",
792
+ "type": "",
793
+ "defaultValue": "",
794
+ "desc": "",
795
+ "rule": { "type": "", "options": {} },
796
+ "children": []
797
+ }
798
+ ```
799
+ - **字段语义**:
800
+ - `name`:该字段的**中文名**(如 `key="loanName"` → `name="贷款名称"`),缺省时用 key 兜底。
801
+ - `rule`:空值时为 `{ "type": "", "options": {} }`(不是 `{}`,必须有 type 和 options 两个子键)。
802
+ - `children`:空值时为 `[]`(不是 null 或缺省)。
803
+ - `desc`:空值时为 `""`。
804
+ - **expand_ir 实现**:`normalizeInputParams()` 在展开后自动补全缺失字段。
805
+ - **validate 实现**:`validate_schema.py` 检查每个 inputParam 是否包含全部 7 个必填字段,缺失 → ERROR。
806
+ - **验收**:`validate_schema.py` 对所有卡片 0 ERROR。
807
+
808
+ ## 10. 子卡回传参数必须按需裁剪,父卡回调不得整体赋值(R50,2026-09-03 固化)
809
+
810
+ > **实测案例**:`transfersjump/row_2d` 点击 `accountCardList` 选卡行,原代码 `that.state.currCard = tmp.currCard` 把子卡回传对象整体挂到父卡 `currCard`,结果父卡 `currCard` 缺 `acctNum`/`branchNodeName`/`balance`/`_index`,显示绑定 `$currCard.xxx` 对不上。根因:子卡 `closeAlertCard` 回传 `data: this.state`(整个子卡作用域,含父卡注入的 `list`/`title`/`parentInstanceId`),父卡再整体赋值必然字段错乱。**不是预览器 `setData` 缺陷。**
811
+
812
+ ### 双端契约(生成事件代码默认遵守)
813
+ - **子卡(closeAlertCard)**:`data` 必须**显式构造、只含父卡需要的字段**,命名清晰(如 `selected:{acctNum,branchNodeName,balance}`)。**禁止 `data: this.state`**——会把整个子卡作用域 + 父卡注入的 payload 一起甩给父卡。
814
+ ```javascript
815
+ ynet.callJSAPI('closeAlertCard', {
816
+ data: { selected: { acctNum: this.state.acctNum, branchNodeName: this.state.branchNodeName, balance: this.state.balance } }
817
+ }, function () {});
818
+ ```
819
+ - **父卡(alertCard 回调)**:**按字段显式提取**再赋值,**绝不直接 `that.state.xxx = res.data` / `that.state.xxx = res.data.currCard` 整体赋值**。
820
+ ```javascript
821
+ ynet.callJSAPI('alertCard', { cardCode: 'accountCardList', data: {...}, parentInstanceId: event.instanceId }, function (res) {
822
+ if (res.success && res.data && res.data.selected) {
823
+ that.state.currCard = {
824
+ acctNum: res.data.selected.acctNum,
825
+ branchNodeName: res.data.selected.branchNodeName,
826
+ balance: res.data.selected.balance
827
+ };
828
+ that.setData(that.state);
829
+ }
830
+ });
831
+ ```
832
+ - **调试日志用值比对**:Console 里 `tmp.currCard`(裸对象)与 `that.state.currCard`(经 `rt.state` 读到的 `reactive` Proxy)展开长得不一样是正常的;要肉眼确认用 `JSON.stringify` 比对值,不要被 Proxy 表象误判"没更新"。
833
+
834
+ ### 为什么整体赋值会错(机制)
835
+ - 运行时 `rt.state` 是 Vue `reactive`:嵌套对象赋值会被自动包一层 **Proxy** 再存,父卡 `that.state.currCard` 读到的是 Proxy 而非裸对象。
836
+ - 子卡 `this.state` 作用域里混有父卡经 `alertCard` 传入的 `list`/`title`/`fullAccount`/`parentInstanceId` 等 payload,整体回传会让父卡 `currCard` 既缺选中卡字段、又混入无关字段。
837
+ - `setData` 本身无缺陷(浅合并 + 自增 revision 触发重渲染,原地改 `rt.state` 不重赋值引用);参数传递失败是**代码赋值选型问题,不是预览器 bug**。
838
+
839
+ ### 验收
840
+ - 子卡 `closeAlertCard` 回传对象无 `list`/`title`/`parentInstanceId` 等父卡注入字段;父卡回调里找不到 `that.state.xxx = res.data.currCard` 这类整体赋值。
841
+ - 选中后父卡 `$currCard.xxx` 显示绑定字段齐全且值正确(事件面板用 `JSON.stringify` 核对)。
842
+ - 关联范本:`references/event_patterns.md` alertCard/closeAlertCard 段、`references/recipes.md` §2。
843
+
844
+ ---
845
+
846
+ ## 11. 语义装配几何纪律(r169-r171,2026-09-06 固化,门禁全绿:passRate 1.0 / avgPix 0.0406)
847
+
848
+ > 来源:喜豆批次训练逐案例归因。以下全部由生成器自动执行;手写/手改卡片时同样适用。
849
+
850
+ ### 11.1 列表项模板钉壳高
851
+ - 奇数字号自然行盒是 .5 量化(fs15→22.5pt),paddingBottom 只能取整 → 每行 ±0.5px 误差在列表纵向堆叠中逐行累积(item2 -0.5、item3 -1,3 行后肉眼可见错位)。
852
+ - **规则**:非复合列表行的 itemTpl 显式钉 `rect.height = spec 行高中位数`(仅在内容估算不超壳高、有底距余量时钉,防裁切);空隙落在底部 padding 区不可见。复合金额行不钉。
853
+
854
+ ### 11.2 列表项标题→副行纵距取标注中位
855
+ - 设计稿行距并非常量,统一 `tight(4)` 会把副行压偏 +2px/项。
856
+ - **规则**:纵距 = `desc.y - (title.y + 渲染行盒高 fs×1.5)`,逐行取样取中位数,作 leftCol 的 gap。
857
+
858
+ ### 11.3 aux 单簇行:flex-start + 无右 padding
859
+ - 同组 aux 行(如「营业 tag + 距您986m」)聚簇后只剩 1 簇时,`space-between` 退化为左对齐,此时右 padding 不参与定位,**只会把内容盒算窄裁切尾字符**(曾把「距您986m」裁成「距您986」)。
860
+ - **规则**:单簇行 `justify:flex-start` 且 `paddingRight:0`;≥2 簇才用 space-between + 右 padding 钉右沿。
861
+
862
+ ### 11.4 壳边沿测量(带背景/描边壳的元素)
863
+ - 状态标签类的壳(如绿底「营业」)比文本层宽(壳 32pt / 文本层 24pt)。行宽、左右 padding、簇内间隙**按文本层边沿测量会推偏相邻元素 4-8px**。
864
+ - **规则**:`visualLeft = min(text.x, shell.x)`,`visualRight = max(textRight, shellRight)`;行 padding、簇内 spacer、聚簇判定全部用可视边沿。
865
+
866
+ ### 11.5 标题 + 右侧小按钮跨行块
867
+ - 按钮竖直跨度越过标题行底沿、且与下方行(标签行)重叠时,按钮实际居中于「标题+标签」整块(实测:按钮中心 y36 == 块中心 (14+58)/2=36)。行内挂载会把标题行撑高到按钮高(24→30),**行以下全部内容压偏 +6**(bestAlignDy -11)。
868
+ - **规则**:检测「按钮底 > 本行文本底 + 2 且存在与其竖直重叠的后续成组行」→ 重构为「左列(本行+被吸收行) | 按钮」外层 `space-between` + `align:center`;被吸收行自带 padding 原样保留,按钮右 padding 钉 spec 右沿。
869
+
870
+ ### 11.6 Input 高度 = 标注行高(标注优先)
871
+ - `max(标注高, fs×1.5)` 的下限会在标注 22 < 22.5 时把每个占位行撑高 0.5-1px,表单多行累计成纵向漂移(dy -6)。
872
+ - **规则**:Input 高度 = `max(value.height, label.height)`,标注缺失才回退 `fs×1.5`。
873
+
874
+ ### 11.7 多行段落:钉标注宽 + 框架行距
875
+ - **钉宽**:多行文本盒宽决定换行折点,比设计稿宽会把每行字数变多、折点全错(曾 279→295 宽,3 行折点全变)。`rect.width = 标注宽`。
876
+ - **框架行距**:行距 = `标注层框高 / 行数`(行数 ≈ round(框高 / fs×1.5))。与自然行距 fs×1.5 偏差 >0.5 时**双向**设 `font.lineHeight`:偏低收拢防段落超高(48@3行=16 < 18),偏高撑开防行块过矮(48@2行=24 > 22.5)。扩张方向无裁切风险(多行不设固定盒高)。
877
+ - **交叉验证**:`textStyle.lineHeight` 属性与框架行距冲突 ≥2px/行时采信框架(实测导出位图行距与框高一致,属性是陈旧元数据)。
878
+
879
+ ### 11.8 半角空格字幅 ≈ 1/3em(徽章行缩进)
880
+ - 徽章行(①②③)的内容层前导空格是为徽章留的缩进:可视缩进 = 空格数 × 空格字幅。**实测 PingFang 系设计稿半角空格 ≈ 0.34em**(4 空格缩进 20.5pt@fs15),按 0.5em 高估会把内容推右 ~0.17em/空格。
881
+ - **规则**:`leadWs = 空格数 × fs/3`(全角 1em);**生成器与训练校正器两侧系数必须一致**,否则校正器会把徽章行整体拉偏(曾 padLeft 16→26,徽章错位 +10)。
882
+ - 评分侧同理:校正器的文本对齐目标是**可视字形左沿(层 x + 前导空白宽)**,不是标注层 x。
883
+
884
+ ### 11.9 周期同构行释放必须要求「多行行」(r199)
885
+ - ≥3 个同几何签名(label 列 x/fs + value fs)表单行等周期时**不直接释放**给列表识别:先判每行行带内标题下方是否还有左栏描述行(或行首图标),组内全部行满足才释放。
886
+ - 反例:地址/验证码类单行 kv 字段栈行距可达 55~100px 同样等周期,误释放后右栏值失去归属整段丢失(锚点曾 9 例 PASS→FAIL)。
887
+
888
+ ### 11.10 右栏堆叠同列按 y 行度量右缘(r199)
889
+ - 多行右栏回退的 sameColumn 先把右簇文本按 y(±4) 聚行、取行内最大右缘再比散度(容忍 64px)。
890
+ - 一行由多个异色 run 拼成(红色警示+灰色补充)时,逐文本度量会把行内左段 run 右缘混入,误判整列散开而拒收,整行退化为平铺孤立块。
891
+
892
+ ### 11.11 列表行时间兼容点分日期;desc+time 右栏纵列(r199)
893
+ - 行内时间正则须含 `\d{4}[-/.]\d{1,2}[-/.]\d{1,2}`(点分 `2025.10.10 14:28:16` 高发);先取 time 再从金额候选排除(点分日期含 `.` 会被 `/¥|\.|元/` 抢成金额)。
894
+ - 未消费的时间行会被 auxTexts 当孤立文本甩到卡底重渲染(账单卡三条时间堆底)。
895
+ - desc 与 time 同存时右栏改 `Column[金额, time]`(align flex-end、gap=标题描述距)与左栏逐行顶对齐,行容器改 flex-start;仅该新组合启用,不动既有单行右栏。
896
+
897
+ ### 11.12 列表行横向内边距取 spec 实测中位(r199)
898
+ - 左 = median(行内容左沿)−卡左沿;右 = 卡右沿−median(右栏右沿)。**右沿只统计金额/时间/行内操作**;标题行后缀与标题右侧同行文本属左栏标题流,混入会把右内边距算成上百 px 挤窄左栏触发换行回归(名册卡曾因此回归)。右栏无内容的行回退 section 内边距。
899
+
900
+
901
+ ## 12. 透明度不支持表达式:透明度切换固定范式(lint r57,2026-09-09 固化)
902
+
903
+ - **根因**:移动端渲染不支持 `style.other.opacity` 走表达式(`itemValueFrom:"1"`)。预览侧更是彻底不消费组件级 opacity(`vendor/preview/standalone.html` 构建产物全文 0 处 opacity)——所以「预览截图正常」完全不能证明透明度生效,真机才会暴露。
904
+ - **错误写法**:`opacity: "$level === 1 ? 100 : 50"`(serviceEvaluation 改造前的 10 个表情 Image 即此形态)。
905
+ - **固定范式**:按用到的透明度取值生成等量**静态变体节点**(opacity 写常量),统一套进一层 Row/Column 容器;**容器宽高 = 被展示节点宽高** + `other.overflow:"hidden"`(隐藏变体若仍占位则被裁掉);**点击等事件全部上移到容器**;变体之间用**互斥且完备的 v-show** 显隐切换,视觉上等价于透明度变化。完整约束与可复制子树见 `recipes.md §17` + `recipe_snippets/opacity-switch.json`。
906
+ - **机械改写**:`node scripts/apply_opacity_pattern.mjs --id <卡id>`(可解析 `COND ? A : B` 与右嵌套三元;不可解析 exit 2 提示手工改);`--check` 只报告(可进 CI)。
907
+ - **验证口径**:预览看不出透明度差异,只能验证「结构等价」——改写前后 `render_card.mjs` 截图应逐字节一致;透明度视觉效果真机核对。
908
+ - **边界**:静态透明度(不随状态变)不受约束,直接写常量或按 r057 §3 乘进颜色/渐变;只有「会变化的透明度」才走本范式。
909
+
910
+
911
+ ## 13. 建卡收敛四红线(CardBuddy 黄金跑固化,2026-09-16)
912
+
913
+ - **背景**:CardBuddy 内建助手与 Codex 用同一条 query(07 画板建卡)各跑一遍:助手 26 步、4 次整份重写 IR(单次 40-110s)、终产物 validate 3 ERROR、match 靠删内容刷到 89.96(渲染高 260 vs 设计 464);黄金跑 1 次写 IR + 5 轮 `--set` 微调收敛到 **match 98.82 / heightDelta 0 / validate 0 error / lint 0 error**。差距全部落在下列红线。
914
+ - **R-a iterate.mjs 是唯一门禁**:单份报告内含 autofix + 真 `validate_schema.py` + lint + render + 像素对比。历史上 iterate 硬编码 `validate:{errors:0}`、expand_ir 又因 autofix 的 exit 1 误报「validate 未执行(未找到 python)」,两个假信号叠加让模型 ship 了 flexEnd 硬错误。现在两处都已修:非零退出码是正常结果,只有 ENOENT 才算 python 缺失。
915
+ - **R-b 并集像素对比**:`pixelDiff` 按 max(渲染, 设计) 画布采样,超出重叠区一律计差异 → 删内容 / 高度塌缩只会降分(旧坏卡从「89.96」被打回 50.41)。收敛条件:`pixelDiff.match ≥ 95` 且 `pixelDiff.size.heightDelta = 0` 且 validate/lint 0 error。match 不升反降或 hotspots 集中在已有内容区 = 在删内容凑分,回退该轮 `--set`。
916
+ - **R-c IR 只写一次**:首写 `fs_write .cache/ai-scratch/<id>.ir.json`,之后一律 `iterate.mjs --set '点路径=值'` 原子微调(一轮可多条;中段不存在响亮报错)。整份重写 IR 是纯输出浪费,只有结构级推翻才允许。
917
+ - **R-d 默认值三陷阱**:① Column/Row 默认 `gap=4`,不需要间距就显式 `gap:"0"`;② Text 不写 `lineHeight` 时渲染器按 1.5×fontSize 撑高(fs15→22.5、fs12→18),整卡累计漂移 +5~6px,标注的 lineHeight 必须逐条抄;③ Row 父级里的 Row / AbsoluteLayout 子节点默认 `width:100%`,space-between 行里会互相挤出画布——定宽子簇显式 `rect.width`,且并列子节点至少一个 `flexShrink:"1"`(lint R19 / R35)。flex 枚举 kebab-case(`flex-end` 不是 `flexEnd`)。
918
+ - **R-e 切图审计先行**:`spec_audit.mjs` 一步交叉审计 spec + 聚焦截图 + slices 目录,产出 bands / gaps / texts / colors / slices(baked) / missing;缺口用 `crop_slices.mjs --from-audit` 从聚焦截图派生到 `src/slices/`。`baked.label=true` 的切图已含标签文字 → tile 用单个 Image;`verdict=reused-differs`(同一张切图被标到内容不同的多个位置)必须用派生的 `_alt` 名,复用原图会渲染错标签。
919
+ - **反例存档**:`.cache/ai-chats/all-components-test.json`(修复前助手轨迹);黄金跑记录见 `docs/CardBuddy 建卡黄金跑基线.md`。
920
+
921
+ ## 14. 切图语义化命名与内容去重(lint r59 / r60,2026-09-17 固化)
922
+
923
+ - **铁律**:切图落 `src/slices/` 必须 ①**按实际功能与作用命名**(`iconArrowRight@3x.png` / `bgCardHeaderDiffuse@3x.png` / `logoBank@3x.png`),②**落地前按内容 sha256 判重**——已存在同内容文件则**复用既有名 + 改写引用**,不新增副本,③上传阶段同内容**只上传一次**,多卡共用同一个 `@filestore` 地址。
924
+ - **根因**:设计稿素材原名不可信(`编组 4.png`、`矩形 4.png`、`8.icon_通用_箭头右@3x.png`、`展开.png`、`icon (2).png`)。扁平化后名字失去语义 → 无法判断能否复用 → 同一张图被不同画板/不同卡各导一份,`src/slices` 堆重复副本(实测 **60 个文件只有 50 份唯一内容、7 组重复**:`chevron_right.png` ≡ `assetAllocRadar_arrow_right.png` ≡ `编组 4.png`),上传后同一张图产生多个线上地址。
925
+ - **判定口径**:**内容 sha256 = 唯一权威判据**;尺寸 w×h + 字节数 = 快速预筛(不单独作判据);来源(导出稿 / 画板 / 图层名,若可知)= 辅助证据与**命名依据**,不参与去重判定。
926
+ - **处理**:IR 里直接写语义名(`pi.value: "/slices/iconArrowRight@3x.png"`);机械产线(`sliceRefPath` / v3)产出的导出扁平名属过渡形态,交付前**成套改名**(文件名 + `lib/slice_dedupe.mjs → rewriteSliceRefs` 改写全部卡片 schema/data + 同步 `manifest.json`),**禁止新旧两份并存**。`expand_ir.mjs`(`syncReferencedSlices`)与 `generate_cards.mjs`(`collectSlicesToSrcSlices`)落地时已自动做同内容复用 + 引用回写并打印 `[slices] 内容已存在 → 复用 …`。`crop_slices.mjs --from-audit` 派生的 `_alt` 名内容确实不同(不算重复,见 §13 R-e),但仍是过渡名,建议改成语义名。
927
+ - **验收**:`node scripts/lint_card.mjs --id <卡id>` 无 `r59-slice-semantic-name` / `r60-slice-duplicate-content` 新增告警;`--all | grep r60` 为空;切图上传后 `src/slices/manifest.json` 里同一 sha256 只有一个 `url`(同内容副本记 `reusedFrom`)。
928
+ - **规则详情**:`slices_convention.md §1.1(命名)/ §3.1(落地判重)/ §3.2(上传去重)`;共享实现 `scripts/lib/slice_dedupe.mjs`;上传侧 `skills/finmall-card-sync/scripts/slice_upload.mjs`。