sino-bc-cli 1.3.3 → 1.4.0

package/dist/api-doc/icenter-mcp-strategy-metrics-facebook-ad-list.md

@@ -21,7 +21,7 @@ https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/facebook/ad
 
 ## 说明
 
-查询 Facebook（Meta）渠道广告的策略维度加成效指标数据。在广告策略配置（广告目标、成效目标、出价方式、受众定向等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
+查询 Facebook（Meta）渠道广告的策略维度加成效指标数据。在广告策略配置（广告目标、成效目标、创意类型、出价方式、受众定向等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
 
 数据最多支持**近 21 天**。
 
@@ -70,17 +70,16 @@ https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/facebook/ad
 | ad_name | 广告名称 |
 | objective | 广告目标 |
 | optimization_goal | 成效目标 |
+| ad_format | 创意类型 |
 | bid_strategy | 出价方式 |
 | audience_type | 受众类型 |
-| targeting_geo_countries | 定向国家 |
-| targeting_geo_country_groups | 定向国家分组 |
 | targeting_interests | 兴趣词包 |
 | targeting_flexible_interests | 弹性兴趣词包 |
 | targeting_exclusion_interests | 排除兴趣词包 |
 | targeting_age | 年龄 |
 | targeting_genders | 性别 |
 
-> 与维度接口相比，本接口的 `dimensions` **不含** `bid_amount`（调整出价）。
+> 与维度接口相比，本接口的 `dimensions` **不含** `bid_amount`（调整出价）、`country_code`（国家）。
 
 ### indicators 可选值
 
@@ -124,6 +123,7 @@ https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/facebook/ad
     "account_id",
     "objective",
     "optimization_goal",
+    "ad_format",
     "bid_strategy"
   ],
   "indicators": [
@@ -155,6 +155,7 @@ https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/facebook/ad
       "account_id": "广告账户",
       "objective": "广告目标",
       "optimization_goal": "成效目标",
+      "ad_format": "创意类型",
       "bid_strategy": "出价方式",
       "spend_usd": "Spend",
       "impressions": "Impressions",
@@ -170,6 +171,8 @@ https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/facebook/ad
         "display_objective": "转化",
         "optimization_goal": "OFFSITE_CONVERSIONS",
         "display_optimization_goal": "网站转化",
+        "ad_format": "SINGLE_IMAGE",
+        "display_ad_format": "单图",
         "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
         "display_bid_strategy": "最低成本",
         "spend_usd": 618.42,

package/dist/api-doc/icenter-mcp-strategy-metrics-google-ad-list.md

@@ -0,0 +1,201 @@
+# Google广告策略成效数据
+
+- **name**：`icenter-mcp-strategy-metrics-google-ad-list`
+- **displayName**：Google广告策略成效数据
+- **Tool ID**：`9e9d2617c7d64a57b7848dafc8eb5cb3`
+- **请求方法**：`POST`
+- **集成类型**：REST
+- **超时**：20000 ms
+- **状态**：Online / Public / enabled
+
+## 接口地址
+
+```
+https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/google/ad/list
+```
+
+- **baseUrl**：`https://test-agent.beyondclick.com`（网关地址，三环境同一地址，唯一来源 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`）
+- **path**：`/sino-icenter/mcp/strategy/metrics/google/ad/list`
+
+> 一律经网关调用，不要直连 iCenter 服务地址。
+
+## 说明
+
+查询 Google 渠道广告的策略维度加成效指标数据。在广告策略配置（成效目标、创意类型、出价方式、广告系列类型、关键字等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
+
+Google 渠道**不支持广告目标和兴趣词包维度**。数据最多支持**近 21 天**。
+
+仅需策略配置、不含成效指标时，请改用 [`icenter-mcp-strategy-dimension-google-ad-list`](./icenter-mcp-strategy-dimension-google-ad-list.md)。
+
+## 请求头
+
+| Header | 值 |
+| --- | --- |
+| Content-Type | `application/json` |
+
+## 请求参数
+
+请求体为 JSON object。
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| startDate | string | 是 | — | 开始日期，格式 `yyyy-MM-dd`，例如 `2026-08-01` |
+| endDate | string | 是 | — | 结束日期，格式 `yyyy-MM-dd`，例如 `2026-08-31`。最多支持查询近 21 天 |
+| dimensionValues | object | 是 | — | 过滤条件，**仅支持 `account_id` 一个 key**，传其他 key 会报错 |
+| dimensions | string[] | 是 | — | 分组维度，必传且**不能为空数组**，否则返回结果为空 |
+| indicators | string[] | 是 | — | 成效指标，必传且**不能为空数组** |
+| order | string | 否 | — | 排序字段，填单个 code，取值范围为 `dimensions` 或 `indicators` 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| orderType | string | 否 | `asc` | 排序方向：`desc` / `asc` |
+| page | integer | 否 | `1` | 页码，从 1 开始 |
+| size | integer | 否 | `10` | 每页条数，建议显式传且不超过 1000 |
+
+### dimensionValues
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| account_id | string[] | 是 | 广告账户 ID（带格式），必须带前缀，例如 `act_1036928420879324`。最多传 500 个 |
+
+### dimensions 可选值
+
+| code | 含义 |
+| --- | --- |
+| calendar_date | 投放日期 |
+| account_id | 广告账户 |
+| account_name | 账户名称 |
+| campaign_id | 广告系列 ID |
+| campaign_name | 广告系列名称 |
+| adgroup_id | 广告组 ID |
+| adgroup_name | 广告组名称 |
+| ad_id | 广告 ID |
+| ad_name | 广告名称 |
+| optimization_goal | 成效目标 |
+| ad_format | 创意类型 |
+| bid_strategy | 出价方式 |
+| audience_type | 受众类型 |
+| targeting_age | 年龄 |
+| targeting_genders | 性别 |
+| cpc_bid_amount | CPC 出价 |
+| cpm_bid_amount | CPM 出价 |
+| cpv_bid_amount | CPV 出价 |
+| advertising_channel_type | 广告系列类型 |
+| keywords | 关键字 |
+
+> 与维度接口相比，本接口的 `dimensions` **不含** `country_code`。Google 渠道**不含** `objective`、`targeting_interests`。
+
+### indicators 可选值
+
+| code | 含义 |
+| --- | --- |
+| spend_usd | 消耗金额，美元 |
+| impressions | 曝光量 |
+| clicks | 点击量 |
+| video_views | 视频观看次数 |
+| add_to_cart | 添加购物车次数 |
+| checkouts | 发起结账次数 |
+| purchase | 购买次数 |
+| purchase_value | 购买金额，美元 |
+| installs | 应用安装量 |
+| complete_registration | 完成注册量 |
+| leads | 留下潜客信息次数 |
+| engagement | 互动次数 |
+
+## 返回格式
+
+- `result.data` 为数据行数组，每行的每个字段有两个 key：
+  - **原始值**：key 即请求的 code，如 `spend_usd: 618.42`，做计算或比较时用这个
+  - **展示值**：key 加 `display_` 前缀，如 `display_spend_usd: "$618.42"`，直接呈现给用户时用这个，空值为 `"-"`
+- `result.headerMap` 是字段 code 到列名的映射：维度列名为中文，指标列名为英文（如 `spend_usd=Spend`）
+- `result.total` 为总条数，`result.page` 和 `result.size` 为当前分页
+- `result.conflictField` 是传入但当前渠道不支持的指标，会被忽略且不报错；为空数组表示全部指标都生效
+- 外层 `code=0` 表示成功；非 0 时 `result` 为 `null`，失败原因在 `message` 字段里
+
+## 请求示例
+
+```json
+{
+  "startDate": "2026-08-10",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": ["act_1036928420879324"]
+  },
+  "dimensions": [
+    "account_id",
+    "optimization_goal",
+    "ad_format",
+    "bid_strategy",
+    "advertising_channel_type"
+  ],
+  "indicators": [
+    "spend_usd",
+    "impressions",
+    "clicks",
+    "purchase",
+    "purchase_value"
+  ],
+  "order": "spend_usd",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+```
+
+## 成功响应示例
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "result": {
+    "page": 1,
+    "size": 20,
+    "total": 1,
+    "conflictField": [],
+    "headerMap": {
+      "account_id": "广告账户",
+      "optimization_goal": "成效目标",
+      "ad_format": "创意类型",
+      "bid_strategy": "出价方式",
+      "advertising_channel_type": "广告系列类型",
+      "spend_usd": "Spend",
+      "impressions": "Impressions",
+      "clicks": "Clicks",
+      "purchase": "Purchase",
+      "purchase_value": "Purchase Value"
+    },
+    "data": [
+      {
+        "account_id": "act_1036928420879324",
+        "display_account_id": "act_1036928420879324",
+        "optimization_goal": "CONVERSIONS",
+        "display_optimization_goal": "转化",
+        "ad_format": "RESPONSIVE_SEARCH_AD",
+        "display_ad_format": "自适应搜索广告",
+        "bid_strategy": "TARGET_CPA",
+        "display_bid_strategy": "目标 CPA",
+        "advertising_channel_type": "SEARCH",
+        "display_advertising_channel_type": "搜索",
+        "spend_usd": 618.42,
+        "display_spend_usd": "$618.42",
+        "impressions": 120340,
+        "display_impressions": "120,340",
+        "clicks": 3210,
+        "display_clicks": "3,210",
+        "purchase": 86,
+        "display_purchase": "86",
+        "purchase_value": 4521.3,
+        "display_purchase_value": "$4,521.30"
+      }
+    ]
+  }
+}
+```
+
+## 失败响应示例
+
+```json
+{
+  "code": 1,
+  "message": "查询区间超过近21天限制",
+  "result": null
+}
+```

package/dist/api-doc/icenter-mcp-strategy-metrics-tiktok-ad-list.md

@@ -0,0 +1,204 @@
+# TikTok广告策略成效数据
+
+- **name**：`icenter-mcp-strategy-metrics-tiktok-ad-list`
+- **displayName**：TikTok广告策略成效数据
+- **Tool ID**：`7a4fd873723a41b28636d64d46b04bce`
+- **请求方法**：`POST`
+- **集成类型**：REST
+- **超时**：20000 ms
+- **状态**：Online / Public / enabled
+
+## 接口地址
+
+```
+https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/metrics/tiktok/ad/list
+```
+
+- **baseUrl**：`https://test-agent.beyondclick.com`（网关地址，三环境同一地址，唯一来源 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`）
+- **path**：`/sino-icenter/mcp/strategy/metrics/tiktok/ad/list`
+
+> 一律经网关调用，不要直连 iCenter 服务地址。
+
+## 说明
+
+查询 TikTok 渠道广告的策略维度加成效指标数据。在广告策略配置（广告目标、成效目标、创意类型、出价方式、转化出价、深度转化出价、兴趣词包等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
+
+数据最多支持**近 21 天**。
+
+仅需策略配置、不含成效指标时，请改用 [`icenter-mcp-strategy-dimension-tiktok-ad-list`](./icenter-mcp-strategy-dimension-tiktok-ad-list.md)。
+
+## 请求头
+
+| Header | 值 |
+| --- | --- |
+| Content-Type | `application/json` |
+
+## 请求参数
+
+请求体为 JSON object。
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| startDate | string | 是 | — | 开始日期，格式 `yyyy-MM-dd`，例如 `2026-08-01` |
+| endDate | string | 是 | — | 结束日期，格式 `yyyy-MM-dd`，例如 `2026-08-31`。最多支持查询近 21 天 |
+| dimensionValues | object | 是 | — | 过滤条件，**仅支持 `account_id` 一个 key**，传其他 key 会报错 |
+| dimensions | string[] | 是 | — | 分组维度，必传且**不能为空数组**，否则返回结果为空 |
+| indicators | string[] | 是 | — | 成效指标，必传且**不能为空数组** |
+| order | string | 否 | — | 排序字段，填单个 code，取值范围为 `dimensions` 或 `indicators` 的可选值。不必包含在已传的字段中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| orderType | string | 否 | `asc` | 排序方向：`desc` / `asc` |
+| page | integer | 否 | `1` | 页码，从 1 开始 |
+| size | integer | 否 | `10` | 每页条数，建议显式传且不超过 1000 |
+
+### dimensionValues
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| account_id | string[] | 是 | 广告账户 ID（带格式），必须带前缀，例如 `act_1036928420879324`。最多传 500 个 |
+
+### dimensions 可选值
+
+| code | 含义 |
+| --- | --- |
+| calendar_date | 投放日期 |
+| account_id | 广告账户 |
+| account_name | 账户名称 |
+| campaign_id | 广告系列 ID |
+| campaign_name | 广告系列名称 |
+| adgroup_id | 广告组 ID |
+| adgroup_name | 广告组名称 |
+| ad_id | 广告 ID |
+| ad_name | 广告名称 |
+| optimization_goal | 成效目标 |
+| ad_format | 创意类型 |
+| bid_strategy | 出价方式 |
+| audience_type | 受众类型 |
+| targeting_age | 年龄 |
+| targeting_genders | 性别 |
+| objective | 广告目标 |
+| targeting_interests | 兴趣词包 |
+| conversion_bid | 转化出价 |
+| deep_cpabid | 深度转化出价 |
+
+> 与维度接口相比，本接口的 `dimensions` **不含** `bid_amount`（调整出价）、`country_code`（国家）。
+
+### indicators 可选值
+
+| code | 含义 |
+| --- | --- |
+| spend_usd | 消耗金额，美元 |
+| impressions | 曝光量 |
+| clicks | 点击量 |
+| video_views | 视频观看次数 |
+| add_to_cart | 添加购物车次数 |
+| checkouts | 发起结账次数 |
+| purchase | 购买次数 |
+| purchase_value | 购买金额，美元 |
+| installs | 应用安装量 |
+| complete_registration | 完成注册量 |
+| leads | 留下潜客信息次数 |
+| engagement | 互动次数 |
+
+## 返回格式
+
+- `result.data` 为数据行数组，每行的每个字段有两个 key：
+  - **原始值**：key 即请求的 code，如 `spend_usd: 618.42`，做计算或比较时用这个
+  - **展示值**：key 加 `display_` 前缀，如 `display_spend_usd: "$618.42"`，直接呈现给用户时用这个，空值为 `"-"`
+- `result.headerMap` 是字段 code 到列名的映射：维度列名为中文，指标列名为英文（如 `spend_usd=Spend`）
+- `result.total` 为总条数，`result.page` 和 `result.size` 为当前分页
+- `result.conflictField` 是传入但当前渠道不支持的指标，会被忽略且不报错；为空数组表示全部指标都生效
+- 外层 `code=0` 表示成功；非 0 时 `result` 为 `null`，失败原因在 `message` 字段里
+
+## 请求示例
+
+```json
+{
+  "startDate": "2026-08-10",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": ["act_1036928420879324"]
+  },
+  "dimensions": [
+    "account_id",
+    "objective",
+    "optimization_goal",
+    "ad_format",
+    "bid_strategy",
+    "conversion_bid"
+  ],
+  "indicators": [
+    "spend_usd",
+    "impressions",
+    "clicks",
+    "purchase",
+    "purchase_value"
+  ],
+  "order": "spend_usd",
+  "orderType": "desc",
+  "page": 1,
+  "size": 20
+}
+```
+
+## 成功响应示例
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "result": {
+    "page": 1,
+    "size": 20,
+    "total": 1,
+    "conflictField": [],
+    "headerMap": {
+      "account_id": "广告账户",
+      "objective": "广告目标",
+      "optimization_goal": "成效目标",
+      "ad_format": "创意类型",
+      "bid_strategy": "出价方式",
+      "conversion_bid": "转化出价",
+      "spend_usd": "Spend",
+      "impressions": "Impressions",
+      "clicks": "Clicks",
+      "purchase": "Purchase",
+      "purchase_value": "Purchase Value"
+    },
+    "data": [
+      {
+        "account_id": "act_1036928420879324",
+        "display_account_id": "act_1036928420879324",
+        "objective": "CONVERSIONS",
+        "display_objective": "转化",
+        "optimization_goal": "CONVERT",
+        "display_optimization_goal": "转化",
+        "ad_format": "SINGLE_VIDEO",
+        "display_ad_format": "单视频",
+        "bid_strategy": "BID_TYPE_CUSTOM",
+        "display_bid_strategy": "自定义出价",
+        "conversion_bid": "12.5",
+        "display_conversion_bid": "12.5",
+        "spend_usd": 618.42,
+        "display_spend_usd": "$618.42",
+        "impressions": 120340,
+        "display_impressions": "120,340",
+        "clicks": 3210,
+        "display_clicks": "3,210",
+        "purchase": 86,
+        "display_purchase": "86",
+        "purchase_value": 4521.3,
+        "display_purchase_value": "$4,521.30"
+      }
+    ]
+  }
+}
+```
+
+## 失败响应示例
+
+```json
+{
+  "code": 1,
+  "message": "查询区间超过近21天限制",
+  "result": null
+}
+```