mathmodel-studio

# mathmodel-studio — 数学建模 多竞赛通用 Skill (v2.6.0, 数模工坊 MathModel Studio) ## 版本与总述 **当前版本 v2.6.0**（2026-09-11）。本版做了三件事：① 选型告知前移到用户可见——新增模型选型入口、选择卡加“依据与文献”列、新增《选型总表》；② 外源文献检索由“未命中才触发”改为选型期默认触发；③ 修通 11 处加载不到的文件引用（含 L2/L4 反馈层、stage 4/6/7 加载表、竞赛经验笔记）。上一版 v2.5.0（2026-09-10）主打领域 playbook 与图表图题纪律。完整历史见 `CHANGELOG.md`。 建模证据纪律（现行规则）：进入 Stage 2/3/5/8 时按需读取 `references/modeling_evidence_protocol.md`，机制案例另读 `references/mechanism_distillation.md`。历史范例中的固定变量数、强制凑三族、修饰词命名和默认复用，不再作为质量要求；题面给定输入优先于跨问复用。 流程分五幕、共十个阶段（-1~9），把"3-4 天打 1 篇竞赛论文"变成可检查的步骤，全程问答式——用户只需回答编号问题，不必手敲命令。每阶段产出经过自评打分和局部精修，终局由多评委模拟评审把关。六个竞赛分支中，研究生赛、华数杯和国赛共享检索、模型接口与论文证据链，但题目、奖项、经验统计和案例身份严格隔离。 图表能力速览：自写模板 27 件（数据图 17 + 示意图 4 + 可编辑 drawio 6），统一色板，出图自动过质量检查——文字重叠越界直接报错，图内不放图名（图名写图注）。复杂多面板主图、物理场图、网络流图、TikZ 框架图由内嵌开源图表库补齐，路由细则见 `references/figure_skill_bridge.md`。 --- ## Codex 编号菜单协议 Codex CLI / Codex app 通常不会弹出 Claude Code 的 `AskUserQuestion` 选择界面。运行在 Codex 时, 不等待、不承诺弹窗 UI; 直接用 Markdown 编号菜单完成选择。 固定规则: - 离散选择必须给 `1)` 到最多 `5)` 的编号菜单。 - 主竞赛菜单固定为 `1) huaweibei 研究生赛 2) huashubei 华数杯 3) cumcm 国赛 4) 其他竞赛 5) 让我决定`；选择 4 后再选 mcm / diangong / apmcm。上下文出现“华为杯/研究生赛”时默认 `huaweibei`，出现“华数杯”时默认 `huashubei`。 - 题号、模型、verdict、是否进入下一阶段等选择都沿用编号菜单。 - 自由文本只问短输入, 例如队员分工、截止时间、题目 PDF 路径。 - 用户回复数字后, agent 自动写入 `cwd/state/decision_log.json` 并继续下一步; 不要求用户手写 JSON, 不二次确认。 Codex 菜单格式: ```text 【需要你选择: <一句话标题>】 1) <选项 A> — <一句话解释> 2) <选项 B> — <一句话解释> 3) <选项 C> — <一句话解释> 4) <选项 D> — <一句话解释> 5) 让我决定 — <推荐项和原因> 回复数字 (1-5) 或直接告诉我你的选择。 ``` --- ## Codex 实战入口路由 当用户在 Codex 中用自然语言召唤本 skill, 先按意图路由, 不必强行从 Stage 0 开始。 | 用户说法 | 入口 | 首要动作 | |---|---|---| | "开始建模" / "我要打国赛/研究生赛/华数杯" | 工作台菜单 | 先给 `references/codex_practical_menu.md` 的一屏式菜单 | | "华为杯" / "研究生赛" / "研赛" | **研究生赛专项** | competition=`huaweibei`; 加载跨赛共用层与 `competitions/huaweibei/` 独立分支 + `references/huaweibei_battle_plan_72h.md` 作战表 | | "华数杯" / "我要打华数杯" / "华数杯国一" | **华数杯专项** | 加载 `references/huashubei_battle_plan_72h.md`, competition=huashubei, 国一标准 | | "比较 A/B/C 题" / "帮我选题" / "华数杯选哪题" | Stage 1 | 加载 `topic_specs.json`; **huashubei 额外加载 `references/huashubei_topic_decision.md`** | | "这道题用什么模型" / "帮我选模型" / "给选型建议" | Stage 3 选型（选择卡） | 加载 `references/stage_03_model_selection.md`，按题目域先查 playbook/案例库，再出每问候选短名单与《选型总表》，**不进入求解** | | "帮我求解" / "直接解这道题" | 检查 state 后进 Stage 5 | 先读 `cwd/state/decision_log.json`；若无 stage 3 选型记录，**必须先补走 stage 3 选择卡**，不得直接求解 | | "帮我查文献" / "有文献支持吗" / "这个方法有人做过吗" | 文献检索（stage 1/3/5 挂点） | 加载 `references/literature_scout.md`，跑 `scripts/literature_scout.py`，方法卡转写机制条目并标 review_status | | "写摘要" / "写华数杯摘要" / "写亚太杯摘要" | Stage 8 局部写作 | 加载对应竞赛 `abstract_template.md` + `phrase_bank.md` | | "写问题分析/模型段/结果解释/图表说明" | Stage 8 局部写作 | 只生成对应章节, 不改 state, 除非用户要求进入完整流程；若用户要的是**求解或选型**，不得走本入口，必须先过 stage 3 选择卡（局部入口绕开 state 等于绕开全部必停点登记） | | "画图/生成图/美化图/规划图表/终审图表" | 图表桥接 | 加载 `references/figure_skill_bridge.md`（配色规范：`references/color_typology.md` + 设计令牌宪法 `references/design_tokens.md`; 1.4.0 起总路由表在桥接文件顶部）; 论文示意图高密度交付默认走 `templates/figures/vendor/scibox-diagram/`（开源分发版无 scibox-*, 自动降级为自写 drawio/matplotlib 模板, 见桥接文件"开源分发版注意"）, 轻量快速路径用自写 drawio 模板 `render_drawio_pack.py --list`, 示意图配色默认走 `DIAGRAM_FAMILIES` 色族（与数据图表色板分离, 见 `color_typology.md` §2.4）; 复杂多面板主图/物理场图/网络流图/TikZ 框架图走 `vendor/icarus-figures/`（v2.3.0, 约束见 VENDOR.md 第 6 条）; **huashubei 额外加载 `references/huashubei_figure_pack.md`** | | "终审论文" / "最后 6 小时检查" | Stage 9 | 进入极速终审路径, 优先查摘要定量结果、图表解释、符号一致、结论对应题问 | | "继续 stage N" / "看进度" | 恢复 state | 读 `cwd/state/decision_log.json`, 加载对应 stage | 如果用户意图不清, Codex 直接给工作台菜单, 让用户回复 `1-5`。 --- ## 触发与首要动作 当用户提到数学建模竞赛、选题、建模、求解、灵敏度、论文、摘要、终审、`$mathmodel-studio`、"开始建模"、"打国赛/美赛/电工杯/亚太杯"、"APMCM"、"亚太赛"时，立即启用本 skill。 首要动作固定为: 1. 用不超过 50 字说明已启动多竞赛 5 幕 10 步问答式流程。 2. 先做实战入口路由；若是局部写作/终审/选题比较, 直接进入对应入口。 3. 若要完整流程, 检查 `<cwd>/state/decision_log.json` 是否存在。 4. 若存在，先读 `competition`、`current_stage`、`mode` 并恢复；若不存在，Codex 直接输出工作台菜单并一次性问 5 个启动问题。 5. 只加载当前阶段需要的 reference，不一次性读完整资料库。 如果用户只想问概念、改一段论文或审一张图表，不启动完整五幕流程；直接完成该小任务，并说明未写入 state。 --- ## 多 Runtime 入口 兼容 skills 标准的运行环境优先按 skill 目录发现本文件: - 用户级安装: `$HOME/.agents/skills/mathmodel-studio/` - 项目级安装: `<repo>/.agents/skills/mathmodel-studio/` - UI 元数据: `agents/openai.yaml` - 插件分发元数据: `.codex-plugin/plugin.json` + `skills/mathmodel-studio/SKILL.md` shim - 项目指导: `AGENTS.md` 仍可作为 repo / workspace 级 instructions, 但不是唯一入口 当 skill 已安装后, 用户可直接说"开始建模"或显式说"使用 `$mathmodel-studio` 开始建模"。 可选自带执行器（非默认流程）: `runtime/mathmodel_agent/` 是薄 agent runtime 原型, 用 `python -m mathmodel_agent run --workspace <dir> --mock` 可离线试跑; 必停点由代码强制——LLM 只能以正文 `checkpoint_request:` 行申请、人工经 CLI `answer` 子命令登记（`source=user_cli`）, 无法自写 checkpoints。需要 skill 身份下的物理拦截时, 路径是插件身份注册 `PreToolUse` hook 接入 check_gate, 或提交阶段用 `package_submission` 校验（见"必停点协议"）。详见 `runtime/README.md`。 开发者自检入口: 留出题评测协议 `evals/holdout_protocol.md` + `evals/run_eval.py`; 反例回归 `evals/rubric_regression/run_rubric_regression.py`。 --- ## Harness 兼容 (Claude Code / Codex) 本 skill v1.0.0 以多 runtime 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)" 兜底选项, 用户无脑选 4 也能跑通 Claude Code: 用 `AskUserQuestion` 工具; Codex: 用 markdown 编号列表 (最多 1-5, 含兜底)。两者语义等价, 见 `references/harness_compat.md` §1。 **交互密度 `interaction` (v2.3.0)**: decision_log 新增正交字段 `interaction`，取值 `"detailed"`（默认）| `"auto"`。detailed 下必停点之外的**关键自由参数**（假设取舍、图表风格细节、章节侧重）也要问；auto 仅当用户明确说"自动模式 / 少问点 / 你自己定"时开启（写入 `decision_log.interaction`），且只减少必停点之外的细节提问密度——**六个必停点永远要问**。注意与 `mode`（fast / standard / championship）的区分：`mode` 管 token 档位与反馈深度，`interaction` 管提问密度，两者正交、不得混用、不得互相覆盖。 --- ## 必停点协议 (v2.3.0) 2025 华为杯 F 题实测病根：agent 全程自写自走，设计的必停点全部未问。本节把必停点从"约定"升级为"登记 + 程序门禁"。 **六个必停点**——任何模式下都必须**真问用户**（Claude Code 用 `AskUserQuestion`；Codex 用编号菜单），**唯一登记路径是 `decision_log.checkpoints`**，登记条目形如 `{"status": "answered", "asked_at": "<ISO>", "answer": "<用户选择摘要>", "source": "chat"}`（主 agent 流程经用户问答后由 agent 写入，`source` 固定为 `"chat"`；runtime 薄执行器的 trusted 写入是 CLI `answer` 命令，`source` 为 `"user_cli"`）。**`source` 缺失或非 `chat`/`user_cli` 的值（model/llm/agent/auto 等）一律视为未答，`check_gate.py` 拦截**： | 必停点 | 触发时机 | 登记键 | 呈现方式 | |---|---|---|---| | 启动 5 问 | 完整流程启动时一次性 5 问（竞赛/题号/队员/截止/PDF） | `checkpoints.kickoff_5q` | AskUserQuestion 或 Codex 编号菜单 | | 审题呈现确认 | Stage 2 审题门四查呈现后、进入分解前 | `checkpoints.analysis_confirm` | 同上 | | 选择卡拍板 | Stage 3 选择卡人类拍板门（先亮短名单+候选档案，用户拍板） | `checkpoints.card_decision` | 同上 | | 每问图表菜单 | Stage 5 每个 Qi 验证通过后、生成图表前（见 `references/stage_05_subproblem_loop.md`） | `checkpoints.figure_menu["Q<i>"]` | 同上 | | 每问 verdict | Stage 5 每个 Qi 的 per-Qi L1 评分产出 verdict 时**即问即登记**该问条目（refine_partial 时明确问修哪问）；聚合整体决策登记进 `stages["5"]` 既有字段，不复制进 qi_verdict | `checkpoints.qi_verdict["Q<i>"]` | 同上 | | 每问选型确认 | Stage 5 每个 Qi 求解前（`A0` 步） | `checkpoints.per_qi_selection["Q<i>"]` | 同上 | 每问选型确认的口径：本问选型与 stage 3 已拍板方案一致时只做轻量确认（一行摘要 + 编号菜单），不一致或本问无 stage 3 记录时必须出完整选择卡；该键与 `card_decision` 各自独立登记，不得互相顶替。 **程序门禁**: stage 推进前必须跑 `python scripts/check_gate.py --gate <N>`（N 为当前 stage，0-8；`--gate N` 只在阶段末尾退出条件处跑，阶段中途的人工停点用 `--checkpoint <key>` 只查该必停点登记、不查 scores）。exit 0 放行；exit 1 拦截并输出缺失项中文清单——与 verdict=block 同级处理：**暂停 + 编号菜单**，缺必停点就补问，缺评分落盘就先跑 rubric L1 自评 + `score_artifact.py`。门禁同时强制 `scores` 里存在 stage N 的合法评分记录（E 合并；stage 5 双路径：`scores["5"]` stage-level 或 `scores["5_per_qi"]` 覆盖全部 Qi，满足其一即可），L1 评分一次没落盘即拦截。**没有跳过/绕过开关**；旧 state 无 `checkpoints` 字段（schema 3.0）时判 FAIL 属预期行为，补走必停点问答即可。CLI 参数语法错误为 argparse 标准 exit 2，业务放行/拦截一律只返回 0/1。 **宿主强制未启用时的口径**: 本 skill 当前以 skill 身份安装，未注册插件 hook，程序门禁由 agent 在阶段末尾主动运行 `check_gate.py` 完成——属协议要求而非物理拦截。若需要物理拦截，路径是在插件身份下注册 `PreToolUse` hook（见“多 Runtime 入口”），或在提交阶段用 `package_submission` 校验。 --- ## 路径解析协议 (任何阶段必读) | 类型 | 位置 | 例 | |------|------|-----| | 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>/` | `templates/latex/cumcm/main.tex`, `templates/latex/mcm/main.tex` | | 用户产物 | 用户 `cwd/` 相对路径 | `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>/` = 当前竞赛 (`huaweibei` | `huashubei` | `cumcm` | `mcm` | `diangong` | `apmcm`)。其中 `huaweibei` 是研究生赛，不能与 `huashubei` 华数杯互换。 --- ## Quick Start (用户首次说"开始建模") **🔴 CHECKPOINT · 启动写入前确认**: 只有在用户明确要进入完整工作流时，才创建或修改 `cwd/state/decision_log.json`。如果用户只是咨询、润色或局部审稿，不写 state。 Codex 首屏优先加载 `references/codex_practical_menu.md` 的"比赛工作台菜单"。用户回复: - `1` → 完整 5 幕 10 步流程, 继续问竞赛/题号/队员/截止/PDF。 - `2` → 只做 A/B/C 题比较, 进入 Stage 1。 - `3` → 局部任务工作台 (写作/摘要/图表/终审), 按任务进 Stage 8 或 Stage 9。 - `4` → 模型选型建议, 进入 Stage 3 选择卡, 出每问候选短名单与《选型总表》, **不进入求解**。 - `5` → 读取已有 state, 恢复当前阶段。 ``` 1. 一段话介绍 (≤50 字): "启动数学建模工作流, 5 幕 10 步 + 多竞赛, 全程问答式." 2. 一次性 5 问 (Claude Code: AskUserQuestion 单条消息; Codex: 一条消息内给首屏 5 项, 其中离散项用编号菜单): - 竞赛 (huaweibei 研究生赛 / huashubei 华数杯 / cumcm 国赛 / mcm 美赛 / diangong 电工杯 / apmcm 亚太杯中文赛；按用户上下文选择，否则默认 cumcm) - 题号 (依竞赛: huaweibei A-F，且字母不固定映射题型 / huashubei A-C / cumcm A-E / mcm A-F / diangong A-B / apmcm A-C; "未公布"亦可) - 队员数 + 各人擅长 (建模/编程/写作) - 截止时间 (ISO 字符串或 "距现在 X 小时") - 题目 PDF 路径 ("未公布"亦可) 3. 自动初始化 (agent 自动完成, 不要让用户编辑 json): - 不存在 cwd/state/decision_log.json → cp <skill>/templates/shared/decision_log.json - 写入 decision_log.competition = <选定竞赛> - 已存在 → 读 current_stage 字段决定恢复点 4. 加载 competitions/<comp>/winning_patterns.md 一次 (建立基线), 后续不再读 5. 进入 Stage 0 (references/stage_00_kickoff.md), 不重复问已问过的问题 ``` **已有 state 触发** (用户中途回到 skill): ``` 1. 读 cwd/state/decision_log.json 的 competition 与 current_stage 2. 加载对应 stage_NN.md (按需结合 competitions/<comp>/* 内容) 3. 不重复读 winning_patterns ``` --- ## 失败兜底协议 | 触发条件 | 一线处理 | 仍失败兜底 | |---|---|---| | 题目 PDF 路径不存在或打不开 | 请用户重新给路径；若题目未公布，记录为 `problem_pdf="pending"` | 用题号和已知竞赛规则进入 Stage 0，不编造题面 | | `decision_log.json` 不存在 | 从 `templates/shared/decision_log.json` 复制并写入 5 个启动答案 | 模板也找不到时，只在对话中维护临时状态，并提示 state 未落盘 | | `decision_log.json` 损坏或字段缺失 | 先备份为 `decision_log.bak.<timestamp>.json`，再用模板补齐缺字段 | 不能备份时暂停，展示损坏位置，请用户确认是否重建 | | competition 缺失或不合法 | 用主菜单选择 huaweibei / huashubei / cumcm / 其他竞赛 | 按上下文推断（华为杯/研究生赛→huaweibei，华数杯→huashubei），否则默认 cumcm，并在 state events 写明原因 | | 当前 stage reference 找不到 | 回到流程总览的五幕索引，加载相邻阶段和 `rubrics.md` 的通用规则 | 暂停该阶段，说明缺失文件，不跳过关键评审 | | 评分脚本运行失败 | 读取报错，先检查输入 JSON、Python 环境和路径 | 改用 rubric 手工评分，并在结果里标注 `manual_fallback` | | LaTeX 编译失败 | 定位首个报错，优先修模板变量、图片路径、中文编译器 | 输出可提交的 markdown/tex 草稿，说明 PDF 未生成 | | token 超预算 | 降级 mode，并只保留阶段摘要、关键数据和文件路径 | 仍超预算时暂停长文生成，先让用户确认优先完成的章节 | --- ## 六个一等竞赛 × 三模式矩阵 时长 / 语言 / 模板 / 数据状态 由 competition 决定; token 预算 / 反馈深度由 mode 决定。两者**正交组合**。 | Competition | 时长 | 语言 | LaTeX | 子问数 IQR | 数据状态 | |---|---|---|---|---|---| | **huaweibei** | 100h (2026 通知口径, 赛前以官方通知复核) | 中文 | xelatex / ctex | 按当年题面 | **empirical_local_2021_2025（30题+190篇；33篇深读: 12篇2021提名+21篇2025优秀选）** |