refactor: unify llm provider runtime access

app/agent/llm/gateway.py

@@ -5,7 +5,7 @@ from typing import Any, Protocol
 
 
 class LLMProviderRuntimePort(Protocol):
-    """声明 LLM helper 所需的最小 provider 运行时能力。"""
+    """声明 LLM helper 与管理 API 共用的 provider 运行时能力。"""
 
     def resolve_cached_model_metadata(self, **kwargs: Any) -> dict[str, Any] | None:
         """从本地目录缓存解析模型元数据。"""
@@ -27,6 +27,26 @@ class LLMProviderRuntimePort(Protocol):
         """解析兼容接口用于查询模型列表的基础地址。"""
         ...
 
+    async def provider_manage(
+        self,
+        provider: str,
+        action: str,
+        **params: Any,
+    ) -> dict[str, Any]:
+        """执行与具体提供商无关的统一管理动作。"""
+        ...
+
+    async def handle_chatgpt_callback(
+        self,
+        provider_id: str,
+        code: str | None,
+        state: str | None,
+        error: str | None,
+        error_description: str | None,
+    ) -> tuple[bool, str]:
+        """完成 ChatGPT OAuth 回调并返回公开结果。"""
+        ...
+
 
 LLMProviderRuntimeFactory = Callable[[], LLMProviderRuntimePort]
 _provider_runtime_factory: LLMProviderRuntimeFactory | None = None

app/api/endpoints/llm.py

@@ -7,17 +7,11 @@ from app.schemas.common import ManageRequest as _SchemaManageRequest
 from app.schemas.response import Response as _SchemaResponse
 from app.api.response import ResponseAPIRouter
 from app.api.dependencies.auth import get_current_active_superuser_async
+from app.agent.llm.gateway import resolve_llm_provider_runtime
 
 router = ResponseAPIRouter()
 
 
-def _get_llm_provider_manager_type() -> type:
-    """在真实管理请求边界解析 provider 运行时。"""
-    from app.agent.llm.provider import LLMProviderManager
-
-    return LLMProviderManager
-
-
 @router.post(
     "/manage",
     summary="LLM提供商统一管理",
@@ -43,7 +37,7 @@ async def manage_provider(
             "callback_url",
             str(request.url_for("llm_provider_auth_callback", provider_id=payload.target)),
         )
-    result = await _get_llm_provider_manager_type()().provider_manage(
+    result = await resolve_llm_provider_runtime().provider_manage(
         payload.target, payload.action, **params
     )
     return _SchemaResponse(
@@ -76,13 +70,14 @@ async def llm_provider_auth_callback(
     """
     处理需要浏览器回跳的 OAuth provider。
     """
-    success, message = await _get_llm_provider_manager_type()().handle_chatgpt_callback(
+    success, message = await resolve_llm_provider_runtime().handle_chatgpt_callback(
         provider_id,
         code,
         state,
         error,
         error_description,
     )
-    from app.agent.llm.provider import render_auth_result_html
+    # 该符号由 app.agent.llm.__getattr__ 惰性公开，Pylint 无法静态发现。
+    from app.agent.llm import render_auth_result_html  # pylint: disable=no-name-in-module
 
     return HTMLResponse(content=render_auth_result_html(success, message))