qqmusic-api-python 0.6.8__tar.gz → 0.6.9__tar.gz

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/.dockerignore

@@ -22,5 +22,3 @@ dist
 .prek_cache
 *.toml
 !pyproject.toml
-!web/config.toml
-!web/accounts.toml

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.8
+Version: 0.6.9
 Summary: QQ音乐API封装库
 Project-URL: documentation, https://l-1124.github.io/QQMusicApi/
 Project-URL: homepage, https://l-1124.github.io/QQMusicApi/

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/docs/release-notes.md

@@ -1,4 +1,44 @@
 
+## [[0.6.8](https://github.com/L-1124/QQMusicApi/compare/v0.6.7..v0.6.8)] - 2026-07-01
+
+### Bug 修复
+
+* **(web)** 禁用 FastAPI 默认按别名响应，使 JSON 输出与 Python 原生变量名保持一致 ([32459a5](https://github.com/L-1124/QQMusicApi/commit/32459a54c03d8a0a738f1917f9eb19fc6f9ac4ef)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** 新增 SignatureRequiredError 错误码 2000 处理 ([a73313a](https://github.com/L-1124/QQMusicApi/commit/a73313a91549a156358ad9311d0e20d7401b861b)) by [@L-1124](https://github.com/L-1124)
+* **(core)** _ensure_session 添加 24h 保活机制 ([2290a32](https://github.com/L-1124/QQMusicApi/commit/2290a32304bcd9052365f60c67f2d4f6b00e4d7e)) by [@L-1124](https://github.com/L-1124)
+* **(helper)** 新增辅助功能接口 ([eb0c40c](https://github.com/L-1124/QQMusicApi/commit/eb0c40c1461826955a1eb005afb723438730142a)) by [@L-1124](https://github.com/L-1124)
+* **(login)** 支持登出API ([73f2a7e](https://github.com/L-1124/QQMusicApi/commit/73f2a7ee9ad1d48cbec2d6aa9dbf844f44b573c2)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 彻底移除 crypt 字段，隐式处理加密状态 ([80edc40](https://github.com/L-1124/QQMusicApi/commit/80edc40e41331f6b5c11146d5daf6eccf344181f)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** [**breaking**] 移除 decrypt 方法，改为默认解密 ([24949c4](https://github.com/L-1124/QQMusicApi/commit/24949c4df8c63b02b35dd69c30e2a8f40d234dfb)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 添加特殊歌曲文件类型 TRY_OGG_640 ([fef7e8c](https://github.com/L-1124/QQMusicApi/commit/fef7e8ceb220aa477ea7d8498f8ebfd240f72cc6)) by [@L-1124](https://github.com/L-1124)
+* **(user)** 新增收藏/取消收藏歌单 API ([7865434](https://github.com/L-1124/QQMusicApi/commit/7865434782dd205815222fe716f52bac9f84aeec)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#281](https://github.com/L-1124/QQMusicApi/pull/281)
+* **(user)** 新增 FeedbackBlack 黑名单 API ([4340554](https://github.com/L-1124/QQMusicApi/commit/4340554aaaafaef175eead7ebced596538bc65e2)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 启用 FastAPI 内置 Swagger UI 和 ReDoc，更新文档地址说明 ([a3245ad](https://github.com/L-1124/QQMusicApi/commit/a3245ad3d3863c7f7eec94352d169a32ba4478c6)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 重构 Dockerfile 为多阶段构建，修复非 root 用户 uv 缓存权限问题 ([00e16a3](https://github.com/L-1124/QQMusicApi/commit/00e16a37b62e989de37232e8af7e77167a28e823)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(core)** 移除 _session_cache 冗余缓存，简化会话验证逻辑 ([0b12b9d](https://github.com/L-1124/QQMusicApi/commit/0b12b9d041a8be24ad84d60bd2ceaed76b81fe92)) by [@L-1124](https://github.com/L-1124)
+* **(models)** [**breaking**] 将所有模型中的 alias 统一替换为 validation_alias，隔离序列化字段名 ([c611b91](https://github.com/L-1124/QQMusicApi/commit/c611b91d607d36327662a80d0e126a6958b21bd5)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 移除冗余的 _require_login 调用，统一使用 require_login 参数 ([1a666f4](https://github.com/L-1124/QQMusicApi/commit/1a666f45ae968c235066c07e8b3e82096c3fc668)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 将 _require_login 收敛到 _build_request 的 require_login 参数中 ([d1a92ca](https://github.com/L-1124/QQMusicApi/commit/d1a92ca07d5a98f3f443453e5fc77b8f8c8dc44e)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(coding)** 更新需登录接口的编码规范，使用 require_login 参数替代 _require_login ([9e56215](https://github.com/L-1124/QQMusicApi/commit/9e562152ec8039b3045ae6c51006401c93b36a36)) by [@L-1124](https://github.com/L-1124)
+* **(dislike)** 更新不喜欢列表项和响应数据的文档说明 ([5dbf711](https://github.com/L-1124/QQMusicApi/commit/5dbf711e46a69f99940f048504446b9e074fd21f)) by [@L-1124](https://github.com/L-1124)
+* **(login)** 更新二维码和手机验证码登录状态的文档注释 ([f31d4d0](https://github.com/L-1124/QQMusicApi/commit/f31d4d0132cb61a9935ebea92657fcfa6591926c)) by [@L-1124](https://github.com/L-1124)
+* **(readme)** 添加 DeepWiki 相关链接 ([fcea758](https://github.com/L-1124/QQMusicApi/commit/fcea758b80a824cb513a8bdfc8b247da786f5a1e)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @jinzhongjia [#281](https://github.com/L-1124/QQMusicApi/pull/281)
+* @github-actions[bot]
+
 ## [[0.6.7](https://github.com/L-1124/QQMusicApi/compare/v0.6.6..v0.6.7)] - 2026-06-17
 
 ### 功能更新

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/__init__.py

@@ -22,7 +22,7 @@ from .core.exceptions import (
 from .core.versioning import Platform
 from .models.request import Credential
 
-__version__ = "0.6.8"
+__version__ = "0.6.9"
 
 __all__ = [
     "ApiDataError",

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/models/album.py

@@ -70,3 +70,52 @@ class GetAlbumSongResponse(Response):
     album_mid: str = Field(validation_alias="albumMid")
     total_num: int = Field(validation_alias="totalNum")
     song_list: list[Song] = Field(default_factory=list, json_schema_extra={"jsonpath": "$.songList[*].songInfo"})
+
+
+class NewAlbumItem(Album):
+    """新碟上架列表中的单张专辑摘要.
+
+    Attributes:
+        singers: 专辑署名歌手列表.
+        release_time: 发行日期, 格式通常为 YYYY-MM-DD.
+        type: 专辑类型.
+        area: 地区标识.
+        genre: 流派标识.
+        language: 语种标识.
+    """
+
+    singers: list[Singer] = Field(default_factory=list)
+    release_time: str = ""
+    type: int = 0
+    area: int = 0
+    genre: int = 0
+    language: int = 0
+
+
+class GetNewAlbumResponse(Response):
+    """新碟上架接口的响应体.
+
+    Attributes:
+        total: 该地区下新碟总数.
+        albums: 当前页新碟列表.
+    """
+
+    total: int = 0
+    albums: list[NewAlbumItem] = Field(default_factory=list)
+
+
+class AlbumFavWriteResponse(Response):
+    """收藏 / 取消收藏专辑的写操作响应.
+
+    Attributes:
+        result: 操作结果码, 0 表示成功.
+        failed_album_id: 操作失败的专辑 ID 列表, 全部成功时为空.
+    """
+
+    result: int = 0
+    failed_album_id: list[int] = Field(default_factory=list, validation_alias="v_failedAlbumId")
+
+    @property
+    def success(self) -> bool:
+        """是否操作成功 (result 为 0 且无失败项)."""
+        return self.result == 0 and not self.failed_album_id

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/models/base.py

@@ -18,21 +18,17 @@ _PHOTO_NEW_SIZE_SEGMENTS: Final[dict[int, str]] = {
 }
 
 
-def _normalize_cover_size(size: CoverSize) -> str:
-    """返回 `photo_new` 模板使用的尺寸片段."""
-    try:
-        return _PHOTO_NEW_SIZE_SEGMENTS[size]
-    except KeyError as exc:
-        raise ValueError("not supported size") from exc
-
-
 def _build_photo_new_cover_url(kind: str, mid: str, size: CoverSize) -> str:
     """按 `photo_new` 规则拼接封面链接."""
     normalized_mid = mid.strip()
     if not normalized_mid:
         return ""
 
-    return f"https://y.gtimg.cn/music/photo_new/{kind}{_normalize_cover_size(size)}M000{normalized_mid}.jpg"
+    try:
+        cover_size = _PHOTO_NEW_SIZE_SEGMENTS[size]
+        return f"https://y.gtimg.cn/music/photo_new/{kind}{cover_size}M000{normalized_mid}.jpg"
+    except KeyError as exc:
+        raise ValueError("not supported size") from exc
 
 
 class Singer(Response):

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/models/mv.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from pydantic import Field
 
-from .base import MV
+from .base import MV, Singer
 from .request import Response
 
 
@@ -116,3 +116,35 @@ class GetMvUrlsResponse(Response):
     """
 
     data: dict[str, MvUrlSet] = Field(json_schema_extra={"jsonpath": "$"})
+
+
+class MvListItem(MV):
+    """MV 分类列表中的单个 MV 摘要.
+
+    Attributes:
+        singers: 歌手列表.
+        subtitle: MV 副标题.
+        playcnt: 播放量.
+        pubdate: 发布时间戳.
+        duration: 时长 (秒).
+        picurl: 封面图片地址.
+    """
+
+    singers: list[Singer] = Field(default_factory=list)
+    subtitle: str = ""
+    playcnt: int = 0
+    pubdate: int = 0
+    duration: int = 0
+    picurl: str = ""
+
+
+class GetMvListResponse(Response):
+    """MV 分类列表接口的响应体.
+
+    Attributes:
+        total: 该分类条件下的 MV 总数.
+        items: 当前页 MV 列表.
+    """
+
+    total: int = 0
+    items: list[MvListItem] = Field(default_factory=list, validation_alias="list")

qqmusic_api_python-0.6.9/qqmusic_api/modules/album.py

@@ -0,0 +1,117 @@
+"""专辑相关 API."""
+
+from typing import Any
+
+from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+from ..models.album import (
+    AlbumFavWriteResponse,
+    GetAlbumDetailResponse,
+    GetAlbumSongResponse,
+    GetNewAlbumResponse,
+)
+from ..models.request import Credential
+from ._base import ApiModule
+
+
+class AlbumApi(ApiModule):
+    """专辑相关 API."""
+
+    def get_detail(self, value: int | str):
+        """获取专辑详细信息.
+
+        Args:
+            value: 专辑 ID 或 MID.
+        """
+        param: dict[str, Any] = {}
+        if isinstance(value, int) or (isinstance(value, str) and value.isdecimal()):
+            param["albumId"] = int(value)
+        else:
+            param["albumMId"] = value
+
+        return self._build_request(
+            module="music.musichallAlbum.AlbumInfoServer",
+            method="GetAlbumDetail",
+            param=param,
+            response_model=GetAlbumDetailResponse,
+        )
+
+    def get_song(self, value: int | str, num: int = 10, page: int = 1):
+        """获取专辑歌曲列表.
+
+        Args:
+            value: 专辑 ID 或 MID.
+            num: 返回结果数量.
+            page: 页码.
+        """
+        param: dict[str, Any] = {
+            "begin": num * (page - 1),
+            "num": num,
+        }
+        if isinstance(value, int) or (isinstance(value, str) and value.isdecimal()):
+            param["albumId"] = int(value)
+        else:
+            param["albumMid"] = value
+
+        return self._build_request(
+            module="music.musichallAlbum.AlbumSongList",
+            method="GetAlbumSongList",
+            param=param,
+            response_model=GetAlbumSongResponse,
+            pager_meta=PagerMeta(
+                strategy=OffsetStrategy(offset_key="begin", page_size_key="num"),
+                adapter=ResponseAdapter(total="total_num", count=lambda response: len(response.song_list)),
+            ),
+        )
+
+    def get_new_album(self, area: int = 1, num: int = 20, page: int = 1):
+        """获取新碟上架列表.
+
+        Args:
+            area: 地区. 1=内地, 2=港台, 3=欧美, 4=韩国, 5=日本, 6=其他.
+            num: 每页返回的专辑数量.
+            page: 页码, 从 1 开始.
+        """
+        return self._build_request(
+            module="newalbum.NewAlbumServer",
+            method="get_new_album_info",
+            param={"area": area, "num": num, "start": num * (page - 1)},
+            response_model=GetNewAlbumResponse,
+            pager_meta=PagerMeta(
+                strategy=OffsetStrategy(offset_key="start", page_size_key="num"),
+                adapter=ResponseAdapter(total="total", count=lambda response: len(response.albums)),
+            ),
+        )
+
+    def fav_album(self, album_id: int | list[int], *, credential: Credential | None = None):
+        """收藏专辑到当前登录用户.
+
+        Args:
+            album_id: 专辑 ID, 支持单个或列表.
+            credential: 登录凭证.
+        """
+        ids = [album_id] if isinstance(album_id, int) else album_id
+        return self._build_request(
+            module="music.musicasset.AlbumFavWrite",
+            method="FavAlbum",
+            param={"v_albumId": ids},
+            credential=credential,
+            require_login=True,
+            response_model=AlbumFavWriteResponse,
+        )
+
+    def del_fav_album(self, album_id: int | list[int], *, credential: Credential | None = None):
+        """取消收藏专辑.
+
+        Args:
+            album_id: 专辑 ID, 支持单个或列表.
+            credential: 登录凭证.
+        """
+        ids = [album_id] if isinstance(album_id, int) else album_id
+        return self._build_request(
+            module="music.musicasset.AlbumFavWrite",
+            method="CancelFavAlbum",
+            param={"v_albumId": ids},
+            credential=credential,
+            require_login=True,
+            response_model=AlbumFavWriteResponse,
+        )

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/modules/mv.py

@@ -1,6 +1,7 @@
 """MV 相关 API."""
 
-from ..models.mv import GetMvDetailResponse, GetMvUrlsResponse
+from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+from ..models.mv import GetMvDetailResponse, GetMvListResponse, GetMvUrlsResponse
 from ..utils.common import get_guid
 from ._base import ApiModule
 
@@ -68,3 +69,31 @@ class MvApi(ApiModule):
             },
             response_model=GetMvUrlsResponse,
         )
+
+    def get_mv_list(
+        self,
+        area: int = 15,
+        version: int = 7,
+        order: int = 0,
+        num: int = 10,
+        page: int = 1,
+    ):
+        """获取 MV 分类列表.
+
+        Args:
+            area: 地区 ID. 15=全部, 8=内地, 5=港台, 6=欧美, 7=韩国, 4=日本.
+            version: 类型 ID. 7=全部, 8=MV, 13=现场, 14=翻唱, 15=舞蹈, 16=影视, 17=综艺, 18=儿歌.
+            order: 排序方式. 0=最新, 1=最热.
+            num: 每页返回数量.
+            page: 页码, 从 1 开始.
+        """
+        return self._build_request(
+            module="MvService.MvInfoProServer",
+            method="GetAllocMvInfo",
+            param={"area": area, "version": version, "order": order, "start": num * (page - 1), "size": num},
+            response_model=GetMvListResponse,
+            pager_meta=PagerMeta(
+                strategy=OffsetStrategy(offset_key="start", page_size_key="size"),
+                adapter=ResponseAdapter(total="total", count=lambda response: len(response.items)),
+            ),
+        )

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/modules/recommend.py

@@ -146,9 +146,13 @@ class RecommendApi(ApiModule):
             ),
         )
 
-    def get_recommend_newsong(self):
-        """获取推荐新歌."""
-        data = {"type": 5}
+    def get_recommend_newsong(self, type: int = 5):  # noqa: A002
+        """获取推荐新歌.
+
+        Args:
+            type: 地区/语种筛选. 1=内地, 2=欧美, 3=日本, 4=韩国, 5=最新, 6=港台.
+        """
+        data = {"type": type}
         return self._build_request(
             "newsong.NewSongServer",
             "get_new_song_info",

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/qqmusic_api/modules/songlist.py

@@ -175,3 +175,43 @@ class SonglistApi(ApiModule):
             if e.code == 80092:
                 return False
             raise
+
+    async def like_song(
+        self,
+        song_info: list[tuple[int, int]],
+        *,
+        credential: Credential | None = None,
+    ) -> bool:
+        """收藏歌曲到 "我喜欢" 歌单.
+
+        Note:
+            "我喜欢" 歌单的目录 ID 固定为 201, 本方法即以 dirid=201 调用 `add_songs`.
+
+        Args:
+            song_info: 歌曲信息列表, 每项为 `(song_id, song_type)`.
+            credential: 登录凭证.
+
+        Returns:
+            操作成功与否 (歌曲已在 "我喜欢" 中也返回 True).
+        """
+        return await self.add_songs(201, song_info, credential=credential)
+
+    async def unlike_song(
+        self,
+        song_info: list[tuple[int, int]],
+        *,
+        credential: Credential | None = None,
+    ) -> bool:
+        """从 "我喜欢" 歌单移除歌曲.
+
+        Note:
+            "我喜欢" 歌单的目录 ID 固定为 201, 本方法即以 dirid=201 调用 `del_songs`.
+
+        Args:
+            song_info: 歌曲信息列表, 每项为 `(song_id, song_type)`.
+            credential: 登录凭证.
+
+        Returns:
+            操作成功与否 (歌曲不在 "我喜欢" 中也返回 True).
+        """
+        return await self.del_songs(201, song_info, credential=credential)

qqmusic_api_python-0.6.9/tests/test_album.py

@@ -0,0 +1,59 @@
+"""专辑模块测试."""
+
+from typing import Literal
+
+import pytest
+
+from qqmusic_api import Client, CredentialInvalidError
+
+CoverSize = Literal[150, 300, 500, 800] | None
+
+
+async def test_get_detail_by_id(client: Client) -> None:
+    """测试通过专辑 ID 获取专辑详情."""
+    result = await client.album.get_detail(100)
+    assert result is not None
+
+
+@pytest.mark.parametrize(
+    ("mid", "num", "page"),
+    [
+        ("001uKKpF1RuJSd", 30, 1),
+        ("001gR6jO1L4MWq", 5, 1),
+        ("0041WVfh2vtlJE", 10, 2),
+    ],
+)
+async def test_get_song(client: Client, mid: str, num: int, page: int) -> None:
+    """测试获取专辑歌曲列表."""
+    result = await client.album.get_song(mid, num=num, page=page)
+    assert result is not None
+
+
+@pytest.mark.parametrize("area", [1, 2, 3])
+async def test_get_new_album(client: Client, area: int) -> None:
+    """测试按地区获取新碟上架列表."""
+    result = await client.album.get_new_album(area=area, num=5, page=1)
+    assert result.albums
+    assert result.albums[0].mid
+    assert result.albums[0].name
+
+
+async def test_get_new_album_pagination(client: Client) -> None:
+    """测试新碟上架分页返回不同数据."""
+    pager = client.album.get_new_album(area=1, num=5, page=1).paginate(limit=2)
+    first = await pager.next()
+    second = await pager.next()
+    assert first.albums[0].mid != second.albums[0].mid
+
+
+async def test_fav_album_roundtrip(authenticated_client: Client) -> None:
+    """测试收藏与取消收藏专辑可逆往返."""
+    album = (await authenticated_client.album.get_new_album(area=1, num=1, page=1)).albums[0]
+    assert (await authenticated_client.album.fav_album(album.id)).success
+    assert (await authenticated_client.album.del_fav_album(album.id)).success
+
+
+async def test_fav_album_requires_login(client: Client) -> None:
+    """测试收藏专辑需要登录凭证."""
+    with pytest.raises(CredentialInvalidError):
+        await client.album.fav_album(100)

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/tests/test_mv.py

@@ -25,3 +25,20 @@ async def test_get_mv_urls_multiple(client: Client) -> None:
     """测试批量获取 MV 播放链接."""
     result = await client.mv.get_mv_urls(["013xscuH0xlbie", "013xscuH0xlbie"])
     assert result is not None
+
+
+async def test_get_mv_list(client: Client) -> None:
+    """测试获取 MV 分类列表."""
+    result = await client.mv.get_mv_list(area=15, version=7, order=0, num=5, page=1)
+    assert result.total > 0
+    assert result.items
+    assert result.items[0].vid
+    assert result.items[0].title
+
+
+async def test_get_mv_list_pagination(client: Client) -> None:
+    """测试 MV 分类列表分页返回不同数据."""
+    pager = client.mv.get_mv_list(num=5, page=1).paginate(limit=2)
+    first = await pager.next()
+    second = await pager.next()
+    assert first.items[0].vid != second.items[0].vid

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/tests/test_recommend.py

@@ -1,5 +1,7 @@
 """推荐模块测试."""
 
+import pytest
+
 from qqmusic_api import Client
 
 
@@ -35,3 +37,11 @@ async def test_get_recommend_newsong(client: Client) -> None:
     result = await client.recommend.get_recommend_newsong()
     assert result.songs
     assert result.songs[0].mid
+
+
+@pytest.mark.parametrize(("area_type", "lan"), [(1, "内地"), (2, "欧美"), (6, "港台")])
+async def test_get_recommend_newsong_by_type(client: Client, area_type: int, lan: str) -> None:
+    """测试按地区类型获取推荐新歌."""
+    result = await client.recommend.get_recommend_newsong(type=area_type)
+    assert result.lan == lan
+    assert result.songs

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/tests/test_songlist.py

@@ -63,3 +63,22 @@ async def test_del_songs_requires_login(client: Client) -> None:
     """测试删除歌单歌曲需要登录凭证."""
     with pytest.raises(CredentialInvalidError):
         await client.songlist.del_songs(dirid=1, song_info=[(100, 0)])
+
+
+async def test_like_song_requires_login(client: Client) -> None:
+    """测试收藏歌曲到我喜欢需要登录凭证."""
+    with pytest.raises(CredentialInvalidError):
+        await client.songlist.like_song([(100, 0)])
+
+
+async def test_unlike_song_requires_login(client: Client) -> None:
+    """测试从我喜欢移除歌曲需要登录凭证."""
+    with pytest.raises(CredentialInvalidError):
+        await client.songlist.unlike_song([(100, 0)])
+
+
+async def test_like_song_roundtrip(authenticated_client: Client) -> None:
+    """测试收藏与取消收藏歌曲可逆往返."""
+    song = (await authenticated_client.recommend.get_recommend_newsong(type=1)).songs[0]
+    assert await authenticated_client.songlist.like_song([(song.id, song.type)])
+    assert await authenticated_client.songlist.unlike_song([(song.id, song.type)])

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/web/Dockerfile

@@ -38,7 +38,4 @@ WORKDIR /app
 
 EXPOSE 8080
 
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD python -c "from urllib.request import urlopen; urlopen('http://localhost:8080/')" || exit 1
-
 CMD ["python", "web/run.py"]

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/web/README.md

@@ -45,17 +45,38 @@ uv run --no-sync web/run.py
 docker build -t qqmusic-api-web -f web/Dockerfile .
 
 # 运行容器
-docker run -p 8080:8080 \
+docker run -d -p 8080:8080 --name qqmusic-api-web \
   -v ./web/data:/app/web/data \
+  -v ./web/accounts.toml:/app/web/accounts.toml:ro \
+  -v ./web/config.toml:/app/web/config.toml:ro \
   qqmusic-api-web
 ```
 
 使用 docker-compose:
 
 ```bash
+# 首次使用请复制示例文件并编辑:
+cp web/docker-compose.example.yml web/docker-compose.yml
+# 然后启动:
 docker compose -f web/docker-compose.yml up -d
 ```
 
+### wslc 部署
+
+[`wslc`](https://learn.microsoft.com/zh-cn/windows/wsl/) 是 Windows 自带的 WSL 容器管理工具。
+
+```bash
+# 构建镜像
+wslc build -t qqmusic-api-web -f web/Dockerfile .
+
+# 运行容器
+wslc run -d -p 8080:8080 --name qqmusic-api-web \
+  -v ./web/data:/app/web/data \
+  -v ./web/accounts.toml:/app/web/accounts.toml:ro \
+  -v ./web/config.toml:/app/web/config.toml:ro \
+  qqmusic-api-web
+```
+
 挂载说明:
 
 * `web/data/` — 设备信息、凭据状态库、日志等持久化数据。

{qqmusic_api_python-0.6.8 → qqmusic_api_python-0.6.9}/web/config.example.toml

@@ -43,6 +43,11 @@ backend = "memory"
 # redis_prefix = "qqapi:"
 
 
+[client]
+# SDK Client 设备信息文件路径
+# device_path = "web/data/device.json"
+
+
 [credential]
 # 是否启用全局默认登录凭证。Cookie 中显式传入的登录凭证始终优先。
 enabled = false