@xtalpi/agentic-lab-skills 0.0.1

package/README.md

@@ -0,0 +1 @@
+# Agentic Lab Skills

package/package.json

@@ -0,0 +1,14 @@
+{
+	"name": "@xtalpi/agentic-lab-skills",
+	"version": "0.0.1",
+	"description": "Agentic Lab Skills",
+	"license": "MIT",
+	"author": "TheoXiong",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"scripts": {
+		"release": "npm publish"
+	}
+}

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

@@ -0,0 +1,360 @@
+---
+name: lab-flow-designer
+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, or Processer start/complete from pipeline docs.
+license: Proprietary
+metadata:
+  embedded-template-dir: embedded-template
+  package-shape-ref: references/skill-package-layout.md
+---
+
+# 从流程说明生成流程注册包
+
+## 适用场景
+
+用户提供**流程说明 Markdown**的路径，并需要在工作区中生成与模板**同构**的流程注册包：根级 `SKILL.md`、`pools/*.md`、`valves/*.md`、`scripts/*.js`；或在**已有流程注册包目录**上修改、增补上述文件。
+
+## 会话模式判定（须先执行）
+
+根据用户意图选择模式；**不得**在「迭代修改」会话中强行要求流程文档预检。
+
+| 模式 | 判定要点（满足其一即可倾向该模式） | 流程文档合规预检 |
+|------|-----------------------------------|------------------|
+| **初次生成** | 从流程说明**新建**整包：用户给出（或隐含）流程说明 `.md` 路径，且目标为**新建或清空后写入**完整 `SKILL.md` + `pools/` + `valves/` + `scripts/`；或用户明确要求「按流程文档生成流程注册包」「脚手架」等。 | **必须**：先完成下文「流程文档合规预检」且**通过**后，才允许进入「生成流程」。 |
+| **迭代修改** | 在**已存在**的流程注册包根目录上工作：目录内已有符合布局的 `SKILL.md` 与 `pools/` / `valves/` / `scripts/`（或用户明确仅改其中部分文件）；诉求为修脚本、改 Schema、改文案、对齐 agentic-lab-sdk、小范围结构调整等，**且**非「用一份流程说明从零重写全包」。 | **跳过**：不要求对照流程说明做合规预检；修改仍须遵守 [references/skill-package-layout.md](references/skill-package-layout.md)、[references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 等本 skill 内条文。 |
+
+**模糊时**：若用户同时给出流程说明路径与已有包路径，且表述为「用新流程说明**整体替换**本包」，按 **初次生成** 处理（须预检新流程文档）；若仅「在某某包上改一下门控脚本」，按 **迭代修改** 处理。
+
+## 输入材料
+
+| 材料 | 说明 |
+|------|------|
+| 流程说明 | **仅「初次生成」模式**下必用：用户指定的 `.md` 文件；须先通过「流程文档合规预检」（[references/业务流程文档标准.md](references/业务流程文档标准.md)），未通过不得进入「生成流程」。**「迭代修改」模式**可不引用流程说明文件 |
+| **极简目录范例（优先打开）** | 本 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**） |
+
+## 执行前确认
+
+1. **输出目录**：用户给出新建目录路径；其中 `SKILL.md` 的 `name` 须与该目录名一致（小写字母、数字、连字符，符合 Agent Skills 对 `name` 的约束）。
+2. **流程条数**：一份流程说明对应一份流程注册包；多条流水线则分多个输出目录。
+
+## 流程文档合规预检（阻断；仅「初次生成」）
+
+**适用**：仅当上文 **「会话模式判定」** 为 **初次生成** 时执行本节。**迭代修改** 模式下一整节跳过（不得要求用户提供流程说明以通过预检）。
+
+在**初次**向目标输出目录创建 `SKILL.md`、`pools/`、`valves/`、`scripts/` 之前，必须完成本预检。
+
+### 依据与范围
+
+- **依据**：[references/业务流程文档标准.md](references/业务流程文档标准.md) 全文，重点：**§1 文档级要求**、**§2 必备章节与检查点**、**§3（含 §3.1～§3.3：门控逻辑严谨性、SDK/字段可支持性、Process 与 SDK 参数格式）**、**§4 合规检查清单**；涉及 API 时须对照 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)（及流程中已引用的 `references/rhea-api/` 文档）。  
+- **对象**：用户指定的流程说明 Markdown（路径以对话约定为准）。  
+- **章节编号**：若用户文档未使用 `## 1.` … `## 6.` 数字标题，仍须能**映射**到标准中 §1～§6 所描述的同等信息（缺失即判不通过并说明缺哪块语义）。
+
+### 预检执行方式
+
+1. 打开 [references/业务流程文档标准.md](references/业务流程文档标准.md)，以 **§4 合规检查清单** 为主轴，逐项核对流程文档；对 §2 各小节**检查点**做交叉验证（池名/门控名/YAML/拓扑/字段表一致性等）。  
+2. **专项**：按标准 **§3.1～§3.3** 审查门控逻辑是否可判定、是否存在**不支持或未文档化的 API/字段**、Process/任务提交等调用的**参数与 JSON 形状**是否与 [references/agentic-lab-sdk.md](references/agentic-lab-sdk.md) 及 [references/rhea-api/](references/rhea-api/) 一致；发现问题须在《优化建议》中**单独小节**列出「不支持或不可生成项」。  
+3. 将每一项标为 **通过** / **不通过**；不通过须写明**标准条款**（可引用标准内小节标题或清单原文）。
+
+### 若不通过（强制中止）
+
+- **禁止**写入目标输出目录下的流程注册包文件（含部分生成：不得先建空目录再补全）。  
+- **必须**向用户交付 **《流程文档合规问题与优化建议》**（可用 Markdown 小节组织），且至少包含：  
+  1. **问题清单**：每条对应标准中的位置（例如「§4 清单第 n 项」「§3.2 不支持的 API」「§3.3 `items` 结构不完整」）。  
+  2. **现状说明**：流程文档中**缺失**、**矛盾**、**模糊**或**不可解析**之处（可引用现有标题、表格列名、YAML 片段；对不支持的依赖/API/字段须**点名**）。  
+  3. **可执行修改建议**：具体应**补写/改写**哪一类内容（例如消除模糊条件、改为 SDK 已支持方法、补全 `process.execute` 的 `items`/`params`/`baseURL` 说明、统一字段拼写）。  
+  4. **严重程度**：**阻断**（不满足则无法稳定生成，含不支持的 API、不可判定逻辑、Process 参数无法落地）与**建议**（不阻断但易导致脚本/Schema 歧义）。  
+  5. **（若适用）不支持或不可生成项**：集中列出标准 **§3.2 / §3.3** 拦截项，避免与一般格式问题混排。  
+- 仅当用户**随后**提供已按建议修订的流程文档时，才允许重新从本预检开始执行。
+
+### 若通过（仅初次生成）
+
+- 用 1～3 句话给出**预检通过摘要**（可列已通过的关键项），再进入 **「生成流程」**。
+
+## 生成流程（按序执行）
+
+**前置条件**：  
+- **初次生成**：已完成「流程文档合规预检」且结论为**通过**；未通过时**不得**执行本节任一步骤。  
+- **迭代修改**：跳过预检；直接进入与本任务相关的文件修改（仍须符合 `skill-package-layout`、`agentic-lab-sdk` 等约定）。
+
+**迭代修改时**：不必从本节 **§1** 起做全量「解析—规划—写入」；按用户指定范围改 `SKILL.md` / `pools/` / `valves/` / `scripts/` 即可，且**不得**为通过预检而虚构流程说明。
+
+### 1. 解析流程说明
+
+从文档中提取结构化事实（勿臆造文档未写的池或门控）：
+
+- **流程元信息**：流程标识、流程名称、版本、业务摘要。
+- **记录**：入口字段表；各门控富化字段分组。
+- **数据池**：显示名称、逻辑 ID、角色、业务含义。
+- **池间流转**：Mermaid 边与文字补充中的合流、分支语义；写入产出包 `## 流程图` 时，池须为矩形节点、门控须为六边形节点（见 §3.4）。
+- **门控**：每个门控的 `valve_id`/`gate_id`、`name`、`order`、`input`、`output` YAML 与检查规则表；若有 **化合物数据查询方式**、**字段映射**、**数据处理规则** 等小节，须单独抽取（写入对应 `valves/*.md` 与脚本注释）。若有操作员步骤则保留为业务步骤列表。
+- **门控三阶段**：每个门控可包含 **前置处理**、**人工处理**、**后置处理** 三个小节，对应门控执行顺序：`门控[前置处理]脚本 → [人工处理]页面 → 门控[后置处理]脚本`。
+  - **前置处理** → 生成 `Processer.start` 函数逻辑。须提取：
+    - 配置项表（如 `bookid`），用于拼装 `orbit_link`
+    - 规则摘要表（条件要点 + 业务动作），落入 `start` 函数体
+    - 数据处理规则（序号表），按序号写入脚本注释与实现
+  - **人工处理** → 描述 Orbit 页面的界面形态与数据绑定（由 `studio-orbit-vue-component` 等技能负责生成 UI，门控脚本中不实现）。须提取：
+    - 界面类型（超级表格、表单等）
+    - 数据来源与操作按钮描述
+  - **后置处理** → 生成 `Processer.complete` 函数逻辑。须提取：
+    - 规则摘要表（条件要点 + 业务动作），落入 `complete` 函数体
+    - 提交参数结构（如 `process.execute` 的 `items` 定义与 `params` 键级说明）
+    - 出口池路由条件与字段映射
+- **门控脚本配置项**：提取全局配置表中的各项，落入脚本为**模块级常量**：
+  - `PageUrl`（含 `{bookid}` 占位符）→ 脚本常量 `PAGE_URL`
+  - `StationBaseURL`（若有）→ 脚本常量 `STATION_BASE_URL`
+  - `门控脚本对入口池单次查询上限`（若有，如 `9000`）→ 脚本常量 `DEFAULT_QUERY_LIMIT`（覆盖默认 `999999`）
+  - 各门控**前置处理**配置项中的 `bookid` → 该门控脚本常量 `BOOK_ID`（用于 `PAGE_URL.replace('{bookid}', BOOK_ID)` 拼装 `orbit_link`）
+- **知识库**（若有独立章节）：字段级语义，供概述与注释引用。
+
+章节编号以用户文档为准；上表按常见顺序列举要提取的内容。
+
+### 2. 规划产物清单
+
+以 [`embedded-template/`](embedded-template/) 实际目录为准规划路径；细则见 [references/skill-package-layout.md](references/skill-package-layout.md) §1。
+
+- **Pool 文件数** = 数据池表行数；每个池一个 `pools/<显示名称>.md`，文件名与表中「显示名称」**逐字一致**（含标点、中间点「·」等）。
+- **Valve / Script 对** = 门控个数；每个门控生成同名一对：`valves/<基名>.md` 与 `scripts/<基名>.js`。
+- **`<基名>` 命名**：与 [references/skill-package-layout.md](references/skill-package-layout.md) §1 及 [`embedded-template/valves/`](embedded-template/valves/) 示例一致——取门控标题中的**稳定简短名**；含空格的英文片段去掉空格（例：`Process 发射判定` → `Process发射判定`）；中文门控名若标题含「门控」则保留；若标题本身为简短名（如「查看结果与复核更新」）则文件名不硬加「门控」。
+
+### 3. 写入根目录 `SKILL.md`
+
+正文**章节顺序、标题层级、表格列名、连接关系写法、`Processer` 代码块、`## 使用方式` 三条**须与 [references/skill-package-layout.md](references/skill-package-layout.md) §2 一致；一级标题为流程名称（来自流程说明）。除 frontmatter 外，二级标题须**按此顺序**出现（缺一则视为未完成）：
+
+`## 概述` → `## 核心概念` → `## 流程图`（图后紧跟 `**连接关系：**` 与编号列表）→ `## 节点清单` → `## 门控执行规范` → `## 使用方式`
+
+#### 3.1 YAML frontmatter
+
+须符合 [Agent Skills 规范](https://agentskills.io/specification)：
+
+- `name`：与输出文件夹名相同；小写字母、数字、连字符；不得连续 `--`，不得以连字符开头或结尾。
+- `description`：≤1024 字符；写清本流程做什么、何时使用该流程注册包（流程名、数据池、门控、实验/分装等关键词）。
+
+#### 3.2 `## 概述`
+
+用流程说明中的**业务摘要**与**自动化/人工路径**事实，写 1～3 段话：业务目标、主要阶段、Pool 与 Valve 如何分工。不引入文档未写的系统名。
+
+#### 3.3 `## 核心概念`
+
+固定两个三级标题，正文可结合本流程改写，语义须与模板一致：
+
+- **`### 数据池（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`），**不要**抄写模板里已过期的成员名。
+
+#### 3.4 `## 流程图`（本节内须含「连接关系」列表，与模板一致）
+
+本节**不要**单独再开 `## 连接关系` 一级标题；流程图与紧随其后的 `**连接关系：**` 列表格式见抽取文档 §2.3：
+
+1. **流程图本体**  
+   - 优先使用 **Mermaid** `flowchart` / `graph`（代码块语言为 `mermaid`）。从流程说明拷贝图时，须**改写成下列节点形状约定**（与下文示例一致）；若原文无图，则按拓扑**新画**一版。  
+   - **数据池（Pool）节点**：须为**四边形（矩形）**，语法 `节点ID[池显示名称]`（Mermaid 默认方括号即矩形）。  
+   - **门控（Valve）节点**：须为**六边形**，语法 `节点ID{{门控显示名称}}`（双花括号 `{{…}}`）。  
+   - 同一图中 `节点ID` 用简短英文/拼音/缩写（无空格），**括号内文字**与数据池表、门控标题的**显示名称**一致。  
+   - 若缺失或无法表达合流，可改用 **ASCII**；池仍用 `┌──┐` 类**矩形**框，门控用可辨认的**六角框线**（或宽矩形内首行标注「门控」）以示区别，标签与上同。  
+
+   **Mermaid 示例（形状约定）：**
+
+   ```mermaid
+   flowchart LR
+     in_pool[入口池示例]
+     gate{{某门控标题示例}}
+     out_pool[出口池示例]
+     in_pool --> gate --> out_pool
+   ```
+
+   生成时替换节点 ID 与中文标签为真实池名、门控名；复杂拓扑可 `subgraph` 分区，但**每个池仍为 `[…]`、每个门控仍为 `{{…}}`**。
+
+2. **`**连接关系：**`**（加粗小标题，紧跟在流程图之后）  
+   其下为**编号列表**，穷举拓扑中有向边对应的业务关系。每条格式与模板一致：
+
+   `序号. \`源节点\` → \`目标节点\`：一句业务说明`
+
+   「节点」为**池显示名称**或**门控显示名称**（与流程说明一致）。生成规则：
+
+   - **池 → 门控**：门控 `input.primary` / `input.secondary` 所指的池 → 该门控标题名。  
+   - **门控 → 池**：该门控 `output` 中每个分支 → 目标池显示名称。  
+   - 不合并为「池 → 池」而省略门控名，除非文档本身只描述池间结果而未命名门控（此时仍应用文档中的门控名若存在）。
+
+   顺序建议按门控 `order` 或文档叙述；**全量列出**（含合流、异常池、终点池）。
+
+#### 3.5 `## 节点清单`
+
+- **`### Pool 节点（数据池）`**：Markdown 表格，列 **`名称` | `文件` | `用途`**。  
+  - `名称`：与 `pools/*.md` 文件名相同。  
+  - `文件`：Markdown 链接 `[pools/<名称>.md](pools/<名称>.md)`。  
+  - `用途`：来自数据池表「业务含义」或概述，一两句。
+
+- **`### Valve 节点（门控）`**：Markdown 表格，列 **`名称` | `文件` | `脚本` | `类型`**。  
+  - `名称`：与流程说明门控标题一致（可读名，可与 valve 文件名略有后缀差异时在「名称」列用完整名）。  
+  - `文件`：`[valves/<基名>.md](valves/<基名>.md)`。  
+  - `脚本`：`[scripts/<基名>.js](scripts/<基名>.js)`。  
+  - `类型`：流程说明中该门控以**操作员步骤/人工称量**为主则填 `人工操作`，否则填 `自动化`（与模板粒度一致；文档无暗示时默认 `自动化`）。
+
+#### 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)）。
+
+#### 3.7 `## 使用方式`
+
+固定 3 条编号步骤，语义对齐模板：查阅 `pools/` Schema、查阅 `valves/` 与脚本路径、执行门控时调用对应 `Processer`。
+
+### 4. 写入每个 `pools/<显示名称>.md`
+
+标题与表格格式对齐 [references/skill-package-layout.md](references/skill-package-layout.md) §3：`# 标题`、`## 概述`、`## Schema`（列名：**字段、字段标题、字段描述、字段类型、属性、默认值**，共六列）。
+
+- **概述**：该池在流程中的职责（数据池含义 + 拓扑位置）。
+- **Schema**  
+  - **字段行范围（按需）**：Schema 表**仅**收录流程说明中与本池记录**明确相关**的字段（如入口字段表、该池字段/列描述、某门控写明写入本池记录者）。**禁止**为对齐 `embedded-template` 或追求「表看起来完整」而增加流程文档未出现的业务字段行。  
+  - **字段**：机器可读键名，**必须**为 `a-z`、数字与下划线组成的 **snake_case**（全小写，如 `compound_id`、`target_amount_1_mg`）。由流程说明中的「字段名」映射而来：去掉空格与括号说明、统一小写、空格或混合写法改为下划线（例：`Compound ID` → `compound_id`，`Target Amount 1 (mg)` → `target_amount_1_mg`）。  
+  - **字段标题**：与流程说明或业务系统一致的**展示名**（可为英文短语如 `Compound ID`，或简短中文标题），供人读表与 UI 列头；**不要**把原「字段」列的英文混进「字段」列。  
+  - **字段描述**、**字段类型**、**属性**、**默认值**：规则同前（属性仍仅写枚举/格式归纳，无则留空）。
+- **属性列**：仅当流程说明对该字段给出了**可选值/枚举**（含「枚举：…」「如 A、B」、用顿号/逗号分隔的取值列表等）时，将归纳后的约束写入本列，**建议**以 `枚举：` 开头（例：`枚举：固体颗粒过大，流动性差，强吸水性，易结块，易粘黏，强静电吸附，液体`）。若说明仅在「说明」列内嵌枚举长句，可将枚举部分抽到「属性」，「字段描述」保留简短业务含义。若说明中约定了**日期或时间的表达格式**（如 ISO8601、`YYYYMMDD`、批次号中的日期段），以 `格式：` 开头写入本列。无枚举、无格式约定则**属性列留空**（不写 `-` 占位语）。业务含义仍以「字段描述」为主，避免在描述与属性中完全重复粘贴同一段长文。
+
+### 5. 写入每个 `valves/<基名>.md`
+
+章节与排版对齐抽取文档 §4，**至少**包含：`## 概述`（编号步骤）、`## 关联脚本`、`## 执行流程`、`## 输入/输出`。`输入/输出` 须与门控 YAML 的 `primary`/`secondary` 与各输出池**显示名称**一致，**勿**照搬范例中的池名。
+
+若流程说明对某门控给出了下列块，须在对应 `valves/<基名>.md` 中**原样结构化呈现**（标题可用 `##` / `###`，便于脚本作者对照）：
+
+- **门控 YAML**（`valve_id`、`name`、`order`、`input`、`output`）；若文档使用 `Stash:` 等非标准键表示目标池，**保留原文**，并在 valve 文内加一句说明：实现时与 `pool.getNext` 返回的 `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` 的对应关系写清。
+- **字段映射表**：「门控加工数据 ↔ 库字段 / API 字段」；脚本写入 `ticket.detail` 的键须与 **pools Schema「字段」列（snake_case）** 一致。
+- **数据处理规则**表：序号（如 1.1、1.2）须在脚本注释中可逐条追溯。
+
+参考范例：[embedded-template/valves/示例数据与校验门控.md](embedded-template/valves/示例数据与校验门控.md)。
+
+### 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`；脚本以类定义结束，禁止添加任何导出语句。示例中与本门控文档无关的业务分支**省略**。
+3. **注释**与流程说明规则编号对应；业务分支处可用 `TODO`，**不得**编造文档未定义的池名或 API。
+4. **实现逻辑**须遵循下文「门控脚本编写指引」（含 **`limit`/`offset` 默认全量** 约定）。
+5. **按需生成**：详见下文「编写指引 §0」。
+
+## 门控脚本编写指引
+
+编写 `scripts/<基名>.js` 时，将流程说明中的**门控逻辑**与 **Agentic Lab SDK** 对齐，推荐顺序如下。
+
+### 0. 按需生成（禁止冗余）
+
+- **代码**：只实现本门控流程说明中已写出的判定、外部查询、对 `ticket.detail` 的更新、出口路由；文档未写的 SDK 调用、辅助逻辑、占位字段一律不写。
+- **`ticket.detail` 键**：读写的 snake_case 键仅来自**字段映射**、**数据处理规则**或规则中显式引用的量；**禁止**新增文档未列出的业务键（含调试用 `_foo`、仅为对齐示例的附加键）。
+- **与 `embedded-template` 的关系**：**目录与 `Processer` 形态**可对齐；**具体调用的 `context` 方法与写入字段**以本门控文档为准，**禁止**整段拷贝示例脚本中与本门控无关的 compound / station / process 等逻辑。
+
+### 1. 从流程说明抽取
+
+下表各项**仅在该门控的流程说明中实际出现对应小节或规则时**才落入脚本；缺失则**不生成**该路径（或仅留 `TODO` 并在预检《优化建议》中提示文档缺口，**不得**臆造业务补全）。
+
+| 来源 | 落点（脚本侧） |
+|------|----------------|
+| 门控 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) |
+| **字段映射表** | 将 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`**），生成门控脚本时遵守：
+
+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` 对应**后置处理**。
+
+**代码格式与风格**须严格对齐 [references/agentic-lab-processer.md](references/agentic-lab-processer.md) 中的类型定义：
+
+- **`start` 入参** `StartExecutionParams`：**必须**含 `valve_id`（`number`）、`pool_ids`（`number[]`）；可通过 `[propName: string]: any` 扩展，但核心参数不可缺少或改名。
+- **`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 原有格式，不受此约束。
+
+- **`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 }` 。
+
+  **`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`）。
+
+### 5. 类型安全的字段访问（防止运行时 TypeError）
+
+`ticket.detail` 的值为**任意 JSON 类型**（`string` / `number` / `boolean` / `array` / `object` / `null`）——即使 pool Schema 声明为 `text`，运行时也可能收到 `number` 或 `null`。**生成代码时须遵守**：
+
+1. **禁止直接对 `detail` 值调用 `.trim()` / `.split()` / `.toLowerCase()` 等 `String.prototype` 方法**——若该值为 `number` 或 `null`，会抛出 `TypeError: xxx.trim is not a function`。
+2. **字符串读取**：先用 `String()` 转换或 `typeof` 判断：
+   ```js
+   // ✅ 正确
+   const barcode = String(detail.source_barcode ?? '');
+   // ✅ 正确
+   const barcode = detail.source_barcode != null ? String(detail.source_barcode) : '';
+   // ❌ 错误——detail.source_barcode 可能为 number / null
+   const barcode = detail.source_barcode.trim();
+   ```
+3. **数字读取**：先用 `Number()` 转换并检查 `Number.isFinite()`：
+   ```js
+   const amount = Number(detail.error_tolerance_mg);
+   if (!Number.isFinite(amount)) { /* fallback */ }
+   ```
+4. **数组 / 对象读取**：先用 `Array.isArray()` 或 `typeof === 'object'` 检查后再操作。
+5. 若脚本内多处需要安全取值，可在模块级定义简短辅助函数（见 [embedded-template/scripts/示例数据与校验门控.js](embedded-template/scripts/示例数据与校验门控.js) 中的 `str()` / `num()`），减少重复模式。
+
+### 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`**）  
+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`**）。
+
+## Gotchas
+
+生成前快速检查清单（规则详见对应章节，此处仅提醒要点）：
+
+- 合规预检仅「初次生成」时执行（见「会话模式判定」）
+- 列表查询默认 `limit: 999999`；门控脚本配置项有自定义上限时从其取（见「编写指引 §2」）
+- Pool Schema 须含六列（字段/字段标题/字段描述/字段类型/属性/默认值），字段列为 snake_case（见「生成流程 §4」）
+- 池文件名与数据池表「显示名称」逐字一致（见「生成流程 §2」）
+- Mermaid 池 = 矩形 `[…]`、门控 = 六边形 `{{…}}`（见「生成流程 §3.4」）
+- 合流门控 `pool_ids` 须覆盖所有入口池（见「编写指引 §1」）
+- `context` 仅使用 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 已列方法，禁止虚构 API
+- start/complete 输入输出严格对齐 [agentic-lab-processer.md](references/agentic-lab-processer.md)（见「编写指引 §3」）
+- 一级参数/返回值 snake_case；嵌套 JSON 保持原格式（见「编写指引 §3」）
+- `orbit_link` = `PageUrl` + `bookid`（见「编写指引 §3 orbit_link 生成步骤」）
+- 门控三阶段：前置处理 → `start`、后置处理 → `complete`、人工处理 → UI 技能（见「解析流程说明 §1」）
+- `complete` 优先使用 `params.tickets`，非必要不重查（见「编写指引 §3」）
+- 脚本以 `Processer` 类结束，禁止 `return`/`module.exports`/`export`（见「生成流程 §6」）
+- 按需生成，禁止冗余：代码和 Schema 仅覆盖流程文档明确写出的内容（见「编写指引 §0」）
+- **类型安全**：禁止直接对 `ticket.detail` 值调用 `.trim()` / `.split()` 等字符串方法；必须先 `String()` 转换或 `typeof` 判断（见「编写指引 §5」）
+
+## 扩展
+
+若一份说明含多条独立流水线，应对每条线各建一个输出目录与独立 `SKILL.md`（各自 `name`），勿混在同一包内。
+
+## 验证生成结果
+
+对**生成目录**（用户指定的输出路径）逐项自检；下列**对照物均为本 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) 篇首约定。
+
+**对照物**：[embedded-template/](embedded-template/)（已知良好缩小范例）、[references/skill-package-layout.md](references/skill-package-layout.md)、[references/agentic-lab-sdk.md](references/agentic-lab-sdk.md)。
+
+**说明**：若工作区根目录另有自动化校验 Shell，可自行对生成包运行；具体脚本名与参数以工作区为准，**不**写入本 skill 必读引用。内置 [`embedded-template/SKILL.md`](embedded-template/SKILL.md) 的 `name` 可与目录名 `embedded-template` **故意不一致**（仅示意）。

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

@@ -0,0 +1,84 @@
+---
+name: embedded-flow-example
+description: >-
+  示意流程注册包。仅作 flow-package-from-design 内置版式样例，演示 SKILL/pools/valves/scripts 目录与章节结构。
+  Do not install as a standalone skill; copy layout to your output directory and replace name with the output folder name.
+---
+
+# 示意流程
+
+## 概述
+
+示意流程用于演示「数据池 + 门控」协作时的文档写法：记录从入口池进入门控，经 **compound / chemical_record 类查询** 与规则校验后写入出口池。生成真实流程注册包时，本段替换为流程说明中的业务摘要。
+
+## 核心概念
+
+### 数据池（Pool）
+
+Pool 存多条记录，每池有独立 Schema，字段随阶段可不同。
+
+### 门控（Valve）
+
+每个门控对应一个脚本，导出 `Processer`，实现 `start` 与 `complete`。`this.context` 能力以本 skill 的 [references/agentic-lab-sdk.md](../references/agentic-lab-sdk.md) 为准；门控文档结构见 [valves/示例数据与校验门控.md](valves/示例数据与校验门控.md)。
+
+## 流程图
+
+（与 flow-package-from-design 约定一致：**池 = 矩形 `[…]`，门控 = 六边形 `{{…}}`**。）
+
+```mermaid
+flowchart LR
+  in_pool[入口池]
+  gate{{示例数据与校验门控}}
+  out_pool[出口池]
+  in_pool --> gate --> out_pool
+```
+
+**连接关系：**
+
+1. `入口池` → `示例数据与校验门控`：待处理记录进入门控
+2. `示例数据与校验门控` → `出口池`：校验与回填完成后写入出口池
+
+## 节点清单
+
+### Pool 节点（数据池）
+
+| 名称 | 文件 | 用途 |
+|------|------|------|
+| 入口池 | [pools/入口池.md](pools/入口池.md) | 流程入口数据 |
+| 出口池 | [pools/出口池.md](pools/出口池.md) | 流程出口数据 |
+
+### Valve 节点（门控）
+
+| 名称 | 文件 | 脚本 | 类型 |
+|------|------|------|------|
+| 示例数据与校验门控 | [valves/示例数据与校验门控.md](valves/示例数据与校验门控.md) | [scripts/示例数据与校验门控.js](scripts/示例数据与校验门控.js) | 自动化 |
+
+## 门控执行规范
+
+每个 Valve 的 JavaScript 脚本导出 `Processer` 类，必须实现 `start` / `complete`。由流程说明生成真实流程注册包时，脚本**仅实现文档明确要求**的逻辑与字段处理，须遵循主 `SKILL.md`「门控脚本编写指引」；下方代码块仅示意类骨架。
+
+```javascript
+class Processer {
+  constructor(context) {
+    this.context = context;
+  }
+
+  async start(params) {
+    // params: { valve_id, pool_ids }
+    // 从入口池拉取数据，执行处理逻辑
+    // 返回中间结果
+  }
+
+  async complete(params) {
+    // params: { valve_id, tickets }
+    // 将数据分发到出口池，更新状态
+    // 返回最终结果
+  }
+}
+```
+
+## 使用方式
+
+1. 查看各 Pool 的 [pools/](pools/) 目录了解数据表结构
+2. 查看各 Valve 的 [valves/](valves/) 目录了解门控逻辑和脚本路径
+3. 执行门控时，调用对应脚本的 `Processer` 类

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

@@ -0,0 +1,12 @@
+# 入口池
+
+## 概述
+
+流程入口池，存放尚未经门控处理的记录。
+
+## Schema
+
+| 字段 | 字段标题 | 字段描述 | 字段类型 | 属性 | 默认值 |
+|------|----------|----------|----------|------|--------|
+| id | ID | 业务主键 | string |  | - |
+| detail | Detail | 业务明细 JSON | json |  | - |

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

@@ -0,0 +1,12 @@
+# 出口池
+
+## 概述
+
+流程出口池，存放经门控处理后的记录。
+
+## Schema
+
+| 字段 | 字段标题 | 字段描述 | 字段类型 | 属性 | 默认值 |
+|------|----------|----------|----------|------|--------|
+| id | ID | 业务主键 | string |  | - |
+| detail | Detail | 业务明细 JSON | json |  | - |