weaver-e10-builder 1.0.12-beta → 1.1.1

package/skill-docs/actionflows/references/components/ebuilder/ActionEbAdd.md

@@ -1,39 +1,61 @@
-# 新建表单数据（`ActionEbAdd`）
-
-## 何时使用
-
-向指定 e-builder 表单新增一条或一批数据；已有数据要修改时改用 `ActionEbUpdate`。
-
-## 先查询
-
-查询目标应用、表单、全量字段及创建人。明细赋值还须查询明细字段。
-
-## 不可猜测
-
-`targetForm`、人员和字段 ID 必须来自当前租户。动态来源只能使用本次触发器的真实 `paramKey`。
-
-## 最小计划
-
-`targetForm`、`person`，以及至少一项 `mapping`、`constants`、`formula` 或 `setting`。
-
-操作人选择：需求明确指定某人时才传该人的真实 Browser 对象并显示为固定值；需求未指定时传 `{"type":"role"}`，生成当前人 `{userid}` 动态值。不得为了补必填项从人员列表任意挑一个人。
-
-`opType:"batchInsert"` 时，`basisValue` 与 `mapping` 都是必填：前者指定要逐行遍历的上游明细，后者指定每行写入哪些目标字段。两者任一缺失，CLI 会在创建动作流前停止，绝不保存空壳批量节点。
-
-若流程触发器上下文中存在 `requestId`，而目标表恰有唯一一个未赋值的流程关联 Browser 字段（如“来源流程”或“关联流程”），CLI 会把它自动映射为当前流程实例 ID，并在结果的 `autoMappings` 中列出。显式映射、固定值、公式和旧 `setting` 始终优先，不会被覆盖；字段不唯一或类型不是流程关联字段时不猜测。
-
-## 动态来源选择与查询结果引用
-
-- AI 应按需求和已生成上游节点的真实上下文选择来源：流程触发字段、前序动作输出、当次循环、系统变量、固定值或查询结果均可；**不得默认把所有映射绑定到流程触发，也不得默认插入查询节点**。
-- 仅当业务需要从另一张表反查、且结果可确定为单条时，才使用 `EnquiryForm` 查询 + 主表字段 `query_result` 引用（手工创建成功样本：`actionflows/references/examples/enquiry-form-batch-insert-scene2.json`）。
-  - EnquiryForm 在前，ActionEbAdd 的 sources 指向 EnquiryForm 节点；主表字段 assign `type=3`，`value="FormData.{查询表id}[{positionId}].id"`，`config.comType="EnquiryForm"`、`comId=EnquiryForm 节点 id`、`paramKey="{查询表id}[].id"`，childs 带固定值取下标 `[{type:"1", value:"0", position}]`。
-  - 细节见 `EnquiryForm.md`「批量新增主表字段引用查询结果」。
-- AI 选择查询结果时，plan 显式写 `kind:"query_result"` 和查询节点 `ref`；未选择时使用普通 `context`、`fixed`、`system_variable` 或函数树，不产生查询结果公式。
-
-## 函数公式赋值（type=6）
-
-- **plan 写法**：顶层 `formula: {目标字段id: <函数树>}`；函数调用为 `{kind:'function', name:'DAYS', args:[...]}`，args 可为 `{kind:'context', paramKey, label, fieldType}` / `{kind:'fixed', value}` / 嵌套 `{kind:'function'}`。`+`、`−`、`×`、`÷` 本身也是函数名；旧 `op: 'add'|'sub'|'mul'|'div'` + fields 列表仅保留兼容。
-- **保存结构**：assign `type=6`，`value="{fnId}#{child.id}#..."`；`childs` 以子公式对象的 `id` 串联。内层函数同样 type=6 嵌套，叶子上下文 type=3 / 固定值 type=1。
-- **excelFunc 必须是对象**：四则运算函数目录无 excelFunc，CLI 传 `null` 由 FormulaBean 构造器生成对象兜底；函数目录带 excelFunc 的（如 DAYS/TODAY）原样透传对象。禁止写字符串（如 `'mul'`）。
-- **函数来源**：除 `custom`（自定义 JS）和 `code`（编码函数）外，标准函数名称、类别与参数约束均内置在 Skill/CLI。plan 只写函数名；仅当计划实际使用函数时，CLI 才调用当前租户接口校验该函数可用并替换函数 ID。接口不参与未使用函数的生成，也不决定标准函数是否受支持；当前租户缺少所用函数时明确停止。
-- 任务工时示例：`DAYS(预计完成日期, TODAY()) × 8`：`{kind:'function',name:'×',args:[{kind:'function',name:'DAYS',args:[{kind:'context',paramKey:'<日期字段>',label:'预计完成日期',fieldType:'date'},{kind:'function',name:'TODAY',args:[]}]},{kind:'fixed',value:8}]}`；首次用于新租户时仍应保存并回读确认。
+# 新建表单数据（`ActionEbAdd`）
+
+## 何时使用
+
+向指定 e-builder 表单新增一条或一批数据；已有数据要修改时改用 `ActionEbUpdate`。
+
+## 选择项跨表映射
+
+来源、目标选择字段的选项 ID 经当前租户字段元数据确认一致时，直接 `mapping` 动态赋值；批量新增会生成“依据值下级”（`switchType:"sub"`），这是任务明细字段的默认做法。需求指定固定选项时，不做动态映射；在 `constants` 中传该字段的真实 `valueKey`（可同时带 `label`），例如 `"<任务类型字段id>":{"kind":"fixed","value":"<研发的valueKey>","label":"研发"}`。CLI 会保留目标字段 `Select` 类型，使设计器以下拉项“研发”回显。只有两边选项 ID 不同、且需求明确要求按语义转换时，才在 `formula`（批量明细为 `detail[].formula`）中用 `SWITCH` 显式映射：
+
+```json
+{
+  "<目标选择字段id>": {
+    "kind": "function",
+    "name": "SWITCH",
+    "args": [
+      {"kind":"context","paramKey":"<来源选择字段paramKey>","label":"来源类型"},
+      {"kind":"fixed","value":"<来源选项id1>"}, {"kind":"fixed","value":"<目标选项id1>"},
+      {"kind":"fixed","value":"<来源选项id2>"}, {"kind":"fixed","value":"<目标选项id2>"},
+      {"kind":"fixed","value":"<默认目标选项id>"}
+    ]
+  }
+}
+```
+
+批量新增时，普通 `mapping` 的 `明细表[].字段` 仍编译为 type=10 的“依据值下级”引用。函数参数则是另一套协议：它会明确引用 `明细表[0].字段`，不会把整张明细数组传入函数。
+
+## 先查询
+
+查询目标应用、表单、全量字段及创建人。明细赋值还须查询明细字段。
+
+## 不可猜测
+
+`targetForm`、人员和字段 ID 必须来自当前租户。动态来源只能使用本次触发器的真实 `paramKey`。
+
+## 最小计划
+
+`targetForm`、`person`，以及至少一项 `mapping`、`constants`、`formula` 或 `setting`。
+
+操作人选择：需求明确指定某人时才传该人的真实 Browser 对象并显示为固定值；需求未指定时传 `{"type":"role"}`，生成当前人 `{userid}` 动态值。不得为了补必填项从人员列表任意挑一个人。
+
+`opType:"batchInsert"` 时，`basisValue` 与 `mapping` 都是必填：前者指定要逐行遍历的上游明细，后者指定每行写入哪些目标字段。两者任一缺失，CLI 会在创建动作流前停止，绝不保存空壳批量节点。
+
+若流程触发器上下文中存在 `requestId`，而目标表恰有唯一一个未赋值的流程关联 Browser 字段（如“来源流程”或“关联流程”），CLI 会把它自动映射为当前流程实例 ID，并在结果的 `autoMappings` 中列出。显式映射、固定值、公式和旧 `setting` 始终优先，不会被覆盖；字段不唯一或类型不是流程关联字段时不猜测。
+
+## 动态来源选择与查询结果引用
+
+- AI 应按需求和已生成上游节点的真实上下文选择来源：流程触发字段、前序动作输出、当次循环、系统变量、固定值或查询结果均可；**不得默认把所有映射绑定到流程触发，也不得默认插入查询节点**。
+- 仅当业务需要从另一张表反查、且结果可确定为单条时，才使用 `EnquiryForm` 查询 + 主表字段 `query_result` 引用（手工创建成功样本：`actionflows/references/examples/enquiry-form-batch-insert-scene2.json`）。
+  - EnquiryForm 在前，ActionEbAdd 的 sources 指向 EnquiryForm 节点；主表字段 assign `type=3`，`value="FormData.{查询表id}[{positionId}].id"`，`config.comType="EnquiryForm"`、`comId=EnquiryForm 节点 id`、`paramKey="{查询表id}[].id"`，childs 带固定值取下标 `[{type:"1", value:"0", position}]`。
+  - 细节见 `EnquiryForm.md`「批量新增主表字段引用查询结果」。
+- AI 选择查询结果时，plan 显式写 `kind:"query_result"`、`source:"<查询节点ref>"`、`formId`、`fieldId`、`index:0`；未选择时使用普通 `context`、`fixed`、`system_variable` 或函数树，不产生查询结果公式。`kind:"enquiry"` 与 `sourceId` 不是合法格式，CLI 必须拒绝，不能生成空固定值。
+
+## 函数公式赋值（type=6）
+
+- **plan 写法**：顶层 `formula: {目标字段id: <函数树>}`；函数调用为 `{kind:'function', name:'DATEDIFF', args:[...]}`，args 可为 `{kind:'context', paramKey, label, fieldType}` / `{kind:'fixed', value}` / 嵌套 `{kind:'function'}`。四则运算也写为函数树，禁止 `op + fields` 的旧格式。
+- **保存结构**：assign `type=6`，`value="{fnId}#{child.position}#..."`；`childs` 按参数槽位 `position` 串联，且 `detail[i].position` 必须与第 i 个 child 的 `position` 完全相同。`position` 与子公式 `id` 都是数字但不能混用：缺任一处会让设计器只显示根运算符（如 `(*)`），不显示参数。函数内部 `formulaType/config.paramType` 使用函数目录的 `resultType`（如 `double`），目标字段 `NumberComponent` 只写在外层 setting。内层函数同样 type=6 嵌套，叶子上下文 type=3 / 固定值 type=1。
+- **函数类别与 excelFunc**：`functionType` 必须原样使用函数目录的 `category`（如四则运算为 `operation`、日期函数为 `date`），不能用结果类型 `double` 代替。仅当函数目录实际返回 `excelFunc` 对象时才透传；没有就省略，尤其不能给 `×/÷/+/-` 伪造通用 `excelFunc`，否则编辑器会丢失运算符。禁止写字符串（如 `'mul'`）。
+- **函数来源与参数契约**：除 `custom`（自定义 JS）和 `code`（编码函数）外，标准函数名称、类别与**每个函数自身的完整参数契约**均内置在 Skill/CLI。参数不得泛化为 `param1/param2`：必须保留真实 `paramName`、`paramType`、`isRequire`、说明和枚举选项；例如 `DATEDIFF` 固定为 `startdate/enddate/datepart`。plan 只写函数名及实参；仅当计划实际使用函数时，CLI 才调用当前租户接口校验该函数可用并替换不可迁移的函数 ID，同时保留该租户的完整参数定义。接口不参与未使用函数的生成，也不决定标准函数是否受支持；当前租户缺少所用函数时明确停止。
+- 枚举函数参数不能只写内部值；固定值同时给 `label`，优先使用当前租户函数目录的参数选项名称。CLI 会保留接口的完整 `detail`（包括 `paramSelect/paramSelectDetail`），供所有函数的枚举参数回显。示例：`DATEDIFF({date}, 预计完成日期, "天数") × 8` 写为 `{kind:'function',name:'×',args:[{kind:'function',name:'DATEDIFF',args:[{kind:'system_variable',key:'{date}'},{kind:'context',paramKey:'<日期字段>',label:'预计完成日期',fieldType:'date'},{kind:'fixed',value:'dy',label:'天数'}]},{kind:'fixed',value:8}]}`；首次用于新租户时仍应保存并回读确认。
+- **函数引用明细行字段**：函数参数若来自流程明细表，仍传真实 `paramKey:"<流程id>.<明细表id>[].<字段id>"`，但必须按手工编辑器的真实结构编译为 `type:3` 上下文引用，不能使用 `type:10/sub`，也不能使用 `mainBasis`。`value` 必须为 `FormData.<流程id>.<明细表id>[<索引子节点position>].<字段id>`；同时挂一个 `type:1`、`name/value:"0"` 的索引子节点，`[]` 内填写该子节点的 `position`。`config` 保留逻辑 `paramKey`（其中仍是 `[]`）、`fieldInfo.tablePrimaryKey:"FormData"`、`parentName:"<流程名>.<明细表名>[].<字段名>"` 和同样使用逻辑 `[]` 路径的 `multTypeObj`。缺少索引子节点时，编辑器会只显示红色字段名，丢失“流程触发 → 明细表[0] → 字段”的上下文链。

package/skill-docs/actionflows/references/components/ebuilder/ActionEbDelete.md

@@ -1,21 +1,23 @@
-# 删除表单数据（`ActionEbDelete`）
-
-## 何时使用
-
-按筛选条件删除 e-builder 表单数据；还原已删除数据使用 `ActionEbRecover`。
-
-## 先查询
-
-查询目标表单、条件字段和操作人。
-
-## 不可猜测
-
-筛选条件必须引用目标表真实字段；不能把名称或非本次上下文的字段键写入条件。
-
-## 最小计划
-
-`targetForm`、`person`、`filterCondition`。
-
-## filterCondition 格式
-
-**以 `actionflows/references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，否则编译报「左侧字段 id 不在目标表单实时字段列表中」。
+# 删除表单数据（`ActionEbDelete`）
+
+## 何时使用
+
+按筛选条件删除 e-builder 表单数据；还原已删除数据使用 `ActionEbRecover`。
+
+## 先查询
+
+查询目标表单、条件字段和操作人。
+
+## 不可猜测
+
+筛选条件必须引用目标表真实字段；不能把名称或非本次上下文的字段键写入条件。
+
+## 最小计划
+
+`targetForm`、`person`、`filterCondition`。
+
+## filterCondition 格式
+
+**以 `references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，否则编译报「左侧字段 id 不在目标表单实时字段列表中」。
+
+当条件左字段是「关联流程」Workflow 时，必须由 Skill 根据实时字段元数据和 `workflowPath.formIds` 反查真实流程表单对象；编译后的左值使用原始数字 `fieldName`、`fieldType:"String"`、顶层 `sformId` 和 `formInfo.formId/layoutId`，不得套用普通业务字段的 `field_` 前缀或把目标表单版本 ID写成 `sformId`。

package/skill-docs/actionflows/references/components/ebuilder/ActionEbUpdate.md

@@ -1,21 +1,23 @@
-# 更新表单数据（`ActionEbUpdate`）
-
-## 何时使用
-
-更新已有 e-builder 数据；新增数据使用 `ActionEbAdd`，删除数据使用 `ActionEbDelete`。
-
-## 先查询
-
-查询目标表单及字段；按条件更新还要确认条件左字段和本次触发器上下文。
-
-## 不可猜测
-
-`id`、`updateData`、`fieldUpdate` 三种定位方式互不替代。`basisValue` 只用于真实上游明细依据值。
-
-## 最小计划
-
-`targetForm`、`person`、更新赋值，以及与 `opType` 对应的定位参数。
-
-## filterCondition 格式（opType=updateData 定位条件）
-
-**以 `actionflows/references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，否则编译报「左侧字段 id 不在目标表单实时字段列表中」。
+# 更新表单数据（`ActionEbUpdate`）
+
+## 何时使用
+
+更新已有 e-builder 数据；新增数据使用 `ActionEbAdd`，删除数据使用 `ActionEbDelete`。
+
+## 先查询
+
+查询目标表单及字段；按条件更新还要确认条件左字段和本次触发器上下文。
+
+## 不可猜测
+
+`id`、`updateData`、`fieldUpdate` 三种定位方式互不替代。`basisValue` 只用于真实上游明细依据值。
+
+## 最小计划
+
+`targetForm`、`person`、更新赋值，以及与 `opType` 对应的定位参数。
+
+## filterCondition 格式（opType=updateData 定位条件）
+
+**以 `references/condition_rules.md` 为准**：`{"field":{"id":"<目标字段id>","label":"<字段名>"},"operator":"eq","right":{...}}`。`field` 是 `{id,label}` 对象、`operator` 用英文操作符（`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`）、右值键用 `right`。**勿用**废弃的 `value` 别名 / `=` / 裸字符串 `field`，否则编译报「左侧字段 id 不在目标表单实时字段列表中」。
+
+当条件左字段是「关联流程」Workflow 时，必须由 Skill 根据实时字段元数据和 `workflowPath.formIds` 反查真实流程表单对象；编译后的左值使用原始数字 `fieldName`、`fieldType:"String"`、顶层 `sformId` 和 `formInfo.formId/layoutId`，不得套用普通业务字段的 `field_` 前缀或把目标表单版本 ID写成 `sformId`。

package/skill-docs/actionflows/references/components/ebuilder/EnquiryForm.md

@@ -1,75 +1,101 @@
-# 查询表单数据（`EnquiryForm`）
-
-## 何时使用
-
-查询 e-builder 表单列表或分组统计；按单条 ID 读取使用 `EbGetDataById`。
-
-## 先查询
-
-查询数据源、全部字段、筛选字段、输出字段和查询操作人。
-
-## 不可猜测
-
-筛选、排序、分组和输出字段都必须来自当前数据源；统计结果应作为后续节点上下文使用。
-
-## 最小计划
-
-`dataSource`、`person`；按 `opType` 补充查询字段和筛选条件。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选主表和系统字段，包含“数据ID”。
-
-## 批量新增主表字段引用查询结果（2026-08-27 真机钉死）
-
-**结论：当需求确实需要反查时，EnquiryForm 查询结果可以赋给 `batchInsert` 主表字段（标量），但只限"单值反查"场景**。它不是任何表单新增动作的默认前置节点。手动创建成功样本：`actionflows/references/examples/enquiry-form-batch-insert-scene2.json`（ApproveTrigger → EnquiryForm → ActionEbAdd(batchInsert) → Output）。
-
-关键结构（与旧结论不同，已修正）：
-
-1. **EnquiryForm 节点（首动作）**：
-   - `dataSource.type = "LOGIC"`、`dataSource.groupId = "weaver-ebuilder-form-service"`（不是表单所属应用 id！）
-   - `queryFields[].id = "id"`（简写，不是 `{表id}[].id`）；`fieldGroup = { name: 表名, id: 表id }`
-   - 筛选：`filterInput.datas[].conditions.value` 用流程上下文 type=3（`ApprovalData.{wfId}.requestId`）
-   - 首动作 **不需要 sources**（undefined），ActionEbAdd 的 sources 指向 EnquiryForm 节点 wId
-
-2. **主表字段引用查询结果（项目名称 5453）**：
-   - assign：`type=3`，`value = "FormData.{查询表id}[{positionId}].id"`（**数组下标用 positionId 而非 `[]`**）
-   - `config.comType = "EnquiryForm"`、`config.comId = EnquiryForm 节点 id`、`config.paramKey = "{查询表id}[].id"`（paramKey 保持 `[]` 数组标记）
-   - **childs 必须带固定值取下标**：`[{ type: "1", value: "0", position: "{positionId}" }]`（value=0 取第一条）
-   - `frontId` = 查询结果字段的临时 id（非表单字段 id）
-
-3. 其余明细字段仍用依据值下级 type=10 直连（paramKey `{wfId}.{明细表id}[].{子字段id}`，source=event 节点 id）。
-
-4. 挂接注意：EnquiryForm 作为**流程首动作**保存成功；此前「两个起始执行组件」报错疑与给首动作补 sources 或 dataSource.type 用 FORM 有关，**勿给首动作补 sources**。
-
-计划中引用该结果时，必须显式写 `kind:"query_result"`，不能把它写成普通流程字段。例如：
-
-```json
-{
-  "mapping": {
-    "<查询表单id>[].id": {
-      "target": "<目标字段id>",
-      "kind": "query_result",
-      "source": "<EnquiryForm动作ref>",
-      "formId": "<查询表单id>",
-      "fieldId": "id",
-      "label": "数据ID",
-      "index": 0
-    }
-  }
-}
-```
-
-其中查询动作需显式声明例如 `{"type":"EnquiryForm","ref":"项目查询","params":{...}}`，后续写 `source:"项目查询"`。编译器会将该语义 `ref` 替换为实际节点 ID，并生成保存所需的 `childs` 下标公式；禁止使用或猜测平台节点 ID。
-
-## 关键边界：只支持"单值反查"，不支持"逐行明细反查"（2026-08-27 用户确认）
-
-**适用条件（场景2 成立的唯一前提）**：EnquiryForm 的筛选条件用的是**流程级唯一值**（如 `关联流程 eq requestId`），业务上一个流程只对应一条查询结果 → 取第一条（childs value=0）就是唯一那条，赋值主表字段正确。
-
-**禁止场景（多条结果）**：如果筛选条件用的是**明细行 id/明细字段**（如"按任务编号反查"），查询结果会有多条，且**数据源返回结果的顺序与流程明细表的行顺序不保证一致**（第 1 行明细对应的结果可能排在返回结果第 5 行）。此时：
-- 无法用"取第一条"对应到正确的明细行；
-- 无法把查询结果作为依据值（basisValue）传给下方组件——明细字段值仍需以**流程明细表本身作为依据值**（type=10 直连）；
-- **转化规则必须逐行做明细字段转化，多条结果做不到 → 该场景明确拒绝，不硬凑 EnquiryForm**。
-
-一句话决策：**EnquiryForm 反查只能给"与明细行无关的全局单值"（主表字段，按流程级唯一条件查）；凡需"按每行明细反查对应值"的，直接拒绝并告知用户**。
-
-## 曾经的错误结论（已推翻，勿沿用）
-
-- ~~EnquiryForm 输出是列表数组不能赋主表标量~~ → 实际通过 childs 固定值取下标（value=0 第一条）实现（仅限单值反查）。
-- ~~批量新增场景不要用 EnquiryForm 反查~~ → 单值反查是标准做法，见上；逐行反查仍不可行。
+# 查询表单数据（`EnquiryForm`）
+
+## 何时使用
+
+查询 e-builder 表单列表或分组统计；按单条 ID 读取使用 `EbGetDataById`。
+
+## 先查询
+
+查询数据源、全部字段、筛选字段、输出字段和查询操作人。
+
+## 不可猜测
+
+筛选、排序、分组和输出字段都必须来自当前数据源；统计结果应作为后续节点上下文使用。
+
+## 最小计划
+
+`dataSource`、`person`；按 `opType` 补充查询字段和筛选条件。未明确限制 `queryFields` 时不要传它（或传空数组），CLI 会默认全选主表和系统字段，包含“数据ID”。
+
+## 分组/汇总查询
+
+`opType:"groupFields"` 是原生“分组/汇总”能力，不需要规则集或外部计算组件：
+
+- `groupFields` 是分组维度：`[{"field":"<真实字段id>"}]`；没有分组维度时传空数组。
+- `groupMessage` 是汇总值：`[{"field":"<真实字段id>","aggregator":"SUM"}]`。
+- 可用聚合方式：`SUM`、`MIN`、`AVG`、`MAX`、`COUNT`、`DISTINCTCOUNT`。其中 `SUM`/`AVG` 只用于数值字段。
+- 汇总输出字段名由平台固定为 `s_sum_<字段id>`、`s_min_<字段id>`、`s_avg_<字段id>`、`s_max_<字段id>`、`s_count_<字段id>`、`s_distinctcount_<字段id>`；后续节点引用它时使用 `kind:"query_result"`、`fieldId:"s_sum_<字段id>"`、`source:"<查询动作ref>"`、`index:0`。
+
+示例：汇总“收款金额”并让后续节点取第一条汇总结果：
+
+```json
+{
+  "type": "EnquiryForm",
+  "ref": "收款汇总",
+  "params": {
+    "dataSource": {"groupId":"<应用id>","id":"<合同收款表id>","text":"合同收款表"},
+    "person": {"type":"role"},
+    "opType": "groupFields",
+    "filter": {"field":{"id":"<关联项目字段id>","label":"关联项目"},"operator":"eq","right":{"kind":"context","paramKey":"<当前表单>.关联项目"}},
+    "groupFields": [],
+    "groupMessage": [{"field":"<收款金额字段id>","aggregator":"SUM"}]
+  }
+}
+```
+
+## 批量新增主表字段引用查询结果（2026-08-27 真机钉死）
+
+**结论：当需求确实需要反查时，EnquiryForm 查询结果可以赋给 `batchInsert` 主表字段（标量），但只限"单值反查"场景**。它不是任何表单新增动作的默认前置节点。手动创建成功样本：`references/examples/enquiry-form-batch-insert-scene2.json`（ApproveTrigger → EnquiryForm → ActionEbAdd(batchInsert) → Output）。样例中的 `opText` 是历史平台序列化快照，不是生成模板；生成时只依据语义 plan 和实时字段元数据，尤其不要复制其中 Workflow 左值的旧 `field_`/`Workflow` 组合。
+
+关键结构（与旧结论不同，已修正）：
+
+1. **EnquiryForm 节点（首动作）**：
+   - `dataSource.type = "LOGIC"`、`dataSource.groupId = "weaver-ebuilder-form-service"`（不是表单所属应用 id！）
+   - `queryFields[].id = "id"`（简写，不是 `{表id}[].id`）；`fieldGroup = { name: 表名, id: 表id }`
+   - 筛选：`filterInput.datas[].conditions.value` 用流程上下文 type=3（`ApprovalData.{wfId}.requestId`）
+   - 首动作 **不需要 sources**（undefined），ActionEbAdd 的 sources 指向 EnquiryForm 节点 wId
+
+2. **主表字段引用查询结果（项目名称 5453）**：
+   - assign：`type=3`，`value = "FormData.{查询表id}[{positionId}].id"`（**数组下标用 positionId 而非 `[]`**）
+   - `config.comType = "EnquiryForm"`、`config.comId = EnquiryForm 节点 id`、`config.paramKey = "{查询表id}[].id"`（paramKey 保持 `[]` 数组标记）
+   - **childs 必须带固定值取下标**：`[{ type: "1", value: "0", position: "{positionId}" }]`（value=0 取第一条）
+   - `frontId` = 查询结果字段的临时 id（非表单字段 id）
+
+3. 其余明细字段仍用依据值下级 type=10 直连（paramKey `{wfId}.{明细表id}[].{子字段id}`，source=event 节点 id）。
+
+4. 挂接注意：EnquiryForm 作为**流程首动作**保存成功；此前「两个起始执行组件」报错疑与给首动作补 sources 或 dataSource.type 用 FORM 有关，**勿给首动作补 sources**。
+
+计划中引用该结果时，必须显式写 `kind:"query_result"`，不能把它写成普通流程字段。例如：
+
+```json
+{
+  "mapping": {
+    "<查询表单id>[].id": {
+      "target": "<目标字段id>",
+      "kind": "query_result",
+      "source": "<EnquiryForm动作ref>",
+      "formId": "<查询表单id>",
+      "fieldId": "id",
+      "label": "数据ID",
+      "index": 0
+    }
+  }
+}
+```
+
+其中查询动作需显式声明例如 `{"type":"EnquiryForm","ref":"项目查询","params":{...}}`，后续写 `source:"项目查询"`。编译器会将该语义 `ref` 替换为实际节点 ID，并生成保存所需的 `childs` 下标公式；禁止使用或猜测平台节点 ID。
+
+## 关键边界：只支持"单值反查"，不支持"逐行明细反查"（2026-08-27 用户确认）
+
+**适用条件（场景2 成立的唯一前提）**：EnquiryForm 的筛选条件用的是**流程级唯一值**（如 `关联流程 eq requestId`），业务上一个流程只对应一条查询结果 → 取第一条（childs value=0）就是唯一那条，赋值主表字段正确。
+
+**禁止场景（多条结果）**：如果筛选条件用的是**明细行 id/明细字段**（如"按任务编号反查"），查询结果会有多条，且**数据源返回结果的顺序与流程明细表的行顺序不保证一致**（第 1 行明细对应的结果可能排在返回结果第 5 行）。此时：
+- 无法用"取第一条"对应到正确的明细行；
+- 无法把查询结果作为依据值（basisValue）传给下方组件——明细字段值仍需以**流程明细表本身作为依据值**（type=10 直连）；
+- **转化规则必须逐行做明细字段转化，多条结果做不到 → 该场景明确拒绝，不硬凑 EnquiryForm**。
+
+一句话决策：**EnquiryForm 反查只能给"与明细行无关的全局单值"（主表字段，按流程级唯一条件查）；凡需"按每行明细反查对应值"的，直接拒绝并告知用户**。
+
+## 曾经的错误结论（已推翻，勿沿用）
+
+- ~~EnquiryForm 输出是列表数组不能赋主表标量~~ → 实际通过 childs 固定值取下标（value=0 第一条）实现（仅限单值反查）。
+- ~~批量新增场景不要用 EnquiryForm 反查~~ → 单值反查是标准做法，见上；逐行反查仍不可行。

package/skill-docs/actionflows/references/components/ebuilder/EventButton.md

@@ -0,0 +1,33 @@
+# e-builder 按钮触发（`EventButton`）
+
+## 何时使用
+
+需求明确为点击 e-builder 表单上的某个按钮时触发。它与 `EventFormData` 不同：后者只监听数据变动，不能识别是由哪个按钮触发。
+
+## 先查询
+
+1. 用 `form-applications`、`form-list` 确认表单和所属业务应用。
+2. 用 `e10-cli actionflow form-buttons '{"tableId":"<表单ID>","appId":"<应用ID>"}'` 读取真实按钮 ID、名称与启用状态。
+
+不要按按钮名称猜测 ID，也不要创建按钮作为生成动作流的隐含步骤。
+
+## 最小计划
+
+```json
+{
+  "event": {
+    "type": "EventButton",
+    "params": {
+      "targetForm": {"groupId":"<应用ID>","id":"<表单ID>"},
+      "buttonType": [{"id":"<按钮ID>","name":"<按钮名称>","buttonLocation":"after"}],
+      "triggerType": "sequence"
+    }
+  }
+}
+```
+
+`buttonLocation` 只能是 `before`（按钮默认动作前）或 `after`（默认动作后）。多选记录场景的 `triggerType` 为 `sequence`、`merge` 或 `parallel`。需要异步时在对应按钮项写 `asyncExecution:true`。
+
+## 上下文
+
+触发后可引用 `FormData`、`FormField`、`FormButton`、`SettingInfo`、`accessId` 和 `monitorId`。先通过组件上下文预检获取当前租户的字段，禁止猜测字段路径。

package/skill-docs/actionflows/references/components/logic/Condition.md

@@ -1,23 +1,23 @@
-# 条件分支（`Condition`）
-
-## 何时使用
-
-根据上游字段进入 if/else if/else 分支。
-
-## 先查询
-
-查询当前触发器的真实上下文字段及字段类型。
-
-## 不可猜测
-
-条件左值只能引用当前可见上下文；右值、操作符和字段类型必须匹配。未知操作符或类型不兼容必须报错，不能静默改成“等于”。无法通过条件编辑器实际回显时，不伪称已验证。
-
-右值使用 `fixed`、`system`、`context` 之一；动态右值传 `type:"context"` 和真实 `paramKey`，或传平台回读的完整 `formula`。不要把动态字段名当作固定字符串。
-
-## 保存与回读
-
-分支条件由运行时在预暂存注册来源节点后保存：取得真实 `mapBaseId`，保存完整嵌套 `childrens` 树，并以保存响应的真实 `conditionId/mapBaseId/mapId` 回填设计。新建后 `getExpressionBean` 可能只返回分组骨架，不能以它覆盖完整叶子树。所有平台 Long ID 都按字符串处理；最终以动作流暂存回读和设计器弹窗确认。
-
-## 最小计划
-
-`branches`，每个 if/else if 有真实 `condition`，每个分支有动作列表。
+# 条件分支（`Condition`）
+
+## 何时使用
+
+根据上游字段进入 if/else if/else 分支。
+
+## 先查询
+
+查询当前触发器的真实上下文字段及字段类型。
+
+## 不可猜测
+
+条件左值只能引用当前可见上下文；右值、操作符和字段类型必须匹配。未知操作符或类型不兼容必须报错，不能静默改成“等于”。无法通过条件编辑器实际回显时，不伪称已验证。
+
+右值使用 `fixed`、`system`、`context` 之一；动态右值传 `type:"context"` 和真实 `paramKey`，或传平台回读的完整 `formula`。不要把动态字段名当作固定字符串。
+
+## 保存与回读
+
+分支条件由运行时在预暂存注册来源节点后保存：取得真实 `mapBaseId`，保存完整 `childrens` 树，并以保存响应的真实 `conditionId/mapBaseId/mapId` 回填设计。顶层 `relationship` 直接作为根关系，不能再包一层相同关系的子组；只有 plan 明确写出的嵌套 AND/OR 才保留嵌套。新建后 `getExpressionBean` 可能只返回分组骨架，不能以它覆盖完整叶子树。所有平台 Long ID 都按字符串处理；最终以动作流暂存回读和设计器弹窗确认。
+
+## 最小计划
+
+`branches`，每个 if/else if 有真实 `condition`，每个分支有动作列表。

package/skill-docs/actionflows/references/components/message/InnerMQSend.md

@@ -0,0 +1,40 @@
+# 内置 MQ 发送（`InnerMQSend`）
+
+## 何时使用
+
+向平台内置 MQ 的 Topic/队列发送消息时使用。它不是外部 MQ 连接器的生产者动作。
+
+## 参数
+
+```json
+{
+  "actions": [
+    {
+      "type": "InnerMQSend",
+      "params": {
+        "queueName": "真实Topic名称",
+        "sendModel": "1",
+        "sendParams": "<平台 InnerMqComponentDTO.sendParams 原生 ParamMappingBean>"
+      }
+    }
+  ]
+}
+```
+
+- `queueName` 和 `sendParams` 必填；固定 Topic 直接传字符串，CLI 会转换为平台所需的 `FormulaBean`。
+- `queueName` 也可以传已解析的 `context`/`fixed`/`system_variable` 赋值或平台原生 `FormulaBean`。
+- `sendModel` 为 `1` 广播模式或 `2` 集群模式，省略时默认 `1`。
+- `sendParams` 必须来自平台发送参数设计器的原生 `ParamMappingBean`，不要用 `receiveParams` 或普通字符串替代。
+
+### 参数类型与数据类型联动
+
+`tableData` 中每一行的 `paramType` 决定 `dataType` 的合法候选和是否允许继续加下级，不能只把 `dataType` 当成一个任意字符串填写：
+
+- 普通标量（如 `string`、`int`、`boolean` 等）且 `arrs:false` 时，合法数据类型只有“属性”；平台因此不会显示数据类型下拉，这是正常行为。
+- `arrs:true` 时，平台允许在该参数类型对应的多个数据类型中选择；数组参数的 `paramKey` 回读时可能规范化为带 `[]` 的形式。
+- `json`、`xml`、`xml_string` 是结构化参数，可以通过 `parentId` 组织下级参数；下级参数仍需按自身 `paramType` 和父节点限制填写，不能把结构化参数拍平成普通标量。
+- 数据类型下拉是否显示是设计器根据参数类型、数组标志、父节点和固定类型限制计算出来的 UI 状态，不由服务端仅凭 `dataType` 字段强行打开。
+
+因此，需求只要求一个数据类型时不要伪造下拉；需求需要多种数据类型或下级节点时，必须按真实参数类型构造 `tableData` 层级。
+
+`InnerMQSend` 与触发器 `InnerMQListener` 不能同时出现在一个动作流中，包括条件和循环内部；CLI 会在创建或更新前拒绝该计划。

package/skill-docs/actionflows/references/components/message/SendMessage.md

@@ -6,11 +6,11 @@
 
 ## 先查询
 
-固定接收人查询当前租户人员；动态内容查询本次上下文。
+固定接收人查询当前租户人员；上游负责人等动态接收人使用本次上下文；标题和正文中的动态片段也使用本次上下文。
 
 ## 不可猜测
 
-标题和内容按需求选固定文本或 `parts` 模板；纯字符串保持固定值，只有 `parts` 模板才进入设计器的动态赋值。模板上下文只传 `paramKey` 和 `label`，由 CLI 按消息编辑器的动态片段结构编译。对定时批量、按日期字段、表单数据等 e-builder 记录触发器，未显式提供链接时 CLI 自动生成 PC/移动端详情链接：`formId` 为触发表单 ID 固定值，`dataId` 为上游“数据ID”动态上下文。显式 `pcLink` / `mobileLink` 会覆盖该默认行为。
+标题和内容按需求选固定文本或 `parts` 模板；纯字符串保持固定值，只有 `parts` 模板才进入设计器的动态赋值。需要动态接收人时传 `receiver: {"type":"context","paramKey":"<真实人员字段paramKey>","label":"<字段名>"}`，不能把人员字段当固定人员 ID，也不能省略 `paramKey`。模板上下文只传 `paramKey` 和 `label`，由 CLI 按消息编辑器的动态片段结构编译，并绑定当前触发节点。对定时批量、按日期字段、表单数据等 e-builder 记录触发器，未显式提供链接时 CLI 自动生成 PC/移动端详情链接：`formId` 为触发表单 ID 固定值，`dataId` 为上游“数据ID”动态上下文。显式 `pcLink` / `mobileLink` 会覆盖该默认行为。
 
 ## 最小计划
 

package/skill-docs/actionflows/references/components/trigger/CustomTrigger.md

@@ -0,0 +1,45 @@
+# 自定义事件触发（`CustomTrigger`）
+
+## 何时使用
+
+需求明确要求由平台自定义事件主动触发动作流时使用。它不是 e-builder 表单数据变化触发，也不是按钮触发。
+
+## 参数
+
+唯一必填参数是 `customData`。设计器实际使用的是 `SetParam` 的参数对象：顶层保留 `customId`、`formType`、`businessModule`、`tableList`，每个 `tableList` 项包含 `id`、`showName`、`isMain`、`orderNum` 和 `fields`；每个字段至少要有 `id`、`paramName`、`showName`、`paramType`。它必须来自平台自定义触发配置/回读或上下文接口返回的原生对象，不要改写成旧的 `tables` 结构，也不要猜测一套字段。
+
+```json
+{
+  "event": {
+    "type": "CustomTrigger",
+    "params": {
+      "customData": {
+        "customId": "<平台返回>",
+        "formType": "input",
+        "businessModule": "esb",
+        "tableList": [{
+          "id": "<平台返回>",
+          "showName": "主表",
+          "isMain": true,
+          "orderNum": 0,
+          "fields": [{
+            "id": "<平台返回>",
+            "paramName": "payload",
+            "showName": "消息体",
+            "paramType": "string",
+            "isRequired": true
+          }]
+        }]
+      }
+    }
+  }
+}
+```
+
+自定义参数的字段定义是业务特定的。没有真实 `customData` 时先读取已有动作流/组件上下文，不要生成空壳触发器。`tableList` 或其中的 `fields` 为空时，设计器“输入参数设置”就是空白；这不是回读截断，而是发送的对象本身没有参数。
+
+根触发器图标不是 `Icon-custom-trigger`，编译器统一保存为 `Icon-N-Triggerrul`。
+
+## 上下文
+
+触发后可引用平台提供的 `FormData`、`FormField`、`SettingInfo`、`accessId` 和 `monitorId`；具体字段以当前租户上下文返回为准。

package/skill-docs/actionflows/references/components/trigger/InnerMQListener.md

@@ -0,0 +1,40 @@
+# 内置 MQ 监听（`InnerMQListener`）
+
+## 何时使用
+
+需求明确要求监听平台内置 MQ 广播 Topic 时使用。它不同于外部 RabbitMQ/Kafka 等 `MqConsumer`。
+
+## 参数
+
+```json
+{
+  "event": {
+    "type": "InnerMQListener",
+    "params": {
+      "queueName": "真实Topic名称",
+      "sendModel": "1",
+      "receiveParams": {
+        "tableId": "<平台参数表 ID>",
+        "tableData": [{
+          "id": "<平台字段 ID>",
+          "paramKey": "payload",
+          "paramName": "payload",
+          "showName": "消息体",
+          "paramType": "string",
+          "dataType": "attribute",
+          "required": true,
+          "arrs": false
+        }]
+      }
+    }
+  }
+}
+```
+
+- `queueName` 必填，使用平台真实 Topic/队列名称。
+- `sendModel` 当前只支持 `1`（广播模式），省略时 CLI 默认填入 `1`。
+- `receiveParams` 可选；有业务接收字段时传平台原生 `ParamSettingBean`，在当前设计器回读结构中表现为 `tableId + tableData`，没有时省略。不能传 `{type:'SETTING', tables:[]}` 期待它自动生成输入字段。
+
+根触发器图标不是猜测的 `Icon-message-queue`，平台内置 MQ 监听实际使用 `Icon-built-in-mq-listening-mcolor`；不要把发送动作的图标当成监听触发器图标。
+
+`InnerMQListener` 与动作 `InnerMQSend` 不能同时出现在一个动作流中，包括条件和循环内部；CLI 会在创建或更新前拒绝该计划。