RDKit 自动化（Python 工具包）
> v1.0.0（2026-09-26）：首版。全部配方在本机 C:\WINDOWS\system32\rdkit-env（Python 3.13 + rdkit 2026.03.6）真实跑通：10 模块回归测试 10 checks, 0 failed，端到端 demo 产出 PNG/SVG/XYZ/SDF/CSV。
> v1.1.0（2026-09-27）：新增 datasources 模块——按常用名 / CAS 号 / 中文名 / InChIKey / DrugBank ID / ChEMBL ID 从开源库取 SMILES 并直接进 RDKit。接入 8 个数据源（PubChem、Wikidata、NCI CADD CIR、OPSIN、ChEMBL、DrugBank、ChemSpider、HuggingFace），内置节流、503 退避重试与本地缓存。实测：PubChem/Wikidata/NCI 可用（OPSIN、ChEMBL、HF 本机不可达；DrugBank/ChemSpider 需 key）。回归测试扩到 14 checks, 0 failed。
> v1.2.0（2026-09-27）：补齐此前未覆盖的 RDKit 能力，新增 4 个模块（chemfeatures / screening / pharmacophore / sar），共 20 项回归测试 0 failed：
> - chemfeatures：手性中心检测（FindMolChiralCenters）、立体化学赋值、立体异构体枚举（AllChem.EnumerateStereoisomers）、移除/翻转手性、SMILES 随机枚举。
> - screening：过滤目录（PAINS/BRENK/CHEMBL/ZINC/NIH，FilterCatalog，实测 480 条 PAINS、105 条 BRENK）、Butina 单连接聚类、领导法多样性挑选。
> - pharmacophore：2D 药效团指纹（Gobbi Pharm2D，阿司匹林实测 32 位）。
> - sar：R-基团分解（RGroupDecomposition，2026.03 新 API：RGroupDecomposition([cores]) + GetRGroupsAsColumns()）。
> - 另扩展 fingerprints：新增 AtomPair/TopologicalTorsion/Avalon 统一分发 fingerprint(kind=...)，相似度检索与去重支持任意指纹类型。
何时使用
凡涉及分子结构处理的任务：SMILES/SDF 读写与批量转换、描述符与类药性计算、指纹相似度检索、子结构匹配/替换、2D 出图、3D 构象生成与优化、反应枚举虚拟库、骨架分析、分子标准化去盐等。
第一步：确认运行环境（关键）
RDKit 装在独立的 venv 里，默认 python 没有。两种方式：
# 方式 A：探测环境并用含 rdkit 的解释器执行脚本（推荐，任何解释器可用）
import sys
sys.path.insert(0, r"C:\Users\Eric Ye\.workbuddy\skills\rdkit-automation\references")
from rdkit_automation import envdetect
info = envdetect.find_rdkit_python()
# 实测 -> EnvInfo(exe='C:\\WINDOWS\\system32\\rdkit-env\\Scripts\\python.exe',
# python_version='3.13', rdkit_version='2026.03.6')
r = envdetect.run_with_rdkit("myscript.py") # 返回 CompletedProcess
# 方式 B：脚本直接用 rdkit-env 解释器运行（bash）
# C:/WINDOWS/system32/rdkit-env/Scripts/python.exe myscript.py
# 脚本内加：
sys.path.insert(0, r"C:\Users\Eric Ye\.workbuddy\skills\rdkit-automation\references")
from rdkit_automation import molio, descriptors, fingerprints, ...
环境不存在时安装：python -m venv rdkit-env && rdkit-env\Scripts\activate && pip install rdkit -i https://pypi.tuna.tsinghua.edu.cn/simple。也可设环境变量 RDKIT_PYTHON 指向解释器。
2026.03 必读坑点（详见 references/v2026_03_recipes.md）
rdMolDraw2D从rdkit.Chem.Draw导入（从rdkit.Chem导入会 ImportError）rdMolStandardize从rdkit.Chem.MolStandardize导入- BRICS 模块改名：
from rdkit.Chem import BRICS（函数名BRICSDecompose不变） CalcMolDescriptors移到Descriptors模块rdMolDraw2D.DrawReaction已移除 → 用rdkit.Chem.Draw.ReactionToImage（返回 PIL）AlignMol子结构对齐 atomMap 方向是(prb_id, ref_id)，且需在去氢副本上求匹配- Morgan 用新 API
rdFingerprintGenerator.GetMorganGenerator(...)（旧 API 弃用告警） - Count 指纹取值用
GetNonzeroElements() RunReactants对反应物顺序敏感 → 用reactions.run_reactants()（内部自动全排列）- 中文 legend 被 PIL 静默丢弃 → grid legends 用英文
- 无效 SMILES 返回 None 不抛异常；批量脚本用
RDLogger.DisableLog("rdApp.*")静默
在线数据源：名称 / CAS / 中文名 -> SMILES（v1.1）
支持 常用名、CAS 号、中文名、InChI/InChIKey、PubChem CID、DrugBank ID、
ChEMBL ID、SMILES 直通，解析结果直接进 RDKit（并可带 CID/IUPAC/分子式等属性）：
from rdkit_automation import datasources as ds
ds.to_mol("aspirin") # 常用名
ds.to_mol("64-19-7") # CAS -> 乙酸
ds.to_mol("阿司匹林") # 中文名（PubChem 不支持中文，走 Wikidata）
ds.to_mol("DB00945") # DrugBank ID（需 DRUGBANK_API_KEY）
ds.batch_to_mols([...], verbose=True) # 批量（自动节流 + 退避重试）
ds.identifiers_to_sdf([...], "out.sdf") # 名称列表 -> SDF 分子库
ds.cir_mol("aspirin", get3d=True) # NCI CIR 直接给 3D 构象分子
ds.pubchem_by_smiles(smi) # SMILES 反查 CID/IUPAC 名
命令行：python datasources.py aspirin 64-19-7 阿司匹林；自检：python datasources.py --status。
数据源状态（本机实测 2026-09-27）：PubChem ✅（会限流，burst 返回 503，模块已退避重试）、
Wikidata ✅（中文名唯一可用源）、NCI/CADD CIR ✅（支持 3D SDF）；
OPSIN ⚠、ChEMBL ⚠、HuggingFace ⚠ 本机不可达（接口保留）；
DrugBank / ChemSpider 需 API key（DRUGBANK_API_KEY / CHEMSPIDER_API_KEY，无 key 自动跳过）。
详见 references/v2026_03_recipes.md 第 11 节。
工具包结构
references/rdkit_automation/
├── __init__.py # 统一入口 + 用法说明
├── envdetect.py # 环境探测（纯标准库，无需 rdkit；venv/py launcher/conda 全扫描）
├── datasources.py # 名称/CAS/中文名/ID -> SMILES（PubChem/Wikidata/NCI/OPSIN/ChEMBL/DrugBank/ChemSpider/HF）
├── molio.py # SMILES/MOL/SDF/InChI/XYZ 读写、加删氢、片段拆分
├── descriptors.py # 描述符、Ro5/Veber/QED、Gasteiger 电荷、批量 CSV
├── fingerprints.py # Morgan 新 API/MACCS/相似度矩阵/Top-k 检索/去重
├── substructure.py # SMARTS 匹配/替换/删除/MCS/RWMol 从零构建
├── depict.py # PNG/SVG/网格图/高亮/反应式（已处理 2026.03 导入坑）
├── conformers.py # ETKDG 嵌入/MMFF→UFF 优化/多构象能量/RMSD/对齐
├── reactions.py # SMARTS 反应/产物枚举（反应物顺序坑已封装）/虚拟库
├── standardize.py # 标准化/去盐/互变异构/Murcko/BRICS/Recap（导入坑已处理）
├── chemfeatures.py # 手性中心检测/立体化学赋值/立体异构体枚举/SMILES 随机枚举（v1.2）
├── screening.py # 过滤目录 PAINS/BRENK/CHEMBL/ZINC/NIH + Butina 聚类 + 多样性挑选（v1.2）
├── pharmacophore.py # 2D 药效团指纹 Pharm2D（v1.2）
├── sar.py # R-基团分解（构效关系 SAR，v1.2）
└── batch.py # SDF↔CSV 流水线/批量变换/PandasTools 封装
references/v2026_03_recipes.md # 实测配方速查 + 坑点 + 数据源状态 + 回归基准数值
examples/demo.py # 端到端示例（描述符→检索→绘图→3D→反应→骨架→SDF）
examples/demo_lookup.py # 在线数据源示例（名称/CAS/中文名 -> 分子 -> 描述符 + 出图）
examples/validate_rdkit_automation.py # 20 项回归测试（含网络部分，离线自动跳过）
典型工作流
虚拟筛选式检索：molio.iter_sdf() 读库 → descriptors.table() 过滤 → fingerprints.most_similar() 排序 → depict.grid_png() 出图。
批量结构处理：batch.batch_transform(in.sdf, out.sdf, fn)（自动统计 ok/fail，继承输入属性）或 batch.smiles_csv_to_sdf()（坏行跳过）。
3D 构象：conformers.embed_and_optimize(smiles)（ETKDGv3 + MMFF，缺参数自动退 UFF）；多构象用 embed_multiple() + conf_energies() 取最低能构象；to_xyz_text() 可直接喂 Gaussian/ORCA。
反应枚举：reactions.enumerate_library(rxn_smarts, [位点1列表, 位点2列表]) 组合枚举并去重。
手性 / 立体化学（v1.2, chemfeatures）
from rdkit_automation import chemfeatures as cf
m = molio.from_smiles("C[C@H](O)C(=O)O")
cf.chiral_centers(m) # [(1, 'R'|'S'|'?')]
cf.is_chiral(m) # 是否含已指定(R/S)手性中心
cf.has_unassigned_stereo(molio.from_smiles("CC(O)C(=O)O")) # 是否含未定义立体中心
cf.enumerate_stereoisomers(m) # 立体异构体 SMILES 列表（唯一化+嵌入校验）
cf.num_stereoisomers(m) # 理论立体异构体数（-1=超上限）
cf.remove_stereo(m) # 移除全部立体标记
cf.invert_chirality(m, atom_idx=1) # 翻转指定中心构型
cf.smiles_enumerate(m, n=16) # 多个互不等价的规范 SMILES
cf.canonical_smiles(m) # 规范化唯一 SMILES
虚拟筛选辅助（v1.2, screening）
from rdkit_automation import screening as sc
# 过滤目录：PAINS / BRENK / CHEMBL / ZINC / NIH / ALL（可组合为列表）
sc.has_filter(mol, "PAINS") # 是否命中（脏骨架/官能团）
sc.matched_filters(mol, "PAINS") # 命中的规则名列表
passed, failed = sc.filter_with_reason(mols, "PAINS") # 返回(通过, 被剔除[(idx,规则)])
sc.filter_mols(mols, "PAINS", keep="pass") # 批量过滤
# 聚类与多样性
clusters = sc.butina_cluster(mols, cutoff=0.35) # Butina 单连接聚类（簇=分子索引列表）
div = sc.pick_diverse(mols, k=10, cutoff=0.35) # 领导法多样性挑选
2D 药效团指纹（v1.2, pharmacophore）
from rdkit_automation import pharmacophore as ph
fp = ph.pharm2d_fp(mol) # Pharm2D 位向量（阿司匹林实测 32 位）
ph.pharm2d_similarity(m1, m2) # 药效团 Tanimoto
ph.pharm2d_most_similar(query, mols, k=5)
R-基团分解 / SAR（v1.2, sar）
from rdkit_automation import sar
# core_smiles 定义切割边界（连接到核心的取代基成为各 R 位点）
rows = sar.rgroup_table(sars, core_smiles="c1ccccc1")
# -> [{'Core':'c1ccc([*:1])cc1','R1':'O=C(O)[*:1]'}, ...]
res = sar.rgroup_decompose(sars, core_smiles="c1ccccc1")
# -> {'labels':['Core','R1'], 'columns':{'Core':[...], 'R1':[...]}}
指纹统一分发（fingerprints 扩展，v1.2）
相似度检索/去重现支持任意指纹类型，不必局限于 Morgan：
from rdkit_automation import fingerprints as fp
fp.fingerprint(mol, kind="morgan"|"atompair"|"torsion"|"maccs"|"avalon"|"rdkit")
fp.most_similar(query, mols, k=5, kind="atompair") # 指定指纹类型检索
fp.deduplicate(mols, threshold=0.9, kind="morgan") # 指定指纹去重
验证
改包后跑回归：C:/WINDOWS/system32/rdkit-env/Scripts/python.exe examples/validate_rdkit_automation.py，应输出 20 checks, 0 failed。
