Last.fm 技能通过命令行工具 lastfm-cli 与 Last.fm 音乐数据 API 交互，覆盖收听历史查询、音乐发现、排行榜、搜索、标签浏览以及写入操作。
用途 该技能适用于回答与 Last.fm 音乐数据相关的问题，例如查询某用户最近在听什么、获取收听统计、发现相似艺人或曲目、查看全球或地区流行趋势、按流派标签探索音乐，以及以编程方式 scrobble 或标记喜爱曲目。
主要能力 用户查询：获取用户资料与统计、最近收听曲目、按周期（7天、1个月、3个月、6个月、12个月或全部）统计的顶级艺人和曲目、喜爱的曲目、好友关系以及可用的周榜周期。 音乐发现：查找相似艺人（基于协同过滤的品味图邻居）、艺人信息（简介、统计、标签）、艺人热门曲目、曲目级相似推荐、专辑信息（曲目列表、元数据），以及按标签浏览顶级艺人。 排行榜：获取全球顶级艺人、按国家/地区的顶级艺人和曲目、按流派标签的顶级曲目。 搜索：按名称搜索艺人、专辑和曲目。 写入操作（需会话认证）：scrobble 曲目、设置正在播放、标记喜爱曲目。
使用方式 首先需设置环境变量：export LASTFM_API_KEY="your_api_key_here"。写入操作还需 export LASTFM_API_SECRET="your_api_secret" 和 export LASTFM_SESSION_KEY="your_session_key"。API 密钥可在 https://www.last.fm/api/account/create 免费获取，需要 Last.fm 账户。 用户查询可通过 LASTFM_USERNAME 环境变量配置默认用户名。 常用命令示例： lastfm-cli user info <username> lastfm-cli user recent-tracks <username> --limit 10 lastfm-cli user top-artists <username> --period 7day lastfm-cli artist similar <artist> --limit 10 lastfm-cli chart top-artists --limit 20 lastfm-cli geo top-artists "Japan" --limit 20 lastfm-cli tag top-tracks "electronic" --limit 15 lastfm-cli artist search "Radiohead" 写入操作示例： lastfm-cli track scrobble "Artist" "Song" --album "Album" lastfm-cli track now-playing "Artist" "Song" lastfm-cli track love "Artist" "Song" 写入操作需要一次性认证流程：先运行 lastfm-cli auth get-token 获取令牌，用户访问 https://www.last.fm/api/auth/?api_key=KEY&token=TOKEN，然后运行 lastfm-cli auth get-session <token> 换取会话密钥，并设置 LASTFM_SESSION_KEY。详细流程见 references/auth-flow.md。 使用 --json 标志可输出结构化数据，便于通过 jq 等工具处理。
音乐发现流程 将用户喜爱的曲目转化为推荐的核心流程：获取用户顶级艺人和曲目（可加 --json），对每个艺人查找相似艺人，对每个曲目查找相似曲目，与用户已 scrobble 的曲目交叉比对以过滤已听内容，再与用户已有收藏（如 Radarr/Sonarr/jellyfin 或 Spotify 库）比对，区分已有与全新发现。
适用场景 用户询问某人最近在听什么；用户想要音乐发现，如查找与某艺人相似的艺人；用户想要按周期统计的收听数据；用户想要地理音乐趋势；用户想要按标签探索流派；用户想要以编程方式 scrobble 或标记喜爱曲目；任何关于音乐元数据、艺人信息、专辑曲目列表的问题。
限制 每个请求都需要 API 密钥，密钥免费但必须获取。速率限制约为每秒 5 个请求，持续超过此速率可能导致账户被暂停，循环中应添加小延迟。User-Agent 头很重要，CLI 发送 lastfm-cli/1.0 (hermes-agent)。默认响应格式为 XML，CLI 请求 format=json。艺人名称可能拼写错误，可使用 --autocorrect 标志让 Last.fm 纠正。写入操作需要完整认证流程，只读端点不需要。相似性端点基于聚合收听模式的算法协同过滤，并非社交或人工策划的推荐。scrobble 时间戳为 UNIX 纪元秒，省略则使用当前时间。recent-tracks 的 --from 和 --to 接受 ISO 8601 日期字符串。周期值固定为 overall、7day、1month、3month、6month、12month。
不适用场景 不要将此技能用于音乐播放控制（本地播放器、流媒体队列）、非 Last.fm 目录数据（MusicBrainz、Spotify 元数据）或作为歌词来源。
可用脚本 scripts/lastfm-cli：该技能驱动的 CLI 工具，用于只读查询、发现、排行榜、地理图表、搜索、标签以及带会话认证的写入操作。 scripts/test-lastfm.sh：Shell 测试套件，覆盖 CLI 的参数处理和输出格式，无需网络调用。修改 scripts/lastfm-cli 后或审计行为变更时运行，CI 通过 scripts/check-skill-tests.py 运行。
前置条件 免费的 Last.fm API 密钥，导出为 LASTFM_API_KEY，每个请求都需要。写入操作还需 LASTFM_API_SECRET 和一次性认证流程获得的会话密钥，导出为 LASTFM_SESSION_KEY。PATH 中需有 Python 3，若工具不可直接执行，可用 python3 scripts/lastfm-cli ... 调用。可选：LASTFM_USERNAME 设置用户查询的默认用户；jq 用于处理 --json 输出。