160 lines
9.6 KiB
Markdown
160 lines
9.6 KiB
Markdown
# 技术架构：Flutter 手机优先、支持 Mac 的个人学习工具
|
||
|
||
> 当前目标：iPhone、Android 手机与 Mac；个人自用；无需发布、登录或自建服务器。
|
||
> 原则：手机优先、本地优先；每台设备都可以独立完成全部学习功能。
|
||
|
||
本文技术方向不代表已验证实现。M1 的范围、内容结构、证据实体及异常行为以 [开发与验收约定](M1-IMPLEMENTATION-CONTRACT.md) 为准；课程总量不限，阶段核心清单固定版本。
|
||
|
||
## 1. 推荐技术路线
|
||
|
||
使用 **Flutter / Dart** 构建 iPhone、Android 与 macOS 客户端，共享课程、学习引擎和对话状态代码；布局以手机为第一优先级，Mac 只是更宽的阅读和练习界面。
|
||
|
||
| 层级 | 方案 | 用途 |
|
||
|---|---|---|
|
||
| 客户端 | Flutter / Dart | iPhone、Android 优先界面，macOS 适配 |
|
||
| 状态管理 | Riverpod 或同类单向状态方案 | 课程步骤、录音状态、对话状态、复习队列 |
|
||
| 本地数据 | SQLite（Drift） | 证据、掌握、复习、会话、评估、进度和临时词条分表保存；旧版完整快照只作迁移/恢复回退，正常写入不再生成快照 |
|
||
| 课程内容 | 内置 JSON | A0 课程、场景、词句、词条释义、练习规则 |
|
||
| 录音与播放 | Flutter 跨平台音频插件 + 原生适配 | 录音、回放、慢速播放、音频缓存 |
|
||
| AI 对话 | 云端模型 API 或本地模型 | 受控情境对话、纠错、每日变式 |
|
||
| 语音转写 | 云端转写或各平台原生语音能力 | 将用户英语录音变成可确认文字 |
|
||
| 英文朗读 | 跨平台 TTS 或云端语音合成 | 播放 AI 的英语回复和标准示范音 |
|
||
| 密钥保存 | 平台安全存储 | iOS Keychain、Android Keystore、macOS Keychain |
|
||
|
||
## 2. 手机优先原则
|
||
|
||
- 单手操作：录音、重说、提示等核心按钮位于手机屏幕下方。
|
||
- 一屏一个任务：课程和对话不要求用户滚动查找下一步。
|
||
- 断网可继续内置课程、本地判题、学习记录、已有音频和模板复习；AI 动态生成、在线对话/反馈及云端语音需网络。原生 STT/TTS 离线可用性须逐设备探测；缺音频的听力题与开放答案反馈留待补做。
|
||
- 声音可选：公共场合可切换为文字输入与静音阅读，不应阻止完成练习。
|
||
- Mac 复用：Mac 端展示同一课程和本机进度，可更适合阅读、输入和查看历史，不重新设计一套学习流程。
|
||
|
||
## 3. 是否需要后台
|
||
|
||
不需要自行部署远程后台。
|
||
|
||
```text
|
||
iPhone / Android / Mac App
|
||
├─ 本地课程 JSON
|
||
├─ 本地学习数据库
|
||
├─ 本地录音与音频缓存
|
||
└─ 通过可切换的 AI 提供商调用对话 / 转写 / 语音服务
|
||
```
|
||
|
||
### 3.1 跨设备同步
|
||
|
||
M1 不做自动跨设备同步。每台设备保存自己的学习记录，但都内置相同课程并可独立使用。
|
||
|
||
如需在手机开始后在 Mac 继续，可在后续版本增加“加密导出/导入学习进度”。导出的内容包括：
|
||
|
||
- 当前课程和步骤；
|
||
- 词句掌握状态与复习到期时间；
|
||
- 对话文字摘要、错误项与重说句；
|
||
- 偏好设置；
|
||
- 不包含原始录音。
|
||
|
||
原始录音默认只保留在产生它的设备，以节省空间并减少隐私暴露。若以后必须自动同步，可选择用户自有的云盘同步或小型后台代理；这不属于 M1。
|
||
|
||
### 3.2 AI 提供商配置与网络请求
|
||
|
||
个人自用时，模型服务密钥或兼容代理 Token 可分别保存在 iPhone、Android 和 Mac 的安全存储中，由客户端直接调用选定的 AI 服务。不要把密钥写进课程 JSON、源代码或可分享的配置文件。
|
||
|
||
这只适用于你自己的设备和开发构建。若未来发布给他人使用，必须改为通过后台代理请求，以保护密钥、控制成本和处理滥用。
|
||
|
||
客户端只依赖统一的 `AIProvider` 接口，而不将课程逻辑写死到单一服务商：
|
||
|
||
```text
|
||
AIProvider
|
||
├─ GeminiProvider
|
||
├─ OpenAIProvider
|
||
└─ OpenAICompatibleProvider
|
||
```
|
||
|
||
每个提供商配置包含：提供商类型、模型名、接口地址、Token 和能力开关（文字对话、转写、语音）。设置页只显示当前选中的提供商；切换提供商不影响本地课程、掌握状态和复习队列。
|
||
|
||
### 3.3 OpenAI 兼容反代（CLIProxyAPI）
|
||
|
||
CLIProxyAPI 可作为 `OpenAICompatibleProvider` 的可选接口地址，用于文字情境对话、课程变式、纠错与结构化返回。它不是 M1 的唯一依赖；不可用时可切换到 Gemini API 或 OpenAI API。
|
||
|
||
使用前必须满足：
|
||
|
||
- 手机和 Mac 都能访问该地址。手机中的 `localhost` 指向手机本身，不能访问 Mac 上运行的反代；需使用可访问的局域网地址或有效 HTTPS 地址。
|
||
- 反代须通过 App 的地址/鉴权、选定模型短文本及结构化返回测试；流式可选，可用非流式降级。测试成功仅证明当前文字能力，不证明语音或全部兼容能力。
|
||
- 反代 Token 仅保存在平台安全存储；不得使用网页 Cookie、账号密码或 OAuth 会话作为 App 凭据。
|
||
- 如果反代基于消费者订阅的登录态或令牌，使用前须自行确认授权方式与相关服务条款。
|
||
|
||
反代先只承担文字 AI。转写优先设备原生能力，朗读优先设备 TTS；设备权限、英语语言包与实际可用性验证通过后才能运行对应语音流程。文字降级允许继续学习，但不能代替口语/听力达标。
|
||
|
||
## 4. M1 数据模型
|
||
|
||
下图仅为概览。实现必须补充 StageDefinition、AbilityNode、Task/Asset、AttemptEvidence、StudySession、StageAssessment 与 ProviderConfiguration，字段和事务约束见《开发与验收约定》第 3 节。掌握度应能从有版本的分技能证据重算，AI 不直接写入升级状态。
|
||
|
||
```text
|
||
Course
|
||
└─ Lesson
|
||
├─ vocabulary / patterns
|
||
├─ listening / reading / writing tasks
|
||
└─ dialogue scenario and completion rules
|
||
|
||
LexiconEntry
|
||
├─ word or phrase, contextual Chinese meaning and example
|
||
├─ audio reference and approval/source status
|
||
└─ related ability / vocabulary / pattern IDs
|
||
|
||
LearnerProfile
|
||
├─ current level and current lesson
|
||
├─ daily study duration
|
||
└─ preferences (voice, subtitles, speed)
|
||
|
||
MasteryItem
|
||
├─ word or sentence pattern
|
||
├─ state: new / recognize / recall / use / master
|
||
├─ success and failure history
|
||
└─ next review date
|
||
|
||
SavedWord
|
||
├─ lexicon entry and saved time
|
||
└─ optional low-priority review state
|
||
|
||
ConversationSession
|
||
├─ scenario, turns and task progress
|
||
├─ transcript summary
|
||
├─ one improvement sentence
|
||
└─ review item
|
||
```
|
||
|
||
## 5. M1 的 AI 提供商与模型组合
|
||
|
||
ChatGPT 与 Gemini 的消费者订阅可用于手动编写课程、检查内容和测试提示词，但不能直接作为 Flutter App 的自动调用额度。App 需要配置各自的开发者 API Key；订阅与 API 计费/额度分开处理。
|
||
|
||
文字 AIProvider、SpeechRecognizer、SpeechSynthesizer 分别抽象；选择文字代理不意味着其也支持语音。M1 手动选择一个文字提供商，不同时调用多家或自动切换付费服务。下表为候选配置，模型名、额度及价格未在本次文档修订中联网验证，使用时以账号实际能力和连接测试为准，不把免费额度作为运行保证。
|
||
|
||
| 能力 | M1 默认方案 | 可切换方案 | 说明 |
|
||
|---|---|---|---|
|
||
| 情境对话、课程变式、纠错、结构化 JSON | Gemini API 免费层（先用于个人原型） | OpenAI API 的 GPT-5 mini | 两者均须各自 API Key；先用已有 Google 账号可访问的免费额度验证流程，额度或质量不够时切换 OpenAI |
|
||
| 兼容反代文字对话 | 不默认启用 | CLIProxyAPI 的 OpenAI 兼容地址 | 在设置中手动填写 Base URL、Token 和模型名；只在接口能力与授权边界明确时启用 |
|
||
| 英语语音转写 | 设备原生语音识别 | OpenAI API 的 GPT-4o mini Transcribe | 先避免增加 API 成本；低可信度时必须允许确认、修改或重说 |
|
||
| 英文朗读 | 设备 TTS | 云端语音合成 | M1 优先本机朗读，减少成本并支持基础离线使用 |
|
||
| 实时全双工语音 | 暂不使用 | 后续单独评估 | 当前采用 3–5 轮的轮流对话，实时打断不是 M1 需求 |
|
||
|
||
每次 AI 对话都应传入当前等级、场景、允许词句、用户已回答内容和任务完成条件；不要用模型决定课程顺序。模型用量主要来自对话和反馈，因此应限制为 3–5 轮短对话，并缓存已生成的课程音频和练习变式。
|
||
|
||
官方参考：[OpenAI API Key 快速开始](https://developers.openai.com/api/docs/quickstart)、[GPT-5 mini](https://developers.openai.com/api/docs/models/gpt-5-mini)、[OpenAI API 定价](https://developers.openai.com/api/docs/pricing)、[Gemini API Key](https://ai.google.dev/gemini-api/docs/api-key)、[Gemini API 计费](https://ai.google.dev/gemini-api/docs/billing)。
|
||
|
||
## 6. M1 实现顺序
|
||
|
||
1. 完成一课听说读写、本地证据与恢复流程。
|
||
2. 加入文字 AI 对话、结构校验、反馈与本地降级。
|
||
3. 加入 TTS、录音、语音转写与确认；分别记录听说读写证据。
|
||
4. 完成每日推荐、复习、变式生成、A0 出口评估与全部种子内容审校。
|
||
5. 完成 iPhone、Android 真机及 macOS 同流程验证，覆盖《开发与验收约定》的异常测试。加密导出/导入留到 M2。
|
||
|
||
## 7. 当前不做
|
||
|
||
- 自建后端、账号、公开用户数据库；
|
||
- Web、多人共享、社交匹配与自动跨设备同步；
|
||
- 支付、订阅、通知、运营分析；
|
||
- 云端长期保存原始录音；
|
||
- 实时全双工电话式 AI 通话。
|
||
- 加密导出/导入、个性化音素诊断；前者留到 M2，后者须另行验证。
|