pagesskill（pagesskill 表格）

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"]',
    '--- 基本信息\
name* | code\
customer_type | industry\
status | level\
--- 联系方式\
phone | email\
address',
    filter_fields='["name","status","industry"]',
    kpis_json='[{"title":"客户总数"},{"title":"已签约","filter":{"status":"已签约"},"color":"#52c41a"},{"title":"跟进中","filter":{"status":"跟进中"},"color":"#1890ff"}]',
    detail_json='[{"title":"客户详情","fields":"name | code\
status | level\
industry | scale\
phone | email\
address\
remark"},{"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.

When to use individual tools instead:

• Non-standard layouts (multiple tables on one page)
• JS blocks, event flows, outlines
• Page modifications after initial build

Manual Path (Individual Tools)

Phase 1: Menu Structure

Use nb_create_menu for the simplest approach:

nb_create_menu("Asset Management", top_group_id,
    '[["Asset Ledger","databaseoutlined"],["Purchases","shoppingcartoutlined"]]',
    group_icon="bankoutlined")

This creates a group + pages in one call, returning {"Asset Ledger": "tab_uid_1", "Purchases": "tab_uid_2"}.

Or build manually:

1. nb_create_group("Module Name", parent_id) — creates the folder
2. nb_create_page("Page Name", group_id) — creates each page

Phase 2: Page Content (Per Page)

For each page, follow this order:

Step 1: Create Page Layout

nb_page_layout("tab_uid")  →  returns grid_uid

This cleans existing content (idempotent) and creates a BlockGridModel.

Step 2: Create KPI Cards (Optional)

nb_kpi_block(grid, "Total", "nb_pm_projects")
nb_kpi_block(grid, "Active", "nb_pm_projects", filter_='{"status":"active"}', color="#52c41a")

Step 3: Create Filter/Search Bar

nb_filter_form(grid, "nb_pm_projects", '["name","code","description"]', target_uid=table_uid)

Parameters:

• label (str, default "Search"): Placeholder label for the search input.

Note: Create filter AFTER table (needs table_uid for target), but place it ABOVE in layout.

Step 4: Create Table Block

nb_table_block(grid, "nb_pm_projects",
    '["name","code","status","priority","createdAt"]',
    first_click=true, title="Projects")

Parameters:

• first_click (bool, default true): If true, the first column becomes click-to-open

(users click to view detail popup). Set to false if no detail popup needed.

• title (str, optional): Card header title displayed above the table.

Returns: {table_uid, addnew_uid, actcol_uid}

Step 5: Create AddNew Form

nb_addnew_form(addnew_uid, "nb_pm_projects",
    "--- Basic Info\
name* | code\
status | priority\
--- Details\
description")

Fields DSL syntax:

• name — single field, full width
• name* — required field
• name | code — two fields side by side (auto 12+12)
• name:16 | code:8 — explicit widths (total=24)
• --- Section Title — divider with label
• --- — plain divider

Step 6: Create Edit Action

nb_edit_action(actcol_uid, "nb_pm_projects",
    "--- Basic Info\
name* | code\
status | priority\
--- Details\
description")

Step 7: Set Layout

nb_set_layout(grid_uid, '[
    [["kpi1",6],["kpi2",6],["kpi3",6],["kpi4",6]],
    [["filter1"]],
    [["table1"]]
]')

Layout rules:

• Each row is an array of [uid, span] pairs
• Spans use Ant Design grid (total = 24 per row)
• [["uid"]] or [["uid",24]] = full width
• [["a",12],["b",12]] = two equal columns

Step 8: Detail Popup (Auto-Generated by Default)

You usually DON'T need to specify detail_json. When omitted in nb_crud_page, a "详情" tab is auto-generated using the same field layout as the Edit form (form_fields DSL minus * required markers). This gives every page a meaningful detail popup with zero extra work.

Only specify detail_json when you need:

• Sub-table tabs (e.g., customer → contacts, orders)
• JS blocks or custom layout inside the popup
• A different field layout from the edit form

# Custom detail popup (only when needed)
nb_detail_popup(click_field_uid, "nb_pm_projects", '[
    {"title":"Info", "fields":"--- Basic\\
name | code\\
status"},
    {"title":"Tasks", "assoc":"tasks", "coll":"nb_pm_tasks", "fields":["name","status"]}
]', mode="drawer", size="large")

Detail popup modes:

• mode="drawer" + size="large" — side panel, good for business detail pages
• mode="drawer" + size="medium" — smaller side panel, for reference data
• mode="dialog" + size="small" — modal dialog, for quick views

Finding the click field UID: The first column in a table created with first_click=true is clickable. Use the click_field_uid from the column's DisplayFieldModel. The field_name passed to the find function must match the first column's field name.

Multi-tab detail popup with sub-tables:

[
    {"title": "Details", "blocks": [
        {"type": "details", "fields": "--- Section 1\\
field1 | field2\\
field3"}
    ]},
    {"title": "Sub Items", "assoc": "items", "coll": "nb_order_items",
     "fields": ["name", "quantity", "price", "createdAt"]}
]

Note: The assoc sub-table requires an o2m relation to be defined between the parent and child collections.

Step 9: Outlines — Plan JS Capabilities (Recommended)

Use nb_outline to plan JS blocks/columns without writing actual code. A dedicated JS agent implements them later.

kind parameter (default "block"):

• "block" — creates JSBlockModel on page grid (for KPI cards, charts)
• "column" — creates JSColumnModel in a table (for status tags, computed columns)
• "item" — creates JSItemModel in a form (for computed form fields)

# KPI outline (page-level block)
nb_outline(grid, "Active Count", '{"type":"kpi","collection":"assets","filter":{"status":"active"}}')

# Table JS column outline
nb_outline(table_uid, "Status Tag", '{"type":"status-tag","field":"status","colors":{"active":"green"}}', kind="column")

# Event flow outline (in form)
nb_outline(form_grid, "Auto Total", '{"type":"event-flow","event":"formValuesChange","formula":"qty*price"}', kind="item")

Step 10: Event Flows (Optional)

nb_event_flow(form_uid, "formValuesChange",
    "const v=ctx.form?.values||{}; if(v.qty&&v.price) ctx.form.setFieldsValue({total:v.qty*v.price});")

Step 11: JS Columns — Direct Implementation (Alternative to Outlines)

nb_js_column(table_uid, "Status",
    "const s=(ctx.record||{}).status;ctx.render(ctx.React.createElement(ctx.antd.Tag,{color:s==='active'?'green':'red'},s||'-'))",
    width=100)

Parameters:

• width (int, optional): Column width in pixels. Omit for auto-width.

Phase 3: Verify & Debug — Three-Level Drill-Down

nb_inspect_all("CRM")            — system overview (~1 line per page, default)
nb_inspect_all("CRM", depth=1)   — full structure of every page

nb_inspect_page("客户列表")       — single page: forms, columns, popups, hidden-point annotations
                                    [JS 1200c] [2 events] [3 linkage] sort: field desc (drawer,large)

nb_read_node(uid, "events")      — deep-dive: JS code, event flows, linkage rules
nb_read_node(uid, "js")
nb_read_node(uid, "linkage")

Full tree (for raw UIDs): nb_show_page("Page Title")

Workflow: Debug → Locate → Fix

1. nb_inspect_page — find the problem area (empty popup, wrong layout, hidden-point hints)
2. nb_read_node(uid, "events") — see the actual event flow code or configuration
3. nb_event_flow / nb_patch_field / nb_js_block — fix it

Common Patterns

Standard CRUD Page

1. page_layout → grid
2. kpi_block × N → kpi cards
3. table_block → table + addnew + actcol
4. filter_form → search bar (target=table)
5. addnew_form → new record form
6. edit_action → edit record form
7. set_layout → arrange: KPIs row → filter → table
8. Optionally: detail_popup, js_column

KPI Row Pattern

kpi1 = nb_kpi_block(grid, "Total", collection)
kpi2 = nb_kpi_block(grid, "Active", collection, filter_='{"status":"active"}', color="#52c41a")
kpi3 = nb_kpi_block(grid, "Pending", collection, filter_='{"status":"pending"}', color="#faad14")
# Then in layout: [["kpi1",8],["kpi2",8],["kpi3",8]]

Multi-Block Detail Popup

[
    {"title": "Overview", "blocks": [
        {"type": "details", "title": "Info", "fields": "name | code\
status"},
        {"type": "js", "title": "Stats", "code": "ctx.render(...)"}
    ], "sizes": [14, 10]},
    {"title": "Tasks", "assoc": "tasks", "coll": "nb_pm_tasks",
     "fields": ["name", "status", "createdAt"]}
]

Page Modification & Debugging

For tweaking existing pages or diagnosing issues:

# 1. Overview — understand the page structure
nb_inspect_page("Page Title")

# 2. Find — locate a specific node
nb_locate_node("Page Title", field="status")  # returns UID
nb_locate_node("Page Title", block="addnew")  # find AddNew form

# 3. Debug — read node configuration
nb_read_node(uid, "events")     # event flow JS code
nb_read_node(uid, "js")         # JS block/column code
nb_read_node(uid, "linkage")    # button linkage rules

# 4. Fix — modify the node
nb_patch_field(uid, '{"required":true}')
nb_patch_column(column_uid, '{"width":120}')
nb_add_column(table_uid, collection, "new_field")
nb_remove_column(column_uid)
nb_event_flow(form_uid, "formValuesChange", "...")

nb_patch_field common patches:

nb_patch_field(uid, '{"required":true}')           # make field required
nb_patch_field(uid, '{"hidden":true}')             # hide field
nb_patch_field(uid, '{"defaultValue":"active"}')   # set default value
nb_patch_field(uid, '{"readOnly":true}')           # read-only field

nb_patch_column common patches:

nb_patch_column(uid, '{"width":120}')              # set column width
nb_patch_column(uid, '{"fixed":"left"}')           # pin column to left
nb_patch_column(uid, '{"title":"New Title"}')      # rename column header

nb_delete_route — remove a menu item:

nb_list_routes()                                    # find route_id
nb_delete_route(350416708763648)                     # delete group + children

Batch inspect — check all pages in a system:

nb_inspect_all("CRM")            # compact overview (1 line per page, default)
nb_inspect_all("CRM", depth=1)   # full structure of every page
nb_inspect_all()                  # ALL pages (compact)

Ant Design Icons

Common icons for menus: homeoutlined, settingoutlined, databaseoutlined, shoppingcartoutlined, bankoutlined, tooloutlined, formoutlined, barchartoutlined, piechartoutlined, idcardoutlined, caroutlined, containeroutlined, clusteroutlined, apartmentoutlined, environmentoutlined, shopoutlined, controloutlined, appstoreoutlined, inboxoutlined, deleteoutlined, swapoutlined, sendoutlined

Status Tag Colors

For ctx.antd.Tag in JS columns/blocks:

• Green: active, completed, approved → color: 'green' or '#52c41a'
• Blue: in progress, processing → color: 'blue' or '#1890ff'
• Orange: pending, warning → color: 'orange' or '#faad14'
• Red: error, rejected, overdue → color: 'red' or '#ff4d4f'
• Default: draft, inactive → color: 'default'