sino-bc-cli 1.2.0 → 1.3.1

package/dist/api-doc/biz-line-strategy.md

@@ -0,0 +1,313 @@
+# 业务线策略（Biz Line）
+
+数据来源：[sino-opti-hive 接口文档](https://o-test-sino-opti-hive.meetsocial.com/doc.html#/default/%E4%B8%9A%E5%8A%A1%E7%BA%BF%E7%AD%96%E7%95%A5)
+
+业务线主数据与周策略的增删改查，共 **17** 个接口。
+
+> **路由前缀**：经网关调用时所有路径需带 `/sino-opti-hive`，例如 `/sino-opti-hive/biz-line/list`。
+>
+> ⚠️ 标记为「写操作」的接口会变更线上数据，`/bc-api` 会按文档示例请求体直接发起调用，调用前请确认环境。
+
+| # | name | 展示名 | 方法 | 路径（含前缀） |
+| --- | --- | --- | --- | --- |
+| 1 | `biz-line-list` | 业务线分页列表 | POST | `/sino-opti-hive/biz-line/list` |
+| 2 | `biz-line-detail` | 业务线详情 | POST | `/sino-opti-hive/biz-line/detail` |
+| 3 | `biz-line-save` | 新建业务线 ⚠️ | POST | `/sino-opti-hive/biz-line/save` |
+| 4 | `biz-line-update` | 编辑业务线 ⚠️ | POST | `/sino-opti-hive/biz-line/update` |
+| 5 | `biz-line-status-update` | 切换业务线状态 ⚠️ | POST | `/sino-opti-hive/biz-line/status/update` |
+| 6 | `biz-line-del` | 删除业务线 ⚠️ | POST | `/sino-opti-hive/biz-line/del` |
+| 7 | `biz-line-list-export` | 业务线列表导出 | POST | `/sino-opti-hive/biz-line/list/export` |
+| 8 | `biz-line-strategy-list` | 全部策略分页 | POST | `/sino-opti-hive/biz-line/strategy/list` |
+| 9 | `biz-line-strategy-detail` | 策略详情（编辑返显） | POST | `/sino-opti-hive/biz-line/strategy/detail` |
+| 10 | `biz-line-strategy-period-list` | 策略周期列表 | POST | `/sino-opti-hive/biz-line/strategy/period-list` |
+| 11 | `biz-line-strategy-preview-info` | 新建策略前置-上期摘要 | POST | `/sino-opti-hive/biz-line/strategy/preview-info` |
+| 12 | `biz-line-strategy-save` | 新建策略 ⚠️ | POST | `/sino-opti-hive/biz-line/strategy/save` |
+| 13 | `biz-line-strategy-update` | 编辑策略 ⚠️ | POST | `/sino-opti-hive/biz-line/strategy/update` |
+| 14 | `biz-line-strategy-del` | 删除策略 ⚠️ | POST | `/sino-opti-hive/biz-line/strategy/del` |
+| 15 | `biz-line-strategy-compare` | 策略对比 | POST | `/sino-opti-hive/biz-line/strategy/compare` |
+| 16 | `biz-line-strategy-spend` | 策略周期消耗汇总 | POST | `/sino-opti-hive/biz-line/strategy/spend` |
+| 17 | `biz-line-strategy-export-all` | 导出全部策略 | POST | `/sino-opti-hive/biz-line/strategy/exprot-all` |
+
+> 第 17 项服务端路径确实拼作 `exprot-all`，与接口文档一致，请勿"修正"为 `export-all`。
+
+所有接口统一返回 `RestResponseVO` 包装，下文只描述 `result`。
+
+---
+
+## 业务线主数据
+
+### 1. 业务线分页列表
+
+`POST /sino-opti-hive/biz-line/list`
+
+`result` 为分页对象：`total` = 总条数，`page`、`size`，`result` = 当前页 `BizLineListVO` 列表。
+
+**请求体：`BizLineListReqVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `name` | string | 业务线名称，模糊搜索 |
+| `idList` | long[] | 业务线 ID 列表 |
+| `status` | int | 状态，默认 `1` 进行中 |
+| `ssoTeamCode` | string | 组别 code，精确筛选（单选，兼容旧版） |
+| `ssoTeamCodeList` | string[] | 组别 code 列表，多选 |
+| `pmUserIds` | long[] | PM 用户 ID 多选（OR 语义：命中任一 PM） |
+| `businessRegionList` | string[] | 商务地区多选，取值见 `BusinessRegionEnum` |
+| `projectRatingList` | string[] | 项目评级多选，取值见 `ProjectRatingEnum` |
+| `newCustomerTag` | string | 新客标签单选，取值见 `NewCustomerTagEnum` |
+| `adCategoryProjectId` | long | 投放类型筛选（`-1` 表示其他；其他值按 like 匹配） |
+| `trafficLightList` | int[] | 红绿灯筛选（策略表现），多选 |
+| `weekOverWeekFilter` | string | 周消耗环比筛选，单选，取值见 `WeekOverWeekFilterEnum` |
+| `sortType` | string | 排序字段，见下方说明 |
+| `sortDirection` | string | `ASC` 升序 / `DESC` 降序，默认 `DESC` |
+| `pageNum` / `pageSize` | int | 分页页数 / 每页数量 |
+| `pagination` | boolean | 是否分页，`false` 则不分页 |
+| `count` | boolean | 是否 Count |
+| `startIndex` | int | 起始行 |
+
+**`sortType` 取值**：`SPEND` 按上期周消耗（effective spend）、`WEEK_OVER_WEEK` 按上期周消耗环比、`PERIOD` 按本期策略周期（`week_start`）、`TRAFFIC_LIGHT` 按上期红绿灯（自定义顺序）。不传时默认按业务线 `id` 倒序。
+
+请求示例：
+
+```json
+{ "pageNum": 1, "pageSize": 20, "pagination": true, "count": true, "status": 1 }
+```
+
+### 2. 业务线详情
+
+`POST /sino-opti-hive/biz-line/detail`
+
+请求体：`{ "id": 1251 }`（`id` = 业务线 ID）。
+
+**响应 `result`：`BizLineDetailVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` / `name` | long / string | 业务线 ID 与名称 |
+| `status` | int | 状态：`1` 进行中、`2` 已完成、`3` 已暂停 |
+| `businessRegion` / `businessRegionDesc` | string | 商务地区枚举值与展示文案 |
+| `ssoTeamCode` / `ssoTeamCodeName` | string | 组别 code 与名称 |
+| `projectRating` / `projectRatingDesc` | string | 项目评级与展示文案 |
+| `newCustomerTag` / `newCustomerTagDesc` | string | 新客标签与展示文案 |
+| `strategyControlDegree` | int | 策略掌控程度：`1` 弱、`2` 强、`3` 中 |
+| `adCategoryIndustryIds` / `adCategoryProjectIds` / `adCategoryOther` | long[] / long[] / string | 投放品类行业、项目标签、其他说明 |
+| `mediaChannels` | int[] | 投放渠道 |
+| `pmUserIds` / `pmUserNames` | long[] / string[] | PM 用户 ID 与姓名，顺序对应 |
+| `amUserIds` / `amUserNames` | long[] / string[] | AM 用户 ID 与姓名，顺序对应 |
+| `corporationIds` / `corporationNames` | string[] / string[] | 关联客户公司 ID 与名称 |
+| `projectIds` / `projectNames` | long[] / string[] | 关联项目 ID 与名称 |
+| `customerTypeIds` / `customerTypeItems` / `customerTypeOther` | long[] / object[] / string | 客户类型 |
+| `customerInfrastructure` | int[] | 客户基建情况 |
+| `coreIndex` / `monthlyMaterialCount` / `projectBrief` | string | 核心指标、月度上新素材量、项目 brief |
+| `projectInitStatus` | string | 项目初始状态 |
+| `createBy` / `createByName` / `createTime` | int / string / string | 创建人与创建时间 |
+| `updateBy` / `updateByName` / `updateTime` | int / string / string | 更新人与更新时间 |
+
+### 3. 新建业务线 ⚠️
+
+`POST /sino-opti-hive/biz-line/save`，成功时 `result` 为新建业务线详情（`BizLineDetailVO`）。
+
+**请求体：`BizLineSaveReqVO`**
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `name` | string | — | 业务线名称 |
+| `businessRegion` | string | **是** | 商务地区，取值见 `BusinessRegionEnum` |
+| `ssoTeamCode` | string | **是** | 组别 code，单选 |
+| `projectRating` | string | 非新客必填 | 项目评级，取值见 `ProjectRatingEnum` |
+| `newCustomerTag` | string | — | 新客标签，取值见 `NewCustomerTagEnum` |
+| `strategyControlDegree` | int | — | 策略掌控程度 `1` 弱 `2` 强 `3` 中 |
+| `adCategoryIndustryIds` | long[] | — | 投放品类-行业 ID |
+| `adCategoryProjectIds` | long[] | — | 投放品类-项目标签 ID；选其他时可为空 |
+| `adCategoryOther` | string | — | 投放品类-其他说明 |
+| `mediaChannels` | int[] | — | 投放渠道 |
+| `pmUserIds` / `amUserIds` | long[] | — | PM / AM 用户 ID |
+| `corporationIds` | string[] | — | 关联签约主体 ID（字符串，与主体系统一致） |
+| `projectIds` | long[] | — | 关联项目 ID |
+| `customerTypeIds` / `customerTypeOther` | long[] / string | — | 客户类型及其他说明 |
+| `customerInfrastructure` | int[] | — | 客户基建情况枚举列表 |
+| `coreIndex` / `monthlyMaterialCount` / `projectBrief` | string | — | 核心指标、月度上新素材量、项目 Brief |
+| `projectInitStatus` | string | — | 项目初始化状态 |
+
+### 4. 编辑业务线 ⚠️
+
+`POST /sino-opti-hive/biz-line/update`，成功时 `result` 为 `Boolean`。
+
+请求体在「新建业务线」字段基础上增加：`id`（业务线 ID，必填）、`status`（`1` 进行中 `2` 已完成 `3` 已暂停）。
+
+### 5. 切换业务线状态 ⚠️
+
+`POST /sino-opti-hive/biz-line/status/update`，仅更新状态与操作人，`result` 为 `Boolean`。
+
+请求体：`{ "id": 1251, "status": 1 }`，`status` 对应 `BizLineStatusEnum`。
+
+### 6. 删除业务线 ⚠️
+
+`POST /sino-opti-hive/biz-line/del`，请求体 `{ "id": 1251 }`，`result` 为 `Boolean`。
+
+### 7. 业务线列表导出
+
+`POST /sino-opti-hive/biz-line/list/export`
+
+导出筛选条件下所有业务线数据，`result` 为 Excel 文件访问 URL。请求体同「业务线分页列表」的 `BizLineListReqVO`。
+
+---
+
+## 周策略
+
+### 8. 全部策略分页
+
+`POST /sino-opti-hive/biz-line/strategy/list`
+
+`result` 为分页对象，`result` 字段是当前页 `BizLineStrategyDetailVO` 列表。
+
+**请求体：`BizLineStrategyListReqVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `bizLineId` | long | 业务线 ID |
+| `trafficLight` | int | 红绿灯筛选 |
+| `sortType` / `sortDirection` | string | 排序方式 `desc` / `asc` |
+| `pageNum` / `pageSize` / `pagination` / `count` / `startIndex` | — | 分页参数，同业务线列表 |
+
+### 9. 策略详情（编辑返显）
+
+`POST /sino-opti-hive/biz-line/strategy/detail`，请求体 `{ "bizLineId": 1251, "id": 1 }`。
+
+**响应 `result`：`BizLineStrategyDetailVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` / `bizLineId` | long | 策略 ID / 所属业务线 ID |
+| `periodStart` / `periodEnd` | string | 策略周期起止（日期） |
+| `trafficLight` / `trafficLightDesc` | int / string | 红绿灯与展示文案 |
+| `customerSatisfaction` / `customerSatisfactionDesc` | int / string | 客户满意度与展示文案 |
+| `satisfactionReason` | string | 满意度原因说明 |
+| `coreEffectIndex` | string | 核心效果指标 |
+| `coreIssueCategories` / `coreIssueCategoryDescs` | int[] / string[] | 核心问题分类与展示文案 |
+| `issuesAndOpportunities` | string | 项目问题 & 机会 |
+| `spend` / `realSpend` / `weekSpendQoq` | string / number / number | 周期消耗（展示用）、媒体统计周消耗、周消耗环比（%） |
+| `budgetStrategyTags` / `budgetStrategyTagDescs` / `budgetStrategySupplement` | int[] / string[] / string | 预算策略标签、文案、补充说明 |
+| `budgetStrategyEffect` / `budgetStrategyEffectDesc` / `budgetStrategyLearning` | int / string / string | 预算策略效果与 Learning |
+| `audienceStrategy*` | — | 受众策略，字段结构同预算策略 |
+| `mediaStrategy*` | — | 媒介策略，字段结构同预算策略 |
+| `creativeStrategy` / `creativeStrategyEffect` / `creativeStrategyEffectDesc` / `creativeStrategyLearning` | — | 素材创意策略说明、效果与 Learning |
+| `version` | int | 乐观锁版本号，编辑时回传 |
+| `createBy` / `createByName` / `updateTime` | — | 创建人与最后更新时间 |
+
+**策略效果枚举**：`1` 有效、`2` 无效、`3` 待观察。
+
+### 10. 策略周期列表
+
+`POST /sino-opti-hive/biz-line/strategy/period-list`，请求体 `{ "bizLineId": 1251 }`。
+
+`result` 为 `BizLineStrategyPeriodListVO`：`items` 策略列表、`total` 策略期数。
+
+### 11. 新建策略前置-上期摘要
+
+`POST /sino-opti-hive/biz-line/strategy/preview-info`
+
+按目标周期取上期策略摘要，用于新建策略时预填。无上期策略时多为空字段。
+
+**请求体：`BizLineStrategyPreviewInfoReqVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `bizLineId` | long | 业务线 ID |
+| `periodStart` | string | 目标周期开始（周一） |
+| `periodEnd` | string | 目标周期结束（周日） |
+
+**响应关键字段**：`periodExist` 标识目标周期是否已有数据；`previewStrategyId` 为上期策略 ID（无上期时为 `null`）；`preview*` 系列字段为上期各维度策略标签与补充说明；`trafficLight`、`customerSatisfaction`、`spend` 为上期回顾数据。
+
+### 12. 新建策略 ⚠️
+
+`POST /sino-opti-hive/biz-line/strategy/save`，成功时 `result` 为 `Boolean`。
+
+**请求体：`BizLineStrategySaveReqVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `bizLineId` | long | 所属业务线 ID |
+| `periodStart` / `periodEnd` | string | 策略周期起止（日期） |
+| `trafficLight` | int | 红绿灯 |
+| `customerSatisfaction` / `satisfactionReason` | int / string | 客户满意度与原因说明 |
+| `coreEffectIndex` | string | 核心效果指标 |
+| `coreIssueCategories` | int[] | 核心问题分类（字典值列表） |
+| `issuesAndOpportunities` | string | 项目问题 & 机会 |
+| `spend` | string | 周期消耗（回顾，展示用字符串） |
+| `budgetStrategyTags` / `budgetStrategySupplement` / `budgetStrategyEffect` / `budgetStrategyLearning` | — | 预算策略标签、补充说明、效果、Learning |
+| `audienceStrategyTags` / `audienceStrategySupplement` / `audienceStrategyEffect` / `audienceStrategyLearning` | — | 受众策略同上 |
+| `mediaStrategyTags` / `mediaStrategySupplement` / `mediaStrategyEffect` / `mediaStrategyLearning` | — | 媒介策略同上 |
+| `creativeStrategy` / `creativeStrategyEffect` / `creativeStrategyLearning` | — | 素材创意策略 |
+| `previewPeriodStart` / `previewPeriodEnd` | string | 上期策略周期起止；缺省为本期 `periodStart` 的上一自然周周一、及其 +6 天 |
+| `previewBudgetStrategyTags` / `previewBudgetStrategySupplement` | — | 上期预算策略标签与补充说明 |
+| `previewAudienceStrategyTags` / `previewAudienceStrategySupplement` | — | 上期受众策略 |
+| `previewMediaStrategyTags` / `previewMediaStrategySupplement` | — | 上期媒介策略 |
+| `previewCreativeStrategy` | string | 上期素材创意策略说明 |
+
+### 13. 编辑策略 ⚠️
+
+`POST /sino-opti-hive/biz-line/strategy/update`，成功时 `result` 为 `Boolean`。
+
+请求体在「新建策略」字段基础上增加：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | long | 策略 ID |
+| `version` | int | 乐观锁版本号，取自策略详情 |
+| `overwrite` | boolean | 默认 `false`：版本冲突则报错；`true` 强制覆盖 |
+
+### 14. 删除策略 ⚠️
+
+`POST /sino-opti-hive/biz-line/strategy/del`，请求体 `{ "id": 1 }`，`result` 为 `Boolean`。
+
+### 15. 策略对比
+
+`POST /sino-opti-hive/biz-line/strategy/compare`，请求体 `{ "bizLineId": 1251, "currentId": 2, "prevId": 1 }`。
+
+**响应 `result`：`BizLineStrategyCompareVO`**
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `current` | `BizLineStrategyDetailVO` | 当前策略 |
+| `prev` | `BizLineStrategyDetailVO` | 对比策略（无主策略或无上期时可能为 `null`） |
+| `diffFields` | string[] | 存在差异的字段名列表，如 `coreIssueCategories`、`budgetStrategyTags` |
+
+### 16. 策略周期消耗汇总
+
+`POST /sino-opti-hive/biz-line/strategy/spend`，请求体 `{ "strategyId": 1 }`。
+
+`result` 为 `BizLineStrategySpendVO`：`totalSpend` 策略周期内关联项目周表消耗汇总。
+
+### 17. 导出全部策略
+
+`POST /sino-opti-hive/biz-line/strategy/exprot-all`，请求体 `{ "bizLineId": 1251 }`。
+
+`result` 为导出文件的访问 URL 字符串（由 Excel 写入组件返回）。
+
+---
+
+## 枚举速查
+
+| 枚举 | 取值 |
+| --- | --- |
+| `BizLineStatusEnum` | `1` 进行中、`2` 已完成、`3` 已暂停 |
+| `TrafficLightEnum` | `1` KPI 达标、`2` 距 GAP 20% 内、`3` 距 GAP 20% 以上、`4` 已暂停、`5` 存在风险、`6` KPI 达标且项目顺利 |
+| `CustomerSatisfactionEnum` | `1` 满意、`2` 不满意 |
+| 策略效果 | `1` 有效、`2` 无效、`3` 待观察 |
+| `strategyControlDegree` | `1` 弱（以客户策略为主）、`2` 强（以我方提供策略）、`3` 中（与客户共创） |
+| `ProjectRatingEnum` | `S` / `A` / `B` / `C` |
+
+---
+
+## 命令调用
+
+```bash
+# 默认生产环境 + 内置 API Key，交互选择接口
+sino-bc-cli /bc-api
+
+# 指定环境（test / pre / prod）
+sino-bc-cli /bc-api test
+```
+
+详见 [README.md](./README.md)。

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

@@ -0,0 +1,162 @@
+# Facebook广告策略维度数据
+
+- **name**：`icenter-mcp-strategy-dimension-facebook-ad-list`
+- **displayName**：Facebook广告策略维度数据
+- **Tool ID**：`309b7030fff848ccb6377c374c26574c`
+- **请求方法**：`POST`
+- **集成类型**：REST
+- **超时**：20000 ms
+- **状态**：Online / Public / enabled
+
+## 接口地址
+
+```
+https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/dimension/facebook/ad/list
+```
+
+- **baseUrl**：`https://o-test-tc-sino-icenter.meetsocial.com`
+- **path**：`/sino-icenter/mcp/strategy/dimension/facebook/ad/list`
+
+## 说明
+
+查询 Facebook（Meta）渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（广告目标、成效目标、出价方式、调整出价、受众类型、兴趣词包、年龄、性别等），用于分析某批账户在某段时间内各广告的策略配置分布。
+
+本接口**只返回策略维度**，不含消耗、点击等成效指标。需要成效数据请改用 [`icenter-mcp-strategy-metrics-facebook-ad-list`](./icenter-mcp-strategy-metrics-facebook-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` |
+| dimensionValues | object | 是 | — | 过滤条件，**仅支持 `account_id` 一个 key**，传其他 key 会报错 |
+| dimensions | string[] | 是 | — | 分组维度，必传且**不能为空数组**，否则返回结果为空 |
+| order | string | 否 | — | 排序字段，填单个维度 code，取值范围为 `dimensions` 的可选值。不必包含在已传的 `dimensions` 中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| orderType | string | 否 | `asc` | 排序方向：`desc` / `asc` |
+| page | integer | 否 | `1` | 页码，从 1 开始 |
+| size | integer | 否 | `10` | 每页条数，建议显式传且不超过 1000 |
+
+### dimensionValues
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| account_id | string[] | 是 | 广告账户 ID（带格式），必须带 `act_` 前缀，例如 `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 | 广告名称 |
+| bid_amount | 调整出价 |
+| objective | 广告目标 |
+| optimization_goal | 成效目标 |
+| bid_strategy | 出价方式 |
+| audience_type | 受众类型 |
+| targeting_geo_countries | 定向国家 |
+| targeting_geo_country_groups | 定向国家分组 |
+| targeting_interests | 兴趣词包 |
+| targeting_flexible_interests | 弹性兴趣词包 |
+| targeting_exclusion_interests | 排除兴趣词包 |
+| targeting_age | 年龄 |
+| targeting_genders | 性别 |
+
+## 返回格式
+
+- `result.data` 为数据行数组，每行的每个字段有两个 key：
+  - **原始值**：key 即请求的 code，如 `account_id: "act_1036928420879324"`，做计算或比较时用这个
+  - **展示值**：key 加 `display_` 前缀，如 `display_account_id`，直接呈现给用户时用这个，空值为 `"-"`
+- `result.headerMap` 是字段 code 到列名的映射，如 `{"objective": "广告目标"}`，用于给用户展示列名
+- `result.total` 为总条数，`result.page` 和 `result.size` 为当前分页
+- 外层 `code=0` 表示成功；非 0 时 `result` 为 `null`，失败原因在 `message` 字段里
+
+## 请求示例
+
+```json
+{
+  "startDate": "2026-08-01",
+  "endDate": "2026-08-31",
+  "dimensionValues": {
+    "account_id": ["act_1036928420879324"]
+  },
+  "dimensions": [
+    "account_id",
+    "ad_id",
+    "ad_name",
+    "objective",
+    "optimization_goal",
+    "bid_strategy",
+    "audience_type"
+  ],
+  "order": "ad_id",
+  "orderType": "asc",
+  "page": 1,
+  "size": 20
+}
+```
+
+## 成功响应示例
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "result": {
+    "page": 1,
+    "size": 20,
+    "total": 1,
+    "headerMap": {
+      "account_id": "广告账户",
+      "ad_id": "广告ID",
+      "ad_name": "广告名称",
+      "objective": "广告目标",
+      "optimization_goal": "成效目标",
+      "bid_strategy": "出价方式",
+      "audience_type": "受众类型"
+    },
+    "data": [
+      {
+        "account_id": "act_1036928420879324",
+        "display_account_id": "act_1036928420879324",
+        "ad_id": "120210000000000001",
+        "display_ad_id": "120210000000000001",
+        "ad_name": "示例广告",
+        "display_ad_name": "示例广告",
+        "objective": "CONVERSIONS",
+        "display_objective": "转化",
+        "optimization_goal": "OFFSITE_CONVERSIONS",
+        "display_optimization_goal": "网站转化",
+        "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
+        "display_bid_strategy": "最低成本",
+        "audience_type": "INTEREST",
+        "display_audience_type": "兴趣"
+      }
+    ]
+  }
+}
+```
+
+## 失败响应示例
+
+```json
+{
+  "code": 1,
+  "message": "dimensionValues 仅支持 account_id",
+  "result": null
+}
+```

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

@@ -0,0 +1,197 @@
+# Facebook广告策略成效数据
+
+- **name**：`icenter-mcp-strategy-metrics-facebook-ad-list`
+- **displayName**：Facebook广告策略成效数据
+- **Tool ID**：`21c4cd671d074b938a75234dae5985ee`
+- **请求方法**：`POST`
+- **集成类型**：REST
+- **超时**：20000 ms
+- **状态**：Online / Public / enabled
+
+## 接口地址
+
+```
+https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/metrics/facebook/ad/list
+```
+
+- **baseUrl**：`https://o-test-tc-sino-icenter.meetsocial.com`
+- **path**：`/sino-icenter/mcp/strategy/metrics/facebook/ad/list`
+
+## 说明
+
+查询 Facebook（Meta）渠道广告的策略维度加成效指标数据。在广告策略配置（广告目标、成效目标、出价方式、受众定向等）的分组下，返回消耗、曝光、点击、购买、安装等成效指标，用于分析哪种策略配置带来更好的投放效果。
+
+数据最多支持**近 21 天**。
+
+仅需策略配置、不含成效指标时，请改用 [`icenter-mcp-strategy-dimension-facebook-ad-list`](./icenter-mcp-strategy-dimension-facebook-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` 的可选值。不必包含在已传的 `dimensions` 或 `indicators` 中，服务端会自动补入参与排序，但该字段不会作为列返回 |
+| orderType | string | 否 | `asc` | 排序方向：`desc` / `asc` |
+| page | integer | 否 | `1` | 页码，从 1 开始 |
+| size | integer | 否 | `10` | 每页条数，建议显式传且不超过 1000 |
+
+### dimensionValues
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| account_id | string[] | 是 | 广告账户 ID（带格式），必须带 `act_` 前缀，例如 `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 | 广告名称 |
+| objective | 广告目标 |
+| optimization_goal | 成效目标 |
+| 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`（调整出价）。
+
+### 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 到列名的映射：
+  - 维度列名为中文（如 `objective=广告目标`）
+  - 指标列名为英文（如 `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",
+    "bid_strategy"
+  ],
+  "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": "成效目标",
+      "bid_strategy": "出价方式",
+      "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": "OFFSITE_CONVERSIONS",
+        "display_optimization_goal": "网站转化",
+        "bid_strategy": "LOWEST_COST_WITHOUT_CAP",
+        "display_bid_strategy": "最低成本",
+        "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
+}
+```