靶点结构和候选分子拖进来，剩下的交给向导：结构修复、加氢、口袋定位、
对接计算、结合能热图与中文报告，全部在本地完成。
示例项目：3CQW 与 1BCI 两个靶点 × Quercetin，QuickVina 2 完成 2/2 组对接，最佳 −8.50 kcal/mol。
对接分数用于同一项目内排序，不等同于实验测得的结合亲和力。
|
全流程跑通，不装第二套软件 结构修复、按 pH 加氢、PDBQT 生成、几何口袋检测、对接、热图、HTML 报告都在一个窗口里。 安装包内置三种对接引擎与无界面 PyMOL，不需要再配置 AutoDock Tools。 |
完全离线，数据不出本机 没有账号、没有卡密、没有云端队列。项目文件只写在你选择的目录里；除主动从 PDB / PubChem / AlphaFold / ChEMBL 下载结构外，其余计算全部在本机完成。 |
|
自动识别，不为难非计算背景的用户 程序根据结构内容判断靶点与候选分子类型，自动选择准备流程；遇到不支持的组合会直接 说明原因并给出替代工具，而不是给出一个看起来合理的假分数。 |
自动化，但不黑箱 自动补全缺失原子、去除非标准残基、检测口袋、用共晶配体或 PDB SITE 交叉校验。 每一步的判断依据、警告和跳过原因都会显示在准备页与报告里。 |
|
科学可信，可复现 分数来自 AutoDock Vina / QuickVina 2 / Smina 的真实输出；报告记录引擎与版本、盒子中心与 尺寸、exhaustiveness、随机种子和 CPU 数。同一套条件可以重复跑。 |
三种引擎，卡死不硬扛 Vina 在个别复合物上可能长时间无输出。可以随时切换 QuickVina 2 或 Smina，也可以开启 “失败自动回退”，让程序换一个已安装的引擎重试。 |
|
结果直接能看、能汇报 结果表、结合能热图、柱状图、可离线打开的中文 HTML 报告；热图可改标题、靶点名称与 配色，并导出 PNG / SVG / PDF。 |
跨平台，也能批处理 Windows 与 macOS 使用同一套 Python 服务层；图形界面与命令行共享准备、对接、报告逻辑， 便于在服务器上批量跑项目。 |
1 · 工作目录首页把流程归纳为四件事：选目录、加结构、一键准备、设置并运行。所有文件留在同一个项目目录。 |
2 · 检查与准备自动补全缺失原子、加氢并生成 PDBQT；非标准残基、离子与配体处理都会逐条说明。 |
3 · 设置对接每个靶点独立设置盒子；几何口袋与共晶配体 / PDB SITE 交叉验证，给出建议尺寸。 |
4 · 3D 盒子编辑器拖动盒子手柄，或直接点击原子设置中心；实时显示尺寸、体积与判断依据。 |
左：全局橙色风格，快速检查复合物整体构象。右：浅青细节风格，标出残基标签与氢键距离，可直接用于汇报。
## 核心实现 这一节把受体/配体预处理、口袋预测和盒子生成写清楚。目的不是宣称发明了对接算法， 而是让实现**可核查**：哪些思想来自公开文献或开源组件，哪些是本项目自己的工程实现。 相关代码集中在 `src/dockflowlab/services/`，可以直接对照阅读。 ### 1. 受体预处理：先让结构“可对接” 入口：[services/receptor.py](src/dockflowlab/services/receptor.py)。图形界面的“开始准备” 与命令行的 `prepare` 走同一条服务层路径，不会出现两套结果。 1. **识别结构类型。** 按文件内容而不是扩展名判断蛋白质、多肽、核酸或小分子；小分子不能 放在靶点栏，会提示改用“候选分子”。PDBQT 直接校验并复用；PDB 有多个 `MODEL` 时只取 第一个；mmCIF 先经 OpenBabel 转成 PDB，再进入统一流程。 2. **按链选择并排除共晶配体链。** 链选择按索引而不是链 ID，避免重复链 ID 或空链 ID 误删。 多肽类共晶配体有时被拆成标准氨基酸（`ATOM`）记录，`removeHeterogens` 删不掉，程序会 先用 `find_ligand_chains` 找到整条配体链并移除，防止它占据结合位点。 3. **PDBFixer 修复。** 替换 MSE 等非标准残基；默认调用 `removeHeterogens(keepWater=False)` 移除水、金属离子、共晶配体和辅因子；补全缺失残基 与缺失原子（固定随机种子 42，保证可复现）；最后按 pH 7.4 加氢。补全残基超过 30 个时 会提示模型可靠性下降。 4. **保留辅因子模式。** 高级用户可以保留非水、非离子的小分子辅因子；程序会明确警告 “请确认它们确实应作为受体的一部分”，不会默认替用户做这个判断。 5. **转成刚性 PDBQT。** 修复后的 PDB 交给 OpenBabel，以 Gasteiger 电荷、`rigid=True` 写出受体 PDBQT，再用内置校验器检查原子数与格式。受体默认保持实验构象，不做全局能量 最小化，减少对实验结构的扰动。 6. **失败不静默。** PDBFixer/OpenMM 不可用或修复失败时，退化为 OpenBabel 加氢与格式转换， 并在结果里明确写出“结构未经过完整修复，缺失残基/原子不会被补全”。如果两种路径都不可 用，任务直接失败，不会拿一个未经处理的结构继续对接。 > 输出：`prepared/targets/<名称>/` 下的修复版 PDB 与 PDBQT，旁边保留每一步的警告与统计。 ### 2. 配体预处理：从任意格式到可旋转 PDBQT 入口：[services/ligand.py](src/dockflowlab/services/ligand.py)。 1. **类型闸门。** 候选分子栏只接受小分子。若文件实际是蛋白质、多肽或核酸，程序会拒绝， 并提示把大分子放到“靶点结构”或不支持该体系，避免把蛋白误当成配体。 2. **读取。** SDF/MOL/MOL2 由 RDKit 读取；SDF 多记录时取第一条并警告；价态异常的记录用 宽松模式读取；RDKit 失败时先经 OpenBabel 转成 SDF 再读。已有 PDBQT 只做校验和复用。 3. **去盐与去溶剂。** 用 RDKit 拆分子片段，保留重原子最多的有机片段，移除盐、溶剂等 小碎片，并报告移除了多少重原子。 4. **补氢与三维构象。** 先 `Chem.AddHs`；输入只有二维坐标时用 **ETKDGv3** 生成三维构象 （随机种子 42，失败时改用随机初始坐标重试）。如果分子已有三维坐标，则保留原构象。 5. **能量最小化。** 优先 MMFF94s；参数不全时退到 UFF；最多 500 步。没有可用力场时保留 输入构象并明确警告，不假装“优化过”。 6. **生理 pH 质子化校正（可选）。** 通过 OpenBabel 的 pH 模型在 7.4 下重新分配质子化 状态。只有重原子数不变时才接受校正结果，否则保留输入结构并警告。 7. **生成柔性 PDBQT。** 用 Meeko 的 `MoleculePreparation` + `PDBQTWriterLegacy` 写出 含 `ROOT/BRANCH/TORSDOF` 的可旋转配体；校验通过才落盘。Meeko 失败时回退到 OpenBabel， 并在结果中注明回退路径。 8. **刚性靶点模式。** 小分子–小分子对接时，先按上述流程准备，再移除扭转树，把该分子 转成刚性受体，保证搜索空间只落在另一个分子上。 > 重原子超过 200 个或可旋转键超过 20 个时，程序会提示搜索空间和耗时显著增加；这类结果 > 应视为初步筛选，而不是高置信度结合模式。 ### 3. 口袋预测：不依赖外部二进制的 LIGSITE 式实现 入口：[services/pockets.py](src/dockflowlab/services/pockets.py)。实现只依赖 NumPy/SciPy， 不需要另外安装 fpocket、P2Rank 等可执行文件，因此可以随应用跨平台打包，也方便逐行审查。 算法使用 **LIGSITE 的 P-S-P（protein–solvent–protein）思想**，具体步骤是： 1. **建网格。** 只取聚合物残基的重原子，按范德华半径把蛋白质占据的区域标记到网格上。 默认间距 1.0 Å；结构很大时自动放宽到不低于 0.75 Å，并把网格单元总数限制在约 300 万， 防止内存失控。 2. **找可及空腔。** 用 1.4 Å 探针（约等于水分子半径）计算每个空网格点到最近原子范德华 表面的净空；再做三维连通，只保留与网格边界相连的溶剂区域，排除完全封闭的内部空腔。 3. **七方向包埋扫描。** 沿 x、y、z 和 4 条体对角线，在 9 Å 范围内检查每个空腔点两侧是否 都能看到蛋白质，统计“P-S-P”成立的方向数。方向数越多，说明这个点被蛋白包围得越严实。 4. **形成候选口袋。** 保留同时满足以下条件的点：至少 4 个方向包埋、探针可及、与外部溶剂 连通、距离蛋白质表面不超过 5 Å。然后做 3×3×3 连通聚类。 5. **过滤与打分。** 每个簇至少 20 个网格点、最大跨度不超过 35 Å、占据包围盒的比例不低于 0.02。综合分数为： ```text score = 0.45 × 包埋度 + 0.20 × 体积分数 + 0.15 × 紧密度 + 0.10 × 深度 + 0.10 × 疏水性 ``` - 包埋度：平均 P-S-P 方向数 / 7； - 体积分数：`log1p(points / 50) / log1p(10)`，限制在 0–1； - 紧密度：网格点占包围盒比例 / 0.15，限制在 0–1； - 深度：平均表面距离 / 2.5 Å，限制在 0–1； - 疏水性：口袋点最近原子中 C/S 原子的比例。 6. **排序与缓存。** 按分数降序返回前 8 个口袋，同时给出中心、尺寸、体积、包埋度、深度、 疏水性和附近残基。结果按“文件路径 + 修改时间 + 大小 + 链”缓存，界面切换页面时不会 重复扫描。 这套实现是**几何启发式**：它回答“哪里像一个能被小分子进入的凹槽”，不预测结合亲和力， 也不保证一定具有生物学功能。有共晶配体或 PDB SITE 记录时，实验证据始终优先于几何预测。 ### 4. 盒子生成：证据优先，几何兜底 入口：[services/boxes.py](src/dockflowlab/services/boxes.py)。自动盒子按固定顺序决策， 每一步都会把来源写进 `Box.source` 和 `Box.note`，报告里可以追溯： | 顺序 | 依据 | 行为 | | --- | --- | --- | | 1 | 用户手动设置 | 采用用户中心/尺寸，并确保不小于“配体尺寸 + 安全边距” | | 2 | 用户提供的参考分子 | 以参考分子坐标为位点，向外扩 `box_padding` | | 3 | 几何口袋 + 共晶配体一致 | 采用联合盒子：口袋裁剪到配体附近 ±4 Å，再留 4 Å 边距 | | 4 | 共晶配体（无一致口袋） | 以共晶配体为中心，尺寸加两侧 padding | | 5 | 几何口袋 + PDB SITE 一致 | 采用联合盒子，规则同上 | | 6 | PDB SITE 记录（无一致口袋） | 以 SITE 残基坐标为中心，外扩 6 Å | | 7 | 无可靠证据 | 全结构盲对接，并明确警告结果仅供初步筛选 | 几个关键细节： - **一致性不是看距离，而是看覆盖。** 对每个实验位点，计算其重原子到最近口袋采样点的 距离；距离 ≤ 5 Å 视为被口袋覆盖。共晶配体要求覆盖率 ≥ 0.35，PDB SITE 要求 ≥ 0.50。 共晶配体阈值更低，是因为配体可能伸出口袋；SITE 记录本身就是口袋衬里残基，所以要求更严。 - **联合盒子会裁掉远端。** 细长的溶剂通道会让口袋包围盒异常膨胀；与实验位点联合时，只保留 实验位点 ±4 Å 范围内的口袋部分，再加 4 Å 边距，既保留口袋形状又控制搜索空间。 - **盒子必须装得下配体。** 程序读取每个候选分子的三维跨度，按“逐轴最大跨度 + 两侧各 4 Å” 计算最低尺寸；手动盒子、参考分子盒子、口袋盒子、共晶盒子和盲对接盒子都会与这个最低 尺寸取逐轴最大值。 - **尺寸有边界。** 默认限制在 18–60 Å（可在设置中调整）；手动输入允许 5–150 Å，但超出 默认范围会给出提示。体积超过 40,000 ų 提示耗时增加，低于 1,500 ų 提示可能限制构象。 - **小分子靶点单独处理。** 分子–分子对接时，盒子以靶点分子为中心，覆盖两个分子的总跨度， 并提示用户检查结果。 ### 5. 为什么这样设计 - **先把证据用尽，再猜。** 共晶配体和 PDB SITE 是实验信息；几何口袋只是补充。两者一致时 联合使用，不一致时明确回退并说明原因，避免“检测到一个口袋就当成结合位点”。 - **所有降级都可见。** PDBFixer 失败、Meeko 失败、几何口袋不可用、盲对接等情况都会写入 警告和报告，不会静默换一条路径。 - **可复现优先。** 固定的默认随机种子、明确记录引擎版本/盒子来源/尺寸，以及保留引擎原始 输出，都是为了同一项目能复核。 - **不把几何预测包装成实验结论。** 口袋分数、盒子来源和对接分数是三类不同信息，报告里 分开呈现。 ### 6. 算法来源与原创性说明 DockFlowLab 的 Python 代码为独立实现，未直接复制 fpocket、P2Rank、AutoDockTools 等项目的 源码。但**算法思想不是凭空产生的**，主要来自公开文献和开源组件： | 环节 | 采用的思想 / 组件 | 来源 | 本项目的工作 | | --- | --- | --- | --- | | 口袋检测 | LIGSITE 的 P-S-P 扫描与溶剂连通性 | Hendlich et al., 1997 | NumPy/SciPy 网格实现、评分权重、缓存、与实验位点的一致性校验 | | 分子对接 | AutoDock Vina / QuickVina 2 / Smina | Trott & Olson, 2010；Eberhardt et al., 2021；Alhossary et al., 2015；Koes et al., 2013 | 引擎适配、卡死/失败回退、结果归一化与报告 | | 配体读取与构象 | [RDKit](https://www.rdkit.org/)；ETKDGv3；MMFF94s / UFF | Riniker & Landrum, 2015；Halgren, 1999 | 读取、去盐、三维构象、能量最小化、pH 校正与回退 | | 结构修复 | [PDBFixer](https://github.com/openmm/pdbfixer) / OpenMM | Eastman et al., 2017 | 链与共晶配体处理、警告、OpenBabel 回退 | | 格式转换 | OpenBabel | O'Boyle et al., 2011 | 统一适配器、PDBQT 校验 | | 配体 PDBQT | [Meeko](https://github.com/forlilab/Meeko)（Forli lab） | Meeko 文档与源码 | 集成、校验、OpenBabel 回退 | | 3D 视图 / 出图 | NGL Viewer；[PyMOL](https://pymol.org/)（Schrödinger） | Rose et al., 2018 | 嵌入、无界面渲染、风格脚本 | | 盒子决策 | 证据优先的决策树 + 覆盖率共识 | 本项目 | 决策顺序、联合盒子裁剪、配体尺寸约束、边界与警告 | **本项目的原创部分**主要是工程与决策层：跨平台预处理流水线及其回退、口袋检测的具体实现与 评分、口袋/共晶配体/SITE 的一致性校验、盒子决策树与尺寸约束、以及把这些步骤组织成可追溯 的桌面工作流。底层物理模型、评分函数和文件格式并不是本项目发明的。 如果你认为某段实现与现有项目过于相似、或某篇文献应被补充引用，欢迎提交 Issue 指出； 我们会核对代码来源并更新署名。MIT 许可只覆盖本项目的原创代码，内置第三方组件仍遵循各自 的许可证，详见[许可与致谢](#许可与致谢)。 ### 主要参考文献 1. Hendlich M, Rippmann F, Barnickel G. LIGSITE: automatic and efficient detection of potential small molecule-binding sites in proteins. *J Mol Graph Model*. 1997;15(6):359–363. doi:10.1016/S1093-3263(98)00002-3 2. Trott O, Olson AJ. AutoDock Vina: improving the speed and accuracy of docking with a new scoring function, efficient optimization, and multithreading. *J Comput Chem*. 2010;31(2):455–461. doi:10.1002/jcc.21334 3. Eberhardt J, Santos-Martins D, Tillack AF, Forli S. AutoDock Vina 1.2.0: new docking methods, expanded force field, and Python bindings. *J Chem Inf Model*. 2021;61(8):3891–3898. doi:10.1021/acs.jcim.1c00203 4. Alhossary A, Handoko SD, Mu Y, Kwoh CK. Fast, accurate, and reliable molecular docking with QuickVina 2. *Bioinformatics*. 2015;31(13):2214–2216. doi:10.1093/bioinformatics/btv082 5. Koes DR, Baumgartner MP, Camacho CJ. Lessons learned in empirical scoring with smina from the CSAR 2011 benchmarking exercise. *J Comput Aided Mol Des*. 2013;27(3):221–234. doi:10.1007/s10822-013-9644-8 6. Riniker S, Landrum GA. Better informed distance geometry: using what we know to improve conformation generation. *J Chem Inf Model*. 2015;55(12):2562–2574. doi:10.1021/acs.jcim.5b00654 7. O'Boyle NM, Banck M, James CA, Morley C, Vandermeersch T, Hutchison GR. Open Babel: an open chemical toolbox. *J Cheminform*. 2011;3:33. doi:10.1186/1758-2946-3-33 8. Eastman P, Swails J, Chodera JD, et al. OpenMM 7: rapid development of high performance algorithms for molecular dynamics. *PLoS Comput Biol*. 2017;13(7):e1005659. doi:10.1371/journal.pcbi.1005659 9. Halgren TA. MMFF VI. MMFF94s option for energy minimization studies. *J Comput Chem*. 1999;20(7):720–729. doi:10.1002/(SICI)1096-987X(199905)20:7<720::AID-JCC7>3.0.CO;2-X 10. Rose AS, Hildebrand PW. NGL Viewer: web-based molecular graphics for large complexes. *Bioinformatics*. 2018;34(21):3755–3758. doi:10.1093/bioinformatics/bty419 ## 支持的对接场景 **候选分子只接受小分子。** 程序不需要你预先选择模式：它根据结构内容自动判断靶点类型， 并在结果中标注对接类型。不支持的组合会直接说明原因，不会继续计算。 | 靶点结构 | 候选分子 | 状态 | 说明 | | --- | --- | --- | --- | | 蛋白质 | 小分子 | ✅ 支持 | 主流程，最可靠 | | 多肽 / 短肽 | 小分子 | ✅ 支持 | 靶点柔性较高，结果需谨慎解读 | | DNA / RNA | 小分子 | ✅ 支持 | 建议结合共晶配体或已知位点设置盒子 | | 小分子 | 小分子 | ✅ 支持 | 靶点按刚性受体处理，适合快速筛选 | | 蛋白质 | 多肽 | ❌ 不支持 | 多肽自由度超出 Vina 可靠搜索范围，请用 HADDOCK / RosettaDock | | 蛋白质 | 蛋白质 | ❌ 不支持 | 请用 ClusPro / HADDOCK / RosettaDock | | 核酸 | 蛋白质 / 多肽 / 核酸 | ❌ 不支持 | 需要专门的核酸–大分子对接工具 | | 小分子 | 蛋白质 / 多肽 / 核酸 | ❌ 不支持 | 请把大分子放在“靶点结构”一栏 | | 多肽 | 多肽 | ❌ 不支持 | 请用 HADDOCK / RosettaDock | ## 快速开始 ### 下载 | 平台 | 推荐文件 | 说明 | | --- | --- | --- | | Windows 10/11 x64 | `DockFlowLab-Windows-x64.zip` | 解压即用，内置三种对接引擎与无界面 PyMOL | | macOS 11+ Apple Silicon | `DockFlowLab-macOS-arm64.dmg` | 拖入“应用程序”即可；内置三种引擎与 PyMOL | - [GitHub Releases](https://github.com/IBN-Spring/DockFlowLab/releases/latest)（推荐，单文件直接下载） - [Gitee 发行版](https://gitee.com/spiral_IBN/dock-flow-lab/releases)（国内网络） - Gitee 单个附件限 100MB，安装包已按 90MB 分卷，并附 `合并并解压-Windows.bat` / `合并并打开-macOS.command` 与 SHA256 校验文件。请下载同一版本的全部分卷后再合并。 ### Windows 1. 下载 `DockFlowLab-Windows-x64.zip` 并解压到任意目录。 2. 双击 `DockFlowLab.exe`。不需要安装，不写注册表。 3. 首次启动若被 SmartScreen 拦截，点击“更多信息 → 仍要运行”。 ### macOS 1. 下载 `DockFlowLab-macOS-arm64.dmg`，打开后把 `DockFlowLab.app` 拖入“应用程序”。 2. 首次打开若提示“无法验证开发者”，右键应用 →“打开”，或在“系统设置 → 隐私与安全性”中允许。 3. 安装包已内置三种引擎与 PyMOL。若要改用本机安装的其他版本，可通过 `brew install autodock-vina` 或 `conda install -c conda-forge vina qvina smina` 安装， 并在“设置”中指定路径。源码运行时同理。 ### 数据放在哪里 | 内容 | Windows | macOS | | --- | --- | --- | | 用户设置 | `%APPDATA%\DockFlowLab` | `~/Library/Application Support/DockFlowLab` | | 日志与缓存 | `%LOCALAPPDATA%\DockFlowLab` | `~/Library/Caches/DockFlowLab` | | 对接项目 | 你选择的任意文件夹 | 你选择的任意文件夹 | 卸载时删除程序文件夹即可；如需彻底清理，再删除上表中的设置与缓存目录。项目目录中的 `inputs/`、`prepared/`、`docking/`、`report/` 等不会被程序删除。 ### 完全离线 安装完成后，结构准备、对接、分析、报告和 PyMOL 渲染都不需要网络。只有你主动点击 “从数据库下载”时，程序才会访问 PDB、PubChem、AlphaFold 或 ChEMBL。没有登录、账号、 授权码或使用次数限制。 ## 命令行 图形界面与命令行共用同一套服务层，适合批处理和服务器环境： ```bash # 检查引擎、OpenBabel、RDKit、Meeko、OpenMM 等组件 dockflowlab-cli doctor # 新建项目 dockflowlab-cli init D:/docking/demo --name 阿司匹林筛选 # 导入结构 dockflowlab-cli import D:/docking/demo protein.pdb --kind target --name 1BCI dockflowlab-cli import D:/docking/demo aspirin.sdf --kind ligand --name 阿司匹林 # 准备、对接、报告 dockflowlab-cli prepare D:/docking/demo dockflowlab-cli dock D:/docking/demo --exhaustiveness 8 dockflowlab-cli dock D:/docking/demo --engine qvina2 dockflowlab-cli report D:/docking/demo ``` 也可以直接从公共数据库下载： ```bash dockflowlab-cli fetch D:/docking/demo pdb 1BCI dockflowlab-cli fetch D:/docking/demo pubchem "aspirin" --kind ligand ``` ## 从源码运行 需要 Python 3.10–3.12。推荐使用 conda 环境（Windows 上 OpenMM 用 conda 安装最省事）： ```bash conda create -n DockFlowLab python=3.12 -y conda activate DockFlowLab conda install -c conda-forge rdkit openbabel openmm pdbfixer -y pip install -e ".[dev]" meeko python -m dockflowlab ``` 只使用 pip 时： ```bash python -m pip install -e ".[chem,dev]" python -m dockflowlab ``` Windows 上若 `openmm` 没有可用的 wheel，请改用上面的 conda 命令。 运行测试： ```bash PYTHONPATH=src python -m pytest ``` 打包分发： ```bat packaging\build_windows.bat ``` ```bash bash packaging/build_macos.sh ``` 产物位于 `release/`，目录版保留在 `dist/`。依赖布局、图标、引擎收集、macOS 签名与公证等 细节见 [docs/packaging.md](docs/packaging.md)。 ## 架构 ```mermaid flowchart LR U[用户] --> GUI[PySide6 图形界面] U --> CLI[命令行] GUI --> S[服务层
如果 DockFlowLab 帮你省下了一个下午的格式转换，欢迎点一个 Star ⭐
GitHub ·
Gitee ·
问题反馈 ·
生信交流群（QQ）306484855