weaver-e10-builder 1.2.2 → 1.2.5

package/skill-docs/references/form/guide-list-custom-text.md

@@ -0,0 +1,52 @@
+# 列表自定义文本列
+
+表单的列表式视图（台账）里，列除了直接绑表单字段，还能加一列**自定义文本**：内容是一段富文本，
+可以写固定文字、插图，也能在文字中间**插入表单字段**（「合计：〔金额〕元」这种说明性排版）。
+
+命令是 `form nlist apply`：模板里**不给 `fieldId`、改给 `html`** 的列项，就是自定义文本列。
+
+```json
+[
+  [
+    {"fieldId": "1317534123603582976", "text": "金额", "width": 1},
+    {"html": "<p>合计：{{金额}} 元</p>", "text": "合计", "width": 1}
+  ]
+]
+```
+
+```bash
+e10-cli form nlist apply <objId> <appId> <listId> @template.json
+```
+
+## 在自定义文本里插入表单字段
+
+写 `{{字段名}}` 或 `{{fieldId}}`，CLI 查表单元数据后展开成平台的字段引用标记。
+
+上面那段 `html` 存进去的是：
+
+```html
+<p>合计：<span contenteditable="false" data-type="list" data-val="{objId.fieldId}">{表名.字段名}</span> 元</p>
+```
+
+规则：
+
+- 同一字段写几次就展开几份 —— 平台按**出现位置**逐个记引用，不去重。
+- 字段显示名在表单内重复时报错，改用 `fieldId`。
+- 字段不存在 → 报错并中止，不会把半截 HTML 写进视图。
+
+## 直接写字段引用标记
+
+已经拿到平台原样标记时，也可以把它整段写进 `html`。CLI 会校验 `data-val` 里的 fieldId 在这张
+表单里是否存在，查不到只**告警**（平台对这种引用不报错，只是静默显示不出值，所以提醒一声）。
+
+标记的形状固定为 `<span contenteditable="false" data-type="list" data-val="{objId.fieldId}">{表名.字段名}</span>`：
+**身份在 `data-val` 里的 `objId.fieldId`**，span 里的 `{表名.字段名}` 只是占位文本。
+
+## 其它
+
+- 列显示名用模板项的 `text`，缺省「自定义文本」。
+- 富文本的配色、字号、背景直接写在内联 `style` 里，与设计器编辑器一致，例如
+  `<span style="background-color:#27ae60">应收</span>`。
+- `form nlist apply` 按模板整体重建显示列与排布，PC 与移动端两个槽位一并写入；
+  当前配置用 `form nlist show <objId> <appId> <listId>` 查看。
+- ⚠ 只对列表式（NList）生效，表格式台账用 `form table-view`。

package/skill-docs/references/menu/system-menus.md

@@ -61,3 +61,15 @@
 ```
 
 > **只有包含工作流的应用**才能挂载工作流系统页面。表单台账会自动挂入菜单，无需手动操作。
+
+---
+
+## 菜单是一棵树
+
+应用菜单不止一层：顶层之外还有 `children` 嵌套（例如平台自带的「设置 → 个人设置 → 个人菜单设置」、系统设置下的「基本信息 / 菜单设置」）。
+
+- `menu list <appId>` **递归展开**整棵树，输出带缩进；末尾会注明含多少个嵌套菜单。**这份列表就是全量**，在它里面找不到某个菜单，才能下结论说「该应用没有这个菜单」。
+- `menu rename <appId> <菜单ID或名称> <新名>` 按 ID 或名称定位，**嵌套里的菜单一样能改**。同名多条时命令会报歧义并列出候选 ID，不会替你挑一条。
+- 改名的命令会**重建写报文**再回读比对：名称变了、且「页面绑定 / 菜单 URL / 可见范围」等字段一个都没动，才算成功。改名只动名字，不会顺带改掉已有的筛选条件或页签配置。
+
+**平台系统菜单（回收站、设置及其子项）不能改名** —— 它们由平台维护、指向内置页面，改名没有语义，命令会直接拒绝。

package/skill-docs/references/workflow/guide-workflow-auth-resp.md

@@ -1,190 +1,198 @@
-# 权责表与权责表方式流程
-
-权责表把多个条件场景及其审批路径维护为“节点列 × 分支行”。它属于工作流公用流转资源，与 HRM 矩阵、普通公共片段和流程图布局分别管理。
-
-## 一、选择方式
-
-- 需要独立维护、供多个流程复用：先创建独立权责表，再由流程引用并映射变量。
-- 只服务于当前流程，且表单已经确定：创建权责表方式流程时选择新建权责表，条件直接引用表单字段。
-- 需要插入另一张权责表的审批路径中：创建中间片段型权责表，首尾位置使用审批等中间节点类型，再由宿主权责表按分支引用。
-- 普通顺序、分支流程继续使用流程图方式；只有需求明确要求权责表时才使用本指南。
-
-## 二、独立权责表搭建顺序
-
-1. `workflow auth-resp create` 创建权责表并记录 `authRespId`。
-2. `workflow auth-resp variable add` 创建条件需要的变量；条件只能引用已创建变量。
-3. 建立发起、结束设置和多个中间审批节点。中间节点统一作为列创建，操作者规则沿用工作流节点操作者规则。
-4. 为每个有效分支填写分支场景说明并创建条件。
-5. 每个分支从已有中间节点中选择自己的路径，通过顺序号表达串行或并行。
-6. `workflow auth-resp save-design --config @design.json` 保存并回读。
-
-从零完整搭建优先使用：
-
-```bash
-e10-cli workflow auth-resp configure <authRespId> --config @auth-resp.json
-```
-
-`auth-resp.json` 使用业务结构描述变量、节点、操作者、分支条件及路径：
-
-```json
-{
-  "baseId": "创建权责表返回的baseId",
-  "name": "合同分级审批权责表",
-  "workflowId": "-99999999",
-  "usage": "workflow",
-  "variables": [
-    { "id": "-自定义稳定ID", "name": "合同金额", "type": "wf_number" }
-  ],
-  "start": { "name": "开始节点", "operator": { "type": "all" } },
-  "end": { "name": "结束节点", "operator": { "type": "initiator" } },
-  "nodes": [
-    { "key": "manager", "name": "部门负责人审批", "type": "approve", "operator": { "type": "user", "keyword": "张三" } },
-    { "key": "finance", "name": "财务审批", "type": "approve", "operator": { "type": "user", "keyword": "李四" } }
-  ],
-  "branches": [
-    {
-      "scenario": "合同金额不超过5万元",
-      "condition": {
-        "relation": "AND",
-        "childrens": [
-          {
-            "selectType": "4",
-            "formField": [{ "id": "-自定义稳定ID", "name": "合同金额", "fieldType": "NumberComponent", "variable": true, "varFirstType": "wf_number" }],
-            "NumberCompareOptionLeft": "4",
-            "NumberValueOptionLeft": "1",
-            "NumberTextValueLeft1": 50000,
-            "elementValue1Id": "",
-            "elementValue2Id": "",
-            "expressionBaseId": "",
-            "dataValueId": ""
-          }
-        ]
-      },
-      "path": [
-        { "node": "manager", "order": 1 },
-        { "node": "finance", "order": 2 }
-      ]
-    }
-  ]
-}
-```
-
-流程内新建权责表时，`workflowId` 写真实流程 ID，条件 `formField` 使用该流程实际表单字段；独立权责表使用 `workflowId=-99999999`，条件引用 `variables` 中的变量。操作者类型直接支持 `all`、`user`、`initiator`；其他已有操作者类型使用 `raw` 并提供平台 `itemDatas`，结构与普通流程操作者一致。
-
-`usage=workflow` 表示完整流转，首尾默认使用发起和结束节点。`usage=fragment` 表示供其他权责表路径引用的中间片段，`start.type` 与 `end.type` 均配置为 `approve`、`confirm` 等中间节点类型；首尾位置不能使用 `start` 或 `end`。
-
-```bash
-e10-cli workflow auth-resp create "合同分级审批权责表"
-e10-cli workflow auth-resp variable add <authRespId> "合同金额" wf_number
-e10-cli workflow auth-resp variable list <authRespId>
-e10-cli workflow auth-resp read <authRespId> --base-id <baseId> > design.json
-e10-cli workflow auth-resp save-design <authRespId> --config @design.json
-```
-
-变量类型码当前已确认：
-
-| 类型码 | 含义 | 补充配置 |
-|---|---|---|
-| `wf_string` | 字符串 | — |
-| `wf_number` | 数值 | — |
-| `wf_select` | 选项 | `--option-template '{"id":"...","name":"..."}'` |
-| `wf_browser` | 浏览 | `--second-type` |
-| `wf_browser_relate` | 关联浏览 | `--relate-browser @browser.json` |
-
-## 三、表格设计结构
-
-`read` 返回的设计以 `columns` 和 `rows` 为核心：
-
-- 固定列：发起设置 `creator`、分支场景说明 `eventColumn`、条件 `condition`、结束设置 `endOperator`。
-- 动态节点列：名称为 `pubNode-<节点ID>`，`pubNodeInfo` 保存节点类型和操作者摘要。
-- 嵌套权责表列：名称为 `pubNode-<权责表sourceId>`，`addMethod=2`，同时保存被引用表的 `baseId` 和版本。
-- 分支行：保存场景说明、`conditionKey`、发起/结束配置及选中的节点单元格。
-- 节点单元格：`nodeInfo` 表示该分支经过此节点；`approveNum` 是执行顺序，相同值表示并行。
-
-每个有效分支必须有非空 `eventColumn` 和 `conditionKey`。界面用于继续录入的空白占位行不进入 CLI 保存数据。
-
-操作者和条件的业务规则与普通工作流一致，具体语法读取 [流程指南](guide-workflow.md) 和 [流程条件指南](guide-workflow-condition.md)。权责表条件的上下文标识由权责表命令负责，不把独立权责表变量当作表单字段创建。
-
-## 四、在分支中引用权责表
-
-先查询当前宿主权责表可以引用的中间型权责表：
-
-```bash
-e10-cli workflow auth-resp reference list <宿主baseId> --name "金额复核"
-```
-
-平台按首尾节点类型过滤可引用项，并排除自身和循环引用。添加时指定被引用权责表的具体版本，以及它出现在哪些分支和对应执行顺序：
-
-```bash
-e10-cli workflow auth-resp reference add <宿主sourceId> --base-id <宿主baseId> --workflow-id <流程ID> --reference @reference.json
-```
-
-```json
-{
-  "id": "被引用权责表sourceId",
-  "name": "金额复核权责表【V1】",
-  "baseId": "被引用权责表baseId",
-  "versionNum": 1,
-  "paths": [
-    { "branch": "金额超过50万元", "order": 2 }
-  ]
-}
-```
-
-相同顺序号表示并行，不同顺序号表示串行。移除引用时，同时删除节点列和各分支中的对应路径单元格：
-
-```bash
-e10-cli workflow auth-resp reference remove <宿主sourceId> <被引用sourceId> --base-id <宿主baseId> --workflow-id <流程ID>
-```
-
-## 五、权责表方式创建流程
-
-权责表是流程的搭建方式，流程表单来源仍按原生工作流程规则选择：自建流程表单、绑定已有流程表单或绑定 EB 表单。基础表单参数写入 `base.json`，其字段与 `workflow create-workflow` 的创建结构一致。
-
-### 随流程新建权责表
-
-```bash
-e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --new-table "合同审批权责表"
-```
-
-服务端在创建流程时生成并返回 `workflowId`、`formId` 和 `newAuthRespId`。这种方式已确定实际表单，分支条件直接选择表单字段，不做变量映射；发起和结束位置直接设置操作者。
-
-### 复用已有权责表
-
-```bash
-e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --reuse-table <authRespId> --mappings @mappings.json
-```
-
-也可以对已经创建的流程分步执行：
-
-```bash
-e10-cli workflow auth-resp-flow bind <workflowId> <authRespId>
-e10-cli workflow auth-resp-flow mapping-read <workflowId>
-e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
-```
-
-复用模式把独立权责表变量映射为当前流程表单字段。先用 `mapping-read` 取得平台返回的变量项和可用字段结构，在对应项补全 `fieldBrowser` 后整体保存；变量类型必须与表单字段匹配。
-
-## 六、已有权责表流程的维护
-
-权责表方式流程的节点、分支条件、流转路径和生成出口统一通过绑定的权责表设计维护：
-
-```bash
-e10-cli workflow auth-resp-flow design-read <workflowId> --auth-resp-id <sourceId> --base-id <baseId> > design.json
-e10-cli workflow auth-resp-flow design-apply <workflowId> --auth-resp-id <sourceId> --config @design.json
-```
-
-权责表设计保存后，平台生成流程节点和出口。流程的出口列表用于查看生成结果及继续配置出口附加能力；改变分支、条件、经过节点和执行顺序时修改权责表设计。
-
-变量映射是独立的流程功能。复用权责表时，将权责表变量映射到当前流程实际表单字段：
-
-```bash
-e10-cli workflow auth-resp-flow mapping-read <workflowId>
-e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
-```
-
-映射项保留变量的 `varId`、`varName`、`varType` 和筛选参数，在 `fieldBrowser` 中写入实际字段；变量类型、主表或明细位置应与字段匹配。流程内新建权责表并直接使用表单字段时无需变量映射。
-
-## 七、Plan 记录
-
-流程计划中写清搭建方式、新建或复用的权责表、变量及字段映射、每个分支的场景说明与条件、经过节点和顺序、中间节点类型及操作者。执行时按“表单确定 → 权责表/流程创建 → 变量或字段条件 → 中间节点 → 分支路径 → 映射 → 其他流程设置”的顺序逐项销号。
+# 权责表与权责表方式流程
+
+权责表把多个条件场景及其审批路径维护为“节点列 × 分支行”。它属于工作流公用流转资源，与 HRM 矩阵、普通公共片段和流程图布局分别管理。
+
+## 一、选择方式
+
+- 需要独立维护、供多个流程复用：先创建独立权责表，再由流程引用并映射变量。
+- 只服务于当前流程，且表单已经确定：创建权责表方式流程时选择新建权责表，条件直接引用表单字段。
+- 需要插入另一张权责表的审批路径中：创建中间片段型权责表，首尾位置使用审批等中间节点类型，再由宿主权责表按分支引用。
+- 普通顺序、分支流程继续使用流程图方式；只有需求明确要求权责表时才使用本指南。
+
+## 二、独立权责表搭建顺序
+
+1. `workflow auth-resp create` 创建权责表并记录 `authRespId`。
+2. `workflow auth-resp variable add` 创建条件需要的变量；条件只能引用已创建变量。变量还必须在某个分支条件里**真正被引用**，否则复用该权责表建流程时它不会进变量映射列表（见 §五）。
+3. 建立发起、结束设置和多个中间审批节点。中间节点统一作为列创建，操作者规则沿用工作流节点操作者规则。
+4. 为每个有效分支填写分支场景说明并创建条件。
+5. 每个分支从已有中间节点中选择自己的路径，通过顺序号表达串行或并行。
+6. `workflow auth-resp save-design --config @design.json` 保存并回读。
+
+从零完整搭建优先使用：
+
+```bash
+e10-cli workflow auth-resp configure <authRespId> --config @auth-resp.json
+```
+
+`auth-resp.json` 使用业务结构描述变量、节点、操作者、分支条件及路径：
+
+```json
+{
+  "baseId": "创建权责表返回的baseId",
+  "name": "合同分级审批权责表",
+  "workflowId": "-99999999",
+  "usage": "workflow",
+  "variables": [
+    { "id": "-自定义稳定ID", "name": "合同金额", "type": "wf_number" }
+  ],
+  "start": { "name": "开始节点", "operator": { "type": "all" } },
+  "end": { "name": "结束节点", "operator": { "type": "initiator" } },
+  "nodes": [
+    { "key": "manager", "name": "部门负责人审批", "type": "approve", "operator": { "type": "user", "keyword": "张三" } },
+    { "key": "finance", "name": "财务审批", "type": "approve", "operator": { "type": "user", "keyword": "李四" } }
+  ],
+  "branches": [
+    {
+      "scenario": "合同金额不超过5万元",
+      "condition": {
+        "relation": "AND",
+        "childrens": [
+          {
+            "selectType": "4",
+            "formField": [{ "id": "-自定义稳定ID", "name": "合同金额", "fieldType": "NumberComponent", "variable": true, "varFirstType": "wf_number" }],
+            "NumberCompareOptionLeft": "4",
+            "NumberValueOptionLeft": "1",
+            "NumberTextValueLeft1": 50000,
+            "elementValue1Id": "",
+            "elementValue2Id": "",
+            "expressionBaseId": "",
+            "dataValueId": ""
+          }
+        ]
+      },
+      "path": [
+        { "node": "manager", "order": 1 },
+        { "node": "finance", "order": 2 }
+      ]
+    }
+  ]
+}
+```
+
+流程内新建权责表时，`workflowId` 写真实流程 ID，条件 `formField` 使用该流程实际表单字段；独立权责表使用 `workflowId=-99999999`，条件引用 `variables` 中的变量。操作者类型直接支持 `all`、`user`、`initiator`；其他已有操作者类型使用 `raw` 并提供平台 `itemDatas`，结构与普通流程操作者一致。
+
+`usage=workflow` 表示完整流转，首尾默认使用发起和结束节点。`usage=fragment` 表示供其他权责表路径引用的中间片段，`start.type` 与 `end.type` 均配置为 `approve`、`confirm` 等中间节点类型；首尾位置不能使用 `start` 或 `end`。
+
+```bash
+e10-cli workflow auth-resp create "合同分级审批权责表"
+e10-cli workflow auth-resp variable add <authRespId> "合同金额" wf_number
+e10-cli workflow auth-resp variable list <authRespId>
+e10-cli workflow auth-resp read <authRespId> --base-id <baseId> > design.json
+e10-cli workflow auth-resp save-design <authRespId> --config @design.json
+```
+
+变量类型码当前已确认：
+
+| 类型码 | 含义 | 补充配置 |
+|---|---|---|
+| `wf_string` | 字符串 | — |
+| `wf_number` | 数值 | — |
+| `wf_select` | 选项 | `--option-template '{"id":"...","name":"..."}'` |
+| `wf_browser` | 浏览 | `--second-type` |
+| `wf_browser_relate` | 关联浏览 | `--relate-browser @browser.json` |
+
+## 三、表格设计结构
+
+`read` 返回的设计以 `columns` 和 `rows` 为核心：
+
+- 固定列：发起设置 `creator`、分支场景说明 `eventColumn`、条件 `condition`、结束设置 `endOperator`。
+- 动态节点列：名称为 `pubNode-<节点ID>`，`pubNodeInfo` 保存节点类型和操作者摘要。
+- 嵌套权责表列：名称为 `pubNode-<权责表sourceId>`，`addMethod=2`，同时保存被引用表的 `baseId` 和版本。
+- 分支行：保存场景说明、`conditionKey`、发起/结束配置及选中的节点单元格。
+- 节点单元格：`nodeInfo` 表示该分支经过此节点；`approveNum` 是执行顺序，相同值表示并行。
+
+每个有效分支必须有非空 `eventColumn` 和 `conditionKey`。界面用于继续录入的空白占位行不进入 CLI 保存数据。
+
+操作者和条件的业务规则与普通工作流一致，具体语法读取 [流程指南](guide-workflow.md) 和 [流程条件指南](guide-workflow-condition.md)。权责表条件的上下文标识由权责表命令负责，不把独立权责表变量当作表单字段创建。
+
+## 四、在分支中引用权责表
+
+先查询当前宿主权责表可以引用的中间型权责表：
+
+```bash
+e10-cli workflow auth-resp reference list <宿主baseId> --name "金额复核"
+```
+
+平台按首尾节点类型过滤可引用项，并排除自身和循环引用。添加时指定被引用权责表的具体版本，以及它出现在哪些分支和对应执行顺序：
+
+```bash
+e10-cli workflow auth-resp reference add <宿主sourceId> --base-id <宿主baseId> --workflow-id <流程ID> --reference @reference.json
+```
+
+```json
+{
+  "id": "被引用权责表sourceId",
+  "name": "金额复核权责表【V1】",
+  "baseId": "被引用权责表baseId",
+  "versionNum": 1,
+  "paths": [
+    { "branch": "金额超过50万元", "order": 2 }
+  ]
+}
+```
+
+相同顺序号表示并行，不同顺序号表示串行。移除引用时，同时删除节点列和各分支中的对应路径单元格：
+
+```bash
+e10-cli workflow auth-resp reference remove <宿主sourceId> <被引用sourceId> --base-id <宿主baseId> --workflow-id <流程ID>
+```
+
+## 五、权责表方式创建流程
+
+权责表是流程的搭建方式，流程表单来源仍按原生工作流程规则选择：自建流程表单、绑定已有流程表单或绑定 EB 表单。基础表单参数写入 `base.json`，其字段与 `workflow create-workflow` 的创建结构一致。
+
+### 随流程新建权责表
+
+```bash
+e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --new-table "合同审批权责表"
+```
+
+服务端在创建流程时生成并返回 `workflowId`、`formId` 和 `newAuthRespId`。这种方式已确定实际表单，分支条件直接选择表单字段，不做变量映射；发起和结束位置直接设置操作者。
+
+### 复用已有权责表
+
+```bash
+e10-cli workflow auth-resp-flow create "合同审批流程" --base @base.json --reuse-table <authRespId> --mappings @mappings.json
+```
+
+也可以对已经创建的流程分步执行：
+
+```bash
+e10-cli workflow auth-resp-flow bind <workflowId> <authRespId>
+e10-cli workflow auth-resp-flow mapping-read <workflowId>
+e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
+```
+
+复用模式把独立权责表变量映射为当前流程表单字段。先用 `mapping-read` 取得平台返回的变量项和可用字段结构，在对应项补全 `fieldBrowser` 后整体保存；变量类型必须与表单字段匹配。
+
+> **前置条件：只有「已被分支条件引用」的变量才会出现在映射列表里。**
+>
+> `mapping-read` 返回的 `variableMappingList` 由平台按「该变量是否被本权责表的条件引用」筛出，未被引用的变量**不会出现**，因而无从映射 —— 列表为空不一定是故障。
+>
+> 自查：`e10-cli workflow auth-resp variable list <authRespId>` 里的 `referred` 字段，为 `false` 的变量不进映射列表。
+>
+> 由此推出搭建顺序：**变量 → 用条件引用它 → 再建/绑流程 → 映射**。反过来（先建流程、后补变量）不会自动补进列表，且 `auth-resp-flow bind` 对已引用过权责表的流程会拒绝重复绑定，只能重建流程。
+
+## 六、已有权责表流程的维护
+
+权责表方式流程的节点、分支条件、流转路径和生成出口统一通过绑定的权责表设计维护：
+
+```bash
+e10-cli workflow auth-resp-flow design-read <workflowId> --auth-resp-id <sourceId> --base-id <baseId> > design.json
+e10-cli workflow auth-resp-flow design-apply <workflowId> --auth-resp-id <sourceId> --config @design.json
+```
+
+权责表设计保存后，平台生成流程节点和出口。流程的出口列表用于查看生成结果及继续配置出口附加能力；改变分支、条件、经过节点和执行顺序时修改权责表设计。
+
+变量映射是独立的流程功能。复用权责表时，将权责表变量映射到当前流程实际表单字段：
+
+```bash
+e10-cli workflow auth-resp-flow mapping-read <workflowId>
+e10-cli workflow auth-resp-flow mapping-save <workflowId> --mappings @mappings.json
+```
+
+映射项保留变量的 `varId`、`varName`、`varType` 和筛选参数，在 `fieldBrowser` 中写入实际字段；变量类型、主表或明细位置应与字段匹配。流程内新建权责表并直接使用表单字段时无需变量映射。
+
+## 七、Plan 记录
+
+流程计划中写清搭建方式、新建或复用的权责表、变量及字段映射、每个分支的场景说明与条件、经过节点和顺序、中间节点类型及操作者。执行时按“表单确定 → 权责表/流程创建 → 变量或字段条件 → 中间节点 → 分支路径 → 映射 → 其他流程设置”的顺序逐项销号。

package/skill-docs/references/workflow/guide-workflow-odoc.md

@@ -58,10 +58,17 @@ e10-cli workflow odoc setting set <workflowId> \
   --request-title-field "公文标题" \
   --upload-word 1 --upload-pdf 1 --upload-ofd 1 \
   --text-in-form 1 --column-position 1 \
-  --attach-area 1 --archive-node "归档"
+  --attach-area 1 --archive-node "归档" \
+  --open-text-select 2 \
+  --edit-text-node "发起节点" \
+  --ai-odoc 1 --ai-abstract 1 --ai-format 1
 ```
 
-字段参数支持字段名称或字段 ID，节点参数支持节点名称或节点 ID。平台开关值使用 `0` 和 `1`。
+字段参数支持字段名称或字段 ID，节点参数支持节点名称或节点 ID（名称在流程内重复时报错并给出候选 ID，不擅自挑一个）。平台开关值使用 `0` 和 `1`。
+
+- `--open-text-select` 默认打开正文节点的范围编码；`--open-text-node` 配合它指定具体节点（可多个，逗号或空格分隔）。
+- `--edit-text-node` 可编辑正文的节点，可多个。
+- `--ai-odoc` 公文助手总开关；`--ai-abstract` 智能摘要、`--ai-format` 智能排版 是它下面的两项，单独打开它们不会自动把总开关带上，需要一并给。
 
 ### 配置结构
 
@@ -74,3 +81,16 @@ e10-cli workflow odoc setting set <workflowId> \
 - AI 与格式：`openAiAbstract`、`openAiFormat`、`defaultFormatTemplate`、`showAiAssistant`、`showOfficialDoc`。
 
 保存请求携带完整公文设置，其中字段选择值为字段 ID、节点选择值为节点 ID，`signNodeList` 保存节点及其启用、必填状态。
+
+**回读的值不能直接写回去。** 平台读回来的形状和保存要的形状不一样，混用会直接被服务端拒掉（`400 Bad Request`）：
+
+| | 读取 | 保存 |
+|---|---|---|
+| 开关 | 布尔 `true` / `false` | 字符串 `"1"` / `"0"` |
+| 基本类型清单 | 数组 `["id1"]` / `[]` | 逗号串 `"id1"` / 空串 `""` |
+| 签章节点表 | 对象数组 | 对象数组，但**每个对象里的布尔同样要转成串** |
+| 节点清单字段（`editTextNode` 等） | 对象数组 `[{name,id}]` | 逗号串 `"id1,id2"` |
+
+分组的落法也分三种：`odocNumber` / `odocAttachArea` **整组保持嵌套**，`signNode` 组以 `signNodeList` 发出，其余分组的键**平铺**到顶层。这些转换由 CLI 自动完成，`--config` 里也按同样规则给值即可。
+
+`setting set` 保存后会**回读比对**，对不上会点名是哪个键没落库 —— 平台对报文形状不合法一律报 400，但对语义问题可能静默收下，读回来才算数。

package/skill-docs/references/workflow/guide-workflow.md

@@ -297,13 +297,28 @@ e10-cli workflow add-link <workflowId> <fromNodeId> <toNodeId> "退回" --reject
 e10-cli workflow add-link <workflowId> <fromNodeId> <toNodeId> "主线路" --default
 ```
 
-批量添加连线：
+批量添加连线（出口表混着退回线和默认出口时用这个）：
 ```bash
 e10-cli workflow add-links <workflowId> @links.json
-# links.json: [{"from":"nodeId","to":"nodeId","label":"发起→审批","reject":true,"default":false}]
+# links.json:
+# [
+#   {"from":"拟稿","to":"套红",       "label":"拟稿 至 套红",       "default":true},
+#   {"from":"部门经理审稿","to":"拟稿", "label":"部门经理审稿 退回 拟稿","reject":true}
+# ]
 ```
 
-> **多条连线用 `add-links`**：`add-link` 内部 fetch→修改→save，并行的会覆盖。`add-links` 按顺序逐条执行，每条都从服务端拉最新 XML 再改，不会丢数据。不要用 `&` 或 `parallel` 并跑 add-link。
+> **退回 / 默认出口逐条给**：`reject` / `default` 写在每条连线上；命令行上的 `--reject` / `--default`
+> 是给整批兜底的默认值，逐条给的值优先于它。
+>
+> **默认出口会自动让位**：指定某条为默认出口时，同一源节点上原有的默认出口会被自动取消，
+> 保证一个源节点只有一条默认出口。同一批里给同一源节点指定了两条默认出口会直接报错，
+> 不会静默留下两条。
+>
+> **多条连线用 `add-links`**：`add-link` 内部 read→改→save，并行的会互相覆盖。`add-links` 一次把整批
+> 拼好、一次保存，不会丢数据。不要用 `&` 或 `parallel` 并跑 add-link。
+>
+> 保存后 CLI 会**回读比对**：新连线的退回/默认标志与让位结果都对得上才算成功，
+> 对不上会直接报错退出，不会因为服务端回了「保存成功」就放过。
 
 ### 删除连线
 
@@ -463,6 +478,13 @@ e10-cli workflow auto-layout <workflowId> --dry-run
 
 **算法**：读 getXml → 按连线最长路径分层（忽略退回线）→ 全量重排节点 mxGeometry → saveLayout 回写 → 回读验证。分支（forkstart→分支们→forkend）自然融入分层，同层节点垂直排开。只改节点坐标，连线自动正交路由。
 
+**什么时候跑**：`create` / `create-workflow` 建流程时自动跑一次，**之后不再自动跑**。所以**加/删节点、加/删连线之后要补跑一次**（`add-node` 只把新节点丢在图的边上，不会融进流程线）。`rename-node` / `set-operator` / 条件与动作配置不改拓扑，不用跑。
+
+两个边界要知道：
+
+- **会覆盖手工摆放**。它是整图重排，人在浏览器里拖过的坐标一律按算法结果重置。手工调过就别再跑，或跑完重新调。
+- **不保证消除交叉**。分层算法只对「跨 ≥2 层的长跳线」把**目标**节点下移一档；跨层连线的水平段仍可能穿过中间层节点。**跑完看一眼流程图**，有交叉只能手工调坐标（或试 `--direction ttb` 换个走线方向）。
+
 ---
 
 ## 相关指南