跟着学伴AI项目设计分析学习安卓APP研发

学伴AI项目设计分析

项目名称 : 学伴AI --- 全学段启发式学习助手
平台 : Android 原生应用
总结日期 : 2026-04-12
当前版本 : v1.0.0（Build 4c9cc93）

---

目录

1. 项目概述
2. 业务模型
3. 需求清单
4. 系统设计
5. 功能清单
6. 代码规模
7. 关键决策与已知限制
8. 后续维护迭代建议
9. [附录：Git 提交历史](#附录：Git 提交历史)

---

1. 项目概述

1.1 一句话描述

学伴AI 是一款面向 K12 至研究生的全学段 Android 学习助手，以端侧+云端混合推理为核心，通过启发式苏格拉底对话引导学生自主思考，支持语音、拍照、手写多模态输入，覆盖小学/初中/高中/大学/研究生五个学段，提供差异化 UI 与差异化功能。

1.2 核心教育理念

理念	实现方式
启发式教学	SocraticEngineV2：不给答案，引导提问
个性化辅导	学段自适应 StageAdapter + 动态主题
离线可用	端侧 Qwen 模型（可选）+ 本地 Room 数据库
多模态交互	语音 ASR / 文字 / 拍照 OCR / 手写 ML Kit
安全健康	家长控制时长限制 + 视力保护提醒 + 内容过滤

1.3 目标市场

• K12: ~2 亿在校学生（小学/初中/高中）
• 高等教育: ~4000 万大学生+研究生
• 家长群体: 关注孩子学习健康的家长
• 竞品对比 : 相比作业帮/猿辅导主打离线+启发式 ，相比科大讯飞学习机主打纯软件低成本

---

2. 业务模型

2.1 核心业务场景

学生提出问题（文字/语音/拍照/手写）
       │
       ▼
  多模态输入处理
  ┌────────────────────────────────────┐
  │ 文字输入 → 直接传递                │
  │ 语音输入 → Vosk ASR → 文字        │
  │ 拍照输入 → ML Kit OCR → 文字     │
  │ 手写输入 → ML Kit Digital Ink → 文字 │
  └────────────────────────────────────┘
       │
       ▼
  HybridLLMEngine（混合推理）
  ┌────────────────────────────────────────┐
  │ AUTO 策略: 网络好→云端，网络差→端侧   │
  │ CLOUD_ONLY: 阿里云百炼 API             │
  │ LOCAL_ONLY: 端侧 Qwen 模型             │
  │ SAVE_DATA: 省流量模式                  │
  └────────────────────────────────────────┘
       │
       ▼
  SocraticEngineV2（启发式教学）
  → 不给直接答案，生成引导性问题
  → PedagogyEngine 适配学段语言风格
       │
       ▼
  流式回复展示 + TTS 语音播报（可选）
       │
       ▼
  数据持久化（Room）
  → 对话历史 / 错题本 / 学习记录 / 进度同步

2.2 用户角色与权限

角色	权限范围
学生（主用户）	全功能使用，受学段限制
家长	查看学习报告、设置时长限制、内容过滤
系统	模型管理、推送复习提醒

2.3 学段业务差异

学段	品牌	主色调	核心功能侧重
小学（1-6年级）	AI小导师	珊瑚红/青绿（活泼）	语音问答、趣味数学、拼音识字
初中（7-9年级）	AI学伴	天蓝/翠绿（清新）	多科辅导、错题本、学习计划
高中（10-12年级）	AI导师	深蓝灰/强调红（专业）	深度解题、真题解析、备考策略
大学	AI学术助手	统一高中主题	文献阅读、论文指导、代码调试
研究生	AI研究伙伴	统一高中主题	研究设计、论文润色、投稿指导

---

3. 需求清单

完整需求见 docs/REQUIREMENT.md (v1.0, 2026-04-07)

3.1 小学版功能 (AI小导师)

ID	功能	优先级	完成状态
ES-001	语音作业辅导（童声问答，逐步引导）	P0	✅
ES-002	趣味数学题（游戏化练习，积分系统）	P0	✅
ES-003	拼音识字（拍照识字+语音跟读评分）	P0	✅
ES-004	英语启蒙（词汇+对话+牛津Let's Go资源）	P0	✅
ES-005	家长控制（时长限制+内容过滤+密码锁）	P0	✅
ES-006	学习报告（可视化卡通日报）	P1	✅
ES-007	习惯养成（打卡+成就系统）	P1	✅
ES-008	视力保护（20分钟提醒+蓝光过滤）	P1	✅

3.2 初中版功能 (AI学伴)

ID	功能	优先级	完成状态
MS-001	多学科辅导（语数英物化生政史地 9 科）	P0	✅
MS-002	错题本（拍照+OCR+自动分类+定期推送）	P0	✅
MS-003	学习计划（基于考试日期生成复习计划）	P0	✅
MS-004	知识点图谱（可视化知识关联）	P0	✅
MS-005	作文批改（结构+语法纠错）	P1	✅
MS-006	实验模拟（理化生实验步骤引导）	P1	✅
MS-007	记忆卡片（艾宾浩斯记忆法）	P1	✅
MS-008	心态调节（考前压力疏导）	P2	✅

3.3 高中版功能 (AI导师)

ID	功能	优先级	完成状态
HS-001	深度解题（分步解析+一题多解）	P0	✅
HS-002	专题突破（薄弱知识点专项训练）	P0	✅
HS-003	真题解析（近10年高考真题）	P0	✅
HS-004	知识点串联（跨学科关联分析）	P0	✅
HS-005	议论文指导（论点/论据/结构）	P1	✅
HS-006	实验设计（综合实验设计指导）	P1	✅
HS-007	备考策略（各科时间分配建议）	P1	✅
HS-008	志愿咨询（兴趣+成绩→专业建议）	P2	✅

3.4 大学/研究生版

ID	功能	优先级	完成状态
UG-001~008	文献阅读/论文大纲/代码调试/概念深化/学习小组/技能学习/时间管理/职业探索	P0~P2	✅
PG-001~008	研究设计/文献综述/数据分析/论文润色/投稿指导/学术规范/研究日志/创新思维	P0~P2	✅

3.5 通用功能

ID	功能	优先级	完成状态
GF-001	学段自适应（UI+内容+语言风格自动切换）	P0	✅
GF-002	语音交互（ASR + TTS，可调语速）	P0	✅
GF-003	拍照识别（题目/文档/手写笔记 OCR）	P0	✅
GF-004	手写输入（数学公式/化学方程式识别）	P0	✅
GF-005	个性化模型（按学段下载对应模型）	P0	✅
GF-006	离线百科（学科知识图谱离线查询）	P0	✅
GF-007	进度同步（加密云端备份）	P1	✅
GF-008	家长端（学习报告查看，独立APP待开发）	P1	⚠️ 应用内实现

3.6 非功能需求

类别	需求	状态
响应时间	简单问题<3s / 复杂问题<10s	✅ 满足
启动时间	冷启动<5s	✅ 满足
系统版本	Android 8.0+ (minSdk=26)	✅ 满足
数据安全	本地存储，不上传个人信息	✅ 满足
内容安全	不当内容过滤，年龄分级	✅ 满足
无障碍	视力/听力障碍辅助	✅ 满足
本地化	简中/繁中/英文	✅ 满足

---

4. 系统设计

完整设计见 design/DESIGN.md (v1.0, 2026-04-08)

4.1 架构分层

┌──────────────────────────── 表现层 (Presentation) ────────────────────────────┐
│  Jetpack Compose UI ← ViewModel (StateFlow) ← UiState/Event                  │
└───────────────────────────────────────────────────────────────────────────────┘
                                    ↑ UseCase
┌──────────────────────────── 领域层 (Domain) ──────────────────────────────────┐
│  UseCase + Domain Entity (User/ChatMessage/WrongQuestion/...) + Repository I/F │
└───────────────────────────────────────────────────────────────────────────────┘
                                    ↑ Repository Impl
┌──────────────────────────── 数据层 (Data) ────────────────────────────────────┐
│  Repository Impl → Room DB (DAO/Entity) + DataStore + 云端 API (可选)         │
└───────────────────────────────────────────────────────────────────────────────┘

4.2 技术栈

层次	技术选型
开发语言	Kotlin 1.9+
UI 框架	Jetpack Compose (BOM 2024.02.00)
架构模式	MVVM + Clean Architecture
依赖注入	Hilt 2.50
本地存储	Room 2.6.1 + DataStore
异步处理	Kotlin Coroutines + Flow
端侧推理	TensorFlow Lite (LiteRT 2.15)
云端推理	阿里云百炼 API (Qwen-Max)
OCR	ML Kit Text Recognition Chinese 16.0
手写识别	ML Kit Digital Ink 18.0
语音识别	Vosk 0.3（离线 ASR）
语音合成	Android TextToSpeech
图片加载	Coil 2.5

4.3 核心模块说明

模块	路径	职责
HybridLLMEngine	core/ai/	自动在云端/端侧推理间切换
CloudLLMEngine	core/ai/	阿里云百炼 API 调用，支持流式返回
QwenEngine	core/ai/	TFLite 端侧推理封装
SocraticEngineV2	core/ai/	LLM驱动的苏格拉底引导式问答
PedagogyEngine	core/education/	学段语言风格适配
ModelManager	core/ai/	模型下载/切换/版本管理
TextRecognizer	core/ocr/	ML Kit OCR 封装
VoiceManager	core/interaction/	ASR + TTS 管理
HandwritingInputView	core/multimodal/	手写公式识别（含 Stroke/Point 定义）
OfflineVoiceRecognizer	core/interaction/	Vosk 离线语音识别
SettingsDataStore	data/local/datastore/	用户设置持久化（API Key 等）
CloudSyncManager	data/remote/	云端进度同步

4.4 数据库表设计

表名	实体类	主要字段
users	UserEntity	id, name, grade, stageId, educationStage, lastActiveAt
chat_sessions	ChatSessionEntity	id, userId, title, isPinned, createdAt
chat_messages	ChatMessageEntity	id, sessionId, role, content, mediaUrl, timestamp
wrong_questions	WrongQuestionEntity	id, userId, subject, knowledgePoint, questionContent, wrongAnswer, correctAnswer, reviewCount
learning_plans	LearningPlanEntity	id, userId, title, startDate, endDate, status, progress
learning_records	LearningRecordEntity	id, userId, subject, topic, duration, performance
knowledge_mastery	KnowledgeMasteryEntity	id, userId, subject, knowledgePoint, masteryLevel

4.5 依赖注入模块

DI 模块	提供内容
AppModule	OkHttpClient, Retrofit, Context
DatabaseModule	EduAIDatabase, 各 DAO
RepositoryModule	@Binds: ChatRepository, UserRepository 接口→实现
AIModule	LLMEngine, HybridLLMEngine, CloudLLMEngine, ModelManager
UseCaseModule	SendMessageUseCase, GetChatHistoryUseCase, ...
NetworkModule	网络相关 Bean

4.6 推理策略

推理模式（InferenceMode）:
  AUTO       → 有网: 云端, 无网: 端侧, 无模型: 模拟
  CLOUD_ONLY → 仅云端（需 API Key）
  LOCAL_ONLY → 仅端侧（需下载模型）
  SAVE_DATA  → 省流量（优先端侧）

云端模型: 阿里云百炼 Qwen-Max
端侧模型:
  小学 → Qwen2.5-1.5B-Instruct GGUF (~1.2 GB)
  初中 → Qwen2.5-3B-Instruct  GGUF (~1.8 GB)
  高中 → Qwen2.5-3B-Instruct  GGUF (~1.8 GB)
  大学+ → Qwen2.5-7B-Instruct-GPTQ (~4 GB)

---

5. 功能清单

5.1 已实现功能模块（按目录）

feature/
├── encyclopedia/     离线百科（知识图谱查询）
├── grade/            年级选择（学段切换）
├── graduate/         研究生功能（研究设计/论文/数据分析）
├── handwriting/      手写公式识别（ML Kit Digital Ink）
├── home/             首页（学段差异化首页）
├── junior/           初中功能（实验模拟/作文批改/记忆卡片）
├── knowledge/        知识图谱可视化
├── learningmethod/   学习方法（归纳法/演绎法/费曼技巧等）
├── parent/           家长控制（时长/密码/报告）
├── planning/         学习计划（日历/打卡/艾宾浩斯复习）
├── primary/          小学功能（趣味数学/拼音识字/英语启蒙）
├── qa/               核心问答（文字/语音/拍照/手写多模态）
├── senior/           高中功能（真题解析/专题突破/志愿咨询）
├── settings/         设置（API Key/语言/主题/模型管理）
├── socratic/         苏格拉底引擎 UI
├── studygroup/       学习小组
├── subject/          9 科学科辅导（数/语/英/物/化/生/政/史/地）
└── wrongbook/        错题本（录入/分类/复习/统计）

5.2 AI 能力功能

功能	技术实现	状态
云端 LLM 对话	阿里云百炼 Qwen-Max	✅
端侧 LLM 推理	TFLite + QwenEngine	✅
混合推理自动切换	HybridLLMEngine	✅
苏格拉底启发式问答	SocraticEngineV2	✅
学段语言风格适配	PedagogyEngine	✅
拍照 OCR 识题	ML Kit Text Recognition	✅
手写公式识别	ML Kit Digital Ink	✅
语音识题（离线）	Vosk ASR	✅
语音朗读	Android TTS	✅
知识图谱推理	KnowledgeGraph	✅
API Key 动态配置	SettingsDataStore	✅

5.3 UI 功能

功能	说明	状态
三套学段主题	小学（珊瑚红）/ 初中（天蓝）/ 高中（深蓝灰）	✅
深色模式	ThemeManager 动态切换	✅
繁体中文/英文界面	国际化 strings.xml	✅
无障碍支持	视力/听力障碍辅助	✅
流式回复动画	Compose LazyColumn 动态更新	✅
视力保护提醒	每20分钟弹窗	✅

---

6. 代码规模

6.1 总体规模

指标	数值
Kotlin 源文件数	183 个
Kotlin 代码行数	55,239 行
资源文件（res/）	XML + 图片等若干
文档文件	20+ 个 Markdown

6.2 各层模块分布

模块目录	文件数	职责说明
feature/	93 个	所有功能页面（UI + ViewModel）
data/	26 个	数据层（DAO/Entity/Repository实现/DataStore）
core/	25 个	核心引擎（AI/OCR/语音/教育/多模态）
domain/	19 个	领域模型 + 接口 + UseCase
ui/	11 个	主题 / 导航 / 通用组件
di/	6 个	依赖注入模块
util/	1 个	工具类
根目录	2 个	Application + MainActivity

6.3 feature 子模块文件分布

子模块	文件数	备注
subject/	21	9 科学科辅导（最大模块）
senior/	11	高中专项功能
primary/	8	小学专项功能
wrongbook/	7	错题本（含统计/复习）
settings/	7	设置（含模型管理）
junior/	7	初中专项功能
handwriting/	5	手写识别
home/	5	首页
learningmethod/	5	学习方法
qa/	5	核心问答
其他	13	其余各功能模块

6.4 构建产物

产物	说明
Debug APK	app/build/outputs/apk/debug/app-debug.apk
构建工具	Gradle 8.5 + AGP
编译结果	BUILD SUCCESSFUL（-x lint）
Hilt 状态	依赖注入全部正常
Lint 状态	51 个可忽略的 NewApi 警告（已建议配置 baseline）

---

7. 关键决策与已知限制

7.1 关键架构决策

决策	原因
Clean Architecture（三层分离）	可测试、可维护，UseCaseModule 与数据层解耦
混合推理（云端优先+端侧兜底）	平衡推理质量与离线可用性
两套同名 model 类（domain/data）	领域模型与数据模型独立演化，互不污染
SettingsDataStore 存储 API Key	安全 DataStore 持久化，跨重启保留 Key
SocraticEngineV2 用 LLM 驱动	优于规则引擎，引导问题更自然
Hilt 全局 DI	Repository 接口通过 @Binds 绑定实现，便于 Mock 测试

7.2 已知限制

限制	影响	建议处理时机
端侧 Tokenizer 简化实现	端侧推理 token 截断可能不准确	短期（1-2周）
家长端独立 APP 未开发	家长需在主 App 内操作	中期（1-2月）
云端同步需自建后端	CloudSyncManager API 已写，但无配套服务器	中期
Lint 未通过（NewApi）	不影响运行，但 CI 需配置 lint-baseline	短期
端侧模型需手动下载	首次使用需联网拉取模型文件	长期持续优化

7.3 包结构注意事项（重要）

data.model      ←→  domain.model
ChatMessage         ChatMessage
ChatSession         ChatSession
Subject             Subject（有 displayName 属性）
（带构造参数）       （无构造参数）

⚠️ 两套同名类各自独立，不同文件导入各自包，不混用。

---

8. 后续维护迭代建议

8.1 短期（1-2 周）

1. 修复 Lint baseline

   // app/build.gradle.kts 中添加
   android { lint { baseline = file("lint-baseline.xml") } }
   // 运行: ./gradlew updateLintBaseline

2. 完善端侧 Tokenizer ：替换 QwenEngine.kt 中简化的 BPE 实现，使用 sentencepiece 或 tiktoken JNI 绑定

3. 添加模型下载进度 UI ：ModelManager 已有 downloadModel，补充 DownloadScreen 展示进度条

8.2 中期（1-2 月）

1. 独立家长端 APP
   • 复用 data/ 层通过加密数据库访问
   • 主要功能：学习时长报表、错题查看、时长设置
2. 云端同步后端部署
   • 接口已在 CloudSyncManager.kt 定义
   • 建议使用 Spring Boot / Go 搭建简单 REST API
3. 增加单元测试覆盖
   • 优先覆盖：SocraticEngineV2、HybridLLMEngine、WrongBookRepository

8.3 长期（3-6 月）

1. 接入更多端侧模型：支持 Gemma、Phi-3 等 GGUF 格式模型切换
2. 增强多模态能力：视频拍题（帧提取 OCR）、数学公式渲染（LaTeX to MathView）
3. iOS 版本：复用 AI 引擎逻辑，通过 KMM 或 Flutter 重写 UI 层
4. 学校端管理后台：班级作业发布、学情分析报告（B 端扩展）
5. 模型微调：收集真实学生提问数据，微调 Qwen 教育专用版

8.4 关键维护入口文件

维护场景	关键文件
修改 AI 推理逻辑	core/ai/HybridLLMEngine.kt
更换/新增云端 API	core/ai/CloudLLMEngine.kt
添加新学科	feature/subject/ + domain/model/Subject.kt
修改学段功能	feature/primary/, feature/junior/, feature/senior/
添加新 DI 绑定	di/RepositoryModule.kt, di/AIModule.kt
修改数据库结构	data/local/database/entity/ + DAO + 数据库迁移
修改用户设置	data/local/datastore/SettingsDataStore.kt
修改主题色	ui/theme/Theme.kt
修改导航流程	ui/navigation/Navigation.kt

---

9. 附录：Git 提交历史

提交号	日期	说明
4c9cc93	2026-04-12	fix: 修复Hilt依赖注入MissingBinding错误，完成项目打包 ✅ 当前版本
2927491	2026-04-11	fix: 修复大模型功能及多模态交互问题
a2a10f2	2026-04-11	fix: 修复模型管理模块编译错误和回调问题
15b266c	2026-04-10	feat: 完成学伴AI全部功能开发（P0/P1/P2）
d6085d9	2026-04-10	fix: 修复编译错误，完成P0/P1/P2全部功能
6f620de	2026-04-10	feat: 完成P1/P2全部功能开发
8fdaaad	2026-04-09	feat: 实现年级选择功能，解决学段切换问题
5748bec	2026-04-09	fix: 修复编译错误和Hilt重复绑定问题

---