math-modeling

name	math-modeling
description	当用户要求数学建模、建模竞赛、建模分析、代码求解、红队评审、结果可视化、论文生成、竞赛规则核验、案例复盘、错题本或建模资料预处理时使用。支持模型设计→程序实现→独立评审→论文发布四阶段、单阶段任务，以及可用时对数学建模私有知识库的统一检索和原图核验。

数学建模

本 Skill 用四个职责隔离的阶段完成数学建模，其中评审阶段在真实计算完成后、论文定稿前执行红队门禁。阶段可以由同一代理顺序执行，也可以由不同代理执行；无论执行者是谁，评审都必须重新建立主张—证据关系，不能沿用上游的确定性措辞。生成的论文仅供用户参考。论文结构与格式必须以目标竞赛当届官方规则和官方模板为准，不能用往届经验替代官方要求。

根目录契约

• SKILL_ROOT：本文件所在目录，只读。角色说明、算法资料、脚本和模板都从这里读取。
• PROJECT_ROOT：用户题目和项目所在目录，所有新产物只能写入这里。
• 两个根目录必须不同；默认禁止覆盖 SKILL_ROOT 内任何文件。
• 输入附件只读。确需修改模板时，先复制到 PROJECT_ROOT 再处理。
• 不自动添加、删除或推断 AI 使用披露，也不把模型或厂商名写入默认作者、批注者、修订者或文档元数据。是否披露及披露内容由用户依据目标竞赛当届官方规则决定；规则强制要求时必须遵守，并把人工决定和规则依据留在项目发布记录中。

用户追加硬限制

• 完整建模、论文生成或论文修改开始前，必须完整读取 references/用户追加硬限制.md，筛选适用于当前任务的有效条目。
• 把适用条目逐项写入项目发布清单：官方规则进入 official_rules.hard_constraints，用户质量硬限制进入 quality_target 并设置 blocking=true。只在对话中记住、不进入门禁，不算落实。
• 后续用户新增、修改或撤销限制时，更新同一文件中的独立条目，保留范围、优先级、验证方式、依据和状态；不得用新要求悄悄覆盖旧要求。
• 官方规则与用户限制冲突时执行更严格且合法的一项，并在交付说明中指出冲突；不得以篇幅目标为由突破官方上限或采用灌水排版。

路由

用户意图	加载入口	是否要求前一阶段已完成
完整建模、完成整题	references/roles/model-designer/SKILL.md → references/roles/model-programmer/SKILL.md → references/roles/model-reviewer/SKILL.md → references/roles/paper-writer/SKILL.md	按顺序执行
只做题目分析、选模型	references/roles/model-designer/SKILL.md	否
只写代码、跑结果、出图	references/roles/model-programmer/SKILL.md	需要题目和可执行的模型说明；缺失时先补齐必要分析
只做复核、审稿或检查现有方案	references/roles/model-reviewer/SKILL.md	需要题目、模型、代码或结果证据；缺失项标为待验证
只写或修改论文	references/roles/model-reviewer/SKILL.md → references/roles/paper-writer/SKILL.md	需要题目、模型、真实运行结果和图表；重大审计失败时回退

不要在单阶段任务中强制执行完整流程。

私有知识库检索

• 需要选模型、查算法、核验竞赛规则、参考优秀案例、补充领域知识、查实现细节或寻找相关图表时，优先调用 search_math_modeling_knowledge，再结合题目附件和当前任务作独立判断。默认用 knowledge_scope="core" 只检索算法、编程、规则、领域和写作主体文本库。
• 查询应明确、独立且不超过 250 字。核心层和经验层先只查文字，不自动检索多模态库。当确实需要原图、图表结构或版面证据时，再用 knowledge_scope="multimodal"、include_images=true 定向查图；先用默认 max_images=4，不足时最多增至 8。
• 完整建模先按子问题、模型、算法、验证和实现分层检索核心文本层，再用 knowledge_scope="experience" 单独检索优秀案例、错题本和实践复盘文本层。经验层查询要明确写出“这是新的当前题，只返回可迁移思路、风险提示和验证方法，不把旧题答案作为当前答案”。只有用户要求全部文本库审计或跨库总览时才使用 knowledge_scope="all"；该范围也不包含多模态库。
• 经验库的使用原则是“借鉴但不接管”：既不机械沿用旧方案，也不因旧题不同而完全忽略。对每个命中建立“历史经验—当前题相同点—当前题差异—拟作调整—采用与否—独立验证”记录；只有适用条件匹配且能在当前题重新推导、独立实现、真实验证的部分才进入方案。
• 练习任务开始时，用 knowledge_scope="experience" 按“新题题型＋当前阶段＋风险”检索 数学建模-错题本。后续阶段优先复用已记录的命中；只有出现新风险、新模型、新数据特征、审计失败或原命中覆盖不足时才增量检索。命中只作为防错提示，不能把旧错误场景误认为当前题已经发生，也不能机械套用旧修正。
• 需要借鉴完整建模过程时，用 knowledge_scope="experience" 检索 数学建模-实践复盘库，优先召回“候选模型—取舍理由—实现架构—验证链—适用边界”。命中描述的是历史题的决策记录，不是模型正在处理的当前题；实际比赛可前置用于启发，同题独立练习仍在主方案锁定后再作对照。
• 多模态库同时包含核心资料与经验资料的视觉内容，不能用于替代文本分层。先从 core 或 experience 命中中确定来源文档、图号、图表主题或所需视觉证据，再以这些限定词调用 knowledge_scope="multimodal"。必须实际查看返回的图片内容块，不能只根据文件名、图片说明或相对路径推断图片含义。
• 在回答和交付物中保留知识库名与来源文档名。过滤低相关命中；私有案例不能替代题目原文、当届官方规则、原始数据或可追溯文献。
• math_modeling_knowledge_status 只用于首次接入检查、故障诊断或用户明确要求查看状态，不要在每个普通任务中重复调用。
• MCP 不可用或检索失败时，继续使用题目附件与本 Skill 的本地资料完成可完成部分，并明确说明降级；禁止伪造知识库结果或图片。
• 仅做用户已提供文件的机械转换、排版或代码修改，且不需要领域知识时，不必强制检索。

详细的九库职责、工具参数、返回结构与冲突处理见 references/知识库与MCP.md。

固定交付物

建模手

只交付：

1. 题目分析报告.md
2. 术语表格.md

编程手

交付：

1. 用户或竞赛允许环境中的可运行代码；本 Skill 对 Python（.py）与 MATLAB（.m）提供内置检查。只有独立交叉验证有价值或用户明确要求时才同时实现多种语言。
2. 代码运行结果表格，如 .csv、题目要求的 .xlsx。
3. 支撑结论所需的原始数据图、模型过程/诊断图和最终结果图。候选图数量由证据需求决定，不为凑数量生成重复图。
4. results/复现清单.json，含项目相对输入路径及 SHA-256、随机种子、运行时和依赖版本、关键参数、唯一复现命令。
5. results/result_registry.json，以稳定键登记论文重复使用的结果、单位、小数位数、项目内来源文件和生成命令。

评审手

在完整流程中验证两个内部产物，不作为额外最终交付物：

1. results/result_registry.json：由编程阶段生成，评审阶段校验其结构、来源和跨表一致性。
2. results/red_team_audit.json：由评审阶段生成，记录适用检查、主张证据、反证条件、失败严重度和回退阶段。

运行 references/roles/model-reviewer/scripts/red_team_gate.py。存在重大失败、待验证的关键主张或无证据的“全局最优”表述时，禁止进入论文手。

用户单独要求复核、审稿或依据评审意见修改时，额外交付 PROJECT_ROOT/评审报告.md，按“主张—证据—反例/推翻条件—严重度—修复建议—回退阶段”组织；缺少代码或证据的结论标为待验证，不伪造门禁通过。只有用户要求修改现有 Word 时，才在不覆盖原稿的前提下生成 PROJECT_ROOT/论文修订稿.docx，并按用户选择保留修订或批注；仅要求报告时不强制生成 Word。

论文手

交付一份完整的可编辑 .docx 论文；目标竞赛当届规则要求 PDF 时，同时交付由同一候选稿渲染并经门禁锁定的最终 PDF。内部检查记录不作为额外交付物，也不得把候选稿误作最终稿。

论文必须采用失败即停止的两阶段发布：先生成 论文候选稿.docx，用与最终阅卷环境兼容的办公软件实际渲染为 PDF，再运行 tools/docx/scripts/paper_release_gate.py。官方模板依赖 Word 专有布局时优先用 Word；使用其他渲染器时必须记录并抽检差异。只有门禁返回 status=pass 时才能生成 完整论文.docx。禁止在渲染前直接保存最终文件，也不得由代理自行降低官方硬约束或掩盖摘要语义、规则来源和模板来源问题。

页面大小、方向、栏数和附录版式首先服从目标竞赛当届官方模板。无明确要求时，采用与内容和阅读媒介相符的稳定可读版式；不得仅为压缩页数擅自把附录改成横版、双栏或过小字号。附录页数不限时，优先保证完整源码的正常可读性。

篇幅只设置两类约束：当届官方硬约束，以及用户明确要求或根据题目论证需求预先声明的质量区间。没有依据时不设固定最低字数、恰好页数或公式/图/表数量。不得靠重复文字、放大图表、增加空白或让一级标题强制另起一页来凑篇幅。

论文图形不限于求解程序直接输出的数值图。可使用 MATLAB、Python、矢量绘图或流程图工具生成算法流程图、模型结构图、几何解释图、变量关系图和验证逻辑图，以解释方法并丰富正文；数值结果图必须来自真实运行数据，解释图必须与最终模型和代码一致，不得伪造结果、误导比例或用装饰图替代证据。

练习复盘

仅在练习、模拟赛或用户要求复盘时追加生成：

1. 复盘报告.md：记录本题表现、证据、根因、修正过程和仍待观察事项。
2. 错题入库条目.md：每条只写一个可迁移问题，包含分类、触发场景、错误表现、证据、根本原因、正确做法、验证方式、复用标签和状态。
3. 实践复盘入库稿.md：从完整复盘和案例对比中提炼可审计的推理摘要、决策轨迹、模型取舍、实现架构、验证链、可迁移经验与不适用边界。

只有完成修正并通过重新运行、扰动检查、渲染检查或规则核验的条目才标为“已验证”，并具备进入 数学建模-错题本 的资格。Skill 默认只生成本地条目；实际上传须由用户明确决定。未经验证的判断保留为“待验证”，不得入正式检索库；规则变化或结论失效时标为“已失效”。合并重复条目，避免把任务特有的小失误和相互矛盾的经验污染错题本。

实践复盘入库稿.md 只在项目目录生成，不自动上传；是否上传由用户决定。原始 复盘报告.md、原始 优秀案例对比报告.md、过程日志和未经筛选的模型猜想不作为默认入库文件。入库稿允许保留本题数值作为验证证据，但必须把可迁移经验与题目特有结论分区，注明来源产物、验证方式、建模模式和失效条件，防止历史输出被当作外部真值或当前题答案。

实践复盘中的“思维过程”写成可审计推理摘要，而不是隐藏的逐字内部思维链。按“观察到的题目事实或运行证据—候选方案—比较标准—采用/拒绝决定—验证结果—何时推翻”的顺序记录，使后续模型能够复现决策依据，又不把未经证实的联想、冗长自言自语或私有内部推理写入知识库。

阶段反馈闭环

• 编程手发现公式不完整、约束冲突或模型不可实现时，停止猜测，在对话中列出证据并回到建模手修正两个 Markdown 交付物。
• 评审手独立检查数据完整性与泄漏、目标—指标对齐、几何/统计判据、参数语义与约束、全域行为、约束重拟合、跨模型冲突、验证与不确定性、实现 oracle、极端反例、集合计量、资源删除边际、离散指派、多随机种子、网格收敛和跨表一致性。重大失败按 reopen_stage 回到建模手或编程手；修正后只重跑受影响链路。
• 论文手发现关键结论没有真实结果、图表或文献支撑时，回到编程手或建模手补齐，禁止编造。
• 论文手发现会使核心结论失效的重大缺陷时，不把它包装成普通“缺点”后继续交付；必须回退修复或替换模型。正式论文只保留不推翻核心结论的适用边界、理想化假设和可改进局限。
• 修正后从被阻断阶段继续，不重复已通过的阶段。

建模约束

1. 先完整理解题目、附件、目标、约束和评价口径，再形成结论与模型方案。
2. 默认用最少且足以回答问题的模型体系；通常先形成一个主模型，只有在机制、假设、任务阶段或独立验证价值确实不同且能真实实现时再增加模型。不得用固定“最多两个”替代问题驱动的复杂度控制，也不得为展示模型数量堆叠同质方法。物理题中，同一机制的不同近似阶次通常按一个模型族组织。
3. 避免直接套用过于常见的简单模型来冒充创新；创新必须来自问题结构、数据处理、约束设计、算法改进或验证方式，并说明依据。
4. 数据判定标准按题目、官方规则、领域文献或数据分析结果确定。
5. 不因两个模型得到相近结论就强制删除其中一个；是否保留由研究目的和证据价值决定。

渐进式加载

先读当前阶段的 SKILL.md，再按其中“何时加载”表读取所需参考，禁止一次性加载全部资料。

当前任务	额外读取
查询私有资料、优秀案例或相关原图	references/知识库与MCP.md，并调用数学建模知识库 MCP
练习复盘、生成错题条目或检索历史不足	references/错题本条目模板.md 与 references/实践复盘入库模板.md，并按需调用数学建模知识库 MCP
选模型或查算法	references/算法索引.md，再按索引分段读取一个或少数几个相关 references/algorithms/*.md
搜索论文	tools/paper-search/SKILL.md
读取题目 PDF	tools/pdf/SKILL.md
批量把论文文档转为知识库 Markdown/多模态图片包	tools/pdf-batch/SKILL.md
处理 Excel	tools/xlsx/SKILL.md
生成 Word 论文	tools/docx/SKILL.md
完整建模交付、赛后审稿或论文修改	references/评审门与证据等级.md、references/参数语义与约束审计.md 与 references/roles/model-reviewer/SKILL.md
完整论文生成、修改或发布	references/用户追加硬限制.md，并把适用条目写入发布清单

完成判定

• 所有计算结论来自实际运行结果。
• 公式、表格和图表与代码结果一致。
• 红队评审门通过；关键主张均有证据与推翻条件，重大失败已回退修正，重复数值均来自 result_registry.json。
• 引用可由 OpenAlex、AnySearch 或原始出版页面追溯。
• 论文已按目标竞赛当届官方规则配置，篇幅目标已经确认，Word 公式可编辑，公式/图/表数量经过检查，图表编号与正文引用连续，参考文献与正文引用双向对应，DOCX 结构校验和渲染页数检查通过。
• 完整论文.docx 及官方要求时的 完整论文.pdf 由发布门禁从同一候选稿和锁定渲染件晋升；发布清单动态锁定竞赛与届次、规则和模板、分页结构、渲染器、摘要必答项，以及候选稿、渲染 PDF、结果注册表和红队审计的 SHA-256。不存在对官方硬约束或红队失败的覆盖项。
• 所有产物位于 PROJECT_ROOT，SKILL_ROOT 未被改写。