Music Weekly — 音乐周报#

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

---

目录#

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

---

快速开始#

安装#

bash

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

一行初始化（推荐）#

bash

python3 scripts/setup.py

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

操作说明✅ 创建配置文件~/.config/music-weekly/config.json，默认值已填好✅ 创建目录covers_dir、media_dir 自动建立✅ 创建历史记录文件music-recommended-log.md 带表头✅ 创建 Notion 数据库所有字段齐全，直接可用

静默模式（传参）#

bash

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

默认值#

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

配置项默认值covers_dir``~/.openclaw/workspace/covers``media_dir``~/.openclaw/media/qqbot``history_log``~/.openclaw/workspace/music-recommended-log.md``sender_name``🎵 音乐编辑``delivery_channel``telegram

手动验证#

bash

python3 scripts/notion_utils.py config

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

---

配置详解#

字段必填类型默认值说明notion_api_key✅string—Notion 集成密钥，以 ntn_ 开头notion_db_id⚠️string—Notion 数据库 UUID（可用 setup.py --parent-page 自动创建）delivery_channel✅stringtelegram推送频道，详见下表delivery_target✅string—推送目标 IDcovers_dir❌string~/.openclaw/workspace/covers封面图片本地缓存目录media_dir❌string~/.openclaw/media/qqbot媒体暂存目录（QQ Bot）history_log❌string~/.openclaw/workspace/music-recommended-log.md历史推荐记录文件sender_name❌string🎵 音乐编辑推送时显示的发件人名称

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

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

Notion 数据库要求#

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

字段名类型用途名称title专辑名（仅专辑名，不含艺术家）艺术家rich_text艺术家名发行日期dateYYYY-MM-DD流派select主要 Genre综合评分number10分制收听状态select未听 / 已听 / 循环中 / 想听专辑类型select全长 / EP / 单曲厂牌rich_text厂牌名评论来源rich_text如 Pitchfork, AllMusic推荐短语rich_text30字以内精炼推荐推荐理由rich_text100字以上推荐正文Apple Music链接urlApple Music 专辑页音乐分布multi_select🇺🇸 美国、🇰🇷 韩国 等周次rich_text如 2026年第20周 2期推送日期date实际推送日期封面URLfiles专辑封面图（⚠️ 见下方注意）

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

---

推送频道设置#

支持的所有频道#

频道delivery_channel 值delivery_target 格式前提QQ Botqqbot``qqbot:c2c:用户OpenID需配置 channels.qqbotTelegramtelegram``123456789（用户ID）或 @username需配置 channels.telegramDiscorddiscord``123456789012345678（频道ID）需配置 channels.discordSignalsignal``+8613800138000需配置 channels.signal企业微信wecom用户ID需配置 channels.wecom飞书feishu``ou_xxxxxxxx（open_id）需配置 channels.feishuSlackslack``C1234567（频道ID）需配置 channels.slackWhatsAppwhatsapp手机号需配置 channels.whatsapp

推送内容格式#

所有频道通用文字模板：

text

{sender_name} | {week_label}

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

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

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

...（重复5张）

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

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

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

text

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

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

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

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

---

核心概念#

1. 周次命名规则#

批次运行日命名第1期周二2026年第{X}周 1期第2期周五2026年第{X}周 2期

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

地区数量说明🇺🇸🇬🇧 英语圈2-3张核心内容，Soul / R&B / Jazz / Indie / Electronic 等🇨🇳 华语最多1张不与日韩同周出现🇯🇵🇰🇷 日韩最多1张不与华语同周出现🌎 拉丁/其他0-1张Reggaeton / Latin Pop 等

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

3. 评分标准#

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

4. 封面URL 是 files 类型#

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

✅ 正确写法：

json

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

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

json

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

5. 查重规则#

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

---

工作流#

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

text

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#

bash

# 搜索专辑信息（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 中调用#

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 搜索不到专辑#

常见原因与对应策略：

原因策略拼写差异尝试不同的关键词组合未在 Apple Music 上线换一个候选专辑仅部分地区可用尝试用美区 iTunes 搜索

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

推送消息没有封面图#

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

---

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