edu-chem-reaction

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

化学反应微观演示 → 交互网页

Microscopic Demonstration of Chemical Reactions → Interactive Webpage

这个技能产出什么

What This Skill Produces

一个可直接用浏览器打开的单页 HTML：一侧是反应对应的 3D 分子动画（Three.js，可旋转缩放，拖动“反应进度”滑块逐帧看 化学键断裂/生成、原子重新组合，分步高亮 + 浮动分子标签），另一侧是 KaTeX 反应方程 + 分步讲解 + 原子守恒计数器，并可选 能量-反应进程曲线、火焰、催化剂质子、电子转移等叠加层。形态与

template/reaction.html

一致。

A single-page HTML file that can be directly opened in a browser: One side displays the corresponding 3D molecular animation (powered by Three.js, rotatable and scalable; drag the "reaction progress" slider to view chemical bond breaking/formation and atomic recombination frame by frame, with step-by-step highlighting + floating molecular labels), while the other side includes KaTeX reaction equations + step-by-step explanations + atom conservation counter, with optional overlays such as energy-reaction progress curves, flames, catalyst protons, and electron transfer. Its form is consistent with

template/reaction.html

依赖（重要）

Dependencies (Important)

计算核心

lib/reaction_kernel.py

依赖 sympy（用于配平）。运行脚本前先确认有一个能 import sympy 的

python3

：跑

python3 -c "import sympy"

（本机：

/opt/homebrew/bin/python3.11

）。

缺库时的处理（重要）：若 import 报错（sympy 或后续用到的任何库都同理），先询问用户是否安装，同意后再装（

python3 -m pip install <库名>

）或换解释器；不要未经询问直接装。 RDKit 是可选项：装了则混合几何会用它由 SMILES 生成真实构象，没装就用自建 VSEPR 库—— 两种都能跑，本技能任何时候都不会自动安装 RDKit。

The core calculation module

lib/reaction_kernel.py

depends on sympy (for equation balancing). Before running the script, ensure you have a

python3

environment that can import sympy: run

python3 -c "import sympy"

(local example:

/opt/homebrew/bin/python3.11

Handling Missing Libraries (Important): If an import error occurs (applies to sympy or any other library used later), ask the user for permission before installation. Install the library only after obtaining consent (using

python3 -m pip install <library name>

) or switch to another interpreter; do not install without user approval. RDKit is optional: If installed, the hybrid geometry will use it to generate real conformations from SMILES; if not installed, the self-built VSEPR library will be used—both options are functional, and this skill will never automatically install RDKit.

工作流程

Workflow

第 1 步：得到 reaction spec（三入口归一）

Step 1: Obtain Reaction Spec (Unified Three Entry Methods)

把反应整理成结构化 spec（格式见

references/problem-schema.md

）：反应物/产物、原子映射或显式原子、条件（点燃/通电/催化/可逆）、所属类别、分步讲解、语言。

文字反应/方程：直接抽取反应物与产物，调 kernel 自动配平。
图片：用视觉读图抽取方程，并把识别到的反应回显给用户确认（方程/条件/类别/语言）后再继续。
随机出题：从注册表挑一个反应，或在库内物种间组合并用
```
balanced_coefficients
```
配平、答案规整再用。

输出语言跟随提示词语言：英文提示 → 英文网页，中文 → 中文。spec 里记下
meta.language
。

Organize the reaction into a structured spec (see

references/problem-schema.md

for format): reactants/products, atomic mapping or explicit atoms, conditions (ignition/electrification/catalysis/reversibility), category, step-by-step explanations, and language.

Text Reaction/Equation: Directly extract reactants and products, and call the kernel to automatically balance the equation.
Image: Use visual recognition to extract the equation, and display the recognized reaction to the user for confirmation (equation/conditions/category/language) before proceeding.
Random Question Generation: Select a reaction from the registry, or combine species from the library, balance using
```
balanced_coefficients
```
, and standardize the answer before use.

Output Language Follows Prompt Language: English prompts → English webpage, Chinese prompts → Chinese webpage. Record
meta.language
in the spec.

第 2 步：用 kernel 精确计算（不要心算）

Step 2: Precise Calculation with Kernel (Do Not Calculate Manually)

按

references/conventions.md

的建模约定，调用

lib/reaction_kernel.py

：

```
balanced_coefficients(...)
```
用 sympy 零空间自动配平（方程系数有保证）；
```
assemble_data(spec)
```
展开分子实例、校验原子守恒与原子映射双射、推导键的断/成（差集）、算出每个原子在反应物态/产物态的世界坐标，产出注入模板的
```
data
```
。

可先命令行自检：

bash

python3 lib/reaction_kernel.py     # 配平 + 守恒 + 键差 自检
python3 lib/molecules.py           # 分子库自检

Follow the modeling conventions in

references/conventions.md

and call

lib/reaction_kernel.py

```
balanced_coefficients(...)
```
uses sympy's null space to automatically balance equations (equation coefficients are guaranteed);
```
assemble_data(spec)
```
expands molecular instances, verifies atom conservation and bijective atomic mapping, deduces bond breaking/forming (difference set), calculates the world coordinates of each atom in reactant/product states, and generates
```
data
```
to be injected into the template.

You can perform a command-line self-check first:

bash

python3 lib/reaction_kernel.py     # Self-check for balancing + conservation + bond difference
python3 lib/molecules.py           # Self-check for molecular library

第 3 步：写 build_* 拼 spec 并注入模板

Step 3: Write build_* Functions to Assemble Spec and Inject into Template

📍 输出位置（重要）：成品 HTML 一律写到用户当前工作目录（
Path.cwd()
），除非用户显式指定路径。 绝不要写进技能自身目录（
skills/edu-chem-reaction/output/
等）——那是技能内部的开发样例目录。

照着

scripts/generate.py

里的

build_*

改即可，再

render_html(K.assemble_data(spec), out)

：

python

from pathlib import Path
out = Path.cwd() / "reaction-<反应简述>.html"   # 落在用户当前目录
render_html(K.assemble_data(spec), out)

范例（直接照抄改）：

```
build_combustion_ch4
```
（甲烷燃烧·morph·火焰·能量）——高层
```
species + atom_map
```
的范本；
```
build_redox_na_cl2
```
（钠+氯气·氧化还原·电子转移）——叠加
```
electrons
```
；
```
build_esterification
```
（酯化·mechanism·催化剂·过渡态）——低层
```
atoms + fragments + 关键帧
```
的范本。

generate.py

可直接出已注册反应；不传路径默认写到 cwd：

bash

python3 <技能目录>/scripts/generate.py combustion_ch4 ./reaction.html
python3 <技能目录>/scripts/generate.py list

📍 Output Location (Important): The final HTML file must be written to the user's current working directory (
Path.cwd()
), unless the user explicitly specifies a path. Never write to the skill's own directory (such as
skills/edu-chem-reaction/output/
)—that is the internal development sample directory for the skill.

Modify the

build_*

functions in

scripts/generate.py

as needed, then call

render_html(K.assemble_data(spec), out)

python

from pathlib import Path
out = Path.cwd() / "reaction-<brief-reaction-description>.html"   # Saved in user's current directory
render_html(K.assemble_data(spec), out)

Examples (Copy and Modify Directly):

```
build_combustion_ch4
```
(Methane Combustion · morph · Flame · Energy) — A template for high-level
```
species + atom_map
```
;
```
build_redox_na_cl2
```
(Sodium + Chlorine · Redox · Electron Transfer) — With
```
electrons
```
overlay;
```
build_esterification
```
(Esterification · mechanism · Catalyst · Transition State) — A template for low-level
```
atoms + fragments + keyframes
```
.

generate.py

can directly generate registered reactions; if no path is specified, it defaults to writing to cwd:

bash

python3 <skill-directory>/scripts/generate.py combustion_ch4 ./reaction.html
python3 <skill-directory>/scripts/generate.py list

第 4 步：自检（对应正确性方案）

Step 4: Self-Check (Corresponding Correctness Plan)

sympy 配平系数 == 方程展示系数 == 各分子实例个数（
```
assemble_data
```
内已断言）。
原子映射是反应物↔产物原子的双射、元素一致；键端点都存在（kernel 已校验）。
原子守恒计数器在反应前后不变（催化剂不计入）。
起本地静态服务（服务输出文件所在目录）用预览检查：无控制台报错、KaTeX 方程渲染正常、拖滑块时断键/成键高亮与分步讲解一致。

⚠️ 必须关闭你开过的端口/服务：预览检查一结束就立即停掉本地服务，绝不留下占用端口的进程。用 preview 工具开的：检查完马上
preview_stop
。交付前确认端口已释放，再告诉用户结果。

sympy balanced coefficients == equation display coefficients == number of each molecular instance (already asserted in
```
assemble_data
```
).
Atomic mapping is a bijection between reactant and product atoms, with consistent elements; all bond endpoints exist (verified by the kernel).
The atom conservation counter remains unchanged before and after the reaction (catalysts are not included).
Start a local static server (serving the directory where the output file is located) for preview checks: no console errors, KaTeX equations render correctly, and bond breaking/forming highlights match step-by-step explanations when dragging the slider.

⚠️ Must Close Opened Ports/Services: Stop the local server immediately after preview checks are completed, never leave port-occupied processes running. If using the preview tool: run
preview_stop
right after checking. Confirm the port is released before delivering the result to the user.

第 5 步：交付

Step 5: Delivery

成品写在用户当前工作目录（cwd），命名形如

reaction-<反应简述>.html

，把路径告诉用户，可直接浏览器打开。交付前确认：(1) 成品在 cwd、不在技能目录；(2) 没有遗留任何由本次预览开启的本地服务/端口。

The final product is saved in the user's current working directory (cwd) with a name like

reaction-<brief-reaction-description>.html

. Inform the user of the path, which can be directly opened in a browser. Before delivery, confirm: (1) The final product is in cwd, not in the skill directory; (2) No local services/ports opened during this preview are left running.

两套引擎与自动选择

Two Engines and Automatic Selection

模板内置一套统一渲染器、两种逐帧定位（共用键差绘制/标签/叠加层/UI）：

morph（原子变形）：原子各自从反应物态插值到产物态，天然展示原子守恒/重组，适配任意反应。
mechanism（机理关键帧）：原子归属刚体片段（fragment），按 K0/K1/K2 关键帧整体位移，基团不变形，适配催化剂/过渡态/离去基团类有机机理。

assemble_data

据

meta.engine

（

auto

morph

mechanism

）选择：

auto

时，类别为

organic

或带

fragments

走 mechanism，否则走 morph。叠加层均为数据开关（见 schema）：

flame

（燃烧/强放热）、

catalyst

（催化剂质子+开关）、

transitionGlow

（过渡态能量光）、

electrons

（氧化还原电子转移）、

energy

（能量-反应进程曲线）、原子守恒计数器（默认开）。

配色：整体为亮色（教科书球棍图风：原子带深色描边 + 柔和投影 + 白底面板），各反应用

meta.accent

区分强调色（燃烧 amber、酯化 indigo、钠氯 violet…）。

The template has a built-in unified renderer and two frame-by-frame positioning methods (sharing bond difference rendering/labels/overlays/UI):

morph (Atomic Deformation): Each atom interpolates from the reactant state to the product state, naturally demonstrating atom conservation/recombination, suitable for any reaction.
mechanism (Mechanism Keyframes): Atoms belong to rigid fragments, and move as a whole according to K0/K1/K2 keyframes. Functional groups do not deform, suitable for organic mechanisms involving catalysts/transition states/leaving groups.

assemble_data

selects the engine based on

meta.engine

(

auto

morph

mechanism

): When set to

auto

, if the category is

organic

or includes

fragments

, it uses the mechanism engine; otherwise, it uses the morph engine. All overlays are data-driven switches (see schema):

flame

(combustion/strong exothermic reactions),

catalyst

(catalyst protons + switch),

transitionGlow

(transition state energy glow),

electrons

(redox electron transfer),

energy

(energy-reaction progress curve), and atom conservation counter (enabled by default).

Color Scheme: Overall bright color scheme (textbook ball-and-stick style: atoms with dark strokes + soft shadows + white background panels). Each reaction uses

meta.accent

to distinguish accent colors (amber for combustion, indigo for esterification, violet for sodium-chlorine reactions, etc.).

扩展

Expansion

加反应：在
```
generate.py
```
加一个
```
build_*
```
（高层
```
species+atom_map
```
，或低层
```
atoms+fragments
```
），注册进
```
REGISTRY
```
。
加分子/离子：在
```
lib/molecules.py
```
的
```
_LIBRARY_BUILDERS
```
加一项（VSEPR 几何 + 显示元数据 + 内部键）。
加叠加层：在
```
template/reaction.html
```
增一个由
```
data
```
字段驱动的可选模块。

Add Reactions: Add a
```
build_*
```
function (high-level
```
species+atom_map
```
or low-level
```
atoms+fragments
```
) to
```
generate.py
```
and register it in
```
REGISTRY
```
.
Add Molecules/Ions: Add an entry to
```
_LIBRARY_BUILDERS
```
in
```
lib/molecules.py
```
(VSEPR geometry + display metadata + internal bonds).
Add Overlays: Add an optional module driven by the
```
data
```
field in
```
template/reaction.html
```
.

edu-chem-reaction

Original

Translation

化学反应微观演示 → 交互网页

Microscopic Demonstration of Chemical Reactions → Interactive Webpage

这个技能产出什么

What This Skill Produces

依赖（重要）

Dependencies (Important)

工作流程

Workflow

第 1 步：得到 reaction spec（三入口归一）

Step 1: Obtain Reaction Spec (Unified Three Entry Methods)

第 2 步：用 kernel 精确计算（不要心算）

Step 2: Precise Calculation with Kernel (Do Not Calculate Manually)

第 3 步：写 build_* 拼 spec 并注入模板

Step 3: Write build_* Functions to Assemble Spec and Inject into Template

第 4 步：自检（对应正确性方案）

Step 4: Self-Check (Corresponding Correctness Plan)

第 5 步：交付

Step 5: Delivery

两套引擎与自动选择

Two Engines and Automatic Selection

扩展

Expansion

目录

Directory