Music Chart Aggregator：全球音乐榜单聚合器

每月自动检索全球 8 大音乐平台的热门歌曲，收集排名、播放量、销量等数据，进行跨平台综合排名和专业评价。

---

Phase 0: 前置准备

0.1 确定报告周期

报告覆盖刚结束的日历月，而非当前月：

• 如果今天是当月 1-3 日 → 覆盖上个月（因为上月数据刚刚完整）
• 如果今天是当月 4 日以后 → 也覆盖上个月（做上月月度总结）
• 用户手动运行时可能指定任意月份

report_year = 年份
report_month = 月份数字 (1-12)
report_month_name = 英文月份名 (如 "June 2026")
report_month_zh = 中文月份名 (如 "6月")
period_start = "{year}-{month:02d}-01"
period_end = "{year}-{month:02d}-{last_day}"  # 该月最后一天
output_label = "{year}-{month:02d}"  # 如 "2026-06"

0.2 创建输出目录

mkdir -p "C:\Users\asus\Music-Charts\{output_label}"

输出路径：

• 原始数据: C:\Users\asus\Music-Charts\{output_label}\raw_data.json
• 归一化数据: C:\Users\asus\Music-Charts\{output_label}\normalized_data.json
• 聚合评分: C:\Users\asus\Music-Charts\{output_label}\aggregate_scores.json
• 最终报告: C:\Users\asus\Music-Charts\{output_label}\report.md

---

Phase 1: 并行收集 8 个平台数据

核心原则

• 每个平台尽可能用 1 次 WebSearch 完成（数据不足时追加 1 次补充查询）
• 独立平台之间并行执行 WebSearch 调用
• 搜索关键词模板见 references/source-catalog.md
• 将 <target_month> 替换为 {report_month_name} {report_year}
• 将 <target_month_zh> 替换为 {report_month_zh}

1.1 执行搜索

按 references/source-catalog.md 中定义的搜索查询模板，对以下 8 个平台依次执行 WebSearch：

| # | 平台 key | 平台名 | 搜索查询 | |---|----------|--------|----------| | 1 | billboard | Billboard Hot 100 | "Billboard Hot 100 top 10 {month} {year}" | | 2 | spotify | Spotify Global | "spotify global top 50 {month} {year} songs" | | 3 | qq_music | QQ音乐 热歌榜 | "QQ音乐热歌榜 TOP10 {中文月份}" | | 4 | youtube | YouTube Music | "YouTube Music top songs global {month} {year}" | | 5 | uk_charts | UK Official Charts | "UK Official Singles Chart top 10 {month} {year}" | | 6 | oricon | Oricon Japan | "Oricon Japan weekly singles top 10 {month} {year}" | | 7 | apple_music | Apple Music | "Apple Music top songs global {month} {year}" | | 8 | netease | 网易云音乐 | "网易云音乐热歌榜 TOP10 {中文月份}" |

1.2 解析搜索结果

从每个平台的搜索片段中提取数据。详细解析规则见 references/source-catalog.md。

每条记录必须提取的字段：

• rank: 整数排名
• artist: 艺人名（原始格式）
• title: 歌曲名（原始格式）

尽可能提取的字段：

• movement: 走势（+N / -N / 0 / NEW / RE）
• weeks: 在榜周数
• peak: 最高排名
• streams / views / sales: 流量/销量数字（解析为原始数字）
• chart_score: 榜单指数（QQ Music 专用）
• notes: 任何额外上下文

1.3 写原始数据

将所有 8 个平台的解析结果写入 raw_data.json：

{
  "report_period": "2026-06",
  "generated_at": "2026-07-01T09:03:00Z",
  "sources": {
    "billboard": {
      "status": "ok",
      "entries": [
        {"rank": 1, "artist": "...", "title": "...", "movement": "+2", "weeks": 12}
      ]
    }
  }
}

status 取值：

• "ok" — 数据完整
• "partial" — 部分数据（搜索返回了结果但不完整）
• "stale" — 搜索返回了错误时间段的数据
• "no_data" — 完全搜不到数据

1.4 针对缺失数据的策略

如果某平台的搜索未返回目标月数据：

1. 追加一次针对性更强的查询（见 source-catalog.md 中每个源的"补充查询"）
2. 若仍无结果 → 该源 status 标记为 "no_data" 或 "stale"
3. 该源从当月评分中排除（aggregate.py 会自动重新分配权重）

---

Phase 2: 归一化 & 评分

2.1 运行归一化脚本

python "C:\Users\asus\.claude\skills\music-chart-aggregator\scripts\normalize.py" \
  "C:\Users\asus\Music-Charts\{output_label}\raw_data.json" \
  "C:\Users\asus\Music-Charts\{output_label}\normalized_data.json"

该脚本为每条记录附加：

• chart_position_score: 排名分（#1=100, #2=90, ... #10=10）
• volume_score: 流量分（有 volume 数据的平台 min-max 归一化到 0-100）
• composite_score: 综合分（0.6×排名分 + 0.4×流量分）

2.2 运行聚合脚本

python "C:\Users\asus\.claude\skills\music-chart-aggregator\scripts\aggregate.py" \
  "C:\Users\asus\Music-Charts\{output_label}\normalized_data.json" \
  "C:\Users\asus\Music-Charts\{output_label}\aggregate_scores.json"

该脚本：

• 跨平台去重（同艺人+同歌曲名合并，英文统一小写比较）
• 按平台权重计算加权总分
• 应用跨平台加成（1平台×1.0 → 5+平台×1.6）
• 输出 Top 20 综合排名表

2.3 读取评分结果

Read aggregate_scores.json 获取最终排名数据，用于填充报告。

2.4 脚本失败时的降级方案

如果 Python 脚本因任何原因无法运行：

1. 打印错误信息，标注 "脚本执行失败，降级为手动评分"
2. 手动按 references/scoring-formula.md 中的公式计算
3. 在报告的数据质量部分注明 "Manual scoring — scripts unavailable"

---

Phase 3: 生成报告

3.1 读取报告模板

Read templates/report-template.md 了解报告结构。

3.2 填充数据

从 aggregate_scores.json 中提取数据填充模板中的 {{PLACEHOLDER}} 变量。

需要 AI 撰写的内容（不可模板化）：

• 执行摘要 2-3 段：本月市场整体趋势、流派主导情况、东西方市场差异、值得关注的跨市场现象
• 每个平台分榜的开头段落：该平台本月的特色和变化
• 市场分析 4.1-4.5：美国/中国/日本市场深度分析 + 跨市场趋势 + 流派趋势
  • 对比中美日三国榜单差异（哪些歌手只在某个市场火？）
  • K-pop / Latin / Afrobeats / C-pop 等流派的全球渗透情况
  • 是否有独立音乐人突围？
  • 是否有"短视频带火老歌"现象？
• 每首歌的简短评价（在综合排名表中添加"点评"列，一句话即可）

撰写风格要求：

• 像专业乐评人一样写，有观点，不干巴巴列数据
• 指出有趣的规律和反常现象
• 中英混合自然（艺人名/歌名保留原文，分析用中文）
• 语气轻松但专业，类似 Billboard 官方 recaps 的风格

3.3 写入报告文件

Write 最终报告到 C:\Users\asus\Music-Charts\{output_label}\report.md。

---

Phase 4: 自调度下一轮

4.1 计算下月执行时间

当前日期 = today
如果 today.month == 12:
    next_month = 1, next_year = today.year + 1
否则:
    next_month = today.month + 1, next_year = today.year

cron_expression = "3 9 1 {next_month} *"
# 使用分钟 3 而不是 0/30，避开整点半点的高峰期
# 举例: next_month=8 → "3 9 1 8 *"

4.2 调用 CronCreate

一次性 cron（recurring: false），持久保存（durable: true）：

CronCreate({
  "cron": "{cron_expression}",
  "prompt": "SKILL: music-chart-aggregator — 执行 {report_month_name} {report_year} 月度音乐榜单聚合。从 8 个平台收集数据，生成跨平台综合排名报告并保存到 C:\\Users\\asus\\Music-Charts\\。",
  "recurring": false,
  "durable": true
})

4.3 告知用户

在 Phase 5 的摘要中展示：

⏰ 下次自动运行: {next_run_date} ⚠️ cron 任务约 7 天后过期。如果下月未自动触发，手动运行 /music-chart-aggregator 即可恢复链路。

---

Phase 5: 验证 & 摘要

5.1 结构完整性检查

• [ ] 报告包含全部 8 个平台分榜章节
• [ ] 综合 Top 20 至少包含 10 条有效记录
• [ ] Sources 章节列出了所有使用的搜索 URL
• [ ] 报告无 {{PLACEHOLDER}} 残留
• [ ] 无 [TODO] 或 [FILL] 标记

5.2 数据合理性检查

• [ ] 第一名统一评分在 55-95 之间
• [ ] Top 20 末尾评分在 3-25 之间
• [ ] 至少 1 首歌出现在 2+ 平台（跨平台验证通过）
• [ ] 无同名歌曲重复（去重失败检查）

5.3 调度确认

• [ ] CronCreate 返回成功
• [ ] 下月运行时间已记录在报告页脚

5.4 如果检查失败

• 记录具体失败项
• 在报告"数据质量说明"中添加备注
• 不阻塞报告生成 — 部分报告比没有报告好

5.5 向用户展示摘要

📊 月度音乐榜单报告生成完成！

🏆 Top 3:
  1. Artist - Title (XX.X 分 | 覆盖 X/8 平台)
  2. Artist - Title (XX.X 分 | 覆盖 X/8 平台)
  3. Artist - Title (XX.X 分 | 覆盖 X/8 平台)

📈 统计:
  - 追踪歌曲: N 首（跨平台热歌: M 首）
  - 可用数据源: X/8
  - 不可用数据源: [列表]（如有）

📁 报告位置: C:\Users\asus\Music-Charts\{YYYY-MM}\report.md
⏰ 下次运行: {next_run_date}

---

手动运行

用户可以通过以下方式手动触发：

• 直接说 "运行音乐榜单" / "生成月度音乐报告" / "music chart report" / "全球音乐排行"
• 或输入 /music-chart-aggregator

指定月份运行

如果用户想指定特定月份（非当前月）：

用户: "生成 2026 年 5 月的音乐榜单"
→ 将 Phase 0 中的 report_month 设为用户指定的月份
→ 其余流程不变

---

恢复断开链路

如果自动调度链路断开（例如上月的 cron 过期未触发）：

1. 用户手动运行一次本技能
2. Phase 4 会重新创建下月的 cron
3. 链路恢复

用户可随时通过 CronList 查看当前是否有待执行的 cron 任务。

---

技能文件索引

| 文件 | 用途 | |------|------| | SKILL.md | 本文件 — 完整执行指令 | | references/source-catalog.md | 8 个平台的搜索模板和数据解析规则 | | references/scoring-formula.md | 评分公式完整推导 | | templates/report-template.md | 月度报告骨架模板 | | scripts/normalize.py | 排名/流量归一化脚本 | | scripts/aggregate.py | 跨平台聚合排名脚本 |