@xtalpi/agentic-lab-skills 0.0.4 → 0.0.5

package/skills/lab-nocobase-flow-generator/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: lab-nocobase-flow-generator
+description: >-
+  根据脚本逻辑文档（或用户对话描述）生成可在 NocoBase 工作流「脚本节点」中运行的 JavaScript 脚本。
+  也可根据用户描述生成符合规范的脚本逻辑文档模板，供用户完善后用于脚本生成。
+  Use when user wants to generate a NocoBase workflow script, script logic document template, or provides a script logic document.
+---
+
+# NocoBase 工作流脚本生成器
+
+## 适用场景
+
+- 用户提供**脚本逻辑文档**（Markdown，格式见 [references/doc-standard.md](references/doc-standard.md)）或在对话中描述需求，需要生成可在 NocoBase 工作流「脚本节点」中直接运行的 JavaScript 脚本。
+- 用户希望生成一份**脚本逻辑文档模板**，用于梳理和描述业务需求，完善后再用本技能生成脚本。
+
+## 分层加载
+
+| 需求 | 打开 |
+|------|------|
+| **运行时 API、Repository 操作、过滤操作符、脚本结构** | [references/runtime-api.md](references/runtime-api.md) |
+| **逻辑文档格式要求与合规检查** | [references/doc-standard.md](references/doc-standard.md) |
+| **数据库查询示例** | [examples/查询化学品信息.js](examples/查询化学品信息.js) |
+| **外部服务调用 + setting 表示例** | [examples/setting表获取外部服务.js](examples/setting表获取外部服务.js) |
+| **脚本逻辑文档模板** | [templates/脚本逻辑文档模板.md](templates/脚本逻辑文档模板.md) |
+| **逻辑文档填写示例** | [templates/脚本逻辑文档示例.md](templates/脚本逻辑文档示例.md) |
+
+## 会话模式判定
+
+| 模式 | 判定条件 | 行为 |
+|------|----------|------|
+| **从文档生成** | 用户提供了脚本逻辑文档路径，或贴入文档内容 | 先执行「文档合规预检」，通过后生成脚本 |
+| **对话式生成** | 用户在对话中描述需求，未提供文档 | 通过提问补全关键信息（见§3），然后生成脚本 |
+| **修改已有脚本** | 用户提供已有脚本路径，要求修改功能 | 跳过预检，按用户要求修改 |
+| **生成逻辑文档** | 用户要求生成文档、模板、操作模板 | 基于模板和用户描述，生成预填充的逻辑文档并写入本地文件 |
+
+## 工作流
+
+### 第 1 步：需求收集与确认
+
+#### A. 从文档生成
+
+1. 读取用户指定的逻辑文档
+2. 按 [references/doc-standard.md](references/doc-standard.md) 的合规检查清单逐项核对
+3. **若不通过**：列出缺失项和补充建议，等待用户修改后重新提交
+4. **若通过**：进入第 2 步
+
+#### B. 对话式生成
+
+向用户确认以下关键信息（已明确的跳过）：
+
+| 主题 | 需要确认的内容 |
+|------|----------------|
+| 输入参数 | 有哪些参数？类型？哪些必填？校验规则？ |
+| 数据库操作 | 操作哪些表？查询/创建/更新/删除？过滤条件？ |
+| 外部接口 | 是否需要调用外部服务？地址从 setting 表读取还是固定？请求方法和参数？ |
+| 核心逻辑 | 数据处理的步骤？条件分支？循环？ |
+| 输出结果 | 成功/失败分别返回什么？ |
+
+#### C. 生成逻辑文档
+
+1. 读取 [templates/脚本逻辑文档模板.md](templates/脚本逻辑文档模板.md) 获取文档结构
+2. 参考 [templates/脚本逻辑文档示例.md](templates/脚本逻辑文档示例.md) 了解填写规范
+3. 根据用户描述的业务场景，预填充模板中的各章节（能确定的内容填入，不确定的保留占位提示）
+4. 将文档写入用户指定路径（按优先级：① 用户指定了具体路径 → 使用该路径；② 用户指定了参考文档路径 → 在该文档所在目录下生成 `【逻辑文档】{脚本名称}.md`；③ 均未指定 → 在当前工作目录下生成 `【逻辑文档】{脚本名称}.md`。**禁止**私自创建子目录）
+5. 提示用户：完善文档内容后，可直接用本技能的「从文档生成」模式生成脚本
+
+### 第 2 步：生成脚本
+
+打开 [references/runtime-api.md](references/runtime-api.md)，按以下结构生成脚本：
+
+```
+1. 引入外部依赖（按需，无外部调用则省略）
+2. 定义辅助函数 ok() / fail()
+2b. 产物版本常量（__ARTIFACT_VERSION__ / __ARTIFACT_SKILL__）+ console.info 版本打印
+3. 解构输入参数（从 input_data）
+4. 获取 Repository
+5. 定义业务辅助函数（如 get_settings，仅需要时添加）
+6. try-catch 包裹以下所有步骤：
+   a. 参数校验（return fail('VALIDATION_ERROR', ...) ）
+   b. 业务逻辑
+   c. return ok(data)
+7. catch 块：return fail(错误码, err_info)
+```
+
+### 第 3 步：输出与说明
+
+向用户输出：
+1. 完整的脚本代码
+2. 简要说明脚本逻辑
+3. 需要在工作流中配置的输入参数列表
+
+## 脚本生成规则
+
+### 运行时环境
+
+- 脚本运行在 NocoBase 工作流的脚本节点中，**非 Node.js 模块**
+- 顶层支持 `await`，无需包裹 async 函数
+- 全局可用：`appContext`、`dayjs`、`getMessageFromError`、`input_data`
+- `return` 的值作为节点输出传递给下游
+- 可使用 `require('axios')`、`require('node:crypto')` 等
+
+### 数据库操作
+
+- Repository 获取：`appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('表名')`
+- 查询大量数据时 `pageSize` 设为 `9999` 或 `99999`
+- 过滤操作符详见 [references/runtime-api.md](references/runtime-api.md) §4
+
+### 外部服务调用（按需）
+
+- 仅当逻辑文档 §3.2 声明了外部服务操作时才引入 `axios`
+- 使用 `const axios = require('axios')`
+- 接口地址来源有两种模式：
+  - **固定地址**：直接写入 URL
+  - **setting 表配置**：通过 `getSettings()` 获取，拼接 URL（参见 [examples/setting表获取外部服务.js](examples/setting表获取外部服务.js)）
+
+### 错误处理与返回格式
+
+- 每个脚本顶部必须定义 `ok()` / `fail()` 辅助函数：
+  ```javascript
+  const ok = (data) => ({ success: true, error_code: null, error_message: null, http_status: null, data })
+  const fail = (error_code, error_message, http_status = null) => ({ success: false, error_code, error_message, http_status, data: null })
+  ```
+- 所有业务逻辑（含参数校验）必须在 `try-catch` 内部
+- 参数校验失败使用 `return fail('VALIDATION_ERROR', '...')`，**不使用 `throw`**
+- 成功返回使用 `return ok(data)`
+- 查询无结果不是错误，返回 `ok([])`
+- 异常捕获使用 `getMessageFromError(err)` 提取信息，通过 `fail()` 返回
+- 错误码枚举：`VALIDATION_ERROR` / `DB_ERROR` / `HTTP_ERROR` / `CONFIG_ERROR` / `UNKNOWN_ERROR`
+- 涉及 axios 调用的脚本，catch 块中需检查 `err.response`（HTTP 错误带状态码）和 `err.request`（无响应）
+- 详见 [references/runtime-api.md](references/runtime-api.md) §8、§9
+
+### 代码风格
+
+- 不写多余注释，代码自解释
+- 变量命名使用 snake_case（与 NocoBase 字段风格一致）
+- 优先使用 `const`，仅在需要重新赋值时使用 `let`
+- 不添加未使用的依赖和变量
+
+### 产物版本追踪
+
+每个生成的脚本**必须**包含版本信息，帮助用户识别产物来源和版本。
+
+版本块放在 `ok()`/`fail()` 定义之后、参数解构之前：
+
+```javascript
+// --- Artifact Version ---
+const __ARTIFACT_VERSION__ = '<semver>'
+const __ARTIFACT_SKILL__ = 'lab-nocobase-flow-generator'
+console.info(`[WorkflowScript] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`)
+```
+
+- **初次生成 / 从文档生成 / 对话式生成**：`__ARTIFACT_VERSION__` = `'1.0.0'`。
+- **修改已有脚本**：读取现有 `__ARTIFACT_VERSION__`，按变更范围递增（patch：修复；minor：新增逻辑；major：输入输出结构变更），**不得**重置为 `1.0.0`。
+
+## 硬性约束
+
+- **必须**通过 `appContext.dataSourceManager` 获取 Repository，不可直接操作数据库
+- **必须**对所有异步操作做错误处理
+- **禁止**硬编码敏感信息（Token、密码等）到脚本中；应从 `input_data` 或 `setting` 表获取
+- **禁止**使用 `module.exports` / `export`，脚本不是模块
+- **禁止**使用 `process.exit()` 或其他退出进程的操作
+- `return` 的值必须是可序列化的（对象、数组、字符串、数字）
+- `return` 必须使用 `ok()` / `fail()` 辅助函数，确保统一信封格式
+- **必须**在 `ok()`/`fail()` 定义之后、参数解构之前包含 `__ARTIFACT_VERSION__` 和 `__ARTIFACT_SKILL__` 常量及 `console.info` 版本打印

package/skills/lab-nocobase-flow-generator/examples/setting/350/241/250/350/216/267/345/217/226/345/244/226/351/203/250/346/234/215/345/212/241.js

@@ -0,0 +1,70 @@
+const axios = require('axios')
+
+const ok = (data) => ({ success: true, error_code: null, error_message: null, http_status: null, data })
+const fail = (error_code, error_message, http_status = null) => ({ success: false, error_code, error_message, http_status, data: null })
+
+// --- Artifact Version ---
+const __ARTIFACT_VERSION__ = '1.0.0'
+const __ARTIFACT_SKILL__ = 'lab-nocobase-flow-generator'
+console.info(`[WorkflowScript] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`)
+
+const setting_repo = appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('setting')
+
+const get_settings = async () => {
+  const res = await setting_repo.find({ pageSize: 9999 })
+  const settings = {}
+  res.forEach(s => {
+    settings[s.setting_name] = s.setting_value
+  })
+  return settings
+}
+
+const { task_id } = input_data
+
+const task_repo = appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('task')
+
+try {
+  if (!task_id) return fail('VALIDATION_ERROR', 'task_id is required')
+
+  const task = await task_repo.find({
+    pageSize: 1,
+    filter: { id: task_id }
+  })
+
+  if (task.length === 0) {
+    return ok({ task: null, processes: [] })
+  }
+
+  const settings = await get_settings()
+  if (!settings.rhea_host) return fail('CONFIG_ERROR', 'rhea_host 未在 setting 表中配置')
+
+  const res = await axios({
+    method: 'post',
+    url: `${settings.rhea_host}/api/process/list_process`,
+    data: {
+      filter: {
+        filter: {
+          operator: 'and',
+          conditions: [
+            { field: 'status', operator: 'not_in', value: ['Failed', 'Completed'] }
+          ]
+        }
+      },
+      per_page: 99999,
+      page: 1
+    }
+  })
+
+  return ok({
+    task: task[0],
+    processes: res.data.results.records
+  })
+} catch (err) {
+  const err_info = getMessageFromError(err)
+  console.error('操作失败:', err)
+
+  if (err.response) return fail('HTTP_ERROR', err_info, err.response.status)
+  if (err.request) return fail('HTTP_ERROR', '外部服务无响应: ' + err_info)
+
+  return fail('DB_ERROR', err_info)
+}

package/skills/lab-nocobase-flow-generator/examples//346/237/245/350/257/242/345/214/226/345/255/246/345/223/201/344/277/241/346/201/257.js

@@ -0,0 +1,30 @@
+const ok = (data) => ({ success: true, error_code: null, error_message: null, http_status: null, data })
+const fail = (error_code, error_message, http_status = null) => ({ success: false, error_code, error_message, http_status, data: null })
+
+// --- Artifact Version ---
+const __ARTIFACT_VERSION__ = '1.0.0'
+const __ARTIFACT_SKILL__ = 'lab-nocobase-flow-generator'
+console.info(`[WorkflowScript] v${__ARTIFACT_VERSION__} (skill: ${__ARTIFACT_SKILL__})`)
+
+const { chemical_name, cas } = input_data
+
+const chemical_repo = appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('chemical')
+
+try {
+  if (!chemical_name && !cas) return fail('VALIDATION_ERROR', 'chemical_name 或 cas 至少提供一个')
+
+  const filter = {}
+  if (chemical_name) filter.chemical_name = chemical_name
+  if (cas) filter.cas = cas
+
+  const data = await chemical_repo.find({
+    pageSize: 999,
+    filter
+  })
+
+  return ok(data)
+} catch (err) {
+  const err_info = getMessageFromError(err)
+  console.error('查询chemical失败:', err)
+  return fail('DB_ERROR', err_info)
+}

package/skills/lab-nocobase-flow-generator/references/doc-standard.md

@@ -0,0 +1,84 @@
+# 脚本逻辑文档规范
+
+本文档定义了产品人员编写「脚本逻辑文档」时须遵循的格式，Skill 依据此规范解析文档并生成脚本。
+
+---
+
+## 必备章节与检查项
+
+### §1 基本信息（必填）
+
+表格形式，包含：
+
+| 字段 | 要求 |
+|------|------|
+| 脚本名称 | 必填，简洁描述功能 |
+| 业务场景 | 必填，说明触发场景和业务目的 |
+| 输入参数来源 | 必填，`input_data` / `workflow_context` / 无 |
+
+### §2 输入参数（必填）
+
+表格列出所有参数：`参数名`、`类型`、`必填`、`说明`。
+
+必须描述**参数校验规则**（如互斥、至少一个必填等）。
+
+### §3 数据操作（必填）
+
+分为两个子节：
+
+#### §3.1 NocoBase 数据库操作
+
+每个操作一个子标题，包含：
+- **数据表**：表名（必填）
+- **操作类型**：`find` / `create` / `update` / `destroy`（必填）
+- **关联加载**：appends 字段名列表或 `无`
+- **过滤条件**：列出所有条件
+- **更新/写入字段**（仅 create/update）：`字段名`、`值来源`、`说明`
+
+#### §3.2 外部服务操作（可选）
+
+每个接口一个子标题，包含：
+- **接口地址来源**：`setting` 表配置项名称 或 固定地址（必填）
+- **请求路径**：接口路径（必填）
+- **请求方法**：`GET` / `POST` / `PUT` / `DELETE`（必填）
+- **认证方式**：`Bearer Token` / 无 / `setting` 表配置项
+- **请求参数/请求体**：JSON 示例
+- **响应取值路径**：如 `res.data.results.records`
+
+### §4 核心逻辑（必填）
+
+编号步骤描述处理流程，可包含：
+- **条件分支**：当 XXX 时 → 执行 A
+- **循环处理**：遍历 XXX，对每条执行 ...
+- **数据转换**：字段映射、计算等
+
+### §5 输出结果（必填）
+
+表格列出各场景的返回值：`场景`、`返回值`、`类型`。
+
+至少覆盖：成功（含空数据）、校验失败、异常。返回格式须符合标准信封格式（`ok()` / `fail()`）。
+
+### §6 备注（可选）
+
+补充说明、注意事项。
+
+---
+
+## 合规检查清单
+
+Skill 在生成脚本前会检查以下项目：
+
+| # | 检查项 | 阻断级别 |
+|---|--------|----------|
+| 1 | §1 基本信息完整 | 阻断 |
+| 2 | §2 输入参数至少列出一项，或明确标注「无输入参数」 | 阻断 |
+| 3 | §3 至少有一个数据操作（数据库或外部服务） | 阻断 |
+| 4 | §3.1 每个数据库操作的表名和操作类型已指定 | 阻断 |
+| 5 | §3.2 外部接口的地址来源、路径、方法已指定 | 阻断 |
+| 6 | §4 核心逻辑步骤清晰，无歧义条件 | 阻断 |
+| 7 | §5 输出结果覆盖成功/异常场景 | 建议 |
+| 8 | §3.1 过滤条件使用支持的操作符 | 建议 |
+| 9 | §3.2 接口认证方式已说明 | 建议 |
+
+- **阻断**：未满足则不生成脚本，输出补充建议
+- **建议**：未满足仍可生成，但提示优化

package/skills/lab-nocobase-flow-generator/references/runtime-api.md

@@ -0,0 +1,224 @@
+# NocoBase 工作流脚本运行时 API
+
+## 1. 全局对象
+
+脚本在 NocoBase 工作流的「脚本节点」中执行，运行时注入以下全局对象：
+
+| 对象 | 说明 |
+|------|------|
+| `appContext` | NocoBase 应用上下文，用于获取数据表 Repository |
+| `dayjs` | 日期处理库（已全局注入，无需 require） |
+| `getMessageFromError(err)` | 从错误对象提取可读信息的工具函数 |
+| `input_data` | 工作流传入的参数对象（由前一个节点或触发器提供） |
+
+## 2. 获取 Repository
+
+```javascript
+const repo = appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('表名')
+```
+
+## 3. Repository 操作
+
+### 3.1 find — 查询
+
+```javascript
+const data = await repo.find({
+  pageSize: 9999,        // 分页大小
+  filter: {              // 过滤条件
+    field_name: 'value',
+    status: { $in: ['A', 'B'] },
+    date_field: {
+      $dateBefore: '2025-01-01 00:00:00',
+      $dateAfter: '2024-01-01 00:00:00'
+    },
+    name: { $notEmpty: true }
+  },
+  appends: ['relation_field']  // 加载关联字段（可选）
+})
+// 返回值: Array
+```
+
+### 3.2 create — 创建
+
+```javascript
+const res = await repo.create({
+  values: {
+    field1: 'value1',
+    field2: 123
+  }
+})
+// 返回值: Object (创建的记录)
+```
+
+### 3.3 update — 更新
+
+```javascript
+const res = await repo.update({
+  filter: { id: 1 },     // 或 { id: { $in: [1, 2, 3] } }
+  values: {
+    status: 'new_status'
+  }
+})
+// 返回值: Array (更新的记录)
+```
+
+### 3.4 destroy — 删除
+
+```javascript
+await repo.destroy({
+  filter: { id: 1 }
+})
+```
+
+## 4. 常用过滤操作符
+
+| 操作符 | 说明 | 示例 |
+|--------|------|------|
+| `$eq` | 等于（默认） | `{ name: 'test' }` |
+| `$ne` | 不等于 | `{ status: { $ne: 'deleted' } }` |
+| `$in` | 在列表中 | `{ status: { $in: ['A', 'B'] } }` |
+| `$notIn` | 不在列表中 | `{ status: { $notIn: ['X'] } }` |
+| `$empty` | 为空 | `{ name: { $empty: true } }` |
+| `$notEmpty` | 不为空 | `{ name: { $notEmpty: true } }` |
+| `$dateBefore` | 日期早于 | `{ date: { $dateBefore: '...' } }` |
+| `$dateAfter` | 日期晚于 | `{ date: { $dateAfter: '...' } }` |
+| `$or` | 或条件 | `{ $or: [{ a: 1 }, { b: 2 }] }` |
+
+## 5. 外部 HTTP 调用（axios）
+
+```javascript
+const axios = require('axios')
+
+const res = await axios({
+  method: 'get',        // 或 'post', 'put', 'delete'
+  url: 'http://example.com/api/xxx',
+  params: { key: 'val' },          // GET 参数
+  data: { key: 'val' },            // POST 请求体
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': 'Bearer xxx'
+  }
+})
+// 响应: res.data
+```
+
+## 6. 从 setting 表读取配置（用于动态获取外部服务地址）
+
+当外部接口地址需要从系统配置中读取时：
+
+```javascript
+const setting_repo = appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('setting')
+
+const get_settings = async () => {
+  const res = await setting_repo.find({ pageSize: 9999 })
+  const settings = {}
+  res.forEach(s => {
+    settings[s.setting_name] = s.setting_value
+  })
+  return settings
+}
+
+// 使用示例
+const settings = await get_settings()
+if (!settings.rhea_host) return fail('CONFIG_ERROR', 'rhea_host 未在 setting 表中配置')
+const url = `${settings.rhea_host}/api/process/list_process`
+```
+
+> **注意：** 不同项目的 setting 表字段名可能不同（`setting_name`/`name`、`setting_value`/`value`），以实际表结构为准。
+> 必要配置缺失时使用 `fail('CONFIG_ERROR', ...)` 返回结构化错误，不要使用 `throw`。
+
+## 7. 脚本结构规范
+
+```javascript
+// 1. 引入外部依赖（按需）
+const axios = require('axios')
+
+// 2. 辅助函数
+const ok = (data) => ({ success: true, error_code: null, error_message: null, http_status: null, data })
+const fail = (error_code, error_message, http_status = null) => ({ success: false, error_code, error_message, http_status, data: null })
+
+// 3. 解构输入参数
+const { param1, param2 } = input_data
+
+// 4. 获取 Repository
+const xxx_repo = appContext.dataSourceManager.dataSources.get('main').collectionManager.getRepository('xxx')
+
+// 5. try-catch 包裹所有业务逻辑（含参数校验）
+try {
+  if (!param1) return fail('VALIDATION_ERROR', 'param1 is required')
+
+  const data = await xxx_repo.find({ ... })
+
+  return ok(data)
+} catch (err) {
+  const err_info = getMessageFromError(err)
+  console.error('操作失败:', err)
+  return fail('DB_ERROR', err_info)
+}
+```
+
+## 8. 标准返回格式
+
+所有脚本必须通过 `ok()` / `fail()` 辅助函数返回统一的信封对象：
+
+```javascript
+const ok = (data) => ({ success: true, error_code: null, error_message: null, http_status: null, data })
+const fail = (error_code, error_message, http_status = null) => ({ success: false, error_code, error_message, http_status, data: null })
+```
+
+**信封字段：**
+
+| 字段 | 类型 | 成功时 | 失败时 |
+|------|------|--------|--------|
+| `success` | `boolean` | `true` | `false` |
+| `error_code` | `string \| null` | `null` | 错误码枚举值 |
+| `error_message` | `string \| null` | `null` | 可读的错误描述 |
+| `http_status` | `number \| null` | `null` | HTTP 状态码（仅 `HTTP_ERROR`） |
+| `data` | `any` | 业务数据 | `null` |
+
+**错误码枚举：**
+
+| 错误码 | 含义 | 使用场景 |
+|--------|------|----------|
+| `VALIDATION_ERROR` | 参数缺失或不合法 | 参数校验 |
+| `DB_ERROR` | 数据库操作失败 | Repository 操作异常 |
+| `HTTP_ERROR` | 外部 HTTP 调用失败 | axios 调用异常 |
+| `CONFIG_ERROR` | 配置缺失 | setting 表缺少必要配置 |
+| `UNKNOWN_ERROR` | 未分类异常 | catch 兜底 |
+
+**约定：**
+- 查询无结果不是错误，返回 `ok([])`，由下游节点判断
+- 参数校验使用 `return fail(...)` 而非 `throw new Error(...)`
+- 下游节点通过 `result.success` 判断成功/失败
+
+## 9. Axios 错误处理
+
+当脚本包含外部 HTTP 调用时，catch 块需区分错误类型：
+
+```javascript
+} catch (err) {
+  const err_info = getMessageFromError(err)
+  console.error('操作失败:', err)
+
+  // HTTP 响应错误（4xx / 5xx）
+  if (err.response) return fail('HTTP_ERROR', err_info, err.response.status)
+
+  // 请求已发出但无响应（网络超时等）
+  if (err.request) return fail('HTTP_ERROR', '外部服务无响应: ' + err_info)
+
+  // 非 HTTP 错误（数据库或其他）
+  return fail('DB_ERROR', err_info)
+}
+```
+
+- `err.response` 存在 → 服务器返回了错误状态码，`err.response.status` 为 HTTP 状态码
+- `err.request` 存在但无 `err.response` → 请求已发出但未收到响应
+- 两者都不存在 → 非 HTTP 错误，归类为 `DB_ERROR`
+
+## 10. 注意事项
+
+- 脚本顶层支持 `await`，无需包裹 async 函数
+- `return` 的值会作为脚本节点的输出，传递给工作流下游节点
+- `console.log` 可用于调试，日志输出到工作流执行日志
+- 查询大量数据时 `pageSize` 设为较大值（如 `9999` 或 `99999`）
+- 日期格式统一使用 `dayjs().format('YYYY-MM-DD HH:mm:ss')`

package/skills/lab-nocobase-flow-generator/templates//350/204/232/346/234/254/351/200/273/350/276/221/346/226/207/346/241/243/346/250/241/346/235/277.md

@@ -0,0 +1,121 @@
+# 脚本逻辑文档模板
+
+> 产品人员按此模板编写脚本需求文档，AI Skill 将根据文档内容生成可在 NocoBase 工作流中运行的脚本。
+
+---
+
+## 1. 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| 脚本名称 | （例：查询化学品信息） |
+| 业务场景 | （简要描述脚本用途和触发场景） |
+| 输入参数来源 | `input_data` / `workflow_context` / 无 |
+
+---
+
+## 2. 输入参数
+
+> 描述脚本接收的参数，来源为工作流传入的变量。
+
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| （例：chemical_name） | string | 否 | 化学品名称 |
+| （例：cas） | string | 否 | CAS 编号 |
+
+**参数校验规则：**
+- （例：`chemical_name` 和 `cas` 至少填写一个）
+
+---
+
+## 3. 数据操作
+
+### 3.1 NocoBase 数据库操作
+
+> 列出所有需要操作的 NocoBase 数据表及操作类型。
+
+#### 操作 1：（描述操作目的）
+
+| 字段 | 值 |
+|------|-----|
+| 数据表 | （表名，例：`chemical`） |
+| 操作类型 | `find` / `create` / `update` / `destroy` |
+| 关联加载 | （需要 appends 的关联字段，无则填 `无`） |
+
+**过滤条件：**
+- （例：按 `chemical_name` 精确匹配）
+- （例：按 `cas` 精确匹配）
+- （例：按 `status` 在 `['Available', 'Expired']` 中筛选）
+
+**更新/写入字段（仅 create/update 时填写）：**
+
+| 字段名 | 值来源 | 说明 |
+|--------|--------|------|
+| （例：status） | 固定值 `'Expired'` | 更新状态 |
+
+---
+
+### 3.2 外部服务操作
+
+> 如需调用系统外部的 HTTP 接口，在此描述。无外部操作则删除本节。
+
+#### 接口 1：（描述接口用途）
+
+| 字段 | 值 |
+|------|-----|
+| 接口地址来源 | `setting` 表配置项（配置项名称，例：`rhea_host`）/ 固定地址 |
+| 请求路径 | （例：`/api/process/list_process`） |
+| 请求方法 | `GET` / `POST` / `PUT` / `DELETE` |
+| 认证方式 | `Bearer Token` / 无 / 其他 |
+
+**请求参数/请求体：**
+
+```json
+{
+  "说明": "在此描述请求的 JSON 结构",
+  "filter": {
+    "field": "status",
+    "operator": "not_in",
+    "value": ["Failed", "Completed"]
+  }
+}
+```
+
+**响应取值路径：**
+- （例：`res.data.results.records` → 任务记录列表）
+
+---
+
+## 4. 核心逻辑
+
+> 用自然语言 + 编号步骤，描述脚本的处理流程。重点描述：条件判断、数据转换、循环处理、错误处理等。
+
+1. 校验输入参数
+2. 查询数据表 / 调用外部接口
+3. 处理数据（过滤、转换、计算等）
+4. 写回数据表 / 返回结果
+
+**条件分支（如有）：**
+- 当 XXX 时 → 执行 A 操作
+- 当 YYY 时 → 执行 B 操作
+
+**循环处理（如有）：**
+- 遍历查询结果，对每条记录执行 ...
+
+---
+
+## 5. 输出结果
+
+> 描述脚本最终 return 的内容。
+
+| 场景 | 返回值 | 类型 |
+|------|--------|------|
+| 成功 | （例：查询到的数据列表） | object / array / string |
+| 无数据 | （例：`"No data found for ..."` 提示信息） | string |
+| 异常 | （例：`"Error: 错误信息"`) | string |
+
+---
+
+## 6. 备注（可选）
+
+- （任何补充说明、注意事项、性能要求等）