woodfishhhh 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。
触发后的第一动作
先读以下七份文件确认本次运行的契约：
pipeline/00-environment-setup.md— 验环境（Python、字体、工作目录、上游缓存状态）references/project-root-protocol.md— 项目总文件夹与用户输入/runtime/outputreferences/setup-policy.md— setup 硬门与临时默认边界references/run-mode-protocol.md—formal/demo/blocked判定references/workdir-protocol.md— runtime 产物结构与命名references/chart-quality-gate.md— 图表有效性门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.mdreferences/roles/coder-guide.mdreferences/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。