@microi.net/cli 4.9.2 → 4.9.4

package/skills/unity-integration/SKILL.md

@@ -0,0 +1,143 @@
+---
+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` + 数据库唯一索引/幂等台账；锁不能替代幂等。
+- 接口引擎 `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 生成素材保存逐图提示词、生成时间、用途和源文件；不要只提交最终图片。
+- 网络素材必须允许商业使用和再分发；许可证不清晰就改用原创、程序化或明确授权素材。
+- 官方包不携带客户专属场景、品牌秘密、私有协议或无法追溯的二进制模型。
+- “超清”不能只靠大纹理：同时控制材质、光照、阴影、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,78 @@
+# 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 时禁止正式发布。
+
+## 商城资源
+
+游戏进度表使用应用前缀 `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. 使用当前协议的 preflight/stage/finalize 同步私有源码；任何期望版本不一致都停止重基线。
+5. 发布不可变 Web 运行版本，回读入口、文件数、哈希、状态与公开 URL。
+6. 调用官方 `ai_app_publish_store` 生成并发布精确版本的应用商城包。
+7. 回读 `sys_microistore` 的 AppKey、版本、状态、预览图、包摘要与资源策略。
+8. 在官网 `/apps.html` 和 `/app-detail.html?app=<appKey>` 做公开页面回读。
+9. 在一个非官方测试租户安装，回读表、菜单、接口和 Hook 所有权；再验证升级不覆盖租户 Hook。
+
+源码同步、运行发布、商城发布、官网可见、目标租户安装是五项独立事实。任一步只有受理 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 回落。

package/skills/v8-api-config/SKILL.md

@@ -3,6 +3,8 @@ name: v8-api-config
 description: Microi V8 接口引擎配置指南。用于设置 ApiEngineKey、ApiAddress、StopHttp、AllowAnonymous、ResponseFile、锁、日志、超时和 HTTP 暴露。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 接口引擎配置
 
 你正在配置 Microi 吾码平台的接口引擎（API 引擎）。除了 JS 代码本身，每个接口还有一系列**安全/性能配置项**，写代码时必须了解这些选项以决定是否需要调整。

package/skills/v8-cache-pattern/SKILL.md

@@ -3,6 +3,8 @@ name: v8-cache-pattern
 description: Microi V8 Redis 缓存与管理模式。用于读写 V8.Cache、租户缓存命名、TTL 策略、防陈旧数据，以及使用 Redis 管理器页面或 MCP 检索、统计、查看和维护 String、Hash、List、Set、Sorted Set、Stream。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 Redis 缓存模式
 
 你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 Redis 缓存提升性能。V8 只获得当前租户的安全缓存代理，不会获得 Redis `IDatabase`、连接管理或服务器扫描能力。

package/skills/v8-crud-api/SKILL.md

@@ -3,6 +3,8 @@ name: v8-crud-api
 description: Microi V8 CRUD 接口引擎开发。用于编写服务端 JavaScript，涉及 V8.FormEngine Add/Upt/Del/GetTableData、DosResult 返回、事务和校验。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 CRUD API 接口引擎开发
 
 你正在开发 Microi 吾码平台的 V8 接口引擎。接口引擎是运行在服务端的 JavaScript 函数，通过 `V8.FormEngine` 操作数据库，通过 `V8.Result` 或 `return` 返回结果。

package/skills/v8-debugging/SKILL.md

@@ -3,6 +3,8 @@ name: v8-debugging
 description: Microi V8 调试与日志指南。用于排查接口引擎、V8 事件、console.log、DataAppend.DebugLog、sys_log、异常处理和远程执行问题。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 调试与日志
 
 你正在为 Microi 吾码平台编写 V8 引擎代码，需要在开发/测试/生产环境进行排错。本指南提供调试模式、异常捕获、系统日志、调试输出的标准做法。

package/skills/v8-explorer-tree/SKILL.md

@@ -3,6 +3,8 @@ name: v8-explorer-tree
 description: Microi.VSCode 插件 V8 资源管理器目录规范（表单引擎 / 字段V8事件 / 模块引擎按钮）。覆盖 diy_table V8 事件、diy_field V8 事件、sys_menu 按钮 JSON 拆分回写，含 7 条安全不变量。用于实现 VSCode V8 事件树、重构目录布局或处理 sys_menu 按钮 JSON 序列化。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # v8-explorer-tree — V8 资源管理器目录规范 v2（2026-05）
 
 > 涉及文件：[Microi.VSCode/src/explorer/engineTreeProvider.ts](Microi.VSCode/src/explorer/engineTreeProvider.ts)、[Microi.VSCode/src/sync/syncManager.ts](Microi.VSCode/src/sync/syncManager.ts)、[Microi.VSCode/src/constants.ts](Microi.VSCode/src/constants.ts)、[Microi.VSCode/src/utils.ts](Microi.VSCode/src/utils.ts)、[Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs](Microi.Server/Microi.net.Api/Controllers/V8EngineController.cs)

package/skills/v8-export-import/SKILL.md

@@ -3,6 +3,8 @@ name: v8-export-import
 description: Microi V8 Office 导入导出指南。用于使用 V8.Office 导出单/多 Sheet Excel、Word、PowerPoint，解析 Excel，自定义表头/图片、文件响应和批量导入校验。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 Office 导入导出
 
 你正在为 Microi 吾码平台编写自定义 Excel、Word、PowerPoint 导入/导出代码。平台通过 `V8.Office` 提供 Office 处理能力，源码在 `Microi.Office` 插件中。

package/skills/v8-file-upload/SKILL.md

@@ -3,6 +3,8 @@ name: v8-file-upload
 description: Microi V8 与 MCP 文件上传下载指南。用于处理流式 AI 应用发布、V8.FilesByteBase64、V8.Method.Upload、私有文件 URL、文件响应、HDFS、OSS、MinIO 和 S3 存储。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 文件上传下载
 
 你正在为 Microi 吾码平台编写文件上传/下载/返回相关代码。平台分布式存储（HDFS）支持阿里云OSS、MinIO、亚马逊S3，存储方案由 SaaS 引擎按租户配置。

package/skills/v8-formengine-http/SKILL.md

@@ -3,6 +3,8 @@ name: v8-formengine-http
 description: 移动端 / 外部系统通过 HTTP 直接调用 Microi FormEngine（GetTableData / GetFormData / Add / Upt / Del）的 RESTful 路由约定与排错指南
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # FormEngine HTTP 路由约定（外部系统调用）
 
 > 适用于：uni-app H5、原生 App、Postman、第三方系统、Playwright/Cypress 自动化测试等任何**没有进入 V8 引擎**的客户端。

package/skills/v8-frontend-events/SKILL.md

@@ -3,6 +3,8 @@ name: v8-frontend-events
 description: Microi 前端 V8 事件与客户端能力指南。用于编写浏览器端字段、按钮、列表事件，或使用 V8.EventName、V8.Form、V8.Print 蓝牙打印、扫码、弹窗、表单联动和界面交互。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 前端事件大全
 
 你正在为 Microi 吾码平台编写 **前端 V8 事件** 代码。前端事件运行在浏览器，通过 `V8.EventName` 区分事件类型，可访问表单/列表/弹窗等丰富的客户端 API。

package/skills/v8-http-integration/SKILL.md

@@ -3,6 +3,8 @@ name: v8-http-integration
 description: Microi V8 HTTP 集成指南。用于通过 V8.Http.Get/Post/Patch、对应 Response 方法及后端 Async 方法调用接口，处理请求头、JSON/form/XML 载荷、超时、文件和响应解析，并兼容前后端 V8。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 HTTP 外部接口集成
 
 你正在开发 Microi 吾码平台的 V8 引擎代码，需要调用外部 HTTP API（微信、支付宝、短信、ERP 等第三方系统）。

package/skills/v8-image-processing/SKILL.md

@@ -3,6 +3,8 @@ name: v8-image-processing
 description: Microi V8.Image 服务端图像处理指南。用于在接口引擎或后端 V8 事件中生成图片、横向/纵向/网格拼接、图层覆盖、水印、缩放、裁剪、旋转、翻转、格式转换、绘制文字与图形、生成二维码、读取图片信息，以及设计安全的 Base64/Data URI 图像处理流程。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 图像处理
 
 使用 `V8.Image` 在服务端处理内存图片。所有方法统一接收对象参数并返回 `DosResult`；图片结果位于 `result.Data.FileByteBase64`。

package/skills/v8-menu-buttons/SKILL.md

@@ -3,6 +3,8 @@ name: v8-menu-buttons
 description: Microi 菜单按钮与 Tab V8 指南。用于配置 sys_menu MoreBtns、FormBtns、BatchSelectMoreBtns、PageTabs、PageBtns、ExportMoreBtns、显隐代码和行操作。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # v8-menu-buttons — 菜单按钮 / Tab / 批量操作 V8 写法
 
 > 适用于 sys_menu 表的 MoreBtns、FormBtns、BatchSelectMoreBtns、PageTabs、ExportMoreBtns、PageBtns 字段。

package/skills/v8-mongodb/SKILL.md

@@ -3,6 +3,8 @@ name: v8-mongodb
 description: Microi V8 MongoDB 指南。用于使用 V8.MongoDb AddFormData、UptFormData、DelFormData、GetFormData、GetTableData、对象过滤和文档 Id。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 MongoDB 操作
 
 你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 MongoDB 存储非结构化数据（如日志、IoT 数据、大文档等）。

package/skills/v8-mq-mqtt/SKILL.md

@@ -3,6 +3,8 @@ name: v8-mq-mqtt
 description: Microi V8 消息队列与 MQTT 指南。用于使用 V8.MQ.SendMsg、RabbitMQ 队列、MQTT 事件处理、主题、载荷、客户端 Id 和异步集成。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 消息队列与 MQTT
 
 你正在开发 Microi 吾码平台的 V8 引擎代码，需要使用 RabbitMQ 消息队列或 MQTT 物联网协议。

package/skills/v8-saas-multi-tenant/SKILL.md

@@ -3,6 +3,8 @@ name: v8-saas-multi-tenant
 description: Microi V8 SaaS 多租户指南。用于处理 OsClient、OsClientType、OsClientNetwork、租户配置、V8.OsClientModel、隔离和租户感知代码。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 SaaS 多租户引擎
 
 你正在为 Microi 吾码平台编写多租户（SaaS）相关代码。每个租户使用独立数据库账号；Redis、对象存储、RabbitMQ、MQTT 和搜索集群可以共享基础设施，但必须使用租户命名空间与独立服务凭据，**所有 V8 代码都在租户上下文中运行**。

package/skills/v8-security/SKILL.md

@@ -3,6 +3,8 @@ name: v8-security
 description: Microi V8 安全指南。用于审查 DiyToken 与权限、可逆业务秘密、Passkey/TOTP/人脸步进验证、接口引擎安全、密钥管理、SQL 注入、匿名端点、文件上传和租户隔离。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 安全最佳实践
 
 你正在开发 Microi 吾码平台的 V8 引擎代码，必须遵守以下安全规范。

package/skills/v8-sql-query/SKILL.md

@@ -3,6 +3,8 @@ name: v8-sql-query
 description: Microi V8 安全 SQL 查询指南。用于选择 V8.FormEngine _Where 或 V8.Db.FromSql，处理参数化查询、联表、聚合并避免 SQL 注入。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 安全 SQL 查询
 
 你正在开发 Microi 吾码平台的 V8 引擎代码。数据库查询有两种方式：`V8.FormEngine`（推荐）和 `V8.Db`（原始 SQL）。必须遵守安全规范。

package/skills/v8-table-event/SKILL.md

@@ -3,6 +3,8 @@ name: v8-table-event
 description: Microi V8 表单事件开发。用于编写 InFormV8、SubmitFormV8、SubmitBeforeServerV8、SubmitAfterServerV8、OutFormV8、DataFilterV8 和事务感知事件。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 表单事件开发
 
 你正在开发 Microi 吾码平台的 V8 表单事件。事件绑定在表单引擎的表上，在数据操作的不同阶段自动触发。

package/skills/v8-template-engine/SKILL.md

@@ -3,6 +3,8 @@ name: v8-template-engine
 description: Microi V8 模板引擎指南。用于编写表格/表单模板渲染、V8.Result HTML/text 输出、行格式化、徽章、图片和自定义显示逻辑。
 ---
 
+> **Codex 强制前置：** 当前宿主为 Codex 时，在使用本 Skill 前必须先完整读取 `../microi-codex-installer/SKILL.md`，完成“Codex 每任务最新版硬门禁”；门禁未通过不得继续本 Skill。非 Codex 宿主跳过此项。
+
 # Microi V8 模板引擎（表格/表单 V8 模板）
 
 你正在为 Microi 吾码平台编写 **表格 V8 模板引擎**、**表单 V8 模板引擎** 代码。模板引擎用于在数据渲染后自定义最终展示效果（颜色、徽章、图片、HTML），是表单引擎的高级特性。