Music Weekly — 音乐周报

一个可配置的每周音乐推荐系统。自动搜索各地区的本周新专辑，评分筛选≥7.5分的优质作品，写入 Notion 数据库，并通过你设定的频道推送到你手上。

目录

1. 快速开始
2. 配置详解
3. 推送频道设置
4. 核心概念
5. 工作流
6. 脚本工具
7. 自定义主题
8. 故障排除

快速开始

安装

npx clawhub install music-weekly
cd skills/music-weekly

一行初始化（推荐）

python3 scripts/setup.py

按提示输入 Notion API Key 和推送目标即可。脚本会自动：

静默模式（传参）

python3 scripts/setup.py \
  --notion-key "ntn_你的密钥" \
  --parent-page "父页面ID" \
  --channel telegram \
  --target "123456789"

默认值

不配置时脚本自动使用以下路径（基于 OpenClaw 工作区约定）：

手动验证

python3 scripts/notion_utils.py config

如果返回了你的配置摘要（key 会被部分隐藏），就说明配好了。

配置详解

❌ = 自动填充默认值，不填也能用 ✅ = 必须填写 ⚠️ = 可用 setup 脚本自动创建

环境变量 NOTION_KEY 也可作为 notion_api_key 的备用来源。

Notion 数据库要求

数据库必须包含以下字段（字段名精确匹配）：

封面URL 字段类型是 files 不是 url，这是一个常见坑。写入时使用外部文件格式，详见「核心概念」章节。

推送频道设置

支持的所有频道

推送内容格式

所有频道通用文字模板：

{sender_name} | {week_label}

━━━━━━━━━━━━━━━━━━

{序号}️⃣ {艺术家} — {专辑名}
📅 发行日期：yyyy-mm-dd
🏷️ {流派}
⭐ 综合评分：{分数}/10
💬 {推荐理由}

Apple Music: {链接}
━━━━━━━━━━━━━━━━━━

...（重复5张）

✨ 本周编辑精选 | {一句话总结}

不同频道的封面图发送方式

QQ Bot： 使用 \x3Cqqmedia> 标签嵌入到消息中。图片文件需先复制到配置的 media_dir 目录。

🎵 本周音乐精选 | 2026年5月15日
\x3Cqqmedia>/home/user/media/music/cover.jpg\x3C/qqmedia>

1️⃣ Broken Social Scene — Remember The Humans
📅 发行日期：2026-05-08
...

Telegram / Discord / Signal 等： 使用 message 工具的 media 参数，直接传本地文件路径。

⚠️ 原则：封面图和文字必须在同一条消息中发送，不要分开推送。

核心概念

1. 周次命名规则

2. 地区比例（每期5张）

补充规则： 如果某周某地区确实找不到≥7.5分的好专辑，可从英语圈补位。但华语和日韩至少各保留候选席位，不要连续多周只有英语专辑。

3. 评分标准

• 基准线：≥7.5分
• 优先推荐：≥8.0分
• 低于7.5分不推荐
• 8分以下的专辑必须有充分理由才能推
• 禁止编造评分：所有分数必须来自 Apple Music、Pitchfork、RateYourMusic、Metacritic、AllMusic、QQ音乐、网易云音乐等真实可查的平台
• 综合评分取多平台加权平均

4. 封面URL 是 files 类型

Notion 的「封面URL」字段类型是 files，不是 url。这是最常见的报错来源。

✅ 正确写法：

"封面URL": {
  "files": [{
    "type": "external",
    "name": "cover.jpg",
    "external": {
      "url": "https://is1-ssl.mzstatic.com/.../600x600bb.jpg"
    }
  }]
}

❌ 错误写法（会报 封面URL is expected to be files）：

"封面URL": {
  "url": "https://is1-ssl.mzstatic.com/..."
}

5. 查重规则

每次推荐前必须读取 music-recommended-log.md 全部历史记录。同一张专辑（相同艺术家+专辑名或相同 Apple Music ID）永远不重复推荐，无论相隔多少周。

工作流

完整的工作流步骤见 references/workflow.md，此处为概要：

Step 0: 读取历史 log，建立已推荐清单
Step 1: 搜索本周新发行（按地区分工）
Step 2: 筛选候选池（评分≥7.5，发行≤1个月）
Step 3: 逐一查重
Step 4: 跨地区平衡（最终5张）
Step 5: 收集详细信息（iTunes API获取封面、厂牌、曲目数等）
Step 6: 写入 Notion（封面URL用 files 格式）
Step 7: 推送消息（文字+封面图一起发）
Step 8: 追加到历史 log

脚本工具

scripts/notion_utils.py

# 搜索专辑信息（iTunes API）
python3 scripts/notion_utils.py search "NMIXX" "Heavy Serenade"

# 通过 Apple Music 链接获取封面图 URL
python3 scripts/notion_utils.py artwork "https://music.apple.com/us/album/remember-the-humans/1871484971"

# 查看当前配置
python3 scripts/notion_utils.py config

# 补填数据库中所有缺失的封面URL
python3 scripts/notion_utils.py backfill

# 查看配置文件路径
python3 scripts/notion_utils.py config-path

在 Python 中调用

from scripts.notion_utils import (
    search_itunes,
    get_artwork_from_apple_link,
    create_record,
    update_cover_url,
    query_all,
    get_config,
)

# 搜索专辑
info = search_itunes("Broken Social Scene", "Remember The Humans")
# info 包含: artist, album, release_date, artwork_url,
#            apple_music_url, track_count, copyright, genre

# 创建 Notion 记录
create_record({
    "名称": info["album"],
    "艺术家": info["artist"],
    "发行日期": info["release_date"],
    "流派": info["genre"],
    "综合评分": 8.0,
    "收听状态": "未听",
    "专辑类型": "全长" if info["track_count"] >= 10 else "EP",
    "厂牌": info["copyright"].replace("℗ ", ""),
    "推荐理由": "这是一张出色的专辑...",
    "Apple Music链接": info["apple_music_url"],
    "音乐分布": ["🇨🇦 加拿大"],
    "周次": "2026年第20周 2期",
    "推送日期": "2026-05-15",
    "封面URL": info["artwork_url"],
})

自定义主题

编辑推送消息的 sender_name 配置项可以自定义发件人名称。也可以在工作流的推送步骤中自定义消息格式，如：

• 增加 emoji 装饰
• 调整信息排列顺序
• 加入个人化的编辑推荐语

推送消息的完整模板见 references/workflow.md 的「推送」章节。

故障排除

「封面URL is expected to be files」

原因： 用了 url 类型写入，但该字段在 Notion 中实际是 files 类型。

解决： 使用 scripts/notion_utils.py 的 create_record() 函数（自动处理 files 格式），或参考「核心概念」章节手动构造正确的 JSON 格式。

「Could not find database with ID」

原因： Notion 集成没有连接到该数据库，或者数据库 ID 填错了。

解决：

1. 确认数据库已与你的集成共享（数据库页面右上角「…」→「连接到」→ 选择你的集成）
2. 确认配置文件中的 notion_db_id 正确（从数据库 URL 中提取 UUID）
3. 数据库中包含所需的全部字段

iTunes 搜索不到专辑

常见原因与对应策略：

重试策略： 3次搜索失败 → 放弃该候选，换下一张。不要卡死在单一专辑上。

推送消息没有封面图

• QQ Bot： 图片需要先复制到配置的 media_dir 目录，使用 \x3Cqqmedia> 标签
• 其他频道： 使用 message 工具的 media 参数传本地文件
• 文件权限问题：确保图片文件可读（chmod 644）

更多问题？在 OpenClaw Discord（https://discord.com/invite/clawd）或 ClawHub 上提出 issue。