Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
137 lines
5.8 KiB
Python
137 lines
5.8 KiB
Python
"""能力 DTO。
|
||
|
||
定义渠道能力相关的不可变值对象，包括渠道能力集合与能力探测结果。
|
||
所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库，用于渠道
|
||
能力声明、探测与降级决策。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ChannelCapabilities:
|
||
"""渠道能力集合。
|
||
|
||
描述渠道支持的能力集合，全部为 ``bool`` 类型的能力声明字段，用于
|
||
适配器能力声明与降级决策。
|
||
|
||
字段（按语义分组）：
|
||
基础消息能力：
|
||
rich_message: 是否支持富消息（默认 False）。
|
||
streaming: 是否支持流式输出（默认 False）。
|
||
typing_indicator: 是否支持输入指示（默认 False）。由出站
|
||
适配器承载，不在加载期校验范围，运行时由
|
||
``CapabilityVerifier`` 证明。
|
||
message_edit: 是否支持消息编辑（默认 False）。
|
||
message_recall: 是否支持消息撤回（默认 False）。
|
||
|
||
消息操作子能力（任一为 True 时要求 ``message_ops_adapters`` 非空）：
|
||
supports_reaction: 是否支持表情反应（默认 False，FR-12）。
|
||
supports_pin: 是否支持置顶（默认 False，FR-12）。
|
||
supports_card_update: 是否支持投递完成后的卡片刷新
|
||
（``MessageOpsAdapter.updateCard``，默认 False，FR-12）。
|
||
**不** 涵盖流式输出过程中的渐进式卡片更新，后者由
|
||
``supports_card_update_streaming`` 声明。
|
||
supports_card_update_streaming: 是否支持流式输出过程中的
|
||
渐进式卡片更新（``StreamingAdapter.updateFullCard`` /
|
||
``updatePartialCard``，默认 False）。声明为 True 时要求
|
||
``streaming_adapters`` 非空。
|
||
|
||
媒体能力（FR-43）：
|
||
supports_image_inbound: 是否支持入站图片（默认 False）。
|
||
supports_video_inbound: 是否支持入站视频（默认 False）。
|
||
supports_image_outbound: 是否支持出站图片（默认 False）。
|
||
supports_video_outbound: 是否支持出站视频（默认 False）。
|
||
|
||
扩展能力：
|
||
mention: 是否支持提及（默认 False）。
|
||
command: 是否支持命令（默认 False，FR-15）。
|
||
directory: 是否支持目录查询（默认 False，FR-14）。
|
||
doctor: 是否支持配置诊断与自动修复（默认 False，FR-17）。
|
||
whitelist: 是否支持白名单管理（默认 False，FR-18）。
|
||
wizard: 是否支持配置向导（默认 False，FR-16）。声明为 True
|
||
时要求 ``wizard_adapters`` 非空。
|
||
tools: 是否支持工具能力（默认 False，FR-12 工具暴露）。
|
||
声明为 True 时要求 ``tools_adapters`` 非空。
|
||
status: 是否支持状态分类（默认 False）。声明为 True 时要求
|
||
``status_adapters`` 非空；未声明的渠道默认将所有事件
|
||
分类为 MESSAGE。
|
||
probeable: 是否支持连接探测（默认 False，FR-17 探测）。
|
||
声明为 True 时要求 ``probeable_adapters`` 非空。
|
||
identity_resolver: 是否支持身份解析适配器（默认 False）。
|
||
由 ``IdentityResolverPort`` 承载，不在加载期校验范围，
|
||
运行时由 ``CapabilityVerifier`` 证明。
|
||
|
||
生命周期与协作能力：
|
||
lifecycle: 是否实现账户生命周期适配器（默认 False，AL-01）。
|
||
supports_qr_login: 是否支持扫码登录（默认 False，QR-02）。
|
||
agent_collaboration: 是否支持多 Agent 协作（默认 False，
|
||
FR-AgentCollab）。声明为 True 时要求 ``mention_adapters``
|
||
非空（FR-21 契约一致性）。
|
||
"""
|
||
|
||
# 基础消息能力
|
||
rich_message: bool = False
|
||
streaming: bool = False
|
||
typing_indicator: bool = False
|
||
message_edit: bool = False
|
||
message_recall: bool = False
|
||
# 消息操作子能力
|
||
supports_reaction: bool = False
|
||
supports_pin: bool = False
|
||
supports_card_update: bool = False
|
||
supports_card_update_streaming: bool = False
|
||
# 媒体能力（FR-43）
|
||
supports_image_inbound: bool = False
|
||
supports_video_inbound: bool = False
|
||
supports_image_outbound: bool = False
|
||
supports_video_outbound: bool = False
|
||
# 扩展能力
|
||
mention: bool = False
|
||
command: bool = False
|
||
directory: bool = False
|
||
doctor: bool = False
|
||
whitelist: bool = False
|
||
wizard: bool = False
|
||
tools: bool = False
|
||
status: bool = False
|
||
probeable: bool = False
|
||
identity_resolver: bool = False
|
||
# 生命周期与协作能力
|
||
lifecycle: bool = False
|
||
supports_qr_login: bool = False
|
||
agent_collaboration: bool = False
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class CapabilityResult:
|
||
"""能力探测结果。
|
||
|
||
描述单项能力的探测结果，包括声明层、证明层与降级标记，用于能力
|
||
探测流程的决策与审计。
|
||
|
||
字段：
|
||
capability: 能力名称。
|
||
declared: 声明层是否支持。
|
||
proven: 证明层是否验证通过（默认 False）。
|
||
degraded: 是否降级（默认 False）。
|
||
"""
|
||
|
||
capability: str
|
||
declared: bool
|
||
proven: bool = False
|
||
degraded: bool = False
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验 capability 非空。
|
||
|
||
``capability`` 必须非空，在构造时即抛出 ``ValidationError``，
|
||
避免空能力名称传播到探测决策（INV-8）。
|
||
"""
|
||
if not self.capability:
|
||
raise ValidationError("capability", "must not be empty")
|