deepvoice_client/local_plugins/chat_api/SPM_MIGRATION.md

Chat API 插件 SPM 迁移说明

迁移概述

chat_api 插件已经完成了 Swift Package Manager (SPM) 支持的迁移，现在可以自动处理 OpenAI Swift 包的依赖。

主要变更

1. 目录结构调整

ios/
├── chat_api.podspec          # 保留，支持双轨模式
├── Classes/                   # 已清空（源码已迁移）
└── chat_api/                  # 新增 SPM 结构
    ├── Package.swift          # SPM 包定义
    └── Sources/
        └── chat_api/          # 源码新位置
            ├── ChatApiPlugin.swift
            └── ChatService.swift

2. Package.swift 配置

• 声明了 MacPaw OpenAI 包依赖
• 自动管理版本（0.4.0+）
• 设置最低 iOS 版本为 13.0

3. podspec 更新

• 更新了 source_files 路径指向新的 SPM 结构
• 添加了友好的迁移提示脚本

4. pubspec.yaml 更新

• 添加了 dartPluginClass 声明，明确支持 SPM

使用方式对比

旧方式（手动集成）

1. 运行 pod install
2. 打开 Xcode
3. 手动添加 OpenAI Swift Package
4. 配置依赖关系

新方式（自动集成）

1. 启用 SPM：flutter config --enable-swift-package-manager
2. 运行 flutter run
3. 完成！Flutter 自动处理所有依赖

兼容性

• Flutter 3.24+：完整 SPM 支持，推荐使用
• Flutter < 3.24：自动降级到 CocoaPods 模式
• 混合项目：如果项目中有其他插件未迁移到 SPM，Flutter 会智能选择合适的集成方式

验证集成

SPM 项目

# 在 example 目录下
flutter clean
flutter pub get
flutter run --verbose

成功标志：

• 看到 "Adding Swift Package Manager integration..." 消息
• Xcode 中 Package Dependencies 自动出现 OpenAI 包
• 构建成功，无需手动干预

CocoaPods 项目

如果项目仍使用 CocoaPods，会看到：

• podspec 中的迁移提示
• 需要按照 IOS_INTEGRATION_LEGACY.md 手动添加依赖

故障排除

1. 清理缓存

   flutter clean
   rm -rf ios/Pods ios/Podfile.lock
   rm -rf ~/Library/Developer/Xcode/DerivedData
   

2. 重置 SPM 缓存

   • Xcode: File > Packages > Reset Package Caches

3. 确认 SPM 已启用

   flutter config
   # 应该看到 enable-swift-package-manager: true
   

开发者注意事项

1. 源码位置：所有 Swift 代码现在位于 ios/chat_api/Sources/chat_api/
2. 双轨支持：保持 podspec 和 Package.swift 同时更新
3. 版本管理：OpenAI 包版本在 Package.swift 中管理

未来计划

• 当 Flutter 生态系统完全迁移到 SPM 后，可以考虑移除 CocoaPods 支持
• 持续跟踪 MacPaw OpenAI 库的更新