"""AgentRunAdapter：实现 AgentRunPort，通过 AgentRunExecutionPort 委托执行。 - createAgentRun 委托 AgentRunExecutionPort.createAgentRunView 创建运行 - streamAgentRun 委托 AgentRunExecutionPort.streamAgentRunEvents 输出流式事件 - getAgentRunFinalOutput 委托 AgentRunExecutionPort.listRunStreamEvents 重放事件流 - 必须支持 Agent 渠道上下文注入（由 AgentRunCmd.context 携带） - 必须支持渠道工具注册（由 AgentRunCmd.context.channel_tools 携带） - 必须支持可信注入边界（服务端强制注入发送者 ID） 依赖边界：主要依赖 yuxi.channels.contract（端口 + DTO + 错误）， 通过构造函数注入 AgentRunExecutionPort 消除对 yuxi.services 的直接 跨层依赖（ADP-001）。createAgentRun 通过 ServiceAccountPort 解析执行 身份（服务账号 uid），并通过 pg_manager 获取 AsyncSession 注入下游， 以支撑会话归属与用户存在性校验（Task 12）。 """ from __future__ import annotations from collections.abc import AsyncIterator from typing import Any from yuxi.channels.contract.dtos.agent_run import AgentRunCmd, AgentRunId from yuxi.channels.contract.dtos.common import MessageContent from yuxi.channels.contract.dtos.option import Nothing, Option, Some from yuxi.channels.contract.dtos.stream_event import StreamEvent from yuxi.channels.contract.dtos.tools import ChannelTool from yuxi.channels.contract.errors import ( DependencyError, InternalError, NotFoundError, ValidationError, ) from yuxi.channels.contract.errors.base import Error from yuxi.channels.contract.ports.driven.agent_run_execution_port import AgentRunExecutionPort from yuxi.channels.contract.ports.driven.agent_run_port import AgentRunPort from yuxi.channels.contract.ports.driven.logger_port import LoggerPort from yuxi.channels.contract.ports.driven.service_account_port import ServiceAccountPort from yuxi.storage.postgres.manager import pg_manager __all__ = ["AgentRunAdapter"] # 单次分页读取的事件上限，与 stream_agent_run_events 保持一致 _EVENTS_PAGE_LIMIT = 200 def _serialize_channel_tool(tool: ChannelTool) -> dict[str, Any]: """将 ``ChannelTool`` 序列化为可存入 meta 的字典。 ``ChannelTool`` 为 frozen dataclass，无法直接序列化到 meta 字典。 本函数把工具名称、描述、handler_id 与参数列表转换为纯字典结构， 供下游 ``resolve_configured_runtime_tools`` 重建为 LangChain 工具。 参数： tool: 渠道工具实例。 返回： 可序列化的工具字典，含 name / description / handler_id / parameters / scope。 """ return { "name": tool.name, "description": tool.description, "handler_id": tool.handler_id, "parameters": [ { "name": p.name, "type": p.type, "description": p.description, "required": p.required, "default": p.default, } for p in tool.parameters ], "scope": tool.scope, } class AgentRunAdapter(AgentRunPort): """Agent 运行被驱动适配器。 通过构造函数注入 ``AgentRunExecutionPort`` 委托实现 ``AgentRunPort`` 契约，不直接依赖 ``yuxi.services``（ADP-001）。 ``createAgentRun`` 委托 ``execution_port.createAgentRunView`` 创建运行 并注入渠道上下文、渠道工具列表与可信发送者；``streamAgentRun`` 委托 ``execution_port.streamAgentRunEvents`` 输出流式事件并转换为 ``StreamEvent`` DTO；``getAgentRunFinalOutput`` 委托 ``execution_port.listRunStreamEvents`` 重放 Redis Stream 事件获取完整 输出文本，用于截断补全候选。 执行身份解析（Task 12）：``createAgentRun`` 通过 ``ServiceAccountPort`` 按 channel_type + channel_account_id 解析服务 账号，以服务账号 uid 作为 ``current_uid`` 注入下游，解决使用渠道发送者 ID 导致会话归属校验失败的问题；同时通过 ``pg_manager`` 获取真实 AsyncSession 注入 ``createAgentRunView``，支撑下游用户存在性校验。 异常放行（ADP-002 / INV-7）：``streamAgentRun`` 与 ``getAgentRunFinalOutput`` 在 ``except Exception`` 兜底前显式放行 ``ValidationError`` / ``DependencyError`` / ``NotFoundError`` 契约错误， 避免契约错误被包装为 ``DependencyError`` 丢失语义。 """ def __init__( self, execution_port: AgentRunExecutionPort, logger: LoggerPort, service_account_port: ServiceAccountPort, ) -> None: """初始化适配器。 Args: execution_port: Agent 运行执行被驱动端口，封装 ``agent_run_service`` 与 ``run_queue_service`` 的技术操作， 由外部 factory 注入并管理生命周期。 logger: 日志被驱动端口，用于记录兜底异常翻译路径上的故障 （INV-10 可观测性）。强制注入，禁止使用全局 logger。 service_account_port: 服务账号领域服务被驱动端口，用于按渠道 账户解析服务账号（执行身份）。渠道来源必须能解析出服务账号， 缺失时抛 ``InternalError``（INV-7 错误显式化，不回退）。 """ self._execution_port = execution_port self._logger = logger self._service_account_port = service_account_port async def createAgentRun(self, cmd: AgentRunCmd) -> AgentRunId: """创建 Agent 运行。 渠道来源下先通过 ``ServiceAccountPort`` 按 channel_type + channel_account_id 解析服务账号，以服务账号 uid 作为 ``current_uid`` （执行身份）注入下游，解决使用渠道发送者 ID 导致会话归属校验失败的 问题；并通过 ``pg_manager`` 获取真实 AsyncSession 注入 ``createAgentRunView``，支撑下游用户存在性校验。随后将渠道上下文、 渠道工具列表、执行身份与渠道用户身份注入 ``meta``。 非渠道来源（ctx 为 None 或无 channel_type）不解析服务账号， ``current_uid`` 回退到 ``channel_sender_id``，``db`` 仍注入真实 session 以保持下游一致。 Args: cmd: Agent 运行命令，携带会话 ID、消息内容与渠道上下文。 Returns: AgentRunId 标识已创建的运行。 Raises: ValidationError: 由 ``AgentRunCmd`` 构造时校验抛出 （``conversation_id`` 或 ``message_content`` 为空）。 InternalError: 渠道来源下服务账号缺失（INV-7 错误显式化，不回退）。 DependencyError: 依赖服务（DB / agent_run_service / service_account）故障。 """ ctx = cmd.context # 通过 ServiceAccountPort 解析服务账号（执行身份）。 # 渠道来源必须解析出服务账号，缺失则抛 InternalError（INV-7 错误显式化， # 不回退）；非渠道来源（ctx 为 None 或无 channel_type）跳过解析。 if ctx is not None and ctx.channel_type is not None and ctx.channel_account_id: try: service_account = await self._service_account_port.getServiceAccountByChannelAccount( ctx.channel_type, ctx.channel_account_id ) except (ValidationError, DependencyError, NotFoundError): raise except Exception as exc: # 契约错误已放行，其余异常包装为 DependencyError（ADP-002） await self._logger.error( "service_account_resolve_failed", resource="service_account", channel_type=ctx.channel_type, account_id=ctx.channel_account_id, error=str(exc), ) raise DependencyError("service_account", exc) from exc if service_account is None: raise InternalError(message="Service account not found for channel account") else: service_account = None meta: dict[str, Any] = {} current_uid = "" if ctx is not None: if ctx.channel_type is not None: meta["channel_type"] = ctx.channel_type meta["channel_account_id"] = ctx.channel_account_id meta["channel_peer_id"] = ctx.channel_peer_id meta["channel_group_id"] = ctx.channel_group_id meta["channel_topic_id"] = ctx.channel_topic_id meta["channel_sender_id"] = ctx.channel_sender_id if ctx.channel_format_spec is not None: meta["channel_format_description"] = ctx.channel_format_spec.format_description # BP-6: supported_formats 序列化为字符串列表，供下游格式渲染。 meta["channel_supported_formats"] = [f.value for f in ctx.channel_format_spec.supported_formats] else: # BP-6: format_spec 为 None 时写入空列表，便于下游统一处理。 meta["channel_supported_formats"] = [] if ctx.channel_context_note is not None: meta["system_prompt_appendix"] = ctx.channel_context_note.system_prompt_appendix meta["context_remark"] = ctx.channel_context_note.context_remark # FR-11: 渠道工具列表序列化到 meta，供下游 Agent 运行时合并。 # 非渠道来源或开关关闭时 channel_tools 为空 tuple，不写入 meta。 if ctx.channel_tools: meta["channel_tools"] = [_serialize_channel_tool(tool) for tool in ctx.channel_tools] # BP-1: 统一身份序列化到 meta，None 时写入 None 保持键存在， # 便于下游统一处理。identity_type 已为 str，直接使用。 meta["unified_identity"] = ( { "identity_id": ctx.unified_identity.identity_id, "user_id": ctx.unified_identity.user_id, "identity_type": ctx.unified_identity.identity_type, "identity_value": ctx.unified_identity.identity_value, "source": ctx.unified_identity.source, } if ctx.unified_identity is not None else None ) # BP-2: DM 安全决策取 .value，配对 ID 直接透传；None 时写入 None。 meta["dm_decision"] = ctx.dm_decision.value if ctx.dm_decision is not None else None meta["pairing_id"] = ctx.pairing_id # 执行身份：服务账号 uid（已解析），非渠道来源为空串。 meta["service_user_uid"] = service_account.uid if service_account else "" # BP-1: 渠道用户身份序列化到 meta，None 时写入 None 保持键存在， # 便于下游统一处理。 meta["channel_user_identity"] = ( { "identity_id": ctx.channel_user_identity.identity_id, "user_id": ctx.channel_user_identity.user_id, "identity_type": ctx.channel_user_identity.identity_type, "identity_value": ctx.channel_user_identity.identity_value, "source": ctx.channel_user_identity.source, } if ctx.channel_user_identity is not None else None ) # 会话来源标识：渠道来源为 True，供下游区分处理。 meta["is_channel_session"] = ctx.channel_type is not None # current_uid 使用服务账号 uid 作为执行身份（已解析）； # 非渠道来源回退到 channel_sender_id，None 时用空串占位以满足服务签名要求。 current_uid = service_account.uid if service_account else (ctx.channel_sender_id or "") if cmd.source: meta["source"] = cmd.source # BP-3: trace_id 透传到 meta，供下游链路追踪。 if cmd.trace_id: meta["trace_id"] = cmd.trace_id # FR-15: 非静默命令结果注入 Agent 上下文。command_result 为 None 时 # 不写入 meta，下游非渠道路径不受影响。 if cmd.command_result is not None: result = cmd.command_result meta["command_result"] = { "command": result.command, "is_silent": result.is_silent, "response": { "content": result.response.content, "content_type": result.response.content_type, } if result.response is not None else None, } # agent_id 由 AgentRunEnqueueStage 从 route_binding.agent_binding 提取并 # 写入 AgentRunContext，此处直接使用。route_binding 未命中时为空串， # 由下游 create_agent_run_view 校验并返回 404。 agent_id = ctx.agent_id if ctx is not None else "" # FR-47: 从 attachments 提取首张图片的 base64_content image_content = self._extractFirstImageBase64(cmd.message_content) # FR-47: 序列化全部附件元数据，供 Agent 感知用户发送的附件内容 # （非图片附件与多图场景）。首图 base64 仍通过 image_content 透传。 meta["attachments"] = self._extractAttachmentsMeta(cmd.message_content) try: # 通过 pg_manager 获取真实 AsyncSession 注入下游，支撑用户存在性校验 # 与会话归属查询（替代原 db=None）。session 在上下文退出时自动提交。 async with pg_manager.get_async_session_context() as session: result = await self._execution_port.createAgentRunView( query=cmd.message_content.text, agent_id=agent_id, thread_id=cmd.conversation_id, meta=meta, image_content=image_content, current_uid=current_uid, db=session, ) return AgentRunId(result["run_id"]) except (ValidationError, DependencyError): raise except Exception as exc: await self._logger.error( "agent_run_create_failed", resource="agent_run_service", error=str(exc), ) raise DependencyError("agent_run_service", exc) from exc @staticmethod def _extractFirstImageBase64(message_content: MessageContent) -> str | None: """从消息内容提取首张图片的 base64 内容。 FR-47: 遍历 attachments，取首个 type="image" 且 base64_content 非空的附件。 多图场景仅取首张（v1 限制，多图演进列入 v2）。 参数： message_content: 消息内容，含附件列表。 返回： 首张图片的 base64 内容；无图片时返回 None。 """ if not message_content.attachments: return None for attachment in message_content.attachments: if attachment.type == "image" and attachment.base64_content: return attachment.base64_content return None @staticmethod def _extractAttachmentsMeta(message_content: MessageContent) -> list[dict[str, Any]]: """提取消息中所有附件的元数据（不含二进制内容）。 FR-47: 序列化附件元数据（type / filename / mime_type / size / url）， 供 Agent 感知用户发送的附件内容。图片附件的 base64_content 不包含 在元数据中，首图仍通过 ``image_content`` 路径透传（v1 单图限制）。 非图片附件（视频/文件/音频）的元数据透传到 Agent，弥补 v1 仅支持 单图 base64 的限制。 参数： message_content: 消息内容，含附件列表。 返回： 附件元数据列表，每项含 type / filename / mime_type / size / url。 """ if not message_content.attachments: return [] attachments_meta: list[dict[str, Any]] = [] for attachment in message_content.attachments: attachments_meta.append( { "type": attachment.type, "filename": attachment.filename, "mime_type": attachment.mime_type, "size": attachment.size, "url": attachment.url, } ) return attachments_meta async def streamAgentRun(self, run_id: AgentRunId) -> AsyncIterator[StreamEvent]: """流式消费 Agent 运行事件。 委托 ``execution_port.streamAgentRunEvents`` 输出流式事件并转换为 ``StreamEvent`` DTO。``current_uid`` 通过 ``execution_port.getRunUid`` 从 run 记录查询获取（创建 run 时由 ``channel_sender_id`` 写入），确保 ``streamAgentRunEvents`` 内部的 权限校验通过。 Args: run_id: Agent 运行 ID。 Yields: ``StreamEvent`` 流式事件 DTO。 Raises: ValidationError: 契约校验失败。 DependencyError: 依赖服务（DB / Redis 流）故障。 NotFoundError: run 记录不存在。 """ try: # 通过 execution_port 查询 run 记录的 uid（创建时由 # channel_sender_id 写入），确保 streamAgentRunEvents 内部 # get_run_for_user 权限校验通过。current_uid="" 会导致查不到 # 记录而报错。 current_uid = await self._execution_port.getRunUid(run_id.value, None) async for event in self._execution_port.streamAgentRunEvents( run_id=run_id.value, after_seq="", current_uid=current_uid, verbose=True, ): yield StreamEvent( event_type=event.get("event_type", ""), payload=event.get("payload") or {}, seq=event.get("seq", ""), ) except (ValidationError, DependencyError, NotFoundError): raise except Exception as exc: await self._logger.error( "agent_run_stream_failed", resource="redis_stream", run_id=run_id.value, error=str(exc), ) raise DependencyError("redis_stream", Error(str(exc))) from exc async def getAgentRunFinalOutput(self, run_id: AgentRunId) -> Option[str]: """获取 Agent 运行的最终输出文本。 委托 ``execution_port.listRunStreamEvents`` 分页读取 Redis Stream 中的全部事件，过滤 ``messages`` 事件并拼接其 ``items`` 中各 chunk 的可见内容（``stream_event.content`` 优先，回退 ``response``）， 返回完整输出文本。用于截断补全：当流式投递因 TTL 超时或异常中断 导致 ``stream_chunks`` 不完整时，通过重放事件流获取更完整的文本 作为截断补全候选。 与 ``streamAgentRun`` 的区别：``streamAgentRun`` 是实时流式消费 （逐块 yield ``StreamEvent``），本方法一次性读取全部事件并拼接为 纯文本，用于事后补全而非实时投递。 Args: run_id: Agent 运行 ID。 Returns: ``Some(完整输出文本)``；事件流为空或已 trim 时返回 ``Nothing``。 Raises: ValidationError: 契约校验失败。 DependencyError: 依赖服务（Redis 流）故障。 NotFoundError: run 记录不存在。 """ parts: list[str] = [] after_seq = "0-0" try: while True: events = await self._execution_port.listRunStreamEvents( run_id=run_id.value, after_seq=after_seq, limit=_EVENTS_PAGE_LIMIT, ) if not events: break for event in events: if event.get("event_type") != "messages": continue envelope = event.get("payload") or {} inner_payload = envelope.get("payload") or {} items = inner_payload.get("items") or [] for chunk in items: if not isinstance(chunk, dict): continue # 优先使用 stream_event.content（语义增量）， # 回退到 response（直接文本），避免重复拼接 stream_event = chunk.get("stream_event") if isinstance(stream_event, dict): content = stream_event.get("content") if isinstance(content, str) and content: parts.append(content) continue response = chunk.get("response") if isinstance(response, str) and response: parts.append(response) after_seq = events[-1].get("seq", after_seq) if len(events) < _EVENTS_PAGE_LIMIT: break except (ValidationError, DependencyError, NotFoundError): raise except Exception as exc: await self._logger.error( "agent_run_final_output_failed", resource="redis_stream", run_id=run_id.value, error=str(exc), ) raise DependencyError("redis_stream", Error(str(exc))) from exc text = "".join(parts) if text: return Some(text) return Nothing()