@microi.net/cli 5.9.1 → 5.9.3

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

@@ -1,119 +1,119 @@
-# 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 输入控件，并在 Unity Player 将 `WebGLInput.captureAllKeyboardInput` 设为 `false`；输入区同时隔离键盘、`beforeinput`、组合输入与指针事件。Unity 6 若未向 Player 编译响应文件引用 `UnityEngine.WebGLModule`，可用 `link.xml` 保留类型后反射设置，并必须以真实键盘输入回归。Windows 可使用原生 UI/UIToolkit。不要在外壳和 Unity 中重复绘制同一组操作提示。
-- 语音字幕由真实播放器时间轴逐 cue 驱动，中英文分行放在底部安全区；WebGL DOM 与 Windows 原生 UI 复用同一份字幕数据。固定 `setTimeout` 只能做无音轨占位，不算同步验收。
-
-## 多人租约与公屏交付
-
-- 在线角色的事实源使用按 `OsClient` 隔离的共享数据库/Redis，不能使用 API 节点静态字典；客户端心跳周期必须短于租约超时。
-- 加入响应只向本人返回会话秘密；数据库保存 SHA-256，位置快照只公开昵称、受限坐标、朝向、动作与房间版本。
-- 正常卸载/离开主动调用 leave；浏览器崩溃、断网或 `kill -9` 依靠服务端租约自然失效，并通过两个真实客户端测量消失时间。
-- 公屏接口校验在线会话、内容长度、表情白名单、速率窗口和请求幂等；公开读取只返回有限时间窗和有限条数。浏览器验收用真实按键输入中文、字母、数字、标点、Shift 符号和输入法组合文本，并由第二个独立会话核对原文；直接调用 `fill()`/赋值只能验证服务端，不能证明键盘链路。
-- 轮询是兼容基线；接入 WebSocket/SignalR 时仍保留共享租约为事实源，并用 V8 授权接口签发短期频道权限。
-
-## WebGL 与 Windows 双端交付
-
-- WebGL 与 Windows 必须来自同一个 Unity 工程、场景和语义版本；禁止用旧本地包搭配新网页版本。
-- Windows 默认交付 x64 安装包，至少包含当前用户安装、开始菜单入口和卸载信息；没有明确需求时不申请管理员权限。
-- 外壳应给出醒目的本地版下载入口，并同时显示版本、文件大小与 SHA-256；文件名包含语义版本，旧版本 URL 不覆盖。
-- 安装包属于公开运行资产，不属于私有源码。同步 `directory` 前必须排除 `public/downloads` 等生成目录，再把完整安装包随 `dist` 走流式资产发布；禁止拆分 Base64 或伪装成源码规避单文件上限。
-- 单文件大于 128 MiB 时，MCP 与 `@microi.net/cli` 共用协议 v3：默认 16 MiB 原始字节分片、逐片 HDFS 回读、整文件 SHA-256 和确定性会话。重启后必须先查状态并只补缺片；5 GiB 文件应规划为 320 片，不得重新从 0 开始。
-- v3 不设置 Microi 产品级文件/目录字节上限；对象存储、磁盘、代理与协议技术边界仍需容量预检。发布期间在“系统引擎 → 超大文件上传记录”回读字节进度、心跳、失败原因和恢复建议，终态记录保留用于审计。
-- 发布后从公网地址重新下载完整 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`。
-
-### 仅共享编译运行产物
-
-消费者只获得运行应用、不安装业务资源时，商城发布显式传
-`RuntimeAssetsOnly=true`。只接受 `ProtocolVersion=3`、`ApplicationType=Web`、
-显式 `IncludeSource=false` 和已通过提交证明校验的 `SharedPublicRuntime`。
-源码是否在本地或私有开发端保管，与消费者包不含源码分别验收；此模式本身不要求上传本地源码。
-
-- 请求资源选择、历史 `SelectMenu/SelectTable/SelectApiEngine/SelectData` 和
-  `PreparedAssets.MenuContract` 均为空，非空时拒绝，不自动抹除；禁止混用 `DatabaseOnlyBuild`。
-- 通过既有 `microi_run_engine.params` 向 `ai_app_publish_store` 传入开关，先
-  `InspectResourceSnapshot` 再 `Publish + ExpectedResourceSnapshotHash`，两次使用同一组冻结参数。
-- 回读真实包的十一项资源数组、`SourceFiles/BuildAssets` 均为零，`SourceZip/BuildZip` 为空，
-  只保留共享运行交付。完整数组和兼容条件见 [应用商城 Skill](../../app-store/SKILL.md#仅共享编译运行产物)。
-- 此模式的目标验收检查编译入口、宿主身份和实际服务契约；没有声明的表、菜单、接口及 Hook
-  不应在消费者租户生成。需要租户业务资源时使用普通资源包流程。
-
-## 官方发布顺序
-
-只有当前 MCP 明确绑定官方 `https://api.itdos.com`、`OsClient=iTdos` 且用户已授权写入时才执行：
-
-1. `microi_list_applications` 按精确 AppKey/中文名查重。
-2. 读取远端应用上下文、源码版本、运行版本、行版本/围栏与路由快照。
-3. 本地完成类型检查、测试、真实 Unity 构建和 dist 完整性校验。
-4. 先同步私有源码；生成的 Unity、安装包与构建证据目录不得混入源码清单。任何期望版本不一致都停止重基线。
-5. 发布不可变 Web 运行版本，回读入口、文件数、哈希、状态与公开 URL。
-   - 官网、二维码、分享与商城“立即体验”必须指向不带版本号的固定当前入口，且游戏加载完成后地址栏仍保持该入口；不能把 `SharedPublicRuntime.EntryUrl`、`/releases/{Version}/requests/...` 或 `/versions/{Version}/` 当作当前体验地址，也不能用 30x、`meta refresh`、`location.replace` 伪装稳定入口。
-   - 不可变版本 URL 只写入历史版本记录、回滚和审计。固定入口可以使用同源全屏加载壳承载当前不可变产物，并必须透传 `autoplay`、`fullscreen` 与 `gamepad` 权限。
-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。
-- 升级遵循先扩展、后迁移、再收缩；新旧运行版本短暂并存时协议向前/向后兼容。
-- 回滚恢复上一不可变运行版本；数据库变更需要显式兼容/补偿方案，不能用文件回滚伪装数据回滚。
+# 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 输入控件，并在 Unity Player 将 `WebGLInput.captureAllKeyboardInput` 设为 `false`；输入区同时隔离键盘、`beforeinput`、组合输入与指针事件。Unity 6 若未向 Player 编译响应文件引用 `UnityEngine.WebGLModule`，可用 `link.xml` 保留类型后反射设置，并必须以真实键盘输入回归。Windows 可使用原生 UI/UIToolkit。不要在外壳和 Unity 中重复绘制同一组操作提示。
+- 语音字幕由真实播放器时间轴逐 cue 驱动，中英文分行放在底部安全区；WebGL DOM 与 Windows 原生 UI 复用同一份字幕数据。固定 `setTimeout` 只能做无音轨占位，不算同步验收。
+
+## 多人租约与公屏交付
+
+- 在线角色的事实源使用按 `OsClient` 隔离的共享数据库/Redis，不能使用 API 节点静态字典；客户端心跳周期必须短于租约超时。
+- 加入响应只向本人返回会话秘密；数据库保存 SHA-256，位置快照只公开昵称、受限坐标、朝向、动作与房间版本。
+- 正常卸载/离开主动调用 leave；浏览器崩溃、断网或 `kill -9` 依靠服务端租约自然失效，并通过两个真实客户端测量消失时间。
+- 公屏接口校验在线会话、内容长度、表情白名单、速率窗口和请求幂等；公开读取只返回有限时间窗和有限条数。浏览器验收用真实按键输入中文、字母、数字、标点、Shift 符号和输入法组合文本，并由第二个独立会话核对原文；直接调用 `fill()`/赋值只能验证服务端，不能证明键盘链路。
+- 轮询是兼容基线；接入 WebSocket/SignalR 时仍保留共享租约为事实源，并用 V8 授权接口签发短期频道权限。
+
+## WebGL 与 Windows 双端交付
+
+- WebGL 与 Windows 必须来自同一个 Unity 工程、场景和语义版本；禁止用旧本地包搭配新网页版本。
+- Windows 默认交付 x64 安装包，至少包含当前用户安装、开始菜单入口和卸载信息；没有明确需求时不申请管理员权限。
+- 外壳应给出醒目的本地版下载入口，并同时显示版本、文件大小与 SHA-256；文件名包含语义版本，旧版本 URL 不覆盖。
+- 安装包属于公开运行资产，不属于私有源码。同步 `directory` 前必须排除 `public/downloads` 等生成目录，再把完整安装包随 `dist` 走流式资产发布；禁止拆分 Base64 或伪装成源码规避单文件上限。
+- 单文件大于 128 MiB 时，MCP 与 `@microi.net/cli` 共用协议 v3：默认 16 MiB 原始字节分片、逐片 HDFS 回读、整文件 SHA-256 和确定性会话。重启后必须先查状态并只补缺片；5 GiB 文件应规划为 320 片，不得重新从 0 开始。
+- v3 不设置 Microi 产品级文件/目录字节上限；对象存储、磁盘、代理与协议技术边界仍需容量预检。发布期间在“系统引擎 → 超大文件上传记录”回读字节进度、心跳、失败原因和恢复建议，终态记录保留用于审计。
+- 发布后从公网地址重新下载完整 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`。
+
+### 仅共享编译运行产物
+
+消费者只获得运行应用、不安装业务资源时，商城发布显式传
+`RuntimeAssetsOnly=true`。只接受 `ProtocolVersion=3`、`ApplicationType=Web`、
+显式 `IncludeSource=false` 和已通过提交证明校验的 `SharedPublicRuntime`。
+源码是否在本地或私有开发端保管，与消费者包不含源码分别验收；此模式本身不要求上传本地源码。
+
+- 请求资源选择、历史 `SelectMenu/SelectTable/SelectApiEngine/SelectData` 和
+  `PreparedAssets.MenuContract` 均为空，非空时拒绝，不自动抹除；禁止混用 `DatabaseOnlyBuild`。
+- 通过既有 `microi_run_engine.params` 向 `ai_app_publish_store` 传入开关，先
+  `InspectResourceSnapshot` 再 `Publish + ExpectedResourceSnapshotHash`，两次使用同一组冻结参数。
+- 回读真实包的十一项资源数组、`SourceFiles/BuildAssets` 均为零，`SourceZip/BuildZip` 为空，
+  只保留共享运行交付。完整数组和兼容条件见 [应用商城 Skill](../../app-store/SKILL.md#仅共享编译运行产物)。
+- 此模式的目标验收检查编译入口、宿主身份和实际服务契约；没有声明的表、菜单、接口及 Hook
+  不应在消费者租户生成。需要租户业务资源时使用普通资源包流程。
+
+## 官方发布顺序
+
+只有当前 MCP 明确绑定官方 `https://api.itdos.com`、`OsClient=iTdos` 且用户已授权写入时才执行：
+
+1. `microi_list_applications` 按精确 AppKey/中文名查重。
+2. 读取远端应用上下文、源码版本、运行版本、行版本/围栏与路由快照。
+3. 本地完成类型检查、测试、真实 Unity 构建和 dist 完整性校验。
+4. 先同步私有源码；生成的 Unity、安装包与构建证据目录不得混入源码清单。任何期望版本不一致都停止重基线。
+5. 发布不可变 Web 运行版本，回读入口、文件数、哈希、状态与公开 URL。
+   - 官网、二维码、分享与商城“立即体验”必须指向不带版本号的固定当前入口，且游戏加载完成后地址栏仍保持该入口；不能把 `SharedPublicRuntime.EntryUrl`、`/releases/{Version}/requests/...` 或 `/versions/{Version}/` 当作当前体验地址，也不能用 30x、`meta refresh`、`location.replace` 伪装稳定入口。
+   - 不可变版本 URL 只写入历史版本记录、回滚和审计。固定入口可以使用同源全屏加载壳承载当前不可变产物，并必须透传 `autoplay`、`fullscreen` 与 `gamepad` 权限。
+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

@@ -1,82 +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。
+# 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

@@ -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 模块。