---
name: md-structure-check
description: 跑 MD 之前对蛋白质结构做体检,按"MD 修得好 / 修不好"分级报告问题。当用户准备用 CHARMM-GUI、tleap、pdb2gmx 等工具建库,或提到同源模型、PDB 上传报错、单点能量异常巨大、D 型氨基酸、手性、顺式肽键、原子重叠、缺失原子、膜蛋白拓扑朝向时使用。也用于横向比较多个待模拟体系是否一致。
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/check_structure.py *) Read
---

# MD 建模前结构体检

跑 `${CLAUDE_SKILL_DIR}/check_structure.py`,然后**按下面的方式解读结果** —— 解读比跑脚本重要。

```bash
python3 ${CLAUDE_SKILL_DIR}/check_structure.py <文件...> [--membrane] [--normal z] [--quiet]
```

脚本零依赖(纯标准库),不需要 numpy/conda 环境,任何有 python3 的机器都能跑。
支持 `.pdb` 和 `.gro`。多个文件一起传会额外做**横向一致性对比**。

## 核心原则:先分清"修得好"和"修不好"

这是本 skill 存在的理由。用户看到一个巨大的单点能量时,第一反应通常是"结构坏了要重做",
但实际上**大部分问题极小化会自己解决**,而真正致命的那几个反而不显眼。

| 级别 | 含义 | 该怎么办 |
|---|---|---|
| **A** | **跑 MD 永远修不好** | **必须建模前修掉**,否则错误会一路带进所有下游结果 |
| B | 极小化能修好 | 照常往下走。建库时单点能量高是正常的 |
| C | 文件格式问题 | 上传/解析会直接失败,必须先修 |
| D | 膜蛋白拓扑几何 | 脚本只报事实,**需要人工判断是否符合真实拓扑** |
| E | 多体系不一致 | 单看每个都正常,放一起才暴露 —— 横向比较的前提 |

**A 级为什么修不好**:手性、顺式肽键、穿环这些是**拓扑层面**的错误。把 D 型变成 L 型需要
断键再重接,而分子动力学从头到尾不断键。所以跑多久都没用。

**B 级为什么不用慌**:键长、键角、原子重叠是**几何**问题,能量极小化推一推就好了。
一个未经优化的同源模型报出几千甚至几百万的单点能量都属正常。

## 报告怎么读

### 看到 A 级问题
明确告诉用户:**这个跑模拟修不好,必须现在修**。并说明后果 —— 错误会存在于整条数据链里,
而且往往在最终结果里表现为"某个体系莫名其妙地不一样",很难追溯。

常见 A 级问题的修法:
- **D 型氨基酸**:把该残基的侧链沿 N–CA–C 平面镜像翻转即可。⚠️ 若该残基的 CA–CB 键长本身
  就严重异常(侧链塌在主链上),单纯镜像会把塌陷转到另一侧、制造新的重叠 —— 这种要重建 CB
  到理想位置,再把侧链刚体跟随。**修完一定要重跑本检查确认重叠数没变多。**
  另外 Ile 和 Thr 的 CB 是第二手性中心,整条侧链镜像对它们是安全的(无内部手性中心),
  但对含有第二手性中心的侧链要单独处理。

  **重建 CB 的标准构造**(键长 1.530 Å,Engh & Huber 值):
  ```
  a = unit(N-CA); b = unit(C-CA); d = -unit(a+b); p = unit(cross(a,b))
  cos(α) = cos(110.5°) / (d·a)              # p 取正向即得 L 型
  CB = CA + 1.530 * (d*cos α + p*sin α)
  ```
  ⚠️ **必须先断言 N–CA–C < 139°**。因为 d·a = -cos(t/2),当 t > 139° 时 |cos α| > 1;
  此时若用 clip 兜住,会得到 α=0 —— CB 被放进 N–CA–C 平面里,行列式为 0、**没有手性,
  而且不会报任何错**。这是最危险的静默失效模式,越界时应当直接报错而不是 clip。
  (正常结构 t ≈ 111°,很安全;但畸变的 MD 帧或粗糙建模产物可能越界。)

  该构造会把 N–CA–CB 和 C–CA–CB **都**定成 110.5°,而理想值是 110.5/110.1 的非对称组合。
  实测影响 < 0.001 Å,可以接受。

- **侧链构象(rotamer)冲突**:沿可旋转二面角转动侧链,内部几何完全不变。
  ⚠️ **脯氨酸必须排除** —— 它的侧链是闭环、经 CD 连回主链 N,当成普通侧链转会把主链拽走。
- **顺式肽键(非 Pro)**:需要重新建模该处主链。
- **穿环**:拓扑打结,必须重建,极小化只会把结锁死。
- **缺失重原子**:多数建库工具会自动补,但补出来的位置未必合理;缺主链原子必须先修。

### 看到 B 级问题
说明这些**不阻塞**,并预告用户建库时会看到偏高的单点能量,那是正常的。
但要提醒:如果最短原子间距 < 1.0 Å,单点能量会到千万级 —— 数字吓人,不代表结构没救。

### 看到 D 级(膜蛋白)
脚本只报**事实**(主轴角度、N/C 端在哪一侧、疏水段位置、K/R 分布),**不判断对错**。
必须结合真实生物学拓扑人工确认,重点问:
- C 端应该在胞质侧还是胞外侧?胞质侧对应含 **PS/PE 的内叶**,胞外侧对应含 **PC 的外叶**。
- Lys/Arg 富集的那一侧是不是胞质侧?(positive-inside 规则)
- 主轴角度为 0° 说明是人为摆正的理想起点 —— 这没问题,平衡后会自己倾斜到天然倾角(通常 10–30°)。

### 看到 E 级不一致
这是最容易被漏掉的一类。多个体系要做横向比较时,**朝向、端基、长度必须一致**,
否则比较的是不同的东西。尤其注意"其中一个体系朝向和其他都相反"这种情况。

## 用完之后

修改过结构后**务必重跑一次本检查**,确认:
1. A 级问题清零;
2. **B 级的原子重叠数量没有变多** —— 修 A 级时很容易制造新的重叠。

建完库拿到单点能量后,可以回头对照:能量在几千量级 = 正常;千万量级 = 大概率还有 A 级问题没清干净。