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
|