@microi.net/cli 4.9.3 → 4.9.4

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/workspace-conventions/SKILL.md

@@ -106,10 +106,11 @@ AI 在工作区任意任务中生成的**一次性临时脚本、诊断文件、
 | 吾码 App 源码 | `microi.app/` |
 | 吾码 UniApp 源码 | `microi.uniapp/` |
 | 吾码官方网站 / 文档源码 | `microi.doc/` |
-| 吾码 AI 应用源码 | `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}/` |
-| 吾码官方应用商城发行包源码 | `microi.apps/{packageKey}/` |
+| 吾码 AI 应用及应用商城发行源码 | `Microi-V8-Engine/{系统名称} ({ApiBase域名})/{OsClient}.{OsClientType}.{OsClientNetwork}/AI应用/{appKey}/` |
 
 以上路径只作为通用工作区相对路径规范，不写入具体本机盘符。跨仓库、空工作区或普通用户项目中，如果路径不存在，以插件生成的 `AGENTS.md`、MCP 配置和实际文件树为准。
+
+每个 `AI应用/{appKey}` 必须是界面、微服务、Manifest、接口引擎、资源策略、测试、构建脚本与商城上传素材的唯一事实源。纯平台应用没有前端时仍使用该目录；禁止另建 `microi.apps/` 平行发行根。
 
 ## Skills 通用化原则