@microi.net/cli 6.2.4 → 6.3.2

package/skills/microi-left-right-layout/SKILL.md

@@ -1,163 +1,176 @@
----
-name: microi-left-right-layout
-description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
----
-
-> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
-
-# Microi 左右树表配置规范
-
-当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
-
-## 适用与禁用场景
-
-- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
-- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
-- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
-
-## 模块配置
-
-目标 `sys_menu` 必须配置：
-
-```json
-{
-  "ComponentName": "树形+表格",
-  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
-}
-```
-
-同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
-
-## `diy_LeftJoinRightView` 字段
-
-| 字段 | 必填 | 含义与写法 |
-| --- | --- | --- |
-| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
-| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
-| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
-| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
-| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
-| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
-| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
-| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
-| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
-| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
-| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
-| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
-| `ShumoHSS` | 否 | 模糊搜索开关。 |
-| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
-| `ShusouSAN` | 否 | 搜索按钮开关。 |
-| `ShushuaX` | 否 | 刷新按钮开关。 |
-| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
-| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
-| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
-| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
-| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
-| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
-| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
-
-## 初始化 V8 与分页契约
-
-左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
-
-当初始化 V8 使用 `V8.FormEngine.GetTableTree/GetTableDataTree` 时，左侧来源 `diy_table.IsTree` 必须为 `1`，并显式配置真实存在的 `TreeParentField`（通常是 `ParentId`）；否则接口会成功返回 `Code=0`，页面只显示“暂无数据”。应用包必须同时携带这两项表元数据，并在发布前通过真实树接口回读，不能只验收 `diy_LeftJoinRightView` 配置行。
-
-```js
-var form = V8.Form || {};
-var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
-var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
-var keyword = String(form.inputText || '').trim();
-var query = {
-    _SelectFields: ['Id', 'Code', 'Name'],
-    _OrderBy: 'CreateTime',
-    _OrderByType: 'DESC',
-    _PageIndex: pageIndex,
-    _PageSize: pageSize
-};
-
-if (keyword) {
-    query._Where = [
-        ['Code', 'Like', keyword],
-        ['OR', 'Name', 'Like', keyword]
-    ];
-}
-
-var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
-
-if (result.Code !== 1) {
-    V8.Result = result;
-    return;
-}
-
-V8.Result = {
-    Code: 1,
-    Data: (result.Data || []).map(function (item) {
-        return {
-            Id: item.Id,
-            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
-            Code: item.Code,
-            Name: item.Name
-        };
-    }),
-    DataCount: Number(result.DataCount || 0),
-    PageIndex: pageIndex,
-    PageSize: pageSize
-};
-```
-
-对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
-
-### 节点事件返回复合筛选
-
-普通主外键继续使用 `ZibiaoGLZD/GuanlianPPLJ`。确需多个关系字段时，在已授权的配置
-`ShujieDDJSJ` 节点 V8 返回 `{ PropsWhere: [...] }`，例如主部门或兼职部门同时匹配：
-
-```js
-var id = String(V8.Form.Id || '');
-V8.Result = { PropsWhere: [
-    { Name: 'DeptId', Type: '=', Value: id, GroupStart: true },
-    { AndOr: 'OR', Name: 'DeptIds', Type: 'Like', Value: '"' + id + '"', GroupEnd: true }
-] };
-```
-
-`GroupStart/GroupEnd` 使用布尔值。字段名、关系及存储格式必须先通过实时 Schema 回读，
-示例不能用于任意业务表。这里只传结构化条件和值，禁止由前端传 SQL；服务端仍校验菜单、表和数据范围。
-运行时只接受非数组对象中的 `PropsWhere` 数组并深复制；明确 `[]` 清空节点条件，未返回或类型非法
-继续原单关联筛选。慢节点事件返回前再次核对节点代次，切节点后的旧结果不能覆盖当前筛选。
-
-配置复用 `microi_get_module`、`microi_get_field_list` 和标准 `microi_admin_table_data`
-读取/更新 `diy_LeftJoinRightView`，不新增通用 SQL 接口。系统账号与角色管理的组织树共同使用
-现有 `RoleTreeWidth/RoleTreeCollapsed` 个人偏好；其它业务树保留各自比例。
-
-加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
-
-## MCP 实施顺序
-
-1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
-2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
-3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
-4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
-5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
-
-## 移动端要求
-
-- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
-- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
-- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
-- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
-- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
-- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
-
-## 验收清单
-
-- 当前菜单只匹配一条配置，模块路径正确。
-- 使用树接口的左表已启用 `IsTree=1`，`TreeParentField` 与物理父级字段一致。
-- 左树标题无 `undefined`、`{}`、空白重复项。
-- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
-- 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
-- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
-- 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
-- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
-- 普通用户不出现仅管理员可用的“页面配置”。
-- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
-- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。
+---
+name: microi-left-right-layout
+description: Microi 吾码模块引擎“树形+表格/表单”左右结构配置规范。用于通过 MCP、模块引擎或源码配置 `diy_LeftJoinRightView`，把项目、分类、组织等主数据作为左树，并用主外键过滤右侧列表；覆盖字段语义、初始化 V8、移动端自适应、幂等写入和回读验收。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi 左右树表配置规范
+
+当需求是“左侧按项目/分类导航，右侧显示该节点的数据列表或表单”时，使用模块组件 `/diy/left-right/LeftTreeJoinRightForm`，配置表为 `diy_LeftJoinRightView`。不要为每个业务菜单复制定制 Vue 页面。
+
+## 适用与禁用场景
+
+- 适用：项目及其成品、用料、请购、提料、锁料、文档，分类及商品，组织及人员。
+- 左侧必须是稳定的主数据；右侧必须能通过明确的主外键过滤。
+- 左右两边没有关联字段、左侧仅是装饰性筛选，或数据量极大却没有分页/搜索方案时，不应直接套用。
+
+## 模块配置
+
+目标 `sys_menu` 必须配置：
+
+```json
+{
+  "ComponentName": "树形+表格",
+  "ComponentPath": "/diy/left-right/LeftTreeJoinRightForm"
+}
+```
+
+同一菜单只能有一条有效的 `diy_LeftJoinRightView` 配置。创建前先按 `GuanlianCD Like 菜单Id` 回读并复用，禁止重复插入。
+
+## `diy_LeftJoinRightView` 字段
+
+| 字段 | 必填 | 含义与写法 |
+| --- | --- | --- |
+| `GuanlianCD` | 是 | 当前右侧业务菜单链，JSON 数组；末级必须是当前 `sys_menu.Id`。 |
+| `ShuxingGLCD` | 是 | 左侧主数据菜单链，JSON 数组；末级对应左表模块。 |
+| `GuanlianBD` | 是 | 左侧主表名，例如 `xiangmuguanli`。 |
+| `FubiaoGLZD` | 是 | 左表参与关联的字段，通常为 `Id`。 |
+| `ZibiaoGLZD` | 右表格必填 | 右表外键，例如 `XiangmuID`、`ProjectId`、`Guid`。必须以实时表结构为准。 |
+| `GuanlianPPLJ` | 右表格必填 | 匹配操作符，普通主外键使用 `=`。 |
+| `ZuobianZSZJ` | 是 | 左侧组件，通常为 `树形控件`。 |
+| `YoubianZSZJ` | 是 | `表格`、`表单` 或 `表单/表格`。 |
+| `ShuxianSZDM` | 是 | 左树显示字段，必须与初始化结果的属性名一致。 |
+| `ChushiHDM` | 是 | 初始化 V8。必须读取 `V8.Form._PageIndex/_PageSize/inputText`，最终返回 `Data` 和 `DataCount`。 |
+| `ZuoyouXSZB` | 否 | 24 栅格比例，例如 `6/18`、`4/20`，中间 `/` 必须保留。 |
+| `ShubiaoT` | 否 | 左树标题，例如 `项目目录`。 |
+| `ShumoHSS` | 否 | 模糊搜索开关。 |
+| `ShuxiaLSS` | 否 | 搜索字段下拉开关。 |
+| `ShusouSAN` | 否 | 搜索按钮开关。 |
+| `ShushuaX` | 否 | 刷新按钮开关。 |
+| `ShudingJXZ` | 否 | 是否允许新增顶级树节点。 |
+| `ShuxinZ`、`ShubianJ`、`ShushanC` | 否 | 树节点新增、编辑、删除开关。只在业务允许时开启。 |
+| `ShujieDDJSJ` | 否 | 节点点击 V8；可读取 `V8.Form`，异步结果写入 `V8.Result`。 |
+| `YincangBSF` | 否 | 节点命中该字段时隐藏右侧区域。 |
+| `TanchuangLX`、`TanchuangDX` | 否 | 树节点维护弹窗类型和尺寸。 |
+| `LanjiaZ`、`LanjiaZDM` | 否 | 懒加载开关和代码；大树优先使用。 |
+| `DefaultExpandLevel` | 否 | 左树默认展开层级。未配置、空值或 `0` 均不展开；`1` 展开一级节点，`2` 再展开二级节点，以此类推。 |
+
+## 初始化 V8 与分页契约
+
+左树按数据表对待，默认每页 20 条，允许 10/20/50/100 条切换。无论当前只有多少数据，都不能用 `_PageSize:500` 一次拉完整主表。搜索时把页码重置为 1，并在服务端按关键字过滤后返回真实总数。
+
+当初始化 V8 使用 `V8.FormEngine.GetTableTree/GetTableDataTree` 时，左侧来源 `diy_table.IsTree` 必须为 `1`，并显式配置真实存在的 `TreeParentField`（通常是 `ParentId`）；否则接口会成功返回 `Code=0`，页面只显示“暂无数据”。应用包必须同时携带这两项表元数据，并在发布前通过真实树接口回读，不能只验收 `diy_LeftJoinRightView` 配置行。
+
+```js
+var form = V8.Form || {};
+var pageIndex = Math.max(1, parseInt(form._PageIndex || 1, 10));
+var pageSize = Math.min(100, Math.max(1, parseInt(form._PageSize || 20, 10)));
+var keyword = String(form.inputText || '').trim();
+var query = {
+    _SelectFields: ['Id', 'Code', 'Name'],
+    _OrderBy: 'CreateTime',
+    _OrderByType: 'DESC',
+    _PageIndex: pageIndex,
+    _PageSize: pageSize
+};
+
+if (keyword) {
+    query._Where = [
+        ['Code', 'Like', keyword],
+        ['OR', 'Name', 'Like', keyword]
+    ];
+}
+
+var result = await V8.FormEngine.GetTableData('xiangmuguanli', query);
+
+if (result.Code !== 1) {
+    V8.Result = result;
+    return;
+}
+
+V8.Result = {
+    Code: 1,
+    Data: (result.Data || []).map(function (item) {
+        return {
+            Id: item.Id,
+            TreeTitle: [item.Code, item.Name].filter(Boolean).join(' '),
+            Code: item.Code,
+            Name: item.Name
+        };
+    }),
+    DataCount: Number(result.DataCount || 0),
+    PageIndex: pageIndex,
+    PageSize: pageSize
+};
+```
+
+对应配置为 `ShuxianSZDM=TreeTitle`、`FubiaoGLZD=Id`。右侧新增时，组件会通过 `ParentDataAppend` 把父节点、父键和 `ZibiaoGLZD` 传给表格；业务字段仍需由表单事件兜底校验。
+
+### 节点事件返回复合筛选
+
+普通主外键继续使用 `ZibiaoGLZD/GuanlianPPLJ`。确需多个关系字段时，在已授权的配置
+`ShujieDDJSJ` 节点 V8 返回 `{ PropsWhere: [...] }`，例如主部门或兼职部门同时匹配：
+
+```js
+var id = String(V8.Form.Id || '');
+V8.Result = { PropsWhere: [
+    { Name: 'DeptId', Type: '=', Value: id, GroupStart: true },
+    { AndOr: 'OR', Name: 'DeptIds', Type: 'Like', Value: '"' + id + '"', GroupEnd: true }
+] };
+```
+
+`GroupStart/GroupEnd` 使用布尔值。字段名、关系及存储格式必须先通过实时 Schema 回读，
+示例不能用于任意业务表。这里只传结构化条件和值，禁止由前端传 SQL；服务端仍校验菜单、表和数据范围。
+运行时只接受非数组对象中的 `PropsWhere` 数组并深复制；明确 `[]` 清空节点条件，未返回或类型非法
+继续原单关联筛选。慢节点事件返回前再次核对节点代次，切节点后的旧结果不能覆盖当前筛选。
+
+配置复用 `microi_get_module`、`microi_get_field_list` 和标准 `microi_admin_table_data`
+读取/更新 `diy_LeftJoinRightView`，不新增通用 SQL 接口。系统账号与角色管理的组织树共同使用
+现有 `RoleTreeWidth/RoleTreeCollapsed` 个人偏好；其它业务树保留各自比例。
+
+加载请求期间必须显示明确的“正在加载项目...”状态，不能先渲染“暂无数据”；多次搜索或翻页并发返回时，只应用最后一次请求，防止旧结果覆盖新页。
+
+## MCP 实施顺序
+
+1. 调用实时 Schema/模块查询，确认左右表、菜单 Id、主键、外键和已有配置。
+2. 读取一个已正常运行的左右结构作为基线，只复用结构，不复制租户或业务字段。
+3. 按当前菜单回读 `diy_LeftJoinRightView`；有记录则更新，无记录才新增。
+4. 更新模块 `ComponentName`、`ComponentPath`，随后回读模块和配置行。
+5. 验证“全部”、单节点切换、右表筛选、右侧新增自动关联、刷新和搜索。
+
+## 移动端要求
+
+- `<=767px` 时不在列表上方直接堆放左树。右侧业务列表占满宽度，顶部显示当前项目和“项目目录”按钮。
+- 点击“项目目录”后，从左向右打开全高抽屉；推荐宽度 `88%`，保留一段遮罩用于快速关闭。抽屉必须支持关闭按钮、点击遮罩和 Esc 关闭。
+- 左树在抽屉内独立滚动，搜索、分页和每页条数选择都必须可操作；关闭抽屉后右表筛选状态不得丢失。
+- 右表与页面使用正常纵向滚动，禁止祖先容器 `overflow:hidden` 截断内容。
+- 右侧卡片、表格 Tab、列表卡片在移动端必须使用 `height:auto` 和 `overflow:visible`；底部操作栏不得盖住最后一条数据。
+- 至少验收桌面 1440x900、手机 390x844；在手机上分别滚动左树和整页到末尾。
+
+## 验收清单
+
+- 当前菜单只匹配一条配置，模块路径正确。
+- 使用树接口的左表已启用 `IsTree=1`，`TreeParentField` 与物理父级字段一致。
+- 左树标题无 `undefined`、`{}`、空白重复项。
+- 点击“全部”清空右侧外键条件；点击节点只显示该节点数据。
+- 后端 `_HasChild=true` 表示可展开，Element Plus 的 `isLeaf` 必须映射为独立 `_IsLeaf=!_HasChild`，不得把 `_HasChild` 直接当叶子标记。
+- `DefaultExpandLevel` 未配置时必须保持全部折叠；只展开有子节点且深度不超过配置值的节点，不能把平台默认值改成一级展开。
+- 页面初始已处于“全部”时，再次点击“全部”不得先清空已加载列表；只清除树节点外键条件并避免重复请求。
+- 右侧新增数据自动写入正确外键，切换节点后不会串数据。
+- 普通用户不出现仅管理员可用的“页面配置”。
+- 桌面左树每页默认 20 条，可翻页并切换 10/20/50/100；加载时不出现错误的空状态。
+- 手机初始不显示树，抽屉打开/节点选择自动关闭/遮罩关闭均正常；列表与操作区可滚动到底，无横向挤压和固定高度裁切。
+
+## 右侧加载子级（9.0.5 配套能力）
+
+RightLoadDescendants 默认0，缺失/NULL/false保持原单节点且无新范围请求；官方账号/角色可启用，其它配置保留。platform-left-tree-scope 只收 SysMenuId/SelectedId，从真实tenant/user和唯一末级菜单配置派生左菜单/树表，逐页100条走普通Client权限，完整有界≤10000节点。重复/缺页/计数变化/循环/超限拒绝；按Sort+Id稳定遍历，不跨不可读中间节点；右表仍执行原菜单/角色/租户数据权限交集。
+
+自定义节点事件显式消费 V8.TreeScope.Values 并返回 TreeScopeApplied:true、PropsWhere；禁止只加确认标记却仍只筛单节点。官方账号保持主/兼职部门OR，角色保持DeptIds JSON值关系；所有部门左树初始化按Sort ASC。旧事件必须fresh完整合并，不能覆盖客户定制。失败隐藏旧右表，不回退全部；旧请求/事件不覆盖新节点，保留全部/新增关联/手机抽屉。真实角色与桌面/手机仍需上线验收。
+
+### 应用更新与重复配置排查
+
+- 后端存在 `platform-left-tree-scope` 不代表元数据已安装。须同时回读 `RightLoadDescendants` 字段、真实物理列、账号/角色配置的开关及完整节点事件。新租户的 SaaS 包和存量租户的系统账号包都应从官方母版标准导出树表闭包与各自拥有的种子，不能只发布接口。
+- 返回“当前菜单的左右结构配置必须唯一”时，以 `GuanlianCD` 的末级菜单 Id 精确核对全部未删除记录。先保存完整自定义初始化/事件及原 Id，再按已授权范围合并到稳定配置并可逆退役重复项；禁止任取第一条、清空客户定制或让下一次安装重新制造重复。
+- 节点事件是可执行脚本，须核验真实 `ShujieDDJSJ` 物理列为大文本；字段元数据声明 `mediumtext` 不能证明数据库已同步。出现 `Data too long` 时走标准字段/应用升级修复，并把真实物理定义纳入包，不能截断脚本后假报成功。
+- 系统账号呈现规则通过 `platform-account-directory-tree-options`（Managed、登录后HTTP）调用 `platform-account-directory-tree-hook`（CreateIfMissing、StopHttp=1）。Hook阶段固定 `ReadPresentationOptions`，仅返回 `Data.ExcludedNodeIds`（最多100个稳定Id）和 `Data.IncludeInactive`（boolean）；默认无定制。原定制隐藏规则迁入租户Hook，再可逆退役重复配置，并真实执行同版本重装证明Hook与唯一活动配置保留。账号初始化须同时检查 `ChushiHDM` 真实大文本列，保留祖先搜索与服务端分页完整性；导航隐藏不能缩窄或扩大右表授权范围。

package/skills/microi-microservice/SKILL.md

@@ -15,6 +15,8 @@ description: Microi 前端微服务 MicroService 开发与交付指南。用于
 
 完整数据模型、文件/路由协议和宿主通信见 `references/runtime-delivery.md`。
 
+设计、创建或修改吾码前端微服务页面、菜单应用或定制弹窗时，默认执行[前端界面任务默认路由](../microi-system-delivery/SKILL.md#前端界面任务默认路由)。用户直接提出页面需求时，同样先读取并应用 [吾码 UI 设计](../ui-design/SKILL.md) 和 [Microi.UI](../microi-ui/SKILL.md)。
+
 ## 何时使用
 
 ### 看板与复杂页面的三种实现方式
@@ -48,6 +50,8 @@ description: Microi 前端微服务 MicroService 开发与交付指南。用于
 
 所有读写必须使用同一 MCP、ApiBase 和 OsClient。写操作先 dry-run，再按用户授权确认。
 
+头像、私有附件等字段的保存值与显示地址分开：上传回执同时返回 `Path/FilePathName` 与 `Url/PreviewUrl` 时，保存持久对象路径，临时签名 URL 只供预览。通用显示解析器的 URL 优先语义不能直接用于私有字段保存；缺少对象路径时应明确失败并保留旧值，不剥掉 URL 的域名或签名来猜对象标识。头像回归覆盖私有/公开、复合回执、URL-only、文件类型与大小拒绝、保存后重新读取及授权预览。
+
 ## 源码与产物分离
 
 - `sys_microistore`：应用主数据。
@@ -138,6 +142,7 @@ AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，
 - 创建/更新元数据：`microi_create_microservice`。
 - 同步私有源码：`microi_sync_microservice_source`；本地工程必须优先传 `directory`，不构造 Base64 文件数组。
 - 真实编译目录优先 `microi_publish_application_directory_stream` 流式发布。
+- 已提交版本的只读回读使用同冻结请求的 `verificationOnly=true`，前提是已保存原 finalize 的 Committed 回执、fresh 应用双指针精确匹配，且保留原 CAS 不追认当前状态。已存在版本分支只取 Native 行版本，不重新上传或 finalize；此选项本身仍可能首次创建 stage，不能当作任意应用的通用只读开关。严格区分 phase 的 `Pending=false` 与 `ProjectionPending/RepairRequired`，并报告本地修复工具与 npm 已发布版本的区别，详见[已提交版本状态回读](references/v3-committed-status-read.md)。
 - 发布前读取 `microi_get_status`，分开报告服务器在线和 `ApplicationAssetStreamGateReady`。`Actual=0` 表示当前读取没有有效门禁行，不证明用户无权限或主控登记缺失。保持用户指定子租户，不索要主租户账号/SSH，不调用补登记接口，不复制业务库 `sys_osclients`，不降级绕过门禁；提交平台排查后端取数来源和版本。
 - 发布门禁由后端从启动主租户的主控库读取当前子租户 `OsClient + Type + Network` 的唯一有效 `sys_osclients` 行，文件、应用和版本仍在当前子租户。门禁转换审计在同一主控库事务中写入。缺少门禁列/审计结构属于平台侧 SaaS/应用商城责任包问题；缺少子租户的 `sys_microistore/mci_ai_app_version/mci_ai_app_file` 则通过该租户应用商城升级。不能因主控结构故障擅自更换业务连接。不执行已退役 Upgrade25，不手动 reset 锁、fence、Storage 或 active/committed 指针；缺少结构与真正 CAS 漂移分别诊断。
 - `changeSummary` 是最多 2000 字符的版本说明文本，不能传对象；v3 在首次 stage 创建版本时存入 `mci_ai_app_version.ChangeSummary`，后续同请求重放和恢复保留原说明。历史节点若发布完成但摘要仍为空，应报告后端版本缺口，不得把编译文件验证成功等同于日志验收通过。
@@ -287,11 +292,25 @@ AI 生成菜单微服务时，应优先封装一个 `callMicroiHost(action, data
 - 品牌车辆和真实建筑只能在拥有明确资产/商标使用依据时描述为精确复刻。程序化或原创近似模型使用“风格化/演示模型”措辞，不得把车型标签当作厂商认证。视觉签收与功能、运行发布、商城包、目标租户安装是不同证据层。
 - 运动物体优先使用可复用几何/材质、LOD、实例化和离屏回绕；相机近景仍要检查曲面法线、透明车窗、轮胎方向、脚底接地、穿模和阴影。页面隐藏时暂停动画，恢复时避免累积大时间差导致物体瞬移。
 - 三维数据标牌可以使用透明 PBR 厚度几何、纹理文字与空间连线，但必须保留对齐的 DOM 点击/键盘目标、读屏文本和焦点环。小屏避碰要测试真实矩形交集，不能仅检查页面无横向滚动；把冲突标牌一律向上推会在工具条边界堆叠。玻璃 transmission 会额外渲染场景，密集人群应先量测绘制次数，再选择透明近似或折射质量档。
+- 先明确标牌属于实体世界还是屏幕 HUD。用户要求嵌入场景的玻璃牌时，位置、米制尺寸和朝向由世界坐标/业务锚点决定，随相机产生透视缩小并参与深度遮挡；不能为保持字号和避碰，每帧把它反投影到固定屏幕槽、复制相机四元数或关闭 depthTest。无操作的只读牌不能用透明 DOM 矩形拦截旋转/缩放；可访问文本与键盘入口另保留。验收固定同一业务锚点，仅改变相机，断言世界矩阵不变、画面投影变化、遮挡正确、背面文字不镜像。
+- 镜头切换的裁剪参数依据相机实际位置与沿途净空，不能只因选中了室内目标就提前使用室内近裁平面，否则相机仍在远景时会丢失深度精度。异步几何/着色器准备期间保留旧场景完整可见，在准备成功且导航世代仍有效后一次提交目标层、剖切、灯光和镜头；不得跨 await 隐藏正在显示的对象，也不能用周期性全屏暗遮罩掩盖准备闪烁。验收应录制总览到室内、跨楼层、连续快览及快速重复切换的实际运动帧，静态像素检查不代替动态验收。
+- 模型库中有精细原型不等于真实业务已使用它。先从当前租户真实 Bootstrap 或资产表取得实际 ModelKey（以真实响应字段为准）及逐键实例数，区分生产设备、布局单元和 IoT；再将细部几何绑定到实际 CAD/业务根，逐条串联业务 Id、模型键、库节点、嵌套实例与运行截图。顶层同名键实例为零时也须检查原型是否已嵌入 CAD 子树，不能由库中存在或某一个计数直接宣称全量可见、全部未展示或逐机一致。
+- 静态 AO 烘焙必须使用当前实际实例的 T·R·S 与对应建筑/设备几何，保留原 UV0，另建独立 UV1；标量 occlusionTexture 使用匹配的 texCoord/aoMap.channel 与 NoColorSpace，不能当 sRGB 彩色贴图。用真实加载器和实际合批后的几何检查 UV1 数量、有限性、范围、通道与字节保全，并分别验证贴图解码、GPU采样和同机位画面；CPU图像mock不计视觉通过。运动构件须排除或明确记录当次零命中；静态布局/姿态改变后显式重烘焙，有限范围环境遮蔽不得冒称完整 GI、实测光度或实时动态阴影。
+- 只有运行者明确 paused、无活动镜头/转场且属于已审计支持范围的真实 AO 输入逐值完全相同时，才可复用最近成功生成的完整 16 AO＋16 降噪结果；颜色、透明玻璃与 Output 仍每帧实时绘制。相机/投影/裁剪、几何/实例/祖先变换、材质/可见性/排序、噪声/采样参数、尺寸、上下文及 GPU 资源等相关输入改变时必须失效；未知可编程变形、外部 GPU 可变输入与未覆盖回调拒绝缓存。首帧、失效、恢复帧完整重算，异常不能保留旧 valid 结果；非暂停实时状态不复用。保持原像素门槛，分别测静态 PNG、真实失效与真实 RAF 帧时；部分样本通过不等于所有视角/实体手机无频闪，不能无证据把残差归因于 AO。
+- CAD近共面柱或构件只在有来源句柄、明确外包络与限定同族范围内做有界并集，保留全部来源身份/元数据、非目标位置/法线/UV/材质和可回滚原件；列出允许变拓扑的具体批次并独立解码核验。不能按全园坐标近似或统一阈值全局“清重复”，以免删掉真实相邻件、通道或实际重叠装配；目标样本零重复三角只证明所查范围，不能承诺全园零共面或所有运动帧零频闪。
 - 人群实例化须按可复用几何及材质属性分组，保留各人物肘膝关节矩阵，颜色用实例属性；实例化之后仍验证抬脚/落脚和长时间回绕。车辆座椅按座舱净高缩放，不能所有车型使用同一绝对头枕高度。静态源码断言之外，应实例化真实几何做边界/有限矩阵单测，并提供街景近景入口供实拍验收。
 - 建筑照片立面、实体墙和屋顶若几乎共面，旋转相机时会触发深度缓冲 z-fighting：外露侧墙的纹理面沿法向留明确间距，屋顶纹理面高于实体面，必要时用 `polygonOffset`；被相邻楼翼/门廊遮住的内部端面不要重复画照片面。验收须从东、西两端短侧墙和斜俯视分别实拍，暂停动态物体后比较同角度连续帧的大幅像素跳变；只看主立面截图不能证明无闪烁。
+- 大车间或楼层按材质合成一个巨型 Mesh 会丢失局部视锥剔除。静态不透明几何应按实际米制空间块与材质分组，保留全部顶点、法线、UV、业务拾取身份和阴影；动态机构及楼层/剖切语义保持独立。用总览、近景和侧向机位比较可见三角形、绘制次数与帧时，不能只因 drawcall 减少就判定更快，也不能把分块当成减面或降低贴图质量。
+- 透明/透射构件保留每个实体的排序边界与真实包围球，不跨整层按玻璃材质合并；缺少资产身份时逐构件保留。沿用原 PBR、深度写入、双面和透明度语义，不用统一 `renderOrder`、改不透明或单面掩盖排序问题；相交透明表面仍须单独检查。AO 法线/深度通道只采真实可遮挡实体，排除投影牌、透明玻璃及装饰背景；临时过滤用 `finally` 精确恢复原可见性、材质和 override，不能留下隐藏楼层或改变颜色通道的实际显示。
+- 拖动拾取按完整 pointer 手势判断：记录按下、全过程最大位移、按键、pointer 身份及多指状态，只有同一次未拖动的正常抬起才执行点击。不能只比较按下与抬起位置，否则绕一圈回到起点会误选设备并触发镜头跳转；取消、失焦、页面隐藏和卸载时清除待定手势，并覆盖触摸与非主键路径。
+- 室内手动镜头碰撞检查前后位置之间的完整扫掠与真实净空，不能只看终点或关闭碰撞换取平滑。碰撞时停在接触前的安全位置，并结算 OrbitControls 的残余阻尼，防止持续推进后弹回；静止镜头不重复全场景扫描。程序镜头和手动控制必须有唯一当前所有者，切换后旧阻尼或迟到回调不能再次改变新机位。
+- 诊断 getter、统计与截图采样必须纯读取，不能通过读取修正面牌可见性、相机或业务状态。投影与避碰在每个实际渲染帧统一更新，不能依赖低频统计定时器；同一相机/时钟下，连续读取诊断、切换采样顺序或暂不读取诊断，实际画面与可见对象集合应一致。
+- 流畅度验收使用真实连续旋转、滚轮/触摸缩放与镜头切换，固定设备/GPU、视口、DPR、画质、数据和模型候选，分别记录冷加载/预热、帧间隔分位、长帧、可见三角形和绘制次数。静止 FPS、CPU 合成剔除或电脑模拟手机视口不能代替实体手机 GPU 结论；移动中的 AO、MSAA、阴影与材质保持约定质量，不在输入期间暗中关闭。颜色 MSAA 与后处理轮廓/着色器高光的抗锯齿范围分别验证，不凭配置名承诺无频闪。
 
 ### 菜单页签缓存与子应用生命周期（强制）
 
+支付配置/充值微服务的秘密只在页面内存、保存后清空，二维码本地生成；未知结果保留稳定原单查询。`afterhidden`/卸载停止轮询、撤销宿主遮罩，`aftershow`只恢复一套当前会话任务，迟到响应不覆盖新订单。原菜单与手机验收仍须先执行完整私有源码拉取、逐文件校验、三方合并和清单CAS，类型检查不能替代。
+
 - 菜单微服务只有一个缓存所有者：Vue 路由宿主固定 `meta.keepAlive=false`，`<micro-app keep-alive>` 独占子应用状态。禁止把外层 Vue `KeepAlive` 打开，也禁止子应用通过随机实例名规避运行时缓存；双层缓存会产生旧宿主与当前路由竞争、无数据、永久骨架屏和白屏。
 - 每个主框架 `fullPath` 使用稳定且不泄露查询参数/Token 的实例指纹。平台最多保留 5 个菜单运行时，超过后按 LRU 销毁最久未使用的隐藏实例；Tab 仍保留，再次进入允许冷启动。关闭当前/其它/全部 Tab、访问记录淘汰、退出登录、Token 重置、角色变化、同路由版本或入口变化时必须精确 `unmountApp(name,{destroy:true,clearData:true})`。
 - 恢复隐藏实例时，宿主用 `forceSetData` 同步当前 Token、OsClient、权限、主题、路由和视口，再复核 `micro-app-body/#app` 的真实可见 DOM；失败只允许自动销毁重建一次。`hostCapabilities.lifecycle` 暴露 `cacheOwner=micro-app`、`cacheMode=runtime-keep-alive`、`maxCachedTabs=5` 和状态事件。

package/skills/microi-microservice/references/runtime-delivery.md

@@ -280,6 +280,12 @@ function openPlatformPrint(printId, businessId) {
 
 公有桶的固定根与版本目录继续作为发布投影。数据库完成态的相对 `PreviewUrl/PublicPublishPath` 保留原值，由展示 consumer 转成公开固定入口，不通过批量改表统一 URL。固定入口 HTML 引用的清单内资产仍可独立经 CDN/NAS 分流。
 
+V3 受信快照已经精确绑定 `microi/application-assets/v3/tenants/{tenant}/...` 的完整不可变对象键。
+提供商签名读取必须与原生发布器 `PutApplicationObject` 和验签回读使用同一键；不能再用普通表单文件的
+`NormalizeStoragePath` 追加租户前缀，也不能接收调用方自由路径。公有编译资产仍可匿名经已提交清单交付，
+受限桶的签名仅在后端；源码、未提交、跨租户和清单外路径保持拒绝。回归用真实 MinIO/S3 HTTP 请求区分
+原始键成功与多余租户前缀 404，并独立保留大小/SHA/MIME、HEAD、Range 和取消验证；不靠开桶、移动对象或重发修复。
+
 历史目录必须已有完整清单与原始字节验证；对象缺失或摘要不符时报告未恢复，不能覆盖成当前版本或宣称可回滚。现有 `/{version}/...` 短 API 和 `?version=` 不能作为通用 V3 历史读取协议。用户显式选择的历史地址、签名地址与私有应用保留原访问语义，不规范化成 current，也不为获得公开入口改变权限。
 
 验收分别直接访问当前固定入口、精确历史入口及其 JS/CSS：当前入口 GET/HEAD 不应产生顶层 Location 跳转，实际浏览器最终地址仍为固定入口；历史版本核对其实际版本与文件摘要，不能只验证当前版本或数字版本字段。

package/skills/microi-microservice/references/v3-committed-status-read.md

@@ -0,0 +1,13 @@
+# 已提交 V3 版本的状态回读
+
+只读状态查询先保存原 finalize 的完整原生回执，确认 `PointerState=Committed`，再从正常应用上下文核验同一 AppId、active/committed 双指针、manifest、fence/row。原业务 RequestId、requestFingerprint、源与运行清单、版本和原始 CAS 保持不变。不得因为回执是 ProjectionPending 就再次 finalize；不得用普通字典版本查询为 0 证明原生版本缺失。
+
+在上述前提成立时，同冻结 stage 请求的 `verificationOnly=true` 跳过全部资产上传。原生实现对已存在且不可变事实匹配的版本只回读 Native 版本行并返回：`PublishMode=stage`、`PhaseState=ReleaseVerified`、`Idempotent=true`、`PointerState=Committed`、`Pending=false`、`Completed=false`，并保留真实 `PublishState` 与 `VersionRowVersion/RowVersion`。这里 Completed=false 是 stage phase 的 DTO 语义，不能将它改成 true 或捏造另一份 finalize DTO。
+
+Native PublishState 可以是 PointerCommitted、ProjectionPending、RepairRequired、Completed。前两个投影待完成状态的准确判断还应结合 fresh 应用状态，不能因为 phase Pending=false 就宣称整个应用发布完成。只有原生和应用均 Completed、应用 Published/Success、双指针/清单一致才进入下一步骤。真实版本 RowVersion 从这一受支持的 Native 回包读取，不能沿用 finalize Pending 回包中的旧行版本。
+
+客户端只允许 `verificationOnly===true` 的上述精确幂等回读。所有原 tenant/app、RequestId/指纹、版本、源与运行清单、路由、门禁与不可变路径校验继续执行。fence 必须大于原请求期望值，应用 row 必须精确前滚 1；Native FencingToken 必须等于当前 PublishFence，RowVersion 必须等于 VersionRowVersion。普通 stage 仍只能返回未提交的 Verifying/ReleaseVerified；字符串 true、未知状态、伪 Pending、状态/指针矛盾或任何身份漂移一律拒绝。
+
+`verificationOnly` 并非任意应用的通用只读接口：没有已存在版本且原 CAS 仍匹配时，该正常发布动作可以首次持久化 stage。因此状态读取必须先以原 Committed 回执和 fresh 双指针限定到已存在版本，保留原 CAS；不得改成当前 CAS 再声称只查询。匹配分支会使用临时分布式租约和只读行锁，不创建/更新发布记录，也不上传、重新投影或重新提交指针。回执须如实区分业务数据 0 写与临时锁操作。
+
+旧 MCP 可能在后端正确回读之后，因旧客户端阶段断言拒绝合法 committed stage。保留真实 isError/evidenceMismatch 回执，修复并测试正式 MCP 校验器与调用点，使用新进程加载已测试的完整 MCP 入口；禁止用 wrapper 把错误改成功、伪造原生回包、越过工具拒绝调用原始 HTTP，或重发 finalize。已有连接、加密凭据、模型配置保持。npm 未发布时明确标注本地修复、源码/编译产物哈希与实际加载路径，不能称所有客户端已更新。

package/skills/microi-mobile-app-quality/SKILL.md

@@ -13,6 +13,8 @@ description: Microi 移动端首版交付质量门禁。用于 UniApp/H5/App/小
 
 开发前读取[首版交付与外部服务验收](references/mobile-first-delivery.md)，按本次实际业务列出适用门禁。首版就验真实手机号流程、会话恢复、手机与桌面布局、持续动效及发布入口；只有首页截图、编译成功或 SDK 对象存在不能宣布产品交付。第三方商户账号尚未开通时完成安全模板与失败路径，并准确区分接入完成和真实业务验收。
 
+涉及新产品设计、整站重设计或用户反馈“平庸/同质/缺少设计感”时，同时读取 [移动产品设计语言](../ui-design/references/mobile-product-language.md) 与 [项目设计签名](../ui-design/references/design-pattern-library.md#项目设计签名与场景配方)。功能、几何和设计表达分开验收：真实可用、图标对齐、无报错是基础，不能据此关闭构图同质的问题；应以同视口、同内容的页面族截图说明具体改善和仍存在的视觉缺陷。不要机械为每页增加动效、照片或大标题。
+
 <!-- microi-progressive:begin -->
 <!-- microi-progressive:chunk id=microi-mobile-app-quality-000 sha256=de98f218788f72f407d39ef9bdee2c1155574ce7a831021f63971d1eaf08943b -->
 ## 1. 导航和快捷入口必须使用真实图标

package/skills/microi-mobile-app-quality/references/mobile-first-delivery.md

@@ -4,7 +4,7 @@
 快捷登录和会话协议以 `microi-uniapp-frontend`、`microi-frontend-sdk` 为准；本参考负责
 把源码、外部服务、后台与正式入口组成一条可回读的交付链，避免只有静态页面。
 
-<!-- microi-progressive:chunk id=microi-mobile-app-quality-022 sha256=33bf185e007fab2c8316f090b1f608143deca2e3ff4b010e7577c7f88d751008 -->
+<!-- microi-progressive:chunk id=microi-mobile-app-quality-022 sha256=2654c16ea78aaccf6a6e742c84ac7e4faac86b7bad6ad51341aa6cda09a61b88 -->
 ## 开发前固定事实源和首版范围
 
 - 使用指定 MCP 的实际 Profile，先回读 `ApiBase + OsClient`，不能因为官网发布归主租户就让试用端请求主租户。不同租户用独立浏览器 context，不能只新开标签。
@@ -27,6 +27,7 @@
 - 地图、短信、支付与电子开票敏感项进入当前租户系统设置的安全配置；公开启动配置只返回明确白名单的能力开关、供应商和当前端必要运行值。不得返回整个 `V8.SysConfig`、`V8.OsClientModel` 或私有设置字典。
 - 获授权从另一租户迁移配置时，先核对供应商产品、运营主体、域名和可复用范围；仅复制所需键的最小允许列表，由可信后端在目标租户重新加密。禁止整行复制 `sys_osclients`、盲拷租户密文、复用基础设施连接串或把秘密写进源码/Manifest。
 - 使用已存在且审阅过的安全配置工具；若没有安全迁移能力，先补可信通用能力或让管理员在后台填写，不能通过 FormEngine、SQL 别名、临时维护引擎或普通 Reveal 绕过权限。具体实现以 `v8-security` 为准。
+- 主租户向同API分区子租户复用阿里云短信凭据，可使用 `microi_copy_main_sms_credentials`：先 Inspect，核对主租户真实管理员、源成对配置、目标及Revision，再精确确认Copy。目标已有秘密不覆盖，只有可信服务端读取并重新加密；回执只含状态。旧后端没有能力时先升级可信控制面，不能改走明文读取。新会员默认角色配置在后端私有 `Auth.Sms.DefaultRoleId`，不得从匿名请求选择角色或使用旧兼容值 `Allow` 绕过验证码。
 - MCP `microi_run_engine` 的原始 `params` 可能被持久化审计；Token、短信码、完整手机号和密钥不得当普通引擎参数用于调试或迁移。认证验收通过标准 SDK/受保护传输在内存使用凭据，日志、报告和错误响应只保留脱敏阶段/追踪号；专用安全写入工具仍按其脱敏契约执行。
 
 ### 地图必须按产品与终端验证

package/skills/microi-system-delivery/SKILL.md

@@ -9,6 +9,8 @@ description: 已初始化吾码工作区的默认 AI 开发总控入口，用户
 
 # Microi 全系统交付复盘与总控规范
 
+浏览器交互验收先执行 `workspace-conventions/SKILL.md` 首部的浏览器选择规则：用户未指定时默认使用当前 Codex/WorkBuddy/DSH 宿主的内置浏览器，包括新开发 PC 后台、UniApp/H5 与本地预览；仅在没有内置浏览器、必要能力不支持或有界诊断确认不可用时降级到本地浏览器。具体测试、独立 CI 与会话隔离按 `playwright-e2e` 执行。
+
 所有范围的收尾都必须执行 [测试临时文件随任务清理](../workspace-conventions/SKILL.md#测试临时文件必须随任务清理强制)：每轮测试结束清理本任务 `.tmp`、宿主临时目录、隔离源码/运行副本和已结束工作树，交付必需证据先最小归档，失败/中断也要回收；独立回读删除结果，并逐项说明确需暂留的文件、体积、原因与清理时机。脚本需有实际 teardown，不能把文字规范当作自动清理功能。
 
 本 Skill 来自一次完整业务系统交付复盘。目标是让下一套 OA、ERP、MES、CRM、商城、预约、互联网项目等 Microi 系统少走返工路：先固定事实源，再用 MCP 正确建模，最后用可视化和业务闭环测试证明可交付。
@@ -26,6 +28,10 @@ description: 已初始化吾码工作区的默认 AI 开发总控入口，用户
 
 完整系统及用户反馈后的交付复测，还须读取 [交付易错项与证据门禁](references/delivery-pitfalls.md)，逐项记录适用、通过、失败或不适用及理由。此表适用于所有模型与宿主；连接成功、模型自述“已完成”或引用规则不能替代实际回执。涉及报表/模拟数据时必须执行 `report-engine` 的默认周期覆盖检查。
 
+## 前端界面任务默认路由
+
+根据吾码工作区、当前应用和用户要操作的界面识别任务。设计、创建或修改前端微服务页面或移动端界面时，即使用户只说“给订单加个详情页”或“调整手机端首页”，也要在设计和实现前完整读取并应用 [吾码 UI 设计](../ui-design/SKILL.md) 和 [Microi.UI](../microi-ui/SKILL.md)。再按下表读取端侧专项规范，沿用既有设计契约和用户指定的设计体系。纯后端改动、只读盘点等按实际范围读取专项。
+
 按本次实际能力读取相关 Skill，不能只读总控入口后凭记忆实现：
 
 | 工作内容 | 相关 Skill |
@@ -36,7 +42,8 @@ description: 已初始化吾码工作区的默认 AI 开发总控入口，用户
 | 菜单骨架、AI 开发中占位、逐菜单切换、PageTabs、模块展示 | `module-engine`、`v8-menu-buttons` |
 | 选项 Key/Label、数据源、状态模板 | `microi-datasource-mapping`、`datasource-engine`、`v8-template-engine` |
 | 业务接口、表单事件 | `v8-crud-api`、`v8-table-event` |
-| 微服务、个人中心、菜单应用、定制组件或复杂弹窗 | `microi-microservice`、`microi-client-frontend`、`ui-design`；必须先读主题色、明暗、密度和样式隔离契约，不能只读模板后实现 |
+| 前端微服务、个人中心、菜单应用、定制组件或复杂弹窗 | [微服务](../microi-microservice/SKILL.md)、[宿主前端](../microi-client-frontend/SKILL.md)，结合上方两份 UI Skill 核对宿主主题色、明暗、密度和样式隔离 |
+| 移动端页面（UniApp、移动 H5、App、微信小程序） | [UniApp 前端](../microi-uniapp-frontend/SKILL.md)、[移动端质量](../microi-mobile-app-quality/SKILL.md)，结合上方两份 UI Skill 核对导航、触控、动效和目标端验收 |
 | MCP 连接入口、角色 AI 开发授权 | `microi-codex`、`v8-security`；服务端逐请求复核范围与操作开关，普通表单路由不能作为绕过通道 |
 | 业务统计、老板经营、领导管理看板及明细报表 | `page-engine`、`report-engine`、`datasource-engine` |
 | 真实业务、截图、账号和跨端验收 | `playwright-e2e`；有独立前端时再读相应前端 Skill |

package/skills/microi-system-delivery/references/delivery-pitfalls.md

@@ -47,6 +47,25 @@
 | 24 | 为同步干净覆盖他人修改、清理误伤共享目录 | 保存本任务文件/进程清单，冲突先三方合并；只收尾可证归属的临时路径，不删共享依赖或其它任务变更。分别列出本任务差异与外部差异，不为零计数覆盖远端 | `workspace-conventions`、`context-quality.md` |
 | 25 | 本地更新 Skills 就称所有用户已获得 | 规范正文单源维护，同步已注册内嵌知识和插件/CLI资源，验证宿主默认路由及包内文件/哈希；源码、构建包、发布渠道和新工作区实际初始化分别记回执。未实际跑过的模型不称已实测 | `microi-docs-coverage`、`microi-codex-installer` |
 
+## 跨端与长任务中容易遗漏的边界
+
+| 现象 | 下一次执行方法 | 所属规范 |
+|---|---|---|
+| 独立 H5 是手机预览，嵌入原菜单却拉满桌面 | 将呈现目的与 embedded 分开；移动预览保持内屏尺寸，工作台才满宽。比较真实 CSS viewport、宿主可用区域、底栏与滚动所有者 | `ui-design/references/mobile-product-language.md` |
+| 功能和构建通过，整体视觉仍粗糙 | 先明确移动产品表达强度，再统一 token、图标、Tab、表单与动效；逐页面模式截图批判。图标间距/中心线和触控尺寸做实际几何断言 | `microi-ui`、`microi-mobile-app-quality` |
+| 角色通过率看似很高，仍漏了大量管理动作 | 开工建立角色×资源×动作×范围分母，单列原生菜单、H5工作台、报表、附件和混合角色；每格记录真实身份、写后回读与失败分支 | `playwright-e2e`、`v8-security` |
+| 网络丢响应后重复聊天、出入库或资产命令 | 幂等键、初始 ExpectedVersion 与业务意图绑定；重试先回读相同业务键，保持首次参数。不能重新生成意图或用最新版本重放旧意图 | `v8-crud-api` |
+| 私有附件路径签名正确但归属仍不安全 | 同时核对实际业务记录、上传者/关联对象、当前角色范围和存储路径；公共商品图与私有工单图分别处理，签名不能代替授权 | `uniapp-mall-assets`、`v8-security` |
+| 普通业务 DTO 被宿主传输字段污染 | 白名单剥离已确认的宿主元数据，业务字段继续严格拒绝未知项；不要整体关闭参数校验 | `microi-microservice`、`v8-security` |
+| 接口源码能运行，但拉取与本地生成永久有差异 | 逐引擎保存发布头和 schema 快照依赖；对未使用新字段的旧引擎声明快照例外，按实际全文回读验证，不伪造零差异 | `v8-crud-api`、`context-quality.md` |
+| 大目录同步调用超时，被误判失败或直接重写 | 为目录操作配置有界长超时与进度续时；未知结果先比候选 manifest，并逐文件回读原始字节。候选已原子提交时不重复上传或取得新基线补票 | `microi-microservice`、`v8-file-upload` |
+| 对比度检查忽略渐变/透明叠层而误报或漏报 | 同时检查实际合成背景与渐变最不利位置，保留实色降级背景；不能通过降低阈值或只测白底消除失败 | `ui-design`、`playwright-e2e` |
+| 主租户短信可用，被假定子租户也有凭据 | 只读核对成对凭据、签名/模板、可信新用户最低角色和会话链；使用受审阅的安全迁移工具，缺能力明确缺口，不取明文、不盲拷密文、不伪造发送成功 | `microi-mobile-app-quality/references/mobile-first-delivery.md` |
+
+### 失败记录要区分归因
+
+命令路径猜错、`rg` 无匹配、缺少本机包管理器、测试程序读取协议字段错误，与平台真实缺陷分别记录。搜索先使用 `rg --files`，读取按语义范围和输出预算进行；依赖、凭据、源码基线与验收分母在首次业务开发前验证。不要给每个项目复制庞大一次性测试脚本，优先维护可复用的小工具与明确的失败恢复点。
+
 ## 失败时的交付规则
 
 - 修复清单必须保留用户原编号及默认交付 1–10 的映射，不用“优化完成”代替位置、证据与未完成项。