@xtalpi/agentic-lab-skills 0.0.5 → 0.0.7

package/package.json

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

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

@@ -114,7 +114,7 @@ metadata:
     - 配置项表（如 `bookid`），用于拼装 `orbit_link`
     - 规则摘要表（条件要点 + 业务动作），落入 `start` 函数体
     - 数据处理规则（序号表），按序号写入脚本注释与实现
-  - **人工处理** → 描述 Orbit 页面的界面形态与数据绑定（由 `studio-orbit-vue-component` 等技能负责生成 UI，门控脚本中不实现）。须提取：
+  - **人工处理** → 描述 Orbit 页面的界面形态与数据绑定（由 `lab-orbit-component-builder` 等技能负责生成 UI，门控脚本中不实现）。须提取：
     - 界面类型（超级表格、表单等）
     - 数据来源与操作按钮描述
   - **后置处理** → 生成 `Processer.complete` 函数逻辑。须提取：
@@ -401,6 +401,7 @@ console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__}
 - 按需生成，禁止冗余：代码和 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`（见「脚本自测」）
 
 ## 扩展
 
@@ -420,3 +421,139 @@ console.info(`[Processer] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__}
 **对照物**：[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,7 +1,7 @@
 ---
 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"
@@ -27,7 +27,7 @@ Pool 存多条记录，每池有独立 Schema，字段随阶段可不同。
 
 ## 流程图
 
-（与 flow-package-from-design 约定一致：**池 = 矩形 `[…]`，门控 = 六边形 `{{…}}`**。）
+（与 lab-flow-designer 约定一致：**池 = 矩形 `[…]`，门控 = 六边形 `{{…}}`**。）
 
 ```mermaid
 flowchart LR

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-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//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 记录中保留**修订日期与变更摘要**。