@xtalpi/agentic-lab-skills 0.0.7 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xtalpi/agentic-lab-skills",
-	"version": "0.0.7",
+	"version": "0.0.9",
 	"description": "Agentic Lab Skills",
 	"license": "MIT",
 	"author": "TheoXiong",

package/skills/lab-flow-designer/SKILL.md

@@ -83,7 +83,7 @@ metadata:
 - **必须**向用户交付 **《流程文档合规问题与优化建议》**（可用 Markdown 小节组织），且至少包含：  
   1. **问题清单**：每条对应标准中的位置（例如「§4 清单第 n 项」「§3.2 不支持的 API」「§3.3 `items` 结构不完整」）。  
   2. **现状说明**：流程文档中**缺失**、**矛盾**、**模糊**或**不可解析**之处（可引用现有标题、表格列名、YAML 片段；对不支持的依赖/API/字段须**点名**）。  
-  3. **可执行修改建议**：具体应**补写/改写**哪一类内容（例如消除模糊条件、改为 SDK 已支持方法、补全 `process.execute` 的 `items`/`params`/`baseURL` 说明、统一字段拼写）。  
+  3. **可执行修改建议**：具体应**补写/改写**哪一类内容（例如消除模糊条件、改为 SDK 已支持方法、补全 SDK 调用方法的参数说明、统一字段拼写）。  
   4. **严重程度**：**阻断**（不满足则无法稳定生成，含不支持的 API、不可判定逻辑、Process 参数无法落地）与**建议**（不阻断但易导致脚本/Schema 歧义）。  
   5. **（若适用）不支持或不可生成项**：集中列出标准 **§3.2 / §3.3** 拦截项，避免与一般格式问题混排。  
 - 仅当用户**随后**提供已按建议修订的流程文档时，才允许重新从本预检开始执行。
@@ -119,7 +119,7 @@ metadata:
     - 数据来源与操作按钮描述
   - **后置处理** → 生成 `Processer.complete` 函数逻辑。须提取：
     - 规则摘要表（条件要点 + 业务动作），落入 `complete` 函数体
-    - 提交参数结构（如 `process.execute` 的 `items` 定义与 `params` 键级说明）
+    - 提交参数结构（如 SDK 调用方法的参数定义与键级说明）
     - 出口池路由条件与字段映射
 - **门控脚本配置项**：提取全局配置表中的各项，落入脚本为**模块级常量**：
   - `PageUrl`（含 `{bookid}` 占位符）→ 脚本常量 `PAGE_URL`
@@ -161,7 +161,7 @@ metadata:
 
 - **`### 数据池（Pool）`**：说明 Pool 存记录、每池有独立 Schema、随阶段变化。
 - **`### 门控（Valve）`**：说明每个 Valve 对应脚本、`Processer` 的 `start` / `complete` 职责分工。  
-  另起简短列表说明执行引擎通过 `this.context` 暴露的能力，**仅写** [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中已出现项（如 `ticket.list` / `update` / `append`、`pool.getNext`、`process.list`、`process.execute`、`station.list`、`compound.getStock`、`compound.getChemicalRecord`），**不要**抄写模板里已过期的成员名。
+  另起简短列表说明执行引擎通过 `this.context` 暴露的能力，**仅写** [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)「可用方法一览」中已列出的方法名（按流程实际使用选取），**不要**抄写模板里已过期的成员名。
 
 #### 3.4 `## 流程图`（本节内须含「连接关系」列表，与模板一致）
 
@@ -238,11 +238,11 @@ metadata:
 
 若流程说明对某门控给出了下列块，须在对应 `valves/<基名>.md` 中**原样结构化呈现**（标题可用 `##` / `###`，便于脚本作者对照）：
 
-- **门控 YAML**（`valve_id`、`name`、`order`、`input`、`output`）；若文档使用 `Stash:` 等非标准键表示目标池，**保留原文**，并在 valve 文内加一句说明：实现时与 `pool.getNext` 返回的 `pool.name` 按**池显示名称**匹配。
+- **门控 YAML**（`valve_id`、`name`、`order`、`input`、`output`）；若文档使用 `Stash:` 等非标准键表示目标池，**保留原文**，并在 valve 文内加一句说明：实现时按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 获取出口池，以返回的 `pool.name` 与**池显示名称**匹配。
 - **前置处理**（对应 `start`）：提取配置项（如 `bookid`）、规则摘要表，说明 `start` 函数需执行的逻辑。
 - **人工处理**：界面形态与数据绑定描述（仅供参考，不由门控脚本实现）。
-- **后置处理**（对应 `complete`）：规则摘要表、提交参数结构（如 `process.execute` 的 `items` 定义），说明 `complete` 函数需执行的逻辑。
-- **化合物数据查询方式**（或等价标题）：表或段落中「查 compound / chemical_record」等表述，与 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中 `compound.getStock`、`compound.getChemicalRecord` 的对应关系写清。
+- **后置处理**（对应 `complete`）：规则摘要表、提交参数结构（如 SDK 调用方法的参数定义），说明 `complete` 函数需执行的逻辑。
+- **化合物数据查询方式**（或等价标题）：表或段落中「查化合物库存」等表述，与 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中对应 SDK 方法的映射关系写清。
 - **字段映射表**：「门控加工数据 ↔ 库字段 / API 字段」；脚本写入 `ticket.detail` 的键须与 **pools Schema「字段」列（snake_case）** 一致。
 - **数据处理规则**表：序号（如 1.1、1.2）须在脚本注释中可逐条追溯。
 
@@ -272,23 +272,20 @@ metadata:
 
 | 来源 | 落点（脚本侧） |
 |------|----------------|
-| 门控 YAML `input` | `start` 中 `ticket.list({ pool_id__in, limit, offset })` 的 `pool_id__in`（入口池 ID 数组；`limit`/`offset` 遵守 §2）；**返回** `TicketListResponse`，业务数据取 **`response.list`**；含 `secondary` 时合并多个入口池 ID 后再传入 `pool_id__in` |
-| 门控 YAML `output` | `complete` 中 `await this.context.pool.getNext(valve_id)` 后按 `pool.name` 与条件分支筛选目标池 |
-| **化合物数据查询方式** | `compound.getStock`、`compound.getChemicalRecord`：入参为 **`filter`（NocoBase Repository 风格）** + 可选 `limit`/`offset`；算子见 agentic-lab-sdk 篇首与 [Filter Operators](https://docs.nocobase.com/api/database/operators) |
+| 门控 YAML `input` | `start` 中按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 查询入口池 tickets（`limit`/`offset` 遵守 §2）；含 `secondary` 时合并多个入口池 ID |
+| 门控 YAML `output` | `complete` 中按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 获取出口池，以 `pool.name` 与条件分支筛选目标池 |
+| **化合物数据查询方式** | 按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 调用化合物库存查询方法 |
 | **字段映射表** | 将 API 返回字段写入 `ticket.detail` 的 snake_case 键 |
 | **数据处理规则**（序号表） | `start` 内计算与回填，或 `complete` 内最终路由前校验；关键分支写 `// 规则 1.x` 注释 |
 | **门控脚本配置项**表 | 脚本模块级常量：`PAGE_URL`（取 `PageUrl` 值）、`DEFAULT_QUERY_LIMIT`（取入口池查询上限，缺省 `999999`）、`STATION_BASE_URL`（若有）；**各门控前置处理**配置中的 `bookid` → `BOOK_ID`（每个门控独立值） |
 
 ### 2. 分页与「查全量」（`limit` / `offset`）
 
-凡 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中带 **`limit`** / **`offset`** 的查询（如 **`ticket.list`**、**`process.list`**、**`compound.getStock`**、**`compound.getChemicalRecord`**），生成门控脚本时遵守：
+凡 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)「可用方法一览」中标注使用 `limit` / `offset` 分页的查询方法，生成门控脚本时遵守：
 
-1. **流程说明未写分页**：未出现「每页/只查前/offset/limit/条数上限」等明确要求时，**默认**显式传入 **`limit: 999999`**、**`offset: 0`**（可用模块级常量如 `DEFAULT_QUERY_LIMIT`），避免依赖引擎默认小页长导致**截断漏数据**。**例外**：若流程文档**门控脚本配置项**表中写明了入口池查询上限（如 `门控脚本对入口池单次查询上限: 9000`），以该值作为 `DEFAULT_QUERY_LIMIT`，不使用默认 `999999`。
 2. **流程说明写了分页**：按文档给出的 `limit`、`offset`（或等价参数名）原样写入调用。
 3. **流程说明写了「查全部/不限制条数」及具体数值**（例如明确要求 `limit: 500000`）：**以流程文档为准**，不得擅自改为 `999999`。
 
-`pool.getNext`、`station.list` 等无分页参数的调用不受影响。
-
 ### 3. `start` 与 `complete` 分工（与门控三阶段对齐）
 
 门控执行顺序为 **前置处理（脚本）→ 人工处理（页面）→ 后置处理（脚本）**。`start` 对应**前置处理**，`complete` 对应**后置处理**。
@@ -299,16 +296,53 @@ metadata:
 - **`start` 返回** `StartExecutionResult`：**必须**含 `orbit_link`（`string`）、`ticket_ids`（`number[]`）。
 - **`complete` 入参** `CompleteExecutionParams`：**必须**含 `valve_id`（`number`）、`tickets`（`Record<string, any>[]`）。
 - **`complete` 返回** `CompleteExecutionResult`：通过 `new_tickets`（`Record<string, any>[]`，可选）返回待写入出口池的工单，由引擎自动创建。
-- **一级参数与返回值键名一律 snake_case**（如 `valve_id`、`pool_ids`、`ticket_ids`、`orbit_link`、`new_tickets`），**禁止** camelCase（如 ~~`ticketIds`~~、~~`poolIds`~~）。嵌套数据（如 `ticket.detail` 内容、`process.execute` 的 `params`/`items` 等 JSON 结构）保持流程文档或 API 原有格式，不受此约束。
+- **一级参数与返回值键名一律 snake_case**（如 `valve_id`、`pool_ids`、`ticket_ids`、`orbit_link`、`new_tickets`），**禁止** camelCase（如 ~~`ticketIds`~~、~~`poolIds`~~）。嵌套数据（如 `ticket.detail` 内容、SDK 方法的 `params`/`items` 等 JSON 结构）保持流程文档或 API 原有格式，不受此约束。
 
-- **`start(params)`**（对应**前置处理**）：解构 **`valve_id`、`pool_ids`**（`Processer` 入参 snake_case）→ `ticket.list({ pool_id__in: pool_ids, … })`（§2 默认大 `limit`；**返回值**为 `TicketListResponse`，取 **`response.list`** 得 `Ticket[]`；筛选键名以 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) `ListTicketParams` 为准）→ **仅当**流程说明前置处理中写明化合物查询 / 流程列表 / 工站等需求时，才分别调用 `compound.getChemicalRecord`、`compound.getStock`、`process.list`、`station.list`（缺则**不调**）→ **仅按**数据处理规则与映射更新 `ticket.detail` 中**文档涉及的键** → `ticket.update`（若确有写回）→ 拼装 `orbit_link`（见下方步骤）→ 返回 `{ orbit_link, ticket_ids }` 。
+- **`start(params)`**（对应**前置处理**）：解构 **`valve_id`、`pool_ids`**（`Processer` 入参 snake_case）→ 按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 查询入口池数据（§2 默认大 `limit`）→ **仅当**流程说明前置处理中写明化合物查询 / 流程列表 / 工站等需求时，才按需调用对应 SDK 方法（缺则**不调**；各方法见 [agentic-lab-sdk.md](references/agentic-lab-sdk.md)）→ **仅按**数据处理规则与映射更新 `ticket.detail` 中**文档涉及的键** → 按 SDK 更新 tickets（若确有写回）→ 拼装 `orbit_link`（见下方步骤）→ 返回 `{ orbit_link, ticket_ids }` 。
 
   **`orbit_link` 生成步骤**：
   1. 从**门控脚本配置项**表提取 `PageUrl`（含 `{bookid}` 占位符），写为脚本模块级常量 `PAGE_URL`
   2. 从该门控**前置处理**配置项中提取 `bookid` 值，写为脚本模块级常量 `BOOK_ID`
   3. `start` 函数末尾拼装：`const orbit_link = PAGE_URL.replace('{bookid}', BOOK_ID)`
 
-- **`complete(params)`**（对应**后置处理**）：解构 **`valve_id`** 与 **`tickets`**（snake_case 入参）→ **优先使用 `params.tickets` 作为业务数据源**（引擎已传入完整 ticket 数据，无需再通过 `ticket.list` 重新查询；仅当流程说明后置处理中**明确要求**获取额外数据或最新状态时才按需调用 `ticket.list`）→ 按流程说明后置处理中的规则执行业务逻辑（准备提交参数、调用外部接口如 `process.execute`、判定成败等）→ **`await`** `this.context.pool.getNext(valve_id)` → 将入口池 tickets 更新为 `finished`（`ticket.update`）→ 按出口池条件映射 `new_tickets`（含 `flow_id`、`pool_id`、`order_id`、`detail`、`status: 'created'`、`parent_ticket_id`）→ 返回 `{ new_tickets }`（由引擎自动创建，**不**在脚本内调用 `ticket.append`）。
+- **`complete(params)`**（对应**后置处理**）：解构 **`valve_id`** 与 **`tickets`**（snake_case 入参）→ **优先使用 `params.tickets` 作为业务数据源**（引擎已传入完整 ticket 数据，无需重新查询；仅当流程说明后置处理中**明确要求**获取额外数据或最新状态时才按需查询）→ 按流程说明后置处理中的规则执行业务逻辑（准备提交参数、按需调用 SDK 方法、判定成败等）→ 按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 获取出口池 → 将入口池 tickets 更新为 `finished` → 按出口池条件映射 `new_tickets`（含 `flow_id`、`pool_id`、`order_id`、`detail`、`status: 'created'`、`parent_ticket_id`）→ 返回 `{ new_tickets }`（由引擎自动创建，**不**在脚本内直接追加 tickets）。
+
+### 4. 运行环境约束（沙箱可用全局对象）
+
+门控脚本在**沙箱**中执行，**仅**以下全局对象/函数可用：
+
+| 类别 | 可用 |
+|------|------|
+| 基础类型 | `Array`, `Object`, `Map`, `Set`, `JSON`, `Math`, `Date`, `Number`, `String`, `Boolean`, `RegExp` |
+| 错误类型 | `Error`, `TypeError`, `ReferenceError` |
+| 数值函数 | `parseInt`, `parseFloat`, `isNaN`, `isFinite` |
+| 编码函数 | `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI` |
+| 异步 | `Promise`, `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval` |
+| 常量 | `undefined`, `NaN`, `Infinity` |
+| IO | `console`（`log`/`info`/`warn`/`error`/`debug`）、`fetch`（仅限 SDK 无法覆盖的外部调用） |
+
+**不可用**（使用即抛 `ReferenceError`）：
+
+- `URLSearchParams`、`URL`、`Headers`、`Request`、`Response`、`FormData`、`Blob`、`Buffer`
+- `TextEncoder`、`TextDecoder`
+- `process`、`require`、`module`、`exports`、`__dirname`、`__filename`
+- `window`、`document`、`globalThis`（浏览器/Node.js 专属）
+
+**替代方案**：
+
+1. **拼接 query string**——用模板字符串 + `encodeURIComponent`（不要用 `URLSearchParams`）：
+   ```js
+   // ✅ 正确
+   const qs = `view_id=${encodeURIComponent(viewId)}&page_size=500`;
+   const url = `${BASE}?${qs}`;
+
+   // ❌ 错误——URLSearchParams 不存在
+   const qs = new URLSearchParams({ view_id: viewId, page_size: '500' });
+   ```
+
+2. **外部 HTTP 调用**——优先使用 `this.context` SDK 方法（见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)）。仅当流程文档要求调用 SDK 未覆盖的第三方 API（如飞书/Lark）时，才使用 `fetch`；此时 URL 手动拼接，**不依赖** `URLSearchParams`。
+
+3. **JSON 序列化**——`JSON.stringify` / `JSON.parse` 可用（`JSON` 在沙箱白名单中）。
 
 ### 5. 类型安全的字段访问（防止运行时 TypeError）
 
@@ -335,9 +369,9 @@ metadata:
 ### 6. 参考代码（按优先序打开）
 
 1. [references/agentic-lab-processer.md](references/agentic-lab-processer.md)（**`Processer` 类型定义与代码风格**参考；`start`/`complete` 输入输出类型、snake_case 命名）
-2. [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js)（**结构与分页约定**参考；compound / `pool.getNext` / `ticket` 等**仅当本门控文档需要时**才纳入生成，勿默认照抄示例中的全部调用；**列表类查询默认 `limit: 999999`**）  
+2. [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js)（**结构与分页约定**参考；SDK 方法**仅当本门控文档需要时**才纳入生成，勿默认照抄示例中的全部调用；**列表类查询默认 `limit: 999999`**）  
 3. [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)  
-4. 多门控流程：按拓扑为每个门控各写一对 `valves/<基名>.md` 与 `scripts/<基名>.js`，API 与分页约定同上；勿使用 `agentic-lab-sdk.md` 未列出的 `context` 成员（如旧代码中的 `processe` 等，应使用 **`process.list`**）。
+4. 多门控流程：按拓扑为每个门控各写一对 `valves/<基名>.md` 与 `scripts/<基名>.js`，API 与分页约定同上；勿使用 `agentic-lab-sdk.md` 未列出的 `context` 成员。
 
 ### 7. 产物版本追踪
 
@@ -400,6 +434,8 @@ console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__}
 - 脚本以 `Processer` 类结束，禁止 `return`/`module.exports`/`export`（见「生成流程 §6」）
 - 按需生成，禁止冗余：代码和 Schema 仅覆盖流程文档明确写出的内容（见「编写指引 §0」）
 - **类型安全**：禁止直接对 `ticket.detail` 值调用 `.trim()` / `.split()` 等字符串方法；必须先 `String()` 转换或 `typeof` 判断（见「编写指引 §5」）
+- **运行环境**：门控脚本在沙箱执行，`URLSearchParams`/`URL`/`Buffer` 等 Web/Node API **不可用**；拼接 query string 须用模板字符串 + `encodeURIComponent`（见「编写指引 §4」）
+- **外部 HTTP**：优先用 `this.context` SDK 方法；仅 SDK 未覆盖的第三方 API 才用 `fetch`，URL 手动拼接（见「编写指引 §4」）
 - **产物版本**：SKILL.md frontmatter 须含 `metadata.version`；每个脚本须含 `__ARTIFACT_VERSION__` / `__ARTIFACT_SKILL__` 常量及 constructor `console.info`（见「编写指引 §7」）
 - **脚本自测**：凡写入或修改 `scripts/*.js`，必须用 `testing/test-processer.mjs` 执行自测并自动修复，直到正常轮全 `pass`（见「脚本自测」）
 
@@ -414,8 +450,6 @@ console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__}
 **流程来源**：若该包为 **初次生成** 产物，源流程文档应已通过 **「流程文档合规预检」**；复查可对照 [references/业务流程文档标准.md](references/业务流程文档标准.md) §4。**迭代修改**路径无此强制要求。  
 **结构清单**：根目录 `SKILL.md`（合法 `name`/`description`、固定二级标题：`概述`、`核心概念`、`流程图`、`节点清单`、`门控执行规范`、`使用方式`）、`**连接关系：**`、`### Pool 节点` / `### Valve 节点`、`Processer` 类与门控执行规范代码块、存在 `pools/` / `valves/` / `scripts/`、`valves` 与 `scripts` 同名成对、任取一个 `pools/*.md` 的 Schema 表头含 **字段** / **字段标题** / **属性** 且数据行「字段」列为 snake_case。
 
-**人工抽查**：生成脚本里 `ticket.list`、`process.list`、`compound.getStock`、`compound.getChemicalRecord` 在无流程分页说明时是否传入 **`limit: 999999`**（或流程说明指定的查全量数值），见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 篇首约定。
-
 **版本追踪**：`SKILL.md` frontmatter 含 `metadata.version` / `metadata.generated_by` / `metadata.generated_at`；每个 `scripts/*.js` 含 `__ARTIFACT_VERSION__` 常量（值与 `metadata.version` 一致）和 `__ARTIFACT_SKILL__` 常量；`Processer` constructor 含 `console.info` 版本打印。
 
 **对照物**：[embedded-template/](embedded-template/)（已知良好缩小范例）、[references/skill-package-layout.md](references/skill-package-layout.md)、[references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)。

package/skills/lab-flow-designer/embedded-template/scripts//347/244/272/344/276/213/346/225/260/346/215/256/344/270/216/346/240/241/351/252/214/351/227/250/346/216/247.js

@@ -55,20 +55,13 @@ class Processer {
       ),
     ];
 
-    let chemicalRecords = [];
     let stockRecords = [];
     if (compoundIdList.length > 0) {
-      const filter = { cmpd_id: { $in: compoundIdList } };
-      chemicalRecords = await this.context.compound.getChemicalRecord({
+      const filter = { 'cas.$in': compoundIdList };
+      const stockResponse = await this.context.compound.getStockFromXfcSh({
         filter,
-        limit: DEFAULT_QUERY_LIMIT,
-        offset: 0,
-      });
-      stockRecords = await this.context.compound.getStock({
-        filter,
-        limit: DEFAULT_QUERY_LIMIT,
-        offset: 0,
       });
+      stockRecords = stockResponse.data || [];
     }
 
     const stations = await this.context.station.list();
@@ -87,14 +80,8 @@ class Processer {
     // --- 规则 1.1～1.4：按 valves/示例数据与校验门控.md「数据处理规则」写回 detail（以下为示意）---
     for (const ticket of tickets) {
       const d = ticket.detail || {};
-      const chem = chemicalRecords.find((r) => r.cmpd_id === d.cmpd_id);
-      const stock = stockRecords.filter((r) => r.cmpd_id === d.cmpd_id);
+      const stock = stockRecords.filter((r) => str(r.cas) === str(d.cmpd_id));
 
-      if (chem) {
-        d.chemist_property = str(chem.chemist_property);
-        d.dispensable = chem.dispensable;
-        d.dispensing_remark = str(chem.dispensing_remark);
-      }
       if (stock.length) {
         d.available_amount_mg = stock.reduce(
           (s, r) => s + num(r.latest_amount_mg, 0),

package/skills/lab-flow-designer/embedded-template/valves//347/244/272/344/276/213/346/225/260/346/215/256/344/270/216/346/240/241/351/252/214/351/227/250/346/216/247.md

@@ -12,7 +12,7 @@
 
 ## 门控 YAML（与流程说明对齐）
 
-流程说明中可能使用 `Stash:` 等键表示目标池；生成脚本时以 **`pool.name`**（或文档中的池显示名称）与 `pool.getNext(valve_id)` 返回值匹配（`valve_id` 来自 `Processer` 入参）。
+流程说明中可能使用 `Stash:` 等键表示目标池；生成脚本时按 [agentic-lab-sdk.md](../../references/agentic-lab-sdk.md) 获取出口池，以返回的 **`pool.name`**（或文档中的池显示名称）匹配目标池（`valve_id` 来自 `Processer` 入参）。
 
 ```yaml
 valve_id: valve_example_1
@@ -29,8 +29,7 @@ output:
 
 | 流程说明中的表述 | 推荐 SDK 调用 |
 |----------------|---------------|
-| 查 compound 表 / 可用量 / 库存汇总 | `context.compound.getStock({ filter, limit, offset })`；`filter` 为 NocoBase 条件；**流程未写分页时**建议 `limit: 999999`、`offset: 0`（见主 `SKILL.md` 门控脚本指引）。另见 [agentic-lab-sdk](../../references/agentic-lab-sdk.md)、[Filter Operators](https://docs.nocobase.com/api/database/operators) |
-| 查 chemical_record / 知识库属性 | `context.compound.getChemicalRecord({ filter, limit, offset })`；同上，默认大 `limit` 防截断 |
+| 查化合物库存 / 可用量 / 库存汇总 | 按 [agentic-lab-sdk.md](../../references/agentic-lab-sdk.md) 中的化合物库存查询方法 |
 
 ## 字段映射（示例：知识库 → ticket.detail）
 
@@ -53,7 +52,7 @@ output:
 | 序号 | 规则摘要 | 业务动作（示意） |
 |------|----------|------------------|
 | 1.1 | 汇总需求量 | `detail.requested_amount = sum(target_amount_n)` |
-| 1.2 | 缺料判定 | 结合 `getStock` 汇总可用量与 `requested_amount` 比较 |
+| 1.2 | 缺料判定 | 结合化合物库存查询（SDK）汇总可用量与 `requested_amount` 比较 |
 | 1.3 | 容差默认 | 目标量 >0 且容差空 → 默认 0.5 mg |
 | 1.4 | 缺料标记 | `source_barcode` 空 → `是否缺料` = 缺料 |
 
@@ -69,9 +68,9 @@ output:
 
 | 规则摘要 | 条件要点 | 业务动作或结果 |
 | -------- | -------- | -------------- |
-| 查询入口池 | 门控启动 | `ticket.list({ pool_id__in: pool_ids, limit: 999999, offset: 0 })`，取返回体 `list` |
-| 查化合物数据 | 有 compound 查询需求 | `compound.getChemicalRecord` / `compound.getStock`（同上默认大 `limit`） |
-| 写回 detail | 查询完成 | 按映射表与规则表写回 `ticket.detail` → `ticket.update` |
+| 查询入口池 | 门控启动 | 按 SDK 查询入口池 tickets（分页遵守主 SKILL.md 编写指引 §2） |
+| 查化合物数据 | 有 compound 查询需求 | 按 SDK 查询化合物库存数据 |
+| 写回 detail | 查询完成 | 按映射表与规则表写回 `ticket.detail` → 按 SDK 更新 tickets |
 | 拼装 orbit_link | 返回前 | `PageUrl.replace('{bookid}', bookid)` |
 
 **start 返回**：`{ orbit_link, ticket_ids }`
@@ -88,11 +87,11 @@ output:
 
 | 规则摘要 | 条件要点 | 业务动作或结果 |
 | -------- | -------- | -------------- |
-| 获取出口池 | `pool.getNext(valve_id)` | 按 `pool.name` 匹配出口池 |
-| 更新入口池状态 | 出口池确定 | 入口池 tickets 更新为 `status: 'finished'` → `ticket.update` |
+| 获取出口池 | 按 SDK 获取出口池 | 按 `pool.name` 匹配出口池 |
+| 更新入口池状态 | 出口池确定 | 入口池 tickets 更新为 `status: 'finished'` → 按 SDK 更新 tickets |
 | 映射出口池记录 | 状态更新完成 | 按出口池 Schema 构建 `new_tickets`（含 `flow_id`、`pool_id`、`order_id`、`detail`、`status: 'created'`、`parent_ticket_id`） |
 
-**complete 返回**：`{ new_tickets }`（由引擎自动创建，脚本不调用 `ticket.append`）
+**complete 返回**：`{ new_tickets }`（由引擎自动创建，脚本不直接追加 tickets）
 
 ## 输入/输出
 

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

@@ -1,4 +1,6 @@
 > Agentic Lab 门控脚本
+>
+> `this.context` 上可用的 SDK 方法详见 [agentic-lab-sdk.md](agentic-lab-sdk.md)。本文件仅定义 `Processer` 类的 `start`/`complete` 输入输出类型与代码风格。
 
 ### 类型定义
 
@@ -50,53 +52,27 @@ class Processer {
 
   // params: { valve_id, pool_ids }
   async start(params) {
-    const tickets = await this.context.ticket.list({ pool_id__in: pool_ids });
-    const stations = await this.context.station.list();
-    
-    const process_ids = []; // 从tickets detail 按需提取出process ids
-    const processes = await this.context.process.list({ process_ids });
-
-    // 基于stations、processes等数据源，筛选待处理tickets
-    const finalTickets = tickets.filter(ticket => ticket);
-
-    // 将processes更新到finalTickets detail中
-    finalTickets.forEach(ticket => { ticket.detail.processes = processes })
-    // 更新数据库中的tickets，以便Orbit视图获取最新数据
-    await this.context.ticket.update(finalTickets)
-    
+    // 按 agentic-lab-sdk.md 查询入口池数据
+    // 按需调用 SDK 方法查询化合物/工站/流程等外部数据
+    // 将查询结果写回 ticket.detail
+    // 按 agentic-lab-sdk.md 更新 tickets
     return {
-      orbit_link: 'https://orbit-sh.xtalpi.xyz/?view=book&book=3947',
-      ticket_ids: finalTickets.map(ticket => ticket.id),
+      orbit_link: 'https://...',
+      ticket_ids: [/* 待处理 ticket ID */],
     }
   }
 
   // params: { valve_id, tickets }
   async complete(params) {
-    // params.tickets 已包含本次待处理的人工录入数据，通常无需重新查询；如需补充数据库数据请按实际需求调用查询方法
-
-    // 获取当前门控的（一个或多个）出口池
-    const nextPools = this.context.pool.getNext(valveId);
-    const successPool = nextPools.find(pool => pool.name === 'xxx成功');
-    const failedPool = nextPools.find(pool => pool.name === 'xxx失败');
-
-    // 基于实时tickets，按实际业务场景(流程说明书中的相关定义)，筛选出“可流入出口池”的tickets
-    const finalTickets = params.tickets.filter(ticket => ticket).map(t => ({ ...t, status: 'finished' }));
-
-    // 将入口池的tickets更新为“已完成”状态，避免重复处理
-    await this.context.ticket.update(finalTickets);
-
-    // 按实际的业务场景(流程说明书中的相关定义)， 筛选出“可流入成功出口池”的tickets，并按出口池的schema 映射为新的tickets
-    const newSuccessTickets = finalTickets.filter(ticket => ticket).map(t => ({ ...t, status: 'created', pool_id: successPool.id }));
-    // 按实际的业务场景(流程说明书中的相关定义)， 筛选出“可流入失败出口池”的tickets，并按出口池的schema 映射为新的tickets
-    const newFailedTickets = finalTickets.filter(ticket => ticket).map(t => ({ ...t, status: 'created', pool_id: failedPool.id }));
-
-    // 脚本不负责创建新ticket，交由引擎自动创建（需返回new_tickets）
+    // 按 agentic-lab-sdk.md 获取出口池
+    // 按业务规则筛选可流入出口池的 tickets
+    // 将入口池 tickets 更新为 finished 状态
+    // 按出口池 Schema 映射 new_tickets（脚本不直接追加 tickets，交由引擎自动创建）
     return {
-      new_tickets: [
-        ...newSuccessTickets,
-        ...newFailedTickets
-      ]
+      new_tickets: [/* 按出口池映射的新 tickets */]
     }
   }
 }
 ```
+
+完整可运行代码参考见 [`embedded-template/scripts/示例数据与校验门控.js`](../embedded-template/scripts/示例数据与校验门控.js)。

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

@@ -6,7 +6,27 @@
 
 ## 门控脚本生成约定（lab-flow-designer）
 
-对 **`ticket.list`**、**`process.list`**、**`compound.getStock`**、**`compound.getChemicalRecord`** 等支持 **`limit` / `offset`** 的查询：若流程说明**未**明确要求分页或条数，生成门控脚本时应显式传入 **`limit: 999999`**、**`offset: 0`**，避免引擎默认小页长截断。若流程说明写了分页或「查全部」的**具体数值**，以流程说明为准。
+对 **`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` 能力列表时，从本表选取流程实际使用的方法即可。各方法的完整签名、参数类型与返回类型见下文各节。
 
 ---
 
@@ -176,265 +196,166 @@ async function station.list(): Promise<Station[]>
 
 ---
 
-## compound.getStock
+## compound.getStockFromXfcSh
 
-- **别名**：`context.compound.getStock`
-- **描述**：按 NocoBase Repository 风格的 **`filter`** 查询化合物库 **库存/瓶位**（collection 如 `compound`）。`filter` 支持 `$eq`、`$in`、`$and`、`$or` 等算子，字段名与库一致，便于流程自定义任意组合条件。算子说明见 NocoBase 文档：[Filter Operators](https://docs.nocobase.com/api/database/operators)。
+- **别名**：`context.compound.getStockFromXfcSh`
+- **描述**：获取 XFC 上海系统化合物库存。使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值（默认 `pageSize: 400`、`page: 1`）。
 
 ```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;
+interface StockFromXfcShParams {
+  filter?: Record<string, any>;
+  fields?: string[] | string;
+  pageSize?: number;
+  page?: number;
+  [propName: string]: any;
 }
 
-/**
- * 嵌套：账户（`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;
-}
+async function compound.getStockFromXfcSh(
+  params?: StockFromXfcShParams
+): Promise<CompoundResponse>
+```
 
-/**
- * 嵌套：品类（`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;
-}
+### 参数说明
+
+| 参数名 | 含义 | 备注 |
+|--------|------|------|
+| `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 → 分页信息
+```
 
-/**
- * 嵌套：最近申领人（`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；备注：无 */
+```typescript
+interface CompoundItem {
   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；备注：全局唯一 */
+  status: string;
+  source: string;
   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;
+  owner: string;
+}
+
+interface CompoundMeta {
+  count: number;
+  page: number;
+  pageSize: number;
+  totalPage: number;
 }
 
-async function compound.getStock(
-  params: GetCompoundStockParams
-): Promise<CompoundStockRecord[]>
+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 }
+}
 ```
 
 ---
 
-## compound.getChemicalRecord
+## agent.chat
 
-- **别名**：`context.compound.getChemicalRecord`
-- **描述**：按 NocoBase **`filter`** 查询 **化合物知识库** `chemical_record`（可分装性、化性状、备注等），与库存 `compound.getStock` 区分；算子与 `GetCompoundStockParams.filter` 相同，见 [Filter Operators](https://docs.nocobase.com/api/database/operators)。
+- **别名**：`context.agent.chat`
+- **描述**：调用外部 Agent 服务。SDK 负责发起请求、消费流式（SSE / NDJSON）或普通 JSON 响应，并将各 chunk 的 `content` 拼接为完整文本。`url`、`query` **必填**。`parseJson: true` 时从返回文本中提取并解析 JSON（支持 Markdown 代码块与多段 JSON 合并）；解析成功返回 object / array，失败返回 `null`。未开启 `parseJson` 时返回原始字符串。请求失败抛出以 `agent.chat:` 为前缀的错误。
 
 ```typescript
-type NocoBaseFilter = Record<string, unknown>;
-
-/** 查询参数：以 `filter` 描述对 `chemical_record` 的筛选。 */
-interface GetChemicalRecordParams {
+interface ChatAgentParams {
+  /** Agent 服务完整 URL（必填） */
+  url: string; // Agent 服务完整 URL（必填
+  /** 用户查询文本（必填；非空字符串） */
+  query: string;
   /**
-   * 示例：`{ cmpd_id: { $in: ['CA1078'] } }`；
-   * `{ compound_id: { $in: ['28022-43-7'] } }`（业务将 CAS 存于 `compound_id` 时）；
-   * `{ dispensable: { $isTruly: true } }`（布尔字段算子见 NocoBase 文档）。
+   * true：从返回文本提取并解析 JSON，成功返回 object/array，失败返回 null；
+   * 未传或 false：返回拼接后的原始 string
    */
-  filter: NocoBaseFilter;
-  limit?: number;
-  offset?: number;
+  parseJson?: boolean;
+  [propName: string]: any;
 }
 
 /**
- * 单条 `chemical_record` 化合物知识库记录（与 collection 元数据及典型 API 返回对齐）
- * 字段注释：库字段 `name`；**别名** = `uiSchema.title`；**备注** = `description`（无则写「无」）
+ * parseJson 未开启：Promise<string>
+ * parseJson 开启且解析成功：Promise<object | any[]>
+ * parseJson 开启且解析失败：Promise<null>
  */
-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 agent.chat(params: ChatAgentParams): Promise<string | object | any[] | null>
+```
 
-async function compound.getChemicalRecord(
-  params: GetChemicalRecordParams
-): Promise<ChemicalRecord[]>
+### 参数说明
+
+| 参数名 | 含义 | 备注 |
+|--------|------|------|
+| `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)`**。

package/skills/lab-flow-designer/references/skill-package-layout.md

@@ -100,7 +100,7 @@ class Processer {
   // returns: { orbit_link, ticket_ids }
   async start(params) {
     const { valve_id, pool_ids } = params;
-    // ticket.list → 按需查询化合物/工站/流程 → 写回 detail → ticket.update
+    // 查询入口池数据 → 按需查询化合物/工站/流程 → 写回 detail → 更新 tickets
     // orbit_link = PageUrl.replace('{bookid}', bookid)
     return { orbit_link, ticket_ids };
   }
@@ -110,8 +110,8 @@ class Processer {
   // returns: { new_tickets }
   async complete(params) {
     const { valve_id, tickets } = params;
-    // pool.getNext → 入口池 tickets 更新为 finished → 按出口池映射 new_tickets
-    // 由引擎自动创建，不在脚本内调用 ticket.append
+    // 获取出口池 → 入口池 tickets 更新为 finished → 按出口池映射 new_tickets
+    // 由引擎自动创建，脚本不直接追加 tickets
     return { new_tickets };
   }
 }
@@ -173,8 +173,8 @@ class Processer {
 
 ## 执行流程
 
-1. **start 阶段**：`ticket.list` 按 `pool_id__in`（由 `Processer` 入参 `pool_ids` 映射）拉数，**取返回体 `list` 字段** → 按需拉化合物库 → 写回 `detail` → `ticket.update`。
-2. **complete 阶段**：`pool.getNext` 取出口池 → `ticket.update` / `ticket.append`。
+1. **start 阶段**：按 [agentic-lab-sdk.md](agentic-lab-sdk.md) 查询入口池数据 → 按需调用其他 SDK 方法查询外部数据 → 写回 `detail` → 按 SDK 更新 tickets。
+2. **complete 阶段**：按 [agentic-lab-sdk.md](agentic-lab-sdk.md) 获取出口池 → 更新入口池 ticket 状态 → 映射出口池 `new_tickets`。
 
 ## 输入/输出
 

package/skills/lab-flow-designer/references//344/270/232/345/212/241/346/265/201/347/250/213/346/226/207/346/241/243/346/240/207/345/207/206.md

@@ -105,7 +105,7 @@
 5. **数据处理规则表**（强烈推荐）：列至少包含 **`序号` | `规则摘要` | `条件要点` | `业务动作或结果`**；序号建议 **章内连续小数编号**（如 `1.1`、`1.2`，与门控章节号前缀一致），便于脚本注释逐条对应。  
 6. **操作员步骤**（若为人工门控）：编号列表，步骤可执行、可验收。
 
-**Process 批量提交（可选）**：若门控需触发 **Rhea / 设备侧批量提交任务**，须在流程文档中写明调用时机、**`items` 每条**中的 **`process`（流程模板名，即 process_name 语义）**、**`params` / `table_objects` 等如何从业务数据拼装**，以及 **`baseURL`（服务根地址）的语义来源**（配置、环境变量、订单字段等，由集成解析为字符串 URL）。**path、HTTP 方法** 由 SDK 固定，流程文档**不要求**写 path / method；生成脚本时映射为 **`this.context.process.execute(items, baseURL)`**（见 [`references/agentic-lab-sdk.md`](agentic-lab-sdk.md)；Wire 细节见 [`references/rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md) 供预检对照 `items[]` 形状）。
+**Process 批量提交（可选）**：若门控需触发 **Rhea / 设备侧批量提交任务**，须在流程文档中写明调用时机、**`items` 每条**中的 **`process`（流程模板名，即 process_name 语义）**、**`params` / `table_objects` 等如何从业务数据拼装**，以及 **`baseURL`（服务根地址）的语义来源**（配置、环境变量、订单字段等，由集成解析为字符串 URL）。**path、HTTP 方法** 由 SDK 固定，流程文档**不要求**写 path / method；生成脚本时映射为 SDK 中对应方法（见 [`references/agentic-lab-sdk.md`](agentic-lab-sdk.md)；Wire 细节见 [`references/rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md) 供预检对照 `items[]` 形状）。
 
 **检查点**：每个 `output` 条件互斥或可判定优先级在文中有说明；缺料/失败等异常分支有定义。  
 **检查点**：`input.secondary` 存在时，§4 文字补充中已描述合流。
@@ -154,12 +154,12 @@
 
 ### 3.3 Process / 任务提交 / 其它 SDK 调用的参数与格式
 
-凡流程文档出现 **Process 执行、批量任务提交、`process.execute`、或任何明确绑定 SDK 的写操作/查询参数**，除满足 **§2.5 Process 批量提交** 小节外，还须满足（否则预检 **不通过**）：
+凡流程文档出现 **Process 执行、批量任务提交、或任何明确绑定 SDK 的写操作/查询参数**，除满足 **§2.5 Process 批量提交** 小节外，还须满足（否则预检 **不通过**）：
 
-1. **方法名**：与 **agentic-lab-sdk** 中条目一致（如 `process.execute`、`process.list`、`ticket.list` 等），且用途与文档叙述一致。  
-2. **请求体与类型**：对 **`process.execute`**，须能整理出 **`items[]`**（与 **[`rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md)** 请求体中 `items` 一项同形）：每条至少含 **`process`**、**`params`**（键、类型、默认值或来源字段）；若流程需绑定业务表记录，则须说明 **`table_objects`**（表名、主键与 ticket 明细的对应）；并须说明 **`baseURL`** 如何得到；**禁止**仅写「组装 JSON」而无键级说明。  
-3. **查询类接口**：若使用 `ticket.list`、`compound.getStock` 等，分页策略须与流程说明及 skill「门控脚本编写指引」一致或显式写出 `limit`/`offset`；**`filter`** 须说明字段名与算子意图，避免无法落地的自然语言。  
-4. **`process.execute` 与 HTTP**：流程文档约束 **`items`**、**`baseURL` 语义**及任务参数；**不要求**写 path / HTTP 方法（由 SDK 封装）。
+1. **方法名**：与 [agentic-lab-sdk.md](agentic-lab-sdk.md) 中条目一致，且用途与文档叙述一致。  
+2. **请求体与类型**：对 **Process 批量提交**，须能整理出 **`items[]`**（与 **[`rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md)** 请求体中 `items` 一项同形）：每条至少含 **`process`**、**`params`**（键、类型、默认值或来源字段）；若流程需绑定业务表记录，则须说明 **`table_objects`**（表名、主键与 ticket 明细的对应）；并须说明 **`baseURL`** 如何得到；**禁止**仅写「组装 JSON」而无键级说明。  
+3. **查询类接口**：分页策略须与 [agentic-lab-sdk.md](agentic-lab-sdk.md) 中该方法的分页方式一致或显式写出分页参数；**`filter`** 须说明字段名与算子意图，避免无法落地的自然语言。  
+4. **Process 批量提交与 HTTP**：流程文档约束 **`items`**、**`baseURL` 语义**及任务参数；**不要求**写 path / HTTP 方法（由 SDK 封装）。
 
 **预检产出**：凡属 **§3.2 / §3.3** 的不通过项，须在《流程文档合规问题与优化建议》中单独列出 **「不支持或不可生成项」**，避免进入代码生成阶段才发现无法对接。
 
@@ -194,8 +194,8 @@
 - §3 → `pools/*.md` 文件名与 Schema；  
 - §4 + §5 → 根 `SKILL.md` 流程图与**连接关系**列表；  
 - §5 → `valves/*.md`、`scripts/*.js` 及规则注释序号；  
-- §2、字段映射、查询方式 → 脚本内 `ticket.detail` 与 `compound.*` 等调用；  
-- 流程中若需 **Process 批量提交** → 脚本内 **`this.context.process.execute(items, baseURL)`**（参数以流程文档为准，见 `references/agentic-lab-sdk.md` 与 `references/rhea-api/execute_process_batch.md`）。
+- §2、字段映射、查询方式 → 脚本内 `ticket.detail` 与按 [agentic-lab-sdk.md](agentic-lab-sdk.md) 调用对应方法；  
+- 流程中若需 **Process 批量提交** → 脚本内按 SDK 对应方法执行（参数以流程文档为准，见 `references/agentic-lab-sdk.md` 与 `references/rhea-api/execute_process_batch.md`）。
 
 主 `SKILL.md` 中 **门控脚本编写指引** 约定：生成 `scripts/*.js` 与 `pools/*.md` Schema 时，**仅实现或收录流程文档在本门控逻辑或池字段描述中明确写出的**查询、回写、路由与字段行，**禁止**为对齐 embedded 示例而附加未文档化的代码或字段。
 

package/skills/lab-flow-designer/templates//344/270/232/345/212/241/346/265/201/347/250/213/346/226/207/346/241/243/347/244/272/344/276/213.md

@@ -135,9 +135,9 @@ output:
 
 **化合物数据查询方式**
 
-查询化合物库的可用量：使用输入池 Compound ID 作为索引，查询 compound 表的 CAS 字段，查找 status = 可用的记录，返回 latest amount 字段的值并汇总加和。
+查询化合物库存的可用量：使用输入池 Compound ID 作为索引，通过 XFC 上海系统接口查询化合物库存（`compound.getStockFromXfcSh`），查找 status = 可用的记录，返回可用量字段的值并汇总加和。
 
-查询化合物知识库属性：使用输入池 Compound ID 查询 chemical_record 表，返回舀粉相关属性。
+查询化合物属性：使用输入池 Compound ID 通过 XFC 上海系统接口查询化合物相关属性。
 
 **字段映射表**
 

package/skills/lab-flow-designer/testing/test-processer.mjs

@@ -212,7 +212,7 @@ function generateMockTickets(pools, valveConfig, adversarial) {
 const KNOWN_SDK_NAMESPACES = new Set(['ticket', 'pool', 'compound', 'process', 'station']);
 
 const PAGINATED_METHODS = new Set([
-  'ticket.list', 'process.list', 'compound.getStock', 'compound.getChemicalRecord',
+  'ticket.list', 'process.list', 'compound.getStockFromXfcSh',
 ]);
 
 function createMockContext(pools, valveConfig, adversarial) {
@@ -250,31 +250,14 @@ function createMockContext(pools, valveConfig, adversarial) {
       },
     },
     compound: {
-      getStock: async (params) => {
-        callLog.push({ method: 'compound.getStock', params });
-        if (params?.limit === undefined) {
-          warnings.push('compound.getStock called without explicit limit');
-        }
-        return [1, 2].map(i => ({
-          id: i, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
-          cas: `12345-67-${i}`, barcode: `BC-MOCK-${i}`, cmpd_id: `CA${1000 + i}`,
-          status: 'available', latest_amount_mg: 50 * i, latest_weight: 10 * i,
-          chemical_name: `MockChemical${i}`,
-        }));
-      },
-      getChemicalRecord: async (params) => {
-        callLog.push({ method: 'compound.getChemicalRecord', params });
-        if (params?.limit === undefined) {
-          warnings.push('compound.getChemicalRecord called without explicit limit');
-        }
-        return [1, 2].map(i => ({
-          id: i, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
-          compound_id: `12345-67-${i}`, cmpd_id: `CA${1000 + i}`,
-          dispensable: i % 2 === 0, chemist_property: ['solid'],
-          dispensing_remark: [], large_particle: false, hygroscopicity: false,
-          agglomeration_tendency: false, sticky: false,
-          strong_electrostatic_adsorption: false,
+      getStockFromXfcSh: async (params) => {
+        callLog.push({ method: 'compound.getStockFromXfcSh', params });
+        const data = [1, 2].map(i => ({
+          id: i, cas: `12345-67-${i}`, status: '可用',
+          source: 'MockSupplier', barcode: `XFC-MOCK-${i}`,
+          cmpd_id: `CA${1000 + i}`, owner: 'mock@example.com',
         }));
+        return { data, meta: { count: data.length, page: 1, pageSize: 400, totalPage: 1 } };
       },
     },
     process: {
@@ -390,6 +373,17 @@ function loadProcesserClass(scriptContent, filename) {
     Promise, Array, Object, Map, Set, JSON, Math, Date,
     Number, String, Boolean, RegExp, Error, TypeError, ReferenceError,
     parseInt, parseFloat, isNaN, isFinite, undefined, NaN, Infinity,
+    encodeURIComponent, decodeURIComponent, encodeURI, decodeURI,
+    fetch: async (url, opts) => {
+      const method = (opts && opts.method) || 'GET';
+      sandbox.console.warn(`[test-processer] fetch called: ${method} ${url}`);
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ data: {} }),
+        text: async () => '{}',
+      };
+    },
   };
   const ctx = createContext(sandbox);
   return script.runInContext(ctx);
@@ -551,25 +545,14 @@ function createTracingContext(pools, valveConfig, tickets) {
       },
     },
     compound: {
-      getStock: async (params) => {
-        const result = [1, 2].map(i => ({
-          id: i, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
-          cas: `12345-67-${i}`, barcode: `BC-MOCK-${i}`, cmpd_id: `CA${1000 + i}`,
-          status: 'available', latest_amount_mg: 50 * i, latest_weight: 10 * i,
-          chemical_name: `MockChemical${i}`,
+      getStockFromXfcSh: async (params) => {
+        const data = [1, 2].map(i => ({
+          id: i, cas: `12345-67-${i}`, status: '可用',
+          source: 'MockSupplier', barcode: `XFC-MOCK-${i}`,
+          cmpd_id: `CA${1000 + i}`, owner: 'mock@example.com',
         }));
-        traceLog.push({ seq: seq++, method: 'compound.getStock', params: JSON.parse(JSON.stringify(params || {})), returnSummary: `${result.length} records` });
-        return result;
-      },
-      getChemicalRecord: async (params) => {
-        const result = [1, 2].map(i => ({
-          id: i, createdAt: '2026-01-01T00:00:00Z', updatedAt: '2026-01-01T00:00:00Z',
-          compound_id: `12345-67-${i}`, cmpd_id: `CA${1000 + i}`,
-          dispensable: i % 2 === 0, chemist_property: ['solid'],
-          dispensing_remark: [], large_particle: false, hygroscopicity: false,
-          agglomeration_tendency: false, sticky: false, strong_electrostatic_adsorption: false,
-        }));
-        traceLog.push({ seq: seq++, method: 'compound.getChemicalRecord', params: JSON.parse(JSON.stringify(params || {})), returnSummary: `${result.length} records` });
+        const result = { data, meta: { count: data.length, page: 1, pageSize: 400, totalPage: 1 } };
+        traceLog.push({ seq: seq++, method: 'compound.getStockFromXfcSh', params: JSON.parse(JSON.stringify(params || {})), returnSummary: `${data.length} records` });
         return result;
       },
     },
@@ -743,7 +726,7 @@ function formatPreviewReport(trace) {
   const allCalls = [...startTraceLog, ...completeTraceLog];
   const usedMethods = new Set(allCalls.map(c => c.method));
   const allMethods = ['ticket.list', 'ticket.update', 'ticket.append', 'pool.getNext',
-    'compound.getStock', 'compound.getChemicalRecord', 'process.list', 'process.execute', 'station.list'];
+    'compound.getStockFromXfcSh', 'process.list', 'process.execute', 'station.list'];
   const unused = allMethods.filter(m => !usedMethods.has(m));
 
   const startStatus = startError ? `✗ 失败: ${startError.split('\n')[0]}` : `✓ 成功 (${startTraceLog.length} SDK 调用, ${inputTickets.length} tickets)`;
@@ -1003,6 +986,16 @@ async function runTests(args) {
         );
       }
     }
+
+    // Check for sandbox-unavailable APIs in source code
+    const UNAVAILABLE_APIS = ['URLSearchParams', 'TextEncoder', 'TextDecoder', 'Buffer'];
+    for (const api of UNAVAILABLE_APIS) {
+      if (scriptContent.includes(api)) {
+        result.phases.compliance.warnings.push(
+          `Script uses '${api}' which is not available in the gate script sandbox — use template literals + encodeURIComponent instead`
+        );
+      }
+    }
   }
 
   const normalPass = result.phases.normalRun.start.pass && result.phases.normalRun.complete.pass;