@xtalpi/agentic-lab-skills 0.0.9 → 0.0.11

package/skills/lab-flow-designer/references/rhea-api/README.md

@@ -1,7 +1,7 @@
-# Rhea HTTP 参考（补充）
-
-本目录为 **Rhea 等服务端点** 的 Wire 级说明，供 **SDK 实现与预检对照**；[`../agentic-lab-sdk.md`](../agentic-lab-sdk.md) 中的 **`process.execute`** 由门控传入 **`items`** 与 **`baseURL`**（服务根），**path、HTTP 方法** 仍由 SDK 按本目录文档固定封装。
-
-| 文件 | 说明 |
-|------|------|
-| [execute_process_batch.md](execute_process_batch.md) | `execute_process_batch`：URL、请求体 `items` / `process` / `params` / `table_objects`、响应 `exp_id_list` 等 |
+# Rhea HTTP 参考（补充）
+
+本目录为 **Rhea 等服务端点** 的 Wire 级说明，供 **SDK 实现与预检对照**；[`../agentic-lab-sdk.md`](../agentic-lab-sdk.md) 中的 **`process.execute`** 由门控传入 **`items`** 与 **`baseURL`**（服务根），**path、HTTP 方法** 仍由 SDK 按本目录文档固定封装。
+
+| 文件 | 说明 |
+|------|------|
+| [execute_process_batch.md](execute_process_batch.md) | `execute_process_batch`：URL、请求体 `items` / `process` / `params` / `table_objects`、响应 `exp_id_list` 等 |

package/skills/lab-flow-designer/references/rhea-api/execute_process_batch.md

@@ -1,58 +1,58 @@
-| 批量提交任务 |                                                           |
-| ------ | --------------------------------------------------------- |
-| url    | http://127.0.0.1:8080/api/process/execute\_process\_batch |
-| 方法     | post                                                      |
-
-## **参数**
-
-| 参数名称              | 参数说明       | 参数类型 | 是否必填          | 示例                                      |
-|----------------------|--------------|----------|-------------------|------------------------------------------|
-| items                | 耗材属性<br>list<br>必填 | list     | 是                | -                                        |
-| ├─ exp_name          | 实验名称       | string   | 否                |                                          |
-| ├─ process           | 流程模板名称     | string   | 是                | "One_to_one"                             |
-| ├─ priority          | 流程优先级     | int      | 否，默认为2，数值越高，优先级越高 |                                          |
-| ├─ params            | 流程参数       | dict     | 是                | 如下所示（JSON）：<br>{<br>&nbsp;&nbsp;"@spoon_calib": "",<br>&nbsp;&nbsp;"@second_spoon_calib": "calib",<br>&nbsp;&nbsp;"@calib_retry_times": 0,<br>&nbsp;&nbsp;"@setting_calib_retry_times": 3,<br>&nbsp;&nbsp;"@add_times": 0<br>} |
-| └─ table_objects     | 表对象         | dict     | 否（可选）         | {表名: {id: value}}；无表绑定时可省略或 `{}` |
-
-```python
-url = f"{base_url}/process/execute_process_batch"
-# process_name = "One_to_more"
-process_name = "workflow_demo_s1"
-
-data = {
-    "items": [
-        {
-            "exp_name": "",
-            "process": process_name,
-            "params": {
-                "@spoon_calib": False,
-                "@second_spoon_calib": True,
-                "@calib_retry_times": 0,
-                "@setting_calib_retry_times": 3,
-                "@add_times": 0},
-            "table_objects": {}
-        },
-        {
-            "exp_name": "",
-            "process": process_name,
-            "params": {
-                "@spoon_calib": False,
-                "@second_spoon_calib": True,
-                "@calib_retry_times": 0,
-                "@setting_calib_retry_times": 3,
-                "@add_times": 0},
-            "table_objects": {}
-        },
-    ]
-}
-
-response = requests.post(url, json=data)
-print(response)
-print(response.json())
-```
-
-## **返回值**
-
-| 参数名称   | 参数说明           | 参数类型 | 示例 |
-|------------|-------------------|----------|------|
-| results    | 批量提交任务的exp_id | json     | {<br>&nbsp;&nbsp;"results": {<br>&nbsp;&nbsp;&nbsp;&nbsp;"exp_id_list": [<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"86cc6fcc-6066-48be-a87a-66f5c370bba5",<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"6c0719d1-cee8-49ed-bdd5-4c89d83c03da"<br>&nbsp;&nbsp;&nbsp;&nbsp;]<br>&nbsp;&nbsp;}<br>} |
+| 批量提交任务 |                                                           |
+| ------ | --------------------------------------------------------- |
+| url    | http://127.0.0.1:8080/api/process/execute\_process\_batch |
+| 方法     | post                                                      |
+
+## **参数**
+
+| 参数名称              | 参数说明       | 参数类型 | 是否必填          | 示例                                      |
+|----------------------|--------------|----------|-------------------|------------------------------------------|
+| items                | 耗材属性<br>list<br>必填 | list     | 是                | -                                        |
+| ├─ exp_name          | 实验名称       | string   | 否                |                                          |
+| ├─ process           | 流程模板名称     | string   | 是                | "One_to_one"                             |
+| ├─ priority          | 流程优先级     | int      | 否，默认为2，数值越高，优先级越高 |                                          |
+| ├─ params            | 流程参数       | dict     | 是                | 如下所示（JSON）：<br>{<br>&nbsp;&nbsp;"@spoon_calib": "",<br>&nbsp;&nbsp;"@second_spoon_calib": "calib",<br>&nbsp;&nbsp;"@calib_retry_times": 0,<br>&nbsp;&nbsp;"@setting_calib_retry_times": 3,<br>&nbsp;&nbsp;"@add_times": 0<br>} |
+| └─ table_objects     | 表对象         | dict     | 否（可选）         | {表名: {id: value}}；无表绑定时可省略或 `{}` |
+
+```python
+url = f"{base_url}/process/execute_process_batch"
+# process_name = "One_to_more"
+process_name = "workflow_demo_s1"
+
+data = {
+    "items": [
+        {
+            "exp_name": "",
+            "process": process_name,
+            "params": {
+                "@spoon_calib": False,
+                "@second_spoon_calib": True,
+                "@calib_retry_times": 0,
+                "@setting_calib_retry_times": 3,
+                "@add_times": 0},
+            "table_objects": {}
+        },
+        {
+            "exp_name": "",
+            "process": process_name,
+            "params": {
+                "@spoon_calib": False,
+                "@second_spoon_calib": True,
+                "@calib_retry_times": 0,
+                "@setting_calib_retry_times": 3,
+                "@add_times": 0},
+            "table_objects": {}
+        },
+    ]
+}
+
+response = requests.post(url, json=data)
+print(response)
+print(response.json())
+```
+
+## **返回值**
+
+| 参数名称   | 参数说明           | 参数类型 | 示例 |
+|------------|-------------------|----------|------|
+| results    | 批量提交任务的exp_id | json     | {<br>&nbsp;&nbsp;"results": {<br>&nbsp;&nbsp;&nbsp;&nbsp;"exp_id_list": [<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"86cc6fcc-6066-48be-a87a-66f5c370bba5",<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;"6c0719d1-cee8-49ed-bdd5-4c89d83c03da"<br>&nbsp;&nbsp;&nbsp;&nbsp;]<br>&nbsp;&nbsp;}<br>} |

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

@@ -1,204 +1,268 @@
-# 流程注册包版式参考（摘录）
-
-以下内容与本 skill 内 **[`embedded-template/`](../embedded-template/)** 极简范例目录一致，用于生成新流程注册包时对齐**目录结构**与**关键文件格式**。业务文案以用户提供的流程说明为准。
-
----
-
-## 1. 目录结构（须同构）
-
-```text
-<流程注册包根目录>/
-├── SKILL.md
-├── pools/
-│   └── <池显示名称>.md
-├── valves/
-│   └── <门控基名>.md
-└── scripts/
-    └── <门控基名>.js
-```
-
-- 根目录名 = `SKILL.md` frontmatter 的 `name`（Agent Skills 规范：小写、数字、连字符）。
-- `pools/` 下文件名 = 流程说明数据池表中的**显示名称**（含 `·` 等标点，与模板一致）。
-- `valves/` 与 `scripts/` 下文件名 = **同一基名**；基名规则与模板现有文件一致（如 `Process发射判定`、`查看结果与复核更新`）。
-
----
-
-## 2. 根文件 `SKILL.md`：章节顺序与块格式
-
-### 2.1 Frontmatter（YAML）
-
-```yaml
----
-name: <与根目录同名-kebab-case>
-description: <≤1024 字符：本流程做什么 + 何时使用该流程注册包，含触发关键词>
-metadata:
-  version: "<semver，初次生成为 1.0.0>"
-  generated_by: lab-flow-designer
-  generated_at: "<YYYY-MM-DD>"
----
-```
-
-### 2.2 正文二级标题（须按此顺序）
-
-| 顺序 | 二级标题 | 内容要求 |
-|------|----------|----------|
-| 1 | `## 概述` | 1～3 段：业务目标、阶段、Pool/Valve 分工 |
-| 2 | `## 核心概念` | 固定两个三级标题：`### 数据池（Pool）`、`### 门控（Valve）`；Valve 小节内说明 `Processer` 的 `start` / `complete`；`context` 能力列表**仅**能写 [agentic-lab-sdk.md](agentic-lab-sdk.md) 中已有项（勿抄旧模板中的 `processe`） |
-| 3 | `## 流程图` | **Mermaid**：数据池节点 `id[池名]`（矩形/四边形），门控节点 `id{{门控名}}`（六边形）；或 ASCII 等价区分。**紧接着** `**连接关系：**` 与编号列表（见 2.3） |
-| 4 | `## 节点清单` | `### Pool 节点（数据池）` 表 + `### Valve 节点（门控）` 表（见 2.4） |
-| 5 | `## 门控执行规范` | `Processer` 代码块（见 2.5） |
-| 6 | `## 使用方式` | 三条编号步骤（见 2.6） |
-
-一级标题 `#`：流程名称（来自流程说明）。
-
-### 2.2.1 Mermaid 节点形状（须遵守）
-
-- **数据池**：`节点ID[显示名称]` → 矩形（四边形）。  
-- **门控**：`节点ID{{显示名称}}` → 六边形。  
-- 详细与示例见主 `SKILL.md`「生成流程」→ **3.4 `## 流程图`**。
-
-### 2.3 `**连接关系：**` 列表格式
-
-紧跟流程图，加粗标题 `**连接关系：**`，每条一行：
-
-```markdown
-**连接关系：**
-
-1. `源节点` → `目标节点`：业务说明
-2. ...
-```
-
-源/目标为池或门控的**显示名称**，用反引号包裹；编号连续。
-
-### 2.4 节点清单表格列
-
-**Pool 节点（数据池）**
-
-| 名称 | 文件 | 用途 |
-|------|------|------|
-| … | [pools/<名称>.md](pools/<名称>.md) | … |
-
-**Valve 节点（门控）**
-
-| 名称 | 文件 | 脚本 | 类型 |
-|------|------|------|------|
-| … | [valves/<基名>.md](valves/<基名>.md) | [scripts/<基名>.js](scripts/<基名>.js) | 自动化 或 人工操作 |
-
-### 2.5 `## 门控执行规范` 代码块（`Processer` 类骨架，须保留；不含脚本尾部导出）
-
-门控执行顺序：**前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`）**。参数与返回值**一律 snake_case**（对齐 [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__})`);
-  }
-
-  // --- 前置处理 → start ---
-  // params: { valve_id, pool_ids }
-  // returns: { orbit_link, ticket_ids }
-  async start(params) {
-    const { valve_id, pool_ids } = params;
-    // 查询入口池数据 → 按需查询化合物/工站/流程 → 写回 detail → 更新 tickets
-    // orbit_link = PageUrl.replace('{bookid}', bookid)
-    return { orbit_link, ticket_ids };
-  }
-
-  // --- 后置处理 → complete ---
-  // params: { valve_id, tickets }
-  // returns: { new_tickets }
-  async complete(params) {
-    const { valve_id, tickets } = params;
-    // 获取出口池 → 入口池 tickets 更新为 finished → 按出口池映射 new_tickets
-    // 由引擎自动创建，脚本不直接追加 tickets
-    return { new_tickets };
-  }
-}
-```
-
-### 2.6 `## 使用方式`（三条，语义对齐）
-
-```markdown
-## 使用方式
-
-1. 查看各 Pool 的 [pools/](pools/) 目录了解数据表结构
-2. 查看各 Valve 的 [valves/](valves/) 目录了解门控逻辑和脚本路径
-3. 执行门控时，调用对应脚本的 `Processer` 类
-```
-
----
-
-## 3. `pools/<池名>.md` 格式（节选范例）
-
-以下与 [`../embedded-template/pools/入口池.md`](../embedded-template/pools/入口池.md) 同构，仅示意**标题层级与 Schema 表头**；行数据按流程说明填写。
-
-```markdown
-# 入口池
-
-## 概述
-
-流程入口池，存放尚未经门控处理的记录。
-
-## Schema
-
-| 字段 | 字段标题 | 字段描述 | 字段类型 | 属性 | 默认值 |
-|------|----------|----------|----------|------|--------|
-| id | ID | 业务主键 | string |  | - |
-| detail | Detail | 业务明细 JSON | json |  | - |
-```
-
-**字段列**：仅 snake_case（`a-z`、数字、`_`）。**字段标题**：展示用名称，与流程说明或业务用语对齐。
-
-**属性列规则**：流程说明里若写清枚举/可选值，写入 `枚举：…`；若写清日期或时间串格式，写入 `格式：…`；否则该格留空。
-
----
-
-## 4. `valves/<基名>.md` 格式（节选范例）
-
-以下与 [`../embedded-template/valves/示例数据与校验门控.md`](../embedded-template/valves/示例数据与校验门控.md) 同风格节选；`输入/输出` 须与用户流程说明中门控 YAML 一致（勿照搬范例中的池名）。
-
-```markdown
-# 示例数据与校验门控
-
-## 概述
-
-演示门控文档结构：门控 YAML、化合物数据查询方式、字段映射、数据处理规则、start/complete 分工。
-
-## 关联脚本
-
-**脚本路径**: [scripts/示例数据与校验门控.js](scripts/示例数据与校验门控.js)
-
-该脚本导出 `Processer` 类，实现 `start` 和 `complete` 方法。
-
-## 执行流程
-
-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`。
-
-## 输入/输出
-
-- **输入池**: 入口池
-- **输出池**: 出口池
-```
-
----
-
-## 5. `scripts/<基名>.js` 格式
-
-- 与模板相同：`Processer` 类、`constructor(context)`、`async start` / `async complete`。**脚本以 `Processer` 类定义结束，禁止在类之后添加** `return`、`module.exports`、`export default` 或任何导出语句——导出由运行环境处理。
-- **API 以** [agentic-lab-sdk.md](agentic-lab-sdk.md) **为准**，勿使用未列出的 `context` 成员。
-- **按需实现**：仅流程说明在本门控下**明确需要**的查询、写回与路由才写代码；**禁止**为对齐示例而复制与本门控无关的 `context` 调用或 `ticket.detail` 键。
-- 与流程说明中的「数据查询方式 / 字段映射 / 数据处理规则」对齐的**可运行骨架**（结构参考），见 [`../embedded-template/scripts/示例数据与校验门控.js`](../embedded-template/scripts/示例数据与校验门控.js)；验证命令与核对项见主 `SKILL.md` **验证生成结果**。
-
----
-
-## 6. 本 skill 内对照关系
-
-| 位置 | 用途 |
-|------|------|
-| [`embedded-template/`](../embedded-template/) | **缩小真目录**：与产出包同构，优先打开对照链接与章节 |
-| 本文件（`skill-package-layout.md`） | **条文摘要**：表格列名、`Processer` 块、连接关系写法 |
-| [agentic-lab-sdk.md](agentic-lab-sdk.md) | **门控脚本 API**：`this.context` 仅使用其中已列成员 |
-
-生成时以用户流程说明为数据源；版式优先对齐 `embedded-template/` 与本文件。
+# 流程注册包版式参考（摘录）
+
+以下内容与本 skill 内 **[`embedded-template/`](../embedded-template/)** 极简范例目录一致，用于生成新流程注册包时对齐**目录结构**与**关键文件格式**。业务文案以用户提供的流程说明为准。
+
+---
+
+## 1. 目录结构（须同构）
+
+```text
+<流程注册包根目录>/
+├── SKILL.md
+├── pools/
+│   └── <池显示名称>.md
+├── valves/
+│   └── <门控基名>.md
+└── scripts/
+    └── <门控基名>.js
+```
+
+- 根目录名 = `SKILL.md` frontmatter 的 `name`（Agent Skills 规范：小写、数字、连字符）。
+- `pools/` 下文件名 = 流程说明数据池表中的**显示名称**（含 `·` 等标点，与模板一致）。
+- `valves/` 与 `scripts/` 下文件名 = **同一基名**；基名规则与模板现有文件一致（如 `Process发射判定`、`查看结果与复核更新`）。
+
+---
+
+## 2. 根文件 `SKILL.md`：章节顺序与块格式
+
+### 2.1 Frontmatter（YAML）
+
+```yaml
+---
+name: <与根目录同名-kebab-case>
+description: <≤1024 字符：本流程做什么 + 何时使用该流程注册包，含触发关键词>
+metadata:
+  version: "<semver，初次生成为 1.0.0>"
+  generated_by: lab-flow-designer
+  generated_at: "<YYYY-MM-DD>"
+---
+```
+
+### 2.2 正文二级标题（须按此顺序）
+
+| 顺序 | 二级标题 | 内容要求 |
+|------|----------|----------|
+| 1 | `## 概述` | 1～3 段：业务目标、阶段、Pool/Valve 分工 |
+| 2 | `## 核心概念` | 固定两个三级标题：`### 数据池（Pool）`、`### 门控（Valve）`；Valve 小节内说明 `Processer` 的 `start` / `complete`；`context` 能力列表**仅**能写 [agentic-lab-sdk.md](agentic-lab-sdk.md) 中已有项（勿抄旧模板中的 `processe`） |
+| 3 | `## 流程图` | **Mermaid**：数据池节点 `id[池名]`（矩形/四边形），门控节点 `id{{门控名}}`（六边形）；或 ASCII 等价区分。**紧接着** `**连接关系：**` 与编号列表（见 2.3） |
+| 4 | `## 节点清单` | `### Pool 节点（数据池）` 表 + `### Valve 节点（门控）` 表（见 2.4） |
+| 5 | `## 门控执行规范` | `Processer` 代码块（见 2.5） |
+| 6 | `## 使用方式` | 三条编号步骤（见 2.6） |
+
+一级标题 `#`：流程名称（来自流程说明）。
+
+### 2.2.1 Mermaid 节点形状（须遵守）
+
+- **数据池**：`节点ID[显示名称]` → 矩形（四边形）。  
+- **门控**：`节点ID{{显示名称}}` → 六边形。  
+- 详细与示例见主 `SKILL.md`「生成流程」→ **3.4 `## 流程图`**。
+
+### 2.3 `**连接关系：**` 列表格式
+
+紧跟流程图，加粗标题 `**连接关系：**`，每条一行：
+
+```markdown
+**连接关系：**
+
+1. `源节点` → `目标节点`：业务说明
+2. ...
+```
+
+源/目标为池或门控的**显示名称**，用反引号包裹；编号连续。
+
+### 2.4 节点清单表格列
+
+**Pool 节点（数据池）**
+
+| 名称 | 文件 | 用途 |
+|------|------|------|
+| … | [pools/<名称>.md](pools/<名称>.md) | … |
+
+**Valve 节点（门控）**
+
+| 名称 | 文件 | 脚本 | 类型 |
+|------|------|------|------|
+| … | [valves/<基名>.md](valves/<基名>.md) | [scripts/<基名>.js](scripts/<基名>.js) | 自动化 或 人工操作 |
+
+### 2.5 `## 门控执行规范` 代码块（`Processer` 类骨架，须保留；不含脚本尾部导出）
+
+门控执行顺序：**前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`）**（人工触发门控）或 **`run`**（自动触发门控）。参数与返回值**一律 snake_case**（对齐 [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__})`);
+  }
+
+  // --- 前置处理 → start ---
+  // params: { valve_id, pool_ids }
+  // returns: { orbit_link, ticket_ids }
+  async start(params) {
+    const { valve_id, pool_ids } = params;
+    // 查询入口池数据 → 按需查询化合物/工站/流程 → 写回 detail → 更新 tickets
+    // orbit_link = PageUrl.replace('{bookid}', bookid)
+    return { orbit_link, ticket_ids };
+  }
+
+  // --- 后置处理 → complete ---
+  // params: { valve_id, tickets }
+  // returns: { new_tickets }
+  async complete(params) {
+    const { valve_id, tickets } = params;
+    // 获取出口池 → 入口池 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 };
+  }
+}
+```
+
+### 2.6 `## 使用方式`（三条，语义对齐）
+
+```markdown
+## 使用方式
+
+1. 查看各 Pool 的 [pools/](pools/) 目录了解数据表结构
+2. 查看各 Valve 的 [valves/](valves/) 目录了解门控逻辑和脚本路径
+3. 执行门控时，调用对应脚本的 `Processer` 类
+```
+
+---
+
+## 3. `pools/<池名>.md` 格式（节选范例）
+
+以下与 [`../embedded-template/pools/入口池.md`](../embedded-template/pools/入口池.md) 同构，仅示意**标题层级与 Schema 表头**；行数据按流程说明填写。
+
+```markdown
+# 入口池
+
+## 概述
+
+流程入口池，存放尚未经门控处理的记录。
+
+## Schema
+
+| 字段 | 字段标题 | 字段描述 | 字段类型 | 属性 | 默认值 |
+|------|----------|----------|----------|------|--------|
+| id | ID | 业务主键 | string |  | - |
+| detail | Detail | 业务明细 JSON | json |  | - |
+```
+
+**字段列**：仅 snake_case（`a-z`、数字、`_`）。**字段标题**：展示用名称，与流程说明或业务用语对齐。
+
+**属性列规则**：流程说明里若写清枚举/可选值，写入 `枚举：…`；若写清日期或时间串格式，写入 `格式：…`；否则该格留空。
+
+### 模型引用（可选）
+
+若流程说明为该数据池指定了 3D 模型文件，在 `## Schema` 之后添加：
+
+```markdown
+## 模型引用
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | （模型文件名称） |
+| 版本 | （模型版本） |
+```
+
+无模型引用时**省略本节**（不写空占位）。
+
+---
+
+## 4. `valves/<基名>.md` 格式（节选范例）
+
+以下与 [`../embedded-template/valves/示例数据与校验门控.md`](../embedded-template/valves/示例数据与校验门控.md) 同风格节选；`输入/输出` 须与用户流程说明中门控 YAML 一致（勿照搬范例中的池名）。
+
+```markdown
+# 示例数据与校验门控
+
+## 概述
+
+演示门控文档结构：门控 YAML、化合物数据查询方式、字段映射、数据处理规则、start/complete 分工。
+
+## 关联脚本
+
+**脚本路径**: [scripts/示例数据与校验门控.js](scripts/示例数据与校验门控.js)
+
+该脚本导出 `Processer` 类，实现 `start` 和 `complete` 方法。
+
+## 执行流程
+
+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`。
+
+## 输入/输出
+
+- **输入池**: 入口池
+- **输出池**: 出口池
+```
+
+### 触发方式（推荐，缺省为人工触发）
+
+每个门控文档建议在 `## 关联脚本` 之后包含 `## 触发方式`：
+
+```markdown
+## 触发方式
+
+人工触发
+```
+
+取值为 `自动触发` 或 `人工触发`。未指定时默认按**人工触发**处理：
+- **人工触发**（默认）：门控执行顺序为 前置处理（脚本 `start`）→ 人工处理（页面）→ 后置处理（脚本 `complete`），脚本实现 `start` + `complete`。
+- **自动触发**：门控无人工处理阶段，脚本实现 `run` 方法（见 [agentic-lab-processer.md](agentic-lab-processer.md)）。
+
+### 模型引用（可选）
+
+若流程说明为该门控指定了 3D 模型文件，添加：
+
+```markdown
+## 模型引用
+
+| 属性 | 值 |
+|------|-----|
+| 名称 | （模型文件名称） |
+| 版本 | （模型版本） |
+```
+
+无模型引用时**省略本节**（不写空占位）。
+
+---
+
+## 5. `scripts/<基名>.js` 格式
+
+- 与模板相同：`Processer` 类、`constructor(context)`、`async start` / `async complete`。**脚本以 `Processer` 类定义结束，禁止在类之后添加** `return`、`module.exports`、`export default` 或任何导出语句——导出由运行环境处理。
+- **API 以** [agentic-lab-sdk.md](agentic-lab-sdk.md) **为准**，勿使用未列出的 `context` 成员。
+- **按需实现**：仅流程说明在本门控下**明确需要**的查询、写回与路由才写代码；**禁止**为对齐示例而复制与本门控无关的 `context` 调用或 `ticket.detail` 键。
+- 与流程说明中的「数据查询方式 / 字段映射 / 数据处理规则」对齐的**可运行骨架**（结构参考），见 [`../embedded-template/scripts/示例数据与校验门控.js`](../embedded-template/scripts/示例数据与校验门控.js)；验证命令与核对项见主 `SKILL.md` **验证生成结果**。
+
+---
+
+## 6. 本 skill 内对照关系
+
+| 位置 | 用途 |
+|------|------|
+| [`embedded-template/`](../embedded-template/) | **缩小真目录**：与产出包同构，优先打开对照链接与章节 |
+| 本文件（`skill-package-layout.md`） | **条文摘要**：表格列名、`Processer` 块、连接关系写法 |
+| [agentic-lab-sdk.md](agentic-lab-sdk.md) | **门控脚本 API**：`this.context` 仅使用其中已列成员 |
+
+生成时以用户流程说明为数据源；版式优先对齐 `embedded-template/` 与本文件。