diff --git a/.cursor/skills/batch-insert-reagent/SKILL.md b/.cursor/skills/batch-insert-reagent/SKILL.md index cd946cc3..884b0e5e 100644 --- a/.cursor/skills/batch-insert-reagent/SKILL.md +++ b/.cursor/skills/batch-insert-reagent/SKILL.md @@ -27,14 +27,15 @@ python -c "import base64,sys; print('Authorization: Lab ' + base64.b64encode(f'{ ### 2. --addr → BASE URL -| `--addr` 值 | BASE | -|-------------|------| -| `test` | `https://uni-lab.test.bohrium.com` | -| `uat` | `https://uni-lab.uat.bohrium.com` | -| `local` | `http://127.0.0.1:48197` | -| 不传（默认） | `https://uni-lab.bohrium.com` | +| `--addr` 值 | BASE | +| ------------ | ----------------------------------- | +| `test` | `https://leap-lab.test.bohrium.com` | +| `uat` | `https://leap-lab.uat.bohrium.com` | +| `local` | `http://127.0.0.1:48197` | +| 不传（默认） | `https://leap-lab.bohrium.com` | 确认后设置： + ```bash BASE="<根据 addr 确定的 URL>" AUTH="Authorization: Lab " @@ -65,7 +66,7 @@ curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH" 返回： ```json -{"code": 0, "data": {"uuid": "xxx", "name": "实验室名称"}} +{ "code": 0, "data": { "uuid": "xxx", "name": "实验室名称" } } ``` 记住 `data.uuid` 为 `lab_uuid`。 @@ -90,6 +91,7 @@ curl -s -X POST "$BASE/api/v1/lab/reagent" \ ``` 返回成功时包含试剂 UUID： + ```json {"code": 0, "data": {"uuid": "xxx", ...}} ``` @@ -98,28 +100,28 @@ curl -s -X POST "$BASE/api/v1/lab/reagent" \ ## 试剂字段说明 -| 字段 | 类型 | 必填 | 说明 | 示例 | -|------|------|------|------|------| -| `lab_uuid` | string | 是 | 实验室 UUID（从 API #1 获取） | `"8511c672-..."` | -| `cas` | string | 是 | CAS 注册号 | `"7732-18-3"` | -| `name` | string | 是 | 试剂中文/英文名称 | `"水"` | -| `molecular_formula` | string | 是 | 分子式 | `"H2O"` | -| `smiles` | string | 是 | SMILES 表示 | `"O"` | -| `stock_in_quantity` | number | 是 | 入库数量 | `10` | -| `unit` | string | 是 | 单位（字符串，见下表） | `"mL"` | -| `supplier` | string | 否 | 供应商名称 | `"国药集团"` | -| `production_date` | string | 否 | 生产日期（ISO 8601） | `"2025-11-18T00:00:00Z"` | -| `expiry_date` | string | 否 | 过期日期（ISO 8601） | `"2026-11-18T00:00:00Z"` | +| 字段 | 类型 | 必填 | 说明 | 示例 | +| ------------------- | ------ | ---- | ----------------------------- | ------------------------ | +| `lab_uuid` | string | 是 | 实验室 UUID（从 API #1 获取） | `"8511c672-..."` | +| `cas` | string | 是 | CAS 注册号 | `"7732-18-3"` | +| `name` | string | 是 | 试剂中文/英文名称 | `"水"` | +| `molecular_formula` | string | 是 | 分子式 | `"H2O"` | +| `smiles` | string | 是 | SMILES 表示 | `"O"` | +| `stock_in_quantity` | number | 是 | 入库数量 | `10` | +| `unit` | string | 是 | 单位（字符串，见下表） | `"mL"` | +| `supplier` | string | 否 | 供应商名称 | `"国药集团"` | +| `production_date` | string | 否 | 生产日期（ISO 8601） | `"2025-11-18T00:00:00Z"` | +| `expiry_date` | string | 否 | 过期日期（ISO 8601） | `"2026-11-18T00:00:00Z"` | ### unit 单位值 -| 值 | 单位 | -|------|------| +| 值 | 单位 | +| ------ | ---- | | `"mL"` | 毫升 | -| `"L"` | 升 | -| `"g"` | 克 | +| `"L"` | 升 | +| `"g"` | 克 | | `"kg"` | 千克 | -| `"瓶"` | 瓶 | +| `"瓶"` | 瓶 | > 根据试剂状态选择：液体用 `"mL"` / `"L"`，固体用 `"g"` / `"kg"`。 @@ -133,8 +135,22 @@ curl -s -X POST "$BASE/api/v1/lab/reagent" \ ```json [ - {"cas": "7732-18-3", "name": "水", "molecular_formula": "H2O", "smiles": "O", "stock_in_quantity": 10, "unit": "mL"}, - {"cas": "64-17-5", "name": "乙醇", "molecular_formula": "C2H6O", "smiles": "CCO", "stock_in_quantity": 5, "unit": "L"} + { + "cas": "7732-18-3", + "name": "水", + "molecular_formula": "H2O", + "smiles": "O", + "stock_in_quantity": 10, + "unit": "mL" + }, + { + "cas": "64-17-5", + "name": "乙醇", + "molecular_formula": "C2H6O", + "smiles": "CCO", + "stock_in_quantity": 5, + "unit": "L" + } ] ``` @@ -163,6 +179,7 @@ cas,name,molecular_formula,smiles,stock_in_quantity,unit,supplier,production_dat ### 执行与汇报 每次 API 调用后： + 1. 检查返回 `code`（0 = 成功） 2. 记录成功/失败数量 3. 全部完成后汇总：「共录入 N 条试剂，成功 X 条，失败 Y 条」 @@ -172,28 +189,28 @@ cas,name,molecular_formula,smiles,stock_in_quantity,unit,supplier,production_dat ## 常见试剂速查表 -| 名称 | CAS | 分子式 | SMILES | -|------|-----|--------|--------| -| 水 | 7732-18-3 | H2O | O | -| 乙醇 | 64-17-5 | C2H6O | CCO | -| 甲醇 | 67-56-1 | CH4O | CO | -| 丙酮 | 67-64-1 | C3H6O | CC(C)=O | -| 二甲基亚砜(DMSO) | 67-68-5 | C2H6OS | CS(C)=O | -| 乙酸乙酯 | 141-78-6 | C4H8O2 | CCOC(C)=O | -| 二氯甲烷 | 75-09-2 | CH2Cl2 | ClCCl | -| 四氢呋喃(THF) | 109-99-9 | C4H8O | C1CCOC1 | -| N,N-二甲基甲酰胺(DMF) | 68-12-2 | C3H7NO | CN(C)C=O | -| 氯仿 | 67-66-3 | CHCl3 | ClC(Cl)Cl | -| 乙腈 | 75-05-8 | C2H3N | CC#N | -| 甲苯 | 108-88-3 | C7H8 | Cc1ccccc1 | -| 正己烷 | 110-54-3 | C6H14 | CCCCCC | -| 异丙醇 | 67-63-0 | C3H8O | CC(C)O | -| 盐酸 | 7647-01-0 | HCl | Cl | -| 硫酸 | 7664-93-9 | H2SO4 | OS(O)(=O)=O | -| 氢氧化钠 | 1310-73-2 | NaOH | [Na]O | -| 碳酸钠 | 497-19-8 | Na2CO3 | [Na]OC([O-])=O.[Na+] | -| 氯化钠 | 7647-14-5 | NaCl | [Na]Cl | -| 乙二胺四乙酸(EDTA) | 60-00-4 | C10H16N2O8 | OC(=O)CN(CCN(CC(O)=O)CC(O)=O)CC(O)=O | +| 名称 | CAS | 分子式 | SMILES | +| --------------------- | --------- | ---------- | ------------------------------------ | +| 水 | 7732-18-3 | H2O | O | +| 乙醇 | 64-17-5 | C2H6O | CCO | +| 甲醇 | 67-56-1 | CH4O | CO | +| 丙酮 | 67-64-1 | C3H6O | CC(C)=O | +| 二甲基亚砜(DMSO) | 67-68-5 | C2H6OS | CS(C)=O | +| 乙酸乙酯 | 141-78-6 | C4H8O2 | CCOC(C)=O | +| 二氯甲烷 | 75-09-2 | CH2Cl2 | ClCCl | +| 四氢呋喃(THF) | 109-99-9 | C4H8O | C1CCOC1 | +| N,N-二甲基甲酰胺(DMF) | 68-12-2 | C3H7NO | CN(C)C=O | +| 氯仿 | 67-66-3 | CHCl3 | ClC(Cl)Cl | +| 乙腈 | 75-05-8 | C2H3N | CC#N | +| 甲苯 | 108-88-3 | C7H8 | Cc1ccccc1 | +| 正己烷 | 110-54-3 | C6H14 | CCCCCC | +| 异丙醇 | 67-63-0 | C3H8O | CC(C)O | +| 盐酸 | 7647-01-0 | HCl | Cl | +| 硫酸 | 7664-93-9 | H2SO4 | OS(O)(=O)=O | +| 氢氧化钠 | 1310-73-2 | NaOH | [Na]O | +| 碳酸钠 | 497-19-8 | Na2CO3 | [Na]OC([O-])=O.[Na+] | +| 氯化钠 | 7647-14-5 | NaCl | [Na]Cl | +| 乙二胺四乙酸(EDTA) | 60-00-4 | C10H16N2O8 | OC(=O)CN(CCN(CC(O)=O)CC(O)=O)CC(O)=O | > 此表仅供快速参考。对于不在表中的试剂，agent 应根据化学知识推断或提示用户补充。 diff --git a/.cursor/skills/batch-submit-experiment/SKILL.md b/.cursor/skills/batch-submit-experiment/SKILL.md index de6fed5e..ad92b62c 100644 --- a/.cursor/skills/batch-submit-experiment/SKILL.md +++ b/.cursor/skills/batch-submit-experiment/SKILL.md @@ -27,14 +27,15 @@ python -c "import base64,sys; print('Authorization: Lab ' + base64.b64encode(f'{ ### 2. --addr → BASE URL -| `--addr` 值 | BASE | -|-------------|------| -| `test` | `https://uni-lab.test.bohrium.com` | -| `uat` | `https://uni-lab.uat.bohrium.com` | -| `local` | `http://127.0.0.1:48197` | -| 不传（默认） | `https://uni-lab.bohrium.com` | +| `--addr` 值 | BASE | +| ------------ | ----------------------------------- | +| `test` | `https://leap-lab.test.bohrium.com` | +| `uat` | `https://leap-lab.uat.bohrium.com` | +| `local` | `http://127.0.0.1:48197` | +| 不传（默认） | `https://leap-lab.bohrium.com` | 确认后设置： + ```bash BASE="<根据 addr 确定的 URL>" AUTH="Authorization: Lab <上面命令输出的 token>" @@ -93,7 +94,7 @@ curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH" 返回： ```json -{"code": 0, "data": {"uuid": "xxx", "name": "实验室名称"}} +{ "code": 0, "data": { "uuid": "xxx", "name": "实验室名称" } } ``` 记住 `data.uuid` 为 `lab_uuid`。 @@ -104,9 +105,33 @@ curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH" curl -s -X GET "$BASE/api/v1/lab/project/list?lab_uuid=$lab_uuid" -H "$AUTH" ``` -返回项目列表，展示给用户选择。列出每个项目的 `uuid` 和 `name`。 +返回： -用户**必须**选择一个项目，记住 `project_uuid`，后续创建 notebook 时需要提供。 +```json +{ + "code": 0, + "data": { + "items": [ + { + "uuid": "1b3f249a-...", + "name": "bt", + "description": null, + "status": "active", + "created_at": "2026-04-09T14:31:28+08:00" + }, + { + "uuid": "b6366243-...", + "name": "default", + "description": "默认项目", + "status": "active", + "created_at": "2026-03-26T11:13:36+08:00" + } + ] + } +} +``` + +展示 `data.items[]` 中每个项目的 `name` 和 `uuid`，让用户选择。用户**必须**选择一个项目，记住 `project_uuid`（即选中项目的 `uuid`），后续创建 notebook 时需要提供。 ### 3. 列出可用 workflow @@ -123,6 +148,7 @@ curl -s -X GET "$BASE/api/v1/lab/workflow/template/detail/$workflow_uuid" -H "$A ``` 返回 workflow 的完整结构，包含所有 action 节点信息。需要从响应中提取： + - 每个 action 节点的 `node_uuid` - 每个节点对应的设备 ID（`resource_template_name`） - 每个节点的动作名（`node_template_name`） @@ -142,30 +168,30 @@ curl -s -X POST "$BASE/api/v1/lab/notebook" \ ```json { - "lab_uuid": "", - "project_uuid": "", - "workflow_uuid": "", - "name": "<实验名称>", - "node_params": [ + "lab_uuid": "", + "project_uuid": "", + "workflow_uuid": "", + "name": "<实验名称>", + "node_params": [ + { + "sample_uuids": ["<样品UUID1>", "<样品UUID2>"], + "datas": [ { - "sample_uuids": ["<样品UUID1>", "<样品UUID2>"], - "datas": [ - { - "node_uuid": "", - "param": {}, - "sample_params": [ - { - "container_uuid": "<容器UUID>", - "sample_value": { - "liquid_names": "<液体名称>", - "volumes": 1000 - } - } - ] - } - ] + "node_uuid": "", + "param": {}, + "sample_params": [ + { + "container_uuid": "<容器UUID>", + "sample_value": { + "liquid_names": "<液体名称>", + "volumes": 1000 + } + } + ] } - ] + ] + } + ] } ``` @@ -194,25 +220,25 @@ curl -s -X GET "$BASE/api/v1/lab/notebook/status?uuid=$notebook_uuid" -H "$AUTH" ### 每轮的字段 -| 字段 | 类型 | 说明 | -|------|------|------| +| 字段 | 类型 | 说明 | +| -------------- | ------------- | ----------------------------------------- | | `sample_uuids` | array\ | 该轮实验的样品 UUID 数组，无样品时传 `[]` | -| `datas` | array | 该轮中每个 workflow 节点的参数配置 | +| `datas` | array | 该轮中每个 workflow 节点的参数配置 | ### datas 中每个节点 -| 字段 | 类型 | 说明 | -|------|------|------| -| `node_uuid` | string | workflow 模板中的节点 UUID（从 API #4 获取） | -| `param` | object | 动作参数（根据本地注册表 schema 填写） | -| `sample_params` | array | 样品相关参数（液体名、体积等） | +| 字段 | 类型 | 说明 | +| --------------- | ------ | -------------------------------------------- | +| `node_uuid` | string | workflow 模板中的节点 UUID（从 API #4 获取） | +| `param` | object | 动作参数（根据本地注册表 schema 填写） | +| `sample_params` | array | 样品相关参数（液体名、体积等） | ### sample_params 中每条 -| 字段 | 类型 | 说明 | -|------|------|------| -| `container_uuid` | string | 容器 UUID | -| `sample_value` | object | 样品值，如 `{"liquid_names": "水", "volumes": 1000}` | +| 字段 | 类型 | 说明 | +| ---------------- | ------ | ---------------------------------------------------- | +| `container_uuid` | string | 容器 UUID | +| `sample_value` | object | 样品值，如 `{"liquid_names": "水", "volumes": 1000}` | --- @@ -233,6 +259,7 @@ python scripts/gen_notebook_params.py \ > 脚本位于本文档同级目录下的 `scripts/gen_notebook_params.py`。 脚本会： + 1. 调用 workflow detail API 获取所有 action 节点 2. 读取本地注册表，为每个节点查找对应的 action schema 3. 生成 `notebook_template.json`，包含： @@ -270,8 +297,11 @@ python scripts/gen_notebook_params.py \ "properties": { "goal": { "properties": { - "asp_vols": {"type": "array", "items": {"type": "number"}}, - "sources": {"type": "array"} + "asp_vols": { + "type": "array", + "items": { "type": "number" } + }, + "sources": { "type": "array" } }, "required": ["asp_vols", "sources"] } diff --git a/.cursor/skills/create-device-skill/SKILL.md b/.cursor/skills/create-device-skill/SKILL.md index 20cd2f33..03172efe 100644 --- a/.cursor/skills/create-device-skill/SKILL.md +++ b/.cursor/skills/create-device-skill/SKILL.md @@ -40,13 +40,13 @@ python ./scripts/gen_auth.py --config 决定 API 请求发往哪个服务器。从启动命令的 `--addr` 参数获取： -| `--addr` 值 | BASE URL | -|-------------|----------| -| `test` | `https://uni-lab.test.bohrium.com` | -| `uat` | `https://uni-lab.uat.bohrium.com` | -| `local` | `http://127.0.0.1:48197` | -| 不传（默认） | `https://uni-lab.bohrium.com` | -| 其他自定义 URL | 直接使用该 URL | +| `--addr` 值 | BASE URL | +| -------------- | ----------------------------------- | +| `test` | `https://leap-lab.test.bohrium.com` | +| `uat` | `https://leap-lab.uat.bohrium.com` | +| `local` | `http://127.0.0.1:48197` | +| 不传（默认） | `https://leap-lab.bohrium.com` | +| 其他自定义 URL | 直接使用该 URL | #### 必备项 ③：req_device_registry_upload.json（设备注册表） @@ -54,11 +54,11 @@ python ./scripts/gen_auth.py --config **推断 working_dir**（即 `unilabos_data` 所在目录）： -| 条件 | working_dir 取值 | -|------|------------------| +| 条件 | working_dir 取值 | +| -------------------- | -------------------------------------------------------- | | 传了 `--working_dir` | `/unilabos_data/`（若子目录已存在则直接用） | -| 仅传了 `--config` | `/unilabos_data/` | -| 都没传 | `<当前工作目录>/unilabos_data/` | +| 仅传了 `--config` | `/unilabos_data/` | +| 都没传 | `<当前工作目录>/unilabos_data/` | **按优先级搜索文件**： @@ -84,24 +84,6 @@ python ./scripts/gen_auth.py --config python ./scripts/extract_device_actions.py --registry <找到的文件路径> ``` -#### 完整示例 - -用户提供： - -``` ---ak a1fd9d4e-xxxx-xxxx-xxxx-d9a69c09f0fd ---sk 136ff5c6-xxxx-xxxx-xxxx-a03e301f827b ---addr test ---port 8003 ---disable_browser -``` - -从中提取： -- ✅ ak/sk → 运行 `gen_auth.py` 得到 `AUTH="Authorization: Lab YTFmZDlk..."` -- ✅ addr=test → `BASE=https://uni-lab.test.bohrium.com` -- ✅ 搜索 `unilabos_data/req_device_registry_upload.json` → 找到并确认时间 -- ✅ 用户指明目标设备 → 如 `liquid_handler.prcxi` - **四项全部就绪后才进入 Step 1。** ### Step 1 — 列出可用设备 @@ -129,6 +111,7 @@ python ./scripts/extract_device_actions.py [--registry ] ./ski 脚本会显示设备的 Python 源码路径和类名，方便阅读源码了解参数含义。 每个 action 生成一个 JSON 文件，包含： + - `type` — 作为 API 调用的 `action_type` - `schema` — 完整 JSON Schema（含 `properties.goal.properties` 参数定义） - `goal` — goal 字段映射（含占位符 `$placeholder`） @@ -150,6 +133,7 @@ python ./scripts/extract_device_actions.py [--registry ] ./ski ``` 描述规则： + - 从 `schema.properties` 读参数列表（schema 已提升为 goal 内容） - 从 `schema.required` 区分核心/可选参数 - 按功能分类（移液、枪头、外设等） @@ -165,6 +149,7 @@ python ./scripts/extract_device_actions.py [--registry ] ./ski ### Step 4 — 写 SKILL.md 直接复用 `unilab-device-api` 的 API 模板，修改： + - 设备名称 - Action 数量 - 目录列表 @@ -177,37 +162,71 @@ API 模板结构： ```markdown ## 设备信息 + - device_id, Python 源码路径, 设备类名 ## 前置条件（缺一不可） + - ak/sk → AUTH, --addr → BASE URL ## 请求约定 + - Windows 平台必须用 curl.exe（非 PowerShell 的 curl 别名） ## Session State + - lab_uuid（通过 GET /edge/lab/info 直接获取，不要问用户）, device_name ## API Endpoints -# - #1 GET /edge/lab/info → 直接拿到 lab_uuid -# - #2 创建工作流 POST /lab/workflow/owner → 拼 URL 告知用户 -# - #3 创建节点 POST /edge/workflow/node -# body: {workflow_uuid, resource_template_name: "", node_template_name: ""} -# - #4 删除节点 DELETE /lab/workflow/nodes -# - #5 更新节点参数 PATCH /lab/workflow/node -# - #6 查询节点 handles POST /lab/workflow/node-handles -# body: {node_uuids: ["uuid1","uuid2"]} → 返回各节点的 handle_uuid -# - #7 批量创建边 POST /lab/workflow/edges -# body: {edges: [{source_node_uuid, target_node_uuid, source_handle_uuid, target_handle_uuid}]} -# - #8 启动工作流 POST /lab/workflow/{uuid}/run -# - #9 运行设备单动作 POST /lab/mcp/run/action + +# - #1 GET /edge/lab/info → 直接拿到 lab_uuid + +# - #2 创建工作流 POST /lab/workflow/owner → 拼 URL 告知用户 + +# - #3 创建节点 POST /edge/workflow/node + +# body: {workflow_uuid, resource_template_name: "", node_template_name: ""} + +# - #4 删除节点 DELETE /lab/workflow/nodes + +# - #5 更新节点参数 PATCH /lab/workflow/node + +# - #6 查询节点 handles POST /lab/workflow/node-handles + +# body: {node_uuids: ["uuid1","uuid2"]} → 返回各节点的 handle_uuid + +# - #7 批量创建边 POST /lab/workflow/edges + +# body: {edges: [{source_node_uuid, target_node_uuid, source_handle_uuid, target_handle_uuid}]} + +# - #8 启动工作流 POST /lab/workflow/{uuid}/run + +# - #9 运行设备单动作 POST /lab/mcp/run/action + # - #10 查询任务状态 GET /lab/mcp/task/{task_uuid} + # - #11 运行工作流单节点 POST /lab/mcp/run/workflow/action + # - #12 获取资源树 GET /lab/material/download/{lab_uuid} + # - #13 获取工作流模板详情 GET /lab/workflow/template/detail/{workflow_uuid} -# 返回 workflow 完整结构：data.nodes[] 含每个节点的 uuid、name、param、device_name、handles + +# 返回 workflow 完整结构：data.nodes[] 含每个节点的 uuid、name、param、device_name、handles + +# - #14 按名称查询物料模板 GET /lab/material/template/by-name?lab_uuid=&name= + +# 返回 res_template_uuid，用于 #15 创建物料时的必填字段 + +# - #15 创建物料节点 POST /edge/material/node + +# body: {res_template_uuid(从#14获取), name(自定义), display_name, parent_uuid?(从#12获取), ...} + +# - #16 更新物料节点 PUT /edge/material/node + +# body: {uuid(从#12获取), display_name?, description?, init_param_data?, data?, ...} ## Placeholder Slot 填写规则 + - unilabos_resources → ResourceSlot → {"id":"/path/name","name":"name","uuid":"xxx"} - unilabos_devices → DeviceSlot → "/parent/device" 路径字符串 - unilabos_nodes → NodeSlot → "/parent/node" 路径字符串 @@ -217,13 +236,15 @@ API 模板结构： - 列出本设备所有 Slot 字段、类型及含义 ## 渐进加载策略 + ## 完整工作流 Checklist ``` ### Step 5 — 验证 检查文件完整性： -- [ ] `SKILL.md` 包含 API endpoint（#1 获取 lab_uuid、#2-#7 工作流/节点/边、#8-#11 运行/查询、#12 资源树、#13 工作流模板详情） + +- [ ] `SKILL.md` 包含 API endpoint（#1 获取 lab_uuid、#2-#7 工作流/节点/边、#8-#11 运行/查询、#12 资源树、#13 工作流模板详情、#14-#16 物料管理） - [ ] `SKILL.md` 包含 Placeholder Slot 填写规则（ResourceSlot / DeviceSlot / NodeSlot / ClassSlot / FormulationSlot + create_resource 特例）和本设备的 Slot 字段表 - [ ] `action-index.md` 列出所有 action 并有描述 - [ ] `actions/` 目录中每个 action 有对应 JSON 文件 @@ -272,92 +293,48 @@ API 模板结构： `placeholder_keys` / `_unilabos_placeholder_info` 中有 5 种值，对应不同的填写方式： -| placeholder 值 | Slot 类型 | 填写格式 | 选取范围 | -|---------------|-----------|---------|---------| -| `unilabos_resources` | ResourceSlot | `{"id": "/path/name", "name": "name", "uuid": "xxx"}` | 仅**物料**节点（不含设备） | -| `unilabos_devices` | DeviceSlot | `"/parent/device_name"` | 仅**设备**节点（type=device），路径字符串 | -| `unilabos_nodes` | NodeSlot | `"/parent/node_name"` | **设备 + 物料**，即所有节点，路径字符串 | -| `unilabos_class` | ClassSlot | `"class_name"` | 注册表中已上报的资源类 name | -| `unilabos_formulation` | FormulationSlot | `[{well_name, liquids: [{name, volume}]}]` | 资源树中物料节点的 **name**，配合液体配方 | +| placeholder 值 | Slot 类型 | 填写格式 | 选取范围 | +| ---------------------- | --------------- | ----------------------------------------------------- | ----------------------------------------- | +| `unilabos_resources` | ResourceSlot | `{"id": "/path/name", "name": "name", "uuid": "xxx"}` | 仅**物料**节点（不含设备） | +| `unilabos_devices` | DeviceSlot | `"/parent/device_name"` | 仅**设备**节点（type=device），路径字符串 | +| `unilabos_nodes` | NodeSlot | `"/parent/node_name"` | **设备 + 物料**，即所有节点，路径字符串 | +| `unilabos_class` | ClassSlot | `"class_name"` | 注册表中已上报的资源类 name | +| `unilabos_formulation` | FormulationSlot | `[{well_name, liquids: [{name, volume}]}]` | 资源树中物料节点的 **name**，配合液体配方 | ### ResourceSlot（`unilabos_resources`） 最常见的类型。从资源树中选取**物料**节点（孔板、枪头盒、试剂槽等）： -```json -{"id": "/workstation/container1", "name": "container1", "uuid": "ff149a9a-2cb8-419d-8db5-d3ba056fb3c2"} -``` +- 单个：`{"id": "/workstation/container1", "name": "container1", "uuid": "ff149a9a-..."}` +- 数组：`[{"id": "/path/a", "name": "a", "uuid": "xxx"}, ...]` +- `id` 从 parent 计算的路径格式，根据 action 语义选择正确的物料 -- 单个（schema type=object）：`{"id": "/path/name", "name": "name", "uuid": "xxx"}` -- 数组（schema type=array）：`[{"id": "/path/a", "name": "a", "uuid": "xxx"}, ...]` -- `id` 本身是从 parent 计算的路径格式 -- 根据 action 语义选择正确的物料（如 `sources` = 液体来源，`targets` = 目标位置） +> **特例**：`create_resource` 的 `res_id`，目标物料可能尚不存在，直接填期望路径，不需要 uuid。 -> **特例**：`create_resource` 的 `res_id` 字段，目标物料可能**尚不存在**，此时直接填写期望的路径（如 `"/workstation/container1"`），不需要 uuid。 +### DeviceSlot / NodeSlot / ClassSlot -### DeviceSlot（`unilabos_devices`） - -填写**设备路径字符串**。从资源树中筛选 type=device 的节点，从 parent 计算路径： - -``` -"/host_node" -"/bioyond_cell/reaction_station" -``` - -- 只填路径字符串，不需要 `{id, uuid}` 对象 -- 根据 action 语义选择正确的设备（如 `target_device_id` = 目标设备） - -### NodeSlot（`unilabos_nodes`） - -范围 = 设备 + 物料。即资源树中**所有节点**都可以选，填写**路径字符串**： - -``` -"/PRCXI/PRCXI_Deck" -``` - -- 使用场景：当参数既可能指向物料也可能指向设备时（如 `PumpTransferProtocol` 的 `from_vessel`/`to_vessel`，`create_resource` 的 `parent`） - -### ClassSlot（`unilabos_class`） - -填写注册表中已上报的**资源类 name**。从本地 `req_resource_registry_upload.json` 中查找： - -``` -"container" -``` +- **DeviceSlot**（`unilabos_devices`）：路径字符串如 `"/host_node"`，仅 type=device 的节点 +- **NodeSlot**（`unilabos_nodes`）：路径字符串如 `"/PRCXI/PRCXI_Deck"`，设备 + 物料均可选 +- **ClassSlot**（`unilabos_class`）：类名字符串如 `"container"`，从 `req_resource_registry_upload.json` 查找 ### FormulationSlot（`unilabos_formulation`） -描述**液体配方**：向哪些物料容器中加入哪些液体及体积。填写为**对象数组**： +描述**液体配方**：向哪些容器中加入哪些液体及体积。 ```json [ { "sample_uuid": "", - "well_name": "YB_PrepBottle_15mL_Carrier_bottle_A1", - "liquids": [ - { "name": "LiPF6", "volume": 0.6 }, - { "name": "DMC", "volume": 1.2 } - ] + "well_name": "bottle_A1", + "liquids": [{ "name": "LiPF6", "volume": 0.6 }] } ] ``` -#### 字段说明 - -| 字段 | 类型 | 说明 | -|------|------|------| -| `sample_uuid` | string | 样品 UUID，无样品时传空字符串 `""` | -| `well_name` | string | 目标物料容器的 **name**（从资源树中取物料节点的 `name` 字段，如瓶子、孔位名称） | -| `liquids` | array | 要加入的液体列表 | -| `liquids[].name` | string | 液体名称（如试剂名、溶剂名） | -| `liquids[].volume` | number | 液体体积（单位由设备决定，通常为 mL） | - -#### 填写规则 - -- `well_name` 必须是资源树中已存在的物料节点 `name`（不是 `id` 路径），通过 API #12 获取资源树后筛选 -- 每个数组元素代表一个目标容器的配方 -- 一个容器可以加入多种液体（`liquids` 数组多条记录） -- 与 ResourceSlot 的区别：ResourceSlot 填 `{id, name, uuid}` 指向物料本身；FormulationSlot 用 `well_name` 引用物料，并附带液体配方信息 +- `well_name` — 目标物料的 **name**（从资源树取，不是 `id` 路径） +- `liquids[]` — 液体列表，每条含 `name`（试剂名）和 `volume`（体积，单位由上下文决定；pylabrobot 内部统一 uL） +- `sample_uuid` — 样品 UUID，无样品传 `""` +- 与 ResourceSlot 的区别：ResourceSlot 指向物料本身，FormulationSlot 引用物料名并附带配方信息 ### 通过 API #12 获取资源树 @@ -365,7 +342,147 @@ API 模板结构： curl -s -X GET "$BASE/api/v1/lab/material/download/$lab_uuid" -H "$AUTH" ``` -注意 `lab_uuid` 在路径中（不是查询参数）。资源树返回所有节点，每个节点包含 `id`（路径格式）、`name`、`uuid`、`type`、`parent` 等字段。填写 Slot 时需根据 placeholder 类型筛选正确的节点。 +注意 `lab_uuid` 在路径中（不是查询参数）。返回结构： + +```json +{ + "code": 0, + "data": { + "nodes": [ + {"name": "host_node", "uuid": "c3ec1e68-...", "type": "device", "parent": ""}, + {"name": "PRCXI", "uuid": "e249c9a6-...", "type": "device", "parent": ""}, + {"name": "PRCXI_Deck", "uuid": "fb6a8b71-...", "type": "deck", "parent": "PRCXI"} + ], + "edges": [...] + } +} +``` + +- `data.nodes[]` — 所有节点（设备 + 物料），每个节点含 `name`、`uuid`、`type`、`parent` +- `type` 区分设备（`device`）和物料（`deck`、`container`、`resource` 等） +- `parent` 为父节点名称（空字符串表示顶级） +- 填写 Slot 时根据 placeholder 类型筛选：ResourceSlot 取非 device 节点，DeviceSlot 取 device 节点 +- 创建/更新物料时：`parent_uuid` 取父节点的 `uuid`，更新目标的 `uuid` 取节点自身的 `uuid` + +## 物料管理 API + +设备 Skill 除了设备动作外，还需支持物料节点的创建和参数设定，用于在资源树中动态管理物料。 + +典型流程：先通过 **#14 按名称查询模板** 获取 `res_template_uuid` → 再通过 **#15 创建物料** → 之后可通过 **#16 更新物料** 修改属性。更新时需要的 `uuid` 和 `parent_uuid` 均从 **#12 资源树下载** 获取。 + +### API #14 — 按名称查询物料模板 + +创建物料前，需要先获取物料模板的 UUID。通过模板名称查询： + +```bash +curl -s -X GET "$BASE/api/v1/lab/material/template/by-name?lab_uuid=$lab_uuid&name=" -H "$AUTH" +``` + +| 参数 | 必填 | 说明 | +| ---------- | ------ | -------------------------------- | +| `lab_uuid` | **是** | 实验室 UUID（从 API #1 获取） | +| `name` | **是** | 物料模板名称（如 `"container"`） | + +返回 `code: 0` 时，**`data.uuid`** 即为 `res_template_uuid`，用于 API #15 创建物料。返回还包含 `name`、`resource_type`、`handles`、`config_infos` 等模板元信息。 + +模板不存在时返回 `code: 10002`，`data` 为空对象。模板名称来自资源注册表中已注册的资源类型。 + +### API #15 — 创建物料节点 + +```bash +curl -s -X POST "$BASE/api/v1/edge/material/node" \ + -H "$AUTH" -H "Content-Type: application/json" \ + -d '' +``` + +请求体： + +```json +{ + "res_template_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "name": "my_custom_bottle", + "display_name": "自定义瓶子", + "parent_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "type": "", + "init_param_data": {}, + "schema": {}, + "data": { + "liquids": [["water", 1000, "uL"]], + "max_volume": 50000 + }, + "plate_well_datas": {}, + "plate_reagent_datas": {}, + "pose": {}, + "model": {} +} +``` + +| 字段 | 必填 | 类型 | 数据来源 | 说明 | +| --------------------- | ------ | ------------- | ----------------------------------- | -------------------------------------- | +| `res_template_uuid` | **是** | string (UUID) | **API #14** 按名称查询获取 | 物料模板 UUID | +| `name` | 否 | string | **用户自定义** | 节点名称（标识符），可自由命名 | +| `display_name` | 否 | string | 用户自定义 | 显示名称（UI 展示用） | +| `parent_uuid` | 否 | string (UUID) | **API #12** 资源树中父节点的 `uuid` | 父节点，为空则创建顶级节点 | +| `type` | 否 | string | 从模板继承 | 节点类型 | +| `init_param_data` | 否 | object | 用户指定 | 初始化参数，覆盖模板默认值 | +| `data` | 否 | object | 用户指定 | 节点数据，container 见下方 data 格式 | +| `plate_well_datas` | 否 | object | 用户指定 | 孔板子节点数据（创建带孔位的板时使用） | +| `plate_reagent_datas` | 否 | object | 用户指定 | 试剂关联数据 | +| `schema` | 否 | object | 从模板继承 | 自定义 schema，不传则从模板继承 | +| `pose` | 否 | object | 用户指定 | 位姿信息 | +| `model` | 否 | object | 用户指定 | 3D 模型信息 | + +#### container 的 `data` 格式 + +> **体积单位统一为 uL（微升）**。pylabrobot 体系中所有体积值（`max_volume`、`liquids` 中的 volume）均为 uL。外部如果是 mL 需乘 1000 转换。 + +```json +{ + "liquids": [["water", 1000, "uL"], ["ethanol", 500, "uL"]], + "max_volume": 50000 +} +``` + +- `liquids` — 液体列表，每条为 `[液体名称, 体积(uL), 单位字符串]` +- `max_volume` — 容器最大容量（uL），如 50 mL = 50000 uL + +### API #16 — 更新物料节点 + +```bash +curl -s -X PUT "$BASE/api/v1/edge/material/node" \ + -H "$AUTH" -H "Content-Type: application/json" \ + -d '' +``` + +请求体： + +```json +{ + "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "parent_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", + "display_name": "新显示名称", + "description": "新描述", + "init_param_data": {}, + "data": {}, + "pose": {}, + "schema": {}, + "extra": {} +} +``` + +| 字段 | 必填 | 类型 | 数据来源 | 说明 | +| ----------------- | ------ | ------------- | ------------------------------------- | ---------------- | +| `uuid` | **是** | string (UUID) | **API #12** 资源树中目标节点的 `uuid` | 要更新的物料节点 | +| `parent_uuid` | 否 | string (UUID) | API #12 资源树 | 移动到新父节点 | +| `display_name` | 否 | string | 用户指定 | 更新显示名称 | +| `description` | 否 | string | 用户指定 | 更新描述 | +| `init_param_data` | 否 | object | 用户指定 | 更新初始化参数 | +| `data` | 否 | object | 用户指定 | 更新节点数据 | +| `pose` | 否 | object | 用户指定 | 更新位姿 | +| `schema` | 否 | object | 用户指定 | 更新 schema | +| `extra` | 否 | object | 用户指定 | 更新扩展数据 | + +> 只传需要更新的字段，未传的字段保持不变。 ## 最终目录结构 diff --git a/.cursor/skills/submit-agent-result/SKILL.md b/.cursor/skills/submit-agent-result/SKILL.md index 18923711..9932e52f 100644 --- a/.cursor/skills/submit-agent-result/SKILL.md +++ b/.cursor/skills/submit-agent-result/SKILL.md @@ -25,14 +25,15 @@ python -c "import base64,sys; print(base64.b64encode(f'{sys.argv[1]}:{sys.argv[2 ### 2. --addr → BASE URL -| `--addr` 值 | BASE | -|-------------|------| -| `test` | `https://uni-lab.test.bohrium.com` | -| `uat` | `https://uni-lab.uat.bohrium.com` | -| `local` | `http://127.0.0.1:48197` | -| 不传（默认） | `https://uni-lab.bohrium.com` | +| `--addr` 值 | BASE | +| ------------ | ----------------------------------- | +| `test` | `https://leap-lab.test.bohrium.com` | +| `uat` | `https://leap-lab.uat.bohrium.com` | +| `local` | `http://127.0.0.1:48197` | +| 不传（默认） | `https://leap-lab.bohrium.com` | 确认后设置： + ```bash BASE="<根据 addr 确定的 URL>" AUTH="Authorization: Lab <上面命令输出的 token>" @@ -45,6 +46,7 @@ AUTH="Authorization: Lab <上面命令输出的 token>" notebook_uuid 来自之前通过「批量提交实验」创建的实验批次，即 `POST /api/v1/lab/notebook` 返回的 `data.uuid`。 如果用户不记得，可提示： + - 查看之前的对话记录中创建 notebook 时返回的 UUID - 或通过平台页面查找对应的 notebook @@ -54,11 +56,11 @@ notebook_uuid 来自之前通过「批量提交实验」创建的实验批次， 用户需要提供实验结果数据，支持以下方式： -| 方式 | 说明 | -|------|------| -| JSON 文件 | 直接作为 `agent_result` 的内容合并 | -| CSV 文件 | 转为 `{"文件名": [行数据...]}` 格式 | -| 手动指定 | 用户直接告知 key-value 数据，由 agent 构建 JSON | +| 方式 | 说明 | +| --------- | ----------------------------------------------- | +| JSON 文件 | 直接作为 `agent_result` 的内容合并 | +| CSV 文件 | 转为 `{"文件名": [行数据...]}` 格式 | +| 手动指定 | 用户直接告知 key-value 数据，由 agent 构建 JSON | **四项全部就绪后才可开始。** @@ -90,7 +92,7 @@ curl -s -X GET "$BASE/api/v1/edge/lab/info" -H "$AUTH" 返回： ```json -{"code": 0, "data": {"uuid": "xxx", "name": "实验室名称"}} +{ "code": 0, "data": { "uuid": "xxx", "name": "实验室名称" } } ``` 记住 `data.uuid` 为 `lab_uuid`。 @@ -121,42 +123,45 @@ curl -s -X PUT "$BASE/api/v1/lab/notebook/agent-result" \ #### 必要字段 -| 字段 | 类型 | 说明 | -|------|------|------| +| 字段 | 类型 | 说明 | +| --------------- | ------------- | ------------------------------------------- | | `notebook_uuid` | string (UUID) | 目标 notebook 的 UUID，从批量提交实验时获取 | -| `agent_result` | object | 实验结果数据，任意 JSON 对象 | +| `agent_result` | object | 实验结果数据，任意 JSON 对象 | #### agent_result 内容格式 `agent_result` 接受**任意 JSON 对象**，常见格式： **简单键值对**： + ```json { - "avg_rtt_ms": 12.5, - "status": "success", - "test_count": 5 + "avg_rtt_ms": 12.5, + "status": "success", + "test_count": 5 } ``` **包含嵌套结构**： + ```json { - "summary": {"total": 100, "passed": 98, "failed": 2}, - "measurements": [ - {"sample_id": "S001", "value": 3.14, "unit": "mg/mL"}, - {"sample_id": "S002", "value": 2.71, "unit": "mg/mL"} - ] + "summary": { "total": 100, "passed": 98, "failed": 2 }, + "measurements": [ + { "sample_id": "S001", "value": 3.14, "unit": "mg/mL" }, + { "sample_id": "S002", "value": 2.71, "unit": "mg/mL" } + ] } ``` **从 CSV 文件导入**（脚本自动转换）： + ```json { - "experiment_data": [ - {"温度": 25, "压力": 101.3, "产率": 0.85}, - {"温度": 30, "压力": 101.3, "产率": 0.91} - ] + "experiment_data": [ + { "温度": 25, "压力": 101.3, "产率": 0.85 }, + { "温度": 30, "压力": 101.3, "产率": 0.91 } + ] } ``` @@ -178,22 +183,22 @@ python scripts/prepare_agent_result.py \ [--output ] ``` -| 参数 | 必选 | 说明 | -|------|------|------| -| `--notebook-uuid` | 是 | 目标 notebook UUID | -| `--files` | 是 | 输入文件路径（支持多个，JSON / CSV） | -| `--auth` | 提交时必选 | Lab token（base64(ak:sk)） | -| `--base` | 提交时必选 | API base URL | -| `--submit` | 否 | 加上此标志则直接提交到云端 | -| `--output` | 否 | 输出 JSON 路径（默认 `agent_result_body.json`） | +| 参数 | 必选 | 说明 | +| ----------------- | ---------- | ----------------------------------------------- | +| `--notebook-uuid` | 是 | 目标 notebook UUID | +| `--files` | 是 | 输入文件路径（支持多个，JSON / CSV） | +| `--auth` | 提交时必选 | Lab token（base64(ak:sk)） | +| `--base` | 提交时必选 | API base URL | +| `--submit` | 否 | 加上此标志则直接提交到云端 | +| `--output` | 否 | 输出 JSON 路径（默认 `agent_result_body.json`） | ### 文件合并规则 -| 文件类型 | 合并方式 | -|----------|----------| -| `.json`（dict） | 字段直接合并到 `agent_result` 顶层 | -| `.json`（list/other） | 以文件名为 key 放入 `agent_result` | -| `.csv` | 以文件名（不含扩展名）为 key，值为行对象数组 | +| 文件类型 | 合并方式 | +| --------------------- | -------------------------------------------- | +| `.json`（dict） | 字段直接合并到 `agent_result` 顶层 | +| `.json`（list/other） | 以文件名为 key 放入 `agent_result` | +| `.csv` | 以文件名（不含扩展名）为 key，值为行对象数组 | 多个文件的字段会合并。JSON dict 中的重复 key 后者覆盖前者。 @@ -210,7 +215,7 @@ python scripts/prepare_agent_result.py \ --notebook-uuid 73c67dca-c8cc-4936-85a0-329106aa7cca \ --files results.json \ --auth YTFmZDlkNGUt... \ - --base https://uni-lab.test.bohrium.com \ + --base https://leap-lab.test.bohrium.com \ --submit ``` diff --git a/unilabos/ros/nodes/base_device_node.py b/unilabos/ros/nodes/base_device_node.py index ca3cdc83..624ec468 100644 --- a/unilabos/ros/nodes/base_device_node.py +++ b/unilabos/ros/nodes/base_device_node.py @@ -606,7 +606,7 @@ class BaseROS2DeviceNode(Node, Generic[T]): for input_well, liquid_type, liquid_volume, liquid_input_slot in zip( input_wells, ADD_LIQUID_TYPE, LIQUID_VOLUME, LIQUID_INPUT_SLOT ): - input_well.set_liquids([(liquid_type, liquid_volume, "uL")]) + input_well.set_liquids([(liquid_type, liquid_volume, "ul")]) final_response["liquid_input_resource_tree"] = ResourceTreeSet.from_plr_resources( input_wells ).dump()