Apple Music Playlist Curator

Append resolved tracks to an existing playlist created by this API client. Use dry_run=true to preview matching; use am_create_playlist for a new playlist. / 中文：向已有歌单追加曲目。注意 Apple 的限制：只有创建该歌单的那个客户端才能写入它。

Read-only diagnosis of BPM, key, loudness, energy, mood, adjacent transitions, and overall arc. It may fetch and cache remote feature data; use am_optimize_order only when a proposed replacement order is wanted. / 中文：歌单「好听度」体检（音频特征层）：抓取每首的 BPM/调性/响度/能量/情绪值（经 ISRC→ReccoBeats，首次会慢，之后走缓存），然后检查四项相邻衔接（两首慢歌相邻 / 「只慢一点」/ tempo 与 key 同时相似 / 能量骤变）和整体弧线形状（Man in a hole、Icarus、Tragedy 等）。只读但会联网抓数据，可能耗时较久。

Read-only metadata audit of playlist length, artist concentration, genres, eras, duplicates, and possible interludes. For BPM, key, energy, and transitions, use am_analyze_flow. / 中文：歌单结构化体检（元数据层）：曲目数、总时长、艺人集中度（同一艺人是否超过 2 首）、流派分布、年代分布、时长分布、重复曲目、<2:00 的疑似间奏。只读，用于判断歌单是否符合策展规范（长度 20–30 首最佳、单一主题等）。

Create a new playlist from 'Title - Artist' strings or ISRCs. Use dry_run=true to verify catalog matching without writing; use am_add_tracks for an existing playlist. / 中文：创建一个新的 Apple Music 歌单，并一次性写入曲目。曲目用 '歌名 - 艺人' 形式的字符串数组给出，服务端会自动在 catalog 里匹配；若有 ISRC 码则更精确。这是全自动建歌单的主入口。

Delete one playlist permanently after it has been shown to the user. This is destructive, requires confirm=true, and does not delete the underlying songs from the library. / 中文：删除一个歌单。这是破坏性操作，必须先把歌单名和它当前的内容展示给用户并得到确认；只删本工具创建的演示/临时歌单，不要删用户自己整理的歌单。

List every playlist in the current user's library, including IDs. Use am_show_playlist when the tracks of one playlist are needed. / 中文：列出当前账号音乐库里的所有歌单（含 ID）。

Optionally refine local audio transitions after the LLM has selected the songs and narrative blocks. By default it does not impose a global narrative arc or tempo curve; pass a named arc only when the user explicitly requests that preset. It returns an order without writing and must not choose songs or judge theme fit. / 中文：为一批曲目**算出更好的顺序**。这是本项目唯一会排序的工具——am_analyze_flow 只诊断（告诉你哪里有 2 处慢歌相邻、形状是 Icarus），不提供修法。这里用模拟退火处理四条相邻硬规则（不要两首慢歌相邻 / 不要「只慢一点」/ 相邻不该在 tempo 与 key 上同时相似 / 不要 BPM 无理由大跳、能量骤变）。默认不拟合全局叙事弧；只有显式传入 arc 才套用一个命名预设。**只读**：只返回建议顺序，不动任何歌单；把返回列表按原顺序交给 am_create_playlist 即可。因为需要每首的 BPM/调性，首次会联网抓特征（之后走缓存）。

Read recent listening or recently added Apple Music content when recency matters. This API does not provide play counts; use am_top_played for Replay rankings. / 中文：查最近播放。kind=tracks 是最近播放的曲目；played 是最近播放的歌单/专辑；stations 是最近听的电台；added 是最近加入音乐库的内容。注意：Apple 的这个接口**不返回播放次数**。

Ground an LLM-curated candidate pool in Apple Music metadata before final selection or creation. It returns exact catalog metadata and Apple Music links, flags unresolved tracks, duplicate recordings, artist concentration, and version markers, and never scores theme fit or writes to the library. / 中文：批量校验 LLM 提出的候选曲目，并返回 Apple Music 的真实曲名、艺人、专辑、发行日期、流派、时长、歌词可用性、版本标记和 catalog ID。还会指出重复录音与艺人集中度，但**不替模型做主题评分或选曲**。模型应直接根据用户描述与这些真实信息比较候选，保留理由充分的曲目。只读，不修改音乐库。

Search the Apple Music catalog for a small exploratory lookup and return stable catalog IDs. For an LLM-proposed playlist-sized pool, use am_resolve_candidates instead. / 中文：在 Apple Music catalog 搜索歌曲/专辑/艺人，返回可用于建歌单的歌曲 ID。

Show the tracks in one playlist selected by name or ID. Use am_list_playlists first when the exact playlist is unknown. / 中文：查看某个歌单的曲目列表。

Check developer-token validity and Apple Music login status. Use before any library write; this check changes nothing. / 中文：查看 Apple Music 自动化状态：developer token 是否有效、是否已登录（music-user-token）。任何写歌单操作前都应先确认已登录。

Read Apple Music Replay play-count rankings by song, album, or artist when frequency matters. Use am_recently_played for latest listening; all-time data may be unavailable, so retry with a specific year. / 中文：查**播放次数**排行（数据来自 Apple Music Replay / 音乐回忆的后端）。可以查 songs / albums / artists，按年份或 all-time。返回每项的播放次数、首次播放日期、最近播放日期。注意：只有 amp-api 主机可用；all-time 期间不一定存在，失败时先试具体年份。