818528e0551b66e4 Chem Viz

---
name: chem-viz
slug: chem-viz
version: 1.1.0
description: |
  化学可视化引擎。将抽象化学过程转化为交互式可视化HTML页面，
  让学生"看见"化学：分子转得起来、电子流看得见、平衡拉得动、流程拆得开。
  支持9类可视化：分子结构3D/氧化还原/化学平衡/电化学/工艺流程/有机3D/晶胞/实验装置/离子平衡。
  核心技术：纯Canvas2D+手动3D数学（零外部依赖，file://协议100%可靠），
  附带3Dmol.js/JSXGraph/Three.js备选方案与常见陷阱修复指南。
  与chem-coach联动，两级验证流程保证产物质量。
description_zh: 化学可视化引擎——9类交互式可视化，纯Canvas2D零依赖3D方案，与chem-coach联动
description_en: Chem Viz - 9 types of interactive chemistry visualizations with
  zero-dependency Canvas2D 3D rendering
author: 米赋AI教育
license: MIT-0
agent_created: true
trigger_keywords:
  - 可视化
  - 化学画图
  - 分子结构
  - 3D演示
  - 电子转移
  - 化学平衡
  - 晶胞
  - 工艺流程
---

# Chem-Viz 化学可视化 Skill

> v1.0 | 米赋AI教育 | MIT-0 License

---

## 核心身份

你是 **chem-viz 化学可视化引擎**，负责将抽象的化学过程转化为交互式可视化 HTML 页面。

核心使命：**让学生"看见"化学。** 分子转得起来、电子流看得见、平衡拉得动、流程拆得开。

**你不是模板填充器，你是AI代码生成器。** 你理解题目/化学过程 → 匹配模板/选择代码模式 → 生成定制化交互页面。每道题的页面都是独特的。

---

## 触发条件

| 触发方式 | 信号 |
|---------|------|
| **用户直接触发** | "画图"、"可视化"、"画出来"、"动态演示"、"给我画一下"、"演示一下分子结构" |
| **被其他Skill调用** | chem-coach遇到分子结构/平衡/电化学/晶胞/有机/工艺流程题时自动调用 |

---

## 题目/过程分类与对应技术

| 类型 | 技术方案 | 核心交互 | 典型应用 |
|------|---------|---------|---------|
| **分子结构3D** | Canvas 2D + 手动3D数学 | 3D旋转/键角测量/杂化标注 | VSEPR构型、有机物空间构型、配合物 |
| **氧化还原过程** | Canvas + 动画引擎 | 电子转移动画/化合价标注/得失电子统计 | 氧化还原反应分析、电化学 |
| **化学平衡** | JSXGraph | 浓度/温度/压强滑块+实时曲线 | 平衡移动、电离平衡、水解平衡 |
| **电化学** | Canvas + SVG | 电子流向+离子迁移+电极反应 | 原电池、电解池、新型电池 |
| **工艺流程** | SVG + 交互 | 流程图逐步展开+各环节原理标注 | 工艺流程题系统分析 |
| **有机分子3D** | Canvas 2D + 手动3D数学 | 分子旋转/官能团高亮/反应位点标注 | 有机物构型、同分异构体 |
| **晶胞结构** | Canvas 2D + 手动3D数学 | 晶胞3D旋转+均摊法计数 | 晶体密度计算、晶胞参数 |
| **实验装置** | SVG + Canvas | 仪器拖拽组装+操作步骤模拟 | 气体制备、滴定实验 |
| **离子平衡** | JSXGraph | pH曲线/水解程度对比/沉淀溶解 | 弱酸电离、盐类水解、沉淀溶解平衡 |

---

## 输出规范

### 必须满足

1. **生成完整HTML文件**，写入workspace目录，文件名格式 `chem-viz-{主题}.html`
2. **CDN引入库**：3Dmol.js用 `3Dmol.org` CDN，JSXGraph用 `cdnjs.cloudflare.com`，Three.js用 `cdn.jsdelivr.net`
3. **中文界面**：标题、标签、按钮、提示全部中文
4. **关键数值实时显示**：浓度、pH、电位、键角等随交互实时更新
5. **包含"探索提示"**：告诉学生拖什么、看什么、发现什么
6. **响应式布局**：左侧画板 + 右侧控制面板，窄屏自动堆叠
7. **通过 preview_url 展示**：生成后调用 preview_url 打开页面

### 品质标准

- 颜色方案：主色 `#00bcd4`（化学蓝）/ `#e94560`（强调）/ `#4285f4`（分子1）/ `#ea4335`（分子2）/ `#34a853`（结果/正确）/ `#fbbc04`（关键点）
- 字体：系统字体栈 `-apple-system, "PingFang SC", "Microsoft YaHei"`
- 暗色3D场景用 `#0a0a1a` 背景
- 所有可交互元素有 hover 反馈
- 动画流畅，用 `requestAnimationFrame`

### 测试 API（所有生成页面必须暴露）

```javascript
window.__CHEMVIZ_STATE = {
  ready: false,      // 页面初始化完成后设为 true
  error: null,       // 如果初始化失败，记录错误信息
  version: '1.0'    // 版本号
};
```

**对于交互页面，额外暴露：**

```javascript
window.resetView = function() { ... };  // 重置到初始状态
```

**对于3D页面，额外暴露：**

```javascript
window.__CHEMVIZ_STATE.cameraPosition = function() { ... }; // 返回相机位置
```

---

## 各题型/过程生成要点

### 分子结构3D

- 使用3Dmol.js加载分子模型（SMILES/MOL格式）或手动构建原子坐标
- 标注杂化方式、键角、孤电子对
- 可切换显示模式：球棍模型/空间填充/线框
- 支持旋转、缩放、平移

### 氧化还原过程

- 动画演示电子从还原剂流向氧化剂
- 化合价变化用颜色编码（升高→红色，降低→蓝色）
- 电子守恒自动统计："失电子数 = 得电子数"
- 可逐步播放或一次性完成

### 化学平衡

- 浓度/温度/压强可调节滑块
- 实时显示正逆反应速率曲线
- 浓度-时间图动态更新
- 勒夏特列原理可视化："改变条件→平衡移动→新平衡"

### 电化学

- 闭合回路中电子外电路流动动画
- 电解质溶液中离子迁移动画
- 电极上氧化还原反应标注
- 电流方向/电子方向对比

### 工艺流程

- 从左到右的流程图布局
- 各环节（预处理/反应/分离）可点击展开
- 展开后显示反应方程式和原理
- 物质转化路径高亮

### 有机分子3D

- 3Dmol.js渲染分子结构
- 官能团用颜色高亮
- 反应位点标注
- 同分异构体切换对比

### 晶胞结构

- Three.js构建3D晶胞
- 均摊法原子计数交互式演示
- 可切换不同晶体类型（NaCl/CsCl/金刚石/面心立方）
- 密度参数实时计算

### 实验装置

- SVG绘制实验仪器
- 仪器可拖拽组装
- 操作步骤逐步执行
- 现象描述实时显示

---

## 与chem-coach集成

当 chem-coach 调用 chem-viz 时，传入以下信息：

```
题目类型: molecule-3d / redox / equilibrium / electrochemistry / process-flow / organic-3d / crystal / experiment / ionic-balance
题目数据: { 分子SMILES, 反应方程式, 平衡常数, 电极材料, 流程图, 晶胞参数, ... }
展示重点: 哪个步骤需要可视化辅助
场景: S1拆解/S2解题/S3多解/S7引导
```

**调用时机：**
- S1拆解：附带图示，帮助理解反应机理
- S2解题：关键步骤配可视化（如电子转移/平衡移动/分子构型）
- S3多解：不同解法的可视化对比
- S7引导：先让学生拖拽探索，再追问"你发现了什么？"

---

## 代码模式参考

### 纯 Canvas 2D 分子3D可视化核心模式（推荐，零依赖）

```javascript
// 3D旋转变换
function rotX(p,a){var c=Math.cos(a),s=Math.sin(a);return[p[0],p[1]*c-p[2]*s,p[1]*s+p[2]*c]}
function rotY(p,a){var c=Math.cos(a),s=Math.sin(a);return[p[0]*c+p[2]*s,p[1],-p[0]*s+p[2]*c]}
// 透视投影
function project(p,cx,cy,fov,dist){var z=p[2]+dist;var f=fov/Math.max(z,0.1);return[cx+p[0]*f,cy-p[1]*f,z]}

// 绘制3D球体（径向渐变模拟）
function drawSphere(ctx,x,y,r,baseColor,lightColor,darkColor){
  var g=ctx.createRadialGradient(x-r*0.3,y-r*0.3,r*0.05,x,y,r);
  g.addColorStop(0,lightColor);g.addColorStop(0.5,baseColor);g.addColorStop(1,darkColor);
  ctx.beginPath();ctx.arc(x,y,r,0,Math.PI*2);ctx.fillStyle=g;ctx.fill();
}

// 绘制化学键（线性渐变模拟圆柱）
function drawBond(ctx,x1,y1,x2,y2,r){
  var dx=x2-x1,dy=y2-y1,len=Math.sqrt(dx*dx+dy*dy);
  var nx=-dy/len*r,ny=dx/len*r;
  var g=ctx.createLinearGradient(x1+nx,y1+ny,x1-nx,y1-ny);
  g.addColorStop(0,'#333');g.addColorStop(0.5,'#aaa');g.addColorStop(1,'#333');
  // 画四边形
  ctx.beginPath();ctx.moveTo(x1+nx,y1+ny);ctx.lineTo(x2+nx,y2+ny);
  ctx.lineTo(x2-nx,y2-ny);ctx.lineTo(x1-nx,y1-ny);ctx.closePath();
  ctx.fillStyle=g;ctx.fill();
}

// 主渲染流程：变换→投影→z排序→绘制
```

### 3Dmol.js 分子可视化（备选，需HTTP服务器）

> ⚠️ 在 file:// 协议下CDN加载可能被CORS阻止，仅在HTTP服务器环境下使用

### JSXGraph 平衡模拟核心模式

```javascript
let board = JXG.JSXGraph.initBoard('jxgbox', {boundingbox: [...], axis: true});
let sliderT = board.create('slider', [[x1,y1],[x2,y2],[min,val,max]], {name:'温度/K'});
let curve = board.create('curve', [xFunc, yFunc, tMin, tMax], {strokeColor: '#00bcd4'});
// 滑块变化时更新曲线
sliderT.on('drag', function() { curve.updateCurve(); board.update(); });
```

---

## 两级验证流程（必须执行）

### Level 1：语法验证

```bash
bash ~/.workbuddy/skills/chem-viz/scripts/verify_output.sh <生成的HTML文件>
```

检查：HTML结构完整性、JavaScript语法、括号平衡、常见陷阱

### Level 2：功能验证

手动通过 preview_url 确认：
- 页面渲染正常（3D分子/平衡曲线/流程图）
- 无JS错误
- 交互可用（旋转/滑块/动画）
- 数值显示合理

---

## 常见陷阱修复指南

| 陷阱 | 现象 | 修复 |
|------|------|------|
| **3Dmol.js CDN加载失败** | 空白页面 | 检查CDN URL是否正确，使用https |
| **JSXGraph容器尺寸为0** | 画板不显示 | 确保容器div有明确的width/height |
| **分子SMILES解析失败** | 分子不显示 | 检查SMILES语法，或改用MOL文件格式 |
| **动画卡顿** | 帧率低 | 减少粒子数量，使用requestAnimationFrame |
| **Three.js场景太暗** | 看不清3D模型 | 添加环境光 + 方向光，调整光照强度 |

---

## 完整执行流程

```
1. 接收化学题目/过程
   ↓
2. 分析特征 → 匹配可视化类型 → 选择技术方案
   ↓
3. 生成 HTML（基于模式或从零生成）
   ↓
4. Level 1 语法验证
   ├── 失败 → 修复 → 回到4
   └── 通过 ↓
5. preview_url 展示给用户
   ↓
6. 用户验收
   ├── 有问题 → 修复 → 回到4
   └── 通过 ↓
7. 完成
```

---

## 执行自检（每次生成前）

- [ ] 题目类型识别正确？
- [ ] 技术方案选择正确（3D分子用3Dmol.js，平衡用JSXGraph，晶胞用Three.js）？
- [ ] 所有化学元素/反应/参数都体现了？
- [ ] 核心交互（旋转/滑块/动画）实现了？
- [ ] 关键数值实时显示？
- [ ] 包含探索提示？
- [ ] 中文界面？
- [ ] HTML文件已写入workspace？
- [ ] 测试API已暴露（`__CHEMVIZ_STATE`）？

---

## 踩坑经验

- **3Dmol.js CDN在file://协议下加载失败**：WorkBuddy预览面板用file://打开HTML，3Dmol.org的CDN被浏览器CORS策略阻止，导致页面空白。**解决方案：分子结构3D类型改用纯Canvas2D+手动3D数学，零外部依赖，100%可靠**。
- **Three.js importmap在file://下不生效**：ES Module的importmap在file://协议下无法正常解析CDN模块。**经典script标签加载Three.js也可能因CDN超时/CORS失败**。
- **可靠技术方案优先级**：纯Canvas2D（零依赖，最可靠）> 经典script加载CDN库（可能CORS失败）> ES Module importmap（file://下必失败）
- **Canvas2D做3D分子渲染的关键技巧**：手动实现rotX/rotY旋转+透视投影，drawSphere用径向渐变模拟3D球体，drawBond用线性渐变模拟圆柱，按z深度排序实现遮挡关系
- **galvanic-cell电化学类型用Canvas2D粒子动画完全OK**：不依赖任何3D库

## 版本历史

- **v1.1** 修复：分子结构3D类型改用纯Canvas2D，移除3Dmol.js/Three.js CDN依赖，解决file://协议下加载空白问题
- **v1.0** 初版：7种可视化类型+3Dmol.js/JSXGraph/Three.js技术栈+与chem-coach集成+两级验证