@xtalpi/agentic-lab-skills 0.0.8 → 0.0.10

package/package.json

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

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

@@ -4,7 +4,7 @@ description: >-
   根据流程说明 Markdown 初次生成流程注册包时，须先按 references/业务流程文档标准.md 做合规预检，不通过则不得写入产出包并须输出优化建议；对已存在的流程注册包做增量修改时跳过流程文档预检。
   也可根据用户描述生成符合规范的业务流程文档模板，供用户完善后用于流程注册包生成。
   产出与本 skill 内 embedded-template、references/skill-package-layout.md 版式同构；根 SKILL.md 须含概述、核心概念、流程图（Mermaid 池为矩形、门控为六边形）、连接关系、节点清单、门控执行规范、使用方式。
-  Use when scaffolding flow skills, valve scripts from gate YAML and compound KB rules, Processer start/complete from pipeline docs, or generating flow document templates.
+  Use when scaffolding flow skills, valve scripts from gate YAML and compound KB rules, Processer start/complete/run from pipeline docs, or generating flow document templates.
 license: Proprietary
 metadata:
   embedded-template-dir: embedded-template
@@ -38,7 +38,7 @@ metadata:
 | **极简目录范例（优先打开）** | 本 skill 内 [`embedded-template/`](embedded-template/)：2 池 + 1 门控；[`embedded-template/valves/示例数据与校验门控.md`](embedded-template/valves/示例数据与校验门控.md) 与 [`embedded-template/scripts/示例数据与校验门控.js`](embedded-template/scripts/示例数据与校验门控.js) 含「数据查询 / 映射 / 规则」与 SDK 对齐的完整参考 |
 | **版式条文** | [references/skill-package-layout.md](references/skill-package-layout.md)：目录约定、根 `SKILL.md` 各块格式、`pools`/`valves` 文字范例摘录 |
 | 门控脚本 API | [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)（生成 `scripts/*.js` 前必读） |
-| 门控脚本规范 | [references/agentic-lab-processer.md](references/agentic-lab-processer.md)：`Processer` 类的 `start`/`complete` 输入输出类型定义与代码风格参考（参数与返回值均为 **snake_case**） |
+| 门控脚本规范 | [references/agentic-lab-processer.md](references/agentic-lab-processer.md)：`Processer` 类的 `start`/`complete`（人工触发）与 `run`（自动触发）输入输出类型定义与代码风格参考（参数与返回值均为 **snake_case**） |
 | **业务流程文档模板** | [templates/业务流程文档模板.md](templates/业务流程文档模板.md)：空白模板，各章节带占位提示；用于「生成流程文档」模式 |
 | **业务流程文档示例** | [templates/业务流程文档示例.md](templates/业务流程文档示例.md)：基于 Fragment 分装流程的填写示例，供参考 |
 
@@ -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,8 +119,10 @@ metadata:
     - 数据来源与操作按钮描述
   - **后置处理** → 生成 `Processer.complete` 函数逻辑。须提取：
     - 规则摘要表（条件要点 + 业务动作），落入 `complete` 函数体
-    - 提交参数结构（如 `process.execute` 的 `items` 定义与 `params` 键级说明）
+    - 提交参数结构（如 SDK 调用方法的参数定义与键级说明）
     - 出口池路由条件与字段映射
+- **触发方式**：每个门控的 `### 触发方式`（`自动触发` 或 `人工触发`）。自动触发门控无人工处理阶段，脚本实现 `run`（见 [references/agentic-lab-processer.md](references/agentic-lab-processer.md)）；人工触发门控保持 `start` + `complete`。
+- **模型引用**（若有）：数据池或门控的 `### 模型引用`（模型名称与版本），写入对应 `pools/*.md` 或 `valves/*.md` 的 `## 模型引用` 章节；无模型引用时省略。
 - **门控脚本配置项**：提取全局配置表中的各项，落入脚本为**模块级常量**：
   - `PageUrl`（含 `{bookid}` 占位符）→ 脚本常量 `PAGE_URL`
   - `StationBaseURL`（若有）→ 脚本常量 `STATION_BASE_URL`
@@ -160,8 +162,8 @@ 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.getStockFromXfcSh`），**不要**抄写模板里已过期的成员名。
+- **`### 门控（Valve）`**：说明每个 Valve 对应脚本、`Processer` 的 `start` / `complete`（人工触发）或 `run`（自动触发）职责分工。  
+  另起简短列表说明执行引擎通过 `this.context` 暴露的能力，**仅写** [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)「可用方法一览」中已列出的方法名（按流程实际使用选取），**不要**抄写模板里已过期的成员名。
 
 #### 3.4 `## 流程图`（本节内须含「连接关系」列表，与模板一致）
 
@@ -214,7 +216,7 @@ metadata:
 
 #### 3.6 `## 门控执行规范`
 
-`Processer` 代码块**原文照抄** [references/skill-package-layout.md](references/skill-package-layout.md) §2.5：`constructor`、`async start`、`async complete` 及注释；不含导出语句。不在此节展开 `context` 各方法签名（见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)）。
+`Processer` 代码块**原文照抄** [references/skill-package-layout.md](references/skill-package-layout.md) §2.5：人工触发门控使用 `constructor`、`async start`、`async complete`；自动触发门控使用 `constructor`、`async run`；不含导出语句。不在此节展开 `context` 各方法签名（见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)）。
 
 #### 3.7 `## 使用方式`
 
@@ -231,18 +233,21 @@ metadata:
   - **字段标题**：与流程说明或业务系统一致的**展示名**（可为英文短语如 `Compound ID`，或简短中文标题），供人读表与 UI 列头；**不要**把原「字段」列的英文混进「字段」列。  
   - **字段描述**、**字段类型**、**属性**、**默认值**：规则同前（属性仍仅写枚举/格式归纳，无则留空）。
 - **属性列**：仅当流程说明对该字段给出了**可选值/枚举**（含「枚举：…」「如 A、B」、用顿号/逗号分隔的取值列表等）时，将归纳后的约束写入本列，**建议**以 `枚举：` 开头（例：`枚举：固体颗粒过大，流动性差，强吸水性，易结块，易粘黏，强静电吸附，液体`）。若说明仅在「说明」列内嵌枚举长句，可将枚举部分抽到「属性」，「字段描述」保留简短业务含义。若说明中约定了**日期或时间的表达格式**（如 ISO8601、`YYYYMMDD`、批次号中的日期段），以 `格式：` 开头写入本列。无枚举、无格式约定则**属性列留空**（不写 `-` 占位语）。业务含义仍以「字段描述」为主，避免在描述与属性中完全重复粘贴同一段长文。
+- **模型引用**（若流程说明为该池指定了 3D 模型）：在 `## Schema` 之后添加 `## 模型引用`，含模型名称与版本（格式见 [references/skill-package-layout.md](references/skill-package-layout.md) §3）。无模型引用时省略。
 
 ### 5. 写入每个 `valves/<基名>.md`
 
-章节与排版对齐抽取文档 §4，**至少**包含：`## 概述`（编号步骤）、`## 关联脚本`、`## 执行流程`、`## 输入/输出`。`输入/输出` 须与门控 YAML 的 `primary`/`secondary` 与各输出池**显示名称**一致，**勿**照搬范例中的池名。
+章节与排版对齐抽取文档 §4，**至少**包含：`## 概述`（编号步骤）、`## 关联脚本`、`## 触发方式`、`## 执行流程`、`## 输入/输出`。`输入/输出` 须与门控 YAML 的 `primary`/`secondary` 与各输出池**显示名称**一致，**勿**照搬范例中的池名。
 
 若流程说明对某门控给出了下列块，须在对应 `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` 函数需执行的逻辑。
-- **化合物数据查询方式**（或等价标题）：表或段落中「查化合物库存」等表述，与 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中 `compound.getStockFromXfcSh` 的对应关系写清。
+- **后置处理**（对应 `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）须在脚本注释中可逐条追溯。
 
@@ -250,8 +255,9 @@ metadata:
 
 ### 6. 写入每个 `scripts/<基名>.js`
 
-1. **先读** [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 与 [references/agentic-lab-processer.md](references/agentic-lab-processer.md)；`this.context` **仅**使用 sdk 文件已列出的成员；`start`/`complete` 的输入输出类型须对齐 processer 规范。
-2. **结构**对齐 [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js)：`Processer` 类、`constructor(context)`、`async start` / `async complete`；脚本以类定义结束，禁止添加任何导出语句。示例中与本门控文档无关的业务分支**省略**。
+1. **先读** [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 与 [references/agentic-lab-processer.md](references/agentic-lab-processer.md)；`this.context` **仅**使用 sdk 文件已列出的成员；`start`/`complete`（或 `run`）的输入输出类型须对齐 processer 规范。
+2. **结构**对齐 [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js)：`Processer` 类、`constructor(context)`、`async start` / `async complete`（人工触发）或 `async run`（自动触发）；脚本以类定义结束，禁止添加任何导出语句。示例中与本门控文档无关的业务分支**省略**。
+2.5. **触发方式分支**：读取对应 `valves/<基名>.md` 中的 `## 触发方式`。若为 **人工触发** → 脚本结构同现有（`constructor` + `start` + `complete`）；若为 **自动触发** → 脚本使用 `constructor` + `run`（类型定义见 [references/agentic-lab-processer.md](references/agentic-lab-processer.md)），不含 `start` 或 `complete`。
 3. **注释**与流程说明规则编号对应；业务分支处可用 `TODO`，**不得**编造文档未定义的池名或 API。
 4. **实现逻辑**须遵循下文「门控脚本编写指引」（含 **`limit`/`offset` 默认全量** 约定）。
 5. **按需生成**：详见下文「编写指引 §0」。
@@ -272,25 +278,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.getStockFromXfcSh`：入参为可选 **`filter`**（**dot-notation** 格式，如 `{ 'cas.$in': [...] }`，不传默认筛选 `status = '可用'`）+ 可选 `fields`/`pageSize`/`page`；返回 `{ data, meta }` 结构，取 **`.data`** 获取数据数组；见 [agentic-lab-sdk](references/agentic-lab-sdk.md) |
+| 门控 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`**），生成门控脚本时遵守：
+凡 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)「可用方法一览」中标注使用 `limit` / `offset` 分页的查询方法，生成门控脚本时遵守：
 
-> **注意**：`compound.getStockFromXfcSh` 使用 `pageSize` / `page` 分页（非 `limit` / `offset`），不传分页参数时使用 API 默认值，不适用下述 `limit: 999999` 约定。
-
-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` 对应**后置处理**。
@@ -301,16 +302,24 @@ 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.getStockFromXfcSh`（返回 `{ data, meta }`，取 `.data` 获取数组）、`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）。
+
+### 3.1 `run` 分工（自动触发门控专用）
+
+自动触发门控无人工处理阶段，`run` 合并了 `start` 与 `complete` 的职责。
+
+- **`run(params)`**：解构 **`valve_id`、`pool_ids`**（snake_case）→ 按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 查询入口池数据 → 按需调用 SDK 方法 → 按数据处理规则更新 `ticket.detail` → 按 SDK 更新 tickets → 按 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 获取出口池 → 将入口池 tickets 更新为 `finished` → 按出口池条件映射 `new_tickets` → 返回 `{ new_tickets }`。
+
+  **与 `start` + `complete` 的区别**：`run` **不返回** `orbit_link` 或 `ticket_ids`（无人工阶段无需页面链接或 ticket 列表交互）。类型定义见 [references/agentic-lab-processer.md](references/agentic-lab-processer.md)。
 
 ### 4. 运行环境约束（沙箱可用全局对象）
 
@@ -345,7 +354,7 @@ metadata:
    const qs = new URLSearchParams({ view_id: viewId, page_size: '500' });
    ```
 
-2. **外部 HTTP 调用**——优先使用 `this.context` SDK 方法（`ticket.list`、`compound.getStockFromXfcSh` 等）。仅当流程文档要求调用 SDK 未覆盖的第三方 API（如飞书/Lark）时，才使用 `fetch`；此时 URL 手动拼接，**不依赖** `URLSearchParams`。
+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` 在沙箱白名单中）。
 
@@ -374,9 +383,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. 产物版本追踪
 
@@ -435,6 +444,8 @@ console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__}
 - 一级参数/返回值 snake_case；嵌套 JSON 保持原格式（见「编写指引 §3」）
 - `orbit_link` = `PageUrl` + `bookid`（见「编写指引 §3 orbit_link 生成步骤」）
 - 门控三阶段：前置处理 → `start`、后置处理 → `complete`、人工处理 → UI 技能（见「解析流程说明 §1」）
+- **触发方式**：自动触发门控脚本须实现 `run`（非 `start` + `complete`）；人工触发保持 `start` + `complete`（见「编写指引 §3.1」与 [agentic-lab-processer.md](references/agentic-lab-processer.md)）
+- **模型引用**：流程说明中关联 3D 模型的池和门控，须在对应 `pools/*.md` 或 `valves/*.md` 写入 `## 模型引用`（模型名称 + 版本）；无模型引用时省略
 - `complete` 优先使用 `params.tickets`，非必要不重查（见「编写指引 §3」）
 - 脚本以 `Processer` 类结束，禁止 `return`/`module.exports`/`export`（见「生成流程 §6」）
 - 按需生成，禁止冗余：代码和 Schema 仅覆盖流程文档明确写出的内容（见「编写指引 §0」）
@@ -455,8 +466,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` 在无流程分页说明时是否传入 **`limit: 999999`**（或流程说明指定的查全量数值），见 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 篇首约定。`compound.getStockFromXfcSh` 使用 `pageSize`/`page` 分页，不传时使用 API 默认值。
-
 **版本追踪**：`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)。
@@ -490,10 +499,11 @@ node <本skill目录>/testing/test-processer.mjs \
 | 轮次 | 检查内容 | 失败级别 |
 |------|---------|---------|
 | **语法检查** | JavaScript 语法正确性 | 阻断 |
-| **结构检查** | `Processer` 类存在，含 `constructor`、`start`、`complete` | 阻断 |
-| **正常轮 `start`** | 正常类型 mock 数据运行，检查返回 `{ orbit_link: string, ticket_ids: number[] }` | 阻断 |
-| **正常轮 `complete`** | 正常类型 mock 数据运行，检查返回 `{ new_tickets: [...] }` 结构正确 | 阻断 |
-| **对抗轮 `start` + `complete`** | 第 3 条 ticket 的 text 字段填为 number/null，验证类型安全编码 | 警告（不阻断） |
+| **结构检查** | `Processer` 类存在，含 `constructor` + (`start`、`complete`)（人工触发）或 `run`（自动触发） | 阻断 |
+| **正常轮 `start`** | 人工触发：正常类型 mock 数据运行，检查返回 `{ orbit_link: string, ticket_ids: number[] }` | 阻断 |
+| **正常轮 `complete`** | 人工触发：正常类型 mock 数据运行，检查返回 `{ new_tickets: [...] }` 结构正确 | 阻断 |
+| **正常轮 `run`** | 自动触发：正常类型 mock 数据运行，检查返回 `{ new_tickets: [...] }` 结构正确 | 阻断 |
+| **对抗轮 `start` + `complete` / `run`** | 第 3 条 ticket 的 text 字段填为 number/null，验证类型安全编码 | 警告（不阻断） |
 | **合规审计** | SDK 方法白名单、列表查询 `limit`/`offset`、返回值 snake_case | 未知 SDK 方法→阻断；其余→警告 |
 
 ### 结果判定与自动修复
@@ -529,6 +539,8 @@ node <本skill目录>/testing/test-processer.mjs \
 | `ticket.list called without limit` | `ticket.list called without explicit limit` | 添加 `limit: DEFAULT_QUERY_LIMIT, offset: 0` |
 | `camelCase key in return value` | `"ticketIds" is camelCase — must be snake_case` | 改为 `ticket_ids` 等 snake_case 键名 |
 | `Processer missing start() method` | 结构检查未通过 | 确保 `Processer` 类包含 `async start(params)` 方法 |
+| `Processer missing run() method` | 自动触发门控结构检查未通过 | 确保 `Processer` 类包含 `async run(params)` 方法，移除 `start`/`complete` |
+| `run() new_tickets 缺必填字段` | `new_tickets[0].pool_id must be number` | 检查 run 中 new_tickets 映射逻辑，补全 `flow_id`/`pool_id`/`order_id`/`detail`/`status` |
 
 ## 脚本预览（试运行）
 

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

@@ -59,7 +59,7 @@ flowchart LR
 
 ## 门控执行规范
 
-每个 Valve 的 JavaScript 脚本导出 `Processer` 类，必须实现 `start` / `complete`。由流程说明生成真实流程注册包时，脚本**仅实现文档明确要求**的逻辑与字段处理，须遵循主 `SKILL.md`「门控脚本编写指引」；下方代码块仅示意类骨架。
+每个 Valve 的 JavaScript 脚本导出 `Processer` 类，必须实现 `start` / `complete`（人工触发）或 `run`（自动触发）。由流程说明生成真实流程注册包时，脚本**仅实现文档明确要求**的逻辑与字段处理，须遵循主 `SKILL.md`「门控脚本编写指引」；下方代码块仅示意类骨架。
 
 ```javascript
 class Processer {
@@ -81,6 +81,21 @@ class Processer {
 }
 ```
 
+**自动触发门控**使用 `run` 替代 `start` + `complete`（详见 [references/agentic-lab-processer.md](../references/agentic-lab-processer.md)）：
+
+```javascript
+class Processer {
+  constructor(context) {
+    this.context = context;
+  }
+
+  async run(params) {
+    // params: { valve_id, pool_ids }
+    // 查询入口池 → 执行业务逻辑 → 获取出口池 → 映射 new_tickets
+  }
+}
+```
+
 ## 使用方式
 
 1. 查看各 Pool 的 [pools/](pools/) 目录了解数据表结构

package/skills/lab-flow-designer/embedded-template/pools//345/205/245/345/217/243/346/261/240.md

@@ -10,3 +10,12 @@
 |------|----------|----------|----------|------|--------|
 | id | ID | 业务主键 | string |  | - |
 | detail | Detail | 业务明细 JSON | json |  | - |
+
+## 模型引用
+
+> 本池无关联 3D 模型，本节仅作版式示意。实际生成时，无模型引用的池省略本节。
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | example-pool-model |
+| 版本 | 1.0.0 |

package/skills/lab-flow-designer/embedded-template/pools//345/207/272/345/217/243/346/261/240.md

@@ -10,3 +10,12 @@
 |------|----------|----------|----------|------|--------|
 | id | ID | 业务主键 | string |  | - |
 | detail | Detail | 业务明细 JSON | json |  | - |
+
+## 模型引用
+
+> 本池无关联 3D 模型，本节仅作版式示意。实际生成时，无模型引用的池省略本节。
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | example-pool-model |
+| 版本 | 1.0.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

@@ -10,9 +10,24 @@
 
 该脚本导出 `Processer` 类，实现 `start` 和 `complete` 方法。
 
+## 触发方式
+
+人工触发
+
+> 人工触发门控执行顺序：前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`）。自动触发门控使用 `run` 方法替代 `start` + `complete`，详见 [references/agentic-lab-processer.md](../../references/agentic-lab-processer.md)。
+
+## 模型引用
+
+> 本门控无关联 3D 模型，本节仅作版式示意。实际生成时，无模型引用的门控省略本节。
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | example-valve-model |
+| 版本 | 1.0.0 |
+
 ## 门控 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,7 +44,7 @@ output:
 
 | 流程说明中的表述 | 推荐 SDK 调用 |
 |----------------|---------------|
-| 查化合物库存 / 可用量 / 库存汇总 | `context.compound.getStockFromXfcSh({ filter })`；filter 使用 **dot-notation** 格式（如 `{ 'cas.$in': [...] }`）；返回 `{ data, meta }`，取 **`.data`** 获取数据数组；不传 filter 时默认筛选 `status = '可用'`。另见 [agentic-lab-sdk](../../references/agentic-lab-sdk.md) |
+| 查化合物库存 / 可用量 / 库存汇总 | 按 [agentic-lab-sdk.md](../../references/agentic-lab-sdk.md) 中的化合物库存查询方法 |
 
 ## 字段映射（示例：知识库 → ticket.detail）
 
@@ -52,7 +67,7 @@ output:
 | 序号 | 规则摘要 | 业务动作（示意） |
 |------|----------|------------------|
 | 1.1 | 汇总需求量 | `detail.requested_amount = sum(target_amount_n)` |
-| 1.2 | 缺料判定 | 结合 `getStockFromXfcSh` 汇总可用量与 `requested_amount` 比较 |
+| 1.2 | 缺料判定 | 结合化合物库存查询（SDK）汇总可用量与 `requested_amount` 比较 |
 | 1.3 | 容差默认 | 目标量 >0 且容差空 → 默认 0.5 mg |
 | 1.4 | 缺料标记 | `source_barcode` 空 → `是否缺料` = 缺料 |
 
@@ -68,9 +83,9 @@ output:
 
 | 规则摘要 | 条件要点 | 业务动作或结果 |
 | -------- | -------- | -------------- |
-| 查询入口池 | 门控启动 | `ticket.list({ pool_id__in: pool_ids, limit: 999999, offset: 0 })`，取返回体 `list` |
-| 查化合物数据 | 有 compound 查询需求 | `compound.getStockFromXfcSh`（不传分页参数，使用 API 默认值） |
-| 写回 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 }`
@@ -87,11 +102,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`（人工触发门控）与 `run`（自动触发门控）输入输出类型与代码风格。
 
 ### 类型定义
 
@@ -37,8 +39,27 @@ interface CompleteExecutionResult {
 async complete(params: CompleteExecutionParams): Promise<CompleteExecutionResult>
 ```
 
+#### run（自动触发门控专用）
 
-### 示例
+自动触发门控不经过人工处理阶段，使用 `run` 替代 `start` + `complete`。`run` 合并了前置与后置处理：接收 `valve_id` 与 `pool_ids`（同 `start`），直接返回 `new_tickets`（同 `complete`），无需 `orbit_link` 或 `ticket_ids`。
+
+```typescript
+interface RunExecutionParams {
+  valve_id: number;
+  pool_ids: number[];
+  [propName: string]: any;
+}
+
+interface RunExecutionResult {
+  new_tickets?: Record<string, any>[]; // 待新增的tickets，由引擎创建到数据表
+  [propName: string]: any;
+}
+
+async run(params: RunExecutionParams): Promise<RunExecutionResult>
+```
+
+
+### 示例（人工触发门控）
 
 ```javascript
 class Processer {
@@ -50,52 +71,51 @@ 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失败');
+    // 按 agentic-lab-sdk.md 获取出口池
+    // 按业务规则筛选可流入出口池的 tickets
+    // 将入口池 tickets 更新为 finished 状态
+    // 按出口池 Schema 映射 new_tickets（脚本不直接追加 tickets，交由引擎自动创建）
+    return {
+      new_tickets: [/* 按出口池映射的新 tickets */]
+    }
+  }
+}
+```
 
-    // 基于实时tickets，按实际业务场景(流程说明书中的相关定义)，筛选出“可流入出口池”的tickets
-    const finalTickets = params.tickets.filter(ticket => ticket).map(t => ({ ...t, status: 'finished' }));
+完整可运行代码参考见 [`embedded-template/scripts/示例数据与校验门控.js`](../embedded-template/scripts/示例数据与校验门控.js)。
 
-    // 将入口池的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 }));
+```javascript
+class Processer {
+  // context: 执行引擎提供的SDK
+  constructor(context) {
+    this.context = context;
+    console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`);
+  }
 
-    // 脚本不负责创建新ticket，交由引擎自动创建（需返回new_tickets）
+  // params: { valve_id, pool_ids }
+  async run(params) {
+    // 按 agentic-lab-sdk.md 查询入口池数据
+    // 按需调用 SDK 方法查询化合物/工站/流程等外部数据
+    // 执行业务逻辑（无人工处理阶段）
+    // 按 agentic-lab-sdk.md 获取出口池
+    // 将入口池 tickets 更新为 finished 状态
+    // 按出口池 Schema 映射 new_tickets
     return {
-      new_tickets: [
-        ...newSuccessTickets,
-        ...newFailedTickets
-      ]
+      new_tickets: [/* 按出口池映射的新 tickets */]
     }
   }
 }

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

@@ -12,6 +12,24 @@
 
 ---
 
+## 可用方法一览
+
+| 方法 | 命名空间 | 用途 | 分页方式 |
+|------|----------|------|----------|
+| `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`
@@ -271,3 +289,73 @@ interface CompoundResponse {
   "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)`**。