mathmodel-skill

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

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

v6.1 更新: 加入竞赛规则基线与 AI 使用披露链路；三竞赛统一使用 marker 模板并对提交元数据 fail closed；修复状态路径错位、评分 verdict 持久化、题型权重合并和 YAML frontmatter 等问题；新增 preflight 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.1 以 Codex Skills 为一等入口, 同时保持 harness-agnostic 设计:

harness	入口文件	用户交互工具	状态文件
Claude Code	SKILL.md (本文件)	AskUserQuestion 工具	<cwd>/state/decision_log.json
Codex CLI / Codex app	skill 目录中的 SKILL.md + 可选 AGENTS.md	markdown 编号列表	同上 (互通)

跨 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 根目录的相对路径	references/stage_05_subproblem_loop.md, templates/shared/decision_log.json
竞赛特化	competitions/<comp>/... 按 decision_log.competition dispatch	competitions/cumcm/winning_patterns.md, competitions/mcm/abstract_template.md
LaTeX 模板	templates/latex/<comp>/main.tex	templates/latex/cumcm/main.tex, templates/latex/mcm/main.tex
用户产物	用户工作目录的相对路径	<cwd>/state/, <cwd>/results/, <cwd>/figures/, <cwd>/paper_workspace/
state 持久化	<cwd>/state/decision_log.json	各 stage 必读必写
环境变量	MATHMODEL_STATE_DIR (兼容 CUMCM_STATE_DIR) / MATHMODEL_COMPETITION 可覆盖	scripts 用此变量

约定: <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):
   - 不存在 `<cwd>/state/decision_log.json` → 创建目录并复制 `<skill>/templates/shared/decision_log.json` 到该路径
   - 写入 decision_log.competition = <选定竞赛>
   - 已存在 → 读 current_stage 字段决定恢复点

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. 读 `<cwd>/state/decision_log.json` 的 competition 与 current_stage
2. 加载对应 stage_NN.md (按需结合 competitions/<comp>/* 内容)
3. 不重复读 winning_patterns

---

三竞赛 × 三模式 矩阵

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

Competition	时长	语言	LaTeX	规则基线	经验数据状态
cumcm	72h	中文	xelatex / 原创 ctexart	CUMCM 2026	91 来源文档 / 59 可提取样本
mcm	96h	English	pdflatex / article	COMAP 2027	n=0，无论文分位
diangong	72h	中文	xelatex / ctex	官网 2026-03-21 页面	n=0，无论文分位

Mode	上下文策略	反馈层	用途
fast	只保留当前阻断项与最小证据	L1 单次	选题试跑 / sanity check
standard	按阶段加载并保留决策摘要	L1+L2	默认主流程
championship	在终审阶段扩展证据与独立视角	L1+L2+L3+L4 + red-team	提交前最后冲刺

模式自动推荐 (按距 deadline 剩余):

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

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

---

10 段階のインデックス

#	段階	reference	所要時間	フィードバック	競技ごとの相違点
0	チームの立ち上げ + 資料の事前確認	stage_00_kickoff.md	1h	L1	所要時間 / 言語 / コンパイラー / 問題番号体系
1	問題の選定（複数問題の比較 → 1 問）	stage_01_problem_selection.md	2-4h	L1	問題番号体系 (A-E/A-F/A-B) + task_type の記録
2	問題の詳細な分析と分解	stage_02_analysis.md	2-3h	L1	共通
3	モデルの選定（エビデンスに基づく候補の比較）	stage_03_model_selection.md	2-4h	L1 + 反実仮想	共通
4	Foundation（仮定 + 記号 + 用語）	stage_04_foundation.md	1h	L1	共通
5	再帰的なサブ問題ループ Q1..Qn + per-Qi の加重集計	stage_05_subproblem_loop.md	問題ごとに割り当て	L1 + サブチェックポイント	問題文から実際のサブ問題数を抽出；per-Qi 加重
6	全体的な感度分析 / ロバスト性	stage_06_robustness.md	2-3h	L1 + L2	工学パラメーター (diangong) と数学パラメーター (cumcm/mcm)
7	モデルの評価 + 拡張	stage_07_evaluation.md	1-2h	L1	共通
8	論文の執筆 + コンプライアンス対応	stage_08_writing.md	12-30h	L1 + L2	当該年度のルール、AI の開示、要旨の種類と LaTeX テンプレート
9	提出要件への準拠 + パネル	stage_09_review.md	2-6h	L1 + L3 panel	ページ数 / 匿名性 / 開示 + anti-patterns + ペルソナ

---

読み込みプロトコル（トークン節約の要）

段階 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

---

収束基準（統一定義、3 か所で一致）

verdict の優先順位（高い順）:

verdict	発動条件	動作
block	issues に high-severity が 1 件以上含まれる	スキルを一時停止し、ユーザーが介入
pass_early	raw_min ≥ 9 AND weighted_mean ≥ 9	iter-1 で早期終了
pass	raw_min ≥ 7 AND weighted_mean ≥ 8	次の段階へ進む
pass_with_review (stage 5)	任意の Qi が mark_for_review だが、加重しきい値を満たす	stage 6 に進み、L2 は review_qis を必ず確認
refine	その他	section-patch で精緻化し、iter+=1 (上限 3)
refine_partial (stage 5)	任意の Qi.min < 7 で、その他の Qi は pass 済み	該当する Qi のみを精緻化し、他は変更しない
carryover	iter == 3 でも refine のまま	次の段階へ進み、L2 が処理するものとしてマーク

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 の 3 か所で完全に一致させる必要があります。

---

状態の永続化

各段階:

• 開始時: <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 出力を必須とし、1 回あたり約 500 token
• 精緻化戦略: section-level patch (scripts/extract_diff.py) を使用し、関連する section のみを優先して渡す
• references/ と competitions/ のファイルは遅延読み込みとし、この SKILL.md 本文は ≤ 6k tokens にする
• 段階の完了後、artifact の要約 + 重要なデータ + パスを decision_log に書き込み、全文をコンテキストに保持しない
• token 消費量を記録するのは、現在の harness / API が信頼できる usage 情報を提供する場合のみとします。観測できない場合は 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
• "看进度" → 输出 decision_log 摘要 + 当前评分

---

数据来源声明

• 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)
• 电工杯: 中国电机工程学会论文集