@microi.net/cli 6.1.4 → 6.1.5

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

@@ -1,66 +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 模块。
+# 既有 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

@@ -1,57 +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 回落。
+# 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 回落。