Lunatic 自动化交付:验证、速查、示例与清单

系列指南 · 第 6 篇

Lunatic 自动化交付：验证、速查、示例与清单

Lunatic 脚本写完，离交付还差几步：进自动化产线之前，要先用真实样品分四轮做湿跑验证；现场出问题时，要能从一串负数状态码里快速看出原因；机柜布置、工作台开孔、机械臂路径规划，要按官方图纸的精确尺寸来。

先认识几个名词

• 湿跑(wet run) — 用真实样品(而不是空跑)把整套系统走一遍，从加样、测量到结果写入共享盘。验证脚本、机械、字符串和数据流都对得上。
• 状态码体系 — Lunatic API 用整数返回结果。约定：0 是成功，正数是状态或补充信息(不是错)，负数是错误，不同负数对应不同错因。
• 降级处理 — 出错时不停下来等人，改用一种不那么自动但仍可继续的方式。比如条码读不到时，从 autodetect 退回到明确传 plate_ID。
• 状态码处理函数 — 把"看到状态码 X 该做什么"集中写在一个函数里，所有命令共用。0 和正数照常往下走；负数的应对动作常分四种：重试 / 降级 / 停产线 / 报警。出错策略要调整时，只改这一处。
• pump profile — Lunatic 测量时控制微流控泵推进样品的运行参数文件。仪器内置一组，新应用安装时一起更新。
• chip ID — Lunatic Plate 上的微流控芯片标识。仪器测量前要先识别 chip ID，识别不到会报 −26。
• IQ / OQ / PV — 仪器合规验证的三个阶段：Installation Qualification(安装确认)、Operational Qualification(运行确认)、Performance Verification(性能验证)。GMP 项目必须有完整记录。
• 交付清单 — 系统调试完毕、交给客户接手时，需要一并提供给客户的资料清单。半年后排查问题时，要查的资料应该都在这一份清单里。

交付前要过的五道关

自动化整合的验收按下面的顺序走。每一步验证的对象不同，前一步通过了再接下一步，问题就会在离源头最近的地方暴露，交付前就能处理掉。

湿跑验证：由简到繁跑四轮

这四轮覆盖了整条链路里最容易出问题的几个环节。前三轮各跑一块板，第四轮连续跑多块。建议按顺序跑，每轮验证通过之后再进入下一轮。这样一旦出现异常，问题范围比较容易锁定。

轮 / 用途 / 关注点

1:用途 空板自检;关注点 不加样品，让机械臂搬一块空 Lunatic Plate 进出几次。看机械臂能否每次精准入位、条码能否每次读到、托盘机械动作有无卡顿。

2:用途 已知浓度标定板;关注点 用 BSA、IgG 等标准品配 3 个浓度梯度，每浓度 4 复孔。再加 4 个 PBS 空白，共 16 孔。比对测出来的浓度和标定值的偏差，确认仪器、应用、字符串字段、E1% 都对得上。

3:用途 真实样品单板;关注点 实际项目要测的样品，先单独跑一板。人工对照 Lunatic & Stunner Client 直接测出来的结果，确认 API 和 Client 给的数据一致。两边数据应当对得上；不一致时优先查实验定义里的字段(application_name、blanking_information、列号映射)是否对得齐。

4:用途 连续多板;关注点 让机械臂连续搬 5–10 块加好样的 Lunatic Plate，中间不人工干预。看 DQ_Get_Status 轮询是否稳定、DQ_Get_Results 一次取走是否成功、.bin 文件是否每块都正确写到共享目录。

几条排查经验:第 2 轮浓度偏差，先查实验定义里的 application_name 和样品定义里的 E1% 列。第 3 轮和 Client 数据不一致，常见原因是 blanking_information 模式或 sample group 列号映射错。第 4 轮偶发失败，通常是轮询频率太快，或网络共享在多板连测时被反复读写，出现间歇性失败。

状态码速查表

湿跑过程中如果出问题，Lunatic 不会弹任何对话框，所有信息都通过命令的整数状态码反馈出来。脚本拿到状态码后自己判断怎么处理。约定：0 是成功，正数是状态信息(不是错)，负数是错误。下表把全部状态码按数值排好，现场出问题时直接对照查。

代码:含义

正数：状态信息

999:Lunatic & Stunner Client 已接受退出

52:已连接，托盘正在移动

51:已连接，托盘已关闭

50:已连接，托盘已打开

33:已连接，测量已暂停

32:已连接，等待加载下一块 Lunatic Plate

31:已连接，测量进行中

30:已连接，测量正在初始化

25:已连接，测量成功

23:已连接，测量已启动

21:已连接，无测量任务

20:访问权空闲

4:托盘本来就是关着的

3:托盘本来就是开着的

1:已持有访问权

0:成功

0:命令执行成功

负数：错误(脚本必须处理)

−1:无访问权

−2:仪器状态不对(常因前一动作未完成)

−3:打不开托盘

−4:关不上托盘

−5:托盘位置不对

−9:解析实验定义出错

−10:解析样品定义出错

−11 / −12:找不到 pump profile

−13:未定义样品

−14:托盘开位超时

−15:条码无效

−16:没有条码扫描器

−17:条码扫描器超时

−22:测量初始化失败

−24:测量失败

−26:测量失败：chip ID 未知

−31:测量进行中，命令无法执行

−52:托盘移动中，命令无法执行

−61:存空白：空白实验来自其他仪器

−62:存空白：空白实验超过 100 天

−63:存空白：仪器在空白测量后做过校准

−64:存空白：找不到可复现的空白

−65:存空白：找不到文件

−66:存空白：按列指定的 sample group 名错误

−67:存空白：按名称指定的 sample group 错误

−68:存空白：存在多个 sample group，需明确指定

−99:超时

−100:访问被本地操作中断

−102:Lunatic Plate ID 无效

−103:Lunatic Plate ID 已经测过

−104:必须等所有 Lunatic Plate 测完才能取结果

−106:仪器里没有板

−111:仪器状态不对

−120:自动化 License 未激活

负数：DropQuant_Remote.dll / 通信内部错(可调 DQ_GetLastInternalError)

−200:TCP 连不上

−201:DLL 内部错：无法把返回字符串转成期望参数

−202:DLL 内部错：无法把状态码转成整数

负数：命令 / 参数 / 板型 / 应用层

−300:未知命令

−400:参数不全

−401:作为参数的文件找不到或读不到

−500:未明确错误

−901:仪器上未安装该应用

−902:实验定义里 plate type 不识别

−903:plate type 不能用于该应用

−904:plate type 不能用于该仪器

−905:应用加载失败

−906:该板需要更新光程文件

常见错误码怎么应对

日常生产里高频出现的状态码只有少数几个，下面是它们的常见原因和处理思路。

### 建议：状态码集中到一个函数里处理

生产脚本里推荐写一个统一的函数，处理所有返回的状态码。不必在每条命令调完之后各自写一份 if-else。0 和正数照常往下走；负数的应对动作分成四种：

- 能自动重试就重试。

- 不行就降级用备选方案(比如条码读不到就改用明确的 plate_ID)。

- 再不行就停产线。

- 最严重的报警让人介入。

函数的写法见命令篇「出错了怎么定位」一节。

仪器外形尺寸

工作台开孔、机柜布置、机械臂路径规划，要用到下面几组官方尺寸。第 2 篇讲过基本规格，这里集中列出，便于对照。

维度:数值

宽(Appendix 3):373.60 mm

深 · 托盘关闭(Appendix 3):461.70 mm

深 · 托盘开启板伸出(Appendix 3):623.46 mm

高(Appendix 3):328.60 mm

两销孔左右间距(Figure 7):200 mm

Lunatic Plate 底面到工作台参考面(Manual §2.4):145.60 mm

板托厚度(Figure 7 侧视):5 mm

机械臂路径要注意两件事。一是托盘打开后会从机身正面伸出约 162 mm(623.46 − 461.70 mm)，这段空间要保持留空。机械臂从板的正上方垂直下放，不能沿托盘伸出方向斜插。二是 Lunatic 顶部有进气口，做堆叠或加防尘罩之前要参照仪器手册，留足散热空间。

Lunatic API Manual Appendix 3(正面)。仪器正面外形，宽 373.60 mm。

Lunatic API Manual Appendix 3(侧面)。仪器侧面外形：深度托盘关闭 461.70 mm、开启时板伸出后 623.46 mm，高 328.60 mm。

Lunatic API Manual Figure 7(底视)。Lunatic 底面两个 12 mm 销孔，配同径的 12m6 销作粗对位，两销左右间距 200 mm。托盘开启时 Lunatic Plate 中心：X 方向距销 1 为 60.41 mm、距销 2 为 139.59 mm;Y 方向距两销连线 428.08 mm。

Lunatic Plate 尺寸

Lunatic Plate 的外框尺寸和 96 个孔的位置都遵循 SBS 标准(A1–H12 命名、9 mm 间距)。机械臂的抓取参数和孔位坐标都能直接套用 SBS 96 板设置。物理结构上，96 个孔分布在 6 条可拆装的 strip 上，每条 16 个孔。孔的形状是 Lunatic 特有的漏斗 + meander 设计。但从脚本和机械臂的角度看，孔位与普通 SBS 96 板完全一致。

• 外框 — 85.48 × 127.76 mm — SBS 96 板标准，机械臂抓取参数可直接套用。
• 总高 — 11.54 mm — Frame 10 mm + Strip 1.54 mm。机械臂的垂直抓取间距按这个高度配置。
• 孔位间距 — 9 mm — SBS 标准；6 条 strip × 16 个加样孔 = 96 个孔。
• 整板重量 — 38 g 或 151 g — molded frame(出厂预装)38 g;aluminum frame(用户自装)151 g。两种重量差近 4 倍，机械臂参数要按实际 frame 配。

Lunatic 还有一个 High Lunatic Plate 版本，光程更短，适合高浓度样品。外形和 Lunatic Plate 完全互换，实验定义里 dropplate_type="High Lunatic Plate" 就能切换。

Lunatic API Manual Appendix 4(上半部分)。Lunatic Plate 完整工程图：俯视 85.48 × 127.76 mm + Section A-A 侧面截面 + 背面安装孔位。

Lunatic API Manual Appendix 4(下半部分)。Detail E 放大 A1 角附近的 strip + alignment mark 布局；Section B-B 板的总高 11.54 mm = Frame 10 mm + Strip 1.54 mm。

合规材料(IQ-OQ-PV)

受 GMP / NMPA / FDA 监管的客户做自动化验收时，除了上面的湿跑，还要做合规文档。合规文档分 IQ / OQ / PV 三个阶段。这部分跟 API 集成是两套独立的工作，但通常一起交付。

• IQ — Installation Qualification — 安装确认。确认仪器到货完整、安装环境符合要求、所有附件到位。
• OQ — Operational Qualification — 运行确认。运行 Instrument QC，并做 350 nm 处的 OD check，检查吸光度准确性。
• PV — Performance Verification — 性能验证。先用 Hellma 认证参考物质(CRM)比色皿验证吸光度准确性、精密度、线性、波长准确性、杂散光、分辨率，对齐 USP ⟨857⟩ 和 Ph.Eur. 2.2.25;再用 Fundamentals kit 的 5 个色氨酸标准品做 Fundamentals check。

Lunatic IQ/OQ/PV 文档:Unchained Labs 官方提供 Lunatic IQ/OQ/PV 与 21 CFR Part 11 IQ/OQ 文档。文档涵盖三阶段验证协议，以及 21 CFR Part 11 电子签名/审计追踪合规材料。GMP 项目验收时一并交付即可。中国团队可以协助提供这份文档。

在自动化集成项目里，PV 通常作为独立的合规验证流程单独维护，不混在日常生产脚本里。一般由 QA 团队按周期手动触发，比如每月或每季度。也可以由调度系统在预留的合规时间段里自动触发。

端到端示例：一段完整的 C# 脚本

下面这段 C# 代码来自 Lunatic API Manual Appendix 1，做了少量注释和缩进调整。代码展示一次"两个 sample group、8 个孔的实验"从建立连接到取结果的完整流程。

这段代码值得留意的几个工程细节：

• goto End / goto Exit 模式:每条命令的返回值都判断 < 0，出错就跳到 End 标签；End 里统一调 DQ_Release_Access。手册示例用 goto，生产代码里换成 try/finally 也是一样的意思。核心是无论成败，DQ_Release_Access 都要执行。
• 轮询条件 != 32 && != 25 && != 31:意思是"状态在'测量中(31)'、'测完(25)'、'等下一块板(32)'之外的任何值，都视为异常退出"。换句话说，只允许这三个码继续轮询，其它一概当错处理。
• DQ_Get_Results 上的 -104 重试:多板实验里，只要还有板没测完，DQ_Get_Results 就返回 -104。手册的写法是 while (status == -104) 死循环等，生产代码里建议加超时(比如累计等 30 分钟还在 -104，就报警)。
• DQ_Get_Results 第二个参数留空:留空表示"返回所有板的结果"，一次取走；传具体 plate_ID 才是只取那一块。

以这段代码为模板，替换 IP、端口和三段字符串，就可以开始写自己的第一个 Lunatic 自动化脚本。

交付清单

验收完成之后，系统通常由客户接手维护。建议在交付时把下面这份清单一并留给客户。半年甚至一年后再去排查问题，要查的资料应该都能在这一份里找到。

• overview · 交付前要过的五道关
• wet-run · 湿跑验证：由简到繁跑四轮
• status-table · 状态码速查表
• common-errors · 常见错误码怎么应对
• instrument-dim · 仪器外形尺寸
• plate-dim · Lunatic Plate 尺寸
• compliance · 合规材料(IQ-OQ-PV)
• end-to-end · 端到端示例(C#)
• 湿跑(wet run) · 用真实样品(而不是空跑)把整套系统走一遍，从加样、测量到结果写入共享盘。验证脚本、机械、字符串和数据流都对得上。
• 状态码体系 · Lunatic API 用整数返回结果。约定：0 是成功，正数是状态或补充信息(不是错)，负数是错误，不同负数对应不同错因。
• 降级处理 · 出错时不停下来等人，改用一种不那么自动但仍可继续的方式。比如条码读不到时，从 autodetect 退回到明确传 plate_ID。
• 状态码处理函数 · 把"看到状态码 X 该做什么"集中写在一个函数里，所有命令共用。0 和正数照常往下走；负数的应对动作常分四种：重试 / 降级 / 停产线 / 报警。出错策略要调整时，只改这一处。
• pump profile · Lunatic 测量时控制微流控泵推进样品的运行参数文件。仪器内置一组，新应用安装时一起更新。
• chip ID · Lunatic Plate 上的微流控芯片标识。仪器测量前要先识别 chip ID，识别不到会报 −26。
• IQ / OQ / PV · 仪器合规验证的三个阶段：Installation Qualification(安装确认)、Operational Qualification(运行确认)、Performance Verification(性能验证)。GMP 项目必须有完整记录。
• 交付清单 · 系统调试完毕、交给客户接手时，需要一并提供给客户的资料清单。半年后排查问题时，要查的资料应该都在这一份清单里。
• 字符串 · 单板手动验三段字符串 · 正式接工作站之前，在 Lunatic 上单独跑一板。把三段字符串和命令顺序逐一调通，确认 DQ_Define_Experiment、DQ_Measure、DQ_Get_Results 全部返回 0。再确认字符串里没有语法或列号错误。详细做法见第 5 篇最后一节。
• 脚本 · 脚本独立跑一遍 · 在客户脚本的运行环境里，先绕开机械臂，直接连 Lunatic，手动放板、关托盘，跑一遍完整流程。验证脚本的命令顺序、异常处理和轮询逻辑都对。
• 湿跑 · 湿跑验证 · 把机械臂或液体工作站接进来。用真实样品按下一节的四轮湿跑跑一遍，核对结果是否符合预期。
• 故障演练 · 故障演练 · 人为制造几个常见异常(条码读不到、放板倾斜、网络断开)。观察脚本和上层调度的反应是否符合预期。
• 交付 · 整理交付文档 · 把脚本源码、API License、Lunatic & Stunner Client 版本、网络配置、空白库内容、错误码处理逻辑全部整理给客户。完整清单见本篇最后一节。
• 网络 · −200 · TCP 连不上 · 多半是网络或 IP 配置出了问题。脚本里可以先重试 3 次，每次间隔 2 秒，仍然失败再让上层调度报警并停产线；同时调一次 DQ_GetLastInternalError() 拿 DLL 内部的详细信息。
• License · −120 · License 未激活 · 激活码没填，或者 Automation 页面顶部没出绿色对勾。这种错脚本无法自动恢复，只能停下来等人去 Lunatic & Stunner Client 里重新激活。
• 会话 · −1 · 无访问权 · 上一个用 Lunatic 的脚本没释放访问权，或者 USB 那边同时连着 Client 软件。重新发 DQ_Request_Access;如果还不行，报警让人介入。
• 字符串 · −9 / −10 · 解析实验或样品定义出错 · 字符串语法有问题。脚本本身没法自动重试，要回去核对字符串。生产脚本里建议先用一个校验值(比如 hash)，比对当前要发的字符串和已验证过的版本是否一致。一致就跳过，不一致再去查改了什么。
• 逻辑 · −104 · 没测完就取结果 · 还有 Lunatic Plate 没测完。多板实验里这是正常返回，按下面示例代码循环重试并加超时。如果超时报警，查轮询逻辑：DQ_Measure 之后有没有等 DQ_Get_Status 返回 25(测量成功)再发 DQ_Get_Results。
• 条码 · −15 / −17 · 条码无效或扫描超时 · 板贴反、条码污损是最常见原因。处理方式是降级：不用 "autodetect"，改用 DQ_Define_Experiment 返回的明确 plate_ID 去测。
• 硬件 · −22 / −24 / −26 · 测量初始化或测量失败 · 这一组通常是真正的设备问题：芯片识别失败、Lunatic Plate 装载异常，或者仪器自身故障。脚本可以先发一次 DQ_Reset() 再重试，仍失败就停产线、走维护流程。
• 空白 · −61 ~ −68 · 存空白相关错误 · 多数是 sample group 命名或时间过期。生产脚本里通常先用 DQ_Get_Stored_Blanks 查一下仪器里现存什么空白，再根据返回结果决定下一步怎么走。
• 外框 · 85.48 × 127.76 mm · SBS 96 板标准，机械臂抓取参数可直接套用。
• 总高 · 11.54 mm · Frame 10 mm + Strip 1.54 mm。机械臂的垂直抓取间距按这个高度配置。
• 孔位间距 · 9 mm · SBS 标准；6 条 strip × 16 个加样孔 = 96 个孔。
• 整板重量 · 38 g 或 151 g · molded frame(出厂预装)38 g;aluminum frame(用户自装)151 g。两种重量差近 4 倍，机械臂参数要按实际 frame 配。
• IQ · Installation Qualification · 安装确认。确认仪器到货完整、安装环境符合要求、所有附件到位。
• OQ · Operational Qualification · 运行确认。运行 Instrument QC，并做 350 nm 处的 OD check，检查吸光度准确性。
• PV · Performance Verification · 性能验证。先用 Hellma 认证参考物质(CRM)比色皿验证吸光度准确性、精密度、线性、波长准确性、杂散光、分辨率，对齐 USP ⟨857⟩ 和 Ph.Eur. 2.2.25;再用 Fundamentals kit 的 5 个色氨酸标准品做 Fundamentals check。
• 仪器 · 仪器 S/N、Lunatic & Stunner Client 软件版本号、API License 激活码(建议把 Unchained Labs 发的原始邮件一起存档)。
• 网络 · 固定 IP 配置(IP / 子网掩码 / 网关);若用 DHCP，记录当前 IP 和 MAC 地址，方便 IT 在路由器里做绑定。API TCP 端口实际值(从 Client Settings/Info 读；Manual 里出现过 6700、6300 两个值)。
• 共享 · 网络共享目录路径、账号、密码失效日期(到期之前需要更新)。
• 脚本 · 客户脚本的源码、依赖(语言运行时、DropQuant_Remote.dll 版本)以及运行环境部署说明。
• 字符串 · 已经验证过的实验定义、样品定义、结果定义字符串模板，每种实验类型留一份。
• 空白 · 仪器空白库当前内容(每种 plate type 一份):Plate type、sample group、有效期。
• 错误处理 · 错误码处理逻辑文档：哪些情况自动重试、哪些直接停产线、哪些需要人工介入。
• 基线 · 湿跑验证那四轮的结果存档，作为后续维护时的对照基线。
• 合规 · GMP 项目额外提供 Lunatic IQ/OQ/PV 与 21 CFR Part 11 IQ/OQ 文档，以及对应的 PV 周期记录。