Day 2 我们完成了后端 Spring AI Alibaba 接入以及鸿蒙端依赖引入。今天聚焦 Flutter 跨平台端：分别在 Android 与 iOS 原生层集成 AGenUI SDK，为后续 Dart 层调用组件库做准备。

---

0. 今日目标

端	事项	内容
Flutter-Android	AAR / Maven / Gradle 自动化	三种方式引入 AGenUI-Client-Android
Flutter-iOS	CocoaPods / Framework	通过 CocoaPods 或手动 Framework 引入 AGenUI
Flutter	工程验证	同步原生层改动，确认双端可正常编译

---

一、Flutter 工程结构说明

在 Flutter 项目中，原生代码位于以下目录：

agen-ui-flutter/
├── android/          # Android 原生工程（Gradle）
├── ios/              # iOS 原生工程（Xcode / CocoaPods）
├── lib/              # Dart 业务代码
└── pubspec.yaml      # Dart 依赖

配置原则：Flutter 端引入 AGenUI 需分别修改 android/ 和 ios/ 下的原生工程配置，Dart 层的调用封装将在 Day 4 展开。

---

二、Android 端集成

2.1 前提条件

组件	版本要求
Android Studio	Hedgehog 或更高版本
Android API	21+ (Android 5.0)
JDK	11
Android NDK	25.2.9519653（如需源码构建）

⚠️ 脚本执行提示：以下所有 ./scripts/android/build.sh 为 Shell 脚本（.sh），Windows 用户请在 Git Bash、WSL、PowerShell（配合 WSL）或 macOS/Linux 终端中执行，不要直接在 Windows CMD 中运行。

---

2.2 方式一：本地源码构建 AAR（快速验证）

1. 进入 AGenUI 源码目录，执行构建脚本：

# 请在 Git Bash / WSL / macOS / Linux 终端中执行
./scripts/android/build.sh

2. 构建产物位于：

dist/android/release/AGenUI-Client-Android-release.aar

3. 将 .aar 文件拷贝至 Flutter 项目的 Android 目录：

agen-ui-flutter/android/app/libs/AGenUI-Client-Android-release.aar

4. 修改 android/app/build.gradle，添加本地依赖：

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    // 其余 Flutter 默认依赖...
}

5. 同步 Gradle，确认无报错。

---

2.3 方式二：本地 Maven（团队协作）

1. 执行构建并发布到本地 Maven（同样需在 Git Bash / 类 Unix 终端执行）：

./scripts/android/build.sh --publish-local

2. 修改 Flutter Android 工程的 settings.gradle（或 settings.gradle.kts），添加 mavenLocal()：

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        mavenLocal()   // 添加本地 Maven 仓库
    }
}

3. 在 android/app/build.gradle 中引入依赖：

dependencies {
    implementation 'com.amap.genui:agenui-sdk:0.1.0'
}

注意：若团队使用私有 Maven 仓库（如 Nexus），可将构建脚本中的 --publish-local 替换为 --publish-remote，统一指向私服地址。

---

方式	适用场景	优点	缺点
方式一：手动拷贝 AAR	快速验证、SDK 源码不可见	简单直接	每次 SDK 更新需手动重新拷贝
方式二：本地 Maven	团队协作、多项目复用	版本化管理、可发布到私服	需额外执行 publish 命令
方式三：Gradle 自动构建	源码与 Flutter 同仓库、频繁调试 SDK	修改 SDK 源码后自动重新编译、零手动操作	首次编译耗时较长、依赖源码目录结构

建议：

• 日常开发：使用方式三，修改 SDK 源码后 flutter run 自动同步
• CI/CD 或发版：切换为方式二（agenui.sdk.source=true + Maven 依赖），避免在构建机重复编译 SDK 源码

---

三、iOS 端集成

3.1 前提条件

组件	版本要求
Xcode	15 或更高版本
iOS 部署目标	13.0 或更高版本
Swift	5.0 或更高版本
包管理器	CocoaPods

---

3.2 方式一：CocoaPods（推荐）

1. 进入 Flutter 项目的 iOS 目录：

cd agen-ui-flutter/ios

2. 打开 Podfile，添加依赖：

pod 'AGenUI'

3. 执行安装：

pod install

4. 此后使用 .xcworkspace 打开工程：

open Runner.xcworkspace

---

3.3 方式二：手动集成 Framework

适用于无法使用 CocoaPods 的离线环境或定制场景。

步骤 1：构建 Framework

# 生成 Framework（x86 架构，仅模拟器）
./scripts/ios/build.sh -t framework -c Release

# 或生成 XCFramework（arm64 + x86，支持真机+模拟器+M 芯片 Mac）
./scripts/ios/build.sh -t xcframework -c Release

⚠️ 脚本执行提示：上述 .sh 脚本同样需要在 Git Bash / WSL / macOS / Linux 终端中执行。

产物位置：

类型	路径
Framework	dist/ios/release/AGenUI.framework
XCFramework	dist/ios/release/AGenUI.xcframework

建议：M 芯片 Mac 或需同时支持真机与模拟器时，优先使用 XCFramework。

步骤 2：添加到 Xcode 项目

1. 将生成的 .framework 或 .xcframework 拖入 ios/Runner.xcodeproj
2. 选中 Target → General → Frameworks, Libraries, and Embedded Content
3. 将 AGenUI 的 Embed 设置为 Embed & Sign
4. 在 Build Settings → Search Paths → Framework Search Paths 中添加：

$(PROJECT_DIR)/Frameworks

步骤 3：处理资源文件

AGenUI SDK 包含独立的资源 Bundle，需手动引入：

1. 找到资源文件：

platforms/ios/AGenUI/Assets/AGenUI.bundle

2. 将 AGenUI.bundle 拖入 Xcode 项目的 Runner Target 下
3. 确认 Build Phases → Copy Bundle Resources 中包含该 Bundle

---

四、Flutter 层验证

完成上述双端配置后，在 Flutter 项目根目录执行：

flutter clean
flutter pub get
cd android && ./gradlew clean && cd ..
cd ios && pod install && cd ..
flutter run

若编译通过且 App 正常启动，说明原生层集成成功。

---

五、Day 3 小结

端	完成项	状态
Flutter-Android	方式一：手动拷贝 AAR	✅
Flutter-Android	方式二：本地 Maven 引入	✅
Flutter-Android	方式三：Gradle 自动化构建 AAR	✅
Flutter-iOS	CocoaPods 集成	✅
Flutter-iOS	手动 Framework / XCFramework 集成	✅
全端	flutter run 编译通过	✅

---

六、下一步（Day 4 预告）

1. 后端：编写 ChatClient 流式对话接口（SSE），对接通义千问
2. 鸿蒙端：使用 @agenui/agenui 搭建聊天 UI，对接后端 SSE
3. Flutter 端：编写 Dart 层 AGenUI 初始化与调用封装，实现跨平台聊天界面

---

提示：

• 所有 .sh 脚本（build.sh 等）均为 Shell 脚本，Windows 用户请务必使用 Git Bash、WSL、macOS/Linux 终端 执行，CMD 无法直接运行。
• Android 端若提示 NDK not found，请在 Android Studio → SDK Manager → SDK Tools 中安装 NDK 25.2.9519653
• iOS 端若使用手动集成，AGenUI.bundle 漏拷会导致运行时资源加载失败，请务必检查 Copy Bundle Resources
• Flutter 热重载不会触发原生层改动，修改 AAR/Framework 后需重新执行 flutter run**

AGenUI代码仓库：https://github.com/AGenUI/AGenUI