docs/setup-guide.md

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

前提条件

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

---

第 1 步：克隆代码

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 界面（推荐）

python src/main.py --web

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

其他启动方式

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

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

---

日常开发流程

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

git pull origin main

改完代码后：推送到 GitHub

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

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

---

项目结构

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 中更新。