@xtalpi/agentic-lab-skills 0.0.9 → 0.0.11

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

@@ -1,361 +1,534 @@
-# 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[]` 一项对齐。
-
-## 门控脚本生成约定（lab-flow-designer）
-
-对 **`ticket.list`**、**`process.list`** 等支持 **`limit` / `offset`** 的查询：若流程说明**未**明确要求分页或条数，生成门控脚本时应显式传入 **`limit: 999999`**、**`offset: 0`**，避免引擎默认小页长截断。若流程说明写了分页或「查全部」的**具体数值**，以流程说明为准。
-
-> **`compound.getStockFromXfcSh`** 使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值。
-
----
-
-## 可用方法一览
-
-| 方法 | 命名空间 | 用途 | 分页方式 |
-|------|----------|------|----------|
-| `pool.getNext(valveId)` | `context.pool` | 获取指定门控的出口池数组 | 无 |
-| `ticket.list(params)` | `context.ticket` | 按条件筛选并分页返回 ticket 列表 | `limit` / `offset` |
-| `ticket.update(tickets)` | `context.ticket` | 批量更新 ticket | 无 |
-| `ticket.append(tickets)` | `context.ticket` | 批量追加 ticket | 无 |
-| `process.list(params)` | `context.process` | 查询 process 列表 | `limit` / `offset` |
-| `process.execute(items, baseURL)` | `context.process` | 批量提交 Process 执行任务 | 无 |
-| `station.list()` | `context.station` | 列出所有工站 | 无 |
-| `compound.getStockFromXfcSh(params)` | `context.compound` | 获取 XFC 上海化合物库存 | `pageSize` / `page` |
-| `agent.chat(params)` | `context.agent` | 调用外部 Agent（流式/非流式），返回文本或解析后的 JSON | 无 |
-
-> 生成「核心概念」中的 `this.context` 能力列表时，从本表选取流程实际使用的方法即可。各方法的完整签名、参数类型与返回类型见下文各节。
-
----
-
-## 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.getStockFromXfcSh
-
-- **别名**：`context.compound.getStockFromXfcSh`
-- **描述**：获取 XFC 上海系统化合物库存。使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值（默认 `pageSize: 400`、`page: 1`）。
-
-```typescript
-interface StockFromXfcShParams {
-  filter?: Record<string, any>;
-  fields?: string[] | string;
-  pageSize?: number;
-  page?: number;
-  [propName: string]: any;
-}
-
-async function compound.getStockFromXfcSh(
-  params?: StockFromXfcShParams
-): Promise<CompoundResponse>
-```
-
-### 参数说明
-
-| 参数名 | 含义 | 备注 |
-|--------|------|------|
-| `filter` | 筛选条件 | 查询化合物常用 `cas`、`cmpd_id`；**不传时默认筛选 `'status': '可用'`**。使用 **dot-notation** 格式（如 `'cas.$in': [...]`），**非**嵌套对象格式 |
-| `fields` | 查询返回的字段 | **默认返回字段（不传时）**：`id, cas, status, source, barcode, cmpd_id, owner`。**全部可用字段**：`barcode, cas, cmpd_id, po_num, source, owner, hazard_class_adr, odor, initial_weight, initial_amount, initial_checkin_time, latest_weight, latest_amount_mg, latest_amount_ml, latest_checkin_time, latest_checkout_time, latest_location, location_detail, checkin_user, status, checkout_user, chemical_name`。**外键**：`f_category, f_account, f_latest_request_user, f_project` |
-| `pageSize` | 分页大小 | 默认 `400` |
-| `page` | 页码 | 默认 `1` |
-
-### 调用示例
-
-```javascript
-const xfcStockSH = await this.context.compound.getStockFromXfcSh({
-  filter: {
-    'cas.$in': ['1065657-51-3']
-  }
-});
-// xfcStockSH.data → 数据数组
-// xfcStockSH.meta → 分页信息
-```
-
-### 返回类型
-
-```typescript
-interface CompoundItem {
-  id: number;
-  cas: string;
-  status: string;
-  source: string;
-  barcode: string;
-  cmpd_id: string;
-  owner: string;
-}
-
-interface CompoundMeta {
-  count: number;
-  page: number;
-  pageSize: number;
-  totalPage: number;
-}
-
-interface CompoundResponse {
-  data: CompoundItem[];
-  meta: CompoundMeta;
-}
-```
-
-### 返回数据示例
-
-```json
-{
-  "data": [
-    {
-      "id": 151,
-      "cas": "1065657-51-3",
-      "status": "可用",
-      "source": "上海锐谱医药科技有限公司",
-      "barcode": "XFC25103100049",
-      "cmpd_id": "BA0062",
-      "owner": "张琳"
-    },
-    {
-      "id": 6613,
-      "cas": "1065657-51-3",
-      "status": "可用",
-      "source": "上海锐谱医药科技有限公司",
-      "barcode": "XFC25121900056",
-      "cmpd_id": "BA0062",
-      "owner": "张琳"
-    }
-  ],
-  "meta": { "count": 2, "page": 1, "pageSize": 400, "totalPage": 1 }
-}
-```
-
----
-
-## agent.chat
-
-- **别名**：`context.agent.chat`
-- **描述**：调用外部 Agent 服务。SDK 负责发起请求、消费流式（SSE / NDJSON）或普通 JSON 响应，并将各 chunk 的 `content` 拼接为完整文本。`url`、`query` **必填**。`parseJson: true` 时从返回文本中提取并解析 JSON（支持 Markdown 代码块与多段 JSON 合并）；解析成功返回 object / array，失败返回 `null`。未开启 `parseJson` 时返回原始字符串。请求失败抛出以 `agent.chat:` 为前缀的错误。
-
-```typescript
-interface ChatAgentParams {
-  /** Agent 服务完整 URL（必填） */
-  url: string; // Agent 服务完整 URL（必填
-  /** 用户查询文本（必填；非空字符串） */
-  query: string;
-  /**
-   * true：从返回文本提取并解析 JSON，成功返回 object/array，失败返回 null；
-   * 未传或 false：返回拼接后的原始 string
-   */
-  parseJson?: boolean;
-  [propName: string]: any;
-}
-
-/**
- * parseJson 未开启：Promise<string>
- * parseJson 开启且解析成功：Promise<object | any[]>
- * parseJson 开启且解析失败：Promise<null>
- */
-async function agent.chat(params: ChatAgentParams): Promise<string | object | any[] | null>
-```
-
-### 参数说明
-
-| 参数名 | 含义 | 备注 |
-|--------|------|------|
-| `url` | Agent 服务完整 URL | **必填**；空字符串会抛错 |
-| `query` | 用户查询文本 | **必填**；空字符串会抛错 |
-| `parseJson` | 是否解析返回 JSON | 默认不解析，返回拼接后的 string。为 `true` 时尝试从正文或 markdown 的 json 代码块中提取 JSON；多段合法 JSON 合并为数组；失败返回 `null`（不抛错） |
-
-### 调用示例
-
-```javascript
-// 返回原始文本
-const text = await this.context.agent.chat({
-  url: agentUrl,
-  query: '请根据以下实验数据给出结论：...',
-});
-
-// 期望 Agent 返回 JSON，解析失败时得到 null
-const result = await this.context.agent.chat({
-  url: agentUrl,
-  query: prompt,
-  parseJson: true
-});
-if (result == null) {
-  throw new Error('agent.chat: failed to parse JSON from response');
-}
-```
-
-### 返回说明
-
-| 场景 | 返回值 |
-|------|--------|
-| `parseJson` 未开启 / 为 `false` | `string`：流式各 chunk `content` 的拼接结果 |
-| `parseJson: true` 且解析成功 | `object` 或 `any[]` |
-| `parseJson: true` 且解析失败 | `null` |
-| 请求 / 流读取失败 | 抛出 `Error`，消息以 `agent.chat:` 为前缀 |
-
-### 请求体要点（SDK 封装，门控不必手拼）
-
-SDK 向 `url` 发送的 JSON 主体主要包括：`query`、`messages`、`context_link`、`message_id`、`response_mode`、`agent_params_global`、`user_info`、`skills`。Header 使用 `Authorization: Bearer <api_key>`。门控脚本侧只需组装 `ChatAgentParams` 并调用 **`this.context.agent.chat(params)`**。
+# 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[]` 一项对齐。
+
+## 门控脚本生成约定（lab-flow-designer）
+
+对 **`ticket.list`**、**`process.list`** 等支持 **`limit` / `offset`** 的查询：若流程说明**未**明确要求分页或条数，生成门控脚本时应显式传入 **`limit: 999999`**、**`offset: 0`**，避免引擎默认小页长截断。若流程说明写了分页或「查全部」的**具体数值**，以流程说明为准。
+
+> **`compound.getStockFromXfcSh`** 使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值。
+
+---
+
+## 可用方法一览
+
+| 方法 | 命名空间 | 用途 | 分页方式 |
+|------|----------|------|----------|
+| `pool.getNext(valveId)` | `context.pool` | 获取指定门控的出口池数组 | 无 |
+| `ticket.list(params)` | `context.ticket` | 按条件筛选并分页返回 ticket 列表 | `limit` / `offset` |
+| `ticket.update(tickets)` | `context.ticket` | 批量更新 ticket | 无 |
+| `ticket.append(tickets)` | `context.ticket` | 批量追加 ticket | 无 |
+| `process.list(params)` | `context.process` | 查询 process 列表 | `limit` / `offset` |
+| `process.execute(items, baseURL)` | `context.process` | 批量提交 Process 执行任务 | 无 |
+| `station.list()` | `context.station` | 列出所有工站 | 无 |
+| `compound.getStockFromXfcSh(params)` | `context.compound` | 获取 XFC 上海化合物库存 | `pageSize` / `page` |
+| `agent.chat(params)` | `context.agent` | 调用外部 Agent（流式/非流式），返回文本或解析后的 JSON | 无 |
+
+> 生成「核心概念」中的 `this.context` 能力列表时，从本表选取流程实际使用的方法即可。各方法的完整签名、参数类型与返回类型见下文各节。
+
+---
+
+## 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.getStockFromXfcSh
+
+- **别名**：`context.compound.getStockFromXfcSh`
+- **描述**：获取 XFC 上海系统化合物库存。使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值（默认 `pageSize: 400`、`page: 1`）。
+
+```typescript
+interface StockFromXfcShParams {
+  filter?: Record<string, any>;
+  fields?: string[] | string;
+  pageSize?: number;
+  page?: number;
+  [propName: string]: any;
+}
+
+async function compound.getStockFromXfcSh(
+  params?: StockFromXfcShParams
+): Promise<CompoundResponse>
+```
+
+### 参数说明
+
+| 参数名 | 含义 | 备注 |
+|--------|------|------|
+| `filter` | 筛选条件 | 查询化合物常用 `cas`、`cmpd_id`；**不传时默认筛选 `'status': '可用'`**。使用 **dot-notation** 格式（如 `'cas.$in': [...]`），**非**嵌套对象格式 |
+| `fields` | 查询返回的字段 | **默认返回字段（不传时）**：`id, cas, status, source, barcode, cmpd_id, owner`。**全部可用字段**：`barcode, cas, cmpd_id, po_num, source, owner, hazard_class_adr, odor, initial_weight, initial_amount, initial_checkin_time, latest_weight, latest_amount_mg, latest_amount_ml, latest_checkin_time, latest_checkout_time, latest_location, location_detail, checkin_user, status, checkout_user, chemical_name`。**外键**：`f_category, f_account, f_latest_request_user, f_project` |
+| `pageSize` | 分页大小 | 默认 `400` |
+| `page` | 页码 | 默认 `1` |
+
+### 调用示例
+
+```javascript
+const xfcStockSH = await this.context.compound.getStockFromXfcSh({
+  filter: {
+    'cas.$in': ['1065657-51-3']
+  }
+});
+// xfcStockSH.data → 数据数组
+// xfcStockSH.meta → 分页信息
+```
+
+### 返回类型
+
+```typescript
+interface CompoundItem {
+  id: number;
+  cas: string;
+  status: string;
+  source: string;
+  barcode: string;
+  cmpd_id: string;
+  owner: string;
+}
+
+interface CompoundMeta {
+  count: number;
+  page: number;
+  pageSize: number;
+  totalPage: number;
+}
+
+interface CompoundResponse {
+  data: CompoundItem[];
+  meta: CompoundMeta;
+}
+```
+
+### 返回数据示例
+
+```json
+{
+  "data": [
+    {
+      "id": 151,
+      "cas": "1065657-51-3",
+      "status": "可用",
+      "source": "上海锐谱医药科技有限公司",
+      "barcode": "XFC25103100049",
+      "cmpd_id": "BA0062",
+      "owner": "张琳"
+    },
+    {
+      "id": 6613,
+      "cas": "1065657-51-3",
+      "status": "可用",
+      "source": "上海锐谱医药科技有限公司",
+      "barcode": "XFC25121900056",
+      "cmpd_id": "BA0062",
+      "owner": "张琳"
+    }
+  ],
+  "meta": { "count": 2, "page": 1, "pageSize": 400, "totalPage": 1 }
+}
+```
+
+---
+
+## agent.chat
+
+- **别名**：`context.agent.chat`
+- **描述**：调用外部 Agent 服务。SDK 负责发起请求、消费流式（SSE / NDJSON）或普通 JSON 响应，并将各 chunk 的 `content` 拼接为完整文本。`url`、`query` **必填**。`parseJson: true` 时从返回文本中提取并解析 JSON（支持 Markdown 代码块与多段 JSON 合并）；解析成功返回 object / array，失败返回 `null`。未开启 `parseJson` 时返回原始字符串。请求失败抛出以 `agent.chat:` 为前缀的错误。
+
+```typescript
+interface ChatAgentParams {
+  /** Agent 服务完整 URL（必填） */
+  url: string; // Agent 服务完整 URL（必填
+  /** 用户查询文本（必填；非空字符串） */
+  query: string;
+  /**
+   * true：从返回文本提取并解析 JSON，成功返回 object/array，失败返回 null；
+   * 未传或 false：返回拼接后的原始 string
+   */
+  parseJson?: boolean;
+  [propName: string]: any;
+}
+
+/**
+ * parseJson 未开启：Promise<string>
+ * parseJson 开启且解析成功：Promise<object | any[]>
+ * parseJson 开启且解析失败：Promise<null>
+ */
+async function agent.chat(params: ChatAgentParams): Promise<string | object | any[] | null>
+```
+
+### 参数说明
+
+| 参数名 | 含义 | 备注 |
+|--------|------|------|
+| `url` | Agent 服务完整 URL | **必填**；空字符串会抛错 |
+| `query` | 用户查询文本 | **必填**；空字符串会抛错 |
+| `parseJson` | 是否解析返回 JSON | 默认不解析，返回拼接后的 string。为 `true` 时尝试从正文或 markdown 的 json 代码块中提取 JSON；多段合法 JSON 合并为数组；失败返回 `null`（不抛错） |
+
+### 调用示例
+
+```javascript
+// 返回原始文本
+const text = await this.context.agent.chat({
+  url: agentUrl,
+  query: '请根据以下实验数据给出结论：...',
+});
+
+// 期望 Agent 返回 JSON，解析失败时得到 null
+const result = await this.context.agent.chat({
+  url: agentUrl,
+  query: prompt,
+  parseJson: true
+});
+if (result == null) {
+  throw new Error('agent.chat: failed to parse JSON from response');
+}
+```
+
+### 返回说明
+
+| 场景 | 返回值 |
+|------|--------|
+| `parseJson` 未开启 / 为 `false` | `string`：流式各 chunk `content` 的拼接结果 |
+| `parseJson: true` 且解析成功 | `object` 或 `any[]` |
+| `parseJson: true` 且解析失败 | `null` |
+| 请求 / 流读取失败 | 抛出 `Error`，消息以 `agent.chat:` 为前缀 |
+
+### 请求体要点（SDK 封装，门控不必手拼）
+
+SDK 向 `url` 发送的 JSON 主体主要包括：`query`、`messages`、`context_link`、`message_id`、`response_mode`、`agent_params_global`、`user_info`、`skills`。Header 使用 `Authorization: Bearer <api_key>`。门控脚本侧只需组装 `ChatAgentParams` 并调用 **`this.context.agent.chat(params)`**。
+
+
+
+## compound.returnCmpdToXfcSh
+
+- **别名**：`context.compound.returnCmpdToXfcSh`
+- **描述**：执行 XFC 上海系统化合物批量退库功能。通过传入需要批量退库的化合物数组（包含化合物barcode、剩余重量、退库位置）以及可选参数（如执行退库人），执行业务的批量退库功能，并返回完成退库的化合物信息数组。
+
+```typescript
+interface ReturnCmpdToXfcShItem {
+  barcode: string;
+  latest_weight: number;
+  location: string;
+}
+
+interface ReturnCmpdToXfcShOptions {
+  submit_user?: string;
+}
+
+interface ReturnCmpdToXfcShParams {
+  items: ReturnCmpdToXfcShItem[];
+  options?: ReturnCmpdToXfcShOptions;
+}
+
+```
+
+### 参数说明
+
+| 参数名  | 含义           | 是否必填 | 示例                                                         |
+| :------ | :------------- | :------- | :----------------------------------------------------------- |
+| items   | 退库化合物列表 | 是       | `[  {    barcode: 'XFC26071300041',    latest_weight: 1, // 单位为g，退库重量（含瓶身）    location: 'KWA-R00-L0-A00', // 注意：此location必须是位置映射表中存在的库外位置  },  {    barcode: 'XFC26071300042',    latest_weight: 1,    location: 'KWA-R00-L0-A00',  } ]` |
+| options | 可选参数       | 否       | `{     submit_user: 'shuyan.wang' // 退库check in单提交人，默认为lab }` |
+
+
+
+### 调用示例
+
+```javascript
+const res = await sdk.compound.returnCmpdToXfcSh([
+    {
+        barcode: 'XFC26071300031',
+        latest_weight: 2,
+        location: 'KWA-R00-L0-A00',
+    },
+    {
+        barcode: 'XFC26071300032',
+        latest_weight: 0.1,
+        location: 'KWA-R00-L0-A00',
+    },
+    {
+        barcode: 'XFC26071300033',
+        latest_weight: 0.5,
+        location: 'KWA-R00-L0-A00',
+    },
+], { submit_user: 'shuyan.wang' })
+// res → 完成退库的化合物数据数组
+```
+
+
+
+### 返回类型
+
+```typescript
+interface CmpdItem {
+  createdAt: string;
+  updatedAt: string;
+  initial_checkin_time: string;
+  latest_checkin_time: string;
+  latest_checkout_time: string | null;
+  id: number;
+  cas: string | null;
+  po_num: string | null;
+  f_account: number;
+  f_project: number;
+  source: string;
+  barcode: string;
+  cmpd_id: string;
+  owner: string;
+  f_category: number;
+  hazard_class_adr: string | null;
+  odor: string;
+  initial_amount: number;
+  initial_weight: number;
+  latest_weight: number;
+  latest_amount_mg: number;
+  latest_amount_ml: number;
+  latest_location: string;
+  location_detail: Record<string, any>;
+  f_latest_request_user: number;
+  status: string;
+  checkin_user: string;
+  checkout_user: string;
+  chemical_name: string | null;
+  createdById: number | null;
+}
+
+async returnCmpdToXfcSh(
+   items: ReturnCmpdToXfcShItem[],
+   options: ReturnCmpdToXfcShOptions = {},
+): Promise<CmpdItem[]> {}
+```
+
+### 返回数据示例
+
+```json
+[
+    {
+        "createdAt": "2026-07-13T09:55:20.578Z",
+        "updatedAt": "2026-07-23T06:03:58.221Z",
+        "initial_checkin_time": "2026-07-13T09:55:20.577Z",
+        "latest_checkin_time": "2026-07-23T06:03:58.143Z",
+        "latest_checkout_time": "2026-07-13T10:27:41.293Z",
+        "id": 9720,
+        "cas": "220598-45-8",
+        "po_num": "PO20250821000113",
+        "f_account": 39,
+        "f_project": 81,
+        "source": "上海皓鸿生物医药科技有限公司",
+        "barcode": "XFC26071300041",
+        "cmpd_id": "BC0998",
+        "owner": "李辉",
+        "f_category": 1,
+        "hazard_class_adr": null,
+        "odor": "",
+        "initial_amount": 100,
+        "initial_weight": 1,
+        "latest_weight": 1,
+        "latest_amount_mg": 100,
+        "latest_amount_ml": 1,
+        "latest_location": "KWA-R00-L0-A00",
+        "location_detail": {},
+        "f_latest_request_user": 11,
+        "status": "可用",
+        "checkin_user": "xtalppi",
+        "checkout_user": "auto",
+        "chemical_name": null,
+        "createdById": null
+    },
+    {
+        "createdAt": "2026-07-13T09:56:36.025Z",
+        "updatedAt": "2026-07-23T06:03:58.225Z",
+        "initial_checkin_time": "2026-07-13T09:56:36.024Z",
+        "latest_checkin_time": "2026-07-23T06:03:58.143Z",
+        "latest_checkout_time": "2026-07-13T10:27:41.293Z",
+        "id": 9721,
+        "cas": "851288-57-8",
+        "po_num": "PO20250821000113",
+        "f_account": 39,
+        "f_project": 81,
+        "source": "上海皓鸿生物医药科技有限公司",
+        "barcode": "XFC26071300042",
+        "cmpd_id": "CA5019",
+        "owner": "李辉",
+        "f_category": 1,
+        "hazard_class_adr": null,
+        "odor": "",
+        "initial_amount": 100,
+        "initial_weight": 1,
+        "latest_weight": 1,
+        "latest_amount_mg": 100,
+        "latest_amount_ml": 1,
+        "latest_location": "KWA-R00-L0-A00",
+        "location_detail": {},
+        "f_latest_request_user": 11,
+        "status": "可用",
+        "checkin_user": "xtalppi",
+        "checkout_user": "auto",
+        "chemical_name": null,
+        "createdById": null
+    }
+]
+```
+