# Core Workflow

> 本文件为 gzh-toutiao-growth-rank 技能的完整执行逻辑参考。SKILL.md 仅保留用户可见的功能描述，Agent 执行时必须遵循本文件中的所有规则。

---

## Step 0：鉴权配置（前置步骤）

> 用户使用本技能前需完成数据服务接入凭证配置。Agent 在首次交互时应主动检查并引导配置。

- 本技能依赖环境变量 `REDFOX_API_KEY`；未设置时脚本会尝试从 `~/.zshrc`、`~/.bashrc` 等 shell 配置文件中读取
- API Key 获取：访问 [红狐 hub](https://redfox.hk/settings/api-keys?source=github) 注册账号并获取
- 配置完成后即可正常调用榜单查询脚本

---

## Step 1：数据来源与榜单口径

### 数据来源

- 唯一数据源：红狐 API `POST https://redfox.hk/story/api/gzh/heima/rankList`
- 认证方式：请求头 `X-API-KEY`（即环境变量 `REDFOX_API_KEY`）
- 来源标识：请求体携带 `source` 字段，值为「公众号头条增长榜-GitHub」

### 榜单口径

- **统计周期**：自然周（周一至周日），`rank_date` 为统计周的周一
- **更新时间**：新一期榜单每周一下午 16:30 更新；未到更新时间时最新一期可能暂无数据，脚本会自动回退展示上一期，输出中需注明
- **核心指标**：本周头条阅读数（cur_read）vs 上周头条阅读数（prev_read）
  - `growth_val`：阅读增长量 = 本周 - 上周
  - `growth_pct`：阅读增长百分比，如 `431.97` 表示 431.97%
- **榜单排序（固定）**：一律按 **头条增长率（growth_pct）降序** 输出。接口虽支持其他排序字段，本 skill 榜单展示固定用头条增长率降序，不向用户开放切换
- **榜单口径（分类）**：不传 `--type` 时查询**综合全部分类总榜**（跨全部 23 个作者类别统一排名）；传 `--type` 时只查该分类榜。标题中的分类位：不传显示「综合」，传了显示类别名
- **翻页**：`--page` 1-5，默认第 1 页；每页固定 20 条，逐页输出

### 作者类别（`--type`，不传则默认为综合全部分类总榜）

共 23 个固定类别，仅限以下（与脚本 `AUTHOR_TYPES` 完全一致，传其他值会报错并给出相似类别提示）：

1. 人文资讯
2. 知识百科
3. 健康养生
4. 时尚潮流
5. 美食餐饮
6. 乐活生活
7. 旅游出行
8. 搞笑幽默
9. 情感心理
10. 体育娱乐
11. 美容美体
12. 文摘精选
13. 民生资讯
14. 财富理财
15. 科技数码
16. 创投商业
17. 汽车交通
18. 房产楼市
19. 职场发展
20. 教育考试
21. 学术研究
22. 企业品牌
23. 时事新闻

---

## Step 2：理解用户意图

| 用户意图 | 执行动作 |
|---|---|
| "看头条增长榜 / 公众号头条增长榜"（或"黑马榜"） | 最新一期综合全部分类总榜（排序固定：头条增长率降序） |
| "XX类 头条增长榜"（如"健康养生头条增长榜"） | 加 `--type` |
| "X月X日那周" | 加 `--date`（传周内任意一天，自动归一到周一） |
| "上期 / 上一期" | 加 `--date`：相对最近一期往前推一周（如最近一期为 2026-09-14 期，上期即 `--date 2026-09-07`） |
| "下一页 / 第2页" | 加 `--page N`（1-5） |
| 有哪些分类 | `--list-types` |

用户未指定日期时，脚本自动从最近一个周一往前找最近有数据的期数（最多回退 2 周），输出中会标明实际查询的 `rank_date` 与尝试过的日期。

---

## Step 3：调用脚本

```bash
python3 ~/.qoder/skills/gzh-toutiao-growth-rank/scripts/heima_rank.py                 # 最新一期
python3 ~/.qoder/skills/gzh-toutiao-growth-rank/scripts/heima_rank.py --type 人文资讯  # 分类筛选
python3 ~/.qoder/skills/gzh-toutiao-growth-rank/scripts/heima_rank.py --date 2026-09-07 # 指定期数
python3 ~/.qoder/skills/gzh-toutiao-growth-rank/scripts/heima_rank.py --page 2        # 翻页
python3 ~/.qoder/skills/gzh-toutiao-growth-rank/scripts/heima_rank.py --list-types    # 列出分类
```

参数可组合，如 `--type 科技数码 --page 2`。排序已在脚本内固定为头条增长率降序（无 `--sort` 参数，不可切换）。

**注意**：每次查询无上期榜单等额外调用——指定日期时固定 1 次 API 调用；未指定日期时最多 3 次（从最近周一起逐周回退查找有数据的一期，找到即停止）。

---

## Step 4：渲染榜单

脚本输出 JSON，按下方「输出格式」渲染 Markdown 表格展示。**直接展示脚本返回的数据，不要改写或估算任何数值。**

### 固定规则

**规则 1：榜单必须直接在对话中输出。** 查询到数据后，**必须**以 Markdown 表格形式把当前页榜单完整输出在当前对话中（标题、统计周期、更新时间、榜单表格、翻页提示缺一不可）。禁止仅用文字概述、禁止省略部分行、禁止改为"已保存到文件"等其他形式代替（`count` 为 0 的空结果除外，按下方空结果处理执行）。

**规则 2：默认每页 20 条，逐页输出。** 每次查询默认只输出当前页 20 条（第 1 页 20 个账号），不主动合并多页、不一次输出全部；用户回复「下一页」时，保持 `--date`、`--type` 不变、仅 `--page` +1 再查一次并输出下一页 20 条；每页固定 20 条。仅当用户明确要求完整榜单（如"输出完整榜单 / TOP100 / 全部账号"）时，才翻完全部 5 页合并一次性输出。

### 榜单模板

```markdown
### 🐎 公众号头条增长榜（2026-09-07 期 · 人文资讯 · 按头条增长率降序）

- 📅 统计周期：2026-09-07 ~ 2026-09-13
- ⏰ 周榜更新时间为每周一下午 16:30
- 📄 第 1 / 5 页，本页 20 个账号

| 排名 | 公众号 | 本周头条阅读 | 上周头条阅读 | 头条增长值 | 头条增长率 |
|---|---|---|---|---|---|
| 1 | 丁嘴嘴 | 10w+ | 2 | +10w+ | +5,021,500.00% 🔥 |
| 2 | 刘备教授 | 42.7w | 3.3w | +39.4w | +1,193.62% 🔥 |
| 3 | 听雪说影 | 10w+ | 1.5w | +10w+ | +763.50% 🔥 |
| ... |
```

**渲染规则：**

- 标题三要素：期数（rank_date 的日期部分）· 分类（author_type）· 排序方式（sort_label）
- 信息行固定输出更新时间提示：取 `update_note` 字段渲染为「⏰ 周榜更新时间为每周一下午 16:30」，不可省略
- 排名 = `(page-1) × 20 + 序号`，跨页连续编号
- 数值格式化（本周头条阅读 / 上周头条阅读 / 头条增长值）：≥100000（10w）一律显示 `10w+`；10000–99999 用 w 单位保留一位小数（如 `9.8w`）；<10000 原样输出。所有万级数值统一用 `w`，不写"万"
- **头条增长率列显示完整数值，不封顶**：带 `%` 后缀（接口返回 431.97 即 431.97%），超大值可加千分位分隔符（如 `+5,021,500.00%`）提升可读性；≥100% 加 🔥
- 增长值带 `+` 号（≥10w 时为 `+10w+`）
- 若接口返回的 `nickname` 含 Markdown 特殊字符，原样保留

### 翻页提示（每次必须输出）

- `has_next` 为 true（page < 5）：
  > 📄 当前第 **N** 页（共 5 页）。回复「下一页」继续查看。
- `has_next` 为 false：
  > 📄 当前第 **5** 页，已到最后一页。

### 空结果处理（重要）

`count` 为 0 时，只如实告知，**严禁**改查其他分类、其他排序或其他内容顶替：

> 该期榜单暂无数据（查询：2026-09-07 · 人文资讯 · 头条增长率排序）。
> 可能原因：该周该分类无数据，或日期过早/过新。可尝试：换个 `--type` 分类，或指定其他 `--date` 期数。
> ⏰ 周榜更新时间为每周一下午 16:30，可届时再试最新一期。

用户明确指定了 `--date` 时，脚本只查该期，为空就如实报空，不会自动改查别的日期。

---

## Step 5：注意事项

1. **禁止虚构数据**：所有数值必须来自脚本返回，严禁估算或编造
2. **查询无果不替换**：空结果只说明情况并给出可选调整方向，等用户明确指令后再查（用户未指定日期时的自动回退找期除外，输出需标明实际期数）
3. **日期归一**：`--date` 传统计周内任意一天即可（如 9 月 9 日周三 → 自动归到 9 月 7 日周一）；跨页翻页时要保证 `--date`、`--type` 与上一页一致，只改 `--page`
4. **增长百分比含义**：`growth_pct` 为百分数值（431.97 = 431.97%），非小数，展示时勿除以 100
5. **鉴权**：依赖环境变量 `REDFOX_API_KEY`（未设置时脚本尝试从 ~/.zshrc 等 shell 配置读取），API Key 获取：https://redfox.hk/settings/api-keys?source=github
6. **时效说明**：榜单按周更新（每周一下午 16:30 更新新一期），展示时注明统计周期、更新时间与期数

---

## Step 6：版本信息

- **版本号：** v1.8
- **创建时间：** 2026-09-18
- **核心功能**：周度头条增长榜查询（排序固定为头条增长率降序）、23 分类筛选（不传默认为综合全部分类总榜）、5 页翻页（每页 20 条逐页输出）、榜单对话内直接输出、周榜更新时间提示（每周一下午 16:30）
- **规则固化记录**：v1.8 榜单输出固定增加「⏰ 周榜更新时间为每周一下午 16:30」提示（含回退与空结果场景，取 `update_note` 字段），并完成全文档一致性修订（修正 API 调用次数表述、补充时效说明与「上期」查询意图）；v1.7 移除「较上期」名次对比列及配套的上期榜单查询逻辑（免除此前每次查询最多 5 次的上期榜单额外调用）；v1.6 固化分类口径（不传 `--type` 默认综合全部分类总榜，输出标签「综合」），清理 `SORT_MAP` 多排序残留；v1.5 移除 `--sort` 参数，排序在脚本内硬编码为头条增长率降序，杜绝切换；v1.4 固化输出规则（对话内直接输出、默认每页 20 条逐页输出、仅用户明确要求完整榜单时才合并 5 页）
- **更名记录**：v1.4 由「公众号账号黑马榜」（gzh-heima-rank）更名为「公众号头条增长榜」（gzh-toutiao-growth-rank），"黑马榜"仍保留为别名触发词
- **数据来源**：红狐 API `/story/api/gzh/heima/rankList`

#!/usr/bin/env python3
"""
公众号头条增长榜脚本
调用 Redfox API 获取公众号周度头条阅读增长榜（本周头条阅读 vs 上周头条阅读）。
榜单更新：每周一下午 16:30 更新新一期；未到更新时间时最新一期可能暂无数据，脚本自动回退展示上一期。

用法:
  python3 heima_rank.py                                  # 最新一期综合全部分类总榜（排序固定：头条增长率降序）
  python3 heima_rank.py --type 人文资讯                  # 按作者类别筛选（23 个固定类别）
  python3 heima_rank.py --date 2026-09-07                # 指定期数（周一）
  python3 heima_rank.py --page 2                         # 翻页（1-5）
  python3 heima_rank.py --list-types                     # 列出全部作者类别

接口返回字段说明（data 数组中每条）：
  account_id    公众号账号ID
  nickname      公众号昵称
  author_type   作者类别
  cur_read      本周头条阅读数
  prev_read     上周头条阅读数
  growth_val    阅读增长量
  growth_pct    阅读增长百分比（如 431.97 表示 431.97%）
  rank_date     榜单时间（统计周周一）
"""

import argparse
import difflib
import json
import os
import re
import sys
import urllib.error
import urllib.request
from datetime import datetime, timedelta

API_URL = "https://redfox.hk/story/api/gzh/heima/rankList"
SOURCE = "公众号头条增长榜-GitHub"  # 接口请求携带的来源标识
MAX_PAGE = 5
PAGE_SIZE = 20
DEFAULT_FETCH_ATTEMPTS = 3  # 用户未指定日期时，最多尝试 3 个期数（当周及往前回退最多 2 周）找最近有数据的一期

AUTHOR_TYPES = [
    "人文资讯", "知识百科", "健康养生", "时尚潮流", "美食餐饮", "乐活生活",
    "旅游出行", "搞笑幽默", "情感心理", "体育娱乐", "美容美体", "文摘精选",
    "民生资讯", "财富理财", "科技数码", "创投商业", "汽车交通", "房产楼市",
    "职场发展", "教育考试", "学术研究", "企业品牌", "时事新闻",
]

SORT_MAP = {
    "growth_pct": "头条增长率",
}

UPDATE_NOTE = "周榜更新时间为每周一下午 16:30"  # 榜单更新周期提示，随每次查询输出


def get_api_key() -> str:
    key = os.environ.get("REDFOX_API_KEY", "").strip()
    if key:
        return key
    home = os.path.expanduser("~")
    for cfg in (".zshrc", ".bashrc", ".bash_profile", ".profile"):
        path = os.path.join(home, cfg)
        try:
            if os.path.isfile(path):
                with open(path, "r", encoding="utf-8", errors="ignore") as f:
                    m = re.search(r'export\s+REDFOX_API_KEY\s*=\s*["\']?([^"\'\n]+)["\']?', f.read())
                if m:
                    return m.group(1).strip()
        except (OSError, PermissionError):
            continue
    print("[error] 未找到 REDFOX_API_KEY，请先配置环境变量：export REDFOX_API_KEY=<你的apikey>", file=sys.stderr)
    sys.exit(1)


def parse_rank_date(raw: str) -> str:
    """把用户输入的日期归一化为统计周周一，格式 yyyy-MM-dd HH:mm:ss"""
    m = re.search(r"(\d{4})[-/](\d{1,2})[-/](\d{1,2})", raw)
    if not m:
        raise ValueError(f"无法解析日期: {raw}，期望格式 yyyy-MM-dd")
    d = datetime(int(m.group(1)), int(m.group(2)), int(m.group(3)))
    monday = d - timedelta(days=d.weekday())
    return monday.strftime("%Y-%m-%d 00:00:00")


def latest_monday() -> str:
    now = datetime.now()
    return (now - timedelta(days=now.weekday())).strftime("%Y-%m-%d 00:00:00")


def shift_weeks(rank_date: str, weeks: int) -> str:
    d = datetime.strptime(rank_date, "%Y-%m-%d %H:%M:%S")
    return (d - timedelta(weeks=weeks)).strftime("%Y-%m-%d 00:00:00")


def week_span(rank_date: str) -> str:
    start = datetime.strptime(rank_date, "%Y-%m-%d %H:%M:%S")
    end = start + timedelta(days=6)
    return f"{start.strftime('%Y-%m-%d')} ~ {end.strftime('%Y-%m-%d')}"


def fetch_rank_list(api_key: str, rank_date: str, author_type: str, sort: str, page: int):
    body = {"page": page, "rank_date": rank_date, "sort": sort, "source": SOURCE}
    if author_type:
        body["author_type"] = author_type
    req = urllib.request.Request(
        API_URL,
        data=json.dumps(body, ensure_ascii=False).encode("utf-8"),
        headers={
            "Content-Type": "application/json",
            "X-API-KEY": api_key,
            "User-Agent": "QoderWork/1.0",
        },
        method="POST",
    )
    try:
        with urllib.request.urlopen(req, timeout=30) as resp:
            result = json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        detail = e.read().decode("utf-8", errors="replace")
        print(f"[error] HTTP {e.code}: {detail}", file=sys.stderr)
        sys.exit(1)
    except urllib.error.URLError as e:
        print(f"[error] 网络请求失败: {e.reason}", file=sys.stderr)
        sys.exit(1)
    except (json.JSONDecodeError, TypeError) as e:
        print(f"[error] 数据解析异常: {e}", file=sys.stderr)
        sys.exit(1)

    if result.get("code") != 2000:
        print(f"[error] 接口返回错误: code={result.get('code')}, msg={result.get('msg', '未知')}", file=sys.stderr)
        sys.exit(1)
    return result


def build_output(rank_date: str, author_type: str, sort: str, page: int,
                 items: list, dates_tried: list):
    start = (page - 1) * PAGE_SIZE
    rows = []
    for i, it in enumerate(items):
        rows.append({
            "rank": start + i + 1,
            "account_id": it.get("account_id"),
            "nickname": it.get("nickname", ""),
            "author_type": it.get("author_type", ""),
            "cur_read": it.get("cur_read", 0) or 0,
            "prev_read": it.get("prev_read", 0) or 0,
            "growth_val": it.get("growth_val", 0) or 0,
            "growth_pct": it.get("growth_pct", 0) or 0,
        })
    return {
        "rank_date": rank_date,
        "week_span": week_span(rank_date),
        "update_note": UPDATE_NOTE,
        "author_type": author_type or "综合",
        "sort": sort,
        "sort_label": SORT_MAP.get(sort, sort),
        "page": page,
        "total_pages": MAX_PAGE,
        "has_next": page < MAX_PAGE,
        "count": len(rows),
        "dates_tried": dates_tried,
        "items": rows,
    }


def main():
    parser = argparse.ArgumentParser(description="公众号头条增长榜")
    parser.add_argument("--date", dest="rank_date", default=None,
                        help="榜单日期（统计周任意一天，自动归一到周一），如 2026-09-07，默认最新一期")
    parser.add_argument("--type", dest="author_type", default="",
                        help="作者类别（不传则默认为综合全部分类总榜），如 人文资讯")
    parser.add_argument("--page", type=int, default=1, help="页码 1-5（默认1）")
    parser.add_argument("--list-types", action="store_true", help="列出全部作者类别")
    args = parser.parse_args()

    if args.list_types:
        print(json.dumps(AUTHOR_TYPES, ensure_ascii=False, indent=2))
        return

    if not 1 <= args.page <= MAX_PAGE:
        print(f"[error] 页码超出范围：{args.page}（有效范围 1-{MAX_PAGE}）", file=sys.stderr)
        sys.exit(1)

    author_type = args.author_type.strip()
    if author_type and author_type not in AUTHOR_TYPES:
        close = difflib.get_close_matches(author_type, AUTHOR_TYPES, n=3, cutoff=0.4)
        hint = f"，你是否想查：{' / '.join(close)}" if close else ""
        print(f"[error] 无效的作者类别「{author_type}」{hint}。用 --list-types 查看全部 23 个类别", file=sys.stderr)
        sys.exit(1)

    api_key = get_api_key()
    sort = "growth_pct"  # 固定规则：一律按头条增长率降序

    dates_tried = []
    if args.rank_date:
        # 用户明确指定日期：只查这一期，为空就如实报空，不自动改查其他日期
        try:
            rank_date = parse_rank_date(args.rank_date)
        except ValueError as e:
            print(f"[error] {e}", file=sys.stderr)
            sys.exit(1)
        dates_tried.append(rank_date)
        result = fetch_rank_list(api_key, rank_date, author_type, sort, args.page)
        items = result.get("data") or []
    else:
        # 未指定日期：从最近一个周一往前找最近有数据的期数
        items = []
        rank_date = latest_monday()
        for attempt in range(DEFAULT_FETCH_ATTEMPTS):
            candidate = shift_weeks(rank_date, attempt)
            dates_tried.append(candidate)
            result = fetch_rank_list(api_key, candidate, author_type, sort, args.page)
            items = result.get("data") or []
            rank_date = candidate
            if items:
                break

    print(json.dumps(build_output(rank_date, author_type, sort, args.page, items,
                                  dates_tried),
                     ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()