docs: classify music library status route

docs/architecture/agent-api-surface-audit.json

@@ -6,7 +6,7 @@
     "provider-skill": 12,
     "stream_or_binary": 10,
     "transport_or_identity": 66,
-    "ui_presentation": 22
+    "ui_presentation": 23
   },
   "dynamic_gateway_routes": [
     {
@@ -21,7 +21,7 @@
   "gateway_http_route_count": 203,
   "gateway_operation_count": 205,
   "matched_gateway_http_route_count": 202,
-  "openapi_operation_count": 395,
+  "openapi_operation_count": 396,
   "operations": [
     {
       "disposition": "consolidated",
@@ -1894,6 +1894,18 @@
         "music"
       ]
     },
+    {
+      "disposition": "ui_presentation",
+      "method": "POST",
+      "operation_ids": [],
+      "owner": "host-ui",
+      "path": "/api/v1/music/library/status",
+      "reason": "Batch music-library presence is a bounded projection for the authenticated artist resource matrix; it is not a standalone Agent business action.",
+      "summary": "批量查询音乐专辑入库状态",
+      "tags": [
+        "music"
+      ]
+    },
     {
       "disposition": "gateway",
       "method": "POST",

docs/architecture/agent-api-surface-audit.md

@@ -5,7 +5,7 @@
 
 ## Result
 
-- OpenAPI HTTP operations: **395**
+- OpenAPI HTTP operations: **396**
 - Stable `moviepilot_api` operations: **205**
 - Exact HTTP routes used by the gateway: **203**
 - OpenAPI routes matched directly by the gateway: **202**
@@ -23,7 +23,7 @@
 | `provider-skill` | 12 | Low-level downloader or media-server capability owned by a provider Skill. |
 | `stream_or_binary` | 10 | Streaming or binary response owned by a direct client transport. |
 | `transport_or_identity` | 66 | Authentication, protocol, callback, account, or conversation transport boundary. |
-| `ui_presentation` | 22 | Frontend or plugin-rendered presentation contract. |
+| `ui_presentation` | 23 | Frontend or plugin-rendered presentation contract. |
 
 ## Bounded Dynamic Routes
 
@@ -183,6 +183,7 @@
 | `GET` | `/api/v1/music/cache` | music | `gateway` | music.cache.get | 查询音乐识别缓存 |
 | `DELETE` | `/api/v1/music/cache/{cache_key}` | music | `gateway` | music.cache.delete | 删除指定音乐识别缓存 |
 | `GET` | `/api/v1/music/explore` | music | `gateway` | music.explore | 探索音乐 |
+| `POST` | `/api/v1/music/library/status` | music | `ui_presentation` | host-ui | 批量查询音乐专辑入库状态 |
 | `POST` | `/api/v1/music/recognize` | music | `gateway` | music.recognize | 识别音乐元数据详情 |
 | `POST` | `/api/v1/notification/config` | notification | `transport_or_identity` | host-runtime | 保存通知渠道并同步登录缓存 |
 | `POST` | `/api/v1/notification/manage` | notification | `transport_or_identity` | host-runtime | 通知渠道统一管理 |

scripts/generate_agent_api_surface_audit.py

@@ -112,6 +112,7 @@ EXPLICIT_TRANSPORT_PATHS = frozenset(
 )
 SUBSCRIPTION_EXECUTION_UI_PREFIX = "/api/v1/subscribe/execution/"
 CLASSIFICATION_POLICY_UI_PREFIX = "/api/v1/media/classification/"
+MUSIC_LIBRARY_STATUS_UI_PATH = "/api/v1/music/library/status"
 
 
 def _gateway_routes() -> dict[tuple[str, str], list[str]]:
@@ -196,6 +197,13 @@ def _classify(
             "Classification policy authoring, validation, preview, impact analysis, and publication are owned by the authenticated frontend editor until a stable Agent governance contract is approved.",
             [],
         )
+    if method == "POST" and path == MUSIC_LIBRARY_STATUS_UI_PATH:
+        return (
+            "ui_presentation",
+            "host-ui",
+            "Batch music-library presence is a bounded projection for the authenticated artist resource matrix; it is not a standalone Agent business action.",
+            [],
+        )
     if path in EXPLICIT_TRANSPORT_PATHS:
         return (
             "transport_or_identity",

tests/test_music_endpoint.py

@@ -132,6 +132,8 @@ def test_media_search_forwards_explicit_music_source():
 
 def test_recognize_music_returns_detail():
     """音乐识别接口应按来源和 ID 经统一识别入口返回详情。"""
+    from app.chain.media import MediaChain
+
     chain = Mock()
     chain.async_recognize_media = AsyncMock(
         return_value=MusicInfo(
@@ -164,6 +166,8 @@ def test_recognize_music_returns_detail():
 
 def test_recognize_music_returns_404_for_unknown_item():
     """音乐详情不存在时接口应返回 404。"""
+    from app.chain.media import MediaChain
+
     chain = Mock()
     chain.async_recognize_media = AsyncMock(return_value=None)