sino-bc-cli 1.3.2 → 1.4.0

package/README.md

@@ -140,11 +140,14 @@ sino-bc-cli/
 │   │
 │   ├── commands/                 # 📦 命令实现层（每命令一个文件，可独立扩展）
 │   │   ├── index.ts              # 命令批量注册入口
-│   │   ├── init.command.ts       # /init 命令实现（注册 Agent 技能）
+│   │   ├── init.command.ts       # /init 命令实现（注册 Agent 技能 + 初始化变量配置）
 │   │   ├── api-list.command.ts   # /api-list 命令实现（列出接口并打开文档）
 │   │   ├── api-endpoint.command.ts # 接口调用类命令基类（选择接口 → 发起调用 → 打印响应）
 │   │   ├── ic-api.command.ts     # /ic-api 命令实现（调用 iCenter 接口地址）
-│   │   └── bc-api.command.ts     # /bc-api 命令实现（调用业务线查询 / 业务线策略接口）
+│   │   ├── bc-api.command.ts     # /bc-api 命令实现（调用业务线查询 / 业务线策略接口）
+│   │   ├── get-config.command.ts # /get-config 命令实现（查看变量配置）
+│   │   ├── set-config.command.ts # /set-config 命令实现（修改变量配置）
+│   │   └── uninstall.command.ts  # /uninstall 命令实现（清理技能目录与配置并卸载）
 │   │
 │   ├── utils/                    # 🛠 工具类层（高内聚的可复用工具）
 │   │   ├── index.ts              # 工具模块统一导出
@@ -152,7 +155,11 @@ sino-bc-cli/
 │   │   ├── browser.ts            # 浏览器工具（跨平台 URL 打开，兼容 Win/macOS/Linux）
 │   │   ├── crypto.ts             # 加密工具（MD5、SHA-256、AES、Base64、签名生成）
 │   │   ├── http.ts               # HTTP 工具（axios 封装：请求/响应拦截、自动重试）
-│   │   └── common.ts             # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
+│   │   ├── common.ts             # 通用工具（日期、深拷贝、防抖节流、ID 生成等）
+│   │   ├── prompt.ts             # 终端交互（复用单一 readline 会话：提问、选择、确认）
+│   │   ├── config-store.ts       # 变量配置读写（字段元信息 + 读 / 写 / 删）
+│   │   ├── config-prompt.ts      # 变量配置交互采集（/init 与 /set-config 共用）
+│   │   └── skill-install.ts      # Agent 技能目录的写入与清理
 │   │
 │   ├── types/                    # 📝 类型定义层
 │   │   └── index.ts              # 全局接口、枚举定义（ICommand、LogLevel 等）
@@ -160,8 +167,8 @@ sino-bc-cli/
 │   └── constants/                # 🔧 常量配置层
 │       └── index.ts              # CLI 配置、命令名称、默认值
 │
-├── dist/                         # 📤 编译输出目录（编译后自动生成）
-│   └── ...                       # JavaScript 编译产物 + 类型声明 + SourceMap
+├── dist/                         # 📤 构建输出目录（构建后自动生成）
+│   └── ...                       # 单文件混淆压缩产物 + SKILL.md + api-doc（不含 SourceMap）
 │
 ├── package.json                  # 📄 项目配置（依赖、脚本、bin 命令）
 ├── tsconfig.json                 # 📄 TypeScript 编译配置
@@ -280,10 +287,38 @@ sino-bc-cli /init
 
 | 命令        | 说明                                                                                          |
 | :---------- | :-------------------------------------------------------------------------------------------- |
-| `/init`     | 将本包 `SKILL.md` 复制到用户主目录下的 Agent 技能目录，供飞书豆包工作 / Cursor / Claude / Codex 自动识别 |
-| `/api-list` | 列出全部可调用接口；Cursor / VS Code 终端中 Ctrl+单击接口名或文档路径打开本地文档，也可输入序号或传入 name |
-| `/ic-api`   | 交互选择并调用 iCenter 接口地址（路径统一带 `/sino-icenter` 前缀）；`ENV` 默认 `prod`，`API_KEY` 默认使用网关常量 |
-| `/bc-api`   | 交互选择并调用业务线查询 / 业务线策略接口（共 22 个，路径统一带 `/sino-opti-hive` 前缀）        |
+| `/init`       | 注册 `SKILL.md` 到 Agent 技能目录，并交互设置环境 / `X-GATEWAY-TYPE` / `API_KEY` 写入变量配置文件 |
+| `/api-list`   | 列出全部可调用接口；Cursor / VS Code 终端中 Ctrl+单击接口名或文档路径打开本地文档，也可输入序号或传入 name |
+| `/ic-api`     | 交互选择并经网关调用 iCenter 接口（路径统一带 `/sino-icenter` 前缀）；**不接收参数**，环境与鉴权取自变量配置文件 |
+| `/bc-api`     | 交互选择并调用业务线查询 / 业务线策略接口（共 22 个，路径统一带 `/sino-opti-hive` 前缀）；**不接收参数** |
+| `/get-config` | 查看变量配置文件内容；`API_KEY` 默认打码，`--show-secret` 显示明文，`--json` 输出 JSON |
+| `/set-config` | 修改变量配置文件内容；不带参数时逐项交互修改 |
+| `/uninstall`  | 删除 `/init` 创建的技能目录与变量配置文件，并从全局 npm 卸载本 CLI |
+
+### 变量配置文件
+
+环境、`X-GATEWAY-TYPE`、`API_KEY` 统一存放在 `<用户主目录>/.sino-bc-cli/config.json`，是这三项取值的唯一来源。
+
+| 字段 | 命令行键名 | 默认值 | 说明 |
+| :--- | :--------- | :----- | :--- |
+| `env` | `env` | `prod` | 目标环境，可选 `test` / `pre` / `prod` |
+| `gatewayType` | `gateway-type` | `A2C-CLI` | `X-GATEWAY-TYPE` 请求头取值 |
+| `apiKey` | `api-key` | 内置默认 Key | 网关鉴权用的 API Key |
+
+```bash
+# 查看（API_KEY 打码）
+sino-bc-cli /get-config
+
+# 三种修改写法等价
+sino-bc-cli /set-config env test
+sino-bc-cli /set-config env=test
+sino-bc-cli /set-config --env=test
+
+# 不带参数则逐项交互修改，直接回车保留当前值
+sino-bc-cli /set-config
+```
+
+> `/init` 在非交互环境（npm `postinstall`、CI、Agent 调用）下不会提问：配置文件不存在时按默认值创建，已存在时保持不变，因此重装或升级不会覆盖你设置好的环境与密钥。
 
 ### 全局选项
 
@@ -293,6 +328,18 @@ sino-bc-cli /init
 | `--help`    | `-h`   | 显示帮助信息                              |
 | `--debug`   | `-d`   | 启用 Debug 日志模式，输出更详细的运行信息 |
 
+### 环境与请求网关
+
+`/ic-api`、`/bc-api` 的请求地址一律由 [`src/constants/gateway.ts`](./src/constants/gateway.ts) 的 `GATEWAY_CONFIG` 决定，命令内部统一走 `joinGatewayUrl(env, path)` 拼接，不在任何命令或文档里硬编码请求地址。
+
+| `ENV`  | 说明     | 网关地址                             |
+| :----- | :------- | :----------------------------------- |
+| `test` | 测试环境 | `https://test-agent.beyondclick.com` |
+| `pre`  | 预发环境 | `https://test-agent.beyondclick.com` |
+| `prod` | 生产环境 | `https://test-agent.beyondclick.com` |
+
+> 当前三环境同一地址。换地址只需改 `GATEWAY_CONFIG`，同时同步 [`SKILL.md`](./SKILL.md) 与 [`src/api-doc/`](./src/api-doc/README.md) 中的示例地址。
+
 ### 使用示例
 
 #### ① 查看版本和帮助
@@ -317,23 +364,22 @@ sino-bc-cli /api-list biz-line-open-list
 
 执行效果：按「iCenter MCP / 业务线查询 / 业务线策略」分组列出全部接口。接口名是终端超链接，文档路径可 Ctrl+单击打开对应 markdown；交互终端也可输入序号。传入序号或接口 `name` 则直接打开该文档。
 
-#### ③ 调用 iCenter 接口地址
+#### ③ 经网关调用 iCenter 接口
 
 ```bash
 sino-bc-cli /ic-api
-sino-bc-cli /ic-api test
 ```
 
-执行效果：交互选择接口后，向对应环境的 iCenter 接口地址发起请求。所有路径带 `/sino-icenter` 前缀。
+执行效果：交互选择接口后，向变量配置文件指定环境的网关地址发起请求。所有路径带 `/sino-icenter` 前缀。
+本命令不接收参数，切换环境请先执行 `sino-bc-cli /set-config env <test|pre|prod>`。
 
 #### ④ 调用业务线查询 / 业务线策略接口
 
 ```bash
 sino-bc-cli /bc-api
-sino-bc-cli /bc-api test
 ```
 
-执行效果：按「业务线查询（5 个）」「业务线策略（17 个）」两组列出接口，输入序号后向对应环境网关发起请求。所有路径统一带 `/sino-opti-hive` 路由前缀，接口清单见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
+执行效果：按「业务线查询（5 个）」「业务线策略（17 个）」两组列出接口，输入序号后向配置文件指定环境的网关发起请求。所有路径统一带 `/sino-opti-hive` 路由前缀，接口清单见 [`src/api-doc/README.md`](./src/api-doc/README.md)。
 
 > ⚠️ 业务线策略组含新建 / 编辑 / 删除等写操作接口，会按文档示例请求体直接发起调用，执行前请确认环境。
 

package/dist/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: sino-bc-cli
 description: >
-  Use when 查询或操作 BeyondClick / iCenter / 业务线数据：Facebook 广告策略维度或成效、
+  Use when 查询或操作 BeyondClick / iCenter / 业务线数据：Facebook / Google / TikTok 广告策略维度或成效、
   投放渠道、投放品类、业务线列表/详情/策略与表现、Top 业务线、周策略增删改查、
   红绿灯、客户满意度、消耗、ROAS；或用户提到 sino-bc-cli、/init、/api-list、
-  /ic-api、/bc-api、sino-icenter、sino-opti-hive、A2C-CLI。
+  /ic-api、/bc-api、/get-config、/set-config、/uninstall、sino-icenter、
+  sino-opti-hive、A2C-CLI。
 metadata:
   requires:
     bins: ["sino-bc-cli"]
@@ -16,7 +17,7 @@ BeyondClick 投放数据与业务线策略的 Agent 调用入口。用本 CLI
 
 ## When to Use
 
-- 查 Facebook（Meta）广告策略配置、消耗/点击/购买等成效
+- 查 Facebook / Google / TikTok 广告策略配置、消耗/点击/购买等成效
 - 查投放渠道、投放行业/品类、业务线主数据、周策略与表现、行业 Top
 - 新建/编辑/删除业务线或周策略（须先确认环境和写操作意图）
 - 用户点名 `/api-list`、`/ic-api`、`/bc-api`、iCenter、sino-opti-hive
@@ -27,15 +28,21 @@ BeyondClick 投放数据与业务线策略的 Agent 调用入口。用本 CLI
 
 | 项 | 规则 |
 | --- | --- |
-| 环境 | `test` / `pre` / `prod`，未指明默认 `prod` |
-| 网关 | `https://test-agent.beyondclick.com`（当前三环境同一地址） |
+| 环境 | `test` / `pre` / `prod`，取自变量配置文件，默认 `prod` |
+| 网关 | `https://test-agent.beyondclick.com`（当前三环境同一地址；所有请求只走网关，不直连服务地址） |
 | iCenter 前缀 | `/sino-icenter` |
 | 业务线前缀 | `/sino-opti-hive` |
-| 鉴权 | `Authorization: Bearer <API_KEY>`；用户未给 Key 时用 CLI 内置默认值 |
-| 来源头 | 必须带 `X-GATEWAY-TYPE: A2C-CLI` |
+| 鉴权 | `Authorization: Bearer <API_KEY>`；取自变量配置文件，未设置时用 CLI 内置默认值 |
+| 来源头 | 必须带 `X-GATEWAY-TYPE`，取自变量配置文件，默认 `A2C-CLI` |
 | 请求体 | 按用户条件组装；禁止原样提交文档示例账号/业务线 ID |
 
-`/ic-api`、`/bc-api` 会停在「请输入序号」，且只用文档默认 body。Agent 在非 TTY 下不要跑这两条；需要真实查询时直接 HTTP。
+### 变量配置文件
+
+环境、`X-GATEWAY-TYPE`、`API_KEY` 统一存放在 `<用户主目录>/.sino-bc-cli/config.json`，由 `/init` 创建、`/set-config` 修改。
+需要知道当前生效取值时执行 `sino-bc-cli /get-config --json`（`API_KEY` 默认打码，加 `--show-secret` 才是明文）。
+
+`/ic-api`、`/bc-api` 不接收任何参数，且必须在交互式终端里选接口、只用文档默认 body。
+Agent 在非 TTY 下跑这两条会直接报错退出；需要真实查询时用 `/api-list` 发现接口后直接 HTTP。
 
 ## Agent 流程
 
@@ -61,8 +68,12 @@ CLI 未安装：`npm i sino-bc-cli@latest -g`（需 Node.js >= 24）。技能未
 
 | 用户在问 | name | 注意 |
 | --- | --- | --- |
-| Facebook 广告策略配置（目标/出价/受众，不含消耗） | `icenter-mcp-strategy-dimension-facebook-ad-list` | `dimensionValues` 只能有 `account_id`；账户须 `act_` 前缀；`dimensions` 非空 |
-| 策略 + 成效（消耗、点击、购买等） | `icenter-mcp-strategy-metrics-facebook-ad-list` | 最多近 21 天；`indicators` 非空 |
+| Facebook 广告策略配置（目标/出价/受众/创意，不含消耗） | `icenter-mcp-strategy-dimension-facebook-ad-list` | `dimensionValues` 只能有 `account_id`；账户须 `act_` 前缀；`dimensions` 非空；`country_code` 必须单独传 |
+| Facebook 策略 + 成效（消耗、点击、购买等） | `icenter-mcp-strategy-metrics-facebook-ad-list` | 最多近 21 天；`indicators` 非空 |
+| Google 广告策略配置（成效目标/出价/系列类型，不含消耗） | `icenter-mcp-strategy-dimension-google-ad-list` | 不支持广告目标和兴趣词包；出价用 `cpc_bid_amount` / `cpm_bid_amount` / `cpv_bid_amount`；`country_code` 必须单独传 |
+| Google 策略 + 成效 | `icenter-mcp-strategy-metrics-google-ad-list` | 最多近 21 天；`indicators` 非空 |
+| TikTok 广告策略配置（含转化出价/深度转化出价，不含消耗） | `icenter-mcp-strategy-dimension-tiktok-ad-list` | TikTok 独有 `conversion_bid` / `deep_cpabid`；`country_code` 必须单独传 |
+| TikTok 策略 + 成效 | `icenter-mcp-strategy-metrics-tiktok-ad-list` | 最多近 21 天；`indicators` 非空 |
 | iCenter git 版本 | `icenter-mcp-version-query` | GET，无 body |
 
 ### 业务线查询（只读，文档 `biz-line-query.md`）
@@ -97,18 +108,25 @@ CLI 未安装：`npm i sino-bc-cli@latest -g`（需 Node.js >= 24）。技能未
 ```bash
 sino-bc-cli /api-list
 sino-bc-cli /api-list biz-line-open-list
-sino-bc-cli /ic-api test          # 交互；默认文档示例 body
-sino-bc-cli /bc-api --env=prod
-sino-bc-cli /init
+sino-bc-cli /ic-api                       # 交互选接口；不接收参数，用文档示例 body
+sino-bc-cli /bc-api
+
+sino-bc-cli /init                         # 注册技能 + 交互设置环境 / 网关头 / API_KEY
+sino-bc-cli /get-config                   # 查看变量配置（API_KEY 打码）
+sino-bc-cli /set-config env prod          # 改单项；也支持 --env=prod、不带参数逐项交互
+sino-bc-cli /uninstall                    # 清理技能目录与配置文件并卸载 CLI
 ```
 
 ## Common Mistakes
 
 | 错误 | 正确做法 |
 | --- | --- |
-| 非 TTY 执行 `/ic-api`、`/bc-api` 卡住 | 直接 HTTP；只用 `/api-list` 发现接口 |
+| 非 TTY 执行 `/ic-api`、`/bc-api` | 这两条会报错退出；改直接 HTTP，只用 `/api-list` 发现接口 |
+| 给 `/ic-api`、`/bc-api` 传环境或 Key | 参数已下线；用 `/set-config` 改、`/get-config` 查 |
 | 用文档里的 `act_…` / `bizLineId: 1251` | 换成用户给出的账户或业务线 |
 | 成效接口一次查超过 21 天 | 拆段或改查维度接口 |
+| 把 `country_code` 和其他维度一起传 | 国家维度必须单独查，不能和其他维度同时传入 |
 | 漏 `X-GATEWAY-TYPE` 或路径前缀 | 带 `A2C-CLI`；iCenter / 业务线分别加对应前缀 |
+| 直连 `o-test-tc-sino-icenter` / `o-test-sino-opti-hive` 等服务地址 | 一律请求网关 `https://test-agent.beyondclick.com` + 路由前缀 |
 | 未确认就调 save/update/del | 先确认环境与写操作 |
 | 把 `exprot-all` 改成 `export-all` | 按服务端拼写调用 |

package/dist/api-doc/README.md

@@ -4,22 +4,40 @@
 
 | 分组 | 命令 | 接口数 | 文档 |
 | --- | --- | --- | --- |
-| iCenter MCP | `/ic-api` | 3 | 见下方「iCenter MCP 接口」 |
+| iCenter MCP | `/ic-api` | 7 | 见下方「iCenter MCP 接口」 |
 | 业务线查询 | `/bc-api` | 5 | [biz-line-query.md](./biz-line-query.md) |
 | 业务线策略 | `/bc-api` | 17 | [biz-line-strategy.md](./biz-line-strategy.md) |
 
 ---
 
+## 请求网关
+
+所有接口一律经网关调用，网关地址的唯一来源是 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`；各文档中出现的上游服务地址（`o-test-tc-sino-icenter`、`o-test-sino-opti-hive` 等）仅作接口文档出处，不作为请求地址。
+
+| 环境 | 网关地址 |
+| --- | --- |
+| `test` 测试环境 | `https://test-agent.beyondclick.com` |
+| `pre` 预发环境 | `https://test-agent.beyondclick.com` |
+| `prod` 生产环境 | `https://test-agent.beyondclick.com` |
+
+> 当前三环境同一地址；改地址只改 `GATEWAY_CONFIG`，代码通过 `joinGatewayUrl(env, path)` 取值，不要在别处硬编码。
+
+---
+
 ## iCenter MCP 接口
 
-数据来源：[ContextForge MCP Gateway Admin - Tools](https://o-test-sino-mcp-gateway.meetsocial.cn/admin/?tools_page=2&tools_size=10&tools_inactive=false#tools)
+数据来源：[ContextForge MCP Gateway Admin - Tools](https://o-test-sino-mcp-gateway.meetsocial.cn/admin/?team_id=61761abbe4a4476c84c7df2cd7335a52#tools)
 
-筛选规则：`name` 以 `icenter-mcp-` 开头。当前共 **3** 个接口，每个接口一份独立文档。所有路径经网关调用时统一带 `/sino-icenter` 路由前缀，例如 `/sino-icenter/version`。
+筛选规则：`name` 以 `icenter-mcp-` 开头。当前共 **7** 个接口，每个接口一份独立文档。所有路径经网关调用时统一带 `/sino-icenter` 路由前缀，例如 `/sino-icenter/version`。
 
 | 文档 | name | 展示名 | 方法 | 说明 |
 | --- | --- | --- | --- | --- |
-| [icenter-mcp-strategy-dimension-facebook-ad-list.md](./icenter-mcp-strategy-dimension-facebook-ad-list.md) | `icenter-mcp-strategy-dimension-facebook-ad-list` | Facebook广告策略维度数据 | POST | 查询广告策略配置（不含成效指标） |
-| [icenter-mcp-strategy-metrics-facebook-ad-list.md](./icenter-mcp-strategy-metrics-facebook-ad-list.md) | `icenter-mcp-strategy-metrics-facebook-ad-list` | Facebook广告策略成效数据 | POST | 查询策略维度 + 成效指标（最多近 21 天） |
+| [icenter-mcp-strategy-dimension-facebook-ad-list.md](./icenter-mcp-strategy-dimension-facebook-ad-list.md) | `icenter-mcp-strategy-dimension-facebook-ad-list` | Facebook广告策略维度数据 | POST | 查询 Facebook 广告策略配置（不含成效指标） |
+| [icenter-mcp-strategy-metrics-facebook-ad-list.md](./icenter-mcp-strategy-metrics-facebook-ad-list.md) | `icenter-mcp-strategy-metrics-facebook-ad-list` | Facebook广告策略成效数据 | POST | 查询 Facebook 策略维度 + 成效指标（最多近 21 天） |
+| [icenter-mcp-strategy-dimension-google-ad-list.md](./icenter-mcp-strategy-dimension-google-ad-list.md) | `icenter-mcp-strategy-dimension-google-ad-list` | Google广告策略维度数据 | POST | 查询 Google 广告策略配置（不含成效指标） |
+| [icenter-mcp-strategy-metrics-google-ad-list.md](./icenter-mcp-strategy-metrics-google-ad-list.md) | `icenter-mcp-strategy-metrics-google-ad-list` | Google广告策略成效数据 | POST | 查询 Google 策略维度 + 成效指标（最多近 21 天） |
+| [icenter-mcp-strategy-dimension-tiktok-ad-list.md](./icenter-mcp-strategy-dimension-tiktok-ad-list.md) | `icenter-mcp-strategy-dimension-tiktok-ad-list` | TikTok广告策略维度数据 | POST | 查询 TikTok 广告策略配置（不含成效指标） |
+| [icenter-mcp-strategy-metrics-tiktok-ad-list.md](./icenter-mcp-strategy-metrics-tiktok-ad-list.md) | `icenter-mcp-strategy-metrics-tiktok-ad-list` | TikTok广告策略成效数据 | POST | 查询 TikTok 策略维度 + 成效指标（最多近 21 天） |
 | [icenter-mcp-version-query.md](./icenter-mcp-version-query.md) | `icenter-mcp-version-query` | 查询git最新提交版本 | GET | 查询 iCenter 服务 git 最新提交版本 |
 
 对应命令：`/ic-api`，接口清单定义在 `src/constants/api-doc.ts`。

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

@@ -4,6 +4,8 @@
 
 对外开放的只读查询接口，共 **5** 个，均不涉及数据变更。
 
+> **网关地址**：`https://test-agent.beyondclick.com`（三环境同一地址，唯一来源 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`），不要直连 sino-opti-hive 服务地址。
+>
 > **路由前缀**：经网关调用时所有路径需带 `/sino-opti-hive`，例如 `/sino-opti-hive/biz-line-open/channels`。
 
 | # | name | 展示名 | 方法 | 路径（含前缀） |

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

@@ -4,6 +4,8 @@
 
 业务线主数据与周策略的增删改查，共 **17** 个接口。
 
+> **网关地址**：`https://test-agent.beyondclick.com`（三环境同一地址，唯一来源 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`），不要直连 sino-opti-hive 服务地址。
+>
 > **路由前缀**：经网关调用时所有路径需带 `/sino-opti-hive`，例如 `/sino-opti-hive/biz-line/list`。
 >
 > ⚠️ 标记为「写操作」的接口会变更线上数据，`/bc-api` 会按文档示例请求体直接发起调用，调用前请确认环境。

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

@@ -11,18 +11,22 @@
 ## 接口地址
 
 ```
-https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/dimension/facebook/ad/list
+https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/dimension/facebook/ad/list
 ```
 
-- **baseUrl**：`https://o-test-tc-sino-icenter.meetsocial.com`
+- **baseUrl**：`https://test-agent.beyondclick.com`（网关地址，三环境同一地址，唯一来源 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`）
 - **path**：`/sino-icenter/mcp/strategy/dimension/facebook/ad/list`
 
+> 一律经网关调用，不要直连 iCenter 服务地址。
+
 ## 说明
 
-查询 Facebook（Meta）渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（广告目标、成效目标、出价方式、调整出价、受众类型、兴趣词包、年龄、性别等），用于分析某批账户在某段时间内各广告的策略配置分布。
+查询 Facebook（Meta）渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（广告目标、成效目标、创意类型、出价方式、调整出价、受众类型、兴趣词包、年龄、性别等），用于分析某批账户在某段时间内各广告的策略配置分布。
 
 本接口**只返回策略维度**，不含消耗、点击等成效指标。需要成效数据请改用 [`icenter-mcp-strategy-metrics-facebook-ad-list`](./icenter-mcp-strategy-metrics-facebook-ad-list.md)。
 
+**国家维度特别说明**：`country_code` 必须单独传入，不能和任何其他维度同时传，否则会报错「country_code 不能和其他维度同时传入」。查国家维度时服务端会转走跨渠道广告数据接口，只返回按国家分组的数据。
+
 ## 请求头
 
 | Header | 值 |
@@ -66,15 +70,15 @@ https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/dimensio
 | bid_amount | 调整出价 |
 | 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 | 性别 |
+| country_code | 国家（必须单独传，不能和其他维度同时传） |
 
 ## 返回格式
 
@@ -100,6 +104,7 @@ https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/dimensio
     "ad_name",
     "objective",
     "optimization_goal",
+    "ad_format",
     "bid_strategy",
     "audience_type"
   ],
@@ -126,6 +131,7 @@ https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/dimensio
       "ad_name": "广告名称",
       "objective": "广告目标",
       "optimization_goal": "成效目标",
+      "ad_format": "创意类型",
       "bid_strategy": "出价方式",
       "audience_type": "受众类型"
     },
@@ -141,6 +147,8 @@ https://o-test-tc-sino-icenter.meetsocial.com/sino-icenter/mcp/strategy/dimensio
         "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": "最低成本",
         "audience_type": "INTEREST",

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

@@ -0,0 +1,170 @@
+# Google广告策略维度数据
+
+- **name**：`icenter-mcp-strategy-dimension-google-ad-list`
+- **displayName**：Google广告策略维度数据
+- **Tool ID**：`8d4fbfda08ea40d2b789ba9b334106af`
+- **请求方法**：`POST`
+- **集成类型**：REST
+- **超时**：20000 ms
+- **状态**：Online / Public / enabled
+
+## 接口地址
+
+```
+https://test-agent.beyondclick.com/sino-icenter/mcp/strategy/dimension/google/ad/list
+```
+
+- **baseUrl**：`https://test-agent.beyondclick.com`（网关地址，三环境同一地址，唯一来源 `src/constants/gateway.ts` 的 `GATEWAY_CONFIG`）
+- **path**：`/sino-icenter/mcp/strategy/dimension/google/ad/list`
+
+> 一律经网关调用，不要直连 iCenter 服务地址。
+
+## 说明
+
+查询 Google 渠道的广告策略配置数据。按指定广告账户和日期范围，返回广告的策略设置明细（成效目标、创意类型、出价方式、CPC/CPM/CPV 出价、广告系列类型、关键字等），用于分析某批账户在某段时间内各广告的策略配置分布。
+
+Google 渠道**不支持广告目标和兴趣词包维度**，出价字段使用 `cpc_bid_amount`、`cpm_bid_amount`、`cpv_bid_amount` 三个独立维度。
+
+本接口**只返回策略维度**，不含消耗、点击等成效指标。需要成效数据请改用 [`icenter-mcp-strategy-metrics-google-ad-list`](./icenter-mcp-strategy-metrics-google-ad-list.md)。
+
+**国家维度特别说明**：`country_code` 必须单独传入，不能和任何其他维度同时传，否则会报错「country_code 不能和其他维度同时传入」。查国家维度时服务端会转走跨渠道广告数据接口，只返回按国家分组的数据。
+
+## 请求头
+
+| 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_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 | 关键字 |
+| country_code | 国家（必须单独传，不能和其他维度同时传） |
+
+> Google 渠道**不含** `objective`（广告目标）、`targeting_interests`（兴趣词包）。
+
+## 返回格式
+
+- `result.data` 为数据行数组，每行的每个字段有两个 key：
+  - **原始值**：key 即请求的 code，做计算或比较时用这个
+  - **展示值**：key 加 `display_` 前缀，直接呈现给用户时用这个，空值为 `"-"`
+- `result.headerMap` 是字段 code 到中文列名的映射，用于给用户展示列名
+- `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",
+    "optimization_goal",
+    "ad_format",
+    "bid_strategy",
+    "advertising_channel_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": "广告名称",
+      "optimization_goal": "成效目标",
+      "ad_format": "创意类型",
+      "bid_strategy": "出价方式",
+      "advertising_channel_type": "广告系列类型"
+    },
+    "data": [
+      {
+        "account_id": "act_1036928420879324",
+        "display_account_id": "act_1036928420879324",
+        "ad_id": "120210000000000001",
+        "display_ad_id": "120210000000000001",
+        "ad_name": "示例广告",
+        "display_ad_name": "示例广告",
+        "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": "搜索"
+      }
+    ]
+  }
+}
+```
+
+## 失败响应示例
+
+```json
+{
+  "code": 1,
+  "message": "country_code 不能和其他维度同时传入",
+  "result": null
+}
+```