@lovrabet/rabetbase-cli 2.3.16-beta.7 → 2.4.1

package/skills/rabetbase/knowledge/page-schema/field-components.md

@@ -0,0 +1,312 @@
+---
+name: field-components
+description: Filter/Form 字段 componentName 速查及平台扩展属性。先验知识：低代码引擎搭建协议、Ant Design 5 组件知识。
+tags: [filter, form, field-components, page-schema]
+---
+
+# 字段 componentName 速查
+
+> **先验知识**：默认已具备低代码引擎搭建协议和 Ant Design 5 组件知识。本文档仅记录平台扩展属性。
+>
+> `LrSmartFilter` 与 `LrSmartCreate` / `LrSmartUpdate` / `LrSmartDetail` 共享部分字段组件能力，但并非完全等同。Filter 偏查询条件组件，Form 偏录入/编辑组件；具体支持范围以各组件文档为准。Ant Design 5 原生 props 可直接用于 `extendProps`。
+
+
+## 按宿主组件选型
+
+### LrSmartFilter 常用字段组件
+
+| 场景 | 推荐 componentName | 说明 |
+|------|--------------------|------|
+| 文本查询 | `YtInput` | 模糊搜索、关键字查询 |
+| 单选筛选 | `YtSingleSelect` | 枚举值或关联表单选 |
+| 多选筛选 | `YtMultiSelect` | 标签、多状态并集筛选 |
+| 小选项集单选 | `YtRadioGroup` | 选项较少时更直观 |
+| 小选项集多选 | `YtCheckboxGroup` | 选项较少的多选 |
+| 单日期 | `YtDatePicker` | 精确到某一天的筛选 |
+| 日期范围 | `YtRangeDatePicker` | 时间区间筛选的主力组件 |
+| 数字单值 | `YtInputNumber` | 单个数值条件 |
+| 数字范围 | `YtRangeInputNumber` | 区间数值筛选 |
+| 级联选择 | `YtCascader` | 层级分类筛选 |
+| 用户筛选 | `YtUserSelect` | 平台用户相关筛选 |
+| 地址筛选 | `YtAddressPicker` | 地址维度筛选 |
+
+**不推荐/不适用**：
+- `YtRichEditor`：不用于筛选场景
+- `YtUpload`：不用于筛选场景
+- `YtTextArea`：一般不作为筛选主组件
+- `YtSwitch`：仅在极少数布尔筛选场景使用，通常优先用选择类组件表达
+
+### LrSmartCreate / LrSmartUpdate / LrSmartDetail 常用字段组件
+
+| 场景 | 推荐 componentName | 说明 |
+|------|--------------------|------|
+| 单行录入 | `YtInput` | 名称、编号、邮箱、电话等 |
+| 数字录入 | `YtInputNumber` | 金额、数量、价格等 |
+| 多行录入 | `YtTextArea` | 备注、说明、简短描述 |
+| 富文本录入 | `YtRichEditor` | 详细内容、正文、复杂说明 |
+| 代码录入 | `YtCodeEditor` | JSON、JavaScript、TypeScript、SQL、CSS、HTML、Markdown 等代码/配置文本 |
+| 单选录入 | `YtSingleSelect` | 枚举值或关联表单选 |
+| 多选录入 | `YtMultiSelect` | 标签、多选枚举 |
+| 小选项集单选 | `YtRadioGroup` | 少量单选项 |
+| 小选项集多选 | `YtCheckboxGroup` | 少量多选项 |
+| 布尔录入 | `YtSwitch` | 是否启用、是否标品等 |
+| 单日期 | `YtDatePicker` | 日期/时间选择 |
+| 级联选择 | `YtCascader` | 层级分类录入 |
+| 文件上传 | `YtUpload` | 附件、图片、材料上传 |
+| 用户选择 | `YtUserSelect` | 平台用户选择 |
+| 地址录入 | `YtAddressPicker` | 地址信息录入 |
+
+**按场景谨慎使用**：
+- `YtRangeDatePicker`：更偏筛选语义，Form 中仅在明确需要录入时间区间时使用
+- `YtRangeInputNumber`：更偏筛选语义，Form 中通常不作为常规录入组件
+
+自动加载系统用户列表，值格式需按场景区分：
+
+- 业务字段（YtUserSelect 录入）：数组 `["80"]` / `["80","81"]`
+- 系统字段（creator_id / updater_id）：字符串 `"80"`
+- Filter 查询场景必须使用数组值，如 `["80"]`，运行时只对数组生成 `$in`
+
+```json
+{
+  "name": "employee_id",
+  "componentName": "YtUserSelect",
+  "label": "负责人"
+}
+```
+
+### YtAddressPicker
+
+自动加载省市区数据
+
+```json
+{
+  "name": "address",
+  "componentName": "YtAddressPicker",
+  "label": "联系地址"
+}
+```
+
+---
+
+## 数据格式速查
+
+| 组件 | 类型 | 初始值 | 用户输入 | 清空值 | 示例 |
+|------|------|--------|---------|--------|------|
+| YtInput | string | `""` / `null` | `"hello"` | `""` / `null` | `"客户名称"` |
+| YtInputNumber | number | `null` | `123` | `null` | `100.50` |
+| YtTextArea | string | `""` / `null` | `"多行文本"` | `""` / `null` | 备注内容 |
+| YtRichEditor | string | `""` / `null` | `"<p>...</p>"` | `""` / `null` | HTML 字符串 |
+| YtCodeEditor | string | `""` / `null` | 代码/配置文本 | `""` | JSON / JS / SQL 字符串 |
+| YtSingleSelect | string/number | `null` / `undefined` | 选中值 | `undefined` | `1` / `"vip"` |
+| YtMultiSelect | array | `[]` | `[value1, value2]` | `[]` | `[1, 2, 3]` |
+| YtRadioGroup | string/number | `null` | 选中值 | `null` | `"enterprise"` |
+| YtCheckboxGroup | array | `[]` | `[value1, value2]` | `[]` | `["phone", "email"]` |
+| YtSwitch | boolean | `false` | `true` / `false` | `false` | `true` |
+| YtDatePicker | number | `null` | 时间戳 | `null` | `1773014400000` |
+| YtRangeDatePicker | number[] | `[]` / `null` | `[startTimestamp, endTimestamp]` | `[]` / `null` | `[1767225600000, 1773014400000]` |
+| YtCascader | array | `[]` | `[level1, level2, ...]` | `[]` | `["浙江省", "杭州市", "西湖区"]` |
+| YtUpload | array | `[]` | `[{uid, name, url, ...}]` | `[]` | 文件对象数组 |
+| YtUserSelect | array / string | `null` | `["80"]` / `["80","81"]` | `null` | 业务字段数组 `["80"]`，系统字段字符串 `"80"` |
+| YtAddressPicker | array | `[]` | `[省, 市, 区]` | `[]` | `["浙江省", "杭州市", "西湖区"]` |
+
+### 关键格式说明
+
+- **YtSingleSelect**：初始值 `null` / `undefined`（不是空字符串）
+- **YtMultiSelect**：始终是数组，清空为 `[]`
+- **YtDatePicker**：运行时提交值为时间戳 number；`extendProps.format` 只控制展示格式
+- **YtRangeDatePicker**：运行时提交值为时间戳数组 `[startTimestamp, endTimestamp]`
+- **YtUserSelect**：业务字段为数组 `["80"]` / `["80","81"]`，系统字段存储可为字符串 `"80"`；Filter 查询值必须是数组
+- **YtCodeEditor**：只用于 Form 录入代码/配置文本，值为 string；Agent 必须显式生成 `language`，不要依赖默认值
+
+---
+
+## 基础示例
+
+```json
+// YtInput
+{"name": "customer_name", "componentName": "YtInput", "label": "客户名称", "extendProps": {"maxLength": 100}}
+
+// YtInputNumber
+{"name": "amount", "componentName": "YtInputNumber", "label": "金额", "extendProps": {"min": 0, "precision": 2}}
+
+// YtTextArea
+{"name": "remark", "componentName": "YtTextArea", "label": "备注", "extendProps": {"rows": 4, "maxLength": 500}}
+
+// YtCodeEditor（Form 场景代码/配置文本录入）
+{"name": "config_json", "componentName": "YtCodeEditor", "label": "配置内容", "language": "json", "height": 240, "placeholder": "请输入配置内容"}
+
+// YtSingleSelect（静态选项）
+{"name": "status", "componentName": "YtSingleSelect", "label": "状态", "options": [{"label": "活跃", "value": 1}, {"label": "流失", "value": 0}]}
+
+// 选择类动态选项（YtSingleSelect / YtMultiSelect 等，需配套 Page.dataSource.list getSelectOptions）
+{"name": "<FromRelationField>", "componentName": "<selectComponentName>", "label": "<fieldLabel>", "options": {"type": "JSExpression", "value": "this.state.dataset_<FromDatasetCode>_<FromRelationField>_options"}}
+
+// YtMultiSelect（静态选项）
+{"name": "tags", "componentName": "YtMultiSelect", "label": "标签", "options": [{"label": "重点", "value": "key"}, {"label": "潜在", "value": "potential"}]}
+
+// YtSwitch
+{"name": "is_active", "componentName": "YtSwitch", "label": "是否启用"}
+
+// YtDatePicker（仅日期；placeholder 用表单项顶层，勿放 extendProps）
+{"name": "expected_date", "componentName": "YtDatePicker", "label": "预计日期", "placeholder": "请选择日期", "extendProps": {"format": "YYYY-MM-DD", "picker": "date"}}
+
+// YtDatePicker（日期+时间，用于 datetime 类型字段）
+{"name": "created_at", "componentName": "YtDatePicker", "label": "创建时间", "extendProps": {"showTime": {"format": "HH:mm"}, "format": "YYYY-MM-DD HH:mm", "picker": "date"}}
+
+// YtRangeDatePicker
+{"name": "visit_time", "componentName": "YtRangeDatePicker", "label": "拜访时间"}
+
+// YtUserSelect
+{"name": "employee_id", "componentName": "YtUserSelect", "label": "负责人"}
+```
+
+## YtDatePicker 时间配置
+
+### 机制
+
+`showTime` 决定是否启用时间选择，`format` 控制显示格式，`picker` 指定基础选择器类型。datetime 类型字段需要 `showTime` + `format: "YYYY-MM-DD HH:mm"`，date 类型字段无需 `showTime`。
+
+### 参数
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| showTime | object \| boolean | 启用时间选择，`{format: "HH:mm"}` 控制时间格式 |
+| format | string | 日期时间显示格式，datetime 用 `"YYYY-MM-DD HH:mm"`，date 用 `"YYYY-MM-DD"` |
+| picker | string | 基础选择器类型：`date` / `week` / `month` / `quarter` / `year` |
+
+### 配置位置
+
+`picker` / `format` / `showTime` 写在 `extendProps`；`placeholder` 写在表单项顶层，禁止放入 `extendProps`。
+
+## 分层设计原则
+
+| 层级 | 职责 |
+|------|------|
+| **Page 层** | dataSource.list 配置数据请求 |
+| **formItem 层** | 绑定数据、字段元数据 |
+| **组件层** | 消费数据、渲染 |
+
+### 属性位置规则
+
+| 写在 formItem 顶层 | 写在 extendProps |
+|-------------------|-----------------|
+| placeholder, options, disabled, readonly | precision, min, max, format, showTime, picker, 其他 Ant Design 5 控件原生 props |
+
+禁止在 extendProps 中重复写顶层已有的属性。
+
+### options 数据获取方式
+
+| options 来源 | 配置位置 | Agent 生成规则 |
+|--------------|---------|----------------|
+| 平台数据集 / 关联关系 | `Page.dataSource.list` + 字段 `options` | 必须配置 `getSelectOptions` 数据源，并通过 `this.state.<dataSourceId>` 绑定 |
+| 三方链接 / 外部接口 / 外部静态资源 | 字段级 `optionsRequest` | 仅外部 options 源可用；禁止用于 `/getSelectOptions` |
+
+> hard rule：`getSelectOptions` 是 Page 数据源能力，Agent 必须生成 Page 层 `dataSource.list` + state 绑定，不生成 `optionsRequest`。即使 `optionsRequest` 技术上能请求完整接口，也会把字段配置耦合到具体域名或部署环境，客户私有化部署、域名切换时会产生迁移成本。
+>
+> `YtSingleSelect`、`YtMultiSelect` 等选择类组件使用平台数据集 / 关联关系动态 options 时，加载机制一致：都必须生成 Page 层 `dataSource.list` 的 `getSelectOptions`，并通过字段 `options` 绑定同名 state；差异仅在字段值是单值还是数组。`<selectComponentName>` 按字段类型选择具体组件，如 `YtSingleSelect` 或 `YtMultiSelect`。
+
+```json
+// ✅ 平台数据集关联关系：Page 层预配置 getSelectOptions
+{
+  "type": "fetch",
+  "id": "dataset_<FromDatasetCode>_<FromRelationField>_options",
+  "isInit": true,
+  "source": "dataset",
+  "options": {
+    "method": "POST",
+    "uri": "/api/<appCode>/<ToDatasetCode>/getSelectOptions",
+    "params": {"code": "<ToValueField>", "label": "<ToLabelField>"}
+  }
+}
+
+// Form / Filter 字段绑定 state（YtSingleSelect / YtMultiSelect 等选择类组件通用）
+{
+  "name": "<FromRelationField>",
+  "componentName": "<selectComponentName>",
+  "options": {
+    "type": "JSExpression",
+    "value": "this.state.dataset_<FromDatasetCode>_<FromRelationField>_options"
+  }
+}
+
+// ✅ 三方链接 / 外部接口：字段级 optionsRequest
+{
+  "name": "external_level",
+  "componentName": "YtSingleSelect",
+  "optionsRequest": {
+    "url": "https://example.com/options/levels.json",
+    "dataProcess": {
+      "type": "JSFunction",
+      "value": "(data) => data.map(item => ({ label: item.name, value: item.id }))"
+    }
+  }
+}
+
+// 说明：dataProcess 是函数型字段。Agent 生成 PageSchema 时使用 JSFunction；
+// 若绕过 PageSchema 运行时直接传给物料组件，则应传入真实函数。
+
+// ❌ 错误：使用 optionsRequest 调 getSelectOptions
+// 运行时会按当前页面域名解析相对 /api 路径，不会使用 Page 数据源的接口域名；
+// 页面域名与接口域名不一致时会请求错地址。
+{
+  "optionsRequest": {
+    "url": "/api/<appCode>/<ToDatasetCode>/getSelectOptions?code=id&label=name"
+  }
+}
+
+// ❌ 错误：把完整域名写进 getSelectOptions
+// 即使当前环境可用，也会把 schema 耦合到某个租户域名或部署环境。
+{
+  "optionsRequest": {
+    "url": "https://<tenant-domain>/api/<appCode>/<ToDatasetCode>/getSelectOptions?code=id&label=name"
+  }
+}
+```
+
+#### 关联关系 From / To 规则
+
+- `dataSource.id = dataset_<FromDatasetCode>_<From表关联字段名>_options`，其中 `FromDatasetCode` 为 From 表字段所属数据集的 code
+- `dataSource.isInit = true`
+- `dataSource.source = "dataset"`
+- `uri = /api/<appCode>/<ToDatasetCode>/getSelectOptions`
+- `params.code = <To表被关联字段，通常是 id>`
+- `params.label = <To表展示字段>`
+- 字段 `options` 绑定 `this.state.dataset_<FromDatasetCode>_<From表关联字段名>_options`
+- 自关联父子关系中，`FromDatasetCode` 与 `ToDatasetCode` 可以相同；state key 仍按 `dataset_<FromDatasetCode>_<FromRelationField>_options` 命名，URI 仍使用 To 侧 options 数据源。
+
+---
+
+## 字段组件选型规则
+
+本节按 Agent 生成时的选型优先级和运行时依赖记录组件。生成 `componentName` 时必须使用真实运行时注册名，不要按相似名称猜测组件名。
+
+### 强平台依赖组件
+
+| 组件 | 依赖 / 定制点 | Agent 生成约束 |
+|------|---------------|----------------|
+| `YtUserSelect` | 读取当前应用 `appCode`，请求平台用户接口 `/api/dept/queryAppUser` | 用户字段用数组值；Filter 查询值必须是数组 |
+| `YtUpload` | 依赖平台上传接口 `/api/common/uploadFile`、运行时域名、当前应用 `appCode` 和平台文件预览能力 | 仅用于 Form；值为文件对象数组 |
+| `YtAddressPicker` | 默认加载 Lovrabet 地址资源 `https://www.lovrabet.com/external/regions.json` | 值为地址路径数组；不用于关联表 `getSelectOptions` |
+| `YtRichEditor` | 动态加载 Lovrabet CDN 富文本 UMD 资源 | 仅用于 Form；值为 HTML 字符串 |
+
+### 推荐优先使用的字段组件
+
+| 组件 | 适用语义 | Agent 生成约束 |
+|------|----------|----------------|
+| `YtCodeEditor` | 代码、脚本、SQL、JSON、配置内容 | 仅用于 Form；必须显式生成 `language` |
+| `YtAmountInput` | 金额、价格、费用 | 值为 number |
+| `YtCurrencySelect` | 币种 | 必须使用真实运行时注册名 `YtCurrencySelect` |
+
+### 低频语义组件
+
+以下组件只有在用户需求或字段语义明确命中时使用，不作为默认选型；不要因为它们以 `Yt` 开头就优先使用。
+
+- `YtInputPassword`
+- `YtRate`
+- `YtTransfer`
+- `YtSingleTreeSelect`
+- `YtMultiTreeSelect`
+- `YtTimePicker`
+- `YtRangeTimePicker`
+
+---

package/skills/rabetbase/knowledge/page-schema/syntax-reference.md

@@ -0,0 +1,278 @@
+---
+name: PageSchema-syntax-reference
+description: PageSchema 平台扩展语法规范。先验知识：低代码引擎搭建协议、Ant Design 5 组件知识。
+tags: [page-schema, syntax, reference]
+---
+
+# PageSchema 语法参考（平台扩展）
+
+> **先验知识**：默认已具备低代码引擎搭建协议和 Ant Design 5 组件知识。本文档仅记录平台特有扩展。
+
+---
+
+## 1. JSFunction vs JSExpression 关键差异
+
+| 特性 | JSFunction | JSExpression |
+|-----|-----------|-------------|
+| **解析方式** | `new Function("return " + value)()` | `new Function("$scope", "with($scope) { return " + value + " }")(self)` |
+| **简写支持** | ❌ 不支持 `state.xxx` | ✅ 支持 `state.xxx` 简写 |
+| **适用场景** | 函数定义（按钮、校验、render） | 动态表达式（属性值、条件判断） |
+
+```json
+// ❌ 错误：JSFunction 不支持 state 简写
+{"type": "JSFunction", "value": "() => state.filterValues"}  // state 未定义
+
+// ✅ 正确：JSFunction 通过参数访问
+{"type": "JSFunction", "value": "(config) => config._context.state.filterValues"}
+
+// ✅ 正确：JSExpression 支持简写
+{"type": "JSExpression", "value": "state.filterValues"}
+```
+
+**state key 限制**：`this.state.xxx` 中的 key（如 `filterValues`）由组件初始化时自动生成，Agent 不可修改或重命名。只能读取和引用已有的 state key。
+
+---
+
+## 2. 按钮配置（optType + options）
+
+**禁止使用 onClick**，必须使用 `optType + options` 结构。
+
+### 顶层按钮 optType 类型
+
+| optType | 说明 | options 关键字段 |
+|---------|------|-----------------|
+| `jsAction` | 执行 JavaScript 函数 | `jsFunction` |
+| `flowAction` | 执行流程 | `flowList` |
+
+### flowAction 的 flowList 子动作 optType 类型
+
+| optType | 说明 | options 关键字段 |
+|---------|------|-----------------|
+| `request` | 发送请求 | `_bindDataSource`, `_bindDataSourceParams`, `confirmConfig` |
+| `submit` | 表单提交 | `_bindForm`, `_bindDataSource` |
+| `reset` | 表单重置 | `_bindForm` |
+| `jsAction` | 执行 JavaScript 函数 | `jsFunction` |
+| `message` | 消息提示 | `type`, `content`, `duration` |
+
+### 示例
+
+```json
+// jsAction：页面跳转
+{
+  "title": "更新",
+  "optType": "jsAction",
+  "options": {
+    "jsFunction": {
+      "type": "JSFunction",
+      "value": "(config) => config._context?.appHelper?.yt?.smartPageHistory?.push({ pageTagName: 'UPDATE', datasetId: '<datasetId>', dataid: config.extraParams?.rowKey })"
+    }
+  }
+}
+
+// flowAction + request：删除
+{
+  "title": "删除",
+  "optType": "flowAction",
+  "options": {
+    "flowList": [{
+      "active": true,
+      "optType": "request",
+      "options": {
+        "_bindDataSource": "<datasetId>_delete",
+        "_bindDataSourceParams": {
+          "type": "JSFunction",
+          "value": "(extraParams) => { return { id: extraParams.rowKey?.toString() }; }"
+        },
+        "confirmConfig": { "enable": true, "title": "确认删除", "content": "确认删除该条数据吗？" }
+      }
+    }]
+  }
+}
+
+// flowAction + message：提示消息
+{
+  "title": "保存成功提示",
+  "optType": "flowAction",
+  "options": {
+    "flowList": [{
+      "active": true,
+      "optType": "message",
+      "options": {
+        "type": "success",
+        "content": "操作成功",
+        "duration": 3
+      }
+    }]
+  }
+}
+```
+
+---
+
+## 3. 事件处理（events）
+
+### Agent 生成边界
+
+当前运行时不消费字段组件上的 `events.onChange` / `events.onMount`，也没有字段级 context 联动方法实现。
+
+Agent 不应为 `LrSmartCreate` / `LrSmartUpdate` / `LrSmartDetail` / `LrSmartFilter` 的字段项生成字段级 `events` 联动 schema。
+
+### 字段联动决策表
+
+| 组件场景 | Agent 应该怎么生成 | 不要生成 |
+|----------|--------------------|----------|
+| 表单型组件字段联动 | 在组件 props 顶层生成 `fieldReactions`；返回“字段名 → 字段属性覆盖”的对象。当前适用于 `LrSmartCreate` / `LrSmartUpdate`，详情展示控制同理遵循 Form 机制 | `items[].events.onChange`、字段级 context 方法 |
+| `LrSmartFilter` 筛选搜索 | 生成宿主级 `events.onSearch`，用于刷新消费 filter state 的数据源 | 筛选项之间的实时字段联动、`fieldReactions`、`items[].events.onChange` |
+| 字段静态隐藏 | 在字段 item 上设置 `hidden` 或 `isShown` | 通过字段级事件动态 setFieldVisible |
+
+`fieldReactions` 只用于表单型组件，不用于 `LrSmartFilter`。返回对象的 key 是被联动字段 `name`，value 是要覆盖的字段属性，例如 `isShown`、`hidden`、`disabled`、`rules`、`options`。具体示例见 `LrSmartCreate.md`。
+
+### 当前可生成的事件入口
+
+| 入口 | 适用场景 | Agent 生成规则 |
+|------|----------|----------------|
+| `optType + options` | 按钮点击、提交、请求、跳转、提示消息 | 标准按钮协议，见 § 2 |
+| 宿主级 `events` | 表单提交、默认值加载完成、筛选搜索、表格行/分页事件 | 仅在组件文档明确给出事件名时生成 |
+| `fieldReactions` | 表单型组件字段显隐、禁用、选项等联动覆盖 | 仅用于表单型组件，不用于 Filter；具体见 `LrSmartCreate.md` |
+
+### 禁止生成模式
+
+不要为字段项生成字段级 `events` 联动 schema，也不要假设存在字段级 context 联动方法。表单型组件字段联动使用 `fieldReactions`；Filter 字段联动当前不作为 Agent 默认生成能力。
+
+---
+
+## 4. 数据绑定（平台扩展字段）
+
+以下划线 `_` 开头的属性是平台扩展字段：
+
+| 属性 | 说明 |
+|------|------|
+| `_bindDataSource` | 绑定数据源 ID（如 `"<datasetId>_filter"`） |
+| `_bindForm` | 绑定表单 ID |
+| `_bindDataSourceParams` | 数据源参数（JSFunction） |
+| `_autoBindDataSourceParams` | 自动绑定表单参数（`true`） |
+
+```json
+{
+  "_bindDataSource": "<datasetId>_delete",
+  "_bindDataSourceParams": {
+    "type": "JSFunction",
+    "value": "function(extraParams) {\n  return { id: extraParams.rowKey };\n}"
+  }
+}
+```
+
+> `_bindDataSourceParams` 仅用于操作型数据源（如 `_delete`、`_create`、`_update`）。filter 查询数据源的 where/orderBy/select 由组件属性自动同步，不可通过 `_bindDataSourceParams` 注入。
+
+**数据源唯一性原则**：
+
+- `datasource.params` 和 `datasource.willFetch` 由平台根据组件属性自动同步生成
+- Agent 只需修改组件属性（如 `initialValue`、`defaultSortOrder`），不应直接修改 `datasource` 配置
+- 示例：筛选器默认值通过 `items[].initialValue` 配置，自动同步到 `datasource.params.filter`
+
+---
+
+## 5. config 对象结构（按钮 JSFunction 参数）
+
+| 属性 | 说明 |
+|------|------|
+| `config._context` | 组件上下文（含 appHelper、state 等） |
+| `config.extraParams` | 额外参数（如行数据 `rowKey`） |
+| `config.getFlowActionInfo()` | 获取流程执行结果 |
+
+### JSFunction 作用域
+
+JSFunction 通过 `new Function("return " + value)()` 执行，作用域中只有：
+
+| 可用对象 | 来源 | 说明 |
+|---------|------|------|
+| `config` | 函数参数 | `_context`、`extraParams` 等 |
+| `window.antd` | UMD externals | antd 全部组件（Modal、message 等） |
+| `window.__GLOBAL__` | 平台注入 | 用户信息等，见 § 6 |
+| `window.*` | 浏览器原生 | `window.open`、`console` 等 |
+
+不可直接使用裸名（如 `Modal`、`Button`），必须从 `window.antd` 解构：
+
+```javascript
+// ✅ 正确
+(config) => { const { Modal } = window.antd; Modal.info({ title: '提示', content: '内容' }); }
+
+// ❌ 错误：Modal is not defined
+(config) => { Modal.info({ title: '提示', content: '内容' }); }
+```
+
+> 与 LrSmartJsx 的区别：LrSmartJsx 的 `render.source` 支持 `import { Modal } from 'antd'`（编译时转译为 `const { Modal } = window.antd`），JSFunction 不经过编译，必须手动解构。
+
+---
+
+## 6. 平台全局对象（window.__GLOBAL__）
+
+### userInfo 当前用户信息
+
+**类型定义**：
+
+```typescript
+window.__GLOBAL__.userInfo: {
+  userId: string;      // 用户ID
+  nickname: string;    // 用户昵称
+  username: string;    // 用户登录账号
+  mobile: string;      // 用户手机号码
+  email?: string;      // 邮箱（可选）
+  image?: string;      // 用户头像（可选）
+}
+```
+
+**高频业务场景**：
+
+| 场景 | 字段 | 用途 | 示例 |
+|------|------|------|------|
+| 快捷过滤按钮 | `userId` | 筛选"我创建的"、"我负责的"数据 | `{ creator_id: { $in: [userId] } }` |
+| 表单默认值 | `userId` | 自动填充创建人、负责人 | `initialValue: window.__GLOBAL__.userInfo.userId` |
+| 联系方式回填 | `mobile` / `email` | 自动填充联系人信息 | `initialValue: window.__GLOBAL__.userInfo.mobile` |
+
+**访问方式**：
+
+```javascript
+// JSFunction 中访问
+const currentUserId = window.__GLOBAL__?.userInfo?.userId;
+
+// JSExpression 中不支持（需通过 JSFunction 传递）
+```
+
+**注意事项**：
+
+- `window.__GLOBAL__` 是平台运行时注入的全局对象，仅在浏览器环境可用
+- 访问时建议使用可选链 `?.` 避免未定义错误
+- `userId` 为字符串类型（如 `"80"`），与数据库 ID 类型保持一致
+
+---
+
+## 7. 点号字段（引用表字段）
+
+引用表字段使用 `关联表名.字段名` 的点号语法，如 `customer.customer_name`。
+
+**底层支持**：仅 filter 接口支持点号字段，可用于 `select`、`where`、`orderBy`。
+
+```typescript
+// filter 接口示例
+await client.models.dataset_xxx.filter({
+  select: ["opportunity_name", "customer.customer_name"],
+  where: { "customer.customer_type": { "$eq": "企业" } },
+  orderBy: [{ "customer.customer_name": "asc" }]
+})
+```
+
+**限制**：
+- 仅支持一级关联（`relation.field`），不支持 `a.b.c`
+- 关联关系必须在数据集 `relations` 中定义
+- create / update / getOne 等其他接口不支持点号语法
+
+数据集关系的主子表声明、字段方向和验收规则见 [数据集关系声明](dataset-relations.md)。
+
+---
+
+## 8. 数据集关系：主子表
+
+主子表是数据集关系元数据，用于表示一条主记录对应多条明细记录。通过 Rabetbase CLI 写入时，关系基数使用 `--cardinality ONE_TO_MANY`，业务类型使用 `--biz-relation-type main_sub`，并保证主表被引用字段与子表关联字段真实匹配。
+
+页面通过 `relation.field` 消费已定义的关系；它不会因为声明主子表而自动生成子表布局或交互。不要将数据集内部关系对象直接复制到 CLI 请求或 PageSchema props；完整字段说明、示例与校验规则见 [数据集关系声明](dataset-relations.md)。