---
title: "链接/文件名定位 / Resolve a link, filename or album code"
method: POST
path: "/agent/v1/km_resolve"
---

# 链接/文件名定位 / Resolve a link, filename or album code

`POST /agent/v1/km_resolve`

## Request

- Base URL: `https://share.kindlemusic.cn`
- URL: `https://share.kindlemusic.cn/agent/v1/km_resolve`
- Auth: one of:
  - none
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://share.kindlemusic.cn/oauth/authorize`, token URL `https://share.kindlemusic.cn/oauth/token`)

把用户手里的下载文件名、UPM 链接、本站链接（专辑 / 厂牌 / 选曲清单 / 歌单 / 搜索结果页）、外站链接或带连字符的专辑编号，定位成下一步可用的对象。
Resolves a download filename, UPM link, kindlemusic.cn link (album / label / pick list / playlist / search page), other web link or hyphenated album code into something the other km_* tools can act on.

何时用 / When: 用户贴的是 KM_PUC045_TK003_xxx.mp3、universalproductionmusic.com 链接、www.kindlemusic.cn/… 链接或 PUC-045 这类编号时，先调本工具；不要把它们当关键词丢进 km_search（会零结果）。

返回 / Returns: { q, resolved }。resolved 为 null 表示认不出或库里没有。按 kind 接下一步：
- kind="track"，source 为 upm / filename（文件名 / UPM 链接）：{ albumCode, trackNumber（主曲曲号）, trackIdentity, trackTitle, albumTitle }。剪辑版文件名一律映射到主版本；接着用 km_track_versions(albumCode, trackNumber) 取全部版本，或 km_search(searchField="album", keyword=albumCode) 拿曲目 id。
- kind="album"，source="code"（编号）：{ albumCode, albumTitle }。接着用 km_search(searchField="album", keyword=albumCode)。
- source="site"（本站链接）：
  - kind="track" 带 trackId：trackId 就是曲目 id，可直接喂 km_similar_by_track；带 trackNumber（专辑页 ?trackNumber=）：可直接喂 km_track_versions(albumCode, trackNumber)。
  - kind="album"：{ albumCode, trackId:null }，同上接 km_search(searchField="album")。
  - kind="label"：{ includeLabels:[厂牌名] }，原样放进 km_search 的 includeLabels 按厂牌收窄。
  - kind="resultSet"：{ code }，选曲清单（/picks/<code>），用 km_get_result_set(code) 读回。
  - kind="playlist"：{ playlistId } 或 { shareType, shareCode }，网站歌单 / 歌单分享链接，MCP 没有读取歌单的工具，请让用户在网站打开，或说出想要的风格改用 km_search。
  - kind="search"：{ tier, args }，网站搜索结果页的条件已还原成 km_search 入参，原样传给 km_search 即可复现用户看到的那次检索。
  - kind="page"：本站首页 / 列表页 / 场景页 / 指南，没有可直接检索的对象。
- kind="keywords"，source="slug"（外站链接、或本站认不出的路径）：{ keyword }，取自链接里的搜索参数或最后一段路径；可作为 km_search 的关键词（含中文时带 expand="fast"，或改用 searchField="ai"）。视频网站链接通常取不出曲名，有参考音频请走 km_similar_by_audio。

## Request body

- object
  - `q` string, required: The filename, link or album code exactly as the user gave it.

## Response `200`

tool 结果（与 MCP tools/call 返回的 JSON 相同）

- object

## Other responses

- `400`: 入参错误或 km 业务错误：{ error, message, hint? } / { error:"km_error", code, message }
- `401`: 需要 scope 的 tool 缺少或带了无效凭据

---

[API](https://skmtc.dev/kindlemusic/apis/kindle-music-agent-api.md) · [All operations](https://skmtc.dev/kindlemusic/apis/kindle-music-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kindlemusic/apis/kindle-music-agent-api/revisions/2673f364b5b0?raw)