Comp Modeling

---

name: comp-modeling

description: "数学建模竞赛核心建模与求解。建立数学模型、推导公式、设计算法。Use when user says \"建模\", \"modeling\", \"模型建立\"."

argument-hint: [problem-analysis-or-topic]

allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, WebSearch, WebFetch, Agent

---

# 竞赛建模求解

基于赛题分析进行数学建模与求解：**$ARGUMENTS**

## 补充说明：原有建模流程与案例继续使用

保留本 Skill 的章节和案例；结合题意选择对应经验，不能把历史案例阈值当成本题要求。
"模型升级"先核是否为本问题目所需，不自动倒灌后问条件或虚构缺参数。
"唯一方法/预案"保持数学合同与可复现性，不锁死实现级修复；经验预期不同先核证据。
内点解、闲置资源、相同目标值都可能正确；跨问单调性须有目标可比和可行域包含依据。
同名物理量在相同对象/场景/时间窗下核对，理论服务能力与实际配额不天然相等。
漂移或发散先核物理定义/收支/数值条件，不自动加阻尼、反馈、饱和或截断。
首次必要验证保留；复用当前证据，共用原返修预算，不新设全量重复实验。
机理、场仿真、反问题及可靠性题按需补读 `_utils/mechanism_accuracy_addendum.md`。
把选中的风险并入原有逐问检验方案：写清适用的题意、可证伪判据和下游证据位置，
由 comp-code 在同一轮验收中落实；本阶段不为这些条目提前运行完整数值求解。
不要求凑固定检查数量、另建报告或照搬往届参数，不以有一份规则文件冒充已验证。

历年原题补充按该文件路由选读 16.10—16.15：目标优先次序/信息边界、本构系数、
离散可执行性、近似模型、实验可识别性、时间窗和长期条件。以下适用边界优先于
后文升级示例：关键词不唯一指定模型；当前问的明确简化优先于后问/文献机制；
缺参数不凭空补值，改目标/约束仍需确认。把适用条目的原题依据、判据与容差依据
并入已有逐问检验方案；只设计验证，不为这份补充提前求解，也不把经验预期升级为硬阈值。

## 数学表达交接

先读取 `_utils/modeling_paper_contract.md` 的逐问数学骨架要求。`MODELING_REPORT.md` 按题号交付实际模型：变量与单位、核心关系、成立条件、求解方法与后续结果口径。核心关系用独立数学块，不能全部隐藏在行内文字、能力清单或函数名中。
概率仿真需说明随机事件、采样和估计/区间定义；最低用量/容量的可靠性反问题需明确目标、可行条件和停止准则。仅采用本题实际需要的模型，不硬凑公式数量。内部覆盖清单可以另存，但不能代替数学推导。

## ⚡ 快速模式检测（开头先跑）

```bash

FAST_MODE=0

grep -q 'MH_FAST_MODE=1' AGENTS.md 2>/dev/null && FAST_MODE=1

echo "FAST_MODE=$FAST_MODE"

```

**若 `FAST_MODE=1`（速度优先）：** 仍必须产出完整的 MODELING_REPORT.md（每个子问题都有数学模型/公式/求解思路、子问题全覆盖、结果预期范围表），但**跳过**：多方案对比择优的反复推敲、灵敏度深挖、发现小瑕疵后的反复重写打磨。一次成型、内容齐全即可。**若 `FAST_MODE=0`（默认）：** 后文审查环节照常。

## 常量

- **COMPETITION** / **PROBLEM_ID** — 从 Additional Parameters 读取

- **TOOLS** — 默认 `python`

- **CUSTOM_REQUIREMENTS** — 用户自定义要求

## 输入

1. **PROBLEM_ANALYSIS.md** — 赛题分析报告（必须存在）

2. **user_data/** — 赛题附件数据

## ⛔⛔⛔ 完成铁律（最高优先级，违反则本步骤失败）

**本步骤必须产出 `MODELING_REPORT.md`（≥ 1.5KB，完整的建模与求解报告）**。

⛔ **MANDATORY: 用 `Write` 工具直接写出 `MODELING_REPORT.md`。不要只调 Read/Bash 工具就 end_turn — 这是本步骤失败的 #1 原因。产出必须是真实落盘的文件。**

⛔ **读用户上传的文献/数据时**：

- 不要 `cat` 整个 `_extracted.md/.txt` 文件 — 一个大文件就能把 context budget 吃光，没空间产出主文件。

- 用 `Read` 工具带 offset/limit 范围读，或用 `Grep` 工具按关键词提取。

- AGENTS.md 已列出所有上传文件清单 + 字数，**优先用清单 + Read 局部，不要全量 cat**。


产出结构、存在性和最低完整性由 `finish` 按模板中的 `output_contract` 自动核验；修复返回的具体问题，不复制执行验证脚本。

⛔⛔ **建模覆盖核对（承接赛题分析的合同，结束前必跑，零额度两模式都跑）**：赛题分析阶段产出的 `CAPABILITY_CHECKLIST.json` 是贯穿全链的合同。建模报告**必须为每条能力项给出对应建模方案**，并在该处标注其能力 id（如『针对能力 P1-C1 事件五元组抽取，采用序列标注 BERT-CRF……』）：

```bash

python _utils/modeling_coverage_check.py --checklist CAPABILITY_CHECKLIST.json --modeling MODELING_REPORT.md

MC=$?   # 0=每条能力项都有建模着落 1=有能力项被整条无视(必修) 2=无清单跳过

```

> `MC=1`（某能力项在建模报告里找不到）说明**建模阶段就把题目要求的能力悄悄简化/跳过了**——这正是"任务降维"最上游的发作点，必须回去为每条能力项补建模方案再结束本步骤，别让它一路歪到编码和论文。⛔ 承上启下：赛题分析定合同 → 本步认领每条能力 → comp-code 按能力清单实现并最终验收。

### Step 1: 读取分析报告 + 方法对照 + 防错审查

提取子问题列表、推荐方法、变量定义、数据特征。

**⛔ 对照 PROBLEM_ANALYSIS.md 的推荐方法：** 如果选择了不同于推荐的方法，必须在 MODELING_REPORT.md 中明确说明理由（为什么推荐方法不适用、替代方法的优势）。不能无声地忽略推荐方法。

**主动推荐·多视角建模**：方法选型阶段调 `comp-model-innovation`（arxiv+DuckDuckGo 前沿方法检索 + **历年国一撞方法查重**——多视角建模思路与创新性防线，避免"烂大街方法"直接上手）；实现路线拿不准时用 `comp-modeling`（按子问题选模型→写代码→验证合理性）做快速对照原型。检索与查重结论按留痕纪律写入 MODELING_REPORT.md。

**⛔⛔⛔ 强制审视赛题分析的"经典问题升级"结论（防止升级被忽略）：**

**核心要求：先完整审视赛题分析的升级建议 → 尽量在建模中满足 → 如有异议必须给出充分理由。**
'

**⛔ 赛题题型差异化策略（题目 A/E 颋型侧重数值优化，C 颋型偏分类预测）:

基于 2021-2025 年国赛 62 篇优秀论文样本分析，不同题型具有明显的写作与建模特征：

| 题型 | 样本量 | 平均字数 | 关键特征 | 推荐模型方向 |
|------|--------|----------|----------|-------------|
| **A** | 15 | 1190 | 字数最多、结果最密集 | 复杂优化模型、详细数值结果、参数敏感度分析 |
| **B** | 15 | 904 | 字数适中 | 中等复杂度模型、综合分析 |
| **C** | 14 | 984 | 结果数最少（均值 0.9 个） | 分类/预测模型、特征重要性分析、结果解释性 |
| **E** | 11 | 1206 | 字数最长、多问题综合 | 综合模型、多问题协同优化、全局视角 |

**决策要点**：
- 审视 PROBLEM_ANALYSIS.md 中的题型标识，判断所属题型
- 根据题型选择对应的模型复杂度和结果呈现方式
- A/E 颋型建模时应确保有足够的数值结果支撑（≥3 个关键数值）
- C 颋型不宜追求结果密度，而应侧重模型可解释性和特征分析
- 题型判断应在建模报告中明确标注，并在方法选择、结果分析中贯穿

此策略有助于避免套用单一模型范式，因不同题型有不同的评审期望与技术路线。

赛题分析阶段（Step 5.6）会输出以下表格，建模阶段**必须逐条审视**：

- **覆盖度检查表**（标注 ⚠️/❌ 的句子是需要额外建模的机制）

- **反向对照检查**（题目某句子指出需要升级到某变体）

- **经典问题升级确认表**（明确标注"初步映射 X → 最终模型 Y"）

**⛔ 执行步骤：**

```bash

echo "=== 审视赛题分析的升级结论 ==="

echo ""

echo "--- 标为⚠️/❌的覆盖度缺口（需要在建模中审视是否补上）---"

grep -A 1 '⚠️\|❌' PROBLEM_ANALYSIS.md | head -40

echo ""

echo "--- 经典问题升级表（需要审视是否采用最终模型）---"

sed -n '/经典问题升级/,/^##/p' PROBLEM_ANALYSIS.md | head -30

echo ""

echo "--- 反向对照的升级要求 ---"

sed -n '/反向对照/,/^##/p' PROBLEM_ANALYSIS.md | head -30

```

**⛔ 三段式决策流程（每个升级建议都必须走完）：**

**第一段：审视**

- 逐条读取赛题分析的升级建议（如 "Orienteering → Multi-Trip OP"）

- 理解升级的触发原因（如 S7"可充电"→多架次飞行）

- 判断升级对最终结果的影响（如不用 Multi-Trip 会导致覆盖数被严重低估）

**第二段：尽量满足（默认行为）**

- 如果升级在技术上可实现 → 必须采用赛题分析推荐的变体

- 如果升级增加复杂度但不超出求解能力 → 必须采用

- 如果升级是题目明确要求的机制（如"可充电"）→ 无论如何必须采用

**第三段：有异议给理由（特殊情况）**

如果建模阶段认为某个升级不应采用，必须在 MODELING_REPORT.md 中给出充分理由：

- **物理/业务不可行**：如"题目说可充电但物理上无法实现（如太阳能电池）"

- **数据不支持**：如"题目没给充电时间参数" → ⛔ 这不是跳过升级的合法理由！必须做合理假设（如假设充电瞬时/固定X分钟/等于飞行时间的X%），然后继续建模升级版

- **超出求解能力**：如"完整 Multi-Trip Stochastic OP 是 PSPACE-hard，简化为序贯单趟 OP，误差预计 < 15%"

- **评审标准考虑**：如"简化后仍能回答题目的核心问题，且提升求解效率"

**⛔⛔⛔ 特别警告：以下理由不是跳过升级的合法理由（等同于无声忽略）：**

- ❌ "题目未给 XXX 参数" → 应做合理假设继续建模，不是跳过

- ❌ "子问题1可以简化，留给子问题2/3扩展" → 子问题1也要考虑完整机制

- ❌ "通过其他方式实现类似效果"（如"多机接力代替充电"）→ 这不等同于题目给定的机制

- ❌ "避免增加模型复杂度" → 复杂度本身不是跳过的理由

- ❌ "短续航无人机覆盖有限，就让它覆盖少" → 这恰恰是升级要解决的问题

**⛔ 缺参数的正确处理流程：**

1. 识别缺失的参数（如充电时间）

2. 做合理假设，假设值基于常识/文献/类似赛题

3. 在假设列表中明确声明"假设 XXX = Y，依据是 Z"

4. 灵敏度分析中扰动该假设参数

5. **用假设值完整建模升级版**，而不是跳过整个机制

**⛔ 禁止行为：**

- ❌ 无声忽略升级建议（连"审视"都没做，直接用简单模型）

- ❌ 不读赛题分析的 7.2/7.3 节就开始建模

- ❌ 有异议但不写理由 → 等同于无声忽略

- ❌ 用"单次XXX作为基线，后续扩展"作为借口跳过升级

- ❌ 用"题目未给参数"作为借口跳过升级

**⛔ 如果采用了升级的简化版本**（如"简化的 Multi-Trip OP"），必须在模型中至少保留升级的**核心机制**：

- Multi-Trip → 必须建模"多次访问同一 base 点"

- 带时间窗 → 必须建模"访问时刻 ∈ [a, b]"

- 随机/鲁棒 → 必须建模至少 2 个场景并对比

- 多阶段 → 必须建模至少 2 个阶段的转移

不能以"简化"为名把升级完全去掉。

**⛔ 防错审查（必做）：** 读取 `_utils/error_prevention.md`，根据本题涉及的题型（优化/微分方程/统计/评价/图论/几何/动态规划），对照对应章节的"必须做"和"禁止做"条目。在 MODELING_REPORT.md 末尾写一行：`本题涉及题型：[X, Y, Z]，已对照防错手册审查。`

**📚 按需查阅章节（覆盖竞赛全流程常见坑）**：

- **第九章 约束闭环校验**（必读，所有题型）：题设硬约束在写稿前必须复核

- **第十章 量纲/单位/参考系一致性**：含物理量/工程量/经济量/时间序列的题必读；建模阶段就要登记每个变量的 SI 单位

- **第十一章 随机性与可复现性**：含蒙特卡洛/启发式/神经网络/MCMC 的题必读；建模阶段就要规划 seed 管理与运行元信息

- **第十二章 数据切分/时间穿越/数据泄露**：含训练/测试/预测/因果识别的题必读

- **第十三章 求解器收敛性误判**：含数值优化/非线性求解/MCMC 的题必读；建模阶段就要规划 multistart 与残差检查

- **第十四章 题面参数保真度**（参数 ≥ 20 时必读）：题面参数 50-100+ 的复杂题目（多武器博弈 / 多智能体调度 / 复杂工程系统），建模前必须建立 PROBLEM_FACTS.json 作为唯一权威源；防止 AI 虚构 / 串台 / 漏抄

本节的升级/缺参数案例按开头适用边界解释：先确认属于当前问的题设要求，
不是因技术上做得到就扩展范围。需保留的是题目机制，等价数学表达不因方法名不同被拒绝。

### Step 2: 模型假设

每个假设必须有合理性说明。假设要合理且必要，不做不切实际的简化。

**⛔ 假设参数化原则：** 关键假设必须在代码层面做成可切换的参数，而不是硬编码到逻辑里。这样发现假设错误时，改一个参数就能修正，不需要重写整个求解逻辑。

在 MODELING_REPORT.md 中，每个假设旁边必须写明：

```

假设 1: [假设内容]

  - 理由: [为什么这样假设，不能留空]

  - 参数化: [对应代码中的哪个变量/开关]

  - 替代假设: [如果这个假设不成立，替代方案是什么]

```

示例：

```

假设 3: 每类设备允许多台并行分担同一工序的工程量

  - 理由: 题目说"各类设备须分别完成该工序对应的工程量"，"各类"指设备类型而非单台设备；且问题四增加预算购买设备才有意义

  - 参数化: ALLOW_PARALLEL = True（代码中的开关变量）

  - 替代假设: 每类设备只用 1 台（ALLOW_PARALLEL = False），但这会导致问题四退化为问题三

```

**⛔ 如果某个假设写不出有力的理由，说明这个假设需要再推敲。** 回到 PROBLEM_ANALYSIS.md 的假设预检结果重新审视。

### Step 3: 逐子问题建模

**⛔ 先做一次批量方法调研（省时省额度，覆盖面不减）：** 多个子问题常属同一"方法族"（都是优化 / 都是预测 / 都是评价），逐个各搜一次会重复检索同类结果、串行拖时间。正确做法：

1. 先把所有子问题按方法族归类，列出**去重后的调研主题**（如：`整数规划求解`、`时间序列预测`、`多目标评价`）。

2. 对每个**去重主题**做一次 WebSearch（不是每个子问题各一次）——同族的多个子问题共用一次调研结果。

3. 把调研到的方法/文献记在手边，下面逐子问题建模时直接引用，**同族不再重复搜**。

4. 若某子问题确有独特之处（如特殊约束、特殊规模）不被已搜主题覆盖，才为它补一次针对性搜索。

这样：3-5 个子问题若同属 1-2 个方法族，联网次数从 3-5 次降到 1-2 次，调研深度和覆盖面完全不变。

每个子问题：

1. **方法调研** — 引用上面批量调研的对应方法族结果（同族已搜过，直接用，不重复搜）；仅当本子问题超出已搜主题时才补搜一次。不要只凭训练知识选方法——同一类问题在不同规模下最优方法可能完全不同（如 TSP 小规模用精确求解，大规模用 LKH 启发式）

2. **模型选择与理由** — 为什么选这个模型，与候选模型的优势对比，引用调研到的文献支撑

3. **数学公式推导** — 完整严谨，使用 LaTeX 数学环境（目标函数+约束条件）

4. **求解算法设计** — 伪代码或流程描述

方法选择参考 `_references/methods_table.md`。

### Step 4: 符号说明表

确保所有公式中的符号都有定义：

| 符号 | 含义 | 单位 | 取值范围 | 首次出现 |

|------|------|------|----------|----------|

### Step 5: 模型检验与灵敏度分析设计

1. **模型检验**：回代检验、交叉验证、残差分析

2. **灵敏度分析**：关键参数的变化范围和影响

3. **鲁棒性检验**：数据扰动下的稳定性

### Step 5.5: ⛔ 合理性预验证 + 结果预期范围表（建模完成后必做）

**核心原则：物理约束 > 数据忠实度 > 计算正确性**

**编码阶段是纯执行者，遇到"结果不对"只能按建模阶段的预案操作，不得自行发明修正方法。因此建模阶段必须把所有决策做完。**

**执行步骤：**

1. **对照防错手册审查模型**：重新查阅 `_utils/error_prevention.md` 中本题对应题型的"必须做"和"禁止做"条目，逐条确认模型是否满足。不满足的当场修改模型。

2. **输出建模报告的必备内容**（在 MODELING_REPORT.md 末尾，comp-code 必须对照执行）：

**⓪ 参数口径表**（⛔ 防"同一物理量在不同子问题口径打架"，comp-code 会按此表校验一致性）：

```markdown

## 参数口径表

| 物理量 | 唯一定义值 | 单位 | 语义标签 | 用于哪些子问题 |

|--------|-----------|------|---------|--------------|

| 单车服务时长 | 45 | min/次 | service_time | Q2 排队、Q3 运输 |

| 单车日服务上限 | 12 | 次/日 | daily_capacity | Q1 容量、Q3 运输 |

| 黄金响应时间 | 4 | min | total_response | Q2 |

| 站点覆盖半径 | 3 | km | coverage_radius | Q1 |

```

⛔⛔ **同一物理量全篇只能有一个定义值和一个语义标签**：若排队模型用"服务率 μ=1.333 次/分"、运输模型用"日上限 12 次"，两者换算出的**日服务力必须一致**（μ×营业时长 应 ≈ 日上限，否则同一辆车在两个模型里能力不同——这正是真实翻车的红线二）。发现换算冲突，当场统一口径再往下写，**禁止**两套并存。每个语义标签在全篇物理含义唯一（如 `total_response` 就是"总响应时间"，不能一处指总响应、一处指纯排队等待）。

**① 结果约束清单**（硬边界，超出即判定代码有误）：

```markdown

## 结果约束清单

- [变量名] ∈ [下界, 上界]，物理含义：[为什么是这个范围]

- [变量名] 的符号/方向约束：[说明]

- [守恒量]：[应满足的恒等式或误差上限]

```

⛔⛔ **每条约束必须可机器审计**（comp-code 步骤会按此清单写 `constraint_audit.py` 复核最终 results.json）：

- 每条用一行 Python lambda 表达式或显式公式表达，**不要用模糊的自然语言**

- **动态派生属性**（依赖载体状态或上游变量变化的量：作用范围 / 时变参数 / 状态依赖容量等）：必须写明"派生量 = f(载体当前状态, 平台/系统参数)"，**禁止**简化成"以静态点为圆心的固定区域"或"取均值后当常数"

  - 例：海战题机动武器作用范围 / SEIR 模型时变接触率 / 交通题时段容量 / 电网时变负载

- 详见 `_utils/error_prevention.md` 第九章 "约束闭环校验"

**② 预期行为描述**（定性描述合理结果的"形状"）：

```markdown

## 预期行为

- 时间尺度：系统应在 [X] 时间内达到 [什么状态]

- 稳态特征：[哪些量] 应趋于常数/周期/衰减

- 瞬态特征：[初始阶段应该看到什么现象]

- 单调性/对称性：[哪些量应该单调递增/对称/...]

```

**③ 异常处理预案**（每种异常只给一种修正方法，不留选择空间）：

```markdown

## 异常处理预案

若出现 [具体异常描述]：

  → 原因判断：[最可能的原因]

  → 唯一修正方法：[具体步骤]

  → 禁止：[不允许的替代方案]

```

**④ 方法唯一性声明**（每个计算步骤指定唯一方法，包括预处理/后处理/插值/滤波）：

```markdown

## 方法指定

步骤 N：[做什么]

  方法：[唯一指定的方法名 + 关键参数]

  输入：[从哪来]

  输出：[到哪去]

  禁止替代：[不允许用的方法，以及为什么不用]

```

**⑤ 验证检查点**（编码阶段必须执行的 pass/fail checklist）：

```markdown

## 验证检查点

□ [检查项]：[判定条件]，若 fail → [跳转到哪个异常预案]

□ [检查项]：[判定条件]，若 fail → [跳转到哪个异常预案]

□ 最终：所有输出量均在约束清单范围内

```

**⑥ 优化结果结构性验证输入**（优化类子问题必须提供，编码阶段的 `structural_validation()` 依赖这些信息）：

```markdown

## 结构性验证输入（供 comp-code 层级 5 使用）

### 约束活跃性预期

- [约束名1]：预期活跃/不活跃，理由：[为什么这个约束应该/不应该取等号]

- [约束名2]：预期活跃/不活跃，理由：[...]

- 如果所有约束都不活跃 → 说明 [什么情况]，需要 [什么操作]

### 决策变量合理范围与预期行为

| 变量 | 物理含义 | bounds | 预期取值区间 | 若取到边界说明什么 |

|------|---------|--------|-------------|------------------|

| x_1 | [含义] | [lb, ub] | [预期在哪个子区间] | [取到上界=资源耗尽/取到下界=该资源无用] |

### 灵敏度方向表

| 决策变量 | 增大时目标函数方向 | 预期灵敏度量级 | 若方向相反说明什么 |

|----------|-------------------|---------------|------------------|

| x_1 | ↓（减小=更优） | 高（主导项） | 目标函数符号写反了 |

### 稳定性预期

- 问题是凸的/非凸的？

- 预期有几个局部最优？（1个=结果应完全稳定；多个=允许 CV<5%）

- 可接受的变异系数阈值：[X]%

### 资源利用率预期

- [资源1]：预期利用率 [X%-Y%]，若为 0 说明 [什么问题]

- [资源2]：预期利用率 [X%-Y%]，若为 0 说明 [什么问题]

```

**⑦ 方法声称清单 METHOD_CLAIMS**（⛔ 防"文本声称的方法 ≠ 代码实际实现"，红线一/三根治；写进 MODELING_REPORT.md，编译阶段严格模式据此做"实现对账"）：

```markdown

## 方法声称清单（METHOD_CLAIMS）

| 编号 | 正文/模型将声称的方法 | 代码里必须真实现的特征（可核查） |

|------|---------------------|-------------------------------|

| M1 | 含单站容量约束的整数规划最优指派 | 有整数决策变量 + 单站容量约束进模型 + 该约束进求解器，不是 p-median 后就近配车 |

| M2 | M/M/c 排队模型算等待时间 | 真按到达率/服务率/台数算 Wq，且 Wq 计入最终响应时间 |

| M3 | 泊松到达 + 指数服务的蒙特卡洛仿真 | 真模拟泊松到达时刻 + 指数服务时长 + 车辆忙闲/排队/无车可派，不是给固定响应时间加小噪声 |

```

⛔⛔ **每一句写进正文的关键方法声称都要在此登记，并写清"代码里凭什么算实现了它"**。这是给编译阶段"方法实现对账"闸用的合同：**声称什么，代码就必须真做到什么**。禁止正文写"整数规划/泊松蒙卡"而代码只做了"p-median 就近/固定响应加噪声"这类**包装层与实现层脱钩**（正是真实翻车的红线一、三）。

⛔⛔⛔ **同时产出机器可核合同块（方向无关，把上表的"可核查特征"翻译成脚本能执行的签名）：** 上表第三列是给人看的散文，脚本核不了。必须**再补一段 `METHOD_CLAIMS_MACHINE` 注释块**写进 MODELING_REPORT.md——每条关键声称给两组签名：`must`（代码里**必须出现**的实现铁证，至少命中一个）、`forbid`（建模**明令禁止**的降级替代，出现任一即判背叛）。编译阶段 `claim_code_check.py` 会零方向知识地逐条核对（must 缺 或 forbid 命中 → HARD FAIL）。

```markdown

<!-- METHOD_CLAIMS_MACHINE

M1 | must: LpInteger, cat=.Integer, GRB.INTEGER | forbid: linprog, 就近配车

M2 | must: from_pretrained, AutoModel, nn\.Module | forbid: LogisticRegression, TfidfVectorizer

M3 | must: \.encode\(, embedding, faiss | forbid: TfidfVectorizer, difflib

-->

```

> - **签名写代码里必然留痕的 API/关键词**（正则，大小写不敏感）：真做深度模型必有 `from_pretrained/torch/nn.Module`；真做语义必有 `encode/embedding`；真做整数规划必有 `LpInteger/GRB.INTEGER`。`forbid` 填这条方法**最容易被偷偷替换成的那个降级**（如"声称 BERT 微调 → 禁 LogisticRegression"）。

> - **这套方向无关**：不管你这题是优化/NLP/CV/时序/强化学习，都由你（最懂本题的建模者）现场把"何为忠实实现"翻译成 must/forbid——平台脚本不预置任何方向规则，只执行你写的合同。

> - ⛔ **每条走进正文的核心方法都要有一行机器签名**；漏写的方法脚本核不到（同能力清单"漏列即漏核"），所以别偷懒只写散文表。

**⛔⛔ 同时产出「逻辑合同」`LOGIC_CONTRACT_MACHINE`（通用元约束，下游 `logic_audit.py` 据此机器核，治"数值合法但逻辑错"）：** 与 METHOD_CLAIMS 并列，写进 MODELING_REPORT.md 的一个 ```json 代码块。四类元约束，方向无关、按本题实质填：

```json

{"LOGIC_CONTRACT_MACHINE":{

  "bounds":[{"quantity":"<反解/取界得到的量>","is":"upper|lower","reason":"<一句推导:为何是上界/下界>"}],

  "no_double_count":[{"aggregate":"<用总量拟合/标定的项,如截距>","contains":"<它已吸收的分项>"}],

  "must_features":["<DATA_FACTS 里 role=observed 的关键变量,必须进模型>"],

  "train_range":{"<量>":[<min>,<max>]},   // 直接抄 DATA_FACTS 的实测区间,供外推报警

  "monotonic":[{"more":"<决策资源>","then":"<目标量>","dir":"better|worse"}],

  "constraints_with_margin":[{"quantity":"<受限量>","limit":<限值>,"kind":"le|ge","min_margin":<要求余量比例,如0.05>}],

  "calibration_anchors":[{"quantity":"<标定锚点对应的量>","anchor":<锚点取值>,"optimistic_dir":"low|high"}]

}}

```

> - **`bounds`（治方向反，⛔ 必须走"方向推导四步"，不许拍脑袋）**：凡有"反解、取界、由删失/封顶值反算"，**禁止直接下结论**，必须在报告里写清四步、再填 `is: upper|lower`：

>   1. **不等号**：观测值和真值什么关系？（如传感器右截断/封顶 → 观测值 ≤ 真值）

>   2. **代入**：把这个不等号代进你的反算公式

>   3. **推界**：推出反算量是**上界**还是**下界**（如 η=1−Cout/Cin，Cout 被低估 → η 被高估 → 是**上界**）

>   4. **数值验算**：代一个具体数字验证方向（如 Cout 真值比观测大 5 → η 真值比算得的小 → 印证上界）

>   把"拍脑袋"逼成"显式慢推导"，能砍掉大半方向错；这四步也是 comp-review 逐步核对的锚点。

> - **⛔ 方向探针(半硬闸，让数据替你验方向)**：对每条 bounds，在建模报告里给 comp-code 下一条指令——"把被截断/封顶的输入朝**真值方向**推一点(加 δ)后重算该量，把变化符号写进 `figures/all_results.json` 的 `logic_probes.bounds`"。下游 `logic_audit.py` 会核：声明 upper 则该量应随之**减小**(sign<0)、lower 应**增大**(sign>0)，符号与声明矛盾 = 方向标反，**FAIL**。这一步不靠模型判断方向，是**数值证伪**，是①方向反唯一能拉回"可验证"的防线。

> - **`no_double_count`（治重复计量）**：任何"总量 = A + B"结构，若 A 的拟合/标定已经吸收了 B（如截距用含某分项的总量拟合），就登记「aggregate=A, contains=B」，下游发现代码又显式 `A + B` 就报警。

> - **`must_features`（治漏变量）**：把 DATA_FACTS 中 `role=observed` 的真实变量列进来，下游断言它们确实进了设计矩阵，漏用即报警。

> - **`train_range`（治外推口吻）**：抄数据实测区间；下游预测点超出太远 → 强制标"情景模拟、需现场标定"。

> - **`constraints_with_margin`（治"顶格达标、零安全裕度"）**：对每条**必须满足限值**的关键量，登记 `limit`+`kind`(le=应≤/ge=应≥)+可选 `min_margin`(要求距限值至少留的余量比例)。下游 `logic_audit` 核：结果**恰好等于限值**(如浓度算出正好=10)→ 零裕度 FAIL(工程不可用，簇内其他时刻/扰动/工况切换极易破限)；留了余量但**低于 min_margin** → 裕度不足 FAIL。⛔ 优化题**务必填**——"数值刚好达标"是最常见的"数值合法但工程不可用"。

> - **`calibration_anchors`（治"标定锚点比观测更乐观→系统性高估能力"）**：若用某个工况点做参数反解/标定，登记该锚点的 `quantity`+`anchor`(取值)+`optimistic_dir`(该量朝哪个方向算"乐观/高估设备能力"：low=越低越乐观 / high=越高越乐观)。下游核：锚点若落在观测区间的**乐观端之外**(如出口浓度锚点取 20，而实测只到 48.74~50) → 报警"锚点比数据更乐观，会系统性高估能力、低估达标所需电压/电耗"。⛔ 凡"单点反解缩放参数"务必填。

> - 填不出的键留空数组/对象即可（下游对空合同软跳过，不误报）。

**⛔⛔ 若为多子问题，产出「跨问结论登记」`CROSS_PROBLEM_LEDGER.json`（治"横向割裂/跨问矛盾"）：** 竞赛链各子问题是隔离跑的，一个问算出的关键结论不会自动传给另一个问（质疑"Q1算出峰值超限、Q2优化却只压稳态"这类矛盾就是这么漏的）。这份登记让上游结论显式约束下游：

```json

{"problems":[

  {"id":"Q1","conclusions":[

     {"quantity":"<关键量,如峰值浓度>","value":<数>,"kind":"peak|steady|bound",

      "imposes":{"on":["Q2","Q4"],"must_le":<上限>,"must_ge":<下限>,"note":"<为何要约束下游>"}}]},

  {"id":"Q2","observed":{"<同名量>":<Q2实际取到的值>}}

]}

```

> - 上游问题若得出"某量会达到 X"这类**对下游有约束意义**的结论，就在 `imposes` 里声明它约束哪些问、上/下限是多少。下游问题把自己实际取到的对应量填进 `observed`。下游 `cross_problem_check.py` 自动对撞，越界即报矛盾。

> - 没有跨问约束就不填（软跳过）。这是唯一负责"跨问对撞"的环节，别省。

**⛔⛔ 假设问责表（治"把假设当数据结论"，对每个"无数据只能假设"的参数强制填）：** 数据台账 `DATA_FACTS.json` 里 `role=assumed`（或 `has_data=false`）的量，在 MODELING_REPORT.md 里逐个填四项——机器拦不了"假设合不合理"（那是判断），但能逼你把"这个结论其实是假设撑起来的"显性化，堵住②那种确定性口吻：

| 假设参数 | (a) 为何无数据只能假设 | (b) 取值依据(文献/经验/量级) | (c) 灵敏度:该假设±X% 时关键结论变多少 | (d) 假设若错,结论还成立吗 |

|---|---|---|---|---|

> - **核心是 (c) 灵敏度**：若某假设一变、关键结论就翻，它就是"结论的软肋"——**必须标红，并在正文明写"本结论强依赖假设 Z、非数据直接支持"**，禁用"结论是/确定"这类口吻。

> - (d) 逼你自问"抽掉这个假设，结论垮不垮"——垮 = 结论是假设的产物不是数据的产物，如实标注为"情景模拟/需现场标定"。

> - ⛔ 这张表不替你判断假设对错(机器做不到)，只逼你**暴露结论对假设的依赖**——这正是治②的关键：不是拦假设，是拦"把假设结果当数据结论陈述"。

**⛔⛔ 目标/约束原文溯源（治"任务读歪"，每个目标函数/约束强制引原句）：** 建模不是凭空写目标——每个**目标函数**和每条**关键约束**，都要在 MODELING_REPORT.md 里注明它对应赛题分析《关键概念对齐表》的哪一行、题目**原句**怎么说（像数字溯源一样给出处）：

| 建模对象 | 数学表达 | 对应题目原句/对齐表行 |

|---|---|---|

| 目标函数 | min C = 建设+运营 | "使总成本最小"(对齐表 S5) |

| 约束1 | W ≤ W_max | "覆盖宽度不超过…"(对齐表 S3) |

> - ⛔ **核对"我建的目标 vs 题目要的目标是不是一回事"**：最优化方向(min/max)、约束不等号方向、优化对象本身，都要和原句对得上。求"覆盖宽度"却建了"面积"的目标、"最小成本"写成 max——在这张溯源表里和原句一比就露馅。

> - ⛔ 溯源不到原句的目标/约束 = 可能是**你脑补的、题目没要求的**，或**把题目要求理解错了**——必须回赛题分析核对《关键概念对齐表》。

> - 天花板：若赛题分析那步就把某概念理解歪了，这里两边可能都错（同源）——所以 comp-review 会带着题目原文独立复核这张表（见 comp-review 第6类）。

**⛔⛔⛔ 建模阶段强制修复原则（不可跳过）：**

审查中发现任何问题，**必须当场修复模型再继续**，不能留给 comp-code 阶段：

- 模型缺少约束 → 立即补充约束条件

- 开环积分可能漂移 → 立即加入反馈/阻尼/去漂移机制

- 守恒律不满足 → 立即补充遗漏项

- 极端输入导致发散 → 立即加入饱和/截断/正则化

**⛔ 禁止的做法：**

- ❌ 发现问题但写"留给 comp-code 阶段处理"

- ❌ 在预期范围表里写了修正方案但不修改模型本身

- ❌ 只在文字中提到"需要注意XXX"但模型公式没变

**⛔ 检测到问题 = 必须修复。解释原因 ≠ 处理完毕。本步骤不允许带着已知问题输出 MODELING_REPORT.md。**

**同时产出可检索的实现提示块**：`METHOD_CLAIMS_MACHINE` 的 `must`/`forbid` 签名帮助定位实现，不能仅凭关键词缺失就断言没有实现，也不能把其他子问题或基线中的同名方法误判为当前模型。真实方法一致性以函数调用、输入输出、结果与 CAPABILITY_CHECKLIST 的逐项证据为准；静态未知项在已有语义核对中确认，不另起全流程。

### Step 6: 输出

保存到 `MODELING_REPORT.md`：模型假设、符号说明、每个子问题的模型/公式/算法、检验方案、灵敏度分析方案、编程实现要点。

**⛔ 必须将 PROBLEM_ANALYSIS.md 中的图表预规划带入 MODELING_REPORT.md。** 在报告末尾附上图表预规划章节（从 PROBLEM_ANALYSIS.md 复制或更新），确保 paper-figure 能读到完整的图表清单。如果建模过程中发现需要额外的图表（如灵敏度分析曲线、模型对比热力图），在此处补充。

**⛔ MANDATORY: 输出前自检（写完 MODELING_REPORT.md 后必须逐项检查）：**

```bash

echo "=== 建模报告自检 ==="

[ -f MODELING_REPORT.md ] || { echo "❌ MODELING_REPORT.md 不存在！"; exit 1; }

# 1. 子问题覆盖度（统一口径：只数标题行声明的子问题，中文/阿拉伯/英文编号都支持，

#    避免历史 bug：PROB_COUNT 用全文松匹配虚高、MODEL_SECTIONS 用标题匹配，两个口径比大小恒误报）

PROB_COUNT=$(bash _utils/count_subproblems.sh PROBLEM_ANALYSIS.md)

MODEL_SECTIONS=$(bash _utils/count_subproblems.sh MODELING_REPORT.md)

echo "赛题子问题数: $PROB_COUNT, 建模报告覆盖: $MODEL_SECTIONS"

[ "$MODEL_SECTIONS" -lt "$PROB_COUNT" ] && echo "❌ 有子问题未建模！"

# 2. 每个子问题是否有目标函数或模型公式

OBJ_COUNT=$(grep -c '目标函数\|min\|max\|最小化\|最大化\|objective\|模型公式\|数学模型' MODELING_REPORT.md 2>/dev/null || echo 0)

echo "目标函数/模型公式出现次数: $OBJ_COUNT"

[ "$OBJ_COUNT" -eq 0 ] && echo "❌ 未找到任何目标函数或模型公式！"

# 3. 约束条件（优化类必须有）

CONSTRAINT_COUNT=$(grep -c '约束\|s\.t\.\|subject to\|限制条件\|≤\|≥' MODELING_REPORT.md 2>/dev/null || echo 0)

echo "约束条件出现次数: $CONSTRAINT_COUNT"

# 4. 符号说明表是否存在

grep -q '符号.*说明\|符号.*含义\|Symbol.*Description' MODELING_REPORT.md && echo "✅ 符号说明表存在" || echo "❌ 缺少符号说明表"

# 5. 灵敏度分析方案是否存在

grep -qi '灵敏度\|sensitivity\|鲁棒性\|robustness\|稳健性' MODELING_REPORT.md && echo "✅ 灵敏度/鲁棒性分析方案存在" || echo "⚠ 缺少灵敏度分析方案（评审加分项）"

# 6. 图表预规划是否带入

grep -qi '图表预规划\|fig_\|TABLE_\|DrawIO' MODELING_REPORT.md && echo "✅ 图表预规划已带入" || echo "❌ 缺少图表预规划（paper-figure 步骤需要）"

# 7. 编程实现要点是否存在

grep -qi '编程\|实现要点\|Python\|算法步骤\|伪代码' MODELING_REPORT.md && echo "✅ 编程实现要点存在" || echo "⚠ 缺少编程实现要点（comp-code 步骤需要）"

# 8. 问题递进性检查（最关键）

echo ""

echo "=== 问题递进性检查 ==="

echo "⛔ 人工审查：在你的模型下，每个问题的结果是否比前一个有明显变化？"

echo "   如果某个后续问题的结果和前一个几乎相同，说明模型假设可能有问题。"

echo "   特别检查：新增的变量/资源/约束是否对目标函数有边际效益？"

echo "   如果没有 → 回到 PROBLEM_ANALYSIS.md 的假设预检重新审视。"

# 9. 假设参数化检查

PARAM_COUNT=$(grep -c '参数化:\|ALLOW_\|ENABLE_\|USE_\|开关变量' MODELING_REPORT.md 2>/dev/null || echo 0)

echo "假设参数化标记数: $PARAM_COUNT"

[ "$PARAM_COUNT" -eq 0 ] && echo "⚠ 未找到假设参数化标记——关键假设应该在代码中做成可切换参数"

```

**如果有 ❌ 项，必须补充后再结束本步骤。⚠ 项建议补充但不强制。**

**⛔⛔⛔ 参数密集型题目必跑（题面参数 ≥ 20 时）：**

```bash

# 1) 复审前置步骤的 facts/OCR 一致性（防 Step 1 通过后中途篡改）

# 2) 新增审计 MODELING_REPORT.md 数字溯源 + rules 覆盖度

python3 _utils/facts_audit.py --stage modeling 2>&1 | tee AUDIT_REPORT.md

RC=${PIPESTATUS[0]}

if [ $RC -eq 1 ]; then

    echo "⛔ Step 2 审计失败：MODELING_REPORT.md 含 facts 中找不到的数字（疑似建模凭印象），或 rules 段规则没体现在建模中。必须修复后重新跑，不要结束本步骤。"

fi

# 在 MODELING_REPORT.md 末尾追加凭证（facts_traced = 报告中能溯源到 facts 的数字数；rules_covered = facts.rules[] 中已在 MODELING_REPORT 中体现的规则数）

echo "" >> MODELING_REPORT.md

echo "<!-- MODELING_OK facts_traced=N rules_covered=M source=PROBLEM_FACTS.json rechecked_at=$(date -Iseconds) -->" >> MODELING_REPORT.md

```

**为什么 Step 2 也要跑审计**：MODELING_REPORT.md 引用 facts 数值时，AI 可能凭印象写错（例如把 facts.weapons[0].targets[0].p_detect=0.95 写成 0.9）。Step 2 不抓 = 错误数值流到 Step 3 建模实现，污染整个 code。


## 执行与产出

使用当前执行会话完成本步工作；产物路径按当前步骤合同。程序采集真实操作、输入输出、版本与运行清单，模型只负责实质成果和领域质量。

建议额外记录：求解器及版本、求解参数、输入数据哈希。

## 关键规则

- 公式必须严谨：每个变量定义，每个等式有推导依据

- ⛔ **机理/场问题题按需读取**：本题涉及**状态相关系数（D(C,T) 变物性）、PDE/场仿真、连续事件/临界值、反问题标定**时，先读 `_utils/mechanism_accuracy_addendum.md`（双副本同 shared-scripts/）对应节——16.2 PDE 场问题（网格收敛/误差分层/收支守恒）、16.1 首达时刻精度、16.3 可辨识性、16.11 本构关系与系数物理含义（D(C,T) 这类系数与它作用后的物理量必须分开）。选影响当前答案的最小有效检查，不全量套用。


- ⛔⛔ **Markdown 中的 LaTeX 公式必须包在 `$` / `$$` 内，否则渲染器当纯文本显示原始 LaTeX 代码**：

  - **行内公式**：`$x^2 + y^2 = r^2$`（一个 `$` 包围）

  - **块级公式**：`$$` 必须单独占一行，前后各空一行：

    ```

    $$

    v_k = |\dot P_k| = b\sqrt{1+\theta_k^2}\,|\dot\theta_k| \tag{12}

    $$

    ```

  - **多行环境**（`\begin{aligned}` / `\begin{cases}` / `\begin{bmatrix}`）必须放在 `$$...$$` 块级公式中，不要放在行内 `$...$` 中

  - **避免 `\text{}` 包裹中文**（KaTeX 对中文支持有限），中文说明放在公式外面

  - ⛔⛔ **典型错误反例**（看到 `\tag{N}` / `\sqrt` / `\hat` / `\frac` 凡是反斜杠命令开头的行，先问自己"包 `$$` 了吗"）：

    ```

    ❌ v_k = |\dot P_k| = b\sqrt{1+\theta_k^2}\,|\dot\theta_k|. \tag{12}

    ❌ \text{角点} = P_k - e\hat{u} \pm \tfrac{W}{2}\hat{n}, \tag{13}

    ❌ \exists\,\hat{a}\in\{\hat{u}_i,\hat{n}_i\}\: ... \tag{14}

    ```

    上面三行都缺 `$$` 包围，渲染器会原样显示 `\dot`、`\sqrt`、`\tag{12}` 这些 LaTeX 代码字面字符。

  - **正确写法**：

    ```

    $$

    v_k = |\dot P_k| = b\sqrt{1+\theta_k^2}\,|\dot\theta_k|. \tag{12}

    $$

    ```

  - **写完每段含公式的章节后必须自检**（在 heredoc 写入 MODELING_REPORT.md 之后立即跑）：

    ```bash

    # 扫描裸 LaTeX 命令（反斜杠开头）但当前行不在 $$ 块内

    python3 - <<'PY'

    import re

    text = open("MODELING_REPORT.md", encoding="utf-8").read()

    # 移除已正确包围的 $$...$$ 块和 $...$ 行内公式以及代码块

    cleaned = re.sub(r'```.*?```', '', text, flags=re.DOTALL)

    cleaned = re.sub(r'\$\$[\s\S]*?\$\$', '', cleaned)

    cleaned = re.sub(r'\$[^\n$]+\$', '', cleaned)

    # 在剩余文本里找 \tag{ / \sqrt / \hat / \frac / \dot / \begin{ 等典型 LaTeX 命令

    bad = []

    for i, line in enumerate(cleaned.split('\n'), 1):

        if re.search(r'\\(tag|sqrt|hat|frac|tfrac|dot|begin|cdot|pm|in|exists|forall|big|cap)\b', line):

            bad.append((i, line.strip()[:80]))

    if bad:

        print(f"❌ 发现 {len(bad)} 处裸 LaTeX（缺 $$ 包围）：")

        for ln, s in bad[:10]:

            print(f"  L{ln}: {s}")

    else:

        print("✓ 公式包围检查通过")

    PY

    ```

    **报告 ❌ = 必须立即用 Edit 工具把那几行包进 `$$...$$`，再继续往下写。**

- 模型假设是评审重点：合理、必要、有说服力

- 符号说明表必须完整

- 灵敏度分析不能省（评审加分项）

- 编程实现要点要具体：算法、库、输入输出格式

- ⛔ 主输出文件：`MODELING_REPORT.md`。不要在根目录写额外报告

- ⛔ **本步骤只输出 MODELING_REPORT.md，不要写 Python/MATLAB 代码文件。** 代码实现是下一步 `comp-code` 的任务。本步骤只需要在报告中描述算法伪代码、求解思路、编程实现要点即可。如果需要验证某个公式或做简单计算，可以用 Bash 内联 Python 一次性脚本，但不要创建 `code/*.py` 文件

- ⛔ **分段写入：每次 Bash heredoc < 150 行。** MODELING_REPORT.md 通常很长，必须分 3-4 段追加写入（`cat << 'EOF' >> MODELING_REPORT.md`），不要一次性写完整个文件

## ⛔⛔ 建模阶段通用禁止声明

详细条目见 `_utils/error_prevention.md`，以下为最高优先级的两条硬性禁止：

1. **禁止未声明的几何/物理简化** — 必须用实体完整几何作为约束判据，禁止降维简化（矩形→线段、实体→质心点）。若确需简化必须显式声明适用条件和误差上界。

2. **禁止约束遗漏** — 题目中每个"不超过/至少/必须满足"都必须对应一个数学约束表达式。物理接触约束（不能穿透/重叠/超出边界）必须显式建模为不等式约束。

## 检查证据与返修范围

检查与返修遵循 `_utils/quality_gate_contract.md`。数据推导值不一定逐字出现在原始 JSON 中，必须先核对计算、单位与舍入；禁止为迎合检查删掉真实结果。静态特征匹配不能替代能力项与实际运行证据。通过标记只能在真实核对之后写入；缺少标记是待核对状态，不是模型错误。不要自行追加固定公式数量、隐藏安全裕度或无限重复检查。

## 退出判据（Verification）

本步完成前逐项自检（不达标即视为未完成）：

- [ ] 符号表完整，与正文/代码命名一致
- [ ] 每条假设给出依据与影响范围
- [ ] 模型公式可被独立复算（含参数取值来源）
- [ ] 跨问衔接已声明（复用/差异/剪枝关系）

## 常见合理化（Common Rationalizations）

| 合理化 | 现实 |
|---|---|
| "假设写得保守一点就行" | 假设决定结论的适用边界；无依据的假设会被审稿判为致命项。 |
| "公式差不多对，细节后面补" | 公式是后续代码与论文的唯一真源，此处含糊会导致跨产物矛盾。 |
| "跨问不必交代关系" | 不问衔接是 fatal（跨问矛盾）。 |

> 本段与 `skills/_utils/anti_rationalization.md`（全局版）配套：本表是本步专属，
> 全局版覆盖跨步骤通用借口。新增借口时优先落到本表（更贴岗位），能泛化再上升。

## 补充参考

- `references/mml-skills/model-quality-contracts.md`：模型质量与逐问递进合同（跨问题统一机制内核/继承扩展纪律）——多子问题建模前读。（来源 Math-model-skills，MIT，溯源见同目录 UPSTREAM.md）