mathmodel-skill
A structured Agent workflow for CUMCM, MCM/ICM, and Diangong Cup — designed to keep a 72–96 hour modeling project coherent from the first decision to the final submission.
数学建模比赛很少因为“缺少一个更聪明的回答”而失败。
更常见的情况是：模型已经换了，摘要还没有更新；第二问重新求解后，第三问仍在引用旧结果；某个关键假设只存在于聊天记录里；直到提交前，团队才发现匿名、页数或 AI 使用披露不符合要求。
mathmodel-skill 为这些问题而设计。
它不是一个试图一次生成整篇论文的 Prompt，也不是一个替团队做决定的黑盒 Agent。它是一套可执行的建模工作流：将选题、拆题、模型选择、求解、稳健性分析、论文装配和终审组织为 10 个阶段，并用一份共享决策日志保存整个项目的状态。
当比赛持续数十小时、队员交替协作，或者工作从 Codex 切换到 Claude Code 时，项目仍然能够沿着同一条主线继续，而不是重新依赖聊天上下文和个人记忆。
支持：
- Codex Skills
- Codex Plugin
- Claude Code
日常使用中，你不需要手工维护 JSON，也不需要记住每个脚本的参数。Agent 会在需要判断的节点向团队确认，并负责维护状态、调用工具和整理产物。
设计动机 · 工作方式 · 设计原则 · 竞赛支持 · 快速开始 · 可信边界
为什么需要它
一场数学建模比赛，本质上不是一道独立问题，而是一组彼此依赖的决定。
选题会影响数据与时间分配；假设会限制模型边界；模型会决定求解方式与图表；结果发生变化后，摘要、评价、灵敏度分析和结论都需要同步调整。
如果这些依赖只存在于对话记录、临时文件或某位队员的记忆里，协作就会逐渐失去一致性。项目可能仍在向前推进，但不同部分已经不再描述同一个模型。
mathmodel-skill 将这些隐含关系显式化。
它帮助团队持续回答四个问题：
- 现在进行到哪一步？
- 已经做出了哪些决定？
- 这些决定基于什么证据？
- 哪些条件满足后，项目才能继续？
它不保证模型一定正确，也不预测奖项。它做的是更基础、也更重要的事情：让项目可以被恢复、检查、局部修改，并最终交付。
它如何工作
flowchart LR
A["题目与团队约束"] --> B["10 阶段主流程"]
C["竞赛特化包"] --> B
D["decision_log.json"] <--> B
B --> E["模型 · 结果 · 图表 · 论文"]
E --> F["L1 / L2 / L3 / L4 反馈"]
F -->|"定向修补"| B
整个系统由三部分组成。
1. 主流程
主流程定义阶段顺序、进入条件、退出条件和回退路径。
每个阶段都有明确的输入与产物。Agent 不会把整场比赛压缩成一次长执行，而是在可检查的位置停下来，让团队知道已经完成了什么，以及为什么可以继续。
2. 共享决策日志
state/decision_log.json 是项目的连续记忆。
它记录：
- 竞赛与题目选择
- 模型候选及淘汰理由
- 假设、符号和术语
- 各阶段评分与 verdict
- 子问状态与局部回修
- 规则核对与 AI 使用台账
- 最终交付状态
对话用于交流，日志用于接力。即使上下文切换，项目状态仍然保留在工作区中。
3. 确定性工具
语言模型适合分析、比较与生成，但并不适合承担所有机械检查。
因此，评分重算、模板装配、环境诊断、差分应用、AI 披露生成和部分合规检查由脚本完成。模型负责需要判断的工作，脚本负责可以确定的工作，团队保留最终决定权。
这套工作流解决什么问题
| 比赛中的常见情况 | mathmodel-skill 的处理方式 |
|---|---|
| 对话越来越长，早期决定难以追溯 | 所有阶段共用 state/decision_log.json，统一保存选择、依据、评分与回退记录 |
| 总体表现尚可，但某个关键维度明显不足 | Verdict 同时检查最低分和加权均分；高严重度问题不能被平均数掩盖 |
| 只有 Q2 需要返工，却牵连全部结果 | Stage 5 按 Qi 保存状态，支持 refine_partial，只修改受影响的子问 |
| 三类竞赛要求不同，维护成本不断增加 | 保留一条主流程，通过 competition pack、权重 overlay 和模板表达差异 |
| Markdown 章节已经生成，但主 TeX 没有正确引用 | 模板使用显式 section marker；缺失、重复或未知 marker 会直接失败 |
| 封面或摘要仍含占位符，却被误当作正式稿 | 正式渲染采用 fail-closed 检查；占位符只能用于显式 dry-run |
| 临近提交才发现页数、匿名或 AI 披露问题 | Stage 0、8、9 会重新打开规则入口；未通过合规门不能进入 submission_ready |
| Pandoc、TeX 或依赖问题直到最后才暴露 | doctor.py 集中检查结构、竞赛包、Python、Pandoc、TeX 与可选依赖 |
设计原则
mathmodel-skill 的设计目标不是加入尽可能多的组件，而是让每个组件只承担自己最擅长的工作。
工作流优先于超长 Prompt
更长的 Prompt 可以增加背景信息，却不能天然维护状态、依赖与回退路径。
这里仍然使用模型完成各阶段任务，但“项目现在在哪里”“上一阶段决定了什么”“什么条件下可以继续”由工作流显式维护。上下文可以变化，项目结构不需要随之消失。
检索提供证据，不管理流程
RAG 很适合寻找竞赛规则、领域论文、真实数据和方法依据，但它并不负责决定下一阶段，也不会自动判断新结果是否推翻旧假设。
因此，仓库内材料采用版本可控、按阶段加载的竞赛包；外部检索负责提供证据，主流程负责组织行动。
Multi-Agent 只用于适合并行比较的环节
多个 Agent 在选题比较、模型攻击和终稿评审中很有价值，但如果每一步都依赖多方协商，协调成本和符号漂移会迅速增加。
主流程始终围绕一份共享日志推进。并行视角只出现在适合独立判断的节点；终稿 Panel 可以并行执行，也可以在单 Agent 环境中顺序降级。
自动化停在可以检查的位置
单 Agent 并不等于黑盒。
fast 和 standard 模式都可以由一个 Agent 完成，但每个阶段仍然留下明确产物，关键选择仍然需要确认，评分仍然由脚本重算，问题仍然可以按 section 或 Qi 局部修补。
团队可以随时查看进度、接管项目、切换模型，或回到某个具体决定，而不必从头重做。
一些小而重要的设计
同一份状态可以被不同工具读取
Codex 与 Claude Code 可以在同一工作区中读取相同的 state schema。这里的共享来自项目目录，而不是云同步，因此切换工具时仍需保留完整工作区与产物。
团队回答问题，Agent 维护流程
选竞赛、选题、接受模型、决定回修等节点通过原生选择 UI 或编号列表完成。团队负责方向判断，Agent 负责状态写入、文件组织和脚本调用。
只加载当前阶段需要的材料
根目录 SKILL.md 只承担调度职责。阶段细则、rubric、竞赛规则和模板按需加载，避免无关内容占用上下文。
一条流程服务三类竞赛
CUMCM、MCM/ICM 与电工杯不会被维护为三套互相漂移的工作流。它们的差异被限制在：
competitions/<comp>/- 题型与阶段权重
- LaTeX 模板
- 提交与披露规则
最低分不会被均分覆盖
加权均分可以用于排序，但任何低于门槛的关键维度都需要单独处理。题型权重被限制在 [0.7, 1.5]，避免局部偏好过度放大。
局部错误优先局部修复
Stage 5 保存每个 Qi 的分数、权重和状态。某个子问失败时，流程只返回真正受影响的位置，而不是默认推翻全部结果。
经验数据只作为参照
CUMCM 分位描述的是公开样本中的观察位置，不是官方评分线，也不能用于推导获奖概率。
MCM/ICM 与电工杯的经验层明确记录为 n=0，不会生成缺乏数据支持的“经验分位”。
规则记录日期，但不假装永久有效
current_rules.md 保存最近核对日期和官方入口。Stage 0、8、9 仍要求重新查看当届通知，因为仓库基线不能覆盖未来变化。
AI 使用从过程开始记录
台账记录工具、版本、使用阶段、用途、采用内容和人工复核。
CUMCM 会根据是否使用 AI 生成相应的支撑材料 PDF 或正文声明；MCM 报告会直接接入主模板，避免截止前再依赖记忆补写。
能自动验证的内容不依赖“记得检查”
YAML/JSON、竞赛包、反模式计数、评分边界、模板 marker、渲染 dry-run 和代码模板边界均有自动测试覆盖。
10 个阶段
| Stage | 任务 | 关键产物 | 主要检查 |
|---|---|---|---|
| 0 | 团队启动与资料预扫 | 竞赛、角色、时限、环境、规则基线 | 可执行性与合规入口 |
| 1 | 多题比较与选题 | 选择理由、放弃项、题型判断 | 资源匹配与失败风险 |
| 2 | 问题拆解 | 子问、变量、约束、依赖图 | 逻辑完整性 |
| 3 | 模型选型 | 候选模型、证据、反事实与淘汰理由 | 模型与问题的匹配程度 |
| 4 | Foundation | 假设、符号、术语表 | 一致性与可解释性 |
| 5 | 递归求解 Q1…Qn | formulation、代码、结果、图表 | per-Qi 评分与定向回修 |
| 6 | 稳健性分析 | 风险匹配的验证、稳健区间、失败边界 | 灵敏度与结论可靠性 |
| 7 | 模型评价 | 优点、局限、改进、迁移条件 | 边界是否诚实、结论能否推广 |
| 8 | 论文装配 | paper_workspace/*.md、TeX/PDF、AI 台账 |
跨阶段一致性与格式合规 |
| 9 | 提交前终审 | 最终 PDF、支持材料、Panel 记录 | 合规门、证据链与视觉检查 |
反馈模式
三种模式使用同一条主流程，只调整反馈预算和评审深度。
| Mode | 反馈层 | 适用场景 |
|---|---|---|
fast |
L1 单轮 | 选题试跑、快速 sanity check |
standard |
L1 + L2 | 默认比赛流程 |
championship |
L1 + L2 + L3 + L4 + red-team | 终稿前的深度评审 |
评分工具输出的是流程状态，而不是奖项预测：
block · refine · refine_partial · pass_with_review · pass · pass_early · carryover
竞赛支持
| 竞赛包 | 语言与模板 | 当前材料 | 可信度说明 |
|---|---|---|---|
| CUMCM 国赛 | 中文；XeLaTeX / 原创 ctexart 电子论文模板 |
收集 91 份公开论文源样本，其中 59 份成功提取文本并进入统计；42 项维护者反模式检查 | 当前材料最完整；观察分位不是官方门槛，规则以当届通知为准 |
| MCM/ICM 美赛 | English；pdfLaTeX / article |
16 项维护者检查；已记录 COMAP 2027 页数、字号与 AI 披露基线 | 经验层 n=0，不提供论文分位；提交前必须重新核对 COMAP 要求 |
| 电工杯 | 中文；XeLaTeX / ctexart |
12 项工程导向检查；已记录官网页序、25 页正文、支撑材料与匿名基线 | 经验层 n=0；当前官网未提供专门 AI 格式，仍需检查当届通知 |
截至 2026-07-22，仓库已核对：
这些链接构成仓库当前的规则基线，但不能替代参赛当年的官方文件。
Quick Start
Codex
macOS / Linux
git clone https://github.com/handsomeZR-netizen/mathmodel-skill.git \
~/.agents/skills/mathmodel-skill
python ~/.agents/skills/mathmodel-skill/scripts/doctor.py \
--competition cumcm
mkdir -p my-modeling-project
cd my-modeling-project
codex
Windows PowerShell
git clone https://github.com/handsomeZR-netizen/mathmodel-skill.git `
"$HOME\.agents\skills\mathmodel-skill"
python "$HOME\.agents\skills\mathmodel-skill\scripts\doctor.py" `
--competition cumcm
New-Item -ItemType Directory -Force my-modeling-project | Out-Null
Set-Location my-modeling-project
codex
进入 Codex 后输入：
使用 $mathmodel-skill，开始 CUMCM 建模。
首次启动时，Agent 会先确认竞赛、题目、队伍能力、截止时间和题面位置，然后创建共享状态并进入 Stage 0。工作区已经存在状态时，则从最近的检查点继续。
也可以安装到当前项目：
mkdir -p .agents/skills
git clone https://github.com/handsomeZR-netizen/mathmodel-skill.git \
.agents/skills/mathmodel-skill
Claude Code
git clone https://github.com/handsomeZR-netizen/mathmodel-skill.git \
~/.claude/skills/mathmodel-skill
mkdir -p my-modeling-project
cd my-modeling-project
claude
进入 Claude Code 后输入：
开始建模
或：
使用 mathmodel-skill 开始 MCM 建模
可选：完整数值环境
核心工作流和 doctor.py --skip-tools 不依赖完整的科学计算栈。只有在需要运行仓库中的建模起步代码时，才需要安装额外依赖：
python -m pip install -r \
~/.agents/skills/mathmodel-skill/templates/shared/requirements.txt
正式进行论文转换与编译时，还需要安装 Pandoc 和 TeX Live 或 MiKTeX。
简化转换器仅用于 --no-compile 结构预检，不应作为正式论文的编译方式。
- CUMCM 与电工杯使用 XeLaTeX
- MCM/ICM 使用 pdfLaTeX
工作区产物
my-modeling-project/
├── state/
│ └── decision_log.json # 决策、评分、回退、规则与 AI 使用台账
├── results/ # 结构化结果与可复现实验输出
├── figures/ # 最终图表
├── paper_workspace/ # 01_abstract.md … 10_appendix.md，以及按需披露片段
├── paper_output/ # TeX 中间文件与最终 PDF
└── support_materials/ # 代码、数据清单与竞赛要求的披露材料
Codex 与 Claude Code 可以在同一目录中接力。decision_log.json 负责保存流程状态，但不会自动同步工作区之外的文件。
辅助工具
| 工具 | 用途 | 典型调用 |
|---|