# Product Hunt Analyst

独立项目：拉取 [Product Hunt](https://www.producthunt.com) 数据，分析近 **1 / 2 / 3 / 4 周** 或 **1 个月** 的热门产品趋势，并提供可视化 Web 界面。

可与 **Codex**、**Cursor**、**Claude Desktop**、**Workbuddy** 等工具通过 MCP / CLI / HTTP API 集成。

## 功能

- 按时间窗口拉取 Product Hunt 产品（按 upvotes 排序）
- 自动生成趋势报告：Top 产品、品类分布、每日发布量、主题关键词、文字洞察
- React 可视化仪表盘（折线图、柱状图、排行榜）
- MCP Server 供 AI Agent 直接调用
- CLI 脚本输出 JSON / Markdown

## 快速开始

### 1. 安装依赖

```bash
cd product-hunt-analyst
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -r requirements.txt
```

### 2. 配置 Product Hunt Token

1. 在 [Product Hunt OAuth Apps](https://www.producthunt.com/v2/oauth/applications) 创建应用
2. 复制 Developer Token
3. 复制 `.env.example` 为 `.env` 并填入：

```bash
PRODUCT_HUNT_TOKEN=your_token_here
```

> 未配置 Token 时，Web UI 会自动切换到 Demo 模式展示示例数据。

### 3. 命令行分析

```bash
# JSON 报告
python scripts/analyze.py --period 2w

# Markdown 报告
python scripts/analyze.py --period 1m --markdown

# 仅拉取原始数据
python scripts/fetch_posts.py --period 3w --compact
```

### 4. 启动 Web 可视化

**方式 A：开发模式（前后端分离）**

```bash
# 终端 1 - API
python -m backend.app

# 终端 2 - 前端
cd frontend
npm install
npm run dev
# 打开 http://localhost:5173
```

**方式 B：生产模式（单端口）**

```bash
cd frontend && npm install && npm run build
cd ..
python -m backend.app
# 打开 http://127.0.0.1:8765
```

## 时间范围

| 参数 | 含义 |
|------|------|
| `1w` | 近 1 周（7 天） |
| `2w` | 近 2 周（14 天） |
| `3w` | 近 3 周（21 天） |
| `4w` | 近 4 周（28 天） |
| `1m` | 近 1 个月（30 天） |

## MCP 集成（Codex / Cursor / Claude）

### Codex

```bash
pip install -r requirements.txt
export PRODUCT_HUNT_TOKEN=your_token
codex mcp add productHuntAnalyst --command python --arg mcp/server.py
```

将 `skill/SKILL.md` 链接或复制到 Codex skills 目录后，可使用 `$product-hunt-analyst` 触发。

### Cursor

在项目根目录 `.cursor/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "productHuntAnalyst": {
      "command": "python",
      "args": ["mcp/server.py"],
      "cwd": "E:/codex/product-hunt-analyst",
      "env": {
        "PRODUCT_HUNT_TOKEN": "your_token"
      }
    }
  }
}
```

### Claude Desktop

在 `claude_desktop_config.json` 中注册同样的 MCP server 配置。

### MCP 工具一览

| 工具 | 说明 |
|------|------|
| `list_periods` | 列出支持的时间窗口 |
| `fetch_posts` | 拉取指定时段产品列表 |
| `analyze_trends` | 完整趋势分析（JSON） |
| `analyze_market` | 完整报告（JSON 或 Markdown） |
| `get_top_products` | Top N 产品 |
| `get_topic_trends` | 品类趋势 |

## HTTP API

| 端点 | 说明 |
|------|------|
| `GET /api/health` | 健康检查 |
| `GET /api/periods` | 时间窗口列表 |
| `GET /api/posts?period=2w` | 原始产品数据 |
| `GET /api/analyze?period=2w` | 分析报告（JSON） |
| `GET /api/analyze?period=2w&format=markdown` | Markdown 报告 |
| `GET /api/demo?period=2w` | Demo 数据（无需 Token） |

## Workbuddy / 自动化

通过 HTTP 或 CLI 调用即可：

```bash
curl "http://127.0.0.1:8765/api/analyze?period=4w"
python scripts/analyze.py -p 4w --markdown > report.md
```

## 项目结构

```
product-hunt-analyst/
├── backend/           # FastAPI + PH API 客户端 + 分析引擎
├── frontend/          # React + Vite + Recharts 可视化
├── mcp/               # MCP Server
├── scripts/           # CLI 工具与测试
├── skill/             # Codex/Cursor Agent Skill
├── agents/            # OpenAI Agents 配置
└── requirements.txt
```

## 测试

```bash
python scripts/test_product_hunt_analyst.py
```

## 注意事项

- Product Hunt API 有速率限制（约 6250 complexity points / 15 分钟）
- 数据仅供研究参考，不构成投资或商业决策建议
- 请遵守 [Product Hunt API Terms](https://api.producthunt.com/v2/docs)

## License

MIT