Drug Design Agent

一个面向计算药物研发的可审计工作台：把临床问题、机制假设、分子结构、工具计算、LLM 协作、候选决策和实验反馈组织到同一个研发项目中。

这是一个正在持续建设的开源研究基础设施项目，适合药物化学、计算化学和 AI for Science 团队在本地部署、扩展工具适配器并共同验证研发流程。

当前版本以小分子研发为主。系统用于组织和审阅计算证据，不替代药化专家、湿实验、临床判断或监管决策。

项目概览

Drug Design Agent 的核心对象是“研发项目”。一个项目可以拥有多条版本化 DAG 工作流、分子数据集、候选决策、文献证据、实验记录、SAR 复盘和阶段评审。

能力	当前状态	说明
项目驾驶舱与研发链路	可用	汇总研究定义、后台任务、证据缺口和最近资产
分子数据集工作区	可用	SMILES/CSV/TSV/SDF 导入、RDKit 标准化、去重、筛选、版本和二维预览
多目标候选决策	可用	硬约束、Pareto 前沿、加权排序、scaffold 多样性和人工审阅
RDKit / Dimorphite-DL 分子处理	beta	标准化、质子化枚举、结构警示、构象生成和基础性质
RCSB / PubChem / ChEMBL 数据源	beta / 服务依赖	查询过程、来源、响应哈希和数据质量会被记录；官方服务异常会显式提示
Vina / ProLIF 对接工具箱	beta	已完成技术回归和 1IEP 重对接基准，具体靶点仍需体系级验证
LLM / Agent 协作	受控 beta	生成计划、DAG 提案和结果反思草案，必须经过 Schema 校验与科学家批准
DeepCYP	接口模拟	只验证统一 I/O，不产生真实预测值

核心架构

平台把智能化和工具化分开：LLM 负责理解和生成，Agent 负责组织目标、状态、工具和行动，Skill 固化版本化研究方法，Tool Adapter 执行真实计算，DAG 固定可复现流程，Memory 保存项目状态与研发证据。

flowchart LR
    Scientist[科学家目标与约束] --> Agent[受控 Agent]
    Agent --> LLM[LLM 推理与生成]
    Agent --> Skill[版本化 Skill]
    Agent --> Approval{科学家批准}
    Approval --> DAG[DAG 工作流]
    DAG --> Adapter[Tool Adapter / MCP]
    Adapter --> Tools[RDKit · Vina · ProLIF · 数据源]
    Tools --> Evidence[运行结果与证据]
    Evidence --> Cockpit[项目驾驶舱 / 候选决策 / SAR]
    Cockpit --> Scientist

Loading

关键边界：LLM 不伪造工具结果、不直接修改历史证据、不绕过审批；planned 节点可以用于设计流程但不能运行；beta 节点的适用域和回归证据必须在目标体系中重新确认。

界面预览

项目驾驶舱、分子数据集和完整 Vina DAG 是当前最主要的三个工作面：

完整的图文说明书位于 docs/；本地启动后可访问 /guide。PDF 是可选的本地导出产物（仓库不提交生成文件），可在具备文档构建依赖的环境中运行 python scripts/build_platform_manual_pdf.py 生成。

目录

• 本地运行
• 研发链路
• 工作流与工具箱
• LLM、Agent 与 Skill
• 开发、测试与前端构建
• 数据与安全
• 文档与接口
• 贡献方式
• 许可证

研发链路

正式研发链路是：

研究问题 → 研究定义 → 文献与结构数据 → 分子数据集 / 研发流程 → 候选优选与决策 → 分子设计 → 合成可行性与任务 → 实际样品批次 → 实验交接与反馈 → SAR / 设计复盘 → 阶段评审

项目驾驶舱负责呈现状态和缺口，不自动生成科学总分或 Go/No-Go 结论。候选决策保存算法排序与科学家审阅的区别；实验判读、阶段评审和证据包均采用追加式记录，历史结果不会被静默覆盖。

各模块职责与边界：

1. 一个研发项目从结构化研究定义开始，保存适应症/患者群体、未满足临床需求、疾病与耐药生物学、机制假设、分子设计标准、候选分子和实验反馈。
2. 项目默认进入研发驾驶舱，汇总研究定义完整度、后台任务、确定性记录缺口、候选实验覆盖和最近研发资产；驾驶舱不生成科学评分或阶段门结论。
3. 一个项目可以拥有多条 DAG 工作流及其运行记录。
4. 项目页和研发流程内置项目助手与流程助手，研发助手页面用于汇总对话记录。
5. ChEMBL、PubChem 与 RCSB 官方接口负责公开数据获取；RDKit 与 Dimorphite-DL 负责真实分子处理；DeepCYP 当前只提供接口模拟。对接工具箱已接入 PDBFixer、Meeko、Vina 和 ProLIF；Vina 已通过 1IEP/STI-571 重对接基准，ProLIF 已通过 PDBQT 相互作用解析技术回归，两者均处于 beta，具体靶点仍需体系级验证。
6. Vina、ProLIF、构象生成和受体准备等长任务由后台运行记录承载。页面提交后显示运行编号、预计耗时和参考完成时间，可离开页面；当前流程左侧“运行记录”保留最近 30 次状态，点击后按需读取完整结果。结果完成后保存在本地数据库。分子数据集、候选池、优选结果和流程结果统一通过 RDKit 显示二维结构预览。
7. 对接审查按运行保存代表 pose、人工状态和备注；受体与 pose 的原始 PDBQT 可以从结果页下载。审查意见不覆盖 Vina 输出，也不被解释为实验结论。
8. 对接结果提供按需加载的 NGL 3D 审查工作区，可叠加受体和当前 pose、切换姿势、聚焦和旋转；包含 ProLIF 结果时还会高亮关键残基和作用连线。该视图用于几何复核，不产生新的科学评分。
9. 阶段评审可以建立不可变研发证据包，冻结当时使用的流程运行、数据集版本、候选、决策、实验、判读和假设证据；支持 JSON 与可打印 HTML 导出。实验结果后续修订会保留追加式修订历史，不改写已建立的证据包。
10. 项目“SAR 工作区”按实验类别、名称、终点、单位、物种、模型系统和协议版本划分可比上下文，展示实验矩阵、pActivity、Bemis-Murcko 化学系列和 matched molecular pairs；不同上下文不会静默合并。
11. 项目“分子设计”把 SAR 观察组织为设计轮次、可证伪结构假设和母体—子体提案；Ketcher standalone 提供网页内二维结构编辑，科学家选择后才进入候选池，实验回流形成不可变设计复盘。
12. 项目“合成与交接”保存人工路线评估、合成任务、实际样品批次和判别实验交接；合成失败、纯度与批次身份都成为可追溯研发记录，assay 可绑定实际批次。

当前分数是基线成药性分数，不包含靶点活性、选择性、真实 ADMET 或临床成功概率，不能替代药化专家和实验判断。

本地运行

环境要求

• macOS Apple Silicon 或 Linux x86_64
• Miniforge/Conda
• Python 3.11
• Node.js 22 和 npm
• 建议至少 8 GB 可用内存；对接和批量计算需要更多资源

从仓库启动

git clone https://github.com/xiaoli/DrugDesignAgent.git
cd DrugDesignAgent

推荐使用 Python 3.11、Miniforge 和 conda-forge。完整的新机器重建、平台差异、验收和数据迁移规范见 环境重建文档。

首次创建核心环境：

conda env create -f environment.yml
conda activate drug-design-agent
cd frontend
npm ci
npm run build
cd ..
PYTHONPATH=src python -m pytest -q

以上命令均从仓库根目录执行；如果你的本地目录名称不同，不需要额外改动环境文件。

需要从零安装完整对接依赖时，使用 conda env create -f environment-full.yml。已有核心环境只需执行 conda env update -n drug-design-agent -f environment-docking-v1.yml。

也可以在已有 Python 3.11 环境中安装核心依赖：

python -m pip install -r requirements-dev.txt

requirements.txt 与 pyproject.toml 保存核心运行依赖，其中包括可执行质子化节点所需的 Dimorphite-DL 2.x；requirements-dev.txt 追加测试依赖。requirements-toolbox-optional.txt 仅作为旧安装入口兼容保留，现在会直接引用核心依赖。

日常启动使用：

conda activate drug-design-agent
PYTHONPATH=src uvicorn drug_design_agent.main:app --reload

打开 http://127.0.0.1:8000。API 文档位于 http://127.0.0.1:8000/docs。

研发流程位于 http://127.0.0.1:8000/workflows。推荐从研发项目的“研发流程”标签中新建流程，使 campaign_id 自动继承；也可以在流程页左侧选择所属项目。流程名称可在顶部直接编辑，保存后会显示在项目的流程列表中。

研发项目和研发流程均支持安全生命周期管理：优先归档并可随时恢复；永久删除前会展示候选、实验、流程运行、提案与 AI 上下文等影响范围，只有输入完整名称后才能确认。后端始终按对象 ID 定位并再次校验名称，同名对象不会被连带删除。项目删除不会触碰公共数据源缓存、全局模型服务或全局技能库。完整边界与 API 见 生命周期文档。

项目中的“分子数据集”页签提供持久数据资产工作区：可导入 SMILES、CSV/TSV 和 SDF，或保存同一项目最近一次流程运行的完整分子结果；系统执行 RDKit 解析、InChIKey 去重、基础性质与警示计算。性质筛选和历史恢复都会创建新版本，支持两个数据集按结构身份比较；科学家选择的有效结构可以显式加入项目候选池，并导出 CSV、SMILES 或 SDF。文件只发送到本地服务，不进入 LLM 上下文。协议和科学边界见 分子数据集工作区 V1。

项目中的“候选优选与决策”页签提供多目标评分与人工审阅：V1 以 RDKit 指标执行硬性约束、Pareto 前沿、加权排序和 scaffold 多样性 shortlist。每次运行冻结数据集版本、指标版本、权重和逐分子结果；算法 recommended 只进入审阅表单，不会自动成为科学家决定。只有保存为 advance 的记录才能显式加入项目候选池。详细契约见 多目标评分与候选决策 V1。

快速分子检查仅用于少量结构的临时 RDKit 基线检查；路线评估是人工药化判断，不是自动逆合成预测。统一的平台说明书位于 http://127.0.0.1:8000/guide（旧地址 /architecture 保留兼容），同时提供架构说明、研发链路和操作步骤。合并后的平台介绍与技术说明位于 http://127.0.0.1:8000/presentation，同一套网页幻灯片覆盖产品价值、研发闭环、LLM、Agent、Skill、Tool、MCP、DAG 与 Memory，并支持键盘翻页、演讲提示、全屏和打印 PDF。

LLM、Agent 与 Skill

研发助手是可选的控制层组件：项目级作用域用于目标拆解，流程级作用域用于 DAG 提案和 GraphPatch。所有提案先经过 Schema、工具目录和 DAG 校验，再由科学家确认；助手不直接执行工具、不修改历史结果，工具输出仍由 Tool Adapter 产生。研究技能是版本化的提示与审查规则，不扩展工具能力。具体协议见统一的平台说明书 http://127.0.0.1:8000/guide。

工作流与工具箱

研发流程左侧提供分子处理、接口模拟和对接流程模板：

• “RDKit 基线模板”计算基础理化性质和基线成药性分数。
• “分子质控模板”执行结构标准化、Dimorphite-DL 质子化状态枚举、PAINS/Brenk 警示和 Morgan + Butina 多样性选择。
• “3D 构象模板”使用 ETKDGv3 生成构象，并可选用 UFF 做几何优化。
• “DeepCYP 接口模拟”只验证 Tool Adapter v1 的批量输入、逐分子错误和证据保存，不生成科学预测。
• “对接输入准备 V1”是当前可运行模板：RCSB 蛋白结构、质子化、RDKit 三维构象、Meeko 配体 PDBQT、PDBFixer 和 Meeko 受体 PDBQT，最后输出可追溯的准备产物，不生成对接分数。
• “Vina 对接筛选 V1”是 beta 可运行模板；它包含输入准备并继续运行 Vina。模板默认选择 1IEP A 链并使用基准搜索盒，运行前仍必须确认配体 PDBQT、受体 PDBQT、链选择、搜索中心和搜索盒。Vina 已通过 1IEP 重对接基准，但这不代表对其他靶点有排序能力。
• “对接结果解析 V1”在完整 Vina 流程后运行 ProLIF，输出 pose 级相互作用、关键残基、最短重原子距离和短接触警示，并在 NGL 中呈现残基与作用连线。几何规则不等于实验结合证据。
• BindingDB 旧 BDBService 已失效，模板移入“验证中与待接入”。历史 BindingDB 流程会在运行前停止，并提供新建 PubChem 分子流程的入口；PubChem 结构数据不冒充 BindingDB 靶点活性。

节点状态、准备产物、对接结果和操作步骤见 分子对接工具箱 V1。

对接依赖使用 conda-forge 单独管理，不加入核心 requirements.txt，以免 Open Babel、Vina 等平台二进制依赖破坏基础环境。在现有环境中安装：

conda activate drug-design-agent
conda env update -n drug-design-agent -f environment-docking-v1.yml

安装后可通过 GET /api/tool-runtime-status 查看依赖和节点执行状态。当前使用 Vina Python API，不要求独立 vina 命令位于 PATH。依赖可见不代表科学适配器已经验证；每个节点仍按 Manifest 生命周期和回归要求独立开放。

1IEP 重对接基准

Vina 节点已通过公开的 Abl/STI-571 共晶体系受控重对接，三次固定种子运行的 top-1 对称性校正重原子 RMSD 均为 0.2946 Å（门槛 ≤ 2.0 Å）。输入选择、运行命令、重复结果和科学边界见 1IEP 基准说明 与 benchmark.json。离线脚本位于 scripts/run_1iep_redocking.py；该基准不代表其他靶点具备结合排序能力。

所有工具保留稳定或可追溯的 molecule_id、适配器版本、运行耗时、警告和逐分子错误。多质子化状态使用确定性派生 ID，并保存父分子 ID、pH 条件、精度因子和上游库版本。质子化枚举不是实验微观 pKa 或状态丰度；结构警示不是自动淘汰规则；ETKDG 不是实验构象分布；UFF 能量不是结合能，也不能跨分子排序。

全部研发助手对话位于 http://127.0.0.1:8000/assistant。

文档与接口

架构与 Tool I/O 规范位于统一的平台说明书 http://127.0.0.1:8000/guide。对应的机器可读协议：

• GET /api/tool-manifests
• GET /api/tool-runtime-status
• GET /api/contracts/tool-io
• GET /api/contracts/agent
• GET /api/agent-skills
• GET /api/campaigns/{campaign_id}/skills
• PUT /api/campaigns/{campaign_id}/skills
• GET /api/campaigns/{campaign_id}/deletion-impact
• PUT /api/campaigns/{campaign_id}/archive
• DELETE /api/campaigns/{campaign_id}
• GET /api/workflows/{workflow_id}/deletion-impact
• PUT /api/workflows/{workflow_id}/archive
• DELETE /api/workflows/{workflow_id}
• GET /api/campaigns/{campaign_id}/datasets
• POST /api/campaigns/{campaign_id}/datasets/import
• POST /api/campaigns/{campaign_id}/datasets/from-workflow
• GET /api/datasets/{dataset_id}
• GET /api/datasets/compare/current
• POST /api/datasets/{dataset_id}/filter
• PUT /api/datasets/{dataset_id}/selection
• POST /api/datasets/{dataset_id}/promote-candidates
• GET /api/datasets/{dataset_id}/export
• GET /api/campaigns/{campaign_id}/assay-summary
• POST /api/campaigns/{campaign_id}/assays
• PUT /api/campaigns/{campaign_id}/assays/{assay_id}
• GET /api/campaigns/{campaign_id}/sar-workspace
• GET|POST /api/campaigns/{campaign_id}/design-cycles
• GET|PUT /api/campaigns/{campaign_id}/design-cycles/{cycle_id}
• GET|POST /api/campaigns/{campaign_id}/design-hypotheses
• GET|POST /api/campaigns/{campaign_id}/design-proposals
• PUT /api/campaigns/{campaign_id}/design-proposals/{proposal_id}/status
• POST /api/campaigns/{campaign_id}/design-proposals/{proposal_id}/promote
• POST /api/campaigns/{campaign_id}/design-proposals/{proposal_id}/reviews
• GET /api/campaigns/{campaign_id}/research-assets
• GET /api/campaigns/{campaign_id}/evidence-packages
• POST /api/campaigns/{campaign_id}/evidence-packages
• GET /api/campaigns/{campaign_id}/evidence-packages/{package_id}
• GET /api/campaigns/{campaign_id}/evidence-packages/{package_id}/export?format=json|html
• GET /api/decision-metrics
• GET /api/campaigns/{campaign_id}/decisions
• POST /api/campaigns/{campaign_id}/decisions
• GET /api/decisions/{decision_id}
• PUT /api/decisions/{decision_id}/reviews
• POST /api/decisions/{decision_id}/promote-candidates

结构化流程提案接口：

• GET /api/llm/workflow-proposals?campaign_id={campaign_id}：读取项目提案及审批状态。
• POST /api/llm/workflow-proposals：根据项目目标生成并校验待审提案，不创建或运行流程。
• POST /api/llm/workflow-proposals/{proposal_id}/decision：接受或放弃提案；接受时原子化创建流程草稿。
• GET /api/llm/workflow-revisions?workflow_id={workflow_id}：读取流程修改提案及审批状态。
• POST /api/llm/workflow-revisions：根据自然语言要求生成并校验 GraphPatch，不直接修改流程。
• POST /api/llm/workflow-revisions/{revision_id}/decision：接受或放弃修改；接受时执行版本检查并原子更新流程。

模型服务设置位于 http://127.0.0.1:8000/settings/models。支持 OpenAI Compatible、Anthropic 与 Ollama；API Key 保存在权限受限的本地 SQLite 数据库中，不会由查询接口返回，也不会写入浏览器存储或工作流 JSON。

开发、测试与前端构建

研发流程编辑器使用 React Flow，二维分子画板使用 Ketcher standalone。修改 frontend/src 后重新构建：

conda activate drug-design-agent
cd frontend
npm ci
npm run build

构建产物会写入 src/drug_design_agent/static/workflow，由 FastAPI 直接提供。

conda activate drug-design-agent
PYTHONPATH=src pytest

建议每次提交前运行完整测试和前端生产构建。测试覆盖工作流契约、工具适配器、数据集版本、候选决策、证据包、LLM 提案和资源生命周期。

数据与安全

默认数据库位于 data/drug_design.db。可用环境变量 DDA_DATA_DIR 指定其他目录：

DDA_DATA_DIR=/path/to/data PYTHONPATH=src uvicorn drug_design_agent.main:app

迁移已有系统时应先停止应用，再迁移整个 data 目录。数据库包含模型服务 API Key，不得提交到 Git 或放入公开存储；仅重建 Conda 环境不会恢复研发项目和模型配置。

数据源工具箱不增加新的 Python 依赖：HTTP 客户端已经是核心依赖。ChEMBL、PubChem 和 RCSB 响应缓存位于 data/cache/data_sources_v1/（或 DDA_DATA_DIR/cache/data_sources_v1/），迁移时与数据库一并处理。详细协议和科研边界见 开源数据源工具箱 V1。

贡献方式

欢迎提交问题、文档改进、工具适配器和可复现实验回归。涉及科学计算的变更请同时提交：

• 明确的输入/输出 Schema 与工具版本；
• 固定输入的回归结果、适用域和已知限制；
• 对应的单元测试或契约测试；
• 对 README 或 docs/ 的使用说明更新。

请不要提交 data/ 下的数据库、缓存、API Key、受版权保护的文献原文、个人数据或大体积结构结果。提交前运行 git diff --check，并确认没有敏感文件进入暂存区。

许可证

仓库当前尚未附带正式 LICENSE 文件。代码和文档的公开使用、再分发及第三方组件组合方式，应以仓库后续发布的许可证为准；在许可证确定前，请通过 Issue 讨论具体的商业使用或再分发需求。RDKit、Vina、Meeko、ProLIF、Ketcher、NGL 以及公开数据源各自拥有独立的许可证和使用条款，集成或再分发前请逐项核查。

近期路线

• v0.1：分子规范化、基线性质评估、实验反馈记录。
• v0.2：ChEMBL/PubChem/RCSB 数据源、靶点确认、活性关系与单位标准化（V1 已完成）；下一步补充离线快照、Parquet 大数据存储和骨架切分验证。
• v0.3：接入服务器上的 Chemprop/GNN 活性模型和不确定性估计。
• v0.4：虚拟筛选、对接结果、多目标 Pareto 排序和候选优选审阅（V1 已完成）。
• v0.5：用实验结果驱动主动学习，建议下一批最值得测试的分子；当前已完成实验反馈标准化和候选来源回溯基础。