Music Weekly

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

Audits

Pass

ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install music-weekly

Music Weekly — 音乐周报

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

快速开始

安装

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

一行初始化（推荐）

python3 scripts/setup.py

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

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

静默模式（传参）

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`

手动验证

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`	`+8613800138000`	需配置 `channels.signal`
企业微信	`wecom`	用户ID	需配置 `channels.wecom`
飞书	`feishu`	`ou_xxxxxxxx`（open_id）	需配置 `channels.feishu`
Slack	`slack`	`C1234567`（频道ID）	需配置 `channels.slack`
WhatsApp	`whatsapp`	手机号	需配置 `channels.whatsapp`

推送内容格式

所有频道通用文字模板：

{sender_name} | {week_label}

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

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

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

...（重复5张）

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

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

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

🎵 本周音乐精选 | 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。这是最常见的报错来源。

✅ 正确写法：

"封面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 填错了。

解决：

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

iTunes 搜索不到专辑

常见原因与对应策略：

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

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

推送消息没有封面图

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

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