Uni-Lab-OS/.cursor/skills/add-resource/SKILL.md

name, description

name	description
add-resource	Guide for adding new resources (materials, bottles, carriers, decks, warehouses) to Uni-Lab-OS (添加新物料/资源). Uses @resource decorator for AST auto-scanning. Covers Bottle, Carrier, Deck, WareHouse definitions. Use when the user wants to add resources, define materials, create a deck layout, add bottles/carriers/plates, or mentions 物料/资源/resource/bottle/carrier/deck/plate/warehouse.

添加新物料资源

Uni-Lab-OS 的资源体系基于 PyLabRobot，通过扩展实现 Bottle、Carrier、WareHouse、Deck 等实验室物料管理。使用 @resource 装饰器注册，AST 自动扫描生成注册表条目。

---

资源类型

类型	基类	用途	示例
Bottle	Well (PyLabRobot)	单个容器（瓶、小瓶、烧杯、反应器）	试剂瓶、粉末瓶
BottleCarrier	ItemizedCarrier	多槽位载架（放多个 Bottle）	6 位试剂架、枪头盒
WareHouse	ItemizedCarrier	堆栈/仓库（放多个 Carrier）	4x4 堆栈
Deck	Deck (PyLabRobot)	工作站台面（放多个 WareHouse）	反应站 Deck

层级关系： Deck → WareHouse → BottleCarrier → Bottle

WareHouse 本质上和 Site 是同一概念 — 都是定义一组固定的放置位（slot），只不过 WareHouse 多嵌套了一层 Deck。两者都需要开发者根据实际物理尺寸自行计算各 slot 的偏移坐标。

---

@resource 装饰器

from unilabos.registry.decorators import resource

@resource(
    id="my_resource_id",        # 注册表唯一标识（必填）
    category=["bottles"],       # 分类标签列表（必填）
    description="资源描述",
    icon="",                    # 图标
    version="1.0.0",
    handles=[...],              # 端口列表（InputHandle / OutputHandle）
    model={...},                # 3D 模型配置
    class_type="pylabrobot",    # "python" / "pylabrobot" / "unilabos"
)

---

创建规范

命名规则

1. name 参数作为前缀：所有工厂函数必须接受 name: str 参数，创建子物料时以 name 作为前缀，确保实例名在运行时全局唯一
2. Bottle 命名约定：试剂瓶-Bottle，烧杯-Beaker，烧瓶-Flask，小瓶-Vial
3. 函数名 = @resource(id=...)：工厂函数名与注册表 id 保持一致

子物料命名示例

# Carrier 内部的 sites 用 name 前缀
for k, v in sites.items():
    v.name = f"{name}_{v.name}"     # "堆栈1左_A01", "堆栈1左_B02" ...

# Carrier 中放置 Bottle 时用 name 前缀
carrier[0] = My_Reagent_Bottle(f"{name}_flask_1")    # "堆栈1左_flask_1"
carrier[i] = My_Solid_Vial(f"{name}_vial_{ordering[i]}")  # "堆栈1左_vial_A1"

# create_homogeneous_resources 使用 name_prefix
sites=create_homogeneous_resources(
    klass=ResourceHolder,
    locations=[...],
    name_prefix=name,  # 自动生成 "{name}_0", "{name}_1" ...
)

# Deck setup 中用仓库名称作为 name 传入
self.warehouses = {
    "堆栈1左": my_warehouse_4x4("堆栈1左"),   # WareHouse.name = "堆栈1左"
    "试剂堆栈": my_reagent_stack("试剂堆栈"),  # WareHouse.name = "试剂堆栈"
}

其他规范

• max_volume 单位为 μL：500mL = 500000
• 尺寸单位为 mm：diameter, height, size_x/y/z, dx/dy/dz
• BottleCarrier 必须设置 num_items_x/y/z：用于前端渲染布局
• Deck 的 __init__ 必须接受 setup=False：图文件中 config.setup=true 触发 setup()
• 按项目分组文件：同一工作站的资源放在 unilabos/resources/<project>/ 下
• __init__ 必须接受 serialize() 输出的所有字段：serialize() 输出会作为 config 回传到 __init__，因此必须通过显式参数或 **kwargs 接受，否则反序列化会报错
• 持久化运行时状态用 serialize_state()：通过 _unilabos_state 字典存储可变信息（如物料内容、液体量），只存 JSON 可序列化的基本类型

---

资源模板

Bottle

from unilabos.registry.decorators import resource
from unilabos.resources.itemized_carrier import Bottle


@resource(id="My_Reagent_Bottle", category=["bottles"], description="我的试剂瓶")
def My_Reagent_Bottle(
    name: str,
    diameter: float = 70.0,
    height: float = 120.0,
    max_volume: float = 500000.0,
    barcode: str = None,
) -> Bottle:
    return Bottle(
        name=name,
        diameter=diameter,
        height=height,
        max_volume=max_volume,
        barcode=barcode,
        model="My_Reagent_Bottle",
    )

Bottle 参数：

• name: 实例名称（运行时唯一，由上层 Carrier 以前缀方式传入）
• diameter: 瓶体直径 (mm)
• height: 瓶体高度 (mm)
• max_volume: 最大容积（μL，500mL = 500000）
• barcode: 条形码（可选）

BottleCarrier

from pylabrobot.resources import ResourceHolder
from pylabrobot.resources.carrier import create_ordered_items_2d
from unilabos.resources.itemized_carrier import BottleCarrier
from unilabos.registry.decorators import resource


@resource(id="My_6SlotCarrier", category=["bottle_carriers"], description="六槽位载架")
def My_6SlotCarrier(name: str) -> BottleCarrier:
    sites = create_ordered_items_2d(
        klass=ResourceHolder,
        num_items_x=3, num_items_y=2,
        dx=10.0, dy=10.0, dz=5.0,
        item_dx=42.0, item_dy=35.0,
        size_x=20.0, size_y=20.0, size_z=50.0,
    )
    # 子 site 用 name 作为前缀
    for k, v in sites.items():
        v.name = f"{name}_{v.name}"

    carrier = BottleCarrier(
        name=name, size_x=146.0, size_y=80.0, size_z=55.0,
        sites=sites, model="My_6SlotCarrier",
    )
    carrier.num_items_x = 3
    carrier.num_items_y = 2
    carrier.num_items_z = 1

    # 放置 Bottle 时用 name 作为前缀
    ordering = ["A1", "B1", "A2", "B2", "A3", "B3"]
    for i in range(6):
        carrier[i] = My_Reagent_Bottle(f"{name}_vial_{ordering[i]}")
    return carrier

WareHouse / Deck 放置位

WareHouse 和 Site 本质上是同一概念：都是定义一组固定放置位（slot），根据物理尺寸自行批量计算偏移坐标。WareHouse 只是多嵌套了一层 Deck 而已。推荐开发者直接根据实物测量数据计算各 slot 偏移量。

WareHouse（使用 warehouse_factory）

from unilabos.resources.warehouse import warehouse_factory
from unilabos.registry.decorators import resource


@resource(id="my_warehouse_4x4", category=["warehouse"], description="4x4 堆栈仓库")
def my_warehouse_4x4(name: str) -> "WareHouse":
    return warehouse_factory(
        name=name,
        num_items_x=4, num_items_y=4, num_items_z=1,
        dx=10.0, dy=10.0, dz=10.0,             # 第一个 slot 的起始偏移
        item_dx=147.0, item_dy=106.0, item_dz=130.0,  # slot 间距
        resource_size_x=127.0, resource_size_y=85.0, resource_size_z=100.0,  # slot 尺寸
        model="my_warehouse_4x4",
        col_offset=0,       # 列标签起始偏移（0 → A01, 4 → A05）
        layout="row-major",  # "row-major" 行优先 / "col-major" 列优先 / "vertical-col-major" 竖向
    )

warehouse_factory 参数说明：

• dx/dy/dz：第一个 slot 相对 WareHouse 原点的偏移（mm）
• item_dx/item_dy/item_dz：相邻 slot 间距（mm），需根据实际物理间距测量
• resource_size_x/y/z：每个 slot 的可放置区域尺寸
• layout：影响 slot 标签和坐标映射
  • "row-major"：A01,A02,...,B01,B02,...（行优先，适合横向排列）
  • "col-major"：A01,B01,...,A02,B02,...（列优先）
  • "vertical-col-major"：竖向排列，y 坐标反向

Deck 组装 WareHouse

Deck 通过 setup() 将多个 WareHouse 放置到指定坐标：

from pylabrobot.resources import Deck, Coordinate
from unilabos.registry.decorators import resource


@resource(id="MyStation_Deck", category=["deck"], description="我的工作站 Deck")
class MyStation_Deck(Deck):
    def __init__(self, name="MyStation_Deck", size_x=2700.0, size_y=1080.0, size_z=1500.0,
                 category="deck", setup=False, **kwargs) -> None:
        super().__init__(name=name, size_x=size_x, size_y=size_y, size_z=size_z)
        if setup:
            self.setup()

    def setup(self) -> None:
        self.warehouses = {
            "堆栈1左": my_warehouse_4x4("堆栈1左"),
            "堆栈1右": my_warehouse_4x4("堆栈1右"),
        }
        self.warehouse_locations = {
            "堆栈1左": Coordinate(-200.0, 400.0, 0.0),  # 自行测量计算
            "堆栈1右": Coordinate(2350.0, 400.0, 0.0),
        }
        for wh_name, wh in self.warehouses.items():
            self.assign_child_resource(wh, location=self.warehouse_locations[wh_name])

Site 模式（前端定向放置）

适用于有固定孔位/槽位的设备（如移液站 PRCXI 9300），Deck 通过 sites 列表定义前端展示的放置位，前端据此渲染可拖拽的孔位布局：

import collections
from typing import Any, Dict, List, Optional
from pylabrobot.resources import Deck, Resource, Coordinate
from unilabos.registry.decorators import resource


@resource(id="MyLabDeck", category=["deck"], description="带 Site 定向放置的 Deck")
class MyLabDeck(Deck):
    # 根据设备台面实测批量计算各 slot 坐标偏移
    _DEFAULT_SITE_POSITIONS = [
        (0, 0, 0), (138, 0, 0), (276, 0, 0), (414, 0, 0),       # T1-T4
        (0, 96, 0), (138, 96, 0), (276, 96, 0), (414, 96, 0),   # T5-T8
    ]
    _DEFAULT_SITE_SIZE = {"width": 128.0, "height": 86.0, "depth": 0}
    _DEFAULT_CONTENT_TYPE = ["plate", "tip_rack", "tube_rack", "adaptor"]

    def __init__(self, name: str, size_x: float, size_y: float, size_z: float,
                 sites: Optional[List[Dict[str, Any]]] = None, **kwargs):
        super().__init__(size_x, size_y, size_z, name)
        if sites is not None:
            self.sites = [dict(s) for s in sites]
        else:
            self.sites = []
            for i, (x, y, z) in enumerate(self._DEFAULT_SITE_POSITIONS):
                self.sites.append({
                    "label": f"T{i + 1}",          # 前端显示的槽位标签
                    "visible": True,                # 是否在前端可见
                    "position": {"x": x, "y": y, "z": z},  # 槽位物理坐标
                    "size": dict(self._DEFAULT_SITE_SIZE),  # 槽位尺寸
                    "content_type": list(self._DEFAULT_CONTENT_TYPE),  # 允许放入的物料类型
                })
        self._ordering = collections.OrderedDict(
            (site["label"], None) for site in self.sites
        )

    def assign_child_resource(self, resource: Resource,
                              location: Optional[Coordinate] = None,
                              reassign: bool = True,
                              spot: Optional[int] = None):
        idx = spot
        if spot is None:
            for i, site in enumerate(self.sites):
                if site.get("label") == resource.name:
                    idx = i
                    break
        if idx is None:
            for i in range(len(self.sites)):
                if self._get_site_resource(i) is None:
                    idx = i
                    break
        if idx is None:
            raise ValueError(f"No available site for '{resource.name}'")
        loc = Coordinate(**self.sites[idx]["position"])
        super().assign_child_resource(resource, location=loc, reassign=reassign)

    def serialize(self) -> dict:
        data = super().serialize()
        sites_out = []
        for i, site in enumerate(self.sites):
            occupied = self._get_site_resource(i)
            sites_out.append({
                "label": site["label"],
                "visible": site.get("visible", True),
                "occupied_by": occupied.name if occupied else None,
                "position": site["position"],
                "size": site["size"],
                "content_type": site["content_type"],
            })
        data["sites"] = sites_out
        return data

Site 字段说明：

字段	类型	说明
label	str	槽位标签（如 "T1"），前端显示名称，也用于匹配 resource.name
visible	bool	是否在前端可见
position	dict	物理坐标 {x, y, z}（mm），需自行测量计算偏移
size	dict	槽位尺寸 {width, height, depth}（mm）
content_type	list	允许放入的物料类型，如 ["plate", "tip_rack", "tube_rack", "adaptor"]

参考实现： unilabos/devices/liquid_handling/prcxi/prcxi.py 中的 PRCXI9300Deck（4x4 共 16 个 site）。

---

文件位置

unilabos/resources/
├── <project>/              # 按项目分组
│   ├── bottles.py          # Bottle 工厂函数
│   ├── bottle_carriers.py  # Carrier 工厂函数
│   ├── warehouses.py       # WareHouse 工厂函数
│   └── decks.py            # Deck 类定义

---

验证

# 资源可导入
python -c "from unilabos.resources.my_project.bottles import My_Reagent_Bottle; print(My_Reagent_Bottle('test'))"

# 启动测试（AST 自动扫描）
unilab -g <graph>.json

仅在以下情况仍需 YAML：第三方库资源（如 pylabrobot 内置资源，无 @resource 装饰器）。

---

关键路径

内容	路径
Bottle/Carrier 基类	unilabos/resources/itemized_carrier.py
WareHouse 基类 + 工厂	unilabos/resources/warehouse.py
PLR 注册	unilabos/resources/plr_additional_res_reg.py
装饰器定义	unilabos/registry/decorators.py