多领域 AI 研究与数据分析 IDE · mathark.cn
MathArk 面向数学建模、统计分析、科研写作、课程作业与数据分析等场景，提供从资料理解、方案构建、代码执行到成果输出的全流程 AI 辅助能力。采用 IDE 风格界面，支持 内置流水线 / Cursor Agent / 磐石 Agent 三种编程引擎，并提供多工作区、项目管理、积分计费与站点运营配置。
| 场景 | 能力 |
|---|---|
| 研究与建模 | 数学建模 · 统计建模 · 数据分析 · 论文 / 报告成稿 |
| 编程执行 | Builtin / Cursor SDK / Claude Code CLI（LiteLLM 网关） |
| 平台运营 | 用户认证 · 用量追踪 · 管理员配置 · Docker 部署 |
联系我们：官网 mathark.cn · QQ 交流群 1048216892
本地开发默认 SQLite；生产环境见 DEPLOYMENT.md。联调计划见 ROADMAP.md。
| 层 | 技术 |
|---|---|
| 前端 | Next.js 15 · TypeScript · TailwindCSS · shadcn/ui · Monaco Editor · React Flow |
| 后端 | FastAPI · LangChain · OpenAI SDK · Celery |
| 编程引擎 | builtin（内置流水线）· cursor（Cursor SDK）· claude（磐石 Agent / Claude Code CLI） |
| 协议网关 | LiteLLM（OpenAI 兼容 → Anthropic Messages，供 Claude 引擎使用） |
| 数据库 | SQLite（开发）/ PostgreSQL 16（生产） |
| 缓存 / 队列 | Redis 7 |
| 部署 | Docker Compose · Nginx · Gunicorn |
- 题目解析 — 上传 PDF/Word 赛题，自动提取文本
- AI 分析 — 识别题型、拆解子问题、推荐建模方法
- 数学建模 — 生成完整的模型方案与求解思路
- 代码生成与执行 — 三种编程引擎可选（见下节），沙箱执行，支持流式输出
- Cursor 编程引擎 — Cursor SDK agent，负责代码生成与执行调试（local / cloud_rest）
- 磐石 Agent 引擎 — Claude Code CLI + 磐石大模型，经 LiteLLM 或 Anthropic 兼容端点驱动
- 自动调试 — 代码执行出错时自动分析错误并重试
- 结果分析 — 对模型运行结果进行 AI 解读
- 论文生成 — 基于 Celery 异步生成完整 LaTeX 论文，支持编译下载
- 工作流引擎 — 多步骤 AI 管道，SSE 实时推送进度
- 项目管理 — 项目创建/归档/恢复，实验记录，交付物管理
- 文件管理 — 上传/预览/删除，全局竞赛模板
- 认证体系 — JWT + 邮箱验证码登录/注册，管理员防暴破
- 用量追踪 — 按请求统计 Token 消耗，响应头附带用量信息
- API 限流 — 基于 Redis 滑动窗口算法（Redis 不可用时降级内存）
工作流中的 coding / execute 阶段由下列引擎之一接管（可在前端「API 设置」或 backend/.env 切换）：
| 引擎 | CODING_MODE |
执行位置 | 模型来源 | 当前状态 |
|---|---|---|---|---|
| 内置流水线 | builtin |
后端本机固定编排 | OpenAI 兼容（DeepSeek 等） | ✅ 默认，稳定 |
| Cursor Agent | cursor |
本机子进程 bridge 或 Cursor 云 VM | Cursor 托管模型 | |
| 磐石 Agent | claude |
本机 Claude Code CLI 子进程（cloud 沙箱规划中） | 磐石经 LiteLLM/Anthropic 端点 |
引擎启动失败时，可通过 CURSOR_FALLBACK_TO_BUILTIN / CLAUDE_FALLBACK_TO_BUILTIN（默认 true）自动回退内置流水线。
math-agent/
├── frontend/ # Next.js 前端
│ ├── src/
│ │ ├── app/ # 页面入口
│ │ ├── components/ # UI 组件
│ │ │ ├── auth/ # 登录页 / 粒子背景
│ │ │ ├── layout/ # 侧边栏 / 顶栏 / 主工作区
│ │ │ ├── ui/ # 通用 UI（按钮/LaTeX/Toast）
│ │ │ └── workspace/ # 业务面板（代码编辑器/工作流图/论文/分析...）
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── lib/ # 工具函数
│ │ └── stores/ # Zustand 状态管理
│ ├── .env.local # 本地 API 地址（如 http://localhost:8000）
│ ├── Dockerfile
│ └── package.json
├── backend/ # FastAPI 后端
│ ├── app/
│ │ ├── agents/ # Agent 实现（builtin/cursor/claude 各阶段）
│ │ ├── api/ # 路由层
│ │ │ ├── auth.py # 认证相关接口
│ │ │ ├── routes/ # 业务路由（分析/代码/论文/工作流/项目/文件...）
│ │ │ └── deps.py # 依赖注入
│ │ ├── core/ # 配置 / 安全
│ │ ├── db/ # 数据库（SQLAlchemy ORM / 会话管理）
│ │ ├── models/ # 数据模型
│ │ ├── runtime/ # 工作流引擎 workflow_engine
│ │ ├── services/ # 业务逻辑（LLM/Cursor/Claude/沙箱等 20+ 服务）
│ │ └── main.py # 应用入口
│ ├── scripts/ # 联调 / 回归 / PoC 脚本（probe、workflow demo 等）
│ ├── alembic/ # 数据库迁移
│ ├── .env # 本地密钥与引擎配置（勿提交）
│ ├── Dockerfile
│ └── requirements.txt
├── docker/
│ └── claude-sandbox/ # 磐石 Agent 云沙箱镜像（P0 已交付）
├── scripts/ # 仓库级脚本（LiteLLM 网关启动等）
│ ├── litellm_config.yaml
│ └── start_litellm.ps1
├── prompts/ # Prompt 模板（热加载）
│ ├── system.txt # 系统提示词
│ ├── analyzer.txt # 题目分析
│ ├── modeling.txt # 数学建模
│ ├── coding.txt # 代码生成
│ ├── debugger.txt # 自动调试
│ ├── paper.txt # 论文生成
│ └── result_analysis.txt # 结果分析
├── nginx/ # Nginx 反向代理
│ ├── nginx.conf
│ └── ssl/ # SSL 证书目录
├── docker-compose.yml # 完整服务编排
├── deploy.sh # 生产一键部署
├── ROADMAP.md # 下一步工作计划（联调优先级）
├── DEPLOYMENT.md # 生产部署详解
├── CLAUDE_CLOUD_SANDBOX_DESIGN.md # 磐石云沙箱设计
├── .env.example # Docker Compose 环境变量模板
└── .gitignore
前置条件: Python 3.11+、Node.js 20+
# 1. 进入项目
cd math-agent
# 2. 启动后端（终端 1）
cd backend
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env # 首次：编辑填入 API Key、管理员密码等
.\venv\Scripts\python -m uvicorn app.main:app --reload --port 8000
# 3. 启动前端（终端 2）
cd frontend
npm install
# 确认 .env.local：NEXT_PUBLIC_API_URL=http://localhost:8000
npm run devcd math-agent/backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --port 8000
# 新终端
cd math-agent/frontend && npm install && npm run dev访问 http://localhost:3000 · 后端健康检查 http://127.0.0.1:8000/health
- 本地开发默认使用 SQLite，无需 PostgreSQL。
- 验证码和限流在 Redis 不可用时自动降级到内存存储。
- 论文异步生成依赖 Celery + Redis；本地若未启 Redis，可先用同步接口或
docker compose up redis celery-worker -d只起队列服务。- 启用 磐石 Agent 需额外安装 Claude Code CLI 并启动 LiteLLM，见下文「磐石 Agent 配置」。
更完整的生产部署、环境变量和 Cursor 引擎检查说明见 DEPLOYMENT.md。
- Linux 服务器（Ubuntu 22.04+ / CentOS 8+ 推荐）
- Docker 24+ & Docker Compose v2
- 开放端口：80（HTTP）、443（HTTPS，可选）
项目附带自动部署脚本 deploy.sh，在服务器上执行：
# 1. 克隆仓库
git clone git@github.com:<你的用户名>/math-agent.git && cd math-agent
# 2. 运行部署脚本
chmod +x deploy.sh
./deploy.sh脚本将自动完成：环境变量配置引导 → Docker 镜像构建 → 服务启动 → 健康检查。
# 1. 配置环境变量
cp .env.example .env
cp backend/.env.example backend/.env
# 编辑 .env 和 backend/.env，填入真实密码和 API Key
# 2. 构建并启动所有服务
docker compose up -d --build
# 3. 查看服务状态
docker compose ps
docker compose logs -f backend
# 4. 数据库迁移（首次部署必须）
docker compose exec backend alembic upgrade head访问 http://服务器IP 即可使用。
# 查看实时日志
docker compose logs -f backend celery-worker
# 重启单个服务
docker compose restart backend
# 更新代码后重新部署
git pull && docker compose up -d --build
# 停止所有服务
docker compose down
# 停止并清除数据卷（⚠ 会删除数据库）
docker compose down -v
# 进入后端容器调试
docker compose exec backend bash
# 数据库备份
docker compose exec postgres pg_dump -U math_agent math_agent > backup_$(date +%Y%m%d).sql浏览器
│
▼ HTTP/HTTPS
Nginx (:80/:443)
├── / → Frontend (:3000) Next.js standalone
├── /api/* → Backend (:8000) Gunicorn + Uvicorn
├── /auth/* → Backend
├── /uploads/* → Backend (静态文件)
└── /outputs/* → Backend (静态文件)
│
┌─────┼──────┐
│ │
PostgreSQL Redis ← Celery Worker
| 变量 | 说明 | 默认值 |
|---|---|---|
OPENAI_API_KEY |
LLM API 密钥 | 必填 |
OPENAI_BASE_URL |
API 基础 URL（DeepSeek/智谱/千问/自定义） | https://api.deepseek.com |
OPENAI_MODEL |
使用的模型 | deepseek-v4-flash |
OPENAI_MAX_TOKENS |
常规请求最大 token | 32000 |
PAPER_MAX_TOKENS |
论文生成最大 token | 65536 |
EXECUTION_TIMEOUT |
代码执行超时（秒） | 300 |
CODING_MODE |
默认编程引擎：builtin 或 cursor |
builtin |
CURSOR_API_KEY |
Cursor SDK API Key，启用 Cursor 引擎时必填 | — |
CURSOR_MODEL |
Cursor agent 使用的模型 | composer-2.5 |
CURSOR_FALLBACK_TO_BUILTIN |
Cursor 启动失败时是否回退内置流水线 | true |
CURSOR_TASK_TIMEOUT |
单个 Cursor 编码/执行任务超时（秒） | 3600 |
CURSOR_LOCAL_WORKER |
本机 bridge 载体：subprocess（推荐）或 thread |
subprocess |
CURSOR_RUNTIME |
Cursor 运行时：local 或 cloud_rest |
local |
CLAUDE_BASE_URL |
磐石/LiteLLM 网关（→ Anthropic Messages） | http://localhost:4000 |
CLAUDE_AUTH_TOKEN |
网关鉴权 token | — |
CLAUDE_MODEL |
磐石模型名（LiteLLM model_name） |
pangu |
CLAUDE_FALLBACK_TO_BUILTIN |
Claude 启动失败是否回退内置流水线 | true |
CLAUDE_LOCAL_WORKER |
本机 CLI 载体：subprocess（推荐）或 thread |
subprocess |
ADMIN_USERNAME |
管理员用户名 | admin |
ADMIN_PASSWORD |
管理员密码 | 必填 |
JWT_SECRET |
JWT 签名密钥 | 自动生成（生产需固定） |
SMTP_HOST |
邮件服务器 | — |
SMTP_PORT |
邮件端口 | 465 |
SMTP_USER / SMTP_PASSWORD |
邮件账号密码 | — |
DATABASE_URL |
数据库连接串 | sqlite:///./math_agent.db |
REDIS_URL |
Redis 地址 | redis://localhost:6379/0 |
CORS_ORIGINS |
允许的前端域名（逗号分隔） | localhost:3000 |
| 变量 | 说明 | 默认值 |
|---|---|---|
POSTGRES_USER |
数据库用户名 | math_agent |
POSTGRES_DB |
PostgreSQL 数据库名 | math_agent |
POSTGRES_PASSWORD |
数据库密码 | 必填 |
DATABASE_URL |
后端容器连接 PostgreSQL 的连接串，必须使用 postgresql:// |
必填 |
HTTP_PORT |
HTTP 端口映射 | 80 |
HTTPS_PORT |
HTTPS 端口映射 | 443 |
Cursor 引擎只接管工作流中的「代码生成 / 执行调试」阶段，其余题目分析、建模、结果分析和论文生成仍使用普通 LLM 提供商配置。
- 在 Cursor Dashboard 的 Integrations 或团队 Service Accounts 中创建
CURSOR_API_KEY。 - 本地开发时写入
backend/.env：
CODING_MODE=builtin
CURSOR_API_KEY=crsr_xxx
CURSOR_MODEL=composer-2.5
CURSOR_FALLBACK_TO_BUILTIN=true
CURSOR_TASK_TIMEOUT=3600- 生产部署时同样写入服务器上的
backend/.env，然后重启后端：
docker compose restart backend celery-worker进入「API 设置」→「编程引擎」，选择 Cursor Agent 后可以：
- 保存或更新服务端全局
CURSOR_API_KEY - 选择或输入 Cursor 模型
- 点击「测试连接」真实启动一次 Cursor bridge，验证 Key 和模型是否可用
测试通过后，新建工作流并选择 Cursor Agent，代码生成与执行调试阶段会由本机 Cursor SDK agent 完成。若 CURSOR_FALLBACK_TO_BUILTIN=true，Cursor bridge、认证或启动失败时会自动回退到内置流水线。
cursor-sdk、claude-agent-sdk已写入backend/requirements.txt；Claude 引擎还需全局安装@anthropic-ai/claude-codeCLI。- Cursor / Claude 本地 agent 会在项目工作目录内读写代码；生产环境应确保后端容器或主机拥有对应目录权限。
- uvicorn 宿主进程兼容：Cursor 与 Claude 均通过 独立子进程 worker（
CURSOR_LOCAL_WORKER=subprocess/CLAUDE_LOCAL_WORKER=subprocess）规避「宿主主线程有活跃 asyncio loop」与子进程 bridge 不兼容的问题。 CURSOR_API_KEY属于服务端全局密钥，只允许管理员在前端配置和测试。
磐石引擎（CODING_MODE=claude）使用 Claude Code CLI 作为自主 coding agent，模型推理走磐石大模型。若磐石为 OpenAI 兼容接口，需前置 LiteLLM 做协议转换。
编辑 scripts/litellm_config.yaml，填入磐石真实 模型名 与 api_base：
model_list:
- model_name: pangu
litellm_params:
model: openai/<磐石真实模型名>
api_base: http://<磐石地址>/v1
api_key: os.environ/PANGU_API_KEY启动网关（PowerShell）：
$env:PANGU_API_KEY = "<你的磐石 API Key>"
.\scripts\start_litellm.ps1
# 网关默认 http://localhost:4000npm i -g @anthropic-ai/claude-code
claude --version在 backend/.env 中配置：
CODING_MODE=claude
CLAUDE_BASE_URL=http://localhost:4000
CLAUDE_AUTH_TOKEN=sk-local-litellm
CLAUDE_MODEL=pangu
CLAUDE_FALLBACK_TO_BUILTIN=truecd backend
python scripts/probe_claude_agent.py # 独立 PoC，应出现 [verify] PASS
python scripts/run_local_two_problems.py # 可选：两题端到端云沙箱（数据不出内网、每任务独立 Docker 容器）见 CLAUDE_CLOUD_SANDBOX_DESIGN.md 与 docker/claude-sandbox/。
| 脚本 | 用途 |
|---|---|
backend/scripts/probe_claude_agent.py |
磐石 + Claude SDK 最小 PoC |
backend/scripts/probe_claude_sandbox.py |
自建 Docker 沙箱 PoC（P0） |
backend/scripts/run_local_two_problems.py |
本机 Cursor/Claude 两题工作流 |
backend/scripts/run_full_workflow_two_problems.py |
完整 workflow 两题 |
backend/scripts/run_full_regression.ps1 |
Windows 全量回归 |
backend/scripts/test_cursor_mvp.py |
Cursor bridge 冒烟 |
scripts/start_litellm.ps1 |
启动 LiteLLM 协议网关 |
| 模块 | 端点 | 说明 |
|---|---|---|
| 认证 | POST /auth/login · POST /auth/register · POST /auth/send-code |
邮箱验证码登录注册 |
| 管理 | POST /auth/admin-login · GET /auth/users |
管理员登录 / 用户管理 |
| 文件 | POST /upload · POST /upload-files · GET /files |
上传解析 PDF / 文件管理 |
| 分析 | POST /analyze · POST /generate-modeling · POST /analyze-results |
题目分析 / 建模方案 / 结果分析 |
| 代码 | POST /generate-code · POST /execute · POST /execute-with-retry |
生成 / 执行 / 自动重试 |
| 论文 | POST /generate-paper · GET /generate-paper/jobs/{id} · POST /compile-paper |
异步生成 / 状态查询 / 编译 |
| 工作流 | POST /workflow/start · GET /workflow/{id}/events |
多步骤流水线 + SSE 推送 |
| 项目 | POST /projects · GET /projects/{id} |
CRUD / 实验 / 交付物 / 归档 |
| 设置 | GET /settings · POST /settings |
运行时 LLM 参数调整 |
| Cursor 设置 | GET /settings/cursor · POST /settings/cursor · POST /settings/cursor/test |
Cursor SDK 配置与真实连接测试 |
| 健康 | GET /health |
服务健康检查 |
详细阶段划分、优先级与完成标准见 ROADMAP.md。摘要：
| 阶段 | 目标 |
|---|---|
| P0 | LiteLLM + 磐石端点联调，probe_claude_agent.py PASS，workflow 走 claude |
| P1 | Cursor 子进程 worker 端到端验证，workflow 可切回 cursor |
| P2 | Docker 云沙箱 ClaudeCloudSession（P1 会话层） |
| P3 | Docker 生产栈、Celery、备份与 HTTPS |
| P4 | 计费、一键启动脚本、监控 |
项目使用 Alembic 管理数据库 schema 变更：
cd backend
# 生成新迁移
alembic revision --autogenerate -m "描述变更"
# 应用迁移到最新
alembic upgrade head
# 回滚上一个版本
alembic downgrade -1- 将 SSL 证书放入
nginx/ssl/（fullchain.pem+privkey.pem） - 编辑
nginx/nginx.conf，取消 SSL 相关注释 - 重启 Nginx：
docker compose restart nginx
MIT
如果你觉得还不错，欢迎打赏一杯奶茶！
