Ez Math Model

ez-math-model

数学建模一站式 skill。把题目交给我，我会自动走完七个阶段：setup → 题目解析 → 建模方案 → 代码求解 → 论文撰写 → 质量审查 → 标准打包交付。首次使用必须完成 setup 提问；完成后写入 external/tools/setup_state.json。未经用户确认，只能使用本次临时默认， 不得写永久配置。

一句话主流程

> 收到题目 → 识别项目总文件夹 → 检查 external/tools/setup_state.json → > 创建 用户输入/runtime/output 标准目录 → 判定 formal/demo/blocked → > 识别赛事/年份/题号 → 选择模型 → 写脚本并执行 → 出图并过 chart gate → > 写论文 → 跑对象级质量门 → staging 导出与审查 → 原子同步到 output/ 并打包 > output.zip。

触发后的第一动作

先读以下七份文件确认本次运行的契约：

1. pipeline/00-environment-setup.md — 验环境（Python、字体、工作目录、上游缓存状态）
2. references/project-root-protocol.md — 项目总文件夹与 用户输入/runtime/output
3. references/setup-policy.md — setup 硬门与临时默认边界
4. references/run-mode-protocol.md — formal/demo/blocked 判定
5. references/workdir-protocol.md — runtime 产物结构与命名
6. references/chart-quality-gate.md — 图表有效性门
7. references/artifact-manifest.md — 产物 manifest 契约

formal 交付不得只检查“文件是否存在”。质量门必须覆盖图表语义、公式语法、 表格对象、优秀论文格式抽取、正文工程痕迹、DOCX/PDF 对象级导出和 zip/manifest 一致性。

然后立刻执行 setup gate：

• 读取 external/tools/setup_state.json。
• 若文件不存在、JSON 无法解析、setup_completed 不是 true，或用户说"重新配置工具 /

重置 setup / 重新 setup"，必须先运行 pipeline 00 的强制提问，禁止进入 pipeline 01、建模、写代码或写论文。

• setup 提问完成后，必须写入 external/tools/setup_state.json，再继续本次任务。
• 若 setup_completed: true，默认跳过交互式 setup，只做本次任务所需的轻量环境检查

和工作目录创建。

不要用"默认不追问"绕过首次 setup；首次 setup 是硬门禁。若用户要求继续但无法 完成交互式 setup，只能写 runtime/{task_id}/setup_assumptions.json，并把 setup_status 标为 temporary_default，最终质量等级最高为 provisional_pass。

Pipeline 索引

| # | 文件 | 入口条件 | 关键产出 | |---|---|---|---| | 00 | pipeline/00-environment-setup.md | 用户给出题目或附件；setup gate 未完成时必须先问 | setup 状态明确、runtime/ 创建完成、env-check 通过 | | 01 | pipeline/01-problem-intake.md | env-check 通过 | runtime/.../problem.md、intake.json、attachments/、run_state.json | | 02 | pipeline/02-modeling-plan.md | intake 完成 | modeling_plan.md、（首次询问 zhanwen 拉取） | | 03 | pipeline/03-coding-solve.md | modeling_plan 落盘 | src/*.py、results/*、figures/*.png | | 04 | pipeline/04-paper-writing.md | coding 完成 | paper.md | | 05 | pipeline/05-quality-audit.md | paper.md 落盘 | quality_report.json、quality_report.md（含证据与未通过项） | | 06 | pipeline/06-packaging-output.md | 质量门评估完成 | export_report.json、export_audit.json、output/paper/* 四格式、output/manifest.json、output.zip |

角色 prompt 索引

需要在阶段中扮演具体角色时载入：

| 角色 | 文件 | 用途 | |---|---|---| | coordinator | prompts/coordinator.md | 拆题，识别赛事/年份/题号/小问 | | modeler | prompts/modeler.md | 建模分析，模型选择树 + 物理可行性 | | coder | prompts/coder.md | 写脚本、出图、防数据泄露、参数有据 | | writer | prompts/writer.md | 写论文，段落式、图必引、文献唯一编号 |

角色守则索引

执行阶段开始前必读对应角色守则（比 prompt 更关注流程纪律）：

• references/roles/modeler-guide.md
• references/roles/coder-guide.md
• references/roles/writer-guide.md

模板索引

• templates/paper_zh.md — 中文 CUMCM 论文 markdown 兜底模板
• templates/paper_en.md — 英文 MCM/ICM 论文 markdown 兜底模板
• templates/chapter_outline.toml — 章节占比与必备小节
• templates/readme_workdir.md — 任务工作目录的 README 模板

算法库索引

references/algorithms/README.md 提供「问题类型 → 推荐算法」速查表；按类别细看：

01 优化 / 02 预测 / 03 评价 / 04 图论 / 05 统计 / 06 综合 / 07 机器学习。

优秀论文样例

references/exemplar-papers/ 下提供 7 篇 CUMCM / MCM 优秀论文的 markdown 摘录（由 MinerU 从 zhanwen/MathModel 转换，前 20 页）。modeler 与 writer 在动笔前应读取与本题最相关的 1-2 篇，抽取格式规则并写 style_reference_notes.md，仅作风格 / 章节 / 表述参考，禁止照抄或同义改写。 索引详见 references/exemplar-papers/README.md。

容错与失败处理

references/fault-tolerance.md 是单一信息源，定义 4 层容错： L1 Bounded Retry / L2 Fallback Switch / L3 Evaluator Shadow / L4 Feedback Rerun。每个 pipeline 阶段都遵守同一套容错协议，绝不死循环。

Agent 工作模式

references/agent-mode.md 单一信息源，定义三种工作模式：

• single：所有阶段在主对话顺序推进；上下文压力大但失败定位最容易
• multi：每个独立子任务派 subagent 并行；并发强但 token 成本高
• hybrid（默认）：关键阶段主对话、琐碎阶段 subagent；兼顾稳定与并发

pipeline 00 首次会强制询问，决策落到 external/tools/setup_state.json 与 external/tools/agent_mode.{single,multi,hybrid}。

继承的辅助 Skills

ezmm 内置 9 个辅助子 skills（在用户机器上检测到才启用）：

| 子 skill | 何时调 | |---|---| | tools/humanizer/SKILL.md | writer 后去 AI 味 | | tools/simplify/SKILL.md | coder 后做代码精简 | | tools/scientific-slides/SKILL.md | 答辩 PPT | | tools/systematic-debugging/SKILL.md | coder 失败的根因分析 | | tools/brainstorming/SKILL.md | modeler 决策卡住时 | | tools/external-context/SKILL.md | multi/hybrid 模式下并行多领域查文献 | | tools/dispatching-parallel-agents/SKILL.md | multi/hybrid 派单方法论 | | tools/subagent-driven-development/SKILL.md | 扩展 ezmm 本身（非建模题） | | tools/verification-before-completion/SKILL.md | quality_audit 强化 |

宿主未安装对应 skill 时，子 skill 文档给出降级方案。详见 references/external-tools-catalog.md 与各子 skill 文件。

共享 Prompt 协议

prompts/shared.md 是所有角色 prompt 隐含加载的通用约束（输出语言 / JSON 格式 / 工具调用 / 反思 / 失败重试 / 段落式 / 引用编号 等），角色 prompt 不 重复列举。

子工具 Skills

ez-math-model 不内嵌 docx/pdf/xlsx/paper-search 实现，而是通过子 skill 协议 调用宿主已安装的同名 skill 或公共 API：

| 域 | 文件 | 何时用 | |---|---|---| | Word 转换 | tools/docx/SKILL.md | paper.md → paper.docx | | PDF 提取（基础） | tools/pdf/SKILL.md | 题目 / 论文 PDF 转文本 | | PDF 高质量解析 | tools/mineru/SKILL.md | 含表格 / 公式的中文学术 PDF | | 表格附件 | tools/xlsx/SKILL.md | csv / xlsx 读写 | | 文献检索（基础） | tools/paper_search/SKILL.md | OpenAlex 单源 | | 多源学术搜索 | tools/scholar/SKILL.md | OpenAlex + arXiv + S2 + SerpAPI 聚合 | | 论文写作编排 | tools/paper-orchestra/SKILL.md | writer 阶段调用 PaperOrchestra 子 skill 做大纲、文献、成文与精修 | | 数据集发现 | tools/dataset/SKILL.md | Kaggle / UCI / HuggingFace / 天池 | | 网页抓取 | tools/webcrawl/SKILL.md | Jina / Firecrawl / Tavily / Exa | | 用户自带 corpus | tools/user-corpus-explorer/SKILL.md | 扫 external/user-corpus/，产出 AGENTS.md |

外部工具的元信息（价格 / 配额 / 何时启用）单一信息源在 references/external-tools-catalog.md。

外部工具配置

启用付费 / 注册类工具前，pipeline 00 会在首次使用时强制问一次，按 7 个域 分组询问，每组给固定选项。决策落到 external/tools/setup_state.json，永久缓存； 后续默认不再进入交互式 setup。详见 pipeline/00-environment-setup.md。

env var 一律以 EZMM_ 开头，写入用户级 ~/.ezmm.env（参考仓库根 .env.example），绝不提交到 git。

7 个域：pdf / scholar / dataset / webcrawl / corpus / agent_mode / inherited_skills。

用户自带参考资料

仓库内 external/user-corpus/ 是给你专门的投放区。把想让 ez-math-model 参考的论文、教材、笔记、历年题解直接拖进去（不限格式 / 层级 / 文件名）， 启用后 pipeline 01 末尾派 subagent 扫描，产出 AGENTS.md 给 modeler / writer 用。详见 tools/user-corpus-explorer/SKILL.md 与 external/user-corpus/README.md。

zhanwen/MathModel 集成

scripts/install/fetch_zhanwen.ps1 / .sh 负责按需拉取上游优秀论文与模板。 匹配协议见 scripts/runtime/match_thesis.py：(赛事, 年份, 题号) → 同年份 → 同赛事最新年份 → 全局最新 → 内置 markdown 兜底，五级回落，命中即返回。

询问只发生一次，发生在 pipeline 02 入口。.skip 标记存在时永久跳过询问。 .failed 标记存在时直接走内置兜底，不再重试拉取。

失败兜底矩阵

| 失败点 | 处理 | |---|---| | Python 不可用 | 打断，提示用户安装 Python ≥ 3.10 | | 题目无法解析（intake 阶段） | 打断，把已读到的内容存入 problem.md 并请求人确认 | | zhanwen 拉取失败 | 写 .failed，pipeline 切到内置模板兜底，不打断 | | 单段代码执行失败 | coder 自动重试至多 2 轮（参考 pipeline/03-coding-solve.md），仍失败则记入 diagnostics.md 并继续 | | 单张图生成失败 | 该绘图尝试写入 chart manifest 的 rejected 记录，论文中跳过，写 quality_report.md 标记缺图，不打断 | | 论文章节缺失 | 质量门记入 quality_report.md；formal 模式阻塞正式打包，demo 可降级打包 | | docx 公式/图片/表格对象审查失败 | formal 模式阻塞正式发布；demo 模式降级并写 diagnostics.md |

运行模式与交付结构

每次运行都必须显式记录 run_mode：

• formal：真实输入齐全，可写正式结论。
• demo：用户允许用合成/示例数据验证流程，不得写正式结果。
• blocked：缺关键输入且未授权 demo，停止并输出诊断。

最终交付必须同步到：

output/
├── source code/
├── paper/
│   ├── paper.md
│   ├── paper.docx
│   ├── paper.txt
│   └── paper.pdf
└── 附件文件夹/

每次运行仍新建 runtime/{YYYYMMDD-HHMMSS}-{8位hash}/，所有中间产物落在其中， 便于失败定位和重试。详见 references/project-root-protocol.md 与 references/workdir-protocol.md。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: woodfishhhh
• Source: woodfishhhh/EZmath_model
• License: MIT

Install and usage instructions live in the source repository linked above.