@xtalpi/agentic-lab-skills 0.0.1

package/skills/lab-orbit-component-builder/examples/xnb-component-template/AgenticAppAPI.md

@@ -0,0 +1,268 @@
+# 页面内调用 AgentLab / AgenticLab App 接口说明
+
+本文档描述在 **AgentLab / AgenticLab APP 前端页面**（含嵌入 Orbit Book / 独立 Cell 页等）中调用后端 HTTP 的约定。
+
+- **Base URL**：本地与 CI 通过 **`VITE_AGENTICLAB_API_URL`** 配置（见 `.env.local.example`）；嵌入 Orbit 时优先走 **`window.xnb.http.client.request`**（见 **`OrbitAPI.md`** 与 `src/utils/orbitHttpClient.ts`），与 Book 代理、鉴权一致。  
+- **鉴权**：Orbit 内用 **`await window.xnb.choreo.getUserToken()`**（无参；与本仓库 `agenticlabTickets` 一致）；本地可用 **`VITE_DEV_TOKEN`**（勿提交生产密钥）。
+
+---
+
+## 与 opener 初始化联动（`ticket_ids` → `ticket_id__in`）
+
+1. 页面挂载后调用 `fetchOpenerInitPayload`（见 `src/utils/openerInitParams.ts`），子页发送 `{ msg: 'get-data', trace }`；**流程页宿主**应回复 `{ msg: 'get-data-response', trace, ticket_ids, valve_id, ... }`（字段平铺在根上）。兼容 `{ msg: 'data', trace, payload }`。
+2. 规范化后的 **`payload`** 中须能解析出 **`ticket_ids`**：`string[]` 或逗号分隔的 `string`（与列表项 `detail.ticket_id` 一致）。**`valve_id`**（`number`）供 **`POST /api/execution/complete`**；亦可使用 **`VITE_AGENTICLAB_VALVE_ID`**，缺省为 `0`。
+3. 超级表格示例在拉表数据时：若已配置 `VITE_AGENTICLAB_API_URL` 且 `ticket_ids` 非空，会在 **`bootstrap` / `refreshTable`** 内请求 `GET /api/ticket/list`，并把 **`ticket_ids` 拼为 query 参数 `ticket_id__in`**（逗号分隔），将返回的 `data.list` 映射为表格行。
+4. 解析工具：`src/utils/openerTicketIds.ts` → `extractTicketIdsFromPayload`；请求实现见 `src/api/agenticlabTickets.ts`（优先 **`orbitRequestJson`**，见 **`OrbitAPI.md`**）。
+
+---
+
+## 通用响应包络
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | number | 业务状态码，成功常见为 `200` |
+| `msg` | string | 提示信息，成功时可为空字符串 |
+| `data` | object | 载荷；列表接口内含 `list` 与 `total` 等 |
+
+---
+
+## 查询工单列表
+
+### 基本信息
+
+| 项目 | 值 |
+|------|-----|
+| Path | `/api/ticket/list` |
+| Method | `GET` |
+| 说明 | 分页查询工单（ticket）列表，支持多条件筛选 |
+
+### Query 参数（与 OpenAPI 一致）
+
+| 名称 | 类型 | 位置 | 说明 |
+|------|------|------|------|
+| `limit` | number | query | 每页条数 |
+| `offset` | number | query | 分页偏移（从 0 开始） |
+| `fields` | string | query | 指定返回字段（可选） |
+| `ordering` | string | query | 排序（可选） |
+| `status__in` | string | query | 状态，**多选**（多值格式以后端为准，常见逗号分隔） |
+| `ticket_id__in` | string | query | 按业务工单号 **`detail.ticket_id`** 匹配，**多选**（示例：`TKT-34-005,TKT-34-006`） |
+| `flow_id__in` | string | query | 按 `flow_id` 匹配，**多选** |
+| `order_id__in` | string | query | 按 `order_id` 匹配，**多选** |
+| `pool_id__in` | string | query | 按 `pool_id` 匹配，**多选** |
+| `parent_ticket_id` | number | query | 按父工单 `parent_ticket_id` **精确**匹配 |
+| `uuid` | string | query | 按 `uuid` **精确**匹配 |
+| `batch_id` | number | query | 按 `batch_id` **精确**匹配 |
+| `id` | number | query | 按主键 `id` **精确**匹配 |
+
+**分页建议**：首次请求可设 `limit=100`、`offset=0`；下一页将 `offset` 增加为上一页 `offset + limit`，直至累计条数达到 `data.total` 或 `list` 为空。全量拉取时可设较大 `limit`（示例工程内默认 `999999`），以业务与网关上限为准。
+
+### 响应示例
+
+```json
+{
+  "data": {
+    "list": [
+      {
+        "id": 445,
+        "flow_id": 34,
+        "order_id": 19,
+        "pool_id": 124,
+        "parent_ticket_id": 73,
+        "uuid": "7798e1af-b47e-4d3b-aa7a-c359b1d65a68",
+        "detail": {
+          "fw": 100.09,
+          "mw": 78.11,
+          "cas": "71-43-2",
+          "smiles": "c1ccccc1",
+          "salt_form": "Na",
+          "salt_mole": 1,
+          "ticket_id": "TKT-34-005",
+          "compound_id": "CMP-E005",
+          "alo_order_id": "ALO-2026-04005",
+          "process_params": {
+            "@compound_id": "CMP-E005",
+            "@alo_order_id": "ALO-2026-04005",
+            "@tolerance_mg_1": 0.5,
+            "@tolerance_mg_2": 0.5,
+            "@tolerance_mg_3": 0.5,
+            "@target_amount_mg_1": 12,
+            "@target_amount_mg_2": 6,
+            "@target_amount_mg_3": 0,
+            "@target_vial_type_1": "2mL",
+            "@target_vial_type_2": "1mL",
+            "@target_vial_type_3": "",
+            "@requested_amount_mg": 18
+          },
+          "process_result": {
+            "error": true,
+            "message": "Request failed with status code 422"
+          },
+          "tolerance_1_mg": 0.5,
+          "tolerance_2_mg": 0.5,
+          "tolerance_3_mg": 0.5,
+          "submission_status": "提交失败",
+          "target_amount_1_mg": 12,
+          "target_amount_2_mg": 6,
+          "target_amount_3_mg": 0,
+          "target_vial_type_1": "2mL",
+          "target_vial_type_2": "1mL",
+          "target_vial_type_3": "",
+          "material_on_machine": false
+        },
+        "status": "created",
+        "batch_id": null,
+        "createdById": 1,
+        "updatedById": 1,
+        "createdAt": "2026-05-11T08:39:49.345Z",
+        "updatedAt": "2026-05-11T08:39:49.345Z"
+      }
+    ],
+    "total": 442
+  },
+  "code": 200,
+  "msg": ""
+}
+```
+
+### 响应字段说明（`data`）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.list` | array | 当前页的工单对象列表 |
+| `data.total` | number | 满足筛选条件的总条数（用于分页） |
+
+### 列表项 `list[]` 常用字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | number | 工单主键 |
+| `flow_id` | number | 流程 ID |
+| `order_id` | number | 订单 ID |
+| `pool_id` | number | 池 ID |
+| `parent_ticket_id` | number | 父工单 ID |
+| `uuid` | string | 工单 UUID |
+| `detail` | object | 业务详情（化合物、工艺参数、提交状态等） |
+| `status` | string | 工单状态，如 `created` |
+| `batch_id` | number \| null | 批次 ID |
+| `createdById` / `updatedById` | number | 创建人 / 最近更新人 |
+| `createdAt` / `updatedAt` | string | ISO 8601 时间 |
+
+`detail` 内与表格映射相关的字段（非穷举）：
+
+- `ticket_id`：业务工单号，对应筛选参数 **`ticket_id__in`**。  
+- `compound_id`、`smiles`：示例映射为表格「名称」列。  
+- `process_params['@requested_amount_mg']`、`target_amount_*_mg`：示例映射为表格「数量」列。
+
+---
+
+## 完成执行（execution complete）
+
+用于在页面侧将 **编辑后的工单数据** 一次性提交给后端，完成门控/执行闭环（**不**替代 Book 整书保存；与 **`OrbitAPI.md`** 中菜单保存事件无关）。
+
+### 基本信息
+
+| 项目 | 值 |
+|------|-----|
+| Path | `/api/execution/complete` |
+| Method | `POST` |
+| Query | 无 |
+| Body | **必填**，JSON |
+
+### 请求体
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `valve_id` | number | 门控或执行实例标识，与后端约定一致；示例可为 `0` |
+| `tickets` | array | 工单对象列表；**每一项的结构须与 `GET /api/ticket/list` 返回的 `data.list[]` 单项一致**（含 `id`、`flow_id`、`detail`、`status` 等），并把用户在表格中修改过的字段写回对应路径（例如示例表「数量」映射到 `detail.process_params['@requested_amount_mg']` 与 `detail.target_amount_1_mg`） |
+
+### 请求体示例
+
+```json
+{
+  "valve_id": 0,
+  "tickets": [
+    {
+      "id": 445,
+      "flow_id": 34,
+      "order_id": 19,
+      "pool_id": 124,
+      "detail": {
+        "ticket_id": "TKT-34-005",
+        "process_params": {
+          "@requested_amount_mg": 18
+        },
+        "target_amount_1_mg": 18
+      },
+      "status": "created"
+    }
+  ]
+}
+```
+
+### 响应
+
+沿用本文 **「通用响应包络」**：成功时常见 `code === 200`；失败时读取 `msg` 与 HTTP 状态。
+
+### 与本仓库示例的对应关系
+
+- **接口调用**：`src/api/agenticlabTickets.ts` → **`postAgenticlabExecutionComplete`**（经 **`orbitRequestJson`**，与列表接口同一鉴权方式）。
+- **提交流程**：`src/use/useSuperTableBitableLifecycle.ts` → **`submitRows`**：先 **`checkRows({ skipLoading: true })`** 校验表格「数量」等规则，再从当前子表 **`items`** 取最新单元格值，与内存中最近一次 **`GET /api/ticket/list`** 的原始行合并后组装 **`tickets`**，最后 **`POST`**；**不会**调用 `updateUserData` 模拟保存或 **`xnb.event.emit('xnb-book-menu', 'save', ...)`**。
+
+---
+
+## 环境变量（AgenticLab App）
+
+| 变量 | 说明 |
+|------|------|
+| `VITE_AGENTICLAB_API_URL` | AgenticLab App API 根地址，如 `https://your-agenticlab-host`（不要尾部的 `/api`） |
+| `VITE_DEV_TOKEN` | 可选；有则请求头 `Authorization: Bearer <token>` |
+| `VITE_AGENTICLAB_VALVE_ID` | 可选；`POST /api/execution/complete` 的 **`valve_id`**，当 opener `payload` 未带 `valve_id` 时使用；缺省按 `0` |
+
+### 与本仓库 HTTP 封装的关系
+
+工单列表与 **`POST /api/execution/complete`** 均由 **`src/api/agenticlabTickets.ts`** 发起，内部经 **`src/utils/orbitHttpClient.ts`** → **`orbitRequestJson`**：在 Orbit 宿主内走 **`window.xnb.http.client.request`**（与 **`OrbitAPI.md`** §6.3 一致）；无 `http.client` 时回退 **`fetch`**。Token 在 Orbit 内由 **`await window.xnb.choreo.getUserToken()`**（无参）或 **`VITE_DEV_TOKEN`** 提供。
+
+---
+
+## 页面调用注意
+
+1. **CORS**：浏览器直连跨域时需在网关或本地 devServer 配置代理。  
+2. **错误处理**：除 `code === 200` 外，应处理 HTTP 错误与业务 `msg`。  
+3. **`ticket_id__in` 多值**：本仓库示例使用英文逗号拼接多个 `ticket_id`。  
+
+---
+
+## 请求示例
+
+```http
+GET /api/ticket/list?limit=100&offset=0&ticket_id__in=TKT-34-005,TKT-34-006 HTTP/1.1
+Host: <VITE_AGENTICLAB_API_URL 主机>
+Accept: application/json
+Authorization: Bearer <token>
+```
+
+```http
+POST /api/execution/complete HTTP/1.1
+Host: <VITE_AGENTICLAB_API_URL 主机>
+Content-Type: application/json
+Accept: application/json
+Authorization: Bearer <token>
+
+{"valve_id":0,"tickets":[{"id":445,"detail":{"ticket_id":"TKT-34-005"}}]}
+```
+
+```javascript
+// 与 src/api/agenticlabTickets.ts 思路一致
+const ticketIdIn = ['TKT-34-005', 'TKT-34-006'].join(',')
+const url = new URL('/api/ticket/list', baseUrl)
+url.searchParams.set('limit', '100')
+url.searchParams.set('offset', '0')
+url.searchParams.set('ticket_id__in', ticketIdIn)
+const res = await fetch(url.toString(), { headers: { Accept: 'application/json', Authorization: `Bearer ${token}` } })
+const { data, code, msg } = await res.json()
+const list = data?.list ?? []
+```
+
+---
+
+后续若有更多 AgenticLab App 接口，可在本文件按「Path + Method + 参数表 + 响应示例」追加章节。

package/skills/lab-orbit-component-builder/examples/xnb-component-template/Jenkinsfile

@@ -0,0 +1,106 @@
+// @Library('exar@2.0dev') _
+// Version: 0.0.1
+def FAILED_STAGE
+
+pipeline {
+  agent {
+    docker {
+      label 'pro-spot'
+      image 'hub.xtalpi.cc/development/webb_ci:1.0.0'
+      registryUrl 'https://hub.xtalpi.cc'
+      registryCredentialsId 'hub_pass'
+      args '-u root:root -v /var/run/docker.sock:/var/run/docker.sock'
+    }
+  }
+  options {
+    skipDefaultCheckout(true)
+    timestamps()
+  }
+  stages {
+    stage ('Pull code') {
+      steps {
+        checkout scm
+      }
+    }
+    stage ('Prepare') {
+      steps {
+        echo 'Prepare env'
+        sh 'env'
+        sh "exar login -k $EXAR_APPKEY -s $EXAR_APPSECRET"
+        sh 'exar context init'
+        load "$WORKSPACE/.exar/env.groovy"
+      }
+    }
+    stage ('Lint') {
+      steps {
+        script { FAILED_STAGE = env.STAGE_NAME }
+        echo 'Static check'
+        sh  """ eslint --ext .js,.ts,.tsx,.vue src \
+                --resolve-plugins-relative-to /usr/local/node-v14.17.5-linux-x64/lib/node_modules \
+                --config /usr/local/node-v14.17.5-linux-x64/lib/.eslintrc.js \
+                --no-eslintrc
+            """
+      }
+    }
+    stage ('Build') {
+      steps {
+        script { FAILED_STAGE = env.STAGE_NAME }
+        echo 'Build project'
+        // sh 'npm install'
+        // sh 'npm run build'
+      }
+    }
+    stage ('Publish') {
+      when {
+        expression {
+          env.EXAR_DEFAULT_COMMIT_MESSAGE =~ /<publish>|<publish-npm>|<publish-dist>/
+        }
+        anyOf {
+          branch 'master'
+          branch 'G2'
+          branch 'hotfix/*'
+        }
+      }
+      steps {
+        script { 
+          FAILED_STAGE = env.STAGE_NAME
+          if (env.EXAR_DEFAULT_COMMIT_MESSAGE =~ /<publish>/) {
+            echo 'Publish to webb'
+            sh  """ webb publish dependency . \
+                --env=0 \
+                --user=$EXAR_DEFAULT_USER \
+                --link=$RUN_DISPLAY_URL \
+                --message='"$EXAR_DEFAULT_COMMIT_MESSAGE"' \
+                --branch="$BRANCH_NAME"
+            """
+          }
+          if (env.EXAR_DEFAULT_COMMIT_MESSAGE =~ /<publish-dist>/) {
+            echo 'Publish to webb'
+          }
+          if (env.EXAR_DEFAULT_COMMIT_MESSAGE =~ /<publish-npm>/) {
+            echo 'Publish to npm'
+            sh 'npm publish'
+          }
+        }
+      }
+    }
+  }
+
+  post {
+    always {
+      sh 'git clean -ffdx'
+    }
+    failure {
+      echo 'Failed...'
+      sh  """ webb notify '[{ "key": "🧭 阶段", "value": "${FAILED_STAGE}" }]' \
+                --title="提交代码失败" \
+                --name="$JOB_NAME" \
+                --user="$EXAR_DEFAULT_USER" \
+                --link="$RUN_DISPLAY_URL" \
+                --message='"$EXAR_DEFAULT_COMMIT_MESSAGE"' \
+                --branch="$BRANCH_NAME" \
+                --type="error"
+              """
+    }
+  }
+}