ubggyhjb/dsh-mathmodel-v7

MathModel Agent — CUMCM 全国大学生数学建模竞赛专项 Agent

专为全国大学生数学建模竞赛（CUMCM/国赛）设计的 AI Agent（WP-01 P0-06：单赛道收缩——仅支持
中文（language=zh-CN）+ LaTeX/Typst 双引擎；不支持 Word，也不服务 MCM/ICM、APMCM、华为杯、
华数杯、华中杯、五一杯、MathorCup、统计建模赛等其他竞赛——非国赛请求在创建任何项目文件前明确拒绝）。
在 DeepSeek Harness（DSH）中作为 agent preset 使用：一条指令，从国赛赛题到一篇可直接提交的中文论文。

工作流（v6 阶段表 + V7 权威化，来源 workflow_spec.yaml，单一事实源）：
*资产接管 → 头脑风暴（Discovery+竞争搜索） → 赛题分析 → 方法学审查(模型契约) → 验证计划 → 代码与图表 →
结果→Claim 判定 → 论文规划 → 编辑计划 → 概念图 → 图表编辑 → 论文撰写 → 编译打包 → 三席终审 → 验证验收。
v5.0 变更与 DoD 核查见 docs/V50_CHANGES.md；v5.1 Competitive Search 见 docs/V51_COMPETITIVE_SEARCH.md；
v6 编辑/视觉证据链见 docs/WORKFLOW_v6.md 与 docs/MIGRATION_V5_TO_V6.md；
V7 各阶段（P0–P3）开发与验收证据链见 reports/dev/v7/；
国赛规则 authority（固定版本带 SHA）见 docs/cumcm_rules/cumcm-2026.json。

功能亮点

- CUMCM 国赛单赛道收缩（V7 WP-01 P0-06）：仅支持中文论文（language=zh-CN）与 LaTeX/Typst 双引擎；
MCM/ICM、APMCM、华为杯、华数杯、华中杯、五一杯、MathorCup、统计建模赛等其他竞赛，以及 Word/英文请求，
在创建任何项目文件前明确拒绝（UNSUPPORTED_COMPETITION / engine=word / language=en 均硬失败）——
收缩能力面，杜绝“错赛道上跑出正确答案”的隐性失败。
- V7 权威化与发现契约：资产接管升级为六态 authority（asset_registry v3：primary_official/verified_legacy/
unverified/conflicting/stale/invalidated——已有结果不是真值，冲突双方保留，stale/invalidated 禁作 claim 输入）；
Brainstorm 内置强制 Discovery 子阶段（DATA_PROFILE / DATA_CONTRACT / PROBLEM_STRUCTURE / EDA_FINDINGS /
MODEL_OPPORTUNITIES 五份 schema 化契约）；模型策略库与特征匹配（MODELING_STRATEGY_LIBRARY / PROBLEM_PROFILE /
STRATEGY_MATCHING）只生成候选策略集，不做自动选型——选择决策仍必须落决策账本。
- v6/v7 编辑与视觉证据链：editorial_plan（逐问 Narrative Arc + 视觉触发器判定）与 figure_editorial
（按冻结 FigureSpec 从 results authority 重绘全部正式图、逐图视觉断言）为强制阶段，禁止手输数值画图；
终审支持动态评审路由（REVIEW_ROUTER_DECISION）与整题 route bundle；验收强制产出
OPTIMALITY_EVIDENCE（最优性声明 L0–L4 机器校准）与全文可读性基准（FULL_PAPER_READABILITY_BENCHMARK）。
- Competitive Search（v5.1）：Brainstorm 升级为路线竞争搜索——主 Agent 仅作 Manager，
派发独立 route scout/bound scout/adversarial reviewer 覆盖问题重表达、模型族与求解器族；
结构筛选 Top-K + 公平侦察实验（同一 canonical evaluator、冻结预算/种子）+ 独立对抗评审；
最优性声明 L0–L4 机器校准，选中 route+solver 冻结贯穿 FINAL_MODEL_SPEC v3 与正式结果 _meta
（idea_gate CS01–CS17 强制；legacy v1 项目继续兼容）。
- 全流程 skills 与 15 阶段 1:1 对应：资产接管、头脑风暴（每子问题 ≥3 条候选路线）、赛题分析、
方法学审查、验证计划、编程与图表、结果判定、论文规划、编辑计划、概念图、图表编辑、论文撰写、
编译打包、三席终审、验证验收；另有 1start 启动、doctor 环境诊断、references 文献与数据来源纪律、
typst-author 排版知识、mathmodel-figure-templates 图表模板等知识/工具型 skills。
- 工作流单一事实源（v5）：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）。
- CUMCM 双模板（Typst + LaTeX）：skills/5writing/templates/zh/cumcm（Typst）与
zh/cumcm-latex（LaTeX）——同一国赛模板的两个引擎实现；不保留通用 default fallback，
不提供其他竞赛模板（WP-01 P0-06）。单个比赛项目只物化一个入口：
python skills/5writing/scripts/materialize_template.py --workspace .（TPL-R01/R03：
读取 project.manifest.json 的 engine/entry，engine 缺失/非法/入口冲突/非空 paper 均硬失败，
写 reports/writing/TEMPLATE_SELECTION.json 选择证据；Typst 同时按本机 typst fonts
重写 paper/font_config.typ（TPL-T01）——避免 unknown font family 且跨机器可复现）。
- 验收引擎（6verity）：run_all_gates.py --strict 一键运行，全部 PASS 才可提交；
门禁执行列表唯一事实源 = workflow_spec.yaml 的 gates: registry（v4.4：run_all_gates 只解析该表，
README 不再手写清单；gate 计数/报告路径/required/strict_aware 均由 registry 派生——当前门数与
roster 以 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 / natural_prose / judge_readability / chinese_lint
（外加聚合器 workflow_order 校验；v5 起新增门见 gate registry 与 docs/V50_CHANGES.md）。
v4.4 关键新增：T110-T125 反 false-pass 回归（含 G1-G6 坏版本 golden）；每门报告注入
input_snapshot_sha256（同轮一致性校验，P2-02）；schema_validation（JSON Schema，P1-19）。
v4.5.2 新增：natural_prose（NP-01~22 中文自然文风频率+上下文判定）、judge_readability（JR-01~06
30 秒可读性）、chinese_lint（CL-01~11 中文标点/符号/全角半角规范，吸收 textlint-zh）——三者只读，
禁止“出现即 FAIL”禁词化（G-WRITE-6 正常文本必须零命中）。
- 验证器只读（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 注册
├── agent.dependencies.json / preset.build.json   # 依赖声明 / 确定性构建清单（payload=git tree，剔除 dev 台账）
├── workflow_spec.yaml    # 工作流单一事实源（阶段/门禁/终审定义；v6 阶段表 + V7 契约字段）
├── README.md / LICENSE
├── docs/                 # 版本变更史（V42~V51）、WORKFLOW_v3/4/5/6、v5→v6 迁移指南、
│   │                     # JSON Schemas、国赛规则 authority（cumcm_rules/）、写作与图表规范、
│   │                     # 内部改进计划归档（plans/）
├── skills/               # 阶段 skills（与 workflow_spec 15 阶段 1:1）+ 知识/工具型 skills
│   ├── 1start-mathmodel/           # 启动：plan.md/todo.md 初始化（阶段表读 workflow_spec）
│   ├── 0intake-assets/             # 资产接管（asset_registry v3 六态 authority）
│   ├── brainstorm-mathmodel/       # Discovery + 竞争搜索（兼容别名 brainstorming）
│   ├── 2analysis-modeling/         # 赛题分析与建模设计
│   ├── 7methodology-review/        # 方法学审查 + FINAL_MODEL_SPEC 可执行模型契约
│   ├── 8validation-plan/           # 运行前冻结验证证据契约（claim→metric→success/failure rule）
│   ├── 3coding-visual/             # 编程实现与图表（只实现契约；sharded_run v2 长任务）
│   ├── 9result-review/             # 结果→Claim 判定（SUPPORTED/REFUTED/INCONCLUSIVE + 自动路由）
│   ├── 10paper-plan/               # Claims-Evidence Matrix 论文规划
│   ├── 13editorial-plan/           # 编辑计划：逐问 Narrative Arc + 视觉触发器判定（v6）
│   ├── 4drawio/                    # 概念图/流程图（≤1 张，不再默认 roadmap）
│   ├── 14figure-editorial/         # 图表编辑：按冻结 FigureSpec 重绘 + 逐图视觉断言（v6）
│   ├── 5writing/                   # 论文撰写（Judge-First 写作总线）+ templates/ CUMCM 双模板
│   ├── 11compile-package/          # 编译 + 错误分类修复
│   ├── 12final-review/             # 三席盲评终审（roster/persona/veto 见 workflow_spec）
│   ├── 6verity/                    # 验收引擎（gates registry SSOT）+ style_policy.json + tests/
│   ├── mathmodel-figure-templates/ # 学术图表模板（mpl_paper_style、FigureBuilder 等）
│   ├── doctor/                     # 环境检查与安装向导
│   ├── references/                 # 文献/数据来源模板、版面实证校准
│   └── typst-author/               # Typst 排版知识
├── benchmarks/           # 门禁 golden 回归集：G1-G6 坏版本反 false-pass、对抗 G-BR、竞争搜索 G-CS、
│                         # 模板/写作/视觉编辑基准、sentinel 冻结基线
├── reports/dev/v7/       # V7 各阶段（P0–P3）开发与验收证据链（preset payload 不含，留作 provenance）
└── tools/                # 确定性 preset 构建（preset_build.py）、漂移检查、sentinel 端到端驱动

使用

作为 DSH preset 安装

git clone https://github.com/ubggyhjb/dsh-mathmodel-v7 ~/.dsh/agent-presets/mathmodel

将本仓库放入 DSH 的 agent-presets 目录（如 ~/.dsh/agent-presets/mathmodel），
会话中选择 mathmodel 预设即可：preset.yml 注册名称与描述，agent.cordis.yml 挂载 persona、
工具映射与全部 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 对齐）：

/
├── 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 份
│   ├── figures/figure_manifest.json  # 正式图唯一清单（figure_editorial 经 figure_finalize 合并）
│   ├── variables.json                 # v4 单位注册（unit registry）
│   └── gates/                         # 门禁报告
├── code/  results/  figures/          # 结果 JSON 带 model_spec_sha256；正式图带 .meta.json
└── paper/                  # main.tex | main.typ + sections/（generated_values.tex 可选：数值来源二选一）

版本历史

- v7.0.0（本仓库）：CUMCM 国赛单赛道收缩（中文 + LaTeX/Typst，非国赛请求创建文件前拒绝）；
V7 权威化——asset_registry v3 六态 authority、Discovery 五契约、动态评审路由、整题 route bundle、
OPTIMALITY_EVIDENCE、全文可读性基准；v6 编辑/视觉证据链成为强制阶段。
各阶段（P0–P3）验收报告见 reports/dev/v7/；发布记录见 Releases。
- v5.x：工作流单一事实源 v5 + Competitive Search（docs/V50_CHANGES.md、docs/V51_COMPETITIVE_SEARCH.md）。
- v4.x：反 false-pass 收口、release graph、CUMCM 模板 v2、三席盲评与答辩门（docs/V4_CHANGES.md 系列）。
- v3.x：方法学审稿升级起点（docs/WORKFLOW_v3.md）。

开发状态与已知问题（V7 开发线）

本仓库是 V7 的源码权威仓库（source authority）：除 preset payload 外，完整保留
reports/dev/v7/ 开发台账与证据链——包括如实记录、尚未收口的开发项。

- 全量回归 python skills/6verity/tests/run_tests.py：629/632 通过。3 个失败
（VE06-A / VE07-B / VE07-C，编辑-视觉证据链）对应 reports/dev/v7/V7_RUN_STATE.json
记录的 V7-P3-01 中断状态（STOPPED_AT_DEADLINE）与两项已登记的工具链矛盾
TD-FIGED-001 / TD-FIGED-002（见
reports/dev/v7/P3-01/P3-01-B2-FIGURE-EDITORIAL-GATE-SCOPE/P3_01_FIGURE_EDITORIAL_BLOCKER.md：
①concept manifest 合并语义与 figure_editorial 阶段门互斥；②P4-00 primary-only 语义扩展与
P4-03 全量机器完备性强制互斥）。V7-P2-02 downstream result review 的修复实现同样标记
NEEDS_REPAIR，属进行中的工作。
- 按本 preset 自身纪律（验证器只读、禁止改门禁换取放行），上述失败被保留为事实而非掩饰性修复；
修复方向已在 blocker 报告中给出（merge 将 concept 条目并入 approved 集合 / semantic_fields
按 figure_role 分级强制）。

许可证

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

| 阶段 | skill | 门禁 | 主要产出 | 目的 |
|---|---|---|---|---|
| intake | 0intake-assets | asset_registry | reports/intake/ASSET_REGISTRY.json, reports/intake/ASSET_CONFLICTS.json, reports/intake/INTAKE_REPORT.md, {'path': 'reports/data/DATASET_SNAPSHOT.json', 'required': False, 'producer': 'intake'} | 资产接管：清点已有题目/数据/代码/结果/图/模板，交叉一致性检查（代码vs数据/结果vs图/结果vs旧论文/模板vs官方规则/旧结果vs新canonical … |
| brainstorm | brainstorm-mathmodel | idea_contracts | {'path': 'reports/data/DATA_PROFILE.json', 'required': False, 'required_when': 'v7_discovery_policy_enabled', 'producer': 'brainstorm', 'schema': 'data_profile.v1'}, {'path': 'reports/data/DATA_CONTRACT.json', 'required': False, 'required_when': 'v7_discovery_policy_enabled', 'producer': 'brainstorm', 'schema': 'data_contract.v1'}, {'path': 'reports/discovery/PROBLEM_STRUCTURE.json', 'required': False, 'required_when': 'v7_discovery_policy_enabled', 'producer': 'brainstorm', 'schema': 'problem_structure.v1'}, {'path': 'reports/discovery/EDA_FINDINGS.json', 'required': False, 'required_when': 'v7_discovery_policy_enabled', 'producer': 'brainstorm', 'schema': 'eda_findings.v1'} | Competitive Search 联合路线搜索：独立 route 发现（问题重表达/模型族/求解器族覆盖）→ 结构筛选 Top-K → 公平侦察实验 → 对… |
| analysis | 2analysis-modeling | — | reports/ANALYSIS_MODELING_REPORT.md | 解析题意、识别变量/约束/数据/评价指标；众数解清单 + 差异化审查 |
| methodology_review | 7methodology-review | methodology | reports/methodology/.json, reports/FINAL_MODEL_SPEC.json, reports/FIGURE_REQUIREMENTS.json, {'path': 'reports/review/REVIEW_ROUTER_DECISION.json', 'required': False, 'required_when': 'v7_dynamic_reviewer_router_enabled', 'producer': 'methodology_review', 'schema': 'review_router_decision.v1', 'introduced_in': 6} | DGP/假设/删失/退化/必要性/泄露/样本量审计；产出可执行模型契约 FINAL_MODEL_SPEC.json 与 Figure Requirements（… |
| validation_plan | 8validation-plan | — | reports/VALIDATION_PLAN.json, reports/VALIDATION_PLAN.md | 运行前冻结验证证据契约：每条 claim 声明 type/metric/success_rule/failure_rule/priority（feasibili… |
| coding_visual | 3coding-visual | leakage | code/.py, results/.json, figures/drafts/.pdf, figures/drafts/.meta.json | 只实现 FINAL_MODEL_SPEC.json 声明的模型；按 VALIDATION_PLAN 运行并记录证据；长任务使用同一 sharded_run v2… |
| result_review | 9result-review | result_review | reports/RESULT_INTERPRETATION.json, reports/RESULT_REVIEW.md, {'path': 'reports/contracts/WHOLE_PROBLEM_ROUTE_BUNDLE.json', 'required': False, 'required_when': 'v7_whole_problem_route_bundle_enabled', 'producer': 'result_review', 'schema': 'whole_problem_route_bundle.v1', 'introduced_in': 6} | Result Review v2：只解释 validation evaluator 的 PASS/FAIL/UNKNOWN/ERROR；evaluator 必须… |
| paper_plan | 10paper-plan | — | reports/PAPER_PLAN.json, reports/PAPER_PLAN.md, {'path': 'repro/CLAIM_PROVENANCE.json', 'required': False, 'producer': 'paper_plan'}, {'path': 'reports/gates/result_paper_narrative_gate.json', 'required': False, 'required_when': 'v7_result_paper_narrative_check_enabled', 'producer': 'paper_plan', 'schema': 'result_paper_narrative_gate.v1', 'introduced_in': 6} | Claims-Evidence Matrix（claim→result→validation→figure/table→section）；无 evidence … |
| editorial_plan | 13editorial-plan | editorial_plan | reports/PAPER_NARRATIVE.json, reports/PAGE_PLAN.json, reports/FIGURE_PLAN.json, reports/VISUAL_REFERENCE_BOARD.json | 科学表达编辑计划：逐问 Narrative Arc（第一眼结论/beats/kill list）+ 视觉触发器判定（primary figure 或结构化 no… |
| schematic | 4drawio | — | figures/.tex|.mmd|.drawio, {'path': 'figures/concept_figure_manifest.json', 'required': False, 'producer': 'schematic', 'note': 'skipped 时由 stage_close 写结构化 skipped closure，不伪造'}, reports/DRAWIO_REPORT.md | 仅当存在无法用正文/数据图表达的结构关系才画概念图（concept figure ≤1）；输出 concept manifest/source/PDF/DRAW… |
| figure_editorial | 14figure-editorial | figure_editorial | figures/.pdf, figures/.png, figures/.meta.json, figures/data_figure_manifest.json | 按冻结的 FigureSpec 从 results authority 生成/重绘全部论文正式图（禁止手输数值）；执行逐图视觉断言（关键对象可见/标签不遮挡/有… |
| writing | 5writing | figure_story | paper/main.tex|main.typ, paper/sections/, {'path': 'reports/writing/STYLE_REWRITE_REPORT.json', 'required': True, 'producer': 'writing', 'schema': 'style_rewrite_report.v1', 'introduced_in': 6}, {'path': 'reports/writing/PAGE_EDIT_DECISIONS.json', 'required': False, 'required_when': 'page_editor_applicable', 'producer': 'writing', 'schema': 'page_edit_decisions.v1', 'introduced_in': 6} | 数值来源二选一（numeric_source_policy.mode=one_of）：generated_values.tex（recommended）或 re… |
| compile_package | 11compile-package | — | paper/main.pdf, reports/compile/COMPILE_REPORT.json, reports/compile/REPAIR_LOG.json | 编译 + 错误分类修复（数学环境/LR mode/undefined control sequence/BibTeX 四类，grep parse log 逐条手… |
| final_review | 12final-review | final_review | {'path': 'reports/review/blind_scores.json', 'required': True, 'producer': 'final_review', 'schema': 'blind_scores.v2'}, {'path': 'reports/review/page_visual_review.json', 'required': True, 'producer': 'final_review'}, {'path': 'reports/review/raw//.json', 'required': True, 'min_matches': 3, 'producer': 'final_review'}, {'path': 'reports/review/REVIEW_CLOSURE.json', 'required': True, 'producer': 'final_review'} | 三席独立终审（seatA_modeling/seatB_statml/seatC_visual，roster=final_review.personas）：只 … |
| verification | 6verity | run_all_gates | reports/gates/.json, reports/VERIFY_REPORT.md, {'path': 'reports/OPTIMALITY_EVIDENCE.json', 'required': True, 'required_when': 'v7_optimality_evidence_enabled', 'producer': 'verification', 'schema': 'optimality_evidence.v1', 'introduced_in': 6}, {'path': 'reports/verification/FULL_PAPER_READABILITY_BENCHMARK.json', 'required': True, 'required_when': 'v7_full_paper_readability_benchmark_enabled', 'producer': 'verification', 'schema': 'full_paper_readability_benchmark.v1', 'introduced_in': 6} | 验证器完全只读（V7-P0-04）：输入=论文/结果/图/清单/契约/方法学 JSON（含 RESULT_INTERPRETATION）与 final_revi… |