nocobase-ui-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

目标

Objective

通过

desktopRoutes

与

flowModels

MCP 工具处理 NocoBase Modern page (v2) 页面与区块。

这个 skill 覆盖：

create / read / update / move / delete 页面、tab、block、action、JS model
route-ready、readback、payload guard 驱动的结构化交付
validation / review / improve / smoke，但只在用户明确要求时进入

顶层

SKILL.md

只保留触发边界、统一入口、少量硬 gate 和最终汇报轴。具体任务路由、recipe、block/pattern/JS 契约都以下面的 canonical docs 为准：

references/index.md

Process NocoBase Modern page (v2) pages and blocks using the

desktopRoutes

and

flowModels

MCP tools.

This skill covers:

create / read / update / move / delete pages, tabs, blocks, actions, JS models
structured delivery driven by route-ready, readback, payload guard
validation / review / improve / smoke, but only initiated when explicitly requested by the user

The top-level

SKILL.md

only retains trigger boundaries, unified entry points, a small number of hard gates, and final reporting axes. Specific task routing, recipes, block/pattern/JS contracts are all subject to the following canonical docs:

references/index.md

何时触发

When to Trigger

用户要创建、读取、更新、移动、删除 Modern page (v2) 页面或区块
用户要用
```
desktopRoutes v2
```
/
```
flowModels
```
修改现有 Modern page
用户要求 route-ready、readback、guard 或结构化 validation 结论
用户明确要求 validation / review / improve / smoke / 浏览器验证

The user wants to create, read, update, move, or delete Modern page (v2) pages or blocks
The user wants to modify existing Modern pages using
```
desktopRoutes v2
```
/
```
flowModels
```
The user requests route-ready, readback, guard, or structured validation conclusions
The user explicitly requests validation / review / improve / smoke / browser validation

何时不要触发

When Not to Trigger

只处理 collections / fields / relations：改用
```
nocobase-data-modeling
```
只处理 workflow：改用
```
nocobase-workflow-manage
```
只做 MCP 安装或连接：改用
```
nocobase-mcp-setup
```

Only handling collections / fields / relations: use
```
nocobase-data-modeling
```
instead
Only handling workflows: use
```
nocobase-workflow-manage
```
instead
Only doing MCP installation or connection: use
```
nocobase-mcp-setup
```
instead

统一入口

Unified Entry Point

先打开 references/index.md。
按任务路由补读对应 canonical docs、recipes、block docs、pattern docs、JS docs。

除

rest_validation_builder.mjs

rest_template_clone_runner.mjs

这类内建流水线外，默认只通过

node scripts/ui_write_wrapper.mjs run --action <create-v2|save|mutate|ensure> ...

执行写入。

wrapper 内部负责
```
start-run -> guard -> write -> readback
```
；不要在外层手动拆流程。
validation / review / improve 只有在用户明确要求时才进入；未进入浏览器验证时，
```
browser_attach
```
/
```
smoke
```
要记为
```
skipped
```
。

First open references/index.md.
Read the corresponding canonical docs, recipes, block docs, pattern docs, JS docs according to task routing.

Except for built-in pipelines like

rest_validation_builder.mjs

rest_template_clone_runner.mjs

, writing is only executed via

node scripts/ui_write_wrapper.mjs run --action <create-v2|save|mutate|ensure> ...

by default.

The wrapper internally handles
```
start-run -> guard -> write -> readback
```
; do not manually split the process at the outer layer.
Validation / review / improve are only initiated when explicitly requested by the user;
```
browser_attach
```
/
```
smoke
```
should be marked as
```
skipped
```
if browser validation is not performed.

默认硬 gate

Default Hard Gates

只要能探测，就不要猜
```
use
```
、slot、
```
requestBody
```
结构。
任何探测或写操作前都必须先
```
start-run
```
；不要先探测、后补日志。

裸

PostDesktoproutes_createv2

PostFlowmodels_save

PostFlowmodels_mutate

PostFlowmodels_ensure

默认全部禁用；agent 默认只能走

ui_write_wrapper.mjs

或已内置完整验证链路的 builder 流水线。

```
preflight_write_gate.mjs
```
、
```
flow_write_wrapper.mjs
```
现在是底层/兼容组件，不再是默认 agent 入口；不要手动拆成“先 gate、再自己写、再自己补 readback”。
```
createV2
```
成功只代表
```
page shell created
```
；没有 route-ready 与 anchor readback 证据前，不得报页面 ready。
```
save
```
/
```
mutate
```
/
```
ensure
```
返回
```
ok
```
只代表请求提交成功；最终以后续 readback 为准。
对现有页面默认做局部补丁，不要为了局部改动重建整棵页面树。
未经 schema / graph 放行的内部、未解析或高风险 model/use，不得直接写入。
除非用户明确要求打开浏览器、进入页面或做 runtime / smoke 验证，否则不要主动 attach / launch 浏览器。
validation 结论必须拆开
```
page shell
```
、
```
route-ready
```
、
```
readback
```
、
```
data
```
、
```
runtime
```
，不能合并成一个“成功”。
live tree patch 禁止靠“旧 uid + 新 parent/subKey/subType”做 reparent；需要移动、克隆或重挂载业务子树时，默认 fresh remap descendants，而不是复用旧 block uid。
只要
```
gridSettings.rows
```
与
```
subModels.items
```
成员不一致，就视为高风险坏树；
```
save ok
```
但 readback 没有稳定
```
items
```
/ slot membership 时，一律不得报成功。

Do not guess the structure of
```
use
```
, slot, or
```
requestBody
```
if detection is possible.
Must execute
```
start-run
```
before any detection or write operation; do not detect first and then supplement logs.
Bare
```
PostDesktoproutes_createv2
```
/
```
PostFlowmodels_save
```
/
```
PostFlowmodels_mutate
```
/
```
PostFlowmodels_ensure
```
are disabled by default; agents can only use
```
ui_write_wrapper.mjs
```
or builder pipelines with a complete built-in validation chain by default.
```
preflight_write_gate.mjs
```
and
```
flow_write_wrapper.mjs
```
are now underlying/compatibility components and are no longer the default agent entry points; do not manually split into "gate first, write manually, then supplement readback manually".
A successful
```
createV2
```
only means
```
page shell created
```
; do not report that the page is ready without evidence of route-ready and anchor readback.
An
```
ok
```
return from
```
save
```
/
```
mutate
```
/
```
ensure
```
only means the request was submitted successfully; the final result is subject to subsequent readback.
By default, apply partial patches to existing pages; do not rebuild the entire page tree for local changes.
Internal, unparsed, or high-risk model/use that are not approved by schema / graph cannot be written directly.
Do not actively attach / launch the browser unless the user explicitly requests to open the browser, access the page, or perform runtime / smoke validation.
Validation conclusions must be split into
```
page shell
```
,
```
route-ready
```
,
```
readback
```
,
```
data
```
,
```
runtime
```
; cannot be merged into a single "success".
Live tree patches are prohibited from reparenting via "old uid + new parent/subKey/subType"; when moving, cloning, or remounting business subtrees, fresh remap descendants by default instead of reusing old block uids.
If
```
gridSettings.rows
```
and
```
subModels.items
```
members are inconsistent, it is considered a high-risk bad tree; if
```
save ok
```
but readback does not have stable
```
items
```
/ slot membership, do not report success under any circumstances.

validation / review 子路径

Validation / Review Subpath

只有在用户明确要求 validation / review / improve / smoke 时才进入这一支：

结构化 validation 规则见 references/validation.md
run log、phase/gate、report、improve 规则见 references/ops-and-review.md

如果用户没有明确要求浏览器验证：

只做到 route-ready、readback、data-ready 这一级

browser_attach

smoke

记为

skipped (not requested)

```
runtime-usable
```
汇报为
```
not-run
```

Only enter this branch when the user explicitly requests validation / review / improve / smoke:

Structured validation rules can be found in references/validation.md
Rules for run log, phase/gate, report, improve can be found in references/ops-and-review.md

If the user does not explicitly request browser validation:

Only proceed to the route-ready, readback, data-ready stage

Mark

browser_attach

smoke

skipped (not requested)

Report
```
runtime-usable
```
as
```
not-run
```

最终汇报轴

Final Reporting Axes

最终说明和 review report 默认至少单独汇报这些轴：

```
pageShellCreated
```
```
routeReady
```
```
readbackMatched
```
```
dataReady
```
```
runtimeUsable
```
```
browserValidation
```
```
dataPreparation
```
```
pageUrl
```

允许出现的保守状态包括：

```
not-recorded
```
```
evidence-insufficient
```
```
skipped (not requested)
```
```
not-run
```

没有 route-ready 或 readback 证据时，不要写“页面已可打开”或“已落库完成”。

如果本轮实际创建或更新了页面，并且能够拿到

adminBase

、候选页面 URL 或其他可推导地址，最终结果必须给出实际页面 URL，方便用户点击查看；只有确实无法推导时，才允许说明阻塞原因。

The final explanation and review report must separately report at least these axes by default:

```
pageShellCreated
```
```
routeReady
```
```
readbackMatched
```
```
dataReady
```
```
runtimeUsable
```
```
browserValidation
```
```
dataPreparation
```
```
pageUrl
```

Allowed conservative states include:

```
not-recorded
```
```
evidence-insufficient
```
```
skipped (not requested)
```
```
not-run
```

Do not write "the page is ready to open" or "has been saved to the database" without route-ready or readback evidence.

If a page was actually created or updated in this round, and the

adminBase

, candidate page URL, or other derivable address can be obtained, the final result must provide the actual page URL for the user to click and view; only explain the blocking reason if it is truly impossible to derive.