README.md

metadata

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 看板展示并支持钉钉推送。

快速开始

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

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

项目结构

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

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

环境变量

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