handsomezr-netizen-mathmodel-skill

---

数学建模比赛很少因为“缺少一个更聪明的回答”而失败。更常见的是：模型换了，摘要没改；第二问重算了，第三问还在引用旧结果；关键假设只活在聊天记录里；直到提交前，才发现匿名、页数或 AI 披露不合规。

mathmodel-skill 不是一个试图一口气生成整篇论文的 Prompt，也不是替团队做决定的黑盒 Agent。它是一套可执行的建模工作流：把选题、拆题、模型选择、求解、稳健性分析、论文装配和终审组织成 10 个阶段，用一份共享决策日志保存整个项目的状态。团队只回答关键的编号问题，Agent 负责维护状态、调用脚本、整理产物。

[!TIP] 一句话上手：安装后在 Codex 里输入 使用 $mathmodel-skill，开始 CUMCM 建模。，或在 Claude Code 里说 开始建模。之后随时说 “看进度”，就能看到当前阶段、评分、合规门和下一步。

✨ 为什么是 mathmodel-skill

🧭 10 阶段，一条主线

选题 → 拆题 → 选型 → 求解 → 稳健性 → 写作 → 终审。每个阶段都有进入条件、退出条件和回退路径，Agent 在可检查的位置停下来，而不是一口气跑到底。

🧠 一份状态，随时接力

state/decision_log.json 记录每个决定、依据、评分与回退。换队员、换对话、从 Codex 换到 Claude Code，都从同一个检查点继续，不靠聊天记忆。

⚖️ 脚本裁决，不靠自评

Critic 打分之后，由 score_artifact.py 重新计算 verdict。任何关键维度低于门槛都会单独暴露，不会被加权均分“平均掉”。

🎯 哪里错，只修哪里

Stage 5 按子问保存状态：refine_partial 只返工没通过的 Qi，其余结果保持不动；论文按 section patch 定向修补，不推倒重来。

🛡️ 提交前 fail-closed

占位符、缺失章节、模板 marker 错位会直接失败；当届规则、匿名、页数、AI 披露、支撑材料五道终审门不过，就不能标记 submission_ready。

📊 一眼看进度 v6.2 新

status.py 汇总 10 个阶段的 verdict、子问状态、合规门和截止倒计时，按剩余时间给出模式建议，并只给出一条明确的下一步。

它专门对付这些“翻车现场”

😵 比赛中的常见情况	✅ 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 与可选依赖
忙了一整天，说不清现在到底卡在哪	status.py 只读汇总进度、阻断项与下一步，不改动任何状态

🎬 30 秒看懂

① 开口说一句 —— Agent 只询问还缺的启动信息（竞赛、题号、队伍、截止时间、题面），然后用 init_workspace.py 建好工作区。

② 关键决策点，只需回答数字 —— 没有原生选择 UI 的环境会退化为编号列表，语义完全一致：

【Stage 3 · Q1 用哪个候选模型？】

  1) 混合整数规划 (MILP) — 目标与约束线性，求解器可给出最优性证明
  2) 遗传算法 — 适合非凸、高维离散搜索
  3) 禁忌搜索 — 中等规模组合优化，易实现
  4) 让我决定（推荐 1：Stage 2 已标记目标为线性）

回复数字即可。

③ 任何时候说“看进度” —— 下面是 status.py 对一份示例状态的真实输出：Stage 5 中只有 Q2 没过，所以下一步只精修 Q2。

🧭 工作流全景

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 记录	合规门、证据链与视觉检查

每一轮评审如何收敛

评分工具输出的是流程状态，而不是奖项预测。Critic 给分之后，verdict 一律由脚本重新计算：

stateDiagram-v2
    direction LR
    state "L1 Critic 打分" as critic
    state "脚本重算 verdict" as verdict
    state "进入下一阶段" as next
    state "定向修补" as patch
    state "团队介入" as human
    [*] --> critic
    critic --> verdict
    verdict --> next: pass / pass_early
    verdict --> next: carryover
    verdict --> patch: refine / refine_partial
    patch --> critic: 迭代 +1
    verdict --> human: block
    human --> critic: 处理后重评

Verdict	触发条件	行为
block	存在至少 1 个高严重度问题	暂停流程，由团队介入
pass_early	最低分 ≥ 9 且加权均分 ≥ 9	首轮即可提前通过
pass	最低分 ≥ 7 且加权均分 ≥ 8	进入下一阶段
pass_with_review Stage 5	个别 Qi 需复核，但加权阈值满足	进入 Stage 6，L2 必读复核项
refine	其他情况	section patch 精修，最多 3 轮
refine_partial Stage 5	部分 Qi 最低分 < 7，其余已通过	只精修这些 Qi
carryover	达到迭代上限仍需精修	进入下一阶段，遗留问题交给 L2 回检

三种反馈模式

同一条主流程，只调整反馈预算和评审深度：

Mode	反馈层	适用场景
fast	L1 单轮	选题试跑、快速 sanity check、时间紧张时的关键阶段
standard	L1 + L2	默认比赛流程
championship	L1 + L2 + L3 + L4 + red-team	终稿前的深度评审

status.py 会按剩余时间给出建议（< 6h 直接进 Stage 9 终审；6–24h 关键阶段用 fast；其余用 standard），但切换模式始终需要团队确认。

🏆 竞赛支持

竞赛包	语言与模板	当前材料	可信度说明
🇨🇳 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 格式，仍需检查当届通知

• CUMCM 2026 竞赛规则
• CUMCM 2026 论文格式规范
• COMAP 2027 Instructions
• 电工杯参赛规则
• 电工杯论文规范

这些链接构成仓库当前的规则基线，但不能替代参赛当年的官方文件。

🚀 快速开始

1. 安装

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

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

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

2. 开口说一句

环境	输入
Codex	使用 $mathmodel-skill，开始 CUMCM 建模。
Claude Code	开始建模，或 使用 mathmodel-skill 开始 MCM 建模

首次启动时，Agent 只询问还缺的竞赛、题号、队伍能力、截止时间和题面位置，然后初始化工作区并进入 Stage 0；工作区已有状态时，则从最近的检查点继续。

3. 之后只需要回答问题

Agent 会在需要判断的节点停下来问你；状态写入、文件组织和脚本调用都由它完成。任何时候都可以说：

看进度 · 进入 stage N · 回退到 stage M · 做 L2 回检 · 升级到 championship · 切到 mcm

[!NOTE] 想先手动体验看板？两条命令即可（init_workspace.py 只创建、不覆盖已有状态）：

python ~/.agents/skills/mathmodel-skill/scripts/init_workspace.py \
  --competition cumcm --workspace . --problem 未公布 --hours-left 72
python ~/.agents/skills/mathmodel-skill/scripts/status.py --workspace .

核心工作流和 doctor.py --skip-tools 不依赖完整的科学计算栈。只有需要运行仓库中的建模起步代码时，才需要安装额外依赖：

python -m pip install -r \
  ~/.agents/skills/mathmodel-skill/templates/shared/requirements.txt

正式进行论文转换与编译时，还需要安装 Pandoc 和 TeX Live 或 MiKTeX：CUMCM 与电工杯使用 XeLaTeX，MCM/ICM 使用 pdfLaTeX。内置简化转换器仅用于 --no-compile 结构预检，不应作为正式论文的编译方式。

📦 工作区产物

my-modeling-project/              # 由 init_workspace.py 创建
├── 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/init_workspace.py 新	创建工作区与初始状态；已有状态时只报告恢复点，从不覆盖	python <skill>/scripts/init_workspace.py --competition mcm --problem C --hours-left 96
scripts/status.py 新	只读进度看板：阶段 verdict、per-Qi、合规门、倒计时、模式建议与下一步	python <skill>/scripts/status.py --workspace . --markdown
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 --stage 5 --critique ...
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。

🧠 设计原则

flowchart LR
    A["题目与团队约束"] --> B["10 阶段主流程"]
    C["竞赛特化包"] --> B
    D[("decision_log.json")] <--> B
    B --> E["模型 · 结果 · 图表 · 论文"]
    E --> F["L1 / L2 / L3 / L4 反馈"]
    F -->|"定向修补"| B
    D -.-> G["status.py 进度看板"]

系统由三部分组成：主流程定义阶段顺序、进入/退出条件和回退路径；共享决策日志是项目的连续记忆；确定性工具承担评分重算、模板装配、环境诊断、差分应用、AI 披露生成和合规检查。

更长的 Prompt 可以增加背景信息，却不能天然维护状态、依赖与回退路径。这里仍然使用模型完成各阶段任务，但“项目现在在哪里”“上一阶段决定了什么”“什么条件下可以继续”由工作流显式维护。上下文可以变化，项目结构不需要随之消失。

RAG 很适合寻找竞赛规则、领域论文、真实数据和方法依据，但它并不负责决定下一阶段，也不会自动判断新结果是否推翻旧假设。因此，仓库内材料采用版本可控、按阶段加载的竞赛包；外部检索负责提供证据，主流程负责组织行动。