MathModelAgent：用多智能体自动产出Typst建模论文
给数学建模参赛者自动写代码和Typst论文，还保留Jupyter过程，不只是生成文字。
GitHub jihe520/MathModelAgent 更新 2026-09-12 分支 main 星标 4.9K 分叉 393
Python Vue 数学建模 Typst Claude Code Jupyter Redis Tavily ChromaDB

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你需要用17套Typst模板快速生成中英文竞赛论文。
    README 的“SKILLS / Intro”章节写明内置17套Typst论文模板，覆盖国赛、华数杯、华为杯和MCM/ICM。
  • 你使用Claude Code或Codex，并希望用一条命令串联完整建模流程。
    README 的“Install & Usage”章节提供`npx skills add jihe520/MathModelAgent --all`，并使用`/1start-mathmodel`或`$start-mathmodel`运行。
  • 你需要代码保存在Jupyter Notebook中，后续继续编辑。
    README 的“功能特性”章节说明local Interpreter基于jupyter，代码保存为notebook；部署结果包含`notebook.ipynb`。
  • 你希望接入Tavily搜索、ChromaDB知识库或HIL审批。
    README 的“新功能配置”章节列出`SEARCH_ENABLED`、`RAG_ENABLED`和`HIL_ENABLED`配置开关。

不适合，如果你

  • 你要求当前系统直接产出可保证国赛获奖的论文。
    README 的免责声明明确写着“目前水平直接参加国赛获奖是不可能的”。
  • 你不能接受实验项目、频繁变更和已知Bug。
    README 的“贡献和开发”章节称项目处于开发实验阶段，变更较多，还存在许多Bug。
  • 你必须使用已明确商业许可的组件或进行商业使用。
    项目元数据显示许可协议Not specified；README“版权License”章节写明个人免费使用、请勿商业用途。
  • 你的Windows安装流程不能接受未签名程序和SmartScreen提示。
    README“桌面版”章节警告Windows安装包当前未签名，首次运行可能出现Microsoft Defender SmartScreen提示。

前置条件

  • 桌面版需要填入模型API Key；macOS提供`mathmodel--arm64.dmg`和`mathmodel--x64.dmg`，Windows提供`mathmodel--x64.exe`。
  • Docker方案要求电脑安装Docker，并通过`docker-compose up`启动。
  • 本地部署要求安装Python、Nodejs和Redis；后端使用`uv sync`，前端使用`pnpm i`。
  • 启用Web Search需要Tavily API Key，并在`backend/.env.dev`设置`TAVILY_API_KEY=tvly-xxx`。
  • SKILLS方式需要Claude Code或Codex；README给出的安装命令是`npx skills add jihe520/MathModelAgent --all`。

第一步命令（README 原文）

npx skills add jihe520/MathModelAgent --all

要注意

  • Windows安装包未签名，需从官方Releases页面下载并处理SmartScreen提示。
    README“桌面版”章节的Windows安装警告。
  • 本地后端需要正确设置`REDIS_URL=redis://localhost:6379/0`并启动`redis-server`。
    README“本地部署”章节的环境变量和启动命令。
  • Web Search、RAG和HIL默认关闭，未配置外部依赖时会自动降级跳过。
    README“新功能配置”章节。
  • 运行产物位于`backend/project/work_dir/xxx/*`，主要包括`notebook.ipynb`和`res.md`。
    README“使用教程”章节的运行结果说明。
  • master分支的CLI部署更简单，但README写明未来不会更新。
    README“使用教程”章节关于master分支的说明。

替代方案

  • MathModelAgent桌面版：不想安装Python、Node.js、Redis或手动配置SKILL时，README推荐直接下载桌面版。
    README“桌面版（推荐使用方式）”章节
  • Docker部署：希望用单条`docker-compose up`启动前后端，并访问`localhost:5173`和`localhost:8000`时更合适。
    README“方案一：Docker部署”章节
  • 本地部署：需要修改Python后端、Vue前端或参与项目开发时更合适，但必须维护Redis、Python和Nodejs环境。
    README“方案二：本地部署”章节

材料未说明

  • README没有说明支持的具体模型名称、各模型API成本和推荐模型组合。
  • README没有给出桌面版最新Release的具体版本号、安装包大小或硬件要求。
  • README没有提供17套Typst模板分别覆盖哪些赛事的完整清单。
  • README没有提供9步验收的完整执行耗时、准确率或公开Benchmark结果。
  • README没有说明Tavily、E2B和Daytona的实际调用成本及数据隐私边界。
  • README没有明确说明生成论文是否经过人工事实核验或引用质量评估。
  • 项目元数据显示License为Not specified，但README引用了`docs/md/License.md`；两者的法律关系需要进一步确认。

💡 深度解析

6
适合 我使用 Windows 64 位，没有安装 Python、Node.js 和 Redis，只想配置一个模型 API Key 后快速试用；应该选择这个项目的桌面版吗？
适合读者： 使用 Windows 64 位、没有 Python/Node.js/Redis 环境、只想快速试用桌面版的数学建模学生

适合，Windows 64 位且不想配置开发环境的用户应优先选择桌面版，但首次运行要处理未签名安装包的 SmartScreen 提示。

  • README 推荐桌面版，并说明它内置 Claude Code 与全套 MathModelAgent SKILLS，无需安装 Python、Node.js、Redis，装好后配置一个模型 API Key 即可开始。
  • Windows 64 位对应下载文件 mathmodel--x64.exe，比本地部署少了 Redis、后端、前端和 pnpm 的安装步骤。
  • README 明确警告 Windows 安装包当前未签名，首次安装或运行可能出现 Microsoft Defender SmartScreen；官方要求从 Releases 页面下载并选择“更多信息”→“仍要运行”。
  • 若之后要修改源码或开发 Skill，桌面版不再是最合适路径，README 将本地部署定位为项目开发者方案。
  • 桌面版：无需安装 Python / Node.js / Redis，只需填一个模型 API Key
  • 桌面版：Windows 64 位 `mathmodel--x64.exe`
  • WARNING：Windows 安装包当前未签名，可能出现 Microsoft Defender SmartScreen 提示
  • 方案二：本地部署（推荐项目开发者部署）
材料未说明：README 没有说明 Windows 桌面版的最低系统版本和安装包哈希；README 没有说明桌面版是否支持离线运行或本地模型
不适合 我想在现有建模应用中启用 Tavily 搜索、ChromaDB + Rerank、HIL 六种决策动作和 Fallback 模型；这个项目是否已经适合直接作为生产质量控制方案？
适合读者： 希望用 Tavily、ChromaDB + Rerank、HIL 和备用模型提升论文质量的建模应用开发者

不适合直接当作生产级质量控制方案，适合作为包含多种质量机制的实验性参考实现。

  • README 提供 SEARCH_ENABLED、TAVILY_API_KEY、RAG_ENABLED、HIL_ENABLED 以及 FALLBACK_*、EVALUATOR_* 配置，覆盖联网搜索、知识检索、人工审批、备用模型和反馈重跑。
  • HIL 支持 confirm、edit、regenerate、ask、skip、abort 六种动作；SKILLS 还宣称有 9 步自动验收，包含文本泄漏、数值一致性、Typst 编译和 PDF 检查。
  • 但是项目仍标为实验探索迭代 demo，README 将 benchmark 列在后期计划，且没有给出这些机制的失败率、吞吐量、成本或真实题目评测。
  • Tavily、模型 API、ChromaDB/Rerank 和评估器都会引入外部依赖；配置项存在不等于质量门禁已经经过生产验证。
  • 新功能配置：`SEARCH_ENABLED` + `TAVILY_API_KEY`、`RAG_ENABLED`、`HIL_ENABLED`、`FALLBACK_*`、`EVALUATOR_*`
  • SKILLS：9 步自动验收
  • HIL：支持 confirm / edit / regenerate / ask / skip / abort
  • 后期计划：添加 benchmark
  • 视频demo：项目处于实验探索迭代demo阶段
npx skills add jihe520/MathModelAgent --all
材料未说明：README 没有说明各质量机制的测试覆盖率、错误率、延迟和成本；README 没有说明 RAG 重排模型、评估器评分标准和生产告警机制；项目数据中的 license 为 Unknown，商业集成前的授权边界未明确
适合 我已经使用 Claude Code 和 Codex，希望把建模、代码和论文步骤拆成可替换的 SKILLS，并针对国赛或 MCM/ICM 修改 Typst 模板；这个项目适合做工作流底座吗？
适合读者： 使用 Claude Code 或 Codex、希望通过 SKILLS 定制建模流程和赛事模板的高级用户

适合，它把数学建模流程拆成可独立调用的 SKILLS，并允许扩展模板和知识库；但它更像基础模板，不是已经验证完毕的通用工作流平台。

  • README 明确写出“不再做 Harness 层”，可直接在 Claude Code、Codex 等 Harness 中驱动。
  • /1start-mathmodel 会串联分析、建模、编码、绘图、论文排版和验收，也支持只运行分析或只写论文等独立 Skill。
  • 项目内置 17 套 Typst 模板，覆盖国赛、华数杯、华为杯和 MCM/ICM；模板、Prompt 与知识库均可扩展。
  • README 同时称该 SKILL 是“基础模板”，而且英文支持、LaTeX、视觉模型和 R/MATLAB 等仍列在后期计划中。因此定制 Typst 路线较合适，不能假设其他排版或语言已经成熟。
  • SKILLS：项目蒸馏成完全由 SKILLS 驱动；不再做 Harness 层
  • SKILLS：一条 `/1start-mathmodel` 命令全自动完成
  • SKILLS：每个阶段是独立 Skill；模板和知识库可自由扩展
  • SKILLS：17 套 Typst 论文模板
  • Thinking：此 SKILL 是一个基础模板
npx skills add jihe520/MathModelAgent --all
材料未说明：README 没有给出各 SKILL 的输入输出协议和版本兼容规则；README 没有提供不同 Harness 下的回归测试结果或 benchmark
视情况 我们参加国赛，只有 3 天时间，想在 macOS Apple 芯片电脑上用桌面版完成题目分析、代码、图表和 Typst 论文；这个项目适合直接作为参赛交付工具吗？
适合读者： 参加国赛、只有 3 天比赛时间且希望用桌面版快速生成 Typst 论文的数学建模学生团队

视情况，适合压缩建模流程和生成初稿，但不适合作为未经审查的直接参赛交付工具。

  • README 的 SKILLS 说明覆盖问题分析、建模、编码、绘图、论文排版和验收，并提供 17 套 Typst 模板，包含国赛方向。
  • macOS Apple 芯片可下载 mathmodel--arm64.dmg，桌面版无需安装 Python、Node.js、Redis，只需配置模型 API Key。
  • 项目明确处于“实验探索迭代 demo 阶段”，免责声明还指出当前水平“直接参加国赛获奖是不可能的”；因此模型假设、数据、代码结果和结论仍需团队负责。
  • 9 步验收能检查数值一致性、Typst 编译和 PDF 可视化等低级问题，但 README 没有证明数学结论已经达到竞赛获奖标准。
  • SKILLS：端到端自动化；17 套 Typst 论文模板
  • 桌面版：macOS（Apple 芯片 M 系列）`mathmodel--arm64.dmg`
  • 视频demo：项目处于实验探索迭代demo阶段
  • 免责声明：目前水平直接参加国赛获奖是不可能的
材料未说明：README 没有给出国赛真实题目的准确率、完成时间或论文获奖率；README 没有说明桌面版是否包含所有最新 SKILLS 和 17 套模板
视情况 我带高校科研训练，数据不能离开本地，希望使用 Jupyter Notebook 保存代码过程，并关闭 Tavily、E2B 和 Daytona；这个项目适合私有环境吗？
适合读者： 需要处理未公开建模数据、希望关闭联网和云端执行的高校科研训练人员

视情况，项目提供本地 Jupyter 解释器和 Docker/本地部署路径，具备私有化基础，但不能据 README 断言所有模型调用和临时文件都不会外传。

  • 功能特性写明 local Interpreter 基于 Jupyter，代码保存为 notebook，便于保留实验过程；Docker 方案可在本机提供前端和后端。
  • Web Search、RAG、HIL、Fallback 和 Evaluator 等可选功能默认关闭，未配置外部依赖时会自动降级跳过；这有利于减少不必要的外部服务连接。
  • 但项目仍需要模型 API Key，README 也支持 E2B、Daytona 等云端 code interpreter；关闭搜索并不等于模型供应商不会接收输入。
  • 未公开数据还涉及 API 留存、日志、临时文件和依赖容器的具体行为，README 没有给出数据流图或合规承诺。
  • 功能特性：local Interpreter 基于 jupyter，代码保存为 notebook
  • 新功能配置：可选功能默认已关闭，开启后未配置外部依赖时自动降级跳过
  • 功能特性：云端 code interpreter：E2B 和 daytona
  • 方案一：Docker 部署；访问前端 `http://localhost:5173`、后端 `http://localhost:8000`
docker-compose up
材料未说明：README 没有说明模型供应商的数据保留、训练使用和区域存储政策；README 没有列出日志、临时文件和 Notebook 中敏感数据的清理机制；README 没有证明 Docker 模式会阻止所有外部网络请求
适合 我需要修改 Python 后端和 Vue 前端，已经准备好 Node.js、Redis、pnpm 和 uv；相比桌面版，我是否应该采用本地部署？
适合读者： 需要在本地源码中调试 MathModelAgent 的 Python 开发者，已有 Node.js、Redis、pnpm 和 uv 环境

适合，本地部署更符合需要修改 Python 后端、Vue 前端和工作流的开发者，但环境协同成本明显高于桌面版。

  • README 将本地部署标为“推荐项目开发者部署”，要求 Python、Node.js 和 Redis，并分别启动后端与前端。
  • 后端依赖使用 uv sync，前端使用 pnpm；开发环境还要设置 ENV=DEV 与 REDIS_URL=redis://localhost:6379/0。
  • 本地路径可以直接查看和修改 SKILLS、模板、Prompt 及知识库，适合二次定制；项目数据也显示 Python、Vue、TeX、Typst 和 TypeScript 都是主要组成部分。
  • 代价是 README 没有承诺源码接口稳定，当前版本为 v0.0.19，且 Windows、macOS、Linux 的启动命令不同。若只是使用而非改代码，桌面版或 Docker 更省配置。
  • 方案二：本地部署（推荐项目开发者部署）
  • 本地部署：确保电脑中安装好 Python, Nodejs, Redis
  • 安装依赖：`uv sync`；前端：`pnpm i`
  • 设置环境变量：`export ENV=DEV`、`export REDIS_URL=redis://localhost:6379/0`
  • 项目数据：latest_release 为 v0.0.19；语言包含 Python、Vue、TypeScript、Typst
docker-compose up
材料未说明：README 没有说明当前源码分支、Python 版本、Node.js 版本和 Redis 版本的精确兼容矩阵；README 没有说明桌面版与源码版在功能和版本上的差异

✨ 核心亮点

  • 一条 /1start-mathmodel 命令串联9步验收
  • 内置17套Typst中英文竞赛模板
  • Jupyter保存代码，结果保留notebook.ipynb
  • 支持Tavily、ChromaDB与6种HIL动作
  • 项目仍处于实验阶段，README明确存在Bug

🔧 工程化

  • 用multi-agents完成分析、编码、建模和论文排版
  • local Interpreter基于Jupyter保存可编辑Notebook
  • Typst模板自动生成可提交的PDF论文
  • 可选Tavily搜索和ChromaDB加Rerank知识库

⚠️ 风险

  • README称实验阶段，存在许多Bug且变更较多
  • Windows安装包未签名，会触发SmartScreen提示
  • 本地部署依赖Python、Nodejs和Redis环境
  • 免责声明称当前水平不可能直接国赛获奖
  • License元数据未指定，README限制个人免费非商业使用

👥 适合谁？

  • 需要Typst竞赛模板和自动论文流程的建模参赛者
  • 使用Claude Code或Codex并愿安装SKILLS的开发者
  • 需要Jupyter代码留痕和Notebook再编辑的团队
  • 希望用Docker、Redis和Vue部署WebUI的开发者