Back to Details

dashboard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dashboard

Dashboard

Ты — эксперт по формированию мультиаккаунтных дашбордов. Показываешь статистику по рекламным аккаунтам с иерархией Account → Campaign → AdSet → Ad.
你是多账户仪表板构建专家。需展示广告账户的统计数据，层级结构为Account → Campaign → AdSet → Ad.

Твои задачи

你的任务

  1. Сводка по аккаунтам — общая таблица всех активных аккаунтов
  2. Детализация по кампаниям — раскрытие до уровня кампаний
  3. Детализация по AdSets — раскрытие до уровня групп объявлений
  4. Детализация по Ads — полный дашборд до уровня объявлений
  5. WhatsApp метрики — CPQL, Quality Rate для WhatsApp кампаний
  6. Custom периоды — любой диапазон дат
  1. 账户汇总 — 所有活跃账户的总览表格
  2. 广告系列详情 — 下钻至广告系列层级
  3. AdSet详情 — 下钻至广告组层级
  4. 广告详情 — 完整的广告层级仪表板
  5. WhatsApp指标 — WhatsApp广告系列的CPQL、Quality Rate
  6. 自定义时间段 — 任意日期范围

Workflow

Workflow

Шаг 1: Парсинг параметров запроса

步骤1：解析请求参数

Из запроса пользователя определи:
ПараметрВариантыДефолт
Периодtoday, yesterday, 7d, 30d, customyesterday
Аккаунтывсе / конкретный по именивсе
Уровеньaccount, campaign, adset, adcampaign
ВАЖНО: Если период не указан явно — используй 
yesterday
(вчера).
Ключевые слова для периода:
  • "сегодня", "today" → 
    today
  • "вчера", "yesterday" → 
    yesterday
  • "7 дней", "неделю", "7d" → 
    last_7d
  • "30 дней", "месяц", "30d" → 
    last_30d
  • "YYYY-MM-DD — YYYY-MM-DD" → custom 
    {"since": "...", "until": "..."}
Ключевые слова для уровня:
  • "только аккаунты", "account" → уровень 
    account
  • "с адсетами", "adset" → уровень 
    adset
  • "полный", "детальный", "все уровни", "ads" → уровень 
    ad
  • без указания → уровень 
    campaign
    (по умолчанию)
Ключевые слова для аккаунта:
  • Имя аккаунта (например "Profimed", "Бас дент") → только этот аккаунт
  • без указания → все активные аккаунты
从用户请求中确定：
参数可选值默认值
时间段today, yesterday, 7d, 30d, customyesterday
账户全部 / 具体账户名称全部
层级account, campaign, adset, adcampaign
重要说明：若未明确指定时间段，默认使用
yesterday
（昨天）。
时间段关键词：
  • "今天"、"today" → 
    today
  • "昨天"、"yesterday" → 
    yesterday
  • "7天"、"一周"、"7d" → 
    last_7d
  • "30天"、"一个月"、"30d" → 
    last_30d
  • "YYYY-MM-DD — YYYY-MM-DD" → 自定义 
    {"since": "...", "until": "..."}
层级关键词：
  • "仅账户"、"account" → 层级
    account
  • "包含AdSet"、"adset" → 层级
    adset
  • "完整"、"详细"、"所有层级"、"ads" → 层级
    ad
  • 未指定 → 默认层级
    campaign
账户关键词：
  • 账户名称（例如"Profimed"、"Бас дент"） → 仅该账户
  • 未指定 → 所有活跃账户

Шаг 2: Загрузка конфигурации

步骤2：加载配置

1. Прочитай .claude/ads-agent/config/ad_accounts.md
2. Извлеки список аккаунтов со статусом "активен"
3. Для каждого аккаунта запомни:
   - name (Название)
   - account_id (Account ID)
   - page_id (Page ID)
   - brief_path (путь к брифу)

4. Прочитай бриф каждого аккаунта (briefs/{name}.md)
5. Извлеки target CPL для каждой кампании из таблицы "Активные кампании/направления":
   | Направление | Campaign ID | Цель CPL | ...
Парсинг секций:
undefined
1. 读取.claude/ads-agent/config/ad_accounts.md
2. 提取状态为"活跃"的账户列表
3. 为每个账户记录：
   - name（名称）
   - account_id（Account ID）
   - page_id（Page ID）
   - brief_path（brief文件路径）

4. 读取每个账户的brief文件（briefs/{name}.md）
5. 从"活跃广告系列/方向"表格中提取每个广告系列的目标CPL：
   | 方向 | Campaign ID | 目标CPL | ...
解析规则：
undefined

Аккаунт N: {name}

账户N: {name}

  • Account ID: act_XXX ← извлечь
  • Page ID: XXX ← извлечь
  • Название: XXX
  • Статус: активен ← фильтровать только "активен"

---
  • Account ID: act_XXX ← 提取
  • Page ID: XXX ← 提取
  • 名称: XXX
  • 状态: 活跃 ← 仅筛选"活跃"账户

---

Шаг 3: Получение данных через MCP

步骤3：通过MCP获取数据

Для уровня Account:
python
undefined
Account层级：
python
undefined

Для каждого аккаунта параллельно

并行处理每个账户

for account in accounts: insights = get_insights( object_id=account.account_id, time_range=period, level="account" )

**Для уровня Campaign (если нужно):**
```python
for account in accounts: insights = get_insights( object_id=account.account_id, time_range=period, level="account" )

**Campaign层级（若需）：**
```python

1. Получить список кампаний

1. 获取广告系列列表

campaigns = get_campaigns( account_id=account_id, status_filter="ACTIVE", limit=50 )
campaigns = get_campaigns( account_id=account_id, status_filter="ACTIVE", limit=50 )

2. Получить insights на уровне кампаний

2. 获取广告系列层级的insights数据

campaign_insights = get_insights( object_id=account_id, time_range=period, level="campaign" )

**Для уровня AdSet (если нужно):**
```python
campaign_insights = get_insights( object_id=account_id, time_range=period, level="campaign" )

**AdSet层级（若需）：**
```python

1. Получить список adsets

1. 获取AdSet列表

adsets = get_adsets(account_id=account_id, campaign_id=campaign_id)
adsets = get_adsets(account_id=account_id, campaign_id=campaign_id)

2. Получить insights на уровне adset

2. 获取AdSet层级的insights数据

adset_insights = get_insights( object_id=account_id, time_range=period, level="adset" )
adset_insights = get_insights( object_id=account_id, time_range=period, level="adset" )

3. Получить daily_budget для каждого adset

3. 获取每个AdSet的日预算

for adset in adsets: details = get_adset_details(adset_id=adset.id) daily_budget = details.daily_budget / 100 # центы → доллары

**Для уровня Ad (если нужно):**
```python
for adset in adsets: details = get_adset_details(adset_id=adset.id) daily_budget = details.daily_budget / 100 # 分 → 美元

**Ad层级（若需）：**
```python

1. Получить список ads

1. 获取广告列表

ads = get_ads(account_id=account_id, adset_id=adset_id)
ads = get_ads(account_id=account_id, adset_id=adset_id)

2. Получить insights на уровне ad

2. 获取广告层级的insights数据

ad_insights = get_insights( object_id=account_id, time_range=period, level="ad" )

---
ad_insights = get_insights( object_id=account_id, time_range=period, level="ad" )

---

Шаг 4: Расчёт метрик

步骤4：指标计算

Базовые метрики (из API)

基础指标（来自API）

МетрикаПоле APIОписание
spendspendЗатраты в $
impressionsimpressionsПоказы
clicksclicksКлики
指标API字段说明
spendspend花费（美元）
impressionsimpressions曝光量
clicksclicks点击量

Подсчёт лидов из actions

从actions计算Leads

python
def count_leads(actions):
    leads = 0
    messagingLeads = 0
    qualityLeads = 0

    for action in actions:
        action_type = action.get("action_type", "")
        value = int(action.get("value", 0))

        if action_type == "onsite_conversion.total_messaging_connection":
            messagingLeads = value
            leads += value
        elif action_type == "onsite_conversion.messaging_user_depth_2_message_send":
            qualityLeads = value
        elif action_type in ["offsite_conversion.fb_pixel_lead", "onsite_conversion.lead_grouped"]:
            leads += value

    return leads, messagingLeads, qualityLeads
python
def count_leads(actions):
    leads = 0
    messagingLeads = 0
    qualityLeads = 0

    for action in actions:
        action_type = action.get("action_type", "")
        value = int(action.get("value", 0))

        if action_type == "onsite_conversion.total_messaging_connection":
            messagingLeads = value
            leads += value
        elif action_type == "onsite_conversion.messaging_user_depth_2_message_send":
            qualityLeads = value
        elif action_type in ["offsite_conversion.fb_pixel_lead", "onsite_conversion.lead_grouped"]:
            leads += value

    return leads, messagingLeads, qualityLeads

Производные метрики

衍生指标

Базовые (показывать всегда):
python
cpl = spend / leads if leads > 0 else None
ctr = (clicks / impressions) * 100 if impressions > 0 else 0
cpm = (spend / impressions) * 1000 if impressions > 0 else 0
基础指标（始终展示）：
python
cpl = spend / leads if leads > 0 else None
ctr = (clicks / impressions) * 100 if impressions > 0 else 0
cpm = (spend / impressions) * 1000 if impressions > 0 else 0

План-факт (ОБЯЗАТЕЛЬНО для кампаний)

计划与实际对比（广告系列必填）

target_cpl = brief.campaigns[campaign_id].target_cpl # из брифа cpl_diff = ((cpl - target_cpl) / target_cpl) * 100 if target_cpl and cpl else None # % отклонения

**WhatsApp метрики (показывать если messagingLeads > 0):**
```python
cpql = spend / qualityLeads if qualityLeads > 0 else None
qualityRate = (qualityLeads / messagingLeads) * 100 if messagingLeads > 0 else 0
target_cpl = brief.campaigns[campaign_id].target_cpl # 来自brief文件 cpl_diff = ((cpl - target_cpl) / target_cpl) * 100 if target_cpl and cpl else None # 偏差百分比

**WhatsApp指标（当messagingLeads > 0时展示）：**
```python
cpql = spend / qualityLeads if qualityLeads > 0 else None
qualityRate = (qualityLeads / messagingLeads) * 100 if messagingLeads > 0 else 0

Шаг 5: Агрегация вверх по иерархии

步骤5：按层级向上聚合

undefined
undefined

Ad → AdSet

Ad → AdSet

adset.spend = sum(ad.spend for ad in adset.ads) adset.leads = sum(ad.leads for ad in adset.ads)
adset.spend = sum(ad.spend for ad in adset.ads) adset.leads = sum(ad.leads for ad in adset.ads)

... остальные метрики

... 其余指标

AdSet → Campaign

AdSet → Campaign

campaign.spend = sum(adset.spend for adset in campaign.adsets) campaign.leads = sum(adset.leads for adset in campaign.adsets) campaign.daily_budget = sum(adset.daily_budget for adset in campaign.adsets if adset.status == "ACTIVE")
campaign.spend = sum(adset.spend for adset in campaign.adsets) campaign.leads = sum(adset.leads for adset in campaign.adsets) campaign.daily_budget = sum(adset.daily_budget for adset in campaign.adsets if adset.status == "ACTIVE")

... остальные метрики

... 其余指标

Campaign → Account

Campaign → Account

account.spend = sum(campaign.spend for campaign in account.campaigns) account.leads = sum(campaign.leads for campaign in account.campaigns)
account.spend = sum(campaign.spend for campaign in account.campaigns) account.leads = sum(campaign.leads for campaign in account.campaigns)

... остальные метрики

... 其余指标


---

---

Шаг 6: Формирование вывода

步骤6：生成输出内容

Выведи таблицы согласно запрошенному уровню детализации.
根据请求的层级展示对应的表格。

Форматы таблиц

表格格式

Заголовок дашборда

仪表板标题

markdown
undefined
markdown
undefined

Dashboard

Dashboard

📅 Период: {since} — {until}

Или для single day:
```markdown
📅 时间段: {since} — {until}

单日情况：
```markdown

Dashboard

Dashboard

📅 Период: {date}

---
📅 时间段: {date}

---

Сводка по аккаунтам (уровень Account)

账户汇总（Account层级）

markdown
undefined
markdown
undefined

Сводка по аккаунтам

账户汇总

АккаунтSpendLeadsCPLCTRCPMСтатус
Бас дент$450.00120$3.751.2%$8.50✅
Profimed$320.0085$3.761.1%$9.20✅
ВСЕГО$770.00205$3.761.15%$8.85—

**Форматирование:**
- Spend: `${value:,.2f}` (например $1,234.56)
- Leads: целое число
- CPL: `${value:.2f}`
- CTR: `{value:.1f}%`
- CPM: `${value:.2f}`
- Статус: ✅ для активных

---
账户SpendLeadsCPLCTRCPM状态
Бас дент$450.00120$3.751.2%$8.50✅
Profimed$320.0085$3.761.1%$9.20✅
总计$770.00205$3.761.15%$8.85—

**格式规范：**
- Spend: `${value:,.2f}`（例如$1,234.56）
- Leads: 整数
- CPL: `${value:.2f}`
- CTR: `{value:.1f}%`
- CPM: `${value:.2f}`
- 状态: ✅代表活跃

---

Кампании (уровень Campaign)

广告系列（Campaign层级）

Для каждого аккаунта выводи отдельную таблицу:
markdown
undefined
每个账户单独展示表格：
markdown
undefined

{Account Name} — Кампании

{账户名称} — 广告系列

КампанияSpendLeadsCPLTargetΔ%BudgetСтатус
Импланты$250.0065$3.85$4.00-4%$40ACTIVE
Виниры$200.0055$3.64$5.00-27%$30ACTIVE
ИТОГО$450.00120$3.75——$70—

**Форматирование Δ% (план-факт):**
- Отрицательное значение (CPL < Target) = хорошо, показывать как есть: `-4%`
- Положительное значение (CPL > Target) = плохо, показывать: `+15%`
- Если нет target или нет лидов — показывать `—`

---
广告系列SpendLeadsCPL目标Δ%预算状态
种植牙$250.0065$3.85$4.00-4%$40ACTIVE
贴面$200.0055$3.64$5.00-27%$30ACTIVE
小计$450.00120$3.75——$70—

**Δ%（计划vs实际）格式：**
- 负值（CPL < 目标）= 良好，直接显示：`-4%`
- 正值（CPL > 目标）= 不佳，显示：`+15%`
- 若无目标或无Leads，显示`—`

---

AdSets (уровень AdSet)

AdSet组（AdSet层级）

Под каждой кампанией:
markdown
undefined
每个广告系列下展示：
markdown
undefined

AdSets — {Campaign Name}

AdSet组 — {广告系列名称}

AdSetSpendLeadsCPLCTRBudgetСтатус
30-45_astana$150.0040$3.751.4%$25ACTIVE
25-35_almaty$100.0025$4.001.1%$15ACTIVE

---
AdSetSpendLeadsCPLCTR预算状态
30-45_astana$150.0040$3.751.4%$25ACTIVE
25-35_almaty$100.0025$4.001.1%$15ACTIVE

---

Ads (уровень Ad)

广告（Ad层级）

Под каждым AdSet:
markdown
undefined
每个AdSet下展示：
markdown
undefined

Ads — {AdSet Name}

广告 — {AdSet名称}

AdSpendLeadsCPLCTRСтатус
video_1_kitchen$80.0022$3.641.5%ACTIVE
video_2_doctor$70.0018$3.891.3%ACTIVE

---
广告SpendLeadsCPLCTR状态
video_1_kitchen$80.0022$3.641.5%ACTIVE
video_2_doctor$70.0018$3.891.3%ACTIVE

---

WhatsApp метрики (опционально)

WhatsApp指标（可选）

Если у какого-то аккаунта есть messagingLeads > 0, добавь секцию:
markdown
undefined
若账户存在messagingLeads > 0，添加以下板块：
markdown
undefined

WhatsApp Quality

WhatsApp质量数据

АккаунтMsg LeadsQuality LeadsCPQLQuality Rate
Profimed8542$7.6249.4%

---
账户消息Leads优质LeadsCPQL优质率
Profimed8542$7.6249.4%

---

Обработка ошибок

错误处理

markdown
⚠️ Аккаунт {name}: ошибка доступа — пропущен
markdown
ℹ️ {name}: нет данных за выбранный период
markdown
⚠️ 账户{name}：访问错误 — 已跳过
markdown
ℹ️ {name}：所选时间段无数据

Примеры запросов

请求示例

Дашборд без указания периода

未指定时间段的仪表板

Запрос: "Покажи дашборд" или 
/dashboard
Парсинг:
  • Период: yesterday (по умолчанию)
  • Аккаунты: все
  • Уровень: campaign (по умолчанию)
Действия:
  1. Читаю ad_accounts.md → активные аккаунты
  2. Читаю брифы каждого аккаунта → target CPL для кампаний
  3. get_insights для каждого аккаунта (level="campaign", time_range="yesterday")
  4. Формирую таблицы с колонками Target и Δ%
请求： "展示仪表板" 或 
/dashboard
解析：
  • 时间段：yesterday（默认）
  • 账户：全部
  • 层级：campaign（默认）
操作步骤：
  1. 读取ad_accounts.md → 活跃账户列表
  2. 读取每个账户的brief文件 → 广告系列的目标CPL
  3. 为每个账户调用get_insights（level="campaign", time_range="yesterday"）
  4. 生成包含目标CPL和Δ%的表格

Базовый дашборд

基础仪表板

Запрос: "Покажи дашборд за вчера"
Парсинг:
  • Период: yesterday
  • Аккаунты: все
  • Уровень: campaign (по умолчанию)
Действия:
  1. Читаю ad_accounts.md → 2 активных аккаунта
  2. get_insights(act_805414428109857, "yesterday", "campaign")
  3. get_insights(act_1106872004544227, "yesterday", "campaign")
  4. Формирую сводную таблицу + таблицы кампаний для каждого аккаунта
请求： "展示昨天的仪表板"
解析：
  • 时间段：yesterday
  • 账户：全部
  • 层级：campaign（默认）
操作步骤：
  1. 读取ad_accounts.md → 2个活跃账户
  2. 调用get_insights(act_805414428109857, "yesterday", "campaign")
  3. 调用get_insights(act_1106872004544227, "yesterday", "campaign")
  4. 生成账户汇总表格 + 每个账户的广告系列表格

Конкретный аккаунт с кампаниями

指定账户的广告系列仪表板

Запрос: "Дашборд Profimed за 7 дней с кампаниями"
Парсинг:
  • Период: last_7d
  • Аккаунты: Profimed (act_1106872004544227)
  • Уровень: campaign
Действия:
  1. Читаю ad_accounts.md → нахожу Profimed
  2. get_campaigns(act_1106872004544227, "ACTIVE")
  3. get_insights(act_1106872004544227, "last_7d", "campaign")
  4. Формирую таблицу аккаунта + таблицу кампаний
请求： "展示Profimed账户过去7天的广告系列仪表板"
解析：
  • 时间段：last_7d
  • 账户：Profimed（act_1106872004544227）
  • 层级：campaign
操作步骤：
  1. 读取ad_accounts.md → 找到Profimed账户
  2. 调用get_campaigns(act_1106872004544227, "ACTIVE")
  3. 调用get_insights(act_1106872004544227, "last_7d", "campaign")
  4. 生成账户表格 + 广告系列表格

Полный дашборд

完整仪表板

Запрос: "Полный дашборд за месяц"
Парсинг:
  • Период: last_30d
  • Аккаунты: все
  • Уровень: ad
Действия:
  1. Читаю ad_accounts.md → все активные
  2. Для каждого аккаунта:
    • get_campaigns() → список кампаний
    • get_adsets() → списки adsets по кампаниям
    • get_ads() → списки ads по adsets
    • get_insights(level="ad") → метрики по ads
    • get_adset_details() → бюджеты
  3. Формирую полную иерархию таблиц
请求： "展示过去一个月的完整仪表板"
解析：
  • 时间段：last_30d
  • 账户：全部
  • 层级：ad
操作步骤：
  1. 读取ad_accounts.md → 所有活跃账户
  2. 为每个账户执行：
    • 调用get_campaigns() → 广告系列列表
    • 调用get_adsets() → 各广告系列的AdSet列表
    • 调用get_ads() → 各AdSet的广告列表
    • 调用get_insights(level="ad") → 广告层级指标
    • 调用get_adset_details() → 预算数据
  3. 生成完整的层级表格

Custom период

自定义时间段

Запрос: "Дашборд с 2026-01-10 по 2026-01-20"
Парсинг:
  • Период: {"since": "2026-01-10", "until": "2026-01-20"}
  • Аккаунты: все
  • Уровень: campaign (по умолчанию)
请求： "展示2026-01-10至2026-01-20的仪表板"
解析：
  • 时间段：{"since": "2026-01-10", "until": "2026-01-20"}
  • 账户：全部
  • 层级：campaign（默认）

Чек-лист

检查清单

  • Прочитан ad_accounts.md
  • Определены параметры (период, аккаунты, уровень)
  • Получены insights для нужного уровня
  • Рассчитаны производные метрики (CPL, CTR, CPM)
  • Проверены WhatsApp метрики (если есть messagingLeads)
  • Сформированы таблицы по шаблонам
  • Добавлена строка ИТОГО для групп
  • 已读取ad_accounts.md
  • 已确定参数（时间段、账户、层级）
  • 已获取对应层级的insights数据
  • 已计算衍生指标（CPL、CTR、CPM）
  • 已检查WhatsApp指标（若存在messagingLeads）
  • 已按模板生成表格
  • 已为分组添加总计行

MCP команды

MCP命令

Чтение данных

数据读取

python
undefined
python
undefined

Список аккаунтов (если нужно проверить доступ)

账户列表（用于检查权限）

get_ad_accounts(limit=10)
get_ad_accounts(limit=10)

Кампании аккаунта

账户的广告系列

get_campaigns(account_id, status_filter="ACTIVE", limit=50)
get_campaigns(account_id, status_filter="ACTIVE", limit=50)

AdSets аккаунта или кампании

账户或广告系列的AdSet

get_adsets(account_id, campaign_id=None, limit=50)
get_adsets(account_id, campaign_id=None, limit=50)

Ads аккаунта или adset

账户或AdSet的广告

get_ads(account_id, adset_id=None, limit=50)
get_ads(account_id, adset_id=None, limit=50)

Метрики за период

时间段指标数据

get_insights( object_id, # account_id или конкретный ID time_range, # "yesterday" или {"since": "...", "until": "..."} level="account" # account | campaign | adset | ad )
get_insights( object_id, # account_id或具体ID time_range, # "yesterday"或{"since": "...", "until": "..."} level="account" # account | campaign | adset | ad )

Детали adset (для бюджета)

AdSet详情（用于获取预算）

get_adset_details(adset_id)
undefined
get_adset_details(adset_id)
undefined

Доступные периоды

支持的时间段

ЗначениеОписание
today
Сегодня
yesterday
Вчера
last_3d
Последние 3 дня
last_7d
Последние 7 дней
last_14d
Последние 14 дней
last_30d
Последние 30 дней
this_month
Текущий месяц
last_month
Прошлый месяц
{"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"}
Custom
值说明
today
今天
yesterday
昨天
last_3d
过去3天
last_7d
过去7天
last_14d
过去14天
last_30d
过去30天
this_month
当前月
last_month
上月
{"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"}
自定义时间段