# 公众号爆款数据格式说明

## 概览

本文档定义了公众号爆款封面数据查询脚本 `fetch_explosive_covers.py` 的输入输出格式规范。

**接口地址**：`POST https://redfox.hk/story/api/gzh/search/hotArticleNew`

## 输入格式

### 脚本参数

```bash
python3 scripts/fetch_explosive_covers.py --keyword <关键词> [选项]
```

| 参数 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `--keyword` | 是 | 搜索关键词（支持多个，逗号分隔，空字符串查全站热门） | - |
| `--start-date` | 否 | 开始日期，格式 yyyy-MM-dd | 不传（接口自行决定） |
| `--end-date` | 否 | 结束日期，格式 yyyy-MM-dd | 不传（接口自行决定） |
| `--max-items` | 否 | 最多展示文章数量 | 20 |
| `--output-format` | 否 | 输出格式：text、json 或 markdown | json |
| `--output-file` | 否 | 输出文件路径 | 不输出文件 |
| `--debug` | 否 | 调试模式 | False |

## 输出格式

### 文章数据字段

每篇文章（`articles` 数组中的对象）包含以下字段：

#### 文章基本信息

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `id` | string | 文章ID（唯一标识） |
| `title` | string | 文章标题（可能为空，需从 summary 提取） |
| `summary` | string | 文章摘要/正文片段 |
| `publicTime` | string | 发布时间（格式：YYYY-MM-DD HH:MM:SS） |
| `url` | string | 文章链接（完整URL） |

#### 作者信息

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `author` | string | 公众号名称/作者名 |

#### 互动数据

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `clicksCount` | int | 阅读数 |
| `watchCount` | int | 在看数 |
| `likeCount` | int | 点赞数 |
| `shareCount` | int | 分享数 |
| `commentsCount` | int | 评论数 |

#### 封面图

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `imageUrl` | string | 封面图URL（旧接口字段名为 `coverUrl`） |

#### 评分字段（用于排序）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| `totalScore` | float | 总分（用于排序） |
| `relevanceScore` | float | 相关性评分 |
| `popularityScore` | float | 热度评分 |
| `recencyScore` | float | 时效评分 |

#### ⚠️ 新接口缺失字段

以下字段在旧接口（getWxCozeSkillData）中存在，**hotArticleNew 接口不返回**：

| 缺失字段 | 说明 | 影响 |
|----------|------|------|
| `userName` | 公众号名称 | 已改为 `author` 字段 |
| `photoId` | 文章旧ID | 已改为 `id` 字段 |
| `oriUrl` | 文章旧链接 | 已改为 `url` 字段 |
| `accountId` | 公众号账号ID | 无法拼接二维码链接 |
| `userHeadUrl` | 作者头像 | 无法展示作者头像 |

### JSON 输出示例

```json
{
  "keyword": "职场",
  "articles": [
    {
      "id": "abc123",
      "title": "职场新人必知的10个技巧",
      "summary": "刚入职场的你是否感到迷茫...",
      "author": "职场达人",
      "publicTime": "2026-07-20 10:30:00",
      "url": "https://mp.weixin.qq.com/s/xxxxx",
      "imageUrl": "https://mmbiz.qpic.cn/mmbiz_jpg/...",
      "clicksCount": 58000,
      "watchCount": 320,
      "totalScore": 85.5,
      "relevanceScore": 8.2,
      "popularityScore": 7.5,
      "recencyScore": 6.0
    }
  ],
  "latestHotArticles": [],
  "hotTopics": [
    { "name": "职场晋升", "count": 120 }
  ],
  "relatedSearches": ["职场沟通", "职场穿搭"]
}
```

## 关于封面图

新接口（hotArticleNew）封面图字段名为 `imageUrl`，旧接口为 `coverUrl`，脚本已做双字段兑容处理。

## 使用注意事项

### 数据获取原则

1. **必须调用脚本查询**：不能使用其他方式查询或直接搜索网络资讯
2. **必须等待脚本执行完成**：获取返回结果后才能进行后续步骤
3. **必须展示完整数据列表**：不能跳过或询问用户

### 字段说明

1. **标题提取**：如果 `title` 字段为空，从 `summary` 字段提取前30个字符作为标题
2. **作者名称**：使用 `author` 字段
3. **阅读数格式**：整数，脚本中格式化为 `1.0w` 形式（≥10000时）
4. **文章链接**：使用 `url` 字段

# 爆款封面分析报告 HTML 模板

## 文件说明

本模板采用 **JS 渲染型** 架构：HTML 结构和渲染逻辑固定在 `references/report_template.html` 中，Agent 只需注入一段 JSON 数据，页面自动渲染，无需在输出时临时生成大量 HTML。

**模板文件**：`references/report_template.html`

**⚠️ 重要：按风格类型分类展示封面，不要逐张输出分析结果！**

---

## 使用方式

1. 读取 `references/report_template.html` 模板文件
2. 将分析结果组装为 JSON 对象
3. 用 SearchReplace 将模板中 `__REPORT_DATA__` 的值替换为实际 JSON
4. 写入 `./爆款封面分析报告_{关键词}.html`
5. 执行 `open ./爆款封面分析报告_{关键词}.html` 打开浏览器

**替换目标**（模板中唯一的占位区域）：
```javascript
var __REPORT_DATA__ = {
    "keyword": "",
    "analysisCount": 0,
    "styles": [],
    "plans": []
};
```

---

## JSON 数据结构

```json
{
    "keyword": "美食,食谱,做饭",
    "analysisCount": 20,
    "styles": [
        {
            "name": "🍽️ 家常俯拍·满桌多菜",
            "count": 12,
            "coreVisual": "俯视/高角度拍摄，3-6道菜品铺满白色桌面，自然暖光",
            "features": "满桌丰盛感营造家的味道；白色桌面干净清爽；菜品色彩丰富",
            "covers": [
                "https://mmbiz.qpic.cn/xxx1/0?wx_fmt=jpeg",
                "https://mmbiz.qpic.cn/xxx2/0?wx_fmt=jpeg"
            ]
        }
    ],
    "plans": [
        {
            "name": "家常俯拍·满桌温馨",
            "coreVisual": "俯视角度拍摄4-6道家常菜铺满白色桌面，暖色自然光",
            "case": {
                "imageUrl": "https://mmbiz.qpic.cn/xxx/0?wx_fmt=jpeg",
                "url": "https://mp.weixin.qq.com/s/xxx",
                "title": "在家待客，简单四道家常菜",
                "author": "小李食代",
                "reads": "10.0w"
            },
            "prompt": "2.35:1横版比例（900x383像素）。参考封面：https://... 。俯视角度拍摄白色大理石桌面上摆放4-5道精致家常菜..."
        }
    ]
}
```

---

## 字段说明

### 顶层字段

| 字段 | 类型 | 说明 | 数据来源 |
|------|------|------|----------|
| `keyword` | string | 用户输入的主题关键词 | 用户输入 |
| `analysisCount` | number | 实际分析的封面图数量 | 过滤后统计 |
| `styles` | array | 风格类型分类列表 | 分析归类 |
| `plans` | array | 3个设计方案 | 分析总结 |

### styles 数组元素

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 风格类型名称（可含emoji） |
| `count` | number | 该风格出现次数 |
| `coreVisual` | string | 核心视觉描述 |
| `features` | string | 关键特征描述 |
| `covers` | string[] | 代表性封面图URL（最多5张） |

### plans 数组元素

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 方案风格名称 |
| `coreVisual` | string | 核心视觉描述 |
| `case.imageUrl` | string | 案例封面图URL（imageUrl 字段原始值） |
| `case.url` | string | 案例文章链接（url 字段） |
| `case.title` | string | 案例文章标题 |
| `case.author` | string | 案例作者名（author 字段） |
| `case.reads` | string | 案例阅读数（格式化后，如"10.0w"） |
| `prompt` | string | 生图提示词（含2.35:1比例说明和参考封面URL） |

---

## 图片过滤规则

- 空白图片（纯色块、无内容）：排除，不放入 covers 数组
- 小尺寸图片（宽或高 <10px）：排除
- 每个风格类型最多5张代表性封面图

---

## 样式规范

| 元素 | 样式规则 |
|------|----------|
| 封面图容器比例 | 2.35:1 (180x77px 风格展示 / 300x128px 案例参考) |
| 封面图适配 | object-fit: cover, object-position: center |
| 防盗链 | 模板已内置 `<meta name="referrer" content="no-referrer">` |

---

## 输出文件命名

生成HTML报告时，文件名格式：
```
爆款封面分析报告_{关键词}.html
```

保存路径：当前工作目录（使用相对路径 ./）

#!/usr/bin/env python3
"""
公众号爆款封面数据查询脚本
对接接口：POST https://redfox.hk/story/api/gzh/search/hotArticleNew
"""

import os
import sys
import argparse
import json
from datetime import datetime

import requests


def _do_fetch(keyword, headers, base_url, start_date=None, end_date=None, debug=False):
    """执行单次 POST 请求，返回解析后的 dict

    startDate / endDate 仅在用户显式指定时传入，否则由接口自行决定默认范围。
    """
    json_body = {
        "keyword": keyword,
        "source": "公众号爆款封面生成-GitHub",
        "pageSize": 50
    }

    # 时间参数：仅在用户显式指定时才传入
    if start_date:
        json_body["startDate"] = start_date
    if end_date:
        json_body["endDate"] = end_date

    if debug:
        print(f"\n[DEBUG] POST {base_url}", file=sys.stderr)
        print(f"[DEBUG] Body: {json_body}", file=sys.stderr)

    try:
        response = requests.post(base_url, json=json_body, headers=headers, timeout=30)

        if debug:
            print(f"[DEBUG] 状态码: {response.status_code}", file=sys.stderr)

        if response.status_code >= 400:
            print(f"[DEBUG] HTTP错误: {response.status_code} {response.text[:200]}", file=sys.stderr)
            return None

        result = response.json()

        if result.get("code") == 2000:
            data = result.get("data", {})
            if debug:
                articles = data.get("articles", [])
                print(f"[DEBUG] 获取到 {len(articles)} 篇文章", file=sys.stderr)
            return data
        else:
            if debug:
                print(f"[DEBUG] 接口错误: {result.get('msg')}", file=sys.stderr)
            return None

    except Exception as e:
        if debug:
            print(f"[DEBUG] 请求异常: {e}", file=sys.stderr)
        return None


def fetch_wx_covers(keyword: str, debug: bool = False, start_date: str = None, end_date: str = None):
    """
    调用 hotArticleNew 接口获取公众号爆款文章数据

    Args:
        keyword: 搜索关键词（多个关键词用逗号分隔，空字符串表示全站热门）
        debug: 是否打印调试信息
        start_date: 开始日期，格式 yyyy-MM-dd
        end_date: 结束日期，格式 yyyy-MM-dd（默认今天）

    Returns:
        dict: 包含 articles / latestHotArticles / hotTopics / relatedSearches
    """
    api_key = os.getenv("REDFOX_API_KEY")
    if not api_key:
        raise ValueError(
            "缺少 API Key 配置，请设置环境变量 REDFOX_API_KEY。"
            "获取方式：前往 https://redfox.hk/settings/api-keys?source=github 申请，"
            '然后执行 export REDFOX_API_KEY="ak_xxxx..."'
        )

    base_url = "https://redfox.hk/story/api/gzh/search/hotArticleNew"
    headers = {
        "X-API-KEY": api_key,
        "Content-Type": "application/json",
        "Accept": "application/json",
    }

    # 关键词原样传入，单次调用
    kw = keyword.strip() if keyword else ""

    data = _do_fetch(kw, headers, base_url, start_date=start_date, end_date=end_date, debug=debug)

    all_articles = data.get("articles", []) if data else []
    all_latest_hot = data.get("latestHotArticles", []) if data else []
    all_hot_topics = data.get("hotTopics", []) if data else []
    all_related_searches = data.get("relatedSearches", []) if data else []

    # 按 id 去重
    seen_ids = set()
    unique_articles = []
    for article in all_articles:
        article_id = article.get("id")
        if article_id and article_id not in seen_ids:
            seen_ids.add(article_id)
            unique_articles.append(article)

    unique_latest = []
    for article in all_latest_hot:
        article_id = article.get("id")
        if article_id and article_id not in seen_ids:
            seen_ids.add(article_id)
            unique_latest.append(article)

    seen_topics = set()
    unique_topics = []
    for topic in all_hot_topics:
        topic_name = topic.get("name", "") or topic.get("topic", "")
        if topic_name and topic_name not in seen_topics:
            seen_topics.add(topic_name)
            unique_topics.append(topic)

    return {
        "keyword": keyword,
        "articles": unique_articles,
        "latestHotArticles": unique_latest,
        "hotTopics": unique_topics[:10],
        "relatedSearches": all_related_searches[:10],
    }


def get_cover_urls(data, max_items=20):
    """
    从 articles 数组提取封面图 URL

    hotArticleNew 接口封面图字段名为 imageUrl（旧接口为 coverUrl），此处做双字段兑容。
    """
    urls = []
    items = data.get("articles", [])[:max_items]
    for item in items:
        # 优先取 imageUrl（新接口），兑容 coverUrl（旧接口）
        cover_url = item.get("imageUrl", "") or item.get("coverUrl", "")
        article_id = item.get("id", "")
        title = (item.get("title", "") or "")[:20]
        url = item.get("url", "")
        if cover_url:
            urls.append({
                "title": title,
                "article_id": article_id,
                "cover_url": cover_url,
                "link": url,
            })
    return urls


def format_num(n):
    """格式化数字：10000 → 1.0w"""
    if not n:
        return "0"
    try:
        n = int(n)
    except (ValueError, TypeError):
        return str(n)
    if n >= 10000:
        return f"{n / 10000:.1f}w"
    return str(n)


def format_output(data: dict, max_items: int = None, start_date: str = None):
    """
    格式化输出爆款数据（表格形式）

    Args:
        data: 原始数据（含 articles 数组）
        max_items: 最多展示条数，None 表示展示所有
        start_date: 开始日期，用于计算统计时间范围
    """

    def get_time_range(start_date):
        if start_date:
            try:
                start = datetime.strptime(start_date, "%Y-%m-%d")
                days = (datetime.now() - start).days
                return f"近{max(days, 1)}天"
            except Exception:
                pass
        return "近30天"

    time_range = get_time_range(start_date)

    def process_title(item):
        title = item.get("title", "") or ""
        if not title.strip():
            summary = item.get("summary", "") or ""
            if summary:
                title = summary.replace("\n", " ").replace("\r", " ").strip()[:30]
                if len(summary) > 30:
                    title += "..."
        if not title.strip():
            title = "无标题"
        title = title.replace("|", "\\|").replace("\n", " ").replace("\r", " ")
        title = " ".join(title.split())
        if len(title) > 30:
            title = title[:30] + "..."
        return title

    def format_time(item):
        pub_time = item.get("publicTime", "") or ""
        if pub_time:
            try:
                month = int(pub_time[5:7])
                day = int(pub_time[8:10])
                return f"{month}月{day}日"
            except Exception:
                pass
        return "--"

    output = []
    articles = data.get("articles", [])

    # 按 clicksCount 降序排序
    def get_clicks(item):
        try:
            return int(item.get("clicksCount", 0) or 0)
        except (ValueError, TypeError):
            return 0

    articles_sorted = sorted(articles, key=get_clicks, reverse=True)
    if max_items is not None:
        articles_sorted = articles_sorted[:max_items]

    total_count = len(articles)

    if total_count == 0:
        keyword = data.get("keyword", "")
        output.append(f"# 公众号爆款数据分析报告\n\n**关键词**：{keyword}\n\n")
        output.append("---\n\n")
        output.append("## 暂无相关爆款数据\n\n")
        output.append(f"很抱歉，当前关键词 **「{keyword}」** 尚未有足够的爆款文章数据。\n\n")
        output.append("### 可能原因\n\n")
        output.append("- 该关键词相对小众或新兴，爆款内容积累较少\n")
        output.append("- 近期该赛道热度较低，暂无突出爆款文章\n")
        output.append("- 关键词表述方式可以更加具体或热门\n\n")
        output.append("### 建议操作\n\n")
        output.append("- 更换为更热门的关键词，如：**\"职场成长\"**、**\"美食\"**、**\"情感故事\"** 等\n")
        output.append("- 尝试更细分的长尾关键词\n")
        output.append("- 输入其他感兴趣的领域或赛道进行追踪\n\n")
        output.append("---\n\n")
        output.append("*数据来源：公众号爆款雷达，每日更新最新热门内容*\n")
        return "\n".join(output)

    output.append(f"\n### 爆款文章（{time_range}，按阅读数排序，共 {total_count} 条）\n")
    output.append("| 序号 | 发布时间 | 标题 | 作者 | 阅读数 | 在看数 |")
    output.append("|------|----------|------|------|--------|--------|")

    for idx, item in enumerate(articles_sorted, 1):
        author = item.get("author", "") or "未知"
        title = process_title(item)
        url = item.get("url", "")
        title_with_link = f"[{title}]({url})" if url else title
        pub_time = format_time(item)
        clicks = format_num(item.get("clicksCount", 0))
        watches = format_num(item.get("watchCount", 0))

        output.append(f"| {idx} | {pub_time} | {title_with_link} | {author} | {clicks} | {watches} |")

    return "\n".join(output)


def main():
    """主函数"""
    parser = argparse.ArgumentParser(description="公众号爆款封面数据查询工具")
    parser.add_argument("--keyword", required=True, help="搜索关键词（多个用逗号分隔，空字符串查全站热门）")
    parser.add_argument(
        "--max-items",
        type=int,
        default=20,
        help="最多展示文章数量（默认20条）",
    )
    parser.add_argument(
        "--output-format",
        choices=["text", "json", "markdown"],
        default="json",
        help="输出格式：text / json（默认）/ markdown",
    )
    parser.add_argument("--output-file", type=str, default=None, help="输出文件路径")
    parser.add_argument("--start-date", type=str, default=None, help="开始日期，格式 yyyy-MM-dd（默认不传，接口自行决定）")
    parser.add_argument("--end-date", type=str, default=None, help="结束日期，格式 yyyy-MM-dd（默认不传，接口自行决定）")
    parser.add_argument("--debug", action="store_true", help="启用调试模式")

    args = parser.parse_args()

    try:
        data = fetch_wx_covers(
            args.keyword,
            debug=args.debug,
            start_date=args.start_date,
            end_date=args.end_date,
        )

        # 生成输出内容
        if args.output_format == "json":
            output_content = json.dumps(data, ensure_ascii=False, indent=2)
        elif args.output_format == "markdown":
            markdown_header = f"# 公众号爆款数据分析报告\n\n**关键词**：{args.keyword}\n\n"
            output_content = markdown_header + format_output(data, max_items=args.max_items, start_date=args.start_date)
        else:
            output_content = format_output(data, max_items=args.max_items, start_date=args.start_date)

        output_file = args.output_file

        if output_file:
            with open(output_file, "w", encoding="utf-8") as f:
                f.write(output_content)
            print(f"✓ 结果已保存到: {output_file}", file=sys.stderr)
            print(f"✓ 关键词: {args.keyword}", file=sys.stderr)
            total = len(data.get("articles", []))
            print(f"✓ 总计: {total} 条数据", file=sys.stderr)
            cover_urls = get_cover_urls(data, max_items=3)
            if cover_urls:
                print(f"\n=== 封面图URL（用于风格分析）===", file=sys.stderr)
                for i, item in enumerate(cover_urls, 1):
                    print(f"{i}. {item['title']}: {item['cover_url']}", file=sys.stderr)
            else:
                print("\n⚠️ 接口未返回 imageUrl/coverUrl 字段，无法提取封面图URL", file=sys.stderr)
        else:
            print(output_content)
            print(f"\n✓ 关键词: {args.keyword}", file=sys.stderr)
            total = len(data.get("articles", []))
            print(f"✓ 总计: {total} 条数据", file=sys.stderr)

        print(f"\n另外红狐配套全量数据库可提供完整详实数据，如需了解采购方案，可发送邮件至 redfoxdata@proton.me 对接咨洵")

    except Exception as e:
        print(f"❌ 错误: {str(e)}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()