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
整个系统由三部分组成。
主流程定义阶段顺序、进入条件、退出条件和回退路径。
每个阶段都有明确的输入与产物。Agent 不会把整场比赛压缩成一次长执行，而是在可检查的位置停下来，让团队知道已经完成了什么，以及为什么可以继续。
state/decision_log.json 是项目的连续记忆。
它记录：
- 竞赛与题目选择
- 模型候选及淘汰理由
- 假设、符号和术语
- 各阶段评分与 verdict
- 子问状态与局部回修
- 规则核对与 AI 使用台账
- 最终交付状态
对话用于交流，日志用于接力。即使上下文切换，项目状态仍然保留在工作区中。
语言模型适合分析、比较与生成，但并不适合承担所有机械检查。
因此，评分重算、模板装配、环境诊断、差分应用、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 可以增加背景信息，却不能天然维护状态、依赖与回退路径。
这里仍然使用模型完成各阶段任务，但“项目现在在哪里”“上一阶段决定了什么”“什么条件下可以继续”由工作流显式维护。上下文可以变化，项目结构不需要随之消失。
RAG 很适合寻找竞赛规则、领域论文、真实数据和方法依据，但它并不负责决定下一阶段，也不会自动判断新结果是否推翻旧假设。
因此，仓库内材料采用版本可控、按阶段加载的竞赛包；外部检索负责提供证据，主流程负责组织行动。
多个 Agent 在选题比较、模型攻击和终稿评审中很有价值，但如果每一步都依赖多方协商，协调成本和符号漂移会迅速增加。
主流程始终围绕一份共享日志推进。并行视角只出现在适合独立判断的节点；终稿 Panel 可以并行执行，也可以在单 Agent 环境中顺序降级。
单 Agent 并不等于黑盒。
fast 和 standard 模式都可以由一个 Agent 完成，但每个阶段仍然留下明确产物，关键选择仍然需要确认，评分仍然由脚本重算，问题仍然可以按 section 或 Qi 局部修补。
团队可以随时查看进度、接管项目、切换模型，或回到某个具体决定，而不必从头重做。
Codex 与 Claude Code 可以在同一工作区中读取相同的 state schema。这里的共享来自项目目录，而不是云同步，因此切换工具时仍需保留完整工作区与产物。
选竞赛、选题、接受模型、决定回修等节点通过原生选择 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 仍要求重新查看当届通知，因为仓库基线不能覆盖未来变化。
台账记录工具、版本、使用阶段、用途、采用内容和人工复核。
CUMCM 会根据是否使用 AI 生成相应的支撑材料 PDF 或正文声明；MCM 报告会直接接入主模板，避免截止前再依赖记忆补写。
YAML/JSON、竞赛包、反模式计数、评分边界、模板 marker、渲染 dry-run 和代码模板边界均有自动测试覆盖。
| 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，仓库已核对：
这些链接构成仓库当前的规则基线，但不能替代参赛当年的官方文件。
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
codexgit 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-skillgit 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 负责保存流程状态，但不会自动同步工作区之外的文件。
| 工具 | 用途 | 典型调用 |
|---|---|---|
scripts/doctor.py |
检查 skill 结构、竞赛包、环境与工作区 | python <skill>/scripts/doctor.py --competition mcm |
scripts/score_artifact.py |
校验 critic JSON、重算加权分数与 verdict、聚合 per-Qi | python <skill>/scripts/score_artifact.py ... |
scripts/extract_diff.py |
生成并应用 section-level patch | python <skill>/scripts/extract_diff.py --apply ... |
scripts/render_paper.py |
将标准 Markdown 工作区装配为三类竞赛的 TeX/PDF | python <skill>/scripts/render_paper.py --competition cumcm --workspace paper_workspace |
scripts/render_ai_usage.py |
根据台账生成 CUMCM/MCM AI 使用披露材料 | python <skill>/scripts/render_ai_usage.py --competition mcm ... |
scripts/ingest_papers.py |
供维护者离线更新经验统计 | 见 scripts/README.md |
完整 CLI 参数与依赖边界见 scripts/README.md。
SKILL.md # 工作流主入口与调度协议
agents/openai.yaml # Codex UI 元数据
.codex-plugin/plugin.json # Codex Plugin manifest
skills/mathmodel-skill/SKILL.md # Plugin 发现 shim
AGENTS.md # 仓库维护约定
competitions/
cumcm/ # 规则、59 份样本统计、写作启发、评分覆盖与模板骨架
mcm/ # COMAP 规则基线；经验统计 n=0
diangong/ # 官网规则基线；经验统计 n=0
references/
stage_00_* ... stage_09_* # 按阶段加载的执行细则
feedback_layer1_* ... layer4_* # 阶段评分、回检、Panel 与校准
model_catalog.md # 模型候选目录
templates/
latex/{cumcm,mcm,diangong}/ # 三类竞赛 LaTeX 模板
shared/ # 状态、AI 台账、表格与 Python 起步代码
config/dim_weights.json # 竞赛 × 题型 × 阶段的评分权重
scripts/ # 环境检查、评分、差分、装配、披露与维护工具
tests/ # 回归测试与 fixture
v6.1 主要补强了环境预检、论文装配、评分一致性、AI 使用披露和数值示例的可靠性。
- 新增
doctor.py，统一检查包结构、竞赛包、反模式计数、模板 marker 和工具链状态。 - 三类竞赛生成的 section 会自动接入
main.tex。缺失章节、空章节、未知 marker 或重复 marker 都会明确失败，正式编译不会静默降级。 - CUMCM 改用仓库原创、MIT 授权的
ctexart电子论文模板。模板不包含身份字段，并对摘要页、正文页数和最终提交元数据执行 fail-closed 检查。 - 评分器改为由脚本重新计算 verdict，同时校验 stage、iteration、最低分、均分和题型权重，修复旧 verdict 被错误持久化的问题。
extract_diff.py --apply不再要求与应用差分无关的 critique 输入。- 新增 AI 使用台账与披露生成器：CUMCM 根据“已使用 / 明确未使用”生成支撑材料 PDF 或正文声明；MCM 报告自动进入主模板，并避免重复标题。
- 补充电工杯官网规则基线，将封面、摘要起始页码、无目录、正文与附录顺序纳入模板和终审门。
- 修复分类交叉验证中的标准化泄漏、优化示例中的不可行贪心基线、熵权法常数列、GM(1,1) 极限和 MAPE 零值边界。
- 将 CUMCM 样本口径校准为“91 份来源、59 份可提取文本”；Stage 9 会根据当前竞赛动态加载对应反模式清单，不再在共享状态中写死数量。
- 加入自动测试和 GitHub Actions，覆盖配置、评分、模板装配、AI 披露与数值边界。
mathmodel-skill 是协作与质量控制工具，不是自动获奖系统。
使用它并不会消除建模本身的不确定性，也不能替代团队对公式、代码、数据、事实、引用和最终署名的责任。
需要特别说明的是：
- CUMCM 统计来自公开样本中成功提取文本的 59 份论文，可能受到年份、题型、来源和 PDF 可提取性的影响。
winning_patterns.md、经验分位和反模式清单属于维护者总结，不是官方 rubric。- MCM/ICM 与电工杯的经验统计目前均为
n=0，相关写作模式只能作为启发，不能解释为实测获奖规律。 - 竞赛规则会变化。仓库保存的是最近一次核对的基线，正式提交前必须以当届官方通知和题目要求为准。
- AI 生成的公式、代码、事实和引用必须由团队复核。台账和披露生成器帮助完整记录，但不代替合规判断。
python -m compileall -q scripts templates/shared/code_starter
python -m unittest discover -s tests -p 'test_*.py' -v
python scripts/doctor.py --competition cumcm --skip-tools
python scripts/doctor.py --competition mcm --skip-tools
python scripts/doctor.py --competition diangong --skip-tools当工作流、模板或竞赛包发生变化时，请同步更新测试、版本号和规则核对日期。
参与贡献前请先阅读 AGENTS.md。Bug、规则更新与改进建议可以通过 Issue 提交。
仓库原创代码、文档以及三类竞赛装配模板采用 MIT License。运行时依赖和外部资料链接仍遵循各自的许可条款，详细边界见 THIRD_PARTY_NOTICES.md。
mathmodel-skill 不替团队完成思考。
它做的是让每一次判断都留下依据，让每一次修改都知道影响范围，也让一场漫长的建模协作最终能够被完整地交付。