# Edu Chem Reaction

> 将教材范围内的化学反应生成 Three.js 微观分子交互网页，展示配平后的方程、断键成键、 原子守恒、电子转移或基础有机机理。适用于燃烧、电解水、氧化还原、酯化等化学反应的 可视化讲解；用户要求化学反应、分子动画、微观演示、原子守恒、化学方程式配平、 断键成键、电子转移或反应机理网页时优先使用。不要用于通用反应预测、未验证的复杂机理 或无法由内置分子库和 schema 支持的物种。

- Skill: `mingchen666/edu-chem-reaction` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add mingchen666/edu-chem-reaction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mingchen666/edu-chem-reaction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mingchen666 (https://skillmd.com/u/mingchen666)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mingchen666/edu-chem-reaction

---


# 化学反应微观演示

## 目标与边界

生成一个可直接打开的单文件 HTML：页面包含 Three.js 分子动画、KaTeX 化学方程、反应进度控制、断键/成键高亮、原子守恒计数、分步讲解，以及按需显示的能量曲线、电子转移或催化剂叠加层。

这是教学可视化，不是化学反应预测器。只生成以下两类内容：

- `scripts/generate.py list` 中已注册并经过 kernel 校验的反应。
- Agent 能根据 `references/problem-schema.md` 建模，且所有物种、原子映射、键变化都可通过 `lib/reaction_kernel.py` 校验的反应。

不支持的物种、模糊图片、无法核验的配平或机理，必须说明限制并请求补充；不能为了生成动画而猜测反应条件、产物、原子去向或电子转移。

## 何时使用

优先用于：

- 燃烧、电解、化合、分解、置换、复分解、氧化还原等反应的微观演示。
- 用户希望理解原子为何守恒、哪些键断裂或生成、电子如何转移。
- 教师需要课堂展示，或学生希望把一条已知化学方程式转成可交互网页。
- 基础有机反应机理，例如内置的酯化示例。

不要用于：

- 只需文字讲清的概念或普通流程图，优先使用 `concept-explainer` 或 `learning-visualization-skill`。
- 数学几何、网络协议或其他已有专项可视化场景。
- 需要预测未知反应、给出实验操作、危险化学品处置或未经资料核验的专业结论。

## 输入处理

按以下优先级处理资料：用户本轮明确要求 > 用户提供的题目/文件 > 已选择知识库 > 可核验资料 > Skill references > 通用知识。

- 对话文字：提取方程、反应条件、语言、教学目标和需要强调的内容。
- Markdown、TXT、JSON、CSV 或代码文件：用 `file_read` 读取。
- 图片、截图、扫描方程：先用 `vision_analyze` 识别方程、箭头条件和可见说明，再把识别结果回显给用户确认。图片模糊、化学式不完整或下标无法辨认时要求清晰图片或文字，不猜测。

当前脚本不包含通用的化学式解析器。收到自然语言反应请求时，先映射到注册反应；无法可靠映射时，只有在内置分子库和 schema 足够支持的情况下才构建临时 reaction spec。

## MindSpace 路径规则

Skill 目录只读：`/skills/edu-chem-reaction/` 只用于读取模板、脚本、分子库和 references。

最终 HTML 写入当前 Agent 的真实输出目录：

```text
/agents/<当前Agent英文名>/outputs/<系统提供的真实日期>/reaction-<reaction>.html
```

临时 spec、检查输出和可选脚本写入：

```text
/tmp/<当前Agent英文名>/<系统提供的真实日期>/
```

尖括号只用于说明路径结构。实际工具调用必须使用系统提供的真实 Agent 目录名和真实日期，不能把占位符原样写入。生成成功后返回实际输出路径；成果中心由系统扫描该目录注册，Skill 不操作数据库或伪造 artifact ID。

## 标准流程

### 1. 确认反应

识别用户提供的反应式和条件。图片输入必须先让用户确认识别结果。对于氧化还原，确认氧化剂、还原剂和电子转移是否有可靠依据；对于有机机理，确认催化剂和关键步骤，不把简化示意当作完整实验机制。

### 2. 选择数据路径

优先使用注册反应。可用 key 为：

- `combustion_ch4`
- `combustion_h2`
- `electrolysis_water`
- `redox_na_cl2`
- `esterification`
- `glucose_combustion`

若确实需要新反应，先读取 `references/problem-schema.md` 和 `references/conventions.md`。将临时 spec 写入当前 Agent 的 `/tmp` 目录，并且只使用 `lib/molecules.py` 已定义的物种；高层 spec 必须提供完整双射的 `atom_map`，低层机理必须明确 atoms、bonds 和 fragments。

### 3. 生成 HTML

先运行依赖检测：

```text
python "/skills/edu-chem-reaction/scripts/check_dependencies.py"
```

如果检测到必需包缺失，把检测器输出的一次性安装命令和包清单展示给用户，等待用户明确确认后再执行 `python -m pip install ...`。一次确认可以覆盖检测器列出的全部缺失包；安装完成后必须重新运行依赖检测。没有用户确认时不得安装、不得继续声称可以生成。检测器本身永远不会安装依赖。

使用 `exec_command` 的实际 `command` 参数执行 Python。所有命令都应引用显式输出路径，等待产品要求的命令审批；不要调用 `bash`、`sh`、`execute` 或启动本地服务。

```text
python "/skills/edu-chem-reaction/scripts/generate.py" \
  combustion_ch4 \
  "/agents/<真实Agent>/outputs/<真实日期>/reaction-methane-combustion.html"
```

需要按 spec 生成时：

```text
python "/skills/edu-chem-reaction/scripts/generate.py" \
  spec \
  "/tmp/<真实Agent>/<真实日期>/reaction-spec.json" \
  "/agents/<真实Agent>/outputs/<真实日期>/reaction-custom.html"
```

可用 `random <output.html> [seed]` 生成一个已注册反应；`all <output-directory>` 只用于明确要求批量示例时。脚本会创建输出父目录、拒绝写入 Skill 目录，并在成功时打印最终路径。

### 4. 确定性校验

生成后必须运行：

```text
python "/skills/edu-chem-reaction/scripts/check_output.py" \
  "/agents/<真实Agent>/outputs/<真实日期>/reaction-methane-combustion.html"
```

校验器检查文件非空、数据岛可解析、必需页面标记存在、模板占位符已替换，且输出不依赖 localhost 或写入 Skill 目录。校验失败时修正 spec 或命令后重试，不能声称文件已经可用。

Node 可用时，可把抽取出的页面脚本写到当前 Agent `/tmp` 目录中的显式 `.mjs` 路径并额外检查语法：

```text
python "/skills/edu-chem-reaction/scripts/check_output.py" \
  "/agents/<真实Agent>/outputs/<真实日期>/reaction-methane-combustion.html" \
  --node-check \
  "/tmp/<真实Agent>/<真实日期>/reaction-module.mjs"
```

### 5. 交付

回复只说明：已生成的实际文件路径、反应和教学重点、验证结果，以及页面首次打开需要访问 CDN。不要启动 localhost 预览，也不要将输出写入系统临时目录或 Skill 目录。

## 核心领域规则

- `reaction_kernel` 是配平、原子守恒、原子映射和键差的唯一数据源。不要手算后绕过 kernel。
- `morph` 用于燃烧、分解、置换和氧化还原，强调原子重组与守恒。
- `mechanism` 用于已明确的有机机理，采用关键帧片段来呈现催化剂、过渡态或离去基团。
- 方程系数、分子实例数、原子守恒计数和动画数据必须来自同一份已校验 spec。
- 内置 Python 仅探测 RDKit 是否可用，当前生成路径不依赖或自动调用 RDKit；不要把它宣传为可用的任意分子构象生成能力。

## 依赖与失败处理

- Python 与 `sympy` 是硬依赖。缺失时先运行依赖检测，向用户展示完整清单；只有用户明确确认后，才用当前解释器执行一次 `python -m pip install ...`，随后重新检测。不能静默安装、切换解释器或从 GitHub 下载依赖。
- Node 可用于增强语法检查，但不是生成 HTML 的硬依赖。传入当前 Agent `/tmp` 内的显式 `.mjs` 路径时，校验器会抽取内联脚本并执行 `node --check`；Node 缺失时保留 Python 和 HTML 结构校验，并说明跳过增强检查。
- 页面为单文件 HTML，但 Three.js、OrbitControls、KaTeX 和 Tailwind 使用 CDN。文件可生成不等于离线环境可完整运行；CDN 不可访问时明确说明运行受限。
- 若当前 Agent 缺少 `file_write`、`vision_analyze` 或 `exec_command`，说明缺少的工具/权限并请求切换到已配置 Agent；不伪造生成成功。
- 命令失败时以 stderr 和退出码为准，说明具体失败点。不得通过启动 localhost、写入 Skill 目录或自动安装依赖来规避失败。

## 与其他 Skills 的边界

- `concept-explainer` 负责文字化解释；当用户明确需要化学反应微观页面时再接入本 Skill。
- `learning-visualization-skill` 适合通用概念、流程和关系，不替代基于原子映射的反应演示。
- `edu-solid-geometry`、`edu-analytic-geometry` 和 `network-protocol-viz` 分别处理几何与网络专项场景，不混用。
- `practice-quiz`、`error-analysis` 和 `review-plan` 负责学习闭环；本 Skill 可作为其中的可视化环节。

## 质量自检

交付前确认：

1. 方程、反应条件和资料来源与用户确认内容一致。
2. kernel 已通过配平、守恒、映射和键差校验。
3. 最终 HTML 位于当前 Agent 的 outputs 目录，临时文件位于该 Agent 的 `/tmp` 目录。
4. `check_output.py` 成功，命令没有遗留服务或后台进程。
5. 已说明 CDN 网络要求、依赖降级和无法支持的部分。