@leonxin/meetgames 0.1.0

package/docs//346/212/200/346/234/257/346/226/271/346/241/210/350/260/203/347/240/224.md

@@ -0,0 +1,329 @@
+# meet-sdk-tool 技术方案调研
+
+| 项 | 内容 |
+|----|------|
+| 文档版本 | v1.2 |
+| 产品目标 | 优化 SDK 接入流程，减少 CP 步骤，提高接入效率 |
+| 关联 PRD | [需求文档.md](./需求文档.md) |
+
+---
+
+## 1. 调研结论
+
+| 决策项 | 结论 |
+|--------|------|
+| 开发语言 | **TypeScript**（Node >= 18） |
+| Gradle 编辑（现阶段） | **Groovy DSL**（`build.gradle`）：正则 + `{`/`}` 括号匹配 + `// >>> TOPSDK` 标记块 upsert |
+| Gradle 编辑（规划） | **仅 Groovy DSL** 改用 AST 改写；**明确不支持** `build.gradle.kts`（Kotlin DSL） |
+| 游戏源码诊断（规划） | Java / Kotlin / ObjC AST（与 Gradle 解析栈分离） |
+| 配置来源 | gp-sdk 新接口 **`GET console/openSDK/downloadSDKConfig`**（唯一拉参入口） |
+| 配置形态 | 工程根 `meetsdk-remote-config.json` + 工具内置 `meetsdk-android.json` |
+| 交付形态 | **CLI** + **MCP**（Cursor MVP） |
+| 宿主 | **仅纯原生**；不支持 Unity / Unreal；**支持 CI 流水线** |
+
+---
+
+## 2. 业务目标与技术映射
+
+```mermaid
+flowchart TB
+  subgraph goals [产品能力]
+    P1[参数自动配置]
+    P2[SDK 自动导入]
+    P3[接口调用诊断]
+    P4[接入客服]
+  end
+  subgraph tool [meet-sdk-tool 当前]
+    FC[fetch-config]
+    IG[integrate / setup]
+    DR[doctor 环境探测]
+    MCP[MCP tools]
+  end
+  subgraph backlog [规划]
+    GAST[Groovy Gradle AST 编辑]
+    SAST[游戏源码 AST 诊断]
+    FAQ[文档问答 Agent]
+    PH[Manifest placeholders]
+  end
+  P1 --> FC --> IG
+  P2 --> IG
+  P3 -.-> SAST
+  P2 -.-> GAST
+  P4 -.-> FAQ
+  P1 -.-> PH
+  MCP --> FC
+  MCP --> IG
+```
+
+| 产品功能 | 技术实现 | 状态 |
+|----------|----------|------|
+| 接口拉参 + 自动写入 Gradle | `downloadSDKConfig` → `meetSdkRemoteGradle` resValue/依赖 upsert | ✅ |
+| 按后台版本/模块导入 SDK | `meetsdk-android.json` merge + `topsdkFeatureModules` | ✅ |
+| 接口调用诊断 | 游戏源码 AST 扫描调用点与签名 | ⏳ |
+| Gradle AST 编辑（仅 Groovy） | 替代 `findBlockRange` + 行级正则 upsert | ⏳ |
+| 接入客服 | RAG + FAQ / SDK 文档 | ⏳ |
+| CI 无人值守接入 | 非交互 CLI `setup` | ✅ |
+
+---
+
+## 3. 方案对比
+
+### 3.1 Gradle 编辑：现阶段正则 vs 规划 Groovy AST
+
+**范围约定**：集成目标文件为 **Groovy DSL** 的 `build.gradle`（及根工程 `settings.gradle` 等 Groovy 脚本中的约定块）。**不支持** `build.gradle.kts`；若工程仅为 Kotlin DSL，`integrate` 应失败并提示改用 Groovy 或人工接入。
+
+| 方案 | 优点 | 缺点 | 结论 |
+|------|------|------|------|
+| **正则 + 括号匹配 + 标记块（现阶段）** | 实现快、纯 TS、已上线、可 dry-run、Vitest 好测 | 非 Groovy 语义；极端脚本可能误匹配 | **当前采用**（`src/android/gradle.ts`、`meetSdkRemoteGradle.ts`） |
+| **Groovy AST（规划）** | 准确定位 `defaultConfig`、`dependencies` 内 `resValue`/`implementation` 等调用 | 需引入 Groovy 解析（Tree-sitter-groovy 或 JVM Groovy AST）；改完需处理格式化 | **M4+ 仅 Groovy**，替代块定位与行级 upsert |
+| Kotlin DSL AST | 覆盖 `.kts` 工程 | 与 Groovy 两套栈；当前产品**明确不做** | **不采用** |
+| 全量模板覆盖 build.gradle | 简单 | 破坏 CP 自定义片段 | 不采用 |
+
+PRD「AST 替代正则」指 **后续 Groovy Gradle 编辑** 与 **游戏源码接口诊断**；现阶段以正则方案交付，幂等语义仍保留 `// >>> TOPSDK … START/END` 标记块（AST 阶段可改为「按语义键合并 AST 节点」）。
+
+### 3.2 配置拉取接口
+
+| 接口 | 路径 | 鉴权 | 返回 | 工具 |
+|------|------|------|------|------|
+| 老接口 | `GET /openSDK/getSDKConfig` | sign + timestamp | `channelAuthConfig` 片段 | 库内保留映射，CLI 不用 |
+| **新接口（采用）** | `GET /console/openSDK/downloadSDKConfig` | 仅 `appId` + `channelType` | 完整 `meetsdk-remote-config.json` | **`fetch-config`** |
+| 老接口 | `GET /openSDK/getSDKConfig` | sign | `channelAuthConfig` 片段 | 不用于 CLI 拉参 |
+
+JSON 内渠道字段：**根级 `channel` only**（无 `channelType`、无 `topsdk.channel`）。
+
+MG 后台另需：三方配置文件 OSS **原文件**存取、SDK 版本配置（与 `meetsdk-android.json` 合并），不另设与 `downloadSDKConfig` 并列的拉参 URL。
+
+### 3.3 与旧工具关系
+
+| 工具 | 配置方式 | Gradle | iOS |
+|------|----------|--------|-----|
+| topsdk-tool-ios (Python) | getSDKConfig + sign | 弱 | 强 |
+| sdk-integration-agent | 本地 JSON | 强（类似现工具） | - |
+| **meet-sdk-tool** | downloadSDKConfig | 强 + MCP | 已实现 integrate |
+
+---
+
+## 4. 系统架构
+
+```mermaid
+flowchart LR
+  MG[MG 后台]
+  GP[gp-sdk console]
+  OSS[三方文件 OSS]
+  CLI[meetgames CLI]
+  JSON[meetsdk-remote-config.json]
+  DEF[meetsdk-android.json]
+  APP[原生宿主工程]
+
+  MG -->|渠道配置| GP
+  MG -->|原文件| OSS
+  CLI -->|GET console/openSDK/downloadSDKConfig| GP
+  GP --> JSON
+  OSS -.->|URL 写入 JSON| JSON
+  CLI --> DEF
+  JSON --> CLI
+  DEF --> CLI
+  CLI -->|recipe ops| APP
+```
+
+### 4.1 模块职责（meet-sdk-tool）
+
+| 模块 | 职责 |
+|------|------|
+| `src/remote/topsdkDownloadSdkConfig.ts` | 拉取远程 JSON |
+| `src/config/meetSdkRemoteConfig.ts` | 解析、校验、合并默认配置 |
+| `src/android/meetSdkRemoteGradle.ts` | 仓库 / 依赖 / resValue / applicationId |
+| `src/ios/*` | Xcode 工程、SDK 拷贝、AppDelegate |
+| `src/core/pipeline.ts` | recipe 执行、dry-run、patch |
+| `src/mcp/*` | Agent 入口 |
+| `recipes/integrate-default.yaml` | 默认集成步骤 |
+
+### 4.2 配置文件分工
+
+| 文件 | 内容 | 谁维护 |
+|------|------|--------|
+| `meetsdk-remote-config.json` | 每游戏/渠道：包名、channel、devicePlatform、appId/secret、各模块凭证 | MG / gp-sdk 下载 |
+| `meetsdk-android.json` | SDK 版本、Maven 仓库、各模块固定 `dependencies`、Firebase classpath | 工具发版随包更新，版本号对齐 MG |
+
+### 4.3 JSON 字段（与 PRD 对齐）
+
+根级 **`channel`**（如 `GOOGLE`），**不再**使用根级 `channelType` 或 `topsdk.channel`。
+
+`downloadSDKConfig` 服务端（`SdkConfigDownloadServiceImpl`）：
+
+- `channel_auth` 仅 `enable=true` 写入参数；  
+- `channel_payment` 仅 `enable=true` 开启 IAP 模块；  
+- 输出 `devicePlatform`（小写 `android` / `ios`）。
+
+---
+
+## 5. Gradle 集成行为（参数 + SDK）
+
+**脚本类型**：仅 **Groovy DSL**（`*.gradle`）。实现见 `src/android/gradle.ts`（`findBlockRange`、`replaceOrInsertManaged`）与 `src/android/meetSdkRemoteGradle.ts`。
+
+### 5.1 参数配置（resValue）
+
+工具在 App Module `defaultConfig` 中写入（模块开启时），例如：
+
+| resValue 键 | 来源 |
+|-------------|------|
+| `top_channel_id` | 根级 `channel` |
+| `top_app_id` | `topsdk.appId` |
+| `facebook_app_id` 等 | `sdkModules.login.*` |
+| `af_dev_key` | `sdkModules.analytics.appsflyer` |
+
+**差异**：PRD 中 Snapchat 的 `addManifestPlaceholders([...])` **尚未实现**，仅写入 `snapchat_client_id` 等 resValue。
+
+### 5.2 SDK 导入
+
+- **根工程**：`allprojects.repositories` 或 `settings.gradle` / `dependencyResolutionManagement`（按工程结构探测）。  
+- **App 模块**：`def topsdk_version` / `def groupId`、`implementation "$groupId:ui:..."` 及可选模块。  
+- **去重**：`groupId:artifact` 为键，已存在则更新版本，不重复插入。
+
+### 5.3 Firebase
+
+- `firebase_file_url` 在 analytics.firebase 对象中；  
+- 集成时拉取或引用 URL（具体拷贝逻辑见 recipe / firebase 相关 op）。
+
+---
+
+## 6. Gradle 编辑技术路线（正则 → Groovy AST）
+
+### 6.1 阶段性决策（已确认）
+
+| 阶段 | Gradle 集成 | Kotlin DSL |
+|------|-------------|------------|
+| **现阶段** | 正则 + `{`/`}` 深度匹配 + TOPSDK 标记块 + 行级键 upsert | **不支持**，不检测、不修改 `.kts` |
+| **将来** | **Groovy AST** 定位并改写 `build.gradle` 等 | **仍不支持** |
+
+### 6.2 现阶段实现（正则，非 AST）
+
+| 机制 | 作用 |
+|------|------|
+| `findBlockRange(keyword)` | 正则 `\bkeyword\s*\{` + 括号深度，得到 `android` / `defaultConfig` / `dependencies` 范围 |
+| `replaceOrInsertManaged` | 在块内查找 `// >>> TOPSDK … START/END`，有则替换，无则在块尾插入 |
+| 行级正则 | `resValue` 第二参数名、`implementation` 的 `group:artifact` 等去重 |
+| `mergeResValuesInDefaultConfigBlock` 等 | 先删同键旧行，再写新标记块 |
+
+优点：纯 TypeScript、与 sdk-integration-agent 一致、可 dry-run、单测覆盖。  
+缺点：不理解 Groovy 表达式；非常规嵌套或 `.kts` 工程不适用。
+
+### 6.3 规划：Groovy AST（仅 Groovy DSL）
+
+候选实现路径（选型待定）：
+
+- **Tree-sitter-groovy**（Node）：轻量，适合「找闭包 + 方法调用」；  
+- **Groovy AstBuilder**（JVM 子进程）：语义完整，适合复杂改写。
+
+迁移原则：
+
+1. 对外行为不变：仍输出相同 `resValue` / `implementation` / 仓库行，仍支持 TOPSDK 标记块或等价幂等；  
+2. **不**为 `build.gradle.kts` 增加解析器；`doctor` / `integrate` 可对 `.kts` 给出明确「仅支持 Groovy DSL」提示；  
+3. 游戏 **Java/Kotlin 源码** 的接口诊断使用独立 AST 管线，不与 Gradle Groovy 解析强绑定。
+
+### 6.4 什么是 AST（与正则对比）
+
+**AST（Abstract Syntax Tree）** 把源码解析成语法树再查询/改写，而不是整文件当字符串匹配。
+
+| 维度 | 现阶段（正则 + 标记块） | 规划（Groovy AST） |
+|------|-------------------------|---------------------|
+| 找 `defaultConfig` | `defaultConfig\s*\{` + 括号计数 | 按 Groovy `BlockStatement` / 闭包节点 |
+| 改一条 `resValue` | 按资源名删行 + 插入标记块 | 改 `MethodCallExpression` 或增删语句节点 |
+| `build.gradle.kts` | 不处理 | **仍不处理** |
+| 接口诊断（游戏代码） | 不适用 | Java/Kotlin/ObjC AST（**另一子项目**） |
+
+### 6.5 游戏源码 AST 诊断（规划，非 Gradle）
+
+1. 解析宿主 **Java / Kotlin / ObjC** 源码；  
+2. 匹配 TOPSDK 公开 API；  
+3. 校验参数个数、类型等 **【规则集待 SDK 团队提供】**。
+
+与 Gradle Groovy AST **分开排期**，可先做诊断、后做 Gradle AST 迁移。
+
+---
+
+## 7. 使用方式
+
+### 7.1 CLI
+
+```bash
+meetgames fetch-config --project-root <原生工程根> \
+  --app-id <APP_ID> --channel-type GOOGLE --env test
+
+meetgames setup --project-root <原生工程根> \
+  --app-id <APP_ID> --channel-type GOOGLE
+```
+
+| 说明 | |
+|------|--|
+| `channel-type` | 商店渠道枚举，对应 HTTP 参数 `channelType` |
+| `app-secret` | **不必**在 fetch-config 传入；由 `downloadSDKConfig` 响应写入 JSON |
+| CI | 设置 `TOPSDK_APP_ID`、`TOPSDK_CHANNEL_TYPE` 或依赖已提交的 JSON 缓存 |
+
+### 7.2 MCP（MVP）
+
+| 工具 | 作用 |
+|------|------|
+| `meetgames_setup` | fetch + integrate |
+| `meetgames_fetch_config` | 仅拉 JSON |
+| `meetgames_integrate_*` | 仅改工程 |
+| `meetgames_doctor` | 工程类型探测 |
+
+---
+
+## 8. MG 后台与服务端改造要点
+
+| 项 | 技术要点 |
+|----|----------|
+| 渠道配置下载 | 与 `downloadSDKConfig` 字节流一致，避免前端再拼 JSON |
+| 三方文件 | 对象存储原文件 + 下载 URL 写入 JSON（如 `firebase_file_url`） |
+| SDK 版本 | 后台配置 → 下发或随工具 `meetsdk-android.json` 同步策略 **【待与发版流程对齐】** |
+| 后台改 JSON 字段 | 与工具约定根级 `channel`，避免回退 `topsdk.channel` |
+
+---
+
+## 9. 风险与缓解
+
+| 风险 | 缓解 |
+|------|------|
+| 测试环境未部署 `downloadSDKConfig` | 本机 gp-sdk；推动 test/pre 部署 |
+| Gradle 仅为 `.kts` | 文档与 `doctor` 声明仅 Groovy；integrate 失败并提示 |
+| Groovy AST 排期晚于正则上线 | 先正则交付；AST 仅 Groovy，不扩 Kotlin DSL |
+| Unity/Unreal 误用 | 文档与 `doctor` 明确仅原生；CI 模板校验工程结构 |
+| `appSecret` 进 git | PR 扫描 + 文档；CI 密钥注入 |
+| 环境未部署 `downloadSDKConfig` | 推动 test/pre/prod 部署；本机 gp-sdk console 联调 |
+
+---
+
+## 10. 测试与 CI
+
+| 层级 | 内容 |
+|------|------|
+| 单元 | Gradle upsert、JSON 解析、Manifest |
+| 集成 | `test-projects/android-sample`、`pipeline.*.test.ts` |
+| CI 建议 | `npm ci && npm test && meetgames setup --dry-run`（需 secrets 与 API 可用） |
+
+**宿主限制**：流水线仅针对标准 Android **Groovy** Gradle / Xcode 原生工程；**不支持** `build.gradle.kts`；Unity / Unreal 不在支持矩阵内。
+
+---
+
+## 11. 演进路线
+
+| 优先级 | 项 |
+|--------|-----|
+| P0 | 全环境部署 `downloadSDKConfig`；MG 下载按钮与文件存取 |
+| P0 | CI 模板（GitHub Actions / 内部 Jenkins） |
+| P1 | Snapchat `addManifestPlaceholders` |
+| P1 | 三方配置文件 OSS 原文件 + JSON 内 URL 字段稳定 |
+| P2 | 游戏源码 AST 接口调用诊断 |
+| P3 | **Groovy AST** 替代 Gradle 正则编辑（不支持 Kotlin DSL） |
+| P3 | FAQ / 接入客服 Agent |
+
+---
+
+## 12. 参考
+
+- [ANDROID.md](./ANDROID.md) — CLI 与 Gradle 细节  
+- [API.md](./API.md) — HTTP 接口索引  
+- [MCP-SKILL.md](./MCP-SKILL.md) — Agent 调用顺序  
+- gp-sdk：`SdkConfigDownloadServiceImpl.java`

package/docs//351/234/200/346/261/202/346/226/207/346/241/243.md

@@ -0,0 +1,320 @@
+# meet-sdk-tool 需求文档（PRD）
+
+| 项 | 内容 |
+|----|------|
+| 文档版本 | v1.2 |
+| 产品名称 | meet-sdk-tool / `meetgames` CLI |
+| 关联方案 | [技术方案调研.md](./技术方案调研.md) |
+
+---
+
+## 1. 产品目标
+
+**优化 SDK 接入流程、减少 CP（游戏研发）操作步骤、提高 SDK 接入效率。**
+
+| 维度 | 传统方式 | 目标方式 |
+|------|----------|----------|
+| 参数配置 | 发行方提供参数文档，研发手工写入工程 | 接口拉取参数，工具自动写入合适位置，**游戏研发无需参与** |
+| SDK 导入 | 手工下载 SDK 或配置仓库与依赖 | 按 MG 后台版本配置自动导入，研发**无需**添加仓库、判断模块与版本 |
+| 问题排查 | 联调阶段才发现调用位置/传参错误 | 工具诊断调用位置、参数个数与类型（规划） |
+| 支持 | 查文档、群里提问 | FAQ / SDK 文档 + 联网问答（规划，MVP 后） |
+
+**宿主范围（已确认）**：仅**纯原生** Android / iOS 工程；**不支持** Unity、Unreal 等引擎导出工程。可在 **CI 流水线**中执行 `meetgames setup` / `fetch-config` + `integrate`。
+
+---
+
+## 2. 功能需求
+
+### 2.1 参数配置（P0 — 已实现主体）
+
+#### 传统方式
+
+发行方提供参数文档 → 研发在 App Module 的 `build.gradle` 等位置手工添加，例如：
+
+```gradle
+// channel（渠道标识）
+resValue('string', 'top_channel_id', 'GOOGLE')
+// topsdk
+resValue('string', 'top_app_id', '768172181700891686')
+// facebook
+resValue('string', 'facebook_app_id', '1759420478385706')
+resValue('string', 'fb_login_protocol_scheme', 'fb1759420478385706')
+resValue('string', 'facebook_client_token', 'b688f17167a5d198adae2d6d090d11f9')
+// snapchat
+resValue('string', 'snapchat_client_id', 'd485fabe-dda2-42d6-93f0-3a480a9c342f')
+addManifestPlaceholders([
+  snapchat_scheme: "https",
+  snapchat_host: "wxa-1256944748.cos.ap-nanjing.myqcloud.com",
+  snapchat_path: "html/snapchat-callback.html"
+])
+```
+
+#### 新方式
+
+1. `fetch-config`：从后台拉取 `meetsdk-remote-config.json` 到工程根目录。  
+2. `integrate`：根据 JSON 中**已开启**的 `sdkModules`，在 App Module `build.gradle` 的 `defaultConfig` 内 **upsert** 对应 `resValue`（同名键存在则更新，不存在则插入）。  
+3. 同步将 `applicationId` 对齐远程 `packageName`。
+
+**实现状态**
+
+| 项 | 状态 |
+|----|------|
+| `top_channel_id` / `top_app_id` 等 resValue | ✅ |
+| Facebook / Google / Twitter / Line / Naver / Kakao / TikTok 等 | ✅（按模块开关） |
+| Snapchat `resValue` | ✅ |
+| Snapchat `addManifestPlaceholders` | ✅（由 `login.snapchat.redirect` URL 本地解析 scheme/host/path，写入 `defaultConfig` TOPSDK 块） |
+| 游戏研发零手工配参 | ✅（流水线或 Agent 执行 setup 即可） |
+
+---
+
+### 2.2 SDK 导入（P0 — 已实现主体）
+
+#### 传统方式
+
+- 项目根 `build.gradle` / `settings.gradle` 手工加 Maven 仓库（Google、MavenCentral、TopSdk 私服等）。  
+- App Module `build.gradle` 手工写 `topsdk_version`、`groupId` 与各 `implementation` 模块。
+
+#### 新方式
+
+- 远程 JSON 决定**接入哪些可选模块**（guest、email、facebook、google-iap、appsflyer 等）。  
+- 工具内置 [`meetsdk-android.json`](../meetsdk-android.json) 提供**固定** SDK 版本、仓库 URL、`classpath`、Firebase plugin、各模块 `dependencies`。  
+- `integrate` 合并后写入根工程与 App Module 的 Gradle（标记块 upsert，避免重复插入）。
+
+**示例（由工具生成，非人工维护）**
+
+```gradle
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+        maven { url 'https://storage-sdk-gameplus.meetsocial.com/repository/TopSdk/' }
+    }
+}
+
+dependencies {
+    def topsdk_version = "1.6.1.1"   // 来自 meetsdk-android.json，可被远程 topsdk.version 覆盖
+    def groupId = "com.sino.topsdk"
+    implementation "$groupId:ui:$topsdk_version"
+    implementation "$groupId:guest:$topsdk_version"      // 仅当 sdkModules.login.guest 开启
+    implementation "$groupId:facebook:$topsdk_version" // 仅当 login.facebook 开启
+    // ...
+}
+```
+
+**实现状态**：仓库、依赖、版本、按模块开关追加构件 ✅；版本以 MG / 内置 defaults 为准 ✅。
+
+#### Gradle 编辑技术路线（已确认）
+
+| 阶段 | 方式 | 支持范围 |
+|------|------|----------|
+| **现阶段** | 正则 + 花括号匹配 + `// >>> TOPSDK` 标记块（见 [技术方案调研 §6](./技术方案调研.md#6-gradle-编辑技术路线正则--groovy-ast)） | **Groovy DSL**：`build.gradle` 等 |
+| **将来** | **Groovy AST** 解析与改写 | **仅 Groovy DSL** |
+| **明确不做** | — | **`build.gradle.kts`（Kotlin DSL）** 不检测、不自动集成 |
+
+若 CP 工程仅使用 Kotlin DSL，需改为 Groovy `build.gradle` 或人工接入；工具应在 `doctor` / `integrate` 中给出明确提示（实现可随 AST 阶段补齐）。
+
+---
+
+### 2.3 接口调用诊断（P1 — 规划中）
+
+**目标**：在不联调的情况下，诊断 SDK 接口的**调用位置**、**参数个数**、**参数类型**是否正确。
+
+**当前**：`meetgames doctor` 仅输出工程类型（Android / iOS）、路径等**环境探测**，**不包含** SDK API 静态分析。
+
+**验收标准（规划）**：对指定 SDK 公开 API 扫描宿主源码，输出违规列表（文件、行号、期望签名）。技术方向见 [技术方案调研 §6.5](./技术方案调研.md#65-游戏源码-ast-诊断规划非-gradle)（与 Gradle Groovy AST 分开）。
+
+---
+
+### 2.4 接入客服（P2 — 规划中 / MVP 外）
+
+**目标**：基于 FAQ、SDK 文档与联网内容回答开发者接入问题（如 Cursor 插件内问答）。
+
+**当前**：未在本仓库实现；可与 MCP 生态后续结合。
+
+---
+
+## 3. 使用方式
+
+### 3.1 CLI（主路径）
+
+减少交互；核心入参：
+
+| 参数 | 说明 |
+|------|------|
+| `--project-root` | 游戏工程根路径 |
+| `--app-id` | MG / TOPSDK 应用 ID |
+| `--channel-type` | 商店渠道：`GOOGLE` / `APPLE` 等（HTTP 查询参数，非 android/ios） |
+| `--env` | `prod` / `pre` / `test` |
+
+说明：`downloadSDKConfig` **无需** CLI 传 `appSecret`，密钥由接口写入 JSON 的 `topsdk.appSecret`。旧文档中的 `--app-secret` 仅适用于已废弃的 `getSDKConfig` 签名流程。
+
+```bash
+# 仅拉配置
+meetgames fetch-config --project-root . \
+  --app-id "$SDK_APP_ID" --channel-type GOOGLE --env test
+
+# 拉配置 + 集成（推荐流水线）
+meetgames setup --project-root . \
+  --app-id "$SDK_APP_ID" --channel-type GOOGLE --env test
+
+# 仅集成（已有 meetsdk-remote-config.json）
+meetgames integrate --project-root . --dry-run
+```
+
+### 3.2 Cursor / Agent（MVP）
+
+在 Cursor 等 IDE 中通过 **MCP** 调用（见 [MCP-SKILL.md](./MCP-SKILL.md)）：
+
+- `meetgames_setup`（推荐：拉取 + 集成）  
+- `meetgames_fetch_config` / `meetgames_integrate_*` / `meetgames_doctor`
+
+---
+
+## 4. 配置文件（`meetsdk-remote-config.json`）
+
+由 **gp-sdk** 新接口拉取并落盘（见 §6）。工具只读该文件，不在 `topsdk` 内重复存放渠道。
+
+### 4.1 字段约定（渠道在根级）
+
+| 规则 | 说明 |
+|------|------|
+| **渠道** | 必须使用根级字段 **`channel`**（如 `"GOOGLE"`） |
+| **禁止** | 不使用根级 `channelType`；不在 `topsdk` 下写 `channel` |
+| **平台** | 根级 **`devicePlatform`**：`android` / `ios`（小写） |
+| **应用凭证** | 仅 `topsdk.appId`、`topsdk.appSecret` |
+
+### 4.2 示例结构
+
+```json
+{
+  "packageName": "com.meet.integrate.androidsample",
+  "channel": "GOOGLE",
+  "devicePlatform": "android",
+  "topsdk": {
+    "appId": "mock-topsdk-app-id",
+    "appSecret": "mock-app-secret-do-not-use-in-production"
+  },
+  "sdkModules": {
+    "login": {
+      "guest": {},
+      "email": {},
+      "facebook": {
+        "facebookAppId": "0000000000000000",
+        "fbLoginProtocolScheme": "fb0000000000000000",
+        "facebookClientToken": "mockfacebookclienttoken00000000"
+      },
+      "google": { "googleClientId": "mock-client-id.apps.googleusercontent.com" }
+    },
+    "payment": { "googleIap": {} },
+    "analytics": {
+      "appsflyer": { "enableDebugLog": true, "devKey": "MOCK_APPSFLYER_DEV_KEY" },
+      "facebookdata": {},
+      "firebase": { "firebase_file_url": "https://example.invalid/firebase/google-services.json" },
+      "adjust": { "appId": "MOCK_ADJUST_APP_ID" }
+    }
+  }
+}
+```
+
+- 模块关闭：值为 `false`。  
+- 模块开启：值为 `{}` 或带业务字段的对象。  
+- 埋点 Facebook Data 子键为 **`facebookdata`**（非 `facebook`）。  
+- Schema：[schema/meetsdk-remote-config.schema.json](../schema/meetsdk-remote-config.schema.json)。
+
+---
+
+## 5. MG 后台需求（与工具配套）
+
+| 编号 | 需求 | 说明 |
+|------|------|------|
+| BG-1 | 游戏配置页增加**下载渠道配置** | 「配置」进入渠道页；「下载」得到 `meetsdk-remote-config.json`（与工具 `fetch-config` 一致） |
+| BG-2 | 三方配置文件**按文件**存取 | 上传保存源文件；下载返回源文件。避免仅存文本导致格式错乱、只能走接口拼文本 |
+| BG-3 | 新增配置文件上传与**路径设置** | 如 `google-services.json`、Adjust 事件 JSON 等 OSS 路径 |
+| BG-4 | 「SDK 下载」改为 **SDK 版本配置** | 版本由后台维护，工具侧通过 `meetsdk-android.json` 合并默认版本与依赖 |
+
+---
+
+## 6. 服务端接口（gp-sdk console）
+
+### 6.1 配置拉取（新接口，工具标准路径）
+
+| 项 | 内容 |
+|----|------|
+| **新接口** | `GET {baseUrl}console/openSDK/downloadSDKConfig` |
+| **Query** | `appId`、`channelType`（商店渠道，如 `GOOGLE` / `APPLE`） |
+| **鉴权** | 无需 sign |
+| **响应** | 响应体即为 `meetsdk-remote-config.json` 全文（附件下载） |
+| **CLI** | `meetgames fetch-config` / `meetgames setup` |
+
+示例：
+
+```http
+GET https://{api-sdk-gameplus-host}/console/openSDK/downloadSDKConfig?appId=791251136341225472&channelType=GOOGLE
+```
+
+响应 JSON **必须**含根级 `channel`（与 `channelType` 查询值一致）、`devicePlatform`，且 **`topsdk` 内不含 `channel`**。
+
+### 6.2 老接口（不再用于一键集成拉参）
+
+| 接口 | 说明 |
+|------|------|
+| `GET /openSDK/getSDKConfig` | 需 `appSecret` 签名；仅返回 `channelAuthConfig` 片段，**不是**完整 `meetsdk-remote-config.json` |
+
+### 6.3 其它（与配置 JSON 分离）
+
+三方配置文件（如 `google-services.json`）建议 OSS **原文件**上传下载；SDK 包版本由 MG 后台「SDK 版本配置」维护，与 `meetsdk-android.json` 合并策略见技术方案。**不**使用单独的 `home/sdk-download/downloadMeetSdkRemoteConfig` 作为本工具拉参入口。
+
+### 6.4 组装规则（`downloadSDKConfig`）
+
+- 仅 `enable=true` 的 `channel_auth` 写入登录参数；未启用项为 `false`。  
+- 根级 `channel`、`devicePlatform`；`topsdk` 仅 `appId` / `appSecret`。  
+- 支付、第三方数据平台按表与 enable 规则映射到 `sdkModules`。
+
+详见 [api/downloadSDKConfig.md](./api/downloadSDKConfig.md)。
+
+---
+
+## 7. 非功能需求
+
+| 项 | 要求 |
+|----|------|
+| 语言 | TypeScript（Node >= 18） |
+| 宿主 | 纯原生 Android / iOS |
+| Android 构建脚本 | **Groovy DSL**（`build.gradle`）；**不支持 Kotlin DSL**（`.kts`） |
+| Gradle 编辑 | 现阶段正则 + 标记块；规划 **Groovy AST only** |
+| CI | 支持非交互执行 `setup` / `integrate` |
+| 安全 | `appSecret` 不得提交公开仓库；流水线用密钥注入 **【组织规范待统一】** |
+| 可审计 | `integrate --dry-run` 输出 patch |
+
+---
+
+## 8. 验收标准
+
+### 8.1 已交付能力（当前版本）
+
+1. **参数配置**：对样例工程执行 `setup` 后，App `build.gradle` 含正确 `resValue` 且同名键不重复堆积。  
+2. **SDK 导入**：根工程含 TopSdk 等仓库；App 模块含 `topsdk_version` 与按开关启用的 `implementation`。  
+3. **拉取**：`fetch-config` 成功时 JSON 含 `channel`、`devicePlatform`，且无 `topsdk.channel`。  
+4. **流水线**：在 CI 中可无人工步骤完成 `fetch-config` + `integrate`（需目标环境已部署 `downloadSDKConfig`）。  
+5. **测试**：`npm test` 通过。
+
+### 8.2 后续版本
+
+| 能力 | 验收 |
+|------|------|
+| 接口调用诊断 | 对约定 API 列表输出静态检查报告 |
+| Snapchat Manifest placeholders | 与 PRD 示例一致的 `addManifestPlaceholders` |
+| 三方配置文件原文件下载 | OSS 直链写入 JSON（如 `firebase_file_url`） |
+| 接入客服 | 可回答 FAQ 范围内接入问题 |
+
+---
+
+## 9. 里程碑建议
+
+| 阶段 | 内容 |
+|------|------|
+| M1 | Android：fetch-config + integrate + CI 样例 ✅ |
+| M2 | gp-sdk `downloadSDKConfig` 测试/预发/正式部署；MG 后台下载按钮与文件存取 |
+| M3 | iOS integrate 与 Android 同等级流水线支持 |
+| M4 | 游戏源码 AST 接口诊断、Snapchat Manifest placeholders、客服 / FAQ Agent |
+| M5 | **Groovy AST** 替代 Gradle 正则编辑（仍不支持 `.kts`） |