每一个技术选型背后都有明确的取舍逻辑
选择 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 用于键值偏好（主题、年级、用户设置）。优势：零服务器成本、用户数据完全本地化、离线可用、隐私安全。
从拍照到交互式可视化的三阶段 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 Web API Proxy | 自建代理 | Node.js 反向代理服务（deploy/proxy_server.js），运行于 mathmate.top 服务器。提供 /api/deepseek、/api/vivo、/api/volc 三条代理路由，将 Flutter Web 客户端请求转发至上游 AI API，在服务端注入真实 API Key，实现密钥安全隔离。Nginx 配置 120s 超时以适配 AI 长推理 |
/var/www/mathmate，Nginx SPA 模式托管deploy/proxy_server.js) 运行于 127.0.0.1:3001，PM2 守护进程管理.env.web（API Key 设为 web-proxy，URL 指向 mathmate.top/api/*），真实密钥仅存储在服务端 .env.server 中/api/* 请求转发至 Node.js，/* 静态资源由 Nginx 直接服务（30 天缓存）三大模型各司其职，协同覆盖 OCR / 推理 / 对话全链路
deepseek-v4-flash (DeepSeek-V4) · 可切换 deepseek-chatdoubao-seed-2-0-pro-260215（通用推理）doubao-seed-1-8-251228（OCR 专用，通过 VOLC_OCR_MODEL_ID 独立配置）qwen3.6-flash-2026-04-16（默认）· 可切换 qwen-plus / qwen-turbo / qwen-max| 服务模块 | 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 | 火山引擎 | 数学图片 | 公式识别 + 结构化文本 |
13 个版本的持续演进，从核心流水线到全平台支持
基于实际使用测试的关键性能数据
| 对比维度 | MathMate | 传统搜题 | 在线教育 | 通用大模型 |
|---|---|---|---|---|
| 即时答疑 | 96 | 72 | 52 | 85 |
| 数学可视化 | 97 | 35 | 58 | 20 |
| 个性化学习 | 88 | 60 | 76 | 55 |
| 成本性价比 | 92 | 78 | 42 | 82 |
| 解题逻辑深度 | 94 | 48 | 71 | 65 |
| 用户体验 | 89 | 70 | 74 | 76 |
| 动态几何画板 | 95 | — | — | 22 |
| 专用可视化引擎 | 97 | — | — | 18 |
学习并参考的优秀开源项目，推动 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