@xtalpi/agentic-lab-skills 0.0.10 → 0.0.11

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

@@ -1,84 +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 接口认证方式已说明 | 建议 |
-
-- **阻断**：未满足则不生成脚本，输出补充建议
-- **建议**：未满足仍可生成，但提示优化
+# 脚本逻辑文档规范
+
+本文档定义了产品人员编写「脚本逻辑文档」时须遵循的格式，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

@@ -1,224 +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')`
+# 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')`