nocobase-ui-builder（nocobase ui 构建器）

Goal

• Canonical transport is nb api flow-surfaces.
• Use nb as the only public transport. If nb is missing or stale, report the blocked command/env state instead of switching transports.
• Keep routing intent-first: open one matching quick-route doc first, not the whole directory.
• When a quick route already matches, stay on it. Do not enumerate the skill directory just to rediscover docs.
• When the task is a partial-match or handoff-only request, answer from this skill's scope boundary directly. Do not inspect runtime, scripts, or helper docs just to justify the handoff.
• Treat one user request that spans several pages as ordered single-page runs.

Router

• whole-page authoring goes through applyBlueprint, nb api flow-surfaces apply-blueprint, and whole-page-quick.md
• localized existing-surface edits go through low-level flow-surfaces and local-edit-quick.md
• localized existing-surface reaction work starts with get-reaction-meta, nb api flow-surfaces get-reaction-meta, writes through set*Rules, and reaction-quick.md; first-pass whole-page reactions stay in reaction.items[] with no live get-reaction-meta; artifact-only localized reaction drafts record the planned get-reaction-meta probe
• partial-match or boundary-only requests go through boundary-quick.md first
• After that route is clear, if template / reference / copy routing is truly in scope, read template-quick.md first and then templates.md for the full decision matrix.
• Do not open tool-shapes.md or helper-contracts.md until you are preparing a real nb body, running the prepare-write gate, or validating a prepared write body.
• If the task involves JS code, renderer: "js", jsBlock, jsColumn, jsItem, JS actions, charts, or ctx.* API questions, read js.md first, then js-surfaces/index.md, then js-snippets/index.md, and only then js-reference-index.md.
• Before using a flow-surfaces subcommand you have not used yet in the current task, run nb api flow-surfaces --help or nb api flow-surfaces <subcommand> --help.
• Local helper CLIs are skill-local, not PATH contracts. Invoke nb-page-preview, nb-runjs, nb-template-decision, and nb-localized-write-preflight through node skills/nocobase-ui-builder/runtime/bin/<helper>.mjs from this repo root, or through the equivalent absolute path to this skill. Do not probe bare helper names first.

Hard Rules

1. For nb writes, pass the business object itself as the raw JSON body. After whole-page prepare-write, that business object is result.cliBody, not the original draft blueprint. Do not wrap that object again.
2. For a normal single-page request, default to exactly one real tab. Do not add empty tabs or placeholder markdown / note / banner blocks unless the user asked for them.
3. Default blueprint fields[] entries to simple strings. Upgrade a field entry to an object only when popup, target, renderer, or a field-specific type is required.
4. For page authoring, field truth comes from live collection metadata. Prefer nb api data-modeling collections get --filter-by-tk <collection> --appends fields -j; if that command family is unavailable, use nb api resource list --resource collections --filter '{"name":"<collection>"}' --appends fields -j. Do not use data-modeling fields list / nb api data-modeling collections fields list as the authoring truth. Any field used in blueprint fields[] must have a non-empty interface. For whole-page applyBlueprint, recompute the full involved collection set from live metadata on every draft and rebuild defaults.collections from scratch instead of reusing stale fragments. For every involved direct collection, always emit popups.view / popups.addNew / popups.edit as {name, description}, and let any table block pull that collection into addNew threshold evaluation even when the blueprint did not spell out an addNew opener. Keep fieldGroups collection-only on the target collection, and add defaults.collections.<collection>.fieldGroups only when one of those fixed generated popup scenes should still have more than 10 effective fields after scene filtering; otherwise omit fieldGroups. For association fields, keep every involved relation scope on the same fixed view / addNew / edit trio under defaults.collections.<sourceCollection>.popups.associations.<associationField>.<action> with the same {name, description} contract, keyed only by the first relation segment; prepare-write may normalize legacy deeper keys down to that first segment. Do not create per-association or relation-scoped fieldGroups. Never generate defaults.blocks, and never put blocks, fields, fieldGroups, or layout under defaults.collections.*.popups.
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 uids, [[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. 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.
12. Update action field assignment uses only public settings.assignValues. bulkUpdate is a collection action under block actions; updateRecord is a record action under recordActions. assignValues must be one plain object keyed by fields from the host collection metadata; {} is valid and clears assignment values. Do not use add-fields, raw flowModels, AssignFormGridModel, or AssignFormItemModel to configure action assignment UI.
13. Treat the local prepare-write helper as the authority for normalized local write shape. If it auto-adds, rewrites, or normalizes fields in ways that are within the helper's expected contract, keep that result as-is. Whole-page work includes whole-page create / replace, one route-backed tab full build, complex multi-block pages, nested-popup pages, and pages with multiple reaction families. Pre-write reads, metadata fetch, preview, and prepare-write are allowed, but the first mutating write in that route must be applyBlueprint. For the first real whole-page write, prepare-write is mandatory and the only nb write body is result.cliBody; do not send the original draft blueprint to applyBlueprint. For whole-page applyBlueprint create / replace and same-blueprint reaction.items[], a successful applyBlueprint response is the default stop point. Run follow-up get only when follow-up localized work or explicit inspection needs live structure. Without that extra readback, report the write from the success response and request intent rather than as a normalized persisted subtree.
14. Treat default values, computed values, field/block/action state, and show/hide as reaction work first. Do not guess raw configure keys.
15. Any JS / RunJS write payload must preserve readable multiline source. For value.source: "runjs", jsBlock / jsItem / JS actions, chart raw code, or any other code field, author non-trivial code with actual newline characters and 2-space indentation before validation or write. Do not compress multiple statements, local variable setup, conditional branches, or string assembly onto one physical line just because the surrounding payload is JSON; encode line breaks as \n in JSON strings. Only a single short return/expression with no setup or branching may stay one line. A validator pass does not waive this readability rule.
16. If live readback shows an existing template reference and the requested change touches template-owned content, default to the template source. Keep host/openView config edits local. Page-scoped wording is not local-only intent, so do not auto-detach to copy; clarify before writing when scope is unresolved. For decision artifacts, record the template-owned content route and the host/openView route separately as templateOwnedContentRoute and hostOpenViewConfigRoute.
17. In testing or multi-agent runs, do not perform destructive cleanup unless the user explicitly asked for deletion.
18. When you actually have persisted readback to summarize for the user or for local helper artifacts, prefer one stable public summary with normalized type labels such as table, details, editForm, filterForm, and createForm; do not rely on raw model names alone. For page-level create / replace, keep page.pageSchemaUid, page.pageTitle, and page.menuGroupTitle explicit in that summary. When a scenario spans multiple pages, use the same canonical page identity keys under pages.*, and use type for concrete summary nodes such as tables.*, lists.*, and forms.*; reserve blockTypes for aggregate arrays such as root.blockTypes or popups.*.blockTypes. Keep root actions under root.actionTitles instead of leaving recordActionTitles as the only proof.
19. For reaction work, pick the final block/action target only after get-reaction-meta proves the required source path is available in that scene. On targets that expose multiple capabilities, select the write slot by matching kind first and then reuse that exact capability fingerprint; do not copy a nearby fingerprint from another kind. If the current target cannot expose the needed path, move the target or restructure the page/popup first instead of writing a guessed rule to an unsupported host.
20. Resolve filter wording before choosing structure. For table / list / gridCard / calendar / kanban-like data surfaces, ambiguous “筛选 / filter” requests default to the same host's block-level filter action/button, not a separate filter block. Treat “搜索 / search” that way only when the request explicitly adds search to a table / list / gridCard / calendar / kanban / card-like host, including wording such as “支持搜索 / 带搜索 / 可搜索 / searchable”; page-noun wording such as “搜索页 / 搜索结果页 / 搜索门户 / 搜索列表页” should stay page intent, not filter intent. Route 树筛选 / 树状筛选 / tree filter / tree filter block / 树形筛选区块 directly to TreeBlockModel, not FilterFormBlockModel; read references/blocks/tree.md before writing it. Route 分析看板 / dashboard / trend / KPI / 概览 to chart/grid-card insight paths by default; route to KanbanBlockModel only when kanban cues such as 看板区块 / kanban / pipeline / status columns / 拖拽 / 泳道 / backlog are present. Plain 看板 alone does not override analytics intent. Do not create a new filterForm by default. Read references/aliases.md first. Open references/blocks/filter-form.md and keep a real filterForm in the first-pass blueprint only when the user explicitly asks for a filter/search block, form, or query area and the phrase is not a tree-filter request; then include stable filter items, submit / reset actions, and same-blueprint string target block keys instead of low-level defaultTargetUid or raw block settings payloads.
21. When you author one localized compose / add-block / add-blocks body locally, validate that body first with the local localized preflight helper (node skills/nocobase-ui-builder/runtime/bin/nb-localized-write-preflight.mjs --operation <compose|add-block|add-blocks> --stdin-json) or runLocalizedWritePreflight(...). Treat it as an explicit local validator for skill-authored low-level payloads, not as a transport wrapper: it requires caller-supplied collectionMetadata for data-bound payloads, reports missing-collection-metadata when metadata is absent, keeps direct non-template public table / list / gridCard / calendar / kanban blocks fail-closed on missing or empty block-level defaultFilter, validates metadata-aware filter coverage, rejects unsupported kanban / calendar main-block sections, validates relation field popup child resource.binding, validates update-action settings.assignValues, auto-adds heightMode: "specifyValue" when settings.height or configure changes.height is present without an explicit mode, and normalizes settings.sort only for sortable public blocks (table, details, list, tree, kanban, gridCard, map). After a successful helper run, send result.cliBody in the later explicit nb api flow-surfaces... call. The backend runtime remains compatibility-tolerant; this stricter requirement belongs to the local skill-side validator contract.
22. If a first-pass whole-page write still leaves filterForm as an empty shell after a successful applyBlueprint, treat it as an explicit local/live gap and keep any low-level addBlock / addAction / addField repair narrowly scoped. If the first applyBlueprint fails with a verified filterForm-specific shape/runtime error, repair the blueprint from that error, rerun prepare-write and preview, and retry blueprint-only up to 5 rounds. Do not switch to low-level writes during those pre-success retries. After 5 failed rounds, report the latest blueprint / preview / error evidence.
23. If a create/edit form helper or reference depends on formValues.*, inspect catalog / get-reaction-meta before choosing the host. When that live scene exposes fields / actions / node but not blocks, model the helper as a jsItem or other field-like helper inside the same form scene, not as a standalone block; for current JSItem targets, implement hide/show by rendering null until the form value is present instead of assuming setFieldState can target the JSItem. When that render-null pattern is used successfully, treat it as a configured helper toggle in readback/evidence instead of marking the helper outcome false only because fieldLinkage cannot target the JSItem itself.
24. Treat pages with multiple work areas, filter/search blocks, nested popups, or multiple reaction families as complex whole-page requests, not as a separate router path. They still stay on whole-page-quick.md and still prefer one applyBlueprint request.
25. For those complex whole-page requests, first-pass blueprint generation should include the structural blocks, inline popups, and top-level reaction.items[] together. Do not split the page into root-shell / popup / reaction phases just because the page is large.
26. Use low-level get-reaction-meta + set*Rules or add* repair only for localized edits on an existing live page, or after a successful whole-page applyBlueprint when an explicit local/live gap still needs narrowly scoped repair. Before one whole-page applyBlueprint succeeds, do not use createMenu, createPage, compose, configure, update-settings, add*, move*, remove*, or set*Rules. 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 switch to low-level writes during those pre-success retries. After 5 failed rounds, report the latest blueprint / preview / error evidence.
27. Stay env-neutral in the general skill contract. Use the current configured CLI env or explicit runtime flags instead of hard-coding local aliases or fixed URLs.

Read Paths

• Route unclear: references/index.md
• Whole-page draft/create/replace from business intent: whole-page-quick.md
• Localized existing-surface edit: local-edit-quick.md
• Whole-page or localized reaction change: reaction-quick.md
• Partial-match handling and narrow handoff reports: boundary-quick.md
• Reuse, template selection, or existing template reference edits: template-quick.md
• Write-time helper CLIs / prewrite gate / helper return shapes for real writes: helper-contracts.md
• JS or chart work: js.md or chart.md

Scope & Handoff

• Handle only Modern page (v2) menu/page/tab/popup/content surfaces and the block / field / action / layout / reaction work inside them.
• For partial-match or boundary-report tasks, keep the Modern-page slice narrow and write the handoff report directly from this boundary list. Do not inspect runtime or scripts unless the request is explicitly about those mechanics.
• Hand off ACL / route permissions / role permissions to nocobase-acl-manage.
• Hand off collection / field / relation authoring to nocobase-data-modeling.
• Hand off workflow create / update / revision / execution to nocobase-workflow-manage.