---
title: DM Analysis Agent
emoji: 📊
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# DM Analysis Agent

数字营销广告数据分析 Agent —— 自动拉取 Meta / Google / Criteo / Bing 广告数据，生成投放分析报告，通过 Web 看板展示并支持钉钉推送。

## 快速开始

```bash
pip install -r requirements.txt
python src/main.py --web
```

浏览器打开后即可使用，页面内有完整的使用说明和快捷按钮。

## 项目结构

```text
DM-Analysis-Agent/
├── .github/workflows/
│   └── deploy-hf.yml       # GitHub Actions → Hugging Face 自动部署
├── api/
│   └── index.py             # Vercel 无服务器入口
├── docs/                    # 架构文档、分析框架定义
├── src/
│   ├── main.py              # 入口（Web/交互/定时/单次/预览）
│   ├── web.py               # Flask Web 服务 + API 路由
│   ├── loader.py            # 数据加载（Google Sheets / Excel / API CSV）
│   ├── monitor.py           # 日常监控引擎（KPI 告警、趋势、数据矩阵）
│   ├── budget.py            # 预算追踪（Pacing、Revenue vs Target）
│   ├── analyzer.py          # 周度/月度/日度聚合分析
│   ├── ai_analyzer.py       # AI 分析（GPT-4o-mini）
│   ├── meta_api.py          # Meta Ads API 拉取
│   ├── google_api.py        # Google Ads API 拉取
│   ├── criteo_api.py        # Criteo API 拉取
│   ├── bing_api.py          # Bing Ads API 拉取
│   ├── parser.py            # 自然语言指令解析
│   ├── formatter.py         # Markdown 报告生成
│   ├── memory.py            # AI 分析记忆系统
│   └── dingtalk.py          # 钉钉 Webhook 推送
├── templates/
│   └── index.html           # Web 前端（三 Tab：监控/预算/分析）
├── tests/                   # 测试
├── data/                    # 运行时数据（API CSV、日志，不入 Git）
├── config.yaml              # 数据源 + 指标 + 定时任务配置
├── Dockerfile               # Docker / Hugging Face 部署
├── requirements.txt
└── .env.example             # 环境变量模板
```

## 数据源

| 平台 | API | 拉取层级 | 状态 |
|------|-----|---------|------|
| Meta | Marketing API v21.0 | Campaign 日度 | 已接入 |
| Google | Google Ads API v23 | Campaign 日度 | 已接入 |
| Criteo | Statistics API | Campaign 日度 | 已接入 |
| Bing | Reporting API v13 | Campaign 日度 | 已接入 |
| Google Sheets | gspread | Export + 各平台工作表 | 已接入 |

## 部署

### Hugging Face（当前）

Push 到 GitHub `main` 分支后自动触发 GitHub Actions 部署到 Hugging Face Spaces。

### Docker

```bash
docker build -t dm-agent .
docker run -p 7860:7860 --env-file .env dm-agent
```

## 环境变量

复制 `.env.example` 为 `.env`，填写 API 密钥和 Webhook 地址。详见 `.env.example` 中的注释。