from __future__ import annotations import warnings from dataclasses import MISSING, dataclass, field, fields from typing import ClassVar from yuxi.channel.config.defaults import ( BLOCK_STREAMING_BREAK, BLOCK_STREAMING_CHUNK_BREAK_PREFERENCE, BLOCK_STREAMING_CHUNK_MAX_CHARS, BLOCK_STREAMING_CHUNK_MIN_CHARS, BLOCK_STREAMING_COALESCE_IDLE_MS, BLOCK_STREAMING_COALESCE_MAX_CHARS, BLOCK_STREAMING_COALESCE_MIN_CHARS, SSE_MAX_REASONING_CHARS, STREAMING_PREVIEW_MIN_INITIAL_CHARS, STREAMING_PREVIEW_THROTTLE_MS, ) # 哨兵对象，用于标记字段尚未被显式设置 _UNSET = object() # 支持的流式传输模式 STREAMING_MODES: tuple[str, ...] = ("card_kit", "block", "c2c_stream_api", "raw") # 块级流式传输的分割断点类型 BLOCK_STREAMING_BREAKS: tuple[str, ...] = ("text_end", "paragraph", "sentence", "token") @dataclass class ChannelCapabilities: """定义通道（Channel）支持的各种能力配置。""" # 聊天类型，默认支持私聊和群聊 chat_types: list[str] = field(default_factory=lambda: ["direct", "group"]) # 消息类型，默认仅支持文本 message_types: list[str] = field(default_factory=lambda: ["text"]) # 交互方式列表 interactions: list[str] = field(default_factory=list) # 以下为各类功能开关，默认使用 _UNSET 表示未显式设置 reactions: bool = field(default=_UNSET) # 是否支持消息表情反应 typing_indicator: bool = field(default=_UNSET) # 是否支持输入状态指示 threads: bool = field(default=_UNSET) # 是否支持话题线程 edit: bool = field(default=_UNSET) # 是否支持编辑消息 unsend: bool = field(default=_UNSET) # 是否支持撤回消息 reply: bool = field(default=_UNSET) # 是否支持回复消息 media: bool = field(default=_UNSET) # 是否支持发送媒体 effects: bool = field(default=_UNSET) # 是否支持消息特效 native_commands: bool = field(default=_UNSET) # 是否支持原生命令 polls: bool = field(default=_UNSET) # 是否支持投票 pins: bool = field(default=_UNSET) # 是否支持置顶消息 group_management: bool = field(default=_UNSET) # 是否支持群组管理 adaptive_cards: bool = field(default=_UNSET) # 是否支持自适应卡片 tasks: bool = field(default=_UNSET) # 是否支持任务 events: bool = field(default=_UNSET) # 是否支持事件 notes: bool = field(default=_UNSET) # 是否支持笔记 task_modules: bool = field(default=_UNSET) # 是否支持任务模块 messaging_extensions: bool = field(default=_UNSET) # 是否支持消息扩展 incoming_webhooks: bool = field(default=_UNSET) # 是否支持传入的 Webhook bot_state: bool = field(default=_UNSET) # 是否支持机器人状态 # 流式传输相关配置 streaming: bool = field(default=_UNSET) # 是否启用流式传输 streaming_mode: str | None = None # 流式传输模式 preview_stream_throttle_ms: int = field(default=_UNSET) # 预览流节流间隔（毫秒） preview_min_initial_chars: int = field(default=_UNSET) # 预览最小初始字符数 # 块级流式传输配置 block_streaming: bool = field(default=_UNSET) # 是否启用块级流式传输 block_streaming_break: str = field(default=_UNSET) # 块级流式分割断点 block_streaming_chunk_min_chars: int = field(default=_UNSET) # 块最小字符数 block_streaming_chunk_max_chars: int = field(default=_UNSET) # 块最大字符数 block_streaming_chunk_break_preference: str = field(default=_UNSET) # 块分割偏好 block_streaming_coalesce_min_chars: int | None = None # 合并块最小字符数 block_streaming_coalesce_max_chars: int | None = None # 合并块最大字符数 block_streaming_coalesce_idle_ms: int = field(default=_UNSET) # 合并空闲等待时间（毫秒） # SSE 与轮询配置 sse_support: bool = field(default=_UNSET) # 是否支持 SSE sse_max_reasoning_chars: int = field(default=_UNSET) # SSE 最大推理字符数 polling_fallback: bool = field(default=_UNSET) # 是否启用轮询降级 # TTS（文本转语音）配置 tts: dict | None = None # 类变量：已警告的冻结字段集合 _WARNED_FROZEN_FIELDS: ClassVar[frozenset[str]] = frozenset() def __post_init__(self) -> None: """初始化后处理：记录原始值并对未设置的字段应用默认值。""" self._raw_values = dict(self.__dict__) # 布尔功能开关默认值均为 False if self.reactions is _UNSET: self.reactions = False if self.typing_indicator is _UNSET: self.typing_indicator = False if self.threads is _UNSET: self.threads = False if self.edit is _UNSET: self.edit = False if self.unsend is _UNSET: self.unsend = False if self.reply is _UNSET: self.reply = False if self.media is _UNSET: self.media = False if self.effects is _UNSET: self.effects = False if self.native_commands is _UNSET: self.native_commands = False if self.polls is _UNSET: self.polls = False if self.pins is _UNSET: self.pins = False if self.group_management is _UNSET: self.group_management = False if self.adaptive_cards is _UNSET: self.adaptive_cards = False if self.tasks is _UNSET: self.tasks = False if self.events is _UNSET: self.events = False if self.notes is _UNSET: self.notes = False if self.task_modules is _UNSET: self.task_modules = False if self.messaging_extensions is _UNSET: self.messaging_extensions = False if self.incoming_webhooks is _UNSET: self.incoming_webhooks = False if self.bot_state is _UNSET: self.bot_state = False if self.streaming is _UNSET: self.streaming = False if self.block_streaming is _UNSET: self.block_streaming = False if self.sse_support is _UNSET: self.sse_support = False if self.polling_fallback is _UNSET: self.polling_fallback = False # 数值类型字段默认值（来源：config/defaults.py） if self.preview_stream_throttle_ms is _UNSET: self.preview_stream_throttle_ms = STREAMING_PREVIEW_THROTTLE_MS if self.preview_min_initial_chars is _UNSET: self.preview_min_initial_chars = STREAMING_PREVIEW_MIN_INITIAL_CHARS if self.block_streaming_break is _UNSET: self.block_streaming_break = BLOCK_STREAMING_BREAK if self.block_streaming_chunk_min_chars is _UNSET: self.block_streaming_chunk_min_chars = BLOCK_STREAMING_CHUNK_MIN_CHARS if self.block_streaming_chunk_max_chars is _UNSET: self.block_streaming_chunk_max_chars = BLOCK_STREAMING_CHUNK_MAX_CHARS if self.block_streaming_chunk_break_preference is _UNSET: self.block_streaming_chunk_break_preference = BLOCK_STREAMING_CHUNK_BREAK_PREFERENCE if self.block_streaming_coalesce_idle_ms is _UNSET: self.block_streaming_coalesce_idle_ms = BLOCK_STREAMING_COALESCE_IDLE_MS if self.sse_max_reasoning_chars is _UNSET: self.sse_max_reasoning_chars = SSE_MAX_REASONING_CHARS # 校验流式传输模式是否合法 if self.streaming_mode is not None and self.streaming_mode not in STREAMING_MODES: warnings.warn( f"Unknown streaming_mode: {self.streaming_mode!r}. Known modes: {STREAMING_MODES}", stacklevel=3, ) # 校验块级流式分割断点是否合法 if self.block_streaming_break not in BLOCK_STREAMING_BREAKS: warnings.warn( f"Unknown block_streaming_break: {self.block_streaming_break!r}. " f"Known breaks: {BLOCK_STREAMING_BREAKS}", stacklevel=3, ) # 校验块字符数范围合理性 if self.block_streaming_chunk_min_chars > self.block_streaming_chunk_max_chars: raise ValueError( f"block_streaming_chunk_min_chars ({self.block_streaming_chunk_min_chars}) " f"must be <= block_streaming_chunk_max_chars ({self.block_streaming_chunk_max_chars})" ) # 块级流式传输仅在流式传输开启时生效 if self.block_streaming and not self.streaming: warnings.warn( "block_streaming=True but streaming=False, block_streaming has no effect", stacklevel=3, ) # 校验合并块字符数范围合理性 if self.block_streaming_coalesce_min_chars is not None and self.block_streaming_coalesce_max_chars is not None: if self.block_streaming_coalesce_min_chars > self.block_streaming_coalesce_max_chars: raise ValueError( f"block_streaming_coalesce_min_chars ({self.block_streaming_coalesce_min_chars}) " f"must be <= block_streaming_coalesce_max_chars ({self.block_streaming_coalesce_max_chars})" ) def to_dict(self) -> dict: """将能力配置转换为字典格式。""" return { "chat_types": list(self.chat_types), "message_types": list(self.message_types), "interactions": list(self.interactions), "reactions": self.reactions, "typing_indicator": self.typing_indicator, "threads": self.threads, "edit": self.edit, "unsend": self.unsend, "reply": self.reply, "media": self.media, "effects": self.effects, "native_commands": self.native_commands, "polls": self.polls, "pins": self.pins, "group_management": self.group_management, "adaptive_cards": self.adaptive_cards, "tasks": self.tasks, "events": self.events, "notes": self.notes, "task_modules": self.task_modules, "messaging_extensions": self.messaging_extensions, "incoming_webhooks": self.incoming_webhooks, "bot_state": self.bot_state, "streaming": self.streaming, "streaming_mode": self.streaming_mode, "preview_stream_throttle_ms": self.preview_stream_throttle_ms, "preview_min_initial_chars": self.preview_min_initial_chars, "block_streaming": self.block_streaming, "block_streaming_break": self.block_streaming_break, "block_streaming_chunk_min_chars": self.block_streaming_chunk_min_chars, "block_streaming_chunk_max_chars": self.block_streaming_chunk_max_chars, "block_streaming_chunk_break_preference": self.block_streaming_chunk_break_preference, "block_streaming_coalesce_min_chars": self.block_streaming_coalesce_min_chars, "block_streaming_coalesce_max_chars": self.block_streaming_coalesce_max_chars, "block_streaming_coalesce_idle_ms": self.block_streaming_coalesce_idle_ms, "sse_support": self.sse_support, "sse_max_reasoning_chars": self.sse_max_reasoning_chars, "polling_fallback": self.polling_fallback, "tts": dict(self.tts) if self.tts is not None else None, } def override_with(self, overrides: ChannelCapabilities | dict) -> ChannelCapabilities: """使用另一组能力配置覆盖当前配置，返回新的 ChannelCapabilities 实例。""" if isinstance(overrides, dict): override_dict: dict | None = overrides overrides = ChannelCapabilities(**overrides) else: override_dict = None if not isinstance(overrides, ChannelCapabilities): raise TypeError(f"Expected ChannelCapabilities or dict, got {type(overrides).__name__}") def _merge_list(base: list[str], override: list[str]) -> list[str]: """合并两个列表并去重，保持原有顺序。""" return list(dict.fromkeys(base + override)) def _should_override(name: str) -> bool: """判断指定字段是否需要被覆盖。""" if override_dict is not None: return name in override_dict raw = getattr(overrides, "_raw_values", None) if raw is None: return True raw_value = raw.get(name) if raw_value is _UNSET: return False field_default = _FIELD_DEFAULTS.get(name) if field_default is not _UNSET: return raw_value != field_default return True return ChannelCapabilities( chat_types=_merge_list(self.chat_types, overrides.chat_types), message_types=_merge_list(self.message_types, overrides.message_types), interactions=_merge_list(self.interactions, overrides.interactions), reactions=overrides.reactions if _should_override("reactions") else self.reactions, typing_indicator=overrides.typing_indicator if _should_override("typing_indicator") else self.typing_indicator, threads=overrides.threads if _should_override("threads") else self.threads, edit=overrides.edit if _should_override("edit") else self.edit, unsend=overrides.unsend if _should_override("unsend") else self.unsend, reply=overrides.reply if _should_override("reply") else self.reply, media=overrides.media if _should_override("media") else self.media, effects=overrides.effects if _should_override("effects") else self.effects, native_commands=overrides.native_commands if _should_override("native_commands") else self.native_commands, polls=overrides.polls if _should_override("polls") else self.polls, pins=overrides.pins if _should_override("pins") else self.pins, group_management=overrides.group_management if _should_override("group_management") else self.group_management, adaptive_cards=overrides.adaptive_cards if _should_override("adaptive_cards") else self.adaptive_cards, tasks=overrides.tasks if _should_override("tasks") else self.tasks, events=overrides.events if _should_override("events") else self.events, notes=overrides.notes if _should_override("notes") else self.notes, task_modules=overrides.task_modules if _should_override("task_modules") else self.task_modules, messaging_extensions=overrides.messaging_extensions if _should_override("messaging_extensions") else self.messaging_extensions, incoming_webhooks=overrides.incoming_webhooks if _should_override("incoming_webhooks") else self.incoming_webhooks, bot_state=overrides.bot_state if _should_override("bot_state") else self.bot_state, streaming=overrides.streaming if _should_override("streaming") else self.streaming, streaming_mode=overrides.streaming_mode if _should_override("streaming_mode") else self.streaming_mode, preview_stream_throttle_ms=overrides.preview_stream_throttle_ms if _should_override("preview_stream_throttle_ms") else self.preview_stream_throttle_ms, preview_min_initial_chars=overrides.preview_min_initial_chars if _should_override("preview_min_initial_chars") else self.preview_min_initial_chars, block_streaming=overrides.block_streaming if _should_override("block_streaming") else self.block_streaming, block_streaming_break=overrides.block_streaming_break if _should_override("block_streaming_break") else self.block_streaming_break, block_streaming_chunk_min_chars=overrides.block_streaming_chunk_min_chars if _should_override("block_streaming_chunk_min_chars") else self.block_streaming_chunk_min_chars, block_streaming_chunk_max_chars=overrides.block_streaming_chunk_max_chars if _should_override("block_streaming_chunk_max_chars") else self.block_streaming_chunk_max_chars, block_streaming_chunk_break_preference=overrides.block_streaming_chunk_break_preference if _should_override("block_streaming_chunk_break_preference") else self.block_streaming_chunk_break_preference, block_streaming_coalesce_min_chars=overrides.block_streaming_coalesce_min_chars if _should_override("block_streaming_coalesce_min_chars") else self.block_streaming_coalesce_min_chars, block_streaming_coalesce_max_chars=overrides.block_streaming_coalesce_max_chars if _should_override("block_streaming_coalesce_max_chars") else self.block_streaming_coalesce_max_chars, block_streaming_coalesce_idle_ms=overrides.block_streaming_coalesce_idle_ms if _should_override("block_streaming_coalesce_idle_ms") else self.block_streaming_coalesce_idle_ms, sse_support=overrides.sse_support if _should_override("sse_support") else self.sse_support, sse_max_reasoning_chars=overrides.sse_max_reasoning_chars if _should_override("sse_max_reasoning_chars") else self.sse_max_reasoning_chars, polling_fallback=overrides.polling_fallback if _should_override("polling_fallback") else self.polling_fallback, tts=overrides.tts if _should_override("tts") else self.tts, ) def supports(self, feature: str) -> bool: """检查是否支持指定功能。""" return bool(getattr(self, feature, False)) def get_action_registry(self, plugin: object) -> MessageActionRegistry: """根据当前能力配置生成消息动作注册表。""" from yuxi.channel.sdk.actions import MessageAction, MessageActionRegistry registry = MessageActionRegistry() base_actions = {MessageAction.SEND, MessageAction.SEND_MEDIA} if self.reply: base_actions.add(MessageAction.REPLY) if self.edit: base_actions.add(MessageAction.EDIT) if self.unsend: base_actions.add(MessageAction.UNSEND) if self.reactions: base_actions.add(MessageAction.REACT) base_actions.add(MessageAction.REACT_REMOVE) base_actions.add(MessageAction.REACTIONS) if self.pins: base_actions.add(MessageAction.PIN) base_actions.add(MessageAction.UNPIN) if self.polls: base_actions.add(MessageAction.POLL) base_actions.add(MessageAction.POLL_VOTE) if self.group_management: base_actions |= { MessageAction.RENAME_GROUP, MessageAction.ADD_PARTICIPANT, MessageAction.REMOVE_PARTICIPANT, MessageAction.MEMBER_INFO, MessageAction.PERMISSIONS, } if self.threads: base_actions |= { MessageAction.THREAD_CREATE, MessageAction.THREAD_LIST, MessageAction.THREAD_REPLY, MessageAction.TOPIC_CREATE, MessageAction.TOPIC_EDIT, } for action in base_actions: registry.register(action, lambda **kwargs: {"success": True}) return registry def derive_from_adapter(self, adapter) -> ChannelCapabilities: """从适配器推导能力配置。""" actions = {a.value for a in adapter.list_actions()} return ChannelCapabilities( chat_types=self.chat_types, message_types=self.message_types, reactions="react" in actions or "react_remove" in actions, edit="edit" in actions, unsend="unsend" in actions, polls="poll" in actions or "poll_vote" in actions, pins="pin" in actions or "unpin" in actions, group_management=( "add_participant" in actions or "remove_participant" in actions or "rename_group" in actions ), threads="thread_reply" in actions or "thread_create" in actions or "thread_list" in actions, media="send_media" in actions, reply="reply" in actions, ) def get_effective_streaming_mode(self) -> str: """获取实际生效的流式传输模式。""" if not self.streaming: return "none" if self.streaming_mode: return self.streaming_mode return "preview" def get_chunk_limit(self) -> int: """获取分块大小限制。""" return 4096 def get_effective_block_config(self) -> dict: """获取实际生效的块级流式传输配置。""" text_limit = self.get_chunk_limit() chunk_min = max(1, self.block_streaming_chunk_min_chars) chunk_max = max(chunk_min, min(self.block_streaming_chunk_max_chars, text_limit)) coalesce_min = self.block_streaming_coalesce_min_chars or chunk_min coalesce_max = self.block_streaming_coalesce_max_chars or chunk_max coalesce_min = min(coalesce_min, coalesce_max) coalesce_max = min(coalesce_max, chunk_max) coalesce_idle_ms = max(0, min(self.block_streaming_coalesce_idle_ms, 5000)) return { "chunk": { "min_chars": chunk_min, "max_chars": chunk_max, "break_preference": self.block_streaming_chunk_break_preference, }, "coalesce": { "min_chars": coalesce_min, "max_chars": coalesce_max, "idle_ms": coalesce_idle_ms, }, "text_limit": text_limit, } # 构建字段默认值映射表，用于 override_with 中的覆盖判断 _FIELD_DEFAULTS: dict[str, object] = {} for _f in fields(ChannelCapabilities): if _f.default is not MISSING: _FIELD_DEFAULTS[_f.name] = _f.default elif _f.default_factory is not MISSING: _FIELD_DEFAULTS[_f.name] = _f.default_factory()