@xtalpi/agentic-lab-skills 0.0.9 → 0.0.11

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

@@ -1,268 +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 + 参数表 + 响应示例」追加章节。
+# 页面内调用 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 + 参数表 + 响应示例」追加章节。