MathModelAgent：面向数学建模的智能体操作系统

1. 这不是又一个“AI写论文”工具——MathModelAgent 是数学建模工作流的底层操作系统

你有没有经历过这样的深夜：国赛倒计时48小时，队友还在争论用Logistic回归还是LSTM预测人口增长；代码跑出一堆NaN，但没人敢动核心模块；LaTeX编译报错在第37页，而你根本找不到哪个括号没闭合；最后交稿前半小时，发现参考文献格式全乱了，手动改完发现公式编号崩了……这不是个别现象，而是过去十年全国大学生数学建模竞赛（CUMCM）和华为杯研究生数学建模大赛中，超过73%的参赛队共同踩过的坑。而MathModelAgent，从第一天设计起就拒绝做“AI润色器”或“论文生成器”——它是一个嵌入式、可拆解、带状态记忆的数学建模专用智能体操作系统。它不替代人思考模型结构，但会替你守住所有技术执行层的底线：自动校验微分方程初值是否满足守恒律、实时追踪符号变量作用域避免代入错误、在LaTeX编译失败时精准定位到\frac{a+b}{c+d}里多打的那个空格、甚至能在你手滑删掉plt.grid(True)后，从Git历史+运行日志交叉比对，自动还原绘图参数。它的核心不是“生成”，而是“保真”——确保从第一行假设推导，到最后一页排版输出，整个链条的数学语义、计算逻辑与文档表达三者严格一致。关键词MathModelAgent、数学建模、Agent、Typst、SKILLS，每一个都不是装饰词：MathModelAgent是系统代号，数学建模是唯一战场，Agent是运行范式，Typst是默认输出引擎（不是LaTeX），SKILLS是能力原子单元——不是插件，不是函数库，而是可验证、可组合、带类型签名的数学建模最小执行单元。它面向的不是“想试试AI”的新手，而是连续三年带队冲击国赛一等奖、清楚知道每个模型背后数值陷阱的指导教师，以及那些在C题“城市交通碳排放优化”中为0.3%精度提升反复调试三天的实战派队员。如果你需要的是“一键成文”，请关掉这个页面；如果你受够了因低级执行错误丢掉省一，那接下来的内容，值得你逐行读完。

2. 为什么必须重构数学建模的技术栈？——从“人肉流水线”到“语义闭环系统”

2.1 传统建模流程的三大结构性断点

数学建模竞赛的典型工作流表面看是“读题→建模→编程→求解→分析→写作”，但实际执行中存在三个无法靠人力弥补的断点，它们直接导致大量队伍在细节上失分：

• 断点一：数学语义与代码实现的语义鸿沟
  题目要求“建立考虑时间延迟的传染病传播模型”，你在纸上写下带时滞项的微分方程组：
  dS/dt = -β·S(t)·I(t-τ)
  但写Python时，却用scipy.integrate.solve_ivp直接积分，完全忽略I(t-τ)需要历史数据缓存与插值——代码能跑通，结果却违背模型本意。这不是能力问题，而是数学表达式与编程接口之间缺乏形式化映射。MathModelAgent强制要求所有模型定义必须通过DSL（领域特定语言）声明，例如：

  model seir_delayed { params: β, γ, τ; state: S, E, I, R; delay: I(t-τ); ode: [ dS/dt = -β * S * I_delay, dE/dt = β * S * I_delay - γ * E, ... ]; }

  系统会自动检查I_delay是否被正确定义为延迟变量，并在生成求解代码时，强制注入solve_dde（而非solve_ivp）调用，且预置好历史数据初始化逻辑。这步检查发生在代码生成前，杜绝“能跑≠正确”。

• 断点二：计算过程与结果呈现的版本漂移
  你用Matplotlib画出热力图，截图插入Word；队友用Origin重绘同一张图，参数微调后发来新图；第三位队员在LaTeX里用pgfplots再画一次……最终提交稿里，同一张图出现三种配色、两种坐标轴标签、一个未标注单位。更致命的是，当评委质疑“图3中峰值为何出现在t=12.3而非t=12.5”，你翻遍Git记录才发现，原始数据文件被覆盖过三次，最后一次修改者备注是“修复y轴刻度”。MathModelAgent采用计算图（Computation Graph）驱动的文档生成：所有图表均由plot_heatmap(data=load_csv("output/sim_result.csv"))这类声明式指令生成，data路径被固化为图节点输入。当你点击“重新生成全文”，系统会：① 检查sim_result.csv哈希值是否变更；② 若变更，则触发上游仿真模块重跑；③ 仅当仿真完成且输出校验通过（如质量守恒误差<1e-6），才允许下游绘图与排版执行。这意味着，你看到的每一张图，都精确绑定到某次特定参数配置下的确定性计算结果。

• 断点三：团队协作与知识沉淀的隐性损耗
  往届优秀论文里的“灰色关联度分析”模块，今年新队员要花两天重写；去年用过的“多目标Pareto前沿提取算法”，今年因依赖库版本升级而报错；指导教师反复强调“C题必须做敏感性分析”，但每年仍有队伍漏掉。这些不是个人疏忽，而是技能（SKILLS）未被封装为可复用、可验证、带上下文的原子单元。MathModelAgent的SKILLS不是函数，而是带元数据的执行包：

  { "id": "skill-sensitivity-partial", "version": "2.1.0", "scope": ["CUMCM-C", "optimization"], "input_schema": {"model": "string", "params": ["list"]}, "output_schema": {"sobol_indices": "array", "confidence_interval": "object"}, "validation": "run_test_sensitivity.py --tolerance 1e-4" }

  当队员在Typst文档中插入@skill-sensitivity-partial(model="NSGA-II", params=["weight_a", "weight_b"])，系统不仅执行分析，还会自动检查当前环境是否满足skill-sensitivity-partial的依赖要求（如salib>=1.4.0），并在报告末尾生成该SKILL的调用日志与验证结果摘要。知识不再散落在个人电脑或微信聊天记录里，而成为可审计、可追溯、可一键复用的组织资产。

2.2 Typst：为什么放弃LaTeX选择这个“冷门”排版引擎？

提到学术排版，99%的人第一反应是LaTeX。但MathModelAgent选择Typst，是经过三轮真实赛题压力测试后的决断，而非技术炫技：

• 编译速度：从分钟级到秒级的质变
  一份含23个公式、17张矢量图、87条参考文献的国赛论文，在Overleaf（LaTeX云平台）平均编译耗时142秒；相同内容用Typst，首次编译4.7秒，增量编译（改一个字）仅0.3秒。这不是数字游戏——在决赛答辩前夜，当评委临时要求“把第三章结论部分加粗显示”，LaTeX用户要等两分钟才能看到效果，Typst用户改完保存，0.3秒后PDF已更新。这种响应速度差，在高压场景下直接转化为决策优势。

• 样式控制：CSS级的直观性 vs LaTeX的黑盒魔法
  LaTeX的\renewcommand{\labelenumi}{(\Roman{enumi})}这类命令，对非TeX专家如同天书；而Typst的样式定义直白如CSS：

  #set enum(numbering: "I.") #set heading(numbering: "1.1") #set math.equation(numbering: "Eq.1")

  更关键的是，Typst支持样式继承链：定义#set page(width: 16cm, height: 24cm)后，所有图表、表格、公式块自动适配页面尺寸，无需像LaTeX那样为每个浮动体单独设置\linewidth。我们在2025年高教社杯D题（“基于多源遥感数据的耕地退化评估”）中实测：当题目要求将原A4尺寸改为A3横向排版时，Typst只需改一行#set page(orientation: landscape)，全文自动重排；LaTeX方案则需手动调整12处\includegraphics宽度、7处tabular列宽、以及3个minipage嵌套层级。

• 与Agent深度集成：真正的“活文档”
  Typst的#show规则和#let变量机制，让文档具备程序执行能力。MathModelAgent利用这一点，实现“文档即接口”：

  #let model_result = run_skill("skill-forecast-lstm", data: load_csv("input/traffic.csv")) #show heading.where(level: "2"): it => { #box( fill: if model_result.mae < 500 { green } else { red }, inset: 4pt, [#Result MAE: #(model_result.mae)] ) }

  这段Typst代码不仅显示二级标题，还实时调用SKILL执行预测，并根据MAE指标自动给标题加绿色/红色底纹。LaTeX无法做到这点——它本质是静态排版工具，而Typst是可编程文档引擎，这正是Agent需要的宿主环境。

提示：Typst学习曲线远低于LaTeX。我们为零基础队员设计的速成路径是：① 用Typst Playground在线编辑器（https://typst.app/playground）粘贴模板；② 修改#set heading(...)参数观察效果；③ 将#lorem占位符替换为真实内容。全程无需安装任何软件，20分钟内即可产出格式规范的初稿。

3. SKILLS：数学建模能力的原子化封装与可信调度

3.1 SKILLS不是函数，而是带“数字护照”的能力实体

在MathModelAgent体系中，“SKILLS”这个词承载着远超字面的重量。它不是Python里的def sensitivity_analysis()，也不是Jupyter Notebook中的代码块，而是一个具备完整身份认证、能力声明、执行约束与结果验证的能力实体（Capability Entity）。每个SKILL都携带一张“数字护照”，包含以下核心字段：

字段	示例值	作用
id	skill-optimization-nsga2	全局唯一标识，用于跨项目引用
version	3.2.1	语义化版本号，3.2.1→3.2.2表示仅修复bug，不影响接口
scope	["CUMCM-A", "multi-objective"]	声明适用场景，Agent调度时自动过滤不匹配SKILL
input_schema	{"variables": "array", "constraints": "object"}	JSON Schema定义输入结构，运行前强制校验
output_schema	{"pareto_front": "array", "runtime_sec": "number"}	定义输出契约，结果必须满足此Schema
validation	"pytest tests/test_nsga2.py --timeout=30"	独立验证脚本，每次部署前必跑
dependencies	{"python": ">=3.9", "pymoo": ">=0.6.0"}	环境依赖声明，Agent自动检查并提示缺失

这个设计解决了数学建模中最痛的协作问题：“这个代码到底能不能用？”
过去，队员A发来一个genetic_algorithm.py，队员B要花半天确认：① Python版本兼容吗？② 是否需要额外安装deap库？③ 输入数据格式是DataFrame还是numpy array？④ 输出结果里best_solution字段是字典还是列表？而现在，当B在Typst文档中写@skill-optimization-nsga2(variables: ["x1","x2"], constraints: {...})，MathModelAgent会：

1. 根据id拉取skill-optimization-nsga2@3.2.1的元数据；
2. 检查本地环境是否满足dependencies；
3. 将传入参数按input_schema校验（若variables传入字符串而非数组，立即报错）；
4. 执行SKILL，并用output_schema验证返回结果；
5. 运行validation脚本，确保本次执行与历史基准一致。

只有全部通过，才允许结果写入文档。这相当于给每个建模能力装上了“出厂质检报告”。

3.2 六类核心SKILLS及其不可替代性

MathModelAgent预置的SKILLS库并非大而全，而是聚焦数学建模高频刚需，每类都解决一个经典痛点：

• 模型构建类（Modeling SKILLS）
  如skill-model-ode-system：输入微分方程组DSL，自动生成可求解的Python代码（含初值设置、求解器选择、稳定性检查）。它内置了刚性检测器：当识别到方程组雅可比矩阵特征值实部跨度超10^6时，自动切换至scipy.solve_ivp(method='Radau')，而非默认的'RK45'。这避免了90%的“ODE求解失败”问题。

• 数据处理类（Data SKILLS）
  如skill-data-impute-knn：针对缺失值填充，不简单调用sklearn.impute.KNNImputer，而是：① 自动标准化数据；② 计算样本间欧氏距离；③ 对每个缺失点，动态选择k值（k=min(5, 非空样本数/10)）；④ 填充后进行残差检验，若填充点残差>3σ则标记为“高风险填充”。这比通用插补工具更懂数学建模数据的物理意义。

• 算法求解类（Solving SKILLS）
  如skill-solver-linear-programming：封装scipy.optimize.linprog，但增加约束可行性预检。当用户输入A_ub @ x <= b_ub时，系统先运行cvxpy快速验证约束集是否为空（即是否存在可行解），若为空则立即报错：“Constraints are infeasible — check sign of inequality or bounds”，而非等到求解器迭代1000次后返回status=2。

• 可视化类（Visualization SKILLS）
  如skill-plot-3d-surface：生成三维曲面图时，自动启用antialiased=True和rstride=1, cstride=1（而非默认稀疏采样），确保图像在PDF放大时无锯齿；同时添加#set page(margin: (top: 2cm, bottom: 2cm))指令，防止图表被页边距裁切——这是LaTeX用户常踩的坑。

• 敏感性分析类（Sensitivity SKILLS）
  如skill-sensitivity-sobol：不仅计算Sobol指数，还生成交互效应热力图。当发现S_AB > 0.15（即参数A与B存在强交互），自动在报告中插入警示框：“检测到显著交互效应，建议采用响应面法替代单因素分析”。

• 文档生成类（Document SKILLS）
  如skill-doc-ref-format：解析references.bib，自动按《全国大学生数学建模竞赛论文格式规范》生成参考文献列表，并检查：① 所有引用是否在正文中标注；② 英文作者名是否缩写（如Zhang, Y.而非Zhang, Yong）；③ 期刊名是否使用标准缩写（如IEEE Trans. Pattern Anal. Mach. Intell.）。这一步节省平均2.3小时人工校对时间。

注意：所有SKILLS均开源可审计。我们提供GitHub仓库（mathmodelagent/skills），每个SKILL目录包含skill.json（元数据）、main.py（核心逻辑）、tests/（验证用例）和docs/（使用示例）。你可以fork后修改，但修改后必须通过validation脚本，否则无法注册进本地Agent。

3.3 SKILLS的组合与编排：用Typst语法定义工作流

SKILLS的价值不仅在于单点强大，更在于可组合性。MathModelAgent不提供复杂的工作流引擎（如Airflow），而是将编排逻辑下沉到Typst文档本身——因为文档才是建模成果的终极载体。例如，C题“城市交通碳排放优化”中，一个典型分析链可这样声明：

// 定义数据管道 #let traffic_data = load_csv("input/traffic_flow_2025.csv") #let weather_data = load_csv("input/weather_2025.csv") // 组合SKILLS：数据融合 → 特征工程 → 模型训练 → 敏感性分析 #let fused_data = @skill-data-fuse-traffic-weather( traffic: traffic_data, weather: weather_data, time_window: "30min" ) #let features = @skill-feature-engineer-carbon( data: fused_data, target: "co2_emission" ) #let model = @skill-model-random-forest( X: features.X, y: features.y, n_estimators: 200 ) #let sensitivity = @skill-sensitivity-partial( model: model, params: ["speed_limit", "bus_frequency", "ev_ratio"] ) // 文档渲染：自动嵌入结果 #heading[模型性能] #block[ #text[MAE: ] #text[(model.mae).round(2)] #text[ | R²: ] #text[(model.r2).round(3)] ] #heading[敏感性分析] #figure[ #caption[各参数对碳排放影响的Sobol一阶指数] #show skill-plot-sobol-index(sensitivity) ]

这段Typst代码完成了四件事：① 声明数据源；② 串行调用四个SKILLS；③ 在指定位置渲染数值结果；④ 插入可视化图表。关键在于，所有中间变量（fused_data,features）均被Agent跟踪：当你双击model.mae数值，可溯源到skill-model-random-forest的执行日志；右键#show skill-plot-sobol-index，可查看该图表对应的skill-plot-sobol-index版本及输入参数。文档不再是静态快照，而是可钻取、可验证、可重放的计算过程记录。

4. 实操：从零部署MathModelAgent并运行首个建模任务

4.1 环境准备：三步完成本地Agent启动

MathModelAgent设计原则是“开箱即用，不碰环境”。我们摒弃复杂的Docker Compose或Conda环境，采用轻量级Python虚拟环境+预编译二进制包方案。实测在Windows 10/11、macOS Monterey+、Ubuntu 22.04上均可5分钟内完成：

1. 安装Python 3.10+（仅需基础环境）

   • Windows：从python.org下载安装包，勾选“Add Python to PATH”；
   • macOS：brew install python@3.10；
   • Ubuntu：sudo apt update && sudo apt install python3.10-venv python3.10-dev。

   注意：无需卸载旧版Python，MathModelAgent自带Python版本隔离机制。

2. 创建专用虚拟环境并激活

   # 创建环境（推荐路径不含中文/空格） python3.10 -m venv ~/mathmodel-agent-env # 激活环境 source ~/mathmodel-agent-env/bin/activate # macOS/Linux # 或 ~/mathmodel-agent-env/Scripts/activate.bat # Windows

3. 一键安装MathModelAgent核心包

   # 从PyPI安装（国内用户自动走清华镜像） pip install mathmodelagent[full] # 验证安装 mathmodel --version # 应输出：MathModelAgent v2.4.0 (built on 2025-04-12)

[full]标记表示安装全部依赖（包括Typst、SciPy、PyTorch等），总大小约1.2GB。若磁盘空间紧张，可用pip install mathmodelagent[core]安装最小集（仅含Typst和基础SKILLS），后续按需pip install mathmodelagent[skills-optimization]扩展。

实操心得：首次安装时，pip可能卡在Building wheel for typst步骤。这是正常现象——Typst编译需1-2分钟。耐心等待，勿中断。若超5分钟无响应，可手动下载预编译wheel（见GitHub Releases页），用pip install typst-0.10.0-py3-none-manylinux_2_17_x86_64.whl安装。

4.2 创建你的第一个建模项目：以2026年C题“新能源汽车充电站选址优化”为例

我们以虚构的2026年C题为案例，演示完整工作流。题目核心要求：在某市127个候选点中，选出≤20个充电站位置，使全市98万电动车用户平均充电等待时间最小化，同时满足单站日服务上限500辆。

1. 初始化项目结构

   # 创建项目目录 mkdir ev-charging-opt && cd ev-charging-opt # 初始化MathModelAgent项目 mathmodel init --template=cumcm-c

   此命令生成标准目录：

   ev-charging-opt/ ├── input/ # 原始数据目录 │ ├── demand.csv # 各区域电动车保有量 │ ├── grid_capacity.csv # 电网容量限制 │ └── candidate_sites.geojson # 候选点地理坐标 ├── skills/ # 本地SKILLS扩展目录（可选） ├── docs/ # Typst文档源码 │ ├── main.typ # 主文档 │ └── config.typ # 文档配置 └── agent.toml # Agent全局配置

2. 编写Typst主文档（docs/main.typ）
   编辑docs/main.typ，填入以下内容（已去除LaTeX式冗余，专注逻辑）：

   #import "@preview/mathmodel:0.1.0": * #set page(width: 16cm, height: 24cm, margin: 2cm) #set heading(numbering: "1.", level: 1) #set math.equation(numbering: "Eq.") #title[2026年全国大学生数学建模竞赛C题：新能源汽车充电站选址优化] #author[建模队：启明队] #date[2026年9月12日] #section[问题重述] #paragraph[ 本题要求在127个候选点中选出≤20个充电站，最小化用户平均等待时间... ] #section[模型构建] #paragraph[ 我们建立混合整数规划模型： #align[ #equation[ min ∑_{i∈U}∑_{j∈S} d_{ij}·x_{ij} ] #equation[ s.t. ∑_{j∈S} x_{ij} = 1, ∀i∈U // 每个用户分配到一个站 ] #equation[ ∑_{i∈U} x_{ij} ≤ 500, ∀j∈S // 单站服务上限 ] ] ] #section[求解与结果] #let demand = load_csv("input/demand.csv") #let sites = load_geojson("input/candidate_sites.geojson") #let solution = @skill-solver-mip-charge( demand: demand, sites: sites, max_stations: 20, capacity_per_station: 500 ) #block[ #text[最优解：选定 ] #text[(solution.selected_sites.len()).str()] #text[ 个站点] #text[，平均等待时间：] #text[(solution.avg_wait_time).round(2)] #text[ 分钟] ] #figure[ #caption[充电站选址结果（红色点）与用户分布（蓝色点）] #show skill-plot-geospatial( sites: solution.selected_sites, users: demand, map_source: "openstreetmap" ) ]

3. 运行Agent生成完整论文

   # 在项目根目录执行 mathmodel build # 输出： # [INFO] Loading skills... # [INFO] Validating input data... # [INFO] Running skill-solver-mip-charge... # [SUCCESS] Build completed. Output: ./output/report.pdf

   mathmodel build命令会：① 解析main.typ中的@skill-*调用；② 按依赖顺序执行SKILLS；③ 实时捕获每个SKILL的stdout/stderr；④ 将结果注入Typst渲染引擎；⑤ 生成output/report.pdf。整个过程无需手动运行Python脚本或LaTeX编译。

常见问题排查：若mathmodel build报错ModuleNotFoundError: No module named 'gurobi'，说明skill-solver-mip-charge依赖Gurobi求解器。此时有两种方案：① 申请Gurobi学术许可（免费）并安装；② 修改agent.toml，将solver参数设为"cbc"（开源求解器），虽然求解稍慢但完全免费。我们推荐方案②，因CBC在中小规模问题上表现稳定。

4.3 调试与验证：如何确认SKILLS执行结果可信？

Agent生成的PDF再漂亮，若底层计算不可信，一切归零。MathModelAgent提供三层验证机制：

• 第一层：SKILL级单元测试
  每个SKILL自带tests/目录。以skill-solver-mip-charge为例，其tests/test_mip_simple.py包含：

  def test_small_instance(): # 构造3个用户、2个候选点的极简案例 demand = pd.DataFrame({"id": [1,2,3], "demand": [100,150,200]}) sites = [{"id": "A", "capacity": 300}, {"id": "B", "capacity": 300}] result = solve_mip(demand, sites, max_stations=1, capacity=300) assert result.selected_sites == ["A"] # 确认最优解为选A站 assert abs(result.avg_wait_time - 150.0) < 1e-6 # 等待时间计算准确

  运行pytest tests/test_mip_simple.py即可验证。

• 第二层：文档级结果溯源
  在生成的PDF中，每个SKILL调用处均有小字脚注，如：
  最优解：选定 18 个站点，平均等待时间：12.37 分钟¹
  点击脚注¹，PDF跳转至附录“执行日志”，显示：

  [2026-09-12 14:22:03] skill-solver-mip-charge@2.1.0 Input: demand_rows=3, sites_count=127, max_stations=20 Output: selected_sites_count=18, avg_wait_time=12.368, solver_status=optimal Runtime: 42.7s, Memory: 1.2GB

• 第三层：计算图完整性检查
  运行mathmodel graph --verify，Agent会生成output/computation-graph.dot，用Graphviz可视化计算依赖关系，并检查：① 所有输入文件是否被至少一个SKILL读取；② 所有SKILL输出是否被至少一处文档引用；③ 是否存在未使用的SKILL调用（即“死代码”）。这确保文档中每个数字都有迹可循。

5. 常见问题与避坑指南：来自三年国赛指导的真实教训

5.1 “Agent生成的图太丑，怎么换配色？”——理解Typst样式继承链

新手常抱怨：“默认图表配色太单调，我想用viridis色图”。这暴露了对Typst样式机制的误解。Typst的#show不是一次性覆盖，而是样式继承。正确做法不是在每个#show里重复写配色，而是在文档顶部统一设置：

// 全局设置图表样式 #show figure: it => { it.with( // 修改所有figure的默认样式 stroke: none, fill: linear-gradient( from: (0%, 0%), to: (100%, 100%), stops: ( ("#440154", 0%), // 紫 ("#3b528b", 50%), // 蓝 ("#21918c", 100%) // 青 ) ) ) } // 此后所有#show skill-plot-*都会自动应用此配色 #figure[#show skill-plot-geospatial(...)]

踩坑实录：曾有队伍为改一张图的配色，在#show里硬编码color: "#ff6b6b"，结果导致其他12张图全部失效。根源在于Typst的样式优先级：局部#show> 文档级#show> 默认样式。应始终优先用文档级#show统一管理。

5.2 “运行mathmodel build卡住不动”——识别三类阻塞点

Agent卡顿通常源于以下原因，按发生频率排序：

现象	原因	解决方案
卡在[INFO] Running skill-xxx...	SKILL内部死循环或等待外部资源（如网络API）	查看output/logs/skill-xxx.log，找到最后一条日志。若含requests.get(，检查网络代理设置；若含while True:，联系SKILL作者修复。
卡在[INFO] Rendering document...	Typst渲染复杂公式或大图时内存不足	在agent.toml中添加render_memory_limit = "2G"，或简化图表（如将dpi=600改为dpi=300）。
卡在[INFO] Validating input data...	input/目录下存在损坏的CSV（如中文逗号分隔）	运行csvvalidator input/demand.csv（MathModelAgent自带工具），它会指出第17行第3列“预期数字，得到‘未知’”。

实操技巧：为快速定位问题，可在mathmodel build后加--debug参数：mathmodel build --debug。这会输出详细调用栈，并在output/debug/生成每个SKILL的输入/输出快照，方便对比。

5.3 “队友的Agent生成PDF和我的不一样”——环境一致性保障

这是团队协作最大雷区。根源在于SKILLS版本或Typst版本差异。解决方案是锁定环境：

1. 导出SKILLS依赖清单

   mathmodel skills list --export=requirements.txt # 生成skills-requirements.txt，内容如： # skill-solver-mip-charge==2.1.0 # skill-plot-geospatial==1.3.2

2. 队友安装时指定版本

   pip install -r skills-requirements.txt

3. 统一Typst版本
   在agent.toml中强制指定：

   [render] typst_version = "0.10.0" # Agent会自动下载并使用此版本，忽略系统已装Typst

重要提醒：不要用pip freeze > requirements.txt！这会导出所有Python包（包括numpy、pandas），而SKILLS只关心自身依赖。MathModelAgent的skills list --export只导出SKILLS元数据，精准可控。

5.4 “评委说‘模型假设不够合理’，怎么快速补充？”——利用Agent的假设管理功能

MathModelAgent内置#assume指令，专为管理模型假设设计：

#assume[ #text[假设1：用户充电需求服从泊松分布] #text[依据：历史数据显示每小时进站车辆数方差≈均值] ] #assume[ #text[假设2：电网容量约束为硬约束] #text[依据：题目明确要求“不得超负荷运行”] ]

当运行mathmodel build时，Agent会：① 将所有#assume块收集到附录“模型假设”；② 自动检查假设与后续模型公式的一致性（如发现#assume中写“线性关系”，但模型中出现log(x)，则警告）；③ 在PDF目录中生成“假设”章节，方便评委快速查阅。

避坑经验：往年有队伍将假设写在正文段落里，导致评委遗漏。用#assume指令，既保证格式统一，又实现机器可读——Agent甚至能统计“共提出7条假设，其中3条有数据支撑，4条引用文献”。

6. 进阶：定制你的专属SKILLS与Typst模板

6.1