name: mathmodel-skill description: CUMCM 国赛、MCM/ICM 美赛与电工杯数学建模竞赛的端到端协作工作流。Use when a user explicitly works on one of these modeling contests or asks to run/review a modeling-competition paper from problem selection through modeling, solving, robustness, writing, compliance, and final submission review. Provides 10 stages, persistent decision state, competition-specific rules/templates, deterministic scoring helpers, numbered decisions, and Codex/Claude Code handoff. Do not trigger for generic model selection, ordinary data analysis, or non-competition paper review.

mathmodel-skill — 数学建模三竞赛工作流 (v6.2)

10 阶段把 72–96 小时的竞赛协作变成可恢复、可检查的流程。用户回答关键问题，agent 维护状态与脚本。每阶段产出经过 rubric 自评、定向精修与跨阶段一致性回检；Stage 8–9 先遵守当届官方规则，再做多视角终审。CUMCM 包含 91 份来源文档，其中 59 份进入文本统计；MCM/电工杯经验统计明确为 n=0，不提供合成分位。

v6.2 更新: 新增 scripts/init_workspace.py（只创建、不覆盖的工作区初始化）与 scripts/status.py（只读进度看板：阶段 verdict、per-Qi、合规门、截止倒计时、模式建议与下一步）；启动与“看进度”改由脚本确定性完成。v6.1 的规则基线、AI 披露链路、fail-closed 模板与 doctor 预检保持不变。

Codex 原生入口

Codex 优先按 skill 目录发现本文件:

• 用户级安装: $HOME/.agents/skills/mathmodel-skill/
• 项目级安装: <repo>/.agents/skills/mathmodel-skill/
• UI 元数据: agents/openai.yaml
• 插件分发元数据: .codex-plugin/plugin.json + skills/mathmodel-skill/SKILL.md shim
• 项目指导: AGENTS.md 仍可作为 repo / workspace 级 instructions, 但不是唯一入口

当 skill 已安装后, 用户可直接说"开始建模"或显式说"使用 $mathmodel-skill 开始建模"。

Harness 兼容 (Claude Code / Codex)

本 skill v6.2 以 Codex Skills 为一等入口, 同时保持 harness-agnostic 设计:

跨 harness 互通: day 1 用 Codex 跑 stage 0-2, day 2 切回 Claude Code 接着 stage 3+, 状态完全保留。详见 references/harness_compat.md。

问答式优先 (Friendly Mode)

核心原则: 用户只需回答编号问题, 不应被要求手敲 bash / python / json。

• 离散选项 (选竞赛 / 选题 / 选模型 / verdict 决策) → 必须用问答式
• 自由文本 (PDF 路径 / 截止时间) → 单行回复
• 状态读写 (decision_log.json) → agent 自动完成
• 每个 stage 的关键决策点都有 "让我决定 (推荐 X)" 兜底选项

优先使用当前 harness 可用的原生选择 UI；没有时回退到 markdown 编号列表。两者语义等价，见 references/harness_compat.md §1。

路径解析协议 (任何阶段必读)

约定: <skill>/ = skill 安装目录, <cwd>/ = 用户 cwd, <comp>/ = 当前竞赛 (cumcm | mcm | diangong)。

Quick Start (用户首次说"开始建模")

1. 一段话介绍 (≤50 字): "启动数学建模工作流, 10 阶段 + 三竞赛, 全程问答式."

2. 收集下列 5 个启动字段；用户已经提供或 state 已记录的字段不再询问，只把尚缺字段合并成一轮问答 (Claude Code: AskUserQuestion; Codex: 编号列表):
   - 竞赛 (cumcm 国赛 / mcm 美赛 / diangong 电工杯, 默认 cumcm)
   - 题号 (依竞赛: cumcm A-E / mcm A-F / diangong A-B; "未公布"亦可)
   - 队员数 + 各人擅长 (建模/编程/写作)
   - 截止时间 (ISO 字符串或 "距现在 X 小时")
   - 题目 PDF 路径 ("未公布"亦可)

3. 自动初始化 (agent 自动完成, 不要让用户编辑 json):
   - 运行 `python <skill>/scripts/init_workspace.py --competition <comp> --workspace <cwd>`，按已知答案追加 `--problem <题号|未公布>`、`--team-size N`、`--deadline <ISO>` 或 `--hours-left H`、`--problem-pdf <path>`
   - 脚本创建 `state/ results/ figures/ paper_workspace/ paper_output/ support_materials/`，从模板生成 state 并写入 competition 与 problem_meta
   - state 已存在时脚本**不修改**任何内容，只报告 competition 与 current_stage；竞赛不一致时失败，按“切到 <comp>”处理
   - 脚本输出的模式建议只是建议；与用户确认后才改 mode 并写入 events
   - 无法运行 Python 时，才手动复制 `<skill>/templates/shared/decision_log.json` 并写入 competition

4. 加载 `competitions/<comp>/current_rules.md`（若存在），打开其中官方链接核对当届规则并写入 compliance；再按需加载 winning patterns

5. 进入 Stage 0 (`references/stage_00_kickoff.md`), 不重复问已知字段；若题面未公布，完成环境与协作准备后保持 `qi_count=null` 并等待题面，不进入 Stage 1

已有 state 触发 (用户中途回到 skill):

1. 运行 `python <skill>/scripts/status.py --workspace <cwd> --json` 取得 competition、current_stage、最新 verdict 与下一步；需要细节时再读 `<cwd>/state/decision_log.json`
2. 加载对应 stage_NN.md (按需结合 competitions/<comp>/* 内容)
3. 不重复读 winning_patterns

三竞赛 × 三模式 矩阵

时长 / 语言 / 模板 / 数据状态 由 competition 决定; token 预算 / 反馈深度由 mode 决定。两者正交组合。

模式自动推荐 (按距 deadline 剩余；scripts/status.py 按同一规则计算，仅作建议):

• 60h: standard (最后 6h 升 championship)

• 24-60h: standard
• 6-24h: fast 关键阶段 + championship 终审
• < 6h: 直接进 stage 9 (championship)

10 阶段索引

加载协议 (节省 token 的关键)

只在进入阶段 N 时加载 references/stage_NN_*.md。切勿一次性全读。

各阶段额外加载 (按需 + 按 competition 切换):

• 每阶段开头: <cwd>/state/decision_log.json 必读
• 每阶段结尾: <cwd>/state/decision_log.json 必写 (核心决策 + 5 维评分)
• stage 1-9: references/rubrics.md 对应章节 (L1 评分用)
• stage 1: competitions/<comp>/topic_specs.json (题号 → task_type 映射)
• stage 3, 5: references/model_catalog.md (跨竞赛通用)
• stage 5: per-Qi 评分跑完后调 scripts/score_artifact.py --mode aggregate_qi 聚合
• stage 0 / 8 / 9: competitions/<comp>/current_rules.md 存在时读取，并核对其中官方链接
• stage 8: competitions/<comp>/{winning_patterns, phrase_bank, abstract_template, paper_skeleton}.md
• stage 8 经验锚点: competitions/<comp>/empirical.json 只作评分前参考；CUMCM 为 59 份可提取样本的观察分位，MCM/电工杯为 n=0 占位且不得推断数值门槛
• stage 9: 先做规则合规门，再用 anti_patterns.md 与 rubric_overlay.json 的 panel personas
• 触发反馈时: 对应 references/feedback_layer*.md
• harness 适配差异 (Codex 用户必读): references/harness_compat.md

收敛准则 (统一定义, 三处一致)

verdict 优先级 (从高到低):

weighted_mean = Σ(s_i × w_i) / Σ(w_i), 权重来自 config/dim_weights.json[<comp>][<task_type>] (clamp [0.7, 1.5]); task_type=default 全 1.0 等价老逻辑。

此定义在 feedback_layer1_critic.md / rubrics.md / scripts/score_artifact.py 三处必须完全一致。

状态持久化

每阶段:

• 开头: 读取 <cwd>/state/decision_log.json, 核对 current_stage 与上下文
• 结尾: 更新 stage 节点 (核心决策 + 摒弃方案 + 评分), current_stage += 1

decision_log.json v3.1 schema 关键字段 (与 templates/shared/decision_log.json 对齐):

• root: competition, task_type, mode, current_stage, budget, events, compliance
• stage_5 扩展: qi_count, qi_weights, qi_status
• scores 扩展: 含 weighted_mean, review_qis, refine_qis (stage 5 加权聚合用)

L2 跨阶段回检 (stage 5/6/8 末尾) 读这个文件主动找冲突, 触发定向回滚: 不重做整阶段, 只针对冲突点。

上下文预算纪律

• L1 Critic 强制 JSON 输出, ~500 token/次
• 精修策略: section-level patch (scripts/extract_diff.py), 优先只传相关 section
• references/ 与 competitions/ 文件懒加载, 本 SKILL.md 主体 ≤ 6k tokens
• 阶段完成后, artifact 摘要 + 关键数据 + 路径写入 decision_log, 不在上下文保留全文
• 只有当前 harness / API 提供可靠 usage 时才记录 token 消耗；不可观测时保留为 null，不得估算成已用额度
• 上下文压力或剩余时间不足时，向用户建议从 championship → standard → fast 降级，并把确认后的 mode change 写入 events；不要声称已自动计量或静默切换

用户指令快捷

• "进入 stage N" / "重做 stage N" → 跳转
• "切到 mcm" / "切到 cumcm" / "切到 diangong" → 改 decision_log.competition (注意已有 state 兼容性)
• "升级到 championship" → 启用 L3 + L4 + red-team
• "切到 fast" → 关闭迭代
• "回退到 stage M" → 读 decision_log, 回退 current_stage 并清理 ≥M 节点
• "做 L2 回检" → 立即触发 cross-stage backtrack
• "看进度" → 运行 python <skill>/scripts/status.py --workspace <cwd> --markdown，原样展示看板与下一步 (只读，不改 state)

数据来源声明

• competitions/cumcm/: 91 份来源文档，59 份成功文本提取并进入观察分位；现有提取有局限，不能解释为官方阈值或获奖预测
• competitions/mcm/: 规则基线已按 COMAP 2027 核对；经验模式是维护者启发，empirical 为 n=0
• competitions/diangong/: 官网参赛规则与论文规范已于 2026-07-22 核对；经验模式是维护者启发，empirical 为 n=0
• 通用模型清单 references/model_catalog.md 跨竞赛复用

当前 scripts/ingest_papers.py 是维护期归档工具，不能直接重建三个竞赛包的 empirical.json。新增语料前先补来源 provenance、提取 QA 与分组样本量。

与外部资源的关系

核心工作流可离线运行；当届规则与问题要求必须从官方来源重新核对。下列资源可作人工补充:

• 国赛: personqianduixue/Math_Model, datawhalechina/intro-mathmodel, dxs.moe.gov.cn 优秀论文展廊
• 美赛: COMAP 官网 comap.com, MCM Tutorial (Frank Giordano)
• 电工杯: 中国电机工程学会论文集

数学建模比赛很少因为“缺少一个更聪明的回答”而失败。更常见的是：模型换了，摘要没改；第二问重算了，第三问还在引用旧结果；关键假设只活在聊天记录里；直到提交前，才发现匿名、页数或 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、子问状态、合规门和截止倒计时，按剩余时间给出模式建议，并只给出一条明确的下一步。

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

🎬 30 秒看懂

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

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

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

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

回复数字即可。

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

🧭 工作流全景

每一轮评审如何收敛

评分工具输出的是流程状态，而不是奖项预测。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: 处理后重评

三种反馈模式

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

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

🏆 竞赛支持

• 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. 开口说一句

首次启动时，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 可