@xtalpi/agentic-lab-skills 0.0.1

package/skills/lab-flow-designer/references/agentic-lab-sdk.md

@@ -0,0 +1,440 @@
+# Agentic Lab SDK
+
+# API 文档
+
+本节为 **`this.context` 门控/SDK 能力**约定。**`process.execute`** 须传入任务数组 **`items`** 与服务根 **`baseURL`**（Rhea 或等价 Process 服务地址）；单次请求的 **path、HTTP 方法** 仍与 Wire 文档一致并由 **SDK 封装**，门控不拼完整 URL。其余常见查询类能力仍以 SDK 封装为主。`items` 单项形状与 **[`rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md)** 中请求体 `items[]` 一项对齐。
+
+## 门控脚本生成约定（flow-package-from-design）
+
+对 **`ticket.list`**、**`process.list`**、**`compound.getStock`**、**`compound.getChemicalRecord`** 等支持 **`limit` / `offset`** 的查询：若流程说明**未**明确要求分页或条数，生成门控脚本时应显式传入 **`limit: 999999`**、**`offset: 0`**，避免引擎默认小页长截断。若流程说明写了分页或「查全部」的**具体数值**，以流程说明为准。
+
+---
+
+## pool.getNext
+
+- **别名**：`context.pool.getNext`
+- **描述**：获取指定门控节点的出口池（返回出口池数组）
+
+```typescript
+interface Pool {
+  id: number;
+  name: string;
+  description: string;
+  schema: {
+    fields: Array<Record<string, any>>;
+  };
+  type: PoolType;
+}
+async function pool.getNext(valveId: number): Promise<Pool[]>
+```
+
+---
+
+## ticket.list
+
+- **别名**：`context.ticket.list`
+- **描述**：按 `ListTicketParams` 筛选并分页返回 **`TicketListResponse`**（`{ list: Ticket[] }`）。业务上取 **`response.list`** 得到 ticket 数组。`limit` **默认 20**、`offset` **默认 0**（以引擎实现为准）。可选组合：`flow_id__in`、`order_id__in`、`pool_id__in`、`status__in`、单条主键 `id`。**`id` 仅筛选一条**；若需按多条主键召回而类型中尚无 `id__in` 等批量字段，以运行环境为准（可分次传入 `id` 调用，或改用 `pool_id__in` + `status__in` 等缩小集合）。
+
+```typescript
+interface ListTicketParams {
+  flow_id__in?: number[];
+  order_id__in?: number[];
+  pool_id__in?: number[]; // 按 pool 筛选
+  status__in?: string[];
+  id?: number; // 按 ticket 筛选（单条主键）
+  limit: number; // 默认为 20
+  offset: number; // 默认为 0
+}
+
+interface Ticket {
+  id: number;
+  flow_id: number;
+  pool_id: number;
+  order_id: number;
+  parent_ticket_id: number;
+  detail: Record<string, any>;
+  status: string;
+  uuid: string;
+  createdAt?: Date | number;
+}
+
+/** `ticket.list` 返回体；列表字段为 `list` */
+interface TicketListResponse {
+  list: Ticket[];
+}
+
+async function ticket.list(
+  params: ListTicketParams,
+): Promise<TicketListResponse>
+```
+
+---
+
+## ticket.update
+
+- **别名**：`context.ticket.update`
+- **描述**：批量更新 ticket
+
+```typescript
+async function ticket.update(tickets: Ticket[]): Promise<void>
+```
+
+---
+
+## ticket.append
+
+- **别名**：`context.ticket.append`
+- **描述**：批量追加 ticket。`status` 未传时由引擎采用默认状态（以实现为准）；`parent_ticket_id` 用于挂接父 ticket，无父子关系时可省略。
+
+```typescript
+enum TicketStatus {
+  Created = 'created',
+  Running = 'running',
+  Finished = 'finished',
+  Failed = 'failed',
+}
+
+interface CreateTicketParams {
+  flow_id: number;
+  pool_id: number;
+  order_id: number;
+  detail: Record<string, any>;
+  status?: TicketStatus | string;
+  parent_ticket_id?: number;
+}
+
+async function ticket.append(tickets: CreateTicketParams[]): Promise<Ticket[]>
+```
+
+---
+
+## process.list
+
+- **别名**：`context.process.list`
+- **描述**：查询 Bluprint process（process/list_process）
+
+```typescript
+interface ListProcessParams {
+  processIds?: string[];   // 按 exp_id 筛选
+  limit: number;           // 默认为20
+  offset: number;          // 默认为0
+}
+
+async function process.list(params: ListProcessParams): Promise<any>
+```
+
+---
+
+## process.execute
+
+- **别名**：`context.process.execute`
+- **描述**：流程说明中需要 **Process 执行 / 设备侧批量提交任务** 时调用。传入 **`items`**（与 Rhea 请求体 **`items` 数组**同形；每项**必填** **`process`（流程模板名）**、**`params`**；**`table_objects`** 等可选字段的拼装须由流程文档写清）及 **`baseURL`**（服务根地址，如 `https://rhea.example.com`）。**path、HTTP 方法** 由 SDK 按 Wire 固定，门控不传。返回数据形如 **`{ results: { … } }`**，具体键名以实现为准。
+
+```typescript
+// baseURL: 服务地址
+// 返回数据形如 { results: { ... } }
+
+/** 单条任务：与 Rhea `items[]` 一项对齐；必填性以 rhea-api/execute_process_batch.md 为准 */
+interface ExecuteProcessItem {
+  exp_name?: string;
+  /** 流程模板名称（流程文档中的 process / process_name） */
+  process: string;
+  priority?: number;
+  /** 流程参数，键值以流程文档为准 */
+  params: Record<string, unknown>;
+  /** 表对象，如 `{ 表名: { id: value } }`，以流程文档为准；无表绑定时可省略 */
+  table_objects?: Record<string, Record<string, unknown>>;
+}
+
+/** 典型成功响应；`results` 内字段以实现为准（如 `exp_id_list`） */
+interface ExecuteProcessResult {
+  results?: {
+    exp_id_list?: string[];
+    [key: string]: unknown;
+  };
+}
+
+async function process.execute(
+  items: ExecuteProcessItem[],
+  baseURL: string,
+): Promise<ExecuteProcessResult>
+```
+
+- **Wire 与实现参考**（供 SDK 实现者）：URL 路径、方法、示例请求体见 [rhea-api/execute_process_batch.md](rhea-api/execute_process_batch.md)。  
+- **流程文档侧**：写明**何时调用**、**`baseURL` 语义来源**（配置键、环境变量名、或 ticket/订单字段等，由集成解析为字符串 URL）、每条 **`process`**、**`params` 键与取值来源**；若需表绑定再写 **`table_objects`**。**不要求**写 path / HTTP 方法。生成 `valves/*.md` 与 `scripts/*.js` 须能追溯到上述说明；脚本调用形态为 **`this.context.process.execute(items, baseURL)`**。
+
+---
+
+## station.list
+
+- **别名**：`context.station.list`
+- **描述**：列出所有工站
+
+```typescript
+async function station.list(): Promise<Station[]>
+```
+
+---
+
+## compound.getStock
+
+- **别名**：`context.compound.getStock`
+- **描述**：按 NocoBase Repository 风格的 **`filter`** 查询化合物库 **库存/瓶位**（collection 如 `compound`）。`filter` 支持 `$eq`、`$in`、`$and`、`$or` 等算子，字段名与库一致，便于流程自定义任意组合条件。算子说明见 NocoBase 文档：[Filter Operators](https://docs.nocobase.com/api/database/operators)。
+
+```typescript
+/**
+ * NocoBase `Repository.find` / `findOne` / `count` 等方法的 `filter` 参数形状（`$eq`、`$in`、`$and`、`$or` 等）。
+ * 官方算子列表：<https://docs.nocobase.com/api/database/operators>
+ */
+type NocoBaseFilter = Record<string, unknown>;
+
+/** 查询参数：以 `filter` 表达条件（空对象是否合法以实现为准，建议至少包含一条有效条件）。 */
+interface GetCompoundStockParams {
+  /**
+   * 作用于库存 collection 的筛选；键为库字段名，例如：
+   * - `{ cmpd_id: { $in: ['CA1078', 'CA1079'] } }`（批量化合物编号）
+   * - `{ cas: { $in: ['28022-43-7'] } }`（按 CAS）
+   * - `{ $or: [{ cmpd_id: 'CA1' }, { barcode: { $startsWith: 'BC' } }] }`
+   */
+  filter: NocoBaseFilter;
+  /** 最大返回条数；默认以实现为准 */
+  limit?: number;
+  /** 分页偏移；默认以实现为准 */
+  offset?: number;
+}
+
+/**
+ * 嵌套：项目（`project` 关联对象，节选）
+ * 注释体例：库字段 `name`；别名：`uiSchema.title`；备注：`description`
+ */
+interface CompoundStockProjectRef {
+  /** 库字段 `id`；别名：id；备注：关联主键 */
+  id: number;
+  /** 库字段 `createdAt`；别名：Created at；备注：无 */
+  createdAt?: string;
+  /** 库字段 `updatedAt`；别名：Last updated at；备注：无 */
+  updatedAt?: string;
+  /** 库字段 `project_code`；别名：项目编码；备注：以运行时为准 */
+  project_code?: string;
+  /** 库字段 `project_name`；别名：项目名称；备注：以运行时为准 */
+  project_name?: string;
+  /** 库字段 `project_link`；别名：项目链接；备注：以运行时为准 */
+  project_link?: string;
+  /** 库字段 `is_sync`；别名：是否同步；备注：以运行时为准 */
+  is_sync?: boolean;
+  /** 库字段 `createdById`；别名：Created by；备注：外键 users */
+  createdById?: number | null;
+  /** 库字段 `updatedById`；别名：Last updated by；备注：外键 users */
+  updatedById?: number | null;
+}
+
+/**
+ * 嵌套：账户（`account` 关联对象，节选）
+ */
+interface CompoundStockAccountRef {
+  /** 库字段 `id`；别名：id；备注：关联主键 */
+  id: number;
+  createdAt?: string;
+  updatedAt?: string;
+  /** 库字段 `account`；别名：Account；备注：账户编码等 */
+  account?: string;
+  /** 库字段 `name`；别名：name；备注：账户名称 */
+  name?: string;
+  createdById?: number | null;
+  updatedById?: number | null;
+}
+
+/**
+ * 嵌套：品类（`category` 关联对象，节选）
+ */
+interface CompoundStockCategoryRef {
+  /** 库字段 `id`；别名：id；备注：关联主键 */
+  id: number;
+  createdAt?: string;
+  updatedAt?: string;
+  /** 库字段 `status`；别名：状态；备注：以运行时为准 */
+  status?: string;
+  /** 库字段 `category_name`；别名：Category Name；备注：品类名称 */
+  category_name?: string;
+  createdById?: number | null;
+  updatedById?: number | null;
+}
+
+/**
+ * 嵌套：最近申领人（`latest_request_user` 关联对象，节选）
+ * 对应 compound 上 `latest_request_user` 关联，`foreignKey` 为 `f_latest_request_user`
+ */
+interface CompoundStockUserRef {
+  id: number;
+  createdAt?: string;
+  updatedAt?: string;
+  nickname?: string;
+  username?: string;
+  email?: string | null;
+  phone?: string | null;
+  passwordChangeTz?: string | null;
+  appLang?: string | null;
+  systemSettings?: Record<string, unknown>;
+  createdById?: number | null;
+  updatedById?: number | null;
+}
+
+/**
+ * 单条 compound 库存/瓶记录（与 collection `compound` 及典型 API 返回对齐）
+ * 字段注释：`name` = 接口/库字段 key；**别名** = `uiSchema.title`（含 i18n 模板时已展开为可读文案）；**备注** = `description`（无则写「无」）
+ * 时间字段一般为 ISO8601 字符串
+ */
+interface CompoundStockRecord {
+  /** 库字段 `id`；别名：ID；备注：无 */
+  id: number;
+  /** 库字段 `createdAt`；别名：Created at；备注：无 */
+  createdAt: string;
+  /** 库字段 `updatedAt`；别名：Last updated at；备注：无 */
+  updatedAt: string;
+  /** 库字段 `initial_checkin_time`；别名：Initial Check-in Time；备注：第一次进入系统的时间 */
+  initial_checkin_time?: string;
+  /** 库字段 `latest_checkin_time`；别名：Latest Check-in Time；备注：最近一次Check-in时间 */
+  latest_checkin_time?: string;
+  /** 库字段 `latest_checkout_time`；别名：Latest Check-out Time；备注：最近一次Check-out时间 */
+  latest_checkout_time?: string | null;
+  /** 库字段 `cas`；别名：CAS；备注：无 */
+  cas: string;
+  /** 库字段 `po_num`；别名：PO Num；备注：无 */
+  po_num?: string;
+  /** 库字段 `f_account`；别名：f_account；备注：外键 → account（化合物关联的客户） */
+  f_account?: number;
+  /** 库字段 `f_project`；别名：f_project；备注：外键 → project（化合物关联的项目） */
+  f_project?: number;
+  /** 库字段 `source`；别名：Source；备注：BB来源的供应商 */
+  source?: string;
+  /** 库字段 `barcode`；别名：Barcode；备注：全局唯一 */
+  barcode: string;
+  /** 库字段 `cmpd_id`；别名：CMPD-ID；备注：对应于自主实验室申请的Compound ID，示例：CA1078 */
+  cmpd_id: string;
+  /** 库字段 `owner`；别名：Owner；备注：化合物的归属人，邮箱 */
+  owner?: string;
+  /** 库字段 `f_category`；别名：f_category；备注：外键 → category（化合物种类） */
+  f_category?: number;
+  /** 库字段 `hazard_class_adr`；别名：HazardClassAdr；备注：危险品等级 */
+  hazard_class_adr?: string | null;
+  /** 库字段 `odor`；别名：Odor；备注：气味 */
+  odor?: string;
+  /** 库字段 `initial_amount`；别名：Initial Amount；备注：第一次进入系统的原料重量（新瓶子），单位mg */
+  initial_amount?: number;
+  /** 库字段 `initial_weight`；别名：Initial Weight；备注：第一次进入系统的瓶子重量（新瓶子），单位g */
+  initial_weight?: number;
+  /** 库字段 `latest_weight`；别名：Latest Weight；备注：当前瓶重，每一次重新回到系统后更新，单位g */
+  latest_weight?: number;
+  /** 库字段 `latest_amount_mg`；别名：Latest Amount(mg)；备注：原料的当前实际重量，每次Check-in时重新计算 */
+  latest_amount_mg?: number;
+  /** 库字段 `latest_amount_ml`；别名：Latest Amount(mL)；备注：当前实际重量，单位mL，手填 */
+  latest_amount_ml?: number | null;
+  /** 库字段 `latest_location`；别名：Latest Location；备注：当前位置 */
+  latest_location?: string;
+  /** 库字段 `location_detail`；别名：Location Detail；备注：详细位置信息 */
+  location_detail?: Record<string, unknown>;
+  /** 库字段 `f_latest_request_user`；别名：f_latest_request_user；备注：外键 → users（申请出库使用者） */
+  f_latest_request_user?: number;
+  /** 库字段 `status`；别名：Status；备注：无（可选值如：可用、已预约、已出库、已核销） */
+  status?: string;
+  /** 库字段 `checkin_user`；别名：Check-in User；备注：初始入库用户的邮箱, 由orbit提交 */
+  checkin_user?: string;
+  /** 库字段 `checkout_user`；别名：Check-out User；备注：出库用户的邮箱, 由orbit提交 */
+  checkout_user?: string;
+  /** 库字段 `chemical_name`；别名：Chemical Name；备注：无 */
+  chemical_name?: string | null;
+  /** 库字段 `createdById`；别名：Created by（外键）；备注：无 */
+  createdById?: number | null;
+  /** 库字段 `updatedById`；别名：Last updated by（外键）；备注：无 */
+  updatedById?: number | null;
+  /** 库字段 `project`（关联）；别名：Project；备注：化合物关联的项目 */
+  project?: CompoundStockProjectRef;
+  /** 库字段 `account`（关联）；别名：Account；备注：化合物关联的客户 */
+  account?: CompoundStockAccountRef;
+  /** 库字段 `category`（关联）；别名：Category；备注：化合物种类 */
+  category?: CompoundStockCategoryRef;
+  /** 库字段 `latest_request_user`（关联）；别名：Latest Request User；备注：申请出库使用者 */
+  latest_request_user?: CompoundStockUserRef;
+}
+
+async function compound.getStock(
+  params: GetCompoundStockParams
+): Promise<CompoundStockRecord[]>
+```
+
+---
+
+## compound.getChemicalRecord
+
+- **别名**：`context.compound.getChemicalRecord`
+- **描述**：按 NocoBase **`filter`** 查询 **化合物知识库** `chemical_record`（可分装性、化性状、备注等），与库存 `compound.getStock` 区分；算子与 `GetCompoundStockParams.filter` 相同，见 [Filter Operators](https://docs.nocobase.com/api/database/operators)。
+
+```typescript
+type NocoBaseFilter = Record<string, unknown>;
+
+/** 查询参数：以 `filter` 描述对 `chemical_record` 的筛选。 */
+interface GetChemicalRecordParams {
+  /**
+   * 示例：`{ cmpd_id: { $in: ['CA1078'] } }`；
+   * `{ compound_id: { $in: ['28022-43-7'] } }`（业务将 CAS 存于 `compound_id` 时）；
+   * `{ dispensable: { $isTruly: true } }`（布尔字段算子见 NocoBase 文档）。
+   */
+  filter: NocoBaseFilter;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * 单条 `chemical_record` 化合物知识库记录（与 collection 元数据及典型 API 返回对齐）
+ * 字段注释：库字段 `name`；**别名** = `uiSchema.title`；**备注** = `description`（无则写「无」）
+ */
+interface ChemicalRecord {
+  /** 库字段 `id`；别名：ID；备注：无 */
+  id: number;
+  /** 库字段 `createdAt`；别名：Created at；备注：无 */
+  createdAt: string;
+  /** 库字段 `updatedAt`；别名：Last updated at；备注：无 */
+  updatedAt: string;
+  /** 库字段 `compound_id`；别名：Compound ID (CAS#)；备注：无 */
+  compound_id: string;
+  /** 库字段 `cmpd_id`；别名：CMPD-ID；备注：无 */
+  cmpd_id: string;
+  /** 库字段 `business_type`；别名：Business Type；备注：无（可选值如：Fragment、VAST、D2B） */
+  business_type?: string;
+  /** 库字段 `chemist_property`；别名：Chemist Property；备注：性状（Chemist） */
+  chemist_property?: string[];
+  /** 库字段 `dispensable`；别名：Dispensable；备注：可分装判断（Chemist） */
+  dispensable: boolean;
+  /** 库字段 `dispensing_remark`；别名：Dispensing Remark；备注：不可分装备注（Chemist） */
+  dispensing_remark?: string[];
+  /** 库字段 `large_particle`；别名：Large Particle；备注：固体颗粒过大（Large Particle） */
+  large_particle?: boolean | null;
+  /**
+   * 库字段 `poor_flowability`；别名：Poor Flowability；备注：流动性差（Poor Flowability）
+   * 库类型为 string；若历史数据为 boolean，以实现为准
+   */
+  poor_flowability?: string | null;
+  /** 库字段 `hygroscopicity`；别名：Hygroscopicity；备注：强吸水性（Hygroscopicity） */
+  hygroscopicity?: boolean | null;
+  /** 库字段 `agglomeration_tendency`；别名：Agglomeration Tendency；备注：易结块（Agglomeration Tendency） */
+  agglomeration_tendency?: boolean | null;
+  /** 库字段 `sticky`；别名：Sticky；备注：易粘黏（Sticky） */
+  sticky?: boolean | null;
+  /** 库字段 `strong_electrostatic_adsorption`；别名：Strong Electrostatic Adsorption；备注：强静电吸附（Strong Electrostatic Adsorption） */
+  strong_electrostatic_adsorption?: boolean | null;
+  /** 库字段 `remark`；别名：Remark；备注：无（schema 默认文案见数据源配置） */
+  remark?: string;
+  /** 库字段 `duplicate_check`；别名：Duplicate Check；备注：重复判断 */
+  duplicate_check?: string;
+  /** 库字段 `lark_record_id`；别名：Lark Record ID；备注：无 */
+  lark_record_id?: string;
+  /** 库字段 `createdById`；别名：Created by（外键）；备注：无 */
+  createdById?: number | null;
+  /** 库字段 `updatedById`；别名：Last updated by（外键）；备注：无 */
+  updatedById?: number | null;
+}
+
+async function compound.getChemicalRecord(
+  params: GetChemicalRecordParams
+): Promise<ChemicalRecord[]>
+```

package/skills/lab-flow-designer/references/rhea-api/README.md

@@ -0,0 +1,7 @@
+# Rhea HTTP 参考（补充）
+
+本目录为 **Rhea 等服务端点** 的 Wire 级说明，供 **SDK 实现与预检对照**；[`../agentic-lab-sdk.md`](../agentic-lab-sdk.md) 中的 **`process.execute`** 由门控传入 **`items`** 与 **`baseURL`**（服务根），**path、HTTP 方法** 仍由 SDK 按本目录文档固定封装。
+
+| 文件 | 说明 |
+|------|------|
+| [execute_process_batch.md](execute_process_batch.md) | `execute_process_batch`：URL、请求体 `items` / `process` / `params` / `table_objects`、响应 `exp_id_list` 等 |

package/skills/lab-flow-designer/references/rhea-api/execute_process_batch.md

@@ -0,0 +1,58 @@
+| 批量提交任务 |                                                           |
+| ------ | --------------------------------------------------------- |
+| url    | http://127.0.0.1:8080/api/process/execute\_process\_batch |
+| 方法     | post                                                      |
+
+## **参数**
+
+| 参数名称              | 参数说明       | 参数类型 | 是否必填          | 示例                                      |
+|----------------------|--------------|----------|-------------------|------------------------------------------|
+| items                | 耗材属性<br>list<br>必填 | list     | 是                | -                                        |
+| ├─ exp_name          | 实验名称       | string   | 否                |                                          |
+| ├─ process           | 流程模板名称     | string   | 是                | "One_to_one"                             |
+| ├─ priority          | 流程优先级     | int      | 否，默认为2，数值越高，优先级越高 |                                          |
+| ├─ params            | 流程参数       | dict     | 是                | 如下所示（JSON）：<br>{<br>&nbsp;&nbsp;"@spoon_calib": "",<br>&nbsp;&nbsp;"@second_spoon_calib": "calib",<br>&nbsp;&nbsp;"@calib_retry_times": 0,<br>&nbsp;&nbsp;"@setting_calib_retry_times": 3,<br>&nbsp;&nbsp;"@add_times": 0<br>} |
+| └─ table_objects     | 表对象         | dict     | 否（可选）         | {表名: {id: value}}；无表绑定时可省略或 `{}` |
+
+```python
+url = f"{base_url}/process/execute_process_batch"
+# process_name = "One_to_more"
+process_name = "workflow_demo_s1"
+
+data = {
+    "items": [
+        {
+            "exp_name": "",
+            "process": process_name,
+            "params": {
+                "@spoon_calib": False,
+                "@second_spoon_calib": True,
+                "@calib_retry_times": 0,
+                "@setting_calib_retry_times": 3,
+                "@add_times": 0},
+            "table_objects": {}
+        },
+        {
+            "exp_name": "",
+            "process": process_name,
+            "params": {
+                "@spoon_calib": False,
+                "@second_spoon_calib": True,
+                "@calib_retry_times": 0,
+                "@setting_calib_retry_times": 3,
+                "@add_times": 0},
+            "table_objects": {}
+        },
+    ]
+}
+
+response = requests.post(url, json=data)
+print(response)
+print(response.json())
+```
+
+## **返回值**
+
+| 参数名称   | 参数说明           | 参数类型 | 示例 |
+|------------|-------------------|----------|------|
+| results    | 批量提交任务的exp_id | json     | {<br>&nbsp;&nbsp;"results": {<br>&nbsp;&nbsp;&nbsp;&nbsp;"exp_id_list": [<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"86cc6fcc-6066-48be-a87a-66f5c370bba5",<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"6c0719d1-cee8-49ed-bdd5-4c89d83c03da"<br>&nbsp;&nbsp;&nbsp;&nbsp;]<br>&nbsp;&nbsp;}<br>} |