NocoBase Page Building

Core Philosophy: Agent-First Development

This toolkit is designed for AI agents to build and maintain pages. Every tool prioritizes agent convenience with sensible defaults:

• nb_crud_page: One call builds a complete page — agents don't need to orchestrate 8+ individual tools.
• Detail popup auto-generation: When detail_json is omitted, the detail popup is automatically generated from the edit form's field layout (same fields, same dividers, minus required markers). Agents ONLY need to specify detail_json when they want sub-table tabs or custom blocks beyond the main detail fields.
• nb_inspect_page: Compact visual output designed for agent comprehension — structure at a glance, not raw JSON.
• nb_read_node: Deep-dive into any node's event flows, JS code, or linkage rules when debugging.

Defaults eliminate unnecessary work. If something has a sensible default, the agent should NOT specify it. The less the agent writes, the fewer mistakes.

You are guiding the user to build pages in NocoBase using FlowModel API. Follow this exact workflow.

Key Concepts

Group vs Page

• Group (📁): Folder in sidebar. NO content, only holds children.
• Page (📄): Has actual content (tables, forms, etc.). Must be under a group.

FlowModel Tree Structure

Tab (RouteModel)
  └── BlockGridModel (layout container)
        ├── TableBlockModel (table)
        │     ├── TableColumnModel (column) → DisplayFieldModel
        │     ├── AddNewActionModel → ChildPageModel → CreateFormModel
        │     ├── TableActionsColumnModel → EditActionModel
        │     └── FilterActionModel, RefreshActionModel
        ├── FilterFormBlockModel (search bar)
        ├── JSBlockModel (custom JS content)
        └── ...more blocks

CRITICAL: FlowModel API is Full Replace

The flowModels:update API does a full replace, not incremental merge. The client always does GET → deep_merge → PUT internally. Never send partial data.

Recommended: Fast Path (nb_crud_page)

For standard CRUD pages, use nb_crud_page — it creates layout + KPIs + filter + table + forms + popup in ONE call:

nb_crud_page("tab_uid", "nb_crm_customers",
    '["name","code","status","industry","phone","createdAt"]',
    '--- 基本信息\nname* | code\ncustomer_type | industry\nstatus | level\n--- 联系方式\nphone | email\naddress',
    filter_fields='["name","status","industry"]',
    kpis_json='[{"title":"客户总数"},{"title":"已签约","filter":{"status":"已签约"},"color":"#52c41a"},{"title":"跟进中","filter":{"status":"跟进中"},"color":"#1890ff"}]',
    detail_json='[{"title":"客户详情","fields":"name | code\nstatus | level\nindustry | scale\nphone | email\naddress\nremark"},{"title":"联系人","assoc":"contacts","coll":"nb_crm_contacts","fields":["name","position","mobile","email"]}]')

This replaces 8+ individual tool calls with ONE call. Use this for every standard page.