内容
# Groww 脉冲代理
一对实现自主客户反馈分析代理的服务。它自动抓取 Groww 移动应用程序的应用程序商店评论（Google Play Store 和 Apple App Store），清洗 PII，规范化数据，使用 Groq LLM 分析反馈趋势，直接将生成的报告附加到 Google Doc，并使用自定义 Server-Sent Events（SSE）模型上下文协议（MCP）服务器向利益相关者发送电子邮件通知。
---
## 🏗️ 架构
```
+------------------------------------------+
| 前端仪表盘 | (托管在 Vercel 上)
| (Vercel 域名) |
+------------------------------------------+
| /api/* 重写
v
+------------------------------------------+
| Python 后端 API | (托管在 Railway 上)
| (Railway 域名) |
+------------------------------------------+
| MCP SSE 会话
v
+------------------------------------------+
| Google Workspace MCP 服务器 | (托管在 Railway 上)
| (MCP 服务器域名) |
+------------------------------------------+
| |
v v
Google Docs API Gmail API
```
---
## 📁 仓库结构
```
├── api/ # Vercel 无服务器函数入口
├── data/ # 原始/规范化评论缓存和备份
├── docs/ # 产品需求和规格
├── output/ # 本地生成的报告备份（Markdown 和 TXT 格式）
├── src/ # 核心源代码
│ ├── app.py # FastAPI 应用程序和后台任务运行器
│ ├── downloader.py # 直播评论爬虫（应用商店和 Play 商店）
│ ├── importer.py # 数据导入器和日期过滤器
│ ├── scrubber.py # PII 屏蔽和字符串清理器
│ ├── analyzer.py # Groq LLM 提示和报告生成引擎
│ └── publisher.py # 连接到 Google API 的 MCP 客户端包装器
├── tests/ # 自动化 pytest 套件（单元测试和 Playwright 浏览器测试）
├── requirements.txt # Python 依赖项
└── vercel.json # 前端路由和 API 重写规则
```
---
## ⚙️ 配置和环境变量
### 1. Python 后端（`Groww-Pulse-Agent`）
在本地开发的根目录中创建 `.env` 文件：
```env
GROQ_API_KEY=您的_groq_api_key
GOOGLE_DOC_ID=您的_google_doc_id
RECIPIENT_EMAIL=您的_recipient_email@example.com
MCP_SERVER_URL=您的_local_mcp_server_sse_url
```
### 2. Google Workspace MCP 服务器（`MCP-Server---Groww-Pulse`）
MCP 服务器从其自己的环境中解析这些变量：
```env
GOOGLE_CLIENT_ID=您的_google_oauth_client_id
GOOGLE_CLIENT_SECRET=您的_google_oauth_client_secret
GOOGLE_REDIRECT_URI=您的_oauth_redirect_uri
GOOGLE_REFRESH_TOKEN=您的_authenticated_google_refresh_token
GOOGLE_ACCESS_TOKEN=您的_authenticated_google_access_token
PORT=3000
MCP_TRANSPORT=sse
LOG_LEVEL=info
```
---
## 🚀 本地设置和运行
### 步骤 1：安装依赖项
在本地机器上安装依赖项：
```bash
# 在后端目录中：
pip install -r requirements.txt
# 在 MCP 服务器目录中：
npm install
```
### 步骤 2：身份验证 Google OAuth
在 MCP 服务器文件夹中运行登录脚本以生成本地凭证令牌：
```bash
npm run auth:login
```
（此操作会删除过时的文件，在端口 3000 上启动本地回调，并启动 Google 身份验证流程以授予范围。它会将生成的令牌保存在 `.gstore/tokens.json` 中）。
### 步骤 3：运行本地服务器
在 SSE 模式下在本地公开 MCP 服务器：
```bash
# 在 MCP 服务器目录中：
set MCP_TRANSPORT=sse&& npm run start
```
在本地启动 FastAPI Python 应用程序：
```bash
# 在 Groww-Pulse-Agent 目录中：
py -m uvicorn src.app:app --host 127.0.0.1 --port 8000
```
在浏览器中打开本地网址以查看本地仪表盘并触发评论脉冲运行。
---
## ☁️ 云部署
1. **前端**：部署到 Vercel。Vercel 匹配重写规则以将所有 API 请求代理到 Railway。
2. **后端**：部署到 Railway。
3. **MCP 服务器**：部署到 Railway 作为持久的 Docker 容器，通过端口 `3000` 公开，并设置环境变量 `MCP_TRANSPORT=sse`。
4. **集成**：在 Railway Python 后端仪表盘中设置 `MCP_SERVER_URL` 以指向 MCP 服务器的公共域名。
