用途
本技能是“建模代码与结果证据生成器”，为数学建模论文提供一个稳定的“结果证据层”和可运行的赛题专用建模代码起点。它避免正文仅根据模型路线空写，也避免 Agent 面对数据时无头乱转。
本技能不是万能自动建模系统，不能替代真实赛题中的建模工作。
在全局流程中的位置
本技能不得作为孤立入口。用户要求完整论文、生成 Word、继续流程或不确定阶段时，应先回到 paper-workflow-orchestrator 判断当前 S0-S8 阶段。
启动或继续正式任务前必须运行：
python .claude/skills/paper-workflow-orchestrator/scripts/workflow_guard.py --skill model-code-and-result-generator
如果输出 [WORKFLOW FAIL] 或 status != "PASS"，应停止本技能，按 paper_output/qa/workflow_guard_report.json 的失败项回补前置阶段，不得凭记忆继续。
完成本技能产物后，应回到 paper-workflow-orchestrator 或运行 workflow_guard.py --status，再用 context-memory-keeper 记录已完成产物、阻塞项和下一步：
python .claude/skills/context-memory-keeper/scripts/update_workflow_memory.py
若上下文变长、阶段不确定或用户分开调用技能，先运行：
python .claude/skills/paper-workflow-orchestrator/scripts/workflow_guard.py --status
再读取 workflow_guard_report.json、preflight_report.json、input_manifest.json、results/run_manifest.json 及本技能上游 JSON 契约，按报告里的 recommended_skill 与 next_action 继续。继续流程时，以 workflow_guard.py --status 报告为准，与 workflow_memory.json 不一致时以 guard 为准。
主要能力
输入
优先读取 paper_output/plan/model_route.json、data_plan.json、visualization_plan.json，并扫描 paper_output/data_cleaned/。
输出
必须输出：
- paper_output/results/model_results.json、metrics.json、conclusions.json、run_manifest.json
- paper_output/tables/table_index.json、paper_output/tables/*.csv
建模代码输出到 paper_output/code/modeling/，包括 result_contract_io.py、run_modeling.py、q1_model.py、q2_model.py、q3_model.py 或与 question_id 对应的 q*_model.py。
下游交接：quality-assurance-auditor 读取结果与表格证据后写入 tasks.json；paper-micro-unit-generator 通过任务清单引用结果、指标、表格和结论。
失败回退：如果没有清洗数据或真实建模代码，仍生成契约骨架，并用 needs_real_modeling 标记，不伪装成最终比赛结果。
脚本
- scripts/build_result_contracts.py：扫描 model_route.json 的每个 question_id，生成结果契约骨架、基础字段画像表、paper_output/code/modeling/README.md，并生成可运行的 q*_model.py。生成文件带有 managed marker；如果 Agent 已手工改写并去掉 marker，脚本会保留用户文件，不覆盖。
- scripts/result_contract_templates.py：提供预测、优化、评价、分类、聚类、仿真、通用建模的契约模板，用于了解不同任务类型应沉淀哪些指标、表格和结论字段。
任务类型分发
- 预测/回归/时间序列 -> forecasting scaffold：生成目标列、特征列、预测值、残差、RMSE、MAE、MAPE。
- 优化/规划/调度/选址/路径 -> optimization scaffold：生成代理目标函数、方案排序、约束满足率待补项。
- 评价/排序/权重/TOPSIS/AHP/熵权 -> evaluation scaffold：生成指标归一化、综合得分、排序和权重敏感性待补项。
- 分类/识别/判别 -> classification scaffold：生成代理分类标签、准确率/F1 待补项。
- 聚类/分群 -> clustering scaffold：生成代理聚类标签、聚类数、簇内紧凑度。
- 仿真/机理/动力学/微分 -> simulation scaffold：生成趋势代理、情景结果、拟合误差和敏感性参数。
- 其他 -> general scaffold：生成数值字段统计摘要和通用结果表。
使用方式
推荐由 paper-workflow-orchestrator 在数据清洗与可视化之后调用。也可手动运行：
python .claude/skills/model-code-and-result-generator/scripts/build_result_contracts.py
生成脚手架后，Agent 应按真实赛题执行：
python paper_output/code/modeling/run_modeling.py
该入口会写入 paper_output/results/run_manifest.json。然后重新运行 QA，让 paper_output/tasks.json 读取刷新后的 model_results.json、metrics.json、conclusions.json、run_manifest.json 和 table_index.json。
输出目录与统一规则
paper_output/ 下结构：
- code/modeling/：run_modeling.py、result_contract_io.py、q1_model.py、q2_model.py、q3_model.py、README.md
- results/：model_results.json、metrics.json、conclusions.json
- tables/：table_index.json、table_q1_result_skeleton.csv、table_q1_forecasting_scaffold.csv 等
统一规则：所有路径使用相对路径；所有 JSON 包含 schema_version、generated_by、generated_at；每条结果、指标、结论和表格都应带 question_id；草稿或脚手架结果必须使用 status 或 evidence_status 标记；正式结果必须带 execution_provenance，包含 source_code_path、run_command、run_exit_code 和 output_artifacts；统一入口 run_modeling.py 还必须写入 paper_output/results/run_manifest.json，记录脚本命令、退出码、输入文件 hash 和输出产物 hash。official evidence gate 会拒绝没有真实代码运行来源或没有 run_manifest 对应运行记录的结果。正文中引用的表格必须能在 paper_output/tables/table_index.json 找到。
适用场景
适用于数学建模论文流程中需要把模型输出、评价指标、结构化结论、论文表格和当前赛题专用建模代码沉淀到 paper_output/results/、paper_output/tables/ 和 paper_output/code/modeling/ 的环节。适合在数据清洗与可视化之后、QA 审计之前使用。
限制
不要把占位式指标或代理结果直接当成最终比赛结果。优先修改 paper_output/code/modeling/q*_model.py，不要修改 skill 包内的 scripts/。正式建模完成后，必须由建模代码实际运行并把真实输出写回 paper_output/results/ 与 paper_output/tables/，不要手写 model_results.json 冒充运行结果。没有 run_manifest.json 对应运行记录时，不能进入正式 evidence gate。如果某一问没有真实结果，QA 应保留 warning，正文不得把该问写成已经完成精确计算。文档中未提供具体收费、价格、平台或效果信息。