lxmusic: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

常用命令

# 安装依赖
uv sync

# 运行测试
uv run pytest tests/ -v

# 运行单个测试
uv run pytest tests/test_tx_music.py::TestPlaylistStore::test_create_and_get -v

# 构建
uv build

# 本地安装（开发模式）
uv tool install .

# 运行 CLI
uv run lxmusic --help
uv run lxmusic search music "周杰伦"
uv run lxmusic mcp                          # 标准 MCP server

架构

lxmusic/ 包采用三层组合架构：

1. Source 层（搜索与元信息）

lxmusic/sources/__init__.py 定义 Source(ABC) 抽象基类，要求实现： search_music / search_album / get_music_info / get_album_info / get_lyric / get_audio_headers / close。

三个实现：

• tx.py — QQ 音乐（通过 musicu.fcg 接口）
• wy.py — 网易云音乐
• local.py — 本地音乐文件 + 歌单 YAML 扫描

LocalSource 特殊性：

• 扫描 cfg.local_dirs（由 music_dir 拆分而来，逗号分隔多目录）
• 同时扫描 *.yaml 文件，解析 {name, tracks} 结构为歌单
• search_album 按 YAML 中 name 字段匹配歌单名
• get_album_info 按 album_mid（歌单名）查找对应 YAML 返回曲目
• 文件 ID 使用 MD5 哈希（确定性，跨进程稳定），不能用 hash()（有随机种子）
• get_music_info 支持 songmid（文件路径）和 song_id（哈希）两种查找

2. PlayURLProvider 层（播放直链）

lxmusic/playurl.py 定义 PlayURLProvider(ABC)，实现 ShiqianjiangProvider：

• 调用 https://source.shiqianjiang.cn/api/music/url
• 需要 API 密钥（从 cfg.api_key 获取）

3. MusicClient 组合层

lxmusic/client.py 中 MusicClient 组合 Source + PlayURLProvider：

• _get_source(name) 懒加载并缓存 Source 实例（LocalSource 接收 cfg.local_dirs）
• get_play_url(song, quality) 对本地源直接返回 song.songmid（即文件路径），远程源走 PlayURLProvider
• 通过 source 参数覆盖默认音源

CLI 与 MCP

入口分发

lxmusic/main.py 根据 sys.argv[1] 分发：

• mcp → 标准 MCP server（FastMCP，stdio）
• 其他 → CLI 命令组（click）

CLI 命令组（cli.py）

search / play / download / album / playlist / config

关键实现细节：

• _resolve_play_url(client, song, quality) — 请求音质不可用时自动降级到 128k
• playlist add 支持 --limit（默认 20）自动翻页拉取搜索结果
• album 下载时若 URL 是本地路径用 shutil.copy2，否则走 _download_file
• 下载进度条通过 _progress_bar 回调显示

配置系统

lxmusic/config.py 采用两层优先级：环境变量 > config.yaml > 默认值