weaver-e10-builder 1.5.16 → 1.6.0

package/skill-docs/references/common/ref-cli-commands.md

@@ -39,6 +39,8 @@
 | 命令 | 说明 |
 | --- | --- |
 | `e10-cli form-engine layout-template advanced scaffold --out <文件>` | 生成高级 PC 模板最小设计配置 |
+| `e10-cli form-engine layout-template catalog [--kind easy\|advanced\|flow\|all] [--name <名称>] [--enabled-only]` | 统一查询 PC 简易、高级和流式模板，显示类别、系统属性与启用状态 |
+| `e10-cli form-engine layout-template flow get <模板ID>` | 读取 PC 流式模板的完整样式配置 |
 | `e10-cli form-engine layout-template advanced create --config @<文件>` | 创建高级 PC 模板；配置可含 `layoutStyle` 设置已支持的布局样式 |
 | `e10-cli form-engine layout-template advanced list|get <模板ID>` | 列出模板或读取指定模板概要 |
 | `e10-cli form-engine layout-template advanced style show <模板ID>` | 查看模板当前布局样式 |
@@ -50,7 +52,7 @@
 | `e10-cli form-engine layout-template advanced delete <模板ID> [更多ID...]` | 批量删除自定义高级 PC 模板，预先检查并回读确认 |
 | `e10-cli form-engine layout-template easy delete <模板ID> [更多ID...]` | 批量删除自定义简易模板，预先检查并回读确认 |
 
-配置项和适用范围见 `references/form/form-template/style-templates-advanced.md`。
+配置项和适用范围见 `references/form/layout/template/advanced.md`。
 
 | 命令 | 说明 |
 |------|------|
@@ -114,7 +116,7 @@
 | `e10-cli form-engine browser-definition inspect\|describe <formId> [<fieldId>] --module ebuilderform\|workflow\|biaoge [--app-id <appId>] [--workflow-id <id>]` | 先列出表单内可配置的浏览字段、各字段高级搜索／范围／Tab 的平台支持和 CLI 适配状态；再查询指定字段的候选项与当前配置。EB 表单须提供 `--app-id`。工作流程表单在表单引擎中没有独立入口，须到所属工作流程的「高级设置 → 浏览数据定义」配置；CLI 用关联表单 ID 加 `--module workflow --workflow-id <流程ID>`。详见 `form/guide-browser-definition.md` |
 | `e10-cli form-engine browser-definition search\|scope\|tabs get\|set <formId> <fieldId> --module ...` | 按字段已开放的能力分别配置高级搜索、数据范围和浏览 Tab；`get` 先读候选结构与现值，`set` 写入并回读。不同浏览来源走不同适配器，未适配项明确拒绝。详见 `form/guide-browser-definition.md` |
 | `e10-cli form validate list <objId> <appId>` | 查看表单**查重规则**（字段重复校验，多字段 AND）。`add <objId> <appId> <字段名...> [--help 提示] [--remind]` 新增（缺省禁止提交 NOSUBMISSION，`--remind` 仅提醒）。**`--help` 会建成多语言标签、存的是标签 id**（平台只收 id，传文本会被拒「提示内容格式不正确」；`list` 会解回文本显示，缓存原因刚建完约 10 秒内可能仍显示 id）；`update <objId> <appId> <ruleId> [--fields <名...>] [--help <文本>] [--remind\|--no-remind]` **修改**（只改传入项，其余保持；**checkFields 是整组替换**，命令内部会把完整字段一起回传，不会丢字段；`--help` 支持 `#[字段名]#` 插入变量，自动转成平台片段 `<a>#[字段id]#</a>`，也支持 `@文件`）；`delete <objId> <appId> <ruleId>` 删除。项目名称重名/工时日期重复不允许 |
-| `e10-cli form add-detail-table <objId> <appId> <明细表名> [首字段名] [--no-place] [--init]` | 给**已存在的主表**加明细子表（saveSubForm 建子表 + 加首字段使其可见），**默认增量放进现有布局**（复制临时布局取平台生成的容器组件，原布局不重建）。`--data-key <物理表名>`、`--first-field-type <类型>`（默认 Text）、`--first-field-data-key <编码>`（首字段字段编码，缺省取首字段名拼音首字母，与 `add-field` 一致）。⚠ **空子表平台会过滤掉、布局里看不见**，首字段名强烈建议传；`--no-place` 只建表不排布局；`--init` 改用整表重建（会换样式模板并重排已有位置）。后续往明细里加字段用 `form add-field --sub-form-id <subFormId>`：建表时一次性带明细用 `form create` 的 fields.json `DetailTable`+`formFields`。详见 `references/form/guide-form-layout-incremental.md` |
+| `e10-cli form add-detail-table <objId> <appId> <明细表名> [首字段名] [--no-place] [--init]` | 给**已存在的主表**加明细子表（saveSubForm 建子表 + 加首字段使其可见），**默认增量放进现有布局**（复制临时布局取平台生成的容器组件，原布局不重建）。`--data-key <物理表名>`、`--first-field-type <类型>`（默认 Text）、`--first-field-data-key <编码>`（首字段字段编码，缺省取首字段名拼音首字母，与 `add-field` 一致）。⚠ **空子表平台会过滤掉、布局里看不见**，首字段名强烈建议传；`--no-place` 只建表不排布局；`--init` 改用整表重建（会换样式模板并重排已有位置）。后续往明细里加字段用 `form add-field --sub-form-id <subFormId>`：建表时一次性带明细用 `form create` 的 fields.json `DetailTable`+`formFields`。详见 `references/form/layout/incremental.md` |
 | `e10-cli form rename-detail-table <objId> <appId> <subFormId\|明细表名> <新名称> [--describe <描述>]` | **修改明细表名称**（同步子表标题、字段引用名与布局 DetailTable 标题）。按 subFormId 或当前名称定位；保存后回读子表标题与布局标题。当前名称与旧值同名、明细表重名、读不到物理表记录 id 或回读不一致会报错；`--describe` 可选同时改描述。流程表单暂不提供 |
 | `e10-cli form delete-detail-table <objId> <appId> <subFormId\|明细表名>` | **删除明细表**（连带表里的字段）。平台不允许删**仍被布局引用**的明细表（报「当前【X】明细表已被布局引用，不允许删除」）—— 明细表只要在表单上就必然被引用，所以多数情况要加 `--force`：先把这张表的组件（本体 + 每列的「字段本体 + 标题标签」）从布局摘掉、清掉 workbook 里的残留，再删。删除是**软删**，记录仍在但不再算数 |
 | `e10-cli form physical-table list <objId> <appId>` | 列出表单的**全部物理表**（含主表），带 `formTableId` / 显示名 / 库表名 / 表类型(`MAIN`\|`SUBSIDIARY`) / 字段数。走 `getFormAGroupList`（设计器「字段管理」那排 chip 的数据源）。**只列物理表**，明细表要用 `form detail-table list` |
@@ -146,18 +148,29 @@
 | `e10-cli form message enable \| disable <appId> <triggerId> [--obj-id <objId>]` | 启用 / 停用消息提醒。停用后不再推，配置保留 |
 | `e10-cli form native <子命令>` | **原生表单引擎**（formdatareport/biaoge，非 Ebuilder；只有 formId、无 objId、无 appId）的命令组：`create <名称>` 建表、`read <formId>` 读字段、`add-field` / `add-detail-table` / `init` / `field-group`，以及 `list [--keyword]`（存活表单，名称模糊搜）、`trash`（回收站）、`delete <formId...>`（停用→检查→删除，进回收站，删后回读确认）。**注意与 EB 表单不通用**：URL 前缀 `/api/formdatareport/...`、body module `biaoge` 或 `formdatareport` 视接口而定 |
 | `e10-cli form layout read <objId> [--view-id <id>] [--raw] [--out <file>]` | 读表单布局结构；raw/out 获取完整原生快照，含 workbook。不传 view-id 读默认布局 |
+| `e10-cli form layout describe <id> [--module ebuilderform\|workflow\|biaoge] [--id-type obj\|form] [--view-id <id>] [--terminal PC\|MOBILE] [--field <名称或ID>] [--out <file>]` | 只读输出目标布局、字段标题和值组件、分组、明细及网格摘要；`--out` 保存完整结构化结果，保留 `layout read --raw` 作为原生快照入口。使用方法见 `form/layout/inspect-edit.md` |
+| `e10-cli form layout diff <id> --terminal PC\|MOBILE --config @layout-edit.json [--module ...] [--view-id <id>] [--out <file>]` | 只读预览表格式布局行高、列宽、已有单元格样式及字段标题／值组件位置的前后差异、关联组件和冲突；不会保存。配置见 `form/layout/inspect-edit.md` |
+| `e10-cli form layout edit <id> --terminal PC\|MOBILE --config @layout-edit.json --preview @layout-diff.json [--module ...] [--view-id <id>] [--out <file>]` | 核对预览报告、配置哈希和最新快照后，单次保存表格式布局网格样式或同网格字段位置调整，并独立回读；旧预览会阻断。见 `form/layout/inspect-edit.md` |
+| `e10-cli form layout document export <id> --out <file> [--module ...] [--view-id <id>]` | 只读导出可编辑的完整 `formLayout` 文档，保留目标、环境、字段与快照指纹。见 `form/layout/document.md` |
+| `e10-cli form layout document diff <id> --draft @file [--out <file>] [--module ...] [--view-id <id>]` | 只读列出完整布局 JSON 的前后差异及新增结构冲突，供 `document apply` 审阅。见 `form/layout/document.md` |
+| `e10-cli form layout document apply <id> --draft @file --preview @diff.json [--out <file>] [--module ...] [--view-id <id>]` | 核对草稿、预览和最新快照后单次保存完整 `formLayout`，独立回读全部布局与字段；失败不自动重试。见 `form/layout/document.md` |
 | `e10-cli form layout add-detail-table <objId> <appId> <subFormId\|明细表名>` | 把**已存在但还没进布局**的明细子表增量放进布局（不重建）。幂等：已在布局里时只提示不重复添加。明细表至少要有 1 个字段（空子表平台不返回） |
-| `e10-cli form code layout read/set <objId> --app-id <appId> --layout-id <id> --terminal PC\|MOBILE [--js <文件>] [--css <文件>]` | 读取或写入指定 EB 布局的 JS/CSS 源码；写入一项保留另一项。代码写法读 `references/code-block/guide-code-block.md`；**源码 ecode 必须用 `encodeURI`（设计器用 `decodeURI` 读取），不能用 `encodeURIComponent`，CLI 已内置写入/回读自检** |
+| `e10-cli form layout set-read-only/set-required <objId> <fieldId> [--view-id <布局ID>]` | 直接修改已有布局组件的只读或必填属性；分别使用 `--read-only/--no-read-only`、`--required/--no-required`。执行后读取目标布局核对，见 `form/layout/incremental.md`。 |
+| `e10-cli form layout move/remove-field <objId> <fieldId>` | 旧的直接保存命令：`move --row <行> --col <列>` 移动默认布局中的字段值组件；`remove-field` 从默认布局移除字段组件但保留字段定义。需要位置差异预览时使用 `layout diff/edit`，详见 `form/layout/incremental.md`。 |
+| `e10-cli form code layout read/set <objId> --app-id <appId> --layout-id <id> --terminal PC\|MOBILE [--js <文件>] [--css <文件>]` | 读取或写入指定 EB 布局的 JS/CSS 源码；写入一项保留另一项。代码写法读 `references/form/layout/code-block/code-block-guide.md`；**源码 ecode 必须用 `encodeURI`（设计器用 `decodeURI` 读取），不能用 `encodeURIComponent`，CLI 已内置写入/回读自检** |
+| `e10-cli form code layout preview/apply <objId> --layout-id <id> --terminal PC\|MOBILE [--js <文件>] [--css <文件>]` | 独立的布局代码块审阅式写入：`preview --out <文件>` 先编译并保存差异，`apply --preview @<文件>` 核对源文件与布局后单次保存并回读。适用于 EB 表格式和流式布局；原有 `read/set` 保持可用。 |
 | `e10-cli form code ecode list/read/add/edit/status <objId> --app-id <appId> ...` | 表单级 ecode 的独立配置，作用范围与布局源码不同；具体参数见命令 help 与代码块指南 |
 | `e10-cli form layout image-context <image> --out <file>` | 离线获取真实原图路径和 SHA256，供 Agent 实际查看后产出图片观察 |
 | `e10-cli form layout style-review --source @json [--spec @json] [--overrides @json] [--confirm] --out <file> [--report <file>]` | 主动展示字体/字号/颜色/对齐及表格线粗细/外框；gridBorderStyle 调整已声明表格内的线型、粗细和颜色，用户修改逐项映射，失败项保留图片值；只有用户已确认或明确修改才用 --confirm，新图片保存前必查确认状态 |
 | `e10-cli form layout extract <file> --out <file> [--observation @json]` | XLSX 确定性提取；图片绑定结构化观察；不创建业务字段 |
 | `e10-cli form layout inspect <id> --out <file>` | 只读导出完整字段和原生布局上下文；可指定 module、id-type、view-id、target-kind |
 | `e10-cli form layout compile <id> --source @json --spec @json --out <file> [--context @json]` | 编译已有字段的源布局，零业务写入；context 模式完全离线 |
+| `e10-cli form layout source-review <id> --artifact @json [--out <file>]` | 只读核对源产物与当前布局的完整文档差异、目标、快照及字段；确认可继续后仍用源布局 apply 保存 |
 | `e10-cli form layout apply <id> --artifact @json [--out <file>]` | 单次保存并独立回读；旧快照阻断，写结果未知先查询，不自动重建 |
 | `e10-cli form layout verify <id> --artifact @json [--out <file>]` | 独立验证布局、支持样式和字段保持；不发写请求；详见源样式指南 |
 | `e10-cli form layout style-audit <id> --artifact @json [--context @json] [--out <file>]` | 图片样式三层差异诊断；context 模式无登录；区分观察/投影/回读与像素验收 |
-| `e10-cli form layout init <objId> [--style-template <名\|id>] [--view-id <id>] [--read-only] [--required] [--disable-edit] [--single-row]` | 初始化/重建表单布局（initLayout）：按实际布局类型解析并应用模板，同时可覆盖字段 readOnly/required/disableEdit/singleRow（不传则保留已有设置）。跨布局类型的模板 ID 会被 CLI 拒绝；平台直接接收跨类型 ID 时可能静默忽略。建表后再调用此命令。模板分类及规则见 `form/form-template/style-templates.md`。 |
+| `e10-cli form layout init <objId> [--style-template <名\|id>] [--view-id <id>] [--read-only] [--required] [--disable-edit] [--single-row]` | 原有初始化命令，保持原行为与参数。会整套重建布局；需要审阅与回读时使用独立的 `init-reviewed`。 |
+| `e10-cli form layout init-reviewed <objId> [--style-template <名\|id>\|--easy-template <名\|id>] [--view-id <id>] [--config @<文件>] [--read-only\|--no-read-only] [--required\|--no-required] [--disable-edit\|--no-disable-edit] [--single-row\|--no-single-row] --preview-only --out <计划>`；随后用相同选项及 `--preview @<计划>` 执行 | 初始化/重建 eBuilder 表单布局。`--style-template` 用于高级表格式或流式模板，`--easy-template` 用于 PC 表格式简易模板。先只读预览影响范围，再核对未变化的布局、字段、配置及显式模板后重建；执行后回读布局身份、组件、字段属性和模板样式依据。`--config` 可按字段 ID 配置显示/编辑属性。会重新生成排版与样式，精细布局先导出底稿。见 `form/layout/initialization.md`。 |
 | `e10-cli form layout save-as-template <id> --view-id <布局ID> --name <模板名> [--module workflow] [--enabled]` | 将实际 PC 流式布局的样式另存为模板；eBuilder 传 objId，流程表单传 formId 并指定 workflow。默认禁用，不复制业务字段和布局组件。 |
 | `e10-cli form layout copy <objId> <appId> --from <源布局ID> [--name <新名>] [--describe <文本>]` | 复制一套已有布局（设计器里的「复制」）。**响应体不含新布局 ID**（平台只回一句「复制成功！」），命令靠**复制前后各回读一次视图列表**反查并把新 ID 报出来。`--name` 缺省沿用源布局名；布局类型自动跟随源（表格式复制出来仍是表格式）。**复制出来的不是默认布局**，要设为默认续跑 `form layout set-default` |
 | `e10-cli form layout set-default <objId> <appId> <布局ID> [--for all\|add\|view\|edit]` | 把某套布局设为默认（设计器右键「设为默认布局」）。⚠ `--for` 是**用途档位**、不是布局类型：`all` 全部布局 / `add` 新建布局 / `view` 显示布局 / `edit` 编辑布局（也收中文说法，缺省 `all`）。**一套布局同时只承担一个档位** —— 换档位会把旧档位摘掉；「新建/显示/编辑各用一套」是靠**三套不同布局各占一档**。设完回读 `defaultType` 确认；只有 `all` 才会让视图的 `default` 变 `true` |
@@ -283,6 +296,7 @@
 | `e10-cli wf-form layout init <formId> [--layout-id <布局ID>]` | 初始化/重建流程表单布局（initLayout，按 layoutType 选模板，默认 FLOW）。**`--layout-id` 指定要重建哪一套**（节点独立布局的 layoutId），不传则重建默认布局；字段属性用 `--read-only`/`--required`/`--single-row` 覆盖 |
 | `e10-cli wf-form layout add <formId> --name <布局名>` | 新增一套流程表单布局。`--layout-type FLOW|EXCEL`（默认 FLOW）、`--terminal-type PC|MOBILE`（默认 PC）、`--describe`、`--workflow-id`；返回 `layoutId`，多套布局并存且不覆盖原布局 |
 | `e10-cli wf-form code layout read/set <formId> --layout-id <id> --terminal PC\|MOBILE [--js <文件>] [--css <文件>]` | 读取或写入指定原生工作流程表单布局源码；代码写法读代码块指南。**源码 ecode 必须用 `encodeURI`，不能用 `encodeURIComponent`（设计器 `decodeURI` 读取）** |
+| `e10-cli wf-form code layout preview/apply <formId> --layout-id <id> --terminal PC\|MOBILE [--js <文件>] [--css <文件>]` | 流程表单布局代码块的独立预览与回读写入；预览用 `--out`，应用用 `--preview @<文件>`。 |
 | `e10-cli wf-form code ecode list/read/add/edit/status <formId> ...` | 原生工作流程表单级 ecode 的独立配置，非布局源码 |
 | `e10-cli wf-form layout delete <formId> <layoutId>` | 删除指定流程表单布局。`layoutId` 取自 `layout add` 返回值；可传 `--workflow-id`、`--terminal PC|MOBILE`（默认 PC）。该操作从布局列表移除目标布局 |
 | `e10-cli wf-form field-prop <formId>` | 设置运行时布局字段属性：`--required <字段...>`、`--no-required <字段...>`、`--readonly <字段...>`、`--editable <字段...>`、`--single-row <字段...>`。字段可传名称或 ID；内部 getConfig 读取并由 initLayout 保存，同时保留已有分组和独占一行设置 |

package/skill-docs/references/form/guide-browser-definition.md

@@ -1,6 +1,6 @@
 # 浏览数据定义
 
-浏览数据定义控制浏览弹窗的默认高级搜索、可选数据范围和显示 Tab。先查询表单中哪些浏览字段可配置，再查看指定字段由数据源提供的条件与选项，最后只配置已开放的项目。不同浏览来源可能仅开放其中一部分。
+浏览数据定义包含三部分：**高级搜索**设置浏览弹窗中的搜索条件及默认值；**数据范围**限定弹窗里哪些数据可选；**浏览 Tab**设置可见页签、默认页签和顺序。先查询表单中哪些浏览字段可配置，再查看指定字段由数据源提供的条件与选项，最后只配置已开放的项目。不同浏览来源可能仅开放其中一部分。
 
 ## 操作顺序
 
@@ -16,7 +16,7 @@ e10-cli form-engine browser-definition describe <formId> <fieldId> --module work
 
 `inspect` 对每个字段分别输出 `search/scope/tabs` 的 `platform`（平台是否开放）、`cli`（CLI 是否有该数据源适配）和 `configured`（已配置标记）。`describe` 返回字段原始元数据、支持项的当前配置及候选条件／范围／Tab。只在 `platform=true, cli=true` 时执行对应写入；`platform=true, cli=false` 表示数据源允许设置，但该浏览来源的保存结构尚未纳入 CLI。字段名重名时使用字段 ID。
 
-EB 表单可从表单引擎的表单设置进入。工作流程表单的表单引擎设置页没有独立的“浏览数据定义”；它跟随所属工作流程配置，入口是「流程引擎 → 工作流管理 → 工作流程 → 高级设置 → 浏览数据定义」。先确定工作流程及其关联的表单，再传该表单 ID 和 `--workflow-id <流程ID>`。流程接口使用 `module=ebuildercard`，浏览配置的 `businessId` 是流程 ID，`formId` 是流程关联的表单 ID；同一表单若用于不同流程，应按目标流程分别读取和设置。流程表单预览不会按此配置过滤，应在流程实际使用场景核对。其他表单引擎模块按各自入口和实际开放能力配置。
+EB 表单可从表单引擎的表单设置进入。工作流程表单的表单引擎设置页没有独立的“浏览数据定义”；它跟随所属工作流程配置，入口是「流程引擎 → 工作流管理 → 工作流程 → 高级设置 → 浏览数据定义」。先确定工作流程及其关联的表单，再传该表单 ID 和 `--workflow-id <流程ID>`。配置时以流程 ID 定位所属工作流程，以关联表单 ID 定位浏览字段；同一表单若用于不同流程，应按目标流程分别读取和设置。流程表单预览不会按此配置过滤，应在流程实际使用场景核对。其他表单引擎模块按各自入口和实际开放能力配置。
 
 ## 高级搜索
 
@@ -49,9 +49,9 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 
 | 来源 | `--config` 结构 | 说明 |
 |---|---|---|
-| 人员 `hrm/resource` | `{"rules":[...],"range":"any"}`；完整报文亦可用 `itemDatas[]` | `get` 返回当下布局码表、表单字段候选、矩阵选项和现存范围。`rules[]` 按当前布局校验并转换，与已有项按范围来源合并。 |
-| 部门 `hrm/department` | `{"rules":[...]}`；完整报文亦可用 `records[]` | 已核对指定部门／分部、创建人、当前操作者、表单部门字段。 |
-| 分部 `hrm/subcompany` | `{"rules":[...]}`；完整报文亦可用 `records[]` | 已核对指定分部、创建人、当前操作者、表单分部字段。 |
+| 人员 `hrm/resource` | `{"rules":[...],"range":"any"}`；完整配置亦可用 `itemDatas[]` | `get` 返回当下布局码表、表单字段候选、矩阵选项和现存范围。`rules[]` 按当前布局校验并转换，与已有项按范围来源合并。 |
+| 部门 `hrm/department` | `{"rules":[...]}`；完整配置亦可用 `records[]` | 已核对指定部门／分部、创建人、当前操作者、表单部门字段。 |
+| 分部 `hrm/subcompany` | `{"rules":[...]}`；完整配置亦可用 `records[]` | 已核对指定分部、创建人、当前操作者、表单分部字段。 |
 | 关联 EBuilder `ebuilder/form/ebuilder` | `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"..."}]}` | `scopeInfoRender` 为条件树 JSON 字符串；已有 `form ebuilder-scope` 提供按字段名编译的简便方式。 |
 | 自定义浏览框 `bcw/customBrowser_*` | `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"..."}]}` | `scope get` 返回该浏览框自己的 `conditionLayout`，从其中选择字段与操作符，按完整条件树写入；字段和操作符在保存前校验。 |
 | 行政区域 `bcw/city` | `{"records":[{"scopeType":"normal_country","scopeInfo":"国家ID","scopeInfoRender":"{...}","type":"normal"}]}` | 例：指定国家为中国；国家 ID 从实际候选列表取得。 |
@@ -89,11 +89,55 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 }
 ```
 
-上面展示的是 `scopeInfoRender` **解码后的条件树**，用于说明嵌套关系；实际 `scope.json` 须把整棵树序列化为 JSON 字符串，放入 `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"<序列化后的条件树>"}]}`。字段 `id/fieldName/fieldType/compType`、`conditions` 的操作符和值结构要按目标字段和 `scope get` 返回的同类条件填写；选项、表单字段、变量字段等值的报文形状与示例的手动文本值不同。更新已有规则时保留其记录 ID（CLI 在未给 ID 时也会按 `scopeType` 查找并沿用已有 ID）。保存后再次 `scope get`，核对树层级、每层 `relationship`、字段和值及记录 ID。工作流程场景还须传 `--workflow-id`，并在所属工作流程的实际使用场景核对筛选效果。
+上面展示的是 `scopeInfoRender` **解码后的条件树**，用于说明嵌套关系；实际 `scope.json` 须把整棵树序列化为 JSON 字符串，放入 `{"records":[{"scopeType":"scopeSql","scopeInfoRender":"<序列化后的条件树>"}]}`。字段 `id/fieldName/fieldType/compType`、`conditions` 的操作符和值结构要按目标字段和 `scope get` 返回的同类条件填写；选项、表单字段、变量字段等值的配置形状与示例的手动文本值不同。更新已有规则时保留其记录 ID（CLI 在未给 ID 时也会按 `scopeType` 查找并沿用已有 ID）。保存后再次 `scope get`，核对树层级、每层 `relationship`、字段和值及记录 ID。工作流程场景还须传 `--workflow-id`，并在所属工作流程的实际使用场景核对筛选效果。
+
+### 关联 EBuilder 的简便规则
+
+关联 EBuilder 字段的数据范围决定**目标表单的哪些记录可以在浏览弹窗中选择**。只需按目标表单主表字段给出一层 AND／OR 条件时，可使用 `form ebuilder-scope`；复杂嵌套条件使用上面的完整条件树。
+
+```bash
+e10-cli form ebuilder-scope get <源objId> <appId> <EBuilder字段fieldId>
+e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> --rules @scope-rules.json --logic and
+e10-cli form ebuilder-scope clear <源objId> <appId> <EBuilder字段fieldId>
+```
+
+`源objId` 是包含关联字段的表单对象 ID；`appId` 是应用 ID；`fieldId` 是该关联字段的 ID。规则中的 `field` 指**被关联的目标表单主表字段**，可用字段名或 ID；名称重名时使用 ID。`--logic and|or` 控制所有规则的关系，缺省为 `and`。`--fill-null` 可在需要关联字段为空时填充的场景下使用，缺省关闭。配置文件是规则数组，例如：
+
+```json
+[
+  { "field": "客户状态", "operator": "eq", "value": "启用" },
+  { "field": "客户名称", "operator": "like", "value": "上海" }
+]
+```
+
+| 规则项 | 可用写法 |
+| --- | --- |
+| `operator` | `eq` 等于、`neq` 不等于、`like` 包含、`isnull` 为空、`notnull` 不为空 |
+| `value` | 文本、数字和日期填写目标值；选项类字段填写选项名或唯一的选项值 ID，由 CLI 匹配目标字段的实际选项；`isnull`、`notnull` 不填写 |
+| `valueFrom` + `valueField` | 不填固定 `value`。`currentFormField` 为“变量字段”，引用当前表单的主表字段；`targetFormField` 为“本表字段”，引用被浏览目标表单的主表字段。`valueField` 可写字段名或 ID，重名用 ID。 |
+
+例如，浏览“关联项目”时，让目标表的“关联合同”等于当前表单的“关联合同”；或者让目标表的“关联客户”等于目标表自己的“项目简介”：
+
+```json
+[
+  {"field":"关联合同","operator":"eq","valueFrom":"currentFormField","valueField":"关联合同"},
+  {"field":"关联客户","operator":"eq","valueFrom":"targetFormField","valueField":"项目简介"}
+]
+```
+
+这两种字段引用的保存结构不同。CLI 会先查字段候选，再分别生成变量字段或本表字段的配置；已有范围规则保存前用 `get` 确认，`set --rules` 会以本次规则数组重建这棵简便条件树。当前仅验证了以关联浏览字段作为筛选条件，且简便写法只支持当前表单和目标表单的主表字段。复杂嵌套条件仍使用上节的完整条件树。
+
+例如，只允许选择状态为“启用”的客户：
+
+```bash
+e10-cli form ebuilder-scope set <源objId> <appId> <EBuilder字段fieldId> --rules '[{"field":"客户状态","operator":"eq","value":"启用"}]'
+```
+
+设置后用 `get` 回读规则，再在设计器和实际浏览弹窗核对可选数据；`clear` 清空这些规则。简便规则只读取目标表单主表字段，不用它筛选目标明细字段。旧 `form ebuilder-filter` 修改的是字段布局中的过滤参数，不保证被浏览数据定义识别；新增数据范围使用本节命令。
 
 ### 人员范围码表与简化规则
 
-下表是已抓到的范围来源；同一 `groupTypeId` 的 `includeType`、组织维度等下级选项仍应以 `scope get` 实时返回的 `groups[].options` 为准。表单字段候选取 `formFieldCandidates`，矩阵候选取 `matrixOptions`；指定对象先用 `scope candidates` 查询。
+下表是当前可用的范围来源；同一 `groupTypeId` 的 `includeType`、组织维度等下级选项仍应以 `scope get` 实时返回的 `groups[].options` 为准。表单字段候选取 `formFieldCandidates`，矩阵候选取 `matrixOptions`；指定对象先用 `scope candidates` 查询。
 
 | `rules[].kind` | 平台组码 | 主要参数 | 适用说明 |
 |---|---:|---|---|
@@ -102,8 +146,8 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 | `creator` | 114 | `includeType`、`virtualId` | 数据创建人及其组织关系 |
 | `operator` | 121 | `includeType`、`virtualId` | 当前操作者及其组织关系 |
 | `field` + `fieldType=resource` | 201 | `field`、`includeType` | 按表单人员字段值取范围 |
-| `field` + `fieldType=department` | 202 | `field`、`includeType` | 按表单部门字段值取范围；抓包有本部门 `1` |
-| `field` + `fieldType=subcompany` | 203 | `field`、`includeType` | 按表单分部字段值取范围；抓包有本分部 `4` |
+| `field` + `fieldType=department` | 202 | `field`、`includeType` | 按表单部门字段值取范围；本部门使用 `1` |
+| `field` + `fieldType=subcompany` | 203 | `field`、`includeType` | 按表单分部字段值取范围；本分部使用 `4` |
 | `matrix` | 401 | `sourceId/sourceIdType/targetId/matrixRules` 等 | 先选择矩阵并读取 `getMaTrixItems` 返回的来源、结果字段及映射项 |
 
 布局中还可出现指定部门 `102`、指定分部 `103`、指定角色 `104`、指定岗位 `105` 等组。它们的组织维度、包含上下级和安全级别选项因当前字段与数据源而异；先从 `get` 读取，未纳入简化规则的结构可使用完整 `itemDatas[]`，不能照搬流程操作者的全量码表。指定部门的已见关系码为 `1/2/3`（本部门／含下级／含上级），指定分部为 `4/5/6`（本分部／含下级／含上级）。
@@ -117,18 +161,18 @@ e10-cli form-engine browser-definition scope set <formId> <fieldId> --module <mo
 }
 ```
 
-矩阵规则示例结构为 `{"kind":"matrix","sourceId":"...","sourceIdCN":"...","sourceIdType":"2","targetId":"...","targetIdCN":"...","matrixRules":[{"sourceField":"矩阵来源字段ID","sourceType":"customBrowser","targetField":"表单字段ID"}]}`。来源和结果字段 ID 应从所选矩阵的候选接口读取，`matrixRules` 映射矩阵来源字段与当前表单字段；只提供矩阵 ID 无法完成此设置。
+矩阵规则示例结构为 `{"kind":"matrix","sourceId":"...","sourceIdCN":"...","sourceIdType":"2","targetId":"...","targetIdCN":"...","matrixRules":[{"sourceField":"矩阵来源字段ID","sourceType":"customBrowser","targetField":"表单字段ID"}]}`。来源和结果字段 ID 应通过 `scope matrix-options` 读取，`matrixRules` 映射矩阵来源字段与当前表单字段；只提供矩阵 ID 无法完成此设置。
 
 ### 部门、分部范围码表
 
-两者走 `browserDataScope`，浏览类型分别是 `hrm_department` 和 `hrm_subcompany`，不是人员范围的 `hrm_resource`。以下是已核对的 `rules[].type`：
+部门和分部使用各自的数据范围配置，不能套用人员范围规则。以下是当前支持的 `rules[].type`：
 
 | 来源字段 | 可用 `type` | 已核对的关系码／值 |
 |---|---|---|
 | 部门 | `targetDepartment`、`targetSubcompany`、`creator`、`operator`、`department` | 指定部门 `ownDepartment`；指定分部 `ownOrSubcompany`；创建人 `subcompanyAsCreator`；操作者 `subcompanyAsOperator`；表单部门 `ownDepartment` |
 | 分部 | `targetSubcompany`、`creator`、`operator`、`subCompany` | 指定分部 `ownOrSubcompany`；创建人 `subcompanyAsCreator`；操作者 `OPERATOR_SUP_SUBCOMPANY`；表单分部 `ownSubcompany` |
 
-`targetDepartment/targetSubcompany` 的 `target` 使用 `scope candidates` 返回的完整候选对象；`department/subCompany` 的 `field` 使用本表字段名或 ID。`creator/operator` 可给 `virtualId`（未给取已核对的行政组织 `1`）。其它上下级关系码要以相应字段的界面候选与保存报文核对后再补，不按中文含义猜码。
+`targetDepartment/targetSubcompany` 的 `target` 使用 `scope candidates` 返回的完整候选对象；`department/subCompany` 的 `field` 使用本表字段名或 ID。`creator/operator` 可给 `virtualId`（未给取已核对的行政组织 `1`）。其它上下级关系码须先读取相应字段的候选项，不按中文含义猜码。
 
 ```json
 {"rules":[{"type":"targetDepartment","target":{"id":"部门ID","name":"技术部","content":"技术部"},"mode":"ownDepartment"},{"type":"department","field":"报销部门","mode":"ownDepartment"}]}
@@ -145,4 +189,4 @@ e10-cli form-engine browser-definition tabs set <formId> <fieldId> --module <mod
 
 ## 支持边界
 
-命令入口与能力发现按表单引擎模块统一；底层仅适配已核对报文的浏览来源。当前已适配关联 EBuilder、人员、部门、分部、城市行政区域及自定义浏览框对应的已开放配置项。项目、关联流程等来源会在 `inspect` 中展示平台支持情况，但保存报文未经核对的子项标为 `cli=false`。工作流程路径需同时给关联表单 ID 与 `--workflow-id`；其写入效果须在流程实际使用场景验证。
+命令入口与能力发现按表单引擎模块统一；当前只支持已确认配置结构的浏览来源。当前已适配关联 EBuilder、人员、部门、分部、城市行政区域及自定义浏览框对应的已开放配置项。项目、关联流程等来源会在 `inspect` 中展示平台支持情况，但尚未支持写入的子项标为 `cli=false`。工作流程路径需同时给关联表单 ID 与 `--workflow-id`；其写入效果须在流程实际使用场景验证。