Music Weekly

Curate weekly music album picks with search, scoring, deduplication, Notion writing, and push to configured messaging channels.

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	✅	string	telegram	推送频道，详见下表
delivery_target	✅	string	—	推送目标 ID
covers_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	艺术家名
发行日期	date	YYYY-MM-DD
流派	select	主要 Genre
综合评分	number	10分制
收听状态	select	未听 / 已听 / 循环中 / 想听
专辑类型	select	全长 / EP / 单曲
厂牌	rich_text	厂牌名
评论来源	rich_text	如 Pitchfork, AllMusic
推荐短语	rich_text	30字以内精炼推荐
推荐理由	rich_text	100字以上推荐正文
Apple Music链接	url	Apple Music 专辑页
音乐分布	multi_select	🇺🇸 美国、🇰🇷 韩国 等
周次	rich_text	如 2026年第20周 2期
推送日期	date	实际推送日期
封面URL	files	专辑封面图（⚠️ 见下方注意）

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

---

推送频道设置

支持的所有频道

频道	delivery_channel 值	delivery_target 格式	前提
QQ Bot	qqbot	qqbot:c2c:用户OpenID	需配置 channels.qqbot
Telegram	telegram	123456789（用户ID）或 @username	需配置 channels.telegram
Discord	discord	123456789012345678（频道ID）	需配置 channels.discord
Signal	signal	[phone]	需配置 channels.signal
企业微信	wecom	用户ID	需配置 channels.wecom
飞书	feishu	ou_xxxxxxxx（open_id）	需配置 channels.feishu
Slack	slack	C1234567（频道ID）	需配置 channels.slack
WhatsApp	whatsapp	手机号	需配置 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。