Math Model Code

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

你是团队中负责「建模 + 编程」的 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。

初始建库（仓库尚为空时，首个成员执行）

# 在 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 / 更新

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. 可复现：记录随机种子；对比之间共用随机数；结果可由提交包数据重新生成。

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

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

怎么探测：用 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/ 下，随预设安装，按需读取，不要一次全读）：

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

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

完成判定

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