内容
# 脉冲智能
一款由AI驱动的消费者智能平台，通过分析公开信号（应用商店、Google Play、Reddit）来提取行为模式，检测品类探索障碍，生成用户角色，并挖掘产品增长机会。
由最初的 **Weekly Product Review Pulse** 演变而来。
---
## 功能介绍
脉冲智能超越了简单的情感分析。通过使用大型语言模型（Groq Llama 3.3 70B）进行深度推理，它回答了用户为什么表现出某种行为：
1. **行为模式检测**：识别习惯循环、信任问题、价格敏感性和发现差距。
2. **品类探索障碍**：为什么用户坚持熟悉的品类（例如，杂货），而避免探索新的品类（例如，美妆或电子产品）？
3. **用户角色**：AI生成的行为原型（例如，“常规购买者”，“好奇的探索者”）。
4. **工作任务（JTBD）**：提取用户为您的产品所雇佣的功能性、情感性和社会性工作。
5. **增长机会**：将分析结果综合成优先的产品机会。
6. **研究副驾驶**：自动生成可测试的假设和“妈妈测试”访谈问题。
---
## 架构与流程
流程通过4个阶段处理消费者信号：
| 阶段 | 技术 | 描述 |
|-------|-----------|-------------|
| **1. 数据收集** | `google-play-scraper`，iTunes RSS，Reddit JSON API | 并行从多个来源获取数据。 |
| **2. 数据标准化** | Pandas，Pydantic，ChromaDB | 标准化数据，检测品类/行为信号，并使用向量嵌入执行语义重复数据删除。 |
| **3. AI分析** | Groq（Llama 3.3 70B），Sentence-Transformers | 深度推理以提取主题、障碍、角色、JTBD和机会。 |
| **4. 报告生成** | Python MCP SDK，Google Sheets（模拟） | 将洞察格式化为可行的报告，通过MCP工具公开，并为仪表板提供REST API。 |
---
## 技术栈
### 后端
- **框架：** FastAPI + Uvicorn
- **AI/LLM：** Groq API（Llama 3.1 8B用于快速任务，Llama 3.3 70B用于深度推理）
- **嵌入：** `sentence-transformers`（`all-MiniLM-L6-v2`）
- **向量存储：** ChromaDB
- **数据模型：** Pydantic
- **PII检测：** Microsoft Presidio + spaCy（`en_core_web_sm`）
### MCP集成
- **协议：** 模型上下文协议（MCP），通过`mcp` Python SDK
- **服务器：** 嵌入式Python MCP服务器，暴露15+个用于收集、分析和报告的工具。
### 前端
- **框架：** React 18 + Vite（React Router用于多页面仪表板）
---
## 详细本地设置指南
### 1. 后端设置
#### 先决条件
- **Python**：3.10+
- **Git**
#### 步骤
1. 导航到后端文件夹：
```bash
cd backend
```
2. 创建并激活虚拟环境：
```bash
python -m venv venv
# Windows: .\venv\Scripts\activate
# Mac/Linux: source venv/bin/activate
```
3. 安装依赖项：
```bash
pip install -r requirements.txt
```
4. 下载spaCy模型（用于PII擦除）：
```bash
python -m spacy download en_core_web_sm
```
5. 配置环境变量：
在`backend/`目录中创建一个`.env`文件：
```env
GROQ_API_KEY="your-groq-api-key-here"
```
6. 启动API服务器：
```bash
python main.py
```
*可在 `http://localhost:8000` 访问*
### 2. MCP服务器设置
后端也作为MCP服务器，允许您直接在Claude Desktop或Cursor中使用Pulse Intelligence工具。
1. 确保后端环境已设置并激活。
2. 运行MCP服务器：
```bash
python mcp_server.py
```
3. 要配置Claude Desktop使用它，请在`claude_desktop_config.json`中添加以下内容：
```json
"mcpServers": {
"pulse-intelligence": {
"command": "python",
"args": ["/absolute/path/to/Weekly-Product-Review-Pulse/backend/mcp_server.py"]
}
}
```
### 3. 前端设置（仪表板）
1. 导航到前端目录：
```bash
cd frontend
```
2. 安装Node包：
```bash
npm install
```
3. 启动开发服务器：
```bash
npm run dev
```
*可在 `http://localhost:5173` 访问*
---
## 向后兼容性（v1）
原始的Weekly Product Review Pulse功能（获取Play/App Store评论，聚类，LLM总结和Node.js MCP推送到Google Docs/Gmail）通过`/api/generate-report`和`/api/mcp-push`端点保持完整。`frontend/src/App.jsx`中的React UI仍然支持此流程。
