@leonxin/meetgames 0.1.8 → 0.1.11

package/docs/archive/ios-migration.md

@@ -0,0 +1,2139 @@
+# iOS 迁移归档
+
+本文由原 iOS 迁移相关文档合并而来，用于保留 `topsdk-tool-ios` Python 工具迁移到 `meet-sdk-tool` 的历史过程、功能对照、测试方法和差异记录。日常接入请查看 `docs/INTEGRATION.md`。
+
+## 合并来源
+
+- 旧 Python 工具完整流程: `docs/ios-topsdk-tool-python-flow.md`
+- 功能点与测试方法: `docs/ios-topsdk-tool-feature-test-plan.md`
+- Python 到 TypeScript 对照: `docs/ios-migration-parity.md`
+- 差异与缺失备忘: `docs/ios-migration-gap-memo.md`
+
+
+---
+
+## 旧 Python 工具完整流程
+
+本文档基于 `topsdk-tool-ios` 工程源码整理，目标是把旧 Python 工具中会被打包为 `TopSDKTool` 的 iOS 原生工程自动接入流程完整记录下来，方便后续在 `meet-sdk-tool` 中用 TypeScript 实现等价能力。
+
+范围只覆盖旧工具对 iOS SDK 接入的核心行为：
+
+- `TopSDKTool` 打包和运行时资源布局。
+- 读取 SDK / 插件配置。
+- 获取并校验远端渠道参数。
+- 自动修改 `.xcodeproj`、`Info.plist`、entitlements。
+- 复制 framework、bundle、lib、源码等资源到游戏工程。
+- 自动注入 `UIApplicationDelegate` / `UIWindowSceneDelegate` 相关代码。
+
+不覆盖上传、更新、Unity、Cocos、LayaNative 等非原生 iOS 工程接入逻辑；这些逻辑在旧工具中存在，但本次迁移目标不需要实现。
+
+## 1. 关键源码位置
+
+旧工程：`/Users/work/Workspace/Projects/topsdk-tool-ios`
+
+| 文件 | 作用 |
+|------|------|
+| `TopSDKTool.py` | 主入口，串联资源读取、在线参数获取、目标 target 选择、SDK / 插件接入、Delegate 注入 |
+| `autoBuild.sh` | 使用 PyInstaller 打包 `TopSDKTool.py` 为单文件可执行程序 |
+| `TopSDKTool.spec` | PyInstaller 打包配置 |
+| `TOPSDKUtils/PluginConfig.py` | 解析 `sdk/*.json` 和 `plugins/*/config.json` |
+| `TOPSDKUtils/ChannelConfigManager.py` | 请求服务端 SDK 渠道配置 |
+| `TOPSDKUtils/XcodeManager.py` | 修改 Xcode 工程、Info.plist、entitlements、查找 Delegate 文件 |
+| `TOPSDKUtils/FileManager.py` | 把 SDK 资源复制到游戏工程 `topSDK/` 目录 |
+| `TOPSDKUtils/InfoPlistManager.py` | 写入 `Info.plist` 字段、URL Scheme、Queries Schemes |
+| `TOPSDKUtils/CodeUtils.py` | 给 Objective-C / Objective-C++ 文件插入 import 和方法代码 |
+| `TOPSDKUtils/commonUtils.py` | 命令行交互选择和路径输入 |
+| `TOPSDKUtils/ToolConfig.py` | 工具版本、环境、wiki 地址、服务端 base url |
+
+## 2. 打包形态
+
+### 2.1 打包命令
+
+`autoBuild.sh` 的实际动作：
+
+1. 删除本地 `build/` 和 `dist/`。
+2. 执行：
+
+```bash
+pyinstaller -F TopSDKTool.py
+```
+
+3. 删除 `TopSDK/TopSDKTool`。
+4. 将 `dist/TopSDKTool` 复制到 `TopSDK/TopSDKTool`。
+5. 再次删除 `build/` 和 `dist/`。
+
+### 2.2 PyInstaller 配置
+
+`TopSDKTool.spec` 中 `datas=[]`、`binaries=[]`，说明 SDK 资源并不会被打进可执行文件。可执行文件只包含 Python 代码和依赖。
+
+因此发布包必须把 `TopSDKTool` 和资源目录放在同一个根目录下：
+
+```text
+TopSDK/
+  TopSDKTool
+  sdk/
+    *.json
+    source/
+      ...
+  plugins/
+    AppleSignin/
+      config.json
+      source/
+        ...
+    GoogleSignin/
+      config.json
+      source/
+        ...
+```
+
+### 2.3 运行时根目录
+
+`TopSDKTool.py` 中：
+
+```python
+rootPath = os.path.dirname(os.path.realpath(sys.argv[0]))
+sdkPath = os.path.join(rootPath, "sdk")
+pluginsPath = os.path.join(rootPath, "plugins")
+```
+
+生产环境下，`rootPath` 是 `TopSDKTool` 可执行文件所在目录。也就是说，工具依赖“可执行文件旁边的 `sdk/` 和 `plugins/`”。
+
+注意：当 `currentEnv != ENV.prod` 时，代码会把 `rootPath` 写死成开发者本机路径：
+
+```python
+rootPath = "/Users/lvyunjie/Downloads/topSDK-ios--V1.6.0.2"
+```
+
+这个行为只用于旧工具本地调试，TS 迁移时不应该保留。
+
+## 3. 运行输入
+
+旧工具通过命令行交互获取输入：
+
+1. `appId`
+2. `appSecret`
+3. 游戏引擎类型
+4. Unity / Cocos 版本，原生 iOS 不需要
+5. `.xcodeproj` 路径
+6. 当工程中有多个 target 时，选择目标 target
+7. 当检测到多个 AppDelegate / SceneDelegate 文件时，选择需要注入的文件
+
+原生 iOS 迁移到 `meet-sdk-tool` 后，建议改为非交互式参数：
+
+| 旧工具交互输入 | TS 工具建议 |
+|----------------|------------|
+| `appId` | 沿用现有 `--app-id` |
+| `appSecret` | 沿用现有 `--app-secret` |
+| `.xcodeproj` 路径 | 使用 `--project-root` 自动查找或由命令参数指定 |
+| 游戏引擎 | 不再识别 engine，只处理 Xcode 工程 |
+| target 选择 | 可默认选择唯一 App target；多 target 时通过参数或明确报错 |
+| Delegate 文件选择 | 唯一时自动注入；多个时通过参数或明确报错 |
+
+## 4. 配置文件模型
+
+旧工具将 SDK 核心和插件都抽象为 `PluginConfig`。
+
+### 4.1 SDK 核心配置
+
+启动时读取：
+
+```text
+sdk/*.json
+```
+
+过滤规则：
+
+- 文件名必须以 `.json` 结尾。
+- 文件名不能以 `.` 开头。
+
+读取后放入 `sdkConfigs`。
+
+### 4.2 插件配置
+
+启动时读取：
+
+```text
+plugins/<PluginName>/config.json
+```
+
+只要 `config.json` 存在，就构造 `PluginConfig` 并放入 `pluginConfigs`。
+
+### 4.3 PluginConfig 字段
+
+`PluginConfig.py` 强依赖这些字段存在：
+
+| 字段 | 用途 |
+|------|------|
+| `name` | 插件名，同时用于匹配插件目录名 |
+| `key` | 服务端渠道配置 key，如 `GOOGLE`、`FACEBOOK` |
+| `type` | 插件类型，`0` SDK 核心、`1` 登录、`2` 支付、`3` UI、`4` 数据 |
+| `pluginVersion` | 插件版本，仅用于日志 |
+| `sources` | 需要复制和加入 Xcode 工程的源码 / 资源 |
+| `frameworks` | framework / bundle 依赖列表 |
+| `libs` | 静态库或系统 lib 依赖列表 |
+| `buildSettings` | 需要写入 target build settings 的配置 |
+| `OtherLinkerFlags` | 需要追加到 `OTHER_LDFLAGS` 的 flag |
+| `queriesSchemes` | 需要追加到 `LSApplicationQueriesSchemes` 的 scheme |
+| `urlScheme` | 需要追加到 `CFBundleURLTypes` 的 URL Scheme |
+| `infoParams` | 需要写入 `Info.plist` 的字段 |
+| `requireConfigs` | 必须从服务端返回的渠道参数 |
+| `pluginParams` | 写入 `TOPSDK.Plugins[].params` 的参数模板 |
+| `appDelegateCodes` | 需要注入到 AppDelegate 的代码片段 |
+| `sceneDelegateCodes` | 需要注入到 SceneDelegate 的代码片段 |
+
+### 4.4 framework 配置
+
+每个 framework 项解析为：
+
+| 字段 | 用途 |
+|------|------|
+| `name` | framework / bundle 文件名 |
+| `system` | 是否系统 framework |
+| `embed` | 是否加入 Embed Frameworks |
+| `copyFile` | 是否额外加入 CopyFiles phase，默认 `false` |
+
+### 4.5 lib 配置
+
+每个 lib 项解析为：
+
+| 字段 | 用途 |
+|------|------|
+| `name` | lib 文件名 |
+| `system` | 是否系统 lib |
+
+### 4.6 code 配置
+
+每个代码注入项解析为：
+
+| 字段 | 用途 |
+|------|------|
+| `type` | `header` 表示插入头部 import；其他值表示插入方法代码 |
+| `method` | 目标 Objective-C 方法签名 |
+| `content` | 要插入的代码 |
+| `addToReturn` | 是否把代码合并到方法 return 结果中 |
+
+## 5. 资源完整性检查
+
+入口在 `checkEnv()`。
+
+### 5.1 SDK 目录检查
+
+如果 `sdk/` 不存在：
+
+```text
+error: sdk目录不存在
+```
+
+返回 `False`，主流程随后退出。
+
+### 5.2 plugins 目录检查
+
+如果 `plugins/` 不存在或为空，只打印 warning：
+
+```text
+warning：没有任何插件资源
+```
+
+不会退出。
+
+### 5.3 插件资源检查
+
+对 `plugins/` 下每个非隐藏目录执行 `checkPlugin(pluginDirName)`。
+
+检查项：
+
+1. `plugins/<PluginName>/config.json` 必须存在。
+2. `config.json` 必须是合法 JSON object。
+3. `config.name` 必须等于插件目录名。
+4. `sources[]` 中每个资源必须存在于：
+
+```text
+plugins/<PluginName>/source/<sourceName>
+```
+
+5. `frameworks[]` 中 `system=false` 的资源必须存在于：
+
+```text
+plugins/<PluginName>/source/<frameworkName>
+```
+
+6. `libs[]` 中 `system=false` 的资源必须存在于：
+
+```text
+plugins/<PluginName>/source/<libName>
+```
+
+注意：旧工具会把错误插件收集到 `errorPlugins`，但 `checkEnv()` 最后仍然返回 `True`。这意味着某个插件校验失败不会真正阻止后续流程。TS 迁移时建议修正为明确失败，避免产物半接入。
+
+## 6. 获取服务端渠道参数
+
+入口在 `getOnlineConfig(pluginConfigs)`。
+
+### 6.1 无插件场景
+
+如果 `pluginConfigs` 为空：
+
+1. 只要求输入 `appId`。
+2. 返回：
+
+```python
+onlineConfig = None
+appId = inputAppId
+```
+
+### 6.2 有插件场景
+
+如果存在插件：
+
+1. 收集所有 `pluginConfig.key` 到 `pluginKeys`。
+2. 汇总所有 `pluginConfig.requireConfigs` 到 `needOnlineParams`。
+3. 如果 `needOnlineParams` 为空，不请求服务端。
+4. 如果 `needOnlineParams` 非空，循环要求输入 `appId`、`appSecret`，直到服务端返回有效配置。
+
+### 6.3 请求接口
+
+`ChannelConfigManager.getSdkConfig(appId, appSecret, types)` 请求：
+
+```text
+GET {baseUrl}/console/openSDK/getSDKConfig
+```
+
+生产 / 预发布 base url 当前都指向：
+
+```text
+https://pre-api-sdk-gameplus.meetsocial.com/
+```
+
+测试环境 base url：
+
+```text
+https://test-api-sdk-gameplus.meetsocial.com:1157/
+```
+
+请求参数：
+
+| 参数 | 来源 |
+|------|------|
+| `appId` | 用户输入 |
+| `authType` | 插件 key 列表，排除 `GUEST`、`UI`、`IAPPAY` |
+| `channelType` | 固定 `"apple"` |
+| `timestamp` | 当前毫秒时间戳 |
+| `sign` | `base64(md5(appId + appSecret + timestamp))` |
+
+### 6.4 返回解析
+
+仅当 HTTP status 为 `200` 且业务 `code == 200` 时解析：
+
+```text
+data.channelAuthConfig[]
+```
+
+每项用 `authType.upper()` 作为 key 存入 `sdkConfig`。
+
+特殊处理：
+
+- `MESSENGER` 会归并为 `FACEBOOK`，并设置 `openMessenger = "1"`。
+- `FACEBOOK` 会设置 `openMessenger = "0"`。
+
+最终结构类似：
+
+```json
+{
+  "GOOGLE": {
+    "authType": "GOOGLE",
+    "clientId": "...",
+    "scheme": "..."
+  },
+  "FACEBOOK": {
+    "authType": "FACEBOOK",
+    "clientId": "...",
+    "name": "...",
+    "scheme": "...",
+    "secret": "...",
+    "openMessenger": "0"
+  }
+}
+```
+
+### 6.5 requireConfigs 校验
+
+服务端返回后，旧工具会把所有非空字段转换成：
+
+```text
+<CHANNEL_KEY>.<fieldName>
+```
+
+例如：
+
+```text
+GOOGLE.clientId
+GOOGLE.scheme
+FACEBOOK.clientId
+FACEBOOK.name
+```
+
+然后逐个检查 `needOnlineParams` 是否都存在。不完整时输出：
+
+```text
+参数缺失，请与SDK方沟通确认配置完整性，缺失配置包括：...
+```
+
+并退出。
+
+### 6.6 `GOOGLE.scheme` 与 `FACEBOOK.name` 的旧逻辑位置
+
+这两个字段不是写死在 `topsdk-tool-ios` 主流程代码里，而是来自旧 iOS SDK 下载包中的插件配置文件。`topsdk-tool-ios` 仓库本体只包含工具源码；运行时会以 `rootPath` 为根读取下载包资源：
+
+```text
+<rootPath>/sdk/*.json
+<rootPath>/plugins/<PluginName>/config.json
+```
+
+对应源码入口：
+
+| 行为 | 旧工程位置 |
+|------|------------|
+| 读取插件配置中的 `requireConfigs`、`infoParams`、`pluginParams`、`urlScheme`、`key` | `TOPSDKUtils/PluginConfig.py` |
+| 汇总所有插件的 `requireConfigs` 到 `needOnlineParams` | `TopSDKTool.py#getOnlineConfig()` |
+| 请求服务端 `console/openSDK/getSDKConfig`，固定 `channelType = "apple"` | `TOPSDKUtils/ChannelConfigManager.py#getSdkConfig()` |
+| 将 `channelAuthConfig[]` 以 `authType.upper()` 存入 `sdkConfig` | `TOPSDKUtils/ChannelConfigManager.py#getSdkConfig()` |
+| 校验 `needOnlineParams` 是否都在服务端返回字段中 | `TopSDKTool.py#getOnlineConfig()` |
+| 用 `checkStr()` 替换 `{$C.GOOGLE.scheme}`、`{$C.FACEBOOK.name}` 等占位符 | `TopSDKTool.py#checkStr()`、`TopSDKTool.py#setPlugin()` |
+
+旧插件配置中这两个字段的使用方式如下。当前 `meet-sdk-tool` 的 `bundled/ios-sdk/ios--V1.6.0.4` 是该旧下载包资源的迁移副本，文件名从旧包常见的 `config.json` 保留为工具内使用的 `config.t.json`：
+
+```json
+// plugins/GoogleSignin/config.json
+{
+  "name": "GoogleSignin",
+  "key": "GOOGLE",
+  "requireConfigs": [
+    "GOOGLE.scheme",
+    "GOOGLE.clientId"
+  ],
+  "pluginParams": {
+    "CLIENT_ID": "{$C.GOOGLE.clientId}",
+    "REVERSED_CLIENT_ID": "{$C.GOOGLE.scheme}"
+  },
+  "urlScheme": "{$C.GOOGLE.scheme}"
+}
+```
+
+`GOOGLE.scheme` 在旧逻辑中有两个作用：
+
+1. 写入 `TOPSDK -> Plugins[] -> params.REVERSED_CLIENT_ID`，供 `GoogleSignin` 插件运行时读取。
+2. 作为 `urlScheme` 写入宿主 `Info.plist` 的 `CFBundleURLTypes[].CFBundleURLSchemes[]`，供 Google 登录回跳 App。
+
+```json
+// plugins/FacebookSignin/config.json
+{
+  "name": "FacebookSignin",
+  "key": "FACEBOOK",
+  "infoParams": {
+    "FacebookAppID": "{$C.FACEBOOK.clientId}",
+    "FacebookDisplayName": "{$C.FACEBOOK.name}",
+    "FacebookClientToken": "{$C.FACEBOOK.secret}"
+  },
+  "requireConfigs": [
+    "FACEBOOK.clientId",
+    "FACEBOOK.name",
+    "FACEBOOK.scheme",
+    "FACEBOOK.secret",
+    "FACEBOOK.openMessenger"
+  ],
+  "pluginParams": {
+    "OPEN_MESSENGER": "{$C.FACEBOOK.openMessenger}"
+  },
+  "urlScheme": "{$C.FACEBOOK.scheme}"
+}
+```
+
+`FACEBOOK.name` 在旧逻辑中只用于 `infoParams`，最终写入宿主 `Info.plist` 顶层的 `FacebookDisplayName`。旧工具不会自动从 `packageName`、App 名称或 `facebookAppId` 推导它；如果服务端 `channelAuthConfig` 没有返回非空 `name` 字段，`requireConfigs` 校验会失败并退出。
+
+字段名要求是旧 iOS 插件配置决定的：Google 要求服务端返回 `scheme` 和 `clientId`；Facebook 要求服务端返回 `clientId`、`name`、`scheme`、`secret`。旧工具本身只做 `MESSENGER -> FACEBOOK` 归并和 `openMessenger` 补值，不会把 `googleClientId` 映射成 `clientId`，也不会把 `fbLoginProtocolScheme` 映射成 `scheme`。
+
+### 6.7 bundled iOS 插件配置矩阵
+
+后续 `meet-sdk-tool` 的 `bundled/ios-sdk` 会提供完整 iOS SDK 包，包内每个插件目录包含 `config.json`（当前仓库测试包使用 `config.t.json`）。旧 Python 工具对这些配置的处理是统一的：
+
+1. `PluginConfig.py` 读取配置字段。
+2. `getOnlineConfig()` 汇总所有启用插件的 `requireConfigs`。
+3. `ChannelConfigManager.getSdkConfig()` 按插件 `key` 拉取在线配置。
+4. `setPlugin()` 根据 `performSettings` 依次处理 `sources`、`frameworks`、`libs`、`buildSettings`、`OtherLinkerFlags`、`queriesSchemes`、`infoParams`、`urlScheme`。
+5. 遍历插件后，将 `pluginParams` 写入 `TOPSDK -> Plugins[]` 或 `TOPSDK -> dataPlugins[]`。
+
+当前 `bundled/ios-sdk/topSDK-ios--V1.6.0.5/plugins` 中的配置要求如下：
+
+| 插件目录 | config.name | key | type | requireConfigs | 写入/作用 |
+|----------|-------------|-----|------|----------------|-----------|
+| `GuestSignin` | `GuestSignin` | `GUEST` | 登录 | 无 | 复制 `TOPGuestSigninPlugin.framework`；注册到 `TOPSDK.Plugins` |
+| `EmailSignin` | `EmailSignin` | `EMAIL` | 登录 | 无 | 复制 `TOPEmailSigninPlugin.framework`；注册到 `TOPSDK.Plugins` |
+| `AppleSignin` | `AppleSignin` | `APPLE` | 登录 | 无 | 复制 `TOPAppleSigninPlugin.framework`；额外开启 Sign in with Apple entitlement；注册到 `TOPSDK.Plugins` |
+| `GoogleSignin` | `GoogleSignin` | `GOOGLE` | 登录 | `GOOGLE.scheme`, `GOOGLE.clientId` | `pluginParams.CLIENT_ID = GOOGLE.clientId`；`pluginParams.REVERSED_CLIENT_ID = GOOGLE.scheme`；`urlScheme = GOOGLE.scheme` |
+| `FacebookSignin` | `FacebookSignin` | `FACEBOOK` | 登录 | `FACEBOOK.clientId`, `FACEBOOK.name`, `FACEBOOK.scheme`, `FACEBOOK.secret`, `FACEBOOK.openMessenger` | `Info.plist` 写 `FacebookAppID`、`FacebookDisplayName`、`FacebookClientToken`；`pluginParams.OPEN_MESSENGER`；`urlScheme = FACEBOOK.scheme`；写入 Facebook 查询 schemes |
+| `SnapchatSignin` | `SnapchatSignin` | `SNAPCHAT` | 登录 | `SNAPCHAT.clientId`, `SNAPCHAT.redirect`, `SNAPCHAT.scheme` | `Info.plist` 写 `SCSDKClientId`、`SCSDKRedirectUrl`、`SCSDKScopes`；`pluginParams.CLIENT_ID/REDIRECT_URL/URL_SCHEME`；`urlScheme = SNAPCHAT.scheme`；写入 Snapchat 查询 schemes |
+| `LineSignin` | `LineSignin` | `LINE` | 登录 | `LINE.clientId`, `LINE.scheme` | `pluginParams.CHANNEL_ID = LINE.clientId`；`pluginParams.URL_SCHEME = LINE.scheme`；`urlScheme = LINE.scheme`；写入 `lineauth2` |
+| `NaverSignin` | `NaverSignin` | `NAVER` | 登录 | `NAVER.name`, `NAVER.clientId`, `NAVER.secret`, `NAVER.scheme` | `pluginParams.APP_NAME/CLIENT_ID/CLIENT_SECRET/URL_SCHEME`；`urlScheme = NAVER.scheme`；写入 Naver 查询 schemes |
+| `KakaoSignin` | `KakaoSignin` | `KAKAO` | 登录 | `KAKAO.clientId`, `KAKAO.scheme` | `pluginParams.NATIVE_APP_KEY = KAKAO.clientId`；`pluginParams.URL_SCHEME = KAKAO.scheme`；`urlScheme = KAKAO.scheme`；写入 Kakao 查询 schemes |
+| `TiktokSignin` | `TiktokSignin` | `TIKTOK` | 登录 | `TIKTOK.clientId`, `TIKTOK.secret`, `TIKTOK.redirect` | `Info.plist` 写 `TikTokClientKey`；`pluginParams.CLIENT_KEY/CLIENT_SECRET/REDIRECT_URL`；`urlScheme = TIKTOK.redirect`；写入 TikTok 查询 schemes |
+| `IAPPay` | `IAPPay` | `IAPPAY` | 支付 | 无 | 复制 `TOPIAPPayPlugin.framework`；注册到 `TOPSDK.Plugins` |
+| `UI` | `UI` | `UI` | UI | 无 | 复制 `TOPUIPlugin.framework`；注册到 `TOPSDK.Plugins` |
+| `AppsFlyerManager` | `AppsFlyerManager` | `APPSFLYER` | data | `APPSFLYER.clientId`, `APPSFLYER.secret` | `Info.plist` 写 `NSAdvertisingAttributionReportEndpoint`；`pluginParams.DEV_KEY = APPSFLYER.secret`；`pluginParams.APPLE_APP_ID = APPSFLYER.clientId`；注册到 `TOPSDK.dataPlugins` |
+| `FirebaseManager` | `FirebaseManager` | `FIREBASE` | data | 无 | 复制 Firebase 相关 frameworks 和 `GoogleService-Info.plist`；注册到 `TOPSDK.dataPlugins` |
+| `AdjustManager` | `AdjustManager` | `ADJUST` | data | `ADJUST.clientId` | `pluginParams.APP_TOKEN = ADJUST.clientId`；注册到 `TOPSDK.dataPlugins` |
+| `FacebookManager` | `FacebookSignin` | `FACEBOOK` | data | `FACEBOOK.clientId`, `FACEBOOK.name`, `FACEBOOK.scheme`, `FACEBOOK.secret` | `Info.plist` 写 `FacebookAppID`、`FacebookDisplayName`、`FacebookClientToken`、`FacebookAutoLogAppEventsEnabled = false`；`urlScheme = FACEBOOK.scheme`；注册到 `TOPSDK.dataPlugins` |
+
+`meet-sdk-tool` 迁移实现要求：
+
+- 插件是否接入只看 `meetsdk-remote-config.json` 中 `sdkModules` 是否存在对应子键。
+- iOS 阶段会读取 `bundled/ios-sdk/**/plugins/<Plugin>/config.json|config.t.json`，并按旧配置的 `requireConfigs` 做校验。
+- 远端字段会归一化为旧 iOS 插件需要的 key；`downloadSDKConfig` 输出只使用 `DTOChannelAuth` / `ChannelThirdDataPlatform` 原字段名：
+  - `login.facebook.clientId -> FACEBOOK.clientId`
+  - `login.facebook.scheme -> FACEBOOK.scheme`
+  - `login.facebook.secret -> FACEBOOK.secret`
+  - `login.facebook.name -> FACEBOOK.name`
+  - `login.google.clientId -> GOOGLE.clientId`
+  - `login.google.scheme -> GOOGLE.scheme`
+  - `analytics.appsflyer.devKey -> APPSFLYER.secret`
+  - `analytics.appsflyer.appleAppId -> APPSFLYER.clientId`
+  - `analytics.adjust.appCode -> ADJUST.clientId`
+  - `analytics.facebookdata.* -> FACEBOOK.*`
+- `infoParams` 支持字符串、布尔值、数组和对象；其中字符串会执行 `{$C...}` 占位符替换。
+- `pluginParams` 会写入 `TOPSDK.Plugins[].params` 或 `TOPSDK.dataPlugins[].params`。
+- `urlScheme` 会写入 `CFBundleURLTypes`；`queriesSchemes` 会写入 `LSApplicationQueriesSchemes`。
+
+当前仍需确认或补齐的项：
+
+| 项 | 当前状态 | 需要确认/处理 |
+|----|----------|---------------|
+| `FirebaseManager/source/GoogleService-Info.plist` | 当前测试包 `topSDK-ios--V1.6.0.5` 中缺失，但配置声明需要复制 | 完整 SDK 包需要提供该文件；如果改为从 `meetsdk-remote-config.analytics.firebase.firebaseUrl` 下载，需要新增 iOS Firebase 下载步骤 |
+| `FacebookManager/config.t.json` | 目录名是 `FacebookManager`，但 `config.name` 是 `FacebookSignin` | 旧 `checkPlugin()` 严格要求目录名等于 `config.name`；当前 TS 已按 data manager 目录兼容处理，但建议确认最终 SDK 包配置是否会修正 |
+| `discord` / `twitter` | 当前 iOS 包没有 `DiscordSignin` / `TwitterSignin` 插件目录 | `meetsdk-remote-config` 即使返回这些子键，iOS 阶段也只能 warning 跳过，除非后续补插件资源 |
+| `GOOGLE.scheme` | 不能从 `clientId` 可靠推导 | 服务端需返回 `scheme` |
+| `FACEBOOK.name` | 不能从 `clientId` 可靠推导 | 服务端需返回 `name` |
+| `SNAPCHAT.scheme` / `LINE.scheme` / `NAVER.scheme` | 仅当 `redirect` 是非 http(s) URL 时可推导 scheme，否则不可推导 | 服务端最好显式返回 `scheme` |
+| `APPSFLYER.clientId` | 旧配置中表示 Apple App ID，不是 devKey | 服务端需返回 `clientId`、`appleAppId` 或 `appId` |
+
+## 7. 模板变量替换
+
+入口在 `checkStr(string, config)`。
+
+旧工具支持在配置字符串中写：
+
+```text
+{$C.GOOGLE.clientId}
+```
+
+替换规则：
+
+1. 只处理字符串类型。
+2. 查找第一个 `{$C` 和第一个 `}`。
+3. 取中间路径，去掉前缀后按 `.` 拆分。
+4. 从 `channelConfig` 中逐级读取值。
+5. 读到 `None` 时替换为空字符串。
+6. 返回替换后的字符串。
+
+限制：
+
+- 单次调用只替换一个占位符。
+- 如果路径不存在，可能直接抛异常。
+- 不支持默认值、转义、多占位符。
+
+TS 迁移时如果追求旧逻辑等价，应先保持单占位符行为；如果要增强，需要单独记录兼容策略。
+
+## 8. 选择 Xcode 工程和 target
+
+### 8.1 输入 `.xcodeproj`
+
+旧工具要求输入 `.xcodeproj` 路径：
+
+```python
+getPath(tips="请输入工程（.xcodeproj）文件路径：", end=".xcodeproj")
+```
+
+校验：
+
+- 输入不能为空。
+- 路径必须存在。
+- 必须以 `.xcodeproj` 结尾。
+
+### 8.2 读取 target
+
+`XcodeManager(projPath)` 加载：
+
+```text
+<project>.xcodeproj/project.pbxproj
+```
+
+再通过 `getNativeTarget()` 读取所有 `PBXNativeTarget`。
+
+### 8.3 选择目标 target
+
+`selectTargetAndStartSetting()` 会过滤这些测试 target：
+
+```text
+layaboxTests
+layaboxUITests
+```
+
+逻辑：
+
+1. 过滤后只剩一个 target：自动选中。
+2. 过滤后多个 target：要求用户选择。
+3. 没有可用 target：退出。
+
+注意：旧代码在只剩一个有效 target 时写的是 `targetName = targetNames[0]`，不是 `effectiveTargetNames[0]`。如果第一个 target 刚好是被过滤的测试 target，可能选错。TS 迁移时建议修正。
+
+## 9. 初始化 XcodeManager
+
+`setupProject()` 内部重新创建 `XcodeManager(projectPath)`，并调用：
+
+```python
+manager.setTarget(targetName)
+```
+
+### 9.1 setTarget 做的事情
+
+1. 通过 target 名称查找 `PBXNativeTarget`。
+2. 读取 target 的 build configurations。
+3. 计算工程源码根目录 `srcRoot`。
+4. 初始化 `FileManager(projectPath, srcRoot)`。
+5. 从 build settings 中解析 `INFOPLIST_FILE`。
+6. 初始化 `InfoPlistManager(infoPlistPaths)`。
+7. 创建或获取名为 `CopyFiles` 的 `PBXCopyFilesBuildPhase`。
+8. 保存一次工程。
+
+### 9.2 srcRoot 计算
+
+默认：
+
+```text
+srcRoot = dirname(.xcodeproj)
+```
+
+如果 pbxproj root object 的 `projectDirPath` 非空，则改用 `projectDirPath`。
+
+这个逻辑主要用于兼容部分 Cocos 工程。原生 iOS 迁移时仍应保留，因为它影响资源复制和文件搜索根目录。
+
+### 9.3 Info.plist 路径解析
+
+从每个 build configuration 的：
+
+```text
+INFOPLIST_FILE
+```
+
+解析真实路径。
+
+处理规则：
+
+- 如果包含 `$(SRCROOT)`，替换为 `srcRoot`。
+- 如果已经包含 `srcRoot`，直接使用。
+- 否则拼接：
+
+```text
+srcRoot + INFOPLIST_FILE
+```
+
+多个 configuration 指向同一个 plist 时会去重。
+
+找不到任何 plist 会退出。
+
+## 10. 资源复制目录
+
+`FileManager` 会在游戏工程源码根目录创建：
+
+```text
+<srcRoot>/topSDK/
+```
+
+所有 SDK 和插件资源都会先复制到这个目录，再加入 Xcode 工程。
+
+复制规则：
+
+| 方法 | 行为 |
+|------|------|
+| `copyFramework` | 只接受路径包含 `.framework` 或 `.bundle` 的目录；目标已存在则先删除再复制 |
+| `copyDir` | 复制目录；目标已存在则先删除再复制 |
+| `copyFile` | 复制单文件；目标已存在则先删除再复制 |
+
+注意：旧 `copyFramework` 不支持 `.xcframework`。如果配置里出现 `.xcframework`，旧逻辑会打印错误并返回 `None`。TS 迁移时需要明确是否兼容旧行为，还是补齐 `.xcframework` 支持。
+
+## 11. SDK 核心接入流程
+
+`setupProject()` 中，如果 `sdkConfig is not None`，会遍历全局 `sdkConfigs` 调用 `setPlugin()`。
+
+默认执行的 `performSettings`：
+
+```python
+[
+  "sources",
+  "frameworks",
+  "libs",
+  "buildSettings",
+  "OtherLinkerFlags",
+  "queriesSchemes",
+  "infoParams",
+  "urlScheme"
+]
+```
+
+SDK 核心配置的 `type == 0`，资源根目录使用：
+
+```text
+sdk/source/
+```
+
+## 12. 插件接入流程
+
+`setupProject()` 接着遍历 `pluginConfigs`：
+
+1. 调用 `setPlugin(pluginConfig, manager, channelConfig, performSettings, engineType, engineVersion)` 完成资源和工程配置。
+2. 如果插件名是 `AppleSignin`，标记 `hasAppleSignIn = True`。
+3. 构造写入 Info.plist 的插件注册信息：
+
+```json
+{
+  "name": "PluginName",
+  "params": {}
+}
+```
+
+4. 如果服务端返回了该插件 `key` 对应的配置，并且插件配置里有 `pluginParams`，则对每个参数执行 `checkStr()` 替换。
+5. `type == 4` 的插件放入 `dataPluginsInfo`。
+6. 其他插件放入 `pluginsInfo`。
+
+## 13. setPlugin 详细行为
+
+`setPlugin()` 是旧工具资源和配置接入的核心方法。
+
+### 13.1 资源根目录
+
+普通插件：
+
+```text
+plugins/<PluginName>/source/
+```
+
+SDK 核心：
+
+```text
+sdk/source/
+```
+
+### 13.2 frameworks
+
+仅当 `performSettings` 包含 `"frameworks"` 时执行。
+
+对每个 `framework`：
+
+#### 非系统 framework
+
+路径：
+
+```text
+<sourcePath>/<framework.name>
+```
+
+普通原生 iOS 逻辑：
+
+1. 调用 `manager.addThirdFramework(path, embed=framework.embed)`。
+2. 如果 `framework.copyFile == True`，再调用 `manager.addCopyFramework(framework.name)`。
+
+`addThirdFramework()` 行为：
+
+1. 按文件名查找工程中是否已存在。
+2. 不存在时：
+   - 复制到 `<srcRoot>/topSDK/`。
+   - 加入 Xcode `Frameworks` group。
+   - 使用 `SOURCE_ROOT` 引用。
+   - `weak=True`。
+   - `code_sign_on_copy=True`。
+3. 如果 `embed=True`：
+   - 创建或获取 `Embed Frameworks` phase。
+   - 如果 phase 中不存在该 framework，则添加 build file。
+
+#### 系统 framework
+
+调用：
+
+```python
+manager.addSystemFramework(framework.name)
+```
+
+行为：
+
+1. 从 `System/Library/Frameworks/<frameworkName>` 添加。
+2. 如果工程中已有同名系统 framework，先移除再添加。
+
+### 13.3 libs
+
+仅当 `performSettings` 包含 `"libs"` 时执行。
+
+#### 非系统 lib
+
+路径：
+
+```text
+<sourcePath>/<lib.name>
+```
+
+调用 `manager.addFile(path)`：
+
+- 已存在同名文件引用时先移除。
+- 复制到 `<srcRoot>/topSDK/`。
+- 添加到 Xcode 工程。
+
+#### 系统 lib
+
+调用：
+
+```python
+manager.addSystemLib(lib.name)
+```
+
+从：
+
+```text
+usr/lib/<libName>
+```
+
+添加。
+
+### 13.4 sources
+
+仅当 `performSettings` 包含 `"sources"` 时执行。
+
+对每个 `source`：
+
+```text
+<sourcePath>/<source>
+```
+
+判断规则：
+
+- 如果是目录，且不是 `.bundle`、`.framework`、`.xcdatamodeld`，调用 `manager.addDir(path)`。
+- 否则调用 `manager.addFile(path)`。
+
+`addDir()` 行为：
+
+1. 整个目录复制到 `<srcRoot>/topSDK/<dirname>`。
+2. 创建或获取同名 group。
+3. 遍历复制后的目录。
+4. 跳过 `.bundle` 和 `.framework` 内部文件。
+5. 添加这些文件类型：
+   - `.h`
+   - `.m`
+   - `.mm`
+   - `.plist`
+   - `.a`
+6. 遇到 `.bundle` 目录时，作为资源整体加入工程。
+
+`addFile()` 行为：
+
+- 普通文件：复制到 `topSDK/` 后加入工程。
+- `.bundle` / `.xcdatamodeld` 目录：复制目录后作为文件引用加入工程。
+
+### 13.5 buildSettings
+
+仅当 `performSettings` 包含 `"buildSettings"` 时执行。
+
+对 `config.buildSettings` 中每个 key：
+
+```python
+manager.setBuildSetting(key, value)
+```
+
+会写入当前 target 的所有 build configurations。
+
+### 13.6 OtherLinkerFlags
+
+仅当 `performSettings` 包含 `"OtherLinkerFlags"` 时执行。
+
+调用：
+
+```python
+manager.addOtherLinkFlag(flag)
+```
+
+处理规则：
+
+- 如果 `OTHER_LDFLAGS` 是字符串：不存在该 flag 时拼接到字符串末尾。
+- 如果是数组：不存在该 flag 时 append。
+- 如果不存在或类型异常：设置为 `[flag]`。
+
+### 13.7 queriesSchemes
+
+仅当 `performSettings` 包含 `"queriesSchemes"` 时执行。
+
+调用：
+
+```python
+manager.addQueriesScheme(scheme)
+```
+
+写入 `Info.plist` 的：
+
+```text
+LSApplicationQueriesSchemes
+```
+
+已存在则跳过。
+
+### 13.8 infoParams
+
+仅当 `performSettings` 包含 `"infoParams"` 时执行。
+
+对 `config.infoParams` 中每个 key：
+
+1. 对 value 执行 `checkStr(value, channelConfig)`。
+2. 写入 `Info.plist` 顶层：
+
+```python
+plist[key] = value
+```
+
+如果已有同名 key，会直接覆盖。
+
+对 `FacebookSignin` 来说，`infoParams` 中的：
+
+```json
+{
+  "FacebookDisplayName": "{$C.FACEBOOK.name}"
+}
+```
+
+会通过 `checkStr()` 读取 `channelConfig["FACEBOOK"]["name"]`，然后写入：
+
+```text
+Info.plist -> FacebookDisplayName
+```
+
+因此 `FACEBOOK.name` 缺失时，旧工具会在 `requireConfigs` 阶段失败；如果绕过校验，`checkStr()` 在路径不存在时可能直接抛异常。
+
+### 13.9 urlScheme
+
+仅当 `performSettings` 包含 `"urlScheme"` 时执行。
+
+处理规则：
+
+1. 对 `config.urlScheme` 执行 `checkStr()`。
+2. 如果结果以 `://` 结尾，移除 `://`。
+3. 调用 `manager.addUrlScheme(urlScheme)`。
+
+写入 `Info.plist`：
+
+```text
+CFBundleURLTypes[]
+```
+
+格式：
+
+```json
+{
+  "CFBundleTypeRole": "Editor",
+  "CFBundleURLSchemes": ["scheme"]
+}
+```
+
+已存在同名 scheme 时跳过。
+
+对 `GoogleSignin` 来说，`urlScheme` 为：
+
+```text
+{$C.GOOGLE.scheme}
+```
+
+会通过 `checkStr()` 读取 `channelConfig["GOOGLE"]["scheme"]`，然后写入 `CFBundleURLTypes`。同时同一个值还会通过 `pluginParams.REVERSED_CLIENT_ID` 写入 `TOPSDK -> Plugins[] -> params`。
+
+### 13.10 保存
+
+`setPlugin()` 末尾会调用：
+
+```python
+manager.save()
+```
+
+保存：
+
+- `.xcodeproj/project.pbxproj`
+- 所有关联 `Info.plist`
+
+## 14. TOPSDK 插件注册信息
+
+插件遍历完成后，如果 `performSettings` 包含 `"infoParams"`，旧工具会写入：
+
+```python
+manager.addInfoConfig("TOPSDK", {
+  "APP_ID": appId,
+  "Plugins": pluginsInfo,
+  "dataPlugins": dataPluginsInfo
+})
+```
+
+写入位置是 `Info.plist` 顶层 key：
+
+```text
+TOPSDK
+```
+
+结构：
+
+```json
+{
+  "APP_ID": "xxx",
+  "Plugins": [
+    {
+      "name": "GoogleSignin",
+      "params": {
+        "CLIENT_ID": "...",
+        "REVERSED_CLIENT_ID": "..."
+      }
+    }
+  ],
+  "dataPlugins": [
+    {
+      "name": "TOPData",
+      "params": {}
+    }
+  ]
+}
+```
+
+这里会直接覆盖已有 `TOPSDK` 字段，不做深度合并。
+
+## 15. Apple Sign In entitlements
+
+旧工具根据是否接入 `AppleSignin` 插件调用：
+
+```python
+manager.openSigninWithApple(hasAppleSignIn)
+```
+
+### 15.1 已接入 AppleSignin
+
+对当前 target 的每个 build configuration：
+
+1. 读取 `CODE_SIGN_ENTITLEMENTS`。
+2. 如果为空：
+   - 创建目录：
+
+```text
+<srcRoot>/<targetName>/
+```
+
+   - 设置：
+
+```text
+CODE_SIGN_ENTITLEMENTS = <targetName>/<targetName>.entitlements
+```
+
+3. 打开或创建 entitlements 文件。
+4. 写入：
+
+```json
+{
+  "com.apple.developer.applesignin": ["Default"]
+}
+```
+
+如果 entitlements 已存在，会保留其他 key，只覆盖 `com.apple.developer.applesignin`。
+
+### 15.2 未接入 AppleSignin
+
+如果 `isOpen == False`：
+
+1. 如果 entitlements 文件存在，删除其中的 `com.apple.developer.applesignin`。
+2. 如果 entitlements 文件不存在，创建空 plist。
+3. 然后直接 `return`。
+
+注意：旧工具每次都会调用该方法。也就是说，如果工程原本手动开启了 Apple Sign In，但本次 SDK 插件列表没有 `AppleSignin`，旧工具可能移除该 entitlement。TS 迁移时需要确认是否继续保持这个副作用。
+
+## 16. AppDelegate / SceneDelegate 自动注入
+
+插件和 plist 配置完成后，如果：
+
+```python
+executeAppDelegate == True and sdkConfig
+```
+
+旧工具会遍历 SDK 核心配置 `sdkConfigs`，读取其中的：
+
+- `appDelegateCodes`
+- `sceneDelegateCodes`
+
+然后自动查找并修改源码文件。
+
+### 16.1 查找 UIApplicationDelegate
+
+`manager.findDelegateFile()` 在 `srcRoot` 下递归扫描：
+
+- `.m`
+- `.mm`
+- `.h`
+
+如果文件内容包含：
+
+```text
+UIApplicationDelegate
+```
+
+则认为是候选。
+
+如果命中的是 `.h` 文件，会尝试查找同名 `.m` 或 `.mm`，把实现文件加入候选列表。
+
+之后会排除这些文件：
+
+```text
+Unity_iPhone_Tests.m
+UnityAppController+ViewHandling.mm
+```
+
+处理逻辑：
+
+- 只有一个候选：自动注入。
+- 多个候选：要求用户选择。
+- 没有候选：提示参考 wiki 手动接入。
+
+### 16.2 查找 UIWindowSceneDelegate
+
+`manager.findSceneDelegateFile()` 在 `srcRoot` 下递归扫描 `.m`、`.mm`、`.h`。
+
+如果文件内容包含：
+
+```text
+UIWindowSceneDelegate
+```
+
+则认为是候选。
+
+`.h` 命中时同样会查找同名 `.m` / `.mm`。
+
+处理逻辑：
+
+- 只有一个候选：自动注入。
+- 多个候选：要求用户选择。
+- 没有候选：不处理，也不退出。
+
+### 16.3 代码注入入口
+
+`addCodes(filePath, codeConfigs)` 对每个 code config：
+
+- `type == "header"`：调用 `CodeUtils.addHeader(content)`。
+- 其他类型：调用 `CodeUtils.addCodeToMethod(method, content, addToReturn)`。
+
+只要有一个 code config 注入失败，最终输出“自动接入失败，请参照在线文档自行接入”。
+
+## 17. CodeUtils 注入规则
+
+### 17.1 重复判断
+
+`checkExisted(code)`：
+
+1. 读取整个文件。
+2. 移除所有空格 `" "`。
+3. 将目标 code 也移除空格。
+4. 用字符串包含判断是否已存在。
+
+注意：只移除普通空格，不移除 tab、换行。
+
+### 17.2 添加 header
+
+`addHeader(code)`：
+
+1. 如果代码已存在，直接成功。
+2. 否则把 code 插入到文件最顶部：
+
+```text
+<code>
+<原文件内容>
+```
+
+### 17.3 添加方法代码
+
+`addCodeToMethod(method, code, addToReturn=False)`：
+
+前置处理：
+
+- 如果目标 code 已存在，直接成功。
+- 删除 `code` 中所有分号 `;`。
+- 删除 `method` 中的 `{` 和 `}`。
+
+#### 方法已存在，且 `addToReturn == False`
+
+1. 找到包含 method 的行。
+2. 从该位置开始，找到第一个 `{`。
+3. 在 `{` 后插入：
+
+```objc
+    <code>;
+```
+
+#### 方法已存在，且 `addToReturn == True`
+
+1. 找到包含 method 的行。
+2. 从该位置开始，找到第一行包含 `return` 的代码。
+3. 如果原 return 是：
+
+```objc
+return YES;
+return NO;
+```
+
+则替换为：
+
+```objc
+return <code>;
+```
+
+4. 否则取原 return 表达式，改为：
+
+```objc
+return (<原return表达式> && <code>);
+```
+
+#### 方法不存在
+
+1. 找到 `@implementation`。
+2. 在后续第一个 `@end` 前插入完整方法：
+
+```objc
+<method> {
+    <code>;
+}
+@end
+```
+
+如果 `addToReturn == True`，方法体为：
+
+```objc
+return <code>;
+```
+
+### 17.4 注入限制
+
+旧实现是纯文本插入，没有 Objective-C AST：
+
+- 不理解注释、宏、多行方法签名等复杂情况。
+- 方法匹配依赖字符串包含。
+- `return` 替换只找方法后的第一行 `return`。
+- 只处理 Objective-C / Objective-C++，不处理 Swift AppDelegate。
+
+TS 迁移时如果保持等价，可以先复刻文本策略；如果提升可靠性，应把差异写入迁移说明，并补 golden diff。
+
+## 18. 幂等性和覆盖行为
+
+旧工具具备部分幂等能力，但不是所有操作都安全。
+
+| 操作 | 旧工具行为 |
+|------|------------|
+| 复制到 `topSDK/` | 目标已存在则删除后重新复制 |
+| 普通文件加入工程 | 已有同名引用时先移除再添加 |
+| system framework / lib | 已有同名引用时先移除再添加 |
+| third framework | 已有同名 framework 时跳过复制和添加 |
+| embed framework | phase 中已有同名项时跳过 |
+| CopyFiles framework | phase 中已有同名项时跳过 |
+| `LSApplicationQueriesSchemes` | 已存在 scheme 时跳过 |
+| `CFBundleURLTypes` | 已存在 scheme 时跳过 |
+| `OTHER_LDFLAGS` | 已存在 flag 时跳过 |
+| `Info.plist` 普通 key | 直接覆盖 |
+| `TOPSDK` | 直接覆盖整个字典 |
+| header / method code | 通过去空格字符串包含判断，已存在则跳过 |
+| Apple Sign In entitlement | 有插件则写入；无插件可能删除 |
+
+TS 迁移验收时要重点验证重复执行：
+
+- 不重复添加 framework。
+- 不重复添加 URL Scheme。
+- 不重复添加 Queries Schemes。
+- 不重复添加 linker flags。
+- 不重复注入 Delegate 代码。
+- `TOPSDK` 字段被稳定更新，不产生重复插件项。
+
+## 19. 原生 iOS 完整执行顺序
+
+下面是旧工具在选择 `ios` 后的实际主流程。
+
+1. 计算 `rootPath`。
+2. 设置：
+
+```text
+sdkPath = <rootPath>/sdk
+pluginsPath = <rootPath>/plugins
+```
+
+3. 读取 `sdk/*.json`，生成 `sdkConfigs`。
+4. 读取 `plugins/*/config.json`，生成 `pluginConfigs`。
+5. 根据插件 `requireConfigs` 判断是否需要请求服务端。
+6. 如需要，输入 `appId`、`appSecret`。
+7. 请求 `/console/openSDK/getSDKConfig`。
+8. 校验 `requireConfigs` 是否全部返回。
+9. 选择游戏引擎，原生 iOS 选择 `ios`。
+10. 输入 `.xcodeproj` 路径。
+11. 检查 `sdk/` 和 `plugins/` 资源完整性。
+12. `checkEngineSource("ios", None)` 直接返回 `True`。
+13. 加载 `.xcodeproj/project.pbxproj`。
+14. 读取所有 `PBXNativeTarget`。
+15. 过滤测试 target。
+16. 自动选择唯一 target，或由用户选择 target。
+17. 调用 `setupProject()`。
+18. `XcodeManager.setTarget()`：
+    - 读取 build configurations。
+    - 解析 `srcRoot`。
+    - 创建 `topSDK/`。
+    - 解析 Info.plist。
+    - 创建 CopyFiles phase。
+19. 遍历 `sdkConfigs`，调用 `setPlugin()` 接入 SDK 核心。
+20. 遍历 `pluginConfigs`，调用 `setPlugin()` 接入插件。
+21. 根据插件生成 `pluginsInfo` / `dataPluginsInfo`。
+22. 根据是否存在 `AppleSignin` 修改 entitlements。
+23. 写入 `Info.plist` 顶层 `TOPSDK`。
+24. 保存 Xcode 工程和 Info.plist。
+25. 查找 AppDelegate 文件。
+26. 根据 `sdkConfigs.appDelegateCodes` 注入 import / 方法代码。
+27. 查找 SceneDelegate 文件。
+28. 根据 `sdkConfigs.sceneDelegateCodes` 注入方法代码。
+29. 输出完成或失败提示。
+
+## 20. TS 迁移建议
+
+为了在 `meet-sdk-tool` 中实现等价能力，建议拆成这些模块：
+
+| TS 模块 | 对应旧逻辑 |
+|---------|------------|
+| `sdkBundle` | 解析 bundled iOS SDK 包，定位 `sdk/`、`plugins/` |
+| `pluginConfig` | 解析旧 `config.json` / 新 `config.t.json` |
+| `remoteConfig` | 请求 `downloadSDKConfig` 或兼容旧 `getSDKConfig` |
+| `templateResolver` | 实现 `{$C.xxx}` 参数替换 |
+| `pbxprojEditor` | 修改 target、build settings、frameworks、libs、build phases |
+| `fileManager` | 复制资源到 `<projectRoot>/topSDK/` |
+| `infoPlist` | 写入普通字段、`TOPSDK`、URL Scheme、Queries Schemes |
+| `entitlements` | 创建 / 修改 Apple Sign In capability |
+| `delegateInjector` | 查找并修改 AppDelegate / SceneDelegate |
+| `iosIntegrator` | 编排完整流程 |
+
+实现时建议优先做这些等价约束：
+
+1. 固定输入，不依赖实时后台接口做单元测试。
+2. 同一份 sample 工程分别跑旧 Python 和新 TS，比较 golden output。
+3. 重复执行两次，确认不重复插入。
+4. 缺少资源、缺少 Info.plist、多 target、多 Delegate 时给明确错误。
+5. 保留旧工具输出目录 `topSDK/`，避免接入文档和 CP 预期变化。
+6. 对 `.xcframework` 做明确决策：要么兼容旧工具不支持，要么新增支持并写入差异说明。
+7. Apple Sign In 无插件时是否删除 entitlement，需要业务确认；不建议默认删除用户已有能力。
+
+## 21. 与现有 meet-sdk-tool 的迁移关系
+
+当前 `meet-sdk-tool` 中已有 iOS MVP 实现，但不能简单认为等价于旧 Python 工具。迁移时应以本文档和 `ios-topsdk-tool-feature-test-plan.md` 为基准逐项对齐。
+
+最低完成标准：
+
+1. 同一输入下，Python 工具和 TS 工具产物语义等价。
+2. `.xcodeproj` 中 framework / lib / source / build setting / build phase 等修改一致。
+3. `Info.plist` 中 `TOPSDK`、URL Scheme、Queries Schemes、插件参数一致。
+4. Delegate / SceneDelegate 注入结果一致或有明确差异说明。
+5. 重复执行不会重复插入 framework、plist、code。
+6. 缺少配置或资源时，TS 工具能给出明确错误，而不是生成半成品工程。
+
+---
+
+## 功能点与测试方法
+
+本文档用于迁移 `topsdk-tool-ios` 到 `meet-sdk-tool` 前的行为梳理。范围只覆盖：
+
+- 下载 TOPSDK 包后的本地资源要求与校验
+- 将 TOPSDK 接入 iOS 原生 `.xcodeproj`
+
+明确不覆盖：
+
+- Unity / Cocos Creator / LayaNative 等非 iOS 原生工程接入
+- `upload.py` 资源上传到下载页
+- `update.py` 将编译产物更新回 TOPSDK 资源目录
+
+## 1. 旧工具入口与范围
+
+旧工具主入口是 `topsdk-tool-ios/TopSDKTool.py`。
+
+运行时默认用 `sys.argv[0]` 所在目录作为 TOPSDK 包根目录，并要求包内存在：
+
+```text
+<topsdk-package>/
+  sdk/
+    *.json
+    source/
+  plugins/
+    <PluginName>/
+      config.json
+      source/
+```
+
+`currentEnv != ENV.prod` 时，旧代码会把 `rootPath` 强制写死为开发者本机路径 `/Users/lvyunjie/Downloads/topSDK-ios--V1.6.0.2`。迁移时不应保留这个本机路径行为。
+
+iOS 原生工程接入分支位于：
+
+```text
+TopSDKTool.py
+  __main__
+    -> engineType == "ios"
+    -> selectTargetAndStartSetting(...)
+    -> setupProject(...)
+    -> setPlugin(...)
+```
+
+非原生分支只作为排除项记录，不迁移。
+
+## 2. 下载 TOPSDK
+
+### 2.1 旧工具实际行为
+
+`topsdk-tool-ios` 主工具本身没有实现“从服务端下载 TOPSDK 包”的网络逻辑。它假设用户已经从下载页拿到了一个本地 TOPSDK 包，然后执行：
+
+1. 读取包内 `sdk/` 目录下的 SDK 配置 JSON。
+2. 读取包内 `plugins/*/config.json`。
+3. 校验 `sdk/` 和 `plugins/` 资源完整性。
+4. 使用这些本地资源修改目标 Xcode 工程。
+
+与“下载页”相关的脚本是 `upload.py`，它负责把 `TopSDK` 目录内资源打包并上传到下载页；这属于资源发布流程，不属于接入工具运行时能力，本次不迁移。
+
+### 2.2 资源完整性校验
+
+旧代码位置：
+
+- `TopSDKTool.py::checkEnv`
+- `TopSDKTool.py::checkPlugin`
+- `PluginConfig.py::PluginConfig`
+
+校验规则：
+
+| 功能点 | 旧行为 | 测试方法 |
+|---|---|---|
+| `sdk/` 存在性 | `sdkPath` 不存在时打印 `error: sdk目录不存在`，返回 `False` | 构造缺少 `sdk/` 的 TOPSDK 包，断言迁移工具失败且错误信息明确 |
+| `plugins/` 存在性 | 不存在或为空时只打印 warning，不中断 | 构造只有 `sdk/`、无 `plugins/` 的包，断言可继续接入核心 SDK |
+| 插件 `config.json` 存在性 | 插件目录缺配置时认为插件异常 | 构造缺少 `plugins/GoogleSignin/config.json` 的包，断言报告具体插件名 |
+| 插件名一致性 | `config.name` 必须等于插件目录名 | 构造目录名与 `config.name` 不一致，断言失败 |
+| `sources` 资源存在性 | `config.sources` 中每一项必须存在于 `source/` | 删除一个 source 文件/目录，断言失败并指出缺失资源 |
+| 非系统 framework 存在性 | `framework.system == false` 时，`source/<framework.name>` 必须存在 | 删除一个三方 framework，断言失败 |
+| 非系统 lib 存在性 | `lib.system == false` 时，`source/<lib.name>` 必须存在 | 删除一个三方 lib，断言失败 |
+| JSON 格式 | `PluginConfig` 解析失败直接退出 | 提供非法 JSON，断言失败且错误可读 |
+
+### 2.3 在线参数拉取
+
+旧工具会根据插件配置中的 `requireConfigs` 判断是否需要在线拉参数。这里拉取的是“渠道配置”，不是 SDK 包下载。
+
+旧代码位置：
+
+- `TopSDKTool.py::getOnlineConfig`
+- `ChannelConfigManager.py::getSdkConfig`
+
+旧接口：
+
+```text
+GET {baseUrl}/console/openSDK/getSDKConfig
+```
+
+请求参数：
+
+```text
+appId
+authType[]
+channelType=apple
+sign=base64(md5(appId + appSecret + timestamp))
+timestamp
+```
+
+特殊处理：
+
+- `GUEST`、`UI`、`IAPPAY` 会从 `authType` 中移除。
+- `MESSENGER` 会映射为 `FACEBOOK`，并设置 `openMessenger = "1"`。
+- `FACEBOOK` 会设置 `openMessenger = "0"`。
+- 如果缺少 `requireConfigs` 中声明的参数，旧工具会打印缺失项并退出。
+
+迁移测试方法：
+
+| 功能点 | 测试方法 |
+|---|---|
+| 签名算法 | 固定 `appId/appSecret/timestamp`，断言输出 sign 与 Python `md5_base64_byte` 一致 |
+| authType 过滤 | 输入 `GUEST/UI/IAPPAY/GOOGLE`，断言请求中只包含需要服务端配置的登录渠道 |
+| MESSENGER 映射 | mock 返回 `authType=MESSENGER`，断言迁移后的配置归入 `FACEBOOK` 且 `openMessenger=1` |
+| FACEBOOK 默认值 | mock 返回 `authType=FACEBOOK`，断言 `openMessenger=0` |
+| 缺配置失败 | 插件 `requireConfigs` 声明 `GOOGLE.clientId`，mock 返回缺失该字段，断言失败并列出缺失参数 |
+| 无需在线配置 | 所有插件 `requireConfigs` 为空时，不发起网络请求，只要求用户/命令提供 `appId` |
+
+## 3. iOS 原生工程接入
+
+### 3.1 输入
+
+迁移后的命令输入应至少包含：
+
+```text
+--project-root <iOS 工程根目录或 .xcodeproj 路径>
+--app-id <APP_ID>
+--app-secret <APP_SECRET>   # 仅在需要拉在线渠道配置时使用
+--channel-type APPLE        # 或沿用 iOS 固定 apple/APPLE 约定
+```
+
+旧工具交互输入：
+
+- 选择游戏引擎：本次迁移固定为 iOS 原生，不再提供选择。
+- 输入 `.xcodeproj` 路径：迁移后使用 `--project-root` 检测。
+- 多 target 时选择打包 App target：迁移后应支持参数或明确报错。
+- 多 AppDelegate / SceneDelegate 时选择目标文件：迁移后应支持参数或明确报错。
+
+### 3.2 Target 选择
+
+旧代码位置：
+
+- `XcodeManager.py::getNativeTarget`
+- `TopSDKTool.py::selectTargetAndStartSetting`
+
+旧行为：
+
+1. 读取 `project.pbxproj` 中所有 `PBXNativeTarget`。
+2. 过滤固定测试 target：`layaboxTests`、`layaboxUITests`。
+3. 有 1 个有效 target 时自动选择。
+4. 有多个有效 target 时交互选择。
+5. 没有有效 target 时退出。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 单 App target | 自动选择该 target 并完成接入 |
+| 多 App target | 无显式 target 参数时给出明确错误，或按迁移设计进入可配置选择 |
+| 只有测试 target | 失败并提示没有有效 App target |
+| 指定不存在 target | 失败并提示 target 不存在 |
+
+### 3.3 读取 Info.plist
+
+旧代码位置：
+
+- `XcodeManager.py::findInfoPlistPath`
+- `InfoPlistManager.py`
+
+旧行为：
+
+1. 从 target 的 build settings 读取 `INFOPLIST_FILE`。
+2. 支持 `$(SRCROOT)` 替换。
+3. 同一个 target 的 Debug/Release 可能对应多个 plist，旧工具会全部写入。
+4. 找不到 Info.plist 时退出。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| `INFOPLIST_FILE` 使用相对路径 | 能解析到真实 plist 并写入 |
+| `INFOPLIST_FILE` 使用 `$(SRCROOT)` | 能正确替换 |
+| Debug/Release 使用不同 plist | 两个 plist 都写入相同 SDK 配置 |
+| plist 不存在或无法解析 | 失败并提示具体路径 |
+
+### 3.4 复制 SDK 与插件资源
+
+旧代码位置：
+
+- `FileManager.py`
+- `XcodeManager.py::addFile`
+- `XcodeManager.py::addDir`
+- `XcodeManager.py::addThirdFramework`
+
+旧行为：
+
+1. 在宿主工程根目录创建 `topSDK/`。
+2. framework / bundle / xcdatamodeld / lib / 源码文件都会复制到 `topSDK/`。
+3. 同名目录已存在时先删除再复制。
+4. 同名文件已存在时先删除再复制。
+5. `addDir` 只把 `.h/.m/.mm/.plist/.a` 和 `.bundle` 加入 Xcode 工程，跳过 `.framework` 和 `.bundle` 内部遍历。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 首次接入 | 工程根目录生成 `topSDK/`，资源被复制 |
+| 重复接入 | `topSDK/` 下同名资源被替换，不产生重复文件引用 |
+| 复制 framework | `project.pbxproj` 中存在 framework 文件引用 |
+| 复制 bundle | bundle 被复制并加入资源引用 |
+| 复制 `.xcdatamodeld` | 被复制并加入工程引用 |
+| 复制源码目录 | 目录内 `.h/.m/.mm/.plist/.a` 被加入工程 |
+| 缺资源 | 失败并提示缺失资源路径 |
+
+### 3.5 Framework 接入
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `XcodeManager.py::addThirdFramework`
+- `XcodeManager.py::addSystemFramework`
+- `XcodeManager.py::addCopyFramework`
+
+配置字段：
+
+```json
+{
+  "frameworks": [
+    {
+      "name": "Some.framework",
+      "system": false,
+      "embed": true,
+      "copyFile": true
+    }
+  ]
+}
+```
+
+旧行为：
+
+| 类型 | 行为 |
+|---|---|
+| 三方 framework | 从 SDK 包复制到 `topSDK/`，加入 `Frameworks` group |
+| `embed=true` | 加入 `Embed Frameworks` build phase |
+| `copyFile=true` | 加入名为 `CopyFiles` 的 `PBXCopyFilesBuildPhase` |
+| 系统 framework | 以 `SDKROOT/System/Library/Frameworks/<name>` 加入工程 |
+| 重复 framework | 已存在时避免重复加入 |
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 三方 framework | 文件复制到 `topSDK/`，`pbxproj` 有文件引用 |
+| embed framework | `Embed Frameworks` phase 中有对应 build file |
+| copyFile framework | `CopyFiles` phase 中有对应 build file |
+| 系统 framework | `pbxproj` 中引用 `System/Library/Frameworks/<name>` |
+| 重复执行 | framework、Embed phase、CopyFiles phase 均不重复 |
+
+### 3.6 Library 接入
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `XcodeManager.py::addSystemLib`
+- `XcodeManager.py::addFile`
+
+旧行为：
+
+| 类型 | 行为 |
+|---|---|
+| 三方 lib | 从 SDK 包复制到 `topSDK/` 并加入工程 |
+| 系统 lib | 以 `SDKROOT/usr/lib/<name>` 加入工程 |
+| 重复 lib | 先移除已有引用，再加入 |
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 三方 `.a` | 文件复制到 `topSDK/`，`pbxproj` 有引用 |
+| 系统 `libz.tbd` / `libsqlite3.tbd` | `pbxproj` 有 `usr/lib/<name>` 引用 |
+| 重复执行 | 不产生重复引用 |
+
+### 3.7 Build Settings
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `XcodeManager.py::setBuildSetting`
+
+旧行为：
+
+`config.buildSettings` 中的每个 key/value 会写入当前 target 的所有 build configurations。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 设置单个 build setting | Debug/Release 都写入对应值 |
+| 覆盖已有值 | 旧值被替换为配置值 |
+| 多插件设置同一 key | 迁移设计需定义优先级；旧工具后执行的插件覆盖前者 |
+
+### 3.8 Other Linker Flags
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `XcodeManager.py::addOtherLinkFlag`
+
+旧行为：
+
+1. 对所有 build configurations 写入。
+2. 如果 `OTHER_LDFLAGS` 是字符串，则拼接追加。
+3. 如果是数组，则 append。
+4. 已存在相同 flag 时不重复添加。
+5. 如果原字段不存在或类型异常，则创建数组。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 原值为字符串 | 追加 flag，不破坏原内容 |
+| 原值为数组 | append flag |
+| 原值为空 | 创建 `OTHER_LDFLAGS` |
+| 重复执行 | flag 不重复 |
+
+### 3.9 Info.plist 普通参数
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `InfoPlistManager.py::addParams`
+
+旧行为：
+
+1. `config.infoParams` 的 key/value 写入 Info.plist 顶层。
+2. value 支持 `{$C.xxx.yyy}` 占位符替换。
+3. 当前 `checkStr` 只处理一个占位符。
+4. 缺失路径在旧代码中可能抛异常；迁移后应给出明确错误。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 普通字符串 | plist 顶层写入 key/value |
+| 字典/数组值 | 保持 plist 结构写入 |
+| 占位符替换 | `{$C.GOOGLE.clientId}` 替换为在线配置值 |
+| 缺少占位符数据 | 失败并提示缺少哪个配置路径 |
+| 重复执行 | 同一 key 被更新，不重复产生结构 |
+
+### 3.10 URL Scheme
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `InfoPlistManager.py::addUrlScheme`
+
+旧行为：
+
+1. `config.urlScheme` 写入 `CFBundleURLTypes`。
+2. 支持占位符替换。
+3. 如果 scheme 以 `://` 结尾，会去掉 `://`，用于兼容 Twitter callback_url。
+4. 已存在相同 scheme 时不重复添加。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 普通 scheme | `CFBundleURLTypes` 添加该 scheme |
+| `scheme://` | 写入时去掉 `://` |
+| 占位符 scheme | 正确替换为渠道配置值 |
+| 重复执行 | 不重复添加 |
+
+### 3.11 LSApplicationQueriesSchemes
+
+旧代码位置：
+
+- `TopSDKTool.py::setPlugin`
+- `InfoPlistManager.py::addQueriesScheme`
+
+旧行为：
+
+`config.queriesSchemes` 中每个值写入 `LSApplicationQueriesSchemes`，已存在时不重复添加。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 添加新 scheme | plist 数组新增 |
+| 已存在 scheme | 不重复 |
+| 多插件相同 scheme | 最终只保留一份 |
+
+### 3.12 TOPSDK 插件注册
+
+旧代码位置：
+
+- `TopSDKTool.py::setupProject`
+
+旧行为：
+
+接入完所有插件后，在 Info.plist 顶层写入：
+
+```plist
+TOPSDK = {
+  APP_ID = <appId>;
+  Plugins = (
+    {
+      name = <PluginName>;
+      params = { ... };
+    }
+  );
+  dataPlugins = (
+    {
+      name = <PluginName>;
+      params = { ... };
+    }
+  );
+}
+```
+
+分类规则：
+
+- `pluginConfig.type == 4` 进入 `dataPlugins`
+- 其它插件进入 `Plugins`
+
+`params` 规则：
+
+- 如果 `pluginConfig.key` 存在于在线配置中，则根据 `pluginParams` 模板生成。
+- `pluginParams` 为 `None` 时写空对象。
+- 不存在对应在线配置时，只写 `name`，不写 `params`。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 登录插件 | 出现在 `TOPSDK.Plugins` |
+| 数据插件 | 出现在 `TOPSDK.dataPlugins` |
+| 插件参数模板 | `params` 被正确替换 |
+| 无在线参数 | 插件仍注册 `name` |
+| 重复执行 | `TOPSDK` 整体被更新，不产生重复插件 |
+
+### 3.13 Apple Sign In Entitlements
+
+旧代码位置：
+
+- `TopSDKTool.py::setupProject`
+- `XcodeManager.py::openSigninWithApple`
+
+旧行为：
+
+1. 如果接入插件名为 `AppleSignin`，则开启 Apple Sign In entitlement。
+2. 如果 target 没有 `CODE_SIGN_ENTITLEMENTS`，创建 `<targetName>/<targetName>.entitlements`。
+3. 对所有 build configurations 设置 `CODE_SIGN_ENTITLEMENTS`。
+4. 在 entitlements plist 中写入：
+
+```plist
+com.apple.developer.applesignin = (Default)
+```
+
+5. 如果没有 AppleSignin 插件，则旧代码会调用 `openSigninWithApple(False)`，移除已有 `com.apple.developer.applesignin`。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| 有 AppleSignin | entitlements 文件存在并包含 applesignin |
+| 原来没有 entitlements | 自动创建并写入 build setting |
+| 原来已有 entitlements | 保留其它 entitlement，只新增 applesignin |
+| 无 AppleSignin | 按迁移设计决定是否保留旧工具“移除 applesignin”的行为；若保留，则断言被移除 |
+
+迁移建议：旧工具在无 AppleSignin 时删除 applesignin，风险较高，可能误删游戏已有能力。迁移时建议改为只管理工具自己添加的能力，或至少在文档/日志中明确提示。
+
+### 3.14 AppDelegate / SceneDelegate 代码注入
+
+旧代码位置：
+
+- `TopSDKTool.py::addCodes`
+- `TopSDKTool.py::setupProject`
+- `XcodeManager.py::findDelegateFile`
+- `XcodeManager.py::findSceneDelegateFile`
+- `CodeUtils.py`
+
+旧行为：
+
+1. 遍历工程目录，查找包含 `UIApplicationDelegate` 的 `.h/.m/.mm`。
+2. 如果命中 `.h`，尝试定位同名 `.m` 或 `.mm`。
+3. 排除固定文件：`Unity_iPhone_Tests.m`、`UnityAppController+ViewHandling.mm`。
+4. 找到 1 个 AppDelegate 实现文件时自动注入。
+5. 找到多个时交互选择。
+6. 找不到时提示用户参考文档手动接入。
+7. SceneDelegate 逻辑类似，查找 `UIWindowSceneDelegate`。
+8. `CodeUtils.addHeader` 将 header 插入文件头部。
+9. `CodeUtils.addCodeToMethod`：
+   - 如果目标方法存在，则在方法 `{` 后插入代码。
+   - 如果 `addToReturn=true`，则把返回语句改写为 SDK 代码参与返回。
+   - 如果目标方法不存在，则在 `@end` 前新增方法。
+   - 插入前会去掉空格检查代码是否已存在，避免重复。
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| AppDelegate 单文件 | header 和方法调用被插入 |
+| AppDelegate 多文件 | 无参数时明确失败或要求指定，不能随机选择 |
+| 无 AppDelegate | 不修改代码，输出明确提示 |
+| SceneDelegate 单文件 | scene delegate code 被插入 |
+| 方法已存在 | 在方法体开头插入代码 |
+| 方法不存在 | 在 `@end` 前新增方法 |
+| `addToReturn=true` 且原来 `return YES;` | 改为返回 SDK 代码 |
+| `addToReturn=true` 且原来 `return xxx;` | 改为 `return (xxx && sdkCode);` |
+| 重复执行 | header 和代码不重复 |
+| Swift AppDelegate | 旧工具不支持；迁移范围需明确是否不支持 |
+
+### 3.15 保存行为
+
+旧代码位置：
+
+- `XcodeManager.py::save`
+- `InfoPlistManager.py::save`
+
+旧行为：
+
+每次 `setPlugin` 后都会保存 `project.pbxproj` 和 Info.plist。最终工程中会落地：
+
+```text
+<project-root>/topSDK/*
+<project>.xcodeproj/project.pbxproj
+<Info.plist>
+<target>.entitlements   # 有 AppleSignin 或需要处理 entitlement 时
+AppDelegate.m/.mm
+SceneDelegate.m/.mm
+```
+
+迁移测试方法：
+
+| 场景 | 断言 |
+|---|---|
+| dry-run | 不写磁盘，只输出预期 diff |
+| apply | 写入上述目标文件 |
+| 中途失败 | 尽量不产生半成品；如不能事务化，错误信息需列出已改文件 |
+
+## 4. 迁移 Golden Output 建议
+
+为了保证迁移不遗漏业务逻辑，建议准备固定输入和 golden output。
+
+### 4.1 固定输入
+
+每个样例工程都应固定：
+
+- `.xcodeproj`
+- target 名
+- Info.plist
+- AppDelegate / SceneDelegate
+- TOPSDK 包资源目录
+- `sdk/*.json`
+- `plugins/*/config.json`
+- mock 的 `getSDKConfig` 响应 JSON
+
+不要在测试中依赖实时后台接口。
+
+### 4.2 样例工程矩阵
+
+| 样例 | 覆盖点 |
+|---|---|
+| `ios-native-minimal` | 单 target、单 Info.plist、无插件或 Guest/UI |
+| `ios-native-login` | Google/Facebook/Apple 登录、URL Scheme、queriesSchemes |
+| `ios-native-payment` | IAP 插件、系统库/framework |
+| `ios-native-data` | AppsFlyer/Firebase/Adjust 等 dataPlugins |
+| `ios-native-multi-target` | 多 target 错误或显式 target 选择 |
+| `ios-native-multi-plist` | Debug/Release 不同 plist |
+| `ios-native-scene` | SceneDelegate 注入 |
+| `ios-native-repeat` | 重复执行幂等性 |
+
+### 4.3 Golden 文件
+
+每个样例至少保存：
+
+```text
+golden/
+  topSDK-file-list.txt
+  project.pbxproj
+  Info.plist.json
+  Entitlements.plist.json
+  AppDelegate.m
+  SceneDelegate.m
+```
+
+plist 建议转成 JSON 后比较，避免二进制 plist 或 key 顺序影响 diff。
+
+### 4.4 断言重点
+
+测试重点不是“函数调用成功”，而是断言输出：
+
+- `topSDK/` 文件列表完全符合预期。
+- `project.pbxproj` 中文件引用、build phase、build settings 正确。
+- Info.plist 中 `TOPSDK`、`CFBundleURLTypes`、`LSApplicationQueriesSchemes` 正确。
+- Entitlements 正确。
+- AppDelegate / SceneDelegate 代码正确且重复执行不重复。
+- 缺少资源、缺少配置、target 不明确时错误信息明确。
+
+## 5. 不迁移清单
+
+以下旧逻辑不迁移到本轮 `meet-sdk-tool`：
+
+| 旧逻辑 | 位置 | 不迁移原因 |
+|---|---|---|
+| Unity target 拆分接入 | `TopSDKTool.py` Unity 分支 | 只支持 iOS 原生工程 |
+| Cocos Creator target 处理 | `TopSDKTool.py` Cocos 分支 | 只支持 iOS 原生工程 |
+| LayaNative 分支 | `TopSDKTool.py` `engineType == layaNative` | 本轮不支持其他引擎 |
+| 引擎桥接资源 `sdkBridge` | `checkEngineSource` / `setupProject` | 非原生引擎能力 |
+| Unity 旧版本 Swift bridging 提示 | Unity 分支 | 非原生引擎能力 |
+| 上传 TOPSDK 资源到下载页 | `upload.py` | 用户明确排除上传 |
+| 更新本地 TOPSDK 资源目录 | `update.py` | 用户明确排除更新 |
+| 开发者本机 `rootPath` 覆盖 | `TopSDKTool.py` `currentEnv != ENV.prod` | 本机硬编码，不应迁移 |
+
+## 6. 迁移完成标准
+
+迁移完成不能只以“命令跑通”为准，应满足：
+
+1. 同一份固定输入下，Python 工具和 `meet-sdk-tool` 的产物等价。
+2. 重复执行不会重复插入 framework、lib、plist、URL Scheme、代码。
+3. 缺少 SDK 包资源时错误信息明确。
+4. 缺少后台配置时错误信息明确，列出缺失配置项。
+5. 多 target、多 delegate 文件时行为确定，不依赖交互式随机选择。
+6. 不触碰 Unity/Cocos/LayaNative 相关逻辑。
+7. 不包含上传和更新能力。
+
+---
+
+## Python 到 TypeScript 对照
+
+This document tracks migration from `topsdk-tool-ios` Python tooling to `meet-sdk-tool`.
+
+## Scope
+
+- Supported host project: iOS `.xcodeproj`.
+- Unsupported in this migration: Python tool branches outside `engineType == "ios"` and SwiftUI-only entry injection.
+- No interactive prompts:
+  - `appId` and `appSecret` come from existing `fetch-config` / `setup` command parameters or environment variables.
+  - `.xcodeproj` can be provided directly as `--project-root`, or auto-detected when `--project-root` points to the iOS project directory.
+  - Target selection is automatic. The current implementation uses the detected primary Xcode target unless recipe args provide `targetName`.
+
+## CLI Contract
+
+```bash
+meetgames setup \
+  --project-root /path/to/ios-project/MyGame.xcodeproj \
+  --app-id <appId> \
+  --app-secret <appSecret> \
+  --channel-type APPLE \
+  --env test
+```
+
+`--project-root` may point to either the iOS project directory or directly to the `.xcodeproj` directory.
+
+## Python-To-TypeScript Mapping
+
+| Python implementation | Behavior | TypeScript implementation |
+|---|---|---|
+| `TopSDKTool.py#setPlugin` | Apply plugin SDK resources and project settings | `src/ios/integrate.ts#applyPlugin` |
+| `PluginConfig.py` | Parse SDK/plugin config JSON | `src/ios/pluginConfig.ts` |
+| `FileManager.py` | Copy SDK files into `topSDK/` | `src/ios/fileManager.ts` |
+| `XcodeManager.py` | Edit `project.pbxproj`, target build phases, build settings | `src/ios/pbxprojEditor.ts` |
+| `InfoPlistManager.py` | Edit `Info.plist`, URL schemes, query schemes | `src/ios/infoPlist.ts` |
+| `CodeUtils.py` | Inject AppDelegate/SceneDelegate snippets | `src/ios/codeUtils.ts` |
+| `ChannelConfigManager.py` | Fetch remote channel config | `src/remote/*`, `src/config/*` |
+
+## Required Behavior Checklist
+
+- [ ] Load SDK core configs from `bundled/ios-sdk/**/sdk/*.json`.
+- [ ] Load enabled plugin configs from `bundled/ios-sdk/**/plugins/*/config.json` or `config.t.json`.
+- [ ] Copy non-system frameworks into host `topSDK/`.
+- [ ] Add non-system frameworks to `project.pbxproj`.
+- [ ] Respect framework `embed`.
+- [ ] Respect framework `copyFile`.
+- [ ] Add system frameworks from SDK/plugin config.
+- [ ] Copy and add non-system libs.
+- [ ] Add system libs.
+- [ ] Copy and add bundle/resource/source entries.
+- [ ] Apply build settings.
+- [ ] Apply `OtherLinkerFlags` idempotently.
+- [ ] Apply `LSApplicationQueriesSchemes` idempotently.
+- [ ] Apply `CFBundleURLTypes` idempotently.
+- [ ] Trim trailing `://` from URL scheme values.
+- [ ] Replace `{$C.xxx.yyy}` channel config placeholders.
+- [ ] Write the `TOPSDK` plist block with `APP_ID`, `Plugins`, and `dataPlugins`.
+- [ ] Enable Apple Sign In entitlements when Apple login is enabled.
+- [ ] Inject AppDelegate snippets idempotently.
+- [ ] Inject SceneDelegate snippets idempotently.
+- [ ] Dry-run reports all text changes and planned binary copies without writing files.
+- [ ] Apply mode is idempotent when run repeatedly on the same project.
+
+## Golden Sample Strategy
+
+Use iOS `.xcodeproj` sample projects only.
+
+1. Run the Python tool with a fixed SDK package and fixed remote config.
+2. Save the resulting files as baseline:
+   - `project.pbxproj`
+   - `Info.plist`
+   - `.entitlements`
+   - `AppDelegate.m` / `.mm`
+   - `SceneDelegate.m` / `.mm`
+   - `topSDK/` file tree
+3. Run `meet-sdk-tool` with the same input.
+4. Compare behavior, not exact UUID ordering in `project.pbxproj`.
+
+## Non-Goals
+
+- Recreate Python interactive target selection.
+- Recreate Python branches for Unity, Cocos, LayaNative, or other game engine exports.
+- Support SwiftUI `@main` App entry injection in this migration.
+
+---
+
+## 差异与缺失备忘
+
+本文记录当前 `meet-sdk-tool` iOS 接入实现与 `topsdk-tool-ios` Python 旧逻辑、[`ios-topsdk-tool-feature-test-plan.md`](./ios-topsdk-tool-feature-test-plan.md) 之间的主要缺失和不一致，后续按条目逐项处理。
+
+## 当前结论
+
+当前 `meet-sdk-tool` 已能跑通 iOS MVP：Core SDK + 部分插件 + `project.pbxproj` + Info.plist + AppDelegate/SceneDelegate 注入。
+
+但它还不是 `topsdk-tool-ios` 的完整等价迁移，现有测试也主要覆盖 Core + GuestSignin，未覆盖完整插件和异常场景。
+
+## 已处理
+
+| 问题 | 处理结果 | 相关位置 |
+|---|---|---|
+| 资源完整性校验缺失 | 已在接入前校验 source/framework/lib，缺失时明确失败，不再静默跳过 | `src/ios/pluginConfig.ts`、`src/ios/integrate.ts` |
+| Apple Sign In entitlements 未实现 | 已在启用 `AppleSignin` 时创建/更新 `.entitlements`，写入 `CODE_SIGN_ENTITLEMENTS` 和 `com.apple.developer.applesignin`；未启用时不删除既有 entitlement | `src/ios/entitlements.ts`、`src/ios/integrate.ts` |
+| `.xcframework` 支持不完整 | 已允许 `.xcframework` 复制并加入 Xcode 工程 | `src/ios/fileManager.ts`、`src/ios/integrate.ts` |
+| `copyFile=true` 未实现 | 已映射到 `PBXCopyFilesBuildPhase` | `src/ios/pbxprojEditor.ts`、`src/ios/integrate.ts` |
+| 插件必需参数校验缺失 | 已按 `requireConfigs` 校验渠道参数，缺少时失败并列出插件名和参数名 | `src/ios/integrate.ts` |
+| `login.apple` 未进入远端配置模型 | 已作为简单登录模块加入配置解析，可启用 iOS `AppleSignin` 插件 | `src/config/meetSdkRemoteConfig.ts`、`src/ios/channelConfig.ts` |
+
+## P0：优先处理
+
+当前没有阻断 iOS 原生迁移的 P0 项。
+
+## P1：行为一致性
+
+| 问题 | 当前表现 | Python 旧逻辑 / 期望 | 相关位置 |
+|---|---|---|---|
+| 插件启用范围不完整 | 只映射 `guest/email/facebook/google/googleIap/apple` | 旧工具读取 `plugins/*/config.json`，按下载包和在线配置接入全部插件 | `src/ios/channelConfig.ts` |
+| Target 选择不一致 | 通过正则取第一个 `PBXNativeTarget` | 过滤测试 target；单 target 自动选，多 target 交互选择 | `src/ios/detect.ts`、旧 `selectTargetAndStartSetting` |
+| 多 AppDelegate/SceneDelegate 处理不一致 | 当前单文件自动注入，多文件 warning 并跳过 | 旧工具单文件自动注入，多文件要求用户选择；后续可增加参数指定路径 | `src/ios/integrate.ts`、旧 `XcodeManager.py::findDelegateFile` |
+| Info.plist 缺失行为不一致 | 找不到时会创建默认 Info.plist | 旧工具找不到 Info.plist 直接失败 | `src/ios/integrate.ts::ensureInfoPlists`、旧 `XcodeManager.py::setTarget` |
+| Swift AppDelegate/SwiftUI 不支持 | 当前只查 `.m/.mm/.h`，SwiftUI 只 warning | 旧工具也不支持 Swift；迁移需明确不支持或新增支持 | `src/ios/codeUtils.ts` |
+
+## P2：需要确认是否保留旧行为
+
+| 问题 | 当前表现 | 风险 / 决策点 | 相关位置 |
+|---|---|---|---|
+| `NSAppTransportSecurity` 自动打开 | 当前会给第一个 plist 写 `NSAllowsArbitraryLoads = true` | Python 主接入流程未显式调用；需确认是否应保留 | `src/ios/integrate.ts`、`src/ios/infoPlist.ts` |
+| 无 AppleSignin 时是否移除 applesignin entitlement | 当前未实现移除 | Python 会调用 `openSigninWithApple(False)`，但可能误删游戏自身能力；建议不要默认删除 | 旧 `XcodeManager.py::openSigninWithApple` |
+| 模板替换行为 | 当前支持多个 `{...}`，缺值替换为空字符串 | Python 只处理第一个 `{$C...}`；当前更强，但需确认是否允许 | `src/ios/template.ts` |
+| `infoParams` 非字符串值 | 类型定义为 `Record<string, string>`，但 plist 写入支持 unknown | 若插件配置有对象/数组值，需要放宽类型并补测试 | `src/ios/types.ts`、`src/ios/infoPlist.ts` |
+
+## 测试缺口
+
+当前已有 iOS 测试：
+
+```text
+tests/pipeline.ios.test.ts
+tests/ios.codeUtils.test.ts
+tests/ios.sdkBundle.test.ts
+```
+
+已验证：
+
+- iOS sample 检测
+- `.xcodeproj` 作为 `--project-root`
+- bundled iOS SDK 根目录解析
+- dry-run 生成 Core + GuestSignin 计划
+- apply 后复制 Core + GuestSignin 并注入 AppDelegate
+- CodeUtils header 去重
+
+缺少测试：
+
+- FacebookSignin + `.xcframework`
+- GoogleSignin + URL Scheme + pluginParams
+- IAPPay + StoreKit
+- `copyFile=true` 独立 fixture
+- 缺 framework/source/lib 失败
+- 多 target
+- Debug/Release 多 Info.plist
+- SceneDelegate 注入
+- 重复执行完整幂等性
+- Swift/SwiftUI 明确不支持提示
+
+## 建议处理顺序
+
+1. 明确 target/delegate 多候选处理策略，非交互命令建议通过参数指定，否则失败。
+2. 补完整 iOS golden sample 和测试矩阵。
+3. 补 FacebookSignin / GoogleSignin / IAPPay 等真实插件组合测试。
+4. 对 `NSAppTransportSecurity`、模板替换增强、Info.plist 缺失时创建默认文件等差异做业务确认。