每一个技术选型背后都有明确的取舍逻辑
选择 Flutter 作为唯一前端框架，而非 React Native 或原生开发。核心考量：Canvas 绘图能力是几何可视化引擎的基石，Flutter 的 CustomPaint + Canvas API 提供了 60fps 的原生渲染性能，无需 WebView 中间层。一套代码覆盖 Android、iOS、Web、桌面全平台。
不引入 Provider、Riverpod、Bloc 等状态管理框架。全部使用 StatefulWidget + setState。理由：MathMate 的页面间数据流是单向的（拍照 → 识别 → 解题 → 展示），没有复杂的全局状态共享需求。减少依赖、降低复杂度、提升可维护性。
拒绝使用现成图表库，从零构建 GeometryPainter。原因：通用图表库无法理解数学语义（如"动点在圆上滑动"的约束关系）。自研引擎实现了 GeometryJSON 协议——AI 输出结构化 JSON，引擎解析并渲染为交互式几何图形，形成"语义-图形"的完整闭环。
没有将所有 AI 任务绑定到单一模型，而是根据各模型的优势分配任务：DeepSeek 负责数学推理（解题+可视化），火山引擎 负责多模态 OCR（手写/印刷识别），Qwen-PLUS 负责流式对话。每个模型在各自领域做到最优，整体效果超越单模型方案。
Hive 保存搜题历史与对话记录，SharedPreferences 保存主题、年级、模型和能力画像等轻量状态；认证、共享题库与考试流程通过 mathmate.top/api/auth、/api/library、/api/exam 接入云端。个人学习数据优先留在设备，跨用户内容由服务端统一提供。
从拍照到交互式可视化的三阶段 AI 流水线
用户拍照后，图片经过裁剪与预处理（自动透视校正、自适应锐化、背景二值化），送入火山引擎多模态 API。AI 将手写或印刷的数学公式、文字识别为结构化的 Markdown + LaTeX 文本。SafeJsonParser 容错处理 AI 返回的非标准 JSON（如 Infinity、NaN）。
OCR 识别的数学文本送入 DeepSeek API，配合专门设计的解题 System Prompt（solve_prompt.dart）。AI 执行分步推理，输出完整的 Markdown 解题过程，包含 LaTeX 公式、步骤说明和最终答案。支持小学到大学各难度层级的数学题。
这是 MathMate 的技术核心。AI 将题目中的几何语义转化为结构化的 GeometryJSON 协议——定义视口（viewport）、几何元素（点、线、圆、椭圆、双曲线、抛物线）、动态约束（动点在曲线上滑动）。GeometryValidator 校验 JSON 合法性，GeometryPainter 使用纯 Dart Canvas 渲染为 60fps 交互式图形，支持手势拖拽动点。
纯 Dart + Flutter Canvas，零 WebView 依赖，原生 60fps
GeoElement 基类GeoPoint — 静态点（固定坐标）GeoCircle — 圆（圆心+半径）DynamicPoint — 动点（含约束目标 ID + 参数化位置）setState 触发重绘CustomPaint + GestureDetector设计 LLM 友好的 GeometryJSON Schema，包含 viewport、elements、constraint 语义
注入"几何翻译家"System Prompt，强制 AI 输出严格格式的 GeometryJSON
CustomPainter 渲染 + GestureDetector 交互 + 约束求解器
流式渲染、触觉反馈、实时 LaTeX 标签、异常降级处理
所有第三方依赖均经过选型评估，按需引入
| 库名 | 版本 | 用途 |
|---|---|---|
| Flutter SDK | Dart ^3.11.3 | 跨平台 UI 框架，Android / iOS / Web / Desktop 全平台构建 |
| flutter_localizations | SDK 内置 | 多语言本地化支持（zh_CN / en_US） |
| cupertino_icons | ^1.0.8 | iOS 风格图标集（CupertinoIcons） |
| http | ^1.1.0 | HTTP 客户端，调用 DeepSeek / 火山引擎 / Qwen API |
| path | ^1.9.1 | 跨平台路径操作工具（文件路径拼接、解析） |
| flutter_dotenv | ^5.2.1 | 从 .env 文件加载 API 密钥，安全隔离敏感配置 |
| 库名 | 版本 | 用途 |
|---|---|---|
| flutter_math_fork | ^0.7.2+1 | LaTeX / MathML 数学公式渲染（计划迁移至 flutter_tex） |
| flutter_markdown_plus | ^1.0.7 | Markdown 内容渲染，支持代码高亮和 LaTeX 行内公式 |
| image | ^4.5.4 | 图像处理库，用于拍照后的裁剪、缩放、预处理 |
| 库名 | 版本 | 用途 |
|---|---|---|
| hive | ^2.2.3 | 高性能本地 NoSQL 数据库，存储搜题历史与 AI 对话记录（v2.2.0 从 Isar 迁移） |
| hive_flutter | ^1.1.0 | Hive Flutter 绑定，提供 Widgets 集成 |
| shared_preferences | ^2.5.3 | 键值对持久化，存储用户主题/年级/设置等偏好 |
| path_provider | ^2.1.5 | 跨平台文件路径获取，数据存储目录管理 |
| 库名 | 版本 | 用途 |
|---|---|---|
| webview_flutter | ^4.10.0 | 内嵌 WebView，用于 GeoGebra 数学工具箱、KaTeX 公式可视化、B 站视频播放 |
| flutter_quill | ^11.5.0 | 富文本编辑器，支持 LaTeX 公式插入、图片、格式化 |
| image_picker | ^1.0.0 | 相机拍照与相册选取，拍照搜题入口 |
| cached_network_image | ^3.4.1 | 网络图片缓存加载，视频缩略图等 |
| ^3.11.3 | PDF 文档生成，支持 KaTeX 公式到 PDF 导出 | |
| file_picker | ^8.0.0 | 文件选择器，PDF 导入等 |
| url_launcher | ^6.3.1 | 打开外部链接（B 站视频、浏览器等） |
| share_plus | ^10.1.4 | 系统分享功能，分享解题结果 |
| permission_handler | ^11.3.1 | 运行时权限管理（相机、存储等） |
| device_info_plus | ^11.0.0 | 设备信息获取，生成唯一设备 ID |
| open_file | ^3.5.10 | 打开本地文件（PDF 等） |
| 库名 | 版本 | 用途 |
|---|---|---|
| build_runner | ^2.4.13 | Dart 代码生成工具，为 Hive 生成序列化代码 |
| hive_generator | ^2.0.1 | Hive TypeAdapter 代码生成器 |
| flutter_launcher_icons | ^0.14.2 | 自动生成多平台应用图标 |
| flutter_lints | ^6.0.0 | Flutter 官方 lint 规则集 |
| 资源 | 类型 | 用途 |
|---|---|---|
| GeoGebra Web3D | 离线嵌入 · GPL v3 | 数学可视化工具套件（科学计算器、几何画板、函数绘图、3D 视图、尺规作图、概率模型）。内含 canvas2pdf、gifshot、whammy、webfont.js 等子库 |
| KaTeX | 离线嵌入 · MIT | 高速 LaTeX 数学公式渲染，用于 WebView 中的公式可视化与 PDF 导出 |
| PDF.js | 离线嵌入 · Apache 2.0 | Mozilla 出品的 PDF 渲染引擎，用于应用内 PDF 查看与标注 |
| SimHei 字体 | 离线嵌入 | 中文黑体字体，用于 LaTeX 编译器生成含中文的 PDF 文档 |
| 库名 | 协议 | 用途 |
|---|---|---|
| Plotly.js v2.27.0 | MIT | 交互式数据可视化图表，用于手写笔记中公式分析的 WebView 可视化 |
| Chart.js | MIT | HTML5 Canvas 图表库，用于手写笔记中的图表渲染 |
| 服务 | 接入方式 | 用途 |
|---|---|---|
| Bilibili API | 公共接口 | 获取视频信息（标题、封面、播放量），用于视频推荐模块的元数据展示 |
| Bilibili Player | iframe 嵌入 | WebView 内嵌 B 站播放器，实现应用内视频学习 |
| MathMate AI API Proxy | Node.js + Nginx | deploy/proxy_server.js 为 Web 客户端代理 DeepSeek、Qwen 与火山引擎请求，在服务端注入真实 API Key，避免浏览器暴露密钥。 |
| MathMate Auth API | /api/auth | 提供验证码、登录认证与用户身份相关接口，由 AuthService 调用。 |
| 共享题库 API | /api/library | 提供题目、板块、统计和健康检查接口，支持资料库、题库与个性化练习。 |
| 考试 API | /api/exam | 支持组卷、答题提交、交卷、图片上传与判卷流程。 |
https://mathmate.top/websitedeploy/proxy_server.js) 运行于 127.0.0.1:3001，PM2 守护进程管理.env.web（API Key 设为 web-proxy，URL 指向 mathmate.top/api/*），真实密钥仅存储在服务端 .env.server 中/api/auth、/api/library 与 /api/exam 分别承载认证、共享题库和考试流程DeepSeek、火山引擎与 Qwen 按任务分工，并通过环境变量与模型选择服务进行配置
DEEPSEEK_MODEL_ID 配置；客户端模型列表包含 deepseek-v4-flash，GeoGebra Agent 默认回退为 deepseek-chatdoubao-seed-2-0-pro-260215（通用推理）doubao-seed-1-8-251228（OCR 专用，通过 VOLC_OCR_MODEL_ID 独立配置）qwen-plus（默认）· 可切换 qwen-turbo、qwen-max、qwen3.6-flash-2026-04-16 与 deepseek-v4-flash| 服务模块 | AI 模型 | 输入 | 输出 |
|---|---|---|---|
| OcrService | 火山引擎 / DeepSeek | 拍照图片 (Base64) | Markdown + LaTeX 文本 |
| SolverService | DeepSeek | 数学题文本 + 解题 Prompt | 分步解题 Markdown |
| VisualizationService | DeepSeek | 解题结果 + 可视化 Prompt | GeometryJSON |
| ChatStreamService | Qwen-PLUS | 多轮对话上下文 | SSE 流式 Markdown |
| HandwritingOcrService | 火山引擎 | 手写笔迹图片 | LaTeX 公式文本 |
| FormulaAnalysisService | 火山引擎 | 单个数学公式 | 公式分析 + 解释 |
| VideoRecommendationService | Qwen (DashScope) | 搜索历史 + 年级 | B 站视频推荐列表 |
| HistoryRepository | Qwen (DashScope) | 搜题结果文本 | 自动生成历史标题 |
| MathRecognizer | 火山引擎 | 数学图片 | 公式识别 + 结构化文本 |
持续演进至 v2.4.2，从核心解题流水线扩展到考试闭环、开放资源和四工作区产品结构
以下数据来自 v2.4.2 代码、依赖和已实现模块，不包含未经公开测试验证的主观评分
学习并参考的优秀开源项目，推动 MathMate 技术演进
工具集成推理（Tool-integrated Reasoning）。GSM8K 84.3%，MATH 51.0%。通过代码执行与外部工具协作增强数学推理。为 MathMate 的未来"工具增强推理"方向提供参考。
DeepSeek 数学推理大模型。MATH 基准 51.7%。工具使用 + Chain-of-Thought 推理。直接启发了 MathMate 选择 DeepSeek 作为核心推理引擎的技术决策。
全学科数学 Web 应用。包含知识库、离线求解、LaTeX 编辑器。其知识库架构和 API 设计为 MathMate 的知识图谱规划提供了架构参考。
手写数学表达式识别。基于深度学习，从 BTTR 改进而来。为 MathMate 的手写笔记 OCR 识别模块提供了算法参考。
精选数学学习资源合集，覆盖数学所有分支。为 MathMate 的分级视频推荐和知识点体系提供了内容结构参考。
开源动态数学软件。MathMate 将其 Web3D 版本离线嵌入 WebView，提供科学计算器、几何画板、函数绘图、3D 视图、尺规作图、概率模型六大数学工具。
一键部署的私人 AI 对话 Web 应用，支持 GPT-4 / Claude / Gemini 等 15+ 模型提供商。MathMate 借鉴了其流式对话 UI 设计、Markdown + LaTeX 渲染方案和多模型切换机制，应用于蓝心 AI 助手模块。
完全离线的 LaTeX 渲染（MathJax），Math2SVG 纯 Flutter 渲染无需 WebView。计划替代 flutter_math_fork。
本地 AI 模型推理，支持 GPU 加速（CUDA/TensorRT/CoreML/NNAPI）。为离线 OCR 和推理铺路。
Grammar of Graphics API，60fps 原生 Flutter 动画图表。计划补充/替代 GeoGebra 用于 2D 可视化。
3D 数学图形渲染（XYZ 坐标系），数学函数定义形状。用于 3D 几何可视化增强。
观看产品演示、访问在线服务、获取源代码
完整展示 MathMate 的核心功能：拍照搜题、AI 分步解题、交互式几何可视化、蓝心 AI 助手、数学工具箱、手写笔记等。Bilibili: BV1EfLJ6bEnw