1flowbase · Schema UI 分层：画布节点、系统页面与插件设置页的边界

1flowbase 的 schema UI 不是一个统一的大 DSL。它按使用场景拆成几类协议：画布节点 UI、宿主容器、系统页面内容，以及插件配置表单。这样做的目的，是让插件和页面可以扩展，但不把节点专属语义、系统权限、React 组件实现和后端接口边界混在一起。

快速判断

用户在画布里编辑节点
  -> canvas_node_schema

用户点击按钮打开 Drawer / Modal / Dock
  -> overlay_shell_schema

系统设置页、插件管理页、普通页面区块显示内容
  -> page_block_schema

插件提供一组配置字段，宿主负责渲染和保存
  -> plugin_form_schema

最重要的区分是：

canvas_node_schema 是节点专属协议。
overlay_shell_schema 是容器外壳协议。
page_block_schema 是系统级页面内容协议。
plugin_form_schema 是插件配置字段协议，通常被 page block 或 overlay shell 承载。

总体结构

schema-ui runtime
├─ canvas_node_schema
│  └─ Agent Flow 节点卡片、节点详情、节点配置、运行态视图
├─ overlay_shell_schema
│  └─ Drawer / Modal / Dock 这类宿主容器
├─ page_block_schema
│  └─ 设置页、插件页、系统页面里的受控 UI primitive
└─ plugin_form_schema
   └─ 插件声明配置字段，宿主用通用控件渲染

底层 runtime 负责按 schema 找 renderer。当前核心形态是：

SchemaRenderer：按 field、view、dynamic_form、section、stack、inline、tabs 渲染 block。
RendererRegistry：宿主注册允许使用的 field / view / dynamic form / shell renderer。
SchemaAdapter：提供 getValue、setValue、getDerived、dispatch，让 renderer 不直接知道业务状态存在哪里。

canvas_node_schema：画布节点专属

canvas_node_schema 描述 Agent Flow 画布上的节点 UI。它不只是配置表单，而是完整节点 UI 的结构：

canvas_node_schema
├─ card
│  └─ 节点卡片上显示什么
├─ detail
│  ├─ header
│  └─ tabs
│     ├─ config
│     └─ lastRun
└─ runtimeSlots

它可以使用节点上下文，所以可以有很多节点专属 renderer：

上游变量选择器
模板文本输入
数据模型查询条件
LLM 模型选择
LLM 参数动态表单
HTTP request body 编辑
if / else 分支配置
state write 配置
输出变量定义
节点运行态 summary / input / output / metadata

这些 renderer 依赖节点上下文，例如上游输出、当前节点类型、数据模型字段、运行记录、节点配置对象等。它们不应该暴露给后台设置页或普通第三方插件页面。

适合放在这里的内容

节点卡片上的标题、模型 badge、描述。
节点详情里的 header、config tab、last run tab。
需要读写节点 config / bindings / runtime 的字段。
需要理解 Agent Flow 变量池、边、节点类型或运行状态的 UI。

不适合放在这里的内容

后台设置页 section。
插件安装页、插件配置页。
系统级资源表格。
普通配置表单。
任意第三方自定义 React 控件。

overlay_shell_schema：容器外壳

overlay_shell_schema 只描述一个内容用什么宿主容器打开。它关心的是“怎么出现”，不是“里面渲染什么”。

典型容器：

drawer_panel
modal_panel
dock_panel

它适合表达：

标题
宽度
shell 类型
是否关闭时销毁
Drawer / Modal 的宿主挂载行为

它不应该表达：

表单字段
表格列
节点变量选择器
插件配置数据结构
后端 API contract

示意：

点击配置按钮
  -> overlay_shell_schema 决定打开 Drawer
  -> Drawer 里面再承载 plugin_form_schema 或 page_block_schema

所以 overlay_shell_schema 是壳层协议，应该保持小而稳定。

page_block_schema：系统级页面内容

page_block_schema 描述系统页面或插件页面里的内容块。它更接近受控低代码 UI primitive，但仍然由宿主控制可用组件和能力。

它适合系统级页面，例如：

后台设置页 section
插件详情页
插件贡献的设置页内容
系统资源列表
简单状态面板
带白名单 action 的按钮区域

可用 primitive 应该是宿主白名单，例如：

Stack
Inline
Grid
Divider
Text
Title
Caption
Badge
Table
Descriptions
Empty
Alert
Form
FormItem
Input
Textarea
Select
Checkbox
Switch
DatePicker
NumberInput
Button
IconButton
Modal

这里的关键不是“让插件写页面代码”，而是让插件声明受控页面内容。宿主仍然负责：

primitive 白名单
样式 token 边界
action 白名单
data permission
route / slot 权限
字段 contract
后端数据来源

plugin_form_schema：插件配置字段

plugin_form_schema 是插件配置表单协议。插件可以声明字段，宿主负责渲染、校验、提交和保存。

它适合：

模型供应商插件配置。
host infrastructure provider 配置。
后续第三方插件注册到设置页后的配置表单。
Drawer / Modal / 页面 section 内的普通设置表单。

建议一期公开的字段类型：

string
number
integer
boolean
enum
json
secret

建议一期公开的 control：

input
textarea
number
slider
switch
select
json_editor
password

字段元数据：

key
label
description
placeholder
required
default_value
group
order
advanced
min
max
step
precision
unit
options
visible_when
disabled_when
send_mode
enabled_by_default

plugin_form_schema 不应该允许插件传入任意 React 组件名。插件只声明字段和规则，控件实现由 1flowbase 维护。

插件注册到设置页时怎么组合

一个插件设置页的推荐组合是：

settings slot
└─ page_block_schema
   ├─ Descriptions：插件状态
   ├─ Table：插件能力或实例列表
   └─ Button：打开配置
      └─ overlay_shell_schema：Drawer
         └─ plugin_form_schema：配置字段

也就是说：

页面上显示什么，用 page_block_schema。
弹层怎么打开，用 overlay_shell_schema。
弹层里的配置字段，用 plugin_form_schema。
如果是画布节点详情，不走这条系统页面协议，而走 canvas_node_schema。

边界规则

不能把节点 renderer 暴露给系统页面

这些属于节点语义，不应该进入系统级插件页面：

selector
selector_list
templated_text
data_model_query
llm_model
condition_group
if_else_branches
state_write
output_contract_definition
http_request_body

它们依赖 Agent Flow 节点上下文。放到系统页面里，会让页面 schema 偷偷依赖节点运行时。

不能让插件直接提供 React 控件

第三方插件可以提供 schema、字段、选项、默认值和规则，但不直接提供 React 组件。否则会破坏：

宿主 UI 一致性
样式边界
权限边界
前后端 contract
插件安全模型
后续升级兼容性

后端仍是唯一数据来源

前端 schema-ui 负责渲染和交互，不负责发明字段别名、兼容后端旧字段或改变业务语义。接口字段名应与后端 DTO / 领域语义保持一致；UI 展示名可以本地化。

普通 runtime / capability plugin 不能注册系统接口

插件页面注册不等于插件能注册新的系统 API。普通 runtime / capability plugin 只能使用宿主预定义的白名单能力槽位。系统接口扩展必须继续由 host 认可的扩展点控制。

当前实现状态

当前代码里已经有这些基础：

web/app/src/shared/schema-ui/runtime/SchemaRenderer.tsx
- schema runtime。
web/app/src/shared/schema-ui/registry/create-renderer-registry.ts
- renderer registry 和 adapter contract。
web/app/src/shared/schema-ui/contracts/canvas-node-schema.ts
- 画布节点 schema contract。
web/app/src/shared/schema-ui/contracts/overlay-shell-schema.ts
- Drawer / Modal / Dock shell contract。
web/app/src/shared/schema-ui/contracts/plugin-form-schema.ts
- 插件配置字段 contract。
web/packages/page-protocol/src/block-ui-schema.ts
- 系统级 page block primitive contract。
web/app/src/features/agent-flow/schema
- Agent Flow 节点专属 schema fragments 和 renderer registry。

当前还需要继续收敛的部分：

plugin_form_schema 的通用表单渲染仍分散在 LLM 参数、模型供应商配置、host infrastructure 配置等不同页面里。
后续应该抽出统一的 PluginSchemaForm，专门服务系统级插件配置。
PluginSchemaForm 不应吞并 canvas_node_schema，也不应复用节点专属 renderer。
page_block_schema 应继续作为系统页面内容协议推进，和 overlay shell 保持分离。