weaver-e10-builder 1.5.9 → 1.5.11

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

@@ -45,7 +45,8 @@
 | `e10-cli app enable <appId>` | 启用应用。`read` 里的 `publishEnabled`：1=已启用 / 2=已停用 / 0=从未启用 |
 | `e10-cli app disable <appId>` | 停用应用。⚠ **会连带收回已发布到前台的入口** —— 不是「临时关一下、发布态还在」 |
 | `e10-cli app publish <appId> [--name] [--description] [--category]` | 发布到**前台**（应用中心出现入口，地址 `/ebdapp/view/<appId>`）。需先 `enable`。`--category` 取汇报/协作/HRM/审批/数据协作/综合办公/CRM/自定义，缺省「自定义」。⚠ **每次发布生成新的前台 id**，取消后重发不沿用旧号 |
-| `e10-cli app publish-info <appId> [--name] [--description] [--category]` | 改**前台那份**配置（不动应用本身的名称描述，那用 `app edit`）。需先 `publish`；不指定分类则沿用现有 |
+| `e10-cli app publish-info <appId> [--name] [--description] [--category] [--short-name] [--clients pc\|mobile\|all]` | 改**前台那份**配置（不动应用本身的名称描述，那用 `app edit`）。需先 `publish`；不指定分类则沿用现有。**一个编辑项都不给 = 只查看当前发布信息**（打印前台显示名/简称/简介/适用端/使用范围）。`--short-name` 改**简称**（`sysMenus.shortname`，与显示名各自独立；改 `--name` 时若没单独给 `--short-name`，简称跟着走）。`--clients` 改**适用端**（`sysMenus.applyClient`：`pc`=仅PC / `all`=PC+移动 / `mobile`=仅移动端，也认中文） |
+| `e10-cli app range <appId> [--client pc\|mobile] [--add-user <名或ID>] [--add-dept …] [--add-role …] [--add-position …] [--add-all] [--remove <序号\|id>] [--clear]` | 前台应用的**使用范围** —— ⚠ **每一端各自一套**，用 `--client` 选终端（缺省 PC）。**不走 `saveCustomApplication`**，是独立一族 `appmanage/permission/table/{list,batchAdd,delete}`，定位用 `appModuleLink.amId`，终端维度的编码是 `permissionType`（0=PC / 2=移动端）。授权对象支持 人员 / 部门 / 角色 / 岗位 / 所有人 五类，主体写名称或 ID（同名多条报错不取首条）。加/删都**回读校验**（新增行的 id 是平台现分配的，按「类型+名字」核对） |
 | `e10-cli app unpublish <appId>` | 取消发布（收回前台入口）。⚠ **不可逆、无回收站**；重新发布是新入口。回读确认入口确实没了才报成功 |
 | `e10-cli app lang get <appId>` | 查看应用名各语言译文 |
 | `e10-cli app lang set <appId> [--zh] [--en]` | 设置应用名多语言。**简体中文那档就是应用名本身**；只给 `--en` 不会清空中文（内部先读回再整份写回）。改应用名（`app edit --name`）不动多语言配置 |
@@ -76,6 +77,7 @@
 | `e10-cli form delete <objId> <appId>` | 删除**整个表单**（不是字段；删字段用上面的 delete-field） |
 | `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` |
 | `e10-cli form permission <list\|add\|remove\|rebuild> <objId> <appId>` | 权限通用管理及兼容入口。新建权限与数据权限分开；旧 `add --right-type` 保留兼容。`list` 查看全部分类；`remove --right-id <id[,id...]>` 删除一条或多条权限；添加后提示 `isShowRebuild=2` 时执行 `rebuild` |
 | `e10-cli form list-view <objId> <appId>` | 查看台账/数据列表（获取 viewId 用于菜单配置） |
 | `e10-cli form list-columns <objId> <appId> <listId> [--add <fieldId...>] [--remove <fieldId...>] [--set @columns.json] [--terminal pc/mobile] [--pc-only]` | 查看/批量设置台账显示列。增量追加、移除或整组指定顺序/列宽/格式；整组模式与增删互斥。支持主表和明细子字段，保留已有列未指定属性、事件及数据主键；一次保存并回读核对目标列和另一终端。详见 `references/form/guide-list-columns.md` |
@@ -100,8 +102,8 @@
 | `e10-cli form list-event <objId> <appId> <listId> [--add-page '<json>'] [--add-field '<json>'] [--open-mode <模式>] [--modal-width <pct>] [--modal-height <pct>] [--win-size <pct>] [--clear] [--pc-only]` | 查看/配置**行事件**（点击行数据 NewPage 打开表单布局）。`--add-page '{"pageId":"1/<objId>","pageName":"新建数据","openMode":"右侧滑出"}'` 选页面方式（pageId 缺省 `1/<objId>` 新建布局，`0/<objId>`=显示布局）、`--add-field '{"urlFieldId":"字段id"}'` 选字段方式（URL取自行内字段值，urlFieldText/Type自动补）、`--clear` 清空。**打开方式** `--open-mode`（或在 JSON 里写 `openMode`）：当前页面/新窗口/弹出窗口/右侧滑出(缺省)/右侧推出；弹出/滑出/推出 用 `--modal-width`/`--modal-height`（缺省 50%），滑出/推出 用 `--win-size`（缺省 100%）。走 saveNListConfig config.eventGroup（明文 JSON，config+mConfig 都写）。**自动保留移动端配置** |
 | `e10-cli form list-group <objId> <appId> <listId> [--enable --group-field <fieldId> [--group-size N]] [--disable] [--pc-only]` | 查看/配置**启用分组**（台账按某字段分组聚合显示）。`--enable --group-field <分组字段id> [--group-size N 默认100]` 启用/换分组字段、`--disable` 禁用（保留 groupField/groupSize 仅 enable=false）。走 saveNListConfig config.enableGroup（对象，持久化，不走 layout/save LZW）。**自动保留移动端配置** |
 | `e10-cli form list-hierarchy <objId> <appId> <listId> [--enable --parent-field <名称或fieldId> [--expand-level N]] [--disable] [--pc-only]` | 查看/配置**上下级树形展示**。上级字段必须是主表中单选、关联当前表单自身的 EBuilder 字段（常见名称“上级类型”）；与普通 `list-group` 分组聚合不是同一能力。走 `saveNListConfig config.superiorField`，保存后独立回读并自动保留移动端配置 |
-| `e10-cli form list-permission <objId> <appId> <listId> [--add-all] [--add-user <userId> --name <name>] [--add-role <roleId> [--name <name>]] [--add-matrix <矩阵id> --name <name>] [--share-level <n>] [--seclevel <min>-<max>] [--add-raw '<json>'] [--remove <id>] [--remove-all] [--clear]` | 查看/配置**台账视图权限**（谁能查看这个台账）。`--add-all` 所有人（自动把空 dataid 与 0 视为同一主体，避免重复）、`--add-user` 人员、`--add-role` 角色、`--add-matrix` 矩阵。`--remove <id>` 删除指定权限；`--remove-all` 删除全部“所有人”，与 `--add-all` 同用可清理重复后只保留一条；`--clear` 清空全部。保存走 `list/permission/save` 全量覆盖并回读。另支持共享级别和安全级别范围 |
-| `e10-cli form list-search-group <objId> <appId> <listId> [--add <字段名或fieldId>] [--position 0\|1] [--option-order default\|field] [--no-show-count] [--date-granularity <列表>] [--options <列表>] [--default-options <列表>] [--remove <fieldId>] [--clear] [--pc-only]` | 查看/配置**分类搜索**（台账顶部/下拉的分类筛选）。`--add` 收**字段名或 fieldId**，已在里面则按本次参数**重建那条**（改配置走它）。支持四类：**选项类**(Select/RadioBox/CheckBox)、**浏览框类**(Ebuilder/Browser/Employee/Department)、**日期类**(DateComponent)、**系统字段**(创建者/数据ID 这类)。`--position` 1=顶部(缺省)/0=下拉样式；`--option-order` 浏览框的选项排序（default 默认排序 / field 按字段属性设置）；`--no-show-count` 关掉统计数字；`--date-granularity` 日期粒度（全年/半年/季度/月，缺省全要）；`--options` / `--default-options` 控制选项类**哪些选项出现 / 哪些默认选中**。**仅主表字段，不支持明细（产品边界，传明细报错）**。走 saveNListConfig `config.searchConditions.groupFilters`（视图级明文） |
+| `e10-cli form list-permission <objId> <appId> <listId> [--add-all] [--add-user <userId> --name <name>] [--add-role <roleId> [--name <name>]] [--add-matrix <矩阵id> --name <name>] [--share-level <n>] [--seclevel <min>-<max>] [--add-raw '<json>'] [--remove <id>] [--remove-all] [--clear]` | 查看/配置**台账视图权限**（谁能查看这个台账）。`--add-all` 所有人（自动把空 dataid 与 0 视为同一主体，避免重复）、`--add-user` 人员、`--add-role` 角色、`--add-matrix` 矩阵（同 `form permission archive` 的矩阵条件参数：`--matrix-condition` / `--matrix-condition-relation` / `--matrix-condition-comp-type` / `--matrix-condition-raw`）。`--remove <id>` 删除指定权限；`--remove-all` 删除全部“所有人”，与 `--add-all` 同用可清理重复后只保留一条；`--clear` 清空全部。保存走 `list/permission/save` 全量覆盖并回读。另支持共享级别和安全级别范围 |
+| `e10-cli form list-search-group <objId> <appId> <listId> [--add <字段名或fieldId>] [--position 0\|1] [--option-order default\|field] [--no-show-count] [--count-update] [--only-with-data] [--date-granularity <列表>] [--default-group <粒度> --default-value <起,止>] [--options <列表>] [--default-options <列表>] [--remove <fieldId>] [--clear] [--pc-only]` | 查看/配置**分类搜索**（台账顶部/下拉的分类筛选）。`--add` 收**字段名或 fieldId**，已在里面则按本次参数**重建那条**（改配置走它）—— 本次没给的选项一律回到缺省，所以只改一项时要把想留着的一起给全。支持四类：**选项类**(Select/RadioBox/CheckBox)、**浏览框类**(Ebuilder/Browser/Employee/Department)、**日期类**(DateComponent)、**系统字段**(创建者/数据ID 这类)。`--position` 1=顶部(缺省)/0=下拉样式；`--option-order` 浏览框的选项排序（default 默认排序 / field 按字段属性设置）；`--no-show-count` 关掉统计数字，`--count-update` 让统计数字**随搜索结果更新**（选项/浏览框/日期可用，缺省只在进入台账时统计一次）；`--only-with-data` **仅显示有数据的选项**（**只有**选项/浏览框类有这个键，日期与系统字段用不了；这个键**勾上才出现**，不勾整个键都没有）；`--date-granularity` 日期粒度（全年/半年/季度/月，缺省全要）；`--options` / `--default-options` 控制选项类**哪些选项出现 / 哪些默认选中**。日期类的**默认值**用 `--default-group <粒度>` + `--default-value "起,止"`（两个**必须一起给**；平台存的是一条 `{value,group}` 的默认值，并把它对应的粒度标成默认勾上）。**仅主表字段，不支持明细（产品边界，传明细报错）**。走 saveNListConfig `config.searchConditions.groupFilters`（视图级明文） |
 | `e10-cli form nlist apply <objId> <appId> <listId> <template>` | 配置**列表式视图**（台账）的显示列：模板是二维数组（行 → 列），列项可绑表单字段（`fieldId`）或做**自定义文本**列（不给 `fieldId`、给 `html`，里面用 `{{字段名}}` 插入表单字段）。自动读移动端槽位一并写入。`show` 查看当前配置。⚠ 仅对列表式(NList)生效，表格式用 `form table-view`。详见 `form/guide-list-custom-text.md` |
 | `e10-cli form view list <objId> <appId> [--with-comps]` | 列出表单全部视图。`--with-comps` 额外拉每个视图布局 comps 数、标出空视图（NList 数据视图会显示「读取失败」，正常） |
 | `e10-cli form view rename <objId> <appId> <viewId> <新名称>` | 修改视图名称并回读。**表单视图与台账各走一条接口**（台账走 `viewlist/buttonEvent` 的编辑动作，其余视图走 `layout/rename`），命令按类型自动选。保留原视图 ID 和配置。需求名称与默认名称不一致时统一用此命令，不新建重复视图 |
@@ -132,8 +134,11 @@
 | 命令 | 说明 |
 |------|------|
 | `e10-cli form button list <objId> <appId>` | 列出所有按钮 |
-| `e10-cli form button add <objId> <appId> <name> [--url <url>\|--open-view <视图>\|--open-layout <表单>\|--start-workflow <流程>] [--layout-type 新建\|编辑\|显示] [--map "目标字段:来源字段"...] [--target-app <appId>] --view <来源视图> --position <位置...>` | 添加通用打开页面按钮。支持固定 URL、平台视图、表单布局及流程快捷入口。`--map` 把当前行的来源字段传出去，可多项，但**两种动作的写法不同**：视图/布局/流程动作写 `"目标字段:来源字段"`，**URL 动作写 `"参数名:来源字段"`**（参数名会成为目标 URL 的查询键）。⚠ **URL 动作的页面类型缺省 `LINK`**（平台设计器对 URL 路径用的就是这个；`CUSTOMPAGE` 是「自定义页面」，`pageId` 要页面 id，装 URL 路径点不开）。⚠ **平台不认 URL 里的 `{字段}` 占位符**，传参只能用 `--map`。当前行映射只允许行上/行末下拉；右上按钮无单行上下文。目标名称不唯一时使用 ID，保存后回读动作和映射 |
-| `e10-cli form button action-set <objId> <appId> <buttonId> [--open-view ...\|--open-layout ...\|--start-workflow ...] [--map ...]` | 更新已有自定义按钮的单一 `openpage` 动作，保留按钮位置和权限；适合修正目标页面或动态字段映射，避免重复创建同名按钮 |
+| `e10-cli form button add <objId> <appId> <name> [--url <url>\|--open-view <视图>\|--open-layout <表单>\|--start-workflow <流程>] [--layout-type 新建\|编辑\|显示] [--map "目标字段:来源字段"...] [--target-app <appId>] --view <来源视图> --position <位置...>` | 添加通用打开页面按钮。支持固定 URL、平台视图、表单布局及流程快捷入口。`--map` 把当前行的来源字段传出去，可多项，但**两种动作的写法不同**：视图/布局/流程动作写 `"目标字段:来源字段"`，**URL 动作写 `"参数名:来源字段"`**（参数名会成为目标 URL 的查询键）。⚠ **URL 动作的页面类型缺省 `LINK`**（平台设计器对 URL 路径用的就是这个；`CUSTOMPAGE` 是「自定义页面」，`pageId` 要页面 id，装 URL 路径点不开）。⚠ **平台不认 URL 里的 `{字段}` 占位符**，传参只能用 `--map`。当前行映射只允许行上/行末下拉；右上按钮无单行上下文。目标名称不唯一时使用 ID，保存后回读动作和映射。建按钮时还可一次带上基础属性：`--tips` / `--desc` / `--icon`（配 `--icon-color` / `--icon-bg` / `--icon-display`）/ `--only-icon` / `--no-log` / `--log-message` / `--data-filter` |
+| `e10-cli form button set <objId> <appId> <buttonId> [--name <名称>] [--tips <文本>] [--desc <文本>] [--icon <图标名> --icon-color <色值> --icon-bg <色值> --icon-display <line\|fill>] [--icon-none] [--only-icon\|--no-only-icon] [--log\|--no-log] [--log-message <文本>] [--add\|--replace\|--remove\|--relation\|--clear-filter] [--disable-condition\|--clear-disable-condition] [--dry-run]` | 改按钮基础属性：名称 / 提示内容 / 备注 / 图标 / 点击日志 / 数据过滤 / 禁用条件。**已有的动作与权限原样保留**。数据过滤的 `--add/--replace/--remove/--relation` 与 `form list-filter` 同名同义；启用时开关自动置 1，`--clear-filter` 置回 0。详见 `references/form/guide-form-button.md` |
+| `e10-cli form button permission <objId> <appId> <buttonId> [--add-all\|--add-company <名或ID>\|--add-department <名或ID>\|--add-people <名或ID>] [--contain-extra] [--remove <序号\|id>] [--clear]` | 配置按钮权限（**哪些人能看见并点击这个按钮**，与表单共享权限是两套），不带选项时列出。授权对象支持 全体 / 分部 / 部门 / 人员；主体可写名称或 ID，名称需精确同名（撞名报错并列候选）。`--contain-extra` 含下级。保存后按集合回读核对（平台会重排顺序） |
+| `e10-cli form button action <objId> <appId> <buttonId> [--add-url <url>\|--add-view <视图>\|--add-layout <表单>\|--add-start-workflow <流程>\|--add-confirm ...\|--add-js --code <源码\|@文件>\|--add-edit-field "字段:值"...\|--add-logic <逻辑流>] [--remove <序号\|id>] [--clear]` | 管按钮动作，**一个按钮可挂多个**；不带选项时列出。追加顺序固定为 打开页面 → 确认框 → JavaScript → 编辑字段值 → 触发逻辑流。`--add-edit-field` 只支持赋固定值，同字段后写覆盖先写。`--add-logic` 只绑现有逻辑流（按名称精确匹配），`--logic-ecode-id` 可指定 `ecodeId`。改动作时权限原样保留。详见 `references/form/guide-form-button.md` |
+| `e10-cli form button action-set <objId> <appId> <buttonId> [--open-view ...\|--open-layout ...\|--start-workflow ...] [--map ...]` | **已废弃**，改用 `form button action`（等价 `--clear` + 一个 `--add-*`）。更新已有自定义按钮的单一 `openpage` 动作，保留按钮位置和权限 |
 | `e10-cli form button toggle <objId> <appId> <buttonId>` | 启用/禁用按钮 |
 | `e10-cli form button position <objId> <appId> <buttonId> [--view <视图...> --position <位置...>] [--show-position <json或@文件>] [--replace]` | 设置已有按钮位置并回读验证。默认合并、保留未指定页面；`--replace` 全量替换。视图支持 ID/唯一名称/新建/编辑/显示；多台账不能省略具体视图。系统按钮适用，保留动作权限及返回的日志/提示配置。详见 `references/form/guide-form-button.md` |
 | `e10-cli form button views <objId> <appId> <buttonId>` | 读取该按钮可选视图及当前 showPosition，配置前先查询 |
@@ -142,6 +147,7 @@
 | `e10-cli form association fields <objId> <appId> --view <viewId> [--target-app <id>]` | 查询来源表单字段和目标视图字段 |
 | `e10-cli form association create <objId> <appId> <name> --view <viewId> --permissions <json或@文件> [--layouts 显示 编辑] [--terminals PC MOBILE] [--mappings <json或@文件>]` | 创建关联页签；默认仅显示布局、PC+MOBILE、启用。权限必须显式提供，筛选映射为 [{targetField,sourceField}] |
 | `e10-cli form association update <objId> <appId> <associationId> [--name <名>] [--view <viewId>] [--layouts 显示 新建 编辑] [--terminals PC MOBILE] [--enabled true/false] [--mappings <json或@文件>]` | 保留未指定配置；布局和终端为集合替换；显示=0，新建=1，编辑=2，none 关闭全部布局。仅启停走独立接口并回读；多动作时传 --action |
+| `e10-cli form association delete <objId> <appId> <associationId>` | 删除关联页签，参数可为 ID 或**唯一**名称（同名多条报错并列 ID）；删前确认归属、删后回读确认消失。不可撤销、无回收站；只想临时下线用 `update --enabled false` |
 | `e10-cli form association set-filter <objId> <appId> <associationId> --mappings <json或@文件> [--action <id>]` | 替换目标视图动作的数据筛选字段映射，区别于权限条件 |
 | `e10-cli form association clear-filter <objId> <appId> <associationId> [--action <id>]` | 清空指定视图动作的数据筛选映射 |
 | `e10-cli form association set-condition <objId> <appId> <associationId> --perm <序号或类型> --rules <json或@文件> [--logic and/or]` | 设置页签权限条件，来源表单字段；与关联目标视图数据筛选独立 |
@@ -159,10 +165,10 @@
 | `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 formula-linkage list <appId> <objId>` | 函数联动（**本表**字段间公式赋值，`linkageType=excel`）：列出 |
 | `e10-cli form formula-linkage read <appId> <objId> <id>` | 回读单条（含公式表达式与参数） |
-| `e10-cli form formula-linkage events <appId> <objId>` | 列出可用的触发事件（值改变时 / 载入时 / 创建数据时 …） |
+| `e10-cli form formula-linkage events <appId> <objId> [--effect <维度>]` | 列出可用的触发事件。默认 10 个（字段组 5 + 表单组 5）；生效维度给 `workFlow`/`includeNode` 时取**流程**那套 = 17 个（多「提交/批准时、转发时、保存时、退回时、转办时、意见征询时、传阅时」7 个） |
 | `e10-cli form formula-linkage columns <appId> <objId>` | 列出可引用/可触发的字段（业务字段 / 系统模块字段分两桶） |
-| `e10-cli form formula-linkage add <appId> <objId> --target <字段> --expression <函数体>` | 新增函数联动。`--event`（默认 `changeField`）、`--trigger <字段...>`（字段级事件必填）、`--effect form\|formLayout`（生效维度，默认当前表单）、`--name`。表达式**只给右侧**，左侧 `{主表.目标}=` 自动拼。**目标只能是业务字段**，模块字段可作来源/触发。详见 `form/guide-formula-linkage.md` |
-| `e10-cli form formula-linkage update <appId> <objId> <id> [--event] [--trigger] [--effect] [--name] [--state on\|off]` | 改触发条件/生效维度/名称/启停。不传则沿用现有 |
+| `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 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` |
 
@@ -219,10 +225,10 @@
 | `e10-cli wf-form delete-field <formId> <fieldId...> [--force]` | 删除流程表单字段（可批量）。**仍被布局引用的字段平台拒删**；`--force` 让 CLI 先从布局摘掉这些字段的组件（含它的标题标签）再删。eb 表侧对应 `form delete-field` |
 | `e10-cli wf-form formula set <formId> --expression "DAYS({主表.开始时间},{主表.结束时间})" --target <fieldId>` | 给流程表单字段绑定计算公式。`{主表.字段}`/`{明细表名.字段}` 引用（getConfig 解析）→ `/api/excel/formula/save`(module=workflow) → ffExpress 绑字段 + saveSourceForm。`--name`/`--return-type`/**`--formula-id <id>`（原地更新已有公式，不新建）**。另：`formula get <id>` / `list <formId>` / `functions`。**⚠ 公式语法四条**：函数名必须大写（自定义 JS 脚本函数除外）、逻辑比较用 `==`、给字段赋值用 `=`、跨表粘贴要换掉非本表字段变量 —— 写错不报错只是算不对，见 `references/form/guide-form-formula-functions.md` |
 | `e10-cli wf-form formula-linkage list <formId> --workflow-id <id>` | 流程表单的**函数联动**（`linkageType=excel`，走 `/api/ebuilder/flow/form/linkage`，module=`ebuildercard`）。`read` / `delete <ids...>` 同形 |
-| `e10-cli wf-form formula-linkage events <formId> --workflow-id <id>` | 列出触发事件（**17 个**：字段组 5 + 表单组 5 + 流程组 7） |
+| `e10-cli wf-form formula-linkage events <formId> --workflow-id <id>` | 列出触发事件（**17 个**：字段组 5 + 表单组 5 + 流程组 7）。这条路由恒取流程那套 |
 | `e10-cli wf-form formula-linkage columns <formId> --workflow-id <id>` | 列出可引用/可触发的字段，按「可作 / 不可作赋值目标」分桶。字段清单取自 `findFormDrivingColumns`，**不依赖 getFormLayout**（后者在部分流程表单上会 500） |
-| `e10-cli wf-form formula-linkage add <formId> --workflow-id <id> --target <字段> --expression <函数体>` | 新增。`--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]` | 改触发条件/生效维度/名称/启停。不传的项沿用现有 |
+| `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 relate <formId> <目标字段> --from <Employee/Department源字段> [--key email/department/code/name] [--title <名>]` | 值带出：换表内 Employee/Department 字段自动填目标字段（HRM 属性带出）。`--key` 默认 Employee=department/Department=name。机制同 eb 表（ffRelateField，Employee 源 module=hrm） |
@@ -239,7 +245,7 @@
 | `e10-cli workflow info <workflowId>` | 单个流程的基础信息 + **它关联的表单**（流程 → 表单反查）。给出 `formId`、表单名、启用状态、是 eb 表还是流程表单。⚠ **formId 不是 objId**，表单类命令要 objId，而平台没有直通的 formId → objId 接口 —— 得先确认表单在哪个应用下再按 formId 匹配 |
 | `e10-cli workflow nodes <workflowId>` | 查看流程节点详情（名称、类型、操作者、连线含 linkId） |
 | `e10-cli workflow nodes <wf> --mode list` | 列表视图：展示全节点含 nodeAttr、合流方式（比 chart XML 更全） |
-| `e10-cli workflow set-operator <wf> <node> [keyword]` | 设置节点操作者。`--type user`(指定人) / `role`(指定角色) / `dept`(指定部门) / `position`(指定岗位) / `all`(所有人) / `free`(自由选择) / `superior`(发起人上级) / `initiator`(流程发起人本人) / `prev-node`(上一节点) / `form`(表单相关人员) / `matrix`(矩阵对应,需 `--matrix-id` `--value-config-id` `--matrix-rule`)。`--sign-order` 会签/非会签/竞签/依次处理/抄送/抄送需批注（概念见 guide-workflow）；**`--type form` 另支持「或签」**，等价于竞签（表单字段里多人任一人签，语义一致），已登记的签署顺序里没有单独一档。**依次处理倒序**用 `--execute-order 2-2`(默认)/`2-1`正序/`1-1,2-2`安全级别正序+倒序。**`--dept-scope 本部门`**=单个部门内会签/`本及下级`默认。**一个节点多人用逗号分隔 keyword**（如 `"区域经理,部门领导"`，user/dept 都支持）；默认每次全量重建操作者组（先清空再新建），重复设置不堆积。**多操作者组叠加（如「部门领导矩阵 + 门店经理矩阵」双组会签）：先用 set-operator 配第一组，再用 `--append` 配第二组**，`--append` 不清空已有组，两组合起来就是双矩阵会签 |
+| `e10-cli workflow set-operator <wf> <node> [keyword]` | 设置节点操作者。`--type user`(指定人) / `role`(指定角色) / `dept`(指定部门) / `position`(指定岗位) / `all`(所有人) / `free`(自由选择) / `superior`(发起人上级) / `initiator`(流程发起人本人) / `prev-node`(上一节点) / `form`(表单相关人员) / `matrix`(矩阵对应,需 `--matrix-id` `--value-config-id`；条件用 `--matrix-rule` 或 `--matrix-rules JSON/@文件`，互斥；支持部门/分部系统来源、表单字段与指定组织，详见 guide-workflow)。`--sign-order` 会签/非会签/竞签/依次处理/抄送/抄送需批注（概念见 guide-workflow）；**`--type form` 另支持「或签」**，等价于竞签（表单字段里多人任一人签，语义一致），已登记的签署顺序里没有单独一档。**依次处理倒序**用 `--execute-order 2-2`(默认)/`2-1`正序/`1-1,2-2`安全级别正序+倒序。**`--dept-scope 本部门`**=单个部门内会签/`本及下级`默认。**一个节点多人用逗号分隔 keyword**（如 `"区域经理,部门领导"`，user/dept 都支持）；默认每次全量重建操作者组（先清空再新建），重复设置不堆积。**多操作者组叠加（如「部门领导矩阵 + 门店经理矩阵」双组会签）：先用 set-operator 配第一组，再用 `--append` 配第二组**，`--append` 不清空已有组，两组合起来就是双矩阵会签 |
 | `e10-cli workflow generate-link-id <wf>` | 生成新连线 ID |
 | `e10-cli workflow add-node <wf> <type> <name>` | 添加节点（列表 API）。`<type>`: 0=发起 1=审批 2=确认 3=归档 5=投递 7=自动处理 8=等待 / forkstart/forkend/forkmiddle。**结束节点=归档节点（type=3）**。`--node-attr` 节点属性；合流点支持 `--merge-type`（0=全部/1=指定/2=数量/3=比例）、`--merge-num`、`--branch-nodes` |
 | `e10-cli workflow rename-node <wf> <nodeId> <name>` | 重命名节点（saveNodeSetForm API） |
@@ -285,7 +291,7 @@
 | `e10-cli workflow node timeout <wf> <nodeId>` | ⚠ **已弃用**，请改用 `workflow node-overtime`。旧命令的超时时长与提醒字段名平台不认（时长恒为 0、提醒直接报错），且配不了退回/提交目标节点 |
 | `e10-cli workflow node field-permission get <wf> <nodeId>` | 查看节点字段权限（各字段 显示/隐藏）。表单字段在节点上可见与否 |
 | `e10-cli workflow node field-permission set <wf> <nodeId> --hide <字段...>` | 设置节点字段显示/隐藏。`--hide 字段名/ID` 隐藏、`--show` 显示；可多个，已设权限则更新、未设则新建 |
-| `e10-cli workflow node sign <wf> <nodeId>` | 节点签字意见必填（退回时必填意见等）。缺省查看；`--all-required` 全部必填、`--none-required` 全部不必填、`--select "退回,加签"` 指定操作类型必填（按 mustInputDto=2 + 选中操作类型 id）。`getSignConfigForm` 枚举操作类型 |
+| `e10-cli workflow node sign <wf> <nodeId>` | 全部签字意见设置；旧必填参数保留，`--data JSON/@文件` 局部修改签批签名、隐藏输入框/区域、显示类型/范围、反馈；`--schema` 字段定义，`--options` 查询完整候选。先读后改并回读 |
 | `e10-cli workflow node empty-handle get <wf> <nodeId>` | 查看节点**流程异常处理**（无可处理人时怎么办） |
 | `e10-cli workflow node empty-handle set <wf> <nodeId> --handle-way <1-5>` | 设置节点流程异常处理：1=指定人员(`--person 名称/ID`) / 2=用户指定 / 3=发起人 / 4=自动流转下一节点 / 5=提交指定节点(`--assign-node <节点ID>`)；`--off` 关闭；`--sync` 同步所有节点 |
 | `e10-cli workflow setting title <wf>` | 流程标题规则（发起后标题按规则生成，如"发起人-提交日期-客户名称"→真实数据）。缺省列出可用变量（发起人/部门/日期/表单字段）；`--rule "发起人\|提交日期\|客户名称"` 竖线分隔字段名设置；`--sep <分隔符>` 默认 `-`；`--disable` 关闭自动生成（标题回退流程名+系统默认）。占位符 `$code$`，平台发起时替换为真实值 |
@@ -334,10 +340,16 @@
 | `e10-cli workflow segment embed <wf> <segmentId> [--x <n>] [--y <n>]` | 在主流程里插入**公用流转节点**（引用指定片段，自动拼 group + 子节点 XML 并入主流程图）。`--sub-company-id` 用于查片段名 |
 | `e10-cli workflow sub-process list <wf> <nodeId>` | 列出节点上全部子流程配置 |
 | `e10-cli workflow sub-process get <wf> <nodeId> <subSetId>` | 查看子流程配置详情（主配置 + detailSet + 触发条件） |
-| `e10-cli workflow sub-process set <wf> <nodeId> --sub-wf <子流程ID> [--name <配置名>] [--id <subSetId>]` | 新建/更新子流程主配置（**不传 `--id` 新建，传了则读-改-写**）。`--enable`/`--disable`（默认停用）、`--tri-once` 只触发一次、`--tri-source <主表objId>`、`--time-day`/`--time-hour`/`--time-minute` 延时 |
-| `e10-cli workflow sub-process set-condition <wf> <nodeId> <subSetId> --rule "..." [--relation AND\|OR]` | 设置子流程触发条件（复用条件构建器，`--rule` 语法同 `workflow condition add`），并回填到主配置 |
-| `e10-cli workflow sub-process set-mapping <wf> --sub-wf <子流程ID> --map 源字段:目标字段[:名] [--field-mapping-id <id>]` | 设置主→子字段映射（`--map` 可多个；不传 `--field-mapping-id` 则新建） |
-| `e10-cli workflow sub-process set-detail <wf> <nodeId> <subSetId> [选项]` | 更新明细设置（创建人 / 读意见等，读-改-写）。`--creator <类型:字段ID>`、`--del-old-sub-request 0\|1`、`--read-main`/`--read-paralle`/`--read-sub`、`--auto-show 0\|1`、`--init-default-val` |
+| `e10-cli workflow sub-process set <wf> <nodeId> --sub-wf <子流程ID> --name <配置名> [--id <subSetId>]` | 新建/更新子流程主配置（不传 `--id` 新建，传了则读-改-写）。主表触发用 `--tri-source-type MAIN --tri-source <主表objId>`；按明细触发用 `--tri-source-type DETAIL --tri-source <明细表subFormId>`。`--tri-time LEAVE_NODE\|ARRIVE_NODE` 指定离开/到达节点；`--tri-operation LAST_NODE_APPRIVE\|LAST_NODE_REJECT` 与 `--tri-operation2 APPRIVE\|REJECT` 成对设置上一节点操作，明细触发缺省为批准。`--tri-moment DELAY --time-day/--time-hour/--time-minute` 配置固定延迟；`--split-detail TRI_DATA\|ALL_DATA` 指定触发明细赋值方式。`--enable`/`--disable` 通过独立状态接口设置；保存后回读核对 |
+| `e10-cli workflow sub-process set-condition <wf> <nodeId> <subSetId> --rule "..." [--relation AND\|OR]` | 设置子流程触发条件并回填主配置；明细字段用 `form:<字段ID>:<操作>:<值>[:任一\|所有]`，例如 `form:123:等于:测试:任一`。条件是否满足与是否按每条明细发起是两项独立设置 |
+| `e10-cli workflow sub-process set-mapping <wf> --sub-wf <子流程ID> --map 源字段:目标字段[:名] [--field-mapping-id <id>]` | 设置主→子字段映射（`--map` 可多个；不传 `--field-mapping-id` 则新建）。明细触发时加 `--detail-source <明细表subFormId>`，将明细来源写入映射上下文 |
+| `e10-cli workflow sub-process set-detail <wf> <nodeId> <subSetId> [选项]` | 更新默认子流程的创建人、读意见与字段映射关联，按普通子流程或按字段路由自动选择保存接口，并读回映射。先用 `set-mapping` 保存映射，取得 `fieldMappingId`，再传 `--data-rule-id <fieldMappingId>`；其他选项有 `--creator <类型:字段ID>`、`--del-old-sub-request 0\|1`、`--read-main`/`--read-paralle`/`--read-sub`、`--auto-show 0\|1`、`--init-default-val` |
+| `e10-cli workflow sub-process set <wf> <nodeId> --name <名> --diff-wf --tri-source-type DETAIL --tri-source <明细表ID> --diff-field-id <区分字段ID>` | 创建“按字段触发不同子流程”的主设置；不在主设置指定唯一 `--sub-wf`，后续分别设置默认子流程和匹配值路由。修改触发节点时同时更新 `triNodeId` 和 `multiTriNodeId` |
+| `e10-cli workflow sub-process diff-route list <wf> <nodeId> <subSetId>` | 读取区分字段、默认子流程及全部路由 ID、匹配值和目标子流程 |
+| `e10-cli workflow sub-process diff-route default <wf> <nodeId> <subSetId> --sub-wf <id>` | 设置未命中匹配值时的默认子流程（`diffFieldValue=-1`） |
+| `e10-cli workflow sub-process diff-route add <wf> <nodeId> <subSetId> --values <值ID[,值ID...]> --sub-wf <id> [--default-sub-wf <id>]` | 新增一条匹配值路由；值传浏览器选项 ID，多个逗号分隔。首条路由需同时传 `--default-sub-wf`，整表保存后读回 |
+| `e10-cli workflow sub-process diff-route update <wf> <nodeId> <subSetId> <routeId> [--values <值ID[,值ID...]>] [--sub-wf <id>]` | 保留路由 ID 原位修改匹配值和/或目标子流程，保存后读回 |
+| `e10-cli workflow sub-process diff-route delete <wf> <nodeId> <subSetId> <routeId>` | 删除路由行，不删除目标子流程；删除后读回确认 |
 | `e10-cli workflow sub-process delete <wf> <subSetId>` | 删除子流程配置（连同 detailSet 一并删） |
 | `e10-cli workflow message create <wf> <nodeId> <名称> [选项]` | 创建**消息提醒动作流**并绑定到流程节点。`--title`、`--content`、`--recipients <用户ID>`（缺省流程发起人）、`--channel im\|yunqiao\|email\|sms`、`--event arrive\|leave\|delete\|save\|revert\|pause\|cancel`（触发时机）、`--node-name` |
 
@@ -358,11 +370,13 @@
 
 | 命令 | 说明 |
 |------|------|
-| `e10-cli menu list <appId>` | 列出当前Ebuilder应用下的菜单。**递归展开嵌套菜单**（如「设置 → 个人设置 → 个人菜单设置」），列表即全量 —— 在这里没找到就是真没有，不必再怀疑被折叠 |
+| `e10-cli menu list <appId>` | 列出当前Ebuilder应用下的菜单。**递归展开嵌套菜单**（如「设置 → 个人设置 → 个人菜单设置」），列表即全量 —— 在这里没找到就是真没有，不必再怀疑被折叠。`--raw [菜单ID]` 打印菜单的**原始报文**（读侧记录与写侧报文形状不同，核对某一项到底存了什么时看它） |
 | `e10-cli menu rename <appId> <菜单ID或名称> <新名>` | 重命名已有菜单（含嵌套菜单）。名称在应用内重复时必须改用 ID，命令会列出候选让你选。平台系统菜单（回收站/设置等）不能改 |
-| `e10-cli menu add <name> <path> <appId>` | 将页面加入左侧导航（LINK 类型，URL path）。ecode 页面 path 如 `/sp/custom/ecode/project-list`。**表单台账/流程发起菜单用下面两条专用命令**（VIEWPORT/LAYOUT 类型，非 URL）。**建完会回读确认**并报出菜单 ID；回读不到就报错退出，不谎报成功 |
-| `e10-cli menu add-table <appId> <objId> [name]` | 给表单加**台账菜单**（VIEWPORT，指向数据列表页）。`form create --menu` 才自动加（默认不加），此处用于事后补加。**建完回读确认** |
-| `e10-cli menu add-start <appId> <formObjId> [name]` | 给流程绑定的表单加**发起菜单**（LAYOUT，指向表单新建页，点开触发流程）。`workflow create --menu` 才自动加（默认不加）。**建完回读确认** |
+| `e10-cli menu add <name> <path> <appId> [--parent <父菜单ID或名称>]` | 将页面加入左侧导航（LINK 类型，URL path）。ecode 页面 path 如 `/sp/custom/ecode/project-list`。**表单台账/流程发起菜单用下面两条专用命令**（VIEWPORT/LAYOUT 类型，非 URL）。`--parent` 挂到父菜单下做子菜单（缺省 `0`=顶级）。**建完会回读确认**并报出菜单 ID；回读不到就报错退出，不谎报成功 |
+| `e10-cli menu add-dir <appId> <name> [--parent <父菜单ID或名称>]` | 加**上级目录**菜单 —— **空链接**的纯分类节点，只用来给子菜单分组，点它不跳页面。设计器里建「上级目录」就是这个（存下来 `pageType=EMPTY`、`pageId/pageName` 空、**没有 `menuUrl`**、`menuType="0"`）。`--parent` 支持菜单 ID 或名称（缺省 `0`=顶级）。**建完回读确认**并核对层级，另外**核对 `pageType` 确实是 `EMPTY`** —— 不是就说明链接没留空，直接报错而不是谎报成功。⚠ 与 `menu add` 的区别：要指向某个页面的父菜单（点得开）用 `menu add`，纯分组的用这条 |
+| `e10-cli menu add-table <appId> <objId> [name] [--parent <父菜单ID或名称>]` | 给表单加**台账菜单**（VIEWPORT，指向数据列表页）。`form create --menu` 才自动加（默认不加），此处用于事后补加。**`--parent` 挂到某个父菜单下做子菜单**（缺省 `0`=顶级；既收菜单 ID 也收名称，同名多条会报错并列 ID）。**建完回读确认**，并**核对层级** —— 只确认菜单存在不够，`pid` 没生效时菜单照样建出来、只是跑到顶级 |
+| `e10-cli menu add-start <appId> <formObjId> [name] [--parent <父菜单ID或名称>]` | 给流程绑定的表单加**发起菜单**（LAYOUT，指向表单新建页，点开触发流程）。`workflow create --menu` 才自动加（默认不加）。`--parent` 同上（子菜单）。**建完回读确认**并核对层级 |
+| ↳ 搭「父菜单 + 子菜单」 | 设计器里的二级菜单 = 先建父菜单（**纯分组用 `menu add-dir`**；父菜单自己也要指向某页才用 `menu add`），再把台账/发起菜单用 `--parent <父菜单>` 挂上去。父菜单 ID 从 `menu list` 拿（输出就是完整菜单树） |
 | `e10-cli menu permission list <appId> <menuId>` | 列菜单可见范围授权（**默认所有人**；无输出=全可见） |
 | `e10-cli menu permission add <appId> <menuId> <目标> --type role\|dept\|user\|all` | 给菜单授权。默认语义：**加角色/人/部门后自动撤「所有人」→ 只有授权对象可见**；`--keep-all` 保留所有人；`--type all` 恢复"所有人可见" |
 | `e10-cli menu permission remove <appId> <menuId> <目标> --type role\|dept\|user\|all` | 撤销菜单授权（撤销所有人用 `--type all`） |
@@ -390,11 +404,11 @@
 | `e10-cli designer comp-remove <pageId> <compId>` | 移除组件（PC/MOBILE 按 refCompId 联动删） |
 | `e10-cli designer factory-list` | 列出 28 个内置 factory 模板（名称↔组件 type 对照） |
 | `e10-cli designer chart dataset-set\|measure-add\|dimension-add\|title\|height` | **图表配置（全 11 种）**。dataset-set 绑表单；measure-add 加度量（SUM/AVG/MAX/MIN 用 `--field-id`，COUNT 用 `--count-records`）；dimension-add 加维度（字段名/ID 均可，Date 自动按月）；title 设业务标题；height 设像素高。**Gauge：COUNT+无维度；堆积：2 度量+1 维度；Bubble：只能 1 度量** |
-| `e10-cli designer digital-panel panel-add ...` | 数字面板加 KPI 卡（`--field-id --aggregator SUM\|COUNT\|AVG\|MAX\|MIN --label`） |
+| `e10-cli designer digital-panel panel-add ...` | 数字面板加 KPI 卡（`--field-id --aggregator SUM\|COUNT\|AVG\|MAX\|MIN --label`）。可选 `--icon <path>` + `--icon-color` / `--icon-bg` 配卡片图标（`panels[].icon`，不给就不发该键；形状与导航面板不同：`fillType:'backgroundColor'`、底色键是 `bgColor`）。**每张卡的 `id` 自动避开已占用的**，保存前复查，重复即中止 |
 | `e10-cli designer list dataset-set\|field-add\|order-add` | NList 绑数据源/加显示列（`--type` `--comp-type` 同值传字段类型）/加排序 |
 | `e10-cli designer calendar dataset-bind\|field-map\|title` | 日历绑数据源（`--start --end --title-field`，内置全视图渲染）/调映射（`--end clear` 全天单日）/设标题 |
 | `e10-cli designer slide pic-add\|title` | 幻灯片加轮播图（**平台资源路径**，已防 Git Bash 路径转换）/设标题 |
-| `e10-cli designer nav-panel menu-add\|menu-source-type\|title` | 导航面板加跳页菜单（NewPage 双层 eventGroup 自动构造）/切菜单来源 DEFAULT\|CUSTOM/设标题 |
+| `e10-cli designer nav-panel menu-add\|menu-source-type\|title` | 导航面板加跳页菜单（NewPage 双层 eventGroup 自动构造）/切菜单来源 DEFAULT\|CUSTOM/设标题。`menu-add --icon <path> [--icon-color]`；**图标 path 不带 `#` 会自动补**（漏了 `#` 平台当图片路径加载 → 静默不显示） |
 | `e10-cli designer css read <pageId> <compId> [--terminal pc\|mobile\|both]` | 读组件**自定义 CSS**（`comp.config.styles[].customStyle.base.codeSource`；compId 给任一端都行） |
 | `e10-cli designer css write <pageId> <compId> (--css <文本>\|--css-file <路径>) [--append\|--clear] [--terminal] [--yes]` | 写自定义 CSS：默认**双端同写**、默认整段替换；`--append` 非幂等；`--clear` 清空但留记录；两端已分叉时须 `--yes`。写后回读比对，对不上报错 |
 | `e10-cli designer dom-list` / `designer dom <type> [--keys] [--section <path>] [--refs]` | 查写 CSS 要用的**组件 DOM 结构索引**（27 个组件，随包分发）。**先 `--keys` 看骨架再 `--section` 取子树**（文档中位数 20 多 KB） |
@@ -593,3 +607,29 @@ e10-cli actionflow generate '{"planFile":"@plan.json","appName":"AI-动作流名
 # 管理: list-node 查节点绑定 / clear-node 清 / delete/disable 删动作流
 e10-cli workflow action list-node <wf> <nodeId>
 ```
+
+## 工作流高级设置：功能管理
+
+| 命令 | 能力 |
+|---|---|
+| `workflow withdraw get/create/update <workflowId>` | 撤回管理 |
+| `workflow add-operator get/create/update <workflowId>` | 加审基础/会签设置及权限规则 |
+| `workflow minus-operator get/create/update <workflowId>` | 减审权限规则 |
+| `workflow receiver-range get/create/update <workflowId> --add-operator-id <id>` | 加审权限规则引用的普通模式接收人范围；自动查询/验证范围引用 |
+| `workflow receiver-range get/create/update <workflowId> --scene assign-flow --node-id <源节点ID>` | 指定流转通用接收人范围：普通模式、仅目标操作者范围、明细适用全部/操作者/抄送人 |
+| `workflow receiver-range get/create/update <workflowId> --scene assign-flow-target --node-id <源节点ID> --target-node-id <目标节点ID>` | 指定流转单独目标节点范围；自动解析配置记录和真实范围主键 |
+| `workflow forward-circulate-back get/create/update <workflowId>` | 转发/传阅/抄送收回 |
+
+写入用 `--data JSON/@文件`，单条规则修改用 `--rule-id`，查询元数据用 `get --schema`。详见 [功能管理指南](../workflow/guide-function-management.md)。
+
+## 拟签与节点转发
+
+| 命令 | 能力 |
+|---|---|
+| `workflow draft-opinion fields <wf>` | 查询已保存的拟签控件 ID |
+| `workflow draft-opinion get/create/update <wf> [--widget-id <id>]` | 流程展现/已有拟签控件配置，get 支持 --schema |
+| `workflow draft-opinion content get/create/update <wf>` | HTML 显示模板 |
+| `workflow draft-opinion style get/create/update <wf>` | 字体、按钮名称/颜色/顺序 |
+| `workflow node forward-setting get/create/update <wf> <node>` | 待办/已办/结束转发、接收人可提交意见/继续转发 |
+
+写入使用 `--data JSON/@文件`，未指定项保留，单次保存后回读。详见 [参数、范围与自然语言示例](../workflow/guide-opinion-settings.md)。

package/skill-docs/references/ebuilder-designer/guide-designer-components.md

@@ -97,6 +97,15 @@ e10-cli designer save <pageId> --layouts @layouts.json
 > 组件 `type`/`package`/`category`/`applyStyle`/`styleCategoryCompKey`/`styleCategoryPackage` 同样从真实 comp 复制真实值，不编造、不赋空。
 >
 > **机器随机 id 硬规则**：页面/组件配置里**所有由工具生成的随机 hex 机器 id 首位都不能是数字**（后端校验，浏览器样本首位恒为 a-f 字母）：`comp.id`(32 位)、图表 `axisId`(32 位)/`shortKey`(7 位，平台数据行/分组键)、NavPanel 菜单项/事件组/事件 id、DigitalPanel panel id 等。CLI `designer chart`/`digital-panel`/`nav-panel` 已统一用 `genLetterHex()`（首位强制 a-f）自动生成；agent 手工改 config 时须遵守同规则。真实数字标识（objId/pageId/formId/字段 id）照常可数字开头，勿动。
+>
+> **图标 path 必须带 `#` 前缀**。平台按 path **首字符分流**：`#` 开头走系统图标（`AssetsIcon`），**否则当成图片路径**去加载（`AssetsImg`）—— 所以写 `Icon-Project-o`（漏了 `#`）**不报错，只是静默不显示**，是最难查的一类问题。平台样本与 CLI 默认值都是带 `#` 的（`#icon-eBuilder-o`）。
+> 真要发**图片**才不带 `#`（以 `/`、`./`、`../`、`http(s)://`、`data:` 开头）。CLI 的 `designer nav-panel menu-add --icon` / `designer digital-panel panel-add --icon` / `form button … --icon` 都会**自动补 `#`**（见 `services/icon-path.ts`）；agent 手工改 config 时须自己带上。
+>
+> **图标对象的形状按组件分两套，别混用**：
+> - 导航面板 / app：`{path, style:{color, fillType:'borderColor', borderColor}}`
+> - **数字面板 KPI 卡**（`panels[].icon`，真机读回的形状）：`{path, style:{fontSize:36, color, disabled:false, fillType:'backgroundColor', borderColor, bgColor}, iconDisplayType:'line'}` —— `fillType` 是 **`backgroundColor`**，底色键叫 **`bgColor`**（在 `style` 里），`iconDisplayType` 在**图标对象顶层**。没有 `path` 时整块图标不渲染。
+>
+> **数字面板的卡 id 硬规则**：`config.panels[]` 里**每张卡的 `id` 必须两两不同**。撞了平台不报错，但设计器里两张卡会互相串。CLI `designer digital-panel panel-add` 会自动避开已占用的 id，并在保存前复查一遍。
 
 ---
 

package/skill-docs/references/form/guide-form-archive-permission.md

@@ -0,0 +1,175 @@
+# 流程归档权限
+
+「流程归档权限」管的是**某个流程归档之后**，它的数据对谁可见、可改、可删。它和表单的共享权限是两套：
+共享权限按表单配一次，归档权限**按流程各配一套**（同一张表单的不同流程可以不一样），并且多一档「归档附件」权限。
+
+## 命令
+
+```bash
+# 查看某个流程的归档权限
+e10-cli form permission archive list <objId> <appId> --workflow <workflowId>
+
+# 通用对象：给某个部门开「归档查看」
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target general --org-type department --org-id <deptId> --rights view --file-rights view download
+
+# 创建人相关：创建人本人及本部门可查看/编辑
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target creator --creator-related 0 --rights view edit
+
+# 字段相关：以表单里的「负责人」字段取值决定权限
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target field --field 负责人 --rights view edit delete
+
+# 矩阵相关（真矩阵）
+e10-cli form permission archive add <objId> <appId> --workflow <workflowId> \
+  --target matrix --matrix 门店经理矩阵 --rights view
+
+# 矩阵相关（e-Builder 表单当矩阵用）
+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...]>
+
+# 归档卡片开关
+e10-cli form permission archive card <workflowId> <appId>
+e10-cli form permission archive card <workflowId> <appId> --set 1
+```
+
+## 四类授权对象
+
+同一个端点上靠 `codeType` + `orgType` 区分四类，命令层用 `--target` 选择：
+
+| `--target` | 类别 | `codeType` | `orgType` | 主体怎么给 |
+|---|---|---|---|---|
+| `general` | 通用对象 | `obj_data_admin` | `employee` / `department` / `company` / `role` / `group` / `all` … | `--org-type` + `--org-id`（`all` 自动 0） |
+| `creator` | 创建人相关 | `obj_data_creator` | `creatorRelated` | `--creator-related` 0~7 |
+| `field` | 字段相关 | `obj_data` | `field_<字段类型>` | `--field <字段 id 或名称>` |
+| `matrix` | 矩阵相关 | `matrix` / `ebuilder_form` | 同 `codeType` | `--matrix`（真矩阵）或 `--eb-form` |
+
+`--target` 也接受中文名（`通用对象` / `创建人相关` / `字段相关` / `矩阵相关`）。
+
+### 创建人相关的 0~7
+
+`0` 本人、本部门、本分部；`1` 直接上级、本部门及所有下级部门、本分部及所有下级分部；`2` 本分部、本部门及所有上级部门、本分部及所有上级分部；
+`3` 本部门、所有下级部门、所有下级分部；`4` 所有上级、所有上级部门、所有上级分部；`5` 本岗位；`6` 直接下属；`7` 上级部门。
+
+### 字段相关的字段类型
+
+`--field` 既可给字段 id，也可给字段名（重名会报错，改用 id）。字段属于明细表时补 `--sub-form-id`。
+
+`orgType` 由字段的组件类型推出，目前覆盖：
+
+| 组件类型 | `orgType` | 回显名 |
+|---|---|---|
+| `Employee` | `field_employee` | 人员字段 |
+| `Department` | `field_department` | 部门字段 |
+| `SubCompany` | `field_company` | 分部字段 |
+| `Post` | `field_post` | 岗位字段 |
+| `EBuilder` | `field_ebuilder` | 关联ebuilder字段 |
+
+其余字段类型（人员范围选择、人力资源条件、人员组织多选等）不在自动推断表里 —— 组件类型名与 `field_*` 后缀不是一一对应，
+猜错会**静默授错对象**，所以命令会报错而不是替你选。这类请用 `--org-type field_xxx` 显式指定：
+
+`field_employee_condition`（人员范围选择字段）、`field_employee_share_condition`（人力资源条件字段）、`field_employee_organization`（人员组织多选）。
+
+### 矩阵相关的「取值字段」
+
+取值字段决定**用矩阵里的哪一列**去匹配当前用户，必需，且取值来源分两种：
+
+- **真矩阵**（`--matrix`）：值字段自动取该矩阵的值字段配置；也可用 `--matrix-value 名称` 指定其中几个。
+- **e-Builder 表单**（`--eb-form`）：取值字段是**系统值**体系，不是矩阵的值字段配置。
+  目前只有「创建者」可直接用名称指定；其余取值请用 `--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`）**同一套参数与语义**。
+
+## 权限码
+
+归档权限 `--rights`（可组合，逗号或空格分隔，也可用编号）：
+
+| 编号 | 别名 | 含义 |
+|---|---|---|
+| 5 | `view` / `read` | 归档查看 |
+| 6 | `edit` / `update` | 归档编辑 |
+| 7 | `delete` | 归档删除 |
+
+归档附件权限 `--file-rights`（与上面的查看/编辑/删除**互相独立**，是另一处勾选）：
+
+| 编号 | 别名 | 含义 |
+|---|---|---|
+| 501 | `view` / `read` | 归档附件查看 |
+| 502 | `download` | 归档附件下载 |
+| 503 | `edit` | 归档附件编辑 |
+
+> 归档附件用的是 `501/502/503`，**不是**共享权限的 `401/402/403`，两套别混。
+
+`--file-rights` 不给就不发生成附件权限键，该行只有数据权限。
+
+## 幂等与回读
+
+- 添加前先查一遍：同一个授权对象 + 同一权限组合已存在时直接跳过并报「已存在」，不会重复创建。
+- 保存后按新增 ID 回读，逐项核对 `codeType` / `orgType` / `rightType` / `fileRight` / 创建人关系 / 取值字段映射；
+  `rightType` 与 `fileRight` 按**集合**比对（平台保留提交时的顺序，但顺序不承载语义）。
+- 回读的 `orgTypeName` 会和该类别的预期名称对照（如 `field_employee` 对应「人员字段」）。对不上直接报错 ——
+  那意味着授权对象写错了，不能静默放过。
+- 字段相关这类计算型授权，平台会回 `isShowRebuild=2`，此时按提示执行
+  `e10-cli form permission rebuild <objId> <appId> <权限ID>` —— 等价于在权限行上点【重构】。
+  这一步不做，权限列表是不完整的（界面上表现为该行还要重构）。
+
+## 归档卡片
+
+每个流程还有一个「归档卡片」开关（`0` 关 / `1` 开）。不带 `--set` 时只读；带 `--set` 时先写再回读，以回读值为准。

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-message.md

@@ -31,14 +31,31 @@
 
 ## 提醒对象怎么写
 
-四类：`user` 人员、`dept` 部门、`role` 角色、`company` 分部。
+五类：`user` 人员、`dept` 部门、`role` 角色、`company` 分部、`matrix` 矩阵。
 
 写法是 `<类型>:<值>[,name=<显示名>][,extra=0|1]`：
 
 - **`<类型>:<名字>`** —— 工具按名字去查。**同名多条会报错并列出候选（带 ID）**，不会替你挑一条，免得配错人还看不出来。
 - **`<类型>:<ID>,name=<名字>`** —— 名字有歧义、或手上只有 ID 时用这个：`<值>` 直接当 ID 用，不查。
 
-`extra` 是组织范围上的附加项 —— 页面上部门 / 分部的提醒对象显示成「营销部:本部门含兼职人员」就是它。部门 / 分部缺省开、人员 / 角色缺省关，需要时显式覆盖。
+`extra` 是组织范围上的附加项 —— 页面上部门 / 分部的提醒对象显示成「营销部:本部门含兼职人员」就是它。部门 / 分部缺省开、人员 / 角色 / 矩阵缺省关，需要时显式覆盖。
+
+### 矩阵提醒对象（`matrix`）
+
+```bash
+form message add <appId> <objId> --name 有新数据了 --type 新建 --channels im \
+  --rule matrix:门店经理矩阵
+```
+
+矩阵那条报文的**键集合与其余四类完全不同**（真机报文坐实）：只有 `selectedType` / `containExtra` / `name` /
+`jobLevelText` / `jobLevelTextSpan` / `matrixValueRelation` / `matrixConditionData` / `ruledetail` / `id`，
+**没有** `levelScope` / `fieldtype` / `roleLevel` / `relation` 那一套，而且**不带 `ruletype`** —— 平台靠
+`selectedType='matrix'` 认它。工具会按矩阵的**值字段**自动构造 `matrixValueRelation`
+（决定用哪一列匹配当前用户），矩阵没配值字段时直接报错。
+
+> ⚠ **矩阵的「条件」这一层暂时配不了**。设计器能给矩阵提醒对象再加条件（`matrixConditionData`），
+> 但那个对话框里的右值是一种新形态（`type:"custom"` + 一组选中的对象数组 + `customSelect`），
+> CLI 还没有对应的构造；报文里这个键会发空串。要带条件的，先去设计器里配。
 
 ```
 form message add <appId> <objId> --name 有新数据了 \