---
name: baoyu-protein-structure-workbench
description: Use when 做蛋白结构/结构域/性能关联工作台。
version: 1.0.0
author: Hermes (zone-b)
license: internal
metadata:
  hermes:
    tags: [protein, pymol, uniprot, pdb, alphafold, 工作台]
    related_skills: [baoyu-workbench-patterns, baoyu-html-inline-svg-figures]
---

# 蛋白结构与性能关联工作台

## When to Use

- 要把酶（Taq、Tth、M-MLV RT、UNG、Bst、Pfu…）做成「三维结构 + 结构域 + 序列 + 性能」的查询工具
- 客户或销售问「这个酶的哪个结构域决定什么性能」「突变体为什么不一样」
- 需要把 UniProt / PDB / AlphaFold / PubMed 四路数据合成一个自包含页面

## 四层数据，顺序不能乱

1. **UniProt**（序列 + 结构域 + 活性位点 + 变异位点）——先拿 accession，不要靠记忆写序列。
2. **PDB**（实验结构）——按覆盖度挑，不是按分辨率挑（见下）。
3. **AlphaFold DB**（预测补全）——实验结构缺的区段才用，必须标「预测」。
4. **PubMed**（性能关联）——只收有 PMID 的，且要读摘要，不能只看标题。

API 细节与代码片段见 `references/protein-data-apis.md`。

## 结构选择：覆盖度优先于分辨率

```python
coverage = deposited_polymer_monomer_count / uniprot_length
```

实测教训：Taq 分辨率最好的 6FBC（1.54 Å）只有 540 aa，**缺整个 5′→3′ 外切域**；1TAQ 只有 2.4 Å 却覆盖 10–832。要展示外切域就必须用 1TAQ。

- 先按覆盖度排序，再在覆盖度相近的里面挑分辨率。
- 结构拿不到全长时，图上必须标「解析区间」，不要让人以为是全长。
- 同一蛋白的实验结构区间会因构建体而差异很大（Tth 8XK9 只解析 296–832，外切域无序）。

## PyMOL 安装与出图（macOS arm64）

```bash
curl -Ls https://micro.mamba.pm/api/micromamba/osx-arm64/latest -o /tmp/mm.tar.bz2
tar -xjf /tmp/mm.tar.bz2 -C /tmp bin/micromamba
cp /tmp/bin/micromamba ~/.local/bin/micromamba
~/.local/bin/micromamba create -y -n pymol -c conda-forge pymol-open-source
```

- 用 **开源版** `pymol-open-source`（BSD 类许可，内部商用可用）；不要装 Schrödinger 版（商用需付费授权）。
- 本机无 conda 时用 micromamba 单文件，不污染系统 Python。
- 1400×1400 `ray=1` 约 1 秒，CPU 即可，不需要 GPU。

## 实验区 / 预测区双色渲染

```pml
load AF-<acc>.pdb, af
load <pdb>.pdb, exp
align exp, af
hide everything, exp
show cartoon, af
color grey80, af
color marine, af and byres (af within 2.5 of exp)
bg_color white
set ray_opaque_background, off
png out.png, width=1400, height=1400, dpi=150, ray=1
```

页面图例必须写清：深蓝＝实验解析（PDB 号 + 区间），浅灰＝AlphaFold 预测（区间 + pLDDT）；结构域轨道里预测区再加**斜纹底纹**，不能只靠颜色区分。

可复用脚本：`scripts/render_overlay.py`。

## PyMOL 四条静默失败坑

1. **选择名不能含中文或连字符**：`select d_5_3外切` 不会报错，但颜色不生效，整张图默认全绿。只用 `dom0`、`dom1` 这类 ASCII 名。
2. **`turn` 必须带逗号**：`turn x 10` 报 `missing required argument`；写 `turn x, 10`。
3. **mmCIF 不能按 PDB 的列位解析**：`line[21]` 取链在 cif 里是错的；先 `load x.cif, m; save x.pdb, m` 转成 PDB 再处理。
4. **直链下载 AlphaFold 会 403**：文件 URL 需要浏览器 UA；更稳的是先请求 `https://alphafold.ebi.ac.uk/api/prediction/<acc>` 拿 `pdbUrl`（返回的 entry 可能按结构域切成多段，选覆盖最长的那段）。

## 性能关联：只收 PMID，且要读摘要

- 每条关联写成「论断 | 结构域 | PMID | 证据强度」。
- 只写摘要能直接支持的；间接推断标「间接」或干脆不收。
- 未读原文的条目标「候选」，不要写成结论——用户会核对。

## 页面结构（已验证）

```
蛋白切换按钮（4 个）
└─ 面板
   ├─ 左：交互式三维视图（3Dmol 内嵌，可缩放/点击残基）+ 图例
   ├─ 右：关键事实表（UniProt / 长度 / 实验结构 / 解析区间 / 预测补全 / RMSD / 用途）
   ├─ 通栏：结构域轨道（SVG，斜纹=预测）
   ├─ 序列（按结构域着色，催化位点深红）
   └─ 关联表（论断 / 结构域 / PMID 链接 / 证据强度 / 文献标题）
```

- 结构域轨道必须**通栏**：放在半栏里会被压到 5px 字，标签看不清。
- 图片转 JPEG（quality 88，1000px）再 base64，4 张图约 0.9 MB，单文件可交付。
- 首个面板必须带 `on` 类，否则首屏空白。

## 交互式三维查看器（3Dmol，零外链）

用户明确要求「结构图要能放大查看，力争到氨基酸维度」——静态 PNG 不够，必须内嵌可交互查看器。

- `3Dmol-min.js`（约 545 KB）**全文 inline** 进 `<script>`，PDB 用 `<script type="text/plain">` 内嵌，不要 CDN。
- **切到该蛋白 Tab 再 init**：隐藏容器宽度为 0，`createViewer` 会初始化失败；用 `V[key]` 缓存，只建一次。
- 按结构域着色并与轨道同色：`setStyle({},{cartoon:{colorfunc:a=>colorFor(k,a.resi)}})`。
- 残基定位（「放大到氨基酸」最可靠的做法）：输入编号 → `selectedAtoms({resi:n})` → 加 stick + 红标签 → `zoomTo({resi:n})`。
- 验收：`window.__V[k].getModel().selectedAtoms({}).length > 0`，并实测已知位点（Taq 667、UNG 64）能否出标签。

三个坑：
1. **结构域颜色必须和轨道一致**，否则用户直接反馈「结构域在图上没有体现」。
2. **多聚蛋白编号体系不同**（MMLV 的 PDB 构造编号 24–487 ≠ UniProt 741–1320），跨体系必须做偏移映射，或直接用 AlphaFold 的 UniProt 编号模型。
3. 直接 `micromamba run ... pymol x.pml` 可能被本机守卫拦；改用 Python 脚本 subprocess 调用，PML 落盘到工作目录（不要 `/tmp`）。

实现细节见 `references/interactive-viewer.md`。

## 销售场景层（把结构知识变成销售动作）

用户要的不是「培训材料」，而是能支撑客户对话的东西。已验证的结构：

1. **PCR 机理图**：变性/退火/延伸三步 × 对应结构域（耐热、Mg²⁺/引物竞争、手掌域催化、拇指域持续合成、外切域切探针）。
2. **场景卡**：每张固定六段——客户原话 → 技术根因（落到结构域）→ 要问的 3 个问题 → 品类方案 → **不能承诺** → 对应结构域。
3. **对话演练**：三段式（确认现状 → 归因到结构域 → 给方案与边界），不是一上来推产品。
4. **自测 10 题**：判分，低于 8 分回看场景卡。

**场景顺序必须用自己数据排**：扫活动记录 + 客诉库词频（实测：冻干 2,397、Ct 851、一步法 718、多重 538、批间差 359/客诉 71），不要拍脑袋。

**交付颗粒度默认品类级**，货号列留空（等 ERP 核对后填），避免销售拿错号；同时保留「品类 → 货号」扩展表。

## 交付形态：先独立，后集成

用户会先要「第五个 TAB」，但看到工作量后会改为「先做独立自包含 HTML」。默认顺序：

1. 先出**独立单文件页面**（45 KB 级，零外链），验收通过再谈集成；
2. 集成到工作台时，先把工作台回滚到无新增 TAB 的版本，避免半成品混在主文件里；
3. 独立页与工作台共用同一套内容生成逻辑，避免两处漂移。

## 验收清单

- [ ] 每个蛋白面板都能切换，默认第一个可见
- [ ] 图片 `naturalWidth > 0`（base64 没断）
- [ ] 序列长度与 UniProt 一致（MMLV 这类多聚蛋白要标明截取区间）
- [ ] 每条性能关联都有 PMID 链接
- [ ] 预测区在图上和轨道上都有标注（颜色 + 斜纹 + 文字）
- [ ] 390/1440 无横向溢出，控制台无报错
- [ ] 若 390px 被 `brand_kit` 顶栏撑宽（`.bior-tagwrap` / `.bior-slogan`），加 `@media(max-width:900px){.bior-tagwrap{display:none!important}}`；品牌信息仍在 DOM，不影响 `BK.verify`