# 用 Python 写 Stuntman 实验设计

- 网址:https://unchainedlabs.help/product/stuntman/resources/python-authoring

**用 Python 写 Stuntman 实验设计 从对象模型到可运行的 .stunt 文件**

Stuntman 的实验设计存成 .stunt 文件，格式是 HDF5。这个文件可以在 PLAN 里拖拽生成，也可以用一段 Python 脚本生成。脚本调用 Stuntman 自带的 .NET 类库，逐项写出化学品、样品库、源和分液步骤，最后写成 .stunt。

内容依据原厂 Stuntman Python Authoring Guide（2026 年 4 月版）。代码里的类名、属性名和示例值照原文保留，注释改成中文。

## 建 .stunt 文件有三条路径，按改动大小和自动化程度选

- **PLAN**：图形界面里新建或修改设计，在 PLAN 里校验，再导出 .stunt。适合看着台面布局设计，或对已有设计做小改动。
- **CONVERT**：把已有设计导出成 Python 脚本，改脚本（可以借助 Stuntman AI），再运行脚本生成 .stunt。适合批量生成设计、用版本管理跟踪改动，以及较复杂的流程。
- **从零写 Python**：载入类库，新建设计，加化学品、样品库和 map，写入 .stunt，再用 PLAN 或 CONVERT 校验。适合自定义流程，所有内容都由代码控制。

三条路径最后都要经过同一个校验步骤。校验依据的是 SystemConfiguration.xml，也就是这台仪器的硬件配置。

手里已有一份接近的设计时，先导出 .py，在脚本上改，不必从空白开始。没有现成设计、流程要完全由代码决定时，从零写 Python。

> | 操作 | PLAN | CONVERT | AI |
> | --- | --- | --- | --- |
> | 图形界面编辑设计 | ✓ |  |  |
> | 打开、浏览 .stunt 文件 | ✓ | ✓ |  |
> | 从 .stunt 导出 .py | ✓ | ✓ |  |
> | 运行 .py 生成 .stunt |  | ✓ | ✓ |
> | 按 SystemConfig.xml 校验 .stunt | ✓ | ✓ | ✓ |
> | 指定 Python DLL 路径 |  | ✓ | ✓（-p） |
> | 指定输出 .stunt 路径 |  | ✓ | ✓（-o） |

表格依据原厂指南第 8 页。PLAN 和 AI 的界面介绍见 Stuntman 软件概览。

## 一份设计由六类对象组成，彼此用 Key 关联

所有数据类都在 UL.StuntmanHdf 命名空间里，Python 通过 pythonnet 提供的 clr 模块调用。

> | 类 | 代表什么 | 每份脚本用几次 |
> | --- | --- | --- |
> | StuntmanDesign | 一份实验设计的根容器，存元数据和下面四个集合 | 每份脚本一个 |
> | StuntmanChemical | 一种试剂：名称、SMILES、分子量、浓度、单位 | 设计里用到的每种试剂一个 |
> | StuntmanLibrary | 一块板或一组样品瓶：行列数、台面位置、初始状态 | 每块板一个；至少一个源、一个目标 |
> | StuntmanSource | 把一种化学品对应到台面上的具体位置和体积 | 每种放在台面上的化学品一个 |
> | StuntmanMap | 一个步骤：分液、转移或仪器参数 | 每个不同的分液步骤一个 |
> | StuntmanFile | HDF 容器，可装一份或多份设计 | 每次保存一个 |

化学品和样品库的 Key 是自动生成的 GUID。StuntmanSource.ChemicalKey 指向化学品的 Key。StuntmanMap.SourceKey 指向化学品或源样品库的 Key，DestinationKey 永远指向一个样品库的 Key。

StuntmanDesign 上几个常用属性：

- **DesignID**：用 Guid.NewGuid().ToString() 生成。
- **DesignName**、**Description**、**CreatedBy**、**CreatedOn**：名称、说明、作者、创建时间。
- **SystemName**：这份设计要在哪台自动化系统上运行。
- **IsReadOnly**：设为 True 后，这份设计在 PLAN 里不能再编辑。
- **Chemicals**、**Libraries**、**Sources**、**Maps**：四个列表，都用 .Add() 往里加。

## 先装好 64 位 Python 和 pythonnet，再载入两个 DLL

> | 组件 | 要求 | 说明 |
> | --- | --- | --- |
> | Python | 3.8–3.11，64 位 | 位数要和 Stuntman 安装一致 |
> | pythonnet | 3.0 及以上 | 提供 clr 模块，用来调用 .NET |
> | UL.StuntmanHdf.dll | 随 CONVERT 安装 | 默认在 C:\Program Files\Unchained Labs\Stuntman |
> | UL.Core.dll | 随 CONVERT 安装 | ASUnit 等共用类型在这里 |
> | .NET Framework | 4.8 | Windows 10 / 11 自带 |

脚本开头做三件事：把 DLL 所在目录加进搜索路径，载入 UL.Core 和 UL.StuntmanHdf，再导入要用的类和枚举。按名称载入失败时，改用完整文件路径载入。

```
import clr
import os
import sys

**把 Stuntman 的 DLL 目录加进搜索路径**
dll_path = r"C:\Program Files\Unchained Labs\Stuntman"
if os.path.exists(dll_path):
    sys.path.append(dll_path)
    # 原生 DLL 的依赖也要能找到,所以同时加进 PATH
    os.environ['PATH'] = dll_path + os.pathsep + os.environ.get('PATH', '')

**载入 .NET 程序集**
try:
    # 先载入核心依赖
    clr.AddReference("UL.Core")
    clr.AddReference("UL.StuntmanHdf")
except Exception as e:
    # 按名称载入失败时,按文件路径载入
    clr.AddReferenceToFileAndPath(os.path.join(dll_path, "UL.Core.dll"))
    clr.AddReferenceToFileAndPath(os.path.join(dll_path, "UL.StuntmanHdf.dll"))

import System
from System import String, Double, Int32, Boolean, Array, DateTime, Guid
from System.Collections.Generic import List
from UL.StuntmanHdf import (InitState, MapType, StuntmanChemical, StuntmanDesign,
    StuntmanFile, StuntmanLibrary, StuntmanMap, StuntmanPrompt, StuntmanSource, Writer)
from UL.Core.Enumerations import ASUnit
```

## 按七步搭设计：先化学品，再样品库和源

- **载入程序集**：上一节的代码。
- **新建设计**：建 StuntmanDesign，填元数据。
- **加化学品**：列出实验要用的试剂，比如缓冲液、辅料和蛋白原液。
- **加样品库**：定义板或样品瓶架，以及它们在台面上的位置。
- **加源**：说明每种试剂放在哪个架子的哪个孔。
- **加 map**：写出每一步分液或处理。
- **保存**：写成 .stunt 文件。

### 新建设计

```
design = StuntmanDesign()
design.DesignID = Guid.NewGuid().ToString()
design.DesignName = "My Experiment"
**接下来往 design 里加化学品、样品库、源和 map**
```

### 化学品：加进设计后 Key 才有效

名称在构造时传入，之后只读。分子量 MolWt 的单位是 g/mol，密度 Density 是 g/mL，Concentration 是储备液浓度，单位由 Unit 指定。Category 是功能类别，原文举例 "Solvent"、"Compound"。

```
chem = StuntmanChemical("Reagent-Name")   # 名称构造后只读
chem.MolWt = 100.0                         # 分子量,g/mol
chem.Density = 1.0                         # 密度,g/mL
chem.Barcode = "000000000001"
chem.Category = "Reagent"
chem.Concentration = 1.0                   # 储备液浓度
chem.Unit = ASUnit.unMOLAR                 # 浓度单位

chem.Reagents = []
chem.Conc = []
chem.ConcUnit = []

design.Chemicals.Add(chem)   # Add 之后 chem.Key 才有效
```

### 样品库：名称和行列数在构造时定死

StuntmanLibrary 构造时传入名称、行数、列数，三者之后都只读。下面的例子是 4 行 6 列，对应 4 × 6 的样品瓶架。SubstrateType 是硬件类型，原文举例 "Rack 8x12 1mL"；SubstratePosition 是台面位置，原文举例 "Deck 1-2"。

InitialState 取 InitState.Empty、Full 或 Partial。SelectedWells 由 design.UpdateSelectedWells() 计算，属性表注明不要手动设置。

```
lib = StuntmanLibrary("LIB001", 4, 6)   # 名称、行数、列数
**按孔填写 WellBarcodes[i]、WellNames[i]、体积等**
lib.SubstrateType = "RackType"           # 架子 / 板的硬件类型
lib.SubstratePosition = "<Deck>"         # 台面位置

design.Libraries.Add(lib)
```

### 源：行列号从 0 开始数

StuntmanSource 把一种化学品放到台面上的某个孔里。Row 和 Column 从 0 开始，下面例子里的 Row = 1、Column = 1 是第 2 行第 2 列。Amount 是可用的体积或质量，单位由 Unit 指定。试剂不放在台面上时，IsOffDeck 为 True。

```
src = StuntmanSource()
src.ChemicalKey = chem.Key           # 指向已加入设计的化学品
src.SubstrateType = "SourceRack"
src.SubstratePosition = "Deck"

src.Row = 1        # 从 0 数,即第 2 行
src.Column = 1     # 从 0 数,即第 2 列

design.Sources.Add(src)
```

## map 分三种：源到库、库到库、参数

> | MapType | 用途 | SourceKey 指向 |
> | --- | --- | --- |
> | MapType.Source | 把一种化学品分到一个样品库 | 化学品的 Key |
> | MapType.Array | 把一个样品库按孔转移到另一个样品库 | 源样品库的 Key |
> | MapType.Parameter | 给样品库加一个处理步骤，比如延时 | 属性表写为化学品的 Key；原文参数示例只设了 DestinationKey |

ValuesFloat 是每个孔的数值，长度等于目标样品库的行数乘列数。字符串参数用 ValuesString，它和 ValuesFloat 只能二选一。Rows、Columns 是目标孔的行列号，SourceRows、SourceColumns 是源孔的行列号。属性表注明这四项只用于 Array map，但原文另两种 map 的示例也设了 Rows、Columns。

GroupNumber 是执行分组，同一组的 map 可以同时执行。DispenseCategory 是分液类别标签；Tags 是给系统执行用的标记，取值和仪器配置有关。

单位用 ASUnit 枚举。原厂指南不同页的写法不一致，有 ASUnit.unMICROLITER，也有 ASUnit.uMICROLITER。写脚本时以本机 UL.Core 里的实际枚举名为准。

### 源到库：从试剂瓶往目标板每孔加 50 µL

```
m_src = StuntmanMap()
m_src.MapType = MapType.Source
m_src.MapName = "Liquid Dispense"
m_src.MapObject = src
m_src.ValuesFloat = [50.0] * n          # n = 目标库行数 × 列数,每孔 50
m_src.Unit = ASUnit.unMICROLITER
m_src.Rows = list(rows_list)            # 目标孔行号
m_src.Columns = list(cols_list)         # 目标孔列号
m_src.Tags = ["PDT", "10uLTip", "SourceTracking"]
m_src.DispenseCategory = "Non-Viscous Liquid"
m_src.GroupNumber = 1
m_src.Description = "Source map: bottle to LIB-DST"
m_src.SourceKey = chem.Key              # 源:化学品
m_src.DestinationKey = lib_dst.Key      # 目标:样品库

design.Maps.Add(m_src)   # 把这一步加进设计
```

### 库到库：按孔把源板转到目标板，每孔 5 µL

```
m_arr = StuntmanMap()
m_arr.MapType = MapType.Array
m_arr.MapName = "Liquid Dispense"
m_arr.MapObject = lib_src
m_arr.ValuesFloat = [5.0] * n
m_arr.Unit = ASUnit.uMICROLITER
m_arr.Rows = list(rows_list)            # 目标孔
m_arr.Columns = list(cols_list)
m_arr.SourceRows = list(rows_list)      # 源孔
m_arr.SourceColumns = list(cols_list)
m_arr.Tags = ["PDT", "10uLTip", "SourceTracking"]
m_arr.DispenseCategory = "Non-Viscous Liquid"
m_arr.GroupNumber = 2
m_arr.Description = "Array map: LIB-SRC to LIB-DST"
m_arr.SourceKey = lib_src.key           # 源:样品库
m_arr.DestinationKey = lib_dst.key

design.Maps.Add(m_arr)
```

### 参数：给目标板每孔加 1 分钟延时

```
m_p1 = StuntmanMap()
m_p1.MapType = MapType.Parameter
m_p1.MapName = "Delay"
m_p1.MapObject = "Delay"
m_p1.ValuesFloat = [1.0] * n
m_p1.Unit = ASUnit.uMINUTE
m_p1.Rows = list(rows_list)
m_p1.Columns = list(cols_list)
m_p1.Tags = ["Processing"]
m_p1.GroupNumber = G_PROC               # 处理步骤所在的执行组
m_p1.DestinationKey = lib_dst.Key
m_p1.Description = "Parameter: delay"

design.Maps.Add(m_p1)
```

三段代码照原厂指南第 17–18 页。原文第 18 页 Key 的大小写有 .Key 和 .key 两种，这里照原文保留。

## 保存前先调用两个方法，再写入 StuntmanFile

- **design.SetMapObjects()**：解析各个 map 的 MapObject 交叉引用。
- **design.UpdateSelectedWells()**：为每个样品库算出 SelectedWells。

然后把设计放进 StuntmanFile，交给 Writer.WriteStuntmanHdf() 写盘。一个 StuntmanFile 可以装多份设计。

```
**保存前必须调用**
design.SetMapObjects()          # 解析 MapObject 交叉引用
design.UpdateSelectedWells()    # 计算每个样品库的 SelectedWells

**把设计放进 StuntmanFile**
file_container = StuntmanFile()
file_container.Designs.Add(design)

**调用 WriteStuntmanHdf 写出 .stunt 文件**
output_path = r"C:\Stuntman\MyExperiment.stunt"
Writer.WriteStuntmanHdf(output_path, file_container)
print("[SUCCESS] File generation complete!")
```

写出的 .stunt 是 HDF5 文件，里面是一份完整的实验设计。要回看内容，用 PLAN 或 CONVERT 打开浏览；要改，从 .stunt 导出 .py，改完再生成新的 .stunt。

## 用 Stuntman.Convert.exe 运行脚本和校验设计

CONVERT 的命令行程序做两件事：运行 .py 生成 .stunt，以及按硬件配置校验已有的 .stunt。校验确认设计正确、能在这台仪器上执行。退出码 0 表示成功，1 表示出错，包括脚本异常、校验失败和找不到文件。

> | 参数 | 取值 | 作用 |
> | --- | --- | --- |
> | 第一个位置参数 | script.py | 要运行的 Python 脚本 |
> | 第二个位置参数 | output.stunt | 输出文件路径，可省略 |
> | -o, --output | 路径 | 输出 .stunt 文件路径 |
> | -p, --python-dll | 路径 | Python DLL 路径，如 python38.dll |
> | -i, --input | 路径 | 要校验的 .stunt 文件 |
> | -c, --system-config | 路径 | SystemConfiguration.xml 路径 |
> | -h, --help, /? |  | 显示用法 |

```
**自动生成输出文件名**
Stuntman.Convert.exe my_design.py

**指定输出文件**
Stuntman.Convert.exe my_design.py my_output.stunt
Stuntman.Convert.exe my_design.py -o my_output.stunt

**指定 Python DLL**
Stuntman.Convert.exe my_design.py -p "C:\Python38\python38.dll"

**按硬件配置校验 .stunt**
Stuntman.Convert.exe -i my_design.stunt -c SystemConfiguration.xml

**显示帮助**
Stuntman.Convert.exe --help
```

批处理或外部调度脚本可以按退出码判断生成和校验是否成功。由脚本逐轮生成设计、转成 .stunt 的例子见 闭环优化应用笔记。

- convert · CONVERT 与校验
