weaver-e10-builder 1.5.10 → 1.5.12

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-archive-permission.md

@@ -29,6 +29,12 @@ e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
 e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
   --target matrix --eb-form <表单名或id> --matrix-value 创建者 --rights view
 
+# 矩阵相关 + 条件（真矩阵才有条件列）：所属门店 等于 本表单的「创建人部门」
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target matrix --matrix 门店经理矩阵 \
+  --matrix-condition '{"column":"所属门店","func":"等于","field":"创建人部门"}' \
+  --rights view
+
 # 删除（按 list 里的权限 ID）
 e10-cli form permission archive remove <objId> <appId> --right-id <id[,id...]>
 
@@ -83,7 +89,53 @@ e10-cli form permission archive card <workflowId> <appId> --set 1
   目前只有「创建者」可直接用名称指定；其余取值请用 `--matrix-value <id>:<名称>:<valueType>` 明写，
   或用 `--matrix-value-raw '<JSON 数组>'` 整体透传（数组元素形状以设计器实际请求为准）。
 
-矩阵下面的「条件」这一层暂未开放，固定为空。
+### 矩阵相关的「条件」
+
+矩阵相关比另外三类多一层**条件**：拿矩阵自己的**条件列**去比「固定值」或「本表单字段」，只有命中的行才生效。
+落库是行报文里的 `matrixConditionData`（一棵条件树的 JSON 串）。
+
+```bash
+# 一条：所属门店 等于 固定值
+--matrix-condition '{"column":"所属门店","func":"等于","value":"123测试的"}'
+
+# 一条：所属门店 等于 本表单字段（field 走字段表按 id/名解析）
+--matrix-condition '{"column":"所属门店","func":"eq","field":"创建人部门"}'
+
+# 两条 + 任一
+--matrix-condition '{"column":"所属门店","func":"等于","value":"上海门店"}' \
+--matrix-condition '{"column":"所属门店","func":"不属于","value":"临时门店"}' \
+--matrix-condition-relation or
+```
+
+| 参数 | 说明 |
+|---|---|
+| `--matrix-condition <json>` | 一条条件，**可重复**；也可 `@文件` 给一个数组。对象三件套：`column`（条件列的 id 或列名）+ `func` + 右值 |
+| `--matrix-condition-relation` | 条件之间的关系：`and`=所有（默认）/ `or`=任一 |
+| `--matrix-condition-comp-type` | 条件列的组件键。**列类型的组件键目前只实证了「部门」→`Department`**，其余类型（人员/分部/岗位/客户/项目/自定义浏览框）命令会报错要求显式给 |
+| `--matrix-condition-raw <json>` | 整棵树透传（不做校验），形状以设计器请求为准 |
+
+**右值三选一**：
+
+- `"value": "字面值"` —— 固定值。**6 个算子都能配**。
+- `"field": "字段名或 id"` —— 引用**本表单字段**，按字段表解析。
+- `"fieldRef": {"id":"…","compType":"…","text":"…"}` —— 直接给字段描述符。**「创建人部门」这类运行时变量必须用这个** ——
+  它出现在设计器的字段选择器里，但 `ds/fields` 与 `getFormFieldPage` 都查不到；描述符从设计器报文里抄。
+
+> ⚠ **引用本表字段（`field` / `fieldRef`）平台卡两条**，CLI 会当场拦下而不是发出去：
+> ① **算子只能是「等于」**；② **字段类型必须与条件列一致** —— 部门列只能引用部门类型的字段，
+> 文本字段在设计器里根本选不到。所以「所属门店（部门）等于 [创建人部门]」成立，
+> 「所属门店（部门）等于 [名称（文本）]」和「所属门店 不等于 [创建人部门]」都会报错。
+
+算子只有界面下拉那 6 个：**等于 / 不等于 / 属于 / 不属于 / 为空 / 不为空**（`eq` / `neq` / `aggregate` / `unaggregate` / `empty` / `nempty`）。
+其中**只有「等于」是对着真机报文核实的**，其余 5 个是按同一族条件树的码表推的 —— 内容平台会原样存下、回读也一模一样，
+**只会在设计器里露馅**（渲染成 `undefined`）。用它配完请在设计器里过一眼。
+
+两条限制：
+
+- **`--eb-form` 不能配条件** —— e-Builder 表单当矩阵用时没有条件列，给了会直接报错。
+- **右值不能引用明细表字段**（只支持主表字段）。
+
+台账那边的矩阵权限（`form list-permission --add-matrix`）**同一套参数与语义**。
 
 ## 权限码
 
@@ -115,7 +167,8 @@ e10-cli form permission archive card <workflowId> <appId> --set 1
 - 回读的 `orgTypeName` 会和该类别的预期名称对照（如 `field_employee` 对应「人员字段」）。对不上直接报错 ——
   那意味着授权对象写错了，不能静默放过。
 - 字段相关这类计算型授权，平台会回 `isShowRebuild=2`，此时按提示执行
-  `e10-cli form permission rebuild <objId> <appId> <权限ID>`。
+  `e10-cli form permission rebuild <objId> <appId> <权限ID>` —— 等价于在权限行上点【重构】。
+  这一步不做，权限列表是不完整的（界面上表现为该行还要重构）。
 
 ## 归档卡片
 

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

@@ -74,6 +74,19 @@ e10-cli form association update <objId> <appId> <associationId> --view <newViewI
 
 仅启用或停用页签时，`update --enabled true|false` 使用 `updateIsOpenById` 独立接口并通过列表回读状态，不整包保存关联配置。
 
+## 删除关联页签
+
+```bash
+e10-cli form association delete <objId> <appId> <associationId>
+e10-cli form association delete <objId> <appId> "全部合同"
+```
+
+第 3 个参数可以是关联 ID，也可以是页签名称；按名称删时**名称必须唯一** —— 同名多条会报错并列出各自的 ID，不会替你挑一条删。找不到时同样报错并列出该表单现有的页签。
+
+命令先按列表确认这条页签属于当前表单，删除后回读列表确认它确实消失，成功输出 `verified: true` 和剩余页签数 `remaining`。
+
+删除不可撤销，也没有回收站。删掉后该页签连同它的权限条件一起不再出现在表单上，但**它引用的目标视图本身不受影响**。只想临时下线这个页签时用 `update --enabled false`，不要删。
+
 ## 修改和清空关联数据筛选
 
 ```bash

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

@@ -73,6 +73,93 @@ e10-cli form button action-set <objId> <appId> <buttonId> --open-view <视图> -
 
 当前仅管理一个 `openpage` 动作，不用于复杂多动作编排。`--start-workflow` 暂只解析当前应用内流程；跨应用普通视图/布局使用 `--target-app`。
 
+## 按钮基础属性
+
+`form button set` 改按钮的展示配置，**已有的动作和权限原样保留**：
+
+```bash
+# 名称 / 提示内容 / 备注
+e10-cli form button set <objId> <appId> <buttonId> --name "提交" --tips "请确认数据无误" --desc "业务备注"
+
+# 图标（存的是 JSON 串，命令负责拼装）
+e10-cli form button set <objId> <appId> <buttonId> --icon Icon-N-Offer-management --icon-display line
+e10-cli form button set <objId> <appId> <buttonId> --icon Icon-N-Offer-management --icon-color "#ff0000" --icon-bg "#ffffff"
+e10-cli form button set <objId> <appId> <buttonId> --icon-none    # 清空图标
+e10-cli form button set <objId> <appId> <buttonId> --only-icon    # 只显示图标
+
+# 点击日志
+e10-cli form button set <objId> <appId> <buttonId> --no-log
+e10-cli form button set <objId> <appId> <buttonId> --log --log-message "提交了单据"
+```
+
+`--icon-display` 取 `line`（描边）或 `fill`（填充）；只改颜色/描边时按钮必须已有图标。
+
+### 数据过滤
+
+按钮的「数据过滤」决定**列表里哪些行**受该按钮影响，条件语法与 `form list-filter` **完全一致**：
+
+```bash
+e10-cli form button set <objId> <appId> <buttonId> --add '{"conditions":[{"fieldId":"<fieldId>","func":"contains","value":"abc"}]}'
+e10-cli form button set <objId> <appId> <buttonId> --replace @cond.json
+e10-cli form button set <objId> <appId> <buttonId> --remove <fieldId>
+e10-cli form button set <objId> <appId> <buttonId> --relation or
+e10-cli form button set <objId> <appId> <buttonId> --clear-filter
+```
+
+`--add` 叠加、`--replace` 整体覆盖、`--remove` 按字段摘、`--relation` 只调顶层关系，同名同义。启用数据过滤时开关 `conditionEnable` 自动置 1，`--clear-filter` 置回 0。另有 `--disable-condition` / `--clear-disable-condition` 管「禁用条件」。
+
+`form button add` 建按钮时也能一次带上：`--tips --desc --icon --only-icon --no-log --log-message --data-filter`。
+
+## 按钮权限
+
+「按钮权限」管**哪些人能看见并点击这个按钮**，与表单共享权限是两套：
+
+```bash
+e10-cli form button permission <objId> <appId> <buttonId>                 # 列出
+e10-cli form button permission <objId> <appId> <buttonId> --add-all
+e10-cli form button permission <objId> <appId> <buttonId> --add-company 某分部 --contain-extra
+e10-cli form button permission <objId> <appId> <buttonId> --add-department 某部门
+e10-cli form button permission <objId> <appId> <buttonId> --add-people 某人
+e10-cli form button permission <objId> <appId> <buttonId> --remove 1      # 序号（从 1 起）或权限 id
+e10-cli form button permission <objId> <appId> <buttonId> --clear
+```
+
+授权对象支持**全体 / 分部 / 部门 / 人员**四类，主体可写名称或 ID。名称要求精确同名，撞名会报错并列出候选 id；取不到显示名也会直接报错，不会写入一条空名字。`--contain-extra` 表示含下级。其余授权对象类型本轮不支持，遇到会当场报错而不是写错。
+
+未配置过权限的按钮，平台会保留一条「全体」。保存后按**集合**回读核对（平台会重排顺序，不比数组顺序）。
+
+## 按钮动作（可挂多个）
+
+一个按钮可以挂**多个**动作。`form button action` 负责增删查：
+
+```bash
+e10-cli form button action <objId> <appId> <buttonId>             # 列出（序号 / 类型 / 摘要）
+e10-cli form button action <objId> <appId> <buttonId> --remove 2  # 按序号或动作 id
+e10-cli form button action <objId> <appId> <buttonId> --clear     # 清空自定义动作
+```
+
+追加动作（同一次命令里按 打开页面 → 确认框 → JavaScript → 编辑字段值 → 触发逻辑流 的顺序追加，可一次给多种）：
+
+| 动作 | 用法 |
+|---|---|
+| 打开页面（URL） | `--add-url <url> [--page-type LINK\|CUSTOMPAGE] [--map "参数名:来源字段"]` |
+| 打开页面（视图 / 布局 / 流程） | `--add-view <视图>`、`--add-layout <表单> [--layout-type 新建\|编辑\|显示]`、`--add-start-workflow <流程>`，共用 `--map "目标字段:来源字段"` |
+| 确认框 | `--add-confirm --confirm-title <标题> --confirm-content <正文> [--confirm-true <文案>] [--confirm-false <文案>]` |
+| JavaScript | `--add-js --code <源码\|@文件>` |
+| 编辑字段值 | `--add-edit-field "字段:值"`（可多个；字段写 fieldId 或字段标题） |
+| 触发逻辑流 | `--add-logic <逻辑流名或ID> [--logic-ecode-id <id>]` |
+
+`--open-type` 管打开方式：`1` 弹窗 / `2` 当前页 / `3` 新窗口。
+
+### 使用说明与边界
+
+- **编辑字段值**本轮只支持「赋固定值」。同一次命令里多次 `--add-edit-field` 会并进同一条动作（按字段去重，同字段后写的覆盖先写的）；按钮上已有该动作时会并入它，不会多出一条。
+- **触发逻辑流**只做绑定，**不生成**逻辑流。按名称解析要求精确同名，撞名报错并列出候选。`ecodeId` 可用 `--logic-ecode-id` 指定；不给时沿用该按钮上已有的绑定值，都没有则留空。
+- **JavaScript** 源码建议用 `--code @文件` 传入，避免命令行转义把脚本弄坏。
+- `action-set` 是早期只支持单一打开页面动作的命令，**已标记废弃**，等价于 `action --clear --add-view …`；仍可用，但新需求请用 `form button action`。
+
+保存沿用「读回为底 → 只覆盖本次要改的部分 → 写 → 回读」：改动作时权限原样保留，改属性或权限时动作原样保留，互不冲掉。改完若提示回读不一致，远端可能已被改动，先重新查询再处理。
+
 ## 保存与验证
 
 命令先分页查找按钮，再读取动作、权限和可选视图。提交时保留按钮基础配置、完整动作和权限，及接口返回的日志/自定义提示设置，并按视图实际名称重建 `showPositionSpan`。

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，也不自动转为默认两字段一行。