{
  "markdown": "<h1 align=\"center\">🤖 MathModelAgent 📐</h1>\n<p align=\"center\">\n    <img src=\"./docs/icon.png\" height=\"250px\">\n</p>\n<h4 align=\"center\">\n    专为数学建模设计的 Agent<br>\n    自动完成数学建模，生成一份完整的可以直接提交的论文。\n</h4>\n\n<h5 align=\"center\">简体中文 | <a href=\"README_EN.md\">English</a></h5>\n\n<p align=\"center\">\n    <a href=\"https://github.com/jihe520/MathModelAgent/releases/latest\"><b>⬇️ 下载最新桌面版（推荐）</b></a>\n</p>\n<p align=\"center\">\n    🎨 姊妹项目：<a href=\"https://github.com/jihe520/sci-box\"><b>sci-box</b></a> —— 科研图表 & 流程图 SKILL 合集\n</p>\n\n---\n\n## 🖥️ 桌面版（推荐使用方式）\n\n> **不想折腾环境？直接下载桌面版，开箱即用。**\n>\n> 👉 **[前往 Releases 下载最新版本](https://github.com/jihe520/MathModelAgent/releases/latest)**\n\n桌面版已内置 Claude Code 与全套 MathModelAgent SKILLS，无需安装 Python / Node.js / Redis，也无需手动配置 SKILL，装好填一个模型 API Key 即可开始建模。\n\n| 系统 | 下载文件 |\n|------|----------|\n| macOS（Apple 芯片 M 系列） | `mathmodel-<version>-arm64.dmg` |\n| macOS（Intel 芯片） | `mathmodel-<version>-x64.dmg` |\n| Windows 64 位 | `mathmodel-<version>-x64.exe` |\n\nmacOS 安装包已 Developer ID 签名并通过 Apple 公证。\n\n> [!TIP]\n> 不确定自己的 Mac 是哪种芯片？点击左上角  → 关于本机，看「芯片」一栏：显示 Apple M 系列选 arm64，显示 Intel 选 x64。\n\n> [!WARNING]\n> Windows 安装包当前未签名，首次安装或运行时可能出现 Microsoft Defender SmartScreen 提示，请选择「更多信息」→「仍要运行」，并务必从官方 [Releases 页面](https://github.com/jihe520/MathModelAgent/releases/latest) 下载。\n\n安装后应用会自动检查更新（macOS 支持自动更新，Windows 待代码签名证书配置完成后启用）。\n\n如果你是开发者，想自行部署或参与贡献，请继续阅读下方的 [SKILLS](#skills) 与 [使用教程](#-使用教程)。\n\n---\n\n## 🌟 愿景：\n\n3 天的比赛时间变为 1 小时\n自动完整一份可以获奖级别的建模论文\n\n<p align=\"center\">\n    <img src=\"./docs/chat.png\">\n    <img src=\"./docs/coder.png\">\n</p>\n\n## ✨ 功能特性\n\n- 🔍 自动分析问题，数学建模，编写代码，纠正错误，撰写论文\n- 💻 Code Interpreter\n    - local Interpreter: 基于 jupyter , 代码保存为 notebook 方便再编辑\n    - 云端 code interpreter: [E2B](https://e2b.dev/) 和 [daytona](https://app.daytona.io/)\n- 📝 生成一份编排好格式的论文\n- 🤝 multi-agents: 建模手，代码手，论文手等\n- 🔄 multi-llms: 每个 agent 设置不同的、合适的模型\n- 🤖 支持所有模型: [litellm](https://docs.litellm.ai/docs/providers)\n- 💰 成本低：workflow agentless，不依赖 agent 框架\n- 🧩 自定义模板：prompt inject 为每个 subtask 单独设置需求\n- 🌐 Web Search: Agent 自主搜索互联网获取真实数据（Tavily API）\n- 📚 RAG 知识库: 从本地知识库检索建模方法、代码模板、论文写作参考（ChromaDB + Rerank）\n- 🤝 HIL 人机协作: 关键节点暂停等待用户审批，支持 6 种决策动作（confirm / edit / regenerate / ask / skip / abort）\n- 🛡️ 四层容错: 有限重试 → Fallback Hand Off → Evaluator Shadow Mode → Feedback Rerun\n\n\n\n\n---\n---\n\n我在平台中托管了一个在线版本，方便使用，欢迎体验：\n\nhttps://mathmodel.top/home\n\n## SKILLS\n\n项目蒸馏成完全由 SKILLS 驱动\n不再做 Harness 层\n\n### Intro\n\nMathModelAgent SKILL —— 直接在 Harness 中驱动的数学建模自动化方案.\n\n**💰 开源免费，接入任意模型**\n完全开源免费，可接入任何模型。\n\n**🧠 端到端自动化**\n从问题分析、建模、编码、绘图到论文排版和验收，一条 `/1start-mathmodel` 命令全自动完成，中间阶段自动串联，无需人工干预。\n\n**📄 17 套 Typst 论文模板**\n内置中英文主流赛事模板（国赛、华数杯、华为杯、MCM/ICM 等），自动匹配赛事类型，生成排版精良、可直接提交的 PDF 论文。\n\n**📐 内置建模知识库**\n包含完整的建模规范、模型选择决策树（AHP、TOPSIS、ARIMA、GA 等）、常见易错模式和 MCM/ICM 评分标准，每个阶段自动参考，降低模型幻觉。\n\n**✅ 9 步自动验收**\n文本泄漏检测 → 数值一致性校验 → Typst 编译 → PDF 可视化检查，确保论文零低级错误。\n\n**🔧 可组合、可扩展**\n每个阶段是独立 Skill，可单独调用（如只跑分析、只写论文）；模板和知识库可自由扩展；支持 Typst 生态排版。\n\n### 🎨 姊妹项目：sci-box（科研图表 & 流程图）\n\n科研绘图和流程图模板已独立成仓库 **[jihe520/sci-box](https://github.com/jihe520/sci-box)**，可单独安装、单独使用：\n\n| SKILL | 内容 |\n|-------|------|\n| `scibox-figure` | SHAP / ROC / Taylor / 云雨图 / 和弦图 / 环形热图等科研图表复刻模板（Python + Matplotlib，导出 PNG / PDF / SVG） |\n| `scibox-diagram` | 可编辑的 draw.io 模板：五层技术路线图、三栏研究框架、三栏流程图、横向任务流水线 |\n\n```\nnpx skills add jihe520/sci-box\n```\n\n![figure](./docs/figure_templates.png)\n\n\n### Install & Usage\n\n安装 SKILL\n```\nnpx skills add jihe520/MathModelAgent --all\n```\n\n运行\n```\n// claude\nclaude --dangerously-skip-permissions\nclaude: /1start-mathmodel 完成这个数学建模任务\n\n// codex\ncodex --yolo\ncodex: $start-mathmodel 完成这个数学建模任务\n```\n\n其他命令\n```\n/doctor:  检查环境配置\n/typst-author: typst 知识\n```\n\n\n### What Can You Contribute?\n\n项目以后只会做 SKLLS 层的迭代和优化，不会再做其他部分。\n\n如果你希望寻找 Agent 开发岗位，你可以研究该项目 Agent 设计并贡献，我会尽量合并.\n\n你能做什么：\n\n- 优化贡献比赛 typst Template , 你可以找一些 LaTeX 转成 typst\n- 优化 SKILL Workflow\n- 在不同的 Harness 上测试 不同的 LLM, 提供反馈和案例放在 example 仓库\n\nHarness SKILL 的优化需要大量黑盒测试和调优.\n\n\n### Thinking\n\n- 两年前，我做了一个 Mulit-Agent 的数学建模项目并开源出来，收到了社区的欢迎和很多 star, 感谢大家支持。\n- 感谢开源的 latex 模板，我在此基础上转化为 typst 模板\n- 此 SKILL 是一个基础模板，你可以基于此构建更适合你自己的 MathModel SKILL\n- For Agent DEVs : 两年前，我都是自己实现一套 Agent 框架，现在和以后更多的 Agent 产品直接基于 Harness 如 Codex / Claude Code / Pi  + SKILLS 来构建\n\n---\n---\n\n\n\n\n\n## 🚀 后期计划\n\n- [x] 添加并完成 webui、cli\n- [x] 完善的教程、文档\n- [ ] 提供 web 服务\n- [ ] 英文支持（美赛）\n- [ ] 集成 latex 模板\n- [ ] 接入视觉模型\n- [x] 添加正确文献引用\n- [x] 更多测试案例\n- [x] docker 部署\n- [ ] human in loop ( HIL ): 关键节点暂停等待用户审批，支持 6 种决策动作（confirm/edit/regenerate/ask/skip/abort）\n  <!-- TODO: 数据模型已实现，但工作流集成不完整 -->\n- [ ] feedback: 评估器评分 + 反馈注入重跑，先 Writer 后 Coder\n  <!-- TODO: 核心逻辑未实现，仅有 Agent 基类中的 TODO 注释 -->\n- [x] codeinterpreter 接入云端 如 e2b 等供应商..\n- [ ] 多语言: R 语言, matlab\n- [ ] 绘图 napki,draw.io,plantuml,svg, mermaid.js\n- [ ] 添加 benchmark\n- [ ] web search tool: Tavily API 搜索互联网获取真实数据\n  <!-- NOTE: 原计划 Tavily API 未实现，当前使用 OpenAlex 替代 -->\n- [ ] RAG 知识库: ChromaDB + Rerank 检索建模方法、代码模板、论文写作参考\n  <!-- TODO: 仅配置项存在，核心检索逻辑未实现 -->\n- [ ] A2A hand off: Fallback 自动切换备用模型 + 有限重试 + Evaluator Shadow Mode\n  <!-- TODO: 配置项和核心逻辑均未实现，仅有基础重试机制 -->\n- [ ] chat / agent mode\n\n## 视频demo\n\n<video src=\"https://github.com/user-attachments/assets/954cb607-8e7e-45c6-8b15-f85e204a0c5d\"></video>\n\n> [!CAUTION]\n> 项目处于实验探索迭代demo阶段，有许多需要改进优化改进地方，我(项目作者)很忙，有时间会优化更新\n> 欢迎贡献\n\n\n## 📖 使用教程\n\n\n提供三种部署方式，请选择最适合你的方案：\n1. [docker(最简单)](#-方案一docker-部署推荐最简单)\n2. [本地部署](#-方案二-本地部署)\n3. [脚本本地部署(社区)](#-方案三自动脚本部署来自社区)\n\n\n下载项目\n\n```bash\ngit clone https://github.com/jihe520/MathModelAgent.git # 克隆项目\n```\n\n\n> 如果你想运行 命令行版本 cli 切换到 [master](https://github.com/jihe520/MathModelAgent/tree/master) 分支,部署更简单，但未来不会更新\n\n\n\n### 🐳 方案一：Docker 部署（推荐：安全简单）\n\n> 确保电脑安装了 docker 环境\n\n1. 启动服务\n\n在项目文件夹下运行:\n\n```bash\ndocker-compose up\n```\n\n2. 访问\n\n现在你可以访问：\n- 前端界面：http://localhost:5173\n- 后端API：http://localhost:8000\n\n3. 配置\n\n侧边栏 -> 头像 -> API Key\n\n### 💻 方案二: 本地部署（推荐项目开发者部署）\n\n> 确保电脑中安装好 Python, Nodejs, **Redis** 环境\n\n\n\n#### step1:安装依赖\n\n1. 下载Redis(记得设置环境变量redis_path)\n\n- windows 下载地址：<https://github.com/tporadowski/redis/releases>\n- linux or mac 下载地址：<https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/>\n\n2. 安装后端依赖\n\n```bash\n# ============ 安装依赖 ============\n# 1. 切换到 backend 目录\ncd backend\n# 2. 安装 uv 包管理器（推荐）\npip install uv\n# 3. 同步项目依赖\nuv sync\n```\n\n```bash\n# ============ MacOS / Linux 安装命令 ============\n# 1. 设置环境变量\nexport ENV=DEV\nexport REDIS_URL=redis://localhost:6379/0\n```\n\n```powershell\n# ============ Windows PowerShell 安装命令 ============\n# 1. 设置环境变量\n$env:ENV=\"DEV\"\n$env:REDIS_URL=\"redis://localhost:6379/0\"\n# 2. 设置 PowerShell 执行策略策略为 RemoteSigned\nSet-ExecutionPolicy RemoteSigned -Scope CurrentUser\n# 3. 创建虚拟环境\npython -m venv venv\n```\n\n3.安装前端依赖\n\n```bash\ncd frontend # 切换到 frontend 目录下\nnpm install -g pnpm\npnpm i\n```\n\n#### step2:启动项目\n\n**windows用户直接双击运行项目中的win_start.bat 即可启动项目**\n\n1.启动 Redis\n\n```bash\nredis-server\n```\n\n2.启动后端\n\n```bash\n# ============ MacOS / Linux 安装命令 ============\n# 1. 激活虚拟环境\nsource .venv/bin/activate\n# 2. 启动后端服务（激活后可直接使用 uvicorn 命令）\nuvicorn app.main:app --host 0.0.0.0 --port 8000 --ws-ping-interval 60 --ws-ping-timeout 120 --reload\n```\n\n```bash\n# ============ Windows PowerShell 安装命令 ============\n# 1. 切换到 backend 目录\ncd .\\backend\\\n# 2. 激活虚拟环境\n.\\venv\\Scripts\\Activate.ps1\n# 3. 启动后端服务\nuvicorn app.main:app --host 0.0.0.0 --port 8000 --ws-ping-interval 60 --ws-ping-timeout 120 --reload\n```\n\n\n3.启动前端\n\n```bash\ncd .\\frontend\\\npnpm run dev\n```\n\n修改 backend/.env.dev 的环境变量 **REDIS_URL**\n\n配置API Key\n\n1. 使用 WebUI\n    侧边栏 -> 头像 -> API Key\n2. 修改 backend/.env.dev 文件\n    先将.env.example文件 改为.env.dev\n    然后在.env.dev中 修改各 Agent API 配置\n\n\n\n### 🚀 方案三：自动脚本部署（来自社区）\n有没有自动部署的脚本 ？\n[mmaAutoSetupRun](https://github.com/Fitia-UCAS/mmaAutoSetupRun)\n\n\n\n[教程](./docs/md/tutorial.md)\n\n运行的结果和产生在`backend/project/work_dir/xxx/*`目录下\n- notebook.ipynb: 保存运行过程中产生的代码\n- res.md: 保存最后运行产生的结果为 markdown 格式\n\n需要自定义自定义提示词模板 template ？\nPrompt Inject : [prompt](./backend/app/config/md_template.toml)\n\n网络状况太差难以配置Docker等设置？\n网络不畅时的配置过程示例：[网络环境极差时的MathModelAgent配置过程](docs/md/网络环境极差时的MathModelAgent配置过程.md)\n\n\n## ⚙️ 新功能配置\n\nMathModelAgent 支持以下可选功能，默认已关闭，开启后未配置外部依赖时自动降级跳过。详见 [升级说明](./升级说明.md)。\n\n| 功能 | 配置开关 | 说明 |\n|------|----------|------|\n| Web Search | `SEARCH_ENABLED` + `TAVILY_API_KEY` | Agent 自主联网搜索真实数据（Tavily API） |\n| RAG 知识库 | `RAG_ENABLED` | 从本地知识库检索建模方法和代码模板（ChromaDB + Rerank） |\n| HIL 人机协作 | `HIL_ENABLED` | 关键节点暂停等待用户审批，支持 6 种决策动作 |\n| Fallback Hand Off | `FALLBACK_*` 系列 | 主模型故障自动切换备用模型 |\n| Evaluator + Feedback | `EVALUATOR_*` 系列 | 输出质量评估 + 反馈重跑 |\n\n快速启用 Web Search：注册 [Tavily](https://tavily.com) 获取 API Key，在 `backend/.env.dev` 中设置 `TAVILY_API_KEY=tvly-xxx`。\n\n## 🤝 贡献和开发\n\n[DeepWiki](https://deepwiki.com/jihe520/MathModelAgent) | [Zread](https://zread.ai/jihe520/MathModelAgent)\n\n\n> [!TIP]\n> 如果你有跑出来好的案例可以提交 PR 在该仓库下:\n> [MathModelAgent-Example](https://github.com/jihe520/MathModelAgent-Example)\n\n- 项目处于**开发实验阶段**（我有时间就会更新），变更较多，还存在许多 Bug，我正着手修复。\n- 希望大家一起参与，让这个项目变得更好\n- 非常欢迎使用和提交  **PRs** 和 issues \n- 需求参考 后期计划\n\nclone 项目后，下载 **Todo Tree** 插件，可以查看代码中所有具体位置的 todo\n\n`.cursor/*` 有项目整体架构、rules、mcp 可以方便开发使用\n\n## 📄 版权License\n\n个人免费使用，请勿商业用途，商业用途联系我（作者）\n\n[License](./docs/md/License.md)\n\n## 🙏 Reference\n\nThanks to the following projects:\n- [OpenCodeInterpreter](https://github.com/OpenCodeInterpreter/OpenCodeInterpreter/tree/main)\n- [TaskWeaver](https://github.com/microsoft/TaskWeaver)\n- [Code-Interpreter](https://github.com/MrGreyfun/Local-Code-Interpreter/tree/main)\n- [Latex](https://github.com/Veni222987/MathModelingLatexTemplate/tree/main)\n- [Agent Laboratory](https://github.com/SamuelSchmidgall/AgentLaboratory)\n- [ai-manus](https://github.com/Simpleyyt/ai-manus)\n\n## 其他\n\n### 💖 Sponsor\n\n[☕️ 给作者买一杯咖啡](./docs/md/sponser.md)\n\nhttps://linux.do/\n\n#### 企业\n\n<div align=\"center\">\n    <a href=\"https://share.302.ai/UoTruU\" target=\"_blank\">\n    <img src=\"./docs/302ai.jpg\">\n    </a>\n</div>\n\n[302.AI](https://share.302.ai/UoTruU) 是一个按用量付费的企业级AI资源平台，提供市场上最新、最全面的AI模型和API，以及多种开箱即用的在线AI应用\n\n#### 用户\n\n[danmo-tyc](https://github.com/danmo-tyc)\n\n### 👥 GROUP\n\n有问题可以进群问\n\n点击链接加入腾讯频道【MathModelAgent】：https://pd.qq.com/s/7rfbai3au\n\n点击链接加入群聊 779159301【MathModelAgent】：https://qm.qq.com/q/Fw2cCJPoki\n\n[Discord](https://discord.gg/3Jmpqg5J)\n\n> [!CAUTION]\n> 免责声明: 注意，AI 生成仅供参考，目前水平直接参加国赛获奖是不可能的，但我相信 AI 和 该项目未来的成长。\n\n",
  "bytes": 10053,
  "sha": "90c9d04c722944a921981344418c5019f100b95679b8feef79c8a4bbfd438bc8",
  "repo_slug": "jihe520/mathmodelagent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_jihe520_mathmodelagent_references_e7a73918/readme"
}