ForcePilot/backend/package/yuxi/channel/protocols.py

from __future__ import annotations

import time
from dataclasses import dataclass, field
from enum import StrEnum
from typing import TYPE_CHECKING, Any, Final, Protocol, runtime_checkable

from yuxi.channel.context import ChannelContext

if TYPE_CHECKING:
    from yuxi.channel.capabilities import ChannelCapabilities
    from yuxi.channel.doctor.models import (
        ConnectivityCheckResult,
        CredentialCheckResult,
        DiagnosisResult,
        DiagnosisWarning,
        LegacyConfigRule,
        PermissionCheckResult,
        RepairResult,
        RepairStep,
    )


_SUPPORTED_SCHEMA_TYPES: Final[frozenset[str]] = frozenset(
    {"string", "number", "integer", "boolean", "object", "array", "null"}
)

# ── Base ─────────────────────────────────────────────────


@runtime_checkable
class MetaProtocol(Protocol):
    id: str
    name: str
    order: int


@runtime_checkable
class CapabilitiesProtocol(Protocol):
    capabilities: ChannelCapabilities


# ── Config ───────────────────────────────────────────────


@runtime_checkable
class ConfigProtocol(Protocol):
    def list_account_ids(self, config: dict) -> list[str]: ...
    async def resolve_account(self, account_id: str) -> dict: ...
    def is_configured(self, account: dict) -> bool: ...

    def inspect_account(self, config: dict, account_id: str | None = None) -> dict: ...
    def default_account_id(self, config: dict) -> str: ...
    def set_account_enabled(self, config: dict, account_id: str, enabled: bool) -> dict: ...
    def delete_account(self, config: dict, account_id: str) -> dict: ...
    def is_enabled(self, account: dict, config: dict) -> bool: ...
    def disabled_reason(self, account: dict, config: dict) -> str: ...
    def unconfigured_reason(self, account: dict, config: dict) -> str: ...
    def describe_account(self, account: dict, config: dict) -> dict: ...
    def resolve_allow_from(self, config: dict, account_id: str | None = None) -> list[str | int] | None: ...
    def format_allow_from(self, config: dict, account_id: str | None, allow_from: list[str | int]) -> list[str]: ...
    def has_configured_state(self, config: dict) -> bool: ...
    def has_persisted_auth_state(self, config: dict) -> bool: ...
    def resolve_default_to(self, config: dict, account_id: str | None = None) -> str | None: ...


# ── Gateway ──────────────────────────────────────────────


@runtime_checkable
class GatewayProtocol(Protocol):
    async def start(self, ctx: ChannelContext) -> Any: ...
    async def stop(self, ctx: ChannelContext) -> None: ...

    def resolve_gateway_auth_bypass_paths(self, config: dict) -> list[str]: ...

    async def login_with_qr_start(
        self, account_id: str | None = None, *, force: bool = False, timeout_ms: int | None = None
    ) -> dict:
        """返回 {"qr_data_url": str, "message": str, "connected": bool}"""
        ...

    async def login_with_qr_wait(
        self, account_id: str | None = None, *, timeout_ms: int | None = None, current_qr_data_url: str | None = None
    ) -> dict:
        """返回 {"connected": bool, "message": str, "qr_data_url": str | None}"""
        ...

    async def logout_account(self, ctx: ChannelContext) -> dict:
        """返回 {"cleared": bool, "logged_out": bool | None}"""
        ...


# ── Outbound ─────────────────────────────────────────────


class OutboundDeliveryMode(StrEnum):
    DIRECT = "direct"
    GATEWAY = "gateway"
    HYBRID = "hybrid"


@dataclass
class OutboundPresentationCapabilities:
    supported: bool = False
    buttons: bool = False
    selects: bool = False
    context: bool = False
    divider: bool = False


@dataclass
class OutboundDeliveryCapabilities:
    pin: bool = False
    durable_final_text: bool = False
    durable_final_media: bool = False
    durable_final_payload: bool = False
    durable_final_silent: bool = False
    durable_final_reply_to: bool = False
    durable_final_thread: bool = False
    durable_final_native_quote: bool = False
    durable_final_message_sending_hooks: bool = False
    durable_final_batch: bool = False
    durable_final_reconcile_unknown_send: bool = False
    durable_final_after_send_success: bool = False
    durable_final_after_commit: bool = False


@runtime_checkable
class OutboundProtocol(Protocol):
    delivery_mode: OutboundDeliveryMode

    def chunker(self, text: str, limit: int, ctx: Any | None = None) -> list[str]: ...

    chunker_mode: str | None
    text_chunk_limit: int | None

    async def send_text(
        self,
        target_id: str,
        content: str,
        *,
        reply_to_id: str | None = None,
        thread_id: str | None = None,
        account_id: str | None = None,
    ) -> None: ...
    async def send_media(
        self,
        target_id: str,
        media_url: str,
        media_type: str,
        *,
        reply_to_id: str | None = None,
        thread_id: str | None = None,
        account_id: str | None = None,
    ) -> None: ...
    async def send_payload(self, ctx: Any) -> Any: ...
    async def send_poll(self, ctx: Any) -> Any: ...

    async def edit_message(
        self,
        target_id: str,
        message_id: str,
        content: str,
        *,
        thread_id: str | None = None,
        account_id: str | None = None,
    ) -> str | None: ...
    async def send_card(
        self,
        target_id: str,
        card_content: dict,
        *,
        reply_to_id: str | None = None,
        thread_id: str | None = None,
        account_id: str | None = None,
    ) -> str | None: ...
    async def edit_card(
        self,
        target_id: str,
        message_id: str,
        card_content: dict,
        *,
        thread_id: str | None = None,
        account_id: str | None = None,
    ) -> str | None: ...

    def sanitize_text(self, text: str, payload: Any) -> str: ...
    def should_skip_plain_text_sanitization(self, payload: Any) -> bool: ...

    poll_max_options: int | None
    supports_poll_duration_seconds: bool
    supports_anonymous_polls: bool
    extract_markdown_images: bool

    def normalize_payload(self, payload: Any, config: dict, account_id: str | None = None) -> Any | None: ...
    def resolve_effective_text_chunk_limit(
        self, config: dict, account_id: str | None = None, fallback_limit: int | None = None
    ) -> int | None: ...

    presentation_capabilities: OutboundPresentationCapabilities | None
    delivery_capabilities: OutboundDeliveryCapabilities | None

    async def render_presentation(self, payload: Any, presentation: Any, ctx: Any) -> Any | None: ...
    async def pin_delivered_message(self, config: dict, target_ref: Any, message_id: str, pin: Any) -> None: ...

    async def before_deliver_payload(
        self, config: dict, target_ref: Any, payload: Any, hint: Any | None = None
    ) -> None: ...
    async def after_deliver_payload(self, config: dict, target_ref: Any, payload: Any, results: list) -> None: ...

    def resolve_target(
        self,
        to: str | None = None,
        *,
        config: dict | None = None,
        allow_from: list[str] | None = None,
        account_id: str | None = None,
        mode: str | None = None,
    ) -> tuple[bool, str]:
        """返回 (ok, to) 或 (False, error_message)"""
        ...

    def should_treat_delivered_text_as_visible(self, kind: str, text: str | None = None) -> bool: ...


# ── Status ───────────────────────────────────────────────


@dataclass
class ChannelAccountSnapshot:
    account_id: str
    name: str | None = None
    enabled: bool | None = None
    configured: bool | None = None
    status_state: str | None = None
    linked: bool | None = None
    running: bool | None = None
    connected: bool | None = None
    restart_pending: bool | None = None
    reconnect_attempts: int | None = None
    last_connected_at: float | None = None
    last_disconnect: dict | None = None
    last_message_at: float | None = None
    last_event_at: float | None = None
    last_transport_activity_at: float | None = None
    last_error: str | None = None
    health_state: str | None = None
    last_start_at: float | None = None
    last_stop_at: float | None = None
    last_inbound_at: float | None = None
    last_outbound_at: float | None = None
    busy: bool | None = None
    active_runs: int | None = None
    last_run_activity_at: float | None = None
    mode: str | None = None
    dm_policy: str | None = None
    allow_from: list[str] | None = None
    probe: Any | None = None
    last_probe_at: float | None = None
    audit: Any | None = None


@dataclass
class ChannelStatusIssue:
    channel: str
    account_id: str
    kind: str
    message: str
    fix: str | None = None


@runtime_checkable
class StatusProtocol(Protocol):
    default_runtime: ChannelAccountSnapshot | None

    async def probe(self, account: dict | None = None) -> bool: ...
    def build_summary(self, snapshot: Any) -> dict: ...

    def build_channel_summary(
        self,
        account: dict,
        config: dict,
        default_account_id: str,
        snapshot: ChannelAccountSnapshot,
    ) -> dict: ...
    def format_capabilities_probe(self, probe: Any) -> list[dict]: ...
    async def audit_account(
        self, account: dict, timeout_ms: int, config: dict, probe: Any | None = None
    ) -> Any: ...
    async def build_capabilities_diagnostics(
        self,
        account: dict,
        timeout_ms: int,
        config: dict,
        probe: Any | None = None,
        audit: Any | None = None,
        target: str | None = None,
    ) -> dict | None: ...
    def build_account_snapshot(
        self,
        account: dict,
        config: dict,
        runtime: ChannelAccountSnapshot | None = None,
        probe: Any | None = None,
        audit: Any | None = None,
    ) -> ChannelAccountSnapshot: ...
    def log_self_id(
        self, account: dict, config: dict, runtime: Any, include_channel_prefix: bool = False
    ) -> None: ...
    def resolve_account_state(
        self,
        account: dict,
        config: dict,
        configured: bool,
        enabled: bool,
    ) -> str: ...
    def collect_status_issues(self, accounts: list[ChannelAccountSnapshot]) -> list[ChannelStatusIssue]: ...


def build_standard_summary(
    snapshot: ChannelAccountSnapshot,
    channel_id: str,
) -> dict:
    return {
        "channel": channel_id,
        "account_id": snapshot.account_id,
        "name": snapshot.name,
        "enabled": snapshot.enabled,
        "configured": snapshot.configured,
        "running": snapshot.running,
        "connected": snapshot.connected,
        "health_state": snapshot.health_state,
        "last_message_at": snapshot.last_message_at,
        "last_event_at": snapshot.last_event_at,
        "active_runs": snapshot.active_runs,
        "busy": snapshot.busy,
        "dm_policy": snapshot.dm_policy,
        "allow_from": snapshot.allow_from,
        "mode": snapshot.mode,
        "last_error": snapshot.last_error,
    }


# ── Security ─────────────────────────────────────────────


@runtime_checkable
class SecurityProtocol(Protocol):
    async def check_allowlist(self, peer_id: str, channel_type: str) -> bool: ...
    def resolve_dm_policy(self) -> dict: ...

    def apply_config_fixes(self, config: dict) -> dict: ...
    def collect_warnings(
        self, config: dict, account_id: str | None = None, account: dict | None = None
    ) -> list[str]: ...
    def collect_audit_findings(
        self,
        config: dict,
        account_id: str | None = None,
        account: dict | None = None,
        source_config: dict | None = None,
        ordered_account_ids: list[str] | None = None,
        has_explicit_account_path: bool = False,
    ) -> list[dict]: ...


# ── Pairing ──────────────────────────────────────────────


@runtime_checkable
class PairingProtocol(Protocol):
    id_label: str

    async def generate_code(self, peer_id: str) -> str: ...
    async def verify_code(self, peer_id: str, code: str) -> bool: ...

    def normalize_allow_entry(self, entry: str) -> str: ...
    async def notify_approval(self, config: dict, peer_id: str, account_id: str | None = None) -> None: ...


# ── Groups ───────────────────────────────────────────────


@dataclass
class ChannelGroupContext:
    config: dict
    group_id: str | None = None
    group_channel: str | None = None
    group_space: str | None = None
    account_id: str | None = None
    sender_id: str | None = None
    sender_name: str | None = None
    sender_username: str | None = None
    sender_e164: str | None = None


@runtime_checkable
class GroupsProtocol(Protocol):
    async def list_groups(self) -> list[dict]: ...

    def resolve_require_mention(self, ctx: ChannelGroupContext) -> bool | None: ...
    def resolve_group_intro_hint(self, ctx: ChannelGroupContext) -> str | None: ...
    def resolve_tool_policy(self, ctx: ChannelGroupContext) -> dict | None: ...


# ── Mentions ─────────────────────────────────────────────


@runtime_checkable
class MentionsProtocol(Protocol):
    def extract_mentions(self, raw_message: dict) -> list[str]: ...

    def strip_mentions(
        self, text: str, ctx: object, config: dict | None = None, agent_id: str | None = None
    ) -> str: ...
    def strip_regexes(self, ctx: object, config: dict | None = None, agent_id: str | None = None) -> list: ...
    def strip_patterns(self, ctx: object, config: dict | None = None, agent_id: str | None = None) -> list[str]: ...


# ── Streaming ────────────────────────────────────────────


class SseEventType(StrEnum):
    REASONING = "reasoning"
    DELTA = "delta"
    TOOL_START = "tool_start"
    TOOL_END = "tool_end"
    MESSAGE_END = "message_end"
    AGENT_END = "agent_end"
    PHASE = "phase"
    IMAGE = "image"
    FILE = "file"
    VIDEO = "video"
    DONE = "done"
    ERROR = "error"


@runtime_checkable
class StreamingEventProtocol(Protocol):
    def build_streaming_events(self, agent_output: dict) -> list[dict]: ...

    @property
    def supported_event_types(self) -> list[str]: ...


@runtime_checkable
class StreamingProtocol(Protocol):
    streaming_mode: str
    preview_stream_throttle_ms: int
    preview_min_initial_chars: int
    block_streaming_enabled: bool
    block_streaming_break: str
    block_streaming_chunk_min_chars: int
    block_streaming_chunk_max_chars: int
    block_streaming_chunk_break_preference: str
    block_streaming_coalesce_defaults: dict | None

    def create_draft_stream_session(self, target_id: str) -> object: ...
    def create_block_chunker(self) -> object: ...


# ── Health ───────────────────────────────────────────────


@runtime_checkable
class HealthProtocol(Protocol):
    async def health_check(self) -> bool: ...


# ── Message ──────────────────────────────────────────────


@runtime_checkable
class MessageProtocol(Protocol):
    async def send_message(self, message: dict) -> None: ...


# ── Routing ──────────────────────────────────────────────


@runtime_checkable
class RoutingProtocol(Protocol):
    pass


# ── Startup ──────────────────────────────────────────────


@runtime_checkable
class StartupProtocol(Protocol):
    async def on_startup(self, config: dict) -> None: ...


# ── Transport ────────────────────────────────────────────


@runtime_checkable
class TransportProtocol(Protocol):
    async def connect(self) -> None: ...
    async def disconnect(self) -> None: ...


# ── Lifecycle ────────────────────────────────────────────


@runtime_checkable
class LifecycleProtocol(Protocol):
    async def on_config_changed(self, prev_cfg: dict, next_cfg: dict, account_id: str) -> None: ...
    async def on_account_removed(self, account_id: str) -> None: ...
    async def run_startup_maintenance(self, cfg: dict) -> None: ...
    async def on_retire(self) -> None: ...

    def detect_legacy_state_migrations(
        self,
        config: dict,
        state_dir: str,
        oauth_dir: str,
    ) -> list[dict]: ...


# ── Secrets ──────────────────────────────────────────────


@runtime_checkable
class SecretsProtocol(Protocol):
    """密钥注册表与运行时配置注入适配器"""

    secret_target_registry_entries: list | None
    unsupported_secret_ref_surface_patterns: list[str] | None

    def collect_unsupported_secret_ref_config_candidates(self, raw: object) -> list[dict]: ...
    def collect_runtime_config_assignments(
        self,
        config: dict,
        defaults: object | None,
        context: object,
    ) -> None: ...


# ── Approval ─────────────────────────────────────────────


class ApprovalAction(StrEnum):
    APPROVE_EXEC = "approve_exec"
    APPROVE_READ = "approve_read"


class ApprovalDecision(StrEnum):
    APPROVED = "approved"
    DENIED = "denied"
    CANCELLED = "cancelled"
    EXPIRED = "expired"


@dataclass
class ApprovalRequest:
    id: str
    channel_type: str
    account_id: str
    initiator_peer_id: str
    action: ApprovalAction
    description: str
    context: dict = field(default_factory=dict)
    created_at: float = field(default_factory=time.monotonic)
    expires_at: float | None = None


@dataclass
class ApprovalResult:
    request_id: str
    decision: ApprovalDecision
    decided_by: str | None = None
    decided_at: float = field(default_factory=time.monotonic)
    reason: str | None = None


@dataclass
class ApprovalForwardTarget:
    channel: str
    to: str
    account_id: str | None = None
    thread_id: str | int | None = None
    source: str | None = None


class ApprovalKind(StrEnum):
    EXEC = "exec"
    PLUGIN = "plugin"


@runtime_checkable
class ApprovalProtocol(Protocol):
    async def check_approval_required(self, config: dict, action: ApprovalAction, initiator_peer_id: str) -> bool: ...
    async def create_approval_request(
        self, config: dict, action: ApprovalAction, initiator_peer_id: str, description: str, context: dict
    ) -> ApprovalRequest: ...
    async def send_approval_notification(
        self, config: dict, request: ApprovalRequest, approver_peer_ids: list[str]
    ) -> bool: ...
    async def check_approval_status(self, config: dict, request_id: str) -> ApprovalResult | None: ...
    def get_approver_ids(self, config: dict) -> list[str]: ...

    # ── Capability 扩展 ──
    def authorize_actor_action(
        self,
        config: dict,
        account_id: str | None,
        sender_id: str | None,
        action: str,
        approval_kind: str,
    ) -> dict:
        """返回 {"authorized": bool, "reason": str | None}"""
        ...

    def get_action_availability_state(
        self,
        config: dict,
        account_id: str | None,
        action: str,
        approval_kind: str | None = None,
    ) -> dict:
        """返回 {"kind": "enabled"|"disabled"|"unsupported"}"""
        ...

    def get_exec_initiating_surface_state(
        self,
        config: dict,
        account_id: str | None,
        action: str,
    ) -> dict: ...

    def resolve_approve_command_behavior(
        self,
        config: dict,
        account_id: str | None,
        sender_id: str | None,
        approval_kind: ApprovalKind,
    ) -> dict | None: ...

    # ── Delivery ──
    def has_configured_dm_route(self, config: dict) -> bool: ...
    def should_suppress_forwarding_fallback(
        self,
        config: dict,
        approval_kind: str,
        target: ApprovalForwardTarget,
        request: object,
    ) -> bool: ...

    # ── Render ──
    def build_exec_pending_payload(
        self,
        config: dict,
        request: object,
        target: ApprovalForwardTarget,
        now_ms: int,
    ) -> object | None: ...
    def build_exec_resolved_payload(
        self,
        config: dict,
        resolved: object,
        target: ApprovalForwardTarget,
    ) -> object | None: ...

    # ── Describe ──
    def describe_exec_approval_setup(
        self,
        channel: str,
        channel_label: str,
        account_id: str | None = None,
    ) -> str | None: ...


# ── Commands ─────────────────────────────────────────────


@dataclass
class ChannelCommand:
    name: str
    aliases: list[str] = field(default_factory=list)
    description: str = ""
    usage: str = ""
    requires_admin: bool = False
    handler: str = ""


@runtime_checkable
class CommandsProtocol(Protocol):
    def get_commands(self) -> list[ChannelCommand]: ...
    async def handle_command(self, config: dict, command_name: str, args: list[str], msg: Any, ctx: Any) -> str: ...

    enforce_owner_for_commands: bool
    skip_when_config_empty: bool
    native_commands_auto_enabled: bool
    native_skills_auto_enabled: bool

    def resolve_native_command_name(self, command_key: str, default_name: str) -> str | None: ...
    def build_commands_list_channel_data(
        self,
        current_page: int,
        total_pages: int,
        agent_id: str | None = None,
    ) -> object | None: ...
    def build_models_menu_channel_data(self, providers: list[dict]) -> object | None: ...
    def build_models_provider_channel_data(self, providers: list[dict]) -> object | None: ...
    def build_models_add_provider_channel_data(self, providers: list[dict]) -> object | None: ...
    def build_models_list_channel_data(
        self,
        provider: str,
        models: list[str],
        current_model: str | None = None,
        current_page: int = 0,
        total_pages: int = 0,
        page_size: int | None = None,
        model_names: dict | None = None,
    ) -> object | None: ...
    def build_model_browse_channel_data(self) -> object | None: ...


# ── Resolver ─────────────────────────────────────────────


class ResolveKind(StrEnum):
    USER = "user"
    GROUP = "group"


@dataclass
class ResolveTarget:
    name: str
    resolved_id: str | None = None
    kind: str = "peer"
    confidence: float = 0.0
    candidates: list[dict] = field(default_factory=list)


@runtime_checkable
class ResolverProtocol(Protocol):
    async def resolve_targets(
        self,
        config: dict,
        inputs: list[str],
        kind: ResolveKind,
        account_id: str | None = None,
    ) -> list[ResolveTarget]: ...

    async def resolve_peer(self, config: dict, name_or_alias: str) -> ResolveTarget: ...
    async def resolve_group(self, config: dict, name_or_alias: str) -> ResolveTarget: ...


# ── Doctor ───────────────────────────────────────────────


@dataclass
class DoctorConfigMutation:
    config: dict
    changes: list[str] = field(default_factory=list)
    warnings: list[str] | None = None


@runtime_checkable
class DoctorProtocol(Protocol):
    """配置诊断与自动修复适配器"""

    async def check_credentials(self, config: dict) -> CredentialCheckResult:
        """验证凭证有效性（AppKey/Secret 是否可获取 token）"""
        ...

    async def check_permissions(self, config: dict) -> PermissionCheckResult:
        """验证 API 权限（是否有收发消息权限）"""
        ...

    async def check_connectivity(self, config: dict) -> ConnectivityCheckResult:
        """连接测试（WebSocket/HTTP 端点可达性）"""
        ...

    def normalize_compatibility_config(self, config: dict) -> dict:
        """旧版配置格式兼容性迁移"""
        ...

    def collect_allowlist_warnings(self, allowlist_config: dict) -> list[DiagnosisWarning]:
        """白名单配置安全告警"""
        ...

    def generate_repair_plan(self, diagnosis: DiagnosisResult) -> list[RepairStep]:
        """根据诊断结果生成修复计划"""
        ...

    async def execute_repair(self, step: RepairStep, config: dict) -> RepairResult:
        """执行单个修复步骤"""
        ...

    def legacy_config_rules(self) -> list[LegacyConfigRule]:
        """声明旧版配置规则（供自动迁移使用）"""
        ...

    @property
    def dm_allow_from_mode(self) -> str:
        """DM 白名单模式"""
        ...

    @property
    def group_model(self) -> str:
        """群组权限模型"""
        ...

    group_allow_from_fallback_to_allow_from: bool
    warn_on_empty_group_sender_allowlist: bool

    def collect_preview_warnings(self, config: dict, doctor_fix_command: str) -> list[str]: ...
    def collect_mutable_allowlist_warnings(self, config: dict) -> list[str]: ...
    def repair_config(self, config: dict, doctor_fix_command: str) -> DoctorConfigMutation: ...
    def run_config_sequence(self, config: dict, should_repair: bool) -> dict: ...
    def clean_stale_config(self, config: dict) -> DoctorConfigMutation: ...
    def collect_empty_allowlist_extra_warnings(self, ctx: dict) -> list[str]: ...
    def should_skip_default_empty_group_allowlist_warning(self, ctx: dict) -> bool: ...


# ── Directory ────────────────────────────────────────────


@dataclass
class DirectoryPeer:
    """目录中的对等体（用户/机器人）"""

    id: str
    display_name: str
    kind: str = "user"
    avatar_url: str | None = None
    mention_name: str | None = None
    extra: dict = field(default_factory=dict)


@dataclass
class DirectoryGroup:
    """目录中的群组/频道"""

    id: str
    display_name: str
    kind: str = "group"
    member_count: int = 0
    extra: dict = field(default_factory=dict)


@dataclass
class DirectoryEntry:
    """统一目录条目（对应 OpenClaw ChannelDirectoryEntry）"""

    kind: str
    id: str
    name: str | None = None
    handle: str | None = None
    avatar_url: str | None = None
    rank: int | None = None
    raw: object | None = None


@dataclass
class DirectorySearchParams:
    """目录搜索参数"""

    query: str
    kind: str = "user"
    limit: int = 20
    offset: int = 0
    include_bots: bool = False


@dataclass
class DirectorySearchResult:
    """目录搜索结果"""

    items: list[DirectoryPeer | DirectoryGroup]
    total: int
    has_more: bool
    offset: int = 0


@runtime_checkable
class DirectoryProtocol(Protocol):
    """用户/群组/频道目录查询适配器"""

    async def self(self, config: dict, account_id: str | None = None) -> DirectoryEntry | None:
        """获取 bot 自身的目录条目"""
        ...

    async def list_peers(self, config: dict) -> list[DirectoryPeer]:
        """列出可用用户/联系人（静态，从配置解析）"""
        ...

    async def list_groups(self, config: dict) -> list[DirectoryGroup]:
        """列出可用群组/频道（静态，从配置解析）"""
        ...

    async def list_peers_live(
        self,
        config: dict,
        account_id: str | None = None,
        query: str | None = None,
        limit: int | None = None,
    ) -> list[DirectoryEntry]:
        """在线 API 查询用户/联系人"""
        ...

    async def list_groups_live(
        self,
        config: dict,
        account_id: str | None = None,
        query: str | None = None,
        limit: int | None = None,
    ) -> list[DirectoryEntry]:
        """在线 API 查询群组/频道"""
        ...

    async def list_group_members(
        self,
        config: dict,
        group_id: str,
        account_id: str | None = None,
        limit: int | None = None,
    ) -> list[DirectoryEntry]:
        """列出群组成员"""
        ...

    async def search_peers(self, config: dict, params: DirectorySearchParams) -> DirectorySearchResult:
        """搜索用户/联系人（在线，渠道 API 查询）"""
        ...

    async def search_groups(self, config: dict, params: DirectorySearchParams) -> DirectorySearchResult:
        """搜索群组/频道（在线，渠道 API 查询）"""
        ...

    async def get_peer(self, config: dict, peer_id: str) -> DirectoryPeer | None:
        """根据 ID 获取单个用户详情"""
        ...

    async def get_group(self, config: dict, group_id: str) -> DirectoryGroup | None:
        """根据 ID 获取单个群组详情"""
        ...


# ── Heartbeat ────────────────────────────────────────────


@runtime_checkable
class HeartbeatProtocol(Protocol):
    """心跳保活 + typing 指示器适配器"""

    @property
    def ping_interval_ms(self) -> int:
        """心跳间隔（毫秒），默认 30000"""
        ...

    async def check_ready(
        self,
        config: dict,
        account_id: str | None = None,
        deps: object | None = None,
    ) -> dict:
        """返回 {"ok": bool, "reason": str}"""
        ...

    async def on_ping(self, account: dict) -> bool:
        """执行心跳 ping，返回是否正常"""
        ...

    async def send_typing(
        self,
        config: dict,
        to: str,
        account_id: str | None = None,
        thread_id: str | int | None = None,
        deps: object | None = None,
    ) -> None: ...

    async def clear_typing(
        self,
        config: dict,
        to: str,
        account_id: str | None = None,
        thread_id: str | int | None = None,
        deps: object | None = None,
    ) -> None: ...

    async def start_typing(self, target_id: str, account: dict) -> object:
        """开始 typing 指示器，返回可用于 stop 的句柄"""
        ...

    async def stop_typing(self, handle: object) -> None:
        """停止 typing 指示器"""
        ...

    async def typing_indicator(
        self,
        target_id: str,
        account: dict,
        _stop_event,
    ) -> None:
        """完整 typing 生命周期：start → keepalive → stop"""
        ...


# ── Agent Prompt ─────────────────────────────────────────


@dataclass
class AgentPromptContext:
    channel_type: str
    account_id: str
    peer_id: str | None = None
    peer_name: str | None = None
    group_id: str | None = None
    group_name: str | None = None
    thread_id: str | None = None


@runtime_checkable
class AgentPromptProtocol(Protocol):
    """渠道特有的 Agent 提示信息注入

    不同渠道有不同的消息格式和交互约束，通过此协议向 LLM 注入
    渠道特定的系统提示，让 Agent 知道当前在哪个渠道、有哪些能力可用。
    """

    def build_system_prompt(self, context: AgentPromptContext) -> str | None:
        """构建渠道特定的系统提示（注入到 Agent system prompt）"""
        ...

    def build_context_note(self, context: AgentPromptContext) -> str:
        """构建当前消息的上下文提示（注入到 user message 前缀）"""
        ...

    @property
    def channel_format_instructions(self) -> str | None:
        """渠道消息格式说明（如支持 Markdown、卡片格式、字数限制）"""
        ...

    def message_tool_hints(self, config: dict, account_id: str | None = None) -> list[str]: ...
    def message_tool_capabilities(self, config: dict, account_id: str | None = None) -> list[str] | None: ...
    def inbound_formatting_hints(self, account_id: str | None = None) -> dict | None: ...
    def reaction_guidance(self, config: dict, account_id: str | None = None) -> dict | None: ...


# ── Threading ────────────────────────────────────────────


@dataclass
class ThreadInfo:
    thread_id: str
    parent_message_id: str | None = None
    title: str | None = None
    is_threaded: bool = True


@dataclass
class ReplyTransport:
    mode: str = "inline"
    thread_id: str | None = None
    target_id: str | None = None


@runtime_checkable
class ThreadingProtocol(Protocol):
    """线程/话题解析适配器"""

    def extract_thread_id(self, msg: object) -> str | None:
        """从原始消息提取线程/话题 ID"""
        ...

    def resolve_reply_transport(self, msg: object, thread_id: str | None) -> ReplyTransport:
        """决定回复是以线程内回复还是广播方式"""
        ...

    def get_thread_info(self, thread_id: str) -> ThreadInfo | None:
        """获取线程详情"""
        ...

    def resolve_reply_to_mode(
        self,
        config: dict,
        account_id: str | None = None,
        chat_type: str | None = None,
    ) -> str:
        """返回 "off"|"first"|"all"|"batched" """
        ...

    allow_explicit_reply_tags_when_off: bool

    def build_tool_context(
        self,
        config: dict,
        account_id: str | None,
        context: object,
        has_replied_ref: object | None = None,
    ) -> object | None: ...

    def resolve_auto_thread_id(
        self,
        config: dict,
        account_id: str | None,
        to: str,
        tool_context: object | None = None,
        reply_to_id: str | None = None,
    ) -> str | None: ...

    def resolve_focused_binding(
        self,
        config: dict,
        account_id: str | None,
        context: object,
    ) -> object | None: ...


# ── Messaging ────────────────────────────────────────────


@dataclass
class SessionResolution:
    """会话归属解析结果"""

    kind: str
    conversation_id: str
    label: str | None = None
    thread_id: str | None = None
    explicit_target: str | None = None


@dataclass
class BoundReplyPayload:
    """渠道感知的回复载荷"""

    target_id: str
    content: str
    reply_to_id: str | None = None
    thread_id: str | None = None
    routing_hint: dict | None = None
    metadata: dict | None = None


@runtime_checkable
class MessagingProtocol(Protocol):
    """会话感知路由适配器

    渠道通过此协议自定义消息归属、会话路由、回复载荷构造。
    不实现此协议的渠道使用默认逻辑（DM/群二分 + 纯文本回复）。
    """

    def resolve_session(self, msg: object) -> SessionResolution:
        """确定消息归属哪个会话"""
        ...

    def parse_explicit_target(self, content: str) -> str | None:
        """解析 @Bot 后缀的显式路由目标"""
        ...

    def build_reply_payload(
        self,
        target_id: str,
        content: str,
        *,
        reply_to_id: str | None = None,
        thread_id: str | None = None,
        session_key: str | None = None,
        agent_config_id: str | None = None,
        **kwargs,
    ) -> BoundReplyPayload:
        """构建渠道感知的回复载荷"""
        ...

    def resolve_focused_binding(self, msg: object, session: SessionResolution, current_binding: object) -> dict | None:
        """会话内临时路由重定向（如话题内切换 Agent）"""
        ...

    @property
    def supported_explicit_targets(self) -> list[str]:
        """支持的显式路由目标关键词"""
        ...

    def build_attachment_refs(self, attachments: list[dict]) -> str:
        """将附件列表转换为文本引用

        输入: [{"file_path": "/tmp/img.png", "file_type": "image", "file_name": "img.png"}]
        输出: "\\n[图片: /tmp/img.png]\\n[文件: /tmp/doc.pdf]"
        """
        ...

    # ── 扩展方法 ──
    target_prefixes: list[str] | None

    def normalize_target(self, raw: str) -> str | None: ...

    default_markdown_table_mode: str | None

    def normalize_explicit_session_key(self, session_key: str, ctx: object) -> str | None: ...
    def derive_legacy_session_chat_type(self, session_key: str) -> str | None: ...
    def is_legacy_group_session_key(self, key: str) -> bool: ...
    def canonicalize_legacy_session_key(self, key: str, agent_id: str) -> str | None: ...
    def resolve_legacy_group_session_key(self, ctx: object) -> dict | None: ...

    def resolve_inbound_attachment_roots(self, config: dict, account_id: str | None = None) -> list[str]: ...
    def resolve_remote_inbound_attachment_roots(self, config: dict, account_id: str | None = None) -> list[str]: ...

    def resolve_inbound_conversation(
        self,
        from_: str | None = None,
        to: str | None = None,
        conversation_id: str | None = None,
        thread_id: str | int | None = None,
        is_group: bool = False,
    ) -> dict | None: ...

    def resolve_delivery_target(
        self,
        conversation_id: str,
        parent_conversation_id: str | None = None,
    ) -> dict | None: ...

    def resolve_session_conversation(self, kind: str, raw_id: str) -> dict | None: ...
    def resolve_session_target(
        self,
        kind: str,
        id: str,
        thread_id: str | None = None,
    ) -> str | None: ...

    def parse_explicit_target_full(self, raw: str) -> dict | None: ...
    def infer_target_chat_type(self, to: str) -> str | None: ...

    preserve_heartbeat_thread_id_for_group_route: bool

    def build_cross_context_presentation(
        self, origin_label: str, message: str, config: dict, account_id: str | None = None
    ) -> object: ...
    def transform_reply_payload(
        self, payload: object, config: dict, account_id: str | None = None
    ) -> object | None: ...
    def enable_interactive_replies(self, config: dict, account_id: str | None = None) -> bool: ...
    def has_structured_reply_payload(self, payload: object) -> bool: ...

    def target_resolver_looks_like_id(self, raw: str, normalized: str | None = None) -> bool: ...
    async def target_resolver_resolve_target(
        self,
        config: dict,
        input_: str,
        normalized: str,
        account_id: str | None = None,
        preferred_kind: str | None = None,
    ) -> dict | None: ...

    def format_target_display(self, target: str, display: str | None = None, kind: str | None = None) -> str: ...

    async def resolve_outbound_session_route(
        self,
        config: dict,
        agent_id: str,
        target: str,
        account_id: str | None = None,
        current_session_key: str | None = None,
        resolved_target: dict | None = None,
        reply_to_id: str | None = None,
        thread_id: str | int | None = None,
    ) -> object | None: ...


# ── Hooks ────────────────────────────────────────────────


@runtime_checkable
class MessageSendingHook(Protocol):
    """入站消息发送前钩子

    渠道插件可实现在回复发送前拦截/修改消息内容。
    """

    async def on_message_sending(self, msg: object, content: str) -> str | None:
        """回复发送前钩子，返回 None 表示阻止发送，返回 str 表示替换内容"""
        ...


@runtime_checkable
class InboundMessageHook(Protocol):
    """入站消息接收钩子

    渠道插件可在消息被调度前进行预处理（过滤/转换）。
    """

    async def on_message_received(self, msg: object) -> object | None:
        """消息接收后、调度前钩子，返回 None 表示丢弃消息"""
        ...


@runtime_checkable
class SendLifecycleHook(Protocol):
    """发送生命周期钩子

    渠道插件可监听发送各阶段事件。
    """

    async def before_send_attempt(self, target_id: str, content: str) -> None:
        """发送前钩子"""
        ...

    async def after_send_success(self, target_id: str, receipt: object) -> None:
        """发送成功后钩子"""
        ...

    async def after_send_failure(self, target_id: str, error: str) -> None:
        """发送失败后钩子"""
        ...

    async def after_commit(self, receipt: object) -> None:
        """提交确认后钩子"""
        ...


# ── Config Schema ────────────────────────────────────────


@runtime_checkable
class ConfigSchemaProtocol(Protocol):
    """渠道配置 JSON Schema 定义

    用于前端表单生成和配置校验。每个渠道声明自己的配置结构。
    """

    def config_schema(self) -> dict:
        """返回 JSON Schema (draft-07) 描述的渠道配置结构"""
        ...


# ── Defaults ─────────────────────────────────────────────


@runtime_checkable
class DefaultsProtocol(Protocol):
    """渠道默认值适配器

    提供渠道级别的默认配置，如 debounce 时长等。
    """

    @property
    def debounce_ms(self) -> int:
        """消息去重 debounce 毫秒数，默认 5000"""
        ...


# ── Reload ───────────────────────────────────────────────


@runtime_checkable
class ReloadProtocol(Protocol):
    """配置热重载适配器

    渠道声明哪些配置前缀变更时需要触发重新加载。
    """

    @property
    def config_prefixes(self) -> list[str]:
        """触发重载的配置键前缀列表"""
        ...


# ── Setup ────────────────────────────────────────────────


@runtime_checkable
class SetupProtocol(Protocol):
    """渠道初始化/安装适配器

    渠道首次启用时执行的初始化流程。
    """

    async def setup(self, config: dict) -> bool:
        """执行渠道初始化，返回是否成功"""
        ...

    def resolve_account_id(
        self,
        config: dict,
        account_id: str | None = None,
        input_: object | None = None,
    ) -> str: ...

    def resolve_binding_account_id(
        self,
        config: dict,
        agent_id: str,
        account_id: str | None = None,
    ) -> str | None: ...

    def apply_account_name(self, config: dict, account_id: str, name: str | None = None) -> dict: ...
    def apply_account_config(self, config: dict, account_id: str, input_: object) -> dict: ...

    async def after_account_config_written(
        self,
        prev_cfg: dict,
        cfg: dict,
        account_id: str,
        input_: object,
        runtime: object,
    ) -> None: ...

    def validate_input(self, config: dict, account_id: str, input_: object) -> str | None: ...

    single_account_keys_to_move: list[str] | None
    named_account_promotion_keys: list[str] | None

    def resolve_single_account_promotion_target(self, channel: dict) -> str | None: ...


# ── Setup Wizard ─────────────────────────────────────────


@dataclass
class SetupWizardStep:
    """安装向导步骤"""

    key: str
    label: str
    description: str = ""
    input_type: str = "text"
    required: bool = True
    default: str | None = None
    options: list[dict] = field(default_factory=list)


@runtime_checkable
class SetupWizardProtocol(Protocol):
    """渠道安装向导适配器

    为渠道提供交互式配置引导流程。
    """

    def setup_wizard_steps(self) -> list[SetupWizardStep]:
        """返回安装向导步骤列表"""
        ...

    async def validate_wizard_input(self, step_key: str, value: str) -> str | None:
        """验证向导输入，返回错误消息或 None"""
        ...


# ── Agent Tool ───────────────────────────────────────────


@dataclass
class AgentToolParam:
    name: str
    type: str = "string"
    description: str = ""
    required: bool = False
    enum: list[str] | None = None
    default: Any = None
    items_type: str | None = None
    additional_properties: bool | None = None


@dataclass
class AgentTool:
    name: str
    description: str
    parameters: list[AgentToolParam] = field(default_factory=list)
    handler_name: str = ""
    scope: str = "current_channel"

    def to_openai_schema(self) -> dict:
        properties = {}
        required = []
        for p in self.parameters:
            prop: dict[str, Any] = {"type": p.type, "description": p.description}
            if p.enum:
                prop["enum"] = p.enum
            if p.type == "array" and p.items_type:
                prop["items"] = {"type": p.items_type}
            if p.type == "object" and p.additional_properties is not None:
                prop["additionalProperties"] = p.additional_properties
            properties[p.name] = prop
            if p.required:
                required.append(p.name)

        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": {
                    "type": "object",
                    "properties": properties,
                    "required": required,
                },
            },
        }


@runtime_checkable
class AgentToolProtocol(Protocol):
    """渠道级 Agent 工具注册适配器

    渠道通过此协议向 Agent 暴露可调用的工具，例如飞书的
    wiki/doc/bitable/drive 等渠道专属能力。
    每个工具包含 schema 定义和 handler 执行逻辑。
    """

    def get_agent_tools(self) -> list[AgentTool]:
        """返回当前渠道注册的 Agent 工具列表"""
        ...

    async def execute_agent_tool(self, tool_name: str, params: dict, context: dict) -> dict:
        """执行 Agent 工具调用

        Args:
            tool_name: 工具名称
            params: 工具参数
            context: 执行上下文，包含 channel_type/account_id/peer_id 等

        Returns:
            {"success": bool, "result": ..., "error": str | None}
        """
        ...


# ── Message Action ───────────────────────────────────────


@dataclass
class MessageActionCapability:
    action: str
    description: str = ""
    parameters: list[AgentToolParam] = field(default_factory=list)
    requires_trusted_sender: bool = False
    scope: str = "current_channel"


@runtime_checkable
class MessageActionProtocol(Protocol):
    """统一消息操作命令适配器

    渠道通过此协议声明支持的消息操作命令体系：
    send / edit / react / pin / unsend / channel-info 等。
    与 AgentToolProtocol 协作，Agent 可通过 tool call 执行这些操作。
    """

    def get_message_actions(self) -> list[MessageActionCapability]:
        """返回渠道支持的消息操作列表"""
        ...

    async def execute_message_action(
        self,
        action: str,
        params: dict,
        context: dict,
    ) -> dict:
        """执行消息操作

        Args:
            action: 操作名称 (send/edit/react/pin 等)
            params: 操作参数
            context: 执行上下文

        Returns:
            {"success": bool, "result": ..., "error": str | None}
        """
        ...

    # ── 扩展方法 ──
    def describe_message_tool(self, ctx: dict) -> dict | None: ...
    def supports_action(self, action: str) -> bool: ...
    def resolve_execution_mode(self, action: str) -> str: ...
    def requires_trusted_requester_sender(self, action: str, tool_context: object | None = None) -> bool: ...
    def extract_tool_send(self, args: dict) -> dict | None: ...
    async def prepare_send_payload(
        self, ctx: object, to: str, payload: object, reply_to_id: str | None = None, thread_id: str | int | None = None
    ) -> object | None: ...
    async def handle_action(self, ctx: object) -> dict: ...


# ── Auth ─────────────────────────────────────────────────


@runtime_checkable
class AuthProtocol(Protocol):
    """渠道认证/登录适配器

    对应 OpenClaw ChannelAuthAdapter。渠道特有的登录认证流程，
    如 OAuth 授权、QR 码登录、账号密码登录等。
    """

    async def login(self, config: dict) -> dict:
        """执行登录，返回认证凭据"""
        ...

    async def logout(self, config: dict) -> None:
        """执行登出，清除认证状态"""
        ...

    async def refresh_token(self, config: dict) -> dict | None:
        """刷新访问令牌，返回新的凭据或 None"""
        ...

    async def qr_auth_start(self, config: dict) -> str:
        """启动 QR 码认证，返回 QR 码 URL 或数据

        Returns:
            QR 码数据字符串（URL 或 base64）
        """
        ...

    async def qr_auth_wait(self, config: dict) -> dict | None:
        """等待 QR 码认证扫描结果

        Returns:
            认证凭据 dict 或 None（超时未扫描）
        """
        ...


# ── Elevated ─────────────────────────────────────────────


@runtime_checkable
class ElevatedProtocol(Protocol):
    """渠道提权适配器

    对应 OpenClaw ChannelElevatedAdapter。
    渠道需要以更高权限执行操作时使用（如管理群组、踢人）。
    """

    async def elevate(self, account: dict, reason: str) -> bool:
        """提升当前权限等级

        Args:
            account: 渠道账户配置
            reason: 提权原因

        Returns:
            是否成功提权
        """
        ...

    async def revoke(self, account: dict) -> None:
        """撤销提权"""
        ...

    @property
    def is_elevated(self) -> bool:
        """当前是否处于提权状态"""
        ...

    def allow_from_fallback(
        self,
        config: dict,
        account_id: str | None = None,
    ) -> list[str | int] | None: ...


# ── Allowlist Management ─────────────────────────────────


@runtime_checkable
class AllowlistManagementProtocol(Protocol):
    """白名单管理适配器

    对应 OpenClaw ChannelAllowlistAdapter。
    渠道通过此协议管理 DM/群组白名单的增删改查。
    """

    async def list_allow_entries(self, config: dict, scope: str) -> list[str]:
        """列出白名单条目

        Args:
            config: 渠道配置
            scope: "dm" 或 "group"
        """
        ...

    async def add_allow_entry(self, config: dict, scope: str, entry: str) -> bool:
        """添加白名单条目"""
        ...

    async def remove_allow_entry(self, config: dict, scope: str, entry: str) -> bool:
        """移除白名单条目"""
        ...

    async def resolve_allow_from(self, config: dict, account_id: str) -> list[str]:
        """解析完整的 allow_from 列表"""
        ...

    # ── 扩展方法 ──
    def apply_config_edit(
        self,
        config: dict,
        account_id: str | None,
        scope: str,
        action: str,
        entry: str,
    ) -> dict | None:
        """返回 {"kind": "ok", "changed": bool, "path_label": str, "write_target": object}
        或 {"kind": "invalid-entry"} 或 None"""
        ...

    async def read_config(self, config: dict, account_id: str | None = None) -> dict:
        """返回 {"dm_allow_from": ..., "group_allow_from": ..., "dm_policy": str, ...}"""
        ...

    async def resolve_names(
        self,
        config: dict,
        account_id: str | None,
        scope: str,
        entries: list[str],
    ) -> list[dict]: ...

    def supports_scope(self, scope: str) -> bool: ...


# ── Binding Provider ─────────────────────────────────────


@dataclass
class BindingConversationRef:
    conversation_id: str
    parent_conversation_id: str | None = None


@runtime_checkable
class BindingProviderProtocol(Protocol):
    """Agent 绑定编译与会话匹配适配器

    对应 OpenClaw ChannelConfiguredBindingProvider。
    """

    self_parent_conversation_by_default: bool

    def compile_configured_binding(
        self,
        binding: dict,
        conversation_id: str,
    ) -> BindingConversationRef | None: ...

    def match_inbound_conversation(
        self,
        binding: dict,
        compiled_binding: BindingConversationRef,
        conversation_id: str,
        parent_conversation_id: str | None = None,
    ) -> object | None: ...

    def resolve_command_conversation(self, ctx: dict) -> BindingConversationRef | None: ...


# ── Conversation Binding ─────────────────────────────────


@runtime_checkable
class ConversationBindingProtocol(Protocol):
    """会话绑定管理适配器

    对应 OpenClaw ChannelConversationBindingSupport。
    """

    supports_current_conversation_binding: bool
    default_top_level_placement: str

    def resolve_conversation_ref(
        self,
        account_id: str | None,
        conversation_id: str,
        parent_conversation_id: str | None = None,
        thread_id: str | int | None = None,
    ) -> dict | None: ...

    async def build_bound_reply_payload(
        self,
        operation: str,
        placement: str,
        conversation: dict,
    ) -> object | None: ...

    def build_model_override_parent_candidates(
        self,
        parent_conversation_id: str | None = None,
    ) -> list[str] | None: ...

    def should_strip_thread_from_announce_origin(self, requester: dict, entry: dict) -> bool: ...

    def set_idle_timeout_by_session_key(
        self,
        target_session_key: str,
        account_id: str | None,
        idle_timeout_ms: int,
    ) -> list[dict]: ...

    def set_max_age_by_session_key(
        self,
        target_session_key: str,
        account_id: str | None,
        max_age_ms: int,
    ) -> list[dict]: ...

    async def create_manager(self, config: dict, account_id: str | None = None) -> object:
        """返回 {"stop": callable}"""
        ...


# ── Message Adapter (Durable Final / Send / Live / Receive) ──


class MessageDurabilityPolicy(StrEnum):
    REQUIRED = "required"
    BEST_EFFORT = "best_effort"
    DISABLED = "disabled"


@runtime_checkable
class MessageDurableFinalProtocol(Protocol):
    """持久化最终投递适配器

    对应 OpenClaw ChannelMessageDurableFinalAdapter。
    """

    capabilities: dict | None

    async def reconcile_unknown_send(self, ctx: object) -> object | None: ...


@runtime_checkable
class MessageSendProtocol(Protocol):
    """消息发送适配器

    对应 OpenClaw ChannelMessageSendAdapter。
    """

    async def send_text(self, ctx: object) -> object: ...
    async def send_media(self, ctx: object) -> object: ...
    async def send_payload(self, ctx: object) -> object: ...

    async def before_send_attempt(self, ctx: object) -> object: ...
    async def after_send_success(self, ctx: object) -> None: ...
    async def after_send_failure(self, ctx: object) -> None: ...
    async def after_commit(self, ctx: object) -> None: ...


@runtime_checkable
class MessageLiveProtocol(Protocol):
    """实时消息/流式预览适配器

    对应 OpenClaw ChannelMessageLiveAdapterShape。
    """

    capabilities: dict | None

    finalizer_capabilities: dict | None


@runtime_checkable
class MessageReceiveProtocol(Protocol):
    """消息接收适配器

    对应 OpenClaw ChannelMessageReceiveAdapterShape。
    """

    default_ack_policy: str
    supported_ack_policies: list[str] | None


# ── File Handling ───────────────────────────────────────


@runtime_checkable
class FileHandlingProtocol(Protocol):
    """文件上传/服务协议

    渠道通过此协议可使用统一的文件上传、分类和服务能力，
    替代各渠道分散实现的文件处理逻辑。
    """

    async def upload_file(self, file_data: bytes, file_name: str, session_id: str) -> dict:
        """上传文件，返回:
        {
            "file_path": "/abs/path/to/file",
            "file_name": "original.png",
            "file_type": "image" | "video" | "file",
            "preview_url": "/api/files/preview/{uuid}"
        }
        """
        ...

    async def serve_file(self, file_path: str) -> tuple[bytes, str]:
        """服务文件，返回 (content_bytes, mime_type)"""
        ...

    @staticmethod
    def classify_file(extension: str) -> str:
        """根据扩展名分类：image / video / file"""
        ...


# ── Reaction ─────────────────────────────────────────────


@runtime_checkable
class ReactionProtocol(Protocol):
    """消息反应/表情协议

    渠道通过此协议支持对消息添加/移除表情反应。
    对应 ChannelCapabilities.reactions 能力标志。
    """

    async def send_reaction(
        self,
        target_id: str,
        message_id: str,
        emoji: str,
        *,
        account_id: str | None = None,
    ) -> None:
        """为指定消息添加表情反应"""
        ...

    async def remove_reaction(
        self,
        target_id: str,
        message_id: str,
        emoji: str,
        *,
        account_id: str | None = None,
    ) -> None:
        """移除指定消息的表情反应"""
        ...

    async def fetch_reactions(
        self,
        target_id: str,
        message_id: str,
        *,
        account_id: str | None = None,
    ) -> list[dict]:
        """获取指定消息的反应列表"""
        ...


# ── Webhook ──────────────────────────────────────────────


@runtime_checkable
class WebhookProtocol(Protocol):
    """Webhook 接收处理协议

    渠道通过此协议注册和处理外部平台推送的 Webhook 事件。
    """

    async def handle_webhook(
        self,
        request: object,
        account_id: str | None = None,
    ) -> object:
        """处理 Webhook 请求，返回 HTTP Response"""
        ...

    def verify_signature(self, body: bytes, signature: str, secret: str) -> bool:
        """验证 Webhook 签名"""
        ...

    def resolve_webhook_auth_bypass_paths(self) -> list[str]:
        """返回不需要认证的 Webhook 路径列表"""
        ...


# ── Inbound Handler ──────────────────────────────────────


@runtime_checkable
class InboundHandlerProtocol(Protocol):
    """入站消息处理协议

    渠道通过此协议将原始平台事件转换为 UnifiedMessage。
    对应各渠道的 Monitor 类核心职责。
    """

    async def handle_raw_event(
        self,
        event: dict,
        account: dict,
    ) -> object | None:
        """处理原始事件，返回 UnifiedMessage 或 None"""
        ...

    def parse_to_unified(
        self,
        raw_event: dict,
        account_id: str,
    ) -> object | None:
        """将原始事件解析为 UnifiedMessage"""
        ...

    def resolve_event_type(self, raw_event: dict) -> str:
        """解析原始事件类型（message/reaction/join/leave 等）"""
        ...


# ── Media ────────────────────────────────────────────────


@runtime_checkable
class MediaProtocol(Protocol):
    """媒体上传/下载/处理协议

    渠道通过此协议统一管理媒体文件的上传、下载、类型检测和 URL 验证。
    """

    async def upload_media(
        self,
        file_path: str,
        media_type: str,
        *,
        account_id: str | None = None,
    ) -> dict:
        """上传媒体文件，返回 {"url": str, "type": str, "size": int}"""
        ...

    async def download_media(
        self,
        media_url: str,
        *,
        account_id: str | None = None,
    ) -> bytes:
        """下载媒体文件，返回文件字节"""
        ...

    def detect_media_type(self, filename: str, content_type: str = "") -> str:
        """根据文件名和 Content-Type 检测媒体类型（image/video/file）"""
        ...

    def validate_media_url(self, url: str) -> bool:
        """验证媒体 URL 是否有效"""
        ...

    def resolve_media_size_limit(self, media_type: str) -> int:
        """返回指定媒体类型的最大允许大小（字节）"""
        ...


# ── Format ───────────────────────────────────────────────


@runtime_checkable
class FormatProtocol(Protocol):
    """消息格式化协议

    渠道通过此协议统一处理文本清理、Markdown 转换、提及剥离和分块。
    """

    def sanitize_text(self, text: str, payload: object | None = None) -> str:
        """清理文本中的非法字符或格式"""
        ...

    def chunker(self, text: str, limit: int, ctx: object | None = None) -> list[str]:
        """将长文本分块，返回文本块列表"""
        ...

    def markdown_to_native(self, md_text: str) -> dict | str:
        """将 Markdown 转换为目标平台的原生格式"""
        ...

    def native_to_markdown(self, native_content: dict | str) -> str:
        """将目标平台的原生格式转换为 Markdown"""
        ...

    def strip_mentions(self, text: str, ctx: object | None = None) -> str:
        """从文本中剥离提及标记"""
        ...


# ── Dedupe ───────────────────────────────────────────────


@runtime_checkable
class DedupeProtocol(Protocol):
    """消息去重协议

    渠道通过此协议防止重复处理相同的消息或事件。
    """

    def is_duplicate(self, key: str) -> bool:
        """检查给定 key 是否已存在（重复）"""
        ...

    def mark_seen(self, key: str) -> None:
        """标记给定 key 为已处理"""
        ...

    def reset(self) -> None:
        """重置去重缓存"""
        ...

    @property
    def ttl_seconds(self) -> int:
        """去重缓存的 TTL（秒）"""
        ...

    @property
    def max_entries(self) -> int:
        """去重缓存的最大条目数"""
        ...


# ── Card ─────────────────────────────────────────────────


@runtime_checkable
class CardProtocol(Protocol):
    """卡片/富文本消息协议

    渠道通过此协议支持发送和更新结构化卡片消息。
    """

    async def send_card(
        self,
        target_id: str,
        card_content: dict,
        *,
        reply_to_id: str | None = None,
        account_id: str | None = None,
    ) -> str | None:
        """发送卡片消息，返回消息 ID"""
        ...

    async def update_card(
        self,
        message_id: str,
        card_content: dict,
        *,
        account_id: str | None = None,
    ) -> bool:
        """更新已发送的卡片消息"""
        ...

    def build_text_card(self, text: str, title: str | None = None, **kwargs) -> dict:
        """构建纯文本卡片"""
        ...

    def supports_card_interactions(self) -> bool:
        """是否支持卡片交互（按钮、选择器等）"""
        ...


# ── Error Handling ───────────────────────────────────────


class ErrorSeverity(StrEnum):
    """错误严重级别"""

    RETRYABLE = "retryable"
    FATAL = "fatal"
    RATE_LIMITED = "rate_limited"
    FORBIDDEN = "forbidden"
    NETWORK = "network"


@dataclass
class ClassifiedError:
    """分类后的错误信息"""

    severity: ErrorSeverity
    retry_after_ms: int = 0
    original_error: BaseException | None = None
    error_message: str = ""


@runtime_checkable
class ErrorHandlingProtocol(Protocol):
    """错误分类与重试协议

    渠道通过此协议统一处理错误分类、重试策略和退避计算。
    """

    def classify_error(self, error: BaseException) -> ClassifiedError:
        """将异常分类为特定严重级别"""
        ...

    def is_retryable(self, error: BaseException) -> bool:
        """判断错误是否可重试"""
        ...

    def should_backoff(self, error: BaseException, attempt: int) -> int:
        """计算重试退避时间（毫秒），返回 0 表示不重试"""
        ...


# ── Polling ──────────────────────────────────────────────


@runtime_checkable
class PollingProtocol(Protocol):
    """轮询消息接收协议

    渠道通过此协议实现基于轮询的消息接收（替代 Webhook/Websocket）。
    """

    poll_interval_seconds: int

    async def poll_once(self, account: dict) -> list[dict]:
        """执行一次轮询，返回原始事件列表"""
        ...

    async def should_poll(self, account: dict) -> bool:
        """判断当前是否应该执行轮询"""
        ...

    def get_poll_cursor(self, account_id: str) -> str | None:
        """获取当前轮询游标"""
        ...

    def set_poll_cursor(self, account_id: str, cursor: str) -> None:
        """设置轮询游标"""
        ...


# ── Pin ──────────────────────────────────────────────────


@runtime_checkable
class PinProtocol(Protocol):
    """消息置顶协议

    渠道通过此协议支持消息的置顶和取消置顶操作。
    """

    async def pin_message(
        self,
        message_id: str,
        *,
        account_id: str | None = None,
    ) -> bool:
        """置顶指定消息"""
        ...

    async def unpin_message(
        self,
        message_id: str,
        *,
        account_id: str | None = None,
    ) -> bool:
        """取消置顶指定消息"""
        ...

    async def list_pins(
        self,
        chat_id: str,
        *,
        account_id: str | None = None,
    ) -> list[dict]:
        """列出指定聊天的置顶消息"""
        ...


# ── Websocket ────────────────────────────────────────────


@runtime_checkable
class WebsocketProtocol(Protocol):
    """WebSocket 生命周期协议

    渠道通过此协议管理 WebSocket 连接的生命周期。
    """

    async def connect_ws(self, account: dict) -> object:
        """建立 WebSocket 连接，返回连接句柄"""
        ...

    async def disconnect_ws(self) -> None:
        """断开 WebSocket 连接"""
        ...

    async def on_ws_message(self, message: str | bytes) -> None:
        """处理收到的 WebSocket 消息"""
        ...

    @property
    def ws_reconnect_interval_ms(self) -> int:
        """WebSocket 重连间隔（毫秒）"""
        ...

    @property
    def ws_heartbeat_interval_ms(self) -> int:
        """WebSocket 心跳间隔（毫秒）"""
        ...


# ── Protocol Composition Type Aliases ────────────────────
#
# 渠道按能力分层，每类渠道只需标注其实现的能力层级。
# 使用示例:
#     def start_channel(plugin: GatewayPluginProtocol) -> None: ...
#     def deliver_message(plugin: FullMessagingPluginProtocol, msg: str) -> None: ...


type BasePluginProtocol = MetaProtocol & CapabilitiesProtocol
"""最小插件协议：每个渠道插件必须满足 MetaProtocol + CapabilitiesProtocol"""

type ConfigPluginProtocol = BasePluginProtocol & ConfigProtocol
"""可配置插件：支持多账户、配置校验、启用/禁用管理"""

type GatewayPluginProtocol = ConfigPluginProtocol & GatewayProtocol & SecurityProtocol & StatusProtocol & HeartbeatProtocol
"""网关插件：具备网关连接、安全校验、状态探测、心跳保活能力"""

type OutboundPluginProtocol = GatewayPluginProtocol & OutboundProtocol
"""外发插件：在网关基础上具备消息发送（文本/媒体/卡片/投票）能力"""

type SessionPluginProtocol = OutboundPluginProtocol & MessagingProtocol & ThreadingProtocol
"""会话感知插件：具备会话路由、线程管理、回复载荷构建能力"""

type FullMessagingPluginProtocol = (
    SessionPluginProtocol
    & StreamingProtocol
    & AgentPromptProtocol
    & PairingProtocol
    & GroupsProtocol
    & MentionsProtocol
    & LifecycleProtocol
)
"""全功能消息插件：流程式消息 + 会话感知 + 完整生命周期"""

type WebhookPluginProtocol = BasePluginProtocol & WebhookProtocol & InboundHandlerProtocol
"""Webhook 插件：通过 Webhook 接收消息的渠道"""

type PollingPluginProtocol = BasePluginProtocol & PollingProtocol
"""轮询插件：通过定时轮询接收消息的渠道"""

type ApprovalPluginProtocol = BasePluginProtocol & ApprovalProtocol
"""审批插件：支持执行/阅读审批流程的渠道"""