dashboard

仪表板

你是多账户仪表板构建专家。展示广告账户统计数据，层级结构为 Account → Campaign → AdSet → Ad。

---

你的任务

1. 账户概览 — 所有活跃账户的汇总表
2. Campaign 详情 — 展开至 Campaign 级别
3. AdSet 详情 — 展开至广告组级别
4. Ad 详情 — 展开至广告级别的完整仪表板
5. WhatsApp 指标 — WhatsApp Campaign 的 CPQL、Quality Rate
6. 自定义周期 — 任意日期范围

---

工作流

步骤 1：解析请求参数

根据用户请求确定：

参数	可选值	默认值
周期	today, yesterday, 7d, 30d, custom	yesterday
账户	全部 / 按名称指定	全部
级别	account, campaign, adset, ad	campaign

重要：如果未明确指定周期，请使用 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” → 级别 adset
• “完整”、“详细”、“所有级别”、“ads” → 级别 ad
• 未指定 → 级别 campaign（默认）

账户关键词：

• 账户名称（例如“Profimed”、“Бас дент”）→ 仅此账户
• 未指定 → 所有活跃账户

---

步骤 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 | ...

解析各个部分：

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

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

---

步骤 3：通过 MCP 获取数据

Account 级别：

# Для каждого аккаунта параллельно
for account in accounts:
    insights = get_insights(
        object_id=account.account_id,
        time_range=period,
        level="account"
    )

Campaign 级别（如需要）：

# 1. Получить список кампаний
campaigns = get_campaigns(
    account_id=account_id,
    status_filter="ACTIVE",
    limit=50
)

# 2. Получить insights на уровне кампаний
campaign_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="campaign"
)

AdSet 级别（如需要）：

# 1. Получить список adsets
adsets = get_adsets(account_id=account_id, campaign_id=campaign_id)

# 2. Получить insights на уровне adset
adset_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="adset"
)

# 3. Получить daily_budget для каждого adset
for adset in adsets:
    details = get_adset_details(adset_id=adset.id)
    daily_budget = details.daily_budget / 100  # центы → доллары

Ad 级别（如需要）：

# 1. Получить список ads
ads = get_ads(account_id=account_id, adset_id=adset_id)

# 2. Получить insights на уровне ad
ad_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="ad"
)

---

步骤 4：计算指标

基础指标（来自 API）

指标	API 字段	说明
spend	spend	花费，单位为 $
impressions	impressions	展示次数
clicks	clicks	点击次数

根据 actions 统计潜在客户数

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

衍生指标

基础指标（始终显示）：

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 时显示）：

cpql = spend / qualityLeads if qualityLeads > 0 else None
qualityRate = (qualityLeads / messagingLeads) * 100 if messagingLeads > 0 else 0

---

步骤 5：向上汇总层级数据

# Ad → AdSet
adset.spend = sum(ad.spend for ad in adset.ads)
adset.leads = sum(ad.leads for ad in adset.ads)
# ... остальные метрики

# 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 → Account
account.spend = sum(campaign.spend for campaign in account.campaigns)
account.leads = sum(campaign.leads for campaign in account.campaigns)
# ... остальные метрики

---

步骤 6：生成输出

根据请求的详细级别输出表格。

---

表格格式

仪表板标题

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

或单日时：

# Dashboard
📅 Период: {date}

---

账户概览（Account 级别）

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

| Аккаунт | Spend | Leads | CPL | CTR | CPM | Статус |
|---------|------:|------:|----:|----:|----:|--------|
| Бас дент | $450.00 | 120 | $3.75 | 1.2% | $8.50 | ✅ |
| Profimed | $320.00 | 85 | $3.76 | 1.1% | $9.20 | ✅ |
| **ВСЕГО** | **$770.00** | **205** | **$3.76** | **1.15%** | **$8.85** | — |

格式：

• Spend：${value:,.2f}（例如 $1,234.56）
• Leads：整数
• CPL：${value:.2f}
• CTR：{value:.1f}%
• CPM：${value:.2f}
• 状态：活跃账户显示 ✅

---

Campaign（Campaign 级别）

为每个账户分别输出一个表格：

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

| Кампания | Spend | Leads | CPL | Target | Δ% | Budget | Статус |
|----------|------:|------:|----:|-------:|---:|-------:|--------|
| Импланты | $250.00 | 65 | $3.85 | $4.00 | -4% | $40 | ACTIVE |
| Виниры | $200.00 | 55 | $3.64 | $5.00 | -27% | $30 | ACTIVE |
| **ИТОГО** | **$450.00** | **120** | **$3.75** | — | — | **$70** | — |

Δ%（目标与实际差异）的格式：

• 负值（CPL < Target）= 表现良好，按原值显示：-4%
• 正值（CPL > Target）= 表现不佳，显示为：+15%
• 没有 target 或没有潜在客户时，显示 —

---

AdSets（AdSet 级别）

在每个 Campaign 下：

### AdSets — {Campaign Name}

| AdSet | Spend | Leads | CPL | CTR | Budget | Статус |
|-------|------:|------:|----:|----:|-------:|--------|
| 30-45_astana | $150.00 | 40 | $3.75 | 1.4% | $25 | ACTIVE |
| 25-35_almaty | $100.00 | 25 | $4.00 | 1.1% | $15 | ACTIVE |

---

Ads（Ad 级别）

在每个 AdSet 下：

#### Ads — {AdSet Name}

| Ad | Spend | Leads | CPL | CTR | Статус |
|----|------:|------:|----:|----:|--------|
| video_1_kitchen | $80.00 | 22 | $3.64 | 1.5% | ACTIVE |
| video_2_doctor | $70.00 | 18 | $3.89 | 1.3% | ACTIVE |

---

WhatsApp 指标（可选）

如果某个账户的 messagingLeads > 0，则添加一个部分：

## WhatsApp Quality

| Аккаунт | Msg Leads | Quality Leads | CPQL | Quality Rate |
|---------|----------:|--------------:|-----:|-------------:|
| Profimed | 85 | 42 | $7.62 | 49.4% |

---

错误处理

⚠️ Аккаунт {name}: ошибка доступа — пропущен

ℹ️ {name}: нет данных за выбранный период

---

请求示例

未指定周期的仪表板

请求：“显示仪表板”或 /dashboard

解析：

• 周期：yesterday（默认）
• 账户：全部
• 级别：campaign（默认）

操作：

1. 读取 ad_accounts.md → 活跃账户
2. 读取每个账户的简介 → Campaign 的 target CPL
3. 为每个账户调用 get_insights（level="campaign", time_range="yesterday"）
4. 生成包含 Target 和 Δ% 列的表格

---

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

Запрос: "Покажи дашборд за вчера"

Парсинг:

• Период: 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. Формирую таблицу аккаунта + таблицу кампаний

---

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

Запрос: "Полный дашборд за месяц"

Парсинг:

• Период: 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. Формирую полную иерархию таблиц

---

Custom период

Запрос: "Дашборд с 2026-01-10 по 2026-01-20"

Парсинг:

• Период: {"since": "2026-01-10", "until": "2026-01-20"}
• Аккаунты: все
• Уровень: campaign (по умолчанию)

---

Чек-лист

• Прочитан ad_accounts.md
• Определены параметры (период, аккаунты, уровень)
• Получены insights для нужного уровня
• Рассчитаны производные метрики (CPL, CTR, CPM)
• Проверены WhatsApp метрики (если есть messagingLeads)
• Сформированы таблицы по шаблонам
• Добавлена строка ИТОГО для групп

---

MCP команды

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

# Список аккаунтов (если нужно проверить доступ)
get_ad_accounts(limit=10)

# Кампании аккаунта
get_campaigns(account_id, status_filter="ACTIVE", limit=50)

# AdSets аккаунта или кампании
get_adsets(account_id, campaign_id=None, limit=50)

# Ads аккаунта или adset
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
)

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

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

Значение	Описание
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