math-modeling-skill

# 数学建模竞赛全流程标准化 Skill 本 skill 从多轮真实数学建模竞赛任务(含四问、56 页、20+ 轮迭代修订的完整竞赛论文)与一个桌面端数学建模智能体工作流软件(mathflow,6 智能体 S0–S6 流水线、98+ 测试)中共同提炼而来。每条规则都是真实竞赛或真实智能体工程中被评审/用户真正纠正过的教训,不是空泛建议。适用于所有数学建模竞赛,不限定任何特定赛事。文中引用的具体赛事数值只作示例,规范本身通用。 ## 核心理念(贯穿所有环节) 1. **大道至简**:优先机理/结构模型(幂律、对数线性、微分方程、排队论、优化模型),参数少、每个参数有业务含义;只在简单模型确实无法解决时才逐步增加复杂度。一个讲得清的简单模型 + 严谨统计推断,永远胜过堆砌的集成黑箱。 2. **可解释性优先**:模型要能说出"为什么",给出弹性系数、显著性、残差诊断等。机器学习(随机森林/XGBoost)只作**非参数稳健性检验**与参数模型对照,不作主角;必须用黑箱时配 SHAP/LIME 等可解释性补救。 3. **诚实**:结果如实报告,改善小就写小,退化就写退化,不挑好看的指标,不编造数据。诚实本身是加分项(模型评价一节有话说)。但"如实披露"建立在**已尝试多种方法**基础上;结果很差时先改进,不要直接提交差结果。 4. **忠于题目**:题目给出的官方公式、口径、规则原样采用(如旅行负担口径、休息约束定义、归一化公式),不自己发明替代口径。只允许**等价改写**(形式变了、数学上完全等价,且注明"等价于题目定义")。 5. **完整闭环**:读题 → 建模 → 求解 → 验证 → 图表 → 论文 → 审稿 → 交付,每步都有可交付产物,代码与论文一一对应。 6. **降 AI 味**:论文读起来要像资深参赛者手写,不是 AI 腔。具体反模式见 `references/writing.md` 第 5 节,核心是:不用破折号"——"过度、不堆"xx-xx-xx"三段式、不故弄玄虚、数字与单位间不加多余空格、不写"值得注意的是""综上所述"等套话。 ## 何时读哪个 reference | 任务阶段 | 读 | 核心内容 | |---|---|---| | 读题/拆解 | `references/parsing.md` | 读题协议、图片多模态识别、数据文件结构探查、问题类型判定、拆题 JSON | | 选方案/建模 | `references/modeling.md` | 大道至简偏好序、候选方案 2-3 个、小巧思技法、可解释性验证、诚实披露、优化模型完整形式 | | 写代码/求解 | `references/coding.md` | 防伪数据红线、真实数据绝对路径、Search-Replace 纠错、可复现清单、求解汇总提炼 | | 做图 | `references/visualization.md` | nature/science/IEEE 三套配色、八大绘图类型选择指南、宋体+Times 字体、TikZ 流程图(各问解题流程=蛇形横向布局+现代柔和6色,见 §5.1.1)、图片命名规范、CJK 豆腐块预警、图表就近/说明字数/占比规范 | | 画论文总体架构图 | `skills/tikz-architecture-diagram/SKILL.md` | **仅用于"论文总体架构图"(1 张,放问题分析节,分层架构图)**;其余各问解题流程图仍用 `visualization.md` 的**蛇形(横向)TikZ 画法**(§5.1.1,现代柔和 6 色),不要混用 | | 写论文 | `references/writing.md` | cumcmthesis 结构骨架(类文件 `templates/cumcmthesis/cumcmthesis.cls` 已随 skill 自带)、各部分长度分布、摘要规则(铺满约80%版心/按小问成段:背景→针对问题一/二…/数值与重点方法加粗)、公式规范、降 AI 味、图表排版硬规范(就近/100–150字/≤2/3占比禁图挨图/公式图后空行)、每问≥10处必要公式推导/定义/约束/证明(主要必要不重复不水,实在写不出不强求)、图表呼应、正文页数 21–30、不分点原则、空白 playbook | | 审稿/修改 | `references/review.md` | 九维评审(方法/题目/谬误矛盾/数值/创新/图表位置/正文页数/布局/乱码)、三级问题清单、版面逐页视觉审查、乱码复检、评分表、修复循环 | | 版面自动体检 | `scripts/check_layout.py` | 交付前一键扫描:图表就近、说明文字 100–150 字、单页占比 ≤2/3、禁图挨图、正文页数 21–30、乱码——五项违规自动报行号 | 通常按工作流顺序读对应 reference 即可;交付前**必读 `review.md` 并完成审查循环**。如果时间紧只读一个,读 `review.md`。 ## 工作流(一次竞赛任务的标准推进顺序) 按以下 7 个阶段推进。每个阶段都有明确输入、产物、检查点;用户在检查点交互,其余自动推进。 ### 阶段 0:启动与环境自检 - 检查 Python ≥3.10、xelatex、pandas/openpyxl/matplotlib/pdfplumber 等依赖。 - **取得 `cumcmthesis.cls`(论文编译的前提,缺它直接 `File 'cumcmthesis.cls' not found`)**:优先 `kpsewhich cumcmthesis.cls` 看系统是否已装;若未装,把本 skill 自带的离线副本 `templates/cumcmthesis/cumcmthesis.cls` 复制到任务 `05_paper/` 与 `main.tex` 同目录(副本=官方 cumcmthesis v2.9,2026/08/26,随 CTeX 发布,仅作离线兜底,以系统版优先)。 - 落地工作目录骨架(见下"目录结构")。 - **产物**:`logs/env_check.json`。 ### 阶段 1:读题与拆解(详见 `references/parsing.md`) - 解析赛题文件(.md/.txt/.pdf/.docx/.doc);题目图片用多模态识别(公式转 LaTeX),生成"图N 描述"。 - 探查附件数据结构:每个 CSV/Excel 的 sheet/列名/行数,落 `task_package.json`。 - 拆题:Q1..Qn,每问给出 `rephrased`(一句话复述)+ `type`(回归/优化/评估/仿真/预测/分类)。 - **检查点 CP1**:用户确认拆题是否完整、类型判定是否准确。 - **产物**:`task_package.json`(题面+图片描述+数据文件清单)、拆题 JSON。 ### 阶段 2:方案选择与建模(详见 `references/modeling.md`) - 按"大道至简偏好序"为每问给 2~3 个候选方案,每个写明:方法名、核心数学公式(LaTeX)、算法步骤、验证计划。 - 候选方案须差异化(不同模型族),不是同族微调。 - **检查点 CP2**:用户点选每问的最终方案,回写 `modeling_doc.json` 的 `chosen` 字段。用户未显式选择时,默认选第一个候选(兜底)。 - 建模手自反思:每个方案的假设是否合理、参数是否有业务含义、是否可解释。 - **产物**:`modeling_doc.json`(每问 candidates + chosen + 反思日志)。 ### 阶段 3:代码实现与求解(详见 `references/coding.md`) - 逐问写可复现 Python 代码,必须用 `pandas.read_excel/read_csv` 读取真实数据文件的**绝对路径**。 - **红线**:严禁 `np.random`/`random` 生成模拟数据却未读真实文件 → 触发"假数据检测"自动纠错。 - 每问至少 5 张可视化图(各图意思互不重复),保存到 `results/` 子目录;中文先设字体。 - 写码 → 运行 → 报错 → **Search-Replace 增量修复**(只改出错处,不重写全文,避免长代码截断)。纠错上限 10 轮/问。 - 求解完成后提炼"求解汇总"(每问关键数字 + 结论),供论文手直接引用。 - **产物**:`Q1/solve.py` ... `Qn/solve.py`、各 `results/` 下详细命名的图片(如 `Q1_各赛季观众数时序折线图.png`,非 fig1.png)与结果 CSV、`solve_summary.md`。 ### 阶段 4:可视化(详见 `references/visualization.md`) - **结构图分两类,别画错(见 `visualization.md` §5.0)**: - **① 论文总体架构图(1 张)**:放在"问题分析"节末尾,用 `skills/tikz-architecture-diagram` 子技能的分层架构画法(数据题面层 → 模型构建层 → 算法求解层 → 结果输出层 → 结论推广层),跨平台字体回退 + Okabe-Ito 分层配色。这是全篇唯一一张"总览式"架构图。 - **② 各问解题流程图(每问 1 张)**:放在每问"模型建立"开头,用 `visualization.md` 的**蛇形(横向)TikZ 画法**(§5.1.1,现代柔和 6 色,整体横向展开像波浪,绝非"糖葫芦"直线),`\resizebox{0.92\textwidth}{!}` 控宽。**注意:两类图不要混用画风**——总体架构图只用 architecture 子技能(分层架构),各问流程图只用蛇形横向 TikZ。 - 数据图:直接复用阶段 3 编程手产出的 `results/` 图片(真实反映求解结果),不重新生成。 - 统一风格:nature/science/IEEE 三套学术配色选一、中文宋体+西文 Times、去 top/right 边框、数值直接标注、图片详细命名(见 `visualization.md`)。 - **产物**:`figures/` 下所有论文用图(含 1 张总体架构图 + 各问流程图 + 数据图)。 ### 阶段 5:论文写作(详见 `references/writing.md`) - 基于 cumcmthesis 模板(`\documentclass[withoutpreface,bwprint]{cumcmthesis}`,xelatex 编译)。**编译前确认 `cumcmthesis.cls` 已在 `05_paper/` 同目录**(见阶段 0 取得方式;也可从官方 `cumcmthesis` 仓库/`tlmgr install cumcmthesis` 获取)。 - **分章节生成**(避免单次输出超长被截断):题目摘要 → 问题分析(节末尾放总体架构图)→ 问题假设 → 符号说明 → 逐问模型建立与求解(每问先规划 3~5 小节再逐节写,开头放该问 TikZ 流程图)→ 评价与改进 → 总结 → 参考文献 → 附录代码。 - 论文手定图单:从编程手产出的结果图片里挑数据图,各问流程图用阶段 4 的 TikZ,总体架构图用 `tikz-architecture-diagram` 子技能产出。 - **图表排版硬规范(见 `writing.md` §6,交付前由 `scripts/check_layout.py` 自动体检)**: - **就近**:图表用 `[H]` 紧邻说明文字,内容上与正文"追随"关系一致;避免 LaTeX 浮动体飘移到远页(同页或相邻页)。 - **说明文字 100–150 字**:四段式写——这是什么图/表 → 怎么得到的 → 关键数字是什么 → 说明什么结论(见 `writing.md` §6.2 范例)。 - **单页占比 ≤2/3,禁图挨图**:单页图表视觉面积不过 2/3;两图之间至少 40 字正文,不得出现"满页都是图"。 - **正文页数硬约束**:不含附录 ≤30 页(红线),目标 21–30 页;偏薄就补解释/灵敏度/假设讨论,偏厚就把代码移附录、砍重复图(见 `writing.md` §7.5,**绝不靠拉行距/放大图凑页**)。 - 拼接固定 preamble(含 `float`/`placeins`/`caption` 宏包,见 `writing.md` §6.5)+ 各章节片段为完整 `main.tex`(骨架保证 `\end{document}` 完整)。 - 编译 + Search-Replace 修复循环:xelatex 报错 → 提取报错附近源码 → 只修复出错片段 → 重编译。上限 3 轮。 - **降 AI 味**贯穿所有章节写作(见 `writing.md` 第 5 节)。 - **产物**:`paper/main.tex`、`paper/main.pdf`。 ### 阶段 6:审稿与修改(详见 `references/review.md`) - 审稿人按 **九维评审** 逐项审查(见 `review.md` §1):① 方法选取是否合理 ② 是否完成题目全部要求 ③ 是否出现谬误与前后矛盾 ④ 数值是否合理 ⑤ 是否有一定创新 ⑥ 图表放置位置是否合理 ⑦ 正文页数是否 ≤30 且落在 21–30(红线)⑧ 页面布局是否合理 ⑨ 图片是否有乱码。每维给 1–5 分,任何维度 ≤3 分即进入修复循环。 - 分级:**红线级 / 一致性级 / 美观级**;只有无红线级与一致性级问题、美观级也较少时才"通过"。 - **页面布局视觉审查(必做,有多模态能力时)**:用 `pdftoppm` 把每页转 PNG(300dpi),逐页看图检查——图表是否飘移太远、是否满页图、字号/留白是否均衡、是否有重叠/溢出(见 `review.md` §10.3)。 - **图片乱码三道关(缺一不可)**:① 编译日志无 `Missing character`/`Glyph missing` 警告;② PDF 文本层无 `�`/□/■ 缺字;③ 逐页转图肉眼无豆腐块(见 `review.md` §10.4)。 - **先跑 `scripts/check_layout.py`** 自动体检(图表就近 / 说明 100–150 字 / 单页占比 ≤2/3 / 禁图挨图 / 正文页数 21–30 / 乱码),据报错修源码 → 重编译 → 再审。 - 需修复时:把审稿意见反馈给论文手修改(片段修复,避免全文截断)→ 重编译 → 再审稿。上限 3 轮。 - 交付前必做交付清单(见下)。 - **产物**:`review_report.json`、最终 `main.pdf`。 ### 阶段 7:交付 - 参赛论文 PDF(LaTeX/xelatex + cumcmthesis,中文宋体、西文 Times 风格)。 - 支撑材料 zip:`代码/`(按问命名,可复现)+ `结果/`(标准命名 CSV)+ `README.md`(运行顺序与依赖)+ AI 工具使用说明(赛规要求时)。代码与论文附录用 `\lstinputlisting` 自动加载,保证一致。 - 项目架构说明:记录每个产物的来源与依赖。 ## 目录结构(每个任务一套) ``` <task_id>/ ├── 01_problem/ # 赛题原文(.md/.pdf/.docx/.png) ├── 02_data/ # 附件数据(原始,只读) ├── 03_modeling/ # task_package.json、modeling_doc.json ├── 04_solving/ │ ├── Q1/solve.py + results/(Q1_内容_图表类型.png, *.csv) │ └── Q2/... ├── 05_paper/ │ ├── figures/ # 论文用图(数据图+流程图) │ └── main.tex / main.pdf ├── 06_delivery/ # 支撑材料 zip + README ├── logs/ # env_check.json、运行日志 └── state/run_state.json # 断点续跑状态 ``` ## 交付物质量门禁(交付前逐项检查;任何一项不过 → 修复 → 重审,循环直到全部通过) **审查与评分(先做,按 `references/review.md` 完整协议):** - [ ] 题目逐条要求全覆盖:每问每个子任务都有论文章节 + 可复现产物支撑;输出文件命名/单位/表头/小数位符合题目规定 - [ ] 题目给出的公式、定义、口径未被擅自篡改:论文公式 = 题目定义 = 代码实现,三者一致 - [ ] 代码—论文一致:论文每个公式/算法/数值在代码中可复现,方法细节与代码实际行为一致,命名口径四者(论文/代码/结果CSV/README)一致 - [ ] 无数据泄露:时序只用过去、特征不用开球后才知道的信息、标准化只在训练集内 fit、CV/OOB 如实标注 - [ ] 数学推导正确:量纲/符号/边界条件核对,统计量可重算 - [ ] 全文字体统一:中文宋体、西文数字 Times 风格,正文/标题/图表/表头同一字体语言 **版式与工程(其次):** - [ ] 无未定义引用、无重复标签(`grep -iE "undefined|multiply defined" main.log` 为空) - [ ] 摘要与标题在同一页(第 1 页),且铺满约 80% 版心、按小问成段(背景→针对问题一/二…)、数值与重点方法加粗 - [ ] 每页底部空白 < 约 90pt(超出则按 `writing.md` 第 7 节 playbook 处理) - [ ] 无 CJK 豆腐块(findfont / Glyph missing 警告视为失败,必须修复) - [ ] 无新增大段 overfull(> 10pt 的 hbox 溢出要消除) - [ ] 编译前置:`cumcmthesis.cls` 已就位(`main.tex` 同目录,来自系统安装或本 skill 副本 `templates/cumcmthesis/cumcmthesis.cls`),否则 xelatex 报 `File 'cumcmthesis.cls' not found` - [ ] 公式/图/表后另起正文段落不顶格:非"式中:"时,`\end{equation}`/`\end{figure}`/`\end{table}` 后留空行(见 `writing.md` §3.3) - [ ] 每个优化模型有完整 max + s.t. + 大括号形式 - [ ] 所有图表配色字体统一、数值标注齐全、图题表题风格统一 - [ ] 图片文件名详细可识别内容(`Q{题号}_{内容}_{图表类型}.png`,无 fig1.png 之类) - [ ] 一页最多两张图表,无 AI 同质化图(雷达图不绘制;热力图仅确实合适时绘制,不滥用,见 `visualization.md` §2.9) - [ ] 支撑材料文件名/单位/口径与论文完全一致 - [ ] **图表就近**:每张图表用 `[H]` 紧邻说明文字,内容上与正文追随关系一致,不飘移到远页(同页或相邻页);由 `scripts/check_layout.py` 的"就近"项核验(见 `writing.md` §6.1) - [ ] **图表说明文字 100–150 字**:四段式(是什么→怎么来→关键数字→说明什么),不写"如图/表所示"空话;由 `check_layout.py` 的"说明字数"项核验并报告行号(见 `writing.md` §6.2) - [ ] **单页图表占比 ≤2/3 且禁图挨图**:单页图表视觉面积不超过 2/3;两图之间至少 40 字正文,不得出现"满页都是图";由 `check_layout.py` 的"占比/图挨图"项核验(见 `writing.md` §6.3) - [ ] **正文页数硬约束**:不含附录 ≤30 页(红线),落在 21–30 页为目标;`check_layout.py` 的"正文页数"项自动判定(附录位置自动识别,可用 `--body-end` 覆盖)(见 `writing.md` §7.5) - [ ] **页面布局视觉审查**:`pdftoppm` 逐页转 PNG 逐张查看,无图表飘移、无满页图、无重叠/溢出、留白均衡(见 `review.md` §10.3) - [ ] **图片乱码三道关**:编译日志无 `Missing character`/`Glyph missing`;PDF 文本层无 `�`/□/■;逐页转图肉眼无豆腐块(见 `review.md` §10.4 / `visualization.md` §7.1) - [ ] 无 AI 味:无破折号过度、无三段式堆砌、无套话、无多余空格(见 `writing.md` 第 5 节) 审查评分(见 `review.md` 第 8 节)中任何维度 ≤3 分,或上述任何一项未过,都进入修复循环,修复后重跑全清单,直到全部通过才交付。 ## 在 agentic 编码工具中加载使用 本 skill 目录可直接放入以下位置后即用: - **Claude Code**:`~/.claude/skills/math-modeling-skill/`(或项目 `.claude/skills/`) - **Codex / 类似工具**:按其 skill 加载约定放置 - **WorkBuddy**:`~/.workbuddy/skills/math-modeling-skill/` 或通过 SkillManage 安装 工具识别到用户意图匹配 `description` 中的触发词时,自动加载本 `SKILL.md`,并按"何时读哪个 reference"表按需读取子文件。每个 reference 都是独立可读的,无需全部加载。