dsh-mathmodel-v7

Readme

# 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 安装

```bash
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/` 用作论文质检工具（按项目结构约定工作）：

```bash
# 依赖：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 用例照常跑）：

```bash
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 份
│   ├── 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](https://github.com/ubggyhjb/dsh-mathmodel-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](./LICENSE)。使用前请遵守全国大学生数学建模竞赛组委会的规则（CUMCM 对 AI 工具使用与检索来源的具体规定），本仓库提供的合规基线以 2026 年国赛口径为准，最终以最新官方文件为准。


<!-- docs_sync:stages -->
| 阶段 | 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… |
<!-- /docs_sync:stages -->