Modeling Workbench

简体中文 | English

从赛题到论文，让 AI 辅助建模有据可查。

面向数学建模比赛的 Codex / Claude Code 工作流。提供官方赛题与附件，由 agent 按阶段完成问题拆解、模型比较、计算、复核和中英文 LaTeX/PDF 交付；你在三个关键节点审阅并决定是否继续。

读题 → 比较模型 → 运行计算 → 独立复核 → 写论文 → 检查并交付 PDF

• 模型经过比较再选定：先试算候选方案，记录取舍依据，再进入正式计算。
• 论文数值有出处：计算记录关联代码、数据和结果，代码修改后能发现旧证据失效。
• 默认充分论证、图文并重：展开关键推导与结果解释，主动绘制有证据支持的图表和模型示意图，按比赛要求控制篇幅。
• 交付包含可检查的材料：中英文论文、源码与结果、复核记录，以及经过编译和逐页检查的 PDF。

工作流帮助组织和核验过程；模型是否合理、结论是否成立，仍需要结合题意与证据判断。

快速开始 · 比赛支持 · 架构与七个阶段 · 完整走查 · 开发说明

快速开始

准备好 Codex 或 Claude Code，把官方赛题、附件和当届提交要求放进同一个文件夹。 接下来复制两段提示词即可，无需先安装 Skill、填写契约或逐个运行脚本。

第一步：准备环境（首次使用）

在一个可写的本地目录中打开对话，发送：

请下载或复用 https://github.com/Lucasuiii/modeling-workbench 到独立工具目录，
先检查已有仓库，不覆盖本地改动。完整读取仓库中的
.agents/skills/cumcm-workflow/SKILL.md，按说明检查 Python 3.10+、
Python 依赖、MATLAB 或 Python 计算后端、XeLaTeX 和 PDF 渲染工具；
先运行 Skill 中的 scripts/doctor.py，说明哪些阶段可用、哪些依赖缺失。
需要安装或修改环境时，先列出变更并等我同意。
本次只准备环境，不初始化赛题；完成后报告工具目录、版本和缺失项。

如果 agent 下载仓库遇到网络问题，可以改用下面的 ZIP 补充方式完成第一步；原来的启动方式仍然可用。

先在浏览器中打开仓库主页，选择 Code → Download ZIP，完整解压后再让 agent 操作。已有完整本地副本可直接使用，无需重新下载。

将解压后的工作流放在独立工具目录，例如 数学建模/modeling-workbench-main/；官方材料另放一个目录，第二步的项目输出目录使用尚不存在的新目录。提供包含 README.md 和 .agents/ 的那一层路径，不要提供 ZIP 文件或它的上级目录。.agents 是隐藏目录，解压时也需要保留。

在环境准备对话中，用下面的提示词替代第一步原提示词：

请使用已下载并完整解压的本地 Modeling Workbench 准备环境。
工作流工具目录：/绝对路径/modeling-workbench-main

不要联网克隆仓库或检查更新，也不要尝试其他下载地址。
完整读取工具目录中的 .agents/skills/cumcm-workflow/SKILL.md，
先运行 scripts/doctor.py，报告可用阶段和缺失依赖。
若本地文件不完整，说明缺失项并停止获取仓库的尝试。
已有依赖不要重复安装；需要安装或修改环境时先列出变更并等我同意。
本次只准备环境，不初始化赛题；完成后报告实际工具目录、版本和缺失项。

随后继续原来的第二步，将工具目录替换为实际解压路径。ZIP 下载仍需要浏览器能访问 GitHub；这条路径避免 agent 反复尝试获取仓库，不代表依赖安装也能离线完成。缺少 LaTeX 等论文工具时，可以先开展基础环境支持的读题与建模，进入论文阶段前再补齐。

第二步：开始建模（每道新题）

环境就绪后，新开一个对话，替换下面三处路径并发送。工具目录用第一步返回的路径；输出目录使用尚不存在的新目录，与工具和材料目录分开。

请使用 Modeling Workbench 开始本次建模任务。
工作流工具目录：/绝对路径/modeling-workbench
官方材料目录：/绝对路径/赛题资料
新项目输出目录：/绝对路径/新项目

完整读取工具目录中的 .agents/skills/cumcm-workflow/SKILL.md。
先检查环境与官方材料，不覆盖已有内容；环境缺失则报告，不在此对话安装。
从材料识别比赛、年份、论文语言和提交要求，不明确时问我。
按 Skill 初始化并开始问题拆解，在模型选择、写论文前的结论、
最终交付三个节点等我明确确认。

接下来你只需跟随阶段提示审阅材料。 同一环境再次使用时可直接从第二步开始。中断后，提供项目输出目录并说“继续 cumcm-workflow”；已有项目应恢复，不要重新初始化。

你也可以随时说“检查环境”或“这个项目现在做到哪了”。agent 会调用环境体检或项目状态工具，报告缺失依赖、证据问题和待确认事项；工具不会自动安装软件、修改项目或替你确认。

S 为工作流工具目录下 .agents/skills/cumcm-workflow/scripts 的绝对路径：

python3 "$S/doctor.py"
python3 "$S/project_status.py" --project /绝对路径/已有项目

加 --json 可查看完整结构化结果。环境体检按阶段报告缺失项，缺 LaTeX 不妨碍先建模；状态检查截至当前阶段，并区分检查结果与行动关卡。退出码为 0 仍可能需要人工确认。详见诊断工具说明。

• macOS：路径例如 /Users/你的名字/Documents/赛题资料。
• Windows 推荐 WSL2：在 WSL2 中运行 agent 和工具，材料路径例如 /mnt/c/Users/你的名字/Documents/赛题资料；新项目可放在 /home/你的WSL用户名/modeling-projects/2026B。
• 路径须采用 agent 执行环境可见的格式。Python、计算后端和 XeLaTeX 也须在同一环境中可用。
• 原生 Windows：决策记录器已使用 Windows 文件锁；提交检查按 UTF-8 读取 JSON 和 Poppler 文本输出。原生 Windows CI 已纳入测试，但不等于完整比赛交付已验证；本文后面的 Bash 示例不能直接照抄进 PowerShell。详见平台与验证边界。
• 让 agent 检查并报告缺失依赖即可，无需预先手动配置整套工具。环境安装时间取决于现有依赖，首次 LaTeX 准备可能较久。
• 初始化会复制并固定官方材料的身份，不修改原材料目录；自主选题任务请提供官方主题与要求。

可用 Codex 的 $cumcm-workflow 或 Claude Code 的 /cumcm-workflow 触发，仍需提供材料目录和新项目目录，并确认实际 Skill 路径及环境可用。

仓库名为 modeling-workbench，Skill 调用名、目录和 .cumcm 工作区格式保持不变。当前版本 v0.6；不支持旧于 v0.6 的工作区。此次多比赛扩展保留 CUMCM/中文默认值，现有 v0.6 工作区无需迁移。

比赛支持范围

从 CUMCM 国赛流程扩展而来，其他比赛可共用建模、计算、复核和中英文论文交付链。

华为杯中文排版模板会在初始化识别到比赛名称时自动启用（可用 --template generic 改回通用模板），预设标题、正文、摘要和题注字号，支持按当届要求调整；另有交付适配指南：可装入按当届官方模板填写的封面 PDF，检查摘要页数、正文身份信息、提交文件名及附件，并记录最终 PDF 的 MD5。规则由项目提供，版式仍需逐页核对；这不代表已完成华为杯真题验收。

通用论文骨架不等于官方模板。 当届官方要求优先；DOCX 导出与任意官方模板的自动转换尚未提供。比赛名称与论文语言由 agent 在论文阶段传入，不需要你手动运行初始化命令。详见比赛适配指南。

已验证中英文骨架的实际编译、渲染和打包，以及其他比赛的合成 finalizing 流程和原有关卡。这不代表逐赛事、逐年份的官方格式认证，也不代表已完成每类比赛的完整赛题求解验收。

1. 它解决什么问题

让模型自由发挥地做数模，典型失败不是"算错"，而是这五种：

它不保证的：模型在数学上正确、全局最优、统计设计合理。检查通过只意味着"结构、来源、执行记录和已记录的评审边界是一致的"。

2. 两条规则

整个 v0.6 就是这两句话的展开。

① tooling 记录机器事实，agent 写语义判断

你永远不需要手算一个哈希。如果某个改动会让 agent 把 SHA-256、退出码、页数或结果数值敲进 JSON，那个改动是错的——去扩展记录器。

② 模型是后选的，而且选择要靠证据挣来

真实建模不是"先写对合同再执行"，而是：

Problem Analysis
      │
      ▼
Model Design ─────► 候选 A / 候选 B
      │             · 为什么值得考虑（why_considered）
      │             · 用什么证据区分（discriminating_evidence）
      ▼
Computation ──────► 低成本 exploratory evaluation
      │             record_run.py --candidate CAND-A
      │             record_run.py --candidate CAND-B
      ▼
选择 A ───────────► status: selected
      │             decision_rationale 说明凭什么选它
      │             evaluation_run_ids 指向那两次探索运行
      ▼
A 做 official computation
      │             record_run.py --official
      ▼
Validation

这条链在 v0.6 里是有结构、被检查的，不只是一段建议：

• 恰好一个候选可以是 selected（MODEL-E013）；
• 被选中的候选必须引用真的评估过它的运行（MODEL-W014）；
• 选中或淘汰都要有理由（MODEL-E014）；
• 候选说不出"用什么区分"会被标出来（MODEL-W012）；
• cumcm_check.py 在报告里打印整张对比表（model_candidates）。

working 期这些是 warning，冻结时变成 error。只有一个候选是允许的（只提示 MODEL-W007）——本工作流不逼你凑候选，它只是不让你声称一场没做过的比较。

3. 七个阶段

intake → problem-analysis → model-design → computation → validation → paper → delivery

原则上 modeling、computation、validation、paper 分别在不同的 fresh task 里做。跨职责只通过四个 handoff 传递，新 task 先读 handoff、再按指针补读，不扫描整个工作区：

modeling-computation   computation-validation   validation-paper   paper-delivery

handoff 只带路径、角色、摘要和一个 upstream digest；不带完整日志、失败运行、调试历史或旧复核对话。任一上游产物变了，handoff 立刻 stale，必须重建。

4. 证据模型

三个等级

正式计算的唯一链条

RESULTS_INDEX.json → 被引用的 run_id → official_run:true 且 exit 0
                   → 当前有效的 sha256-tree-v1 源码快照
                   → locator 指向该运行声明的 claim_bearing_output

computation→validation handoff、独立复核包、paper→delivery handoff 三个消费者共用同一个解析器。任何一环缺失、失败、非 official 或 stale，三处一起明确失败——不会一个忽略、另一个才报错。

探索运行是一等公民

record_run.py --project <p> -- python3 code/try.py

零 flag，产出一份合法的 official_run: false 记录。它被记录、不被信任、永不阻断：断言失败、非零退出、缺日志、缺 capability，全都是 warning。它也不进入阶段批准范围——新增探索运行不会让已批准的 computation 失效。

这是有意的：Deferred Model Selection 的全部收益都来自"试算便宜"。

运行是追加的，证据是冻结的

--rerun 不覆盖，它追加一个新运行（RUN-Q1-001 → RUN-Q1-002），parent_run_id 指向被取代的那个。父运行连同日志原封不动留下——"改代码之前那次正式运行算出了什么"永远答得上来。

每次运行还会把 --source 和 --output 冻结进自己的目录，镜像原来的相对路径：

runs/RUN-Q1-002/
├── RUN_MANIFEST.json
├── stdout.log  stderr.log
├── source/code/solve.py        ← 执行时那一版代码的副本
└── outputs/results/q1.json     ← 那次产出的副本，locator 指这里

冻结副本不可变，所以被保留的运行永远可验证。而"改了代码却没重跑"这条最有价值的检查并没有丢——它改成比对冻结副本与当前活文件：

ERROR RUN-E020  the working tree no longer matches this official run: code/solve.py
                remediation: record_run.py --rerun RUN-Q1-001 --official

被取代的运行豁免这条（它当然不一样，这正是你取代它的原因）；反过来，改动冻结副本本身是另一类失败 RUN-E021（证据被篡改）。

superseded 由 parent_run_id 链推导，绝不回写旧 manifest——回写会改变它的哈希，把已经绑定它的 accepted decision 全部打成 stale。结果仍指着被取代的运行时报 RESULT-E017，用 index_result.py --follow-lineage 显式重新指向：换哪次运行支撑结论是语义判断，不能让工具偷偷替你做。

problem/official/ 下的 input 就地取哈希（不可变契约已保护，且附件可能很大）；其余 formal input（data/cleaned.csv 这类会被重新生成的）同样冻结，有体积上限。

还有两条记录期的硬规则，都是防伪造：

• 不能冒领输出。claim 输出与断言文件运行前先备份移开，运行后必须重新生成非空常规文件；仅 touch 不再能继承旧内容。缺失或空文件会被拒绝，并在有备份时恢复旧文件。
• 不能继承判决。--rerun 永不继承父运行的 assertions。新代码没有被旧的 pass 验证过，继承它等于凭空给 MODEL-E009（冻结模型必须有已执行的验证）喂证据。
• 手打的判决不算已验证。--assert x=pass 记为 declared（调用者备注），--assert-file 读程序自己写出的判决、记为 recorded。只有 recorded 能满足冻结模型的 verification_plan；offici