weaver-e10-builder 1.7.1 → 1.7.2

package/skill-docs/actionflows/references/condition_rules.md

@@ -1,100 +1,100 @@
-# 条件业务规则
-
-仅在需求包含条件、筛选或 if/else 时读取本文件。
-
-- 用户没有说明条件成立或不成立后要做什么时，不擅自补写更新、删除、通知或其他业务动作。
-- 条件的业务含义存在多个合理解释时，向用户确认比较含义与各结果分支的预期动作。
-- 条件字段、操作符、值形态的**权威规范（前端 ConditionSet 源码逆向）**见下方「二、ESB filterInput / ConditionSet 右值规范」，来源：工作区 `condition-generator-skill/`（SKILL.md 第 6 章 + references/）。
-
----
-
-## 一、筛选条件（filterCondition）plan 写法
-
-- 单条件：`{"field": {"id": "<目标字段id>", "label": "<字段名>"}, "operator": "<操作符>", "right": {...}}`。`right` 是唯一对外计划字段；不要使用历史别名 `value`。
-- 条件组（且/或）：`{"relationship": "and|or", "conditions": [ <条件1>, <条件2>, ... ]}`（编译器支持嵌套）。不接受平台输出 DTO 的 `datas` 或 `1/0`。
-- `right` 值形态（type）：
-  - `context`：`{"type":"context","paramKey":"<真实paramKey>","label":"<显示名>"}` —— 引用上游上下文（esbAssign.wId 自动指向当前节点）
-  - `native` + `mode: "currentTime"|"currentDate"|"now"|"today"`：**当前时间/当前日期**。编译器自动改写为系统参数 `{time}`/`{date}`（见下节 6），`conditions.value` 非空、`type:""`，设计器点开筛选器右值区能正常回显，不会出现「右值未配置」（真机验证 2026-08-18）
-  - `fixed`：普通固定值；字符串为 `{...}` 系统变量时自动识别为 system
-  - `system`：系统参数 token，如 `{userid}`/`{date}`/`{time}`（由动作流编译器内置 system_params 处理）
-- 操作符：`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`（`empty/nempty` 无右值）
-- 日期字段用系统值：直接 `right.value = "{date}"` 或 `{time}`（ESB 体系），无需 `{today}`（那是通用 ConditionSet 的占位符写法，ESB 编译器会归一为 system）
-
-## 分支条件（`Condition`）
-
-分支条件和 `filterCondition` 共用 AND/OR 业务语义，但保存协议不同，不能互相复制 DTO。
-
-- **分支位置**：`branches` 写在节点顶层或 `params.branches` 都会被受理（`component-describe Condition` 声明的就是 `params.branches`）；归一化后草稿只保留顶层 `branches`。**同一节点不要两处各写一份**——读分支的实现统一走同一入口，两份写法只会让人误判哪份生效。
-- 计划用 `condition: { relationship: "and|or", conditions: [...] }`；叶子为 `{left, operator, right}`。顶层 `relationship` 直接作为条件树根关系；编译器不会额外套同关系 AND/OR，只有条件中明确嵌套的规则组才保留子组。
-- `left` 只能是当前上游组件的实时字段；`operator` 由字段类型限制，未知或不兼容时编译失败。
-- `right` 只用 `fixed`、`system`、`context`，或 `formula` 完整回读对象。`context` 必须写真实 `paramKey`，由运行时生成 FormulaBean；禁止把字段名作为固定值。
-- 保存采用 ESB `source=8`：预暂存注册来源节点 → `getConditionSet` → `saveCondition` → 以保存响应回填真实持久化 ID → 最终暂存。新建后 `getExpressionBean` 可能只返回分组骨架，不能覆盖完整 `childrens` 叶子树；`mapBaseId`、`conditionId`、`mapId` 和所有 Long ID 都保持字符串，新建条件不传本地 `conditionId`。
-
-## 二、ESB filterInput / ConditionSet 右值规范（源自 condition-generator-skill）
-
-ESB 动作流的 `filterInput`（TimeBatchTrigger/DateTrigger/数据动作筛选）与通用 ConditionSet 筛选器**结构同源**（`isNewFilter/isParent/datas/relationship/key` + 叶子 `conditions{func,type,value,text}`）。生成条件时遵循以下规范：
-
-### 1. 叶子条件结构
-
-```json
-{
-  "id": "<字段id>", "fieldName": "<字段英文名>",
-  "conditions": { "func": "lt", "type": "", "value": "{time}", "text": "当前时间" }
-}
-```
-
-`fieldType/text/objId/compType` 等元信息由编译器按真实字段补全（`buildFilterInput`），**plan 里不写**。对于关联字段，编译器必须保留平台所需的真实 `sformId`；`refObjId` 仅在该组件的正式 DTO 要求时保留，不能把它作为所有关联字段的统一必填项，也不能只写字段 ID或把表单版本 `formId` 当作关联对象身份，否则保存后设计器可能显示“字段已删除”。
-
-其中 Workflow 字段要区分两种 ID：`formInfo.formId` 是当前目标表单的版本 ID；顶层 `sformId` 是该字段关联的流程表单对象 ID。正式回读的 Workflow DTO 使用原始数字 `fieldName`、`fieldType:"String"`、空 `module`/`originBrowserType`，`config` 只保留 `fieldId`；不能按普通 e-builder 业务字段加 `field_` 前缀，也不能把组件名 `Workflow` 当作存储类型。`refObjId` 对 Workflow 不是必填。若实时字段接口没有返回 Workflow 的关联对象，预检必须根据当前 `workflowPath.formIds` 在同一应用的表单列表中反查对象 ID，并把目标表 `getFormLayout` 返回的默认布局 ID写入 `formInfo.layoutId`。反查不到时应报错停止，不能用目标表单版本 ID兜底。
-
-### 2. 值类型 `conditions.type` 枚举
-
-| type | 含义 | 适用 |
-|---|---|---|
-| `""` | 手动输入 / 选选项 / **系统值** | 文本/数值直接输入、选择框选选项、**日期选系统占位符** |
-| `"custom"` | 专用选择器 / 选择框手动输入 | 人员/部门/级联/地区/Select 手动输入；**日期 range 模式推荐**（渲染日期选择器） |
-| `"custombyhander"` | 手动输入（浏览器类组件） | 人员/部门/关联字段/文档/附件 |
-| `"formField"` | 引用本表/关联表字段值 | 所有类型（value 含 `compareFormField`，必须含 `objId`+`name` 否则回显空白） |
-| `"varField"` | 引用系统/流程变量 | 所有类型（value 含 `compareVarField`，`id` 必须是真实变量 id 否则回显空白） |
-| `"filterVal"` | 引用其他筛选组件搜索值 | 文本/数值/日期 |
-
-### 3. 系统日期占位符（通用 ConditionSet 写法，type 为 `""`）
-
-| 占位符 | 含义 |
-|---|---|
-| `{today}` | 当前日期 |
-| `{yesterday}` / `{tomorrow}` | 昨天 / 明天 |
-| `{currweek}` / `{lastweek}` / `{nextweek}` | 本周 / 上周 / 下周 |
-| `{currmonth}` / `{lastmonth}` / `{nextmonth}` | 本月 / 上月 / 下月 |
-| `{currseason}` / `{lastseason}` / `{nextseason}` | 本季 / 上季 / 下季 |
-| `{curryear}` / `{lastyear}` / `{nextyear}` | 本年 / 去年 / 明年 |
-
-自定义日期占位符（type `"custom"`，后端 `handleValue` 识别）：`{year}`（本年区间）、`{year}-{month}`（当月区间）、`{date:±N}`（今天±N 天）。
-
-> **ESB 差异**：ESB 动作流的系统值 token 由编译器内置 system_params 处理（`{date}`=当前日期、`{time}`=当前时刻、`{userid}` 等）；通用 ConditionSet 的 `{today}` 等占位符在 ESB filterInput 中由编译器归一（native `currentTime/currentDate/now/today` → `{time}`/`{date}`），生成时两者皆可，编译器兜底。
-
-### 4. func 操作符
-
-| func | 含义 | 适用 |
-|---|---|---|
-| `eq`/`neq` | 等于/不等于 | 所有 |
-| `gt`/`lt`/`gte`/`lte` | 大于/小于/大于等于/小于等于 | 数值、日期 |
-| `range` | 区间（value 为 `[起始,结束]`） | 数值、日期 |
-| `contains`/`uncontains` | 包含/不包含 | 文本 |
-| `empty`/`nempty` | 为空/不为空（无右值） | 所有 |
-
-### 5. 字段类型 × 值类型速查
-
-- 文本（String/Text/TextArea）：type `""`、`formField`、`varField`、`filterVal`；无 `custombyhander`
-- 数值（Number/NumberComponent）：type `""`（含 range）、`formField`、`varField`、`filterVal`；**无 `custombyhander`**
-- 日期（Date/DateComponent/DateInterval）：type `""`（手动输入/系统日期）、`"custom"`（手动输入，range 推荐）、`"customDate"`（仅宿主注入回调时可用，**默认不用**）、`formField`、`varField`、`filterVal`
-- 选择框（Select/RadioBox/CheckBox）：type `""`（选选项，value 逗号分隔）、`"custom"`（手动输入）、`formField`、`varField`
-- 人员（Employee）/部门（Department）：type `""`（系统选项）、`"custom"`（选人/选部门）、`"custombyhander"`、`formField`、`varField`
-
-### 6. 「当前时间」筛选的正确表达（真机验证 2026-08-18）
-
-ESB TimeBatchTrigger/DateTrigger 等定时器的 `filterCondition` 用「字段 < 当前时间」时：
-
-- plan 写：`{"field": {"id": "<日期字段id>", "label": "<字段名>"}, "operator": "lt", "right": {"type": "native", "mode": "currentTime", "label": "当前时间"}}`
-- 编译器把 `native currentTime/now/current_time` 改写为系统参数 `{time}`（`currentDate/today/current_date` → `{date}`），落到 system 路径
-- 读回后 `conditions = {"func":"lt","text":"当前时间","value":"{time}","type":"","isEsb":false}` —— value 非空，设计器点开筛选器右值区正常回显「当前时间」，**不会空**（此前直接透传 `type:"currentTime"` + `value:""` 导致点进去右值区空白，外部摘要正常）
+# 条件业务规则
+
+仅在需求包含条件、筛选或 if/else 时读取本文件。
+
+- 用户没有说明条件成立或不成立后要做什么时，不擅自补写更新、删除、通知或其他业务动作。
+- 条件的业务含义存在多个合理解释时，向用户确认比较含义与各结果分支的预期动作。
+- 条件字段、操作符、值形态的**权威规范（前端 ConditionSet 源码逆向）**见下方「二、ESB filterInput / ConditionSet 右值规范」，来源：工作区 `condition-generator-skill/`（SKILL.md 第 6 章 + references/）。
+
+---
+
+## 一、筛选条件（filterCondition）plan 写法
+
+- 单条件：`{"field": {"id": "<目标字段id>", "label": "<字段名>"}, "operator": "<操作符>", "right": {...}}`。`right` 是唯一对外计划字段；不要使用历史别名 `value`。
+- 条件组（且/或）：`{"relationship": "and|or", "conditions": [ <条件1>, <条件2>, ... ]}`（编译器支持嵌套）。不接受平台输出 DTO 的 `datas` 或 `1/0`。
+- `right` 值形态（type）：
+  - `context`：`{"type":"context","paramKey":"<真实paramKey>","label":"<显示名>"}` —— 引用上游上下文（esbAssign.wId 自动指向当前节点）
+  - `native` + `mode: "currentTime"|"currentDate"|"now"|"today"`：**当前时间/当前日期**。编译器自动改写为系统参数 `{time}`/`{date}`（见下节 6），`conditions.value` 非空、`type:""`，设计器点开筛选器右值区能正常回显，不会出现「右值未配置」（真机验证 2026-08-18）
+  - `fixed`：普通固定值；字符串为 `{...}` 系统变量时自动识别为 system
+  - `system`：系统参数 token，如 `{userid}`/`{date}`/`{time}`（由动作流编译器内置 system_params 处理）
+- 操作符：`eq/neq/gt/lt/gte/lte/contains/uncontains/empty/nempty`（`empty/nempty` 无右值）
+- 日期字段用系统值：直接 `right.value = "{date}"` 或 `{time}`（ESB 体系），无需 `{today}`（那是通用 ConditionSet 的占位符写法，ESB 编译器会归一为 system）
+
+## 分支条件（`Condition`）
+
+分支条件和 `filterCondition` 共用 AND/OR 业务语义，但保存协议不同，不能互相复制 DTO。
+
+- **分支位置**：`branches` 写在节点顶层或 `params.branches` 都会被受理（`component-describe Condition` 声明的就是 `params.branches`）；归一化后草稿只保留顶层 `branches`。**同一节点不要两处各写一份**——读分支的实现统一走同一入口，两份写法只会让人误判哪份生效。
+- 计划用 `condition: { relationship: "and|or", conditions: [...] }`；叶子为 `{left, operator, right}`。顶层 `relationship` 直接作为条件树根关系；编译器不会额外套同关系 AND/OR，只有条件中明确嵌套的规则组才保留子组。
+- `left` 只能是当前上游组件的实时字段；`operator` 由字段类型限制，未知或不兼容时编译失败。
+- `right` 只用 `fixed`、`system`、`context`，或 `formula` 完整回读对象。`context` 必须写真实 `paramKey`，由运行时生成 FormulaBean；禁止把字段名作为固定值。
+- 保存采用 ESB `source=8`：预暂存注册来源节点 → `getConditionSet` → `saveCondition` → 以保存响应回填真实持久化 ID → 最终暂存。新建后 `getExpressionBean` 可能只返回分组骨架，不能覆盖完整 `childrens` 叶子树；`mapBaseId`、`conditionId`、`mapId` 和所有 Long ID 都保持字符串，新建条件不传本地 `conditionId`。
+
+## 二、ESB filterInput / ConditionSet 右值规范（源自 condition-generator-skill）
+
+ESB 动作流的 `filterInput`（TimeBatchTrigger/DateTrigger/数据动作筛选）与通用 ConditionSet 筛选器**结构同源**（`isNewFilter/isParent/datas/relationship/key` + 叶子 `conditions{func,type,value,text}`）。生成条件时遵循以下规范：
+
+### 1. 叶子条件结构
+
+```json
+{
+  "id": "<字段id>", "fieldName": "<字段英文名>",
+  "conditions": { "func": "lt", "type": "", "value": "{time}", "text": "当前时间" }
+}
+```
+
+`fieldType/text/objId/compType` 等元信息由编译器按真实字段补全（`buildFilterInput`），**plan 里不写**。对于关联字段，编译器必须保留平台所需的真实 `sformId`；`refObjId` 仅在该组件的正式 DTO 要求时保留，不能把它作为所有关联字段的统一必填项，也不能只写字段 ID或把表单版本 `formId` 当作关联对象身份，否则保存后设计器可能显示“字段已删除”。
+
+其中 Workflow 字段要区分两种 ID：`formInfo.formId` 是当前目标表单的版本 ID；顶层 `sformId` 是该字段关联的流程表单对象 ID。正式回读的 Workflow DTO 使用原始数字 `fieldName`、`fieldType:"String"`、空 `module`/`originBrowserType`，`config` 只保留 `fieldId`；不得自行拼接字段前缀，也不能把组件名 `Workflow` 当作存储类型。`refObjId` 对 Workflow 不是必填。若实时字段接口没有返回 Workflow 的关联对象，预检必须根据当前 `workflowPath.formIds` 在同一应用的表单列表中反查对象 ID，并把目标表 `getFormLayout` 返回的默认布局 ID写入 `formInfo.layoutId`。反查不到时应报错停止，不能用目标表单版本 ID兜底。
+
+### 2. 值类型 `conditions.type` 枚举
+
+| type | 含义 | 适用 |
+|---|---|---|
+| `""` | 手动输入 / 选选项 / **系统值** | 文本/数值直接输入、选择框选选项、**日期选系统占位符** |
+| `"custom"` | 专用选择器 / 选择框手动输入 | 人员/部门/级联/地区/Select 手动输入；**日期 range 模式推荐**（渲染日期选择器） |
+| `"custombyhander"` | 手动输入（浏览器类组件） | 人员/部门/关联字段/文档/附件 |
+| `"formField"` | 引用本表/关联表字段值 | 所有类型（value 含 `compareFormField`，必须含 `objId`+`name` 否则回显空白） |
+| `"varField"` | 引用系统/流程变量 | 所有类型（value 含 `compareVarField`，`id` 必须是真实变量 id 否则回显空白） |
+| `"filterVal"` | 引用其他筛选组件搜索值 | 文本/数值/日期 |
+
+### 3. 系统日期占位符（通用 ConditionSet 写法，type 为 `""`）
+
+| 占位符 | 含义 |
+|---|---|
+| `{today}` | 当前日期 |
+| `{yesterday}` / `{tomorrow}` | 昨天 / 明天 |
+| `{currweek}` / `{lastweek}` / `{nextweek}` | 本周 / 上周 / 下周 |
+| `{currmonth}` / `{lastmonth}` / `{nextmonth}` | 本月 / 上月 / 下月 |
+| `{currseason}` / `{lastseason}` / `{nextseason}` | 本季 / 上季 / 下季 |
+| `{curryear}` / `{lastyear}` / `{nextyear}` | 本年 / 去年 / 明年 |
+
+自定义日期占位符（type `"custom"`，后端 `handleValue` 识别）：`{year}`（本年区间）、`{year}-{month}`（当月区间）、`{date:±N}`（今天±N 天）。
+
+> **ESB 差异**：ESB 动作流的系统值 token 由编译器内置 system_params 处理（`{date}`=当前日期、`{time}`=当前时刻、`{userid}` 等）；通用 ConditionSet 的 `{today}` 等占位符在 ESB filterInput 中由编译器归一（native `currentTime/currentDate/now/today` → `{time}`/`{date}`），生成时两者皆可，编译器兜底。
+
+### 4. func 操作符
+
+| func | 含义 | 适用 |
+|---|---|---|
+| `eq`/`neq` | 等于/不等于 | 所有 |
+| `gt`/`lt`/`gte`/`lte` | 大于/小于/大于等于/小于等于 | 数值、日期 |
+| `range` | 区间（value 为 `[起始,结束]`） | 数值、日期 |
+| `contains`/`uncontains` | 包含/不包含 | 文本 |
+| `empty`/`nempty` | 为空/不为空（无右值） | 所有 |
+
+### 5. 字段类型 × 值类型速查
+
+- 文本（String/Text/TextArea）：type `""`、`formField`、`varField`、`filterVal`；无 `custombyhander`
+- 数值（Number/NumberComponent）：type `""`（含 range）、`formField`、`varField`、`filterVal`；**无 `custombyhander`**
+- 日期（Date/DateComponent/DateInterval）：type `""`（手动输入/系统日期）、`"custom"`（手动输入，range 推荐）、`"customDate"`（仅宿主注入回调时可用，**默认不用**）、`formField`、`varField`、`filterVal`
+- 选择框（Select/RadioBox/CheckBox）：type `""`（选选项，value 逗号分隔）、`"custom"`（手动输入）、`formField`、`varField`
+- 人员（Employee）/部门（Department）：type `""`（系统选项）、`"custom"`（选人/选部门）、`"custombyhander"`、`formField`、`varField`
+
+### 6. 「当前时间」筛选的正确表达（真机验证 2026-08-18）
+
+ESB TimeBatchTrigger/DateTrigger 等定时器的 `filterCondition` 用「字段 < 当前时间」时：
+
+- plan 写：`{"field": {"id": "<日期字段id>", "label": "<字段名>"}, "operator": "lt", "right": {"type": "native", "mode": "currentTime", "label": "当前时间"}}`
+- 编译器把 `native currentTime/now/current_time` 改写为系统参数 `{time}`（`currentDate/today/current_date` → `{date}`），落到 system 路径
+- 读回后 `conditions = {"func":"lt","text":"当前时间","value":"{time}","type":"","isEsb":false}` —— value 非空，设计器点开筛选器右值区正常回显「当前时间」，**不会空**（此前直接透传 `type:"currentTime"` + `value:""` 导致点进去右值区空白，外部摘要正常）

package/skill-docs/references/common/guide-install.md

@@ -32,6 +32,8 @@ npx -y skills add ./weaver-e10-builder.zip --skill -y
 
 1.1.0 起发布的 skill 是**薄指令层**：只带 SKILL.md、`_catalog.md`、actionflows 指令层和 scripts，不含深目录文档树（适配 marketplace 两级目录限制）。完整文档随配套 CLI 的 `skill-docs` 分发。
 
+薄层 zip 的**根目录另带 `INSTALL.md`**，新用户还没装 CLI、本文件（`references/common/guide-install.md`）尚未同步时，先按 `INSTALL.md` 装 CLI；装好后跑一次 `e10-cli auth status` 即可拿到本文档。
+
 - 每次 `e10-cli auth status` 会自动探测本机已装 skill（`~/.claude/skills`、`~/.workbuddy/skills`、`~/.codex/skills`）并同步文档；版本一致则跳过。
 - 手动刷新：`e10-cli skill sync`；可 `--target <安装根目录>` 指定其他工具目录。
 - 装完 skill 后看到 references 文档多出/更新、旧文档被清理，都是正常的同步现象，不是装错或重复安装。

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

@@ -119,7 +119,7 @@
 | `e10-cli form permission create <add\|update\|show> <objId> <appId> [--right-id <id>] --org-type <类型> [--org-id <id>] [--org-name <名>] [设置项]` | **创建权限**（谁能新建记录）。通用对象支持 all/employee/department/company/role/group/post/partTime/grade/external/externalAll；`all`/`externalAll` 的 orgId 自动 0。`update` 只改点名项并整行回写；`show` 查看布局/优先级/描述/条件/同步列表。设置项见下一行 |
 | `e10-cli form permission data <add\|update\|show> <objId> <appId> [--right-id <id>] --target <general\|creator\|field\|matrix\|govern> --rights <view/edit/delete/comment...> [设置项]` | **共享权限**（查看/编辑/删除/评论；`1/2/3/4`）。`general` 通用对象（同上 11 种类型）；`creator --creator-related 0~7` 创建人相关；`field --field <字段id或名>` 字段相关（`--sub-form-id` 支持明细字段）；`matrix --matrix <矩阵>` 或 `--eb-form <e-Builder表单>` + `--matrix-value`/`--matrix-value-raw`/`--matrix-condition-raw`；`govern --govern-json <json>` 政务单位相关。附件 `--file-rights view/download/edit`（401/402/403）与 `--file-right-type temporary\|insert`（临时/插入赋权）。保存后按权限 ID 回读核对。详见 `form/guide-form-permission.md` |
 | 权限通用设置（`create` / `data` 的 `add\|update`） | `--layout` / `--edit-layout` / `--mobile-layout` / `--mobile-edit-layout`（关联 PC、编辑、移动、移动编辑布局）、`--same-layout on\|off`（PC 移动统一布局）、`--layout-order <n>`（优先级，0 最高）、`--desc <文本>` / `--desc-label-id`（权限描述）、`--condition <json\|@file>` / `--clear-condition`（权限条件，写入前按平台算法压缩）、`--org-virtual-type`（组织维度）、`--contain-extra on\|off`（含兼职人员）、`--min-seclevel` / `--max-seclevel`（安全级别 0~100）、`--exclude-obj <json\|@file>`（排除项）、`--sync-forms <objId...>`（同步至其他表单，整体替换）。修改只改点名项；未点名的布局、条件、同步列表原样保留 |
-| `e10-cli form permission imp-exp <list\|add\|update\|show> <objId> <appId> [--right-id <id>] ...` | **导入导出权限**（独立分类 `data_imp_exp`，⚠ 勿用 `data add` 加——共享权限只有 查看/编辑/删除 三种，导出/导入不在其中）。`list` 查看；`add/update --org-type <类型> [--org-id] --rights <export/import/delete-import...> [--update-import] [--export-details] [--export-attachment] [--export-field-range listShowField\|allField]`；`show` 查看单条。`export=8`、`import=9`、`delete-import=93`（93 须与 import 同选，自动带更新导入）；授权对象与共享权限同一套 11 种通用对象（含兼职岗位/职级/外部联系人/所有外部联系人）。保存后按权限 ID 回读 `impRightList` 校验；修改只改点名项，并原样保留已有的权限描述/导入关联布局（`rightDesc`/`layoutId` 等，防止被更新报文清空）。删除同 `permission remove --right-id`。不支持配置权限描述/更新导入校验数据编辑权限/导入关联布局/优先级/同步至其他表单 |
+| `e10-cli form permission imp-exp <list\|add\|update\|show> <objId> <appId> [--right-id <id>] ...` | **导入导出权限**（独立分类，⚠ 勿用 `data add` 加——共享权限只有 查看/编辑/删除 三种，导出/导入不在其中）。`list` 查看；`add/update` 支持两类授权对象：`--target general`（默认，`codeType=data_imp_exp`）+ `--org-type <类型> [--org-id]`，或 `--target matrix`（`codeType=data_imp_exp_matrix`）+ `--matrix <矩阵id或名称>` / `--eb-form <表单id或名称>`、`--matrix-value <取值字段...>`（或 `--matrix-value-raw` / `--matrix-condition-raw`）；`--rights <export/import/delete-import...> [--update-import] [--export-details] [--export-attachment] [--export-field-range listShowField\|allField]`；`show` 查看单条。`export=8`、`import=9`、`delete-import=93`（93 须与 import 同选，自动带更新导入）；通用对象与共享权限同一套 11 种对象（含兼职岗位/职级/外部联系人/所有外部联系人）。保存后按权限 ID 回读 `impRightList` 校验（矩阵两键按语义比对）；修改只改点名项，并原样保留已有的权限描述/导入关联布局（`rightDesc`/`layoutId` 等，防止被更新报文清空）。删除同 `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`（e-Builder 表单按名取它自己的人员字段/创建者，人员字段 valueType=resource），另可加**矩阵条件**（e-Builder 表单的条件列自动取该表单主表字段） `--matrix-condition '<json>'`（可重复 / `@文件` 给数组；右值三选一 `value` 固定值 / `field` 引本表单字段 / `fieldRef` 直给字段描述符）+ `--matrix-condition-relation and\|or`。权限码 `5/view` 归档查看、`6/edit` 归档编辑、`7/delete` 归档删除（**归档查看是系统默认必选，界面不可取消；`--rights` 没传 view 会自动并入**）；归档附件另算 `501/view`、`502/download`、`503/edit`（**不是**共享权限的 401/402；**归档附件查看 501 同属系统必选，不给 `--file-rights` 也会带上**）。保存后按 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 用于菜单配置） |
@@ -213,10 +213,10 @@
 | 命令 | 说明 |
 |------|------|
 | `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，保存后回读动作和映射。建按钮时还可一次带上基础属性：`--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 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`。`--icon` 写前校验平台图标名，错名报错并给近似候选；确认是目录未覆盖的自定义图标时加 `--force-icon` |
+| `e10-cli form button set <objId> <appId> <buttonId> [--name <名称>] [--tips <文本>] [--desc <文本>] [--icon <图标名> --icon-color <色值> --icon-bg <色值> --icon-display <line\|fill>] [--force-icon] [--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]` | 改按钮基础属性：名称 / 提示内容 / 备注 / 图标 / 点击日志 / 数据过滤 / 禁用条件。**已有的动作与权限原样保留**。`--icon` 写前校验平台图标名，错名报错并给近似候选（`--force-icon` 跳过）。数据过滤的 `--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 <objId> <appId> <buttonId> [--add-url <url>\|--add-view <视图>\|--add-layout <表单>\|--add-start-workflow <流程>\|--add-confirm ...\|--add-js --code <源码\|@文件>\|--add-edit-field "字段:值"...\|--add-reply\|--add-view-logs [--log-types 1,2,3,4]\|--add-close-page\|--add-scan-upload\|--add-logic <逻辑流>] [--execute-selected] [--remove <序号\|id>] [--clear]` | 管按钮动作，**一个按钮可挂多个**；不带选项时列出。追加顺序固定为 打开页面 → 确认框 → JavaScript → 编辑字段值 → 评论和日志 → 查看日志 → 关闭页面 → 扫描上传 → 触发逻辑流。`--log-types` 为查看日志的记录类型（1查阅/2操作/3表单修改/4打印，可写数字或中文名，缺省全部）。`--add-edit-field` 只支持赋固定值，同字段后写覆盖先写；**选项字段可写选项名或 valueKey，命令会同时写入 `content` 与 valueKey**（写错/写不到选项会报错），多选支持 `"A,B"` 或 JSON 数组。`--execute-selected` 把本次新增/合并的动作设为「按勾选数据执行」（`executeSelectedDatas=1`，打开页面动作不适用）。`--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` |
@@ -224,8 +224,11 @@
 | `e10-cli form association list/get <objId> <appId> [associationId]` | 查询关联页签列表或详情；get 必须传 associationId，详情含目标视图、筛选映射和权限 |
 | `e10-cli form association views <objId> <appId> [--target-app <id>]` | 查询可绑定视图及所属表单 |
 | `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 create <objId> <appId> <name> --view <viewId> --permissions <json或@文件> [--layouts 显示 编辑] [--terminals PC MOBILE] [--order <n>] [--selected true/false] [--group <id/name/none>] [--mappings <json或@文件>]` | 创建关联页签；默认仅显示布局、PC+MOBILE、启用。权限必须显式提供，筛选映射为 [{targetField,sourceField}]。`--selected true` 会把其它页签改为未选中；`--group` 按 ID 或唯一名称绑定分组 |
+| `e10-cli form association update <objId> <appId> <associationId> [--name <名>] [--view <viewId>] [--layouts 显示 新建 编辑] [--terminals PC MOBILE] [--enabled true/false] [--order <n>] [--selected true/false] [--group <id/name/none>] [--permissions <json或@文件>] [--mappings <json或@文件>]` | 保留未指定配置；布局和终端为集合替换；显示=0，新建=1，编辑=2，none 关闭全部布局。仅启停走独立接口并回读；多动作时传 --action。`--permissions` 为整组替换 |
+| `e10-cli form association reorder <objId> <appId> <id...>` | 按给定顺序整体重排全部关联页签（必须给本表单全部 ID）；走 updateOrderV2 并回读顺序 |
+| `e10-cli form association group list/add/update/delete <objId> <appId> ...` | 关联页签分组增删改查。`add <名称> [--order n]`、`update <分组ID或名称> [--name] [--order]`、`delete <分组ID或名称>`；保存为整组回写，删除分组不会删除组内页签 |
+| `e10-cli form association set-seclevel <objId> <appId> <associationId> --perm <序号或类型> --seclevel <min>-<max>` | 修改某条关联权限的安全级别 `levelScope`（0~100，如 30-100），读整行回写并回读 |
 | `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>]` | 清空指定视图动作的数据筛选映射 |
@@ -597,7 +600,8 @@ e10-cli report py preagg --report-id <id> [--app-id <id>]
 | 命令 | 说明 |
 |------|------|
 | `e10-cli user search <keyword> [count]` | 模糊搜索员工（返回 ID/姓名/部门/手机） |
-| `e10-cli icon search <keyword...>` | 搜索 Ebuilder 图标（4999 个，支持多关键词） |
+| `e10-cli icon search <keyword...>` | 搜索 Ebuilder 图标（7438 个，按名称/中文名，多关键词需同时命中） |
+| `e10-cli icon check <图标名>` | 校验图标名是否存在；不存在时给近似候选（只读本地图标目录，不访问平台） |
 
 ---
 

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

@@ -63,15 +63,51 @@ e10-cli form association create <objId> <appId> "全部合同" --view <viewId> -
 | `--layouts none` | 三种布局均不显示 |
 | `--terminals PC MOBILE` | 两端适用；可只传其中一个 |
 | `--enabled true/false` | 启用或停用页签 |
+| `--order <n>` | 显示顺序（1 起）；新建不传时平台自动追加到末尾 |
+| `--selected true/false` | 是否默认选中该页签；`true` 时平台会把本表单其它页签改为未选中 |
+| `--group <id/name/none>` | 关联分组；`none` 移出分组 |
+| `--permissions <json/@file>` | 关联权限数组，整组替换（`update` 也可用；不支持用空数组清空） |
 
 ```bash
 e10-cli form association update <objId> <appId> <associationId> --layouts 显示
 e10-cli form association update <objId> <appId> <associationId> --name "相关合同" --terminals PC --enabled true
 e10-cli form association update <objId> <appId> <associationId> --view <newViewId> --mappings @association-mappings.json
+e10-cli form association update <objId> <appId> <associationId> --order 2 --selected true
+e10-cli form association update <objId> <appId> <associationId> --group "客户信息"
 ```
 
 `update` 保留未指定属性以及原动作、权限条件和提示。布局、终端参数表示替换对应集合。修改绑定视图且已有映射时必须显式提供新映射（`[]` 可清空），避免原目标表字段被用于新视图。
 
+### 调整页签顺序
+
+单个页签可直接 `update --order <n>`。需要整体重排时，必须给出本表单**全部**关联页签 ID，按目标显示顺序排列：
+
+```bash
+e10-cli form association reorder <objId> <appId> <id1> <id2> <id3>
+```
+
+命令走 `association/updateOrderV2`，平台按传入顺序写成 1..N，保存后回读排序；只给部分 ID 会直接报错，避免未传页签的 order 冲突。
+
+### 页签分组
+
+```bash
+e10-cli form association group list <objId> <appId>
+e10-cli form association group add <objId> <appId> "客户信息" [--order 1]
+e10-cli form association group update <objId> <appId> <分组ID或名称> [--name "新名称"] [--order 2]
+e10-cli form association group delete <objId> <appId> <分组ID或名称>
+```
+
+平台分组保存是**整组回写**：命令会先读现有分组，再增/改/删目标项并把完整列表提交；未提交的分组会被平台删除，所以不要手工拼 `groups`。分组的 `showOrder` 由提交列表顺序重新计算；`--order` 就是列表中的位置（1 起）。删除分组不会删除组内页签，页签会变成未分组。
+
+### 权限安全级别
+
+```bash
+e10-cli form association set-seclevel <objId> <appId> <associationId> \
+  --perm <1-based序号|selectedType> --seclevel 30-100
+```
+
+`--seclevel` 写入该权限的 `levelScope.minShowlevel/maxShowlevel`（0~100，最小值不能大于最大值），走读整行 → 改目标权限 → `saveOrUpdate` → 回读。也可以用 `update --permissions @file` 整组替换权限数组，文件里的 `levelScope` 按同样格式写。
+
 仅启用或停用页签时，`update --enabled true|false` 使用 `updateIsOpenById` 独立接口并通过列表回读状态，不整包保存关联配置。
 
 ## 删除关联页签

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

@@ -94,6 +94,18 @@ e10-cli form button set <objId> <appId> <buttonId> --log --log-message "提交
 
 `--icon-display` 取 `line`（描边）或 `fill`（填充）；只改颜色/描边时按钮必须已有图标。
 
+### 图标名校验
+
+平台对不存在的图标名**不报错**，只会在运行时渲染成空白 —— 按钮看起来像“没样式”，排查时很难发现是名字写错。`form button add|set --icon` 现在写前按平台图标目录校验：
+
+```bash
+e10-cli icon check Icon-N-Delete      # ❌ 不存在，并给出 Icon-N-Deleted 等近似候选
+e10-cli icon check Icon-N-Deleted     # ✅ 已存在（已删除）
+e10-cli icon search 删除               # 按名称/中文名搜索（7438 个）
+```
+
+错名会直接停止保存；确认目标环境确实有该图标（目录未覆盖的自定义图标）时可加 `--force-icon` 跳过校验。图片地址（`/…`、`http(s)://…`、`data:…`）不参与图标名校验。
+
 ### 数据过滤
 
 按钮的「数据过滤」决定**列表里哪些行**受该按钮影响，条件语法与 `form list-filter` **完全一致**：
@@ -147,13 +159,22 @@ e10-cli form button action <objId> <appId> <buttonId> --clear     # 清空自定
 | 确认框 | `--add-confirm --confirm-title <标题> --confirm-content <正文> [--confirm-true <文案>] [--confirm-false <文案>]` |
 | JavaScript | `--add-js --code <源码\|@文件>` |
 | 编辑字段值 | `--add-edit-field "字段:值"`（可多个；字段写 fieldId 或字段标题） |
+| 评论和日志 | `--add-reply` |
+| 查看日志 | `--add-view-logs [--log-types 1,2,3,4]` |
+| 关闭页面 | `--add-close-page` |
+| 扫描上传 | `--add-scan-upload` |
 | 触发逻辑流 | `--add-logic <逻辑流名或ID> [--logic-ecode-id <id>]` |
 
 `--open-type` 管打开方式：`1` 弹窗 / `2` 当前页 / `3` 新窗口。
 
+`--execute-selected` 把本次新增/合并的动作设为「按勾选数据执行」（`executeSelectedDatas=1`），用于批量按钮；「打开页面」动作不适用。它只作用于本次新增的动作，不改按钮上已有的老动作。
+
+`--log-types` 对应查看日志的记录类型：`1` 查阅情况 / `2` 操作日志 / `3` 表单修改日志 / `4` 打印日志；可写数字或中文名，缺省全部四种。
+
 ### 使用说明与边界
 
-- **编辑字段值**本轮只支持「赋固定值」。同一次命令里多次 `--add-edit-field` 会并进同一条动作（按字段去重，同字段后写的覆盖先写的）；按钮上已有该动作时会并入它，不会多出一条。
+- **编辑字段值**本轮只支持「赋固定值」。同一次命令里多次 `--add-edit-field` 会并进同一条动作（按字段去重，同字段后写的覆盖先写的）；按钮上已有该动作时会并入它，不会多出一条，且保留该动作原有的执行方式/日志等设置。
+- **选项字段（Select / RadioBox / CheckBox）**的值可以写选项名，也可以写 valueKey；命令会读字段选项并同时写入 `content` 与 `value`（valueKey）。只写选项名不写 valueKey 时平台不报错，但运行时是空值，因此解析不到选项会直接报错并列出可选值。多选字段支持 `"A,B"` 或 JSON 数组 `'["A","B"]'`；选项名本身带逗号时用 JSON 数组。
 - **触发逻辑流**只做绑定，**不生成**逻辑流。按名称解析要求精确同名，撞名报错并列出候选。`ecodeId` 可用 `--logic-ecode-id` 指定；不给时沿用该按钮上已有的绑定值，都没有则留空。
 - **JavaScript** 源码建议用 `--code @文件` 传入，避免命令行转义把脚本弄坏。
 - `action-set` 是早期只支持单一打开页面动作的命令，**已标记废弃**，等价于 `action --clear --add-view …`；仍可用，但新需求请用 `form button action`。

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

@@ -150,27 +150,37 @@ e10-cli form permission data update <objId> <appId> --right-id <id> \
 
 ## 导入导出权限
 
-导入导出是**独立分类**（`data_imp_exp`），不在共享权限里。命令：
+导入导出是**独立分类**，不在共享权限里；授权对象分两类：通用对象 `data_imp_exp`、矩阵相关 `data_imp_exp_matrix`。
 
 ```bash
 e10-cli form permission imp-exp list <objId> <appId>
 
+# 通用对象
 e10-cli form permission imp-exp add <objId> <appId> \
-  --org-type <类型> [--org-id <id>] \
+  --target general --org-type <类型> [--org-id <id>] \
   --rights export import delete-import \
   [--update-import] [--export-details] [--export-attachment] \
   [--export-field-range listShowField|allField]
 
+# 矩阵相关（真矩阵 / e-Builder 表单）
+e10-cli form permission imp-exp add <objId> <appId> \
+  --target matrix --matrix <矩阵id或名称> \
+  [--matrix-value <取值字段>...] [--matrix-condition-raw <JSON>] \
+  --rights export import
+
+# 改/看
 e10-cli form permission imp-exp update <objId> <appId> --right-id <id> [要改的项]
 e10-cli form permission imp-exp show <objId> <appId> --right-id <id>
 ```
 
 - `rights`：`export=8` 导出、`import=9` 导入、`delete-import=93` 删除导入数据；93 必须与 9 同选。
 - `--update-import`：允许更新导入（`importType` 加 1）；勾 93 时自动带更新导入。
-- 授权对象与共享权限同一套 11 种通用对象（含兼职岗位、职级、外部联系人、所有外部联系人）。
+- `--target`：`general` 通用对象（默认）/ `matrix` 矩阵相关。未给 `--target` 时，带 `--matrix`/`--eb-form`/`--matrix-value*` 等矩阵选项会自动按矩阵处理。
+- 通用对象与共享权限同一套 11 种对象（含兼职岗位、职级、外部联系人、所有外部联系人）。
+- 矩阵相关：`--matrix` 真矩阵、`--eb-form` e-Builder 表单；`--matrix-value` 指定取值字段（名称或 `id:名称:valueType`），缺省取矩阵第一个可用取值字段（e-Builder 表单优先「创建者」）；`--matrix-value-raw` / `--matrix-condition-raw` 为原始 JSON 兜底。矩阵类不能用 `--org-type/--org-id/--org-name`。
 - `--export-field-range`：`listShowField` 列表显示字段（默认）/ `allField` 全部字段。
 - `--export-details` / `--export-attachment`：导出明细、导出附件。
-- 修改只改点名项，整行回写并回读。
+- 修改只改点名项，整行回写并回读。`update` 可切换通用/矩阵：切到通用必须给 `--org-type`；只改权限项不给矩阵选项时沿用当前矩阵来源与条件。矩阵取值字段与条件按语义回读（临时 id / 条件节点 key 不同不算失败）。
 
 导入导出权限**不提供**权限描述、更新导入校验数据编辑权限、导入关联布局、优先级、同步至其他表单这些配置参数。