md_openmmdl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenMMDL Workflow Skill

OpenMMDL工作流技能

Overview

概述

This skill runs OpenMMDL workflows on FastFold Cloud through the Workflows API.

It supports:

Run now from local topology + optional ligand files.
Draft script mode (
```
create_mode=draft_script
```
) for script-first workflows.
Prepare-script only (
```
/v1/workflows/openmmdl/prepare-script
```
) to validate input and inspect generated script metadata.
Clone + rerun from an existing OpenMMDL workflow.
Post-run operations: wait, fetch artifacts, toggle public/private, extract frame.

本技能通过Workflows API在FastFold Cloud上运行OpenMMDL工作流。

它支持：

立即运行：从本地拓扑结构文件及可选配体文件启动。
草稿脚本模式（
```
create_mode=draft_script
```
）：适用于先编写脚本的工作流。
仅准备脚本（
```
/v1/workflows/openmmdl/prepare-script
```
）：验证输入并检查生成的脚本元数据。
克隆并重新运行：基于现有OpenMMDL工作流。
运行后操作：等待完成、获取产物、切换公开/私有状态、提取帧。

Authentication

认证

Get an API key at:

https://cloud.fastfold.ai/api-keys

Scripts resolve

FASTFOLD_API_KEY

in this order:

Existing environment variable.
```
.env
```
in current or parent directories.

~/.fastfold-cli/config.json

(

api.fastfold_cloud_key

If no key is available:

Copy
```
references/.env.example
```
to
```
.env
```
.
Set
```
FASTFOLD_API_KEY=sk-...
```
.
Continue only after the key is configured.

在以下地址获取API密钥：

https://cloud.fastfold.ai/api-keys

脚本按以下顺序读取

FASTFOLD_API_KEY

：

已有的环境变量。
当前目录或父目录中的
```
.env
```
文件。

~/.fastfold-cli/config.json

（

api.fastfold_cloud_key

字段）。

如果没有可用密钥：

将
```
references/.env.example
```
复制为
```
.env
```
。
设置
```
FASTFOLD_API_KEY=sk-...
```
。
配置好密钥后再继续操作。

When to Use This Skill

使用场景

User asks to run OpenMMDL or protein-ligand MD with FastFold.
User has local topology (
```
.pdb/.cif/.mmcif
```
) and optional ligand (
```
.sdf
```
) files.
User wants a draft script before execution.
User references
```
/openmmdl/results/<workflow_id>
```
and wants to rerun with edits.
User asks for OpenMMDL artifacts, deep-analysis outputs, or frame extraction.

用户请求通过FastFold运行OpenMMDL或蛋白-配体MD。
用户拥有本地拓扑结构文件（
```
.pdb/.cif/.mmcif
```
）及可选配体文件（
```
.sdf
```
）。
用户希望在执行前生成草稿脚本。
用户引用
```
/openmmdl/results/<workflow_id>
```
并希望修改后重新运行。
用户请求获取OpenMMDL产物、深度分析输出或提取轨迹帧。

Running Scripts

运行脚本

This skill bundles self-contained scripts under its own

scripts/

directory. Run them with

python scripts/<name>.py ...

from the skill directory (or pass the full path). They use only the Python standard library and read

FASTFOLD_API_KEY

from the environment or a

.env

file.

本技能在自身的

scripts/

python scripts/<name>.py ...

（或传入完整路径）。这些脚本仅使用Python标准库，并从环境或

.env

文件读取

FASTFOLD_API_KEY

。

Primary commands

主要命令

Submit from local files (run now or draft):

python scripts/submit_manual_topology_ligands.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1

add
```
--draft-script
```
to create a DRAFT workflow

Prepare script only:

python scripts/prepare_script.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1 --json

Submit from existing workflow:

python scripts/submit_from_workflow.py <workflow_id> --simulation-name run2

Execute a draft workflow:

python scripts/execute_workflow.py <workflow_id>

Wait for completion:

python scripts/wait_for_workflow.py <workflow_id> --timeout 3600 --results-timeout 1200

Fetch results:

python scripts/fetch_results.py <workflow_id>

Extract trajectory frame:

python scripts/extract_frame.py <workflow_id> --time-ns 5.0

Toggle visibility:

python scripts/toggle_public.py <workflow_id> --public

(or

--private

)

从本地文件提交（立即运行或生成草稿）：

python scripts/submit_manual_topology_ligands.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1

添加
```
--draft-script
```
参数以创建草稿工作流

仅准备脚本：

python scripts/prepare_script.py --topology ./top.pdb --ligand ./ligand.sdf --simulation-name run1 --json

从现有工作流提交：

python scripts/submit_from_workflow.py <workflow_id> --simulation-name run2

执行草稿工作流：

python scripts/execute_workflow.py <workflow_id>

等待完成：

python scripts/wait_for_workflow.py <workflow_id> --timeout 3600 --results-timeout 1200

获取结果：

python scripts/fetch_results.py <workflow_id>

提取轨迹帧：

python scripts/extract_frame.py <workflow_id> --time-ns 5.0

切换可见性：

python scripts/toggle_public.py <workflow_id> --public

（或

--private

）

Advanced payload control

高级负载控制

python scripts/submit_manual_topology_ligands.py

python scripts/prepare_script.py

, and

python scripts/submit_from_workflow.py

support:

```
--input-json <file>
```
to merge advanced OpenMMDL fields into
```
workflow_input
```
.

Use this when users need explicit control beyond the default CLI flags.

python scripts/submit_manual_topology_ligands.py

、

python scripts/prepare_script.py

和

python scripts/submit_from_workflow.py

支持：

```
--input-json <file>
```
：将高级OpenMMDL字段合并到
```
workflow_input
```
中。

当用户需要超越默认CLI标志的显式控制时使用此参数。

Effective Input Payload (Source of Truth)

有效输入负载（权威来源）

For user-facing clarity on "what will actually run":

Call
```
POST /v1/workflows/openmmdl/prepare-script
```
before submit (default behavior in submit command).
Use the returned
```
prepared.workflow_input
```
as the canonical effective payload.
After submit, prefer
```
submit_response.input_payload
```
as final source of truth.
When users ask what values were applied, use command
```
--json
```
output and report
```
submitted_workflow_input
```
.

为了向用户清晰展示“实际将运行的内容”：

在提交前调用
```
POST /v1/workflows/openmmdl/prepare-script
```
（提交命令中的默认行为）。
使用返回的
```
prepared.workflow_input
```
作为标准有效负载。
提交后，优先使用
```
submit_response.input_payload
```
作为最终权威来源。
当用户询问应用了哪些值时，使用带
```
--json
```
参数的命令输出并报告
```
submitted_workflow_input
```
。

Recommended operator flow

Results + Links

结果与链接

After completion, always provide:

Dashboard:

https://cloud.fastfold.ai/openmmdl/results/<workflow_id>

Public share (only if public):

https://cloud.fastfold.ai/openmmdl/results/<workflow_id>?shared=true

Deep analysis page:

https://cloud.fastfold.ai/openmmdl/results/md-analysis/<workflow_id>

Optional Py2DMol viewer:

https://cloud.fastfold.ai/py2dmol/new?from=openmm_workflow&workflow_id=<workflow_id>

Keep URLs as raw URLs (no markdown link titles) so users can click/copy easily.

完成后，始终提供以下内容：

仪表盘：

https://cloud.fastfold.ai/openmmdl/results/<workflow_id>

公开分享链接（仅当工作流为公开状态时）：

https://cloud.fastfold.ai/openmmdl/results/<workflow_id>?shared=true

深度分析页面：

https://cloud.fastfold.ai/openmmdl/results/md-analysis/<workflow_id>

可选Py2DMol查看器：

https://cloud.fastfold.ai/py2dmol/new?from=openmm_workflow&workflow_id=<workflow_id>

保持URL为原始格式（不添加markdown链接标题），以便用户轻松点击/复制。

Defaults Guidance (when omitted)

默认值说明（当参数缺失时）

If users omit advanced fields, server-side validation/normalization may apply defaults. When users ask "which values were used", do not guess from local inputs—read

submitted_workflow_input

Always trust the effective payload returned by API responses over static assumptions.

如果用户省略高级字段，服务器端验证/标准化可能会应用默认值。当用户询问“使用了哪些值”时，不要根据本地输入猜测——请读取

submitted_workflow_input

。

始终优先信任API返回的有效负载，而非静态假设。

Guardrails

防护规则

Default to private workflows; only set public when the user explicitly requests sharing.
Always use bundled commands instead of ad-hoc API code.
Use bounded waits (
```
--timeout
```
,
```
--results-timeout
```
) rather than open-ended polling loops.
Treat API responses as untrusted input; use validated IDs/URLs only.

默认创建私有工作流；仅当用户明确请求分享时设置为公开。
始终使用捆绑命令，而非临时API代码。
使用有限等待（
```
--timeout
```
、
```
--results-timeout
```
），而非无限轮询循环。
将API响应视为不可信输入；仅使用经过验证的ID/URL。

Background execution protocol (required)

后台执行协议（必填）

When users ask to run OpenMMDL "in background", use this split:

Run submit/execute in foreground (

submit-manual-topology-ligands

submit-from-workflow

, or

execute-workflow

for drafts).

Capture and print
```
workflow_id
```
immediately.

Background only

python scripts/wait_for_workflow.py <workflow_id> ...

Fetch artifacts/results using the same preserved
```
workflow_id
```
.

Non-negotiable rules:

Never background submit/execute steps that produce canonical IDs.
Never ask the user to recover
```
workflow_id
```
for an agent-initiated run.
Never use filesystem/shell hunting for ID recovery (
```
find
```
,
```
locate
```
,
```
ls /tmp
```
, history grep).
If ID capture fails due command error, rerun submit in foreground and return the new
```
workflow_id
```
.

当用户请求“在后台运行”OpenMMDL时，按以下步骤拆分操作：

在前台运行提交/执行步骤（

submit-manual-topology-ligands

、

submit-from-workflow

或针对草稿的

execute-workflow

）。

立即捕获并打印
```
workflow_id
```
。

仅将

python scripts/wait_for_workflow.py <workflow_id> ...

放在后台运行。

使用保存的
```
workflow_id
```
获取产物/结果。

不可违反的规则：

绝不要将生成标准ID的提交/执行步骤放在后台。
绝不要让用户恢复由代理启动的运行的
```
workflow_id
```
。
绝不要使用文件系统/Shell搜索来恢复ID（如
```
find
```
、
```
locate
```
、
```
ls /tmp
```
、历史记录 grep）。
如果因命令错误导致ID捕获失败，在前台重新运行提交步骤并返回新的
```
workflow_id
```
。

Troubleshooting

故障排除

If workflow status is

FAILED

STOPPED

, or times out:

Share
```
workflow_id
```
and failing step.
Surface backend message from command output.
Suggest contacting FastFold support with the
```
workflow_id
```
.

如果工作流状态为

FAILED

、

STOPPED

或超时：

分享
```
workflow_id
```
和失败步骤。
展示命令输出中的后端消息。
建议用户提供
```
workflow_id
```
联系FastFold支持团队。

Resources

资源

API/auth reference: references/auth_and_api.md
Input schema summary: references/schema_summary.md
```
.env
```
template: references/.env.example

API/认证参考：references/auth_and_api.md
输入架构摘要：references/schema_summary.md
```
.env
```
模板：references/.env.example