MathModel Agent — 数学建模竞赛 Agent

专为数学建模竞赛（CUMCM 国赛、MCM/ICM 美赛、APMCM、华为杯、华数杯等）设计的 AI Agent。 在 DeepSeek Harness（DSH）中作为 agent preset 使用：一条指令，从赛题到一篇可直接提交的论文。

工作流（v4，来源 workflow_spec.yaml，单一事实源）： 头脑风暴 → 赛题分析 → 方法学审查(模型契约) → 代码与图表 → 概念图 → 论文撰写 → 验证验收。

功能亮点

• 12 个 skills 完整流水线：头脑风暴（每子问题 ≥3 条候选路线）、赛题分析、方法学审查、 编程与图表、概念图、论文撰写、验证验收、环境诊断、参考文献与数据来源纪律。
• 工作流单一事实源（v4）：workflow_spec.yaml 定义全部阶段顺序/输入输出， workflow_spec.py --check 校验 1start/persona/README/docs/decision_log 与它一致； 禁止在文档中手写第二份阶段顺序。
• 可执行模型契约（v4）：reports/FINAL_MODEL_SPEC.json——7methodology-review 产出， 3coding 只实现它、结果 JSON 写 model_spec_sha256、methodology 门逐问题核验 （同一 outcome 跨问题观察机制不一致自动 FAIL）。
• 17 套中英文论文模板（每套含 Typst 与 LaTeX 两个版本）：CUMCM 国赛、MCM/ICM 美赛、 APMCM、华为杯、华数杯、电工杯、东三省、华东杯、华中杯、数维杯、五一赛、MathorCup、 长三角赛、统计建模赛等，另有通用 default 模板。
• 验收引擎（6verity，v4.4 起 16 门）：run_all_gates.py --strict 一键运行，全部 PASS 才可提交； 门禁执行列表唯一事实源 = workflow_spec.yaml 的 gates: registry（v4.4：run_all_gates 只解析该表， README 不再手写清单；gate 计数/报告路径/required/strict_aware 均由 registry 派生）： manifest / layout / text_integrity / trace / style / decision / refs / methodology / leakage / figure_story / idea_contracts / visual_review_gate / figure_spec / deployment_utility / submission_package / schema_validation（外加聚合器 workflow_order 校验）。 v4.4 关键新增：T110-T125 反 false-pass 回归（含 G1-G6 坏版本 golden）；每门报告注入 input_snapshot_sha256（同轮一致性校验，P2-02）；schema_validation（JSON Schema，P1-19）。
• 验证器只读（v4）：run_all_gates 绝不修改被验对象（不刷 decision_log 时间戳）； writer updates, verifier verifies。
• 排版规范基于实证：从官方展示论文全库统计的摘要加粗优先级、图内字号、配色等阈值 （单一事实源 skills/6verity/style_policy.json；官方硬规则与推荐经验分层）。
• 三席盲评陪审团 + 致命否决（v4）：3 个上下文隔离的评审子代理按固定打分表独立评分， ≥70 放行；Reviewer B 的 leakage/wrong likelihood/invalid censoring/invalid test protocol 任一 Critical、Reviewer C 的 figure blank/table clipped/unresolved reference 任一 Submission blocker → 总分再高也 FAIL。
• 答辩门（v4）：attack_questions 每条带 severity/status/answer/evidence； P0/P1 open > 0 → FAIL（真正"答辩通过才 final PASS"）。
• 竞赛合规内置：AI 声明定句、2026 提交格式（无目录、摘要页页码、正文 ≤30 页）、 组队与纪律规则、检索边界（禁止浏览交流平台讨论赛题）。

目录结构

mathmodel/
├── preset.yml            # 预设元数据（name/description）
├── agent.cordis.yml      # DSH preset 组合：persona、工具、skills 注册
├── workflow_spec.yaml    # v4 工作流单一事实源（阶段/门禁/终审定义）
├── README.md
├── LICENSE
└── skills/
    ├── 1start-mathmodel/         # 启动：plan.md/todo.md 初始化（阶段表读 workflow_spec）
    ├── brainstorm-mathmodel/     # 头脑风暴（兼容别名 brainstorming）
    ├── 2analysis-modeling/       # 赛题分析与建模设计
    ├── 7methodology-review/      # 方法学审查 + FINAL_MODEL_SPEC 契约（v4）
    ├── 3coding-visual/           # 编程实现与图表（只实现契约）
    ├── 4drawio/                  # 概念图/流程图（≤1 张，不再默认 roadmap）
    ├── 5writing/                 # 论文撰写 + templates/ 17 套中英文模板
    ├── 6verity/                  # 验收引擎（v4.4：16 门，gates registry SSOT）+ style_policy.json + tests/
    ├── mathmodel-figure-templates/ # 学术图表模板（mpl_paper_style、FigureBuilder 等）
    ├── doctor/                   # 环境检查与安装向导
    ├── references/               # 文献/数据来源模板、版面实证校准
    └── typst-author/             # Typst 排版知识

使用

作为 DSH preset 安装

将本仓库放入 DSH 的 agent-presets 目录（如 ~/.dsh/agent-presets/mathmodel）， 会话中选择 mathmodel 预设即可：preset.yml 注册名称与描述，agent.cordis.yml 挂载 persona、 工具映射与 12 个 skills，skills 内的技能会出现在会话目录中。

独立使用验收引擎

不依赖 DSH 也可以直接把 skills/6verity/scripts/ 用作论文质检工具（按项目结构约定工作）：

# 依赖：python 3.10+，pip install pymupdf   # 其余用标准库
python skills/6verity/scripts/run_all_gates.py --workspace <项目目录> --strict
python skills/6verity/scripts/project_manifest.py --workspace <项目目录> --check
python skills/6verity/scripts/workflow_spec.py --check --root <仓库根>  # 单一事实源一致性

回归测试（含 fixture 与负向 regression 用例；未提供真实项目时基线用例自动 SKIP， fixture 用例照常跑）：

python skills/6verity/tests/run_tests.py                        # 无真实项目：fixture 用例
python skills/6verity/tests/run_tests.py --workspace <项目目录>  # 全量（含基线）

项目目录约定

一个可用 run_all_gates.py 验收的项目工作区布局（与 workflow_spec.yaml 的 inputs/outputs 对齐）：

<workspace>/
├── project.manifest.json    # 引擎/入口/HIL_POLICY/工件哈希（singular source of truth）
├── plan.md / todo.md        # 阶段表来源 workflow_spec.yaml
├── state/decision_log.json  # 阶段状态机 + 关键决策（v4 阶段集合）
├── references/              # literature.md / data_sources.md
├── reports/
│   ├── FINAL_MODEL_SPEC.json          # v4 模型契约（3coding/5writing 只消费它）
│   ├── methodology/*.json             # 7methodology-review 审计 7 份
│   ├── figure_story_manifest.json     # Figure Story 唯一清单
│   ├── variables.json                 # v4 单位注册（unit registry）
│   └── gates/                         # 门禁报告
├── code/  results/  figures/          # 结果 JSON 带 model_spec_sha256；正式图带 .meta.json
└── paper/                  # main.tex | main.typ + sections/（generated_values.tex 可选：数值来源二选一）

许可证

MIT。使用前请遵守各竞赛组委会的规则（如 CUMCM 对 AI 工具使用与检索来源的具体规定），本仓库提供的合规基线以 2026 年国赛口径为准，最终以最新官方文件为准。

阶段	skill	门禁	主要产出	目的
brainstorm	brainstorm-mathmodel	idea_contracts	reports/contracts/QUESTION_CONTRACT.json, reports/contracts/IDEA_CANDIDATES.json, reports/contracts/IDEA_DECISION.json, reports/BRAINSTORM_REPORT.md	题意契约 + 受约束候选生成（minimal/recommended/advanced 三档）+ 淘汰状态机；禁止实验结论词；不直接形成可执行模型定义
analysis	2analysis-modeling	—	reports/ANALYSIS_MODELING_REPORT.md	解析题意、识别变量/约束/数据/评价指标；众数解清单 + 差异化审查
methodology_review	7methodology-review	methodology	reports/methodology/*.json, reports/FINAL_MODEL_SPEC.json, figures/figure_manifest.json	DGP/假设/删失/退化/必要性/泄露/样本量审计；产出可执行模型契约 FINAL_MODEL_SPEC.json 与唯一 Figure Manifest（dr…
coding_visual	3coding-visual	leakage	code/.py, results/.json, figures/.pdf, figures/.meta.json	只实现 FINAL_MODEL_SPEC.json 声明的模型；结果 JSON 写 model_spec_sha256；图写 meta.json
schematic	4drawio	—	figures/*.tex	*.mmd
writing	5writing	figure_story	paper/main.tex	main.typ, paper/sections/*
verification	6verity	run_all_gates	reports/gates/*.json, reports/VERIFY_REPORT.md	v4.1（R-02）：验证器输入=论文/结果/图/清单/契约/方法学 JSON——不得把自产的 gates_report 当输入（无自输入循环）；输出门禁报告与…