name: math-modeling description: 当用户要求数学建模、建模竞赛、建模分析、代码求解、结果可视化或生成数学建模论文时使用。支持完整三阶段流程，也支持只执行建模手、编程手或论文手中的一个阶段。

数学建模

本 Skill 用三个独立角色完成数学建模。生成的论文仅供用户参考，不作为可直接提交的作品。论文结构与格式必须以目标竞赛当届官方规则和官方模板为准，不能用往届经验替代官方要求。

根目录契约

• SKILL_ROOT：本文件所在目录，只读。角色说明、算法资料、脚本和模板都从这里读取。
• PROJECT_ROOT：用户题目和项目所在目录，所有新产物只能写入这里。
• 两个根目录必须不同；默认禁止覆盖 SKILL_ROOT 内任何文件。
• 输入附件只读。确需修改模板时，先复制到 PROJECT_ROOT 再处理。

路由

不要在单阶段任务中强制执行完整流程。

固定交付物

建模手

只交付：

1. 题目分析报告.md
2. 术语表格.md

编程手

交付：

1. 可运行的 Python（.py）或 MATLAB（.m）代码；可同时交付两种语言。
2. 代码运行结果表格，如 .csv、题目要求的 .xlsx。
3. 原始数据图、模型运行过程图、模型最终结果图。图可以多生成候选版本，由用户和论文手选择。
4. results/复现清单.json，含随机种子、输入文件 SHA-256、运行时和依赖版本、关键参数、唯一复现命令。

论文手

只交付一份完整的 .docx 论文。内部检查记录不作为额外交付物。

阶段反馈闭环

• 编程手发现公式不完整、约束冲突或模型不可实现时，停止猜测，在对话中列出证据并回到建模手修正两个 Markdown 交付物。
• 论文手发现关键结论没有真实结果、图表或文献支撑时，回到编程手或建模手补齐，禁止编造。
• 修正后从被阻断阶段继续，不重复已通过的阶段。

建模约束

1. 先完整理解题目、附件、目标、约束和评价口径，再形成结论与模型方案。
2. 每道子问题最多使用两个独立模型体系。物理题中，同一控制方程或同一物理机制在不同近似阶次、边界条件或精度下的展开，计为一个模型族，不机械拆成多个模型；只有控制机理、状态变量或求解目标实质不同才另计模型。辅助的灵敏度分析、误差检验和可视化不计作独立模型。
3. 避免直接套用过于常见的简单模型来冒充创新；创新必须来自问题结构、数据处理、约束设计、算法改进或验证方式，并说明依据。
4. 数据判定标准按题目、官方规则、领域文献或数据分析结果确定。
5. 不因两个模型得到相近结论就强制删除其中一个；是否保留由研究目的和证据价值决定。

渐进式加载

先读当前阶段的 SKILL.md，再按其中“何时加载”表读取所需参考，禁止一次性加载全部资料。

完整导航见 references/README.md。

完成判定

• 所有计算结论来自实际运行结果。
• 公式、表格和图表与代码结果一致。
• 引用可由 OpenAlex、AnySearch 或原始出版页面追溯。
• 论文已按目标竞赛当届官方规则配置，篇幅目标已经确认，Word 公式可编辑，公式/图/表数量经过检查，图表编号与正文引用连续，参考文献与正文引用双向对应，DOCX 结构校验和渲染页数检查通过。
• 所有产物位于 PROJECT_ROOT，SKILL_ROOT 未被改写。

🎯 Math Modeling Skill

面向数学建模竞赛与建模项目的三阶段工作流

关注我

📖 简介

本 Skill 将数学建模任务拆分为 建模分析 → 代码实现 → 论文撰写 三个阶段。既可以按顺序完成整道题，也可以只执行其中一个阶段。

当前版本：1.0.0

生成的论文仅供参考。论文结构与格式必须以目标竞赛当届官方规则和官方模板为准。

✨ 核心能力

• 🧠 建模分析：读题、检查附件、拆分子问题、选择模型、设计求解与验证方案。
• 💻 双语言实现：支持 Python 和 MATLAB，按选中的模型与功能动态检查依赖。
• 📊 完整结果输出：生成结果表格、原始数据图、模型运行过程图和最终结果图。
• 🔁 可复现运行：记录随机种子、输入文件 SHA-256、运行时与依赖版本、关键参数和唯一复现命令。
• 🔎 双引擎论文搜索：并行调用 OpenAlex 与 AnySearch，按 DOI 或题名交叉核验。
• 📄 Word 论文生成：支持官方模板、Word 原生 OMML 公式、可编辑表格、篇幅与图文引用检查、结构校验和渲染抽检。
• 🧩 渐进式加载：只读取当前阶段需要的角色规范、算法资料和工具说明。

🔄 三阶段工作流

阶段反馈

• 编程手发现公式、约束或参数无法实现时，携带实际报错返回建模手修正。
• 论文手发现关键结论缺少真实结果、图表或文献支撑时，返回对应阶段补齐。
• 修正后从被阻断阶段继续，不重复已经通过的阶段。

🚀 快速开始

推荐 Agent

本 Skill 可用于支持本地 Skills 或 Agent 工作流的工具，例如 Claude Code、Codex、Cursor、Trae 和 Qoder。具体加载方式以对应工具的当前文档为准。

安装

Git 克隆

git clone https://github.com/XiaoMaColtAI/math-modeling-skill.git

克隆后，将仓库放入所用 Agent 的 Skills 目录或按其方式加载本目录。

npx 安装

npx skills add https://github.com/xiaomacoltai/math-modeling-skill --skill math-modeling

也可以下载仓库 ZIP，解压后放入对应 Skills 目录。

使用示例

完整流程：

使用数学建模 Skill 完成这道题，从题目分析一直生成完整 Word 论文。

单阶段执行：

只做建模分析，输出题目分析报告和术语表格。
只实现现有模型，使用 MATLAB 运行并生成全部结果和图。
根据现有代码结果生成完整论文.docx。

主入口见 SKILL.md。

📁 工作目录约定

• SKILL_ROOT：本仓库根目录，只读；角色规范、算法资料、脚本和模板从这里读取。
• PROJECT_ROOT：用户题目所在目录；所有运行产物只写入这里。
• 题目与附件保持只读；需要修改模板时，先复制到 PROJECT_ROOT。

典型产物结构：

PROJECT_ROOT/
├── data/                         # 题目附件，只读
├── 题目分析报告.md
├── 术语表格.md
├── 问题1_求解.py 或 问题1_求解.m
├── results/
│   ├── 问题1_结果.csv
│   └── 复现清单.json
├── figures/
│   ├── raw_*.svg / raw_*.png
│   ├── process_*.svg / *.png
│   └── result_*.svg / *.png
└── 完整论文.docx

🛠️ 集成工具

双引擎论文搜索

python tools/paper_search/scripts/hybrid_scholar.py \
  --query "robust optimization vehicle routing" \
  --limit 10 \
  --json

• OpenAlex 可通过 --email 提供礼貌池邮箱。
• AnySearch 需要密钥时设置环境变量 ANYSEARCH_API_KEY。
• 正式检索默认同时运行两个引擎；单引擎参数只用于诊断。

动态依赖检查

Python 只检查实际需要的功能：

python references/roles/编程手/scripts/check_env.py \
  --features data visualization optimization

MATLAB 使用：

addpath("references/roles/编程手/scripts");
report = check_matlab_env(["data", "visualization", "optimization"]);

🧮 算法资料

算法资料覆盖七类问题：

先读取 算法索引，再按问题类型加载对应资料。每道子问题最多使用两个独立模型体系；物理题中同一机理的基础近似与高精度展开按一个模型族计数。

📄 论文生成

推荐采用模板驱动方式：

当届官方模板
  → python-docx 填充正文、表格和图片
  → LaTeX 严格转换为 Word 原生 OMML
  → 篇幅、公式、图表、编号引用和参考文献校验
  → DOCX 结构校验与渲染页数抽检

官方模板包含固定摘要页、编号页或占位符时，在原位置填充；只借用模板样式时，清除示例正文后再生成论文。

CUMCM 默认以约 15000 字词单位、约 20 页作为完整度质量目标，但这不是官方最低要求。以 2026 年官方规范为例，摘要原则上不超过一页、正文不超过 30 页；实际交付必须重新核对目标届次的官方文件。校验器还会检查公式、图、表的基本数量，图表题注与正文引用，以及参考文献和正文引用是否双向对应。

📸 示例展示

以下图表展示本项目可视化规范生成的候选图效果。

2025 年国赛 A 题：烟幕干扰弹的投放策略

2025 年国赛 B 题：碳化硅外延层厚度的确定

🏆 适用场景

工作流可用于 CUMCM、MCM/ICM、APMCM、MathorCup、认证杯、数维杯等数学建模竞赛和一般建模项目。不同竞赛的页面、摘要、编号、页数和提交格式必须按当届官方要求配置。

📂 仓库结构

math-modeling-skill/
├── VERSION
├── SKILL.md
├── README.md
├── CHANGELOG.md
├── assets/                         # 算法资料
├── imgs/                           # README 示例图
├── references/
│   ├── README.md                   # 渐进式导航
│   ├── 算法索引.md
│   └── roles/
│       ├── 建模手/
│       ├── 编程手/
│       └── 论文手/
├── tools/                          # DOCX、PDF、XLSX、论文搜索
└── tests/                          # 回归测试

✅ 验证

python -m unittest discover -s tests -v
python tools/docx/scripts/self_check.py
python -m compileall -q tools references/roles/编程手/scripts

回归测试覆盖双引擎搜索、公式转换、DOCX、Excel 重算、论文结构、动态依赖和复现清单。

📋 版本与更新日志

当前版本：1.0.0

1.0.0 由 GPT 5.6 Sol 进行全面检查和完善，系统修正了角色工作流、双引擎论文检索、公式转换、DOCX/Excel 工具、Python/MATLAB 支持、可复现机制、路径隔离和渐进式加载。详细内容见 CHANGELOG.md。

采用语义化版本 MAJOR.MINOR.PATCH：

• MAJOR：固定交付物、目录契约、命令参数或数据结构发生不兼容变化。
• MINOR：增加向后兼容的新能力。
• PATCH：向后兼容的错误修复、文档校正或测试补充。

完整记录见 CHANGELOG.md。

⭐ GitHub Star 历史

🙏 致谢

• AnySearch Skill：为学术垂直搜索提供参考。
• Nature Skills：为科学可视化与写作方法提供参考。

算法索引 · 使用文档 · 角色说明 · 更新日志