# DM Analysis Agent — 新电脑开发环境搭建指南

## 前提条件

- 已安装 Python 3.12+
- 已安装 Git
- 有 GitHub 账号并能访问 `Binbom-Jared/DM-Agent` 仓库

---

## 第 1 步：克隆代码

```bash
git clone https://github.com/Binbom-Jared/DM-Agent.git
cd DM-Agent
pip install -r requirements.txt
```

---

## 第 2 步：复制密钥文件

从已有的开发电脑上拿到以下两个文件，放到项目根目录：

| 文件 | 作用 | 如何获取 |
|------|------|---------|
| `.env` | 所有 API 密钥、Token、钉钉 Webhook | 从已有电脑的项目根目录复制 |
| `credentials.json` | Google Sheets 服务账号密钥 | 从已有电脑的项目根目录复制 |

> **安全提醒**：这两个文件包含敏感信息，不要上传到 GitHub 或发到公开渠道。通过 U 盘或加密传输方式拷贝。

---

## 第 3 步：启动项目

### Web 界面（推荐）

```bash
python src/main.py --web
```

浏览器打开 `http://localhost:5000` 即可使用。

### 其他启动方式

```bash
# 交互模式
python src/main.py --chat

# 预览报告（不推送）
python src/main.py --dry-run
```

---

## 日常开发流程

### 开始工作前：拉取最新代码

```bash
git pull origin main
```

### 改完代码后：推送到 GitHub

```bash
git add -A
git commit -m "你的改动说明"
git push origin main
```

推送到 GitHub 后会自动触发 Hugging Face 部署。

---

## 项目结构

```text
DM-Analysis-Agent/
├── .github/workflows/deploy-hf.yml   # GitHub Actions → HF 自动部署
├── api/index.py                      # Vercel 入口
├── docs/                             # 架构文档
├── src/
│   ├── web.py                        # Flask Web 服务 + API 路由
│   ├── loader.py                     # 数据加载（Sheets / Excel / CSV）
│   ├── monitor.py                    # 日常监控引擎
│   ├── budget.py                     # 预算追踪
│   ├── 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
│   ├── dingtalk.py                   # 钉钉推送
│   ├── memory.py                     # AI 记忆系统
│   ├── parser.py                     # 自然语言解析
│   └── formatter.py                  # 报告格式化
├── templates/index.html              # Web 前端
├── tests/                            # 测试
├── config.yaml                       # 配置文件
├── Dockerfile                        # Docker 部署
├── requirements.txt                  # Python 依赖
├── .env                              # 密钥（不入 Git）
└── credentials.json                  # Google 服务账号（不入 Git）
```

---

## 数据源

| 来源 | 说明 | 数据位置 |
|------|------|---------|
| Google Sheets | 主数据源，手动维护 + API 回写 | 云端 |
| Meta Ads API | Campaign 级日度数据 | API 实时拉取 → 本地 CSV 缓存 |
| Google Ads API | Campaign 级日度数据 | API 实时拉取 → 本地 CSV 缓存 |
| Criteo API | Campaign 级日度数据 | API 实时拉取 → 本地 CSV 缓存 |
| Bing API | Campaign 级日度数据 | API 实时拉取 → 本地 CSV 缓存 |

本地 CSV 只是缓存，删掉可以重新拉取，不影响系统运行。

---

## 常见问题

### Q: Google API 报 `invalid_grant`
A: OAuth refresh token 过期了，需要重新授权。参考 Google Ads API 文档刷新 token，更新 `.env` 中的 `GOOGLE_ADS_REFRESH_TOKEN`。

### Q: Bing API 报 `未配置 BING_ACCOUNT_IDS`
A: 在 `.env` 中添加 `BING_ACCOUNT_IDS=account_id:country`（如 `123456:US,789012:CA`）。

### Q: Hugging Face 没有更新
A: 确认 GitHub Actions 是否触发成功。到 GitHub 仓库的 Actions 页面查看。如果 `HF_TOKEN` 过期，需要在 GitHub Settings → Secrets 中更新。