系列概览

三个仓库共享“审题—取数—建模—写作—校验”的阶段结构，按运行环境与交付要求分别演化。

通用版 · MathModeling

工作流架构

仓库分为技能入口、方法参考、模板和 Python 脚本四层。SKILL.md 定义 P0–P4 阶段任务，references/ 提供题型方法，assets/ 约定论文结构，scripts/ 执行重复操作。

审题阶段按逐问信号区分机理／优化与数据驱动路径，再选择主模型及对照方法。数据路径先做探索分析，机理路径核对物理约束与可解性。阶段推进由 Agent 遵循执行约定，脚本负责具体处理与检查。

项目结构与计算记录

scaffold.py 创建项目目录，复制论文模板，生成来源说明、推导稿和绘图辅助模块；目标目录已存在时返回错误。题面、输入、程序、结果和图像分别保存到 problem/、data/、code/、results/ 和 figures/。

analysis/derivations.md 记录符号、假设、方程与可解形式，data/SOURCES.md 记录来源、字段和取数口径。工作流要求模型检验与灵敏度分析，并从量纲、退化、不变量、界、良态性和反例检查模型；仿真数据单独标记。

图形布局

plot_setup.py 集中管理样式与保存流程。label_points() 将坐标转换到显示空间，测量标签包围盒，在八个方向、三个距离档生成候选。布局优先选择轴内位置，再按标签和数据点的重叠代价排序，以逐点贪心方式放置标注。

图例重叠时依次尝试九个位置；多面板图例文本一致时合并为顶部共享图例，轴内无合适位置时移到面板上方或右侧。保存阶段检查色条重叠和文字越界，四个及以上阶段的横向流程图自动改为纵向。

文档构建与失败处理

build_docx.py 按 Word 模板样式重建正文、表格、图像和代码附录。公式经 LaTeX → MathML → Office XSLT 转为原生 OMML，失败时回退为图片；独立公式用制表位组织居中公式与右侧编号。

precheck.py 检查章节、占位符、图片文件、摘要数值和灵敏度章节，题注引用、编号与正文厚度等问题产生警告。ERROR 返回非零退出码，WARN 不阻断。publish.py 依次运行预检、DOCX 构建和可选 Word COM 导出：前两步失败即停止，PDF 不可用或导出失败时跳过并保留 DOCX。

上述检查覆盖结构和生成过程；数学论证与最终版面另行审核。

查看项目仓库

Codex 版 · MathModeling-Codex

执行架构

项目从 MathModeling 的 Codex 适配目录拆出，保留技能入口、方法参考、模板和 Python 工具的分层。资源路径相对技能目录解析，环境探针检查解释器、依赖与文档导出能力，绘图支持回退到标准 Matplotlib。

执行入口区分从零求解、局部修订、提交整理和只读审核。题号作为输入信息，具体方法按逐问目标、约束和数据选择。模型及推理强度属于执行规划，实际调用单独记录。

证据结构与严格预检

analysis/ 保存问题地图、推导稿和证据矩阵，将结论关联到公式、源码、结果文件和图表。数据来源进入 data/SOURCES.md，项目根目录记录依赖、复跑步骤与 AI 使用详情。

precheck.py --strict 解析逐问章节，检查方法选择、模型建立、求解、结果、验证、稳健性和结论，并识别数值、公式及图表引用标记。证据矩阵缺失、完成记录不足或残留占位项均产生错误；正文后的 AI 声明另行检查位置和内容。

支撑包校验

build_support.py 要求复现 README、依赖清单、来源说明、证据矩阵和 AI 详情非空。code/、data/、results/、figures/ 均须包含非空材料，代码目录须有实际求解源码，仅有绘图或统计辅助模块不能通过。

收集过程检查路径归属，拒绝符号链接与 Windows 重解析点，排除隐藏项、缓存、环境和常见密钥文件。文件按相对路径入包；压缩后读取实际归档字节，计算 SHA-256，写入含排除记录的 MANIFEST.json，再检查 ZIP 完整性。

批次交付与失败路径

publish.py 先检查支撑材料、附录范围和论文，再在临时目录构建 DOCX 并尝试 Word COM 导出。PDF 存在且文件头有效才记为成功；失败时删除本次临时 PDF，在回执中保留状态。DOCX 与支撑 ZIP 为必需产物。

支撑检查 → 严格预检 → DOCX → 可选 PDF
        → 支撑 ZIP → delivery.json → 独立批次

必需步骤全部成功后，临时目录改名为带时间与随机标识的新批次。delivery.json 记录路径、大小、哈希、PDF 状态和检查方式，旧批次保留。--no-strict 仅放宽论文深度检查，不绕过支撑要求。人工终稿和自定义目录按专门整理流程处理，避免旧 Markdown 覆盖最终文件。

自动检查负责结构与归档完整性，数学验证、独立复跑和作者终审单独完成。

查看项目仓库

美赛版 · MCM / ICM Workflow

配置与项目结构

项目从 MathModeling-Codex 独立演化。contest.json 保存年份、A–F 题号、队伍控制号、AI 使用标记、引用键与规则核对日期。scaffold.py 创建分析、代码、数据、结果、图表和论文目录，复制模板并生成问题地图、推导稿与来源记录。

预检要求年份、题号和数字队号格式有效，AI 标记为布尔值，核对日期可解析且不在未来。逐问方法由目标、约束与数据决定；跨学科任务另有尺度衔接、利益相关者与可实施性的参考要求。

正文与 AI 报告

paper/paper.md 组织 Summary、模型、结果、题定 memo／letter、参考文献和附录；paper/ai-report.md 单独保存英文 AI 使用报告。本地支撑包保留工具、用途、交互及采纳核验记录。

precheck.py 检查配置和支撑材料，再核对正文标题、Summary、References 与占位符。启用 AI 时，每个引用键须同时出现在正文和参考文献中，AI 报告须有指定标题及实质内容。正文源稿混入独立 AI 报告标题时直接报错，保持解答与报告分离。

文档输入与产物

源稿路径先构建可编辑 DOCX，再由 Windows Word COM 导出 PDF。--final-pdf 直接复制已有终稿并保持字节，不重建历史 Markdown；该路径仍检查项目与支撑材料。--final-pdf 与 --draft-only 互斥。

PDF 检查与交付状态

pdf_preflight.py 用 PyMuPDF 读取实际 PDF，核对可读性、可提取文字、首页字段、队号与页眉，并检查文件大小和解答页数。AI 报告边界通过页面靠前位置的独立标题识别，避免将目录条目当成报告起点。字号、页码及作者元数据检查可产生警告，指定身份词和个人绝对路径命中产生错误。

PDF 预检失败时停止交付；未生成 PDF 时记录 draft_only，通过机器检查则记录 machine_pass_manual_review_required。必需支撑包与回执写入后，临时目录才改名为正式批次。回执明确作者审核待完成、尚未提交；复现 ZIP 保留在本地，程序不向主办方上传。

检查阈值以所核对代码版本为准；当届规则、数学结论、页面图像与披露完整性另行审核。

查看项目仓库