XiaoMaColtAI/math-modeling-skill

**面向数学建模竞赛与建模项目的三阶段工作流**
**关注我**
---
📖 简介
本 Skill 将数学建模任务拆分为 **建模分析 → 代码实现 → 论文撰写** 三个阶段。既可以按顺序完成整道题，也可以只执行其中一个阶段。
当前版本：1.3.0
> 生成的论文仅供参考。论文结构与格式必须以目标竞赛当届官方规则和官方模板为准。
✨ 核心能力
- 🧠 **建模分析**：读题、检查附件、拆分子问题、选择模型、设计求解与验证方案。
- 💻 **双语言实现**：支持 Python 和 MATLAB，按选中的模型与功能动态检查依赖。
- 📊 **完整结果输出**：生成结果表格、原始数据图、模型运行过程图和最终结果图，以及必须的总体建模流程图。
- 🎨 **出版级科学可视化**：先剖析数据和论证目标再选图，提供 Python/MATLAB 统一样式、色觉友好编码、SVG + 300 DPI PNG 导出与成图自检闭环。
- 🔁 **可复现运行**：记录随机种子、输入文件 SHA-256、运行时与依赖版本、关键参数和唯一复现命令。
- 🔎 **双引擎论文搜索**：并行调用 OpenAlex 与 AnySearch，按 DOI 或题名交叉核验。
- 📄 **Word / LaTeX 论文生成**：支持官方模板、嵌套主入口、整篇 LaTeX→DOCX、Word 原生 OMML 公式、真实 PDF 编译、权威资源—源码—产物哈希绑定和完整质量门禁。默认只生成 Word 论文，LaTeX 可选。
- 🧾 **论文组件规范**：使用“符号、含义、单位”三列符号说明表和标准数学排版，按当届规则组织附录。
- 🛡️ **阶段内独立质检**：默认只在建模终检、最小可运行结果、编程终检、论文证据大纲和论文终检节点派发只读 Subagent，发现问题立即返工复验。
- 🤝 **可选 Subagent 协作**：用户可按需启用规则核验、附件盘点、文献与模型调研、算法原型、独立实验、双语言对照或术语核验；默认全部关闭。
- 🧩 **渐进式加载**：只读取当前阶段需要的角色规范、算法资料和工具说明。
🔄 三阶段工作流
| 阶段 | 角色 | 核心任务 | 独立门禁 | 固定交付物 |
|:---:|---|---|---|---|
| ① | 建模手 | 理解题目、设计模型、定义算法和验证方案 | M1 建模终检 | 题目分析报告.md、术语表格.md |
| ② | 编程手 | 编写并运行 Python/MATLAB，生成结果与图 | P1 最小可运行结果、P2 编程终检 | 代码、结果表格、三类各至少 3 张且覆盖全部子问题的候选图、至少 1 幅总体建模流程图、results/复现清单.json |
| ③ | 论文手 | 基于真实结果构建论证并生成 Word 论文 | W1 证据大纲、W2 论文终检 | 至少 8 幅且覆盖全部子问题的正式图；默认交付 完整论文.docx；用户显式要求时同时交付 LaTeX 源码项目、PDF 与哈希清单 |
质检 Subagent 是阶段内只读验收者，不是第四个固定角色。默认只启用固定质检；其他协作仅在用户明确选择后运行。P1 在全量计算和正式出图前执行，W1 在长篇正文和双格式排版前执行；禁止等全流程结束后才首次质检。完整协议见 Subagent 调度与阶段门禁。
阶段反馈
- 编程手发现公式、约束或参数无法实现时，携带实际报错返回建模手修正。
- 论文手发现关键结论缺少真实结果、图表或文献支撑时，返回对应阶段补齐。
- 任一独立门禁返回 FAIL 时，由原阶段执行者按证据修正并重新派发复验；主 Agent 不得自行覆盖失败结论。
- 修正后从被阻断阶段继续，不重复已经通过的阶段。
🚀 快速开始
推荐 Agent
本 Skill 可用于支持本地 Skills 或 Agent 工作流的工具，例如 Claude Code、Codex、Cursor、Trae 和 Qoder。具体加载方式以对应工具的当前文档为准。
DeepSeek Harness 插件
本仓库同时提供 DeepSeek Harness（dsh）的 **Agent 预设**：dsh-plugin/math-modeling-agent/，把三阶段工作流、五门禁质检、任务看板与完成判定封装为 mm_* 工具，供 dsh 桌面端使用。
**安装**：把整个 dsh-plugin/math-modeling-agent/ 目录复制到本机 dsh 预设根目录（ \.agent-presets\，Windows 默认 C:\Users\ \AppData\Roaming\dsh-desktop\dsh-home\.agent-presets），目录名即预设 id（如 math-modeling）。也可直接复制 dsh-plugin/README.md 中附带的安装提示词给 dsh Agent 自动完成安装。
**使用**：新建 dsh 会话 → 选择预设「数学建模 Workbench」，即可使用 mm_project_init / mm_phase_enter / mm_todo / mm_gate / mm_check_deliverables / mm_complete / mm_state 等工具，并通过 skill 工具加载内置 math-modeling 知识库。
> 插件为**自包含**设计：知识库随预设持久化，不依赖外部仓库路径，可整体复制到任意机器使用。
安装
Git 克隆
克隆后，将仓库放入所用 Agent 的 Skills 目录或按其方式加载本目录。
npx 安装
也可以下载仓库 ZIP，解压后放入对应 Skills 目录。
使用示例
完整流程：
单阶段执行：
主入口见 SKILL.md。
📁 工作目录约定
- SKILL_ROOT：本仓库根目录，只读；角色规范、算法资料、脚本和模板从这里读取。
- PROJECT_ROOT：用户题目所在目录；所有运行产物只写入这里。
- 题目与附件保持只读；需要修改模板时，先复制到 PROJECT_ROOT。
典型产物结构：
🛠️ 集成工具
| 工具 | 用途 |
|---|---|
| 科研可视化 | 数据剖析、选图决策、Nature/SCI 出版级绘制、建模流程图、自检闭环、多格式导出 |
| 双引擎论文搜索 | OpenAlex + AnySearch 搜索、融合和交叉核验 |
| DOCX 工具 | 官方模板、递归 LaTeX→DOCX、警告发布门禁、OMML 公式、三线表、修订、批注和校验 |
| LaTeX 工具 | 环境诊断、官方模板溯源、真实编译、哈希绑定、引用与 PDF 质量校验 |
| Excel 工具 | XLSX 模板处理、公式重算和错误检查 |
| PDF 工具 | 读取题目 PDF，提取文本、表格和图片 |
双引擎论文搜索
- OpenAlex 可通过 --email 提供礼貌池邮箱。
- AnySearch 需要密钥时设置环境变量 ANYSEARCH_API_KEY。
- 正式检索默认同时运行两个引擎；单引擎参数只用于诊断。
动态依赖检查