@xtalpi/agentic-lab-skills 0.0.8 → 0.0.10

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

@@ -86,7 +86,7 @@ metadata:
 
 ### 2.5 `## 门控执行规范` 代码块（`Processer` 类骨架，须保留；不含脚本尾部导出）
 
-门控执行顺序：**前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`）**。参数与返回值**一律 snake_case**（对齐 [agentic-lab-processer.md](agentic-lab-processer.md)）。
+门控执行顺序：**前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`）**（人工触发门控）或 **`run`**（自动触发门控）。参数与返回值**一律 snake_case**（对齐 [agentic-lab-processer.md](agentic-lab-processer.md)）。
 
 ```javascript
 class Processer {
@@ -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,28 @@ 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 };
+  }
+}
+```
+
+**自动触发门控**的 `Processer` 骨架使用 `run` 替代 `start` + `complete`（详见 [agentic-lab-processer.md](agentic-lab-processer.md)）：
+
+```javascript
+class Processer {
+  constructor(context) {
+    this.context = context;
+    console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`);
+  }
+
+  // --- 自动触发 → run ---
+  // params: { valve_id, pool_ids }
+  // returns: { new_tickets }
+  async run(params) {
+    const { valve_id, pool_ids } = params;
+    // 查询入口池数据 → 执行业务逻辑 → 获取出口池 → 入口池 tickets 更新为 finished → 映射 new_tickets
     return { new_tickets };
   }
 }
@@ -152,6 +172,21 @@ class Processer {
 
 **属性列规则**：流程说明里若写清枚举/可选值，写入 `枚举：…`；若写清日期或时间串格式，写入 `格式：…`；否则该格留空。
 
+### 模型引用（可选）
+
+若流程说明为该数据池指定了 3D 模型文件，在 `## Schema` 之后添加：
+
+```markdown
+## 模型引用
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | （模型文件名称） |
+| 版本 | （模型版本） |
+```
+
+无模型引用时**省略本节**（不写空占位）。
+
 ---
 
 ## 4. `valves/<基名>.md` 格式（节选范例）
@@ -173,8 +208,8 @@ class Processer {
 
 ## 执行流程
 
-1. **start 阶段**：`ticket.list` 按 `pool_id__in`（由 `Processer` 入参 `pool_ids` 映射）拉数，**取返回体 `list` 字段** → 按需拉化合物库存（`compound.getStockFromXfcSh`） → 写回 `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`。
 
 ## 输入/输出
 
@@ -182,6 +217,35 @@ class Processer {
 - **输出池**: 出口池
 ```
 
+### 触发方式（推荐，缺省为人工触发）
+
+每个门控文档建议在 `## 关联脚本` 之后包含 `## 触发方式`：
+
+```markdown
+## 触发方式
+
+人工触发
+```
+
+取值为 `自动触发` 或 `人工触发`。未指定时默认按**人工触发**处理：
+- **人工触发**（默认）：门控执行顺序为 前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`），脚本实现 `start` + `complete`。
+- **自动触发**：门控无人工处理阶段，脚本实现 `run` 方法（见 [agentic-lab-processer.md](agentic-lab-processer.md)）。
+
+### 模型引用（可选）
+
+若流程说明为该门控指定了 3D 模型文件，添加：
+
+```markdown
+## 模型引用
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | （模型文件名称） |
+| 版本 | （模型版本） |
+```
+
+无模型引用时**省略本节**（不写空占位）。
+
 ---
 
 ## 5. `scripts/<基名>.js` 格式

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

@@ -64,6 +64,8 @@
 **检查点**：每个在拓扑与门控 YAML 中出现的池，表中有一行；**显示名称**与 YAML `input`/`output` 中的池名一致。  
 **检查点**：**逻辑 ID** 在同一文档内唯一（如 `stash_input`），且仅使用字母、数字、下划线（便于下游映射）。
 
+**模型引用（可选）**：若数据池关联 3D 模型，须在该池的描述中包含 `模型引用` 标题子节，写明模型名称与版本。无关联模型时省略。
+
 ---
 
 ### 2.4 `## 4. 池间流转（拓扑）`（必备）
@@ -97,15 +99,19 @@
 
 对每个门控，建议按下列顺序组织（可合并标题，但**信息不得缺**）：
 
+> **标题层级**：下列各项标题文字（如「触发方式」「模型引用」等）的 Markdown 层级（`##` / `###` / `####`）取决于门控在文档中的嵌套深度，以标题文字匹配为准，不要求固定 `#` 数量。
+
 1. **门控标题**：`### 5.x <门控显示名称>`（编号与 `order` 建议一致或递增）。  
 2. **YAML 代码块**：`yaml`，须含 `name`、`order`、`input`、`output`；**`valve_id` 可选**（若写则全文档唯一）。  
    - 目标池键名可使用 `Stash:` 等非标准键，但须在总述或脚注说明与实现侧 **pool 显示名称** 的对应关系。  
-3. **化合物 / 外部数据查询方式**（若本门控需要）：说明查哪类库、用哪些入口字段作键、汇总规则等。  
-4. **字段映射表**（若存在库表/API 列与门控加工字段对应）：两列表头清晰（如「门控加工数据 | 库字段」）。  
-5. **数据处理规则表**（强烈推荐）：列至少包含 **`序号` | `规则摘要` | `条件要点` | `业务动作或结果`**；序号建议 **章内连续小数编号**（如 `1.1`、`1.2`，与门控章节号前缀一致），便于脚本注释逐条对应。  
-6. **操作员步骤**（若为人工门控）：编号列表，步骤可执行、可验收。
+3. **触发方式**（推荐，缺省为人工触发）：`触发方式` 标题，取值 `自动触发` 或 `人工触发`。未指定时默认按**人工触发**处理。自动触发门控无人工处理阶段，脚本实现 `run`；人工触发门控脚本实现 `start` + `complete`。
+4. **化合物 / 外部数据查询方式**（若本门控需要）：说明查哪类库、用哪些入口字段作键、汇总规则等。  
+5. **字段映射表**（若存在库表/API 列与门控加工字段对应）：两列表头清晰（如「门控加工数据 | 库字段」）。  
+6. **数据处理规则表**（强烈推荐）：列至少包含 **`序号` | `规则摘要` | `条件要点` | `业务动作或结果`**；序号建议 **章内连续小数编号**（如 `1.1`、`1.2`，与门控章节号前缀一致），便于脚本注释逐条对应。  
+7. **操作员步骤**（若为人工门控）：编号列表，步骤可执行、可验收。
+8. **模型引用**（若本门控关联 3D 模型）：`模型引用` 标题，写明模型名称与版本。无关联模型时省略。
 
-**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 +160,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.getStockFromXfcSh` 等，分页策略须与流程说明及 skill「门控脚本编写指引」一致或显式写出分页参数（`ticket.list` 使用 `limit`/`offset`，`compound.getStockFromXfcSh` 使用 `pageSize`/`page`）；**`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** 的不通过项，须在《流程文档合规问题与优化建议》中单独列出 **「不支持或不可生成项」**，避免进入代码生成阶段才发现无法对接。
 
@@ -182,6 +188,8 @@
 - [ ] **§3.1**：门控规则与 `output` 条件可判定，无未定义模糊用语；分支互斥或优先级已说明。  
 - [ ] **§3.2**：所提依赖、**SDK/API**、字段均在 **agentic-lab-sdk**（及已列 rhea-api）与 §2 中有依据；**无不支持或未文档化的 API**。  
 - [ ] **§3.3**：凡 **Process / 任务提交 / SDK 调用**，**`items`** 与 **`baseURL` 语义**可对照 **agentic-lab-sdk + rhea-api** 校验；其它查询的分页与 **filter** 意图可落地；**不**要求流程写 path/HTTP 方法。
+- [ ] **触发方式**（推荐）：建议每个门控含 `触发方式` 标题（`自动触发` 或 `人工触发`）；未指定时默认为人工触发。自动触发门控无操作员步骤与人工处理章节。
+- [ ] **模型引用**：关联 3D 模型的数据池或门控含 `模型引用` 标题（模型名称、模型版本）；无关联模型时可省略。
 
 ---
 
@@ -194,8 +202,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/346/250/241/346/235/277.md

@@ -60,6 +60,14 @@
 
 > **提示**：显示名称须与门控 YAML 中的 `input`/`output` 池名逐字一致（含标点、中间点「·」等）。逻辑 ID 仅使用小写字母、数字、下划线。
 
+### 3.1 数据池模型引用（按需）
+
+> 若数据池关联 3D 模型，在此列出模型信息。无关联模型时省略本节。
+
+| 池显示名称 | 模型名称 | 模型版本 |
+| --------- | ------- | ------- |
+| （例：待处理池） | （例：reactor_v2） | （例：1.0.0） |
+
 ***
 
 ## 4. 池间流转（拓扑）
@@ -111,6 +119,10 @@ output:
     condition: （路由条件）
 ```
 
+#### 触发方式
+
+（自动触发 / 人工触发）
+
 **化合物数据查询方式**（若本门控需要查询外部数据）
 
 （说明查哪类库、用哪些入口字段作键、返回什么、汇总规则等）
@@ -133,6 +145,13 @@ output:
 1. （步骤描述，可执行、可验收）
 2. （...）
 
+**模型引用**（若本门控关联 3D 模型，无则省略）
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | （模型名称） |
+| 版本 | （模型版本） |
+
 ***
 
 ### 5.2 （门控 2 显示名称）
@@ -149,13 +168,17 @@ output:
     condition: （路由条件）
 ```
 
+#### 触发方式
+
+（自动触发 / 人工触发）
+
 **数据处理规则**
 
 | 序号 | 规则摘要 | 条件要点 | 业务动作或结果 |
 | --- | ------- | ------- | ----------- |
 | 2.1 | （简述） | （条件） | （动作或路由结果） |
 
-> **提示**：按需复制门控子节，每个门控至少包含 YAML 代码块和数据处理规则表。需查询外部数据的加「查询方式」和「字段映射表」，人工门控加「操作员步骤」。
+> **提示**：按需复制门控子节，每个门控至少包含 YAML 代码块和触发方式。需查询外部数据的加「查询方式」和「字段映射表」，含计算/判定的加「数据处理规则」，人工触发门控加「操作员步骤」，关联 3D 模型的加「模型引用」。
 
 ***
 

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

@@ -76,6 +76,8 @@
 | 缺料化合物池 | `stash_missing` | 异常池 | 无可用源瓶或库存不足 |
 | 已分装化合物池 | `stash_done` | 终点池 | 交货确认完成，流程结束 |
 
+> **提示**：本流程数据池未关联 3D 模型，故省略模型引用。
+
 ***
 
 ## 4. 池间流转（拓扑）
@@ -133,6 +135,10 @@ output:
     condition: 是否缺料 = 缺料
 ```
 
+#### 触发方式
+
+人工触发
+
 **化合物数据查询方式**
 
 查询化合物库存的可用量：使用输入池 Compound ID 作为索引，通过 XFC 上海系统接口查询化合物库存（`compound.getStockFromXfcSh`），查找 status = 可用的记录，返回可用量字段的值并汇总加和。
@@ -174,6 +180,10 @@ output:
     condition: 任一档位偏差超出容差或其它执行失败情形
 ```
 
+#### 触发方式
+
+人工触发
+
 **数据处理规则**
 
 | 序号 | 规则摘要 | 条件要点 | 业务动作或结果 |