@xtalpi/agentic-lab-skills 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xtalpi/agentic-lab-skills",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"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. 提示用户：完善文档内容后，可直接用本技能的「初次生成」模式生成流程注册包
+
+**注意**：生成流程文档模式下**不执行**流程文档合规预检，也**不生成**流程注册包。
+
 ## 流程文档合规预检（阻断；仅「初次生成」）
 
 **适用**：仅当上文 **「会话模式判定」** 为 **初次生成** 时执行本节。**迭代修改** 模式下一整节跳过（不得要求用户提供流程说明以通过预检）。
@@ -97,7 +114,7 @@ metadata:
     - 配置项表（如 `bookid`），用于拼装 `orbit_link`
     - 规则摘要表（条件要点 + 业务动作），落入 `start` 函数体
     - 数据处理规则（序号表），按序号写入脚本注释与实现
-  - **人工处理** → 描述 Orbit 页面的界面形态与数据绑定（由 `studio-orbit-vue-component` 等技能负责生成 UI，门控脚本中不实现）。须提取：
+  - **人工处理** → 描述 Orbit 页面的界面形态与数据绑定（由 `lab-orbit-component-builder` 等技能负责生成 UI，门控脚本中不实现）。须提取：
     - 界面类型（超级表格、表单等）
     - 数据来源与操作按钮描述
   - **后置处理** → 生成 `Processer.complete` 函数逻辑。须提取：
@@ -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,8 @@ 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」）
+- **脚本自测**：凡写入或修改 `scripts/*.js`，必须用 `testing/test-processer.mjs` 执行自测并自动修复，直到正常轮全 `pass`（见「脚本自测」）
 
 ## 扩展
 
@@ -348,13 +409,151 @@ 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` **故意不一致**（仅示意）。
+
+## 脚本自测（生成后必须执行）
+
+**适用**：**初次生成** 与 **迭代修改** 两种模式下，凡写入或修改了 `scripts/*.js`，都**必须**对涉及的脚本执行自测。全部正常轮 `pass` 后方可交付用户。
+
+### 自测工具
+
+本 skill 内置测试工具 [`testing/test-processer.mjs`](testing/test-processer.mjs)，零外部依赖，直接通过 `node` 执行。
+
+### 执行命令
+
+对每个生成或修改的 `scripts/<基名>.js` 执行：
+
+```bash
+node <本skill目录>/testing/test-processer.mjs \
+  --script <输出目录>/scripts/<基名>.js \
+  --pools-dir <输出目录>/pools \
+  --valves-dir <输出目录>/valves \
+  --valve-name <基名>
+```
+
+### 验证范围
+
+工具分两轮 mock 执行，分开报告：
+
+| 轮次 | 检查内容 | 失败级别 |
+|------|---------|---------|
+| **语法检查** | JavaScript 语法正确性 | 阻断 |
+| **结构检查** | `Processer` 类存在，含 `constructor`、`start`、`complete` | 阻断 |
+| **正常轮 `start`** | 正常类型 mock 数据运行，检查返回 `{ orbit_link: string, ticket_ids: number[] }` | 阻断 |
+| **正常轮 `complete`** | 正常类型 mock 数据运行，检查返回 `{ new_tickets: [...] }` 结构正确 | 阻断 |
+| **对抗轮 `start` + `complete`** | 第 3 条 ticket 的 text 字段填为 number/null，验证类型安全编码 | 警告（不阻断） |
+| **合规审计** | SDK 方法白名单、列表查询 `limit`/`offset`、返回值 snake_case | 未知 SDK 方法→阻断；其余→警告 |
+
+### 结果判定与自动修复
+
+工具输出 JSON，`status` 为 `pass` 或 `fail`。
+
+**自动修复循环（最多 3 轮）：**
+
+1. 运行测试，读取输出 JSON
+2. 若**正常轮有 `fail`**：
+   a. 读取 `errors` 数组中的错误描述
+   b. 对照下方「修复指引表」，在脚本中定位并修复问题
+   c. 修复后**立即重新运行测试**
+   d. 重复直到正常轮全部 `pass`（最多 3 轮）
+3. 若**对抗轮有 `fail`**：
+   a. 读取 `warnings`，检查是否为真实的类型安全隐患
+   b. 若是：按「编写指引 §5」添加 `String()` / `Number()` 防御
+   c. 若为误报（该字段在真实数据中不可能为 null/number）：忽略
+4. **3 轮后仍有正常轮 `fail`**：停止修复，向用户报告剩余问题及已尝试的修复
+5. 所有正常轮 `pass` 后：向用户报告测试结果摘要（含对抗轮警告，如有）
+
+### 修复指引表
+
+| 错误类型 | 错误示例 | 自动修复策略 |
+|---------|---------|------------|
+| `SyntaxError` | `Unexpected token` | 检查脚本语法，修正括号/引号/关键字错误 |
+| `TypeError: x.trim is not a function` | detail 值非字符串直接调 `.trim()` | 替换为 `String(x ?? '').trim()` 或用 `str()` 辅助函数 |
+| `TypeError: Cannot read properties of null` | 未做 null 检查 | 添加可选链 `?.` 或空值合并 `??` |
+| `start() 返回值缺 orbit_link` | `orbit_link must be string, got undefined` | 检查 `start` 返回语句，补全 `orbit_link` 字段 |
+| `start() 返回值缺 ticket_ids` | `ticket_ids must be array, got undefined` | 确保返回 `ticket_ids: tickets.map(t => t.id)` |
+| `complete() new_tickets 缺必填字段` | `new_tickets[0].pool_id must be number` | 检查 new_tickets 映射逻辑，补全 `flow_id`/`pool_id`/`order_id`/`detail`/`status` |
+| `Unknown SDK namespace/method` | `Unknown SDK method called: context.xxx.yyy` | 替换为 [agentic-lab-sdk.md](references/agentic-lab-sdk.md) 中已有的方法 |
+| `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)` 方法 |
+
+## 脚本预览（试运行）
+
+**定位**：自测验证脚本"对不对"（语法、结构、契约），预览验证脚本"做了什么"（SDK 调用链、数据变换、路由逻辑）——两者互补。自测必须先 `pass`，预览才有意义。预览结果不影响 `pass/fail` 判定。
+
+### 何时使用
+
+- **初次生成后**：自测全部通过后，自动执行一次预览，将报告展示给用户确认
+- **用户提供样本数据时**：使用 `--data` 模式，用真实或半真实数据验证具体业务场景
+- **迭代修改脚本逻辑后**：重新预览确认变更效果
+
+### 执行命令
+
+**自动生成数据**（从 pool schema 生成 5 条场景 tickets）：
+
+```bash
+node <本skill目录>/testing/test-processer.mjs \
+  --preview \
+  --script <输出目录>/scripts/<基名>.js \
+  --pools-dir <输出目录>/pools \
+  --valves-dir <输出目录>/valves \
+  --valve-name <基名>
+```
+
+**用户提供样本数据**：
+
+```bash
+node <本skill目录>/testing/test-processer.mjs \
+  --preview \
+  --data <样本数据.json> \
+  --script <输出目录>/scripts/<基名>.js \
+  --pools-dir <输出目录>/pools \
+  --valves-dir <输出目录>/valves \
+  --valve-name <基名>
+```
+
+### 样本数据格式
+
+用户只需提供 `detail` 对象，工具自动补全 `id`/`flow_id`/`pool_id`/`order_id`/`status`/`uuid`：
+
+```json
+{
+  "tickets": [
+    { "detail": { "cmpd_id": "CA1078", "cas": "28022-43-7", "amount": 50 } },
+    { "detail": { "cmpd_id": "CA1079", "cas": "12345-67-8", "amount": 120 } }
+  ]
+}
+```
+
+### 场景数据生成指引
+
+当用户未提供 `--data` 时，工具从 pool schema 自动生成场景 tickets。若 pool schema 字段较少（如仅 `id` + `detail`），自动生成的 tickets 可能无业务字段，导致脚本中依赖特定字段的分支不被触发。此时 agent 应：
+
+1. 阅读门控的 `valves/<基名>.md` 中的「数据处理规则」
+2. 提取脚本依赖的关键字段（如 `cmpd_id`、`process_ids`、`amount` 等）
+3. 生成一份 `--data` JSON，字段值覆盖主要业务路径
+4. 用 `--data` 模式重新预览，确认完整数据流
+
+### 报告解读
+
+预览报告包含以下关键信息，agent 应逐项核对：
+
+| 报告区域 | 关注点 |
+|----------|--------|
+| **SDK 调用链** | 调用顺序是否与流程文档描述一致；参数是否正确（如 `filter` 中的字段名、`limit` 值） |
+| **ticket.detail 变更** | 变更的字段是否与流程文档「数据处理规则」吻合；是否有意外的字段被覆盖 |
+| **start() 返回值** | `orbit_link` 格式正确；`ticket_ids` 包含所有处理的 tickets |
+| **数据路由** | tickets 是否按预期分流到对应出口池；池名、数量、status 是否正确 |
+| **执行摘要** | 确认 start/complete 均成功；检查「未调用的 SDK 方法」是否符合预期 |

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

@@ -1,8 +1,12 @@
 ---
 name: embedded-flow-example
 description: >-
-  示意流程注册包。仅作 flow-package-from-design 内置版式样例，演示 SKILL/pools/valves/scripts 目录与章节结构。
+  示意流程注册包。仅作 lab-flow-designer 内置版式样例，演示 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"
 ---
 
 # 示意流程
@@ -23,7 +27,7 @@ Pool 存多条记录，每池有独立 Schema，字段随阶段可不同。
 
 ## 流程图
 
-（与 flow-package-from-design 约定一致：**池 = 矩形 `[…]`，门控 = 六边形 `{{…}}`**。）
+（与 lab-flow-designer 约定一致：**池 = 矩形 `[…]`，门控 = 六边形 `{{…}}`**。）
 
 ```mermaid
 flowchart LR

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/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

@@ -82,7 +82,7 @@ output:
 
 1. **界面类型**：超级表格
 2. **数据来源**：前置处理写入 `ticket.detail` 的字段
-3. **操作按钮**：刷新 / 检查 / 提交（由 `studio-orbit-vue-component` 技能生成 UI）
+3. **操作按钮**：刷新 / 检查 / 提交（由 `lab-orbit-component-builder` 技能生成 UI）
 
 ### 后置处理
 

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/agentic-lab-sdk.md

@@ -4,7 +4,7 @@
 
 本节为 **`this.context` 门控/SDK 能力**约定。**`process.execute`** 须传入任务数组 **`items`** 与服务根 **`baseURL`**（Rhea 或等价 Process 服务地址）；单次请求的 **path、HTTP 方法** 仍与 Wire 文档一致并由 **SDK 封装**，门控不拼完整 URL。其余常见查询类能力仍以 SDK 封装为主。`items` 单项形状与 **[`rhea-api/execute_process_batch.md`](rhea-api/execute_process_batch.md)** 中请求体 `items[]` 一项对齐。
 
-## 门控脚本生成约定（flow-package-from-design）
+## 门控脚本生成约定（lab-flow-designer）
 
 对 **`ticket.list`**、**`process.list`**、**`compound.getStock`**、**`compound.getChemicalRecord`** 等支持 **`limit` / `offset`** 的查询：若流程说明**未**明确要求分页或条数，生成门控脚本时应显式传入 **`limit: 999999`**、**`offset: 0`**，避免引擎默认小页长截断。若流程说明写了分页或「查全部」的**具体数值**，以流程说明为准。
 

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/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

@@ -187,7 +187,7 @@
 
 ## 5. 与流程注册包生成的关系
 
-使用 skill **`flow-package-from-design`** 时：**仅「初次从流程说明生成整包」**须先按主 `SKILL.md` 中 **「流程文档合规预检」** 对照本标准执行；不通过则不得写入产出目录，并须给出《流程文档合规问题与优化建议》（结构见该节）。**对已有流程注册包做增量修改**的会话不要求流程文档预检（可选自行对照本标准做人工评审）。
+使用 skill **`lab-flow-designer`** 时：**仅「初次从流程说明生成整包」**须先按主 `SKILL.md` 中 **「流程文档合规预检」** 对照本标准执行；不通过则不得写入产出目录，并须给出《流程文档合规问题与优化建议》（结构见该节）。**对已有流程注册包做增量修改**的会话不要求流程文档预检（可选自行对照本标准做人工评审）。
 
 生成器依赖（初次生成路径）：
 
@@ -205,4 +205,4 @@
 
 ## 6. 修订与版本
 
-本标准随 `flow-package-from-design` skill 与常见流程说明实践演进可修订；建议在文末或 Git 记录中保留**修订日期与变更摘要**。
+本标准随 `lab-flow-designer` skill 与常见流程说明实践演进可修订；建议在文末或 Git 记录中保留**修订日期与变更摘要**。

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 |