weaver-e10-builder 1.6.5 → 1.6.6

package/skill-docs/actionflows/SKILL.md

@@ -33,6 +33,8 @@ description: "将业务需求编译为 Weaver ESB 动作流，或读取已有动
 
 - 流程：`e10-cli actionflow workflow-browser-list` / `workflow-search` / `workflow-nodes`。
 - 流程动态字段：`e10-cli actionflow workflow-context-fields`。默认每页 20 条；按需求字段名先传 `query`（例如 `{"workflowId":"<id>","query":"数据ID"}`），只使用本次返回的 `fields[].paramKey`。完整响应过大时用 `--out context.json` 落盘，禁止依赖终端截断后的片段。
+- 其他组件动态字段：`e10-cli actionflow component-context-fields '{"componentType":"<组件类型>","currentApplication":"<当前动作流ID；新建传0>","eventNodeId":"<上游节点ID>","params":{...},"query":"<字段名或关键词>"}'`。该命令会先解析数据源 Browser，再查询 `showDataSourceFields` 匹配实际可选输出字段，随后编译组件上下文并调用 `getComponentContext`。`EnquiryForm`、`TimeBatchTrigger`、`DateTrigger` 都适用。**必须在写入任何动态赋值前查询来源组件**；只允许从本次 `getComponentContext` 结果选择 `fields[].paramKey`，接口未返回的字段必须先查明该组件是否有受支持的依据值/循环语义，否则停止该映射，不得凭字段名、约定根节点或历史经验补造。
+- 计划按执行顺序构造时，先查询触发器，再逐个查询会提供动态数据的上游动作；每一步都用该组件本次真实参数（尤其数据源、目标表和选中的字段）查询。下游映射只能选择已查询来源返回的字段。`generate` 的预检是最后一道校验，不可代替生成前的字段发现。
 - e-builder（**已知表名时首选**）：`e10-cli actionflow form-search '{"keyword":"<表名>"}'` 一次拿到表单 `objId` 与它所属的业务应用 `appId`。服务端是**子串模糊匹配**，同名表跨多个应用很常见（返回体里的 `完全同名` 即同名条数）—— **多于一条时必须按 `appName` 收窄再取**，不得自行挑一个：`'{"keyword":"<表名>","appName":"<应用名>"}'`。`keyword` 传 `objId` 则是精确命中，可用来由 id 反查所属应用。
   - **`appName` 走服务端过滤**（不是本地二次筛）：应用名精确唯一才用；**同名多命中或查无此名会直接报错并列出候选**，此时改用 `appId` 指定，不要换个近似名重试。
   - **返回体 `total` 是服务端在该筛选下的命中总数，`hits` 可能只是其中一部分。** 默认最多返回 100 条，超出时 `truncated: true` 并给出 `omitted`（未返回条数）。**`truncated` 为真时绝不能判定「表单不存在」** —— 先按 `appName` 收窄，确需全部再传 `{"max":0}`（条数大时用 `--out <file>` 落盘）。判断是否唯一命中以 `唯一命中` 字段为准，不要自己数 `hits` 长度。
@@ -53,7 +55,7 @@ description: "将业务需求编译为 Weaver ESB 动作流，或读取已有动
 5. 不把 `Output` 写入 `actions`。需要配置终止状态、提示或页面动作时使用顶层 `finalOutput.params`；提醒内容使用前端富文本组件对应的 `reminderContent`（`ContestSettingDTO`，动态片段放在 `formulaBeans`），不要使用旧的 `reminderMsgFormula`。流程触发（`ApproveTrigger`）只支持提醒，不支持页面交互、页面动作或跳转地址；页面动作仅可用于 `EventButton`。平台内部 FormulaBean 由 CLI 生成，只有组件契约明确要求前端原对象时才传原生 DTO。
 5.1. 所有 CLI 生成或继续编译的 FormulaBean，只要包含 `frontId`，允许使用空串；非空时必须使用平台真实字段 ID 的纯数字字符串。`field_<数字>` 仅可在生成时规范化为 `<数字>`。禁止把字段名、paramKey 尾段、临时公式 ID 或其他包含字母/符号的值写入 `frontId`；非空值无法解析为纯数字时必须直接报错。
 6. 定时组件优先使用平台原生频率：`rate=1` 一次、`2` 按小时、`3` 按日、`4` 按周、`5` 按月，并按需提供 `cycle`、`hour`、`day`、`week`、`atWeek`、`atWeekDetail` 或 `lastWeek`；只有明确选择 `rate=6` 时才传 `cornString`。图形化频率必须提供 `startTime`。
-7. 触发器或查询组件未被需求明确限制输出字段时，不传 `queryFields`（或传空数组）：CLI 会默认全选，包含“数据ID”。如果需求明确引用某个业务字段，必须从当前租户的实时字段接口/字段选择器获取完整字段对象并保存真实 `id`，不能凭字段名、临时 ID 或只拼 `id/content`。查询节点还必须使用自身真实节点 ID 作为 `dataSource.enquiryId`，否则平台可能静默丢弃业务字段。正式回读必须确认每个声明的 `queryFields` 仍存在；缺失即生成失败，不能仅凭接口 `code=200`、`saved=true` 判定成功。e-builder 数据触发后发送消息且未显式给链接时，CLI 自动补 PC/移动端当前记录详情链接；不手写 `{formId}` / `{dataId}` 的 FormulaBean。查询结果字段动态赋值必须按手工设计器对象编译：普通业务字段使用 `FormField.<查询表单ID>.field_<真实字段ID>`，`config.paramKey` 使用 `<查询表单ID>.field_<真实字段ID>`，`config.fieldInfo.tablePrimaryKey` 为 `FormField`；系统字段按平台真实字段键（例如 `id`）保留。禁止使用 `FormData.<表单ID>[临时位置]...`，也禁止把临时公式 ID 当作 `frontId`。
+7. `EnquiryForm`、`TimeBatchTrigger`、`DateTrigger` 的 `queryFields` 会裁剪 `getComponentContext` 返回的动态上下文。字段必须来自当前租户的 `showDataSourceFields` 完整字段对象；若后续动态赋值引用了其中字段，预检会按真实字段 ID 匹配并把它并入 `queryFields`，匹配不到就报错，不能按名称或路径尾段造字段。未明确限制输出字段时不传 `queryFields`（或传空数组），CLI 默认全选。查询节点还必须使用自身真实节点 ID 作为 `dataSource.enquiryId`，否则平台可能静默丢弃业务字段。正式回读必须确认每个声明的 `queryFields` 仍存在；缺失即生成失败，不能仅凭接口 `code=200`、`saved=true` 判定成功。e-builder 数据触发后发送消息且未显式给链接时，CLI 自动补 PC/移动端当前记录详情链接；不手写 `{formId}` / `{dataId}` 的 FormulaBean。查询结果字段动态赋值必须按手工设计器对象编译：普通业务字段使用 `FormField.<查询表单ID>.field_<真实字段ID>`，`config.paramKey` 使用 `<查询表单ID>.field_<真实字段ID>`，`config.fieldInfo.tablePrimaryKey` 为 `FormField`；系统字段按平台真实字段键（例如 `id`）保留。禁止使用 `FormData.<表单ID>[临时位置]...`，也禁止把临时公式 ID 当作 `frontId`。
 8. `ActionEbAdd` 批量新增以 `basisValue` 为明细行上下文：来源于该行的字段都用 `mapping`，编译为“依据值下级”（`switchType:"sub"`），下拉字段也同样处理。只有已核实来源/目标选项 ID 不同且语义需要转换时，才使用 `SWITCH`。关联 e-builder 字段应引用查询结果的 `数据ID`，固定格式为 `{target,kind:"query_result",source:"<EnquiryForm ref>",formId,fieldId:"id",index:0}`；`kind:"enquiry"`、`sourceId` 等旧写法会直接报错，绝不降级为空固定值。
 9. 动态赋值可使用或新建动作流变量、租户常量：已有资源必须用真实 ID；计划新建变量写顶层 `variables[]`，新建常量写 `constantDefinitions[]`，常量分组可传 `groupPk` 或 `groupName`。变量按当前 `applicationId + sceneId` 隔离，常量按分组跨动作流复用。生成时先调用真实接口创建/解析资源，再编译为变量 `type:"7"` 或常量 `type:"5"` FormulaBean；详细格式见 `references/dynamic_resources.md`。消息 `SendMessage.msgTitlev/msgContentv/picLink/msgPcLink/msgMobileLink` 的 `parts` 支持 `variable`/`constant` 动态片段，并统一保存为 `ContestSettingDTO`。
 9.1. 每个参数先分为“动态公式属性”“动态人员属性”“固定平台资源属性”三类：上下文、系统变量、变量、常量、函数/公式必须保留为 FormulaBean；动态人员必须使用真实人员字段上下文或系统变量，不得把引用里的 `id` 当人员 Browser ID 查询；工作流、文档目录、按钮、规则等平台资源只有在其组件契约明确提供动态引用时才允许动态化。生成前必须记录本次组件/属性的判定，生成后按属性检查回读结果；具体映射和验证状态见 `references/dynamic_capability_matrix.md`。
@@ -120,13 +122,17 @@ e10-cli actionflow generate '{"planFile":"@...","mode":"stash"}'
 e10-cli actionflow application-list '{"name":"动作流名称"}'              # 先发现动作流应用，再用唯一结果的精确 appId
 e10-cli actionflow application-categories '{"name":"类别名称"}'          # 查询动作流类别
 e10-cli actionflow application-update '{"appId":"动作流ID","name":"新名称","categoryId":"类别ID","description":"描述"}' # 只传需要修改的字段；categoryId 为 0 时清空类别
+e10-cli actionflow execution-setting-get '{"appId":"动作流ID"}'        # 查看动作流执行设置
+e10-cli actionflow execution-setting-set '{"appId":"动作流ID","actuator":"main","controlMode":"max","concurrentNum":5,"maxExecuteTimeout":100,"memoryKb":2048,"streamlineFlag":true,"reminders":[{"configType":1,"enabled":true,"remindType":"1","remindUser":[{"id":"人员ID","name":"姓名"}]}]}' # 只修改传入项；内存单位 KB
 e10-cli actionflow activate-version '{"appId":"动作流ID","sceneId":"版本场景ID"}' # 只切换默认打开版本，不改变启用状态
 e10-cli actionflow enable '{"appId":"动作流ID"}'                         # 单独启用，不修改设计、不创建版本
 e10-cli actionflow disable '{"appId":"动作流ID"}'                        # 单独禁用，不修改设计、不创建版本
 e10-cli actionflow update '@update-plan.json' --out update-result.json       # 读取后按原 ID 保留式修改；一次保存，失败停止
 ```
 
-常用发现命令：`form-search`、`form-applications`、`form-list`、`form-fields`、`workflow-browser-list`、`workflow-search`、`workflow-nodes`、`workflow-context-fields`、`recipient-search`、`document-statuses`、`hrm-onboarding-fields`、`variable-list`、`variable-create`、`constant-list`、`constant-group-list`、`constant-group-create`、`constant-create`、`http-connectors`、`http-resources`、`http-interfaces`、`http-interface-detail`、`application-list`、`design-versions`、`read-stash`。变量/常量计划定义和引用见 `references/dynamic_resources.md`。
+常用发现命令：`form-search`、`form-applications`、`form-list`、`form-fields`、`workflow-browser-list`、`workflow-search`、`workflow-nodes`、`workflow-context-fields`、`component-context-fields`、`recipient-search`、`document-statuses`、`hrm-onboarding-fields`、`variable-list`、`variable-create`、`constant-list`、`constant-group-list`、`constant-group-create`、`constant-create`、`http-connectors`、`http-resources`、`http-interfaces`、`http-interface-detail`、`application-list`、`design-versions`、`read-stash`。变量/常量计划定义和引用见 `references/dynamic_resources.md`。
+
+执行设置支持 `actuator`（`main` 主执行器 / `low` 慢速执行器）、`controlMode`（`max` 高并发 / `low` 低并发）、`concurrentNum`、`maxExecuteTimeout`（秒）、`maxCycleTimes`、`maxQueryNum`、`memoryKb`（KB）、`streamlineFlag`（布尔值或 0/1）及 `reminders`。提醒 `configType` 1–6 依次为执行失败、执行异常、执行超时、输出失败、其他状态、动作流受影响；每项可传 `enabled`、`remindType`（1 手动选择 / 2 动作流创建人 / 3 维护权限对象）和 `remindUser:[{id,name}]`。提醒数组只 patch 指定类型，其余提醒保留。
 
 ## 触发器边界
 

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

@@ -4,7 +4,7 @@
 
 ## 1. 「数据ID」paramKey 格式因触发器而异（最关键）
 
-「按数据ID更新/引用当前数据」场景中，数据ID 字段的 paramKey **不是统一的 `{formId}.id`**，三种触发器各不相同：
+「按数据ID更新/引用当前数据」场景中，paramKey 随触发器和租户返回的上下文而异。下表只记录曾见过的形式，**不得作为生成依据**：
 
 | 触发器 | 数据ID 的 paramKey | 说明 |
 |---|---|---|
@@ -12,15 +12,15 @@
 | `DateTrigger` | `dataResponse.id` | 前缀是 `dataResponse.`，不是表单 id |
 | `EventFormData` | `{formId}.5` | **数据ID 是数字 `5`，不是 `.id`！** 极易踩坑 |
 
-生成 plan 时，`mapping` 源侧引用「数据ID」必须按上表写真实 paramKey，否则 preflight 的源字段校验会报「源字段 paramKey 未在真实上下文中找到」。
+生成 plan 时必须先实际查询当前触发器的上下文；上表中的历史形式不能替代当前接口响应。`mapping` 源侧仅能使用本次 `getComponentContext` 返回的 `paramKey`。
 
-> 最稳妥的做法：先跑 `workflow-context-fields` 查该触发器在当前数据源下的真实上下文，从返回里确认「数据ID」的精确 paramKey，再写入 plan，不要凭记忆猜格式。
+`ApproveTrigger` 使用 `workflow-context-fields`。其他触发器使用 `component-context-fields`，传入真实组件参数和当前动作流 ID（新建流程传 `0`）；接口没有返回该字段时，不得按表格补造。
 
-## 2. queryFields 需包含系统字段
+## 2. queryFields 的可用输出必须经上下文接口确认
 
-定时/批量/日期触发器的 `queryFields` 全选时，除了业务字段，还必须包含**平台系统字段**（数据ID / 标题 / 创建者 / 创建时间 等 9 个）。否则 `getComponentContext` 返回的上下文中**缺少「数据ID」**，导致「按数据ID更新」引用失败。
+定时/批量/日期触发器的可用字段以 `getComponentContext` 当前响应为准。是否包含数据 ID、系统字段或业务字段都必须从响应核对；`queryFields` 配置或字段选择器的结果不能代替上下文查询结果。
 
-系统字段的 `id` 是英文字符串（`id`/`name`/`creator`/`createTime`/`lastUpdateTime`/`lastUpdater`/`dataStatus`/`myTag`/`publicTag`），`content` 是中文名。宿主 agent 侧无需手动列全，但需知晓：**数据ID 属于系统字段，不随业务字段自动出现**。
+系统字段的显示名、ID 和是否出现在当前上下文都以接口响应为准；不要仅凭字段选择器或既有字段清单推断。
 
 ## 3. 动态人员引用用 `context`，不要用 `{userid}`
 

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

@@ -448,18 +448,19 @@
 
 | 命令 | 说明 |
 |------|------|
-| `e10-cli menu list <appId>` | 列出当前Ebuilder应用下的菜单。**递归展开嵌套菜单**（如「设置 → 个人设置 → 个人菜单设置」），列表即全量 —— 在这里没找到就是真没有，不必再怀疑被折叠。`--raw [菜单ID]` 打印菜单的**原始报文**（读侧记录与写侧报文形状不同，核对某一项到底存了什么时看它） |
-| `e10-cli menu rename <appId> <菜单ID或名称> <新名>` | 重命名已有菜单（含嵌套菜单）。名称在应用内重复时必须改用 ID，命令会列出候选让你选。平台系统菜单（回收站/设置等）不能改。**改父级用 `menu move`** |
-| `e10-cli menu add <name> <path> <appId> [--parent <父菜单ID或名称>] [--first\|--show-order <n>]` | 将页面加入左侧导航（LINK 类型，URL path）。ecode 页面 path 如 `/sp/custom/ecode/project-list`。**表单台账/流程发起菜单用下面两条专用命令**（VIEWPORT/LAYOUT 类型，非 URL）。`--parent` 挂到父菜单下做子菜单（缺省 `0`=顶级）。**排序**：平台按同级 `showOrder` 升序显示，新建默认 1（落在最后）；`--first` 排到同级最前，`--show-order <n>` 指定任意排序号。**建完会回读确认**菜单 ID、层级与排序；回读不到就报错退出，不谎报成功 |
-| `e10-cli menu add-dir <appId> <name> [--parent <父菜单ID或名称>] [--first\|--show-order <n>]` | 加**上级目录**菜单 —— **空链接**的纯分类节点，只用来给子菜单分组，点它不跳页面。设计器里建「上级目录」就是这个（存下来 `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或名称>] [--first\|--show-order <n>]` | 给表单加**台账菜单**（VIEWPORT，指向数据列表页）。`form create --menu` 才自动加（默认不加），此处用于事后补加。**`--parent` 挂到某个父菜单下做子菜单**（缺省 `0`=顶级；既收菜单 ID 也收名称，同名多条会报错并列 ID），`--first`/`--show-order` 控制同级顺序。**建完回读确认**，并**核对层级与排序** —— 只确认菜单存在不够，`pid` / `showOrder` 没生效时菜单照样建出来、只是跑到顶级或最后 |
-| `e10-cli menu add-start <appId> <formObjId> [name] [--parent <父菜单ID或名称>] [--first\|--show-order <n>]` | 给流程绑定的表单加**发起菜单**（LAYOUT，指向表单新建页，点开触发流程）。`workflow create --menu` 才自动加（默认不加）。`--parent` / 排序参数同上。**建完回读确认**并核对层级与排序 |
-| `e10-cli menu order <appId> <menu> [--first\|--show-order <n>]` | **调整已有菜单在同级里的顺序**（不改父级）。`--first` 排到同级最前（排序号取同级非系统菜单最小值 - 1）；`--show-order <n>` 直接指定整数排序号，越小越靠前。改完回读 `showOrder` 与同级位置，并确认名字/页面/链接等其它字段没被改动。系统菜单（设置/回收站）拒绝调整 |
-| `e10-cli menu move <appId> <menu> --parent <父菜单ID或名称> [--first\|--show-order <n>]` | **把已有菜单移动到另一个父级下**（名称、页面不变）。`--parent 0` 移到顶级；可同时用 `--first` / `--show-order <n>` 调整在新同级里的顺序。拒绝系统菜单、拒绝移到自身或自己的子菜单下（防成环）；已在目标父级且排序未变时提示无需移动。写 `savePublishMenu` 的 `pid`，回读父级、排序与同级位置，并确认其它字段未被改动 |
+| `e10-cli menu list <appId> [--terminal pc\|mobile]` | 列出当前Ebuilder应用下的菜单。**递归展开嵌套菜单**（如「设置 → 个人设置 → 个人菜单设置」），列表即全量 —— 在这里没找到就是真没有，不必再怀疑被折叠。`--raw [菜单ID]` 打印菜单的**原始报文**（读侧记录与写侧报文形状不同，核对某一项到底存了什么时看它）。PC 与移动端是**两套独立菜单**，移动端要加 `--terminal mobile` |
+| `e10-cli menu rename <appId> <菜单ID或名称> <新名> [--terminal pc\|mobile]` | 重命名已有菜单（含嵌套菜单）。名称在应用内重复时必须改用 ID，命令会列出候选让你选。平台系统菜单（回收站/设置等）不能改。**改父级用 `menu move`**；**改打开方式用 `menu open-mode`** |
+| `e10-cli menu add <name> <path> <appId> [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile]` | 将页面加入左侧导航（LINK 类型，URL path）。ecode 页面 path 如 `/sp/custom/ecode/project-list`。**表单台账/流程发起菜单用下面两条专用命令**（VIEWPORT/LAYOUT 类型，非 URL）。`--parent` 挂到父菜单下做子菜单（缺省 `0`=顶级）。**排序**：平台按同级 `showOrder` 升序显示，新建默认 1（落在最后）；`--first` 排到同级最前，`--show-order <n>` 指定任意排序号。**打开方式**：缺省「默认窗口」，`--open-mode new-window` 点击后在新窗口打开。**建完会回读确认**菜单 ID、层级、排序与打开方式；回读不到就报错退出，不谎报成功 |
+| `e10-cli menu add-dir <appId> <name> [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--terminal pc\|mobile]` | 加**上级目录**菜单 —— **空链接**的纯分类节点，只用来给子菜单分组，点它不跳页面。设计器里建「上级目录」就是这个（存下来 `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或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile]` | 给表单加**台账菜单**（VIEWPORT，指向数据列表页）。`form create --menu` 才自动加（默认不加），此处用于事后补加。**`--parent` 挂到某个父菜单下做子菜单**（缺省 `0`=顶级；既收菜单 ID 也收名称，同名多条会报错并列 ID），`--first`/`--show-order` 控制同级顺序，`--open-mode` 选打开方式。**建完回读确认**，并**核对层级与排序** —— 只确认菜单存在不够，`pid` / `showOrder` 没生效时菜单照样建出来、只是跑到顶级或最后 |
+| `e10-cli menu add-start <appId> <formObjId> [name] [--parent <父菜单ID或名称>] [--first\|--show-order <n>] [--open-mode default\|new-window] [--terminal pc\|mobile]` | 给流程绑定的表单加**发起菜单**（LAYOUT，指向表单新建页，点开触发流程）。`workflow create --menu` 才自动加（默认不加）。`--parent` / 排序参数同上，`--open-mode` 选打开方式。**建完回读确认**并核对层级与排序 |
+| `e10-cli menu open-mode <appId> <menu> <default\|new-window> [--terminal pc\|mobile]` | **改已有菜单的打开方式**：`default`=默认窗口、`new-window`=新窗口。只改这一项，改完回读打开方式，并确认名字/页面/链接等其它字段未被改动。系统菜单与上级目录（无页面）拒绝设置 |
+| `e10-cli menu order <appId> <menu> [--first\|--show-order <n>] [--terminal pc\|mobile]` | **调整已有菜单在同级里的顺序**（不改父级）。`--first` 排到同级最前（排序号取同级非系统菜单最小值 - 1）；`--show-order <n>` 直接指定整数排序号，越小越靠前。改完回读 `showOrder` 与同级位置，并确认名字/页面/链接等其它字段没被改动。系统菜单（设置/回收站）拒绝调整 |
+| `e10-cli menu move <appId> <menu> --parent <父菜单ID或名称> [--first\|--show-order <n>] [--terminal pc\|mobile]` | **把已有菜单移动到另一个父级下**（名称、页面不变）。`--parent 0` 移到顶级；可同时用 `--first` / `--show-order <n>` 调整在新同级里的顺序。拒绝系统菜单、拒绝移到自身或自己的子菜单下（防成环）；已在目标父级且排序未变时提示无需移动。写 `savePublishMenu` 的 `pid`，回读父级、排序与同级位置，并确认其它字段未被改动 |
 | ↳ 搭「父菜单 + 子菜单」 | 设计器里的二级菜单 = 先建父菜单（**纯分组用 `menu add-dir`**；父菜单自己也要指向某页才用 `menu add`），再把台账/发起菜单用 `--parent <父菜单>` 挂上去。父菜单 ID 从 `menu list` 拿（输出就是完整菜单树）。新建的子菜单默认排在同级最后；要放第一个加 `--first`，已建好的用 `menu order <appId> <menu> --first` |
-| `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`） |
+| `e10-cli menu permission list <appId> <menuId>` | 列菜单可见范围，**分「可见」与「可见范围内禁用」两栏**输出（可见栏为空 = 默认所有人可见）。授权对象支持人员 / 部门 / 角色 / 岗位 / 所有人 |
+| `e10-cli menu permission add <appId> <menuId> <目标> --type role\|dept\|user\|position\|all [--scope visible\|disabled]` | 给菜单授权。`--scope` 缺省 `visible`（可见栏）：**加角色/人/部门后自动撤「所有人」→ 只有授权对象可见**；`--keep-all` 保留所有人；`--type all` 恢复"所有人可见"。`--scope disabled` 加到「可见范围内禁用」栏（在可见人群里排除这些对象），不触发收窄。写入后回读该栏确认 |
+| `e10-cli menu permission remove <appId> <menuId> <目标> --type role\|dept\|user\|all [--scope visible\|disabled]` | 撤销菜单授权（撤销所有人用 `--type all`）。不给 `--scope` 时先找可见栏、找不到再找禁用栏；撤销后回读确认该行已消失 |
 | `e10-cli menu delete <menuId> <appId>` | 删除菜单项 |
 
 ---

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

@@ -2,7 +2,8 @@
 
 通过 `savePublishMenu` API 挂载系统内置页面到应用菜单。menuUrl 格式固定，禁止瞎编。
 
-> **暂不支持 H5/移动端菜单**。移动端是独立体系（不同 URL + 不同 pageId），目前尚未整理完整，禁止 AI 自行编造。
+> **移动端菜单是另一套记录**：同一个 `savePublishMenu` 接口，只把 `terminalType` 换成 `H5`；页面绑定与 `menuUrl` 与 PC 相同。菜单命令统一用 `--terminal mobile` 指定移动端（缺省 PC），两端互不影响。
+> 移动端**内置系统页**的 URL 尚未整理，不要自行编造。
 
 ---
 
@@ -85,3 +86,45 @@
 - 已建好的菜单调整：`e10-cli menu order <appId> <菜单ID或名称> --first`，或 `--show-order <n>`。
 
 命令在写完会回读：`showOrder` 必须落成请求值；`--first` 还会确认同级下标为 0。系统菜单不允许调整顺序。
+
+---
+
+## 打开方式
+
+菜单点击后在哪儿打开，由 `navigation.openMode` 决定：
+
+| 界面选项 | 值 |
+|---|---|
+| 默认窗口（缺省） | `1` |
+| 新窗口 | `2` |
+
+- 新建时指定：`menu add / add-table / add-start`、`page publish-menu` 加 `--open-mode new-window`。
+- 已建好的菜单：`e10-cli menu open-mode <appId> <菜单ID或名称> new-window`（改回用 `default`）。
+- 上级目录（空链接）没有页面，设置打开方式没有意义，命令会拒绝。
+- 改完回读打开方式，并确认名字、页面、链接等其它字段一个都没动。
+
+---
+
+## 可见范围（两栏）
+
+「可见范围」弹窗其实是**两栏**，各自一套授权对象：
+
+| 界面栏位 | 存储差异 |
+|---|---|
+| 可见 | `permissionType = 1` |
+| 可见范围内禁用 | `permissionType = -1` |
+
+两栏的写报文除这个字段外完全相同，所以命令必须显式分清栏位：
+
+```bash
+# 只让某部门可见（自动撤掉「所有人」）
+e10-cli menu permission add <appId> <menuId> 营销部 --type dept
+
+# 在可见人群里排除某人
+e10-cli menu permission add <appId> <menuId> 张三 --type user --scope disabled
+
+# 查看两栏
+e10-cli menu permission list <appId> <menuId>
+```
+
+授权对象五类：人员 `user` / 部门 `dept` / 角色 `role` / 岗位 `position` / 所有人 `all`。命令写完回读**同一栏**确认生效。