实现 Adapter

WowAdapter 是源项目唯一需要实现的业务接口。SDK 负责 Express 路由、参数解析、响应包裹、错误状态和 OpenAPI。

import type { WowAdapter } from 'aduoer-wow-sdk';

export const adapter: WowAdapter = {
  async getTrackDetail(id) {
    const raw = await upstream.song(id);
    return {
      id: String(raw.id),
      title: raw.name,
      artists: raw.artists.map((artist) => ({ id: String(artist.id), name: artist.name })),
      album: { id: String(raw.album.id), name: raw.album.name, coverUrl: raw.album.cover },
      durationMs: raw.duration,
      qualities: []
    };
  }
};

不要返回上游原始对象。开发与测试环境会校验 Adapter 返回值，不符合契约时返回 500 并指出 Schema 路径。

Capabilities

GET /v1/status 的 data.capabilities 根据当前请求上下文中的 Adapter 方法自动生成，无需手动维护能力清单

搜索能力分别为 searchTracks、searchArtists、searchAlbums、searchPlaylists，实现哪一类就声明哪一类，互不依赖；搜索建议由 searchSuggest 单独声明。SDK 不再返回聚合的 search 标识，新版 App 应逐项判断能力并只展示、请求支持的搜索分类，源需要升级 SDK 以返回这些独立标识

现有采用固定能力的 Aduoer App 的 Wow 搜索不读取服务端能力，不依赖服务端的 search 标识，因此移除该标识不会影响已实现搜索接口的调用。旧版 App 仍可能请求未实现的分类，此时返回 HTTP 501

歌曲漫游能力使用 roamTracks，对应 SDK Adapter 方法为 getRoamTracks()，HTTP 路径为 GET /v1/track/roam；SDK 0.3.2 起替代旧的 trackRoam 和 getTrackRoam()

当前 SDK 可生成的全部能力如下

能力标识	用途	适用源
`playlists`	歌单列表	全部源
`playlistCategory`	歌单分类	全部源
`playlistMutation`	创建、删除、编辑歌单及增删歌曲	仅有状态源
`playlistFavorite`	收藏或取消收藏歌单	仅有状态源
`toplist`	排行榜列表	全部源
`toplistTracks`	排行榜歌曲	全部源
`newTracks`	新歌	全部源
`topArtists`	热门艺人	全部源
`songDetail`	歌曲详情	全部源
`similarTracks`	相似歌曲	全部源
`songUrl`	歌曲播放地址	全部源
`lyrics`	歌词	全部源
`streaming`	歌曲流媒体播放（与 songUrl 使用同一方法）	全部源
`searchSuggest`	搜索建议	全部源
`searchTracks`	歌曲搜索	全部源
`searchArtists`	艺人搜索	全部源
`searchAlbums`	专辑搜索	全部源
`searchPlaylists`	歌单搜索	全部源
`artistDetail`	艺人详情	全部源
`albumDetail`	专辑详情	全部源
`trackFavorite`	收藏或取消收藏歌曲	仅有状态源
`favoriteTracks`	用户收藏歌曲	仅有状态源
`userPlaylists`	用户歌单	仅有状态源
`userProfile`	当前用户资料	仅有状态源
`roamTracks`	歌曲漫游	全部源
`dailyTracks`	每日推荐歌曲	全部源

stateless 默认是 true，此时“仅有状态源”的能力即使实现了方法也不会出现在列表中。只有 resolveContext 返回 stateless: false 才会声明这些能力

例如只实现 searchTracks 和 searchSuggest，搜索相关能力返回 ["searchSuggest", "searchTracks"]，不会声明艺人、专辑或歌单搜索

能力检测只检查方法是否为函数，不会调用方法验证上游是否可用。请仅实现源真实支持的方法，避免用始终抛错或空结果的占位方法声明能力。能力列表不是所有接口的清单，未参与推断的基础接口仍可直接调用，未实现时返回 HTTP 501

歌曲音质列表

在 createWowRouter 的 resolveContext 返回值中配置 qualityMap: [{ key, label }]，声明当前源支持的音质选项。使用源模板时，可在 src/app.ts 中修改这项配置

app.use(createWowRouter({
  resolveContext: ({ authorization }) => {
    if (!apiToken || authorization !== apiToken) return null;

    return {
      adapter,
      qualityMap: [
        { key: 'standard', label: '标准音质' },
        { key: 'lossless', label: '无损音质' }
      ]
    };
  }
}));

key 是源自定义的音质标识，用作获取歌曲地址时的 quality 参数，例如 standard、lossless
label 是面向用户展示的音质名称，例如“标准音质”“无损音质”
只声明上游实际支持的音质；如果音质权限因账号而异，应在 resolveContext 中根据当前账号返回对应的列表

SDK 会通过 GET /v1/status 的 data.qualityMap 返回这份配置，未配置时返回空数组。配置后，请求歌曲地址时传入不在列表中的音质标识会返回 HTTP 400

qualityMap 声明源支持的音质范围，单首歌曲实际可用的音质则通过 Track.qualities 返回，例如在 getTrackDetail 返回的歌曲对象中加入以下字段

qualities: [
  { key: 'standard', label: '标准音质', bitrate: 128_000, format: 'mp3', size: 2_880_000 },
  { key: 'lossless', label: '无损音质', bitrate: null, format: 'flac', size: 24_000_000 }
]

其中 size 为必填的文件大小，单位为字节；bitrate 为可选码率，单位为 bps，未知时可返回 null；format 和 description 分别为可选的音频格式和补充说明。应根据歌曲的实际情况填写，不能直接将源支持的所有音质复制给每首歌曲

还需要实现 getTrackUrl(id, quality)，将收到的音质标识映射到上游接口的对应参数。未传 quality 时，由 Adapter 选择默认音质；返回值中的 quality 应填写实际返回的音质标识，如果上游降级返回了其他音质，也应如实填写。qualityMap[].key、Track.qualities[].key 和播放地址返回的 quality 应使用同一套标识

歌单歌曲排序

在 resolveContext 中提供 playlistSortOptions: [{ key, label }]，声明源实际支持的歌单歌曲排序字段。

实现 Adapter ​

Capabilities ​

歌曲音质列表 ​

歌单歌曲排序 ​

实现 Adapter

Capabilities

歌曲音质列表

歌单歌曲排序