Kris
b88c0ae29e
新增完整的 channels 限界上下文模块，包含契约层、领域核心层、应用服务、管道编排、插件体系、基础设施组合根等全层级代码，新增飞书与微信 iLink 渠道插件基础结构，补充各类 DTO、端口协议与领域服务实现。
160 lines
6.2 KiB
Python
160 lines
6.2 KiB
Python
"""插件元数据。
|
||
|
||
定义插件清单相关的枚举、不可变值对象，包括失败策略、插件依赖、资源配额、
|
||
配置字段、渠道清单与插件清单。所有 DTO 均为 ``dataclass(frozen=True)``，
|
||
集合字段使用 tuple，仅依赖标准库与契约层内部类型，用于插件注册、依赖解析、
|
||
资源配额声明与能力边界声明。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from datetime import datetime
|
||
from enum import StrEnum
|
||
from typing import Any
|
||
|
||
from yuxi.channels.contract.dtos.capability import ChannelCapabilities
|
||
from yuxi.channels.contract.dtos.channel import ChannelType
|
||
from yuxi.channels.contract.dtos.config import ConfigField
|
||
from yuxi.channels.contract.dtos.plugin import EnvVar
|
||
|
||
|
||
class FailurePolicy(StrEnum):
|
||
"""失败策略。
|
||
|
||
标识插件失败时的处理策略，用于宿主决定降级、熔断或隔离。继承
|
||
``str, Enum`` 以支持 JSON 序列化与字符串比较。
|
||
|
||
取值：
|
||
DEGRADE: 降级（走降级路径，保留部分能力）。
|
||
CIRCUIT_BREAK: 熔断（打开熔断器，暂时停止调用）。
|
||
ISOLATE: 隔离（隔离插件，阻止其继续运行）。
|
||
"""
|
||
|
||
DEGRADE = "degrade"
|
||
CIRCUIT_BREAK = "circuit_break"
|
||
ISOLATE = "isolate"
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class PluginDependency:
|
||
"""插件依赖。
|
||
|
||
描述插件对其他插件的依赖关系，包括插件 ID 与版本范围，用于插件加载
|
||
前的依赖解析。
|
||
|
||
字段：
|
||
plugin_id: 依赖的插件 ID。
|
||
version_range: 语义化版本范围表达式（SemVer range）。
|
||
"""
|
||
|
||
plugin_id: str
|
||
version_range: str
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ResourceQuota:
|
||
"""资源配额。
|
||
|
||
描述插件的资源配额限制，包括 CPU、内存、连接数与每秒调用数，用于
|
||
宿主对插件施加资源边界（FR-32 / §8.5）。
|
||
|
||
字段：
|
||
max_cpu: CPU 上限（如 "500m"），可选。
|
||
max_memory: 内存上限（如 "512Mi"），可选。
|
||
max_connections: 最大连接数，可选。
|
||
max_calls_per_sec: 每秒最大调用数，可选。
|
||
"""
|
||
|
||
max_cpu: str | None = None
|
||
max_memory: str | None = None
|
||
max_connections: int | None = None
|
||
max_calls_per_sec: int | None = None
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ChannelManifest:
|
||
"""渠道清单。
|
||
|
||
描述渠道插件的元数据，包括标识、版本、渠道类型、提供的能力、配置 schema、
|
||
入口模块、依赖、生命周期、兼容性、失败策略、资源配额与能力边界声明，
|
||
用于插件注册与装配。
|
||
|
||
字段：
|
||
id: 全局唯一标识（如 com.yuxi.channels.feishu）。
|
||
name: 人类可读名称。
|
||
version: 语义化版本。
|
||
channel_type: 渠道类型。
|
||
provides: 提供的能力列表。
|
||
entry_module: 插件入口模块路径。
|
||
capabilities: 渠道能力集合（静态声明，必填）。
|
||
config_schema: 配置项 schema（必填）。
|
||
depends: 依赖的其他插件（默认空）。
|
||
lifecycle: 支持的生命周期钩子（默认 init/start/stop/unload）。
|
||
compatibility: 兼容性信息（可选）。
|
||
failure_policy: 失败策略（默认 DEGRADE）。
|
||
resource_quota: 资源配额（可选）。
|
||
accessible_ports: 可访问的端口列表（默认空）。
|
||
injectable_pipelines: 可注入的管道列表（默认空）。
|
||
skills: 提供的技能列表（默认空）。
|
||
env_vars: 环境变量声明（默认空）。
|
||
critical: 是否为关键渠道（默认 False）。关键渠道失败时宿主标记为
|
||
``unhealthy``，非关键渠道失败标记为 ``degraded``（FR-31 / FR-35）。
|
||
requires_dm_pairing: 是否要求 DM 安全配对审批（默认 True）。声明
|
||
``False`` 的渠道（如已通过宿主认证体系）跳过 DM 配对审批直接放行
|
||
（FR-31）。插件未注册时框架回退为 ``True``（fail-closed）。
|
||
requires_outbound_delivery: 是否要求出站投递（默认 True）。声明 ``False``
|
||
的渠道无需实现 ``OutboundAdapter``，框架跳过出站投递阶段（FR-31）。
|
||
"""
|
||
|
||
id: str
|
||
name: str
|
||
version: str
|
||
channel_type: ChannelType
|
||
provides: tuple[str, ...]
|
||
entry_module: str
|
||
capabilities: ChannelCapabilities
|
||
config_schema: tuple[ConfigField, ...]
|
||
depends: tuple[PluginDependency, ...] = ()
|
||
lifecycle: tuple[str, ...] = ("init", "start", "stop", "unload")
|
||
compatibility: dict[str, Any] | None = None
|
||
failure_policy: FailurePolicy = FailurePolicy.DEGRADE
|
||
resource_quota: ResourceQuota | None = None
|
||
accessible_ports: tuple[str, ...] = ()
|
||
injectable_pipelines: tuple[str, ...] = ()
|
||
skills: tuple[str, ...] = ()
|
||
env_vars: tuple[EnvVar, ...] = ()
|
||
critical: bool = False
|
||
requires_dm_pairing: bool = True
|
||
requires_outbound_delivery: bool = True
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class PluginManifest:
|
||
"""插件清单。
|
||
|
||
描述插件注册到宿主的完整清单，包括渠道清单与插件提供的扩展点（适配器、
|
||
阶段、事件订阅、配置源），由 ``CHANNEL_ENTRY`` 返回给宿主。
|
||
|
||
字段：
|
||
manifest: 渠道清单。
|
||
adapters: 提供的适配器类型列表（默认空）。
|
||
stages: 提供的管道阶段列表（默认空）。
|
||
event_subscriptions: 订阅的事件类型列表（默认空）。
|
||
config_sources: 配置源列表（默认空）。
|
||
installed_at: 文件级安装时间（PLG-INSTALL 端点写入，默认 None
|
||
表示未通过文件级安装流程注册）。
|
||
install_source: 安装来源标识（如文件路径、URL、包名，默认 None）。
|
||
install_version: 安装时的版本号（可能与 manifest.version 不同，
|
||
如安装后未升级，默认 None）。
|
||
"""
|
||
|
||
manifest: ChannelManifest
|
||
adapters: tuple[str, ...] = ()
|
||
stages: tuple[str, ...] = ()
|
||
event_subscriptions: tuple[str, ...] = ()
|
||
config_sources: tuple[str, ...] = ()
|
||
installed_at: datetime | None = None
|
||
install_source: str | None = None
|
||
install_version: str | None = None
|