@linkl/link-openapi-skills 0.0.0-stage → 0.1.0

package/openapi/user-service.json

@@ -0,0 +1,289 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "链路ERP开放平台",
+    "description": "userservice",
+    "contact": {
+      "name": "link",
+      "url": "https://www.linkl.com.cn"
+    },
+    "version": "1.0"
+  },
+  "servers": [
+    {
+      "url": "https://www.linkl.com.cn"
+    }
+  ],
+  "paths": {
+    "/openapi/oauthLogin": {
+      "post": {
+        "tags": [
+          "API列表"
+        ],
+        "summary": "oauth登录",
+        "description": "仅用于第三方登录",
+        "operationId": "oauthLogin",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CLURO_OpenApiOauthLoginRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/CLCMRLURO_OpenApiOauthLoginResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-order": 1,
+        "parameters": [
+          {
+            "name": "linkToken",
+            "in": "header",
+            "required": true,
+            "description": "接口访问凭证，请按接口要求填写。",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/openapi/getReceiveWarehouse": {
+      "post": {
+        "tags": [
+          "API列表"
+        ],
+        "summary": "获取收货仓库",
+        "operationId": "getReceiveWarehouse",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CLURO_OpenApiReceiveWarehouseRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/CLCMRULLURO_OpenApiWarehouseResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-order": 2,
+        "parameters": [
+          {
+            "name": "linkToken",
+            "in": "header",
+            "required": true,
+            "description": "接口访问凭证，请按接口要求填写。",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    },
+    "/openapi/getOwmsWarehouse": {
+      "post": {
+        "tags": [
+          "API列表"
+        ],
+        "summary": "获取海外仓仓库",
+        "operationId": "getOwmsWarehouse",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CLURO_OpenApiOwmsWarehouseRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/CLCMRULLURO_OpenApiWarehouseResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-order": 3,
+        "parameters": [
+          {
+            "name": "linkToken",
+            "in": "header",
+            "required": true,
+            "description": "接口访问凭证，请按接口要求填写。",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ]
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "CLURO_OpenApiOauthLoginRequest": {
+        "required": [
+          "password",
+          "userName"
+        ],
+        "type": "object",
+        "properties": {
+          "userName": {
+            "type": "string",
+            "description": "用户名"
+          },
+          "password": {
+            "type": "string",
+            "description": "密码"
+          }
+        },
+        "description": "OAuth登录请求",
+        "title": "OAuth登录请求"
+      },
+      "CLCMRLURO_OpenApiOauthLoginResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "integer",
+            "description": "返回码(0:成功 其他:失败)，业务code需大于1000",
+            "format": "int32"
+          },
+          "data": {
+            "$ref": "#/components/schemas/CLURO_OpenApiOauthLoginResponse"
+          },
+          "msg": {
+            "type": "string",
+            "description": "错误消息"
+          }
+        },
+        "description": "Result",
+        "title": "Result"
+      },
+      "CLURO_OpenApiOauthLoginResponse": {
+        "type": "object",
+        "properties": {
+          "redirectUrl": {
+            "type": "string",
+            "description": "重定向地址"
+          }
+        },
+        "description": "单点登录登录响应",
+        "title": "单点登录登录响应"
+      },
+      "CLURO_OpenApiReceiveWarehouseRequest": {
+        "type": "object",
+        "description": "收件仓库请求",
+        "title": "收件仓库请求"
+      },
+      "CLCMRULLURO_OpenApiWarehouseResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "integer",
+            "description": "返回码(0:成功 其他:失败)，业务code需大于1000",
+            "format": "int32"
+          },
+          "data": {
+            "type": "array",
+            "description": "数据结果",
+            "items": {
+              "$ref": "#/components/schemas/CLURO_OpenApiWarehouseResponse"
+            }
+          },
+          "msg": {
+            "type": "string",
+            "description": "错误消息"
+          }
+        },
+        "description": "Result",
+        "title": "Result"
+      },
+      "CLURO_OpenApiWarehouseResponse": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "仓库代码"
+          },
+          "name": {
+            "type": "string",
+            "description": "仓库名称"
+          },
+          "phone": {
+            "type": "string",
+            "description": "电话"
+          },
+          "address": {
+            "type": "string",
+            "description": "地址"
+          },
+          "contactName": {
+            "type": "string",
+            "description": "联系人"
+          }
+        },
+        "description": "仓库响应",
+        "title": "仓库响应"
+      },
+      "CLURO_OpenApiOwmsWarehouseRequest": {
+        "type": "object",
+        "description": "海外仓仓库请求",
+        "title": "海外仓仓库请求"
+      }
+    }
+  },
+  "x-openapi": {
+    "x-setting": {
+      "customCode": 200,
+      "language": "zh-CN",
+      "enableSwaggerModels": false,
+      "swaggerModelName": "Swagger Models",
+      "enableReloadCacheParameter": false,
+      "enableAfterScript": true,
+      "enableDocumentManage": false,
+      "enableVersion": false,
+      "enableRequestCache": true,
+      "enableFilterMultipartApis": false,
+      "enableFilterMultipartApiMethodType": "POST",
+      "enableHost": false,
+      "enableHostText": "",
+      "enableDynamicParameter": false,
+      "enableDebug": false,
+      "enableFooter": true,
+      "enableFooterCustom": false,
+      "enableSearch": true,
+      "enableOpenApi": true,
+      "enableHomeCustom": false,
+      "enableGroup": true,
+      "enableResponseCode": true
+    },
+    "x-markdownFiles": []
+  }
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@linkl/link-openapi-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "LINK OpenAPI Agent Skills",
+  "type": "module",
+  "bin": {
+    "link-openapi-skills": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "openapi/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/skills/link-basic-data/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: link-basic-data
+description: >
+  链路 ERP 基础数据 API：偏远验证、地址验证、城市邮编查询。
+  当用户需要调用该模块接口、生成 Java 接入代码或排查接口问题时使用。
+---
+
+# LINK 基础数据 Skill
+
+## 使用规则
+- 先阅读 `references/api-reference.md`，再选择接口。
+- 真实请求字段、必填项、枚举和响应结构必须以官方 OpenAPI 定义为准，不得猜测。
+- 所有接口使用服务端配置注入的 `linkToken` Header；不要把 Token 作为模型参数。
+- 部分请求体中的 `customerKey` 是业务字段，不等同于 `linkToken`。
+- 检查响应业务码，不要只凭 HTTP 200 判断成功。
+- 创建、取消、删除、上传、打印、推送等有副作用的操作，必须确认用户意图。
+- 非幂等请求失败后不得盲目重试；先检查业务结果。
+
+## Java 代码规范
+- Java 17+、Jackson、Lombok。
+- 密钥从环境变量、密钥管理服务或租户凭证库读取。
+- 金额、重量、尺寸等数值按 OpenAPI 类型处理，避免不必要的浮点精度损失。

package/skills/link-basic-data/references/api-reference.md

@@ -0,0 +1,22 @@
+# LINK 基础数据 API 参考
+
+- OpenAPI：`3.0.1`
+- Server：`https://www.linkl.com.cn`
+- 接口数：3
+
+> 本文件从对应 Swagger JSON 提取。请求字段和响应结构应以随包 OpenAPI 原文件为准。
+
+## 偏远验证
+
+- operationId：`validateRemote`
+- 请求：`POST /openapi/validateRemote`
+
+## 地址验证
+
+- operationId：`validateAddress`
+- 请求：`POST /openapi/validateAddress`
+
+## 城市邮编查询
+
+- operationId：`cityPostCodeSearch`
+- 请求：`POST /openapi/cityPostCodeSearch`

package/skills/link-general-service/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: link-general-service
+description: >
+  链路 ERP 综合服务 API：业务数据推送。
+  当用户需要调用该模块接口、生成 Java 接入代码或排查接口问题时使用。
+---
+
+# LINK 综合服务 Skill
+
+## 使用规则
+- 先阅读 `references/api-reference.md`，再选择接口。
+- 真实请求字段、必填项、枚举和响应结构必须以官方 OpenAPI 定义为准，不得猜测。
+- 所有接口使用服务端配置注入的 `linkToken` Header；不要把 Token 作为模型参数。
+- 部分请求体中的 `customerKey` 是业务字段，不等同于 `linkToken`。
+- 检查响应业务码，不要只凭 HTTP 200 判断成功。
+- 创建、取消、删除、上传、打印、推送等有副作用的操作，必须确认用户意图。
+- 非幂等请求失败后不得盲目重试；先检查业务结果。
+
+## Java 代码规范
+- Java 17+、Jackson、Lombok。
+- 密钥从环境变量、密钥管理服务或租户凭证库读取。
+- 金额、重量、尺寸等数值按 OpenAPI 类型处理，避免不必要的浮点精度损失。

package/skills/link-general-service/references/api-reference.md

@@ -0,0 +1,12 @@
+# LINK 综合服务 API 参考
+
+- OpenAPI：`3.0.1`
+- Server：`https://www.linkl.com.cn`
+- 接口数：1
+
+> 本文件从对应 Swagger JSON 提取。请求字段和响应结构应以随包 OpenAPI 原文件为准。
+
+## 推送数据
+
+- operationId：`pushPost`
+- 请求：`POST /openapi/push`

package/skills/link-international-logistics/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: link-international-logistics
+description: >
+  链路 ERP 国际物流 API：专线下单、快递下单、运单详情、物流轨迹、单号/文件上传、打印、订单删除及推送。
+  当用户需要调用该模块接口、生成 Java 接入代码或排查接口问题时使用。
+---
+
+# LINK 国际物流 Skill
+
+## 使用规则
+- 先阅读 `references/api-reference.md`，再选择接口。
+- 真实请求字段、必填项、枚举和响应结构必须以官方 OpenAPI 定义为准，不得猜测。
+- 所有接口使用服务端配置注入的 `linkToken` Header；不要把 Token 作为模型参数。
+- 部分请求体中的 `customerKey` 是业务字段，不等同于 `linkToken`。
+- 检查响应业务码，不要只凭 HTTP 200 判断成功。
+- 创建、取消、删除、上传、打印、推送等有副作用的操作，必须确认用户意图。
+- 非幂等请求失败后不得盲目重试；先检查业务结果。
+
+## Java 代码规范
+- Java 17+、Jackson、Lombok。
+- 密钥从环境变量、密钥管理服务或租户凭证库读取。
+- 金额、重量、尺寸等数值按 OpenAPI 类型处理，避免不必要的浮点精度损失。

package/skills/link-international-logistics/references/api-reference.md

@@ -0,0 +1,62 @@
+# LINK 国际物流 API 参考
+
+- OpenAPI：`3.0.1`
+- Server：`https://www.linkl.com.cn`
+- 接口数：11
+
+> 本文件从对应 Swagger JSON 提取。请求字段和响应结构应以随包 OpenAPI 原文件为准。
+
+## 上传单号
+
+- operationId：`uploadNo`
+- 请求：`POST /openapi/uploadNo`
+
+## 上传文件
+
+- operationId：`uploadFile`
+- 请求：`POST /openapi/uploadFile`
+
+## 专线下单
+
+- operationId：`specialLineOrder`
+- 请求：`POST /openapi/specialLineOrder`
+
+## 查询轨迹
+
+- operationId：`queryTracks`
+- 请求：`POST /openapi/queryTracks`
+
+## 推送数据
+
+- operationId：`pushPost`
+- 请求：`POST /openapi/push`
+
+## 打印文件
+
+- operationId：`print`
+- 请求：`POST /openapi/print`
+
+## 运单详情
+
+- operationId：`orderDetail`
+- 请求：`POST /openapi/orderDetail`
+
+## 快递下单
+
+- operationId：`expressOrder`
+- 请求：`POST /openapi/expressOrder`
+
+## dws文件上传
+
+- operationId：`dwsUploadFile`
+- 请求：`POST /openapi/dwsUploadFile`
+
+## dws上传数据
+
+- operationId：`dwsUploadDataPost`
+- 请求：`POST /openapi/dwsUploadData`
+
+## 删除订单
+
+- operationId：`deleteOrder`
+- 请求：`POST /openapi/deleteOrder`

package/skills/link-last-mile-order/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: link-last-mile-order
+description: >
+  链路 ERP 尾派制单 API：尾程下单、运费试算、根据试算结果下单、订单详情、取消及打印。
+  当用户需要调用该模块接口、生成 Java 接入代码或排查接口问题时使用。
+---
+
+# LINK 尾派制单 Skill
+
+## 使用规则
+- 先阅读 `references/api-reference.md`，再选择接口。
+- 真实请求字段、必填项、枚举和响应结构必须以官方 OpenAPI 定义为准，不得猜测。
+- 所有接口使用服务端配置注入的 `linkToken` Header；不要把 Token 作为模型参数。
+- 部分请求体中的 `customerKey` 是业务字段，不等同于 `linkToken`。
+- 检查响应业务码，不要只凭 HTTP 200 判断成功。
+- 创建、取消、删除、上传、打印、推送等有副作用的操作，必须确认用户意图。
+- 非幂等请求失败后不得盲目重试；先检查业务结果。
+
+## Java 代码规范
+- Java 17+、Jackson、Lombok。
+- 密钥从环境变量、密钥管理服务或租户凭证库读取。
+- 金额、重量、尺寸等数值按 OpenAPI 类型处理，避免不必要的浮点精度损失。

package/skills/link-last-mile-order/references/api-reference.md

@@ -0,0 +1,37 @@
+# LINK 尾派制单 API 参考
+
+- OpenAPI：`3.0.1`
+- Server：`https://www.linkl.com.cn`
+- 接口数：6
+
+> 本文件从对应 Swagger JSON 提取。请求字段和响应结构应以随包 OpenAPI 原文件为准。
+
+## 打印文件
+
+- operationId：`print`
+- 请求：`POST /openapi/print`
+
+## 下单
+
+- operationId：`order`
+- 请求：`POST /openapi/order`
+
+## 运单详情
+
+- operationId：`orderDetail`
+- 请求：`POST /openapi/orderDetail`
+
+## 根据试算id下单
+
+- operationId：`orderByCalPrice`
+- 请求：`POST /openapi/orderByCalPrice`
+
+## 取消运单
+
+- operationId：`cancel`
+- 请求：`POST /openapi/cancel`
+
+## 运费试算
+
+- operationId：`calPrice`
+- 请求：`POST /openapi/calPrice`

package/skills/link-openapi-integration/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: link-openapi-integration
+description: >
+  LINK 链路 ERP 物流开放平台接入技能。用于根据 LINK OpenAPI 规范选择接口、
+  解释认证、生成 Java 请求代码、使用 LINK MCP 工具、处理物流订单和轨迹，
+  以及排查接口错误。用户提到 LINK、链路 ERP、物流开放平台、运单、轨迹、
+  尾派、查价、仓库、结算或地址验证时使用。
+---
+
+# LINK OpenAPI Integration
+
+## Source of truth
+- 先读取 `references/API-INVENTORY.md` 定位业务接口，再读取对应业务参考文件。
+- 接口字段、必填项、枚举、路径和响应结构必须以随包的 LINK OpenAPI 文档为准。
+- 不得臆造接口、字段、签名算法或错误码。信息缺失时明确询问用户或要求官方确认。
+
+## Authentication observed in supplied specs
+- 六份 Swagger 中接口声明的通用认证 Header 为 `linkToken`。
+- 这些 Swagger 没有声明统一的 `X-API-Key` / `apiKey` 安全方案。
+- 部分请求体中存在 `customerKey`，这是业务参数，不要与认证 Header 混淆。
+- `linkToken` 必须由 SDK/MCP 服务端从环境变量或租户凭证库注入，不能暴露给模型或写入示例源码。
+
+## MCP and side effects
+- Skill 只提供工作流指引；实际调用 LINK API 需要单独配置 LINK MCP Server 或应用后端工具。
+- 创建、取消、删除、上传、打印、推送等有副作用的操作，必须在执行前确认用户意图。
+- 非幂等请求失败后不得盲目重试；先查询业务结果。
+- 检查响应业务码和业务消息，不能只依据 HTTP 200 判断成功。
+
+## Java SDK conventions
+- Java 17+、Jackson、Lombok。
+- AppKey/Token 等凭证从环境变量、密钥管理服务或租户凭证库读取。
+- 金额、重量、尺寸等数值遵循 OpenAPI Schema；需要精度的数值使用 BigDecimal。
+- 生成代码时包含 Request DTO、Response DTO、Client、异常处理和测试示例。
+
+## Business references
+- International logistics: `references/international-logistics.md`
+- User service: `references/user-service.md`
+- Last-mile order: `references/last-mile-order.md`
+- Settlement: `references/settlement-service.md`
+- General service: `references/general-service.md`
+- Basic data: `references/basic-data.md`

package/skills/link-openapi-integration/references/API-INVENTORY.md

@@ -0,0 +1,33 @@
+# LINK OpenAPI 接口清单
+
+> 从用户提供的 OpenAPI 3.0.1 JSON 文件提取；当前纳入 27 个接口。
+
+| 业务模块 | operationId | 方法 | 路径 |
+|---|---|---|---|
+| 国际物流 | `uploadNo` | POST | `/openapi/uploadNo` |
+| 国际物流 | `uploadFile` | POST | `/openapi/uploadFile` |
+| 国际物流 | `specialLineOrder` | POST | `/openapi/specialLineOrder` |
+| 国际物流 | `queryTracks` | POST | `/openapi/queryTracks` |
+| 国际物流 | `pushPost` | POST | `/openapi/push` |
+| 国际物流 | `print` | POST | `/openapi/print` |
+| 国际物流 | `orderDetail` | POST | `/openapi/orderDetail` |
+| 国际物流 | `expressOrder` | POST | `/openapi/expressOrder` |
+| 国际物流 | `dwsUploadFile` | POST | `/openapi/dwsUploadFile` |
+| 国际物流 | `dwsUploadDataPost` | POST | `/openapi/dwsUploadData` |
+| 国际物流 | `deleteOrder` | POST | `/openapi/deleteOrder` |
+| 用户服务 | `oauthLogin` | POST | `/openapi/oauthLogin` |
+| 用户服务 | `getReceiveWarehouse` | POST | `/openapi/getReceiveWarehouse` |
+| 用户服务 | `getOwmsWarehouse` | POST | `/openapi/getOwmsWarehouse` |
+| 尾派制单 | `print` | POST | `/openapi/print` |
+| 尾派制单 | `order` | POST | `/openapi/order` |
+| 尾派制单 | `orderDetail` | POST | `/openapi/orderDetail` |
+| 尾派制单 | `orderByCalPrice` | POST | `/openapi/orderByCalPrice` |
+| 尾派制单 | `cancel` | POST | `/openapi/cancel` |
+| 尾派制单 | `calPrice` | POST | `/openapi/calPrice` |
+| 结算服务 | `queryPrice` | POST | `/openapi/queryPrice` |
+| 结算服务 | `fetchAvailableProducts` | POST | `/openapi/fetchAvailableProducts` |
+| 结算服务 | `balance` | POST | `/openapi/balance` |
+| 综合服务 | `pushPost` | POST | `/openapi/push` |
+| 基础数据 | `validateRemote` | POST | `/openapi/validateRemote` |
+| 基础数据 | `validateAddress` | POST | `/openapi/validateAddress` |
+| 基础数据 | `cityPostCodeSearch` | POST | `/openapi/cityPostCodeSearch` |

package/skills/link-openapi-integration/references/basic-data.md

@@ -0,0 +1,9 @@
+# 基础数据
+
+链路 ERP 基础数据 API：偏远验证、地址验证、城市邮编查询。
+
+| operationId | Method | Path |
+|---|---|---|
+| `validateRemote` | POST | `/openapi/validateRemote` |
+| `validateAddress` | POST | `/openapi/validateAddress` |
+| `cityPostCodeSearch` | POST | `/openapi/cityPostCodeSearch` |

package/skills/link-openapi-integration/references/general-service.md

@@ -0,0 +1,7 @@
+# 综合服务
+
+链路 ERP 综合服务 API：业务数据推送。
+
+| operationId | Method | Path |
+|---|---|---|
+| `pushPost` | POST | `/openapi/push` |

package/skills/link-openapi-integration/references/international-logistics.md

@@ -0,0 +1,17 @@
+# 国际物流
+
+链路 ERP 国际物流 API：专线下单、快递下单、运单详情、物流轨迹、单号/文件上传、打印、订单删除及推送。
+
+| operationId | Method | Path |
+|---|---|---|
+| `uploadNo` | POST | `/openapi/uploadNo` |
+| `uploadFile` | POST | `/openapi/uploadFile` |
+| `specialLineOrder` | POST | `/openapi/specialLineOrder` |
+| `queryTracks` | POST | `/openapi/queryTracks` |
+| `pushPost` | POST | `/openapi/push` |
+| `print` | POST | `/openapi/print` |
+| `orderDetail` | POST | `/openapi/orderDetail` |
+| `expressOrder` | POST | `/openapi/expressOrder` |
+| `dwsUploadFile` | POST | `/openapi/dwsUploadFile` |
+| `dwsUploadDataPost` | POST | `/openapi/dwsUploadData` |
+| `deleteOrder` | POST | `/openapi/deleteOrder` |

package/skills/link-openapi-integration/references/last-mile-order.md

@@ -0,0 +1,12 @@
+# 尾派制单
+
+链路 ERP 尾派制单 API：尾程下单、运费试算、根据试算结果下单、订单详情、取消及打印。
+
+| operationId | Method | Path |
+|---|---|---|
+| `print` | POST | `/openapi/print` |
+| `order` | POST | `/openapi/order` |
+| `orderDetail` | POST | `/openapi/orderDetail` |
+| `orderByCalPrice` | POST | `/openapi/orderByCalPrice` |
+| `cancel` | POST | `/openapi/cancel` |
+| `calPrice` | POST | `/openapi/calPrice` |