mathmodel-studio · 数模工坊

用于数学建模竞赛的 AI Skill，协助完成审题、建模、求解、验证和论文整理。

数模工坊为 AI 编程助手提供建模流程、方法参考和配套脚本。你可以带着一道完整赛题从头开始，也可以拿已有代码、计算结果或论文草稿，只处理当前需要帮助的部分。

支持 Codex、Claude Code、ZCode 等能够加载 Skill、读取文件并执行工具的助手。实际可用功能取决于所用平台的能力、工具权限和本地环境。

v3.4.0 重点改进模型与算法的选择：从题目、数据和误差中寻找值得验证的方向，结合文献和历史案例提出候选，再用实验比较单一方法或多模块组合。助手会主动说明推荐理由、替代方案和证据缺口，发现新问题时可以返回研究和验证。已有绘图、附件处理和论文整理能力继续保留。项目结构见 ARCHITECTURE.md。

处理附件不需要一次装齐所有依赖：WAV 和 CSV 用 Python 标准库就能查；看图需要 Pillow；视频和压缩音频需要 FFmpeg；地理和科学数据按具体格式再装 rasterio、fiona、laspy、h5py 或 xarray。做普通表格任务这些都不用装。每种格式能查什么、哪些还没实现，见 多类型附件。实验比较工具只汇总已经跑过的候选结果，不是自动训练平台。

Skill 是什么？

Skill 是一套供 AI 助手读取的专业工作指南，也可以包含脚本、模板和参考资料。

使用普通对话处理建模题时，你可能需要反复提醒助手：先分析题目、不要急着选模型、检查计算结果、保留数字来源、最后再写论文。数模工坊把这些要求整理进了流程，并提供相应的工具和记录方式。

使用时不需要记住内部阶段名称，也不必每次写很长的提示词。说明你正在做什么、有哪些材料、希望完成哪一步即可。

能帮你做什么？

对刚接触数学建模的人，它可以帮助理解每一步需要做什么、为什么做。对已有经验的队伍，它可以承担代码实现、结果核对、图表整理和文档处理等工作。

安装

先安装 Skill，再配置运行环境。依赖通常只需安装一次，后续换题目不需要重复配置。

1. 安装 Skill

电脑已安装 Git 时，根据使用的助手，选择一条命令执行。

Codex

git clone https://github.com/yan315598-design/mathmodel-studio.git ~/.agents/skills/mathmodel-studio

Claude Code

git clone https://github.com/yan315598-design/mathmodel-studio.git ~/.claude/skills/mathmodel-studio

ZCode

git clone https://github.com/yan315598-design/mathmodel-studio.git ~/.zcode/skills/mathmodel-studio

以上命令用于首次安装，目标目录应当尚不存在。~ 表示当前用户的主目录；Windows 用户可以在 Git Bash 中执行。

不使用 Git，也可以手动安装：

1. 在仓库页面点击 Code → Download ZIP。
2. 解压后，将文件夹命名为 mathmodel-studio。
3. 放入所用助手对应的 Skill 目录。
4. 确认 SKILL.md 直接位于该文件夹内，避免多套一层同名目录。

安装后，重新打开会话或按助手提供的方式刷新 Skill 列表。

2. 一次安装 Python 依赖

完整脚本链需要 Python 3.10 或以上版本。本轮回归测试使用 Python 3.13.9，其他版本尚未逐一验证。

在准备使用的 Python 环境中，根据安装位置执行对应命令：

Codex

python -m pip install -r "$HOME/.agents/skills/mathmodel-studio/templates/shared/requirements.txt"

Claude Code

python -m pip install -r "$HOME/.claude/skills/mathmodel-studio/templates/shared/requirements.txt"

ZCode

python -m pip install -r "$HOME/.zcode/skills/mathmodel-studio/templates/shared/requirements.txt"

这些命令适用于 Bash／Git Bash。使用其他终端时，可以直接填写依赖文件的完整路径：

python -m pip install -r "<Skill安装目录>/templates/shared/requirements.txt"

依赖文件包含常用的数据处理、科学计算、优化、机器学习、绘图和文档处理库；Windows 专用的 pywin32 会按平台条件安装。

Windows PowerShell 运行脚本前，建议为当前会话设置 UTF-8，避免中文或特殊符号输出失败：

$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"

这些设置仅影响当前会话及其子进程，不修改系统全局编码。

部分专用模型、商业求解器或可选图形功能可能仍需额外依赖。安装报错时，应先处理报错，不能把部分安装成功当作完整环境已经就绪。

3. 配置论文导出工具

Python 依赖之外，论文导出还会用到以下工具：

这些是系统工具，不包含在 pip install 命令中。Word 和 LaTeX 是两条成稿路径，可以按实际需要配置；希望两条路径都能使用时，再准备完整环境。

4. 检查是否安装成功

在助手中发出请求：

请使用 mathmodel-studio 数模工坊。

确认 Skill 已加载，并检查 Python 建模环境、绘图依赖、
Pandoc、Word 或 LibreOffice、LaTeX 和中文字体是否可用。

列出可用项、缺失项和未执行的检查，先不要安装软件或修改系统配置。

只做审题和方法讨论时，可以先开始使用。需要运行代码或导出文档时，再依据检查结果解决相应的环境问题。

第一次使用：从审题开始

打开题目所在的工作目录，将题目和附件提供给助手：

使用数模工坊，阅读当前目录里的题目和附件。

先帮我整理：
1. 每一问需要回答什么。
2. 哪些数据可以直接使用，哪些需要处理。
3. 主要约束和可能存在的歧义。
4. 开始建模前需要确认哪些问题。

先完成审题，不急着选模型和写论文。

拿到分析后，先核对助手是否正确理解了题意，尤其是单位、约束条件，以及各问之间是否需要共用结果。

确认题意后，再比较方法：

针对问题一，结合题目、数据和已有结果研究模型与算法。

参考相关文献和历史案例，提出适合本题的候选方法或组合，
说明各自要解决什么问题、依据是什么、哪些部分还没有验证。

可以先运行必要的小实验，并主动向我解释比较结果和推荐理由。
正式确定主模型前，与我讨论关键取舍。

选择路线后，进入实现：

按确认的路线处理问题一，编写并运行求解代码。

保留关键中间结果，检查约束是否满足。
如果数据不足、运行失败或结果异常，先说明问题。

不必一次性把整道题的工作全部交出去。逐问确认和推进，更容易发现题意理解、模型假设和计算结果中的问题。

一道题通常怎么推进？

实际工作中可以返回前面的步骤，也可以从已有成果接着做。

关键模型选择、图表方案和逐问结果需要使用者确认。工作记录用于保存已经确定的决策、完成情况和待解决的问题，便于后续继续。

模型和算法怎么选？

先看题目需要回答什么、数据能支持什么，以及当前方法在哪里失效。候选可以来自机理推导、数据分析、文献和历史案例；既可以是单一方法，也可以组合数据处理、特征表示、模型与求解算法。每个新增模块都应说明要解决的问题。

对影响选择的路线，助手会把文献里的机制、适用条件和实现线索转成可验证的方案，再根据时间和算力安排实验。比较时考虑数据划分、调参机会、训练是否充分和评价指标，避免因为一次实现不佳就排除整个方法方向。

推荐会说明实测优势、替代方案、成本和未解决的风险。正式单题研究按关键缺口继续检索，不设固定总篇数；没有新增信息时停止泛搜。方法更复杂并不自动代表更好，最终选择取决于本题证据。

只处理一个环节也可以

如果已经完成了一部分工作，说明已有材料和本次任务范围即可。

比较建模方法

问题二考虑使用回归模型或机理模型。

请结合题目和数据比较这两种方案：
各自依赖什么假设、如何验证，以及数据不足时怎样处理。

检查公式与代码

这是论文中的模型公式和对应代码。

请核对变量、单位、目标函数和约束是否一致，
重点检查边界条件以及可能导致结果失真的实现。

先报告问题，不修改文件。

绘制论文图表

根据已有计算结果绘制一张对比图。

保留原始数值，标明坐标单位和图例，
说明这张图可以支持什么结论，还有哪些信息不足。

整理已有论文

根据已有代码、结果和草稿，整理问题一的论文内容。

保留能够核实的数字和结论。
缺少的实验、引用或解释请明确标出，不要自行补造。

从上次进度继续

读取这个项目已有的工作记录。

先概括已经确认的模型、已完成的结果和未解决的问题，
然后继续处理问题二。

恢复进度依赖项目中保存的文件和记录。换会话或换设备时，需要保留这些材料；安装 Skill 本身不会带回之前的项目内容。

支持的竞赛

目前提供以下六类竞赛的流程与资料配置，各竞赛的案例积累深度不同。

开始时告诉助手比赛名称和题号即可：

使用数模工坊，处理全国大学生数学建模竞赛 A 题。
题目和附件都在当前目录，先完成审题分析。

华为杯和华数杯是不同竞赛。使用历史案例时，需要核对赛事、题目条件和数据背景；历史论文中的数值不能直接作为当前题目的结果。

结果、图表和论文如何对应？

模型和数据经常会在过程中调整。重新计算后，正文可能仍保留旧数字，图表和结论也可能没有同步更新。

数模工坊提供数字来源登记与一致性检查，帮助核对论文中的关键数值和计算结果。修改结果后，相关图表和文字也需要重新检查；工具不会自动证明新结论成立。

论文以 Markdown 保存内容源，再按所选路径生成 Word 或 LaTeX 文档。涉及数字、公式含义、论证或图注的修改，应同步回内容源，避免只改最终文档而留下多个不一致版本。

正式图交给助手画：先渲染，再跑自动检查（遮挡、单位、图例这类问题），有明显毛病就修一轮；机制示意图保留可编辑的源文件，方便手工微调。常规的布局和配色不用逐张来问你，但改动科学含义、明显增加计算量或要改已定风格时，仍会先确认。自动检查代替不了人眼，定稿前请把最终页面完整看一遍。拼图方法和六套示例见 任务范例，什么情况按哪层标准验收见 分层验收。

使用边界

模型假设是否合理、数据是否可信、结论是否回答了题目，仍需要使用者判断。

• 数据不足时，应补充材料、调整假设或缩小结论范围。
• 程序运行成功不代表模型正确，需要检查约束、数量级和现实含义。
• 文献检索依赖网络和服务可用性，引用前应核对来源与实际内容。
• 自动检查无法覆盖所有错误，关键结果应复现，最终论文应人工通读。
• 工具缺失、计算失败或检查未执行时，应明确记录，不能写成已经通过。
• 参赛前请核对赛事关于 AI 使用、引用和提交材料的规定。

数模工坊不承诺获奖，也不能替代队伍对论文内容的理解和负责。

更新已有安装

使用 Git 安装的用户，可以先检查本地修改：

git -C "<Skill安装目录>" status

确认没有需要保留的本地改动后，再更新：

git -C "<Skill安装目录>" pull --ff-only

如果新版调整了依赖，再执行一次对应的 pip install -r ...。使用 ZIP 安装的用户，应先保留自己的修改，再替换为新版文件。

3.4.0 更新

• 强化模型与算法研究：从题目、数据、文献和误差提出候选，支持有依据的组合，并主动解释推荐理由。
• 按研究缺口分配检索和实验预算，完善公平比较、关键实现核验和证据范围记录。
• 合并重复流程，修复阶段检查和证据追溯问题，兼容已有工作区。验证范围见 v3.4 审查记录。

3.3.0 更新

• 新增原生 Matplotlib axes 组合、毫米画布、共享图例/色条与独立修订导出；旧 CLI、模板 ID、返回值与 save_fig 行为不变。
• A-F 六类合成范例支持选择运行和面板拆装，不是图型白名单，也不替代领域求解。
• 实验比较 v2 支持任务分型、实例内重复、多目标与未知成本；图库 v2 区分诊断、候选、审阅、采用和排除。
• 修复缺测连线、预览替代原图质检、混合坐标误判；补强原 mask、TIFF、NPZ、NetCDF 检查。
• 科学约束、交付检查和设计建议分层；已有授权不重复询问，必交内容不受图库预算限制。
• 已知限制：示例仍待最终尺寸视觉目检；GIS/点云/3D/视频等可选后端未全部实测，不宣称已支持完整分析。详见 docs/upgrade_acceptance.md。

3.2.0 更新

• 默认入口减重，启动、专项能力与竞赛细则按需读取。
• 先探索、跑基线和比较，再确定正式模型与图型。
• 新增附件检查、实测比较和备选图库工具，保留证据与运行预算。

验证范围与本地后端限制见 docs/upgrade_acceptance.md；历史验证记录保留在 CHANGELOG。

详细变更见 CHANGELOG.md。

许可证

项目许可证见 LICENSE。随仓库分发的第三方资源遵循各自的许可证，使用和再分发时请同时查看对应说明。