企业官网建设流程全解析

RDKit Cheminformatics 实战指南：基于 scientific-agent-skills 仓库的分子处理、描述符、指纹与子结构搜索全解析

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

RDKit 是计算化学与药物发现领域最核心的开源化学信息学（cheminformatics）工具库，提供 SMILES/SDF 解析、分子描述符（MW、LogP、TPSA）、指纹、子结构搜索、化学反应、2D/3D 构象生成与可视化等完整能力。本文以scientific-agent-skills仓库中的skills/rdkit技能包为骨架，结合其 5 份参考文档、3 个开箱即用的示例脚本与对应测试用例，系统讲解从分子读入到药物相似性评估、相似性筛选、子结构过滤的完整实战链路。读完本文，你将掌握 RDKit 的 12 大核心能力、常用 SMARTS 模式库，以及一套可直接运行的命令行工作流。

技能包概览与仓库定位

skills/rdkit/SKILL.md定义了一个面向 AI Agent 与科研人员的高质量 RDKit 技能包，其核心定位是对分子进行细粒度控制（fine-grained molecular control）。SKILL.md 明确指出：对于标准、简单的化学信息学工作流，推荐使用 RDKit 的轻量封装库datamol（仓库中也有独立的skills/datamol技能包）；而当需要高级控制、自定义净化（custom sanitization）或专用算法时，则应直接使用 RDKit 本身。该技能包遵循 BSD-3-Clause 许可证，版本号为 1.2。

技能包的目录结构如下：

• 技能定义与能力总览：skills/rdkit/SKILL.md
• 参考文档（仅此 5 份为本地捆绑资源）：
  • references/api_reference.md —— 按功能组织的完整 RDKit Python API 清单
  • references/core_capabilities.md —— 12 大能力域的完整代码示例
  • references/descriptors_reference.md —— 分子描述符速查手册
  • references/smarts_patterns.md —— 常用 SMARTS 模式库
  • references/workflows_and_best_practices.md —— 工作流与最佳实践
• 示例脚本：
  • scripts/molecular_properties.py
  • scripts/similarity_search.py
  • scripts/substructure_filter.py

注意：文档中出现的rdkit、datamol、scipy、sklearn等名称均指可安装的 Python 包，而非技能包内的本地文件。

安装与运行环境

SKILL.md 给出的安装建议同时覆盖「已有 Python 环境」与「全新可复现环境」两种场景。

方式一：在已有环境中使用uv安装（推荐用于快速上手）：

uv pip install rdkit

方式二：使用 conda-forge 创建全新可复现环境（上游官方推荐）：

conda create -c conda-forge -n my-rdkit-env rdkit conda activate my-rdkit-env

关键约束与版本基线（以 SKILL.md 2026-06-07 检查结果为准）：

• 示例面向 RDKit2026.03.x版本；该版本为当时的 GitHub/PyPI 最新发布（PyPI 包名rdkit2026.3.3）。
• 包名演进：PyPI 上的官方包名现在是rdkit（提供跨平台 wheel），rdkit-pypi是历史遗留包名，仅应在维护旧环境时出现。
• 在需要混合编译型科学计算包的场景下，conda-forge 仍是上游推荐的安装渠道（二进制兼容性最广）。
• 严禁混装：避免在同一环境中同时安装 conda 的rdkit与 PyPI 的rdkit/rdkit-pypi，否则无法确定实际导入的是哪个二进制扩展模块。

核心能力全景：12 大能力域

SKILL.md 将 RDKit 能力归纳为 12 大领域，每一项都有配套的完整代码示例（见 references/core_capabilities.md）：

下面按能力域逐一展开，代码示例均可在 core_capabilities.md 中验证。

分子 I/O 与创建

从各种格式读取分子

所有MolFrom*函数在解析失败时返回None并打印错误信息，因此使用前必须判空。分子在导入时默认自动净化（校验价态、感知芳香性等）。

from rdkit import Chem # 从 SMILES 字符串 mol = Chem.MolFromSmiles('Cc1ccccc1') # 返回 Mol 对象或 None # 从 MOL 文件 mol = Chem.MolFromMolFile('path/to/file.mol') # 从 MOL block（字符串数据） mol = Chem.MolFromMolBlock(mol_block_string) # 从 InChI mol = Chem.MolFromInchi('InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H')

写出分子

# 转成规范 SMILES smiles = Chem.MolToSmiles(mol) # 转成 MOL block mol_block = Chem.MolToMolBlock(mol) # 转成 InChI / InChIKey inchi = Chem.MolToInchi(mol) key = Chem.MolToInchiKey(mol)

批量处理：Supplier / Writer

处理大量分子时应使用 Supplier/Writer 对象，api_reference.md 记录了它们的签名，如SDMolSupplier(filename, sanitize=True, removeHs=True)、SmilesMolSupplier(filename, delimiter=' ', titleLine=True)、SDWriter(filename)等。

# 读取 SDF 文件（注意判空） suppl = Chem.SDMolSupplier('molecules.sdf') for mol in suppl: if mol is not None: # 检查解析错误 pass # 读取 SMILES 文件 suppl = Chem.SmilesMolSupplier('molecules.smi', titleLine=False) # 大型文件 / 压缩数据：ForwardSDMolSupplier 逐条流式读取，避免整文件载入 import gzip with gzip.open('molecules.sdf.gz') as f: suppl = Chem.ForwardSDMolSupplier(f) for mol in suppl: pass # 多线程处理大数据集 suppl = Chem.MultithreadedSDMolSupplier('molecules.sdf') # 写入 SDF writer = Chem.SDWriter('output.sdf') for mol in molecules: writer.write(mol) writer.close()

SKILL.md 给出两条数据存储建议：共享数据优先用可移植格式（SMILES、SDF）；本地缓存优先用 RDKit 二进制分子表示（mol.ToBinary()）而非通用 pickle。

分子净化与验证

RDKit 在解析时自动执行净化，包含13 个步骤（价态检查、芳香性感知、手性指派等）。当需要精细控制时，可禁用自动净化并手动操作：

# 禁用自动净化 mol = Chem.MolFromSmiles('C1=CC=CC=C1', sanitize=False) # 手动净化 Chem.SanitizeMol(mol) # 净化前先检测问题 problems = Chem.DetectChemistryProblems(mol) for problem in problems: print(problem.GetType(), problem.Message()) # 部分净化（跳过特定步骤，此处跳过属性计算） Chem.SanitizeMol(mol, sanitizeOps=Chem.SANITIZE_ALL ^ Chem.SANITIZE_PROPERTIES)

api_reference.md 列出了完整的净化操作位标志：SANITIZE_NONE、SANITIZE_ALL（默认）、SANITIZE_CLEANUP、SANITIZE_PROPERTIES、SANITIZE_SYMMRINGS、SANITIZE_KEKULIZE、SANITIZE_FINDRADICALS、SANITIZE_SETAROMATICITY、SANITIZE_SETCONJUGATION、SANITIZE_SETHYBRIDIZATION、SANITIZE_CLEANUPCHIRALITY。

常见净化问题包括：原子显式价态超上限抛异常、无效芳香环引发 kekulization 错误、自由基电子未显式指定时可能指派不当。这正是技能定位中「自定义净化」能力的用武之地——用DetectChemistryProblems()先诊断、再决定如何处理。

分子分析与属性

原子、键与环

# 遍历原子和键 for atom in mol.GetAtoms(): print(atom.GetSymbol(), atom.GetIdx(), atom.GetDegree()) for bond in mol.GetBonds(): print(bond.GetBeginAtomIdx(), bond.GetEndAtomIdx(), bond.GetBondType()) # 环信息 ring_info = mol.GetRingInfo() ring_info.NumRings() ring_info.AtomRings() # 返回原子索引元组 # 原子是否在环中 atom = mol.GetAtomWithIdx(0) atom.IsInRing() atom.IsInRingSize(6) # 是否在 6 元环中 # 最小环集合（SSSR） from rdkit.Chem import GetSymmSSSR rings = GetSymmSSSR(mol)

原子方法还包括GetAtomicNum()、GetTotalDegree()（含氢）、GetFormalCharge()、GetIsAromatic()、GetHybridization()、GetChiralTag()等；键方法包括GetIsConjugated()、GetIsAromatic()、bond.IsInRing()、bond.GetStereo()（取值为STEREONONE、STEREOZ、STEREOE等）。

立体化学

from rdkit.Chem import FindMolChiralCenters chiral_centers = FindMolChiralCenters(mol, includeUnassigned=True) # 返回 (atom_idx, chirality) 元组列表 # 从 3D 坐标指派立体化学 from rdkit.Chem import AssignStereochemistryFrom3D AssignStereochemistryFrom3D(mol) # 检查键的立体化学 stereo = bond.GetStereo()

碎片分析

frags = Chem.GetMolFrags(mol, asMols=True) # 断开连接的碎片 from rdkit.Chem import FragmentOnBonds frag_mol = FragmentOnBonds(mol, [bond_idx1, bond_idx2]) from rdkit.Chem.Scaffolds import MurckoScaffold scaffold = MurckoScaffold.GetScaffoldForMol(mol) # Murcko 骨架

分子描述符与药物相似性

常用描述符

from rdkit.Chem import Descriptors mw = Descriptors.MolWt(mol) # 平均分子量 exact_mw = Descriptors.ExactMolWt(mol) # 按同位素组成的精确分子量 logp = Descriptors.MolLogP(mol) # Wildman-Crippen LogP（油水分配系数） tpsa = Descriptors.TPSA(mol) # 拓扑极性表面积 hbd = Descriptors.NumHDonors(mol) # 氢键供体数（N-H、O-H） hba = Descriptors.NumHAcceptors(mol) # 氢键受体数（N、O） rot_bonds = Descriptors.NumRotatableBonds(mol) # 可旋转键数（柔性） aromatic_rings = Descriptors.NumAromaticRings(mol)

批量计算

# 一次性计算全部描述符，返回字典 all_descriptors = Descriptors.CalcMolDescriptors(mol) # {'MolWt': 180.16, 'MolLogP': 1.23, ...} # 获取全部可用描述符名称 descriptor_names = [desc[0] for desc in Descriptors._descList]

descriptors_reference.md 是完整的描述符速查手册，将 200+ 描述符划分为十大类：物理化学类（MolWt、MolLogP、MolMR、TPSA）、拓扑类（BertzCT、BalabanJ、Kappa 指数）、电子类（部分电荷、E-state 指数）、形状类（Kappa 指数、BCUT）、连通性类（Chi 指数族 Chi0–Chi4 及 Chi0n–Chi4n、Chi0v–Chi4v）、2D 指纹密度类（FpDensityMorgan1/2/3）、原子计数类（重原子、杂原子、各类环）、药物相似性类（QED、Lipinski 参数）、柔性类（NumRotatableBonds、HallKierAlpha）、表面积类（PEOE_VSA、SMR_VSA、SLogP_VSA、EState_VSA、BCUT 等）。

此外还包括 MQN 分子量子数（mqn1–mqn42）等整数描述符。使用建议：批量计算避免冗余；部分描述符对无效分子返回None需判空；ML 应用前需归一化；按任务精选描述符而非全量使用；3D 描述符需单独处理（依赖 3D 坐标）。

Lipinski 五规则（类药性）

mw = Descriptors.MolWt(mol) <= 500 logp = Descriptors.MolLogP(mol) <= 5 hbd = Descriptors.NumHDonors(mol) <= 5 hba = Descriptors.NumHAcceptors(mol) <= 10 is_drug_like = mw and logp and hbd and hba

指纹与分子相似性

指纹类型一览

core_capabilities.md 强调：新代码统一优先使用rdFingerprintGenerator现代 API，而AllChem.GetMorganFingerprint*系列为遗留辅助接口（api_reference.md 中也有同样提示）。

from rdkit.Chem import rdFingerprintGenerator from rdkit.Chem import MACCSkeys # RDKit 拓扑指纹（路径范围 1-7，2048 位） rdk_gen = rdFingerprintGenerator.GetRDKitFPGenerator(minPath=1, maxPath=7, fpSize=2048) fp = rdk_gen.GetFingerprint(mol) # Morgan 指纹（圆形指纹，类 ECFP），radius=2 即 ECFP4 morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048) fp = morgan_gen.GetFingerprint(mol) fp_count = morgan_gen.GetCountFingerprint(mol) # 计数型指纹 # MACCS 结构键（166 位） fp = MACCSkeys.GenMACCSKeys(mol) # 原子对指纹 ap_gen = rdFingerprintGenerator.GetAtomPairGenerator() fp = ap_gen.GetFingerprint(mol) # 拓扑扭转角指纹 tt_gen = rdFingerprintGenerator.GetTopologicalTorsionGenerator() fp = tt_gen.GetFingerprint(mol) # Avalon 指纹（若可用） from rdkit.Avalon import pyAvalonTools fp = pyAvalonTools.GetAvalonFP(mol)

相似性计算

from rdkit import DataStructs mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048) fp1 = mfpgen.GetFingerprint(mol1) fp2 = mfpgen.GetFingerprint(mol2) # Tanimoto 相似度 similarity = DataStructs.TanimotoSimilarity(fp1, fp2) # 批量计算（性能关键） fps = [mfpgen.GetFingerprint(m) for m in [mol2, mol3, mol4]] similarities = DataStructs.BulkTanimotoSimilarity(fp1, fps) # 其他度量：Dice、Cosine dice = DataStructs.DiceSimilarity(fp1, fp2) cosine = DataStructs.CosineSimilarity(fp1, fp2)

api_reference.md 还列出 Sokal、Kulczynski、McConnaughey 等度量，以及对应的Bulk*批量版与*Distance（1 − 相似度）版本。

Butina 聚类与多样性

from rdkit.ML.Cluster import Butina # 构建距离矩阵 dists = [] fps = [mfpgen.GetFingerprint(mol) for mol in mols] for i in range(len(fps)): sims = DataStructs.BulkTanimotoSimilarity(fps[i], fps[:i]) dists.extend([1 - sim for sim in sims]) # 按距离阈值聚类 clusters = Butina.ClusterData(dists, len(fps), distThresh=0.3, isDistData=True)

子结构搜索与 SMARTS

基本匹配

# 用 SMARTS 定义查询：苯环 query = Chem.MolFromSmarts('[#6]1:[#6]:[#6]:[#6]:[#6]:[#6]:1') has_match = mol.HasSubstructMatch(query) # 是否包含 matches = mol.GetSubstructMatches(query) # 所有匹配（原子索引元组的元组） match = mol.GetSubstructMatch(query) # 仅第一个匹配

GetSubstructMatches支持uniquify、useChirality、maxMatches等参数（默认maxMatches=1000）。

匹配规则要点（易错点）

• 查询中未指定的属性可匹配目标分子的任意值；
• 氢原子除非显式指定否则被忽略；
• 带电荷的查询原子不会匹配不带电的目标原子；
• 芳香查询原子不会匹配脂肪族目标原子（除非查询是通用原子）。

常用 SMARTS 模式库

smarts_patterns.md 提供了覆盖面极广的模式库，以下为精选：

# 官能团 primary_alcohol = Chem.MolFromSmarts('[CH2][OH1]') carboxylic_acid = Chem.MolFromSmarts('C(=O)[OH]') amide = Chem.MolFromSmarts('C(=O)N') nitrile = Chem.MolFromSmarts('C#N') nitro = Chem.MolFromSmarts('N+[O-]') aromatic_n = Chem.MolFromSmarts('[nR]') # 环内芳香氮 macrocycle = Chem.MolFromSmarts('[r{12-}]') # 12 元以上大环 # 杂环（吡啶/吡咯/呋喃/噻吩/咪唑/嘧啶/噻唑/噁唑） pyridine = Chem.MolFromSmarts('n1ccccc1') furan = Chem.MolFromSmarts('o1cccc1') # 稠环（萘/吲哚/喹啉/苯并咪唑/嘌呤） naphthalene = Chem.MolFromSmarts('c1ccc2ccccc2c1') indole = Chem.MolFromSmarts('c1ccc2[nH]ccc2c1') # 立体化学 cw = Chem.MolFromSmarts('[C@]') # 顺时针手性 ccw = Chem.MolFromSmarts('[C@@]') # 逆时针手性 e_bond = Chem.MolFromSmarts('C/C=C/C') # 药效团特征 hbd = Chem.MolFromSmarts('[OH,NH,NH2,NH3+]') # 氢键供体 hba = Chem.MolFromSmarts('[O,N]') # 氢键受体 alkyl = Chem.MolFromSmarts('CCCC') # 4+ 碳烷基链 # 药物相关骨架 benzamide = Chem.MolFromSmarts('c1ccccc1C(=O)N') sulfonamide = Chem.MolFromSmarts('S(=O)(=O)N') piperazine = Chem.MolFromSmarts('N1CCNCC1') morpholine = Chem.MolFromSmarts('N1CCOCC1') # PAINS 毒性/干扰性警示 rhodanine = Chem.MolFromSmarts('S1C(=O)NC(=S)C1') catechol = Chem.MolFromSmarts('c1ccc(O)c(O)c1') michael_acc = Chem.MolFromSmarts('C=CC(=O)[C,N]')

模式库中还包含金属螯合基团（羧酸根C(=O)[O-]、异羟肟酸C(=O)N[OH]、邻苯二酚等）、反应性基团（酰氯C(=O)Cl、环氧化物C1OC1）、环大小过滤器（[r3]–[r7]、[r{8-}]、[r{9-15}]）、连通性（[D1]–[D4]、[R]/[!R]/[R1]/[R2]）、杂化状态（[CX2]/[CX3]/[CX4]）等。

SMARTS 编写技巧：需要时用[CX3]而非[C]精确限定；方括号内[C]与裸C（芳香）含义不同；小写字母（c、n、o）表示芳香原子；[R]表示在环中、[!R]表示不在环中；复杂模式可用递归 SMARTS$(...)；写完后务必用已知分子验证。

化学反应

反应 SMARTS 与应用

from rdkit.Chem import AllChem # 反应 SMARTS 语法：反应物 >> 产物（此处为酮还原示例） rxn = AllChem.ReactionFromSmarts('[C:1]=[O:2]>>[C:1][O:2]') # 应用到分子 reactants = (mol1,) products = rxn.RunReactants(reactants) # products 为元组的元组（每组产物一个元组） for product_set in products: for product in product_set: Chem.SanitizeMol(product) # 产物需净化

反应机制要点：原子映射（:1、:2）保留反应物与产物间的原子对应；产物中的哑元原子（dummy atoms）会被对应反应物原子替换；"Any" 键继承反应物的键级；除非显式改变，手性被保留。

反应相似性

fp = AllChem.CreateDifferenceFingerprintForReaction(rxn) similarity = DataStructs.TanimotoSimilarity(fp1, fp2)

2D 与 3D 坐标生成

2D 描绘坐标

AllChem.Compute2DCoords(mol) # 生成 2D 描绘坐标 # 对齐到模板结构 template = Chem.MolFromSmiles('c1ccccc1') AllChem.Compute2DCoords(template) AllChem.GenerateDepictionMatching2DStructure(mol, template)

3D 构象与力场优化

# ETKDG 嵌入单个 3D 构象（randomSeed 保证可复现） AllChem.EmbedMolecule(mol, randomSeed=42) # 生成多个构象 conf_ids = AllChem.EmbedMultipleConfs(mol, numConfs=10, randomSeed=42) # 力场几何优化 AllChem.UFFOptimizeMolecule(mol) # UFF 力场 AllChem.MMFFOptimizeMolecule(mol) # MMFF94 力场 # 优化所有构象 for conf_id in conf_ids: AllChem.MMFFOptimizeMolecule(mol, confId=conf_id) # 构象间 RMSD 与对齐 rms = AllChem.GetConformerRMS(mol, conf_id1, conf_id2) AllChem.AlignMol(probe_mol, ref_mol)

约束嵌入

# 将分子的一部分约束到指定坐标（例如基于已知活性构象的骨架对接） AllChem.ConstrainedEmbed(mol, core_mol)

分子可视化

基本绘制

from rdkit.Chem import Draw img = Draw.MolToImage(mol, size=(300, 300)) # 绘制为 PIL 图像 img.save('molecule.png') Draw.MolToFile(mol, 'molecule.png') # 直接写文件 # 网格绘制多分子 img = Draw.MolsToGridImage(mols, molsPerRow=2, subImgSize=(200, 200))

子结构高亮与自定义绘制

query = Chem.MolFromSmarts('c1ccccc1') match = mol.GetSubstructMatch(query) # 高亮匹配原子 img = Draw.MolToImage(mol, highlightAtoms=match) # 自定义高亮颜色 highlight_colors = {atom_idx: (1, 0, 0) for atom_idx in match} # 红色 img = Draw.MolToImage(mol, highlightAtoms=match, highlightAtomColors=highlight_colors) # 使用 rdMolDraw2D 深度自定义 from rdkit.Chem.Draw import rdMolDraw2D drawer = rdMolDraw2D.MolDraw2DCairo(300, 300) opts = drawer.drawOptions() opts.addAtomIndices = True opts.addStereoAnnotation = True opts.bondLineWidth = 2 drawer.DrawMolecule(mol) drawer.FinishDrawing() with open('molecule.png', 'wb') as f: f.write(drawer.GetDrawingText())

Jupyter 集成与指纹位可视化

from rdkit.Chem.Draw import IPythonConsole IPythonConsole.ipython_useSVG = True # 使用 SVG 而非 PNG IPythonConsole.molSize = (300, 300) mol # 在 notebook 中自动显示分子图像 # 查看 Morgan 指纹某一位对应的化学环境 from rdkit.Chem import rdFingerprintGenerator additional_output = rdFingerprintGenerator.AdditionalOutput() additional_output.AllocateBitInfoMap() morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048) fp = morgan_gen.GetFingerprint(mol, additionalOutput=additional_output) bit_info = additional_output.GetBitInfoMap() img = Draw.DrawMorganBit(mol, bit_id, bit_info)

分子修饰

氢原子管理与芳香性

mol_h = Chem.AddHs(mol) # 添加显式氢（计算依赖氢的属性前先加氢） mol = Chem.RemoveHs(mol_h) # 移除显式氢 Chem.Kekulize(mol) # 芳香键转交替单/双键 Chem.SetAromaticity(mol) # 设置芳香性

子结构替换与电荷中和

# 将苯环替换为环己烷 query = Chem.MolFromSmarts('c1ccccc1') replacement = Chem.MolFromSmiles('C1CCCCC1') new_mol = Chem.ReplaceSubstructs(mol, query, replacement)[0] # 用 Uncharger 去除形式电荷 from rdkit.Chem.MolStandardize import rdMolStandardize uncharger = rdMolStandardize.Uncharger() mol_neutral = uncharger.uncharge(mol)

分子哈希与标准化

分子哈希函数

from rdkit.Chem import rdMolHash scaffold_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.MurckoScaffold) canonical_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.CanonicalSmiles) regio_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.Regioisomer) # 忽略立体化学

api_reference.md 列出全部哈希函数：AnonymousGraph、CanonicalSmiles、ElementGraph、MurckoScaffold、Regioisomer、NetCharge、HetAtomProtomer、HetAtomTautomer。MolStandardize 还提供Normalize、Reionize、RemoveFragments、Cleanup、TautomerEnumerator（含Canonicalize得到规范互变异构体）等标准化工具。

随机 SMILES（数据增强）

from rdkit.Chem import MolToRandomSmilesVect random_smiles = MolToRandomSmilesVect(mol, numSmiles=10, randomSeed=42)

药效团与 3D 特征

from rdkit.Chem import ChemicalFeatures from rdkit import RDConfig import os fdef_path = os.path.join(RDConfig.RDDataDir, 'BaseFeatures.fdef') factory = ChemicalFeatures.BuildFeatureFactory(fdef_path) features = factory.GetFeaturesForMol(mol) for feat in features: print(feat.GetFamily(), feat.GetType(), feat.GetAtomIds()) # 例如输出 (Donor, SingleAtomDonor, (atom_ids,))

feature.GetFamily()返回供体（Donor）/受体（Acceptor）等家族，GetAtomIds()返回参与该特征的原子的索引。

完整实战工作流

workflows_and_best_practices.md 提供了三个可直接套用的函数级工作流：

药物相似性分析

def analyze_druglikeness(smiles): mol = Chem.MolFromSmiles(smiles) if mol is None: return None results = { 'MW': Descriptors.MolWt(mol), 'LogP': Descriptors.MolLogP(mol), 'HBD': Descriptors.NumHDonors(mol), 'HBA': Descriptors.NumHAcceptors(mol), 'TPSA': Descriptors.TPSA(mol), 'RotBonds': Descriptors.NumRotatableBonds(mol) } results['Lipinski'] = ( results['MW'] <= 500 and results['LogP'] <= 5 and results['HBD'] <= 5 and results['HBA'] <= 10 ) return results

指纹相似性筛选

def similarity_screen(query_smiles, database_smiles, threshold=0.7): query_mol = Chem.MolFromSmiles(query_smiles) if query_mol is None: return [] morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048) query_fp = morgan_gen.GetFingerprint(query_mol) hits = [] for idx, smiles in enumerate(database_smiles): mol = Chem.MolFromSmiles(smiles) if mol: fp = morgan_gen.GetFingerprint(mol) sim = DataStructs.TanimotoSimilarity(query_fp, fp) if sim >= threshold: hits.append((idx, smiles, sim)) return sorted(hits, key=lambda x: x[2], reverse=True)

子结构过滤

def filter_by_substructure(smiles_list, pattern_smarts): query = Chem.MolFromSmarts(pattern_smarts) hits = [] for smiles in smiles_list: mol = Chem.MolFromSmiles(smiles) if mol and mol.HasSubstructMatch(query): hits.append(smiles) return hits

开箱即用的命令行脚本

技能包附带 3 个可直接运行的 CLI 脚本（源码见 skills/rdkit/scripts，被 tests/rdkit/test_scripts.py 覆盖测试）：

1. molecular_properties.py —— 分子属性计算器

# 单分子分析 python molecular_properties.py "CCO" # 从文件批量处理（支持 .sdf/.mol 与 .smi/.smiles/.txt） python molecular_properties.py --file molecules.smi --output properties.csv

脚本计算分子式、MW/ExactMW、LogP、MR、TPSA、LabuteASA、HBD/HBA、重原子/杂原子/价电子计数、各类环计数、可旋转键、FractionCsp3、BertzCT、QED 等 20+ 项属性，并自动给出Lipinski 五规则判定（MW≤500、LogP≤5、HBD≤5、HBA≤10）与lead-like 判定（250≤MW≤350、LogP≤3.5、RotBonds≤7）。

2. similarity_search.py —— 指纹相似性搜索

python similarity_search.py "CCO" database.smi --threshold 0.7 python similarity_search.py query.smi database.sdf --method morgan --output hits.csv

内置 5 种指纹方法（morgan/rdkit/maccs/atompair/torsion）与 3 种度量（tanimoto/dice/cosine），支持--radius（默认 2）、--bits（默认 2048）调参，结果按相似度降序输出并可存为 CSV。

3. substructure_filter.py —— 子结构过滤器

# 保留含苯环的分子 python substructure_filter.py molecules.smi --pattern "c1ccccc1" -o filtered.smi # 排除反应性基团 python substructure_filter.py database.sdf --exclude "C(=O)Cl" -o clean.sdf # 使用预置模式库（functional-groups / rings / pains / privileged） python substructure_filter.py molecules.smi --filter-type functional-groups -o fg.smi # 剔除 PAINS 干扰子结构 python substructure_filter.py compounds.smi --filter-type pains --exclude-mode -o clean.smi

脚本内置 4 套预置模式库（functional-groups、rings、pains、privileged，模式内容见脚本中的PATTERN_LIBRARIES字典，与 smarts_patterns.md 一致），支持 include/exclude 组合、--match-all全匹配模式、--list-patterns列出全部模式，并输出详细过滤报告（CSV）。

测试用例对行为契约的验证

tests/rdkit/test_scripts.py 以「化学事实」为基准验证了脚本行为，这些测试同时是理解 RDKit 行为契约的绝佳材料：

• SMARTS 模式库契约：逐一编译所有模式并断言非空；验证代表性模式命中其对应化学实体（如carboxylic_acid命中CC(=O)O、pyridine命中c1ccncc1），并验证不匹配场景（苯环不含羧酸）；这正是 SKILL.md 强调「SMARTS 查询中未指定属性匹配任意值」的实证。
• 过滤器逻辑契约：include 只保留匹配分子（苯环过滤后仅剩 aspirin、benzene）；exclude 优先于 include；match_all_include时须匹配全部模式；每条分子都有included/excluded/no_match状态；不可解析分子被跳过而非崩溃。
• 属性计算契约：苯环有 1 个芳香环、0 个可旋转键、分子式 C6H6；阿司匹林分子式 C9H8O4、HBD=1、MW≈180.16（与测试断言delta=0.1一致）；不可解析输入返回 False 而非抛异常。
• 指纹契约：所有声明的指纹方法均能产出指纹；方法名大小写不敏感；未知方法名抛ValueError；分子与自身 Tanimoto 相似度为 1.0；不同分子相似度小于 1.0；n_bits=512时指纹长度严格为 512。
• 文件读取契约：SMILES 文件可读；文件中单行损坏不会中止整个文件读取（坏行被跳过）。

常见陷阱与最佳实践

SKILL.md 总结的 6 大常见陷阱，务必熟记：

1. 忘记判空：解析后必须验证分子是否为None；
2. 净化失败：用DetectChemistryProblems()排查问题；
3. 缺氢：计算依赖氢的属性（如 3D 描述符、某些力场操作）前先AddHs()；
4. 2D vs 3D：可视化和 3D 分析前先生成相应坐标（Compute2DCoords/EmbedMolecule）；
5. SMARTS 匹配规则：未指定的属性会匹配任意值，易产生意外命中；
6. MolSupplier 线程安全：不要在多个线程间共享 supplier 对象。

性能优化与安全存储

import base64, json from pathlib import Path # 本地可信缓存：RDKit 二进制表示（避免通用 pickle） payload = [base64.b64encode(mol.ToBinary()).decode("ascii") for mol in mols] Path("molecules.rdmol.json").write_text(json.dumps(payload)) cached = json.loads(Path("molecules.rdmol.json").read_text()) mols = [Chem.Mol(base64.b64decode(item)) for item in cached]

安全红线：绝不从不可信来源加载 Python pickle——pickle 反序列化可执行任意代码。数据交换用 SMILES/SDF，本地缓存用 RDKit 二进制载荷。

批量操作：优先BulkTanimotoSimilarity等批量 API，避免逐对调用造成性能损失。

版本敏感行为（针对 2026.03 及近期版本）

workflows 文档明确提示：当精确的分子标识符或数值特征进入持久化数据集、模型特征管线或受监管报告时，必须固定（pin）RDKit 版本。近几个版本的关键行为变化：

• 规范 SMILES 与立体化学：2026.03 调整了规范双键的处理以避免立体信息损坏，部分含立体 SMILES 的输出与旧版不同；
• 描述符与哈希：2024.09 修正了无支链烷烃碎片描述符的 SMARTS，并改变了一些互变异构体/质子异构体哈希输出；
• 绘制：遗留rdkit.Chem.Draw画布模块及MolToImageFile、MolToMPL、MolToQPixmap已被移除，改用Draw.MolToFile、Draw.MolToImage或rdMolDraw2D；
• MolStandardize：使用rdkit.Chem.MolStandardize.rdMolStandardize，旧版 Python 实现已移除；
• 相似性图：GetSimilarityMapFromWeights()、GetSimilarityMapForFingerprint()、GetSimilarityMapForModel()现在要求传入rdMolDraw2D绘制对象。

线程安全与内存管理

RDKit 大多数操作线程安全：分子 I/O（SMILES、MOL block）、坐标生成、指纹与描述符、子结构搜索、反应、绘制。唯一例外是 MolSupplier 的并发访问。处理超大数据集时，用ForwardSDMolSupplier逐条流式读取（避免整文件载入内存），或用MultithreadedSDMolSupplier('large.sdf', numWriterThreads=4)并行解析。

在 Agent 工作流中的使用建议

回到本技能包的设计初衷：SKILL.md的 frontmatter 声明了allowed-tools: Read Write Edit Bash，这意味着该技能面向可读写文件、可执行命令的 Agent 环境。在实际的化学信息学 Agent 任务中，推荐按以下模式组合使用：

1. 数据读取：用SmilesMolSupplier/SDMolSupplier读取输入化合物库；
2. 属性计算：用molecular_properties.py或Descriptors.CalcMolDescriptors批量计算描述符；
3. 初筛过滤：用substructure_filter.py以 PAINS/反应性基团模式剔除干扰物，或用 Lipinski 规则过滤类药性；
4. 相似性检索：用similarity_search.py（Morgan 指纹 + Tanimoto）对命中化合物排序；
5. 结果沉淀：将命中集以 SMILES/SDF 写出（可移植），或对需持久化的中间结果使用 RDKit 二进制缓存。

整个流程均由本仓库的脚本、参考文档与测试用例提供可验证依据，可直接在安装了 RDKit（uv pip install rdkit或 conda-forge 环境）的机器上复现运行。

总结

skills/rdkit技能包把 RDKit 的复杂 API 组织为「12 大能力域 + 参考文档 + 示例脚本 + 测试契约」四位一体的知识体系。从分子 I/O、净化验证、描述符、指纹、SMARTS 子结构搜索，到化学反应、构象生成、可视化、修饰、哈希标准化与药效团特征，本文已完整覆盖其能力地图，并深入底层脚本与测试，印证了每个关键 API 的实际行为与边界条件。无论是药物发现中的类药性初筛、化合物库的相似性排序，还是结构-活性关系研究中的子结构过滤，这套工作流都能直接落地复用。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills