@microi.net/cli 4.9.3 → 4.9.5

package/skills/microi-form-layout/SKILL.md

@@ -143,10 +143,11 @@ Q1: 核心可见字段数、子表和强任务域？
   "Name": "MrpGroup",
   "Label": "MRP 运算",
   "Component": "CollapseGroup",
-  "Type": "varchar(50)",
+  "Type": "",
   "Sort": 120,
   "Visible": 1,
   "AppVisible": 1,
+  "FormWidth": 24,
   "Config": "{\"CollapseGroup\":{...}}"
 }
 
@@ -164,6 +165,10 @@ Q1: 核心可见字段数、子表和强任务域？
 
 **作用范围**：从该 CollapseGroup 字段开始，到下一个 `Component in (Tabs, CollapseGroup, Divider)` 字段为止。
 
+**默认值硬规则**：`CollapseGroup` 必须保存 `FormWidth=24`（PC 表单 100% 宽度）；
+`Config.CollapseGroup.ShowFieldCount` 省略时必须补为 `true`。只有用户明确要求隐藏数量时
+才允许写 `ShowFieldCount=false`，只有用户明确要求非整行实验布局时才允许覆盖宽度。
+
 **与 Tab 的关键区别**：所有 CollapseGroup 标题**始终可见**，分组内字段**默认展开**或**默认收起**，但所有分组的字段**都在同一页面**，可同时展开多个。
 
 ### 3.4 控件视觉对比
@@ -223,6 +228,7 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 - 字段数 13~30 的表单，必须有可见的**业务分组**（Tab 或 CollapseGroup 二选一），不能让用户上下滚动 5 屏找字段。
 - 创建 CollapseGroup 分组时，必须设置 `Icon`（如 `fas fa-calculator` / `fas fa-info-circle`），不要默认空白。
 - 任何 Tab / CollapseGroup 都必须有 `Description` 解释分组用途，不要只放一个标题。
+- 每个 CollapseGroup 必须回读到 `FormWidth=24`；`Config.CollapseGroup.ShowFieldCount` 默认必须为 `true`。
 - 修改 `diy_table.Tabs` 或 `diy_field.Tab` / `Config.CollapseGroup` / `Config.FieldTabs` 后，必须调用 `microi_refresh_schema_cache`。
 - Tab 内嵌套 CollapseGroup 时，CollapseGroup 必须设 `DefaultCollapsed=true`（默认收起），避免 Tab 内继续被折叠分组抢首屏空间。
 - 新增布局节点后必须同时回读 `diy_field` 元数据和目标业务表结构，确认没有新增物理业务列；若当前工具不提供仅元数据能力，只报告设计建议，不得绕过后端直接写表。
@@ -233,7 +239,7 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 - ❌ **禁止**仅凭 13~30 个原始字段决定平铺或分 Tab；总有效行超过 6 且存在明确业务域时，至少使用 CollapseGroup 分组。
 - ❌ **禁止**为 8~10 字段的简单业务表创建多层 Tab 嵌套（直接用 CollapseGroup 即可）。
 - ❌ **禁止**在用户没有要求时使用 `Tabs` 字段控件（`diy_field.Component='Tabs'`），更优先用 `diy_table.Tabs`。
-- ❌ **禁止**为 `Tabs` / `CollapseGroup` / `Divider` / `Alert` 等布局控件设置 `FormWidth=24`，这些控件天然占整行。
+- ❌ **禁止**让 `CollapseGroup.FormWidth` 为空或依赖表默认列宽；CollapseGroup 默认必须显式保存 `FormWidth=24`。Tabs / Divider / Alert 继续按各自运行时规范处理。
 - ❌ **禁止**只创建 Tab 不写字段的 `Tab` 归属（每个 Tab 必须有至少 1 个非空 `Tab` 的字段）。
 - ❌ **禁止**用 Tabs 控件的 `FieldCount` 跨过 CollapseGroup 或 Divider 计数（不同布局控件的计数是隔离的）。
 - ❌ **禁止**把高频访问的字段（如单据编号、项目名称）放进默认收起的 CollapseGroup。
@@ -244,6 +250,7 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
 修改或新建表单布局后，AI 必须按以下顺序验收：
 
 1. **回读字段**：`microi_get_field_list` 检查 `Tab` / `Component` / `Config` 与设计一致。
+   CollapseGroup 还必须检查 `FormWidth=24`、`Config.CollapseGroup.ShowFieldCount=true`（除非用户明确覆盖）。
 2. **回读表与结构**：`microi_get_table_data _SelectFields=['Id'] _PageSize=1` 验证表可读，并检查实时表结构未因纯布局节点新增物理业务列。
 3. **清缓存**：`microi_refresh_schema_cache tables=['表名']`。
 4. **手动打开表单**：通过 Playwright 或 V8 引擎调用，截图第一屏。
@@ -253,6 +260,10 @@ V8 事件中可用 `V8.HideFormTab('tabId')` / `V8.ShowFormTab('tabId')` / `V8.C
    - 没有任何"只剩 1 个字段的 Tab"。
 6. **业务闭环**：新建一条测试数据、编辑、查看、删除，验证字段在正确分组中显示。
 
+若“表单设计器能看到、真实新增/编辑/查看表单看不到”，必须先读取表级 `InFormV8`
+以及相关字段 V8，搜索 `V8.FieldSet`、`hideField`、`Visible=false`、`HideFields`。设计模式
+通常跳过这些运行态事件；未完成这一步不得直接判定为 Microi.Client 渲染缺陷。
+
 ## 7. 反例参考（必须避免）
 
 ### 反例 1：MRP 运算 3 字段单独建 Tab
@@ -328,11 +339,10 @@ microi_update_table({
 
 ```js
 // 1. 创建一个 CollapseGroup 字段
-microi_add_field({
+microi_add_layout_field({
   tableId: "01KTASHWEBE514R1XTB0WVJJRX",
   name: "MrpGroup",
   label: "MRP 运算",
-  type: "varchar(50)",
   component: "CollapseGroup",
   sort: 150,
   visible: 1,
@@ -346,9 +356,12 @@ microi_add_field({
       Theme: "primary",
       ShowFieldCount: true
     }
-  })
+  }),
+  confirmExecution: "MrpGroup"
 })
 
+// 工具默认写入 FormWidth=24；回读必须确认宽度为 24 且 ShowFieldCount=true。
+
 // 2. 让"MRP 运算"相关字段归属到该 CollapseGroup
 // 范围方式：把 CalcStatus、CalcBatchNo、MrpTime 三个字段的 Sort 排在 150~300 之间，
 // 下一个 CollapseGroup/Tabs/Divider 字段之前的所有字段都属于该分组

package/skills/microi-microservice/SKILL.md

@@ -67,7 +67,7 @@ src/
 AppKey 稳定且只含安全字符。`microi.routes.json` 是页面事实源，删除/新增路由后由
 发布流程同步 `sys_microiservice_page`，不要从 Vue 源码猜路由。
 
-本地项目必须位于当前连接对应的 `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}`。`microi.apps/` 是官方应用商城发行包工程目录，不是 MicroService 源码目录；发行包只能引用、构建或快照当前租户的唯一源码，不得在包内嵌套第二份可编辑 `microservice/` 工程。
+本地项目必须位于当前连接对应的 `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}`。该应用目录同时承载 MicroService 源码、Manifest、接口引擎、资源策略、测试和应用商城上传素材，是唯一事实源；禁止创建平行的 `microi.apps/` 发行根，也不得在应用内嵌套第二份可编辑 `microservice/` 工程。
 
 构建前遵守本地 OOM 保护；已有 dev server 可复用时不重复启动。新脚手架必须支持独立
 访问时的平台帐号登录，但独立 Vite 预览仍没有菜单/弹窗等完整宿主上下文，不能替代宿主验收。

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

@@ -99,12 +99,12 @@ Detail/Edit 自定义表单，不能用它关闭 List/Card 展示设计。
 - ❌ **禁止**为 ≤7 字段的业务域单独建 Tab（必须改用 `CollapseGroup`，否则用户必须点击 Tab 才能看到 3~5 个字段，违反"首屏信息密度"原则）。
 - ❌ **禁止**为 13~30 字段的表把所有字段平铺（必须用 Tab 或 CollapseGroup 分组）。
 - ❌ **禁止**在用户没有要求时使用 `Component='Tabs'` 字段级控件（更优先用 `diy_table.Tabs` 表级 Tab）。
-- ❌ **禁止**为 Tabs / CollapseGroup / Divider / Alert 等布局控件设置 `FormWidth=24`（这些控件天然占整行）。
+- ❌ **禁止**让 CollapseGroup 依赖空 `FormWidth`；CollapseGroup 默认必须显式保存 `FormWidth=24`，并默认设置 `Config.CollapseGroup.ShowFieldCount=true`。Tabs / Divider / Alert 按各自运行时规范处理。
 - ❌ **禁止**只创建 Tab 不写字段的 `Tab` 归属（每个 Tab 必须有至少 1 个非空 `Tab` 的字段）。
 
 典型反例：`yutaoliaojieguo` 表 13 字段有"MRP 运算"3 字段 Tab — 这是错误的，应该用 `CollapseGroup` 把 MRP 3 字段收起（默认展开），让用户第一屏看到基础信息 + MRP 字段而不是必须点击 Tab 切换。详见 `microi-form-layout/SKILL.md` 的"反例参考"章节。
 
-表单控件选择必须参考 `Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json`，包括文本、数字、日期、选择、树、部门、地址、关联表单、弹窗选表、子表、上传、富文本、代码、地图、二维码、布局控件等；普通字段不手动设置 `FormWidth`，整行控件才设 `24`。
+表单控件选择必须参考 `Microi.Client/src/views/form-engine/diy-field-component/diy-component-list.json`，包括文本、数字、日期、选择、树、部门、地址、关联表单、弹窗选表、子表、上传、富文本、代码、地图、二维码、布局控件等；普通字段不手动设置 `FormWidth`，整行控件才设 `24`。CollapseGroup 必须显式设 `24`，并默认开启 `ShowFieldCount`。
 
 ### 3. 主子表与关联表单设计
 
@@ -124,6 +124,9 @@ Detail/Edit 自定义表单，不能用它关闭 List/Card 展示设计。
   关系语义审查。MCP 会硬性拒绝“1:N + JoinForm”、自关联 JoinForm、缺主/子外键、缺
   `Display=0/AppDisplay=0/HasChild=0` 隐藏子菜单或缺 `(OsClient, FK)` 回查索引；AI
   不得改用直接单字段工具绕过。
+- 复用已有子表时，优先复用源 `TableChild` 已验证、当前用户有权限的子表菜单；只有不存在
+  可复用菜单时才新建隐藏菜单。设计器显示但运行表单不显示时，必须先检查主表 `InFormV8`
+  是否通过 `V8.FieldSet`/`hideField` 把目标 TableChild 设为不可见。
 
 `JoinForm` 的可移植 Manifest 只写名称，不写租户 Id：
 

package/skills/print-engine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: print-engine
-description: 生成和审查 Microi 打印引擎 Print Engine 模板 JSON。用于创建 mic_print 模板、PageObj 布局、PrintObj 数据绑定、可打印报告、标签或合同。
+description: 生成和审查 Microi 打印引擎 Print Engine 模板 JSON。用于创建 mic_print 模板、PageObj 布局、PrintObj 数据绑定、可打印报告、标签或合同；蓝牙 TSPL/CPCL/ESC-POS、GP-M322 或 CC4 需求转交 v8-frontend-events 蓝牙参考。
 ---
 
 > **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
@@ -19,14 +19,15 @@ description: 生成和审查 Microi 打印引擎 Print Engine 模板 JSON。用
 ## 与蓝牙直连打印的边界
 
 本 Skill 负责 `mic_print`、`PageObj`、`PrintObj`、浏览器预览和模板化纸张输出。
-如果需求明确是蓝牙标签机/小票机、TSC/TSPL、ESC/POS 或
+如果需求明确是蓝牙标签机/小票机、TSC/TSPL、CPCL、ESC/POS、佳博 GP-M322、
+ZICOX CC4、BLE/SPP 或
 `V8.Print.prepareSend`，应同时读取
 `../v8-frontend-events/references/bluetooth-print.md`：
 
 - Print Engine 决定“页面/模板如何排版”，适合 A4、PDF、浏览器打印和统一模板。
-- `V8.Print` 生成打印机原生命令并通过 BLE 写特征，适合标签和热敏小票。
+- `V8.Print` 生成/适配打印机原生命令并通过 BLE 或 Android SPP 写入，适合标签和热敏小票；GP-M322 保持 TSPL 原字节，CC4 可自动生成 CPCL。
 - 两者可以由同一个按钮按设备能力选择，但不能把 `PageObj` 直接交给
-  `V8.Print.prepareSend`，也不能把 TSC/ESC 字节当作 Print Engine JSON。
+  `V8.Print.prepareSend`，也不能把 TSPL/CPCL/ESC-POS 字节当作 Print Engine JSON。
 
 ## 数据模型
 

package/skills/unity-integration/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: unity-integration
+description: Microi吾码 Unity、UPM SDK、WebGL、3D 游戏/数字孪生、DiyToken/V8 通讯、AI 应用商城交付与完整验收规范。用于评估或提取 Unity 工具箱，创建 Microi.Unity 包，开发 WebGL 场景，接入 Microi.Client 宿主与 V8 接口，引入可授权素材，发布可安装 AI 应用，或审查 Unity 代码是否错误进入 Microi.Server。
+---
+
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
+# Microi Unity 完整交付
+
+目标不是“做出一个 Unity 工程”，而是交付一条可复用、可安装、可升级、可验证的 Microi 3D 应用链。
+
+## 按任务读取参考
+
+| 当前任务 | 必须读取 |
+|---|---|
+| 新建或调用 `Microi.Unity` | `references/sdk-api.md` |
+| WebGL 模板、Microi.Client/AI 应用宿主、性能与部署 | `references/webgl-hosting.md` |
+| AI 应用源码、商城包、官方发布与安装回读 | `references/ai-app-delivery.md` |
+| 从已有客户项目提取 Unity 工具箱或素材 | `references/toolbox-migration.md` |
+
+若任务横跨多项，逐个读取相应参考，不从文件名猜协议。
+
+## 先做架构裁决
+
+1. Unity 客户端 SDK 使用仓库根级 UPM 包：`Microi.Unity/package.json`。
+2. `UnityEngine`、`UnityWebRequest`、Editor API 和 `.jslib` 不进入 `Microi.Server` 的 .NET 类库。
+3. 玩家进度、设备状态、任务、积分和交互记录优先由 V8 接口引擎编排。
+4. 只有缺失的平台级可信协议、鉴权、密钥隔离或底层原子能力，才允许修改 `Microi.Server`；修改前必须说明 V8 为什么无法完成。
+5. 实时房间、租约、进度和去重事实必须按 `OsClient` 存入共享数据库、Redis 或可靠消息系统，不能用单节点内存字典当事实源。
+
+推荐目录：
+
+```text
+Microi.Unity/                         公共 UPM SDK
+├─ Runtime/Api/                       UnityWebRequest 与 DosResult
+├─ Runtime/WebGL/                     C# 浏览器桥
+│  └─ Plugins/WebGL/*.jslib
+├─ Editor/                            通用构建工具
+└─ Samples~/                          可运行最小示例
+
+AI-Project/<project>/Unity/           具体 Unity 工程与场景
+Microi-V8-Engine/.../AI应用/<appKey>/ 唯一 AI 应用源码与商城资源
+microi.doc/docs/doc/system-engine/    官方长期文档
+```
+
+## 标准工作流
+
+### 1. 发现与盘点
+
+- 读取 Unity 版本、渲染管线、`Packages/manifest.json`、场景、Editor、Runtime、WebGL Plugins 和现有构建脚本。
+- 搜索 Microi.Client 已有 Unity 宿主、现有 V8 Key、官方 AI 应用是否重名。
+- 为模型、动作、贴图、字体、音频逐项记录来源、作者、许可证、版本和是否允许再分发。
+- 在启动 Unity、Node、浏览器或构建前检查物理内存、同类进程、端口与任务归属。
+
+### 2. 分离公共能力与业务能力
+
+- API 客户端、DosResult、上下文注入、Token 轮换、浏览器事件和通用构建工具进入 UPM。
+- 相机路径、触发区、特定场景模型、关卡、客户设备协议与业务脚本留在具体项目。
+- 首次提取采用复制和重构；新包完成引用替换与回归前，不移动或删除旧项目文件。
+- 公共包必须有 `package.json`、asmdef、README、LICENSE、CHANGELOG 与 Sample。
+
+### 3. 建立 WebGL 宿主握手
+
+- Unity 就绪后由宿主用 `SendMessage` 注入 `ApiBaseUrl/OsClient/Authorization/Did`。
+- 会话只保存在运行时内存；禁止 Token 进入 URL、场景、Prefab、日志、构建产物或版本库。
+- `.jslib` 只提供稳定事件：ready、authorization rotated、business event。
+- Token 轮换回调同时携带发起请求时的旧 Token；宿主先做迟到响应保护，再更新统一会话。
+- 页面离屏暂停；组件卸载调用 Unity `Quit()`，清理 iframe/Canvas、WASM、WebGL 上下文、监听器与全局回调。
+
+### 4. 用 V8 设计服务端
+
+```text
+POST {ApiBase}/apiengine/{ApiEngineKey}
+Content-Type: application/json
+osclient: {OsClient}
+apiengine: 1
+authorization: Bearer {DiyToken}
+did: {DeviceId}
+```
+
+- 身份只取 `V8.CurrentUser`；禁止相信客户端 UserId、角色、部门或权限结论。
+- 重新校验坐标、数量、字符串长度、状态转换和资源归属。
+- 写接口使用稳定 `RequestId/EventId` + 数据库唯一索引/幂等台账；锁不能替代幂等。
+- 匿名多人由服务端签发 `SessionId + SessionSecret`；数据库只保存秘密哈希，公开快照不得返回秘密、UserId、设备指纹或内部权限字段。
+- 在线角色、房间版本和掉线到期时间进入共享数据库/Redis；客户端心跳、接口重试和节点切换都不能依赖进程内字典。
+- 位置心跳由服务端限制地图边界、最大速度和递增序列；过期查询以服务端时间为准，正常离场与租约超时都必须幂等。
+- 公屏文字限制长度、频率、表情白名单与稳定请求 ID；DOM 输入框阻止键盘事件冒泡，避免聊天时角色继续移动。
+- 接口引擎 `Code=1` 自动提交，失败返回其它 Code 自动回滚，不手动 Commit/Rollback。
+- 表、索引、菜单、接口与权限通过应用 Manifest 安装，不为游戏资源新增 `Microi.Upgrade` 定制迁移。
+- 所有接口必须声明 `ResourcePolicies.ApiEngines`：官方核心 `Managed`；租户扩展 `CreateIfMissing`，后续升级不覆盖。
+
+### 5. 构建可安装 AI 应用
+
+- `ApplicationType` 使用 `Web`；Vue 3 + Vite + TypeScript 作为页面外壳，Unity Canvas/WebGL 与普通 DOM 分层。
+- 官方租户的 `AI应用/<appKey>` 是私有源码、构建脚本、V8、Manifest 与商城合约的唯一编辑根。
+- 页面必须 poster-first：未启动时不下载大体积 WASM/Data；提供加载、错误、重试、全屏、退出和低性能提示。
+- 多人界面要显示本地及远端昵称；同模型远端角色使用快照插值，失效租约及时销毁；公屏固定在不遮挡核心操作区的位置并支持键盘与表情选择。
+- 构建门禁必须拒绝缺失 Unity 产物的“空壳发布”，并校验 WASM、Data、体积、哈希、本机地址、source map 与疑似硬编码 Token。
+- 先同步私有源码，再发布不可变 Web 产物，最后生成/发布商城包；三个动作分别回读。
+
+### 6. 补齐官网与 Skill
+
+- 长期能力在中文官网“系统引擎”下建立独立页面，并加入 `mapping_zh.json`、视觉画像与文档责任映射。
+- 页面优先使用主视觉、架构卡、步骤卡和折叠技术细节；不要用连续大段文字堆满屏幕。
+- 不手工维护 `microi.doc/docs/en/`，不因普通功能文档修改 `about/update-log.md`。
+- 文档至少覆盖：架构边界、UPM 安装、宿主握手、V8 请求、安全、CORS、构建、部署、商城安装和分层验收。
+
+## 资产与视觉红线
+
+- AI 生成素材保存逐图提示词、生成时间、用途和源文件；不要只提交最终图片。
+- AI 设定图、渲染目标图与真实 Unity 运行截图必须分开标注；未通过实机近景、拓扑、材质、性能验收时禁止宣称“与设定图一模一样”或“商业 AAA 已达成”。
+- 网络素材必须允许商业使用和再分发；许可证不清晰就改用原创、程序化或明确授权素材。
+- 官方包不携带客户专属场景、品牌秘密、私有协议或无法追溯的二进制模型。
+- “超清”不能只靠大纹理：同时控制材质、光照、阴影、LOD、裁剪、像素比和下载体积。
+- 支持浅/深色外壳、键盘焦点、减少动效偏好、响应式安全区与清晰错误状态。
+
+## WebGL 质量基线
+
+- 使用仓库已验证的 Unity LTS；WebGL 采用兼容的 Built-in 或 URP，不走 HDRP。
+- 校验 WebGL 2、WASM、正确 MIME、gzip/Brotli 响应头或解压回退、高 DPI 上限、全屏、键鼠/手柄、焦点恢复和退出释放。
+- WebGL 必须经 HTTP(S) 验收，不能用 `file://`。
+- Unity 2022.3 不把移动浏览器描述为官方支持；移动端需要独立触控、内存、画质和弱网测试。
+- 程序化创建、反射或字符串类型名先用 `link.xml` 精确保留；若 WebGL 仍报告原生 `class ID` 被裁剪，可对该构建关闭 `PlayerSettings.stripEngineCode`，但必须复核包体和浏览器控制台。
+- WebGL 模板设置 `autoSyncPersistentDataPath: true`，并把弃用警告也纳入控制台验收。
+- 同一次高资源阶段只运行一个 Unity/Node/浏览器重任务，并遵守工作区 OOM 保护。
+
+## 分层验收矩阵
+
+| 证据层 | 必须断言 |
+|---|---|
+| 源码 | UPM 可解析、C# 编译、V8/Manifest/策略测试、安全扫描 |
+| Unity Editor | Play、移动、奔跑、跳跃、碰撞、交互、暂停恢复 |
+| WebGL | IL2CPP/WASM 构建成功，Loader/Data/WASM 完整 |
+| 浏览器 | HTTP 加载、全屏、输入、控制台、DPR、退出释放 |
+| Microi 租户 | 当前用户隔离、Token 轮换、保存重放、无权失败 |
+| 多人在线 | 至少两个独立会话互见唯一昵称、移动与动作；异常断线超过租约后双方快照均不再返回该角色 |
+| 实时公屏 | 两个独立会话互相收发文字与表情；非法表情、超长、超频和请求重放均被正确处理 |
+| 多节点 | 重复投递、节点切换、失败恢复时副作用仅一次 |
+| AI 应用 | 私有源码回读、运行版本哈希、列表/详情公开可见 |
+| 应用商城 | 包版本/策略回读，非官方租户安装与升级通过 |
+
+任何未执行层都要明确写成未验证或受阻。应用受理编号、源码测试或本地构建不能替代公开 URL、真实租户和非官方安装证据。
+
+## 停止发布的条件
+
+- Unity 许可证未激活或 WebGL 模块缺失。
+- Unity 构建只有外壳，没有真实 WASM/Data。
+- 素材许可证、AI 提示词或资产来源不可追溯。
+- 正式产物出现本机地址、Token、source map 或超限单文件。
+- 官方应用重名、目标版本不明确、远端源码/运行版本基线未回读。
+- 商城包缺少 `ResourcePolicies.ApiEngines`，或把租户 Hook 错设为 `Managed`。

package/skills/unity-integration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Microi Unity 集成"
+  short_description: "交付 Unity UPM、WebGL、V8 与可安装 AI 应用"
+  default_prompt: "使用 $unity-integration 设计、实现并分层验收完整的 Microi Unity WebGL 应用。"

package/skills/unity-integration/references/ai-app-delivery.md

@@ -0,0 +1,98 @@
+# Unity AI 应用与商城交付
+
+## 唯一源码
+
+官方 AI 应用源码放在当前官方连接对应的：
+
+```text
+Microi-V8-Engine/<connection>/<product>/AI应用/<appKey>/
+```
+
+同一应用的 Vue 外壳、Unity 构建接入、V8 源码、Manifest、资源策略、测试和发布合约都从这里生成。Unity 工程可以保留服务端镜像，但必须由唯一源码生成并做一致性检查。
+
+最小文件：
+
+```text
+.microi-micro-app.json
+app.json
+package.json
+microi.routes.json
+package-contract.json
+resource-policies.json
+system.manifest.json
+src/
+public/
+server/engines/
+scripts/
+tests/
+```
+
+## Web 外壳
+
+- Vue 3 + Vite + TypeScript。
+- 复用工作区标准 `microi.v8.js` 与 `microi-ai-app-auth.js`，不要复制改造出第二套认证协议。
+- 匿名模式可以承载公开多人玩法，但必须使用服务端签发、只存哈希、可过期的会话秘密；个人持久化接口仍要求 DiyToken。
+- `ApplicationType=Web`，独立入口为 `index.html`。
+- 构建状态明确区分 `available` 与 `publishable`；无真实 Unity WASM/Data 时禁止正式发布。
+- WebGL 公屏优先使用可访问的 DOM 输入控件并拦截键盘传播；Windows 可使用原生 UI/UIToolkit。不要在外壳和 Unity 中重复绘制同一组操作提示。
+
+## 多人租约与公屏交付
+
+- 在线角色的事实源使用按 `OsClient` 隔离的共享数据库/Redis，不能使用 API 节点静态字典；客户端心跳周期必须短于租约超时。
+- 加入响应只向本人返回会话秘密；数据库保存 SHA-256，位置快照只公开昵称、受限坐标、朝向、动作与房间版本。
+- 正常卸载/离开主动调用 leave；浏览器崩溃、断网或 `kill -9` 依靠服务端租约自然失效，并通过两个真实客户端测量消失时间。
+- 公屏接口校验在线会话、内容长度、表情白名单、速率窗口和请求幂等；公开读取只返回有限时间窗和有限条数。
+- 轮询是兼容基线；接入 WebSocket/SignalR 时仍保留共享租约为事实源，并用 V8 授权接口签发短期频道权限。
+
+## WebGL 与 Windows 双端交付
+
+- WebGL 与 Windows 必须来自同一个 Unity 工程、场景和语义版本；禁止用旧本地包搭配新网页版本。
+- Windows 默认交付 x64 安装包，至少包含当前用户安装、开始菜单入口和卸载信息；没有明确需求时不申请管理员权限。
+- 外壳应给出醒目的本地版下载入口，并同时显示版本、文件大小与 SHA-256；文件名包含语义版本，旧版本 URL 不覆盖。
+- 安装包属于公开运行资产，不属于私有源码。同步 `directory` 前必须排除 `public/downloads` 等生成目录，再把完整安装包随 `dist` 走流式资产发布；禁止拆分 Base64 或伪装成源码规避单文件上限。
+- 发布后从公网地址重新下载完整 EXE，比较字节数和 SHA-256；本地制包成功、MCP 返回文件 Id 或 HTTP HEAD 成功都不能替代完整回读。
+- 本地验收至少覆盖静默安装、主程序存在、可启动和卸载入口；签名状态、SmartScreen 信誉和硬件帧率必须单独如实说明。
+
+## 商城资源
+
+游戏进度表使用应用前缀 `app_*`，不要占用平台保留的 `mci_*` 名称。技术幂等表可以不创建可见菜单；玩家运营表创建父菜单 + 子数据菜单，隐藏 UserId、RequestId、哈希等技术字段。
+
+接口策略示例：
+
+```json
+{
+  "SchemaVersion": 1,
+  "ApiEngines": {
+    "app_game_bootstrap": { "Ownership": "Application", "UpgradePolicy": "Managed" },
+    "app_game_save": { "Ownership": "Application", "UpgradePolicy": "Managed" },
+    "app_game_after_save": { "Ownership": "Tenant", "UpgradePolicy": "CreateIfMissing" }
+  }
+}
+```
+
+租户 Hook 使用新的稳定 Key；首次安装后归租户维护，同 Key 后续版本不能改回 `Managed`。
+
+## 官方发布顺序
+
+只有当前 MCP 明确绑定官方 `https://api.itdos.com`、`OsClient=iTdos` 且用户已授权写入时才执行：
+
+1. `microi_list_applications` 按精确 AppKey/中文名查重。
+2. 读取远端应用上下文、源码版本、运行版本、行版本/围栏与路由快照。
+3. 本地完成类型检查、测试、真实 Unity 构建和 dist 完整性校验。
+4. 先同步私有源码；生成的 Unity、安装包与构建证据目录不得混入源码清单。任何期望版本不一致都停止重基线。
+5. 发布不可变 Web 运行版本，回读入口、文件数、哈希、状态与公开 URL。
+6. 若同时交付 Windows，从稳定公网地址下载完整安装包并核对大小、SHA-256 和版本；在线入口还要加载真实 WASM/Data。
+7. 调用官方 `ai_app_publish_store` 生成并发布精确版本的应用商城包。超时属于结果不确定，必须回读包正文和 ZIP 后才能决定是否重试。
+8. 回读 `sys_microistore` 的 AppKey、版本、状态、预览图、包摘要与资源策略，断言 `AppVersion == PackageInfo.Version == PreparedAssets.PackageVersion`。
+9. 在官网 `/apps.html` 和 `/app-detail.html?app=<appKey>` 做公开页面回读。
+10. 在一个非官方测试租户安装，回读表、菜单、接口和 Hook 所有权；再验证升级不覆盖租户 Hook。
+11. 多人应用用两个独立浏览器会话互相验证昵称、位置、公屏；强制关闭一端，确认超过约定租约后另一端不再看到该角色。
+
+源码同步、运行发布、商城发布、官网可见、目标租户安装是五项独立事实。任一步只有受理 ID 或 `doing` 状态，都不能报告最终成功。
+
+## 版本与回滚
+
+- 运行产物不可变；相同版本不可覆盖为不同哈希。
+- 商城版本必须精确对应已验证运行版本与 Manifest。
+- 升级遵循先扩展、后迁移、再收缩；新旧运行版本短暂并存时协议向前/向后兼容。
+- 回滚恢复上一不可变运行版本；数据库变更需要显式兼容/补偿方案，不能用文件回滚伪装数据回滚。

package/skills/unity-integration/references/sdk-api.md

@@ -0,0 +1,82 @@
+# Microi.Unity SDK API
+
+## 包边界
+
+`Microi.Unity` 是 Unity Package Manager 包，不是普通 .NET 类库。Runtime 代码兼容项目选定的 Unity LTS 和 C# 语言级别；Editor 代码使用独立 asmdef，不能被播放器编译。
+
+## Editor Toolbox 菜单与边界
+
+| 菜单 | 能力 | 可恢复保证 |
+|---|---|---|
+| `Camera Points...` | 按前缀与完整层级路径导入导出 Transform/Camera | 导入注册 Unity Undo |
+| `Mesh Combine...` | 对选中场景根节点按材质合并 Mesh | 精确保存源 Renderer；Restore 或 Undo；生成 Mesh 资产保留 |
+| `Texture Optimization...` | 对 Project 窗口选中目录分析和修改 importer | 修改前写 `ProjectSettings/MicroiUnityBackups` JSON，可恢复 |
+| `Analyze Active Scene` | Mesh、顶点、三角面、材质、Camera、Light 统计 | 只读，不把结构统计换算成虚假 FPS |
+| `Analyze Camera Depth Precision` | near/far 深度比诊断 | 只读 |
+| `WebGL Quality and Depth...` | Balanced/High Definition 画质和选中 Camera 深度 | 画质先备份 JSON；Camera 使用 Undo |
+| `Remove Camera Components...` | 清理选中层级里的 `CameraPoint_` Camera | 仅选中范围，支持 Undo |
+
+禁止把工具改回全场景、全工程无范围扫描。凡是修改 AssetImporter、质量设置或生成 Mesh 的新功能，都必须先定义备份、恢复和失败中断语义。
+
+```text
+Runtime/Api/MicroiApiClient.cs
+Runtime/Api/MicroiApiModels.cs
+Runtime/WebGL/MicroiWebGLBridge.cs
+Runtime/WebGL/Plugins/WebGL/MicroiWebGLBridge.jslib
+Editor/MicroiWebGLBuildUtility.cs
+Samples~/V8ApiQuickStart/
+```
+
+## MicroiApiClient
+
+场景保持一个名称稳定的 `MicroiApiClient` GameObject。主要方法：
+
+- `Configure(baseUrl, osClient, did)`：规范化 API 地址和租户上下文。
+- `SetAuthorization(tokenOrBearerValue)`：去掉 Bearer 前缀，仅保存在内存。
+- `ClearAuthorization()`：登出或宿主切换时清空会话。
+- `ApplyMicroiHostContext(json)`：供 WebGL `SendMessage` 调用。
+- `Post<TRequest,TData>()`：类型化 DosResult 请求。
+- `PostJson()`：发送原始 JSON；ApiEngineKey 只允许字母、数字、点、下划线与短横线。
+
+事件：
+
+- `HostContextApplied`：宿主上下文完成更新。
+- `AuthorizationRotated`：响应头返回新 DiyToken。
+
+不要把 Token 暴露为可序列化字段或 Unity Inspector 字段。日志只允许记录状态，不输出请求头、Token 或完整敏感响应。
+
+## DosResult 模型
+
+成功判断同时考虑 HTTP 状态和 `Code=1`。`Code=1001/1002` 应交给宿主认证层处理，不能由 Unity 自行伪造新 Token。
+
+```csharp
+StartCoroutine(client.Post<SaveRequest, SaveData>(
+    "app_unity_taoyuan_save",
+    request,
+    result => Apply(result.Data),
+    failure => ShowRetry(failure.Msg)));
+```
+
+`JsonUtility` 不适合任意字典和顶层数组；复杂协议应增加稳定 DTO，或在明确兼容的 JSON 库上建立独立适配层。
+
+## WebGL Bridge
+
+C# 调用：
+
+- `MicroiWebGLBridge.NotifyReady()`
+- `MicroiWebGLBridge.NotifyAuthorizationRotated(token, requestToken)`
+- `MicroiWebGLBridge.Emit(eventName, jsonPayload)`
+
+`.jslib` 只转换字符串并调用页面全局函数，不缓存会话。非 WebGL/Editor 下的业务事件可以写脱敏调试日志，便于 Play 验收。
+
+## Editor 构建工具
+
+公共构建工具负责：
+
+- 确认 WebGL BuildTargetSupport 已安装；
+- 选择场景与模板；
+- 固定 WebGL 2/WASM 和兼容压缩策略；
+- 建立输出目录并生成可追溯构建结果；
+- 失败时返回非零进程码，不生成“成功”哨兵。
+
+特定游戏的场景创建、PlayerSettings 和输出路径配置放项目 Editor 脚本，调用公共工具，不硬编码进 UPM。

package/skills/unity-integration/references/toolbox-migration.md

@@ -0,0 +1,66 @@
+# 既有 Unity 工具箱提取
+
+## 先建立清单
+
+按目录和程序集记录：
+
+- Runtime 通用脚本；
+- Editor 菜单、导入器和构建工具；
+- WebGL `.jslib`、模板和 JavaScript；
+- 相机、路径、触发区、设备协议与客户业务脚本；
+- Prefab、模型、动作、材质、贴图、字体、音频；
+- 第三方 Package 与其许可证。
+
+同时记录 Unity 版本、渲染管线、API Compatibility Level、Scripting Backend、目标平台和程序集依赖图。
+
+## 分类规则
+
+| 类型 | 去向 |
+|---|---|
+| 与业务无关的 API 客户端、宿主桥、构建基础能力 | `Microi.Unity/Runtime` 或 `Editor` |
+| 可展示的最小使用方式 | `Microi.Unity/Samples~` |
+| 场景、客户模型、设备字段、项目配置 | 原项目或独立业务项目 |
+| 来源不明或限制再分发的素材 | 不进入公共包；替换或取得授权 |
+| 只为旧项目兼容的适配代码 | 原项目 Adapter，不污染公共 API |
+
+## 安全迁移顺序
+
+1. 只读盘点并记录基线；不先移动文件。
+2. 复制候选公共代码到 UPM，移除业务命名和硬编码配置。
+3. 建 asmdef，限制 Runtime/Editor 引用方向。
+4. 在独立 Sample 编译并运行最小场景。
+5. 让旧项目通过 `Packages/manifest.json` 引用新 UPM。
+6. 替换旧项目调用并执行 Editor、目标平台和 WebGL 回归。
+7. 比较导出接口、序列化字段、Prefab GUID 和运行行为。
+8. 只有用户明确要求且回归通过，才考虑删除旧副本；否则保留来源并标注镜像关系。
+
+## 兼容性注意
+
+- 移动脚本可能改变 `.meta` GUID，导致 Prefab/Scene 引用丢失；公共提取优先新 API + Adapter，不直接搬走序列化脚本。
+- Editor-only 命名空间必须放 Editor asmdef 或 `#if UNITY_EDITOR`。
+- WebGL 不支持所有线程、Socket、反射和文件系统用法；公共 API 要明确平台条件。
+- Unity 内置 JSON 对字典、多态和顶层数组有限制，不能在提取时默默改变协议。
+- 不把客户服务器地址、OsClient、Token、设备密钥或私有证书写入 Sample。
+
+## 提取验收
+
+- UPM `package.json` 可解析，Runtime/Editor asmdef 引用无环。
+- Sample 编译与 Play 通过。
+- 原项目改用 UPM 后功能等价。
+- WebGL 插件实际链接，无 `EntryPointNotFound`。
+- 公共包扫描不含客户品牌、秘密、本机路径与未授权二进制素材。
+- README 说明支持版本、安装、最小示例、平台限制和升级策略。
+
+## 当前官方包已提取能力
+
+`Microi.Unity` 已从既有数字孪生项目重构以下公共能力：
+
+- WebGL 宿主事件桥、V8/DiyToken 客户端和构建入口；
+- 相机点按层级路径导入导出，导入支持 Undo；
+- 选中根节点范围内的 Mesh 合并，使用精确 Renderer 引用恢复；
+- 选中资源目录范围内的贴图优化，执行前保存完整 importer JSON；
+- 场景结构统计、Camera 深度精度诊断和选中 Camera 的 Undo 调整；
+- Balanced / High Definition WebGL 质量预设和 JSON 恢复；
+- 选中层级内多余 `CameraPoint_` Camera 组件的安全清理。
+
+旧项目的镜头路径、位置触发区、设备字段和业务 GameManager 仍属于项目 Adapter，不进入公共包。不要把这类保留项误报为“遗漏”；只有出现两个以上无业务字段的复用项目时，再抽取新的 Runtime 模块。

package/skills/unity-integration/references/webgl-hosting.md

@@ -0,0 +1,57 @@
+# WebGL 宿主、性能与部署
+
+## Poster-first 生命周期
+
+1. 首屏只加载 DOM、主视觉和轻量构建状态。
+2. 用户点击“进入 3D”后才创建 iframe/Canvas 并下载 Loader、Data、WASM。
+3. 加载中显示真实进度，不用无限假动画。
+4. 页面不可见或离开视口时 `SendMessage(..., SetHostPaused, true)`。
+5. 重回前台恢复；离开页面调用 `Quit()` 并移除全部监听与全局回调。
+
+错误状态至少区分：构建缺失、Loader 下载失败、Unity 初始化失败、浏览器能力不足、网络/CORS 失败。错误页仍应保留重试、返回与文档入口。
+
+## 上下文注入
+
+宿主在 Unity ready 后调用：
+
+```js
+unityInstance.SendMessage('MicroiApiClient', 'ApplyMicroiHostContext', JSON.stringify({
+  ApiBaseUrl: runtime.apiBase,
+  OsClient: runtime.osClient,
+  Authorization: runtime.token,
+  Did: runtime.did
+}))
+```
+
+- 不使用 `?token=`、`?osClient=` 或 `?apiBase=` 传会话。
+- iframe 同源时可读取父窗口内存上下文；跨域时由父页面显式 SendMessage，不能放宽为 `postMessage('*')` 接收秘密。
+- 若使用 `postMessage`，发送与接收双方都校验精确 Origin、消息类型和结构。
+
+## Token 轮换
+
+Unity 发送 `(newToken, requestToken)`。宿主只在当前 Token 仍等于 `requestToken`（或统一认证库明确允许）时覆盖，防止先发请求后到达的旧响应回滚新会话。
+
+更新顺序：统一认证库 → 微应用宿主 → 当前内存上下文 → 再注入 Unity。任何日志和业务事件都不得携带 Token。
+
+## 性能分档
+
+- 桌面 DPR 上限通常不超过 2；移动实验档建议 1.0–1.25。
+- 阴影距离、级联、粒子、后处理、LOD 与贴图分辨率按设备档位联动。
+- 首次下载和解压峰值要纳入浏览器内存；不能只看压缩包大小。
+- 大型孪生数据按区域/层级流式加载，避免把全部模型放入一个 Data 包。
+- 尊重 `prefers-reduced-motion`；DOM 外壳禁用非必要动效，Unity 内按项目需求提供镜头/粒子降级。
+
+## 静态服务器
+
+常见文件类型：
+
+| 文件 | MIME |
+|---|---|
+| `.wasm` | `application/wasm` |
+| `.js` | `application/javascript` |
+| `.data` | `application/octet-stream` |
+| `.json` | `application/json` |
+
+预压缩 `.gz/.br` 必须返回匹配的 `Content-Encoding`，不能只靠扩展名。若托管方不能配置响应头，构建时启用 Unity 解压回退，并实测性能。
+
+正式验收使用 HTTP(S)，检查状态码、MIME、Content-Encoding、CORS、缓存、Service Worker、控制台错误、全屏和退出后的内存/GPU 回落。