@xtalpi/agentic-lab-skills 0.0.8 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/package.json +1 -1
  2. package/skills/lab-flow-designer/SKILL.md +16 -23
  3. 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 +9 -9
  4. package/skills/lab-flow-designer/references/agentic-lab-processer.md +15 -39
  5. package/skills/lab-flow-designer/references/agentic-lab-sdk.md +88 -0
  6. package/skills/lab-flow-designer/references/skill-package-layout.md +5 -5
  7. 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 +8 -8
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xtalpi/agentic-lab-skills",
3
- "version": "0.0.8",
3
+ "version": "0.0.9",
4
4
  "description": "Agentic Lab Skills",
5
5
  "license": "MIT",
6
6
  "author": "TheoXiong",
package/skills/lab-flow-designer/SKILL.md CHANGED
@@ -83,7 +83,7 @@ metadata:
83
83
  - **必须**向用户交付 **《流程文档合规问题与优化建议》**（可用 Markdown 小节组织），且至少包含：
84
84
  1. **问题清单**：每条对应标准中的位置（例如「§4 清单第 n 项」「§3.2 不支持的 API」「§3.3 `items` 结构不完整」）。
85
85
  2. **现状说明**：流程文档中**缺失**、**矛盾**、**模糊**或**不可解析**之处（可引用现有标题、表格列名、YAML 片段；对不支持的依赖/API/字段须**点名**）。
86
- 3. **可执行修改建议**：具体应**补写/改写**哪一类内容（例如消除模糊条件、改为 SDK 已支持方法、补全 `process.execute` 的 `items`/`params`/`baseURL` 说明、统一字段拼写）。
86
+ 3. **可执行修改建议**：具体应**补写/改写**哪一类内容（例如消除模糊条件、改为 SDK 已支持方法、补全 SDK 调用方法的参数说明、统一字段拼写）。
87
87
  4. **严重程度**：**阻断**（不满足则无法稳定生成，含不支持的 API、不可判定逻辑、Process 参数无法落地）与**建议**（不阻断但易导致脚本/Schema 歧义）。
88
88
  5. **（若适用）不支持或不可生成项**：集中列出标准 **§3.2 / §3.3** 拦截项，避免与一般格式问题混排。
89
89
  - 仅当用户**随后**提供已按建议修订的流程文档时，才允许重新从本预检开始执行。
@@ -119,7 +119,7 @@ metadata:
119
119
  - 数据来源与操作按钮描述
120
120
  - **后置处理** → 生成 `Processer.complete` 函数逻辑。须提取：
121
121
  - 规则摘要表（条件要点 + 业务动作），落入 `complete` 函数体
122
- - 提交参数结构（如 `process.execute` 的 `items` 定义与 `params` 键级说明）
122
+ - 提交参数结构（如 SDK 调用方法的参数定义与键级说明）
123
123
  - 出口池路由条件与字段映射
124
124
  - **门控脚本配置项**：提取全局配置表中的各项，落入脚本为**模块级常量**：
125
125
  - `PageUrl`（含 `{bookid}` 占位符）→ 脚本常量 `PAGE_URL`
@@ -161,7 +161,7 @@ metadata:
161
161
 
162
162
  - **`### 数据池（Pool）`**：说明 Pool 存记录、每池有独立 Schema、随阶段变化。
163
163
  - **`### 门控（Valve）`**：说明每个 Valve 对应脚本、`Processer` 的 `start` / `complete` 职责分工。
164
- 另起简短列表说明执行引擎通过 `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.getStockFromXfcSh`），**不要**抄写模板里已过期的成员名。
164
+ 另起简短列表说明执行引擎通过 `this.context` 暴露的能力，**仅写** [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)「可用方法一览」中已列出的方法名（按流程实际使用选取），**不要**抄写模板里已过期的成员名。
165
165
 
166
166
  #### 3.4 `## 流程图`（本节内须含「连接关系」列表，与模板一致）
167
167
 
@@ -238,11 +238,11 @@ metadata:
238
238
 
239
239
  若流程说明对某门控给出了下列块，须在对应 `valves/<基名>.md` 中**原样结构化呈现**（标题可用 `##` / `###`，便于脚本作者对照）：
240
240
 
241
- - **门控 YAML**（`valve_id`、`name`、`order`、`input`、`output`）；若文档使用 `Stash:` 等非标准键表示目标池，**保留原文**，并在 valve 文内加一句说明：实现时与 `pool.getNext` 返回的 `pool.name` 按**池显示名称**匹配。
241
+ - **门控 YAML**（`valve_id`、`name`、`order`、`input`、`output`）；若文档使用 `Stash:` 等非标准键表示目标池，**保留原文**，并在 valve 文内加一句说明：实现时按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 获取出口池，以返回的 `pool.name` 与**池显示名称**匹配。
242
242
  - **前置处理**（对应 `start`）：提取配置项（如 `bookid`）、规则摘要表，说明 `start` 函数需执行的逻辑。
243
243
  - **人工处理**：界面形态与数据绑定描述（仅供参考，不由门控脚本实现）。
244
- - **后置处理**（对应 `complete`）：规则摘要表、提交参数结构（如 `process.execute` 的 `items` 定义），说明 `complete` 函数需执行的逻辑。
245
- - **化合物数据查询方式**（或等价标题）：表或段落中「查化合物库存」等表述，与 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中 `compound.getStockFromXfcSh` 的对应关系写清。
244
+ - **后置处理**（对应 `complete`）：规则摘要表、提交参数结构（如 SDK 调用方法的参数定义），说明 `complete` 函数需执行的逻辑。
245
+ - **化合物数据查询方式**（或等价标题）：表或段落中「查化合物库存」等表述，与 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中对应 SDK 方法的映射关系写清。
246
246
  - **字段映射表**：「门控加工数据 ↔ 库字段 / API 字段」；脚本写入 `ticket.detail` 的键须与 **pools Schema「字段」列（snake_case）** 一致。
247
247
  - **数据处理规则**表：序号（如 1.1、1.2）须在脚本注释中可逐条追溯。
248
248
 
@@ -272,25 +272,20 @@ metadata:
272
272
 
273
273
  | 来源 | 落点（脚本侧） |
274
274
  |------|----------------|
275
- | 门控 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` |
276
- | 门控 YAML `output` | `complete` 中 `await this.context.pool.getNext(valve_id)` 后按 `pool.name` 与条件分支筛选目标池 |
277
- | **化合物数据查询方式** | `compound.getStockFromXfcSh`：入参为可选 **`filter`**（**dot-notation** 格式，如 `{ 'cas.$in': [...] }`，不传默认筛选 `status = '可用'`）+ 可选 `fields`/`pageSize`/`page`；返回 `{ data, meta }` 结构，取 **`.data`** 获取数据数组；见 [agentic-lab-sdk](references/agentic-lab-sdk.md) |
275
+ | 门控 YAML `input` | `start` 中按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 查询入口池 tickets（`limit`/`offset` 遵守 §2）；含 `secondary` 时合并多个入口池 ID |
276
+ | 门控 YAML `output` | `complete` 中按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 获取出口池，以 `pool.name` 与条件分支筛选目标池 |
277
+ | **化合物数据查询方式** | 按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 调用化合物库存查询方法 |
278
278
  | **字段映射表** | 将 API 返回字段写入 `ticket.detail` 的 snake_case 键 |
279
279
  | **数据处理规则**（序号表） | `start` 内计算与回填，或 `complete` 内最终路由前校验；关键分支写 `// 规则 1.x` 注释 |
280
280
  | **门控脚本配置项**表 | 脚本模块级常量：`PAGE_URL`（取 `PageUrl` 值）、`DEFAULT_QUERY_LIMIT`（取入口池查询上限，缺省 `999999`）、`STATION_BASE_URL`（若有）；**各门控前置处理**配置中的 `bookid` → `BOOK_ID`（每个门控独立值） |
281
281
 
282
282
  ### 2. 分页与「查全量」（`limit` / `offset`）
283
283
 
284
- 凡 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中带 **`limit`** / **`offset`** 的查询（如 **`ticket.list`**、**`process.list`**），生成门控脚本时遵守：
284
+ 凡 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)「可用方法一览」中标注使用 `limit` / `offset` 分页的查询方法，生成门控脚本时遵守：
285
285
 
286
- > **注意**：`compound.getStockFromXfcSh` 使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值，不适用下述 `limit: 999999` 约定。
287
-
288
- 1. **流程说明未写分页**：未出现「每页/只查前/offset/limit/条数上限」等明确要求时，**默认**显式传入 **`limit: 999999`**、**`offset: 0`**（可用模块级常量如 `DEFAULT_QUERY_LIMIT`），避免依赖引擎默认小页长导致**截断漏数据**。**例外**：若流程文档**门控脚本配置项**表中写明了入口池查询上限（如 `门控脚本对入口池单次查询上限: 9000`），以该值作为 `DEFAULT_QUERY_LIMIT`，不使用默认 `999999`。
289
286
  2. **流程说明写了分页**：按文档给出的 `limit`、`offset`（或等价参数名）原样写入调用。
290
287
  3. **流程说明写了「查全部/不限制条数」及具体数值**（例如明确要求 `limit: 500000`）：**以流程文档为准**，不得擅自改为 `999999`。
291
288
 
292
- `pool.getNext`、`station.list` 等无分页参数的调用不受影响。
293
-
294
289
  ### 3. `start` 与 `complete` 分工（与门控三阶段对齐）
295
290
 
296
291
  门控执行顺序为 **前置处理（脚本）→ 人工处理（页面）→ 后置处理（脚本）**。`start` 对应**前置处理**，`complete` 对应**后置处理**。
@@ -301,16 +296,16 @@ metadata:
301
296
  - **`start` 返回** `StartExecutionResult`：**必须**含 `orbit_link`（`string`）、`ticket_ids`（`number[]`）。
302
297
  - **`complete` 入参** `CompleteExecutionParams`：**必须**含 `valve_id`（`number`）、`tickets`（`Record<string, any>[]`）。
303
298
  - **`complete` 返回** `CompleteExecutionResult`：通过 `new_tickets`（`Record<string, any>[]`，可选）返回待写入出口池的工单，由引擎自动创建。
304
- - **一级参数与返回值键名一律 snake_case**（如 `valve_id`、`pool_ids`、`ticket_ids`、`orbit_link`、`new_tickets`），**禁止** camelCase（如 ~~`ticketIds`~~、~~`poolIds`~~）。嵌套数据（如 `ticket.detail` 内容、`process.execute` 的 `params`/`items` 等 JSON 结构）保持流程文档或 API 原有格式，不受此约束。
299
+ - **一级参数与返回值键名一律 snake_case**（如 `valve_id`、`pool_ids`、`ticket_ids`、`orbit_link`、`new_tickets`），**禁止** camelCase（如 ~~`ticketIds`~~、~~`poolIds`~~）。嵌套数据（如 `ticket.detail` 内容、SDK 方法的 `params`/`items` 等 JSON 结构）保持流程文档或 API 原有格式，不受此约束。
305
300
 
306
- - **`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.getStockFromXfcSh`（返回 `{ data, meta }`，取 `.data` 获取数组）、`process.list`、`station.list`（缺则**不调**）→ **仅按**数据处理规则与映射更新 `ticket.detail` 中**文档涉及的键** → `ticket.update`（若确有写回）→ 拼装 `orbit_link`（见下方步骤）→ 返回 `{ orbit_link, ticket_ids }` 。
301
+ - **`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 }` 。
307
302
 
308
303
  **`orbit_link` 生成步骤**：
309
304
  1. 从**门控脚本配置项**表提取 `PageUrl`（含 `{bookid}` 占位符），写为脚本模块级常量 `PAGE_URL`
310
305
  2. 从该门控**前置处理**配置项中提取 `bookid` 值，写为脚本模块级常量 `BOOK_ID`
311
306
  3. `start` 函数末尾拼装：`const orbit_link = PAGE_URL.replace('{bookid}', BOOK_ID)`
312
307
 
313
- - **`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`）。
308
+ - **`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）。
314
309
 
315
310
  ### 4. 运行环境约束（沙箱可用全局对象）
316
311
 
@@ -345,7 +340,7 @@ metadata:
345
340
  const qs = new URLSearchParams({ view_id: viewId, page_size: '500' });
346
341
  ```
347
342
 
348
- 2. **外部 HTTP 调用**——优先使用 `this.context` SDK 方法（`ticket.list`、`compound.getStockFromXfcSh` 等）。仅当流程文档要求调用 SDK 未覆盖的第三方 API（如飞书/Lark）时，才使用 `fetch`；此时 URL 手动拼接，**不依赖** `URLSearchParams`。
343
+ 2. **外部 HTTP 调用**——优先使用 `this.context` SDK 方法（见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)）。仅当流程文档要求调用 SDK 未覆盖的第三方 API（如飞书/Lark）时，才使用 `fetch`；此时 URL 手动拼接，**不依赖** `URLSearchParams`。
349
344
 
350
345
  3. **JSON 序列化**——`JSON.stringify` / `JSON.parse` 可用（`JSON` 在沙箱白名单中）。
351
346
 
@@ -374,9 +369,9 @@ metadata:
374
369
  ### 6. 参考代码（按优先序打开）
375
370
 
376
371
  1. [references/agentic-lab-processer.md](references/agentic-lab-processer.md)（**`Processer` 类型定义与代码风格**参考；`start`/`complete` 输入输出类型、snake_case 命名）
377
- 2. [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js)（**结构与分页约定**参考；compound / `pool.getNext` / `ticket` 等**仅当本门控文档需要时**才纳入生成，勿默认照抄示例中的全部调用；**列表类查询默认 `limit: 999999`**）
372
+ 2. [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js)（**结构与分页约定**参考；SDK 方法**仅当本门控文档需要时**才纳入生成，勿默认照抄示例中的全部调用；**列表类查询默认 `limit: 999999`**）
378
373
  3. [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)
379
- 4. 多门控流程：按拓扑为每个门控各写一对 `valves/<基名>.md` 与 `scripts/<基名>.js`，API 与分页约定同上；勿使用 `agentic-lab-sdk.md` 未列出的 `context` 成员（如旧代码中的 `processe` 等，应使用 **`process.list`**）。
374
+ 4. 多门控流程：按拓扑为每个门控各写一对 `valves/<基名>.md` 与 `scripts/<基名>.js`，API 与分页约定同上；勿使用 `agentic-lab-sdk.md` 未列出的 `context` 成员。
380
375
 
381
376
  ### 7. 产物版本追踪
382
377
 
@@ -455,8 +450,6 @@ console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__}
455
450
  **流程来源**：若该包为 **初次生成** 产物，源流程文档应已通过 **「流程文档合规预检」**；复查可对照 [references/业务流程文档标准.md](references/业务流程文档标准.md) §4。**迭代修改**路径无此强制要求。
456
451
  **结构清单**：根目录 `SKILL.md`（合法 `name`/`description`、固定二级标题：`概述`、`核心概念`、`流程图`、`节点清单`、`门控执行规范`、`使用方式`）、`**连接关系：**`、`### Pool 节点` / `### Valve 节点`、`Processer` 类与门控执行规范代码块、存在 `pools/` / `valves/` / `scripts/`、`valves` 与 `scripts` 同名成对、任取一个 `pools/*.md` 的 Schema 表头含 **字段** / **字段标题** / **属性** 且数据行「字段」列为 snake_case。
457
452
 
458
- **人工抽查**：生成脚本里 `ticket.list`、`process.list` 在无流程分页说明时是否传入 **`limit: 999999`**（或流程说明指定的查全量数值），见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 篇首约定。`compound.getStockFromXfcSh` 使用 `pageSize`/`page` 分页，不传时使用 API 默认值。
459
-
460
453
  **版本追踪**：`SKILL.md` frontmatter 含 `metadata.version` / `metadata.generated_by` / `metadata.generated_at`；每个 `scripts/*.js` 含 `__ARTIFACT_VERSION__` 常量（值与 `metadata.version` 一致）和 `__ARTIFACT_SKILL__` 常量；`Processer` constructor 含 `console.info` 版本打印。
461
454
 
462
455
  **对照物**：[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/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 CHANGED
@@ -12,7 +12,7 @@
12
12
 
13
13
  ## 门控 YAML（与流程说明对齐）
14
14
 
15
- 流程说明中可能使用 `Stash:` 等键表示目标池；生成脚本时以 **`pool.name`**（或文档中的池显示名称）与 `pool.getNext(valve_id)` 返回值匹配（`valve_id` 来自 `Processer` 入参）。
15
+ 流程说明中可能使用 `Stash:` 等键表示目标池；生成脚本时按 [agentic-lab-sdk.md](../../references/agentic-lab-sdk.md) 获取出口池，以返回的 **`pool.name`**（或文档中的池显示名称）匹配目标池（`valve_id` 来自 `Processer` 入参）。
16
16
 
17
17
  ```yaml
18
18
  valve_id: valve_example_1
@@ -29,7 +29,7 @@ output:
29
29
 
30
30
  | 流程说明中的表述 | 推荐 SDK 调用 |
31
31
  |----------------|---------------|
32
- | 查化合物库存 / 可用量 / 库存汇总 | `context.compound.getStockFromXfcSh({ filter })`；filter 使用 **dot-notation** 格式（如 `{ 'cas.$in': [...] }`）；返回 `{ data, meta }`，取 **`.data`** 获取数据数组；不传 filter 时默认筛选 `status = '可用'`。另见 [agentic-lab-sdk](../../references/agentic-lab-sdk.md) |
32
+ | 查化合物库存 / 可用量 / 库存汇总 | 按 [agentic-lab-sdk.md](../../references/agentic-lab-sdk.md) 中的化合物库存查询方法 |
33
33
 
34
34
  ## 字段映射（示例：知识库 → ticket.detail）
35
35
 
@@ -52,7 +52,7 @@ output:
52
52
  | 序号 | 规则摘要 | 业务动作（示意） |
53
53
  |------|----------|------------------|
54
54
  | 1.1 | 汇总需求量 | `detail.requested_amount = sum(target_amount_n)` |
55
- | 1.2 | 缺料判定 | 结合 `getStockFromXfcSh` 汇总可用量与 `requested_amount` 比较 |
55
+ | 1.2 | 缺料判定 | 结合化合物库存查询（SDK）汇总可用量与 `requested_amount` 比较 |
56
56
  | 1.3 | 容差默认 | 目标量 >0 且容差空 → 默认 0.5 mg |
57
57
  | 1.4 | 缺料标记 | `source_barcode` 空 → `是否缺料` = 缺料 |
58
58
 
@@ -68,9 +68,9 @@ output:
68
68
 
69
69
  | 规则摘要 | 条件要点 | 业务动作或结果 |
70
70
  | -------- | -------- | -------------- |
71
- | 查询入口池 | 门控启动 | `ticket.list({ pool_id__in: pool_ids, limit: 999999, offset: 0 })`，取返回体 `list` |
72
- | 查化合物数据 | 有 compound 查询需求 | `compound.getStockFromXfcSh`（不传分页参数，使用 API 默认值） |
73
- | 写回 detail | 查询完成 | 按映射表与规则表写回 `ticket.detail` → `ticket.update` |
71
+ | 查询入口池 | 门控启动 | 按 SDK 查询入口池 tickets（分页遵守主 SKILL.md 编写指引 §2） |
72
+ | 查化合物数据 | 有 compound 查询需求 | 按 SDK 查询化合物库存数据 |
73
+ | 写回 detail | 查询完成 | 按映射表与规则表写回 `ticket.detail` → 按 SDK 更新 tickets |
74
74
  | 拼装 orbit_link | 返回前 | `PageUrl.replace('{bookid}', bookid)` |
75
75
 
76
76
  **start 返回**：`{ orbit_link, ticket_ids }`
@@ -87,11 +87,11 @@ output:
87
87
 
88
88
  | 规则摘要 | 条件要点 | 业务动作或结果 |
89
89
  | -------- | -------- | -------------- |
90
- | 获取出口池 | `pool.getNext(valve_id)` | 按 `pool.name` 匹配出口池 |
91
- | 更新入口池状态 | 出口池确定 | 入口池 tickets 更新为 `status: 'finished'` → `ticket.update` |
90
+ | 获取出口池 | 按 SDK 获取出口池 | 按 `pool.name` 匹配出口池 |
91
+ | 更新入口池状态 | 出口池确定 | 入口池 tickets 更新为 `status: 'finished'` → 按 SDK 更新 tickets |
92
92
  | 映射出口池记录 | 状态更新完成 | 按出口池 Schema 构建 `new_tickets`（含 `flow_id`、`pool_id`、`order_id`、`detail`、`status: 'created'`、`parent_ticket_id`） |
93
93
 
94
- **complete 返回**：`{ new_tickets }`（由引擎自动创建，脚本不调用 `ticket.append`）
94
+ **complete 返回**：`{ new_tickets }`（由引擎自动创建，脚本不直接追加 tickets）
95
95
 
96
96
  ## 输入/输出
97
97
 
package/skills/lab-flow-designer/references/agentic-lab-processer.md CHANGED
@@ -1,4 +1,6 @@
1
1
  > Agentic Lab 门控脚本
2
+ >
3
+ > `this.context` 上可用的 SDK 方法详见 [agentic-lab-sdk.md](agentic-lab-sdk.md)。本文件仅定义 `Processer` 类的 `start`/`complete` 输入输出类型与代码风格。
2
4
 
3
5
  ### 类型定义
4
6
 
@@ -50,53 +52,27 @@ class Processer {
50
52
 
51
53
  // params: { valve_id, pool_ids }
52
54
  async start(params) {
53
- const tickets = await this.context.ticket.list({ pool_id__in: pool_ids });
54
- const stations = await this.context.station.list();
55
-
56
- const process_ids = []; // 从tickets detail 按需提取出process ids
57
- const processes = await this.context.process.list({ process_ids });
58
-
59
- // 基于stations、processes等数据源，筛选待处理tickets
60
- const finalTickets = tickets.filter(ticket => ticket);
61
-
62
- // 将processes更新到finalTickets detail中
63
- finalTickets.forEach(ticket => { ticket.detail.processes = processes })
64
- // 更新数据库中的tickets，以便Orbit视图获取最新数据
65
- await this.context.ticket.update(finalTickets)
66
-
55
+ // 按 agentic-lab-sdk.md 查询入口池数据
56
+ // 按需调用 SDK 方法查询化合物/工站/流程等外部数据
57
+ // 将查询结果写回 ticket.detail
58
+ // 按 agentic-lab-sdk.md 更新 tickets
67
59
  return {
68
- orbit_link: 'https://orbit-sh.xtalpi.xyz/?view=book&book=3947',
69
- ticket_ids: finalTickets.map(ticket => ticket.id),
60
+ orbit_link: 'https://...',
61
+ ticket_ids: [/* 待处理 ticket ID */],
70
62
  }
71
63
  }
72
64
 
73
65
  // params: { valve_id, tickets }
74
66
  async complete(params) {
75
- // params.tickets 已包含本次待处理的人工录入数据，通常无需重新查询；如需补充数据库数据请按实际需求调用查询方法
76
-
77
- // 获取当前门控的（一个或多个）出口池
78
- const nextPools = this.context.pool.getNext(valveId);
79
- const successPool = nextPools.find(pool => pool.name === 'xxx成功');
80
- const failedPool = nextPools.find(pool => pool.name === 'xxx失败');
81
-
82
- // 基于实时tickets，按实际业务场景(流程说明书中的相关定义)，筛选出“可流入出口池”的tickets
83
- const finalTickets = params.tickets.filter(ticket => ticket).map(t => ({ ...t, status: 'finished' }));
84
-
85
- // 将入口池的tickets更新为“已完成”状态，避免重复处理
86
- await this.context.ticket.update(finalTickets);
87
-
88
- // 按实际的业务场景(流程说明书中的相关定义)， 筛选出“可流入成功出口池”的tickets，并按出口池的schema 映射为新的tickets
89
- const newSuccessTickets = finalTickets.filter(ticket => ticket).map(t => ({ ...t, status: 'created', pool_id: successPool.id }));
90
- // 按实际的业务场景(流程说明书中的相关定义)， 筛选出“可流入失败出口池”的tickets，并按出口池的schema 映射为新的tickets
91
- const newFailedTickets = finalTickets.filter(ticket => ticket).map(t => ({ ...t, status: 'created', pool_id: failedPool.id }));
92
-
93
- // 脚本不负责创建新ticket，交由引擎自动创建（需返回new_tickets）
67
+ // 按 agentic-lab-sdk.md 获取出口池
68
+ // 按业务规则筛选可流入出口池的 tickets
69
+ // 将入口池 tickets 更新为 finished 状态
70
+ // 按出口池 Schema 映射 new_tickets（脚本不直接追加 tickets，交由引擎自动创建）
94
71
  return {
95
- new_tickets: [
96
- ...newSuccessTickets,
97
- ...newFailedTickets
98
- ]
72
+ new_tickets: [/* 按出口池映射的新 tickets */]
99
73
  }
100
74
  }
101
75
  }
102
76
  ```
77
+
78
+ 完整可运行代码参考见 [`embedded-template/scripts/示例数据与校验门控.js`](../embedded-template/scripts/示例数据与校验门控.js)。
package/skills/lab-flow-designer/references/agentic-lab-sdk.md CHANGED
@@ -12,6 +12,24 @@
12
12
 
13
13
  ---
14
14
 
15
+ ## 可用方法一览
16
+
17
+ | 方法 | 命名空间 | 用途 | 分页方式 |
18
+ |------|----------|------|----------|
19
+ | `pool.getNext(valveId)` | `context.pool` | 获取指定门控的出口池数组 | 无 |
20
+ | `ticket.list(params)` | `context.ticket` | 按条件筛选并分页返回 ticket 列表 | `limit` / `offset` |
21
+ | `ticket.update(tickets)` | `context.ticket` | 批量更新 ticket | 无 |
22
+ | `ticket.append(tickets)` | `context.ticket` | 批量追加 ticket | 无 |
23
+ | `process.list(params)` | `context.process` | 查询 process 列表 | `limit` / `offset` |
24
+ | `process.execute(items, baseURL)` | `context.process` | 批量提交 Process 执行任务 | 无 |
25
+ | `station.list()` | `context.station` | 列出所有工站 | 无 |
26
+ | `compound.getStockFromXfcSh(params)` | `context.compound` | 获取 XFC 上海化合物库存 | `pageSize` / `page` |
27
+ | `agent.chat(params)` | `context.agent` | 调用外部 Agent（流式/非流式），返回文本或解析后的 JSON | 无 |
28
+
29
+ > 生成「核心概念」中的 `this.context` 能力列表时，从本表选取流程实际使用的方法即可。各方法的完整签名、参数类型与返回类型见下文各节。
30
+
31
+ ---
32
+
15
33
  ## pool.getNext
16
34
 
17
35
  - **别名**：`context.pool.getNext`
@@ -271,3 +289,73 @@ interface CompoundResponse {
271
289
  "meta": { "count": 2, "page": 1, "pageSize": 400, "totalPage": 1 }
272
290
  }
273
291
  ```
292
+
293
+ ---
294
+
295
+ ## agent.chat
296
+
297
+ - **别名**：`context.agent.chat`
298
+ - **描述**：调用外部 Agent 服务。SDK 负责发起请求、消费流式（SSE / NDJSON）或普通 JSON 响应，并将各 chunk 的 `content` 拼接为完整文本。`url`、`query` **必填**。`parseJson: true` 时从返回文本中提取并解析 JSON（支持 Markdown 代码块与多段 JSON 合并）；解析成功返回 object / array，失败返回 `null`。未开启 `parseJson` 时返回原始字符串。请求失败抛出以 `agent.chat:` 为前缀的错误。
299
+
300
+ ```typescript
301
+ interface ChatAgentParams {
302
+ /** Agent 服务完整 URL（必填） */
303
+ url: string; // Agent 服务完整 URL（必填
304
+ /** 用户查询文本（必填；非空字符串） */
305
+ query: string;
306
+ /**
307
+ * true：从返回文本提取并解析 JSON，成功返回 object/array，失败返回 null；
308
+ * 未传或 false：返回拼接后的原始 string
309
+ */
310
+ parseJson?: boolean;
311
+ [propName: string]: any;
312
+ }
313
+
314
+ /**
315
+ * parseJson 未开启：Promise<string>
316
+ * parseJson 开启且解析成功：Promise<object | any[]>
317
+ * parseJson 开启且解析失败：Promise<null>
318
+ */
319
+ async function agent.chat(params: ChatAgentParams): Promise<string | object | any[] | null>
320
+ ```
321
+
322
+ ### 参数说明
323
+
324
+ | 参数名 | 含义 | 备注 |
325
+ |--------|------|------|
326
+ | `url` | Agent 服务完整 URL | **必填**；空字符串会抛错 |
327
+ | `query` | 用户查询文本 | **必填**；空字符串会抛错 |
328
+ | `parseJson` | 是否解析返回 JSON | 默认不解析，返回拼接后的 string。为 `true` 时尝试从正文或 markdown 的 json 代码块中提取 JSON；多段合法 JSON 合并为数组；失败返回 `null`（不抛错） |
329
+
330
+ ### 调用示例
331
+
332
+ ```javascript
333
+ // 返回原始文本
334
+ const text = await this.context.agent.chat({
335
+ url: agentUrl,
336
+ query: '请根据以下实验数据给出结论：...',
337
+ });
338
+
339
+ // 期望 Agent 返回 JSON，解析失败时得到 null
340
+ const result = await this.context.agent.chat({
341
+ url: agentUrl,
342
+ query: prompt,
343
+ parseJson: true
344
+ });
345
+ if (result == null) {
346
+ throw new Error('agent.chat: failed to parse JSON from response');
347
+ }
348
+ ```
349
+
350
+ ### 返回说明
351
+
352
+ | 场景 | 返回值 |
353
+ |------|--------|
354
+ | `parseJson` 未开启 / 为 `false` | `string`：流式各 chunk `content` 的拼接结果 |
355
+ | `parseJson: true` 且解析成功 | `object` 或 `any[]` |
356
+ | `parseJson: true` 且解析失败 | `null` |
357
+ | 请求 / 流读取失败 | 抛出 `Error`，消息以 `agent.chat:` 为前缀 |
358
+
359
+ ### 请求体要点（SDK 封装，门控不必手拼）
360
+
361
+ 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 CHANGED
@@ -100,7 +100,7 @@ class Processer {
100
100
  // returns: { orbit_link, ticket_ids }
101
101
  async start(params) {
102
102
  const { valve_id, pool_ids } = params;
103
- // ticket.list → 按需查询化合物/工站/流程 → 写回 detail → ticket.update
103
+ // 查询入口池数据 → 按需查询化合物/工站/流程 → 写回 detail → 更新 tickets
104
104
  // orbit_link = PageUrl.replace('{bookid}', bookid)
105
105
  return { orbit_link, ticket_ids };
106
106
  }
@@ -110,8 +110,8 @@ class Processer {
110
110
  // returns: { new_tickets }
111
111
  async complete(params) {
112
112
  const { valve_id, tickets } = params;
113
- // pool.getNext → 入口池 tickets 更新为 finished → 按出口池映射 new_tickets
114
- // 由引擎自动创建，不在脚本内调用 ticket.append
113
+ // 获取出口池 → 入口池 tickets 更新为 finished → 按出口池映射 new_tickets
114
+ // 由引擎自动创建，脚本不直接追加 tickets
115
115
  return { new_tickets };
116
116
  }
117
117
  }
@@ -173,8 +173,8 @@ class Processer {
173
173
 
174
174
  ## 执行流程
175
175
 
176
- 1. **start 阶段**：`ticket.list` 按 `pool_id__in`（由 `Processer` 入参 `pool_ids` 映射）拉数，**取返回体 `list` 字段** → 按需拉化合物库存（`compound.getStockFromXfcSh`） → 写回 `detail` → `ticket.update`。
177
- 2. **complete 阶段**：`pool.getNext` 取出口池 → `ticket.update` / `ticket.append`。
176
+ 1. **start 阶段**：按 [agentic-lab-sdk.md](agentic-lab-sdk.md) 查询入口池数据 → 按需调用其他 SDK 方法查询外部数据 → 写回 `detail` → 按 SDK 更新 tickets。
177
+ 2. **complete 阶段**：按 [agentic-lab-sdk.md](agentic-lab-sdk.md) 获取出口池 → 更新入口池 ticket 状态 → 映射出口池 `new_tickets`。
178
178
 
179
179
  ## 输入/输出
180
180
 
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 CHANGED
@@ -105,7 +105,7 @@
105
105
  5. **数据处理规则表**（强烈推荐）：列至少包含 **`序号` | `规则摘要` | `条件要点` | `业务动作或结果`**；序号建议 **章内连续小数编号**（如 `1.1`、`1.2`，与门控章节号前缀一致），便于脚本注释逐条对应。
106
106
  6. **操作员步骤**（若为人工门控）：编号列表，步骤可执行、可验收。
107
107
 
108
- **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[]` 形状）。
108
+ **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[]` 形状）。
109
109
 
110
110
  **检查点**：每个 `output` 条件互斥或可判定优先级在文中有说明；缺料/失败等异常分支有定义。
111
111
  **检查点**：`input.secondary` 存在时，§4 文字补充中已描述合流。
@@ -154,12 +154,12 @@
154
154
 
155
155
  ### 3.3 Process / 任务提交 / 其它 SDK 调用的参数与格式
156
156
 
157
- 凡流程文档出现 **Process 执行、批量任务提交、`process.execute`、或任何明确绑定 SDK 的写操作/查询参数**，除满足 **§2.5 Process 批量提交** 小节外，还须满足（否则预检 **不通过**）：
157
+ 凡流程文档出现 **Process 执行、批量任务提交、或任何明确绑定 SDK 的写操作/查询参数**，除满足 **§2.5 Process 批量提交** 小节外，还须满足（否则预检 **不通过**）：
158
158
 
159
- 1. **方法名**：与 **agentic-lab-sdk** 中条目一致（如 `process.execute`、`process.list`、`ticket.list` 等），且用途与文档叙述一致。
160
- 2. **请求体与类型**：对 **`process.execute`**，须能整理出 **`items[]`**（与 **[`rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md)** 请求体中 `items` 一项同形）：每条至少含 **`process`**、**`params`**（键、类型、默认值或来源字段）；若流程需绑定业务表记录，则须说明 **`table_objects`**（表名、主键与 ticket 明细的对应）；并须说明 **`baseURL`** 如何得到；**禁止**仅写「组装 JSON」而无键级说明。
161
- 3. **查询类接口**：若使用 `ticket.list`、`compound.getStockFromXfcSh` 等，分页策略须与流程说明及 skill「门控脚本编写指引」一致或显式写出分页参数（`ticket.list` 使用 `limit`/`offset`，`compound.getStockFromXfcSh` 使用 `pageSize`/`page`）；**`filter`** 须说明字段名与算子意图，避免无法落地的自然语言。
162
- 4. **`process.execute` 与 HTTP**：流程文档约束 **`items`**、**`baseURL` 语义**及任务参数；**不要求**写 path / HTTP 方法（由 SDK 封装）。
159
+ 1. **方法名**：与 [agentic-lab-sdk.md](agentic-lab-sdk.md) 中条目一致，且用途与文档叙述一致。
160
+ 2. **请求体与类型**：对 **Process 批量提交**，须能整理出 **`items[]`**（与 **[`rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md)** 请求体中 `items` 一项同形）：每条至少含 **`process`**、**`params`**（键、类型、默认值或来源字段）；若流程需绑定业务表记录，则须说明 **`table_objects`**（表名、主键与 ticket 明细的对应）；并须说明 **`baseURL`** 如何得到；**禁止**仅写「组装 JSON」而无键级说明。
161
+ 3. **查询类接口**：分页策略须与 [agentic-lab-sdk.md](agentic-lab-sdk.md) 中该方法的分页方式一致或显式写出分页参数；**`filter`** 须说明字段名与算子意图，避免无法落地的自然语言。
162
+ 4. **Process 批量提交与 HTTP**：流程文档约束 **`items`**、**`baseURL` 语义**及任务参数；**不要求**写 path / HTTP 方法（由 SDK 封装）。
163
163
 
164
164
  **预检产出**：凡属 **§3.2 / §3.3** 的不通过项，须在《流程文档合规问题与优化建议》中单独列出 **「不支持或不可生成项」**，避免进入代码生成阶段才发现无法对接。
165
165
 
@@ -194,8 +194,8 @@
194
194
  - §3 → `pools/*.md` 文件名与 Schema；
195
195
  - §4 + §5 → 根 `SKILL.md` 流程图与**连接关系**列表；
196
196
  - §5 → `valves/*.md`、`scripts/*.js` 及规则注释序号；
197
- - §2、字段映射、查询方式 → 脚本内 `ticket.detail` 与 `compound.*` 等调用；
198
- - 流程中若需 **Process 批量提交** → 脚本内 **`this.context.process.execute(items, baseURL)`**（参数以流程文档为准，见 `references/agentic-lab-sdk.md` 与 `references/rhea-api/execute_process_batch.md`）。
197
+ - §2、字段映射、查询方式 → 脚本内 `ticket.detail` 与按 [agentic-lab-sdk.md](agentic-lab-sdk.md) 调用对应方法；
198
+ - 流程中若需 **Process 批量提交** → 脚本内按 SDK 对应方法执行（参数以流程文档为准，见 `references/agentic-lab-sdk.md` 与 `references/rhea-api/execute_process_batch.md`）。
199
199
 
200
200
  主 `SKILL.md` 中 **门控脚本编写指引** 约定：生成 `scripts/*.js` 与 `pools/*.md` Schema 时，**仅实现或收录流程文档在本门控逻辑或池字段描述中明确写出的**查询、回写、路由与字段行，**禁止**为对齐 embedded 示例而附加未文档化的代码或字段。
201
201