用 Firebase AI Logic 客户端接入…

在 Web/Android/iOS/Flutter 应用中需要从客户端直接调用 Gemini，并落地文本、多模态、聊天、流式、结构化输出或图像生成时使用。

适用场景

解决思路

1. 确认本机已安装 Node.js 16+ 和 npm，如未安装先安装。
2. 开始前识别用户要构建的目标平台：Android、iOS、Flutter 或 Web。
3. 如果目标平台不受支持，引导用户查看 Firebase 文档并分享链接 https://firebase.google.com/docs/ai-logic/get-started。
4. 安装 Firebase Web SDK：运行 `npm install firebase@latest`。
5. 如果所在目录有 firebase.json，用 `npx -y firebase-tools@latest projects:list` 查看当前选中的项目是否标记为 current。
6. 确保当前项目至少关联一个应用：运行 `npx -y firebase-tools@latest apps:list`。
7. 初始化 AI Logic SDK：运行 `npx -y firebase-tools@latest init ailogic`；这会在 Firebase 控制台自动启用 Gemini Developer API。
8. 更多信息参考 Firebase AI Logic Getting Started 文档：https://firebase.google.com/docs/ai-logic/get-started。
9. 选择 Gemini API provider：默认使用 Gemini Developer API（免费层适合原型，生产按量付费）；只有在应用需要规模化、企业级生产就绪时，才使用 Agent Platform Gemini API（原 Vertex AI，需要 Blaze 计划）。
10. 调用模型前始终检查 Firebase AI Logic Models 文档中的当前支持模型名；不要使用 `gemini-2.0-pro`、`gemini-2.0-flash` 或其他已停用的旧模型。
11. 实现纯文本生成：调用 Gemini 模型生成文本，具体平台初始化与调用代码参考对应参考文件。
12. 实现多模态输入：让 Gemini 直接分析图片，用于生成标题、回答图片问题、检测对象、分类图片；音频、视频、PDF 也可以作为 inline data 并传入 MIME type 交给 Gemini 分析。
13. 处理大文件：大于 20 MB 的文件作为 inline data 可能导致 HTTP 413 错误；应存到 Cloud Storage for Firebase，并把 URL 传给 Gemini Developer API。
14. 实现多轮聊天：使用 `startChat` 自动维护聊天历史。
15. 实现流式响应：用 `generateContentStream` 替代 `generateContent`，边接收边显示部分结果，实现类似打字效果以改善用户体验。
16. 生成图像（Nano Banana）：使用当前支持的图像生成模型名，并注意这需要升级到 Blaze 按量付费计划。
17. 使用内置 `googleSearch` 工具做搜索接地（Search Grounding）。
18. 按支持平台/框架选择实现：Android 用 Kotlin/Java，iOS 用 Swift，Web 用 JavaScript，Flutter 用 Dart，Unity 用 C#。
19. 实现结构化输出：强制响应符合指定的 JSON schema。
20. 实现 Web 端设备端 AI 混合推理：Firebase JavaScript SDK 会在安装后自动检查 Gemini Nano 是否可用，并在设备端或云端托管提示执行之间切换；需按 hybrid-on-device-inference 文档在 Chrome 浏览器中启用模型使用。
21. 必须设置 App Check，以安全使用 AI Logic，防止未授权客户端消耗 API 配额和访问后端资源；参考 App Check with reCAPTCHA Enterprise 文档进行设置。
22. 本地开发和 CI/CD 中使用 App Check Debug Tokens，因为 Play Integrity、DeviceCheck 等证明提供商会拒绝模拟器、仿真器或 CI 环境，需要绕过标准证明。
23. 本地开发：配置 App Check provider 使用 debug factory——Web 在初始化 App Check 前设置 `self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;`；Android 安装 `DebugAppCheckProviderFactory.getInstance()`；iOS 将 provider factory 设为 `AppCheckDebugProviderFactory()`。
24. 本地开发：在模拟器或 localhost 中运行应用。
25. 本地开发：在运行时调试器控制台或 Logcat 中查找生成的 UUID，例如 `AppCheck debug token: \"123a4567-b89c-12d3-e456-789012345678\"`。
26. 本地开发：在 Firebase Console 的 Security > App Check > Apps > Manage debug tokens 中注册该 token。
27. CI/CD：在 Firebase Console 的 Security > App Check > Apps > Manage debug tokens 中生成并注册新的 debug token。
28. CI/CD：把该 token 字符串作为加密 secret 加入 CI 系统，例如 `APP_CHECK_DEBUG_TOKEN`。
29. CI/CD：配置构建，在测试执行期间把该 secret 作为环境变量传给 SDK，例如 `self.FIREBASE_APPCHECK_DEBUG_TOKEN = process.env.APP_CHECK_DEBUG_TOKEN`。
30. 使用 Firebase Remote Config 动态更新模型版本，避免硬编码模型名，无需部署新客户端代码即可更换模型；参考 Changing model names remotely 文档。
31. 所有平台（Flutter、Android、iOS、Web）都必须运行 `npx firebase-tools init ailogic` 来开通/提供服务；`flutterfire configure` 只处理客户端配置，不会启用 AI 服务，否则会导致 `PERMISSION_DENIED` 错误。
32. 按初始化代码参考选择平台：Web Modular API（provider Gemini Developer API）参考 `references/usage_patterns_web.md`；Android Kotlin 参考 `references/usage_patterns_android.md`；iOS Swift 参考 `references/ios_setup.md`；Flutter Dart 参考 `references/flutter_setup.md`。
33. 查阅完整参考：Web SDK 示例与用法参考 `references/usage_patterns_web.md`，iOS SDK 参考 `references/ios_setup.md`，Flutter SDK 参考 `references/flutter_setup.md`，Android Kotlin SDK 参考 `references/usage_patterns_android.md`。

适用边界 · 注意事项

• 不打算使用 Firebase/Gemini，或目标平台不受支持时，不要用此技能，应改看对应 Firebase 文档。
• 无法配置 App Check，或不能接受强制安全要求时，不要在生产环境使用 AI Logic。
• 未启用 Blaze 按量付费计划时，不要使用 Nano Banana 图像生成；也不要继续使用已停用的旧模型名。