weaver-e10-builder 1.5.16 → 1.6.4

package/skill-docs/references/common/guide-plan-template.md

@@ -1,6 +1,6 @@
 # 搭建计划模板（按依赖与功能批次执行）
 
-使用本模板生成项目 `plan.md` 时，先读[规划能力地图](map.md)识别资源、配置和依赖；需要明确具体规则或能力边界时读对应专题指南，再填写实际涉及的条目。执行某项前仍须读取该项指南。
+使用本模板生成项目 `plan.md` 时，先读[规划能力地图](map.md)识别资源、配置和依赖；需要明确具体规则或能力边界时读对应专题指南，再填写实际涉及的条目。**先完成 0.1 方案澄清与可行性预检，并与用户集中确认一次。** 执行某项前仍须读取该项指南。
 
 规划阶段全部保持 `[ ]`。第一阶段先完成全部表单的字段、明细和布局，再以**功能项为外层、所有适用表单/视图为内层**组织配置：例如先完成所有表单的关联浏览数据范围，再处理所有表单的公式；视图也按显示列、搜索、排序等功能逐批覆盖。每进入一个功能项先读对应指南，确认方法、参数和边界；同一连续批次已读过的无需重复读取。每个对象及独立规则分别列项、核对、回填和销号；暂不能完成的保留 `[ ]` 并注明原因、已完成部分及所需条件，继续处理其他项目，不因步骤繁琐而省略。整个功能批次的覆盖对象处理完后进入下一批次，真实依赖优先于批次顺序。每段完成后停下让用户确认，确认后进入下一段。仅单步修改或查询不套用三段流程。
 
@@ -20,6 +20,31 @@
 - 待业务确认：<歧义及其影响；无则“无”>
 - 待环境核查：<资源或环境行为；无则“无”>
 
+### 0.1 方案澄清与可行性预检（执行前先看）
+
+> 先完成本节并与用户**集中确认一次**；确认前不写任何数据。执行中出现新的实质业务选择才再次询问，不为平台默认值制造确认。
+
+- 需求理解：<一句话说明本次范围；明确不做什么>
+- 关键假设：<只在必要时列；无则“无”>
+- 验收判据：<每条关键需求一个可观察结果；详细用例可另附>
+
+#### 待确认项
+
+| # | 级别 | 问题 | 选项 | 建议 | 影响 | 决策 |
+|---|---|---|---|---|---|---|
+| 1 | P0/P1/P2/P3 | <需要用户决定的事项> | <A / B / 其他> | <推荐及理由> | <会改变哪些字段、权限或路由> | 待确认 / 已确认：<内容> |
+
+> 级别：P0=阻断（未解决不执行）/ P1=高 / P2=中 / P3=低。
+
+#### 可行性 / 边界
+
+| 需求 | 结论 | 依据与证据等级 | 影响与处理 |
+|---|---|---|---|
+| <需求项> | 可做 / 部分可做 / 做不到 / 待环境核查 | 实测 / 回读字段 / 命令表 / 未证实 + <具体依据> | <保留未完成、替代方式或需用户决定> |
+
+> 证据等级：**实测**=有平台回执或回读；**回读字段**=返回体确有该字段但语义未实测；**命令表**=只能证明当前 CLI 没暴露，**不能**证明平台不支持；**未证实**=有结论无证据，不得对外宣称。
+> P0 或阻断项未解决前不进入执行；已确认做不到或部分做不到的需求保持 `[ ]`，不用替代配置冒充完成。
+
 ### 1. 资源清单与依赖
 
 | 资源 | 决策与归属 | 来源及用途 | 前置依赖 | 实际 ID/结果 |
@@ -54,7 +79,7 @@
 
 > 样表有标题、分组、空白、字段同排或跨列时逐行保留，并与字段清单互相核对。缺少的合并范围标待确认。建新表时按蓝图准备 fields.json，按所选布局创建并初始化；公式、联动、校验等后续配置在功能批次单列。
 
-- 明确还原图片/XLSX源样式时，另记录源哈希、LayoutSpec、已有字段绑定、编译产物和独立回读结果。字段创建完成与布局还原通过分别勾选；未匹配、未支持项不能合并销号。相关指南为 `form/guide-form-layout-source.md`，精确保存晚于字段补写和归组重排。
+- 明确还原图片/XLSX源样式时，另记录源哈希、LayoutSpec、已有字段绑定、编译产物和独立回读结果。字段创建完成与布局还原通过分别勾选；未匹配、未支持项不能合并销号。相关指南为 `form/layout/source-restoration.md`，精确保存晚于字段补写和归组重排。
 
 #### 1.2 视图与流程设计依据
 - 每张视图：所属表单、默认/新增、视图类型、终端、名称、数据范围及需要的显示列/交互要求。
@@ -92,7 +117,7 @@
 - [ ] 编号规则 | 表单/字段：<名称> | 组成与位数：<内容> | 核验：生成值
 - [ ] 表单权限 | 表单/主体：<名称> | 新建/查看/编辑/删除范围：<内容> | 核验：授权结果
 - [ ] 表单页按钮 | 表单/页面/位置：<名称> | 目标与字段映射：<内容> | 核验：点击结果
-- [ ] 表单代码块 | 表单/布局/终端/代码层级：<名称> | 触发时机、字段/明细 Key、预期效果：<内容> | 方法参考：`code-block/guide-code-block.md` | 核验：读回与运行场景；无受支持写入命令时保持未完成并说明影响
+- [ ] 表单代码块 | 表单/布局/终端/代码层级：<名称> | 触发时机、字段/明细 Key、预期效果：<内容> | 方法参考：`form/layout/code-block/code-block-guide.md` | 核验：读回与运行场景；无受支持写入命令时保持未完成并说明影响
 
 > 每个功能批次先核对覆盖表单清单，再逐表配置；同一表单有多条独立规则时继续拆行。建表时已配置并核验的分组、必填、只读、默认值等写在 2.1 的表单项结果中，不重复执行。
 
@@ -151,6 +176,7 @@
 |---|---|---|---|
 | <章节及要求> | 待业务确认/待环境核查/需其他方式补充/已确认无法实现 | <内容> | <内容> |
 
+> 0.1 是执行前的集中确认；本节保留执行过程中新增的待确认/缺失/无法实现项，新增项同样保持 `[ ]`。
 > 当前 CLI 暂不支持的配置项保持 `[ ]`，在此说明能力缺口及影响；不得用临时脚本、内部接口或浏览器操作代做，也不得以替代配置冒充完成。其他状态继续保留相应待办与依赖。
 
 ### 6. 阶段验收与交付资源

package/skill-docs/references/common/map.md

@@ -5,7 +5,7 @@
 ## 使用方法与状态
 
 1. 逐段阅读正文、表格和图片，将每条业务要求映射到资源与配置项，记录原文来源、所属应用/表单/视图/流程、前置依赖及可观察结果。已有资源先只读盘点，再决定复用、修改或新建。
-2. 需求含完整布局样表时，按[布局规划](../form/guide-form-layout-planning.md)保留标题、分组、同排、空白与字段顺序，并同时写入字段清单和布局蓝图。每张表单创建前确认 FLOW 或 EXCEL。
+2. 需求含完整布局样表时，按[布局规划](../form/layout/planning.md)保留标题、分组、同排、空白与字段顺序，并同时写入字段清单和布局蓝图。每张表单创建前确认 FLOW 或 EXCEL。
 3. 规划状态区分：**待业务确认**（语义或取值有歧义）、**待环境核查**（资源、权限或环境行为未证实）、**需其他方式补充**（现有 CLI 只能完成一部分）、**已确认无法实现**（核实无可行路径）。只有最后一种写入 plan 的“无法实现的项”，原需求项保持未完成。
 4. 按资源依赖组织 plan；关键配置写明读回点和最小业务验收点。接口保存、配置读回与页面实际生效是不同层次，按风险选择必要的检查。
 
@@ -15,6 +15,7 @@
 - **Ebuilder 应用** — 独立概念，包含表单、流程等资源（与 Ecode 项目不同）。
 - **默认台账与菜单入口是两件事** — 表单创建后会生成默认台账/列表视图，但 `form create` 默认不加应用菜单；需要入口时用 `--menu`，或建表后 `menu add-table`。默认台账已存在不等于菜单入口已存在。
 - 只有图表仪表盘、跨表单聚合视图、特殊交互流程、对外公开页面等场景才需要自定义页面。
+- 用户明确要求 Ecode、还原 HTML 原型或说明不要设计器时，按定制页面规划，直接走 Ecode；不要建议改用设计器。
 - 所有系统交互命令均通过 `e10-cli` 执行（已全局 link）。auth 文件自动查找，也可 `--auth <path>` 指定。
 - 当前登录用户的 userId 是固定变量 `TEAMS.currentUser.id`，前端代码里可以直接使用。
 
@@ -28,7 +29,7 @@
 | EB 表单 | 持久化业务记录和默认台账 | 写应用、字段、类型、布局及关联对象 | 验收 objId/formId、字段及默认台账 | [创建表单](../form/guide-create-form.md) |
 | 明细表 | 承载一对多业务行 | 写所属主表、明细字段和层级 | 二级明细另写父子行标识；验收结构及挂载 | [二级明细](../form/guide-form-sub-detail.md) |
 | 虚拟表 | 展示已有来源的组合数据 | 写数据来源、主键、来源字段和展示类型映射 | 先验证稳定主键和字段兼容；验收数据展示 | [虚拟表](../form/guide-virtual-form.md) |
-| 表单布局 | 控制新建/显示页面的字段排布 | 写 FLOW/EXCEL、字段顺序、分组和布局样表 | 建表前确定类型；验收实际字段与位置 | [布局规划](../form/guide-form-layout-planning.md) |
+| 表单布局 | 控制新建/显示页面的字段排布 | 写 FLOW/EXCEL、字段顺序、分组和布局样表 | 建表前确定类型；验收实际字段与位置 | [布局规划](../form/layout/planning.md) |
 | 表单视图与台账 | 按业务场景展示、检索记录 | 写默认视图复用/改名及额外视图类型 | PC/MOBILE 分别核对；视图不等于菜单入口 | [视图](../form/guide-form-view.md) |
 | EB 流程 | 应用内审批，默认流程路径 | 先有 EB 表单；写节点、出口及操作者 | 验收完整拓扑和关键条件 | [流程](../workflow/guide-workflow.md) |
 | 原生工作流程 | 流程中心或明确要求原生表单的审批 | 写自建/绑定表单、固定/自由模式和 formId | 与 EB 资源 ID 分开；验收流程与绑定表单 | [流程](../workflow/guide-workflow.md) |
@@ -40,7 +41,7 @@
 | 报表 | 统计、分组和报表布局 | 写单元格、查询、共享和交付效果 | 保存与实际展示分别核对 | [报表创建](../report/guide-report-build.md) |
 | 菜单 | 提供台账、流程或页面入口 | 目标资源先存在；写层级、名称与可见主体 | 验收点击目标与菜单权限 | [菜单](../menu/system-menus.md) |
 | 配置式页面 | 用设计器组件搭建页面 | 写数据源、组件、布局和 PC/MOBILE 要求 | 验收两端布局与数据绑定 | [设计器](../ebuilder-designer/guide-designer.md) |
-| 定制页面 | 实现标准配置之外的交互 | 写目标页面、作用范围、发布与入口 | 验收实际加载和业务交互 | [页面编码](../coding/guide-page-code.md) |
+| 定制页面 | 实现标准配置之外的交互 | 写目标页面、作用范围、发布与入口；HTML 原型还原写清样式复用方式 | 验收实际加载和业务交互 | [页面编码](../coding/guide-page-code.md)、[HTML 原型还原](../coding/guide-html-to-react.md) |
 | ESB 系统接口 | 从接口文档创建对外接口定义 | 写系统池、接口清单和文档来源 | 区分接口定义与动作流 HTTP 调用；验收创建结果 | [接口导入](../esb-interface/guide-import.md) |
 | 组织数据 | 维护部门、人员等基础数据 | 写机构归属、人员来源和导入范围 | 批量导入先预检；验收数据和归属 | [组织](../hrm/guide-org-employee.md) |
 
@@ -55,9 +56,9 @@
 | 字段类型 | 选择文本、金额、日期、组织、关联等录入组件 | 表单；逐字段写主/明细位置、类型与来源 | 按对象类型选原生字段；验收读回类型 | [字段码表](../form/ref-form-fields.md) |
 | 选项与默认值 | 限定可选值或预置新记录内容 | 字段；写选项、默认值及触发时机 | 选项模板与字段内选项分别记录；验收新建页面 | [字段码表](../form/ref-form-fields.md) |
 | 字段多语言 | 同一字段显示中英文名称 | 字段；写中文、英文及目标 fieldId | 建字段后配置；验收两种语言读回 | [创建表单](../form/guide-create-form.md) |
-| 字段显示属性 | 控制必填、只读、隐藏及独占一行 | 布局；逐字段写目标状态 | 字段定义与布局呈现分别核对 | [布局规划](../form/guide-form-layout-planning.md) |
-| 布局样表 | 从完整表格提取空间排布 | 写 FLOW/EXCEL、标题、行列、同排、空白和合并 | 字段清单与布局蓝图同时保留；验收实际位置 | [布局规划](../form/guide-form-layout-planning.md) |
-| 字段分组 | 将业务字段归入折叠分段 | 写分组名称、顺序及成员字段 | 需求明确时配置；验收字段归属 | [布局规划](../form/guide-form-layout-planning.md) |
+| 字段显示属性 | 控制必填、只读、隐藏及独占一行 | 布局；逐字段写目标状态 | 字段定义与布局呈现分别核对 | [布局规划](../form/layout/planning.md) |
+| 布局样表 | 从完整表格提取空间排布 | 写 FLOW/EXCEL、标题、行列、同排、空白和合并 | 字段清单与布局蓝图同时保留；验收实际位置 | [布局规划](../form/layout/planning.md) |
+| 字段分组 | 将业务字段归入折叠分段 | 写分组名称、顺序及成员字段 | 需求明确时配置；验收字段归属 | [布局规划](../form/layout/planning.md) |
 | 关联字段 | 选择客户、合同、流程等原生业务对象 | 写字段子类、目标对象、单/多选 | 关联对象与通用浏览来源分别选型；验收选择范围 | [字段码表](../form/ref-form-fields.md) |
 | 浏览数据定义 | 限定浏览可选数据、默认搜索及弹窗 Tab | 先查可配置字段，再查各字段开放的配置项与候选值 | 按浏览来源适配；验收实际可选数据、搜索与 Tab | [浏览数据定义](../form/guide-browser-definition.md) |
 | 二级明细 | 父级每行挂载子级明细记录 | 主/子明细表；写父子行标识与层级 | 子表归属需按行核对 | [二级明细](../form/guide-form-sub-detail.md) |
@@ -130,7 +131,7 @@
 | 点击按钮打开关联任务或发起流程 | 视图按钮或表单按钮，逐项写目标、当前行过滤与预填映射 |
 | 复杂自动写入其他表 | 动作流，写清触发、字段映射及目标记录定位；单纯本表计算选公式/联动 |
 | 标准配置无法表达的页面交互 | 明确目标范围后规划配置式页面或定制页面，并单列发布和交互验收 |
-| 当前表单布局中的字段、明细或交互需用 JS 实现 | 规划布局源码或表单级 ecode：写目标表单、布局/终端、触发事件、字段 Key、效果和运行检查；按[代码块指南](../code-block/guide-code-block.md)选 CLI 写入入口和对应 JSSDK 方法 |
+| 当前表单布局中的字段、明细或交互需用 JS 实现 | 规划布局源码或表单级 ecode：写目标表单、布局/终端、触发事件、字段 Key、效果和运行检查；按[代码块指南](../form/layout/code-block/code-block-guide.md)选 CLI 写入入口和对应 JSSDK 方法 |
 
 ## 四、常见依赖与计划顺序
 
@@ -160,4 +161,8 @@
 | 已确认无法实现 | 原需求项保持 `[ ]`，在 plan 第 8 节记录原因、影响及待用户决定的处理 |
 | 验收标准不足 | 给关键配置写读回字段与一个典型页面/业务结果，避免只凭保存成功销号 |
 
-规划结果应能回答：要建或复用哪些资源、每条需求落在哪个配置项、依赖顺序是什么、哪些信息须确认、哪些需环境核查、哪些只能部分实现，以及如何判断关键结果生效。最终清单与逐项销号使用[计划模板](guide-plan-template.md)。
+规划结果应能回答：要建或复用哪些资源、每条需求落在哪个配置项、依赖顺序是什么、哪些信息须确认、哪些需环境核查、哪些只能部分实现，以及如何判断关键结果生效。
+
+> 预检结论写入 `plan.md` 的 **0.1 方案澄清与可行性预检**，与用户集中确认一次后再执行；做不到/部分做到项保持 `[ ]`。证据等级与判定方式见[能力边界](capability-boundaries.md)。
+
+最终清单与逐项销号使用[计划模板](guide-plan-template.md)。

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

@@ -18,7 +18,7 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli project create <name> [desc]` | 新建 Ecode 项目（名称自动追加时间戳） |
-| `e10-cli project import <projectId> <zip> --main-url <url>` | 导入 zip 包，`--main-url` **必填** |
+| `e10-cli project import <projectId> <zip> --main-url <url> [--replace]` | 导入 zip 包，`--main-url` **必填**；`--replace` 导入前清理同名旧应用目录（含 `ecode1`/`ecode2` 后缀），避免并存 |
 | `e10-cli project tree <parentId>` | 查看目录结构 |
 | `e10-cli project read <fileId>` | 读取代码文件内容 |
 | `e10-cli project update <fileId> <content>` | 更新代码文件（content 以 `@` 开头则为文件路径） |
@@ -28,7 +28,8 @@
 | `e10-cli project delete-folder <folderId>` | 删除文件夹（= 删除应用） |
 
 - 导入成功后会在 Ecode 项目下生成应用文件夹
-- 二次导入之前先删掉旧应用文件夹（通过 `e10-cli project tree` 找到 folderId）
+- 二次导入用 `--replace`；不带时会新建一个同名/带数字后缀的目录
+- `--replace` 先删同名旧目录再导入；如果导入失败，旧目录已删除，需要重新导入
 
 ---
 
@@ -39,6 +40,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 +53,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`。
 
 | 命令 | 说明 |
 |------|------|
@@ -68,8 +71,8 @@
 | `e10-cli app unpublish <appId>` | 取消发布（收回前台入口）。⚠ **不可逆、无回收站**；重新发布是新入口。回读确认入口确实没了才报成功 |
 | `e10-cli app lang get <appId>` | 查看应用名各语言译文 |
 | `e10-cli app lang set <appId> [--zh] [--en]` | 设置应用名多语言。**简体中文那档就是应用名本身**；只给 `--en` 不会清空中文（内部先读回再整份写回）。改应用名（`app edit --name`）不动多语言配置 |
-| `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段+Select/RadioBox/CheckBox 选项、**并标注每个字段属于哪张物理表**（`· 物理表: 表1`，JSON 里是 `formTable` 键；多物理表见 `form physical-table list`）；**输出里的字段名（文本那栏 / JSON 的 `fieldName`）就是字段标题** —— 与设计器「字段管理」里看到的是同一个值，它为空就说明标题没写进去；`--out fields.json` 写 UTF-8 JSON（推荐，机器可读）。旧版 `[dir]` 参数写 memo.md，已过时 |
-| `e10-cli form read <objId> --app-id <appId> --out fields.json` | 读取字段含选项（Select/RadioBox/CheckBox 自动带 options）。**含明细表字段**，配动作流/联动拿明细 fieldId 用这个 |
+| `e10-cli form read <objId> [--app-id <appId>] [--out <file>]` | 读取表单字段。`--app-id` 含明细表字段、Select/RadioBox/CheckBox 选项、`dataKey`（写入 request key）、`multiSelect`、日期 `format`、`optionIds`（选项名→ID）及物理表归属；`--out fields.json` 写 UTF-8 JSON。**字段名就是字段标题**；标题为空说明没写进去 |
+| `e10-cli form read <objId> --app-id <appId> --out fields.json` | 生成页面 `fields.js` 和选项映射的推荐入口：选项、dataKey、多选、日期格式一次导出 |
 | `e10-cli form list <appId>` | 列出应用下的所有表单 |
 | `e10-cli form create <appId> <name> <dir> --fields @<json文件>` | 创建表单。`--fields` **必填**。支持 DetailTable(嵌套formFields)、EBuilder(sformId+dataTitle，**明细 `formFields` 内的 EBuilder 同样绑定**)、relateFrom(联动)。**开关 `Switch` 自动配置固定选项 开启=1 / 关闭=0**（主表/明细/后续加字段同）。fields.json 字段可带 `"required":true`/`"readOnly":true` 直标（写进布局 comps）。**字段名与平台系统字段重名（标题/创建者/创建时间/数据ID/最后更新人/数据状态）→ 不新建物理字段、复用系统字段**，并把该字段在**布局置为可见**（platform 系统字段默认隐藏；可写 `"singleRow":true` 独占一行、`"hidden":true` 保持隐藏）。`--json` 返回 `skippedSys`。**默认不加菜单**，要入口传 `--menu`（台账菜单 VIEWPORT）；漏加 `e10-cli menu add-table <appId> <objId>` 补。**`--table-name <名>` 自定义数据库表名**（平台前缀如 `uf_` 由 CLI 自动补，传 `cs_khxx` 与 `uf_cs_khxx` 等价；字母开头、只含字母数字下划线；自定义部分受平台长度上限约束——`uf_` + 总长 30 时最多 27 位，越界直接报错不建半张表；建成后回读校验实际表名；仅物理表应用适用） |
 | `e10-cli form virtual source-groups` / `sources <groupId>` | 查询 EB 表单和系统业务数据源分组、数据源列表 |
@@ -114,7 +117,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,25 +149,37 @@
 | `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` |
 | `e10-cli form layout delete <objId> <appId> <布局ID>` | 删除一套布局（设计器的「删除」）。⚠ **不可逆**。删完**回读确认列表里确实没了**才算成功；该布局原先占的用途档位会一并打印。删掉正占着 `all` 的那套会怎样**未验证**，慎用 |
 | `e10-cli form group <objId> <appId> --groups '{"基本信息":["字段名/fieldId",...]}'` | 给**已建好的 eb 表**加字段分组（折叠容器）。建组 saveFieldGroup → 分配 updateFormFieldGroup → initLayout generateCollapse 渲染。`--groups` 可 `@文件`；`--required` 同时设分组内字段必填；同名分组复用不重复建（去重）。建表时一次性带分组用 `form create` 的 fields.json `group` 属性 |
 | `e10-cli form data add <objId> <appId> <json>` | 写入表单数据（`@` 开头为 JSON 文件路径）。JSON key 可用 fieldId 或字段名；Select/RadioBox 值填选项名（自动解析 valueKey）或 valueKey、CheckBox/SelectMultiple 用数组、TextArea 直接值、Employee/Department 用 ID。详见 `form/guide-form-data.md` |
-| `e10-cli form data list <objId> [--page <n>] [--size <n>]` | 查询表单数据（**只含主表**）。`--page` 页码（缺省1）、`--size` 每页条数（缺省1000；不传 pageInfo 平台默认卡 10） |
+| `e10-cli form data upload --file <路径...> [--create-doc on\|off] [--module ebuilder]` | 上传附件文件，返回 `fileId` / `docId`。表单附件默认 `createDoc=true`，同时生成文档；`--create-doc off` 只留文件、文档中心没有文档。输出 `fileIds` 逗号串，可直接填 `form data add/update` 的附件字段 |
+| `e10-cli form data list <objId> [--page <n>] [--size <n>]` | 查询表单数据（**只含主表**）。`--page` 页码（缺省1）、`--size` 每页条数（缺省1000；不传 pageInfo 平台默认卡 10）。平台返回 `datajson.status=false` 时命令报错并打印原始 message，不再显示“共 0 条” |
 | `e10-cli form data detail <objId> <appId> <dataId> [--no-detail]` | 读一条数据详情，**默认连明细一起读**（`--no-detail` 只要主表）。要明细用这条，`list` 不返回明细。详见 `form/guide-form-data.md` |
 | `e10-cli form data update <objId> <appId> <dataId> <json> [--detail-mode cover\|append]` | 按数据 ID 修改（`@` 开头为文件路径）。只需写要改的字段；带明细表名即处理明细，缺省 `cover` **整表覆盖**，`append` 只追加 |
 | `e10-cli form data delete <objId> <dataId>` | 删除一条表单数据 |
@@ -212,6 +227,11 @@
 | `e10-cli form formula-linkage add <appId> <objId> --target <字段> --expression <函数体>` | 新增函数联动。**`--event <事件...>` 可给多个**（一条联动能挂多个触发时机），每个可自带触发字段：`--event changeField:数量,单价 onclick:按钮`；没自带字段的字段级事件回退 `--trigger <字段...>`。默认 `changeField`。`--effect form\|formLayout\|workFlow\|includeNode`（后两者需 `--workflow-id`，`includeNode` 另需 `--node`）、`--name`。表达式**只给右侧**，左侧 `{主表.目标}=` 自动拼。**目标只能是业务字段**，模块字段可作来源/触发。详见 `form/guide-formula-linkage.md` |
 | `e10-cli form formula-linkage update <appId> <objId> <id> [--event...] [--trigger...] [--effect] [--workflow-id] [--node] [--name] [--state on\|off]` | 改触发时机/生效维度/名称/启停。**不给 `--event`/`--trigger` 就原样沿用现有的触发时机**（不会按第一条重建）。生效维度在「表单/布局 ↔ 工作流/节点」之间切换时**必须**同时给 `--event` |
 | `e10-cli form formula-linkage delete <appId> <objId> <ids...>` | 删除（批量）。`form field-linkage delete` 删不掉这类，会报错指路 |
+| `e10-cli form attachment-setting get <appId> <objId> [--field <字段>]` | 读取附件上传设置：不传 `--field` 看通用配置，传了看字段级覆盖。通用配置分上传目录、新建文档存储位置、新建方式、上传格式、大小限制；字段级空项表示继承通用 |
+| `e10-cli form attachment-setting set <appId> <objId> [--upload-dir] [--doc-dir] [--doc-types] [--formats] [--max-size] [--enable] [--display-tip]` | 修改通用配置。`--upload-dir` 附件/图片上传目录，`--doc-dir` 新建文档存储位置，`--doc-types` 新建方式（逗号分隔），`--formats` 上传格式（扩展名逗号串或 `@doc/@image/@video/@audio/@archive` 预设），写 `none` 清空。读—合并—写—回读校验 |
+| `e10-cli form attachment-setting set <appId> <objId> --field <字段> --upload-mode fixed\|option ...` | 修改字段级覆盖：`fixed` 配 `--upload-dir`，`option` 配 `--option-field`；`--doc-dir`/`--doc-types`/`--formats` 同样可用于字段级。字段级未写的项保持继承通用。详见 `form/guide-form-attachment-setting.md` |
+| `e10-cli form attachment-setting folders [--search <关键字>]` | 列出可用文档目录（系统知识库 + 公司/私有知识库）；`--upload-dir` / `--doc-dir` 可写目录 ID，也可写唯一名称或路径 |
+| `e10-cli form attachment-setting doc-types [--folder <目录ID>]` | 列出“新建方式设置”可选的文档类型（html / WORD / markdown / UPLOAD） |
 | `e10-cli form formula set <objId> <appId> --target <fieldId> --expression "<公式>"` | 给 eb 表字段**绑定**计算公式。`{主表.字段}` / `{明细表名.字段}`（平台存储格式）与设计器的 `[字段]` 两种写法都收，保存前归一化成花括号再下发。`--name`、`--return-type`（不传按目标字段类型推断）。**`--formula-id <id>` 原地更新已有公式**（平台认这个字段：不新建、返回 id 不变、字段绑定不受影响），不传才是新建；更新时不传 `--name` 会沿用原公式名，不会被改成「公式_&lt;时间戳&gt;」。另：`formula get <id>` / `list <objId> <appId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错**不报错**只是算不对，见 `references/form/guide-form-formula-functions.md` |
 
 > **创建表单流程**：
@@ -283,6 +303,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 保存，同时保留已有分组和独占一行设置 |
@@ -595,7 +616,7 @@ e10-cli report py preagg --report-id <id> [--app-id <id>]
 
 | 命令 | 说明 |
 |------|------|
-| `e10-cli check <项目目录>` | 代码质量检查，逐条自检，全部确认通过后再 build |
+| `e10-cli check <项目目录>` | 代码质量检查：递归扫描整个项目（排除 `node_modules/.target`），核对 `build.json` 是否登记全部运行时 JS，并检查 let/const、CSS import、options 短 ID、String(React 节点) 等；通过后再 build |
 
 ---
 

package/skill-docs/references/components/display-FilePreview.md

@@ -36,11 +36,12 @@ export default class FilePreviewDemo extends React.Component {
 
 附件字段（FileComponent）的 `fileid` 可通过以下方式获取：
 
-**1. 从表单数据读取** — `getSimpleData` 对 FileComponent 字段返回 `fieldOptionId`（即 fileid）：
+**1. 从表单数据读取** — `formClient` 的行里，FileComponent 的 `items[字段ID]` 已经给出文件 ID 与名称；`values[字段ID]` 是逗号分隔的文件 ID 串：
 ```js
-var fileId = item[F.attachment];
-// 多文件时为逗号分隔，取第一个
-var firstFileId = (fileId || '').split(',')[0];
+var firstFileId = (row.values[F.attachment] || '').split(',')[0];
+var firstName = row.items[F.attachment] && row.items[F.attachment][0]
+  ? row.items[F.attachment][0].name
+  : '';
 ```
 
 **2. 上传时** — 从 `uploadedFiles` 状态中获取：

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`；其写入效果须在流程实际使用场景验证。