AI数模科研绘图

技能文档

---
name: modelviz-skill
title: AI数模科研绘图
category: 学术研究
description: 数学建模与科研可视化工作流。将用户的 CSV/XLSX/XLS 数据和自然语言绘图需求，通过模板选择、代码适配、执行绘图、质量检查与自动修复，生成论文级科学图表。当用户需要「科研绘图」「数学建模画图」「数据可视化」「模板绘图」「论文图表」时触发。
---

# AI数模科研绘图

从用户数据和本地模板库出发，自动完成选图、模板适配、绘图生成、质量检查与有限修复，输出论文或答辩级别的科学图表。

不适用于：纯数学概念讲解（不绘图）、修改用户原始数据、执行非绘图代码、或强制生成模板库不支持的图表类型。

## 输入

- 用户自然语言绘图需求
- 用户数据文件（支持 `csv`、`xlsx`、`xls`，通过 `src/tools/prepare_dataset_context.py` 处理）
- 可选：图表类型、风格偏好、负面要求、输出格式、Excel `sheet_name`
- 支持结构化输出的对话模型

需求过于模糊、数据表不明确、数据无法支撑需求、无合适模板、或多列含义歧义时，先向用户追问再继续。

## 核心规则

职责分工：

- **程序代码**负责：文件读写、Pydantic 校验、确定性候选召回、数据采样、依赖检查/安装、脚本执行、产物检查、图像统计、警告收集、修复限制、JSON 报告
- **语言模型**负责：自然语言需求解析、语义数据解读、从候选中选择最终模板、模板风格理解、列映射、模板代码适配、视觉判断、局部代码修复

禁止引入 Agent、RAG、向量数据库。禁止编造文件、依赖、候选模板、生成图片或质量状态。

## 实现参考

目录与工作流参考：

- `docs/template_catalog.yaml`
- `docs/template_index.csv`
- `docs/stage5_stage6_skill_workflow.md`

服务入口：

- `src/services/requirement_parser.py`
- `src/services/candidate_matching_pipeline.py`
- `src/services/final_template_selection_pipeline.py`
- `src/services/template_adaptation_pipeline.py`
- `src/services/plot_quality_pipeline.py`

## 技能工作流

### 步骤1：解析用户需求

调用 `src.services.requirement_parser.parse_and_save_requirement`。

组合内容：

- Prompt：`src/prompts/requirement_parser.py`
- Schema：`schemas/requirement_schema.py`
- 词表：`docs/requirement_vocabulary.yaml`
- 输出：`workspace/user_requirement.json`

Schema 为 `PlotRequirement`，字段包括 `original_request`、`goal`、`functional_keywords`、`chart_types`、`style_keywords`、`use_case`、`negative_requirements`、`explicit_template`、`is_ambiguous`、`clarification_question`。

规则：

- 保留 `original_request` 原文
- 用户未指定图表类型时保持 `chart_types=[]`
- 风格词（如「科研风」「简洁」「低饱和」）放入 `style_keywords`，不放 `functional_keywords`
- 排除项（如「不要雷达图」「不要三维」）放入 `negative_requirements`
- `is_ambiguous=true` 时，输出 `clarification_question` 并暂停

### 步骤2：召回候选模板

调用 `src.services.candidate_matching_pipeline.run_candidate_matching_pipeline`。

按顺序调用：

1. `load_user_requirement`
2. `load_template_catalog`
3. `match_candidate_templates`
4. `rank_candidate_templates`
5. `save_candidate_templates`

输入：`workspace/user_requirement.json`、`docs/template_catalog.yaml`
输出：`workspace/candidate_templates.json`

模板库当前包含 12 个类别共 89 个模板。候选召回为确定性匹配，不读取用户数据。默认 `top_k=8`，约束范围 5-10。`min_score` 约束范围 0-1。

评分优先级：

- 功能关键词匹配
- 图表类型精确匹配
- 用户原文与模板同义词匹配
- 目标与使用场景匹配
- 风格匹配（低权重）
- 用户负面要求作为排除条件
- 模板 `negative_keywords` 作为惩罚

不要把排名第一的候选当作最终答案，步骤2仅召回 5-10 个合理候选。

### 步骤3：结合数据选择最终模板

调用 `src.services.final_template_selection_pipeline.run_final_template_selection_pipeline`。

组合内容：

- 数据工具：`prepare_dataset_context`
- Prompt：`src/prompts/final_template_selector.py`
- Schema：`src/schemas/final_template_selection.py`
- 输入：`workspace/user_requirement.json`、`workspace/candidate_templates.json`、用户数据文件
- 输出：`workspace/dataset_context.json`、`workspace/final_template_selection.json`

`prepare_dataset_context` 仅返回事实：文件名、类型、Sheet、行数、列数、列名、头部记录、采样记录、采样状态和警告。不决定最佳图表。

模型必须分析真实数据含义，且只能从 `candidate_templates.json` 中选择。Python 校验会拒绝：

- 不在候选列表中的模板 ID
- 与 ID 不一致的模板名称
- 数据文件中不存在的列
- `needs_clarification=true` 时缺少 `clarification_question`

`selected_template_id` 为 null 时，停止并返回原因或追问。

### 步骤4：检查并补全模板依赖

调用 `src.services.template_adaptation_pipeline.run_template_adaptation_pipeline` 的前半部分。

调用链：

- `load_selected_template`
- `inspect_template_dependencies`
- `check_python_dependencies`
- `install_python_dependencies`
- 再次 `check_python_dependencies`

相关文件：

- 模板目录：`docs/template_catalog.yaml`
- 包名映射：`docs/package_name_mapping.yaml`
- 报告：`workspace/dependency_report.json`、`workspace/dependency_install_result.json`、`workspace/requirements.generated.txt`

依赖规则：

- 用 Python AST 检查 import，合并 catalog 依赖
- 子模块转为顶级 import
- 排除标准库和项目内部模块
- 用 `docs/package_name_mapping.yaml` 映射 pip 包名
- 无法映射时停止
- 仅安装经过验证的正规包名
- 禁止执行模板代码中的安装命令
- 禁止 `shell=True`、`sudo`、URL、Git 地址、本地路径或额外 pip 参数
- 不覆盖项目 `requirements.txt`，写入 `workspace/requirements.generated.txt`

### 步骤5：生成适配计划与代码

继续 `run_template_adaptation_pipeline`。

适配计划：

- Prompt：`src/prompts/template_adaptation_plan.py`
- Schema：`src/schemas/adaptation_plan.py`
- 输出：`workspace/adaptation_plan.json`

代码生成：

- Prompt：`src/prompts/template_code_adapter.py`
- Schema：`src/schemas/adaptation_result.py`
- 输出：`workspace/adaptation_result.json`、`workspace/adapted_plot.py`

模型必须保留核心模板布局、绘图库、配色风格和报告结构。必须用用户文件的真实数据替换模板演示数据，仅使用真实列名。

Python 校验拒绝：不存在的列、未确认的依赖、空 `adapted_code`、尝试写入 `templates/`。

`templates/` 下的原始模板为只读。不编辑或覆盖用户数据。

如模型请求额外依赖，允许一次额外安装。失败则停止。

### 步骤6：执行适配脚本

通过以下工具保存并执行脚本：

- `save_adapted_script`
- `execute_plot_script`
- 脚本：`workspace/adapted_plot.py`
- 输出目录：`outputs`
- 执行报告：`workspace/execution_result.json`

`execute_plot_script` 使用 `subprocess.run([...], shell=False)`，传入数据路径和输出目录作为参数，设置 `DATA_PATH` 和 `OUTPUT_DIR` 环境变量，捕获 stdout/stderr 并记录生成文件。

脚本超时、数据路径不存在、执行失败或无输出文件时停止。

### 步骤7：技术与视觉质量检查

调用 `src.services.plot_quality_pipeline.run_plot_quality_pipeline`。

技术检查工具：

- `execute_plot_script`
- `validate_output_artifacts`
- `inspect_generated_image`
- `collect_plot_warnings`

技术输出：

- `workspace/technical_quality_report.json`
- `workspace/execution_result.json`

检查项：输出位置、扩展名、大小、缺失文件、PNG 可读性、图像尺寸、像素方差、近空白风险、Python 运行时错误、依赖错误、字体警告、布局警告、图例警告、数据警告、保存失败。

视觉检查：

- Prompt：`src/prompts/visual_quality_checker.py`
- Schema：`src/schemas/visual_quality_report.py`
- 输出：`workspace/visual_quality_report.json`

视觉模型对比生成图像与需求、最终选择、适配计划、技术报告和模板预览（如有）。使用多模态模型时，调用方应提供实际生成图像和预览图像作为视觉输入。

### 步骤8：仅修复明确问题

技术或视觉检查需要修复时，`run_plot_quality_pipeline` 调用：

- Prompt：`src/prompts/plot_code_repair.py`
- Schema：`src/schemas/repair_result.py`
- 备份：`workspace/repair_versions/adapted_plot_v{n}.py`
- 历史：`workspace/repair_history.json`
- 最终报告：`workspace/final_quality_report.json`

修复规则：

- 仅修复技术或视觉报告中指出的问题
- 不重新设计图表
- 不修改 `templates/` 或用户数据
- 保留数据含义和模板风格
- 优先使用已有依赖和绘图逻辑
- 新依赖必须经过 `install_python_dependencies`

限制：

- `max_repair_attempts=3`
- `max_dependency_install_rounds=2`

停止条件：所有检查通过、达到最大修复次数、问题重复出现、修复代码未变化、依赖安装轮次耗尽、安装失败、模型返回 `can_retry=false`、或用户数据无法满足需求。

## Prompt 文件

可执行的 `ChatPromptTemplate` 模块：

- `src/prompts/requirement_parser.py`
- `src/prompts/final_template_selector.py`
- `src/prompts/template_adaptation_plan.py`
- `src/prompts/template_code_adapter.py`
- `src/prompts/visual_quality_checker.py`
- `src/prompts/plot_code_repair.py`

Markdown 参考文档位于 `prompts/` 目录，作为辅助参考，不是第二执行路径。

## 文件与输出

中间 JSON 写入 `workspace/`，使用 UTF-8 编码。最终图表写入 `outputs/`。文件未创建前不声称其存在。

典型输出：

- `workspace/user_requirement.json`
- `workspace/candidate_templates.json`
- `workspace/dataset_context.json`
- `workspace/final_template_selection.json`
- `workspace/dependency_report.json`
- `workspace/adaptation_plan.json`
- `workspace/adapted_plot.py`
- `workspace/execution_result.json`
- `workspace/technical_quality_report.json`
- `workspace/visual_quality_report.json`
- `workspace/final_quality_report.json`
- `outputs/chart.png` 或其他生成文件

## 失败处理

返回结构化失败信息，包含失败阶段、`error_type`、消息、详情和建议。以下情况必须停止而非伪造成功：

- 缺少或无效的输入文件
- 不支持的数据格式或缺失 Excel Sheet
- 未澄清的模糊需求
- 空候选列表
- 模型输出不符合 Schema
- 模型选择的模板不在候选中
- 模型编造数据列
- 无法映射或安装的关键依赖
- 非法包名或依赖安装失败
- 空或不安全的适配代码
- 脚本超时或失败
- 输出图像缺失、损坏或空白
- 视觉检查失败
- 达到最大修复次数

## 当前限制

- 工作流需要调用方提供结构化输出模型对象
- 视觉检查质量取决于是否传入实际图像内容
- 旧版 `run_template_matching_pipeline` 仍保留兼容，主流程应使用 `run_candidate_matching_pipeline`

使用说明

# AI数模科研绘图

从自然语言需求和真实数据出发，自动完成选图、模板适配、绘图生成、质量检查与修复，输出论文级科学图表。

## 使用

直接用自然语言描述绘图需求：

```text
请用 data.csv 画不同年份产量和增长率的趋势图，适合论文正文，风格简洁。
```

```text
请分析这些变量之间的相关性，生成科研风热力图，要求标签清晰。
```

```text
我想展示不同算法的预测误差对比，不要饼图，突出误差和排名。
```

## 工作原理

1. 解析用户自然语言需求，结构化图表类型、风格和场景
2. 从 89 个科研模板中确定性召回 5-10 个候选
3. 结合真实数据语义选择最终模板
4. 保留模板布局与配色，适配用户数据生成代码
5. 执行绘图脚本，进行技术检查与视觉检查
6. 仅修复检查明确指出的问题，最多 3 次

## 支持数据格式

CSV、XLSX、XLS

## 输出

- 论文级 PNG/SVG/PDF 图表
- 可复现的 Python 绘图代码
- 技术质量报告与视觉质量报告

## 适用场景

- 数学建模竞赛论文绘图
- 科研报告数据可视化
- 答辩展示图表制作
- 聚类、相关性、分布、预测评估、敏感性分析等方向

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。