@tapdb/tapdb-data-analysis 0.1.30 → 0.1.34

package/README.md

@@ -65,6 +65,7 @@ python3 tapdb-data-analysis/scripts/tapdb_query.py -r sg list_projects
 - "用 TapDB 分析一下 XXXX 游戏近 30 天的留存趋势有没有异常"
 - "用 TapDB 对比 XXX 游戏 和  XXX 游戏 的收入数据"
 - "用 TapDB 查下 XXX 游戏鲸鱼用户排行"
+- "用 TapDB 查一下 XXX 游戏最近 30 天各媒体的买量成本和 ROI"
 
 AI 会自动调用 `tapdb_query.py` 脚本查询数据并生成分析报告。
 
@@ -81,4 +82,6 @@ AI 会自动调用 `tapdb_query.py` 脚本查询数据并生成分析报告。
 | 用户价值 | `user_value` | LTV (N日贡献) |
 | 鲸鱼用户 | `whale_user` | 高付费用户排行 |
 | 生命周期 | `life_cycle` | 付费转化率/金额/累计 |
+| 买量成本 | `cost` | 花费/展示/点击/获客/留存/ROI（支持 `--measurement-criteria device\|account` 切换统计口径） |
+| 广告投放 | `ad_data` | 广告投放数据（cost 无数据时的回退方案） |
 | 广告变现 | `ad_monet` | 广告收入数据 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tapdb/tapdb-data-analysis",
-  "version": "0.1.30",
+  "version": "0.1.34",
   "description": "TapDB 游戏数据分析 AI Agent Skill - 查询和分析 TapDB 中的游戏运营数据（活跃/留存/付费/来源/LTV 等）",
   "keywords": [
     "tapdb",

package/tapdb-data-analysis/SKILL.md

@@ -3,15 +3,16 @@ name: tapdb-data-analysis
 description: >
   TapDB 游戏数据分析技能。用于查询和分析 TapDB 中的游戏运营数据，包括活跃(DAU/WAU/MAU)、
   留存(1日留存-180日留存)、付费(收入/ARPU/ARPPU)、来源(新增/转化)、用户价值(LTV)、版本分布、
-  玩家行为、广告变现等指标。
-  当用户需要查询游戏数据、分析运营指标、对比项目表现、检测数据异常、生成数据报告时使用此技能。
+  玩家行为、广告变现、买量成本(CPI/CPA/ROI)等指标。
+  当用户需要查询游戏数据、分析运营指标、对比项目表现、检测数据异常、生成数据报告、
+  分析买量成本与 ROI 时使用此技能。
   触发关键词：TapDB、DAU、MAU、留存、付费、收入、ARPU、LTV、活跃、新增、来源、玩家行为、
-  版本分布、鲸鱼用户、广告变现、游戏数据分析。
+  版本分布、鲸鱼用户、广告变现、游戏数据分析、买量、投放、广告投放、买量成本、CPI、CPA、ROI、ROAS、花费。
 ---
 
 # TapDB 数据分析
 
-> Skill 版本：v0.1.30
+> Skill 版本：v0.1.33
 
 通过 Python 脚本调用 TapDB 运营数据查询接口，获取游戏指标数据并分析。
 
@@ -93,6 +94,16 @@ npm view @tapdb/tapdb-data-analysis version --registry https://registry.npmjs.or
 2. 候选日期展示给用户确认
 3. 按确认的周期分别查 active/income/retention/source，对比输出
 
+### F: 广告投放(买量)数据查询
+
+**触发**："买量数据/投放效果/CPI/CPA/广告花费/ROI/ROAS"
+
+#### 优先使用 `cost` 子命令（主路径）
+
+#### 当 `cost` 无数据或报错时，切换到 `ad_data` 子命令
+
+
+
 ## 脚本使用
 
 ### 基础命令
@@ -141,7 +152,13 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py life_cycle -p 2588 -s 2026-02-01 -e 2
 python3 <SKILL_DIR>/scripts/tapdb_query.py whale_user -p 2588 -s 2026-01-01 -e 2026-02-25
 python3 <SKILL_DIR>/scripts/tapdb_query.py version_distri -p 2588 -s 2026-02-01 -e 2026-02-25
 python3 <SKILL_DIR>/scripts/tapdb_query.py player_behavior -p 2588 -s 2026-02-01 -e 2026-02-25 -g time
+python3 <SKILL_DIR>/scripts/tapdb_query.py cost -p 2588 -s 2026-02-01 -e 2026-02-25 -g dt
+python3 <SKILL_DIR>/scripts/tapdb_query.py cost -p 2588 -s 2026-02-01 -e 2026-02-25 -g media
+python3 <SKILL_DIR>/scripts/tapdb_query.py cost -p 2588 -s 2026-02-01 -e 2026-02-25 -g dt --measurement-criteria device
 python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"start_time":"2026-02-01 00:00:00.000","end_time":"2026-02-25 23:59:59.999","subject":"device","quota":"dau","group":{"col_name":"time","col_alias":"date","is_time":true,"trunc_unit":"day"},"is_de_water":false,"filters":[]}'
+# 广告投放数据（独立参数，不复用通用参数）
+python3 <SKILL_DIR>/scripts/tapdb_query.py ad_data -p 2588 -s 2026-03-01 -e 2026-03-10 --quotas cost,display,activation,activationCost -g time
+python3 <SKILL_DIR>/scripts/tapdb_query.py ad_data -p 2588 -s 2026-03-01 -e 2026-03-10 --quotas cost,activation,day1LTV,day7LTV,day30LTV -g platform_id
 ```
 
 ## 子命令速查
@@ -157,6 +174,8 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 | `user_value` | LTV | 通用参数 | `activation_time` |
 | `whale_user` | 鲸鱼用户 | 通用参数 | 无分组 |
 | `life_cycle` | 生命周期 | `--quota payment_amount\|payment_cvs_rate\|payment_cvs\|acc_payment` | `activation_time` |
+| `cost` | 买量成本(全链路) **← 广告数据首选** | 通用参数；分组维度: dt/media/os/country/campaign_id/ad_id 等；`--measurement-criteria device\|account`（统计口径：设备/账户，默认 device） | `dt` |
+| `ad_data` | 广告投放(买量回退) **← cost 无数据时回退** | `--quotas cost,display,...`, `-g platform_id\|time\|...`（独立参数，不复用通用参数） | `time` |
 | `ad_monet` | 广告变现 | 通用参数 | 可能返回 404（未开通或路径不同） |
 
 ## 数据量控制策略（先小后大，必须遵守）
@@ -196,6 +215,12 @@ python3 <SKILL_DIR>/scripts/tapdb_query.py raw /op/active '{"project_id":2588,"s
 - `life_cycle` 在 `-g activation_os` 时仅支持 `--quota payment_cvs_rate`（其他 quota 会 500）
 - filters 格式: `{"col_name":"...", "data_type":"string|number|bool|date", "calculate_symbol":"include|un_include", "ftv":[...]}`
 - 各接口维度不同，不支持的维度返回 500。**先 `describe` 确认**
+- **`ad_data` 广告投放接口注意**：
+  - 走 `/mcp/ad/multiple_display_web`，非 `/mcp/op/*`，独立参数体系
+  - 响应为二维数组格式（非 dict），脚本内部自动转为 dict 列表
+  - 时间粒度固定为 day，不支持 week/month
+  - cost/display/click 等花费类指标仅在 platform_id/advertisement_id/tag_id 等广告维度分组时有意义
+  - 需项目已开通 ad_plus 功能，未开通会返回错误
 
 ## 分析与报告
 

package/tapdb-data-analysis/references/analysis_guide.md

@@ -14,10 +14,11 @@
 
 ### 数据失败处理
 
-1. **部分成功**：基于已有数据输出分析，注明缺失部分
-2. **全部失败**：如实告知原因，不编造分析
+1. **部分成功必须继续输出**：只要任一查询成功返回数据，就必须基于已有数据继续输出分析；在输出开头披露缺失（如 `⚠️ XX 数据未获取到（原因：…），以下分析基于已获取数据`）。**绝对不允许**在有成功数据的情况下声称“没有数据/没查到”。
+2. **全部失败才停止**：全部查询失败时，如实告知失败原因，格式：`查询失败：[具体错误原因]，请稍后重试或联系管理员`。**禁止**编造分析或让用户“自行准备数据”。
 3. **重试收敛**：同一查询连续失败 2 次即停止，标记为"数据未获取到"，继续用已有数据完成任务
 4. ❌ 禁止通过拆分时间范围来"绕过"失败的查询
+5. 更细的输出纪律见 `references/output_rules.md` 的「失败/输出纪律（最高优先级）」
 
 ---
 

package/tapdb-data-analysis/references/metrics_glossary.md

@@ -101,6 +101,54 @@ API 直接返回 DRx_rate/WRx_rate/MRx_rate（小数形式，如 0.7656=76.56%
 - ❌ 错误：周总收入(12,230,904) ÷ 周去重活跃(195,663) = 62.46 → 这不是ARPU
 - ✅ 正确：日均收入(1,747,272) ÷ 日均DAU(155,768) = 11.22 → 这才是日均ARPU
 
+### 投放 ROI / ROAS（cost 子命令，重要！）
+
+cost 接口返回的金额字段有两套口径，计算 ROI 时必须区分：
+
+| 指标 | 公式 | 含义 | 使用场景 |
+|------|------|------|----------|
+| **ROI** | `dayX_paid_amount / real_cost` | 付费金额 ÷ 实际消耗 | **默认使用**，投放效果评估 |
+| **真实 ROI** | `dayX_real_income / real_cost` | 扣除渠道分成后的真实收入 ÷ 实际消耗 | 仅在用户明确要求"真实ROI"时使用 |
+
+**字段说明**：
+- `cost`：消耗（含平台服务费等）
+- `real_cost`：实际消耗（扣除返点/折扣后的真实花费），**ROI 分母统一用 real_cost**
+- `dayX_paid_amount`：新增设备上，注册后 X 天内累计付费总额（未扣渠道分成）
+- `dayX_real_income`：新增设备上，注册后 X 天内累计真实收入（已扣渠道分成）
+
+**硬规则**：
+- ❌ 禁止用 `cost` 作为任何指标的分母或成本基准（应统一使用 `real_cost`）
+- ❌ 禁止用 `dayX_real_income` 计算默认 ROI（那是"真实 ROI"）
+- ❌ 禁止在用户未明确要求"真实收入"时使用 `dayX_real_income` 作为收入展示值
+- ✅ 所有涉及成本计算的指标（CPA、ROI、ROAS 等）统一使用 `real_cost` 作为成本值
+- ✅ 展示"消耗/成本"时优先展示 `real_cost`（真实成本），而非 `cost`
+- ✅ **展示"收入/付费金额"时默认使用 `dayX_paid_amount`**，仅在用户明确要求"真实收入"时才使用 `dayX_real_income`
+- ✅ 默认 ROI = `dayX_paid_amount / real_cost`
+- ✅ 真实 ROI = `dayX_real_income / real_cost`（需用户明确要求）
+
+### 成本数据统计口径（measurement_criteria）
+
+cost 接口支持两种统计口径，通过请求体中的 `measurement_criteria` 字段控制：
+
+| 值 | 含义 | 对应表 |
+|---|------|--------|
+| `"account"` | 账户口径 | `dwd_autogrowth_game_agent_retention_charge_fully_hr_v3` |
+| 不传（默认） | 设备口径 | `dwd_autogrowth_game_agent_retention_charge_fully_hr_v2_device` |
+
+**项目路由规则（用户未明确指定 account/device 口径时）**：
+- ✅ **香肠派对（705）、火炬之光（2588）**：默认传 `measurement_criteria=account`（走 v3 账户口径表）
+- ✅ 其余项目：不传此字段，走默认 v2 设备口径表
+- ⚠️ 若用户明确要求使用 device 或 account 口径，以用户指定为准
+
+**注意**：`cmd_cost` 子命令当前可能无法正确生效 `measurement_criteria`，需使用 `raw /op/omp-cost` 并在 JSON body 中显式传入 `"measurement_criteria":"account"` 以确保查询到 v3 表数据。
+
+### 成本/投放数据分析准则（硬规则，必须遵守）
+
+1. **所有数值必须来源于查询结果**：CPA、CTR、ROI、留存率等衍生指标必须基于接口返回的原始字段计算，禁止凭经验估算或编造任何数值
+2. **过滤自然量**：分析投放效果时，必须排除 `media` 为"自然量"的数据行（自然量 cost/real_cost 为 0，纳入会严重扭曲 CPA、ROI 等指标）。仅在用户明确要求"包含自然量"或查看"全量数据"时才保留
+3. **零消耗渠道不计算 ROI/CPA**：当某渠道 `real_cost = 0` 时，ROI 和 CPA 无意义，应标注"—"或"无投放"，不能输出 0% 或 Inf
+4. **汇总指标以 API 返回为准**：若接口返回了汇总行（分组字段为 `null`），直接使用该行数据，不要在本地重复汇总（可能因截断导致不一致）
+
 ### LTV (Life Time Value)
 
 N日内人均累计付费金额（LTV1/3/7/14/30/60/90）。通过 `user_value` 子命令查询。

package/tapdb-data-analysis/references/output_rules.md

@@ -4,6 +4,13 @@
 
 ---
 
+## 0) 失败/输出纪律（最高优先级）
+
+- **部分成功必须继续输出**：只要任一工具成功返回了数据，就必须基于已获取数据继续完成输出；在开头用一句话披露缺失，例如：`⚠️ XX 数据未获取到（原因：…），以下基于已获取数据`。**绝对不允许**在有成功数据的情况下声称“没有数据/没查到”，也不得要求用户补充数据才能继续。
+- **全部失败才允许停止**：全部工具失败时，如实告知失败原因，格式：`查询失败：[具体错误原因]，请稍后重试或联系管理员`。**禁止**编造数据、禁止输出“通用分析框架”、禁止让用户“自行准备数据再来”。
+- **禁止输出中间分析过程/过渡话术**：工具调用完成后，直接输出最终报告。❌ 禁止输出“让我分析一下”“数据已齐全”“现在生成报告”等过渡性文字。
+- **禁止“先错后改”的更正表**：发现计算/汇总有误时，不输出“修正汇总/更正/补充”表；先在内部把派生指标（如 ARPU/ARPPU）算对，最终只输出一张正确的表。
+
 ## 1) 报告结构（结论优先）
 
 - 先给 **3~7 条关键结论**（每条尽量带 1 个关键数字或时间点），再给数据表，最后给建议/下一步

package/tapdb-data-analysis/scripts/tapdb_query.py

@@ -182,6 +182,38 @@ def _rebuild(resp, path, rows, info):
     return result
 
 
+def _parse_ad_response(resp):
+    """Parse ad API response into (rows_as_dicts, summary_row_or_None).
+
+    The ad API returns a flat list:
+      [ total_count, [header1, header2, ...], [row1_val, ...], ..., [total_val, ...] ]
+    or wrapped in {"data": [...]}.
+    The first element is a total_count integer, followed by headers, data rows,
+    and a summary/total row at the end.
+    """
+    data = resp
+    if isinstance(resp, dict):
+        if resp.get("error"):
+            return None, None
+        data = resp.get("data", resp)
+    if not isinstance(data, list) or len(data) < 2:
+        return None, None
+    # Skip leading scalar (total_count) if present
+    start = 0
+    if not isinstance(data[0], list):
+        start = 1
+    if start >= len(data):
+        return None, None
+    headers = [str(h) for h in data[start]]
+    rows = [dict(zip(headers, r)) for r in data[start + 1:]]
+    if not rows:
+        return [], None
+    # Last row is the summary/total row
+    summary = rows[-1]
+    rows = rows[:-1]
+    return rows, summary
+
+
 def truncate_response(resp, cmd_type=None, group_alias=None):
     """Truncate API response to save context window tokens."""
     if not resp or (isinstance(resp, dict) and resp.get("error")):
@@ -221,10 +253,47 @@ COL_ALIAS_MAP = {
     "activation_app_version": "activation_app_version",
     "first_server": "first_server",
     "current_server": "current_server",
+    # cost 维度
+    "dt": "date",
+    "media": "media",
+    "media_source": "msrc",
+    "campaign_id": "camp",
+    "ad_id": "ad",
+    "creative_id": "crtv",
+    "account_id": "acct",
+    "material_id": "mtrl",
+    "medium_id": "mdm",
+    "ad_platform_id": "adplt",
+    "opt_obj": "optobj",
+    "scene": "scene",
+    "scene_final": "scnf",
+    "city": "city",
+    "country": "country",
+    "country_code": "cycd",
+    "province": "province",
+    "os": "os",
+    "channel": "channel",
+    "app_id": "appid",
+    "tap_app_id": "tapid",
+    "google_opt_obj": "gopt",
+    "china_opt_obj": "copt",
+    "project_name": "proj",
 }
 
 COUNTRY_GROUP_DIMS = {"activation_country", "activation_province"}
 
+AD_COL_ALIAS_MAP = {
+    "time": "date_",
+    "platform_id": "pf",
+    "advertisement_id": "ad",
+    "tag_id": "tag",
+    "first_ad_sub_channel1": "subc",
+    "first_ad_sub_channel2": "subc",
+    "first_ad_sub_channel3": "subc",
+    "first_ad_sub_channel4": "subc",
+    "first_ad_sub_channel5": "subc",
+}
+
 
 # ── 各接口能力描述（基于源码 + 实测验证） ────────────────────
 #
@@ -475,9 +544,94 @@ ENDPOINT_CAPS = {
         },
         "unsupported_note": "分组仅支持 time/activation_time/activation_os；过滤不支持 activation_app_version/first_server/current_server/utmsrc/login_type/payment_source",
     },
+    "cost": {
+        "description": "买量成本数据: 花费/展示/点击/获客/留存/付费/ROI 全链路",
+        "time_field": "dt",
+        "returned_metrics": [
+            "cost", "real_cost", "show_cnt", "click_cnt", "reserve_cnt",
+            "new_device", "new_user", "new_device_safe", "new_user_safe",
+            "reattr_new_device", "reattr_new_user", "paid_user_uv",
+            "retention_2d", "retention_3d", "retention_7d", "retention_14d",
+            "retention_30d", "retention_60d", "retention_90d", "retention_180d",
+            "day1_paid_amount", "day2_paid_amount", "day3_paid_amount",
+            "day7_paid_amount", "day14_paid_amount", "day30_paid_amount",
+            "day60_paid_amount", "day90_paid_amount", "day180_paid_amount",
+            "day1_real_income", "day2_real_income", "day3_real_income",
+            "day7_real_income", "day14_real_income", "day30_real_income",
+            "day60_real_income", "day90_real_income", "day180_real_income",
+        ],
+        "groups": [
+            "dt", "media", "media_source", "os", "country", "country_code", "province", "city",
+            "channel", "campaign_id", "ad_id", "creative_id",
+            "account_id", "material_id", "medium_id", "ad_platform_id",
+            "app_id", "tap_app_id", "opt_obj", "scene", "scene_final",
+            "google_opt_obj", "china_opt_obj", "project_name",
+        ],
+        "filters": [
+            "media", "media_source", "os", "country", "country_code", "province", "city",
+            "channel", "campaign_id", "ad_id", "creative_id",
+            "account_id", "material_id", "medium_id", "ad_platform_id",
+            "app_id", "tap_app_id", "opt_obj", "scene", "scene_final",
+            "google_opt_obj", "china_opt_obj", "project_name",
+            "material_type", "material_mode",
+            "name", "tags_str", "jump_url", "account_alias",
+        ],
+        "unsupported_note": "不支持现有运营维度(activation_channel等)，使用广告维度(media/campaign_id等)",
+    },
     "ad_monet": {
         "description": "广告变现数据（MCP 代理路径 /mcp/op/ad_monet 返回 404，可能未开通或路径不同）",
     },
+    "ad_data": {
+        "description": "广告投放(买量)数据: 花费/展示/点击/激活/留存/LTV等（仅用户明确要求广告/买量数据时使用）",
+        "quotas": {
+            "cost_display": ["cost", "display"],
+            "click": ["click", "uClick", "clickRate", "clickCost"],
+            "activation": [
+                "activation", "activeRate", "activationCost",
+                "newUser", "convertRate", "convertDevice",
+                "payUserNew", "payRateNew", "payAmountNew",
+            ],
+            "device_retention": [
+                "day1Retain", "day1RetainRate",
+                "day6Retain", "day6RetainRate",
+                "day13Retain", "day13RetainRate",
+                "day29Retain", "day29RetainRate",
+            ],
+            "payment": ["income", "payUser", "payRate", "payTimes"],
+            "ltv": [
+                "day1LTV", "day3LTV", "day7LTV", "day14LTV",
+                "day30LTV", "day60LTV", "day90LTV", "day180LTV", "day360LTV",
+            ],
+        },
+        "groups": [
+            "time", "platform_id", "advertisement_id", "tag_id",
+            "first_ad_sub_channel1", "first_ad_sub_channel2",
+            "first_ad_sub_channel3", "first_ad_sub_channel4",
+            "first_ad_sub_channel5",
+        ],
+        "filters": [
+            "activation_os", "activation_country", "activation_continent",
+            "activation_province", "activation_network", "activation_provider",
+            "activation_device_model", "activation_app_version",
+            "first_ad_platform_id", "first_ad_advertiser_id",
+            "first_campaign_id", "first_adgroup_id", "first_creative_id",
+            "first_ad_conversion_link_id", "activation_channel",
+        ],
+        "extra_params": [
+            "ad_increment (bool, 默认true: 仅广告增量)",
+            "tz_offset (int, 默认8: 时区偏移)",
+            "sort_field / sort_order (排序字段和顺序)",
+            "charge_subject (user|device, 默认user)",
+            "exchange_to_currency (str, 如 USD/CNY/JPY，默认CNY)",
+        ],
+        "notes": [
+            "走 /mcp/ad/multiple_display_web 接口，非 /mcp/op/*",
+            "时间粒度固定为 day，不支持 week/month",
+            "cost/display/click 等花费类指标仅在 platform_id/advertisement_id/tag_id 分组时有意义",
+            "响应格式为二维数组（非 dict），脚本内部会转为 dict 列表",
+            "需项目已开通 ad_plus 功能",
+        ],
+    },
 }
 
 
@@ -500,8 +654,9 @@ def cmd_describe(args):
         if "subjects" in cap:
             info["subjects"] = cap["subjects"]
         if "groups" in cap:
+            alias_map = AD_COL_ALIAS_MAP if name == "ad_data" else COL_ALIAS_MAP
             info["supported_groups"] = [
-                {"col_name": g, "col_alias": COL_ALIAS_MAP.get(g, g),
+                {"col_name": g, "col_alias": alias_map.get(g, g),
                  **({"note": cap.get("group_notes", {}).get(g)} if g in cap.get("group_notes", {}) else {})}
                 for g in cap["groups"]
             ]
@@ -519,6 +674,8 @@ def cmd_describe(args):
             info["returned_metrics"] = cap["returned_metrics"]
         if "unsupported_note" in cap:
             info["unsupported_note"] = cap["unsupported_note"]
+        if "notes" in cap:
+            info["notes"] = cap["notes"]
         result[name] = info
 
     output(result)
@@ -536,6 +693,19 @@ def build_group(group_by, group_unit):
     }
 
 
+def build_ad_group(group_by):
+    """Build group dict for the ad API (fixed day granularity)."""
+    if not group_by:
+        return None
+    is_time = group_by == "time"
+    return {
+        "col_name": group_by,
+        "col_alias": AD_COL_ALIAS_MAP.get(group_by, group_by),
+        "is_time": is_time,
+        "trunc_unit": "day",
+    }
+
+
 def build_base_body(args):
     body = {"project_id": int(args.project_id)}
     if hasattr(args, "start") and args.start:
@@ -651,6 +821,67 @@ def cmd_life_cycle(args):
     do_query(args, "life_cycle", {"quota": args.quota})
 
 
+def cmd_cost(args):
+    if not args.group_by or args.group_by == "time":
+        args.group_by = "dt"
+    extra = {}
+    mc = getattr(args, "measurement_criteria", None)
+    if mc:
+        extra["measurement_criteria"] = mc
+    do_query(args, "omp-cost", extra=extra or None, cmd_type="cost")
+
+
+def cmd_ad_data(args):
+    """查询广告投放(买量)数据 — 走 /mcp/ad/multiple_display_web。"""
+    key, base_url = get_config(args.region)
+    group_by = args.group_by or "time"
+    quotas = [q.strip() for q in args.quotas.split(",") if q.strip()]
+    body = {
+        "project_id": int(args.project_id),
+        "start_time": f"{args.start} 00:00:00",
+        "end_time": f"{args.end} 23:59:59",
+        "group": build_ad_group(group_by),
+        "quotas": quotas,
+        "ad_increment": args.ad_increment.lower() != "false",
+        "tz_offset": args.tz_offset,
+        "charge_subject": args.charge_subject,
+        "filters": json.loads(args.filters) if args.filters else [],
+        "use_cache": True,
+        "page": 1,
+        "page_size": 5000,
+    }
+    if args.sort_field:
+        body["sort"] = {"field": args.sort_field, "order": args.sort_order}
+    exchange_to = getattr(args, "exchange_to_currency", None)
+    if exchange_to and exchange_to.lower() != "none":
+        body["exchange_to_currency"] = exchange_to.upper()
+
+    url = f"{base_url}/mcp/ad/multiple_display_web"
+    resp = http_request("POST", url, {"MCP-KEY": key}, body)
+
+    if isinstance(resp, dict) and resp.get("error"):
+        output(resp)
+        return
+
+    rows, summary = _parse_ad_response(resp)
+    if rows is None:
+        output(resp)
+        return
+
+    group_alias = AD_COL_ALIAS_MAP.get(group_by, group_by)
+    if not getattr(args, "no_truncate", False):
+        rows, trunc_info = _slim_rows(rows, "ad_data", group_alias=group_alias)
+    else:
+        trunc_info = None
+
+    result = {"data": rows}
+    if summary is not None:
+        result["summary"] = summary
+    if trunc_info:
+        result["_truncation"] = trunc_info
+    output(result)
+
+
 def cmd_ad_monet(args):
     do_query(args, "ad_monet")
 
@@ -752,6 +983,34 @@ def main():
                     choices=["payment_cvs_rate", "payment_cvs", "payment_amount", "acc_payment"],
                     help="生命周期指标 (默认 payment_amount)")
 
+    # cost
+    p = sub.add_parser("cost", help="买量成本数据: 花费/展示/点击/获客/留存/ROI")
+    add_common_args(p)
+    p.add_argument("--measurement-criteria", default="device", choices=["device", "account"],
+                    help="统计口径: device(按设备,默认) | account(按账户)")
+
+    # ad_data (广告投放/买量)
+    p = sub.add_parser("ad_data", help="广告投放(买量)数据: 花费/展示/点击/激活/留存/LTV")
+    p.add_argument("-p", "--project-id", required=True, help="项目ID")
+    p.add_argument("-s", "--start", required=True, help="开始日期 YYYY-MM-DD")
+    p.add_argument("-e", "--end", required=True, help="结束日期 YYYY-MM-DD")
+    p.add_argument("-g", "--group-by", default="time",
+                    help="分组: time/platform_id/advertisement_id/tag_id/first_ad_sub_channel1-5 (默认 time)")
+    p.add_argument("--quotas", required=True,
+                    help="逗号分隔指标列表 (如 cost,display,activation,activationCost)")
+    p.add_argument("--ad-increment", default="true",
+                    help="仅广告增量 (默认 true; false 包含自然量)")
+    p.add_argument("--tz-offset", type=int, default=8,
+                    help="时区偏移 (默认 8, 即 UTC+8)")
+    p.add_argument("--sort-field", help="排序字段 (如 cost, activation)")
+    p.add_argument("--sort-order", default="desc", choices=["asc", "desc"],
+                    help="排序方向 (默认 desc)")
+    p.add_argument("--filters", help='过滤条件JSON')
+    p.add_argument("--charge-subject", default="user", choices=["user", "device"],
+                    help="付费主体 (默认 user)")
+    p.add_argument("--exchange-to-currency", default="CNY",
+                    help="金额目标货币 (如 USD/CNY/JPY，默认CNY)")
+
     # ad_monet
     p = sub.add_parser("ad_monet", help="广告变现数据")
     add_common_args(p)
@@ -779,6 +1038,8 @@ def main():
         "user_value": cmd_user_value,
         "whale_user": cmd_whale_user,
         "life_cycle": cmd_life_cycle,
+        "cost": cmd_cost,
+        "ad_data": cmd_ad_data,
         "ad_monet": cmd_ad_monet,
         "raw": cmd_raw,
     }