weaver-e10-builder 1.5.11 → 1.5.12

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

@@ -54,6 +54,8 @@
 
 > 样表有标题、分组、空白、字段同排或跨列时逐行保留，并与字段清单互相核对。缺少的合并范围标待确认。建新表时按蓝图准备 fields.json，按所选布局创建并初始化；公式、联动、校验等后续配置在功能批次单列。
 
+- 明确还原图片/XLSX源样式时，另记录源哈希、LayoutSpec、已有字段绑定、编译产物和独立回读结果。字段创建完成与布局还原通过分别勾选；未匹配、未支持项不能合并销号。相关指南为 `form/guide-form-layout-source.md`，精确保存晚于字段补写和归组重排。
+
 #### 1.2 视图与流程设计依据
 - 每张视图：所属表单、默认/新增、视图类型、终端、名称、数据范围及需要的显示列/交互要求。
 - 每个流程：表单来源、节点、操作者及签署方式、全部连线、默认出口、逐条条件、节点显示属性和动作流落点。普通流程和权责表流程分别按对应指南列出；权责表逐场景写说明、条件、经过节点及顺序，独立复用时写变量→主/明细字段映射。
@@ -154,6 +156,7 @@
 - 第一阶段：全部应建表单的字段、明细、布局和默认台账已核对；表单级与视图级需求逐项销号，后续流程依赖已标注。
 - 第二阶段：流程结构、关键条件、操作者及动作流已核对；第一阶段的流程依赖项已回填。
 - 第三阶段：报表、菜单和页面入口已核对；交付时列出应用→表单→视图、流程、矩阵、报表、页面的真实 ID 与未完成项。
+
 ```
 
 ## 使用边界

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

@@ -75,6 +75,9 @@
 | `e10-cli form relate <appId> <objId> <目标字段> --from <源字段>` | **HRM 值带出联动**：源字段为表内 Employee（人员）或 Department（部门）类型，换源自动填目标字段（换申请人→填邮箱/工号/部门；换所属部门→填部门编号/上级部门）。`--key` 从平台清单校验（默认 Employee=department、Department=name），`--title` 指定显示名（默认属性中文名）。详见 `form/guide-form-linkage.md` |
 | `e10-cli form delete-field <objId> <appId> <fieldId...>` | **删除字段**（可一次多个，批量）。**仍被布局引用的字段平台不允许删除**（报「当前字段已被布局引用，不允许删除」）；加 `--force` 时 CLI 先从布局移除再重试——会**连字段的标题组件一起摘**（一个字段在布局里是「字段本体 + 标题标签」两个组件），否则表单上会留下孤儿标签。字段**有数据**时同样删不掉 |
 | `e10-cli form delete <objId> <appId>` | 删除**整个表单**（不是字段；删字段用上面的 delete-field） |
+| `e10-cli form rename <objId> <appId> <新名称>` | 修改**表单名称**。⚠ 表单名称与**自定义标题**是分开的两套（标题用 `form title`），两者不一致属正常状态，不是漏改。平台该接口是整对象覆盖，命令内部**先读回完整对象、只换名称、再整体回写**，不会清掉其它配置；改完回读校验。改名称**不影响**标题 |
+| `e10-cli form title get <objId> <appId>` | 查看**表单自定义标题**：标题文本、表单页面名、是否隐藏页面头部 / 隐藏表单标题、页面名是否全含 |
+| `e10-cli form title set <objId> <appId> [--show-name <文本>] [--form-page-name <文本>] [--hide-header\|--no-hide-header] [--hide-title\|--no-hide-title] [--page-name-all-in 0\|1]` | 修改自定义标题（至少要给一项）。先读回现有标题、叠上改动再整份提交，改完逐项回读校验。⚠ **标题处于隐藏状态时，改了标题文本界面上也看不出变化**（`get` 会提示） |
 | `e10-cli form permission data add <objId> <appId> --org-type <类型> [--org-id <id>] --rights <view/edit/delete...> [--file-rights <view/download...>]` | **表单数据权限**，`1/view=查看`、`2/edit=编辑`、`3/delete=删除`，可任意组合；附件 `401/view=查看`、`402/download=下载`。固定写入 `obj_data_admin` 并按新增权限 ID 回读。授权对象支持 all/role/department/company/employee/group/post；all 的 orgId 自动为 0 |
 | `e10-cli form permission imp-exp <list\|add> <objId> <appId> ...` | **导入导出权限**（独立分类 `data_imp_exp`，⚠ 勿用 `data add` 加——共享权限只有 查看/编辑/删除 三种，导出/导入不在其中）。`list` 查看；`add --org-type <类型> [--org-id] --rights <export/import/delete-import...> [--update-import] [--export-details] [--export-attachment] [--export-field-range listShowField|all]`。`export=8`、`import=9`、`delete-import=93`（93 须与 import 同选，自动带更新导入）；添加后按权限 ID 回读 `impRightList` 校验。删除同 `permission remove --right-id` |
 | `e10-cli form permission archive <list\|add\|remove\|card> <objId> <appId> --workflow <workflowId>` | **流程归档权限**（归档后数据对谁可见/可改/可删，**按流程各一套**，与共享权限不同）。`add --target <general/creator/field/matrix>`：`general` 通用对象配 `--org-type`+`--org-id`；`creator` 创建人相关配 `--creator-related 0~7`；`field` 字段相关配 `--field <字段id或名>`（`--sub-form-id` 支持明细字段，未收录的字段类型需 `--org-type field_xxx` 显式指定）；`matrix` 矩阵相关配 `--matrix`（真矩阵）或 `--eb-form`（e-Builder 表单）+ `--matrix-value`，另可加**矩阵条件** `--matrix-condition '<json>'`（可重复 / `@文件` 给数组；右值三选一 `value` 固定值 / `field` 引本表单字段 / `fieldRef` 直给字段描述符）+ `--matrix-condition-relation and\|or`。权限码 `5/view` 归档查看、`6/edit` 归档编辑、`7/delete` 归档删除；归档附件另算 `501/view`、`502/download`、`503/edit`（**不是**共享权限的 401/402）。保存后按 ID 回读逐项核对；`card <workflowId> <appId> [--set 0\|1]` 读写归档卡片开关。详见 `form/guide-form-archive-permission.md` |
@@ -86,7 +89,7 @@
 | `e10-cli form list-click <objId> <appId> <listId> <fieldId> [--target <formObjId>] [--open-mode <模式>] [--win-size <尺寸>] [--clear] [--pc-only]` | 设置台账列**点击跳转**。`--open-mode` 支持当前页面/新窗口/弹出窗口/右侧滑出/右侧推出；`--win-size` 仅用于滑出/推出，具体数值按需求填写：百分比使用 `%`（0～100），像素使用 `px`，两种单位不可混用。缺省 `800px` |
 | `e10-cli form ebuilder-columns <objId> <appId> <fieldId> [字段名/ID...] [--clear]` | 设置 EBuilder 关联字段的**浏览显示列**（存在字段配置 `ffDisplayColumns:{id,name}[]`）。**缺省查看**：列出当前显示列 + 目标表单全部**业务字段候选**（系统字段已自动过滤，不设显示列时浏览走平台默认列会带系统字段）；**传目标表业务字段名/ID 设置**，系统字段会被拦截提示"系统字段不能设为显示列"；`--clear` 清空。关联浏览显示哪些字段（只留业务字段） |
 | `e10-cli form ebuilder-scope <get\|set\|clear> <objId> <appId> <fieldId>` | **浏览数据定义 → 数据范围设置**（关联浏览字段，限定被关联数据须满足条件才可选，如关联客户只选"客户状态=启用"的）。走 `browserDataScope` 接口（独立于字段布局）。`set --rules '[{"field":"客户状态","operator":"eq","value":"启用"}]'`（选项类 value 用选项名，CLI 自动解析 valueKey）；`--logic and/or` 多规则关系；`--fill-null` 关联字段为空时填充；`get` 读已设条件；`clear` 清空。**这是关联浏览筛选的正解**，旧 `ebuilder-filter` 走 layout/save 不被设计器识别 |
-| `e10-cli form validate list <objId> <appId>` | 查看表单**查重规则**（字段重复校验，多字段 AND）。`add <objId> <appId> <字段名...> [--help 提示] [--remind]` 新增（缺省禁止提交 NOSUBMISSION，`--remind` 仅提醒）。**`--help` 会建成多语言标签、存的是标签 id**（平台只收 id，传文本会被拒「提示内容格式不正确」；`list` 会解回文本显示，缓存原因刚建完约 10 秒内可能仍显示 id）；`delete <objId> <appId> <ruleId>` 删除。项目名称重名/工时日期重复不允许 |
+| `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> <明细表名> [首字段名] [--init]` | 给**已存在的主表**加明细子表（saveSubForm 建子表 + 加首字段使其可见）。`--data-key <物理表名>`、`--first-field-type <类型>`（默认 Text）。⚠ **空子表平台会过滤掉、布局里看不见**，首字段名强烈建议传；`--init` 建完把 DetailTable 组件放进布局。后续往明细里加字段用 `form add-field --sub-form-id <subFormId>`：建表时一次性带明细用 `form create` 的 fields.json `DetailTable`+`formFields` |
 | `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` |
@@ -117,7 +120,15 @@
 | `e10-cli form message delete <appId> <triggerId> [--obj-id <objId>]` | 删除消息提醒（不可逆） |
 | `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>]` | 读表单布局结构（comps 坐标/只读）。不传 `--view-id` 读默认布局，传则读指定视图 |
+| `e10-cli form layout read <objId> [--view-id <id>] [--raw] [--out <file>]` | 读表单布局结构；raw/out 获取完整原生快照，含 workbook。不传 view-id 读默认布局 |
+| `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 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，按表单实际布局类型实时查（传错套会直接报错并列出可用项；**平台对跨套 id 不报错、只会静默忽略，表现为"命令成功但样式没变"**）。缺省：流式=标准版、表格式=表格版。完整模板表见 `form/style-templates.md`。**建表时不能指定样式，只能建完再用本命令换** |
 | `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` |
@@ -161,8 +172,10 @@
 | `e10-cli form field-linkage list <appId> <objId>` | 字段联动（跨表带出赋值）：列出联动 |
 | `e10-cli form field-linkage read <appId> <objId> <id>` | 回读单条（inFields/outFields） |
 | `e10-cli form field-linkage fields <appId> <formId>` | 查源表可带出字段 |
+| `e10-cli form field-linkage events <appId> <objId> [--effect <维度>]` | 可用触发动作。默认 10 个；`workFlow`/`includeNode` 维度取流程那套 17 个 |
 | `e10-cli form field-linkage delete <appId> <objId> <ids...>` | 删除（批量） |
-| `e10-cli form field-linkage add <appId> <objId> --trigger <字段名> --target <字段名> --hops "<objId:字段名,...>"` | 新增。`--hops` 多跳链式（单跳用 `--source-form/--query-field`）。**Text 字段必须多跳取名称**。详见 `form/guide-field-linkage.md` |
+| `e10-cli form field-linkage add <appId> <objId> --trigger <字段名> --source-form <objId> --condition "<字段:算子:值>"... --assign "<源字段>=<目标字段>"...` | 快捷配置：任意条件（可多个）、多查询字段（`--query-fields`）、多赋值（目标写 `明细表名.字段名` 则写明细表）、`--basis` 明细行依据、`--detail-mode add/cover/update`、`--detail-add override/append`、`--fission on/off`、`--precondition "<字段:算子[:值]>"`（可多个）、`--event`/`--effect`/`--state`。旧单跳/多跳用 `--query-field`/`--target`/`--hops`。详见 `form/guide-field-linkage.md` |
+| `e10-cli form field-linkage update <appId> <objId> <id> [--name] [--state] [--event] [--trigger] [--effect] [--detail-mode] [--detail-add] [--fission] [--precondition] [--clear-precondition]` | 改名称/启停/触发动作/生效维度/明细开关/赋值前提。不给触发项就原样沿用；只改启停走专用接口 |
 | `e10-cli form formula-linkage list <appId> <objId>` | 函数联动（**本表**字段间公式赋值，`linkageType=excel`）：列出 |
 | `e10-cli form formula-linkage read <appId> <objId> <id>` | 回读单条（含公式表达式与参数） |
 | `e10-cli form formula-linkage events <appId> <objId> [--effect <维度>]` | 列出可用的触发事件。默认 10 个（字段组 5 + 表单组 5）；生效维度给 `workFlow`/`includeNode` 时取**流程**那套 = 17 个（多「提交/批准时、转发时、保存时、退回时、转办时、意见征询时、传阅时」7 个） |
@@ -230,7 +243,7 @@
 | `e10-cli wf-form formula-linkage add <formId> --workflow-id <id> --target <字段> --expression <函数体>` | 新增。**`--event <事件...>` 可给多个**（一条联动能挂多个触发时机），每个可自带触发字段：`--event EVENT_FORWARD --event changeField:数量,单价`。`--trigger <字段...>` 作用于没自带字段的字段级事件。`--effect form\|formLayout\|workFlow\|includeNode`（后两者需 `--workflow-id`，`includeNode` 另需 `--node`）、`--name`。表达式只给右侧，左侧自动拼。详见 `form/guide-formula-linkage.md` |
 | `e10-cli wf-form formula-linkage update <formId> --workflow-id <id> <linkageId> [--event...] [--trigger...] [--effect] [--node] [--name] [--state on\|off]` | 改触发时机/生效维度/名称/启停。**不给 `--event`/`--trigger` 就原样沿用现有的触发时机**。生效维度在「表单/布局 ↔ 工作流/节点」之间切换时**必须**同时给 `--event` |
 | `e10-cli wf-form linkage <formId> <联动名> --config '{"conditions":[{"field":"请假天数","operator":"EQUAL","value":"3"}],"actions":[{"prop":"hide","fields":["请假事由"]}]}'` | 显隐联动。`--config` 写字段名（自动解析 fieldId/dataKey）；**为空写 `NULL`（或 `EMPTY`，会归一）、不为空写 `NOT_NULL`**（写错平台报的是一句与条件无关的写库异常）。prop: hide/show/edit/readonly/required/hideLine；operator 另有 EQUAL/NOT_EQUAL/CONTAIN/GREATER/LESS 等。顶层可选 `"detailType":"AND\|OR"`（界面「所有/任一」）。**`"effect"` 指定生效维度**（这条路由有四种）：不写=当前表单、`"formLayout"`=**表单布局**、`"workFlow"`=**当前工作流**、`"includeNode"`+`"nodeId"`=**选择节点**（后两者需配 `--workflow-id`） |
-| `e10-cli wf-form validate add <formId> <字段名...> [--remind] [--help <提示>]` | 字段查重规则（多字段 AND，重复禁止提交/提醒）。`list`/`delete <ruleId>`。字段名自动 getConfig 解析 |
+| `e10-cli wf-form validate add <formId> <字段名...> [--remind] [--help <提示>]` | 字段查重规则（多字段 AND，重复禁止提交/提醒）。`list` / `update <ruleId> [--fields <名...>] [--help <文本>] [--remind\|--no-remind]` / `delete <ruleId>`。`update` 只改传入项，其余保持；**checkFields 是整组替换**，内部会把完整字段一起回传；本组的提示内容是**纯文本**（不走多语言标签）。字段名自动 getConfig 解析（含明细子字段） |
 | `e10-cli wf-form relate <formId> <目标字段> --from <Employee/Department源字段> [--key email/department/code/name] [--title <名>]` | 值带出：换表内 Employee/Department 字段自动填目标字段（HRM 属性带出）。`--key` 默认 Employee=department/Department=name。机制同 eb 表（ffRelateField，Employee 源 module=hrm） |
 | `e10-cli wf-form permission get <formId>` | 查看流程表单字段权限（display/readOnly/required/disableEdit）。**写字段权限用 `workflow node field-permission`**（节点级，流程表单表单级写平台多返 500） |
 | `e10-cli wf-form add-detail-table <formId> <明细表名> [首字段名] [--init]` | 给流程表单加明细子表（saveSubForm+首字段+可选 init 放入布局）。机制同 eb 表 `form add-detail-table` |

package/skill-docs/references/form/guide-create-form.md

@@ -192,6 +192,8 @@ EBuilder 关联字段在创建时指定目标表单 `objId` 和显示字段：
 
 ## 执行创建
 
+需要还原图片或 XLSX 源样式时，可在普通创建完成后使用[源样式还原命令链](guide-form-layout-source.md)，或同时传 `--layout-source @source.json --layout-spec @spec.json --layout-artifact-out artifact.json`。该入口先验证源文件，继续使用原字段创建链，最后在高级属性、公式和分组重排结束后保存精确布局。失败保留已有 objId/formId，重试只处理该对象，不重复建表。
+
 ```bash
 e10-cli form create <appId> "采购合同" --fields @fields.json --layout EXCEL
 ```

package/skill-docs/references/form/guide-field-linkage.md

@@ -2,9 +2,14 @@
 
 ## 概述
 
-字段联动（FormDataLinkage）：表单字段值改变时，自动查询**另一张表**（按数据ID=触发字段值过滤），把查到的字段值**带出赋值**到本表单字段。支持单跳（一次直接带出）和多跳链式（多次中转后带出）。
+字段联动（FormDataLinkage）：表单字段变化时，按条件查询**另一张表**，把查到的值**赋给本表字段**（主表或明细表）。
 
-背后是一个 ESB FieldLinkage 动作流（触发 + N 个 EnquiryForm 查询 + Output 赋值），CLI 自动完成建 ESB app + saveDesign + 绑定。
+背后是一条 ESB FieldLinkage 动作流（触发 + EnquiryForm 查询 + Output 赋值），CLI 自动完成建 ESB app + saveDesign + 绑定联动记录。
+
+支持两种配置方式：
+
+- **快捷配置**（`--condition` / `--assign`）：任意条件 + 多查询字段 + 多赋值，对应设计器里的「快捷配置」页
+- **旧单跳/多跳**（`--source-form` / `--query-field` / `--hops`）：固定按「数据ID = 触发字段值」过滤，多跳用于把 ID 换成名称
 
 ## 三种联动对比
 
@@ -14,22 +19,10 @@
 | 接口 | viewlinkage | ffRelateField module:hrm | saveFormDataLinkage + saveDesign（ESB） |
 | 作用 | 改字段显示属性（hide/show/required） | 换 Employee/Department→带 HRM 属性 | **查任意表→带出任意字段赋值** |
 | 源 | 表单字段值条件 | Employee/Department（HRM 源） | 任意字段→任意表查询 |
-| 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表多跳，ESB 动作流） |
-| 关系 | — | — | **字段联动是关联表带出的进阶版** |
+| 复杂度 | 简单 | 简单（单源单属性） | 复杂（跨表，ESB 动作流） |
 
 > 本文讲的是**跨表**带出。本表字段之间用公式互相计算赋值的是**函数联动**（eb 表 `form formula-linkage`、流程表单 `wf-form formula-linkage`），见 `guide-formula-linkage.md` —— 两者 `linkageType` 不同（`excel` vs `template`），`form field-linkage list/delete` 看不到也删不掉函数联动。
 
-## 何时用多跳
-
-**Text 字段赋值必须用名称（多跳），不能直接赋 ID。**
-
-| 场景 | 跳数 | 示例 |
-|------|------|------|
-| 带出字段是 EBuilder（存 ID）→ 目标也是 EBuilder | 单跳 | 关联合同→查合同信息表→带出关联客户（ID→EBuilder 字段） |
-| 带出字段存 ID → 目标是 Text（要名称） | **多跳** | 关联客户→查客户信息表→客户类型(ID)→查客户类型表→类型名称(Text)→填 Text 字段 |
-
-**判断原则**：目标字段是 EBuilder/Select（存 ID）→ 单跳即可；目标字段是 Text（要展示名称）→ 必须多跳到名称表取名称。
-
 ## CLI 命令
 
 ```bash
@@ -42,82 +35,174 @@ e10-cli form field-linkage read <appId> <objId> <linkageId>
 # 查源表可带出字段
 e10-cli form field-linkage fields <appId> <formId>
 
+# 可用触发动作
+e10-cli form field-linkage events <appId> <objId> [--effect formLayout|workFlow|includeNode]
+
 # 删除（批量）
 e10-cli form field-linkage delete <appId> <objId> <linkageId...>
 ```
 
-### 新增（add）
+## 快捷配置（add）
 
-**单跳**（一次直接带出）：
 ```bash
 e10-cli form field-linkage add <appId> <objId> \
-  --trigger <触发字段名> \
-  --source-form <目标表objId> \
-  --query-field <目标表带出字段名> \
-  --target <本表目标字段名>
+  --trigger <本表触发字段名> \
+  --source-form <查询目标表 objId> \
+  --condition "源表字段:算子:值" \
+  --query-fields "源表字段1,源表字段2" \
+  --assign "源表查询字段=本表目标字段"
 ```
 
-**多跳**（多次中转后带出）：
+### 查询条件（`--condition`）
+
+可重复，多个为「且」。写法 `源表字段:算子:值`，算子与动作流筛选共用同一套：
+
+| 类别 | 算子 |
+|---|---|
+| 比较 | 等于 / 不等于 / 大于 / 大于等于 / 小于 / 小于等于 |
+| 文本 | 包含 / 不包含 / 开头包含 / 开头不包含 / 结尾包含 / 结尾不包含 |
+| 集合 | 属于 / 不属于 / 被包含于 |
+| 无值 | 为空 / 不为空（可不写冒号和值） |
+| 区间 | 区间（写 `起始~结束`） |
+
+值写 `@本表字段名` 表示引用本表字段；否则按字面值。示例：
+
 ```bash
-e10-cli form field-linkage add <appId> <objId> \
-  --trigger <触发字段名> \
-  --target <本表目标字段名> \
-  --hops "<源表objId:带出字段名,源表objId:带出字段名,...>"
+--condition "测试字段C:eq:11111"
+--condition "测试字段C:等于:@测试字段A"
+--condition "日期字段A:区间:2026-10-20~2026-10-21"
+--condition "备注:不为空"
 ```
 
-`--hops` 格式：每跳 `objId:字段名`，逗号分隔。前一跳的带出值 = 下一跳的过滤值（数据ID=前一跳结果）。最后一跳的带出值赋给 `--target`。
+### 查询字段（`--query-fields`）
+
+逗号分隔的源表字段名。不给时会自动并入 `--assign` 的源字段和明细依据字段。
 
-## 配置示例
+### 赋值（`--assign`）
 
-### 示例1：单跳——关联合同→合同信息表→关联客户
+可重复，`源表查询字段=本表目标字段`：
 
+- 主表字段直接写字段名
+- 明细表字段写 `明细表名.字段名`
+
+```bash
+--assign "测试字段C=测试字段A"
+--assign "测试字段C=明细表1.明细字段1"
 ```
-关联合同(EBuilder→合同信息表) 值改变
-→ 查合同信息表 by 数据ID=关联合同
-→ 带出关联客户(EBuilder→客户信息表，存ID)
-→ 赋值到本表.关联客户(EBuilder字段，存ID)
+
+### 明细行依据（`--basis`）
+
+`明细表名=源表字段名`。决定写入明细表时按哪一列匹配/生成行。不给则取该明细表第一个赋值的源字段；当被赋值的源字段正好是依据值时，设计器里显示为「依据值本身」。
+
+```bash
+--basis "明细表1=测试字段C"
 ```
 
+### 明细配置（三个开关）
+
+| 参数 | 取值 | 对应设计器 |
+|---|---|---|
+| `--detail-mode` | `add`（默认）/ `cover` / `update` | 主表联动明细表时：添加明细 / 覆盖明细 / 更新明细 |
+| `--detail-add` | `override`（默认）/ `append` | 明细表添加行时：删除已联动出的明细再添加 / 累计添加明细 |
+| `--fission` | `on`（默认）/ `off` | 联动出的值继续触发联动 |
+
+### 触发动作（`--event`）
+
+可重复，写法同函数联动：事件名或 type，可带 `类型:字段,字段`。默认 `changeField`（值改变时），字段取 `--trigger`。
+
 ```bash
-e10-cli form field-linkage add <appId> <objId> \
-  --trigger 关联合同 --source-form <合同信息表objId> --query-field 关联客户 --target 关联客户
+--event changeField
+--event onLoadForm
+--event "changeField:测试字段A"
 ```
 
-### 示例2：多跳——关联客户→客户信息表→客户类型→客户类型表→类型名称→填Text
+表单级 / 流程级事件（载入时、创建数据时…）不需要触发字段。流程事件（提交/批准、转发、保存…）需要配合 `--effect workFlow|includeNode`。
+
+### 生效维度（`--effect`）
+
+`form`（默认，当前表单）/ `formLayout`（表单布局，可配 `--layout-id`）/ `workFlow`（当前工作流）/ `includeNode`（选择节点，配 `--workflow-id` 与 `--node`）。
+
+### 启用状态（`--state`）
+
+`on`（默认）/ `off`。
+
+### 赋值前提（`--precondition`）
 
+满足前提时才执行赋值。可重复，多个为「且」：
+
+```bash
+--precondition "rlytest:不为空"
+--precondition "测试字段C:包含:@rlytest"     # @ 先查查询结果字段
+--precondition "日期字段A:包含:@测试字段A"   # 查不到再按本表字段
 ```
-关联客户(EBuilder→客户信息表) 值改变
-→ Step1: 查客户信息表 by 数据ID=关联客户 → 带出客户类型(EBuilder→客户类型表，存ID)
-→ Step2: 查客户类型表 by 数据ID=客户类型(Step1结果) → 带出类型名称(Text)
-→ 赋值到本表.客户类型(Text字段，要名称不要ID)
+
+前提条件保存在 ESB 条件服务里，开关它等价于重新保存动作流设计。
+
+## 修改（update）
+
+```bash
+e10-cli form field-linkage update <appId> <objId> <linkageId> \
+  [--name <名称>] [--state on|off] \
+  [--event <事件...>] [--trigger <字段...>] [--effect <维度>] \
+  [--detail-mode add|cover|update] [--detail-add override|append] [--fission on|off] \
+  [--precondition <条件...>] [--clear-precondition]
 ```
 
+- 不给 `--event` / `--trigger` 时原样沿用现有触发动作
+- 只改启停时走专用接口，不重发整套联动报文
+- 赋值前提不属于联动记录，由 CLI 读回动作流设计后只改 Output 节点再保存
+
+## 旧单跳 / 多跳（兼容保留）
+
+**单跳**：按「数据ID = 触发字段值」过滤。
+
 ```bash
 e10-cli form field-linkage add <appId> <objId> \
-  --trigger 关联客户 --target 客户类型 \
-  --hops "<客户信息表objId>:客户类型,<客户类型表objId>:类型名称"
+  --trigger <触发字段名> \
+  --source-form <目标表objId> \
+  --query-field <目标表带出字段名> \
+  --target <本表目标字段名>
 ```
 
-### 示例3：链式联动（两条独立 linkage 串联）
+**多跳**：`--hops "objId:字段名,objId:字段名"`，前一跳的带出值作为下一跳的过滤值。
 
-关联合同→(linkage1)→关联客户→(linkage2)→客户类型→(linkage3)→类型名称
+**何时用多跳**：目标字段是 Text（要名称）而源表存的是 ID（EBuilder/Select）时，需要多跳一次到名称表取名称；目标字段本身存 ID 则单跳即可。
 
-每条 linkage 的 `--trigger` 是上一条的 `--target`。分开 `add` 多次即可。
+## 示例
 
-## 查源表字段
+**单跳（快捷配置）**：
 
 ```bash
-# 查某表单有哪些可带出字段
-e10-cli form field-linkage fields <appId> <formId>
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger 关联合同 \
+  --source-form <合同信息表objId> \
+  --condition "关联合同:等于:@关联合同" \
+  --query-fields "关联客户" \
+  --assign "关联客户=关联客户"
 ```
 
-或用 `e10-cli form read <objId> --app-id <appId>` 取字段 fieldId（配置 --hops 时需知道字段名）。
+**主表联动明细表（多值写入 + 赋值前提）**：
+
+```bash
+e10-cli form field-linkage add <appId> <objId> \
+  --trigger 客户编号 \
+  --source-form <订单表objId> \
+  --condition "客户编号:等于:@客户编号" \
+  --query-fields "订单号,金额" \
+  --assign "订单号=订单明细.订单号" \
+  --assign "金额=订单明细.金额" \
+  --basis "订单明细=订单号" \
+  --detail-mode add --detail-add override --fission on \
+  --precondition "订单号:不为空"
+```
 
 ## 注意事项
 
-1. **Text 字段必须多跳取名称**：目标字段是 Text → 带出值必须是名称（文本），不能是 ID。如果源表存的是 ID（EBuilder/Select），需多跳到名称表取名称。
-2. **orgId 必须正确**：CLI 自动从 getForm 取 orgId，传给 application/save 建 ESB app。没有 orgId 的 app 不完整，saveDesign 会 500。
-3. **多跳 EnquiryForm 需要 sources**：非首跳的查询动作必须有 `sources` 指向前一跳，否则服务器报"有两个起始执行组件"（CLI 已处理）。
-4. **FormData 引用格式**：触发字段 `FormData.<本表formId>.<触发字段id>`；查询结果 `FormData.<源表objId>[].field_<带出字段id>`。
-5. **--hops 的 objId 是表单 objId**（不是 formId）。CLI 内部自动解析 objId→formId。
-6. **联动名称**：不传 `--name` 时自动生成 `<本表名>.<触发字段>→<最后源表名>.<最后带出字段>`。
+1. **三种明细模式**：添加/覆盖/更新由 `--detail-mode` 决定；「删除再添加 / 累计添加」是另一个开关 `--detail-add`。
+2. **明细行依据**决定行匹配：写入明细表时，依据值相同的行按模式处理。
+3. **赋值前提引用字段**：`@字段名` 先按查询结果字段解析（`source` = 查询节点），找不到再按本表字段（`source` = 触发事件）。
+4. **算子与动作流筛选同源**：按字段类型族校验，不支持的算子会直接报错。
+5. **FormData 引用格式**：本表字段 `FormData.<本表formId>.<字段id>`；查询结果 `FormData.<源表objId>[].field_<字段id>`。
+6. **--source-form 的 objId 是表单 objId**（不是 formId），CLI 内部自动解析。
+7. **联动名称**：不传 `--name` 时自动生成 `<本表名>.<触发字段>→<源表名>.<条件字段>`。
+8. **SQL 联动类型尚未覆盖**：只支持「动作流联动」（`linkageType=template`）；设计器里的「SQL可视化配置 / SQL联动」两条支路尚未实现。

package/skill-docs/references/form/guide-form-layout-planning.md

@@ -66,3 +66,9 @@ e10-cli form layout read <objId>
 ```
 
 创建后需要调整局部位置或显示属性时，使用 `form layout` 下的移动、只读和必填设置命令；具体参数通过 `form layout --help` 查询。
+
+## 图片与 Excel 源样式还原
+
+明确要求保留原样表的合并、留白、尺寸、静态文字和样式时，使用[源样式还原指南](guide-form-layout-source.md)。字段解析、创建及业务配置仍由 CLI 完成；布局模块在全部字段补写和归组结束后，将源网格绑定到已存在的字段与组件，编译 pageLayouts，再单次保存并独立回读。
+
+Plan 中的文字蓝图不直接作为保存请求。必须产出版本化 LayoutSpec，分别绑定 TITLE、VALUE 和普通明细。图片由 Agent 实际观察形成源网格，Excel 使用确定性提取。未知或冲突位置会阻断，不生成手写原生组件 JSON，也不自动转为默认两字段一行。