Skill: romanticmysterylh/music-weekly (version 1.3.0)

--- name: music-weekly description: Weekly music album curation system — auto-search new releases across regions (English/Chinese/Japanese/Korean/Latin), score-filter ≥7.5, dedup against history, write to Notion DB, and push to your preferred channel (QQ/Telegram/Discord/Signal/WeCom/Feishu). Includes one-command setup script that creates the Notion database from scratch, config file with sensible defaults, and all required directories. Ideal for cron-driven music recommendation workflows. Use when: (1) running weekly music recommendation cron, (2) user asks "本周有什么好专辑", (3) user needs to fix/backfill cover URLs, (4) setting up the music weekly system for the first time. --- # 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` | `+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**。这是最常见的报错来源。 **✅ 正确写法：** ```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`](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` ```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`](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。


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)