@microi.net/cli 5.1.7 → 5.1.9

package/skills/module-engine/SKILL.md

@@ -1,182 +1,186 @@
----
-name: module-engine
-description: Microi 模块引擎与 sys_menu 配置指南。用于创建或修改后台菜单、菜单统计角标、模块标题指标、复合列表列、移动端业务卡片、查询列、接口替换、跨端 ViewSchema、动态按钮、PageTabs、树形加表格布局和 MicroService 菜单。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi 模块引擎
-
-模块引擎决定同一张表在某个菜单、角色和终端中“如何查询、展示和操作”。
-配置实体是 `sys_menu`，不是 `sys_module`；表结构与字段仍属于
-`diy_table/diy_field`。
-
-## 必读参考
-
-- 字段、打开方式、查询配置、ViewSchema 和接口替换：
-  `references/module-config.md`
-- 动态按钮 JSON 与后台任务：`../v8-menu-buttons/SKILL.md`
-- 树形+表格：`../microi-left-right-layout/SKILL.md`
-- 表单控件：`../microi-form-engine/SKILL.md`
-- 表单平铺、CollapseGroup 与 Tabs 决策：`../microi-form-layout/SKILL.md`
-- MicroService 菜单：`../microi-microservice/SKILL.md`
-
-## 创建/修改标准流程
-
-1. `microi_get_db_schema` 读取真实 `diy_table`、字段、已有菜单和父菜单。
-2. 绑定表的菜单使用 `microi_create_module`/Manifest，不直接写 `sys_menu`。
-3. 明确 `openType`、父菜单、路由、PC/移动端显隐和角色范围。
-4. 用字段名配置 `listFields/searchFields/sortFields/hiddenFields/mobileFields`；
-   MCP 解析为字段 Id 和 `SelectFields/SearchFieldIds/...`。
-5. 同一次创建配齐业务按钮、FormBtns、PageTabs 和批量按钮。
-6. 写后回读模块，检查字段映射、按钮 JSON、路由和目标页面。
-
-### 新模块表单打开方式（强制默认）
-
-- AI 新建 `diy_table` / 业务模块时，`FormOpenType` 默认写 `Dialog`，`FormOpenWidth`
-  默认写 `80%`；缺省值也必须按这组语义处理，不能再把所有模块统一生成为 Drawer。
-- 只有表单确实非常庞大时才使用 `Drawer`：通常是 36 个以上业务字段、至少 2 个
-  `TableChild`、28 个以上字段且含大型子表，或 7 个以上子表/富文本/代码编辑/上传/地图等
-  重型控件。达到阈值仍应先用 `diy_table.Tabs` 与 CollapseGroup 整理信息架构。
-- 用户显式指定 `Dialog/Drawer/Page` 或宽度时以用户配置为准。Drawer 是贴边直角容器；
-  Dialog 使用平台统一大圆角、可拖动、居中弹层，遮罩服从 `sys_config.DisableFormMaskBlur`。
-7. 为管理员/目标角色分配菜单权限，并以真实登录用户验收。
-
-## 绑定表菜单不能只写两个字段
-
-除 `Name` 和 `DiyTableId` 外，至少配置或允许平台推断：
-
-- `TableDiyFieldIds`
-- `SelectFields`
-- `SearchFieldIds`
-- `SortFieldIds`
-- `NotShowFields`
-- `StatisticsFields`
-- `MobileListFields`
-- `CardTitleTagFields`
-- `CardBottomTagFields`
-- `DefaultOrderBy`
-
-普通状态、开关等低基数字段不能机械创建单列索引。只有真实查询、关联、唯一约束
-或扫描需要的索引才进入 Manifest 并通过 MCP 创建、回读。
-
-## AI 模块视觉交付门禁（强制）
-
-对每个 `Display=1` 或 `AppDisplay=1` 且绑定业务表的 Diy 模块，AI 不能只依赖 CRUD
-默认页，也不能只写 `Name/DiyTableId` 后结束。至少完成以下设计和回读：
-
-1. 每个列表字段都给出符合内容长度的 `TableWidth`；标题/名称/地址较宽，日期/编码居中，
-   金额/数量/状态较紧凑。PC 复合列必须另给合理的 `MinWidth`，不得让末列自适应覆盖它。
-2. 每个模块都配置紧凑 Hero 的业务标题、简短副标题和 2~4 个动态指标。优先统计待处理、
-   逾期、金额、容量、风险、完成率等当前表真正有意义的业务数据，不能全部退化为总记录数。
-3. 指标只能来自 `StatisticsFields`、当前列表 `DataCount/PageCount` 或一个批量聚合接口。
-   禁止随机数、伪统计、静态演示数字和没有口径的“看起来好看”数值。无法推断时允许用
-   `DataCount + PageCount` 做诚实最低兜底，并在后续由业务人员补充口径。
-4. 左侧菜单角标只给少量有行动含义的重要菜单，例如待办、未读、逾期、低库存；禁止每个
-   菜单都加。`PageTabs` 的状态数量、`MoreBtns/PageBtns/FormBtns/BatchSelectMoreBtns/
-   ExportMoreBtns` 的有用数量也应设计角标，但同页统计必须批量返回，禁止 N+1。
-5. PC 至少设计一个 `Field + Lines + TrailingFields` 复合主列。已放入次要行或右侧图标/
-   状态的字段必须从普通独立列去重；主字段、次要行、右侧字段及其 `RequiredFields` 都要
-   进入查询结果，宽度必须足以容纳多行和尾随标签。一般情况下每个复合列最多两行，即
-   一个主字段加一个 `Lines` 次要字段；可以配置多个各自两行的复合列，但不要在同一列放
-   两个 `Lines` 形成三行高表格。确有特殊层级价值时才允许三行，并必须完成桌面视觉验收。
-6. 移动端卡片按真实字段规划图片/头像、标题、副标题、顶部标签、状态、右侧金额、正文、
-   Meta、底部区域；同一字段不得在多个区域机械重复，空区域应隐藏而不是留下占位。
-7. `EnableViewSchema` 只控制 Detail/Edit 自定义表单。Hero、指标、列表密度、PC 复合列、
-   移动端卡片只要有配置就始终生效；设计器必须提供独立的“自定义表单”Tab。
-
-平台自动生成的 List/Card 配置只是防止空白界面的最低值，不能替代 AI 对业务状态、金额、
-时效和操作路径的分析。显式配置优先于自动值；写后用 `microi_get_module` 回读 ViewSchema、
-列宽、统计列、卡片区域和角标配置。
-
-## 打开方式
-
-| OpenType | 用途 |
-|---|---|
-| `Diy` | 标准表单引擎列表/表单 |
-| `Component` | 主前端已注册 Vue 组件 |
-| `Iframe` | 受控外部页面 |
-| `SecondMenu` | 仅作为父菜单 |
-| `Report` | 虚拟报表 |
-| `MicroService` | 已发布前端微服务页面 |
-
-Iframe 不把长期 Token、密码或连接串放 URL。第三方单点登录使用短期、一次性、
-可撤销的服务端交换票据，限制 redirect/scope，并在落地后清理地址栏。
-
-## 数据与业务逻辑
-
-- 单表 CRUD 已由绑定表菜单提供，不额外创建重复接口引擎。
-- 后端 V8 可用 `V8.ModuleEngine.GetTableData({...})`，通过
-  `ModuleEngineKey` 应用模块的关联表查询配置；标准前端 V8 不挂载
-  `V8.ModuleEngine`。
-- 查询接口替换、导入/导出替换和跨表动作属于复杂逻辑时，使用接口引擎。
-- 前端按钮只做确认、收集少量参数、调用接口和刷新；事务与最终校验在后端。
-- 预计超过 2 分钟、500 条、1000 个扇出或 100 次外部调用时使用真实后台任务。
-- 不复制官网旧“Redis 文本进度 + 长事务循环”导入示例作为新实现；必须有稳定
-  幂等键、业务任务状态、真实 Current/Total、失败恢复和必要的 checkpoint 分片。
-
-## 跨端 ViewSchema
-
-顶层 PC 数据列表默认使用紧凑的新模块标题样式；即使未启用自定义表单视图，也不能退回无标题的旧外观。无指标头部固定 `44px`、含指标头部固定 `62px`，连同间距总纵向占用约 `50px / 68px`。子表、关联表、嵌入表不重复显示，移动端由固定导航栏承载标题。`Scene=List/Card` 的个性化标题、指标、复合列和卡片配置存在时必须直接生效；`EnableViewSchema` 只控制 Detail/Edit 自定义表单视图。
-
+---
+name: module-engine
+description: Microi 模块引擎与 sys_menu 配置指南。用于创建或修改后台菜单、菜单统计角标、模块标题指标、复合列表列、移动端业务卡片、查询列、接口替换、跨端 ViewSchema、动态按钮、PageTabs、树形加表格布局和 MicroService 菜单。
+---
+
+> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
+
+# Microi 模块引擎
+
+模块引擎决定同一张表在某个菜单、角色和终端中“如何查询、展示和操作”。
+配置实体是 `sys_menu`，不是 `sys_module`；表结构与字段仍属于
+`diy_table/diy_field`。
+
+## 必读参考
+
+- 字段、打开方式、查询配置、ViewSchema 和接口替换：
+  `references/module-config.md`
+- 动态按钮 JSON 与后台任务：`../v8-menu-buttons/SKILL.md`
+- 树形+表格：`../microi-left-right-layout/SKILL.md`
+- 表单控件：`../microi-form-engine/SKILL.md`
+- 表单平铺、CollapseGroup 与 Tabs 决策：`../microi-form-layout/SKILL.md`
+- MicroService 菜单：`../microi-microservice/SKILL.md`
+
+## 创建/修改标准流程
+
+1. `microi_get_db_schema` 读取真实 `diy_table`、字段、已有菜单和父菜单。
+2. 绑定表的菜单使用 `microi_create_module`/Manifest，不直接写 `sys_menu`。
+3. 明确 `openType`、父菜单、路由、PC/移动端显隐和角色范围。
+4. 用字段名配置 `listFields/searchFields/sortFields/hiddenFields/mobileFields`；
+   MCP 解析为字段 Id 和 `SelectFields/SearchFieldIds/...`。
+5. 同一次创建配齐业务按钮、FormBtns、PageTabs 和批量按钮。
+6. 写后回读模块，检查字段映射、按钮 JSON、路由和目标页面。
+
+### 新模块表单打开方式（强制默认）
+
+- AI 新建 `diy_table` / 业务模块时，`FormOpenType` 默认写 `Dialog`，`FormOpenWidth`
+  默认写 `80%`；缺省值也必须按这组语义处理，不能再把所有模块统一生成为 Drawer。
+- 只有表单确实非常庞大时才使用 `Drawer`：通常是 36 个以上业务字段、至少 2 个
+  `TableChild`、28 个以上字段且含大型子表，或 7 个以上子表/富文本/代码编辑/上传/地图等
+  重型控件。达到阈值仍应先用 `diy_table.Tabs` 与 CollapseGroup 整理信息架构。
+- 用户显式指定 `Dialog/Drawer/Page` 或宽度时以用户配置为准。Drawer 是贴边直角容器；
+  Dialog 使用平台统一大圆角、可拖动、居中弹层，遮罩服从正向开关 `sys_config.FormMaskBlur`，缺失或 `0/false` 默认关闭毛玻璃。
+7. 为管理员/目标角色分配菜单权限，并以真实登录用户验收。
+
+## 绑定表菜单不能只写两个字段
+
+除 `Name` 和 `DiyTableId` 外，至少配置或允许平台推断：
+
+- `TableDiyFieldIds`
+- `SelectFields`
+- `SearchFieldIds`
+- `SortFieldIds`
+- `NotShowFields`
+- `StatisticsFields`
+- `MobileListFields`
+- `CardTitleTagFields`
+- `CardBottomTagFields`
+- `DefaultOrderBy`
+
+普通状态、开关等低基数字段不能机械创建单列索引。只有真实查询、关联、唯一约束
+或扫描需要的索引才进入 Manifest 并通过 MCP 创建、回读。
+
+## AI 模块视觉交付门禁（强制）
+
+对每个 `Display=1` 或 `AppDisplay=1` 且绑定业务表的 Diy 模块，AI 不能只依赖 CRUD
+默认页，也不能只写 `Name/DiyTableId` 后结束。至少完成以下设计和回读：
+
+1. 每个列表字段都给出符合内容长度的 `TableWidth`；标题/名称/地址较宽，日期/编码居中，
+   金额/数量/状态较紧凑。PC 复合列必须另给合理的 `MinWidth`，不得让末列自适应覆盖它。
+2. 每个模块都配置紧凑 Hero 的业务标题、简短副标题和 2~4 个动态指标。优先统计待处理、
+   逾期、金额、容量、风险、完成率等当前表真正有意义的业务数据，不能全部退化为总记录数。
+3. 指标只能来自 `StatisticsFields`、当前列表 `DataCount/PageCount` 或一个批量聚合接口。
+   禁止随机数、伪统计、静态演示数字和没有口径的“看起来好看”数值。无法推断时允许用
+   `DataCount + PageCount` 做诚实最低兜底，并在后续由业务人员补充口径。
+4. 左侧菜单角标只给少量有行动含义的重要菜单，例如待办、未读、逾期、低库存；禁止每个
+   菜单都加。`PageTabs` 的状态数量、`MoreBtns/PageBtns/FormBtns/BatchSelectMoreBtns/
+   ExportMoreBtns` 的有用数量也应设计角标，但同页统计必须批量返回，禁止 N+1。
+5. PC 至少设计一个 `Field + Lines + TrailingFields` 复合主列。已放入次要行或右侧图标/
+   状态的字段必须从普通独立列去重；主字段、次要行、右侧字段及其 `RequiredFields` 都要
+   进入查询结果，宽度必须足以容纳多行和尾随标签。一般情况下每个复合列最多两行，即
+   一个主字段加一个 `Lines` 次要字段；可以配置多个各自两行的复合列，但不要在同一列放
+   两个 `Lines` 形成三行高表格。确有特殊层级价值时才允许三行，并必须完成桌面视觉验收。
+6. 移动端卡片按真实字段规划图片/头像、标题、副标题、顶部标签、状态、右侧金额、正文、
+   Meta、底部区域；同一字段不得在多个区域机械重复，空区域应隐藏而不是留下占位。
+7. `EnableViewSchema` 只控制 Detail/Edit 自定义表单。Hero、指标、列表密度、PC 复合列、
+   移动端卡片只要有配置就始终生效；设计器必须提供独立的“自定义表单”Tab。
+
+平台自动生成的 List/Card 配置只是防止空白界面的最低值，不能替代 AI 对业务状态、金额、
+时效和操作路径的分析。显式配置优先于自动值；写后用 `microi_get_module` 回读 ViewSchema、
+列宽、统计列、卡片区域和角标配置。
+
+## 打开方式
+
+| OpenType | 用途 |
+|---|---|
+| `Diy` | 标准表单引擎列表/表单 |
+| `Component` | 主前端已注册 Vue 组件 |
+| `Iframe` | 受控外部页面 |
+| `SecondMenu` | 仅作为父菜单 |
+| `Report` | 虚拟报表 |
+| `MicroService` | 已发布前端微服务页面 |
+
+Iframe 不把长期 Token、密码或连接串放 URL。第三方单点登录使用短期、一次性、
+可撤销的服务端交换票据，限制 redirect/scope，并在落地后清理地址栏。
+
+## 数据与业务逻辑
+
+- 单表 CRUD 已由绑定表菜单提供，不额外创建重复接口引擎。
+- 后端 V8 可用 `V8.ModuleEngine.GetTableData({...})`，通过
+  `ModuleEngineKey` 应用模块的关联表查询配置；标准前端 V8 不挂载
+  `V8.ModuleEngine`。
+- 查询接口替换、导入/导出替换和跨表动作属于复杂逻辑时，使用接口引擎。
+- 前端按钮只做确认、收集少量参数、调用接口和刷新；事务与最终校验在后端。
+- 预计超过 2 分钟、500 条、1000 个扇出或 100 次外部调用时使用真实后台任务。
+- 不复制官网旧“Redis 文本进度 + 长事务循环”导入示例作为新实现；必须有稳定
+  幂等键、业务任务状态、真实 Current/Total、失败恢复和必要的 checkpoint 分片。
+
+## 跨端 ViewSchema
+
+顶层 PC 数据列表默认使用紧凑的新模块标题样式；即使未启用自定义表单视图，也不能退回无标题的旧外观。无指标头部固定 `44px`、含指标头部固定 `62px`，连同间距总纵向占用约 `50px / 68px`。子表、关联表、嵌入表不重复显示，移动端由固定导航栏承载标题。`Scene=List/Card` 的个性化标题、指标、复合列和卡片配置存在时必须直接生效；`EnableViewSchema` 只控制 Detail/Edit 自定义表单视图。
+
 PC 列表的固定结构顺序是“模块 Hero（标题/副标题/动态指标）→ PageTabs → 查询与表格”，Hero 必须渲染在页面多 Tab 上方。头部只使用一次性入场和一次性轻量光效，禁止持续循环动画；`prefers-reduced-motion: reduce` 必须关闭动画和过渡。
 
-`ViewSchema` 是模块级视图，不写入已废弃的通用 `DiyConfig`。优先通过 sys_menu“跨端视图”的 `DiyModulePresentationDesigner` 配置；Detail/Edit 使用独立的“自定义表单视图 JSON”，需要完整协议、角色优先级或未知扩展字段时再使用高级 JSON。启用自定义表单视图后仍须：
-
-- 配置 `EnableViewSchema=1`；`ViewSchemaVersion/ViewConfigVersion` 可为空，分别按 `1.0/1` 处理并在后续变更时递增配置版本。
-- 按 Scene、Device、RoleIds、Priority 选择视图。
-- 配置损坏或客户端不支持时回退标准 `sys_menu + diy_table + diy_field`，不能白屏。
-- 小程序只消费声明式动作，不执行 PC 的任意 `V8Code`。
-- 声明式动作中的 ParamMap/VisibleWhen 只允许白名单字段，不使用 `eval`。
-
-### 重要模块的统计与信息层级
-
-- 待办、库存预警、未读、逾期、待收/待付等有行动含义的菜单，主动询问并配置
-  `MenuBadgeEnabled=1` 与 `MenuBadgeApiEngineKey`。接口统一返回
-  `{ Code:1, Data:{ Value: number } }`，并按当前用户权限统计。
-- `Scene=List` 的 `Layout.Hero` 用 `Eyebrow/Title/Description/Metrics` 建立模块标题与
-  指标条。相同 `ApiEngineKey` 的指标必须由一个聚合接口批量返回，使用 `ValuePath`
-  取值；禁止一个指标一次请求。
-- PC Hero 有指标时采用“左侧标题说明约 25%~30% + 右侧指标区弹性占满”的信息层级，
-  中间只允许一条弱化渐变分隔；指标条容器和单个指标不得叠加多层描边。无指标时标题说明
-  自动占满整行，不保留空指标区。每个指标必须显式配置 `Icon`，并通过不同的 `Tone` 或
-  `Color` 形成可辨识的图标色块与轻背景；同一 Hero 内不得让全部指标使用相同图标和颜色。
-- Hero 指标可用 `Source=DataCount` 读取当前筛选总记录数、用 `Source=PageCount` 读取本页
-  已加载记录数；两者复用列表结果，不调用额外接口。字段汇总继续用 `Field`，跨表或复合
-  统计才用 `ApiEngineKey + ValuePath`。
-- `Layout.List.Columns[]` 用 `Field + Lines + TrailingFields` 配置复合列和右侧图标状态；
-  默认按 `Field + 1 个 Lines` 形成双行，多个信息组应拆成多个双行复合列，避免单列三行
-  抬高整张表。声明支持 `Tone/Color/Icon/ShowLabel/Prefix/Suffix`，引用字段必须进入查询列。
-- `Scene=Card, Device=Mobile` 用 `Layout.Card` 配置 `AvatarTextField/TitleField/TopFields/
-  SubtitleFields/RightFields/Fields/MetaFields/BottomFields`。未配置时继续兼容
-  `MobileListFields/CardTitleTagFields/CardBottomTagFields`。
-- `PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 需要数量时配置
-  `BadgeEnabled/BadgeApiEngineKey`；一个接口接收当前页 `Ids + ButtonKeys` 并一次返回
-  `Data.Buttons` 与 `Data.Rows`，禁止逐行调用。
-- 能直接用字段表达的信息优先配置复合列/卡片字段；只有确需 HTML 样式或组合逻辑时
-  才使用字段的 `V8TmpEngineTable`，且仍需遵守 DOMPurify 和查询字段范围。
-- 存量菜单没有 Hero.Metrics 时，客户端只允许根据真实后端汇总、当前筛选总数、本页加载数
-  和本页真实状态分布生成兜底指标；不得用随机值装饰页面。字段聚合缺少全量口径时必须明确
-  标注“本页”，不能把当前页求和冒充全表汇总。
-
-### 表单布局协同
-
-- `<=6` 个核心可见字段优先平铺；`7~29` 个字段按基础、业务、状态、附件等信息域使用
-  `CollapseGroup`；`30+` 个字段，或存在多个大型子表、扫码/代码编辑等强任务域时使用
-  表级 `diy_table.Tabs`。最终还要按有效表单行校正，避免产生只有少量字段的空洞 Tab。
-- 新增 `Tabs/CollapseGroup/Divider/Alert` 等布局节点必须走明确的“仅元数据”专用路径。
-  普通新增字段接口可能同步对业务表执行物理 DDL，不能把向 `diy_field` 新增一行误认为
-  仅保存布局配置；写入后要同时回读元数据并核对业务表结构未新增实体列。
-
-## 验收
-
-- `Display/AppDisplay` 除明确隐藏外为 1，父子菜单层级正确。
-- 路由刷新、直接访问、切换菜单均不 404/白屏。
-- 列表字段、筛选、排序、统计、移动端卡片与预期一致。
-- 权限用户可访问，未授权用户不能靠 URL、`_SysMenuId` 或前端字段绕过。
-- MoreBtns/FormBtns/PageTabs/BatchSelectMoreBtns 显隐、调用和刷新正确；PageTabs 数字角标使用稳定 Tab Id 取 `Data.Buttons`。
-- 菜单角标、模块指标和按钮角标按真实权限返回，零值/超限/接口失败降级正确且无 N+1。
-- Hero 在有指标、无指标、长标题和 3~5 个指标时均层级清晰；指标无多层线框，同一组图标与
-  语义色可区分，并在浅色/深色主题下保持可读。
-- PC 复合列和 Mobile Card 引用的附加字段均在查询结果中；长文本、空值、模板值不破版。
-- PC 和移动端分别验证；MicroService 还要验证运行时、页面路由和宿主上下文。
+PageTabs 通过 `TargetSysMenuId` 切换不同模块/表时，入口模块必须作为稳定宿主：客户端在同一个 `diy-table` 实例内加载目标模块的菜单、表、字段与列表数据，只更新当前 URL 的 `Tab` 查询参数，不替换路由、面包屑、顶部访问标签或宿主 Hero。入口模块只配置一组 PageTabs；目标菜单可隐藏导航，但只需保留目标表格设计和角色权限，不得复制同一组 PageTabs。切换时必须中止旧请求并以模块上下文版本丢弃迟到响应，失败时回滚原模块。
+
+模块首屏或跨模块切换期间，Hero 标题/指标、PageTabs、工具栏与列表必须显示与最终布局同尺寸的主题化骨架屏；不能先渲染空白旧布局再整体位移。骨架屏同样遵守 `prefers-reduced-motion: reduce`，并在无指标或无 PageTabs 时按元数据提示隐藏对应占位。
+
+`ViewSchema` 是模块级视图，不写入已废弃的通用 `DiyConfig`。优先通过 sys_menu“跨端视图”的 `DiyModulePresentationDesigner` 配置；Detail/Edit 使用独立的“自定义表单视图 JSON”，需要完整协议、角色优先级或未知扩展字段时再使用高级 JSON。启用自定义表单视图后仍须：
+
+- 配置 `EnableViewSchema=1`；`ViewSchemaVersion/ViewConfigVersion` 可为空，分别按 `1.0/1` 处理并在后续变更时递增配置版本。
+- 按 Scene、Device、RoleIds、Priority 选择视图。
+- 配置损坏或客户端不支持时回退标准 `sys_menu + diy_table + diy_field`，不能白屏。
+- 小程序只消费声明式动作，不执行 PC 的任意 `V8Code`。
+- 声明式动作中的 ParamMap/VisibleWhen 只允许白名单字段，不使用 `eval`。
+
+### 重要模块的统计与信息层级
+
+- 待办、库存预警、未读、逾期、待收/待付等有行动含义的菜单，主动询问并配置
+  `MenuBadgeEnabled=1` 与 `MenuBadgeApiEngineKey`。接口统一返回
+  `{ Code:1, Data:{ Value: number } }`，并按当前用户权限统计。
+- `Scene=List` 的 `Layout.Hero` 用 `Eyebrow/Title/Description/Metrics` 建立模块标题与
+  指标条。相同 `ApiEngineKey` 的指标必须由一个聚合接口批量返回，使用 `ValuePath`
+  取值；禁止一个指标一次请求。
+- PC Hero 有指标时采用“左侧标题说明约 25%~30% + 右侧指标区弹性占满”的信息层级，
+  中间只允许一条弱化渐变分隔；指标条容器和单个指标不得叠加多层描边。无指标时标题说明
+  自动占满整行，不保留空指标区。每个指标必须显式配置 `Icon`，并通过不同的 `Tone` 或
+  `Color` 形成可辨识的图标色块与轻背景；同一 Hero 内不得让全部指标使用相同图标和颜色。
+- Hero 指标可用 `Source=DataCount` 读取当前筛选总记录数、用 `Source=PageCount` 读取本页
+  已加载记录数；两者复用列表结果，不调用额外接口。字段汇总继续用 `Field`，跨表或复合
+  统计才用 `ApiEngineKey + ValuePath`。
+- `Layout.List.Columns[]` 用 `Field + Lines + TrailingFields` 配置复合列和右侧图标状态；
+  默认按 `Field + 1 个 Lines` 形成双行，多个信息组应拆成多个双行复合列，避免单列三行
+  抬高整张表。声明支持 `Tone/Color/Icon/ShowLabel/Prefix/Suffix`，引用字段必须进入查询列。
+- `Scene=Card, Device=Mobile` 用 `Layout.Card` 配置 `AvatarTextField/TitleField/TopFields/
+  SubtitleFields/RightFields/Fields/MetaFields/BottomFields`。未配置时继续兼容
+  `MobileListFields/CardTitleTagFields/CardBottomTagFields`。
+- `PageTabs/MoreBtns/PageBtns/BatchSelectMoreBtns/ExportMoreBtns/FormBtns` 需要数量时配置
+  `BadgeEnabled/BadgeApiEngineKey`；一个接口接收当前页 `Ids + ButtonKeys` 并一次返回
+  `Data.Buttons` 与 `Data.Rows`，禁止逐行调用。
+- 能直接用字段表达的信息优先配置复合列/卡片字段；只有确需 HTML 样式或组合逻辑时
+  才使用字段的 `V8TmpEngineTable`，且仍需遵守 DOMPurify 和查询字段范围。
+- 存量菜单没有 Hero.Metrics 时，客户端只允许根据真实后端汇总、当前筛选总数、本页加载数
+  和本页真实状态分布生成兜底指标；不得用随机值装饰页面。字段聚合缺少全量口径时必须明确
+  标注“本页”，不能把当前页求和冒充全表汇总。
+
+### 表单布局协同
+
+- `<=6` 个核心可见字段优先平铺；`7~29` 个字段按基础、业务、状态、附件等信息域使用
+  `CollapseGroup`；`30+` 个字段，或存在多个大型子表、扫码/代码编辑等强任务域时使用
+  表级 `diy_table.Tabs`。最终还要按有效表单行校正，避免产生只有少量字段的空洞 Tab。
+- 新增 `Tabs/CollapseGroup/Divider/Alert` 等布局节点必须走明确的“仅元数据”专用路径。
+  普通新增字段接口可能同步对业务表执行物理 DDL，不能把向 `diy_field` 新增一行误认为
+  仅保存布局配置；写入后要同时回读元数据并核对业务表结构未新增实体列。
+
+## 验收
+
+- `Display/AppDisplay` 除明确隐藏外为 1，父子菜单层级正确。
+- 路由刷新、直接访问、切换菜单均不 404/白屏。
+- 列表字段、筛选、排序、统计、移动端卡片与预期一致。
+- 权限用户可访问，未授权用户不能靠 URL、`_SysMenuId` 或前端字段绕过。
+- MoreBtns/FormBtns/PageTabs/BatchSelectMoreBtns 显隐、调用和刷新正确；PageTabs 数字角标使用稳定 Tab Id 取 `Data.Buttons`。
+- 菜单角标、模块指标和按钮角标按真实权限返回，零值/超限/接口失败降级正确且无 N+1。
+- Hero 在有指标、无指标、长标题和 3~5 个指标时均层级清晰；指标无多层线框，同一组图标与
+  语义色可区分，并在浅色/深色主题下保持可读。
+- PC 复合列和 Mobile Card 引用的附加字段均在查询结果中；长文本、空值、模板值不破版。
+- PC 和移动端分别验证；MicroService 还要验证运行时、页面路由和宿主上下文。

package/skills/module-engine/references/module-config.md

@@ -185,13 +185,15 @@ ApiEngineKey、Workload、幂等字段、并发 Key、业务状态/任务 Id/进
 ## PageTabs 两种模式
 
 - 无目标菜单：在当前模块执行 V8，通常 `V8.SearchSet(...)`。
-- 有 `TargetSysMenuId`：加载目标模块。目标菜单即使隐藏导航，也必须给角色权限。
+- 有 `TargetSysMenuId`：在当前 `diy-table` 实例内加载目标模块的菜单、表、字段和列表数据。目标菜单即使隐藏导航，也必须给角色权限。
 
 PageTabs 可以通过 `BadgeApiEngineKey` 显示数字角标。接口按 `ButtonKeys` 一次返回所有 Tab 数量到 `Data.Buttons`，`BadgeValuePath` 可显式指定 `Data.Buttons.{TabId}`；失败只隐藏角标，不能阻断页签切换。
 
 PageTabs 只表达当前模块的数据类别/状态，不能取代模块 Hero，也不能渲染到 Hero 上方。
 
-跨表 Tab 应让每个目标菜单配置同一组 PageTabs，不在前端按菜单名写死。
+跨表 Tab 由入口模块统一配置一组 PageTabs，目标菜单只保留各自的模块设计、表绑定和角色权限，不复制 PageTabs。切换只更新当前 URL 的 `Tab` 查询参数；路由、面包屑、顶部访问标签和入口模块 Hero 保持稳定，表格上下文在原实例中切换。实现时必须取消旧请求、丢弃迟到响应并在失败时回滚，禁止按菜单名或业务表名写死。
+
+首屏和跨模块切换应为 Hero 标题/统计、PageTabs、工具栏和列表提供与最终几何尺寸一致的主题化骨架屏；根据模块元数据判断是否预留指标区和 PageTabs，并支持 `prefers-reduced-motion: reduce`。
 
 ## URL 参数
 

package/skills/ui-design/SKILL.md

@@ -28,8 +28,8 @@ description: Microi UI 设计系统指南。用于设计 PC Vue、Element Plus
 
 - 当需求只描述“高级、主流、好看”而没有明确视觉方向时，先从 Microi 内置模式中确定一种主结构：品牌叙事、真实产品流程、趋势构图、沉浸互动、动态首屏或数据工作台；再选择至多两种辅助能力。禁止把多套视觉语言堆成拼盘。
 - 设计结果必须被拆成可执行规则：首屏目标、信息层级、栅格与最大宽度、字体层级、语义颜色、间距、圆角/阴影、组件状态、动效时间线、响应式重排、低性能降级和 `prefers-reduced-motion`。
-- 先完成默认、加载、空、错误、成功、权限、禁用等真实业务状态，再增加装饰和动效；任何看起来可点击的元素都必须有真实结果。
-- 所有异步内容加载统一使用贴合最终几何的主题骨架；菜单切换、首页、表格、表单/详情、弹窗和远程媒体都不得退回半透明黑色遮罩。具体实现、主题令牌与状态边界读取 [references/progressive-02-字体.md](references/progressive-02-字体.md)。
+- 先完成默认、加载、空、错误、成功、权限、禁用等真实业务状态，再增加装饰和动效；任何看起来可点击的元素都必须有真实结果。
+- 所有异步内容加载统一使用贴合最终几何的主题骨架；菜单切换、首页、表格、表单/详情、弹窗和远程媒体都不得退回半透明黑色遮罩。具体实现、主题令牌与状态边界读取 [references/progressive-02-字体.md](references/progressive-02-字体.md)。
 - 所有成品只使用 Microi 自有内容、`--mci-*` token、`mci-*` 组件/类名和项目合法资产。禁止复制第三方页面、源码、图片、字体、3D 模型、商标或原始设计 token。
 - 设计前必须读取 [references/design-pattern-library.md](references/design-pattern-library.md)；涉及登录、订阅、支付、权限、搜索、设置等流程时再读 [references/product-flow-recipes.md](references/product-flow-recipes.md)；涉及滚动、3D、Canvas/WebGL 或动态 Hero 时再读 [references/motion-and-media.md](references/motion-and-media.md)；生成整站或交给 AI 延续设计时使用 [references/mci-design-contract.md](references/mci-design-contract.md)。
 - 可运行原创案例位于 [assets/pattern-showcase/index.html](assets/pattern-showcase/index.html)，用于理解结构和状态，不作为需要逐像素复制的模板。
@@ -184,22 +184,22 @@ Microi 项目必须支持用户或项目级形态偏好：`data-mci-shape="round
 - [references/progressive-06-主题切换实现.md](references/progressive-06-主题切换实现.md)：主题切换实现；命名规范
 - [references/progressive-07-速查-从头搭建一个移动端页面.md](references/progressive-07-速查-从头搭建一个移动端页面.md)：速查：从头搭建一个移动端页面；🚨 移动端低代码项目落地踩坑（必读，2026.5）；🔗 关联字段：保存真实 Id，界面展示可读标签；表单布局规范（Column）
 - [references/progressive-08-表单分组规范-tabs-vs-collapsegroup-强制.md](references/progressive-08-表单分组规范-tabs-vs-collapsegroup-强制.md)：表单分组规范：Tabs vs CollapseGroup（强制）；缓存刷新（解决"我改了字段但页面不变"问题）；接口引擎匿名访问；MCI-UI 与第三方组件库策略；MCI-UI 源码落地位置；VitePress 中文文档布局规范
-<!-- microi-progressive:end -->
-
-## Microi 低代码工作台默认清爽体验（强制）
-
-`diy-form`、`diy-table`、模块卡片、设计器弹窗和框架导航默认采用清爽、紧凑、层次明确的现代视觉；经典样式只能作为显式兼容模式保留，不能继续作为新页面或未配置页面的默认外观。
-
-- **只升级呈现，不改变业务链路**：不得删除、合并或绕开页面 V8 按钮、行 V8 按钮、批量按钮、字段事件、表单事件、权限判断、校验、工作流与保存逻辑。按钮仍应出现在其业务语义对应的位置；只有原本属于“更多”的操作才进入更多菜单。
-- **普通表单使用连续画布**：弹窗/页面的表单区使用柔和底色，普通字段外壳透明、无独立边框和阴影，只有输入、选择、日期、文本域等真实控件使用白色/主题高亮表面；禁止把每个字段切成一张小卡片。系统设置、控制中心等明确配置为工作台的模式可以保留分区卡片。字段间距以一屏可读更多信息为目标，布局字段、富文本、上传、地图、代码编辑器、子表等重型控件不强制固定高度。
-- **尊重三种标签布局**：`left`、`right`、`top` 三种 `FormLabelPosition` 必须完整保留，标签宽度继续服从表单配置；移动窄屏允许回落到顶部标签，但不能破坏桌面配置语义。字段存在说明文字时，`left/right` 把灰色小字放在 Label 与控件整行下方，默认最多两行并压缩上下间距；`top` 把说明放在 Label 右侧，单行省略并通过原生 `title` 或等价可访问方式查看全文。不得再以孤立 `i` 图标和仅鼠标悬停 Tooltip 作为默认说明入口。
-- **Label 与紧凑控件共用中心线**：左右标签布局下，普通字段 Label、输入控件、日期文字与日期前缀图标必须共用同一控件高度和垂直中心线；不得保留会把 Label 单独上抬/下压的底部外边距。多行文本、上传、子表等高控件才切换为顶部对齐。
-- **弹窗与抽屉边界有区别**：表单对话框采用中性细边界、柔和遮罩与模糊背景，标题顶部不加装饰色线；抽屉必须贴边且无圆角，可在顶部保留克制的 2–3px 主题色识别线。两者都使用连续的柔和表单画布和紧凑操作区；设计器双击字段弹窗必须可拖动，并继续提供控件专项配置入口。
-- **平台 Dialog 统一壳**：除 Drawer 外，框架弹层、微应用弹层、系统设置、商城、通知与业务表单默认使用 20–24px 大圆角、上下左右居中、标题栏可拖动的 Dialog；禁止页面自行恢复方角壳或顶部主题色粗线。标题栏左侧依次提供语义图标、英文眉题、大字标题和可选小字副标题；右上关闭按钮与标题区垂直居中并必须有可辨识的按钮底色。内容区使用连续、固定的柔和背景和整齐栅格；底部操作区右对齐大号关闭/保存按钮，两者都带语义图标。拖动与窗口缩放必须按弹层真实宽高重新约束，四边至少保留 8–18px 可视余量，不得把内容拖出视口。Teleport 到 `body` 的微应用弹层必须在弹层根同步 `data-mci-ui-root`、主题与必要 token，不能只依赖原祖先 CSS 变量。遮罩默认毛玻璃，只有 `sys_config.DisableFormMaskBlur=1/true` 才全局关闭；`prefers-reduced-motion` 只能停止动画与过渡，不得关闭静态毛玻璃。
-- **Dialog 关闭按钮可见性**：右上关闭按钮固定使用 40×40px（移动端不低于 40px）中性灰底、细边框和 10–12px 圆角，不能只显示悬空的细线 X；亮色和暗色主题都必须保持可辨识背景。hover/focus-visible 时使用更深一级灰底、主题色图标和清晰焦点环。底部关闭/取消/保存按钮高度不低于 42px、最小宽度 96px，并保持右对齐与 12px 间距。
-- **Tabs 统一视觉**：顶部工作区、数据列表 PageTabs、表单 Tabs 与右侧关联数据 Tabs 使用同一套清爽、独立标签视觉。横向 Tabs 禁止铺设贯穿整行的有色轨道、边框底板、下划线或其它装饰线；未选项保持透明，悬停与选中只使用克制的文字色、浅色独立表面和轻阴影。纵向 Tabs 可使用截图式中性浅色分组容器，选中项是独立浅色卡片。数字角标放在标签文本之后且不得挤压标题；过渡只用于交互，并尊重 `prefers-reduced-motion`。
-- **表格与卡片行为完整**：桌面数据卡片采用连续白色表面、弱边界和轻阴影，操作区不得再叠加有色底板或硬分割线；表格模块门头的标题/副标题卡片与每个动态统计卡片必须彼此独立，父布局保持透明，禁止用一个大卡片或外框把标题和全部统计项包在一起。表格默认取消无意义的纵向网格，只保留浅表头与轻量横向行节奏，工具栏和分页不得层层套框。`PageBtns`、`BatchSelect`、行内/行外 V8 按钮均不可因改版丢失；需多选而当前未选中时，应先把当前记录纳入选中集再执行。
-- **启动状态可理解、可恢复**：Vue 挂载和业务就绪是两个状态。进度到 100% 后若仍在初始化，应显示“正在连接/后端响应较慢/仍在等待”等阶段文字；明确失败时提供原因摘要与刷新重试，禁止撤掉启动层后留下空白页。
-- **侧栏清爽但层级清晰**：压缩无效间距，保留足够点击区域、选中态、父子层级和键盘焦点；颜色、圆角、阴影必须来自主题 token。
-- **纵向导航使用短圆角侧标**：侧栏、纵向 Tab、分组导航等选中态的左/右侧强调线统一参照平台左侧菜单：宽 3–4px、高度约为选中项的 45%–60%，垂直居中，端点使用小圆角；禁止铺满 100% 高度，也禁止做折线或包边。右侧 Tab 镜像到右边；横向 Tabs 不使用这条侧标，也不额外增加上下指示线。
-- **主题与可访问性验收**：至少验证亮色/暗色、租户主题色、1366/1440/1920 桌面与 390px 移动宽度、三种标签对齐、慢接口和接口失败；动效必须服从 `prefers-reduced-motion`。
+<!-- microi-progressive:end -->
+
+## Microi 低代码工作台默认清爽体验（强制）
+
+`diy-form`、`diy-table`、模块卡片、设计器弹窗和框架导航默认采用清爽、紧凑、层次明确的现代视觉；经典样式只能作为显式兼容模式保留，不能继续作为新页面或未配置页面的默认外观。
+
+- **只升级呈现，不改变业务链路**：不得删除、合并或绕开页面 V8 按钮、行 V8 按钮、批量按钮、字段事件、表单事件、权限判断、校验、工作流与保存逻辑。按钮仍应出现在其业务语义对应的位置；只有原本属于“更多”的操作才进入更多菜单。
+- **普通表单使用连续画布**：弹窗/页面的表单区使用柔和底色，普通字段外壳透明、无独立边框和阴影，只有输入、选择、日期、文本域等真实控件使用白色/主题高亮表面；禁止把每个字段切成一张小卡片。系统设置、控制中心等明确配置为工作台的模式可以保留分区卡片。字段间距以一屏可读更多信息为目标，布局字段、富文本、上传、地图、代码编辑器、子表等重型控件不强制固定高度。
+- **尊重三种标签布局**：`left`、`right`、`top` 三种 `FormLabelPosition` 必须完整保留，标签宽度继续服从表单配置；移动窄屏允许回落到顶部标签，但不能破坏桌面配置语义。字段存在说明文字时，`left/right` 把灰色小字放在 Label 与控件整行下方，默认最多两行并压缩上下间距；`top` 把说明放在 Label 右侧，单行省略并通过原生 `title` 或等价可访问方式查看全文。不得再以孤立 `i` 图标和仅鼠标悬停 Tooltip 作为默认说明入口。
+- **Label 与紧凑控件共用中心线**：左右标签布局下，普通字段 Label、输入控件、日期文字与日期前缀图标必须共用同一控件高度和垂直中心线；不得保留会把 Label 单独上抬/下压的底部外边距。多行文本、上传、子表等高控件才切换为顶部对齐。
+- **弹窗与抽屉边界有区别**：表单对话框采用中性细边界、柔和遮罩与模糊背景，标题顶部不加装饰色线；抽屉必须贴边且无圆角，可在顶部保留克制的 2–3px 主题色识别线。两者都使用连续的柔和表单画布和紧凑操作区；设计器双击字段弹窗必须可拖动，并继续提供控件专项配置入口。
+- **平台 Dialog 统一壳**：除 Drawer 外，框架弹层、微应用弹层、系统设置、商城、通知与业务表单默认使用 20–24px 大圆角、上下左右居中、标题栏可拖动的 Dialog；禁止页面自行恢复方角壳或顶部主题色粗线。标题栏左侧依次提供语义图标、英文眉题、大字标题和可选小字副标题；右上关闭按钮与标题区垂直居中并必须有可辨识的按钮底色。内容区使用连续、固定的柔和背景和整齐栅格；底部操作区右对齐大号关闭/保存按钮，两者都带语义图标。拖动与窗口缩放必须按弹层真实宽高重新约束，四边至少保留 8–18px 可视余量，不得把内容拖出视口。Teleport 到 `body` 的微应用弹层必须在弹层根同步 `data-mci-ui-root`、主题与必要 token，不能只依赖原祖先 CSS 变量。遮罩毛玻璃由 `sys_config.FormMaskBlur=1/true` 全局显式开启，缺失或 `0/false` 默认关闭；`prefers-reduced-motion` 只能停止动画与过渡，不得擅自反转静态毛玻璃配置。
+- **Dialog 关闭按钮可见性**：右上关闭按钮固定使用 40×40px（移动端不低于 40px）中性灰底、细边框和 10–12px 圆角，不能只显示悬空的细线 X；亮色和暗色主题都必须保持可辨识背景。hover/focus-visible 时使用更深一级灰底、主题色图标和清晰焦点环。底部关闭/取消/保存按钮高度不低于 42px、最小宽度 96px，并保持右对齐与 12px 间距。
+- **Tabs 统一视觉**：顶部工作区、数据列表 PageTabs、表单 Tabs 与右侧关联数据 Tabs 使用同一套清爽、独立标签视觉。横向 Tabs 禁止铺设贯穿整行的有色轨道、边框底板、下划线或其它装饰线；未选项保持透明，悬停与选中只使用克制的文字色、浅色独立表面和轻阴影。纵向 Tabs 可使用截图式中性浅色分组容器，选中项是独立浅色卡片。数字角标放在标签文本之后且不得挤压标题；过渡只用于交互，并尊重 `prefers-reduced-motion`。
+- **表格与卡片行为完整**：桌面数据卡片采用连续白色表面、弱边界和轻阴影，操作区不得再叠加有色底板或硬分割线；表格模块门头的标题/副标题卡片与每个动态统计卡片必须彼此独立，父布局保持透明，禁止用一个大卡片或外框把标题和全部统计项包在一起。表格默认取消无意义的纵向网格，只保留浅表头与轻量横向行节奏，工具栏和分页不得层层套框。`PageBtns`、`BatchSelect`、行内/行外 V8 按钮均不可因改版丢失；需多选而当前未选中时，应先把当前记录纳入选中集再执行。
+- **启动状态可理解、可恢复**：Vue 挂载和业务就绪是两个状态。进度到 100% 后若仍在初始化，应显示“正在连接/后端响应较慢/仍在等待”等阶段文字；明确失败时提供原因摘要与刷新重试，禁止撤掉启动层后留下空白页。
+- **侧栏清爽但层级清晰**：压缩无效间距，保留足够点击区域、选中态、父子层级和键盘焦点；颜色、圆角、阴影必须来自主题 token。
+- **纵向导航使用短圆角侧标**：侧栏、纵向 Tab、分组导航等选中态的左/右侧强调线统一参照平台左侧菜单：宽 3–4px、高度约为选中项的 45%–60%，垂直居中，端点使用小圆角；禁止铺满 100% 高度，也禁止做折线或包边。右侧 Tab 镜像到右边；横向 Tabs 不使用这条侧标，也不额外增加上下指示线。
+- **主题与可访问性验收**：至少验证亮色/暗色、租户主题色、1366/1440/1920 桌面与 390px 移动宽度、三种标签对齐、慢接口和接口失败；动效必须服从 `prefers-reduced-motion`。