lastfm

Last.fm

设置

export LASTFM_API_KEY="your_api_key_here"
# For write operations only:
export LASTFM_API_SECRET="your_api_secret"
export LASTFM_SESSION_KEY="your_session_key"

在 https://www.last.fm/api/account/create 获取 API 密钥（免费，但需要 Last.fm 账户）。

基本命令

用户查询——“我现在在听什么”

可通过 LASTFM_USERNAME 环境变量进行配置。未设置时，默认为 <username>。

lastfm-cli user info <username>                      # Profile + stats
lastfm-cli user recent-tracks <username> --limit 10   # Recent listening
lastfm-cli user top-artists <username> --period 7day  # Weekly top artists
lastfm-cli user top-tracks <username> --period overall # All-time faves
lastfm-cli user loved-tracks <username>               # Loved tracks
lastfm-cli user friends <username>                    # Social graph
lastfm-cli user weekly-charts <username>              # Available chart periods

音乐发现——“有什么和 X 相似”

lastfm-cli artist similar <artist> --limit 10         # Taste graph neighbors
lastfm-cli artist info <artist>                       # Bio, stats, tags
lastfm-cli artist top-tracks <artist>                 # Their most popular
lastfm-cli track similar <artist> "<track>"           # Track-level similarity
lastfm-cli album info <artist> "<album>"              # Tracklist, metadata
lastfm-cli tag top-artists <tag>                      # Genre browsing

榜单——“什么比较热门”

lastfm-cli chart top-artists --limit 20               # Global
lastfm-cli geo top-artists "Japan" --limit 20         # Per-country
lastfm-cli geo top-tracks "Germany" --limit 20
lastfm-cli tag top-tracks "electronic" --limit 15     # By genre tag

搜索——“帮我找那个东西”

lastfm-cli artist search "Radiohead"                  # Find by name
lastfm-cli album search "OK Computer"                 # Find albums
lastfm-cli track search "Karma Police"                # Find tracks

写入操作（需要会话身份验证）

lastfm-cli track scrobble "Artist" "Song" --album "Album"
lastfm-cli track now-playing "Artist" "Song"
lastfm-cli track love "Artist" "Song"

身份验证流程（一次性设置）

# 1. Get a token
lastfm-cli auth get-token

# 2. User visits: https://www.last.fm/api/auth/?api_key=KEY&token=TOKEN

# 3. Exchange for session key
lastfm-cli auth get-session <token>
# → Set export LASTFM_SESSION_KEY=<key>

参考文件

• references/auth-flow.md — 写入操作身份验证（scrobble、love、now-playing）的完整设置指南。尝试执行写入操作前请先阅读。

音乐发现流程——“给我推荐一些我会喜欢的新音乐”

将喜爱的曲目转化为推荐内容的核心流程：

1. 获取用户最常听的艺人/曲目，来源为 Last.fm：

   lastfm-cli user top-artists <username> --period 1month --limit 5 --json
   lastfm-cli user top-tracks <username> --period 1month --limit 10 --json
   lastfm-cli user loved-tracks <username> --json
   

2. 查找每位艺人的相似艺人，通过 Last.fm 的协同过滤实现：

   lastfm-cli artist similar "<artist>" --limit 5 --json
   

3. 查找每首曲目的相似曲目，以获得更细致的推荐：

   lastfm-cli track similar "<artist>" "<track>" --limit 5 --json
   

4. 交叉比对用户已经 scrobble 过的内容（recent-tracks），过滤掉已经听过的内容。

5. 检查用户自己的收藏（通过 Radarr/Sonarr/jellyfin 或 Spotify 媒体库），确认哪些内容已在媒体库中，哪些是真正的新发现。

使用 --json 进行机器处理

# Pipe to jq for structured queries
lastfm-cli artist similar "Radiohead" --limit 5 --json | jq '.similarartists.artist[] | {name, match}'

# Get a user's all-time top artists with playcounts
lastfm-cli user top-artists <username> --period overall --limit 3 --json | jq '.topartists.artist[] | {name, playcount}'

# Find most popular tracks by a genre
lastfm-cli tag top-tracks "electronic" --limit 10 --json | jq '.tracks.track[] | {name, artist: .artist.name, listeners}'

已知注意事项

• 每个请求都需要 API 密钥。 密钥免费，可在 Last.fm API 账户页面获取。
• 持续速率限制约为 5 req/sec。 API 文档的要求是“合理使用”——如果持续每秒发起多次调用，你的账户可能会被暂停。循环调用时请加入短暂延迟。
• User-Agent 请求头很重要。 CLI 会发送 lastfm-cli/1.0 (hermes-agent)。Last.fm 的文档明确要求使用可识别的 User-Agent。
• XML 是默认响应格式。 CLI 会请求 format=json。如果不指定，响应将以 XML 格式返回。
• 艺人名称可能拼写有误。 在艺人命令中使用 --autocorrect 标志，让 Last.fm 更正拼写错误。
• 写入操作需要完成身份验证设置。 scrobble、love 和 now-playing 需要完整的身份验证流程（token → session key）。只读端点不需要。
• 协同过滤关系图并非社交关系图。 artist.getSimilar 返回的是基于整体收听模式计算的算法相似度，而非由人工整理的推荐。
• Scrobble 的时间戳使用 UNIX 纪元秒数。省略时将使用当前时间。
• recent-tracks 的 --from 和 --to 接受 ISO 8601 日期字符串（例如 2026-05-27）。
• 时间段取值：overall、7day、1month、3month、6month、12month。

何时使用此工具

• 用户询问“[某人] 最近在听什么？”
• 用户想发现音乐：“给我找一些和……相似的艺人”
• 用户想查看收听统计：按时间段统计最常听的艺人、曲目和专辑
• 用户想了解地区音乐趋势：“[某个国家] 什么比较热门”
• 用户想通过标签探索流派
• 用户想以编程方式 scrobble 或 love 曲目
• 任何关于音乐元数据、艺人信息、专辑曲目列表的问题

可用脚本

脚本	用途	调用方式
scripts/lastfm-cli	此技能调用的 CLI 工具：只读查询（用户信息/recent-tracks/top-artists/top-tracks/loved-tracks/friends/weekly-charts）、发现功能（artist similar、track similar）、榜单和地区榜单、搜索、标签，以及通过会话身份验证执行的 scrobble、now-playing 和 love。对于上述所有 Last.fm 数据问题都应运行此工具；完整命令列表请参阅“基本命令”。	scripts/lastfm-cli user top-artists <username> --period 7day --limit 10
scripts/test-lastfm.sh	Shell 测试套件，无需网络调用即可测试 CLI 的参数处理和输出格式。修改 scripts/lastfm-cli 后，或审查其行为变更时，请运行此测试；CI 通过 scripts/check-skill-tests.py 运行它。	bash scripts/test-lastfm.sh

前提条件

• 一个免费的 Last.fm API 密钥，并将其导出为 LASTFM_API_KEY（在 https://www.last.fm/api/account/create 创建）；没有此密钥，所有请求都会失败。
• 仅用于写入操作：LASTFM_API_SECRET，以及通过 references/auth-flow.md 中的一次性授权流程获取的会话密钥，并将其导出为 LASTFM_SESSION_KEY。
• PATH 中需有 Python 3——如果无法直接执行捆绑的工具，请使用 python3 scripts/lastfm-cli ... 调用；SKILL.md 中的示例假设 lastfm-cli 可通过 PATH 找到。
• 可选：设置 LASTFM_USERNAME，以指定用户查询的默认用户；通过管道处理 --json 输出时，可使用 jq 进行结构化处理。

限制

• 只读端点仅需 API 密钥；记录播放、正在播放和标记喜欢都需要完整的令牌 → 会话密钥授权流程，没有该流程会导致操作失败。
• 持续以高于约 5 req/sec 的速率调用可能导致账户被暂停——在循环中加入短暂延迟。
• 相似度端点使用基于整体聆听模式的算法协同过滤，而非社交推荐或人工策划的推荐。
• 周期值固定为 overall、7day、1month、3month、6month 和 12month；只有 recent-tracks 支持通过 --from/--to 指定任意日期范围。
• 艺术家名称拼写错误会返回空结果或错误结果，除非使用 --autocorrect。

不适用场景

不要将此技能用于控制音乐播放（本地播放器、流媒体播放队列）、获取非 Last.fm 目录数据（MusicBrainz、Spotify 元数据）或查找歌词——该 API 仅涵盖聆听历史、元数据、榜单、标签、相似度和播放记录功能。