数据清洗与可视化 (Data Cleaning and Visualization)

Resolve <SKILL_ROOT> to the parent directory of this loaded skill folder, using its actual absolute path. Run commands from the contest project root, never from the installed skill directory. The placeholder is not a shell environment variable.

全局流程协作约束（长对话防漂移）

• S3 自动图表都是 needs_review 的探索草图，不是实验结论。不得根据原始字段直接宣称预测效果、敏感性或模型优劣；敏感性图必须先运行参数扰动实验。

• 核对字段、单位和图形类型后，由赛题建模脚本基于真实结果重画正式图表，并登记到对应运行的 output_artifacts。正式索引只收录这些证据；保留探索文件和失败日志，不要改状态冒充正式结果。

• 本 skill 不得作为孤立入口。用户要求完整论文、生成 Word、继续流程或不确定阶段时，先回到 paper-workflow-orchestrator 判断当前 S0-S8 阶段。

• 启动或继续本 skill 的正式任务前，必须运行：

  python "<SKILL_ROOT>/paper-workflow-orchestrator/scripts/workflow_guard.py" --skill data-cleaning-and-visualization
  

• 如果输出 [WORKFLOW FAIL] 或报告 status != "PASS"，停止本 skill，按 paper_output/qa/workflow_guard_report.json 的失败项回补前置阶段，不得凭记忆继续。

• 本 skill 只写入自己契约范围内的 paper_output/ 产物；完成后必须回到 paper-workflow-orchestrator 判断下一步，并用 context-memory-keeper 记录已完成产物、阻塞项和下一步。

• 长对话中如果上下文变长、阶段不确定或用户分开调用 skill，先运行：

  python "<SKILL_ROOT>/paper-workflow-orchestrator/scripts/workflow_guard.py" --status
  

  再读取 paper_output/qa/workflow_guard_report.json、paper_output/preflight_report.json、paper_output/input_manifest.json、paper_output/results/run_manifest.json 和本 skill 的上游 JSON 契约，按报告里的 recommended_skill 与 next_action 继续。

• 继续流程前，必须把 paper_output/context/workflow_memory.json 视为长期断点记录；若其中的 current_step、next_step、recommended_skill 与 workflow_guard.py --status 不一致，以 guard 报告为准。

• 每次完成本 skill 的产物后，先回到 paper-workflow-orchestrator 或运行 workflow_guard.py --status，再更新 workflow memory：

  python "<SKILL_ROOT>/context-memory-keeper/scripts/update_workflow_memory.py"
  

  更新后读取 paper_output/context/workflow_memory.json / .md，确认下一步和推荐 skill 已记录。

执行契约

• 上游输入：优先读取 paper_output/input_manifest.json、paper_output/step1/problem_analysis.json 与 paper_output/plan/model_route.json；正式流程只处理 manifest 中标为 raw_data 且 usable_for_modeling=true 的附件。
• 必须输出：paper_output/data_cleaned/load_report.json、paper_output/plan/data_plan.json、paper_output/plan/visualization_plan.json、paper_output/figure_index.json；有可处理数据时同步输出 paper_output/data_cleaned/ 与 paper_output/figures/。
• 下游交接：quality-assurance-auditor 审计数据/图表证据；S7 写作计划直接引用 figure_index.json、表格索引和结果契约。tasks.json 仅供 legacy/quickstart。
• 推荐下一步：完成数据和图表计划后回到 paper-workflow-orchestrator，按 S4-S6 运行模型和证据审计，再由正式主笔写作。
• 失败回退：若没有可处理数据文件，仍尽量根据题意和模型路线生成计划文件；不得把模板图表直接当作最终真实结果。

本技能用于自动处理数学建模中的原始数据，执行标准化的清洗流程，并生成基础的数据探索性分析（EDA）图表。旨在减少手动处理数据的繁琐步骤，快速获取数据的统计特征和分布情况。

重要定位：脚本是代码级提示词

数学建模赛题的数据表结构、字段名称、单位口径和图表需求通常都不同，因此本技能的 scripts/ 不应被理解为所有赛题通用的固定程序。它们的核心价值是提供高质量的数据处理与图表生成样板：包括输入输出目录、清洗步骤、图表尺寸、配色、标注、保存路径和论文引用口径。

真实赛题中，应先分析当前附件的数据格式和建模需求，再引用 scripts/ 中的写法二次修改，或让 Agent 读取这些脚本后重新生成适配当前赛题的新代码。

功能特性

1. 按清单读取数据源：只读取 manifest 中 raw_data 且 usable_for_modeling=true、哈希未变化的文件；清单缺失或损坏时停止，不回退扫描。
2. 读取诊断报告：先运行 robust_loader.py，生成 paper_output/data_cleaned/load_report.json，记录 xlsx/csv/json 结构与 PDF 诊断结论；脚本会优先读取 paper_output/input_manifest.json，跳过 result_template、题面文档和不可用于建模的附件。PDF 表格抽取只作诊断，不直接视为可信原始数据。
3. 数据与图表计划：生成 data_plan.json、visualization_plan.json 与 figure_index.json，作为后续 QA 和正文生成的图表证据交接单。
4. 保真导入与诊断：
   • 保留空值、重复记录和文本编号，不自动填补、去重或强制转数值。
   • CSV 字段数量异常或引号损坏时明确失败，不跳过坏行。
   • Excel 各工作表独立导出；合并单元格、公式或含糊表头需要赛题专用读取代码。
   • cleaning_report.json 记录来源、工作表、行数、空值、重复记录和输入输出哈希；PASS 只表示导入完成，不代表字段语义正确。
   • 需要统计预处理时按需读 数据处理规则，在赛题代码中明确单位、缺失含义和训练/验证切分，记录变更。
5. 自动可视化：
   • 数值变量：直方图、箱线图。
   • 分类变量：柱状图。
   • 多变量关系：相关性热力图、散点矩阵。
   • 论文级图表样板：预测对比图、残差分布图、方案/模型对比图、敏感性分析图、权重图、排序图、热力图、聚类散点图。
6. 规范化输出：所有清洗后的数据和图表统一保存到 paper_output/ 目录下，方便后续论文写作调用。

脚本清单

本技能包含以下核心脚本，位于 <SKILL_ROOT>/data-cleaning-and-visualization/scripts/ 目录下：

• scripts/robust_loader.py

  • 何时用：任何正式数据清洗、建模或绘图之前，先诊断附件是否可读、哪些 sheet/字段可用、PDF 是否需要人工转表。
  • 做什么：优先读取 paper_output/input_manifest.json，只对标为 raw_data 的 xlsx/xls/csv/tsv/json 生成结构报告；对 PDF 只生成文本/表格诊断，不把 PDF 自动抽取结果当作可信数据；输出 paper_output/data_cleaned/load_report.json，并记录当前 input_manifest_sha256。manifest 变化后必须重跑 loader。

• scripts/run_pipeline.py

  • 何时用：用户提供赛题数据或完成爬虫后，需要自动完成清洗和绘图时。这是最常用的辅助脚本。
  • 做什么：依次诊断附件、保真导入、基于真实导出路径生成计划、绘图；任一步失败即停止。支持 --project-root。

• scripts/build_data_visualization_plan.py

  • 何时用：已有 problem_analysis.json 或 model_route.json，需要先明确“哪些数据支撑哪些问题、哪些图表放在哪里”时。
  • 做什么：读取赛题分析、模型路线和现有数据文件，输出 paper_output/plan/data_plan.json、paper_output/plan/visualization_plan.json 与 paper_output/figure_index.json。

• scripts/clean_data.py

  • 何时用：只需要清洗数据，不需要绘图，或者需要自定义清洗逻辑时。
  • 做什么：按 manifest 导入所有可处理工作表到独立 data_cleaned/runs/<id>/，写入清洗报告。支持 --project-root；不会自动执行统计填补。

• scripts/visualize_data.py

  • 何时用：已有清洗好的数据，需要重新生成图表时。
  • 做什么：只读取当前清洗报告绑定且哈希未变的输出，生成 EDA 草图；不扫描旧运行数据。数值列推断仅供探索，不能代替单位、编号和数据含义确认。

• scripts/paper_figure_templates.py

  • 何时用：Agent 需要生成论文级图表代码时，优先读取本文件作为代码样板。
  • 做什么：提供预测对比、残差分布、模型/方案对比、敏感性分析、指标权重、综合得分排序、热力图、散点图等函数模板。无法读取真实数据时返回结构化 placeholder 状态，不生成可冒充真实结果的 PNG。

• scripts/generate_paper_figures_from_plan.py

  • 何时用：已有 visualization_plan.json 和清洗后的 CSV，希望先生成一版论文级图表草稿时。
  • 做什么：按图表计划调用 paper_figure_templates.py，把真实可生成图写入 paper_output/figures/fig_*.png，并在 figure_index.json 中记录 ok、placeholder 和 status。任何 placeholder 都不能通过正式 evidence gate。

输出结构

运行后，将在 paper_output 目录下生成以下内容：

paper_output/
├── plan/
│   ├── data_plan.json       # 数据字段、清洗任务与子问题链接
│   └── visualization_plan.json # 建议图表、图题、用途与输出路径
├── figure_index.json        # 图表计划索引，供 QA 和正文生成核对
├── data_cleaned/       # 清洗后的数据文件
│   ├── load_report.json # 附件读取诊断报告
│   ├── cleaning_report.json # 当前导入清单、统计与哈希
│   └── runs/<id>/*.csv      # 各来源与工作表独立输出；旧运行不自动复用
├── figures/            # 生成的可视化图表
│   ├── fig_q1_1.png     # 按 visualization_plan 生成的论文级图表草稿
│   ├── fig_q1_2.png
│   ├── dataset1/
│   │   ├── dist_column_A.png
│   │   ├── heatmap.png
│   │   └── ...
│   └── ...

目录约定（与项目全局对齐）

• 输入数据优先放在 problem_files/（赛题附件）与 crawled_data/（补充/爬虫数据）。
• 本技能只写入 paper_output/，不会改动原始数据文件。
• data_plan.json 与 visualization_plan.json 是交接单，不是固定代码。Agent 应根据它们和当前附件结构二次生成或修改真实建模代码。
• paper_figure_templates.py 生成的是论文图表代码样板。若当前赛题已经有真实模型输出，应优先把真实结果表接入这些模板，而不是直接把模板图当最终结果。
• figure_index.json 中 placeholder=true、ok=false、exists=false、失败消息或空文件都表示图表证据未完成；不得仅凭索引条目存在就继续正式写作。

前后衔接

• 后续按 S4-S6 计算和验证，再进入 paper-formal-writer；微单元只用于局部修复，不是正式主线。
• 若要继续到论文草稿：回到 paper-workflow-orchestrator。

约束（必须遵守）

• Memory Interaction (必做):
  • 完成清洗后，必须调用 context-memory-keeper，记录“数据质量概况（样本量/缺失情况）”与“关键图表路径”到 Short-term Workbench。
• 本技能只允许读取：problem_files/ 与 crawled_data/；只允许写入：paper_output/。
• 正式流程读取附件前必须先生成 paper_output/input_manifest.json 与 paper_output/data_cleaned/load_report.json；Agent 不得跳过 manifest 直接复述 PDF 表格内容或把 result*.xlsx 当作原始数据。
• 任何需要在论文中出现的图表，必须从 paper_output/figures/ 引用，避免散落在根目录或附件目录。
• 若用户目标是“产出完整论文草稿”，本技能结束后必须进入：quality-assurance-auditor 或直接回到 paper-workflow-orchestrator，否则会出现“有图但无正文/有正文但无任务清单”的断链。