# 用 PLAN 一步步建实验设计

- 网址:https://unchainedlabs.help/product/stuntman/resources/plan-guide

**用 PLAN 一步步建实验设计 从选系统到检查通过，每一步填什么、会被什么拦住**

PLAN 用五步向导建实验设计。每一步点 Next 时都会先检查，不通过就不能进入下一步。走到 Finish 的设计，就是这台 Stuntman 能运行的设计。

文中的截图大多来自原厂指南里的同一个例子：一份注射剂稳定性筛选设计。先在 4 × 6 母板上配 8 个处方，再分到振荡、热和冻融三块子板上加应力。五个程序各做什么，见 Stuntman 软件概览。内容依据原厂 Stuntman PLAN User Guide（Rev A）。

## 一个 .stunt 项目文件可以存多个设计

PLAN 启动后是 Dashboard，只有两个按钮。Create New Design 新建设计，Open Existing Design 打开已有设计。

新建设计时不会马上让你起名。第一次点 Save 时，才弹出 Design Management 窗口，选文件位置、填设计名。默认文件名是「Active Design」加日期时间，可以改成有意义的名字。

### Design Management 窗口

打开和保存用的是同一个窗口，分四块。顶部是文件路径，左边是最近用过的文件，最多 30 个。中间是文件里的设计列表，右边是所选设计的详情。

- 同一块样品库要在几个设计里用，建议把这些设计存进同一个 .stunt 文件。后面第 2 步可以直接从下拉列表选这块库。
- 无关的设计分开存。一个 .stunt 文件上限 10 GB，RUN 的结果数据也写在里面。
- 双击设计名可以重命名，最长 256 个字符。重命名时按 Esc 等于点 Cancel，整个窗口关闭，未保存的改动全部丢掉。
- 同一文件里设计名不能重复，不分大小写。Design1 和 design1 算同名。
- Description 和 Created By 建议随手填好，以后在文件里找设计靠这两栏。

*图:Design Management 窗口。中间选中的是注射剂稳定性筛选设计，右边是它的描述，以及已经写好的加单抗、组氨酸缓冲液、辅料等步骤。System Name 一栏已涂去。图取自原厂用户指南。*

### 复制和删除

- **Duplicate**：复制选中的整个设计。Current File 复制到同一个文件，Another File 复制到另一个 .stunt 文件。副本自动改名为「原名_年月日_时分秒」。
- 复制到另一个文件时，如果那个文件里已有同名样品库，行列数必须一致，否则报「Library Conflict in Target File」。
- **Delete**：删除前会让你确认。只读设计不能删，选中时 Delete 按钮是灰的。
- 窗口里的 Cancel 只放弃改名和描述这类改动，撤销不了已经做的复制和删除。

### 运行过的设计变成只读

RUN 往设计里写入第一条结果数据时，这份设计就永久锁定，列表里显示挂锁图标。只读设计能看，不能改名、编辑或删除，也没有办法解锁。要改就先 Duplicate，改副本。

如果你正在 PLAN 里编辑的设计被 RUN 运行了，界面不会变灰，照样能输入。点 Save 或 Next 时，PLAN 才发现它已锁定，丢掉刚才的输入，弹出 Design Locked 对话框。可能被运行的设计，先复制一份再继续改。

### 多人共用项目文件

打开 .stunt 文件时，PLAN 在同一文件夹里建一个 .lock 文件，防止另一个 PLAN 同时编辑。回到 Dashboard 或关闭 PLAN 时自动释放。

- 文件放在共享网络盘上，用映射的盘符访问，不要直接输入 UNC 路径。
- 每个要编辑的人都要有这个文件夹的写权限。只有读权限的人建不了 .lock 文件，PLAN 也不报错，两个人可能同时改同一个文件。
- 不要放在 OneDrive、SharePoint、Dropbox、Google Drive 这类云同步文件夹里。.lock 文件不一定及时同步，两个人可能各改一份副本。
- .lock 文件锁和挂锁图标是两回事。挂锁表示设计已运行过、不能再改；.lock 表示有人正开着这个文件。

PLAN 没有自动保存，也没有崩溃恢复。从第 2 步起每一步都有 Save 按钮，Save 不做完整检查，未完成的设计也能存下来，下次接着做。

## 第 1 步 Select System：选定这台 Stuntman 的硬件配置

选的系统决定了后面能用哪些分液、处理和检测工具，以及台面上有哪些位置。

- 在 Current System 下拉列表里选系统。没选之前，页面提示「Please select a system configuration to proceed」，Next 是灰的。
- 选好后，左边出现 Dispense Tools、Process Tools、Analysis Tools 三类工具卡片，系统里没有的类别不显示。右边是台面布局图。
- 核对工具和台面无误，点 Next。

在连着 Stuntman 的电脑上，或者配置文件夹里只有一个系统时，系统会自动选好，直接点 Next。列表里缺系统，要往 C:\Stuntman\Plan\Configurations 里加配置文件夹，做法见 电脑要求与软件安装。

*图:第 1 步选定系统后的界面。左边是这台系统的工具，分液用 PDT。处理工具有 Time Controls、VPG、Capping Station、Vortexer 等。右边是台面布局。图取自原厂用户指南。*

已保存的设计如果换系统，PLAN 会从项目文件里删除这份设计，化学品、样品库和流程全部清空。换之前会弹出警告，点 Cancel 可以退回。拿不准以后会不会换系统，先 Duplicate 一份再换。

## 第 2 步 Add Chemicals & Libraries：登记试剂，定义板子

这一步有两张表。上面登记化学品，下面定义样品库。样品库就是一块板或一个样品瓶架，用行数 × 列数定义，每个设计至少要有一个。

注射剂稳定性的例子里有六种化学品。单抗原液 50 mg/mL，组氨酸缓冲液 pH 6.0，蔗糖 40% w/v。另外三种是 1% w/v 聚山梨酯 80、150 mM 氯化钠和注射用水。样品库是 4 × 6 的母板、三块 4 × 6 的应力子板，以及一块 8 × 12 的 Lunatic 读板。

### 化学品

- 表头有名称、类别、分子量、密度、浓度、浓度单位、SMILES 和条码。只有 Name 必填。
- Category 决定第 3 步里化学品按什么分组，例如 Buffer、Excipient、Protein、Solvent、Surfactant。
- 分子量、密度和浓度只能填数字、小数点或科学计数法，填了就必须大于 0。
- Conc Unit 从下拉列表选，有 mol/L、mmol/L、mg/mL、Mass %、Volume %、mol % 等。
- 化学品名和条码在设计内不能重复，不分大小写。

常用试剂不必每次手敲。Import 从 .tsv 文件批量导入，表头必须和 PLAN 的列一致。Add To Favorites 把选中的行存进个人常用清单，下次用 Add From Favorites 调出来。名称、分子量和密度都相同的行会跳过。

### 样品库

- 表头是 Name、Rows、Columns、Description、Barcode。
- 行列数要对应这台系统上配置过的板或样品瓶架。尺寸放不进任何台面位置时，报「No accommodating substrate found」。
- Name 下拉列表列出同一 .stunt 文件里其他设计用过的库，显示为「库名 (设计名)」。选一个，行列数、描述和条码自动填好，上一个设计跑完后的剩余体积带过来作为起始体积。
- 库一旦被流程步骤用到，行列数就不能再改，也不能删。要改，先删掉用到它的步骤。
- Duplicate 复制选中的库，名字后加「 - Copy」。同一块库复制两次会得到两个同名的库，保存前要改掉一个。

库在另一个 .stunt 文件里时，点 Libraries 下面的 Import。浏览到那个文件，选设计，勾选要的库加入导入清单，再点 Import。当前文件里已有同名的库，整次导入会被拒绝。

*图:从另一个 .stunt 文件导入样品库。选中注射剂稳定性设计后，右上列出它的四块库。母板和冻融板都是 4 × 6，已加入导入清单。系统名已涂去。图取自原厂用户指南。*

### Save 和 Next 检查的内容不同

选整行要点最左边的行号。只点单元格不算选中行，Delete Rows、Add To Favorites、Duplicate 这些按钮会一直是灰的。PLAN 里所有表格都是这样。

- **Save**：只查两件事。有数据的行必须有名字，化学品和库的名字不能重复。
- **Next**：做全部检查，所有问题一起列出来。包括必填项、名称和条码不重复、数值大于 0、库的尺寸与系统配置相符。
- 一个设计最多 1024 种化学品、1024 个样品库。

*图:第 2 步的两张表。下面两块 8 × 12 库是复制出来的，条码都是 1，底部状态栏报条码重复，改好才能继续。图取自原厂用户指南。*

## 第 3 步 Create a Recipe：按顺序加分液、处理和检测步骤

这是 PLAN 里内容最多的一屏。上半部分编辑当前这一步，下半部分是 Recipe 列表，存放已经加好的所有步骤。左上角选步骤类型：Dispense Step、Process Step 或 Analytics Step。

这一屏的选项、参数和操作名都有鼠标悬停说明。不确定某个选项做什么，先把鼠标停在上面看。

### 分液步骤的选项

右边的 Options 面板从上到下这样填：

- **Dispense Operation**：Liquid Dispense（液体）或 Powder Dispense（粉末），只列出系统支持的。
- **Dispense Tool**：第 1 步系统里的分液工具，例如 6Tip 或 PDT。工具有多种吸头规格时，会多出一个 Tip Type。
- **Dispense Category**：选好工具后出现，进一步细分操作，例如 BackSolvent。
- **可选勾选项（Tag）**：如 Source Tracking、Destination Tracking、Look Ahead。列表随上面选的操作和类别变化。RUN 按这些 Tag 决定用哪个硬件、怎么执行。

有些 Tag 在同一系统上互斥，勾选时 PLAN 会自动处理。分液类别和液面跟踪的原理，见 Stuntman 分液指南。

*图:分液步骤的编辑区：左边选来源，中间选目标库和孔，右边是 Options。这里选的是 Liquid Dispense、H6Tip 和 BackSolvent 类别，下面是可勾选的 Tag。图取自原厂用户指南。*

### 从化学品加到孔里

- Select Source 选 Chemicals，从按 Category 分组的树里点一种化学品，例如单抗原液。
- Select Destination Library 选目标库，在下面的板图上选孔。选中的每个孔都会加这种化学品。
- 切到 Value 标签，填加入量，选单位。
- 在右边 Options 里选操作、工具和类别。
- 点 Add To Recipe，这一步出现在下方列表里。

Value 标签容易忘，它和 Options 不在一处。没填加入量就点 Add To Recipe，会弹框说明缺了什么。

选孔有几种方式：单击选一个孔，Ctrl+单击增减单个孔，拖动框选一块，点行号或列号选整行整列，勾 Select All 选全板。

所有孔加同样的量，用 Uniform。每个孔加的量不同，用 Discrete，逐孔填写，也可以用 Import 从 CSV 文件批量导入。例子里的糖、聚山梨酯 80、氯化钠和注射用水都用 Discrete 逐孔加，8 个孔配成 8 个处方。体积单位有 µL 和 mL，质量单位有 µg、mg、g、kg。

### 从一块板转移到另一块板

板间转移，例如梯度稀释、复制子板，来源要选 Libraries。

- Select Source 选 Libraries，选来源库，在弹出的小板图上选要吸的孔。
- 选目标库和目标孔。
- 两边都选好后，切到 Map 标签，查看来源孔和目标孔的对应关系，需要时调整。
- 切到 Value 标签填转移量，点 Add To Recipe。

来源和目标是同一块库时，同一个孔不能两边都选。两边选了同一个孔，Add To Recipe 会报错，并列出重叠的孔。

### Auto-Mapping：多孔对多孔时选 Daughter 或 Transpose

- **一个来源孔**：自动对应到所有选中的目标孔，不弹框。
- **多个来源孔对一个目标孔**：只能 Pool，把所有来源孔合到这一个孔里，弹框确认。
- **多个来源孔对多个目标孔**：两边都必须是连续的矩形区域。弹框让你选 Daughter（默认）或 Transpose，Pool 不可选。

Daughter 把来源区域的排布原样印到目标区域，能整除时重复铺满。例如 4 × 6 的排布按 2 × 2 印满 8 × 12 板。不能整除时，按顺序把来源孔依次排到目标区域。Transpose 做同样的事，但行列互换。目标板的方向相对来源板旋转时用它，例如来源的 8 行要排到目标板的列上。

*图:从 4 × 6 母板选了 A1–B3 共 6 个孔，转移到同为 4 × 6 的冻融板。多孔对多孔，PLAN 弹框选映射方式，默认 Daughter，Pool 不可选。图取自原厂用户指南。*

### 处理步骤：振荡、控温、加盖、等待

- Select Step Type to Create 选 Process Step。
- 在 Select Hardware & Operation 树里选操作。树按工具分组，例如 Vortexer、Time Controls、Capping Station。鼠标停在操作名上，会列出它涉及的所有参数。按 Ctrl+F 可以在树里搜索。
- 选目标库和孔。处理步骤没有 Map 标签，操作施加在选中的孔上。
- 在 Options 里填参数。参数的单位由系统配置定义，例如温度用 °C、振荡用 rpm。
- 点 Add To Recipe。

一个处理步骤可以同时设几个参数。例如 Set Heated Cooled Vortex with Delay 一步里设起始振荡速度、振荡时间和结束速度。这时板图上的 Value 标签会拆成几个，每个参数一个，各自可选 Uniform 或 Discrete。

有些处理步骤只是设置，在流程里的那个位置不执行，到需要时才生效。OSR 相关的步骤多是这种。

*图:处理步骤：左边的操作树按工具分组，可见加盖、振荡、压盖等工具下的操作。中间选的是 4 × 6 母板。图取自原厂用户指南。*

### 检测步骤

Analytics Step 的界面和处理步骤一样：选检测工具和方法、选库和孔、填参数。树按检测工具分组，列出各自的检测方法。例子里母板配完后，加了一步 pH 测量。

### 双击一个孔，查看里面加了什么

在 Recipe 列表里选一步，切到板图的 Volume % 或 Mass % 标签，双击一个孔，打开 Well Details。左边是这个孔到这一步为止的组成，按体积和质量列出绝对量和百分比。右边是动过这个孔的每一步。

*图:母板 A4 孔共 2,400 µL。单抗原液和组氨酸缓冲液各 480 µL，蔗糖 600 µL，聚山梨酯 80 为 120 µL，注射用水 720 µL。这个处方不加氯化钠。右边是对应的六步分液。图取自原厂用户指南。*

### 管理 Recipe 列表

- 点列表里的一步，它回到上面的编辑区，按钮变成 Update Recipe。改完点 Update Recipe。再点一次或点 Clear Selection 取消选择。
- 有问题的步骤，行首显示红色警示图标，鼠标停上去看原因。
- Move Up、Move Down 调顺序，Duplicate 在原步骤后插入副本，Delete 删除。这几个按钮都支持多选：Shift+单击选连续几步，Ctrl+单击挑选。
- 角上的展开图标把列表弹成独立窗口，可以拖到第二台显示器上。
- Validate 打开模拟日志，逐步模拟整个流程。和点 Next 时自动做的检查相同。

流程长的时候，每加几步就点一次 Validate。加完一步就查出问题，比最后一起排查容易。几步只差目标孔时，先 Duplicate 一步，再改孔，点 Update Recipe。

同一种化学品分几步加入时，单位类别和 Backing Solvent、Inventory 这两个 Tag 要每步一致。一步用 mL、另一步用 mg，Next 时会报「inconsistent unit categories」。

*图:例子的流程弹成独立窗口后的样子。母板配好、混匀、测 pH 后，各取 700 µL 转到三块子板。振荡板 400 rpm 振荡 120 min。热应力板以 2 °C/min 升到 40 °C，保持 240 min。冻融板每个循环先暂停，由人放进 −20 °C 冰箱 12 h，再放回台面。图取自原厂用户指南。*

Recipe 列表为空时 Next 不可用，提示「At least one recipe step is required」。第 1 步换过系统后，原来的步骤可能指向已经不存在的工具或类别，要删掉重建。

## 第 4 步 Configure Deck：给每块库和每种化学品指定台面位置

上半部分是台面图，下半部分分 Libraries 和 Chemicals 两个标签。

### Libraries 标签

- **Library Substrate Type**：先选载具类型。只列出和第 2 步行列数相符的类型。
- **Library Substrate Position**：再选台面位置。可选的位置由载具类型决定。
- **Initial State**：起始状态，None、Covered、Capped 或 Uncapped。
- **Cap Rack Substrate Position**：起始状态是 Capped 或 Uncapped 时，指定盖子放在哪个瓶盖架位置。这个位置不能和库本身的位置相同。

*图:第 4 步。4 × 6 反应板用 4 mL 样品瓶架，放在 Deck 1-2 Position 1。8 × 12 分析板用 1 mL 样品瓶架，放在 Deck 5-6 Position 1。台面图上对应的两个位置标为 Library。图取自原厂用户指南。*

### Chemicals 标签

化学品分 On-Deck 和 Off-Deck 两张表。Backing solvent 自动归入 Off-Deck，只填阀位。其他化学品都在台面上，和库一样要指定载具类型和位置，还要填它在架子上的行和列。

- 一种化学品要装几个容器时，可以复制成几行，每行单独指定位置。
- 粉末分液的化学品必须用 Hopper 类载具，起始状态固定为 None。
- 填了 Amount 就要选 Unit。

### 位置不能重复

同一个台面位置只能放一块库或一种化学品。几种化学品共用一个架子时，行列位置必须不同。瓶盖架位置在不同时使用的情况下可以共用。

几块库放同一种载具时，先把一行设好，选中它点 Lock Info，再选其他行点 Apply Info，设置就复制过去。载具类型不适用的行会跳过，并在警告里列出。Reset 清空选中行的设置，释放位置。

编辑时状态栏实时显示第一个未满足的要求，例如「Library Substrate Type must be selected」。点 Next 时再全部检查一遍。

## 第 5 步 Validate Design：整体检查通过后点 Finish

点 Validate Design，PLAN 把前面各步的检查全部重做一遍，再做几项整体检查：

- 跨步骤检查：几个步骤之间的依赖关系，单看一步查不出来。
- 化学品和样品库：同第 2 步。
- 化学品和样品库的台面分配：同第 4 步。
- 流程：同第 3 步。
- 分液体积：按起始体积模拟整个流程，标出会不够吸的孔。

只有硬错误会拦住你，例如配置缺失或无效。体积不足以 ⚠ 警告显示，不拦，带警告的设计也能继续。从未保存过的新设计会提示「Save Required」，先保存一次再检查。

*图:检查通过：化学品和样品库、台面分配、流程、整体设计四项都打勾，Generate Script 和 Finish 可用。图取自原厂用户指南。*

- **Generate Python Script**（可选）：把这份设计转成 Python 设计脚本，存成 .py 文件。可以交给编程的同事扩展，或作为起点交给 Stuntman AI 修改。这是设计脚本，不是 RUN 执行用的脚本。跳过不影响完成。
- **Finish**：检查通过后可用。保存设计并回到 Dashboard。

检查不过时，看界面底部的信息，它会指出出错的步骤。常见原因是步骤放在了硬件不支持的位置，例如在不能加热的位置加热，或者数值超出允许范围。

用 AI 写设计的方法见 怎么给 Stuntman AI 写提示词。设计完成后在 RUN 里运行、在 SHOW 里看结果，见 用 RUN 运行、用 SHOW 看结果。

## 常见提示和处理办法

> | 提示 | 原因和处理 |
> | --- | --- |
> | There are multiple designs with the same name. | 文件里有同名设计，不分大小写。改掉一个再保存。 |
> | This design is locked for editing. | 设计已运行过，是只读的。Duplicate 一份再改。 |
> | This design has been run and is now read-only, so your changes were not saved. | 打开后被 RUN 运行了，刚才的修改没有存下。Duplicate 后在副本里重做。 |
> | File In Use | .stunt 文件被另一个 PLAN、RUN 或其他程序占用。在那边关掉再试。 |
> | System configuration … cannot be found. | C:\Stuntman\Plan\Configurations 里没有这份设计用的系统配置。把对应的配置文件夹加回去。 |
> | Changing the system will delete the loaded design and all completed work. | 第 1 步要换系统。点 Cancel 退回，什么都不会丢。 |
> | At least one library must be provided | 第 2 步还没有定义样品库。 |
> | Duplicate Names Detected | 两种化学品或两块库同名。按提示改名。 |
> | No accommodating substrate found for library … | 库的行列数放不进台面上任何载具。按系统支持的板或架子改尺寸。 |
> | … cannot be deleted because they are used in recipe maps | 化学品或库已被流程步骤用到。先删掉那些步骤。 |
> | Library with same name already available. Rename the library before import. | 导入的库在当前文件里已有同名。先改名再导入。 |
> | At least one recipe step is required | 第 3 步的 Recipe 列表为空。 |
> | One or more Dispense steps have invalid operation selections | 分液步骤的工具、吸头、类别或 Tag 与系统配置对不上。按列出的步骤逐个改。 |
> | Chemical … has multiple dispense maps with inconsistent … | 同一种化学品在几步里的单位类别或 Tag 不一致。统一后再继续。 |
> | 分液步骤报吸头超出板边界 | 多吸头工具放不进选中的孔，例如 6 吸头头对板边的单列孔加液。换吸头数合适的工具，或改选孔。 |
> | Save Required: Please save the design before running validation. | 新设计还没保存过。在任一步点 Save 后再检查。 |

- chemicals · 第 2 步 化学品与样品库
- validate · 第 5 步 检查与完成
