feat: improve ui builder skill (#47)

* fix: menu group mismatch

* fix: incorrect columnCount

* chore: improve skill

* chore: improve skill

* chore: improve skill

* chore: improve skill

Author: gchust

skills/nocobase-ui-builder/SKILL.md

@@ -47,7 +47,7 @@ description: >-
 5. `layout` belongs only on `tabs[]` or inline `popup`, never on a block object. For `createForm`, `editForm`, `details`, and `filterForm`, use `fieldsLayout` when the blueprint must control the inner field grid directly. Omit page/popup `layout` only when that tab/popup has at most one non-filter block; otherwise explicit layout is required. For low-level `set-layout`, do not reuse public `{ rows: [[{ key, span }]] }` syntax: runtime `rows` is `Record<string, string[][]>`, each cell array stacks live child `uid`s, `[[uidA], [uidB]]` means two columns, and `[[uidA, uidB]]` means one stacked column.
 6. For `createForm`, `editForm`, and `details`, once the block contains more than 10 real fields, use explicit `fieldGroups` instead of one flat `fields[]` list. Do not treat manual `divider` items as a substitute, and do not combine `fieldGroups` with `fieldsLayout`.
 7. If clicking a shown record or relation record should open details, prefer a field popup. Use a button or action column only when the request explicitly asks for one.
-8. If visible same-title destination menu groups already exist, never create another same-title group just to avoid ambiguity and never choose one locally. In that multi-match case, require explicit `navigation.group.routeId` before write. Only zero-match create and one-match title-only reuse may proceed without `routeId`.
+8. If visible same-title destination menu groups already exist, never create another same-title group just to avoid ambiguity and never choose one locally. In that multi-match case, require explicit `navigation.group.routeId` before write. Without `routeId`, only zero-match create and one-match title reuse may proceed; metadata on reused groups is ignored.
 9. In `applyBlueprint create`, any newly created `navigation.group` and any top-level or second-level `navigation.item` must carry one valid Ant Design icon name. When `navigation.item` is attached under an explicit existing `navigation.group.routeId`, keep an icon by default but do not assume the local preview can prove whether that live target is already third-level or deeper.
 10. `navigation.group.routeId` and desktop-route `id` are navigation locators only. When follow-up localized work or explicit inspection is needed after create/init or successful whole-page `applyBlueprint`, normalize to `pageSchemaUid` for page-level `flow-surfaces get`, and only use live `uid` values returned by `get` / `describe-surface` / create responses for `catalog`, `context`, `get-reaction-meta`, `compose`, `configure`, `add*`, or `remove*`. Never pass a desktop-route `id` as `target.uid`. For artifact-only locator handoffs, keep direct machine-readable fields `navigation.routeId`, `page.pageSchemaUid`, and `liveTargets[].uid`; when no live uid exists yet, use a non-empty placeholder string instead of `null`.
 11. Before the first real whole-page `applyBlueprint`, run the local prepare-write gate (`node skills/nocobase-ui-builder/runtime/bin/nb-page-preview.mjs --stdin-json --prepare-write` or `prepareApplyBlueprintRequest(...)`) and show one ASCII-first prewrite preview from the same draft blueprint. Treat that helper as a local shape/threshold gate: the CLI path normalizes any helper-envelope `collectionMetadata`, scans the blueprint, and auto-fetches only missing collection metadata with `nb api data-modeling collections get --filter-by-tk <collection> --appends fields -j`, falling back to `nb api resource list --resource collections --filter '{"name":"<collection>"}' --appends fields -j`; already supplied metadata wins and is not overwritten. `--no-auto-collection-metadata` keeps the old fail-closed `missing-collection-metadata` behavior for offline checks. `collectionMetadata` belongs only in the helper envelope/call options, never inside the blueprint root. It accepts omitted data-surface `filter` actions, but every direct non-template public `table` / `list` / `gridCard` / `calendar` / `kanban` block must still carry a non-empty block-level `defaultFilter`; if a `filter` action also provides `settings.defaultFilter`, prepare-write validates that explicit action payload too. Public `kanban` main blocks may keep `fields[]`, but must not carry `fieldGroups`, `fieldsLayout`, or `recordActions`; allowed main-block actions are `filter`, `addNew`, `popup`, `refresh`, and `js`. For block settings, numeric `height` means a fixed height and must be paired with `heightMode: "specifyValue"`; prepare-write auto-adds that mode when `settings.height` is present and `settings.heightMode` is omitted, including popup blocks. For sortable public blocks (`table`, `details`, `list`, `tree`, `kanban`, `gridCard`, `map`), legacy `settings.sort` is normalized to canonical `settings.sorting`; `calendar` is left unchanged by that alias path. With resolved `collectionMetadata`, it validates fixed defaults completeness for every involved scope: required `defaults.collections` entries, required popup `{ name, description }` entries for the fixed `view` / `addNew` / `edit` trio, relation field popup child `resource.binding`, and required `fieldGroups` when any fixed generated popup scene still has more than 10 effective fields. Automatic metadata only fills metadata gaps; it does not generate large-collection `fieldGroups`. For artifact-only drafts with no real write, draft `prewrite-preview.txt` directly from the same draft blueprint instead of attempting the local helper CLI.

skills/nocobase-ui-builder/references/blocks/grid-card.md

@@ -22,46 +22,42 @@ description: Grid card 区块的最小稳定树、两层 actions slot 语义与
 
 ```json
 {
-  "use": "GridCardBlockModel",
-  "stepParams": {
-    "resourceSettings": {
-      "init": {
-        "dataSourceKey": "main",
-        "collectionName": "assets"
-      }
-    },
-    "GridCardSettings": {
-      "columnCount": {
-        "xs": 1,
-        "md": 2,
-        "lg": 3,
-        "xxl": 4
+  "type": "gridCard",
+  "title": "资产指标",
+  "collection": "assets",
+  "defaultFilter": {
+    "logic": "$and",
+    "items": [
+      {
+        "path": "name",
+        "operator": "$includes",
+        "value": ""
       },
-      "rowCount": {
-        "rowCount": 3
+      {
+        "path": "status",
+        "operator": "$eq",
+        "value": ""
       }
-    }
+    ]
   },
-  "subModels": {
-    "item": {
-      "use": "GridCardItemModel",
-      "subModels": {
-        "grid": {
-          "use": "DetailsGridModel",
-          "subModels": {
-            "items": []
-          }
-        },
-        "actions": []
-      }
+  "settings": {
+    "columns": {
+      "xs": 1,
+      "sm": 1,
+      "md": 2,
+      "lg": 3,
+      "xl": 3,
+      "xxl": 4
     },
-    "actions": []
-  }
+    "rowCount": 3
+  },
+  "fields": []
 }
 ```
 
 skill 至少要知道三件事：
 
+- public authoring 使用 `settings.columns` 控制列数，可以传数字或包含 `xs` / `sm` / `md` / `lg` / `xl` / `xxl` 的响应式对象
 - `subModels.item.use` 必须是 `GridCardItemModel`
 - `subModels.item.subModels.grid.use` 必须是 `DetailsGridModel`
 - block 与 item 各有一层 `actions`，语义不同

skills/nocobase-ui-builder/references/chart-core.md

@@ -41,7 +41,7 @@ Other than that, the chart block should only expose four additional outer-block
 
 The priority is to stabilize both "card displays" and "chart renders". Do not expose frontend-internal details such as `props / decoratorProps / stepParams` to the user.
 
-Chart is also an example of the general public-settings pattern: when creating or reconfiguring, prefer public semantics such as `query / visual / events / title / displayTitle / height / heightMode`. Do not reverse internal `props / decoratorProps / stepParams` from readback into the next input template.
+Chart is also an example of the general public-settings pattern: when creating or reconfiguring, prefer public semantics such as `query / visual / events / title / height / heightMode`. Do not reverse internal `props / decoratorProps / stepParams` from readback into the next input template.
 
 ## Default Strategy
 
@@ -59,9 +59,9 @@ Chart is also an example of the general public-settings pattern: when creating o
 
 The most stable execution order for a chart block is not a one-shot blind write. It is:
 
-1. `add-block(type="chart", settings={ title?, displayTitle?, height?, heightMode? })`
+1. `add-block(type="chart", settings={ title?, height?, heightMode? })`
 2. If you are configuring a builder query, read `context(path="collection")` first to pick fields
-3. Run `configure(changes={ query, title?, displayTitle?, height?, heightMode? })` first
+3. Run `configure(changes={ query, title?, height?, heightMode? })` first
 4. Then read `context(path="chart")`
 5. Based on `chart.queryOutputs / aliases / supportedMappings / supportedStyles / safeDefaults / riskyPatterns / unsupportedPatterns`, run `configure(changes={ visual, events? })`
 6. Use `nb api flow-surfaces get --uid <chart-uid>` for canonical readback
@@ -81,10 +81,9 @@ Only use `changes.configure` when you are explicitly preserving compatibility wi
 
 ## Outer Block Parameters (Minimum Exposed Set)
 
-In addition to `query / visual / events / configure`, the chart block should expose only these four outer parameters to this skill:
+In addition to `query / visual / events / configure`, the chart block should expose only these three outer parameters to this skill:
 
 - `title?: string`
-- `displayTitle?: boolean`
 - `height?: number`
 - `heightMode?: "defaultHeight" | "specifyValue" | "fullHeight"`
 
@@ -95,7 +94,7 @@ Notes:
   - `specifyValue`
   - `fullHeight`
 - For compatibility with old skills / historical payloads, the server still accepts `fixed` and automatically normalizes it to `specifyValue`
-- `title` only accepts a non-empty string; `displayTitle` only accepts `true | false`
+- `title` only accepts a non-empty string
 - `height` only accepts numbers; it must be paired with `heightMode = "specifyValue"` for the frontend to use the fixed value
 - The local prepare-write and localized preflight helpers auto-add `heightMode = "specifyValue"` when `height` is present and `heightMode` is omitted
 - If `heightMode = "specifyValue"`, it is recommended to also pass `height`
@@ -106,6 +105,7 @@ Notes:
 
 Invalid:
 
+- passing `displayTitle`; current flowSurfaces chart configureOptions do not support it
 - documenting `heightMode = "fixed"` as the primary public syntax
 - passing arbitrary unknown strings into `heightMode`
 
@@ -412,10 +412,9 @@ Rules:
 
 Minimum required post-write readback:
 
-- `tree.stepParams.cardSettings.titleDescription.title` when `displayTitle !== false` and `title` is non-empty
+- `tree.stepParams.cardSettings.titleDescription.title` when `title` is non-empty
 - `tree.stepParams.cardSettings.blockHeight.heightMode`
 - `tree.stepParams.cardSettings.blockHeight.height` when `heightMode = "specifyValue"`
-- if `displayTitle = false`, expect `tree.stepParams.cardSettings.titleDescription` to be absent
 - `cardSettings` is the primary criterion; if `tree.decoratorProps.*` exists it is only an auxiliary mirror, and `tree.props.*` is not the primary criterion
 - `tree.stepParams.chartSettings.configure.query`
 - `tree.stepParams.chartSettings.configure.chart.option`

skills/nocobase-ui-builder/references/helper-contracts.md

@@ -15,6 +15,7 @@ Use this before the first real whole-page write.
 - treat the normalized write body as authoritative local write shape; expected helper-added or helper-normalized fields should be kept as-is instead of being locally undone
 - once this helper has run successfully, the first whole-page write must consume `result.cliBody` rather than reusing the original draft blueprint
 - this helper is local/read-only for page writes; it never performs the remote `apply-blueprint` write for you
+- by default, in `create` mode it also resolves `navigation.group.title` against live `desktopRoutes`: zero matches keep `title + icon` for new-group creation, one match rewrites the prepared `cliBody` to `navigation.group.routeId`, and multiple matches fail locally requiring explicit `routeId`
 - by default, the CLI path auto-resolves missing `collectionMetadata` entries before validation: it normalizes supplied metadata, scans data-bound blocks and popups, resolves association targets from known metadata for up to 5 rounds, fetches only missing collections with `nb api data-modeling collections get --filter-by-tk <collection> --appends fields -j`, and falls back to `nb api resource list --resource collections --filter '{"name":"<collection>"}' --appends fields -j`
 - caller-supplied `collectionMetadata` wins; fetched metadata only fills missing collection entries and is not emitted in `result.cliBody`
 - pass `--no-auto-collection-metadata` to keep fail-closed behavior; then any data-bound block (a block with `collection`, `resource`, `binding`, `dataSourceKey`, `associationPathName`, or `associationField`) with missing or empty metadata fails with `missing-collection-metadata`

skills/nocobase-ui-builder/references/normative-contract.md

@@ -221,8 +221,7 @@ For `replace` runs:
 - skill-side authoring may omit layout only for scopes with at most one non-filter block; otherwise the draft must decide layout before write
 - in `create`, if an existing menu group is already known, prefer `navigation.group.routeId`; when only `navigation.group.title` is given, applyBlueprint reuses one unique same-title group, creates a new group if none exists, and rejects ambiguous multi-match titles
 - at the skill-authoring layer, if visible same-title menu groups already exist and title lookup would hit multiple groups, do **not** create another same-title group for disambiguation and do **not** choose one locally; require explicit `routeId` before write
-- `navigation.group.routeId` is exact targeting only and must not be mixed with `icon`, `tooltip`, or `hideInMenu`
-- same-title reuse is title-only; if an existing group's metadata must change, use low-level `updateMenu` instead of applyBlueprint create
+- `navigation.group.routeId` has highest priority and ignores `title`, `icon`, `tooltip`, and `hideInMenu`; title-based reuse also ignores `icon`, `tooltip`, and `hideInMenu` when an existing group is reused; if an existing group's metadata must change, use low-level `updateMenu` instead of applyBlueprint create
 
 Use the resolved page `target` from the public response as the carry-forward locator. A successful `apply-blueprint` response is the default stop point. Run follow-up `get` only when follow-up localized work or explicit inspection needs live structure.
 

skills/nocobase-ui-builder/references/page-blueprint.md

@@ -210,15 +210,16 @@ Example:
 ### `navigation.group` semantics
 
 - Prefer `navigation.group.routeId` when the destination menu group is already known.
-- `navigation.group.routeId` is exact targeting only; do not mix it with `icon`, `tooltip`, or `hideInMenu`.
-- `navigation.group.title` is for new-group creation or title-only unique same-title reuse.
+- `navigation.group.routeId` has highest priority; when it is present, `title`, `icon`, `tooltip`, and `hideInMenu` are ignored for the existing group.
+- `navigation.group.title` is for new-group creation or unique same-title reuse.
 - When `navigation.group.title` creates a new group, `navigation.group.icon` is required.
 - When `routeId` is omitted and `title` matches:
   - zero existing groups -> create a new group
   - one existing group -> reuse that group
   - multiple existing groups -> reject and require `routeId`
-- If same-title reuse hits an existing group, keep it title-only.
+- If same-title reuse hits an existing group, `icon`, `tooltip`, and `hideInMenu` are ignored.
 - If an existing group's metadata must change, do not rely on applyBlueprint create; use low-level `updateMenu` instead.
+- During real-write prepare, the local helper may rewrite one unique same-title existing group or one explicit `routeId` group to `navigation.group.routeId` in `cliBody`. Treat that prepared shape as authoritative.
 
 ### `navigation.item` semantics
 

skills/nocobase-ui-builder/references/settings.md

@@ -284,11 +284,13 @@ When `add-block` creates a public `kanban`, keep collection binding in `resource
 
 Common settings that are suitable for direct inline use:
 
-- generic block: `title`, `displayTitle`, `height`, `heightMode`
+- generic card-like block: `title`, `displayTitle`, `height`, `heightMode`
 - `table`: `quickEdit`, `treeTable`, `defaultExpandAllRows`, `dragSort`, `dragSortBy`
 - `calendar`: `titleField`, `colorField`, `startField`, `endField`, `defaultView`, `quickCreateEvent`, `showLunar`, `weekStart`, `dataScope`, `linkageRules`, `quickCreatePopup`, `eventPopup`
 - form-like blocks: `labelWidth`, `labelWrap`, `layout`, `labelAlign`, `colon`
 
+Do not copy `displayTitle` into block families whose runtime configureOptions do not expose it. Known unsupported cases include `chart` and `tree`; chart blocks accept `title`, `height`, `heightMode`, `query`, `visual`, and `events` instead.
+
 Height settings:
 
 - If you set a numeric `height`, pair it with `heightMode: "specifyValue"` so the frontend uses the value.

skills/nocobase-ui-builder/references/tool-shapes.md

@@ -375,7 +375,7 @@ nb request body:
 }
 ```
 
-When the target group is not already known, `navigation.group.title` is also valid; applyBlueprint will reuse a unique same-title group or create a new one when no match exists, but multi-match same-title cases must stop and require explicit `routeId` before write. Same-title reuse is title-only. `navigation.group.routeId` is exact targeting only and must not be mixed with `icon`, `tooltip`, or `hideInMenu`; if an existing group's metadata must change, use low-level `update-menu` instead.
+When the target group is not already known, `navigation.group.title` is also valid; applyBlueprint will reuse a unique same-title group or create a new one when no match exists, but multi-match same-title cases must stop and require explicit `routeId` before write. `navigation.group.routeId` has highest priority; if it is present, `title`, `icon`, `tooltip`, and `hideInMenu` are ignored. For title-based reuse, `icon`, `tooltip`, and `hideInMenu` are also ignored when an existing group is reused. If an existing group's metadata must change, use low-level `update-menu` instead.
 
 When the requirement is "click the shown record / relation record to open details", prefer a field popup rather than inventing a new action button:
 

skills/nocobase-ui-builder/references/whole-page-quick.md

@@ -30,6 +30,7 @@ Treat these as whole-page too: a whole page create / replace, one route-backed t
    - If a whole-page `applyBlueprint` fails before first success, repair the blueprint from the error, rerun `prepare-write` and preview, and retry blueprint-only up to 5 rounds. Do not continue with low-level writes during those pre-success retries. After 5 failed rounds, report the latest blueprint / preview / error evidence.
 5. For `create`, any newly created `navigation.group` and any top-level or second-level `navigation.item` must include one valid semantic Ant Design icon. When `navigation.item` is attached under one explicit existing `navigation.group.routeId`, keep an icon by default but do not assume the local preview can prove whether that live target is already third-level or deeper.
 6. If visible same-title menu groups already exist, do not pick one locally and do not create another same-title group just to disambiguate. Require explicit `navigation.group.routeId` before the write whenever title lookup would hit multiple groups.
+   - The real-write prepare helper resolves `navigation.group.title` against live `desktopRoutes` when possible. If exactly one same-title group exists, use the prepared `cliBody` with `navigation.group.routeId`; if more than one exists, stop on the local error and ask for the routeId.
 7. When the page is being created now, keep structure, popup, and whole-page interaction logic in the same blueprint:
    - root blocks in `tabs[].blocks[]`
    - popup content inline under the owning field/action/record action