学伴AI项目设计分析
项目名称: 学伴AI — 全学段启发式学习助手
平台: Android 原生应用
总结日期: 2026-04-12
当前版本: v1.0.0（Build 4c9cc93）
目录
- 项目概述
- 业务模型
- 需求清单
- 系统设计
- 功能清单
- 代码规模
- 关键决策与已知限制
- 后续维护迭代建议
- 附录：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 周）
- 修复 Lint baseline
android { lint { baseline = file("lint-baseline.xml") } }
- 完善端侧 Tokenizer：替换
QwenEngine.kt 中简化的 BPE 实现，使用 sentencepiece 或 tiktoken JNI 绑定
- 添加模型下载进度 UI：
ModelManager 已有 downloadModel，补充 DownloadScreen 展示进度条
8.2 中期（1-2 月）
- 独立家长端 APP
- 复用
data/ 层通过加密数据库访问
- 主要功能：学习时长报表、错题查看、时长设置
- 云端同步后端部署
- 接口已在
CloudSyncManager.kt 定义
- 建议使用 Spring Boot / Go 搭建简单 REST API
- 增加单元测试覆盖
- 优先覆盖：
SocraticEngineV2、HybridLLMEngine、WrongBookRepository
8.3 长期（3-6 月）
- 接入更多端侧模型：支持 Gemma、Phi-3 等 GGUF 格式模型切换
- 增强多模态能力：视频拍题（帧提取 OCR）、数学公式渲染（LaTeX to MathView）
- iOS 版本：复用 AI 引擎逻辑，通过 KMM 或 Flutter 重写 UI 层
- 学校端管理后台：班级作业发布、学情分析报告（B 端扩展）
- 模型微调：收集真实学生提问数据，微调 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重复绑定问题 |
2
0
已为社区贡献16条内容
所有评论(0)