qqmusic-api-python 0.7.3__tar.gz → 0.8.1__tar.gz

{qqmusic_api_python-0.7.3 → qqmusic_api_python-0.8.1}/.gitignore

@@ -14,7 +14,7 @@ device.json
 .ccb/
 docs/superpowers/
 .omo/
-
+.omp/
 # Distribution / packaging
 .Python
 build/

{qqmusic_api_python-0.7.3 → qqmusic_api_python-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: qqmusic-api-python
-Version: 0.7.3
+Version: 0.8.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,7 @@ 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: typing-extensions>=4.12.2
+Requires-Dist: typing-extensions>=4.16.0
 Provides-Extra: upload
 Requires-Dist: cos-python-sdk-v5>=1.9.44; extra == 'upload'
 Description-Content-Type: text/markdown

qqmusic_api_python-0.8.1/docs/coding.md

@@ -0,0 +1,560 @@
+# API 编写指南
+
+`qqmusic_api` 采用 `Client + ApiModule + Request` 的结构:
+
+* `ApiModule` 通过 `@cgi_endpoint` / `@http_endpoint` 声明接口契约，方法体只负责返回 `CgiRequestData` / `HttpRequestData` 装载运行时参数。
+* `Request`（`CgiRequest` / `HttpRequest` 及分页子类）是由上述声明装配出的惰性描述符，被 `await` 时才真正执行。
+* `Client` 是使用者门面，持有默认凭证与平台，并把 `Request` 交由 `RequestEngine` 执行。
+
+## 调用流程图
+
+### 单请求
+
+```text
+模块方法
+  -> 装配为 BaseRequest 描述符 (CgiRequest / HttpRequest 及分页子类)
+  -> await request: RequestExecutor 解析身份并交由 RequestEngine 分派
+  -> CgiExecutor / HttpExecutor 装配物理请求
+  -> Transport.request(prepared) 发送并释放响应
+  -> core/response.py 统一解析
+  -> 返回原始 dict 或 Pydantic 模型
+```
+
+### 批量并发请求
+
+```text
+多个模块方法
+  -> 各自产出 BaseRequest 描述符
+  -> Client.gather(requests)
+  -> RequestEngine.gather(calls, batch_size=...)
+  -> 按请求类型 (CGI / HTTP) 分区并行执行
+  -> CGI 条目按快照身份自动分组, 每组按 batch_size 拆分后经 send_many 批量发送
+  -> 统一解包解析每个响应项, 逐项归属错误
+  -> 按输入顺序还原结果列表
+```
+
+`gather` 的分组边界由执行器按 **快照身份** 计算 (生效平台, 完整凭证, 规范化公共参数, 覆盖模式与签名)。只有这些线上环境完全一致的请求才会安全地合并到同一个批量请求中。
+
+服务端接入不经过 `Client`: 由 `RequestEngine` 配合 `ScopedRequestExecutor` 按请求绑定身份, 单请求流程一致。
+
+## 编写新的 API
+
+### 添加新模块
+
+1. 在 `qqmusic_api/modules/` 下创建新文件，例如 `foo.py`。
+2. 定义模块类，继承 `ApiModule`。
+3. 在 `Client` 中注册为 `@cached_property`。
+
+```python
+# qqmusic_api/modules/foo.py
+from ._base import ApiModule
+from ..core.endpoint import cgi_endpoint, CgiRequestData
+
+
+class FooApi(ApiModule):
+    """Foo 相关 API."""
+
+    @cgi_endpoint(
+        key="foo.get_something",
+        module="music.foo.Svc",
+        method="GetSomething",
+    )
+    def get_something(self, id: int) -> CgiRequestData:
+        """获取某项数据."""
+        return CgiRequestData(param={"id": id})
+```
+
+```python
+# qqmusic_api/core/client.py
+from functools import cached_property
+
+
+class Client:
+    @cached_property
+    def foo(self) -> "FooApi":
+        from ..modules.foo import FooApi
+
+        return FooApi(self)
+```
+
+### 添加新的请求方法
+
+API 方法返回 `BaseRequest` 描述符对象，并不立即发起请求。可以通过声明式装饰器（`@cgi_endpoint` / `@http_endpoint`）或原生构建方法（`self._build_cgi` / `self._build_http`）构建：
+
+#### 1. CGI 接口 (RPC 风格)
+
+对于标准 CGI 风格的 RPC 请求，可以使用 `@cgi_endpoint` 装饰器声明端点契约，并在方法体中返回 `CgiRequestData` 装载运行时参数：
+
+```python
+from ..core.endpoint import cgi_endpoint, CgiRequestData
+
+
+@cgi_endpoint(
+    key="song.get_detail",  # 端点唯一标识
+    module="music.songDetail",  # 接口所属模块
+    method="GetDetail",  # 方法名
+)
+def get_detail(self, song_id: int) -> CgiRequestData:
+    """获取歌曲详情."""
+    return CgiRequestData(
+        param={"songid": song_id},  # 业务参数
+    )
+```
+
+也可以使用 `self._build_cgi(...)` 构建：
+
+```python
+def get_detail(self, song_id: int):
+    """获取歌曲详情."""
+    return self._build_cgi(
+        module="music.songDetail",  # 接口所属模块
+        method="GetDetail",  # 方法名
+        param={"songid": song_id},  # 业务参数
+    )
+```
+
+#### 2. HTTP 接口 (标准 HTTP)
+
+对于标准 HTTP 请求（如直接 GET 请求、获取网页或二维码），可以使用 `@http_endpoint` 装饰器声明，并在方法体中返回 `HttpRequestData`：
+
+```python
+from ..core.endpoint import http_endpoint, HttpRequestData
+
+
+@http_endpoint(
+    key="search.quick_search",
+    method="GET",
+    url="https://c.y.qq.com/splcloud/fcgi-bin/smartbox_new.fcg",
+)
+def quick_search(self, keyword: str) -> HttpRequestData:
+    """快速搜索 (直接返回解析后的 JSON 数据)."""
+    return HttpRequestData(
+        params={"key": keyword},
+    )
+```
+
+也可以使用 `self._build_http(...)` 构建：
+
+```python
+async def quick_search(self, keyword: str) -> dict[str, Any]:
+    """快速搜索 (直接返回解析后的 JSON 数据)."""
+    resp = await self._build_http(
+        "GET",
+        "https://c.y.qq.com/splcloud/fcgi-bin/smartbox_new.fcg",
+        params={"key": keyword},
+    )
+    return resp["data"]
+```
+
+### `@cgi_endpoint` 声明参数说明
+
+`@cgi_endpoint` 装饰器用于在定义期静态声明端点的核心契约：
+
+| 参数 | 类型 | 说明 |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `key` | `str` | 端点唯一标识符（如 `"song.get_detail"`） |
+| `module` | `str` | 接口所属 CGI 模块名 |
+| `method` | `str` | CGI 方法名 |
+| `response_model` | `type[BaseModel]` 或 `None` | 响应模型，为 None 时返回原始 dict |
+| `item_type` | `type` 或 `None` | （仅分页）数据项模型，声明后推导为 `ItemPaginatedCgiRequest` |
+| `pager` | `bool` | （仅分页）是否为分页端点，若 `item_type` 已填则无需填此项 |
+| `sign` | `bool` | 是否对请求进行签名 |
+| `require_login` | `bool` | 是否在执行时强制校验用户登录态 |
+| `platform` | `Platform` 或 `None` | 强制指定该接口使用的目标平台 |
+
+### `CgiRequestData` 运行时参数说明
+
+在被 `@cgi_endpoint` 装饰的函数体内返回，用于承载每次调用的动态参数：
+
+| 参数 | 类型 | 说明 |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `param` | `dict` | 请求体的业务参数 `param` 字段 |
+| `comm` | `dict` 或 `None` | 附加的公共参数 |
+| `override_comm` | `bool` | 为 True 时 `comm` 完全替代自动生成的参数；为 False 时合并 |
+| `credential` | `Credential` 或 `None` | 覆盖本次请求的凭证 |
+| `platform` | `Platform` 或 `None` | 覆盖本次请求的平台 |
+| `preserve_bool` | `bool` 或 `None` | 是否保留布尔值原样（默认转为 0/1 整型） |
+| `pager_strategy` | `PagerStrategy` 或 `None` | 分页策略，必须与装饰器的分页声明匹配 |
+| `items_extractor` | `Callable` 或 `None` | （仅声明了 item_type 时需要）从单页响应对象中提取目标列表的闭包 |
+
+### `@http_endpoint` 声明参数说明
+
+`@http_endpoint` 装饰器用于静态声明 HTTP 接口契约：
+
+| 参数 | 类型 | 说明 |
+| ---------------- | -------------------------------- | -------------------------------------------------------------------- |
+| `key` | `str` | 端点唯一标识符（如 `"search.quick_search"`） |
+| `method` | `str` | HTTP 方法，如 `"GET"`、`"POST"` |
+| `url` | `str` | 请求地址模板，支持 `{param}` 占位符配合 `path_params` 渲染 |
+| `response_model` | `type[ResponseModel]` 或 `None` | 响应模型类型 |
+| `raw` | `bool` 或 `None` | 为 True 时返回 `RawPayload`（当模型为 `RawPayload` 时默认为 True） |
+
+### `HttpRequestData` 运行时参数说明
+
+在被 `@http_endpoint` 装饰的函数体内返回，用于承载每次 HTTP 调用的动态参数：
+
+| 参数 | 类型 | 说明 |
+| ------------- | --------------------------- | --------------------------------------------------------- |
+| `path_params` | `dict[str, Any]` 或 `None` | URL 路径参数，用于格式化 `url` 中的占位符 |
+| `params` | `Any` 或 `None` | URL 查询参数（Query string） |
+| `headers` | `Any` 或 `None` | HTTP 请求头 |
+| `cookies` | `Any` 或 `None` | HTTP 请求 Cookies |
+| `json` | `Any` 或 `None` | 请求体 JSON 数据 |
+| `data` | `Any` 或 `None` | 原始请求体数据 |
+| `credential` | `Credential` 或 `None` | 覆盖本次请求的凭证 |
+| `options` | `dict[str, Any]` | 透传给底层客户端的可选参数（如 `timeout`、`files` 等） |
+
+### `_build_cgi` 参数说明
+
+`_build_cgi` 用于构建 CGI 风格 RPC 请求描述符：
+
+| 参数 | 类型 | 说明 |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `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` | 是否对请求进行签名 |
+| `require_login` | `bool` | 是否在执行时强制校验用户登录态 |
+| `pager_strategy` | `PagerStrategy` 或 `None` | 分页策略，提供后返回 `PaginatedCgiRequest`；可链式调用 `.with_extractor()` 提升为 `ItemPaginatedCgiRequest` |
+
+### `_build_http` 参数说明
+
+`_build_http` 用于构建标准 HTTP 请求描述符，遵循 httpx 风格参数规范，自动装配凭证 Cookies 和平台 User-Agent：
+
+| 参数 | 类型 | 说明 |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------- |
+| `method` | `str` | HTTP 方法，如 `"GET"`、`"POST"` |
+| `url` | `str` | 请求地址 |
+| `params` | `Mapping` 或 `None` | URL 查询参数 |
+| `json` | `Any` 或 `None` | 请求体 JSON 数据 |
+| `data` | `bytes` / `str` / `None` | 原始请求体数据（非 JSON 场景） |
+| `headers` | `Mapping` 或 `None` | HTTP 请求头 |
+| `cookies` | `Mapping` 或 `None` | HTTP 请求 Cookies |
+| `credential` | `Credential` 或 `None` | 覆盖本次请求的凭证，默认使用客户端凭证 |
+| `response_model` | `type[ResponseModel]` 或 `None` | 响应模型类型 |
+| `raw` | `bool` | 校验 HTTP 状态并返回 `RawPayload`（值语义，无需释放） |
+| `**options` | | 透传给底层客户端的参数（`timeout`、`allow_redirects`、`files` 等） |
+
+常见用法：
+
+```python
+# GET 请求
+req = self._build_http("GET", "https://example.com/api", params={"key": "value"})
+
+# POST JSON
+req = self._build_http("POST", "https://example.com/api", json={"key": "value"})
+
+# 覆盖凭证
+req = self._build_http("GET", "https://example.com/api", credential=my_credential)
+
+# 返回 RawPayload 而非解析 JSON
+req = self._build_http("GET", "https://example.com/api", raw=True)
+```
+
+## 响应模型
+
+### 基础用法
+
+每个响应模型都应继承 `models.request.Response`：
+
+```python
+from pydantic import Field
+
+from .request import Response
+
+
+class MyResponse(Response):
+    """我的响应模型."""
+
+    name: str
+    count: int
+```
+
+`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 映射路径，自动从嵌套响应中提取数据：
+
+```python
+class SonglistMeta(Response):
+    """歌单元数据示例."""
+
+    id: int = Field(json_schema_extra={"jsonpath": "$.result.tid"})
+    dirid: int = Field(json_schema_extra={"jsonpath": "$.result.dirId"})
+    name: str = Field(json_schema_extra={"jsonpath": "$.result.dirName"})
+```
+
+对于列表字段，使用 `[*]` 通配符：
+
+```python
+class CommentListResponse(Response):
+    """评论列表响应."""
+
+    comments: list[Comment] = Field(
+        default_factory=list,
+        json_schema_extra={"jsonpath": "$.commentlist[*]"},
+    )
+```
+
+### 字段别名
+
+Pydantic 的 `validation_alias` 支持多别名兼容：
+
+```python
+class Singer(Response):
+    """歌手信息."""
+
+    id: int = Field(
+        default=-1,
+        validation_alias=AliasChoices("id", "singerID", "singerId", "SingerID"),
+    )
+    mid: str = Field(
+        default="",
+        validation_alias=AliasChoices("mid", "singerMid", "singerMID"),
+    )
+```
+
+### 需登录接口
+
+需要登录的接口通过 `@cgi_endpoint` 的 `require_login=True` 参数校验凭证：
+
+```python
+@cgi_endpoint(
+    key="user.get_vip_info",
+    module="VipLogin.VipLoginInter",
+    method="vip_login_base",
+    response_model=UserVipInfoResponse,
+    require_login=True,
+)
+def get_vip_info(self, *, credential: Credential | None = None) -> CgiRequestData:
+    """获取 VIP 信息."""
+    return CgiRequestData(credential=credential)
+```
+
+> 若接口需要凭证对象的属性（如 `musicid` 等）来构建请求内联参数，
+> 仍可通过 `credential = credential or self._client.credential` 获取并显式验证其有效性。
+
+## 连续翻页与批次刷新
+
+### 连续翻页
+
+通过返回的 `CgiRequestData(pager_strategy=...)` 声明连续翻页能力，建议为策略配合显式的 Generic 标注（形如 `OffsetStrategy[GetSonglistDetailResponse]`）以确保静态类型推断。
+若要提取特定类型的数据条目流，请在 `@cgi_endpoint(item_type=...)` 中声明目标类型，并在 `CgiRequestData` 中同时提供 `items_extractor`：
+
+```python
+from ..core.pagination import OffsetStrategy
+
+
+@cgi_endpoint(
+    key="songlist.get_detail",
+    module="music.srfDissInfo.DissInfo",
+    method="CgiGetDiss",
+    response_model=GetSonglistDetailResponse,
+    item_type=Song,
+)
+def get_detail(self, songlist_id: int, num: int = 10, page: int = 1) -> CgiRequestData:
+    """获取歌单详情."""
+    return CgiRequestData(
+        param={
+            "disstid": songlist_id,
+            "song_begin": num * (page - 1),
+            "song_num": num,
+        },
+        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),
+        ),
+        items_extractor=lambda response: response.songs,
+    )
+```
+
+### 批次刷新 (Batch Refresh)
+
+批次刷新（Batch Refresh）是一种针对推荐或关联接口、支持游标复位与防循环重复游标的特殊游标分页，同样通过 `pager_strategy` 声明：
+
+```python
+from ..core.pagination import BatchRefreshStrategy
+from ..models.base import MV
+
+
+@cgi_endpoint(
+    key="song.get_related_mv",
+    module="MvService.MvInfoProServer",
+    method="GetSongRelatedMv",
+    response_model=GetRelatedMvResponse,
+    item_type=RelatedMv,
+)
+def get_related_mv(self, songid: int, last_mvid: str | None = None) -> CgiRequestData:
+    """获取歌曲相关 MV."""
+    return CgiRequestData(
+        param={"songid": str(songid), "songtype": 1, "lastmvid": last_mvid or 0},
+        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),
+        ),
+        items_extractor=lambda response: response.mv,
+    )
+```
+
+### 内置策略速查
+
+| 策略 | 适用场景 | 关键参数 |
+| ---------------------------------- | -------------: | --------------------------------- |
+| `PageStrategy` | 页码递增 | `page_key` |
+| `OffsetStrategy` | 偏移量滑窗 | `offset_key` + `page_size_key` |
+| `CursorStrategy` | 响应游标回写 | `cursor_key` |
+| `MultiFieldContinuationStrategy` | 多字段续翻 | 自定义 `build_next_params` 函数 |
+| `BatchRefreshStrategy` | 批次刷新 | `refresh_key` |
+
+## 请求签名
+
+部分接口需要对请求体进行签名。通过 `@cgi_endpoint` 的 `sign=True` 启用：
+
+```python
+@cgi_endpoint(
+    key="song.get_sheet",
+    module="music.mir.SheetMusicSvr",
+    method="GetMoreSheetMusic",
+    sign=True,
+)
+def get_sheet(self, mid: str) -> CgiRequestData:
+    """获取曲谱."""
+    return CgiRequestData(
+        param={"songMid": mid},
+    )
+```
+
+签名后请求会发送到 `musics.fcg` 而非 `musicu.fcg`，并在 URL 参数中附加 `_`（时间戳）和 `sign`。
+
+## 公共参数 `comm`
+
+默认情况下，`comm` 参数由 `VersionPolicy.build_comm()` 自动生成。可以通过 `comm` 附加额外参数：
+
+```python
+# 合并到自动生成的 comm 中（默认行为）
+CgiRequestData(
+    ...,
+    comm={"extra_key": "value"},
+)
+```
+
+发送前，所有 `comm` 值都会转换为字符串。合并模式下可将值设为 `None` 或空字符串，删除自动生成的同名参数。
+
+使用 `override_comm=True` 完全替代自动生成的参数：
+
+```python
+CgiRequestData(
+    ...,
+    comm={
+        "g_tk": 5381,
+        "uin": "",
+        "format": "json",
+        "inCharset": "utf-8",
+        "outCharset": "utf-8",
+        "notice": 0,
+        "needNewCode": 1,
+    },
+    override_comm=True,
+)
+```
+
+## 异常处理
+
+在抛出或处理异常时，应使用项目统一的基于领域驱动（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`）。
+
+### 基本格式
+
+```python
+"""歌曲模块测试."""
+
+import pytest
+
+from qqmusic_api import Client
+
+
+async def test_query_song(client: Client) -> None:
+    """测试根据 ID 查询歌曲."""
+    result = await client.song.query_song([SongQueryInfo(mid="003w2xz20QlUZt")])
+    assert result.tracks
+    assert result.tracks[0].name
+```
+
+### 使用 parametrize
+
+```python
+@pytest.mark.parametrize("page", [1, 2])
+async def test_general_search(client: Client, page: int) -> None:
+    """测试综合搜索翻页逻辑."""
+    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
+```
+
+### 需要登录的测试
+
+使用 `authenticated_client` fixture：
+
+```python
+async def test_get_vip_info(authenticated_client: Client) -> None:
+    """测试获取 VIP 信息."""
+    result = await authenticated_client.user.get_vip_info()
+    assert result.vip_flag is not None
+```
+
+### 测试分页
+
+```python
+async def test_search_paginate(client: Client) -> None:
+    """测试搜索分页."""
+    pager = client.search.search_by_type("周杰伦", num=5).pager(limit=2)
+
+    assert pager.has_more() is True
+    first_page = await pager.next()
+    assert pager.has_more() is True
+    second_page = await pager.next()
+
+    assert first_page.song
+    assert second_page.song
+```

qqmusic_api_python-0.8.1/docs/reference/model/sound_power.md

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

qqmusic_api_python-0.8.1/docs/reference/modules/sound_power.md

@@ -0,0 +1,3 @@
+# SoundPowerApi
+
+::: modules.sound_power.SoundPowerApi

{qqmusic_api_python-0.7.3 → qqmusic_api_python-0.8.1}/docs/release-notes.md

@@ -1,4 +1,80 @@
 
+## [[0.8.0](https://github.com/L-1124/QQMusicApi/compare/v0.7.3..v0.8.0)] - 2026-10-04
+
+### Bug 修复
+
+* **(core)** 修复请求分页提取器的参数克隆冲突 ([e74d00b](https://github.com/L-1124/QQMusicApi/commit/e74d00b6cc6274676adb9855902234c6a9a9fcb1)) by [@L-1124](https://github.com/L-1124)
+* **(tests)** 修复 disable_parse 移除后的测试残留并清理装饰性框线 ([39fc259](https://github.com/L-1124/QQMusicApi/commit/39fc259bdeefb3fd9f740d678a380da59e98f8da)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 未捕获异常统一返回 JSON 形状的 500 响应 ([95e5ab4](https://github.com/L-1124/QQMusicApi/commit/95e5ab44c79e7503df969677e5848b5b376efafa)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 屏蔽上游 5xx 异常细节并修正凭证快照的阻塞调用 ([2d384b0](https://github.com/L-1124/QQMusicApi/commit/2d384b021d0082dc2715c84884b36d29801ca342)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复池凭证过期判定与刷新未同锁导致的重复登录 ([4426508](https://github.com/L-1124/QQMusicApi/commit/442650810e9fe43d0a646b4dfc8f76696dbb55e5)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 修复调用方 Cookie 凭证被刷新并写回共享池的问题 ([4aeab21](https://github.com/L-1124/QQMusicApi/commit/4aeab216a26b873707c817457321b225a8e9d169)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(core)** Android comm 参数补充注入 traceid ([84cc613](https://github.com/L-1124/QQMusicApi/commit/84cc6131a1cd44939d63edcdde5b3b554211bc88)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 提升全局 Android 协议版本为 20.9.0.8 ([6ce5d7e](https://github.com/L-1124/QQMusicApi/commit/6ce5d7ef6c45cea392173c33e493d98f0f3d2913)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 引入声明式 Endpoint 与无客户端网关 ([116e7fd](https://github.com/L-1124/QQMusicApi/commit/116e7fdb701f6d261ac913c3636b56f188c17ced)) by [@L-1124](https://github.com/L-1124) in [#304](https://github.com/L-1124/QQMusicApi/pull/304)
+* **(core)** 优化 comm 参数与设备标识语义 ([072011a](https://github.com/L-1124/QQMusicApi/commit/072011a5f5d9d60181148d79981701862906d6dc)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 解耦设备缓存并完善并发控制 ([2eb66c4](https://github.com/L-1124/QQMusicApi/commit/2eb66c4c1651d6f525015c8c4bf6cb72e963c814)) by [@L-1124](https://github.com/L-1124)
+* **(core)** [**breaking**] 引入统一请求内核与显式流式读取 ([bc09d1c](https://github.com/L-1124/QQMusicApi/commit/bc09d1c60b1ffb093255938d63fa5a197af9939f)) by [@L-1124](https://github.com/L-1124) in [#303](https://github.com/L-1124/QQMusicApi/pull/303)
+* **(device)** 完善 Android 设备档案生成 ([4c67b50](https://github.com/L-1124/QQMusicApi/commit/4c67b50bfd4a03fde786e63b4fef0a587f3f4d12)) by [@L-1124](https://github.com/L-1124)
+* **(device)** 优化设备生成与 QIMEI 参数 ([f207f82](https://github.com/L-1124/QQMusicApi/commit/f207f8281e63da2b4fac4391dd7dbe10c527d68d)) by [@L-1124](https://github.com/L-1124)
+* **(sound_power)** 新增音响力与听歌榜模块及 Web 路由 ([514fc3f](https://github.com/L-1124/QQMusicApi/commit/514fc3f4f1357d0b73d95f6fd37f65ec9b6d86b7)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 缓存未命中引入请求合并与上游失败标记熔断 ([807421d](https://github.com/L-1124/QQMusicApi/commit/807421db284db78e034d3abb1948228462d7d6e5)) by [@L-1124](https://github.com/L-1124)
+
+### 功能重构
+
+* **(album)** 迁移 AlbumApi 端点至 @cgi_endpoint 并更新 Web 路由 ([7522cea](https://github.com/L-1124/QQMusicApi/commit/7522ceadc69c4be3a3aa188b45f9f3d752109797)) by [@L-1124](https://github.com/L-1124)
+* **(comment)** 迁移 CommentApi 端点至 @cgi_endpoint 并更新 Web 路由 ([1565743](https://github.com/L-1124/QQMusicApi/commit/1565743030dc6bed7c2574ffc37ecb4aec93a919)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 让 CgiRequestData.param 默认为空字典并移除冗余空参数 ([55f7b01](https://github.com/L-1124/QQMusicApi/commit/55f7b014ea4b118d2520278db8ffda900a871bf2)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 彻底移除 disable_parse 选项并更新端点声明范式文档 ([5cf1a06](https://github.com/L-1124/QQMusicApi/commit/5cf1a0645f7fec6523ec05a725ab1ef161d577d1)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 彻底分离端点元数据与运行期覆盖契约 ([46a1a2e](https://github.com/L-1124/QQMusicApi/commit/46a1a2e143698bbf77e3c8b318ff334c491f4755)) by [@L-1124](https://github.com/L-1124)
+* **(core)** 为端点装饰器增加分页类型重载与通用契约校验 ([f443e65](https://github.com/L-1124/QQMusicApi/commit/f443e6561ff5331d7023d2b538a9ace9dd1e8d6e)) by [@L-1124](https://github.com/L-1124)
+* **(lyric)** 迁移 LyricApi 端点至 @cgi_endpoint 并更新 Web 路由 ([e12ae87](https://github.com/L-1124/QQMusicApi/commit/e12ae875b1170d3eb7fbcf7724a801439807166f)) by [@L-1124](https://github.com/L-1124)
+* **(modules)** 为各模块端点声明 item_type 与 pager 契约并清理测试 ([8308052](https://github.com/L-1124/QQMusicApi/commit/8308052cfeee23c8bb78425d28d0bc6d997d8375)) by [@L-1124](https://github.com/L-1124)
+* **(mv)** 迁移 MvApi 端点至 @cgi_endpoint 并更新 Web 路由 ([d2e383c](https://github.com/L-1124/QQMusicApi/commit/d2e383cbcb8e304931afc04bf76167cce365cc1d)) by [@L-1124](https://github.com/L-1124)
+* **(recommend)** 迁移 RecommendApi 端点至 @cgi_endpoint 并更新 Web 路由 ([b97c043](https://github.com/L-1124/QQMusicApi/commit/b97c0436907e51a3ca489797e95f37de53cb1dde)) by [@L-1124](https://github.com/L-1124)
+* **(search)** 迁移 SearchApi 端点至 @cgi_endpoint 并更新 Web 路由 ([25fe3eb](https://github.com/L-1124/QQMusicApi/commit/25fe3ebeac8f65119d7b5ab3bc3f3e681c4a1b01)) by [@L-1124](https://github.com/L-1124)
+* **(singer)** [**breaking**] 移除 get_name_special_display 并合并至 get_info ([e293aa3](https://github.com/L-1124/QQMusicApi/commit/e293aa320f316ae9e654f90503c8a4b9186b0b91)) by [@L-1124](https://github.com/L-1124)
+* **(singer)** 迁移 SingerApi 端点至 @cgi_endpoint 并更新 Web 路由 ([79af270](https://github.com/L-1124/QQMusicApi/commit/79af2704002f53f29024eb0aabd82d9917b798d4)) by [@L-1124](https://github.com/L-1124)
+* **(song)** 迁移 SongApi 端点至 @cgi_endpoint 并更新 Web 路由 ([8c08868](https://github.com/L-1124/QQMusicApi/commit/8c08868cd72c633ac023635fcf4f28c58a25576d)) by [@L-1124](https://github.com/L-1124)
+* **(songlist)** 迁移 SonglistApi 端点至 @cgi_endpoint 并更新 Web 路由 ([ba50d18](https://github.com/L-1124/QQMusicApi/commit/ba50d1864e69d91e6ce896cf47085745e93bed7a)) by [@L-1124](https://github.com/L-1124)
+* **(top)** 迁移 TopApi 端点至 @cgi_endpoint 并更新 Web 路由 ([e2a1fee](https://github.com/L-1124/QQMusicApi/commit/e2a1fee9c7a3d5193a3b2a37b6f6b4a6bf5348de)) by [@L-1124](https://github.com/L-1124)
+* **(user)** 迁移 UserApi 端点至 @cgi_endpoint 并更新 Web 路由 ([49921f6](https://github.com/L-1124/QQMusicApi/commit/49921f600cb9ede33990bffa1d85ef502c985896)) by [@L-1124](https://github.com/L-1124)
+* **(web)** [**breaking**] 优化 web 端参数声明，减少冗余 ([ba95861](https://github.com/L-1124/QQMusicApi/commit/ba95861ee9391f5b5f60f89caa8d4de4af160c8b)) by [@L-1124](https://github.com/L-1124)
+* **(web)** 在路由注册器中增加 Web 模块白名单校验 ([9b0bc65](https://github.com/L-1124/QQMusicApi/commit/9b0bc6590ab597db25b5da378298dfd2a6817881)) by [@L-1124](https://github.com/L-1124)
+
+### 性能优化
+
+* **(qimei)** 优化设备特征计算与静态参数缓存 ([e19fdf2](https://github.com/L-1124/QQMusicApi/commit/e19fdf2f2e8f25a2b3bb24c03b7db16b90a832f6)) by [@L-1124](https://github.com/L-1124)
+
+### 文档更新
+
+* **(coding)** 补充声明式端点撰写指南并更新架构概览与调用流程 ([866bffb](https://github.com/L-1124/QQMusicApi/commit/866bffb6b20ef37ba81b36c7476164f9a8b8e556)) by [@L-1124](https://github.com/L-1124)
+* **(examples)** 新增音响力查询与听歌时长上报示例 ([a408059](https://github.com/L-1124/QQMusicApi/commit/a40805982fd53c2db45db1e878aa9ab6934141af)) by [@L-1124](https://github.com/L-1124)
+
+### 贡献者
+
+* @L-1124
+* @github-actions[bot]
+
+## [[0.7.3](https://github.com/L-1124/QQMusicApi/compare/v0.7.2..v0.7.3)] - 2026-09-13
+
+### Bug 修复
+
+* **(song)** 恢复 get_song_urls 的 mid 数量上限校验 ([c358c77](https://github.com/L-1124/QQMusicApi/commit/c358c77783ef2209a83b734f86a928ba7c91b70b)) by [@L-1124](https://github.com/L-1124)
+
+### 功能更新
+
+* **(singer)** 新增歌手名称透明 PNG 接口及演示 ([3740170](https://github.com/L-1124/QQMusicApi/commit/374017047c39dc987418450b6d513bc216499a69)) by [@Lincb522](https://github.com/Lincb522) in [#302](https://github.com/L-1124/QQMusicApi/pull/302)
+
+### 贡献者
+
+* @L-1124
+* @Lincb522 [#302](https://github.com/L-1124/QQMusicApi/pull/302)
+* @github-actions[bot]
+
 ## [[0.7.2](https://github.com/L-1124/QQMusicApi/compare/v0.7.1..v0.7.2)] - 2026-08-05
 
 ### Bug 修复