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

{qqmusic_api_python-0.6.9 → qqmusic_api_python-0.7.1}/.github/workflows/docs.yml

@@ -19,22 +19,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GH_TOKEN }}
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d  # v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
         with:
           enable-cache: true
           python-version: 3.12
       - name: Install the project
         run: uv sync --group docs
       - name: Generate release-notes
-        uses: orhun/git-cliff-action@v4
+        uses: orhun/git-cliff-action@f50e11560dce63f7c33227798f90b924471a88b5  # v4
         with:
           config: cliff.toml
           args: --verbose --strip all
@@ -55,7 +55,7 @@ jobs:
       - name: Build with zensical
         run: uv run zensical build
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
         with:
           path: ./site
 
@@ -68,4 +68,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5

{qqmusic_api_python-0.6.9 → qqmusic_api_python-0.7.1}/.github/workflows/release.yml

@@ -15,13 +15,13 @@ jobs:
     outputs:
       release_body: ${{ steps.git-cliff.outputs.content }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           fetch-depth: 0
           token: ${{ secrets.GH_TOKEN }}
       - name: Generate release body
         id: git-cliff
-        uses: orhun/git-cliff-action@v4
+        uses: orhun/git-cliff-action@f50e11560dce63f7c33227798f90b924471a88b5  # v4
         with:
           args: -vv --latest --strip all
 
@@ -32,11 +32,11 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           token: ${{ secrets.GH_TOKEN }}
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
         with:
           enable-cache: true
       - name: Install the project
@@ -51,11 +51,11 @@ jobs:
     needs: [generate-release-body, publish]
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
         with:
           token: ${{ secrets.GH_TOKEN }}
       - name: Release
-        uses: softprops/action-gh-release@v3
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228  # v3
         with:
           body: ${{ needs.generate-release-body.outputs.release_body }}
           tag_name: ${{ github.ref_name }}

{qqmusic_api_python-0.6.9 → qqmusic_api_python-0.7.1}/.github/workflows/testing.yml

@@ -10,9 +10,9 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803  # v6
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@94527f2e458b27549849d47d273a16bec83a01e9  # v7
         with:
           enable-cache: true
           python-version: "3.10"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qqmusic-api-python
-Version: 0.6.9
+Version: 0.7.1
 Summary: QQ音乐API封装库
 Project-URL: documentation, https://l-1124.github.io/QQMusicApi/
 Project-URL: homepage, https://l-1124.github.io/QQMusicApi/
@@ -35,7 +35,6 @@ Requires-Dist: niquests[speedups]>=3.18.7
 Requires-Dist: orjson>=3.10.15
 Requires-Dist: paho-mqtt>=2.1.0
 Requires-Dist: pydantic>=2.13.3
-Requires-Dist: tarsio>=0.5.1
 Requires-Dist: typing-extensions>=4.12.2
 Provides-Extra: upload
 Requires-Dist: cos-python-sdk-v5>=1.9.44; extra == 'upload'

{qqmusic_api_python-0.6.9 → qqmusic_api_python-0.7.1}/docs/coding.md

@@ -15,9 +15,9 @@
   -> Request
   -> await request
   -> Client.execute(request)
-  -> Client.request_api(...)  (根据 request.is_jce 分发改用 JCE 或 JSON 协议)
+  -> Client.request_api(...)
   -> Client._build_result(...)
-  -> 返回原始 dict / TarsDict 或 Pydantic 模型
+  -> 返回原始 dict 或 Pydantic 模型
 ```
 
 ### 批量并发请求
@@ -66,6 +66,7 @@ class FooApi(ApiModule):
 # qqmusic_api/core/client.py
 from functools import cached_property
 
+
 class Client:
     @cached_property
     def foo(self) -> "FooApi":
@@ -81,9 +82,9 @@ API 方法返回 `Request` 对象，不直接发起请求。使用 `self._build_
 def get_detail(self, song_id: int):
     """获取歌曲详情."""
     return self._build_request(
-        module="music.songDetail",       # 接口所属模块
-        method="GetDetail",              # 方法名
-        param={"songid": song_id},       # 业务参数
+        module="music.songDetail",  # 接口所属模块
+        method="GetDetail",  # 方法名
+        param={"songid": song_id},  # 业务参数
     )
 ```
 
@@ -103,21 +104,20 @@ async def quick_search(self, keyword: str) -> dict[str, Any]:
 
 ### `_build_request` 参数说明
 
-| 参数             | 类型                        | 说明                                                      |
-|------------------|-----------------------------|-----------------------------------------------------------|
-| `module`         | `str`                       | 接口所属模块名                                            |
-| `method`         | `str`                       | 方法名                                                    |
-| `param`          | `dict`                      | 业务参数                                                  |
-| `response_model` | `type[BaseModel]` 或 `None` | 响应模型，为 None 时返回原始 dict                         |
-| `comm`           | `dict` 或 `None`            | 附加的公共参数                                            |
-| `override_comm`  | `bool`                      | 为 True 时 `comm` 完全替代自动生成的参数；为 False 时合并 |
-| `credential`     | `Credential` 或 `None`      | 覆盖本次请求的凭证                                        |
-| `platform`       | `Platform` 或 `None`        | 覆盖本次请求的平台                                        |
-| `is_jce`         | `bool`                      | 是否作为 JCE (Tars) 二进制协议发送                        |
-| `preserve_bool`  | `bool`                      | 是否保留布尔值原样（默认转为 0/1 整型）                   |
-| `sign`           | `bool`                      | 是否对请求进行签名                                        |
-| `pager_meta`     | `PagerMeta` 或 `None`       | 分页元数据，提供后返回 `PaginatedRequest`                 |
-| `refresh_meta`   | `RefreshMeta` 或 `None`     | 换一批元数据，提供后返回 `RefreshableRequest`             |
+| 参数               | 类型                          | 说明                                                                                                        |
+|--------------------|-------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `module`           | `str`                         | 接口所属模块名                                                                                              |
+| `method`           | `str`                         | 方法名                                                                                                      |
+| `param`            | `dict`                        | 业务参数                                                                                                    |
+| `response_model`   | `type[BaseModel]` 或 `None`   | 响应模型，为 None 时返回原始 dict                                                                           |
+| `comm`             | `dict` 或 `None`              | 附加的公共参数                                                                                              |
+| `override_comm`    | `bool`                        | 为 True 时 `comm` 完全替代自动生成的参数；为 False 时合并                                                   |
+| `credential`       | `Credential` 或 `None`        | 覆盖本次请求的凭证                                                                                          |
+| `platform`         | `Platform` 或 `None`          | 覆盖本次请求的平台                                                                                          |
+| `preserve_bool`    | `bool`                        | 是否保留布尔值原样（默认转为 0/1 整型）                                                                     |
+| `sign`             | `bool`                        | 是否对请求进行签名                                                                                          |
+| `pager_strategy`   | `PagerStrategy` 或 `None`     | 分页策略，提供后返回 `PaginatedRequest`；可链式调用 `.with_extractor()` 提升为 `ItemPaginatedRequest`       |
+| `refresh_strategy` | `RefresherStrategy` 或 `None` | 换一批策略，提供后返回 `RefreshableRequest`；可链式调用 `.with_extractor()` 提升为 `ItemRefreshableRequest` |
 
 ### `client.request` 参数说明
 
@@ -176,6 +176,17 @@ class MyResponse(Response):
 
 `Response` 基类配置了 `frozen=True`（不可变）和 `extra="ignore"`（忽略多余字段）。
 
+!!! warning "Pydantic 默认值规范"
+
+    定义模型时应避免使用 `None` 作为隐式兜底默认值。如果字段可选或为空，应当使用显式的空标量，或通过 `Field(default_factory=...)` 声明：
+    ```python
+    class Album(Response):
+        name: str = ""
+        publish_time: str = ""
+        # 列表必须使用 default_factory
+        singers: list[Singer] = Field(default_factory=list)
+    ```
+
 ### JSONPath 字段映射
 
 可以通过 `Field(json_schema_extra={"jsonpath": ...})` 声明字段的 JSONPath 映射路径，自动从嵌套响应中提取数据：
@@ -239,14 +250,16 @@ def get_vip_info(self, *, credential: Credential | None = None):
 > 若接口需要凭证对象的字段来构建请求参数，
 > 仍可显式调用 `_require_login` 获取凭证对象。
 
-## 翻页与换一批
+## 连续翻页与批次刷新
 
 ### 连续翻页
 
-通过 `pager_meta` 声明连续翻页能力，返回的请求对象会暴露 `.paginate()`：
+通过 `pager_strategy` 声明连续翻页能力，建议配合显示 Generic 标注（形如
+`OffsetStrategy[GetSonglistDetailResponse]`）以确保静态类型检查与类型推断的准确性，并通过 `.with_extractor()`
+链式调用绑定实体数据项的提取逻辑：
 
 ```python
-from ..core.pagination import OffsetStrategy, PagerMeta, ResponseAdapter
+from ..core.pagination import OffsetStrategy
 
 
 def get_detail(self, songlist_id: int, num: int = 10, page: int = 1):
@@ -260,23 +273,23 @@ def get_detail(self, songlist_id: int, num: int = 10, page: int = 1):
             "song_num": num,
         },
         response_model=GetSonglistDetailResponse,
-        pager_meta=PagerMeta(
-            strategy=OffsetStrategy(offset_key="song_begin", page_size_key="song_num"),
-            adapter=ResponseAdapter(
-                has_more_flag="hasmore",
-                total="total",
-                count=lambda response: len(response.songs),
-            ),
+        pager_strategy=OffsetStrategy[GetSonglistDetailResponse](
+            offset_key="song_begin",
+            page_size_key="song_num",
+            has_more_extractor=lambda response: bool(response.hasmore),
+            total_extractor=lambda response: response.total,
+            count_extractor=lambda response: len(response.songs),
         ),
-    )
+    ).with_extractor(lambda response: response.songs)
 ```
 
-### 换一批
+### 批次刷新 (Batch Refresh)
 
-通过 `refresh_meta` 声明换一批能力，返回的请求对象会暴露 `.refresh()`：
+批次刷新（Batch Refresh）是一种针对推荐或关联接口、支持游标复位与防循环重复游标的特殊游标分页，同样通过 `pager_strategy` 声明：
 
 ```python
-from ..core.pagination import BatchRefreshStrategy, RefreshMeta, ResponseAdapter
+from ..core.pagination import BatchRefreshStrategy
+from ..models.base import MV
 
 
 def get_related_mv(self, songid: int, last_mvid: str | None = None):
@@ -286,14 +299,12 @@ def get_related_mv(self, songid: int, last_mvid: str | None = None):
         method="GetSongRelatedMv",
         param={"songid": str(songid), "songtype": 1, "lastmvid": last_mvid or 0},
         response_model=GetRelatedMvResponse,
-        refresh_meta=RefreshMeta(
-            strategy=BatchRefreshStrategy(refresh_key="lastmvid"),
-            adapter=ResponseAdapter(
-                has_more_flag="has_more",
-                cursor=lambda response: response.mv[-1].id if response.mv else None,
-            ),
+        pager_strategy=BatchRefreshStrategy[GetRelatedMvResponse](
+            refresh_key="lastmvid",
+            cursor_extractor=lambda response: response.mv[-1].id if response.mv else None,
+            has_more_extractor=lambda response: bool(response.has_more),
         ),
-    )
+    ).with_extractor(lambda response: response.mv)
 ```
 
 ### 内置策略速查
@@ -304,26 +315,7 @@ def get_related_mv(self, songid: int, last_mvid: str | None = None):
 | `OffsetStrategy`                 |   偏移量滑窗 | `offset_key` + `page_size_key`  |
 | `CursorStrategy`                 | 响应游标回写 | `cursor_key`                    |
 | `MultiFieldContinuationStrategy` |   多字段续翻 | 自定义 `build_next_params` 函数 |
-| `BatchRefreshStrategy`           |       换一批 | `refresh_key`                   |
-
-`pager_meta` 与 `refresh_meta` 不能同时声明。
-
-## JCE (Tars) 协议
-
-部分接口使用 JCE 二进制协议而非 JSON。通过 `is_jce=True` 启用：
-
-```python
-def get_something(self):
-    """获取数据 (JCE 协议)."""
-    return self._build_request(
-        module="music.foo.Svc",
-        method="GetSomething",
-        param={0: "value"},  # JCE 使用整数 key
-        is_jce=True,
-    )
-```
-
-JCE 协议的响应会自动解码为 `TarsDict`。
+| `BatchRefreshStrategy`           |     批次刷新 | `refresh_key`                   |
 
 ## 请求签名
 
@@ -372,6 +364,20 @@ self._build_request(
 )
 ```
 
+## 异常处理
+
+在抛出或处理异常时，应使用项目统一的基于领域驱动（DDD）风格的异常类（继承自 `BaseApiException` 或 `ApiException`
+）。在包装底层异常时，必须使用原生异常链（`raise ... from exc`）保留堆栈追踪：
+
+```python
+from ..core.exceptions import ApiDataError
+
+try:
+# ...
+except KeyError as e:
+    raise ApiDataError("无法解析歌曲信息") from e
+```
+
 ## 编写测试
 
 测试文件放在 `tests/` 下，按模块命名（如 `test_song.py`）。
@@ -388,7 +394,7 @@ from qqmusic_api import Client
 
 async def test_query_song(client: Client) -> None:
     """测试根据 ID 查询歌曲."""
-    result = await client.song.query_song(["003w2xz20QlUZt"])
+    result = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
     assert result.tracks
     assert result.tracks[0].name
 ```
@@ -398,8 +404,15 @@ async def test_query_song(client: Client) -> None:
 ```python
 @pytest.mark.parametrize("page", [1, 2])
 async def test_general_search(client: Client, page: int) -> None:
-    """测试综合搜索翻页."""
-    result = await client.search.general_search("周杰伦", page=page)
+    """测试综合搜索翻页逻辑."""
+    try:
+        result = await client.search.general_search("周杰伦", page=page)
+    except Exception as e:
+        # 示例：优雅处理网络风控或限流 (需根据实际异常类型调整)
+        if "limit" in str(e).lower() or "risk" in str(e).lower():
+            pytest.skip(f"Triggered rate limit or risk control: {e}")
+        raise
+
     assert result.song.items is not None
 ```
 
@@ -419,7 +432,7 @@ async def test_get_vip_info(authenticated_client: Client) -> None:
 ```python
 async def test_search_paginate(client: Client) -> None:
     """测试搜索分页."""
-    pager = client.search.search_by_type("周杰伦", num=5).paginate(limit=2)
+    pager = client.search.search_by_type("周杰伦", num=5).pager(limit=2)
 
     assert pager.has_more() is True
     first_page = await pager.next()

{qqmusic_api_python-0.6.9 → qqmusic_api_python-0.7.1}/docs/contributing.md

@@ -76,11 +76,19 @@ uv run mkdocs serve
 * Lint 使用 [Ruff](https://docs.astral.sh/ruff/)
 * 类型检查使用 `pyrefly`
 
+## 测试规范
+
+* **专注 Modules 层**：测试重心放在 `modules` 层，将其视为黑盒。采用基于数据驱动（`@pytest.mark.parametrize`）的函数式测试方法。
+* **真实网络请求（No Mock）**：禁止 Mock 底层网络请求或核心组装逻辑。必须直接与真实的 QQ 音乐 API 交互。
+* **优雅处理限流**：触发上游 API 风控或频率限制异常时，必须捕获异常并调用 `pytest.skip()` 安全跳过，严禁导致测试失败。
+* **平铺函数写法**：摒弃测试类（`class TestXXX`），强制采用独立纯函数（Flat Functions）。
+* **无需过度清理**：对于获取、查询类操作，验证连通性与模型解析即可。
+
 ## 代码注释
 
 * 注释内容包括：模块注释、类注释、函数注释、参数类型注释、返回值注释
 * 注释风格遵循 [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
-* 测试函数应包含单行中文 docstring（英文标点）
+* 测试用例必须包含**单行中文 docstring**，且内部必须使用**英文标点符号**。
 
 ## 文档规范
 

qqmusic_api_python-0.7.1/docs/reference/model/helper.md

@@ -0,0 +1,3 @@
+# helper
+
+::: models.helper

qqmusic_api_python-0.7.1/docs/reference/model/private_message.md

@@ -0,0 +1,3 @@
+# private_message
+
+::: models.private_message

qqmusic_api_python-0.7.1/docs/reference/modules/helper.md

@@ -0,0 +1,3 @@
+# HelperApi
+
+::: modules.helper.HelperApi

qqmusic_api_python-0.7.1/docs/reference/modules/helper_utils.md

@@ -0,0 +1,3 @@
+# HelperUtils
+
+::: modules.helper_utils

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

@@ -1,4 +1,57 @@
 
+## [[0.7.0](https://github.com/L-1124/QQMusicApi/compare/v0.6.9..v0.7.0)] - 2026-07-22
+
+### Bug 修复
+
+* fix retry import path ([75d0693](https://github.com/L-1124/QQMusicApi/commit/75d069344a07c6713b4a616ed6304ca6dc1b740a)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(lyric)** 支持指定特殊歌曲类型(song_type)查询歌词 ([1b0aae0](https://github.com/L-1124/QQMusicApi/commit/1b0aae0db3ee6876b3a77b8d1ce3057b4b3c9cd5)) by [@L-1124](https://github.com/L-1124)
+* **(song)** [**breaking**] 重构歌曲查询支持 SongQueryInfo 与 Web POST 批量路由 ([4cbb2c6](https://github.com/L-1124/QQMusicApi/commit/4cbb2c6e993d58db71494ce31809a144bfc33be4)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
+## [[0.6.9](https://github.com/L-1124/QQMusicApi/compare/v0.6.8..v0.6.9)] - 2026-07-12
+
+### Bug 修复
+
+* **(web)** 修复凭据刷新异常捕获过宽与 ETag 缓存机制形同虚设的问题 ([305a063](https://github.com/L-1124/QQMusicApi/commit/305a0637f6261b3de3710c504dc8b22ec0ec52b8)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复配置账号由于重置逻辑缺陷被永久标记失效与流式响应并发槽位泄露 ([56f3034](https://github.com/L-1124/QQMusicApi/commit/56f30347a5182380e14febb1b6b1a80debc74ea3)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 避免将 credential 对象盲目混入参数导致 SDK 签名报错 ([fc8b32c](https://github.com/L-1124/QQMusicApi/commit/fc8b32ca1d8d20f16c52f37272798b3688f2848b)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复 KeyedLock finalizer 泄漏与 Redis 序列化 Pydantic 模型问题 ([5440a5e](https://github.com/L-1124/QQMusicApi/commit/5440a5e83b1d110d29f4e1b2eab74f5a8f509847)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修正 songlist 创建与删除路由的 HTTP 方法 ([43c9ce6](https://github.com/L-1124/QQMusicApi/commit/43c9ce6fd0779895afe70a5c7062d7ead0d69957)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复凭据刷新锁与限流器的内存泄漏 ([c5ed6a3](https://github.com/L-1124/QQMusicApi/commit/c5ed6a315e7de680b60b63199350fca276781a46)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复 search 路由声明中 Any 导致的类型检查错误 ([d1aea06](https://github.com/L-1124/QQMusicApi/commit/d1aea0631aeee866cc8b09d1d6a086b07f24e7a9)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复返回 bool 类型时生成的文档和数据格式问题 ([af8550d](https://github.com/L-1124/QQMusicApi/commit/af8550d08038dc8f66be39e28c9d3a905abf7e63)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(web)** 添加 UserApi 的DisLike和favor api ([b1aa67d](https://github.com/L-1124/QQMusicApi/commit/b1aa67d5e6608d722b337c53274b4d91963a008d)) by [@L-1124](https://github.com/L-1124)
+* 新增新碟上架 / MV 分类 / 收藏专辑 / 收藏歌曲接口与推荐新歌地区筛选 ([520c92b](https://github.com/L-1124/QQMusicApi/commit/520c92bd4d3546a20358c0a6daf47f67af8813d8)) by [@jinzhongjia](https://github.com/jinzhongjia) in [#284](https://github.com/L-1124/QQMusicApi/pull/284)
+
+### 功能重构
+
+* **(web)** 收敛配置修改与硬编码路径到配置层 ([0e5950c](https://github.com/L-1124/QQMusicApi/commit/0e5950c9fec28783f081c7d37754de130dcd1950)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 抽取统一的 refresh_and_store 方法消除重复，并补全重试刷新失败时的无效标记逻辑 ([a4a0729](https://github.com/L-1124/QQMusicApi/commit/a4a072984f2dce212885bc240640c9a859d9b0ed)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 移除 songlist 的动态 getattr 分发以恢复类型安全与修复潜在凭据 KeyError ([c1030e1](https://github.com/L-1124/QQMusicApi/commit/c1030e1d867eed8e42957dbf797f548a754796e5)) by [@L-1124](https://github.com/L-1124)
+
+### 性能优化
+
+* **(web)** 启用 SQLite WAL 模式并延迟反序列化随机凭据 ([7d01994](https://github.com/L-1124/QQMusicApi/commit/7d019942ae3812fe286d90eb668dc52318ccabe7)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 缓存路由参数解析以避免重复的 SDK 签名内省 ([61cc5a5](https://github.com/L-1124/QQMusicApi/commit/61cc5a5494afb750149d6689e252cb429e9d109d)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 抽取 app 为会话级 fixture 以大幅降低测试耗时 ([6d13b50](https://github.com/L-1124/QQMusicApi/commit/6d13b50ad42c1bf8f56c596a2fd810cadc23208d)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 移除缓存层与响应中不必要的双重序列化 ([bbc865c](https://github.com/L-1124/QQMusicApi/commit/bbc865c8aa52da6a027064510e94c8fcf8d5ab76)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @jinzhongjia [#284](https://github.com/L-1124/QQMusicApi/pull/284)
+* @github-actions[bot]
+
 ## [[0.6.8](https://github.com/L-1124/QQMusicApi/compare/v0.6.7..v0.6.8)] - 2026-07-01
 
 ### Bug 修复

{qqmusic_api_python-0.6.9 → qqmusic_api_python-0.7.1}/docs/tutorial/download.md

@@ -34,7 +34,7 @@ asyncio.run(main())
 通过 `query_song` 获取歌曲信息后，可从 `pay` 字段判断是否需要付费：
 
 ```python
-song = await client.song.query_song(["003w2xz20QlUZt"])
+song = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
 track = song.tracks[0]
 
 # pay_play: 1=需要付费播放, 0=免费
@@ -72,7 +72,7 @@ for info in urls.data:
 `query_song` 返回的 `file` 字段包含各音质的文件大小，值为 `0` 表示该音质不存在：
 
 ```python
-song = await client.song.query_song(["003w2xz20QlUZt"])
+song = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
 track = song.tracks[0]
 
 file = track.file

qqmusic_api_python-0.7.1/docs/tutorial/pagination.md

@@ -0,0 +1,177 @@
+# Pagination
+
+QQMusicApi 提供了统一的分页体系：
+
+* **`PaginatedRequest`**：具备连续翻页与批次刷新能力的请求描述符。既可直接 `await` 获取首批响应，也可通过 `.pager()`
+  手动按需步进，或使用 `.paginate()`、`.collect()` 和 `async for` 进行流式与批量遍历。
+* **`ItemPaginatedRequest`**：具备数据项提取能力的分页扩展类。除具备通用分页方法外，还通过 `.iter_items()` 与
+  `.collect_items()` 实现了跨越页面边界、直接消费单一具体业务元素（如歌曲、专辑等）的功能。
+
+## 1. 单次请求与无状态步进
+
+即使请求具备分页能力，你依然可以像普通请求一样直接 `await` 它，仅拉取单页数据：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        # 仅获取第 1 页数据
+        first_page = await client.album.get_new_album(page=1, num=10)
+        print(len(first_page.albums))
+
+
+asyncio.run(main())
+```
+
+如果你希望配合上一次响应手动构建下一页请求：
+
+```python
+req1 = client.album.get_new_album(page=1, num=10)
+res1 = await req1
+
+# 根据上一次响应获取下一次请求的描述符
+req2 = req1.next_request(res1)
+if req2 is not None:
+    res2 = await req2
+```
+
+## 2. 有状态控制器
+
+通过 `.pager()` 可以创建一个有状态的 `AsyncPager` 控制器：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        pager = client.comment.get_hot_comments(102065756, page_size=5).pager(limit=2)
+
+        while pager.has_more():
+            page = await pager.next()
+            print(len(page.comments))
+
+
+asyncio.run(main())
+```
+
+> `has_more()` 只读取当前分页器的内部状态，不会发起网络请求。`next()` 没有更多数据时会抛出 `StopAsyncIteration`。
+
+## 3. 全量收集与条目平铺
+
+如果你希望直接获取多页响应列表，或者直接获取展平后的所有实体数据项（如所有歌曲或专辑）。为防止无休止拉取带来的耗时与风控风险，强烈建议调用时始终设置合理的
+`limit` 参数：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        req = client.singer.get_album_list(mid="0025NhlN2yWrP4")
+
+        # 收集前 3 页的 Response 响应对象列表
+        pages = await req.collect(limit=3)
+        print(f"共获取 {len(pages)} 页响应")
+
+        # 自动跨页展开提取前 25 个专辑实体
+        albums = await req.collect_items(limit=25)
+        print(f"共收集 {len(albums)} 个专辑实体")
+
+
+asyncio.run(main())
+```
+
+## 4. 异步流式迭代
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        req = client.search.search_by_type("周杰伦", num=5)
+
+        # 方式 1：直接迭代对象本身，等价于 paginate()，连续翻页直至尾页
+        async for page in req:
+            print("当前页歌曲数:", len(page.song))
+            break  # 演示示例：仅处理一页后退出
+
+        # 方式 2：显式限制最大翻页数（推荐在生产环境中为循环设置合理的上限）
+        async for page in req.paginate(limit=2):
+            print("当前页歌曲数:", len(page.song))
+
+        # 方式 3：跨页条目级别迭代（自动展平为实体）
+        async for song in req.iter_items(limit=10):
+            print("歌曲名:", song.name)
+
+
+asyncio.run(main())
+```
+
+## 5. 批次刷新与单批次步进
+
+部分关联或推荐类接口（如歌曲相关 MV、相似歌曲等）并非按传统的页码（Page）或偏移量（Offset）递增，而是 **按批次（Batch）** 持续更新内容。
+
+对于此类以批次刷新为主、常通过单次触发拉取的场景，推荐使用有状态的分页控制器 `.pager()` 配合 `.first()` 与 `.next()`
+精准控制每一批次的获取：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        # 1. 实例化分页控制器
+        pager = client.song.get_related_mv(1114857).pager()
+
+        # 2. 首次加载页面时，拉取首批推荐数据
+        first_batch = await pager.first()
+        print("首批 MV 数量:", len(first_batch.mv))
+
+        # 3. 按需触发：调用 pager.next() 刷新拉取下一个批次
+        if pager.has_more():
+            next_batch = await pager.next()
+            print("下一批 MV 数量:", len(next_batch.mv))
+
+
+asyncio.run(main())
+```
+
+通过 `pager().first()` 与 `pager().next()`，既能在规范的接口契约下享受自动游标维护与防重复终止保护，又能贴合按批次更新的数据消费模式。
+
+## 6. 动态数据项提取
+
+如果你使用的某个 API 返回的请求对象是原生的 `PaginatedRequest`（即 API 层没有预设数据项提取器），你仍然可以通过
+`.with_extractor()` 动态注入一个提取逻辑。这会将请求无缝转换为具备跨页提取能力的 `ItemPaginatedRequest`。
+
+这在处理一些层级较深、或者没有统一结构的响应时非常有用：
+
+```python
+import asyncio
+from qqmusic_api import Client
+
+
+async def main() -> None:
+    async with Client() as client:
+        # 这个 API 返回原生的 PaginatedRequest
+        req = client.search.general_search("周杰伦")
+
+        # 动态绑定 extractor
+        # 此时 item_req 类型变为 ItemPaginatedRequest
+        item_req = req.with_extractor(lambda r: r.song.items if r.song else [])
+
+        # 现在你可以非常自然地跨页迭代数据项了！
+        async for song in item_req.iter_items(limit=10):
+            print("提取到的歌曲:", song)
+
+
+asyncio.run(main())
+```