@xtalpi/agentic-lab-skills 0.0.4 → 0.0.5

package/package.json

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

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

@@ -2,8 +2,9 @@
 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.
+  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.
 license: Proprietary
 metadata:
   embedded-template-dir: embedded-template
@@ -14,7 +15,8 @@ metadata:
 
 ## 适用场景
 
-用户提供**流程说明 Markdown**的路径，并需要在工作区中生成与模板**同构**的流程注册包：根级 `SKILL.md`、`pools/*.md`、`valves/*.md`、`scripts/*.js`；或在**已有流程注册包目录**上修改、增补上述文件。
+- 用户提供**流程说明 Markdown**的路径，并需要在工作区中生成与模板**同构**的流程注册包：根级 `SKILL.md`、`pools/*.md`、`valves/*.md`、`scripts/*.js`；或在**已有流程注册包目录**上修改、增补上述文件。
+- 用户希望生成一份**业务流程文档模板**，用于梳理和描述新的业务流程，完善后再用本技能生成流程注册包。
 
 ## 会话模式判定（须先执行）
 
@@ -24,6 +26,7 @@ metadata:
 |------|-----------------------------------|------------------|
 | **初次生成** | 从流程说明**新建**整包：用户给出（或隐含）流程说明 `.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 内条文。 |
+| **生成流程文档** | 用户要求生成流程文档、流程模板、业务流程描述文档 | 基于模板和用户描述，生成预填充的业务流程文档并写入本地文件；**不生成**流程注册包。 |
 
 **模糊时**：若用户同时给出流程说明路径与已有包路径，且表述为「用新流程说明**整体替换**本包」，按 **初次生成** 处理（须预检新流程文档）；若仅「在某某包上改一下门控脚本」，按 **迭代修改** 处理。
 
@@ -36,12 +39,26 @@ metadata:
 | **版式条文** | [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**） |
+| **业务流程文档模板** | [templates/业务流程文档模板.md](templates/业务流程文档模板.md)：空白模板，各章节带占位提示；用于「生成流程文档」模式 |
+| **业务流程文档示例** | [templates/业务流程文档示例.md](templates/业务流程文档示例.md)：基于 Fragment 分装流程的填写示例，供参考 |
 
 ## 执行前确认
 
-1. **输出目录**：用户给出新建目录路径；其中 `SKILL.md` 的 `name` 须与该目录名一致（小写字母、数字、连字符，符合 Agent Skills 对 `name` 的约束）。
+1. **输出目录**（按优先级）：① 用户指定了具体路径 → 使用该路径；② 用户指定了流程说明文档路径 → 在文档所在目录下生成；③ 均未指定 → 在当前工作目录（CWD）下生成。**禁止**私自在任何子路径（如 `docs/`）下创建目录。`SKILL.md` 的 `name` 须与输出目录名一致（小写字母、数字、连字符，符合 Agent Skills 对 `name` 的约束）。
 2. **流程条数**：一份流程说明对应一份流程注册包；多条流水线则分多个输出目录。
 
+## 生成流程文档（仅「生成流程文档」模式）
+
+当用户要求生成流程文档模板时，按以下步骤执行：
+
+1. 读取 [templates/业务流程文档模板.md](templates/业务流程文档模板.md) 获取文档结构
+2. 参考 [templates/业务流程文档示例.md](templates/业务流程文档示例.md) 了解各章节的填写规范
+3. 根据用户描述的业务场景，预填充模板中的各章节（能确定的内容填入，不确定的保留占位提示）
+4. 将文档写入用户指定路径（按优先级：① 用户指定了具体路径 → 使用该路径；② 用户指定了参考文档路径 → 在该文档所在目录下生成 `【流程文档】{流程名称}.md`；③ 均未指定 → 在当前工作目录下生成 `【流程文档】{流程名称}.md`。**禁止**私自创建子目录）
+5. 提示用户：完善文档内容后，可直接用本技能的「初次生成」模式生成流程注册包
+
+**注意**：生成流程文档模式下**不执行**流程文档合规预检，也**不生成**流程注册包。
+
 ## 流程文档合规预检（阻断；仅「初次生成」）
 
 **适用**：仅当上文 **「会话模式判定」** 为 **初次生成** 时执行本节。**迭代修改** 模式下一整节跳过（不得要求用户提供流程说明以通过预检）。
@@ -322,6 +339,48 @@ metadata:
 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`**）。
 
+### 7. 产物版本追踪
+
+每次生成或修改流程注册包时，**必须**在产物中维护版本信息，帮助用户识别产物来源和版本。
+
+#### 7.1 SKILL.md frontmatter 版本
+
+生成的流程注册包 `SKILL.md` frontmatter **必须**包含 `metadata` 块：
+
+```yaml
+---
+name: <与根目录同名-kebab-case>
+description: <≤1024 字符>
+metadata:
+  version: "<semver>"
+  generated_by: lab-flow-designer
+  generated_at: "<YYYY-MM-DD>"
+---
+```
+
+- **初次生成**：`version: "1.0.0"`，`generated_at` 为当天日期。
+- **迭代修改**：读取现有 `metadata.version`，按变更范围递增（patch：修复；minor：新增逻辑；major：输入输出结构变更），更新 `generated_at`。
+
+#### 7.2 脚本版本常量
+
+每个 `scripts/<基名>.js` 在 doc comment 之后、`DEFAULT_QUERY_LIMIT` 等业务常量之前，**必须**包含：
+
+```javascript
+// --- Artifact Version ---
+const __ARTIFACT_VERSION__ = '<与 SKILL.md metadata.version 一致>';
+const __ARTIFACT_SKILL__ = 'lab-flow-designer';
+```
+
+迭代修改时同步更新 `__ARTIFACT_VERSION__` 值。
+
+#### 7.3 构造函数版本打印
+
+`Processer` 的 `constructor` 中，`this.context = context;` 之后**必须**添加：
+
+```javascript
+console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`);
+```
+
 ## Gotchas
 
 生成前快速检查清单（规则详见对应章节，此处仅提醒要点）：
@@ -341,6 +400,7 @@ metadata:
 - 脚本以 `Processer` 类结束，禁止 `return`/`module.exports`/`export`（见「生成流程 §6」）
 - 按需生成，禁止冗余：代码和 Schema 仅覆盖流程文档明确写出的内容（见「编写指引 §0」）
 - **类型安全**：禁止直接对 `ticket.detail` 值调用 `.trim()` / `.split()` 等字符串方法；必须先 `String()` 转换或 `typeof` 判断（见「编写指引 §5」）
+- **产物版本**：SKILL.md frontmatter 须含 `metadata.version`；每个脚本须含 `__ARTIFACT_VERSION__` / `__ARTIFACT_SKILL__` 常量及 constructor `console.info`（见「编写指引 §7」）
 
 ## 扩展
 
@@ -348,13 +408,15 @@ metadata:
 
 ## 验证生成结果
 
-对**生成目录**（用户指定的输出路径）逐项自检；下列**对照物均为本 skill 内路径**。
+对**生成目录**（输出目录，即当前工作目录或用户指定的路径）逐项自检；下列**对照物均为本 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) 篇首约定。
 
+**版本追踪**：`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)。
 
 **说明**：若工作区根目录另有自动化校验 Shell，可自行对生成包运行；具体脚本名与参数以工作区为准，**不**写入本 skill 必读引用。内置 [`embedded-template/SKILL.md`](embedded-template/SKILL.md) 的 `name` 可与目录名 `embedded-template` **故意不一致**（仅示意）。

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

@@ -3,6 +3,10 @@ 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.
+metadata:
+  version: "1.0.0"
+  generated_by: lab-flow-designer
+  generated_at: "2026-06-20"
 ---
 
 # 示意流程

package/skills/lab-flow-designer/embedded-template/scripts//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.js

@@ -10,6 +10,11 @@
  * 类型安全：ticket.detail 值为任意 JSON 类型（string/number/null/array/object），
  * 禁止直接调 .trim()/.split() 等 String 方法——须先 String() 转换（见「编写指引 §5」）。
  */
+
+// --- Artifact Version ---
+const __ARTIFACT_VERSION__ = '1.0.0';
+const __ARTIFACT_SKILL__ = 'lab-flow-designer';
+
 const DEFAULT_QUERY_LIMIT = 999999;
 
 // orbit_link 由流程文档门控脚本配置项中的 PageUrl 与门控前置处理中的 bookid 组合生成
@@ -28,6 +33,7 @@ function num(v, fallback) {
 class Processer {
   constructor(context) {
     this.context = context;
+    console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`);
   }
 
   // --- 前置处理 → start ---

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

@@ -45,6 +45,7 @@ class Processer {
   // context: 执行引擎提供的SDK
   constructor(context) {
     this.context = context;
+    console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`);
   }
 
   // params: { valve_id, pool_ids }

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

@@ -31,6 +31,10 @@
 ---
 name: <与根目录同名-kebab-case>
 description: <≤1024 字符：本流程做什么 + 何时使用该流程注册包，含触发关键词>
+metadata:
+  version: "<semver，初次生成为 1.0.0>"
+  generated_by: lab-flow-designer
+  generated_at: "<YYYY-MM-DD>"
 ---
 ```
 
@@ -88,6 +92,7 @@ description: <≤1024 字符：本流程做什么 + 何时使用该流程注册
 class Processer {
   constructor(context) {
     this.context = context;
+    console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`);
   }
 
   // --- 前置处理 → start ---

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

@@ -0,0 +1,169 @@
+# 业务执行手册描述
+
+# （流程名称）
+
+***
+
+## 1. 流程元信息
+
+| 属性   | 值 |
+| ---- | --- |
+| 流程标识 | （机器可读 ID，如 `fragment`，小写字母、数字、下划线） |
+| 流程名称 | （人类可读名称） |
+| 版本   | （如 1.0.0） |
+| 业务摘要 | （1～3 句说明业务目标与边界） |
+
+***
+
+## 2. 记录（Record）
+
+**记录**是沿数据池与门控流转的最小业务单元：一条记录对应（描述最小流转单元，例如「一个化合物的分装任务」）。字段分两类：
+
+* **入口字段**：进入流程时即应具备（或由上游写入）。
+* **富化字段**：在特定门控的检查或回填过程中逐步写入；下文按门控分组列出。
+
+### 2.1 入口字段（必填与选填）
+
+| 字段名 | 类型 | 必填 | 说明 |
+| ----- | ---- | -- | --- |
+| （例：Order ID） | text | Y | （字段说明） |
+| （例：Target Amount） | number | Y | （字段说明，注明单位如 mg） |
+| （例：Status） | text | N | （枚举/布尔字段须列出可选值） |
+
+### 2.2 门控「（门控 1 显示名称）」可能写入的字段
+
+| 字段名 | 类型 | 说明 |
+| ----- | ---- | --- |
+| （例：Available Amount） | number | （字段含义与来源） |
+| （例：Source Barcode） | text | （字段含义与来源） |
+
+### 2.3 门控「（门控 2 显示名称）」可能写入的字段
+
+| 字段名 | 类型 | 说明 |
+| ----- | ---- | --- |
+| （按需继续添加...） | | |
+
+> **提示**：每个会修改记录的门控都需要一个对应的富化字段小节（§2.x）。若门控不写入新字段，可显式写「无新增字段」。
+
+***
+
+## 3. 数据池（Stash）
+
+数据池是**记录的容器**：记录只在门控驱动下从一个池进入另一个池。
+
+| 显示名称 | 逻辑 ID | 角色 | 池中记录的业务含义 |
+| ------- | ------- | --- | ------------- |
+| （例：待处理池） | `stash_input` | 入口池 | （业务含义） |
+| （例：处理中池） | `stash_processing` | 中间池 | （业务含义） |
+| （例：异常池） | `stash_error` | 异常池 | （业务含义） |
+| （例：完成池） | `stash_done` | 终点池 | （业务含义） |
+
+> **提示**：显示名称须与门控 YAML 中的 `input`/`output` 池名逐字一致（含标点、中间点「·」等）。逻辑 ID 仅使用小写字母、数字、下划线。
+
+***
+
+## 4. 池间流转（拓扑）
+
+```mermaid
+graph LR
+    stash_input["待处理池"]
+    gate_1{{"门控 1 名称"}}
+    stash_processing["处理中池"]
+
+    stash_input --> gate_1 --> stash_processing
+```
+
+> **提示**：数据池使用矩形 `["..."]`，门控使用六边形 `{{"..."}}`。
+
+**文字补充**
+
+* **（门控 1 名称）**：入口为「（入口池名）」；出口为（列出各出口分支语义）。
+* **（门控 2 名称）**：（描述入口池集合和出口分支；合流门控须写明多入口来源）。
+
+***
+
+## 5. 门控（Valve）
+
+每个门控是**检查—路由**节点：对输入池中待处理的记录执行业务规则，并依据结果将记录路由到**唯一匹配的输出池**。
+
+查询约定：
+- （例：默认最大查询条数 3000，即 limit: 3000）
+
+约定字段：
+
+* `valve_id`：文档内稳定标识。
+* `order`：建议执行顺序，与拓扑中依赖关系一致。
+* `input`：`primary` 为主输入池；`secondary` 为合流时的第二输入池。
+* `output`：每条包含目标池与路由条件。
+
+### 5.1 （门控 1 显示名称）
+
+```yaml
+valve_id: valve_1
+name: （门控显示名称，须与拓扑边标签一致）
+order: 1
+input:
+  primary: （入口池显示名称）
+output:
+  - Stash: （出口池 A 显示名称）
+    condition: （路由条件，须引用 §2 中的字段名）
+  - Stash: （出口池 B 显示名称）
+    condition: （路由条件）
+```
+
+**化合物数据查询方式**（若本门控需要查询外部数据）
+
+（说明查哪类库、用哪些入口字段作键、返回什么、汇总规则等）
+
+**字段映射表**（若存在库表/API 列与门控加工字段对应）
+
+| 门控加工数据 | 库字段 |
+| --------- | ----- |
+| （例：性状） | （例：chemistProperty） |
+
+**数据处理规则**
+
+| 序号 | 规则摘要 | 条件要点 | 业务动作或结果 |
+| --- | ------- | ------- | ----------- |
+| 1.1 | （简述） | （条件，须引用字段名） | （动作或路由结果） |
+| 1.2 | （简述） | （条件） | （动作或路由结果） |
+
+**操作员步骤**（若为人工门控）
+
+1. （步骤描述，可执行、可验收）
+2. （...）
+
+***
+
+### 5.2 （门控 2 显示名称）
+
+```yaml
+valve_id: valve_2
+name: （门控显示名称）
+order: 2
+input:
+  primary: （入口池显示名称）
+  secondary: （合流时的第二入口池，无合流则删除此行）
+output:
+  - Stash: （出口池显示名称）
+    condition: （路由条件）
+```
+
+**数据处理规则**
+
+| 序号 | 规则摘要 | 条件要点 | 业务动作或结果 |
+| --- | ------- | ------- | ----------- |
+| 2.1 | （简述） | （条件） | （动作或路由结果） |
+
+> **提示**：按需复制门控子节，每个门控至少包含 YAML 代码块和数据处理规则表。需查询外部数据的加「查询方式」和「字段映射表」，人工门控加「操作员步骤」。
+
+***
+
+## 6. 知识库 / 外部主数据（按需）
+
+> 若门控规则依赖外部主数据（如化合物知识库、设备资源库等），在此列出字段语义。无外部依赖时可写「本流程不依赖外部主数据」。
+
+| 逻辑键 | 字段含义 | 类型/取值说明 |
+| ----- | ------- | ----------- |
+| （例：Compound ID） | （含义） | text |
+| （例：latest_amount_mg） | （含义） | number |

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

@@ -0,0 +1,197 @@
+# 业务执行手册描述
+
+# Fragment 分装流程
+
+***
+
+## 1. 流程元信息
+
+| 属性   | 值 |
+| ---- | --- |
+| 流程标识 | `fragment` |
+| 流程名称 | Fragment 分装 |
+| 版本   | 1.0.0 |
+| 业务摘要 | 将化合物从源瓶按目标量分装到 1～3 个目标瓶；同一记录可走自动化或人工路径，最终在「已分装」状态结束。 |
+
+***
+
+## 2. 记录（Record）
+
+**记录**是沿数据池与门控流转的最小业务单元：一条记录对应一个化合物的分装任务。字段分两类：
+
+* **入口字段**：进入流程时即应具备（或由上游写入）。
+* **富化字段**：在特定门控的检查或回填过程中逐步写入；下文按门控分组列出。
+
+### 2.1 入口字段（必填与选填）
+
+| 字段名 | 类型 | 必填 | 说明 |
+| ----- | ---- | -- | --- |
+| Ticket ID | text | Y | 系统分配，单个池子里唯一 |
+| ALO Order ID | text | Y | 上层订单号 |
+| Compound ID | text | Y | 化合物编号，用于查询知识库 |
+| CAS | text | N | CAS 号 |
+| MW | number | Y | 分子量 (g/mol)，须大于 0 |
+| Salt Form | text | Y | 盐型，如 Free Base、HCl、Na |
+| Target Amount 1 (mg) | number | Y | 目标瓶 1 目标量 |
+| Tolerance 1 (mg) | number | Y | 目标瓶 1 允许误差，默认 0.5 mg |
+| Target Amount 2 (mg) | number | N | 目标瓶 2 目标量 |
+| Target Amount 3 (mg) | number | N | 目标瓶 3 目标量 |
+
+### 2.2 门控「数据完整性与需求量门控」可能写入的字段
+
+| 字段名 | 类型 | 说明 |
+| ----- | ---- | --- |
+| Requested Amount | number | 需求总量 (mg)，为 Target Amount 1 + 2 + 3 的和 |
+| Available Amount | number | 从化合物管理系统查询相同 CAS 号且 Status = 可用的 Latest Amount 总和 |
+| Source Barcode | text | 源瓶条码；来自化合物库查询 |
+| 是否缺料 | 枚举 | 缺料 / 充足 |
+| 性状 (Chemist) | 枚举 | 粉末 / 液体 / 固体等，默认从化合物库查询 |
+| 可舀粉判断 (Feasibility of Dispensing) | text | 是否可以舀粉 |
+
+### 2.3 门控「查看结果与复核更新」可能写入的字段
+
+| 字段名 | 类型 | 说明 |
+| ----- | ---- | --- |
+| Actual Amount 1 | number | 第一个目标瓶自动化称量量 |
+| Actual Amount 2 | number | 第二个目标瓶自动化称量量 |
+| Actual Amount 3 | number | 第三个目标瓶自动化称量量 |
+| 执行状态 | 枚举 | 执行完成 / 执行失败 |
+| 执行方式 | 枚举 | Automated / Manual，该门控默认为 Automated |
+| 人工确认状态 | 枚举 | 成功 / 失败，由人工最终确认 |
+| 执行失败原因 | text | 人工填写的备注 |
+
+***
+
+## 3. 数据池（Stash）
+
+| 显示名称 | 逻辑 ID | 角色 | 池中记录的业务含义 |
+| ------- | ------- | --- | ------------- |
+| 待分装化合物池 | `stash_input` | 入口池 | 上层下发、尚未经首道门控处理 |
+| 已领取·可自动化的化合物池 | `stash_auto` | 中间池 | 可走自动称粉路径且非缺料 |
+| 已领取·不可自动称量的化合物池 | `stash_manual` | 中间池 | 不可自动称粉，但非缺料 |
+| 上机实验池 | `stash_on_machine` | 中间池 | 已提交设备执行或等待结果 |
+| 完成实验池 | `stash_success` | 中间池 | 自动化路径下称量结果在容差内通过 |
+| 失败实验池 | `stash_failure` | 中间池 | 自动化失败或终检未通过 |
+| 人工完成物料池 | `stash_manual_done` | 中间池 | 人工路径完成称量与回填 |
+| 缺料化合物池 | `stash_missing` | 异常池 | 无可用源瓶或库存不足 |
+| 已分装化合物池 | `stash_done` | 终点池 | 交货确认完成，流程结束 |
+
+***
+
+## 4. 池间流转（拓扑）
+
+```mermaid
+graph LR
+    stash_input["待分装化合物池"]
+    gate_1{{"数据完整性与需求量门控"}}
+    stash_auto["已领取·可自动化的化合物池"]
+    stash_manual["已领取·不可自动称量的化合物池"]
+    stash_missing["缺料化合物池"]
+    gate_3{{"查看结果与复核更新"}}
+    stash_on_machine["上机实验池"]
+    stash_success["完成实验池"]
+    stash_failure["失败实验池"]
+
+    stash_input --> gate_1
+    gate_1 --> stash_auto
+    gate_1 --> stash_manual
+    gate_1 --> stash_missing
+
+    stash_on_machine --> gate_3
+    gate_3 --> stash_success
+    gate_3 --> stash_failure
+```
+
+**文字补充**
+
+* **数据完整性与需求量门控**：唯一入口为「待分装化合物池」；出口为三选一（可自动化 / 不可自动称量 / 缺料）。
+* **查看结果与复核更新**：仅从「上机实验池」进入；出口为「完成实验池」或「失败实验池」（按各目标瓶实际量与容差比较）。
+
+***
+
+## 5. 门控（Valve）
+
+每个门控是**检查—路由**节点：对输入池中待处理的记录执行业务规则，并依据结果将记录路由到**唯一匹配的输出池**。
+
+查询约定：
+- 默认最大查询条数 3000，即（limit: 3000）
+
+### 5.1 数据完整性与需求量门控
+
+```yaml
+valve_id: valve_1
+name: 数据完整性与需求量门控
+order: 1
+input:
+  primary: 待分装化合物池
+output:
+  - Stash: 已领取·可自动化的化合物池
+    condition: 可舀粉判断为 true，且 Source Barcode 非空
+  - Stash: 已领取·不可自动称量的化合物池
+    condition: 可舀粉判断为 false，且 Source Barcode 非空
+  - Stash: 缺料化合物池
+    condition: 是否缺料 = 缺料
+```
+
+**化合物数据查询方式**
+
+查询化合物库的可用量：使用输入池 Compound ID 作为索引，查询 compound 表的 CAS 字段，查找 status = 可用的记录，返回 latest amount 字段的值并汇总加和。
+
+查询化合物知识库属性：使用输入池 Compound ID 查询 chemical_record 表，返回舀粉相关属性。
+
+**字段映射表**
+
+| 门控加工数据 | chemical_record 表字段 |
+| --------- | -------------------- |
+| 性状 (Chemist) | chemistProperty |
+| 可舀粉判断 (Feasibility of Dispensing) | feasibilityOfDipensing |
+| 固体颗粒过大 (Large Particle) | largeParticle |
+| 流动性差 (Poor Flowability) | poorFlowability |
+
+**数据处理规则**
+
+| 序号 | 规则摘要 | 条件要点 | 业务动作或结果 |
+| --- | ------- | ------- | ----------- |
+| 1.1 | 汇总需求量 | 始终 | Requested Amount = Target Amount 1 + 2 + 3 |
+| 1.2 | 是否缺料判定 | Requested Amount > Available Amount | 是否缺料 = 缺料 |
+| 1.3 | 容差默认 | Target Amount N > 0 且 Tolerance N 为空 | Tolerance 默认 0.5 mg |
+| 1.4 | 缺料标记 | Source Barcode 为空 | 是否缺料 = 缺料 |
+
+***
+
+### 5.2 查看结果与复核更新
+
+```yaml
+valve_id: valve_3
+name: 查看结果与复核更新
+order: 3
+input:
+  primary: 上机实验池
+output:
+  - Stash: 完成实验池
+    condition: 对每个 Target Amount > 0 的档位，均有 Actual，且 |Actual - Target| ≤ 对应 Tolerance
+  - Stash: 失败实验池
+    condition: 任一档位偏差超出容差或其它执行失败情形
+```
+
+**数据处理规则**
+
+| 序号 | 规则摘要 | 条件要点 | 业务动作或结果 |
+| --- | ------- | ------- | ----------- |
+| 3.1 | 执行方式 | 本门控处理自动化回传 | 执行方式 = Automated |
+| 3.2 | 实际量 | Target Amount N > 0 | 写入 Actual Amount N（来自设备或复核） |
+| 3.3 | 偏差 | 某档实际量与目标量之差大于该档 Tolerance | 计入失败分支 |
+| 3.4 | 执行状态 | 全部档位满足容差 | 执行状态 = 执行完成 |
+| 3.5 | 执行失败 | 存在超差或设备失败 | 执行状态 = 执行失败，填写执行失败原因 |
+
+***
+
+## 6. 知识库 / 外部主数据
+
+| 逻辑键 | 字段含义 | 类型/取值说明 |
+| ----- | ------- | ----------- |
+| Compound ID | 与记录中化合物编号对应 | text |
+| latest_amount_mg | 最新可用库存 (mg) | number |
+| 性状 | 物理性状 | 粉末 / 液体 / 固体 等 |
+| 可分装判断 | 是否可分装 | bool |
+| Source Barcode | 推荐源瓶条码；空表示无可分装源瓶 | text |