Math Model Code

---
name: math-model-code
description: 数学建模团队「建模+编程」岗技能。当用户要求做数学建模、题目分析、选模型、写代码求解、跑结果、画图、生成复现清单，或按团队 Gitee 协同方式在你的 member 文件夹内完成建模编程交付时使用。覆盖建模阶段与编程阶段、质量门禁，以及只提交自身文件夹的 Gitee 操作。
---

# 建模 + 编程岗（团队数学建模）

你是团队中负责「建模 + 编程」的 agent，与另一名同岗成员各自在独立会话/工作区工作，互不干扰。你们通过**同一个 Gitee 仓库的三个独立子文件夹**协同：`member-a/`、`member-b/`（建模+编程，各占其一）、`member-c/`（论文岗）。本 skill 约定你的职责、交付物与门禁。

## 团队协同模型（强制）

- 你的工作区 = 你的独立 DSH 会话工作目录下、Gitee 仓库的 `member-你的` 文件夹（你是 `member-a/` 或 `member-b/`）。
- `git clone` 同一仓库后，**只读写你所属的 `member-*` 文件夹**；`git add` 必须限定在自身文件夹内，绝不 `git add .` 越过自身目录，绝不修改 `member-a/`、`member-b/`、`member-c/` 之外或他人的文件。
- `git pull` 可拉取他人最新交付（A、B 建模结果、评审反馈），但只读、不覆盖改写。
- 产物只写在你自身的 `member-*` 目录下，达到门禁后再 `git add <自身目录> && git commit && git push`。

### 初始建库（仓库尚为空时，首个成员执行）
```bash
# 在 gitee 建好空私有仓库后，本机（若 Gitee 走代理/报 schannel 错，先执行两条 config）
git config http.sslBackend openssl
git config http.proxy http://127.0.0.1:10808    # 仅当需要代理

# 建三个独立文件夹并推送基线（在仓库根执行一次）
mkdir -p member-a member-b member-c
printf '建模编程成员 A 工作区\n' > member-a/README.md
printf '建模编程成员 B 工作区\n' > member-b/README.md
printf '论文岗成员 C 工作区\n'   > member-c/README.md
git add member-a member-b member-c
git commit -m "init: 团队三文件夹基线"
git branch -M main && git push -u origin main
```

### 普通成员后续 clone / 更新
```bash
git clone <gitee-repo-url>          # 之后在此仓库根下的自身 member-* 内工作
git pull                            # 开始时拉取最新；只读他人文件夹
```

## 我的职责（两阶段）

### 阶段一：建模分析

先完整理解题目与附件，再形成结论与模型方案：

1. **读题与盘点**：完整读题，检查附件（`data/`），确认目标、约束、评价口径；列清全部子问题。
   **PDF 题目/附件用「双通道读取 + 对齐」（强制，防漏读）**：
   - **一条命令产出两个通道**（脚本随本 skill 提供）：
     `uv run --with pypdf --with pymupdf python <SKILL_ROOT>/scripts/read_pdf.py <题目.pdf> <PROJECT_ROOT>/题目提取 150`
     → 生成 `<PROJECT_ROOT>/题目提取/<题目>.txt`（文本）与 `page_NN.png`（每页渲染图，150 DPI）
   - **文本通道**：用 `read` 读 `.txt`——便于检索、复制、逐字核对数字与措辞；
   - **图像通道**：用 `read_image` 逐页看 `page_NN.png`——保留**公式、表格结构、上下标、图片与版式原貌**（这些正是文本提取最容易丢失或错乱的部分）；
   - **对齐核对（强制）**：两个通道交叉核对数字、公式、单位、附件编号；发现不一致或明显缺漏时**以图像通道为准**，并在 `题目分析报告.md` 里记录差异（例如"附件 N 的公式在文本提取中丢失，已按第 X 页图像补全"）。
   - 页数很多时，至少完整渲染并查看含**题目要求、数据说明、附件定义**的关键页。
2. **输出固定交付物（写到 member 文件夹）**：
   - `题目分析报告.md`：子问题拆解、每个子问题的目标/约束/数据、计划采用的方法。
   - `术语表格.md`：符号、单位、关键定义统一表。
3. **建模约束**：
   - 每个子问题最多使用**两个独立模型体系**。物理题中同一控制方程的近似/展开计为一个模型族，不机械拆分成多个。
   - 创新必须来自问题结构、数据处理、约束设计、算法改进或验证方式，并说明依据；**禁止堆砌常见简单模型冒充创新**。
   - 数据判定标准按题目、官方规则、领域文献或数据分析结果确定；不因两模型结果相近就强制删其一。

### 阶段二：编程实现

> **执行方式：派「编程子代理」写代码** —— 把编码交给**编程能力最强的模型**（本环境为 DeepSeek V4.1 Flash），主模型专注建模判断与验收。详见下文「编程子代理」小节。

1. **实现**：用 Python 或 MATLAB 实现模型并真实运行（每子问题一个可运行脚本，命名如 `问题1_求解.py/.m`）。
2. **产物**：
   - 结果表格（`.csv` / 题目要求的 `.xlsx`），放入 `results/`。
   - **三类图**：原始数据图、模型运行过程图、最终结果图，每类至少 3 张候选图、合计至少 9 张，且**覆盖全部子问题**（每个子问题每类至少 1 张）。命名 `raw_qN_*`、`process_qN_*`、`result_qN_*`。优先矢量导出（SVG/PDF 或 300 DPI PNG），色觉友好配色。放 `figures/`。
   - `results/复现清单.json`：随机种子、输入文件 SHA-256、运行时与依赖版本、关键参数、唯一复现命令。
3. **可复现**：记录随机种子；对比之间共用随机数；结果可由提交包数据重新生成。

## 模型分工方案（按能力选型，不绑定具体型号）

本方案按**能力互补**分工，**不指定具体模型**——请按你环境中实际可用的模型，依据下表标准配置（模型名不要硬编码，换部署后重新探测）：

| 角色 | 能力要求 | 怎么选 |
|---|---|---|
| **主模型** | 世界知识广、判断敏锐、综合推理强 | 选你环境里**知识面/推理最强**的模型，负责题目理解、建模分析、方案判断等知识密集型工作 |
| **编程** | 代码/工程能力强 | 选**编程能力最强**的模型（可与主模型不同）；用 `workflow` 派它做子代理写代码、跑结果、出图；若它知识面较弱，只用于编码执行，不单独作知识权威 |
| **审查（≥2 个不同模型各审一遍）** | 与产出方不同厂商 / 不同能力侧重 | **至少挑两个不同模型各独立审一遍**，交叉覆盖盲区（一个偏知识/逻辑/口径，一个偏代码/复现/实现）；两份结论都要记录 |
| **识图** | 支持图像输入、成本可控 | 优先**经济型视觉模型**（高频轻量任务，成本优先），见「识图子代理」小节 |

**怎么探测**：用 `llm` 服务的 `listProviders()` / `resolveModelInfo()` 列出本环境可用模型及能力（`inputModalities` 等），再按上表挑选。某角色在环境中找不到合适模型时，如实标注受限，不要假装具备。

> **本环境已验证示例**（仅供参考，非强制）：主模型 Kimi K3（知识丰富、敏锐）· 编程 DeepSeek V4.1 Flash（编程强）· 审查 Kimi K3-256K + DeepSeek V4.1 Flash 双模型各审一遍 · 识图 Kimi K2.7 Code（`kimi-coding/kimi-for-coding`）。这只是"某环境的一种配置"，**你可以用任何满足上表能力的模型替代**。

- **⚠️ 子代理模型白名单**：本环境的子代理只能用 `subagent-model-selection.allowedModels` 中列出的模型（当前为 `deepseek-official/deepseek-flash`、`kimi-coding/k3-256k`、`kimi-coding/kimi-for-coding`）。派发子代理时若指定白名单外的模型会**失败**；请从白名单中按能力挑选，或让使用者把目标模型加入白名单。

## 编程子代理（派编程最强的模型写代码）

**为什么**：主模型（知识型）负责读题、建模、判断与验收；**编码交给编程能力最强的模型**，各展所长、互补盲区。

- **编程模型怎么选**：用 `llm` 服务的 `listProviders()` / `resolveModelInfo()` 探测，挑**代码/工程能力最强**的模型。**本环境为 `deepseek-official/deepseek-flash`（DeepSeek V4.1 Flash）**——编程强，且在子代理白名单内。
- **怎么派**：用 `workflow` 的 `agent(prompt, { provider, model })` 指定该编程模型；prompt 里写清**模型规格（引用题目分析报告）、输入数据路径、产出要求、运行环境**。
- **⚠️ 必须用 `workflow` 派发，不能用 `subagent`/`subagent_fork`**：后两个工具的入参只有 `description`/`prompt`/`run_in_background`，**不暴露 `provider`/`model`**，只能继承父模型——用它们派发就**无法指定 V4.1 Flash**，会退化成"只有一个模型"。要指定模型，一律走 `workflow` 的 `agent(prompt, { provider, model })`。
- **职责边界**：
  - **编程子代理**：写脚本、跑通、出结果表与图、按报错修 bug、给出复现命令；
  - **主模型**：负责数学正确性与口径判断、验收子代理产出、补齐/修正规格；**不把知识与建模判断外包**。
- **产出要求**：可运行脚本（`问题N_求解.py` / `.m`）、真实运行结果、`results/` 结果表、`figures/` 三类图、复现命令。
- **不豁免门禁**：P1 最小可运行、M2 稳健性攻击、P2 编程终检 **不因子代理而豁免**；子代理产出由主模型验收，不合格时带证据退回重做（走通用复验闭环）。
- **环境限制**：子代理只能用白名单内模型（见「模型分工方案」）；指定白名单外的模型会失败。

## 质量门禁（强制，顺序执行）

1. **M1 建模终检**：题目要求是否全部有对应模型/方案；子问题有无遗漏；约束与评价口径是否理解正确。
2. **P1 最小可运行结果**：全量计算前，先跑通最小可运行代码，确认能出真实结果。
3. **M2 稳健性攻击终检**：对核心模型做系统性"攻击"——质疑模型假设、换方法验证、加不确定性、样本外检验。通过后才允许全量出图和进入 P2。详见下方「M2 稳健性攻击终检」专节。
4. **P2 编程终检**：所有子问题都有真实运行结果与图表；数字有源；无未运行却声称的结果；复现清单完整。**图表强制图审**：所有正式图必须经识图子代理逐张审核为 `PASS`（有视觉模型时），审核记录写入审查记录；未走图审的正式图，P2 不通过。
5. **复现验证**：用清单中的命令能重新生成关键结果。

**通用复验闭环（适用于所有门禁与审查，强制）**：任一门禁/审查发现问题（FAIL / 不通过）后：**按证据修复 → 重新执行同一门禁/审查复审 → 仍有问题则继续"修复 → 复审"，循环直到全部问题清零、复审通过为止**。每次"问题 → 修复动作 → 复审结果"写入记录。不得把"审一次出 FAIL"当作已质检，不得修复后不经复审就直接宣称通过；超限仍不过时如实标记"多轮修复未通过"，不降级为通过。**不可用自检冒充独立通过**；若环境无独立子代理/评审方，如实标记受限并告知团队。

## M2 稳健性攻击终检（核心模型必须经受的怀疑）

**目的**：防止"模型建出来之后反复怀疑不够"。很多论文完成度很高，但经不起评委一句话："你这个模型换一种做法还成立吗？" M2 要求对每个核心模型主动攻击，形成「提出模型 → 攻击模型 → 换方法验证 → 加误差 → 样本外检验 → 写清适用边界」的闭环。

**执行步骤（对每个核心模型/每个核心结论）**：

1. **识别威胁**：列出 3-5 个"最可能被评委攻击的点"，写入交付物 `results/模型攻击清单.md`。攻击点要具体，例如：
   - 工具变量真的成立吗（相关性/排他性）？
   - 弹性/关键参数设成这个值，有没有别的可能？
   - 这个结果换一个基准窗口/样本期还成立吗？
   - 销量是不是被缺货截断过（用销量当需求会系统性低估）？
   - 单品份额/品类结构真的稳定吗（时间上会不会漂移）？
2. **换方法验证**：对每个攻击点至少换一种方法重算（如 IV vs OLS、不同弹性设定、不同基准窗口、不同损耗口径），记录结论是否稳健。
3. **加不确定性**：headline 数值给出置信区间或敏感性区间，不只报点估计；区间与点估计一并写入结果表。
4. **样本外检验**：时间序列类模型必须留出样本外（如 2022 同期）回测/验证，不得只用样本内拟合度自证。
5. **写清适用边界**：在交付物里明确"模型在什么条件下成立、什么条件下不成立"，边界不清晰的结论要标注为待验证。

**通过标准**：每个核心模型的攻击清单、换法验证、区间、样本外检验、适用边界五样齐备；攻击中发现的不稳健结论要么已修正、要么如实标注局限。M2 未过，不得进入 P2 全量出图。

**C 题真实案例（2023 国赛 C 题跑题实录）**：
- **攻击点"弹性取值"**：品类价格弹性（花叶 -0.364、辣椒 -0.647）是 2SLS 估计的，攻击时换了 OLS 与不同规格（是否含节假日哑变量）重估，结论方向一致但幅度有差异 → 在论文里给出弹性区间与口径说明，而非只报单值。
- **攻击点"缺货截断"**：销量 ≈ 需求这个假设在缺货时会低估需求 → 攻击清单里明确记录，Q3 用"需求满足率"下界约束对冲，并在论文局限中说明"用销量近似需求"。
- **攻击点"损耗口径"**：损耗按进货总量计提 vs 按过剩量计提两种口径 → 做了敏感性对比，标注两种口径下收益的差异，避免单一口径误导。
- **攻击点"份额稳定"**：单品集中度（Top50 占 84%）是否随时间漂移 → 用不同年份窗口复算集中度，确认长尾结构稳定后才作为结论写进论文。
- **攻击点"编造数值"**：论文初稿曾出现"天花板约 0.78"，评审发现该数值在攻击清单/扫描数据中不存在 → 独立审查拦截删除，改为诚实区间 (0.7,0.8)。这正说明"怀疑-攻击-核验"循环的必要性。

> 这些案例表明：M2 不是走过场，它能把"看似成立但经不起追问"的结论拦在论文之外。

## 图表质检（图审）—— 强制门禁

**所有正式图在 P2 终检前必须经过视觉审查**（是否空白、遮挡、坐标轴缺标签、是否支撑结论）。这是强制门禁，不是可选项。

**执行方式（优先第一种）**：
1. **主模型直接读图（首选）**：若当前主模型的 `inputModalities` 含 `image`（用 `llm.resolveModelInfo` 确认），直接用 `read_image` 工具**逐张读图审查**——快、少一层派发。主模型能读图时不需要再派识图子代理。
2. **识图子代理（主模型不支持图像时）**：用 `workflow` 派发一个指定视觉模型的子代理去读图，方式如下。

- **先探测可用的视觉模型（成本优先）**：不要硬编码模型名。用 `llm` 服务的 `listProviders()` / `resolveModelInfo(provider, model)` 遍历各 provider，挑出 `inputModalities` 含 `image` 的模型作为识图模型，得到 `{ provider, model }`。**优先选择经济型视觉模型**（识图是高频轻量任务，不需要强推理），避免用最贵的旗舰。本环境已验证可用：`deepseek-official/deepseek-flash`（DeepSeek V4.1 Flash，官方便是"快·高效·经济"定位，已配置 image 能力）与 `kimi-coding/kimi-for-coding`（Kimi K2.7 Code）。
- **⚠️ 模型必须声明图像能力**：`inputModalities` 在配置里**默认是 `["text"]`**；若某模型实际支持读图却被拒（`read_image` 报 "does not declare image input"），检查 `settings.yaml` 中该模型是否声明了 `image`。
- 用 `workflow` 工具派发一个子代理，在 `agent(prompt, { provider: <探测到的provider>, model: <探测到的视觉model> })` 里指定该视觉模型。
- 在 prompt 里告诉子代理用 `read_image` 工具读取目标图片路径，并要求它输出结构化审查（标题/坐标轴/图例/数据线条/空白或遮挡/是否达标）。
- 例子（`provider`/`model` 用探测结果替换）：
  `agent('用 read_image 读取 <图片路径>，审查图表：标题、坐标轴刻度/标签、图例、线条、是否有空白或遮挡，给出可改进项。', { provider: 'kimi-coding', model: 'kimi-for-coding' })`
- **逐张审核**：每一幅正式图都要单独过一遍审核（可一次派发多张，但每张都要有结论）。
- 若探测不到任何 `image` 模型，则如实标记"此环境无视觉模型，视觉质检受限，未走图审的正式图需真人终审"，不要假装通过。
- 视觉审查结果作为 P2 编程终检的**强制证据**：全部正式图审核有记录且最终 PASS。
- **复验闭环（强制）**：图像审核 `FAIL` 后，必须按缺陷回到画图端修改，然后**重新派发识图子代理对修改后的图复审**，循环直至 `PASS`；每次"FAIL 原因 → 修改动作 → 重审结果"写入审查记录，不得把"审一次出 FAIL"当作已质检。超限仍 FAIL 时如实标记"多次修改未通过审检"，不降级为通过。（完整规则见全局 skill `vision-subagent` 的「复验闭环」小节。）

## 独立模型审查（多个不同模型各审一遍，对抗式评审）

为跳出主模型自身的盲区，交付物的**独立评审/质检由多个不同模型各独立审一遍**——用不同厂商、不同能力侧重的模型交叉覆盖彼此盲区。主模型容易对自己产出的内容失去批判距离，换模型才能暴露它忽略的缺陷（如编造数值、口径不自洽、图表与结论脱节、代码不可复现）。

- **至少两个不同模型各审一遍（强制）**：挑两个与产出方不同、能力侧重不同的模型，例如：
  - 模型 A（偏**知识、逻辑、口径、结论合理性**与常识判断）：审结论是否站得住、有无知识性错误；
  - 模型 B（偏**代码、复现、实现正确性与数值可追溯**）：审代码可运行、结果可复现、数字可溯源。
- 用 `workflow` 派发**多次**审查子代理，分别在 `agent(prompt, { provider, model })` 里指定不同模型；**每份结论都要记录**（各自 PASS/FAIL 与问题清单）。
- **⚠️ 必须用 `workflow` 派发，不能用 `subagent`/`subagent_fork`**：后两个工具的入参只有 `description`/`prompt`/`run_in_background`，**不暴露 `provider`/`model`**，只能继承父模型——用它们派发就**无法指定其他模型**，会退化成"只有一个模型"。要指定模型，一律走 `workflow` 的 `agent(prompt, { provider, model })`。
- **模型名不硬编码**：用 `llm` 服务的 `listProviders()` / `resolveModelInfo()` 探测本环境可用模型，按能力侧重挑两个。**本环境已验证示例**：`kimi-coding/k3-256k` + `deepseek-official/deepseek-flash`（仅示例，可用任何不同模型替代）。
- **审查 prompt 要求**（结构化，每次都查）：
  - 事实性：结论是否有真实结果/表/图支撑？有无编造的数值或来源？
  - 一致性：口径/符号/结论在报告、代码、结果、图之间是否自洽？
  - 完备性：是否覆盖全部子问题？有无遗漏的约束或维度？
  - 独立判断：基于以上给出 `通过 / 不通过`，不通过时列出必须修复的证据项。
- 例子（`provider`/`model` 用探测结果替换）：
  `agent('你是独立审查员，审查 member-a 的交付物（题目分析报告、代码、results、figures）……', { provider: '<模型A provider>', model: '<模型A>' })`
  `agent('同上，重点审查代码与复现正确性……', { provider: '<模型B provider>', model: '<模型B>' })`
- **多模型结论合并**：任一方发现的问题都视为待修复项；修复后**必须重新派发该模型复审**（通用复验闭环），循环直至所有审查模型的结论都无遗留问题。环境只提供一个可用模型时，如实标注"单模型审查，覆盖受限"。
- 审查结果作为 M1/P2 门禁的证据；不得由主模型口头覆盖审查 FAIL。

## 与其他岗的交接

- 你的产物就是论文岗的证据来源：`题目分析报告.md`、`术语表格.md`、`results/`、`figures/`。
- 提交前确认上述文件齐全、位次正确，再 push。
- 评审反馈（论文岗或其他方）若要求补数据/图/复现，回到对应阶段补齐后重新 push。

## 渐进式加载

本 skill 自带一套方法论文档（在预设的 `skills/math-model-code/references/` 下，随预设安装，按需读取，不要一次全读）：

| 当前任务 | 加载参考（相对本 skill 的 references/） |
|---|---|
| 建模流程 / 术语合同 / 常见模式 | `roles-建模手/SKILL.md`、`roles-建模手/前置合同.md`、`roles-建模手/工作流程.md`、`roles-建模手/常见模式.md`、`roles-建模手/建模设计理论.md` |
| 建模质量检查 | `roles-建模手/质检清单.md` |
| 选模型 / 查算法 | `算法索引.md`，再按问题类型读 `assets/0N-*.md`（优化/预测/评价/图论/统计/综合/机器学习） |
| 编程工作流程 / 复现 | `roles-编程手/SKILL.md`、`roles-编程手/工作流程.md`、`roles-编程手/质检清单.md` |
| MATLAB 实现 | `roles-编程手/MATLAB规范.md` |
| 画图 / 出版级可视化 | `可视化规范/SKILL.md` 及 `可视化规范/chart-types/`、`design/`、`quality/` 下文档 |
| 读题目/附件 PDF（双通道） | `scripts/read_pdf.py` + 本文件「阶段一 · 读题与盘点」 |
| 竞赛截止时间 / 可提交性优先 | `交付与截止时间协议.md` |
| Gitee 提交 | 本文件「团队协同模型」小节 |

> **路径说明**：`scripts/*` 相对本 skill 根目录，其余相对 `references/`。

> 说明：这些文档移自 `math-modeling-skill` 参考仓库（脚本与工具源码未搬入，仅方法论文档）。需要脚本/工具实现时按文档中的思路自行实现，或团队后续单独补充。

## 完成判定

- 阶段一/二的固定交付物齐全且写入你的 `member-*` 文件夹。
- 通过 **M1、P1、M2、P2** 全部门禁（含 **图表强制图审 PASS**、**≥2 个不同模型的独立审查通过**）并完成复现验证。
- 已 push 到 Gitee，且未改动他人文件夹。
- 若独立评审/图审未执行（无评审方/子代理/视觉模型），如实标注"独立验收未完成"，不宣称完整完成。