@leonxin/meetgames 0.1.8 → 0.1.11

package/docs/INTEGRATION.md

@@ -0,0 +1,116 @@
+# SDK 接入说明
+
+本文档说明 `meet-sdk-tool` 当前支持的 Android / iOS 原生工程接入流程。历史迁移资料已归档到 [`archive/`](./archive/)。
+
+## 支持范围
+
+| 平台 | 支持情况 | 说明 |
+|---|---|---|
+| Android 原生工程 | 支持 | Groovy `build.gradle` / `settings.gradle`；不支持 Kotlin DSL `.kts` 自动改写 |
+| iOS 原生工程 | 支持 | `.xcodeproj`；支持传工程目录或 `.xcodeproj` 目录作为 `--project-root` |
+| Unity / Cocos / LayaNative / Unreal | 不支持 | 当前工具只面向原生 Android / iOS 工程 |
+
+## 配置文件
+
+工具使用两类配置和一个版本接口：
+
+| 来源 | 类型 | 作用 |
+|---|---|---|
+| `<project-root>/meetsdk-remote-config.json` | `downloadSDKConfig` 接口拉取后落盘 | 每个游戏/渠道不同的业务参数，例如 `appId`、登录渠道 `clientId/secret/redirect/scheme/name` |
+| `meetsdk-android.json` | 工具内置文件 | Android 固定 SDK 集成配置，例如 SDK 版本、Maven 仓库、依赖坐标、Firebase Gradle plugin |
+| `meetsdk-ios.json` | 工具内置文件 | iOS 固定 SDK 集成配置，例如当前 bundled SDK 版本、发布日期、包类型、插件组合 |
+| `GET https://business-api.meetgames.com/sdk/home/version` | sdk-home 接口 | Android 接入/检查时读取 `data.result.android.ver` 并写入 `meetsdk-android.json`；iOS 下载时读取 `data.result.ios.ver` 并写入 `meetsdk-ios.json` |
+
+`meetsdk-remote-config.json` 由 `fetch-config`、`setup`、`doctor` 拉取并原样写入工程根目录。  
+`integrate` 读取本地配置并执行接入；Android 接入会额外请求 sdk-home 版本接口获取最新 SDK 版本，并同步写回 `meetsdk-android.json`，不会重新拉取 `meetsdk-remote-config.json`。
+
+## 推荐流程
+
+### 一步接入
+
+```bash
+node dist/entry.js setup \
+  --app-id <APP_ID> \
+  --app-secret '<APP_SECRET>' \
+  --channel-type GOOGLE \
+  --project-root /path/to/project \
+  --env test \
+  --verbose
+```
+
+### 接入后校验
+
+```bash
+node dist/entry.js doctor \
+  --app-id <APP_ID> \
+  --app-secret '<APP_SECRET>' \
+  --channel-type GOOGLE \
+  --project-root /path/to/project \
+  --env test \
+  --verbose
+```
+
+`doctor` 会先重新拉取远程配置，再根据当前工程类型执行 Android 或 iOS 的详细校验。
+
+## 本地 console 联调
+
+如果本地启动了 gp-sdk console：
+
+```bash
+TOPSDK_API_BASE_URL=http://127.0.0.1:8081/ \
+node dist/entry.js setup \
+  --app-id 791251136341225472 \
+  --app-secret 'YOUR_APP_SECRET' \
+  --channel-type APPLE \
+  --project-root ./fixtures/ios-test-project/tooltest \
+  --env test \
+  --verbose
+```
+
+`TOPSDK_API_BASE_URL` 会覆盖 `--env` 对应的默认域名。
+
+## Android 接入内容
+
+Android 接入时会根据 `meetsdk-remote-config.json` 和内置默认配置检查/写入：
+
+- Application module 默认自动检测；如果工程存在多个 application module，需要通过 `--app-target <module>` 指定，例如 `:app` 或 `launcher`。
+- sdk-home `version` 接口中的 `data.result.android.ver` / `date`，用于更新 `meetsdk-android.json` 并生成 App Module `build.gradle` 里的 `topsdk_version`。
+- `settings.gradle` 或根 `build.gradle` 中的 Maven 仓库。
+- 根 `build.gradle` 中的 Gradle plugin 声明，例如 Firebase google-services。
+- App Module `build.gradle` 中的 SDK 依赖。
+- App Module `defaultConfig` 中的 `resValue` 参数。
+- `google-services.json` 下载和落盘。
+- 默认 recipe 中声明的其他资源拷贝。
+
+`doctor` 会校验仓库、依赖、`resValue`、Firebase 文件等是否已正确接入。
+
+## iOS 接入内容
+
+iOS 接入时会根据 bundled iOS SDK 中的 `config.t.json` 执行：
+
+- 复制 framework / xcframework / bundle / lib / source 到 `topSDK/`。
+- 启用 Firebase 时，从 `meetsdk-remote-config.json` 中的 `sdkModules.analytics.firebase.firebaseUrl` 下载 `GoogleService-Info.plist` 到和 `Info.plist` 同级的 App target 目录，不要求 bundled SDK 内置该 plist。
+- 修改 `.xcodeproj/project.pbxproj`，加入 framework、资源、系统库、build settings、copy files 等配置。
+- 修改 `Info.plist`，写入 `TOPSDK`、三方 SDK 参数、URL Scheme、Queries Schemes。
+- 启用 Apple Sign In 时创建/更新 entitlements。
+- 注入 Objective-C `AppDelegate` / `SceneDelegate` 回调代码：启动初始化保留在 `AppDelegate`；存在唯一 `SceneDelegate` 时，URL、Universal Link、前后台回调写入 `SceneDelegate`。
+
+`doctor` 会校验 SDK 文件、Xcode 引用、`GoogleService-Info.plist`、`Info.plist` 参数、插件参数、URL Scheme 是否按配置写入，以及 Delegate 注入是否完整。
+
+`meetsdk-ios.json` 由 `download-ios-sdk` 更新，用于记录当前工具包内 `bundled/ios-sdk` 对应的 SDK 版本信息。iOS 接入的具体文件复制和参数模板仍以 bundled SDK 内的 `sdk/`、`plugins/` 配置为准。
+
+## iOS 插件模板字段
+
+iOS bundled SDK 插件中的 `config.t.json` 是接入规则来源：
+
+| 字段 | 作用 |
+|---|---|
+| `requireConfigs` | 声明插件必需的远程配置字段，缺失时接入/doctor 失败 |
+| `pluginParams` | 写入 `Info.plist -> TOPSDK -> Plugins -> params` |
+| `infoParams` | 写入 `Info.plist` 顶层字段，供三方 SDK 读取 |
+| `urlScheme` | 写入 `Info.plist -> CFBundleURLTypes -> CFBundleURLSchemes` |
+| `queriesSchemes` | 写入 `Info.plist -> LSApplicationQueriesSchemes` |
+| `frameworks` / `libs` / `sources` | 声明需要复制并加入 Xcode 工程的资源 |
+| `appDelegateCodes` / `sceneDelegateCodes` | 声明要注入 Delegate 的代码片段 |
+
+例如 `"{$C.FACEBOOK.scheme}"` 表示从远程配置 `sdkModules.login.facebook.scheme` 构建出的 `C.FACEBOOK.scheme` 取值。

package/docs/MCP.md

@@ -0,0 +1,86 @@
+# MCP 使用说明
+
+本文档说明 `meet-sdk-tool` 的 MCP server 及 Cursor 配置方式。
+
+## 构建
+
+```bash
+cd /Users/work/Workspace/Projects/meet-sdk-tool
+npm run build
+```
+
+## 启动 MCP server
+
+```bash
+npm run mcp:stdio
+```
+
+或直接：
+
+```bash
+node dist/mcp-entry.js
+```
+
+## 暴露工具
+
+| MCP 工具 | 作用 |
+|---|---|
+| `meetgames_doctor` | 拉取配置并检查 Android / iOS 接入是否正确 |
+| `meetgames_fetch_config` | 调用 `downloadSDKConfig` 并写入 `meetsdk-remote-config.json` |
+| `meetgames_integrate_dry_run` | 只生成接入预览，不写工程文件 |
+| `meetgames_integrate_apply` | 执行接入并写工程文件 |
+| `meetgames_setup` | 先 fetch-config，再 integrate |
+
+所有 integrate 类工具都使用内置 recipe：
+
+```text
+recipes/integrate-default.yaml
+```
+
+与 CLI 一样，多入口工程可显式指定目标：
+
+| 参数 | 适用平台 | 说明 |
+|---|---|---|
+| `appTarget` | Android / iOS | 统一指定要接入/检查的 App 目标；Android 传 application module（如 `:app` / `app`），iOS 传 App target 名 |
+
+传入 `appTarget` 时会校验目标是否存在：Android 校验目标 application module，iOS 校验目标 App target。
+
+## 推荐调用顺序
+
+一次性接入：
+
+```text
+meetgames_setup(dryRun=false)
+meetgames_doctor()
+```
+
+需要先审查 diff：
+
+```text
+meetgames_fetch_config()
+meetgames_integrate_dry_run()
+meetgames_integrate_apply()
+meetgames_doctor()
+```
+
+## Cursor 配置
+
+将 `.cursor/mcp.example.json` 中的 server 配置复制到 Cursor MCP 配置中。
+
+推荐本地开发配置：
+
+```json
+{
+  "mcpServers": {
+    "meetgames-mcp-local-node": {
+      "command": "node",
+      "args": [
+        "/Users/work/Workspace/Projects/meet-sdk-tool/dist/mcp-entry.js"
+      ],
+      "cwd": "/Users/work/Workspace/Projects/meet-sdk-tool"
+    }
+  }
+}
+```
+
+如果已经全局安装 npm 包，也可以使用全局 bin 方式；开发阶段建议使用本地 `dist/mcp-entry.js`，避免版本不一致。

package/docs/README.md

@@ -1,12 +1,21 @@
 # meet-sdk-tool 文档索引
 
-| 文档 | 类型 | 说明 |
-|------|------|------|
-| [需求文档.md](./需求文档.md) | 产品需求（PRD） v1.0 | 目标、四大功能、MG/服务端配套、验收与里程碑 |
-| [技术方案调研.md](./技术方案调研.md) | 技术调研 v1.2 | Gradle：现阶段正则，规划 Groovy AST only（不支持 `.kts`） |
-| [ANDROID.md](./ANDROID.md) | 使用说明 | Android 集成、CLI 参数、Gradle 行为 |
-| [API.md](./API.md) | 接口索引 | `downloadSDKConfig` 等 HTTP 接口 |
-| [MCP-SKILL.md](./MCP-SKILL.md) | 运维 / Agent | MCP 工具与推荐调用顺序 |
-| [CURSOR-MCP-SETUP.md](./CURSOR-MCP-SETUP.md) | 环境 | Cursor MCP 配置 |
-
-实现细节以仓库代码为准；PRD 中标注 **【待补充】** 的条目需产品 / 业务方确认后定稿。
+当前日常使用只需要优先查看根目录下的文档：
+
+| 文档 | 用途 |
+|---|---|
+| [CLI.md](./CLI.md) | `meetgames` 命令、参数、环境变量和退出码 |
+| [INTEGRATION.md](./INTEGRATION.md) | Android / iOS SDK 自动接入流程、doctor 校验内容、发版前测试方式 |
+| [API.md](./API.md) | `downloadSDKConfig` 接口、签名、落盘 JSON 结构 |
+| [MCP.md](./MCP.md) | MCP server、Cursor 配置和 Agent 调用顺序 |
+| [AAB_CONVERTER_CLI_PLAN.md](./AAB_CONVERTER_CLI_PLAN.md) | AAB 转 APK 命令行绿色版工具方案 |
+
+历史资料已归档到 [`archive/`](./archive/)：
+
+| 目录 / 文件 | 内容 |
+|---|---|
+| [archive/ios-migration.md](./archive/ios-migration.md) | iOS Python 工具迁移到 TypeScript 的完整历史记录 |
+| [archive/api/](./archive/api/) | 旧接口、对照接口和旧版详细接口文档 |
+| [archive/product/](./archive/product/) | PRD、技术调研等过程文档 |
+
+实现细节以代码为准；如果文档和代码不一致，以 `src/cli.ts`、`src/core/doctor.ts`、`src/ios/`、`src/android/` 当前实现为准。

package/docs/{api → archive/api}/downloadSDKConfig.md

@@ -48,15 +48,17 @@ meetgames fetch-config --app-id 791251136341225472 --app-secret YOUR_APP_SECRET
 | `channel` | `channel.channel_type` | 枚举名如 `GOOGLE` / `APPLE` |
 | `devicePlatform` | `channel.device_platform` | 小写，如 `android` / `ios` |
 | `topsdk.appId` / `topsdk.appSecret` | `app` | |
-| `sdkModules.login.*` | `channel_auth`（`enable=true`） | 各登录渠道凭证 |
+| `sdkModules.login.*` | `channel_auth` | key 直接使用 `authType` 小写，如 `guest` / `email` / `google` / `snapchat`；参数使用 `DTOChannelAuth` 字段名 |
 | `sdkModules.payment.*` | `channel_payment` + 部分 `channel_auth` | IAP 平台 |
-| `sdkModules.analytics.*` | `channel_third_data_platform` | AppsFlyer / Firebase / Adjust |
-| `sdkModules.analytics.firebase.firebase_file_url` | `channel_third_data_platform.firebase_url` | MG 经 **uploadV2** 上传后多为 OSS **objectKey**；组装 JSON 时经 `AliYunOssUtil.getOssUr` 生成下载链接（与 `downLoadXml` 一致）。若库内为 http(s) URL 则 `getFileUrl` 换签 |
-| `sdkModules.analytics.firebase.firebase_file_name` | `channel_third_data_platform.firebase_name` | 上传原始文件名（含后缀）；落盘路径由 meet-sdk-tool 按工程 **app module** 检测 |
+| `sdkModules.analytics.*` | `channel_third_data_platform` | AppsFlyer / Firebase / Adjust；参数使用 `ChannelThirdDataPlatform` 字段名 |
+| `sdkModules.analytics.firebase.firebaseUrl` | `channel_third_data_platform.firebase_url` | MG 经 **uploadV2** 上传后多为 OSS **objectKey**；组装 JSON 时经 `AliYunOssUtil.getOssUr` 生成下载链接（与 `downLoadXml` 一致）。若库内为 http(s) URL 则 `getFileUrl` 换签 |
+| `sdkModules.analytics.firebase.firebaseName` | `channel_third_data_platform.firebase_name` | 上传原始文件名（含后缀）；落盘路径由 meet-sdk-tool 按检测到或通过 `--app-target` 指定的工程 **app module** 决定 |
 
 详见 gp-sdk `SdkConfigDownloadServiceImpl`；**不包含** `topsdk.version`（integrate 时用 `meetsdk-android.json` 兜底）。
 
-**子模块写入**：只要库表里有对应配置参数即写入子键，value 为对象（或 `{}`）；无配置**不写该键**（不出现 `false`）。**不**再根据 `channel_auth.enable` / `channel_payment.enable` 过滤。`analytics.facebookdata` 等独立开关字段预留，待 meetgames-business 配置后再接。
+**子模块写入**：只要库表里有对应配置参数即写入子键，value 为对象（或 `{}`）；无配置**不写该键**（不出现 `false`）。插件对象内只写有值字段，不写空字符串占位。`channel_auth` 输出字段为 `clientId` / `secret` / `redirect` / `scheme` / `name`；`channel_third_data_platform` 输出字段保持 `devKey` / `appleAppId` / `firebaseUrl` / `firebaseName` / `appCode` 等实体字段名。**不**再根据 `channel_auth.enable` / `channel_payment.enable` 过滤。`analytics.facebookdata` 等独立开关字段预留，待 meetgames-business 配置后再接。
+
+`meet-sdk-tool` 按上述 DTO/entity 原字段名读取配置；旧字段名不再作为兼容输入。
 
 **meet-sdk-tool integrate**：仅当 JSON 里写了对应子键时接入（如 `login.kakao`、`analytics.appsflyer`）；有键则 value 必为 `{…}`。
 
@@ -83,7 +85,7 @@ JSON Schema：[`schema/meetsdk-remote-config.schema.json`](../../schema/meetsdk-
 ### 响应体样例
 
 仓库内测试用 mock：[`fixtures/meetsdk-remote-config.mock.json`](../../fixtures/meetsdk-remote-config.mock.json)  
-Vitest 样例工程：[`test-projects/android-latest-project/meetsdk-remote-config.json`](../../test-projects/android-latest-project/meetsdk-remote-config.json)（联调后可能被覆盖）
+Vitest 样例工程：[`fixtures/android-test-project/android-latest-project/meetsdk-remote-config.json`](../../../fixtures/android-test-project/android-latest-project/meetsdk-remote-config.json)（联调后可能被覆盖）
 
 ## 与 getChannelConfig 的区别
 

package/docs/{api → archive/api}/getChannelConfig-meetgames.md

@@ -90,7 +90,7 @@ GET https://test-business-api.meetgames.com/customer/topsdk/console/meetgames/ch
 | `appId` | `topsdk.appId`（secret 在 `app` 表，此接口 result 未必带出） |
 | `authConfigs[]`（`enable`） | `sdkModules.login.*` |
 | `thirdDataPlatform.devKey` | `sdkModules.analytics.appsflyer` 等 |
-| `thirdDataPlatform.firebaseUrl` | Firebase / `firebase_file_url` 类字段 |
+| `thirdDataPlatform.firebaseUrl` | Firebase / `firebaseUrl` 字段 |
 | `parameterConfig` | 支付 / Google Play 服务账号等，与 `channel_payment`、parameter 表相关 |
 
 完整 Gradle 集成仍依赖工具侧 [`meetsdk-android.json`](../../meetsdk-android.json) 合并版本与依赖。