MoleCode

把分子表示成显式图代码,让大语言模型直接读、写和编辑分子结构,而不是费力从 SMILES 字符串里重建拓扑。

Star 数
★ 311
最近更新
5 个月前
License
MIT
主语言
Python

30 秒速览

运行形态
代码库 / SDKAgent 插件 / 技能
可在哪里用
通用 · 跨平台Codex · Claude Code
费用
软件免费,模型调用费用自付
上手难度
低 · 几分钟可跑通
开始前需要
Python 3.9+RDKitnetworkxShell / 命令行本地文件系统
典型场景
药物化学家想让 Claude Code 或 Codex 直接在命名原子/键层面编辑分子(如加一个甲基),并得到 RDKit 确定性校验
不适合
  • 需要纯字符串 SMILES 管线且不愿切换表示格式的团队
  • 不需要 LLM 参与化学推理、只想做传统化学信息学的用户
  • 期望开箱即用托管 Web 应用而非代码库的用户
官网
arxiv.org/pdf/2605.16480 ↗ 来自 GitHub 仓库设置
维护状态
近半年有提交最近提交 2026-06-04

这个 Agent 能做什么,适合哪些场景?

MoleCode(AtomFlow-AI/MoleCode,MIT 许可)是一种面向 LLM 的分子表示语言:原子和化学键被写成带持久标识符的类型化声明,序列化为 Mermaid 图,拓扑在上下文窗口中直接可读、可编辑、可审计。它通过 RDKit 与 SMILES/MOL 无损、确定性互转,不依赖任何学习模型。库覆盖三个领域、共用同一套 Subgraph→Node→Edge 语法:小分子(molecode.molecule)、聚合物(molecode.polymer,重复单元显式带 ×n 计数)和 Markush 结构(molecode.markush,含缩写节点与图同构比较器)。它以 pip 包发布(含 molecode.prompts 系统提示词与可选的 OpenAI 兼容 LLMClient),仓库还附带 Claude Code Agent Skill 和 AGENTS.md 入口,让编码智能体通过 molecode_convert.py CLI 完成转换、校验与图编辑。论文报告其在陌生分子上的准确率约 76–80%(SMILES 约 20–42%),Markush 理解从 38.1% 提升至 84.0%,且推理 token 成本约为 SMILES 的五分之一。

MoleCode 在 SMILES/MOL/Polymer-SMILES/Markush 与 Mermaid 图之间做无损双向转换(mol_to_mermaid、mermaid_to_mol、polymer_to_mermaid、mermaid_to_psmiles),并提供确定性 RDKit 回路校验。工作流是:转换分子 → 检查命名原子/键 → 编辑图 → 校验(公式、计数、往返一致性)→ 转回 SMILES。库还提供 MOLECULE_SYSTEM_PROMPT 等系统提示词、可选的 molecode.llm.LLMClient(基于标准库 urllib 的 OpenAI 兼容客户端,用户自备 key 与 base_url,支持 OpenAI、DeepSeek、Azure、vLLM、Ollama 等)。examples/ 目录有 8 个可运行脚本,覆盖往返转换、原子/分子式/环计数、约束下的从头设计、局部图编辑(加/删/取代基)、反应产物预测和分子图像转 MoleCode(OCSR,需视觉模型)。作为 Claude Code / Codex 的 Agent Skill,它通过 .claude/skills/molecode/scripts/molecode_convert.py 的 doctor、smiles-to-molecode、validate、compare、molecode-to-smiles 子命令工作。

  1. 药物化学家想让 Claude Code 或 Codex 直接在命名原子/键层面编辑分子(如加一个甲基),并得到 RDKit 确定性校验
  2. 研究 Markush 专利结构的计算化学团队,需要表达 {R1}、{Boc} 等缩写节点并对预测做图同构评分
  3. 处理长聚合物链(如 Nylon-6)的团队,希望重复单元保持显式 ×n 形式而不是随链长爆炸
  4. 为任意 LLM 构建分子理解/生成/编辑/推理任务的工程师,直接复用 molecode.prompts 与 OpenAI 兼容客户端
  5. 需要 OCSR(分子图像转结构)的研究者,用视觉模型把图片转为 MoleCode 再转回 SMILES

安装与配置要点

摘自下方的安装和使用说明,以项目 README 的最新说明为准。

安装 / 启动命令
  • pip install molecode
  • pip install -e
环境变量
MOLECODE_API_KEY MOLECODE_BASE_URL MOLECODE_MODEL
运行环境
Python 3.9+

如何安装或部署这个 Agent?

从 PyPI 安装库(会带上 rdkit 和 networkx):

pip install molecode

从源码安装(含 examples、Agent Skill 与开发环境):

git clone https://github.com/AtomFlow-AI/MoleCode.git
cd MoleCode
pip install -e .

要求 Python 3.9+。pip 安装得到 molecode.molecule、molecode.polymer、molecode.markush、molecode.prompts、molecode.llm;可运行的 examples 和 Agent Skill 在仓库中。

如何使用这个 Agent?

核心往返转换:

from rdkit import Chem
from molecode import mol_to_mermaid, mermaid_to_mol, mol_to_smiles

# SMILES  ->  MoleCode graph
graph = mol_to_mermaid(Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O"), name="Aspirin")
print(graph)

# MoleCode graph  ->  SMILES  (lossless round-trip)
assert mol_to_smiles(mermaid_to_mol(graph)) == Chem.CanonSmiles("CC(=O)Oc1ccccc1C(=O)O")

调用任意 LLM(自备 key 和 base_url):

from molecode import LLMClient
from molecode.prompts import MOLECULE_SYSTEM_PROMPT
from molecode.molecule import mol_to_mermaid
from rdkit import Chem

client = LLMClient(api_key="sk-...", base_url="https://api.openai.com/v1", model="")
# 或设置 MOLECODE_API_KEY / MOLECODE_BASE_URL / MOLECODE_MODEL 后直接调用 LLMClient()

graph = mol_to_mermaid(Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)O"), name="Aspirin")
reply = client.chat(f"How many carbons are in this molecule?\n
mermaid\n{graph}\n
                    system=MOLECULE_SYSTEM_PROMPT)
print(reply)

作为 Agent Skill 在 Claude Code / Codex 中使用,通过仓库内的 CLI:

python .claude/skills/molecode/scripts/molecode_convert.py doctor
python .claude/skills/molecode/scripts/molecode_convert.py smiles-to-molecode "CCO" --name Ethanol
python .claude/skills/molecode/scripts/molecode_convert.py validate --input edited.mmd
python .claude/skills/molecode/scripts/molecode_convert.py molecode-to-smiles --input edited.mmd

examples/ 中的脚本默认离线运行(只打印精确提示词);设置 MOLECODE_API_KEY 后才会实际调用模型。

这个 Agent 有哪些优点和局限?

优点
  • 拓扑显式化:原子带持久 ID、键为具名边,无需模型先从 SMILES 语法重建图
  • 与 SMILES/MOL 经 RDKit 无损确定性互转,输出可机器校验,不靠学习模型
  • 论文数据:陌生分子上约 76–80% 准确率(SMILES 约 20–42%),推理 token 成本约 5× 更低
  • 一套语法覆盖小分子、聚合物(显式 ×n 重复单元)和 Markush 缩写节点
  • 模型无关:提示词是纯字符串,支持任意 OpenAI 兼容端点(OpenAI、DeepSeek、vLLM、Ollama 等)
局限
  • 输入表示更长,若现有管线深度绑定 SMILES 字符串,迁移需改数据格式
  • 实际调用 LLM 需自备付费 API key(MOLECODE_API_KEY),项目本身不提供模型
  • 领域覆盖不均:聚合物与 Markush 的生成、编辑、推理任务尚未全部支持(README 任务表多处为 —)
  • OCSR(图像转结构)依赖外部视觉模型,非库内置能力

这个 Agent 与同类方案有什么区别?

README 将 MoleCode 与 SMILES 逐项对比:SMILES 中拓扑隐式、原子无身份标识、编辑需整串重写、校验依赖脆弱的字符串解析;MoleCode 则显式命名节点与边、支持局部图操作(加一个甲基 = 1 节点 + 1 边)、可确定性 RDKit 往返校验,并从记忆语法转向对结构的泛化。

与相关度最高的同类 agent 并排比较关键指标。

Agent 源码审查 形态 / 费用 Star 最近更新 主语言 完整支持的平台
MoleCode 当前 66 · 存在缺口 代码库 / SDK免费 + 模型费 ★ 311 5 个月前 Python Codex · Claude Code
Graphicle 84 · 表现良好 命令行工具免费 + 模型费 ★ 620 1 天前 Rust Codex · Claude Code
寓言方法论(Fable Method)——可蒸馏的智能体工作流 79 · 表现良好 Agent 插件 / 技能免费 + 模型费 ★ 2.3k 1 个月前 Python Claude Code
Caura 77 · 表现良好 自托管服务免费版 + 付费版 ★ 576 今天 Python Codex · Claude Code · Claude.ai

FollowAgents 如何评估这个 Agent?

FollowAgents 源码审查 · FARS-2.1
存在缺口
66/ 100 五分制 3.3 / 5
信任安全 17/29
可靠稳定 8/14
适用触发 15/18
规范维护 12/18
有效结果 10/13
证据核验 4/8
查看各维度的扣分理由
信任安全17 / 29 · 2.9/5

最小权限:技能仅做本地文件读写与转换,AGENTS.md 明确'未经询问不安装包'、'结束后清理临时文件',未见破坏性默认行为,得2分;但缺少提交/写入用户文件前的确认机制,user_confirmation 仅1分。数据流透明:转换均通过打包 CLI 本地执行,SKILL.md 明确'不调用外部服务做转换',外部 LLM 调用需用户自备 key 与 base_url,流程清楚。敏感数据:API key 由环境变量/用户传入,无硬编码,但未见对 key 泄漏风险的明示提示,未满分。依赖:rdkit/networkx 为成熟库且版本下限明确,发布走 PyPI OIDC 可信发布且 workflow 权限最小化(contents: read),未见锁定哈希或漏洞说明,2分。回滚:仅靠临时文件自行清理,无版本化回滚保障,1分。来源归属:文档与引用清晰署名 AtomFlow 与论文,2分。

可靠稳定8 / 14 · 2.9/5

自一致性:README/AGENTS.md/SKILL.md/pyproject 对安装、CLI 命令、目录结构的描述相互吻合(示例数量一处写7处写8的小出入),2分。依赖可用性:pip install -e . 拉取 rdkit/networkx,doctor 命令可诊断环境,2分。失败信息:doctor 存在但 packet 中未见错误信息与排错文本的具体内容,仅得1分。

适用触发15 / 18 · 4.2/5

受众与场景:面向化学研究者与 LLM 智能体,覆盖小分子/聚合物/Markush、四类任务族,示例离线可跑,3分。能力边界:SKILL.md 说明何时回退到专业化学信息学代码,但 polymer 的编辑/推理、Markush 的生成标记为不支持并可用,边界大体清晰,2分。触发精度:SKILL.md description 列出明确的触发动词与任务类型,且明确不适用情形(trivial SMILES 编辑),3分。环境适配:Python>=3.9,Claude Code 与 Codex 双入口,但依赖 RDKit 在部分环境的安装难度未讨论,2分。

规范维护12 / 18 · 3.3/5

信息架构:目录分层清晰(库/示例/docs/技能),文档编号成体系,3分。安装说明:PyPI 与源码两种路径、doctor 冒烟检查齐备,3分。命名稳定性:CLI 子命令命名一致,但版本仅 0.1.0 且承诺'上传后版本号不可复用'无 changelog,2分。示例与FAQ:示例丰富,但未见 FAQ 与 troubleshooting 之外的答疑,2分。已知局限:paper 引用了 SMILES 对比数据但仓库文件中未列出 MoleCode 自身局限(如芳香性歧义仅一句带过),1分。许可证:MIT 全文齐备,3分。版本与变更:无 CHANGELOG,仅 tag 触发发布说明,1分。维护责任:无 CONTRIBUTING/维护者联系渠道或更新承诺,仅署名,1分。

有效结果10 / 13 · 3.8/5

输出可用性:validate/compare/doctor 与 round-trip 校验使输出可核验,文件工作流要求保留验证证据,2分。边际价值:把隐式 SMILES 拓扑显式化、局部图编辑替代整串重写,且有论文与 docs/06 支撑其收益主张,3分。成本收益:宣称 token 成本约低5倍属论文结论而非本仓库可静态验证,输入变长本身是代价,2分。

证据核验4 / 8 · 2.5/5

主张可追溯:性能数字均指向 arXiv 论文与 docs/06-why-it-works.md,可追溯,2分。跨源佐证:packet 内无测试代码或独立基准可复核论文数字,2分中仅1分(README 中的数字只有论文链接佐证,本仓库未附评测脚本/数据)。事实与推断分离:经验数字标注为'empirically (see paper)',与设计动机表述区分清楚,2分。

风险与缓解建议
  • 论文中的性能数字(~76–80%、5倍成本降低、38.1%→84.0%)在本仓库 packet 中没有测试代码或基准数据可独立复核,使用前建议自行跑 round-trip 验证。
  • 本产品为未验证发布者(AtomFlow-AI)的早期版本 0.1.0,无 CHANGELOG 与维护承诺,生产采用需自行评估。
  • 使用 LLMClient 时请自行保管 API key(环境变量注入),避免将 key 写入共享的 scratch 文件或提交记录。
  • RDKit 在部分平台安装较重,建议先运行 doctor 命令确认环境可用。
证据充分度:低 评估于 2026年11月22日 审查版本 a4df3b04552b
查看完整评分方法 →
你是这个项目的维护者?把 FARS 徽章加到 README

徽章显示当前的评审分数和结论,点击回到本页。重新评审后约一小时内更新。

FARS

[![FARS 评测](https://followagents.com/badge/molecode.svg?lang=zh)](https://followagents.com/zh/agents/molecode)
<a href="https://followagents.com/zh/agents/molecode"><img src="https://followagents.com/badge/molecode.svg?lang=zh" alt="FARS 评测"></a>

常见问题

它需要联网或付费服务吗?
库本身完全离线可用:转换、校验、examples 默认离线运行。只有实际调用 LLM 时需要你自备 API key(MOLECODE_API_KEY),费用由你选择的供应商决定。
支持哪些模型和端点?
MoleCode 只是表示层,提示词是纯字符串,可接任何 SDK。内置的 molecode.llm.LLMClient 是零依赖的 OpenAI 兼容客户端,支持 OpenAI、DeepSeek、Azure、Together、vLLM、Ollama 等,key 与 base_url 由用户指定。
输出可靠吗,会不会像 LLM 写 SMILES 那样易错?
模型输出的 Mermaid 图可经 molecode_convert.py validate 或 mermaid_to_mol 做 RDKit 确定性校验(公式、原子计数、往返一致性),错误可被程序捕获而非静默接受。
聚合物和 Markush 支持到什么程度?
聚合物支持理解、生成、编辑(molecode.polymer,带 ×n 与 TL/TR 端点标记);Markush 支持理解(molecode.markush,含 {R1} 缩写节点与图同构比较器),生成、编辑和推理尚未支持。
怎么在 Claude Code 或 Codex 里用?
克隆仓库即可:Claude Code 自动发现 .claude/skills/molecode/ 下的 Skill;Codex 及其他智能体读根目录 AGENTS.md 并使用捆绑 CLI,无需 MCP 服务器或额外配置。
MoleCode 官网是什么?
MoleCode 的 GitHub 仓库填写的官网是 https://arxiv.org/pdf/2605.16480。这个链接由仓库作者设置;源码在 GitHub(AtomFlow-AI/MoleCode)。
MoleCode 开源吗?
开源。源码在 GitHub(AtomFlow-AI/MoleCode),许可证是 MIT。
MoleCode 安全吗?
FollowAgents 的 FARS 评审(2026年11月22日)给 MoleCode 的“信任与安全”打了 17/29 分。评审检查的 8 项安全措施没有完全缺失的。
MoleCode 还在维护吗?
更新变慢了:GitHub 上最近一次提交是 2026-06-04,在最近半年内,但不在最近 30 天内。
MoleCode 是谁开发的?
MoleCode 由 GitHub 账号 AtomFlow-AI 发布。FollowAgents 没有核实这个账号背后是哪个人或公司。
这页内容对你有帮助吗?
在 GitHub 查看 ↗ 安装 ↓

对比同类 Agent

用同一套 FARS 评审,横向比较这个 Agent 所属的短名单。

相关核心概念