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，停止并输出诊断。 最终交付必须同步到： ```text 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`。