@maptec/cli 1.0.0

package/skills/webapi-skills/references/direction-api.md

@@ -0,0 +1,175 @@
+# 路线规划
+
+## 1. 接口概述
+
+**路线规划** 是一项企业级 HTTP 服务，面向驾车等场景：接收一个或多个坐标点（及可选途经点），返回可导航的路线方案。
+
+## 2. 接口定义
+
+| 属性 | 定义 |
+| --- | --- |
+| HTTP 方法 | `POST` |
+| Endpoint URL | `https://api.maptec.com/routes/v1/directions` |
+| 认证方式 | HTTP Header：`Authorization: Bearer <YOUR_API_KEY>` |
+| 请求体格式 | `application/json` |
+| 响应体格式 | `application/json` |
+
+## 3. 请求参数
+
+### 3.1 顶级对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| origin | `Location Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 路线的起点。 |
+| destination | `Location Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 路线的终点。 |
+| waypoints | `Location[](Array)` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 途经点列表，按顺序访问。 |
+| mode | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 交通模式。V1.0支持：<br>· **`driving`**（标准驾车，默认）。 |
+| departureTime | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | **ISO 8601** 格式的时间戳（如 `2025-10-31T10:00:00Z`）。 <br>• **提供此时间**：计算未来该时间的交通状况。<br>• **不提供此时间**：默认为 **now**，使用 **实时路况**。 |
+| strategy | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 路线计算策略，默认 `fastest`。<br>• fastest: 时间最快路线（时间优先）。 <br>• shortest: 最短距离路线（距离优先）。<br>• balanced: 在时间和驾驶复杂度（如减少复杂转向）之间取得平衡。 |
+| alternatives | `Boolean` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 是否返回备选路线，默认 `false`。 |
+| language | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 导航指令(TBT)返回的语言。默认 `en-GB`。示例：`pt-BR`、`es-AR`。<br>V1.0支持：`en-GB`，`zh-CN`。 |
+| units | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 距离单位.metric（米/公里）或 imperial（英尺/英里），默认 :metric。 |
+| avoid | `Avoid Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | **[B2B核心]**<br>需要规避的区域或类型。需规避的区域或类型。 |
+
+
+### 3.2 Location 对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| location | `LatLng Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span>（或 `placeId` ） | 经纬度坐标。 |
+| placeId | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span>（或 `location` ） | 使用我们的地理编码或搜索接口获取的 `placeId`。 |
+| bearing | `Integer` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 车辆的行驶航向 **0–359**，用于更精准的出发匹配。 |
+| radius | `Integer` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 允许匹配的半径（米），用于纠正不精确的坐标。 |
+
+#### LatLng 对象
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| latitude | `Number` | 纬度值（以度为单位）, 取值`[-90.0, +90.0]` |
+| longitude | `Number` | 经度值（以度为单位），取值 `[-180.0, +180.0]` |
+
+
+### 3.3 Avoid 对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| criteria | `String[]` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 规避的常规类型。示例：`["highways"]`。<br>V1.0支持： highways: 避高速 |
+| polygons | `GeoJSON Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 客户自定义的规避多边形区域（GeoJSON FeatureCollection）。 |
+
+
+## 4. 返回值
+
+### 4.1 顶级响应对象
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| status | `String` | 响应状态吗：`“OK”`：成功且有结果\|`“ERROR”`：请求失败\|`“NO_ROUTE_FOUND”`：成功但无结果 |
+| routes | `Route[](Array)` | 路线方案列表。<br>如果 alternatives=true 且存在备选，则包含多条。 |
+| error | `Error Object` | 当 `"status"` 为 `"ERROR"` 时返回，含 `code`、`message`. |
+
+
+### 4.2 Route 对象
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| summary | `Summary Object` | 整条路线的概要信息。 |
+| legs | `Leg[](Array)` | 路线分段的列表；一个 leg 代表两个途经点（或起终点）之间的一段。 |
+| overviewPolyline | `String` | **(核心)** 整条路线的缩略图，使用Google Polyline 5编码。 |
+| warnings | `String[]` | 导航的警告信息，示例： ["Route avoids high_crime_zones due to user request."]。 |
+
+
+### 4.3 Summary 对象 (用于 Route 和 Leg)
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| distanceMeters | `Integer` | 距离（米）。 |
+| durationSeconds | `Integer` | 基础通行时间（秒），不考虑实时路况。 |
+| trafficDurationSeconds | `Integer` | 基于 `departureTime` 的预测性通行时间（秒）。 |
+
+
+### 4.4 Leg 对象 (路段)
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| summary | `Summary Object` | 此路段的概要信息（距离、时间）。 |
+| startAddress | `String` | 此路段起点的格式化地址。 |
+| endAddress | `String` | 此路段终点的格式化地址。 |
+| steps | `Step[]` | **（核心）** <br>Turn-by-Turn（TBT） 导航指令列表。 |
+
+
+### 4.5 Step 对象 (TBT指令)
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| instruction | `String` | **(核心)** <br>人类可读的TBT文本。示例："Vire à direita na Av. Paulista."<br>“前方500米进入某某道路” |
+| turnType | `String` | **(核心)** <br>TBT的类型，用于UI显示图标，如 `STRAIGHT`、`TURN_LEFT`、`KEEP_RIGHT`、`ENTER_ROUNDABOUT`。 |
+| distanceMeters | `Integer` | 该步骤的距离（米）。 |
+| durationSeconds | `Integer` | 该步骤的（动态）通行时间（秒）。 |
+| startLocation | `LatLng Object` | 经纬度坐标。 |
+| endLocation | `LatLng Object` | 经纬度坐标。 |
+| polyline | `String` | 该步骤的 Polyline 编码。 |
+| speedLimit | `Integer` | 该段最高限速（km/h）。前段可根据此数据做“您已超速”的闪烁提示。 |
+| roadClass | `String` | 道路等级。例如 `motorway`、`primary`、`residential`。（前段可根据此渲染不同颜色的路） |
+
+
+## 5. 示例
+
+### 示例 1：简单驾车请求 (实时路况)
+
+**Request:** POST /v1/directions?apiKey=...
+
+JSON
+
+```plain
+{
+  "origin": { "location": { "latitude": -23.5505, "longitude": -46.6333 } }, // São Paulo
+  "destination": { "location": { "latitude": -23.5616, "longitude": -46.6562 } },
+  "mode": "driving",
+  "language": "pt-BR"
+}
+```
+
+### 示例 2：核心返回值
+
+**Response:** HTTP 200 OK
+
+JSON
+
+```plain
+{
+  "status": "OK",
+  "routes": [
+    {
+      "summary": {
+        "distanceMeters": 435100,
+        "durationSeconds": 19800,
+        "trafficDurationSeconds": 21600 // [AI结果] 考虑早高峰预测，耗时21600秒
+      },
+      "overviewPolyline": "_p~iF~ps|U_ulLnnqC_...",
+      "legs": [
+        {
+          "summary": { "distanceMeters": 435100, ... },
+          "startAddress": "Av. Pres. Vargas, Rio de Janeiro - RJ, Brazil",
+          "endAddress": "Av. Paulista, São Paulo - SP, Brazil",
+          "steps": [
+            {
+              "instruction": "Siga na Av. Pres. Vargas.",
+              "turnType": "STRAIGHT",
+              "distanceMeters": 500,
+              "durationSeconds": 60,
+              "startLocation": { "latitude": -22.9068, "longitude": -43.1729 },
+              "endLocation": { "latitude": -22.9070, "longitude": -43.1735 }
+            },
+            {
+              "instruction": "Vire à direita na Av. Rio Branco.",
+              "turnType": "TURN_RIGHT",
+              ...
+            }
+            // ... 更多 steps
+          ]
+        }
+      ]
+    }
+  ]
+}
+```

package/skills/webapi-skills/references/geocoding.md

@@ -0,0 +1,195 @@
+# 正向地理编码
+
+**正向地理编码** 能够将人类可读的地址转换为经纬度坐标。
+
+## 1. 接口定义
+
+- 接口请求方式为GET，在 Header 中传递API密钥（优先），URL备选，既安全又易于调试。
+
+- **请求头包含** :
+
+| **Header** | **描述** |
+| --- | --- |
+| Authorization: YOUR_API_KEY | 用于请求服务的API密钥。 |
+
+**请求：** GET /search/{versionNumber}/geocode
+
+**接口串 (Endpoint):** https://api.maptec.com/search/v1/geocode?parameters
+
+- `parameters` 代表的参数包括必填参数和可选参数。所有参数均使用字符(&)进行分隔
+
+## 2. 请求参数
+
+### 2.1 查询参数
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| apiKey | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 用于请求服务的API密钥。 |
+| address | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 地址字符串。<br>注意事项：<br>·components 已包含足够信息，则可选。但对于完整地址进行地理编码时，如果请求中包含建筑物名称和编号，则必填。<br>·建议提供符合相关国家/地区的邮政服务所使用的地址格式，避免使用其他地址元素，例如企业名称、单元号、房间号或楼层号。<br>·搜索文本应以 URL 编码的 UTF-8 字符串形式表示，且不得包含分号（无论是原始分号还是 URL 编码后的分号）。解码后的搜索文本最多只能包含 50 个单词和数字，单词和数字之间用空格和标点符号分隔，且总长度不得超过 256 个字符。<br>*示例：`address=1%20St%20andrews%20rd,%20Singapore（%20为空格的网址转义）`* |
+| components | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 地址组成部分过滤器，限制服务仅返回特定区域的结果。<br>格式：`component:value\|component:value`。<br> **支持过滤的 components 包括：** <br>·country：国家/地区名称或[ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)国家代码（如GB）。<br>·postalCode：邮政编码 <br>**以下 components 可用于影响结果：** <br>·thoroughfare：匹配路线的全称或简称。<br>·administrativeArea：匹配所有行政区划级别（匹配region、subregion，在某些国家地区会有区别）。<br> **注意事项：** <br>1.如果请求包含重复的过滤条件，将被视为“AND”，而不是“OR”。<br>2.对于每个地址组成部分，可以在 address 参数中指定它，也可以在 components 过滤条件中指定它，但不能同时指定这两者。在两者中指定相同的值可能会导致空值。<br>*示例：*<br>*1. 组合使用，查询位于 SG 内的 Bayfront Avenue :*<br>*`address=Bayfront+Avenue&components=country:SG`*<br>*2. 不使用address参数，仅使用 components 发出有效查询，如位于 Singapore 的 Surrey 路：*<br>*`components=thoroughfare:surrey\|country:Singapore`* |
+| locationBias | `Rectangle Object` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 地理偏向：优先返回该参数设置的矩形范围中的结果。<br>矩形（Rectangle对象）：用两个经纬度值定义边界区域的 southwest 和 northeast 角。<br>*该参数只会增加对矩形范围内结果的偏向，但不能保证所有或任何结果都包含在该矩形范围内。* |
+| language | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 返回结果中可本地化文本的首选语言。取值为符合 IETF BCP 47 / RFC 5646 的语言标签，且必须在本平台支持的语言列表内。例如：`en`、`en-US`。 <br>大小写不敏感，推荐使用规范大小写。若指定语言不可用、部分字段无对应翻译，或该地区数据仅有本地语言名称，则返回本地语言或平台默认语言。 <br>默认值：`en`。 |
+| region | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 国家/地区代码，设置返回偏向特定地区的结果。该参数不会将结果严格限制在指定国家/地区内。<br>取值为 ISO 3166-1 alpha-2 / CLDR two-letter region code，大小写不敏感，推荐使用大写形式。例如：`BR`、`SG`。 |
+
+### 2.2 Rectangle 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 矩形框的东北角。 |
+| southwest | `LatLng Object` | 矩形框的西南角。 |
+
+### 2.3 LatLng 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| latitude | `Number` | 纬度值（以度为单位），取值 `[-90.0, +90.0]` |
+| longitude | `Number` | 经度值（以度为单位），取值 `[-180.0, +180.0]` |
+
+## 3. 标准返回值
+
+### 3.1 顶级响应对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| status | `String` | 响应请求的状态码。可能包含以下值：<br>`"OK"` 表示请求成功，并且至少返回了一条结果。<br>`"ZERO_RESULTS"` 表示请求成功，但未返回任何结果。<br>`"ERROR"` 表示请求失败。 |
+| results | `GeoResult[]` | 以 JSON 对象的形式返回响应。当服务返回结果时，会将结果放置在 results 数组中。即使未返回任何结果（例如，地址不存在），仍会返回一个空的 results 数组。 |
+| error | `Error Object` | 当 `"status"` 为 `"ERROR"` 时返回，包含 `code`、`message`。 |
+
+### 3.2 GeoResult 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| placeId | `String` | 地点的唯一标识符，可与其他服务搭配使用。 |
+| formattedAddress | `String` | 该位置格式化后完整地址。 |
+| types | `String[]` | 返回结果的实体类型，用于标识结果中所返回的地图项的类型。*详细类型见[《地址类型和地址组成部分》](#5.-地址类型与组成部分)*。 |
+| languageCode | `String` | 符合 IETF BCP 47 / RFC 5646 的语言标签。如 `en-US`。 |
+| addressComponents | `AddressComponent[]` | 结构化地址组件数组，包含适用于该地址的各个组成部分。 |
+| geometry | `Geometry Object` | 返回要素空间几何形状与坐标置信度评价。 |
+| matchDetails | `Object` | 匹配质量评价。|
+| supplementaryInfo | `Object` | 附加元数据与辅助描述。 |
+
+### 3.3 AddressComponent 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| type | `String` | 表示地址组成部分的通用类型。 |
+| localType | `String` | 当地称呼。 |
+| longName | `String` | 地址组成部分的完整文本说明或名称。 |
+| shortName | `String` | 地址组成部分的缩写文本名称（如有）。 |
+| isoCode | `String` | 仅 `type` 为 `country`、`region` 时返回：ISO 3166 唯一代码。 |
+
+### 3.4 Geometry 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| location | `LatLng Object` | 纬度/经度对应的对象。 |
+| locationType | `String` | 位置匹配精度类型。目前支持以下值：<br>·“ROOFTOP” 表示返回的结果是一个精确到街道地址级别的地理编码。<br>·“INTERPOLATED” 表示返回的结果为插值结果。当无法精确匹配时，通常会返回插值到两个精确点之间的位置（通常是在道路上）。<br>·“CENTER” 表示返回的结果是多段线（例如街道）或多边形（区域）等结果的几何图形中心。 |
+| viewport | `Viewport Object` | 返回结果的推荐视口，通过 northeast 和 southwest 定义的矩形范围。 |
+
+### 3.5 Viewport 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| northeast | `LatLng Object` | 推荐视口的矩形区域东北角。 |
+| southwest | `LatLng Object` | 推荐视口的矩形区域西南角。 |
+
+### 3.6 matchDetails 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| matchScore | `Double` | 综合匹配得分 **(0.00 - 1.00)**。 |
+| matchLevel | `String` | 最终匹配到的最高层级。 |
+| isDegraded | `Boolean` | 是否发生回退（如输入门牌但仅匹配到道路）。 |
+| isPartial | `Boolean` | 是否仅进行部分匹配，表示服务无法返回与原始请求完全匹配的结果。<br>最常见原因：<br>·请求中所传递的市行政区内不存在相关街道地址。<br>·当请求与同一市行政区中的两个或更多位置相匹配时，也可能会返回部分匹配。<br>·如果请求中包含拼写错误的地址组成部分，地理编码服务可能会推荐备选地址。通过这种方式触发的建议也将标记为部分匹配。 |
+| fieldScores | `fieldScores Object` | 各层级匹配得分，包含匹配到的层级及得分。（用于分析诊断） |
+
+### 3.7 supplementaryInfo 对象
+
+| 字段 | 类型 | 描述 |
+| --- | --- | --- |
+| externalId | `String` | 本地官方编码（如阿联酋 Makani码）。 |
+| relativeLocation | `String` | 相对位置描述（地址上下文）。 |
+
+## 4. JSON 示例
+
+```json
+{
+  "status": "OK",
+  "results": [
+    {
+      "placeId": "ChIJRxcAvRO7j4AR6hm6tys8yA8",
+      "formattedAddress": "Unit 201, Marina Heights, Dubai Marina, Dubai, AE",
+      "types": ["premise"],
+      "languageCode": "en-US",
+      "addressComponents": [
+        {
+          "type": "country",
+          "longName": "United Arab Emirates",
+          "shortName": "AE",
+          "isoCode": "AE"
+        },
+        {
+          "type": "region",
+          "localType": "Emirate",
+          "longName": "Dubai",
+          "isoCode": "AE-DU"
+        },
+        {
+          "type": "premise",
+          "longName": "Marina Heights"
+        }
+      ],
+      "geometry": {
+        "location": {
+          "lat": 25.08,
+          "lng": 55.14
+        },
+        "locationType": "ROOFTOP",
+        "viewport": {
+          "northeast": {
+          "latitude": 40.780785,
+          "longitude": -73.961895
+          },
+          "southwest": {
+            "latitude": 40.778088,
+            "longitude": -73.964593
+          }
+        }
+      },
+      "matchDetails": {
+        "matchScore": 0.98,
+        "matchLevel": "premise",
+        "isDegraded": false,
+        "isPartial": false，
+        "fieldScores": {
+          "country": 1.0,
+          "region": 1.0,
+          "sublocality": 1.0,
+          "premise": 0.98,
+          "subpremise": 0.97
+        }
+    },
+    "supplementaryInfo": {
+      "externalId": "1234567890",
+      "relativeLocation": "Next to the Marina Pharmacy"
+      }
+    }
+  ]
+}
+```
+
+## 5. 地址类型与组成部分
+
+| 地址类型 | 说明 |
+| --- | --- |
+| `country` | 表示国家政治实体（ISO 3166-1 alpha-2） |
+| `region` | 一级行政区（ISO 3166-2，省/州/自治区/酋长国等） |
+| `subregion` | 二级行政区（地级市/郡/县），在部分国家不常用 |
+| `locality` | 城镇/核心城市，用户常用的行政定位 |
+| `sublocality` | 区/街道/社区，对于在人口密集的亚洲/拉美是非常关键的 |
+| `neighborhood` | 最小地块单元（小区/村/住宅区） |
+| `thoroughfare` | 道路名称 |
+| `premise` | 门牌号、楼栋号 |
+| `subpremise` | 单元/楼层/房间号（通常由用户手动输入） |
+| `postalCode` | 表示国家/地区内邮寄地址所用的邮政编码 |
+| `intersection` | 主要交叉路口，通常是两条主要道路的交叉路口 |

package/skills/webapi-skills/references/ip-location.md

@@ -0,0 +1,87 @@
+---
+title: IP 定位服务(IP Location)
+source: https://www.yuque.com/zhishitairenxing/qp9bda/qg5hfpkpl2lvonwo/markdown?plain=true
+---
+
+# IP 定位服务(IP Location)
+
+## 1. 接口设计定义
+
+- **请求协议：** HTTP POST (Content-Type: application/json)
+- **请求地址：** [https://test-api.maptec.com/location/v1/ip](https://test-api.maptec.com/location/v1/ip)
+- **鉴权方式：** Header `Authorization: YOUR_API_KEY`
+
+## 2. 接口参数定义 (Request)
+
+| 参数名 | 类型 | 必填 | 描述 |
+| --- | --- | --- | --- |
+| ip | String | 是 | 待查询的 IPv4 或 IPv6 地址，如 `"114.114.114.114"`。 |
+| output | String | 否 | 返回格式，默认 `json`。 |
+
+### 请求示例
+
+```json
+{
+  "ip": "223.5.5.5"
+}
+```
+
+## 3. 返回值定义 (Response)
+
+返回结构需包含业务状态码与地理信息实体。
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| status | String | 响应请求的状态码。`"OK"` 表示请求成功并至少返回一条结果；`"ZERO_RESULTS"` 表示请求成功但未返回结果；`"ERROR"` 表示请求失败。 |
+| message | String | 状态说明。 |
+| result | Object | 结果实体。 |
+| result.country | String | 国家名称。 |
+| result.countryCode | String | 国家简码，ISO 3166-1 alpha-2，如 `US`。 |
+| result.province | String | 一级行政区名称，如省、州、直辖市等。 |
+| result.provinceCode | String | 一级行政区简码，ISO 3166-2，如 `CA`。 |
+| result.city | String | 城市名称。 |
+| result.location | Object | 地理位置对象。 |
+| result.location.lat | Double | 纬度。 |
+| result.location.lng | Double | 经度。 |
+| error | Error Object | 当 `status` 为 `"ERROR"` 或 `"ZERO_RESULTS"` 时返回，包含 `code` 和 `message`。 |
+
+### 正常返回示例
+
+```json
+{
+  "status": "OK",
+  "result": {
+    "country": "United States",
+    "countryCode": "US",
+    "province": "California",
+    "provinceCode": "CA",
+    "city": "San Francisco",
+    "location": {
+      "lat": 37.7749,
+      "lng": -122.4194
+    }
+  }
+}
+```
+
+### 空值返回示例
+
+```json
+{
+  "status": "ZERO_RESULTS",
+  "message": "NOT_FOUND_IP",
+  "error": null
+}
+```
+
+### 错误返回示例
+
+```json
+{
+  "status": "ERROR",
+  "error": {
+    "code": "21400",
+    "message": "INVALID_REQUEST_IP"
+  }
+}
+```

package/skills/webapi-skills/references/matrix-api.md

@@ -0,0 +1,149 @@
+# 距离矩阵
+
+**距离矩阵** 是一项全球兼容的企业级 HTTP 服务，提供从多个起点到多个终点的行程距离与时间批量计算能力。服务支持 **1×N** （单起点多终点）与 **M×N** （多起点多终点）两种矩阵模式，面向同城配送、网约车调度、长途货运规划等多样化业务需求。
+
+## 1. 接口定义
+
+| 属性 | 定义 |
+| :--- | :--- |
+| HTTP 方法 | `POST` |
+| Endpoint URL | `https://api.maptec.com/matrix/v1/distance` |
+| 认证方式 | HTTP Header：`Authorization: Bearer <YOUR_API_KEY>` |
+| 请求体格式 | `application/json` |
+| 响应体格式 | `application/json` |
+
+
+### 矩阵模式支持：
+
+| 模式 | 描述 | 典型场景 |
+| :--- | :--- | :--- |
+| **1×N** | 一个起点 → 多个终点 | 门店配送、就近查询 |
+| **M×N** | 多个起点 → 多个终点 | 路由优化、物流调度 |
+
+
+## 2. 请求参数
+
+### 2.1 顶级对象
+
+| 参数 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| origins | `Location[](Array)` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 起点数组。格式：`[{"lat": 39.9, "lng": 116.4}, ...]` 。<br>`origins` 数量 × `destinations` 数量 ≤ **25 × 25** 个元素。 |
+| destinations | `Location[](Array)` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 终点数组。格式：`[{"lat": 39.9, "lng": 116.4}, ...]` 。 |
+| mode | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 交通模式，默认 `driving` 。 |
+| trafficEnabled | `boolean` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 是否启用实时路况，默认为 `false` 。 |
+| departureTime | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 出发时间，**ISO 8601** 格式（如 `2025-10-31T10:00:00Z`)。 <br>· **提供此时间:** 预测性 ETA，按该时刻预测路况。<br>· **不提供此时间:** 视为 now，使用实时路况。 |
+| strategy | `String` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#FEE2E2;color:#991B1B;font-weight:600;">否</span> | 路线策略，默认 `default` 。可选值：`fastest` （最快）、`shortest` （最短）等。 |
+
+
+### 2.2 Location 对象（起终点坐标）
+
+| 字段 | 类型 | 必填 | 说明 |
+| :--- | :--- | :--- | :--- |
+| lat | `Number` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 纬度值（WGS-84），取值 `[-90.0, +90.0]` |
+| lon | `Number` | <span style="display:inline-block;padding:2px 10px;border-radius:999px;background:#DCFCE7;color:#166534;font-weight:600;">是</span> | 经度值（WGS-84），取值 `[-180.0, +180.0]` |
+
+
+## 3. 返回值
+
+### 3.1 同步模式响应（HTTP 200）
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| code | `String` | 业务状态码，`0` 表示成功，`-1` 表示失败 |
+| message | `String` | 响应说明，`OK` 表示成功 |
+| data | `Object` | 矩阵计算结果对象 |
+
+
+### 3.2 data 对象
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| routes | `RouteResult[](Array)` | 路线结果列表，按 `sources × destinations` 展开 |
+
+
+### 3.3 RouteResult 对象
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| status | `String` | 单条路线状态：`OK` / `FAILED` / `NO_ROUTE` |
+| diatance | `number` | 路线距离，单位：米（m）。`status != OK` 时为 `-1` |
+| duration | `number` | 路线时间，单位：秒（s）。`status != OK` 时为 `-1` |
+
+
+## 4. 示例
+
+### 4.1 请求（2 起点 × 2 终点）
+
+```json
+{
+  "origins": [
+    { "lon": 116.397428, "lat": 39.90923 },
+    { "lon": 116.3221,   "lat": 39.9033  }
+  ],
+  "destinations": [
+    { "lon": 116.4378, "lat": 39.9234 },
+    { "lon": 116.4074, "lat": 39.9042 }
+  ],
+  "mode": "driving",
+  "departure_time": "2025-10-31T09:00:00Z",
+  "strategy": "fastest"
+}
+```
+
+### 4.2 返回值
+
+*Response: HTTP 200 OK*
+
+```json
+{
+  "code": "OK",
+  "message": "success",
+  "data": {
+    "routes": [
+      { "status": "OK",       "distance": 8.5, "duration": 2  },
+      { "status": "OK",       "distance": 6.2, "duration": 8  },
+      { "status": "NO_ROUTE", "distance": -1,  "duration": -1 },
+      { "status": "FAILED",   "distance": -1,  "duration": -1 }
+    ]
+  }
+}
+```
+
+> **结果顺序说明：** `routes` 数组按 `origins × destinations` 顺序展开，即 `routes[i * len(destinations) + j]` 对应 `origins[i]` → `destinations[j]` 的路线结果。
+
+## 6. 错误与状态
+
+### 6.1 HTTP 状态码
+
+| HTTP Code | 说明 |
+|---|---|
+| `200` | 同步请求成功（业务结果见 `code` 字段） |
+| `202` | 异步任务已接受（仅异步接口） |
+| `400` | 请求参数错误 |
+| `401` | 认证失败，Token 无效或已过期 |
+| `403` | 权限不足 |
+| `429` | 请求过于频繁，触发限流 |
+| `500` | 服务端内部错误 |
+| `503` | 服务暂不可用（如引擎加载中） |
+
+
+### 6.2 单条路线状态码（status 字段）
+
+| 状态码 | 含义 | 说明 |
+|---|---|---|
+| `OK` | 成功 | 路线计算成功 |
+| `FAILED` | 失败 | 路线计算失败 |
+| `NO_ROUTE` | 无路线 | 起终点间不存在可用路线 |
+
+
+## 7. 约束与限制
+
+| 限制项 | 规则 | 超限处理方式 |
+|---|---|---|
+| 起点数量（同步） | ≤ 25 | 返回 `400`，错误信息：`sources count exceeds limit of 25` |
+| 终点数量（同步） | ≤ 25 | 返回 `400`，错误信息：`destinations count exceeds limit of 25` |
+| 路线总数（同步） | ≤ 625（25×25） | 由起点和终点数量乘积决定，超限返回 `400` |
+| 起终点最大距离 | ≤ 400 km | 单条路线超限返回 `status: FAILED`，`status_code: 3003` |
+| 实时路况路线数 | ≤ 100 | 启用 `traffic_enabled=true` 时，路线总数不得超过 100 |
+| 坐标系 | WGS-84 | 非 WGS-84 坐标可能导致吸附偏差 |
+| 坐标精度 | 建议保留 6 位小数 | 约 0.1 米精度 |