AIGC Visual Math

AIGC Visual Math 是一个面向中小学平面几何题的移动端数学解析应用。应用支持拍照或从相册导入题目图片，框选题目区域后调用 OCR 与大模型完成题目清洗、启发式解析、动态几何交互生成，并支持历史记录、收藏、动画回放、分步拆解和自由探索。

核心功能

• 拍照搜题：调用系统相机拍摄纸质题目、试卷或课堂材料。
• 相册导入：从相册选择电子版题目截图。
• 题目框选：对拍摄或导入的图片进行题目区域裁剪，减少 OCR 干扰。
• OCR 清洗：使用 Vivo OCR 获取原始文字，再由大模型整理为规范数学题干。
• 启发式解析：大模型输出结构化 JSON，生成 Markdown/LaTeX 解析内容。
• 动态交互：大模型输出受限 JSXGraph 代码或 geometry_spec，在 WebView 中渲染几何交互图。
• 分步拆解：按关键步骤展示构造、折叠、拉直、验证等过程。
• 动画回放：通过 window.setAnimProgress(ratio) 控制动点从初始状态移动到目标状态。
• 自由探索：允许用户拖动指定动点观察几何关系变化。
• 历史与收藏：保存题目图片、识别文本、解析内容、交互代码和步骤名称。
• 调试端口：应用启动后自动开启本机调试服务，便于热推送解析、交互代码和步骤名。

技术栈

• Flutter / Dart
• Android 包名：com.aigc.visualmath
• Vivo OCR 与 Vivo 大模型接口
• WebView 渲染本地 MathJax 与 JSXGraph
• SharedPreferences 保存模型、Prompt 与调试配置
• 本地文件存储历史记录与题目图片

大模型调用链路

应用的大模型调用分为三层：

1. OCR 清洗模型

   • 输入：Vivo OCR 返回的原始文本。
   • 输出：规范数学题干，统一 LaTeX 表达。
   • 入口：ApiService.askLLM(...)

2. 数学解析模型

   • 输入：清洗后的题目文本。
   • 输出：严格 JSON，包含：
     • latex_steps：解析内容，标题以 ### 开头，并包含 ### 【交互探索指南】。
     • key_steps：3 到 5 个分步按钮名称。
     • jsx_guidance：给交互生成模型的绘图约束说明。
   • 入口：ApiService.askMathLLM(...)

3. 动态交互模型

   • 输入：题目文本与 jsx_guidance。
   • 输出：geometry_spec 或受限 JSXGraph 代码。
   • 运行约束：
     • 使用应用注入的 board，不能重新初始化 JSXGraph 容器。
     • 必须实现 window.setStep(stepIndex)。
     • 必须实现 window.setAnimProgress(ratio)。
     • 文字元素固定，不参与拖动。
     • 动点必须是真实可见点或 glider，动画必须改变可见几何对象。
   • 入口：ApiService.askJsxLLM(...)

当交互代码运行失败时，应用会调用 ApiService.repairJsxLLM(...) 对 JSXGraph 代码进行修复。

核心代码文件

• lib/api_service.dart

  • Vivo OCR 请求
  • Vivo 大模型请求
  • OCR 清洗、数学解析、交互生成、交互修复接口

• lib/about_page.dart

  • 默认 Prompt
  • 模型选择
  • Vivo 通道配置
  • 隐藏开发者设置入口

• lib/result_page.dart

  • OCR、清洗、解析、交互生成的主流程编排
  • MathJax 解析渲染
  • JSXGraph 交互渲染
  • 调试推送覆盖逻辑
  • 历史与收藏保存

• lib/geometry_spec_compiler.dart

  • 将模型输出的结构化 geometry_spec 编译为受控 JSXGraph 代码
  • 降低模型直接生成 JavaScript 的不稳定性

• lib/debug_server.dart

  • 应用启动时开启 127.0.0.1:8080 调试服务
  • 支持分别推送解析内容、交互代码和分步按钮名称

• lib/sandbox_page.dart

  • App 内调试页面
  • 可本地预览解析内容和 JSXGraph 交互效果

• lib/home_page.dart

  • 首页拍照、相册导入、使用指引、历史、收藏入口

• lib/crop_page.dart

  • 图片裁剪与题目框选

• lib/library_page.dart

  • 历史记录与收藏页面

• lib/saved_problem.dart、lib/saved_problem_store.dart

  • 题目图片、解析内容、交互代码和收藏状态的本地持久化

调试方式

应用启动后会自动开启本机调试端口。使用 USB 调试连接手机后，在电脑执行：

adb forward tcp:8080 tcp:8080

然后在浏览器打开：

http://127.0.0.1:8080/

调试页支持：

• 全局保存模型与 Prompt 配置。
• 只推送解析内容。
• 只推送交互代码。
• 只推送分步按钮名称。
• 同步覆盖 App 内调试页和已打开的解析页。

运行项目

安装 Flutter SDK 后，在项目根目录执行：

flutter pub get
flutter run

构建 Android release APK：

flutter build apk --release

构建产物位置：

build/app/outputs/flutter-apk/app-release.apk

模型配置说明

默认模型为：

qwen3.5-plus

设置页支持以下模型选项：

qwen3.5-plus
Volc-DeepSeek-V3.2
Doubao-Seed-2.0-pro

请在隐藏设置中配置自己的 Vivo AppID 与 API Key。版本号连续点击六次可开启隐藏开发者设置。

比赛提交建议

如果只提交“核心功能调用大模型的代码包”，建议至少包含：

lib/api_service.dart
lib/about_page.dart
lib/result_page.dart
lib/geometry_spec_compiler.dart

如果需要可复现调试与演示，建议补充：

lib/debug_server.dart
lib/sandbox_page.dart
pubspec.yaml
assets/web/tex-svg.js

如果需要完整运行项目，则提交整个 Flutter 工程。

当前状态

• 支持拍照与相册导入。
• 支持题目框选。
• 支持 OCR 清洗、数学解析、动态交互生成。
• 支持横屏与竖屏展示。
• 支持动画回放、分步拆解、自由探索。
• 支持历史记录与收藏。
• 支持调试端口热推送。