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。