Agent/gateway/core/channels/router.py

from __future__ import annotations

from gateway.core.channels.manager import TraceBackend


class ChannelTraceRouter:
    """
    与具体 IM 无关：按渠道 user_id 解析 workspace_id，并委托 TraceBackend 获取/创建 trace。

    飞书等渠道的入站消息路由见 ``gateway.core.channels.feishu.router.FeishuMessageRouter``。
    """

    def __init__(
        self,
        *,
        trace_backend: TraceBackend,
        workspace_prefix: str,
        default_agent_type: str = "personal_assistant",
    ) -> None:
        self._trace = trace_backend
        self._workspace_prefix = workspace_prefix
        self._agent_type = default_agent_type

    def _workspace_id_for_user(self, user_id: str) -> str:
        return f"{self._workspace_prefix}:{user_id}"

    async def get_trace_id(self, channel: str, user_id: str, *, create_if_missing: bool = True) -> str:
        """获取或创建 Trace ID（对应 channels.md get_trace_id / create_trace_for_user 语义）。"""
        if not create_if_missing:
            raise NotImplementedError("仅内存后端支持 create_if_missing=False 时需扩展 TraceBackend")
        return await self._trace.get_or_create_trace(
            channel=channel,
            user_id=user_id,
            workspace_id=self._workspace_id_for_user(user_id),
            agent_type=self._agent_type,
            metadata={"source": "channels.channel_trace_router"},
        )

    async def create_trace_for_user(self, channel: str, user_id: str) -> str:
        return await self.get_trace_id(channel, user_id, create_if_missing=True)