ChatPilot 是一款面向移动端的多模型 AI 对话助手,用 Flutter 构建一套代码同时覆盖 Android、iOS 与 Web。项目目标是做一个离线可演示、上线可扩展的聊天工具:用户不绑定单一模型,可在 Mock 离线流与 DeepSeek、GPT-4o、Claude 3.5、Gemini 1.5 之间切换,并按 General、Translator、Writer、Engineer、Tutor 五种角色预设调整对话风格。核心模块包括会话管理、角色选择、多模型流式对话、语音听写、Markdown 消息渲染、API 密钥与语音设置,以及可选的 Supabase 云端同步。典型流程为:打开应用进入本地会话列表,选择角色与模型后输入文字或语音发送,助手逐段流式返回并可中途停止;会话默认保存在本机,登录邮箱账号后再与云端历史按时间合并同步。
整体采用 feature-first 分层架构,lib/features 下按 chat、conversations、persona、settings、auth、voice 六个模块划分,每层分为表现层(页面 + Riverpod 状态)、领域层(仓库接口与实体)、数据层(仓库实现与适配)和外部服务层。技术栈为 Flutter / Dart 3.12、flutter_riverpod 状态管理、go_router 路由、http 接收 SSE 流式响应、shared_preferences 本机存储、flutter_markdown 渲染回复、supabase_flutter 完成邮箱认证与 Postgres 会话同步(RLS 行级权限),语音基于 speech_to_text 与 record;界面支持中英文双语切换。lib/ 共 6 个功能模块、76 个 Dart 文件、约 6000 行(含功能模块与本地化资源),配套 17 个测试文件并接入 CI 流水线执行 analyze 与测试。项目由我独立完成架构设计、UI 实现、状态管理、数据层、多后端适配、语音与同步逻辑及本地化。
主要难点与方案:
1. 多厂商流式协议差异:各家 SSE 报文格式不同(OpenAI Chat Completions、Anthropic Messages、Google streamGenerateContent、DeepSeek 兼容接口)。领域层抽象统一的 ChatRepository 接口(返回 Stream),数据层为每家编写独立仓库与 SSE 解析客户端,CompositeChatRepository 按模型枚举分发;上层只依赖接口,新增厂商只需补充实现。
2. 本地优先与云端冲突:离线先写本机,登录后再同步。同步仓库以本地为准,登录后尽力推送 / 拉取;拉取远端后按更新时间戳合并会话,网络或权限失败时保留本地数据,不丢历史。
3. 跨平台语音可用性:设备语音识别的权限与平台支持不一,Whisper 需要 OpenAI 密钥且 Web 端不可用。语音引擎统一为 StreamingSttEngine 接口;默认使用设备识别(Device STT),可选 Auto 模式在启动时先探测设备识别、不可用再改用 Whisper;两者都不可用时抛出明确异常并提示手动选择 Mock 演示引擎,Mock 仅作为显式演示,不静默伪造听写。
4. API 密钥安全:密钥不打包进客户端、不提交仓库。密钥按厂商隔离存于本机 SharedPreferences,设置页掩码显示,源码与安装包均不含真实密钥。