refactor: introduce typed host runtime

app/api/context.py

@@ -0,0 +1,48 @@
+"""从 FastAPI AppState 读取类型化宿主能力。"""
+
+from collections.abc import AsyncGenerator
+from typing import cast
+
+from fastapi import Depends, Request
+
+from app.application.messaging.chat import AsyncAgentChatRepository, AsyncUnitOfWork
+from app.startup.context import AgentChatRuntime, HostRuntime
+
+
+def get_host_runtime(request: Request) -> HostRuntime:
+    """返回当前 lifespan 挂载的宿主运行时。"""
+    runtime = getattr(request.app.state, "host_runtime", None)
+    if not isinstance(runtime, HostRuntime):
+        raise RuntimeError("HostRuntime 尚未由启动组合根装配")
+    return runtime
+
+
+def get_agent_chat_runtime(
+    runtime: HostRuntime = Depends(get_host_runtime),
+) -> AgentChatRuntime:
+    """从完整宿主运行时收窄到 Agent 会话能力。"""
+    return runtime.agent_chat
+
+
+async def get_agent_chat_session(
+    runtime: AgentChatRuntime = Depends(get_agent_chat_runtime),
+) -> AsyncGenerator[object, None]:
+    """从类型化 Agent 会话运行时生成请求独占会话。"""
+    async for session in runtime.async_session():
+        yield session
+
+
+def get_agent_chat_repository(
+    session: object = Depends(get_agent_chat_session),
+    runtime: AgentChatRuntime = Depends(get_agent_chat_runtime),
+) -> AsyncAgentChatRepository:
+    """构造绑定当前请求会话的 Agent 会话仓储。"""
+    return cast(AsyncAgentChatRepository, runtime.repository(session))
+
+
+def get_agent_chat_transaction(
+    session: object = Depends(get_agent_chat_session),
+    runtime: AgentChatRuntime = Depends(get_agent_chat_runtime),
+) -> AsyncUnitOfWork:
+    """构造绑定当前请求会话的 Agent 会话事务端口。"""
+    return cast(AsyncUnitOfWork, runtime.transaction(session))

app/api/data.py

@@ -48,6 +48,12 @@ class ApiDataPorts:
 _ports: ApiDataPorts | None = None
 
 
+def configure_api_data_runtime(ports: ApiDataPorts) -> None:
+    """让旧全局 Facade 委托启动组合根创建的同一个端口实例。"""
+    global _ports
+    _ports = ports
+
+
 def configure_api_data_ports(
     *,
     sync_session: SessionProvider,
@@ -57,14 +63,13 @@ def configure_api_data_ports(
     unit_of_work: dict[str, UnitOfWorkFactory],
 ) -> None:
     """由启动组合根登记 API 数据实现，切断 API 对数据库实现包的直接导入。"""
-    global _ports
-    _ports = ApiDataPorts(
+    configure_api_data_runtime(ApiDataPorts(
         sync_session=sync_session,
         async_session=async_session,
         repositories=repositories,
         standalone=standalone,
         unit_of_work=unit_of_work,
-    )
+    ))
 
 
 def get_api_data_ports() -> ApiDataPorts:

app/api/deps.py

@@ -29,6 +29,14 @@ from app.application.workflow import (
 )
 from app.application.messaging.message import MessageQueryService
 from app.application.messaging.chat import AgentChatService
+from app.api.context import (
+    get_agent_chat_repository,
+    get_agent_chat_transaction,
+)
+from app.application.messaging.chat import (
+    AsyncAgentChatRepository,
+    AsyncUnitOfWork as AgentChatUnitOfWork,
+)
 from app.application.mediaserver import MediaServerQueryService
 from app.application.servarr import ServarrSubscriptionService
 from app.application.dashboard import DashboardQueryService
@@ -304,12 +312,13 @@ def get_message_query_service(
 
 
 def get_agent_chat_service(
-        db: AsyncSession = Depends(get_async_db),
+        repository: AsyncAgentChatRepository = Depends(get_agent_chat_repository),
+        unit_of_work: AgentChatUnitOfWork = Depends(get_agent_chat_transaction),
 ) -> AgentChatService:
     """组装 Agent 会话历史查询和删除服务。"""
     return AgentChatService(
-        repository=_repository("agent_chat", db),
-        unit_of_work=_transaction("async", db),
+        repository=repository,
+        unit_of_work=unit_of_work,
     )