ForcePilot/backend/package/yuxi/channels/adapters/mattermost/adapter.py

from __future__ import annotations

import asyncio
import json
import os
import random
import time
from collections.abc import AsyncIterator
from typing import Any

import httpx
from mattermostdriver import Driver

from yuxi.channels.base import BaseChannelAdapter
from yuxi.channels.capabilities import ChannelCapabilities
from yuxi.channels.exceptions import (
    ChannelAuthenticationError,
    ChannelException,
    ChannelNotConnectedError,
    DeliveryFailedError,
)
from yuxi.channels.infra.circuit_breaker import CircuitBreaker, CircuitBreakerOpenError
from yuxi.channels.meta import ChannelMeta
from yuxi.channels.models import (
    ChannelAccountSnapshot,
    ChannelIdentity,
    ChannelMessage,
    ChannelResponse,
    ChannelStatus,
    ChannelType,
    DeliveryResult,
    EventType,
    HealthStatus,
    MentionsInfo,
    MessageType,
)
from yuxi.channels.registry import register_builtin_adapter
from yuxi.utils.datetime_utils import utc_now_naive
from yuxi.utils.logging_config import logger

from .agent_route import resolve_agent_route
from .approval import ApprovalManager, ApprovalRequest
from .cache import MattermostChannelCache, SentMessageCache
from .config_writes import ConfigWritesManager
from .debounce import InboundDebouncer
from .monitor import MentionGate
from .normalizer import (
    check_bot_mentioned,
    detect_message_type,
    extract_attachments,
    extract_mentions,
    extract_urls,
    parse_channel_json,
    parse_post_json,
)
from .pairing import MattermostPairingManager
from .reply import ReplyManager
from .security import MattermostSecurity
from .send import build_patch_options, build_post_options, chunk_text_for_outbound
from .session import resolve_chat_id, resolve_chat_type

STREAM_UPDATE_MIN_INTERVAL_MS = 500
STREAM_BUFFER_MAX_CHARS = 100_000
STREAM_MIN_CHARS_DEFAULT = 50
STREAM_IDLE_MS_DEFAULT = 1000
BLOCK_STREAM_MIN_CHARS_DEFAULT = 1500
BLOCK_STREAM_IDLE_MS_DEFAULT = 1000
WS_CONNECT_TIMEOUT_S = 30.0
WS_RECONNECT_BASE_DELAY_S = 2.0
WS_RECONNECT_MAX_DELAY_S = 120.0
WS_RECONNECT_MAX_ATTEMPTS = 10
WS_RECONNECT_JITTER = 0.2
WS_PING_INTERVAL_S = 30.0
WS_PONG_TIMEOUT_S = 10.0
SEEN_POSTS_MAX = 2000
SEEN_POSTS_TTL_S = 300
AUTH_401_RETRY_BASE_S = 30.0
AUTH_401_RETRY_MAX_S = 600.0
AUTH_401_RETRY_COUNT = 10
DEBOUNCE_TTL_MS = 1500
DEBOUNCE_MAX_ENTRIES = 3000
WS_EVENT_CAPTURE_MAX = 200


def _parse_driver_scheme_port(server_url: str) -> tuple[str, int]:
    """浠?server_url 鎺ㄦ柇 scheme 鍜?port"""
    from urllib.parse import urlparse

    parsed = urlparse(server_url)
    scheme = parsed.scheme or "https"
    if parsed.port is not None:
        return scheme, parsed.port
    return scheme, 443 if scheme == "https" else 80


def _parse_json_field(data: dict, field: str) -> dict:
    value = data.get(field)
    if isinstance(value, dict):
        return value
    if isinstance(value, str) and value.strip():
        try:
            return json.loads(value)
        except (json.JSONDecodeError, TypeError):
            pass
    return {}


async def probe_mattermost(server_url: str, bot_token: str, timeout_s: float = 30.0) -> dict:
    """独立探测 Mattermost 服务器连通性和 Bot Token 有效性。

    返回状态字典：
    - ok: 连接正常，返回 bot 信息
    - error: 连接失败，返回错误信息
    """
    if not server_url or not bot_token:
        return {"status": "error", "message": "Missing server_url or bot_token"}

    server_url = server_url.rstrip("/")
    scheme, port = _parse_driver_scheme_port(server_url)

    driver = Driver(
        {
            "url": server_url,
            "token": bot_token,
            "scheme": scheme,
            "port": port,
            "verify": True,
            "timeout": int(timeout_s),
        }
    )

    try:
        await driver.login()
        auth_user = driver.users.get_user(user_id="me")
        await driver.logout()
        return {
            "status": "ok",
            "bot_id": auth_user["id"],
            "bot_username": auth_user["username"],
            "server_url": server_url,
        }
    except Exception as e:
        return {"status": "error", "message": str(e)}


@register_builtin_adapter
class MattermostAdapter(BaseChannelAdapter):
    channel_id = "mattermost"
    channel_type = ChannelType.MATTERMOST
    webhook_path = None

    text_chunk_limit = 4000
    supports_markdown = True
    supports_streaming = True
    streaming_modes = ["off", "partial", "block", "progress"]
    max_media_size_mb = 100
    silence_send = False

    capabilities = ChannelCapabilities(
        chat_types=["direct", "group", "channel", "thread"],
        polls=True,
        reactions=True,
        edit=True,
        unsend=True,
        reply=True,
        media=True,
        threads=True,
        block_streaming=True,
        native_commands=True,
        supports_markdown=True,
        supports_streaming=True,
        streaming_modes=["off", "partial", "block", "progress"],
        text_chunk_limit=4000,
        max_media_size_mb=100,
    )
    meta = ChannelMeta(id="mattermost", label="Mattermost")

    def __init__(self, config: dict[str, Any] | None = None):
        super().__init__(config)
        self._status = ChannelStatus.DISCONNECTED
        self._driver: Driver | None = None
        self._ws_task: asyncio.Task | None = None
        self._connected_event = asyncio.Event()
        self._connected_at: float | None = None
        self._bot_user_id: str = ""
        self._bot_username: str = ""
        self._server_url: str = ""
        self._circuit_breaker = CircuitBreaker(failure_threshold=5, recovery_timeout=60)
        self._stream_min_chars = STREAM_MIN_CHARS_DEFAULT
        self._stream_idle_ms = STREAM_IDLE_MS_DEFAULT
        self._block_stream_min_chars = BLOCK_STREAM_MIN_CHARS_DEFAULT
        self._block_stream_idle_ms = BLOCK_STREAM_IDLE_MS_DEFAULT

        if config:
            self.text_chunk_limit = int(config.get("text_chunk_limit", self.text_chunk_limit))
            self.silence_send = bool(config.get("silence_send", False))
            self._stream_min_chars = int(config.get("stream_min_chars", STREAM_MIN_CHARS_DEFAULT))
            self._stream_idle_ms = int(config.get("stream_idle_ms", STREAM_IDLE_MS_DEFAULT))
            coalesce = config.get("blockStreamingCoalesce", {})
            self._block_stream_min_chars = int(coalesce.get("minChars", BLOCK_STREAM_MIN_CHARS_DEFAULT))
            self._block_stream_idle_ms = int(coalesce.get("idleMs", BLOCK_STREAM_IDLE_MS_DEFAULT))
        self._streaming_messages: dict[str, dict[str, Any]] = {}
        self._streaming_lock = asyncio.Lock()
        self._ws_reconnect_attempt = 0
        self._ws_reconnect_task: asyncio.Task | None = None
        self._seen_posts: dict[str, float] = {}
        self._security = MattermostSecurity(config)
        self._mention_gate = MentionGate(config)
        self._reply_manager = ReplyManager(config)
        self._pairing_manager = MattermostPairingManager()
        self._message_queue: asyncio.Queue[ChannelMessage] = asyncio.Queue()
        self._last_error: str | None = None
        self._last_disconnect: dict | None = None
        self._token_source: str = ""
        self._last_pong_at: float = 0.0
        self._ws_heartbeat_task: asyncio.Task | None = None
        self._bot_health_task: asyncio.Task | None = None
        self._auth_401_retry_count = 0
        self._sent_cache = SentMessageCache()
        self._channel_cache = MattermostChannelCache()
        self._inbound_debouncer = InboundDebouncer(
            ttl_ms=DEBOUNCE_TTL_MS,
            max_entries=DEBOUNCE_MAX_ENTRIES,
        )
        self._config_writes = ConfigWritesManager(config)
        self._approval_manager = ApprovalManager(config)
        self._ws_event_capture: list[dict] = []
        self._ws_event_capture_enabled = False
        self._debug_proxy_url = os.getenv("OPENCLAW_DEBUG_PROXY", "")
        self._proxy_applied = False

    def _is_connected(self) -> bool:
        return self._status == ChannelStatus.CONNECTED and self._driver is not None

    async def connect(self) -> None:
        if self._status == ChannelStatus.CONNECTED:
            return

        self._status = ChannelStatus.CONNECTING
        self._connected_event.clear()
        logger.info(f"[Mattermost] Starting channel '{self.config.get('name', self.channel_id)}'")

        server_url = self._resolve_server_url()
        bot_token = self._resolve_bot_token()
        if not server_url or not bot_token:
            raise ChannelAuthenticationError(
                "Mattermost server_url and bot_token must be configured.\n"
                "  server_url: e.g. https://mattermost.example.com\n"
                "  bot_token: MATTERMOST_BOT_TOKEN env or config"
            )

        self._server_url = server_url.rstrip("/")
        scheme, port = _parse_driver_scheme_port(self._server_url)

        driver_kwargs: dict[str, Any] = {
            "url": self._server_url,
            "token": bot_token,
            "scheme": scheme,
            "port": port,
            "verify": True,
            "timeout": 30,
        }

        if self._debug_proxy_url and not self._proxy_applied:
            driver_kwargs["proxy"] = self._debug_proxy_url
            self._proxy_applied = True
            logger.info(f"[Mattermost] Debug proxy enabled: {self._debug_proxy_url}")

        self._driver = Driver(driver_kwargs)

        try:
            await self._driver.login()
        except Exception as e:
            raise ChannelAuthenticationError(f"Mattermost login failed: {e}") from e

        auth_user = self._driver.users.get_user(user_id="me")
        if not auth_user:
            raise ChannelAuthenticationError("Failed to verify Bot Token")
        self._bot_user_id = auth_user["id"]
        self._bot_username = auth_user["username"]

        logger.info(f"[Mattermost] Bot verified: @{self._bot_username} (ID: {self._bot_user_id}), server: {server_url}")

        self._ws_reconnect_attempt = 0
        self._seen_posts.clear()
        await self._start_ws_monitor()
        self._ws_heartbeat_task = asyncio.create_task(self._ws_heartbeat_monitor())

        try:
            await asyncio.wait_for(
                self._connected_event.wait(),
                timeout=WS_CONNECT_TIMEOUT_S,
            )
        except TimeoutError:
            self._status = ChannelStatus.ERROR
            raise ChannelException(
                "Mattermost WebSocket connection timed out",
                retryable=True,
                retry_after_ms=5000,
            )

        self._status = ChannelStatus.CONNECTED
        self._connected_at = time.time()
        logger.info(f"[Mattermost] Channel started, bot: @{self._bot_username}, server: {server_url}")

        self._bot_health_task = asyncio.create_task(self._check_bot_health_periodically())

        slash_cfg = self.config.get("slash_commands", {})
        if slash_cfg.get("auto_register"):
            from .slash_commands import register_slash_commands_across_teams

            asyncio.create_task(
                register_slash_commands_across_teams(
                    self._driver,
                    self._bot_user_id,
                    callback_url=slash_cfg.get("callback_url", ""),
                    auto_register=True,
                )
            )

    async def disconnect(self) -> None:
        if self._status == ChannelStatus.DISCONNECTED:
            return

        logger.info(f"[Mattermost] Stopping channel '{self.config.get('name', self.channel_id)}'")
        self._status = ChannelStatus.DISCONNECTED
        self._connected_event.clear()

        if self._ws_reconnect_task and not self._ws_reconnect_task.done():
            self._ws_reconnect_task.cancel()
            self._ws_reconnect_task = None

        if hasattr(self, "_ws_heartbeat_task") and self._ws_heartbeat_task and not self._ws_heartbeat_task.done():
            self._ws_heartbeat_task.cancel()
            self._ws_heartbeat_task = None

        if self._bot_health_task and not self._bot_health_task.done():
            self._bot_health_task.cancel()
            self._bot_health_task = None

        self._streaming_messages.clear()
        self._seen_posts.clear()
        self._sent_cache.clear()
        self._channel_cache.clear()
        self._inbound_debouncer.clear()
        self._ws_event_capture.clear()
        self._ws_reconnect_attempt = 0

        if self._ws_task and not self._ws_task.done():
            self._ws_task.cancel()
            try:
                await self._ws_task
            except (asyncio.CancelledError, Exception):
                pass
            self._ws_task = None

        if self._driver:
            try:
                await self._driver.logout()
            except Exception:
                pass

        self._driver = None
        self._connected_at = None
        logger.info("[Mattermost] Channel stopped")

    async def send(self, response: ChannelResponse) -> DeliveryResult:
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        text = response.content
        if len(text) <= self.text_chunk_limit:
            return await self._send_single(response)

        chunks = chunk_text_for_outbound(text, self.text_chunk_limit)
        last_id: str | None = None
        for chunk in chunks:
            chunk_response = ChannelResponse(
                identity=response.identity,
                message_type=response.message_type,
                content=chunk,
                attachments=response.attachments if chunk is chunks[-1] else [],
                reply_to_message_id=response.reply_to_message_id,
                metadata=response.metadata,
                timestamp=response.timestamp,
            )
            result = await self._send_single(chunk_response)
            if result.success and result.message_id:
                last_id = result.message_id

        return DeliveryResult(success=True, message_id=last_id)

    async def _send_single(self, response: ChannelResponse) -> DeliveryResult:
        options = build_post_options(response)

        async def _do_send():
            return self._driver.posts.create_post(options=options)

        try:
            result = await self._circuit_breaker.call(_do_send)
            msg_id = result.get("id", "")
            if msg_id:
                self._sent_cache.record(
                    msg_id=msg_id,
                    chat_id=response.identity.channel_chat_id,
                    channel_id=response.identity.channel_chat_id,
                    thread_id=response.reply_to_message_id or "",
                )
            return DeliveryResult(success=True, message_id=msg_id)
        except CircuitBreakerOpenError:
            return DeliveryResult(success=False, error="Circuit breaker open")
        except Exception as e:
            raise DeliveryFailedError(str(e)) from e

    async def send_media(self, chat_id: str, media_type: str, data: Any) -> DeliveryResult:
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        filename = self.config.get("media_filename", "file")
        try:

            async def _do_upload():
                return self._driver.files.upload_file(
                    channel_id=chat_id,
                    files={filename: data},
                )

            result = await self._circuit_breaker.call(_do_upload)
            file_ids = [f["id"] for f in (result.get("file_infos", []) if isinstance(result, dict) else [])]
            return DeliveryResult(success=True, metadata={"file_ids": file_ids})
        except CircuitBreakerOpenError:
            return DeliveryResult(success=False, error="Circuit breaker open")
        except Exception as e:
            logger.warning(f"[Mattermost] Media upload failed, falling back to URL text: {e}")
            url = getattr(data, "url", None) or (data.get("url") if isinstance(data, dict) else None)
            if url:
                return DeliveryResult(
                    success=True,
                    message_id=None,
                    metadata={"file_ids": [], "fallback_url": url},
                )
            raise DeliveryFailedError(str(e)) from e

    async def edit_message(self, chat_id: str, msg_id: str, content: str) -> DeliveryResult:
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        async def _do_edit():
            return self._driver.posts.update_post(
                post_id=msg_id,
                options={"message": content, "id": msg_id},
            )

        try:
            await self._circuit_breaker.call(_do_edit)
            return DeliveryResult(success=True, message_id=msg_id)
        except CircuitBreakerOpenError:
            return DeliveryResult(success=False, error="Circuit breaker open")
        except Exception as e:
            logger.error(f"[Mattermost] Edit message failed for {msg_id}: {e}")
            return DeliveryResult(success=False, error=str(e))

    async def delete_message(self, chat_id: str, msg_id: str) -> DeliveryResult:
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        async def _do_delete():
            return self._driver.posts.delete_post(post_id=msg_id)

        try:
            await self._circuit_breaker.call(_do_delete)
            return DeliveryResult(success=True, message_id=msg_id)
        except CircuitBreakerOpenError:
            return DeliveryResult(success=False, error="Circuit breaker open")
        except Exception as e:
            logger.error(f"[Mattermost] Delete message failed for {msg_id}: {e}")
            return DeliveryResult(success=False, error=str(e))

    async def send_reaction(self, chat_id: str, msg_id: str, emoji: str, remove: bool = False) -> DeliveryResult:
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        if remove:
            return await self._remove_reaction(chat_id, msg_id, emoji)

        async def _do_react():
            return self._driver.reactions.create_reaction(
                options={
                    "user_id": self._bot_user_id,
                    "post_id": msg_id,
                    "emoji_name": emoji.strip(":"),
                }
            )

        try:
            await self._circuit_breaker.call(_do_react)
            return DeliveryResult(success=True, message_id=msg_id)
        except CircuitBreakerOpenError:
            return DeliveryResult(success=False, error="Circuit breaker open")
        except Exception as e:
            logger.error(f"[Mattermost] Send reaction failed for {msg_id} ({emoji}): {e}")
            return DeliveryResult(success=False, error=str(e))

    async def _remove_reaction(self, chat_id: str, msg_id: str, emoji: str) -> DeliveryResult:
        """Remove a reaction: DELETE /users/{bot_id}/posts/{post_id}/reactions/{emoji}"""

        async def _do_remove():
            return self._driver.reactions.remove_reaction(
                user_id=self._bot_user_id,
                post_id=msg_id,
                emoji_name=emoji.strip(":"),
            )

        try:
            await self._circuit_breaker.call(_do_remove)
            return DeliveryResult(success=True, message_id=msg_id)
        except CircuitBreakerOpenError:
            return DeliveryResult(success=False, error="Circuit breaker open")
        except Exception as e:
            logger.error(f"[Mattermost] Remove reaction failed for {msg_id} ({emoji}): {e}")
            return DeliveryResult(success=False, error=str(e))

    async def send_typing(self, chat_id: str) -> DeliveryResult:
        """Send typing indicator: POST /users/me/typing"""
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        async def _do_typing():
            return self._driver.users.create_user_typing(
                options={
                    "channel_id": chat_id,
                }
            )

        try:
            await self._circuit_breaker.call(_do_typing)
            return DeliveryResult(success=True)
        except Exception as e:
            return DeliveryResult(success=False, error=str(e))

    async def send_stream_chunk(self, chat_id: str, msg_id: str, chunk: str, finished: bool) -> DeliveryResult:
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        min_chars = self._stream_min_chars
        idle_ms = self._stream_idle_ms

        now = time.monotonic()
        async with self._streaming_lock:
            entry = self._streaming_messages.get(chat_id, {})
            draft_mode = entry.get("_draft_mode", False)
            is_draft = draft_mode and not finished

            should_send = finished or self._should_flush_stream(entry, chunk, now, min_chars, idle_ms)

            if not should_send:
                entry["_pending"] = (entry.get("_pending", "") + chunk)[:STREAM_BUFFER_MAX_CHARS]
                entry["_pending_chars"] = entry.get("_pending_chars", 0) + len(chunk)
                self._streaming_messages[chat_id] = entry
                return DeliveryResult(success=True, message_id=msg_id)

            pending = entry.pop("_pending", "")
            full_text = pending + chunk if pending else chunk
            entry.pop("_pending_chars", None)

            if is_draft:
                display_text = self._format_stream_display(entry, full_text, finished)
            else:
                display_text = self._format_stream_display(entry, full_text, finished)

            entry["_last_update"] = now
            entry["_last_flush_chars"] = len(full_text)

            if self._can_finalize_in_place(entry, finished):
                display_text = full_text

            if not msg_id:
                resp = ChannelResponse(
                    identity=ChannelIdentity(
                        channel_id=self.channel_id,
                        channel_type=self.channel_type,
                        channel_user_id="",
                        channel_chat_id=chat_id,
                    ),
                    content=display_text,
                    metadata={"streaming": True, "finished": finished},
                )
                result = await self.send(resp)
                if result.success and result.message_id:
                    self._streaming_messages[chat_id] = {
                        "_last_update": now,
                        "msg_id": result.message_id,
                        "_draft_mode": draft_mode,
                    }
                return result

            try:
                self._driver.posts.patch_post(
                    post_id=msg_id,
                    options=build_patch_options(display_text),
                )
            except Exception as e:
                if hasattr(e, "response") and getattr(e.response, "status_code", None) == 401:
                    logger.warning(f"[Mattermost] Stream patch got 401 for {msg_id}, triggering backoff")
                    await self._handle_401_backoff()
                logger.error(f"[Mattermost] Stream patch failed for {msg_id}: {e}")
                return DeliveryResult(success=False, error=str(e))

            if finished:
                if not is_draft:
                    self._streaming_messages.pop(chat_id, None)
                else:
                    entry.pop("_pending", None)
                    entry["_last_update"] = now
                    entry["_draft_finalized"] = True
                    self._streaming_messages[chat_id] = entry
            else:
                self._streaming_messages[chat_id] = entry
            return DeliveryResult(success=True, message_id=msg_id)

    async def send_stream_chunk_with_status(
        self,
        chat_id: str,
        msg_id: str,
        chunk: str,
        finished: bool,
        tool_name: str = "",
        reasoning: bool = False,
        draft_preview: bool = False,
    ) -> DeliveryResult:
        """带状态提示的流式输出。

        支持 Tool Status 预览和 Reasoning 预览。
        """
        if not self._is_connected():
            return DeliveryResult(success=False, error="Not connected")

        async with self._streaming_lock:
            entry = self._streaming_messages.get(chat_id, {})
            entry["_tool_name"] = tool_name
            entry["_reasoning"] = reasoning
            entry["_draft_mode"] = draft_preview or reasoning
            self._streaming_messages[chat_id] = entry

        return await self.send_stream_chunk(chat_id, msg_id, chunk, finished)

    async def _create_dm_channel_with_retry(self, user_id: str, max_retries: int = 3) -> str | None:
        retry_delay_s = float(self.config.get("dmChannelRetry", {}).get("baseDelayMs", 1000) / 1000.0)
        max_retries_config = int(self.config.get("dmChannelRetry", {}).get("maxRetries", max_retries))
        retries = min(max_retries, max_retries_config)

        for attempt in range(retries):
            try:
                channel = self._driver.channels.create_direct_channel(options=[self._bot_user_id, user_id])
                channel_id = channel.get("id", "")
                if channel_id:
                    return channel_id
            except Exception as e:
                logger.warning(f"[Mattermost] DM channel creation attempt {attempt + 1}/{retries} failed: {e}")
            if attempt < retries - 1:
                await asyncio.sleep(retry_delay_s * (2**attempt))
        return None

    def _apply_response_prefix(self, text: str) -> str:
        prefix = self.config.get("responsePrefix", "")
        if prefix and text:
            return prefix + text
        return text

    @staticmethod
    def _format_stream_display(entry: dict, text: str, finished: bool) -> str:
        """格式化流式显示文本，支持状态提示前缀。"""
        tool_name = entry.get("_tool_name", "")
        reasoning = entry.get("_reasoning", False)

        if finished and (tool_name or reasoning):
            return text

        prefix = ""
        if reasoning:
            prefix = "🤔 Thinking…\n\n"
        elif tool_name:
            prefix = f"🔧 Running {tool_name}…\n\n"

        if prefix and text:
            return prefix + text
        return text

    def _should_flush_stream(
        self,
        entry: dict,
        chunk: str,
        now: float,
        min_chars: int,
        idle_ms: int,
    ) -> bool:
        """判断是否需要刷新流式缓冲。

        刷新条件：
        1. 距上次刷新超过 STREAM_UPDATE_MIN_INTERVAL_MS
        2. 待刷新字符数超过 min_chars
        3. 距上次活动超过 idle_ms（缓冲有内容时）
        """
        last_update = entry.get("_last_update", 0)
        if last_update == 0:
            return True

        elapsed_ms = (now - last_update) * 1000
        if elapsed_ms >= STREAM_UPDATE_MIN_INTERVAL_MS:
            return True

        pending_chars = entry.get("_pending_chars", 0) + len(chunk)
        if pending_chars >= min_chars:
            return True

        if pending_chars > 0 and elapsed_ms >= idle_ms:
            return True

        return False

    @staticmethod
    def _can_finalize_in_place(entry: dict, finished: bool) -> bool:
        """判断是否可以在当前位置原地最终化流式消息。

        判定条件：
        1. 必须是最终块 (finished=True)
        2. 处于 draft 模式且已被标记为 draft_finalized
        3. 内容的 replyToId 未发生变更
        """
        if not finished:
            return False
        is_draft = entry.get("_draft_mode", False)
        is_finalized = entry.get("_draft_finalized", False)
        has_error = entry.get("_error", False)
        has_media = entry.get("_has_media", False)

        if has_error and not is_draft:
            return True

        if has_media:
            return False

        return is_draft and is_finalized

    def _record_ws_event(self, event_name: str, data: dict) -> None:
        """记录 WebSocket 事件帧用于调试。"""
        if not self._ws_event_capture_enabled:
            return
        entry = {
            "event": event_name,
            "at": time.time(),
            "data_keys": list(data.keys()) if isinstance(data, dict) else None,
        }
        self._ws_event_capture.append(entry)
        if len(self._ws_event_capture) > WS_EVENT_CAPTURE_MAX:
            self._ws_event_capture = self._ws_event_capture[-WS_EVENT_CAPTURE_MAX:]

    def enable_ws_event_capture(self) -> None:
        self._ws_event_capture_enabled = True

    def disable_ws_event_capture(self) -> None:
        self._ws_event_capture_enabled = False

    def get_ws_event_capture(self) -> list[dict]:
        return list(self._ws_event_capture)

    async def receive(self) -> AsyncIterator[ChannelMessage]:
        while True:
            try:
                msg = await self._message_queue.get()
                yield msg
            except asyncio.CancelledError:
                break

    def normalize_inbound(self, raw: Any) -> ChannelMessage:
        event = raw.get("event", "")
        data = raw.get("data", {})
        broadcast = raw.get("broadcast", {})

        if event in ("reaction_added", "reaction_removed"):
            return self._normalize_reaction(event, data, broadcast)

        post_data = parse_post_json(data)
        channel_data = parse_channel_json(data)

        user_id = post_data.get("user_id") or ""
        message_text = post_data.get("message") or data.get("message") or ""
        msg_id = post_data.get("id") or ""

        bot_mentioned = check_bot_mentioned(message_text, self._bot_username)
        chat_type = resolve_chat_type(post_data, channel_data)
        chat_id = resolve_chat_id(post_data, channel_data)

        event_type = EventType.MESSAGE_RECEIVED
        if event == "post_edited":
            event_type = EventType.MESSAGE_UPDATED
        elif event == "post_deleted":
            event_type = EventType.MESSAGE_DELETED

        message_type = detect_message_type(post_data)
        if message_type == MessageType.TEXT and message_text.strip().startswith("/"):
            message_type = MessageType.COMMAND

        return ChannelMessage(
            identity=ChannelIdentity(
                channel_id=self.channel_id,
                channel_type=self.channel_type,
                channel_user_id=user_id,
                channel_chat_id=chat_id,
                channel_message_id=msg_id,
            ),
            event_type=event_type,
            message_type=message_type,
            chat_type=chat_type,
            content=message_text,
            attachments=extract_attachments(post_data),
            mentions=MentionsInfo(
                mentioned_user_ids=extract_mentions(message_text),
                is_bot_mentioned=bot_mentioned,
            ),
            extracted_urls=extract_urls(message_text),
            reply_to_message_id=post_data.get("root_id") or None,
            metadata={
                "root_id": post_data.get("root_id"),
                "channel_name": channel_data.get("display_name") or channel_data.get("name"),
                "team_id": broadcast.get("team_id") or "",
            },
        )

    def _normalize_reaction(self, event: str, data: dict, broadcast: dict) -> ChannelMessage:
        reaction_data = _parse_json_field(data, "reaction")
        user_id = reaction_data.get("user_id") or ""
        post_id = reaction_data.get("post_id") or ""
        emoji_name = reaction_data.get("emoji_name") or ""
        channel_id = broadcast.get("channel_id") or ""

        return ChannelMessage(
            identity=ChannelIdentity(
                channel_id=self.channel_id,
                channel_type=self.channel_type,
                channel_user_id=user_id,
                channel_chat_id=f"channel_{channel_id}",
                channel_message_id=post_id,
            ),
            event_type=EventType.SYSTEM_EVENT,
            message_type=MessageType.TEXT,
            content=f":{emoji_name}:",
            metadata={
                "reaction_event": event,
                "emoji_name": emoji_name,
                "post_id": post_id,
                "channel_id": channel_id,
                "team_id": broadcast.get("team_id") or "",
            },
        )

    def format_outbound(self, response: ChannelResponse) -> dict[str, Any]:
        return build_post_options(response)

    def resolve_debug_proxy(self) -> str:
        """返回 Debug Proxy URL（如果配置了 OPENCLAW_DEBUG_PROXY 环境变量）。"""
        return self._debug_proxy_url

    async def _check_bot_health_periodically(self, interval_s: float = 300.0) -> None:
        """定期检查 Bot 是否被禁用/重新启用。

        通过 getBotUpdateAt 检查 update_at 变更，
        检测到变更后触发 401 退避重新认证。
        """
        last_update_at: int = 0
        while self._status == ChannelStatus.CONNECTED:
            await asyncio.sleep(interval_s)
            if self._status != ChannelStatus.CONNECTED or not self._driver:
                break

            try:
                bot_user = self._driver.users.get_user(user_id=self._bot_user_id)
                current_update_at = bot_user.get("update_at", 0)

                if last_update_at == 0:
                    last_update_at = current_update_at
                    continue

                if current_update_at != last_update_at:
                    logger.info(
                        f"[Mattermost] Bot update_at changed: {last_update_at} → {current_update_at}, checking auth"
                    )
                    last_update_at = current_update_at
                    alive = await self._driver.client.get("/api/v4/users/me")
                    if hasattr(alive, "status_code") and alive.status_code == 401:
                        logger.warning("[Mattermost] Bot appears disabled, triggering 401 backoff")
                        await self._handle_401_backoff()
            except Exception as e:
                logger.debug(f"[Mattermost] Bot health check error: {e}")
                if hasattr(e, "response") and getattr(e.response, "status_code", None) == 401:
                    await self._handle_401_backoff()

    async def health_check(self) -> HealthStatus:
        if not self._is_connected():
            return HealthStatus(
                status="unhealthy",
                last_error="Not connected",
            )

        try:
            start = time.monotonic()
            await asyncio.get_event_loop().run_in_executor(None, self._driver.system.ping)
            latency_ms = (time.monotonic() - start) * 1000

            return HealthStatus(
                status="healthy",
                latency_ms=latency_ms,
                last_connected_at=utc_now_naive(),
                metadata={
                    "bot_id": self._bot_user_id,
                    "bot_username": self._bot_username,
                    "server_url": self._server_url,
                    "bot_token_source": self._token_source,
                    "last_disconnect": self._last_disconnect,
                    "last_error": self._last_error,
                    "reconnect_attempts": self._ws_reconnect_attempt,
                },
            )
        except Exception as e:
            return HealthStatus(status="unhealthy", last_error=str(e))

    async def get_user_info(self, channel_user_id: str) -> dict[str, Any]:
        if not self._is_connected():
            return {}
        try:
            return self._driver.users.get_user(user_id=channel_user_id)
        except Exception:
            return {}

    async def download_media(self, file_id: str) -> bytes:
        if not self._is_connected():
            raise ChannelNotConnectedError()
        try:
            link_data = self._driver.files.get_file_link(file_id=file_id)
            url = link_data.get("link", "")
            if not url:
                raise ChannelException("No file link returned")

            async with httpx.AsyncClient() as client:
                resp = await client.get(url, timeout=30)
                resp.raise_for_status()
                return resp.content
        except Exception as e:
            raise ChannelException(f"Failed to download media: {e}") from e

    async def pre_connect(self) -> dict:
        server_url = self._resolve_server_url()
        bot_token = self._resolve_bot_token()
        if not server_url or not bot_token:
            return {"status": "error", "message": "Missing server_url or bot_token"}

        scheme, port = _parse_driver_scheme_port(server_url.rstrip("/"))

        driver = Driver(
            {
                "url": server_url.rstrip("/"),
                "token": bot_token,
                "scheme": scheme,
                "port": port,
                "verify": True,
                "timeout": 30,
            }
        )

        try:
            await driver.login()
            auth_user = driver.users.get_user(user_id="me")
            await driver.logout()
            return {
                "status": "ok",
                "bot_id": auth_user["id"],
                "bot_username": auth_user["username"],
                "server_url": server_url,
            }
        except Exception as e:
            return {"status": "error", "message": str(e)}

    async def _refresh_token_if_needed(self) -> bool:
        return True

    async def _handle_401_backoff(self) -> bool:
        """处理 401 错误：指数退避重试认证。

        Bot 禁用后重新启用时，通过此机制自动恢复连接。
        返回 True 表示重连成功。
        """
        self._auth_401_retry_count += 1
        if self._auth_401_retry_count > AUTH_401_RETRY_COUNT:
            logger.error(f"[Mattermost] 401 backoff max retries ({AUTH_401_RETRY_COUNT}) reached, giving up")
            self._status = ChannelStatus.ERROR
            self._last_error = "401 backoff max retries reached"
            return False

        delay = min(
            AUTH_401_RETRY_BASE_S * (2 ** (self._auth_401_retry_count - 1)),
            AUTH_401_RETRY_MAX_S,
        )
        jitter = delay * 0.2 * (2 * random.random() - 1)
        delay = max(1.0, delay + jitter)

        logger.info(
            f"[Mattermost] 401 backoff: retrying in {delay:.0f}s "
            f"(attempt {self._auth_401_retry_count}/{AUTH_401_RETRY_COUNT})"
        )
        await asyncio.sleep(delay)

        try:
            await self._driver.login()
            self._auth_401_retry_count = 0
            logger.info("[Mattermost] 401 backoff: re-authenticated successfully")
            return True
        except Exception as e:
            logger.warning(f"[Mattermost] 401 backoff: re-login failed: {e}")
            return await self._handle_401_backoff()

    def _resolve_server_url(self) -> str:
        url = self.config.get("server_url", "") or os.getenv("MATTERMOST_SERVER_URL", "")
        if "MATTERMOST_URL" not in os.environ and not self.config.get("server_url"):
            url = url or os.getenv("MATTERMOST_URL", "")
        return url

    def _resolve_bot_token(self) -> str:
        token = self.config.get("bot_token", "")
        if token:
            self._token_source = "config"
            return token
        token = os.getenv("MATTERMOST_BOT_TOKEN", "")
        if token:
            self._token_source = "env"
            return token
        self._token_source = "none"
        return ""

    @staticmethod
    def _parse_ws_post(data: dict) -> dict | None:
        post_str = data.get("post", "")
        if isinstance(post_str, str):
            try:
                return json.loads(post_str)
            except json.JSONDecodeError:
                return None
        return post_str if isinstance(post_str, dict) else None

    def _should_ignore_post(self, post: dict) -> bool:
        if post.get("user_id") == self._bot_user_id:
            return True
        if post.get("type") in ("system_add_remove", "system_join_leave"):
            return True
        return False

    def _dedup_check(self, post_id: str) -> bool:
        if not post_id:
            return False
        now = time.monotonic()
        if post_id in self._seen_posts:
            if now - self._seen_posts[post_id] < SEEN_POSTS_TTL_S:
                return True
        self._seen_posts[post_id] = now
        if len(self._seen_posts) > SEEN_POSTS_MAX:
            cutoff = now - SEEN_POSTS_TTL_S
            self._seen_posts = {k: v for k, v in self._seen_posts.items() if v > cutoff}
        return False

    async def _handle_ws_message(self, event_name: str, data: dict) -> None:
        self._record_ws_event(event_name, data)

        post = self._parse_ws_post(data)
        if post is None or self._should_ignore_post(post):
            return

        if event_name in ("posted", "post_edited") and self._dedup_check(post.get("id", "")):
            return

        channel_id = post.get("channel_id", "")
        thread_id = post.get("root_id", "")
        post_text = post.get("message", "")

        if not self._inbound_debouncer.should_process(channel_id, thread_id, post_text):
            return

        user_id = post.get("user_id", "")
        channel_data = _parse_json_field(data, "channel")
        chat_type_raw = channel_data.get("type", "")

        if chat_type_raw == "D":
            security_result = self._security.check_dm(user_id)
        else:
            security_result = self._security.check_group(user_id)

        if not security_result.allowed:
            logger.info(f"[Mattermost] Blocked message from {user_id}: {security_result.reason}")
            return

        bot_mentioned = check_bot_mentioned(post_text, self._bot_username)
        chat_type = resolve_chat_type(
            {"root_id": post.get("root_id"), "user_id": user_id, "channel_id": post.get("channel_id")},
            channel_data,
        )
        mention_result = self._mention_gate.check(
            str(chat_type.value) if hasattr(chat_type, "value") else str(chat_type),
            post_text,
            bot_mentioned,
        )
        if not mention_result.should_respond:
            logger.debug(f"[Mattermost] Mention gate blocked: {mention_result.reason}")
            return

        try:
            msg = self.normalize_inbound(
                {
                    "event": event_name,
                    "data": data,
                    "broadcast": data.get("broadcast", {}),
                }
            )
            await self._handle_message(msg)
            self._message_queue.put_nowait(msg)
        except Exception as e:
            logger.error(f"[Mattermost] Error handling {event_name} event: {e}")

    async def _handle_reaction_event(self, event_name: str, data: dict) -> None:
        self._record_ws_event(event_name, data)

        post = self._parse_ws_post(data)
        if post is None or self._should_ignore_post(post):
            return

        try:
            msg = self.normalize_inbound(
                {
                    "event": event_name,
                    "data": data,
                    "broadcast": data.get("broadcast", {}),
                }
            )
            await self._handle_message(msg)
            self._message_queue.put_nowait(msg)
        except Exception as e:
            logger.error(f"[Mattermost] Error handling {event_name} event: {e}")

    async def _start_ws_monitor(self) -> None:
        if not self._driver:
            return

        async def on_posted(data: dict):
            await self._handle_ws_message("posted", data)

        async def on_post_edited(data: dict):
            await self._handle_ws_message("post_edited", data)

        async def on_post_deleted(data: dict):
            await self._handle_ws_message("post_deleted", data)

        async def on_reaction_added(data: dict):
            await self._handle_reaction_event("reaction_added", data)

        async def on_reaction_removed(data: dict):
            await self._handle_reaction_event("reaction_removed", data)

        async def on_error(data: dict):
            logger.error(f"[Mattermost] WebSocket error: {data}")

        async def on_close(data: dict):
            logger.warning(f"[Mattermost] WebSocket closed: {data}")
            self._last_disconnect = {
                "reason": data.get("reason", "unknown"),
                "code": data.get("code", 0),
                "at": time.time(),
            }
            if self._status == ChannelStatus.CONNECTED and (
                self._ws_reconnect_task is None or self._ws_reconnect_task.done()
            ):
                self._ws_reconnect_task = asyncio.create_task(self._ws_reconnect())

        async def on_connected(data: dict):
            logger.info("[Mattermost] WebSocket connected")
            self._ws_reconnect_attempt = 0
            self._last_pong_at = time.monotonic()
            self._connected_event.set()

        self._ws_task = asyncio.create_task(
            self._driver.init_websocket(
                event_handler={
                    "posted": on_posted,
                    "post_edited": on_post_edited,
                    "post_deleted": on_post_deleted,
                    "reaction_added": on_reaction_added,
                    "reaction_removed": on_reaction_removed,
                    "error": on_error,
                    "close": on_close,
                    "hello": on_connected,
                }
            )
        )

    async def _ws_heartbeat_monitor(self) -> None:
        """独立 WebSocket 心跳检测：每隔 PING_INTERVAL_S 检查最后 pong 时间。

        如果超过 PONG_TIMEOUT_S 未收到 pong，触发重连。
        """
        while self._status == ChannelStatus.CONNECTED:
            await asyncio.sleep(WS_PING_INTERVAL_S)
            if self._status != ChannelStatus.CONNECTED:
                break

            elapsed = time.monotonic() - self._last_pong_at
            if elapsed > WS_PING_INTERVAL_S + WS_PONG_TIMEOUT_S:
                logger.warning(f"[Mattermost] WS heartbeat timeout: last pong {elapsed:.0f}s ago, reconnecting")
                self._last_error = f"WS heartbeat timeout after {elapsed:.0f}s"
                if self._ws_reconnect_task is None or self._ws_reconnect_task.done():
                    self._ws_reconnect_task = asyncio.create_task(self._ws_reconnect())

    async def _ws_reconnect(self) -> None:
        if self._status != ChannelStatus.CONNECTED:
            self._ws_reconnect_task = None
            return

        self._ws_reconnect_attempt += 1
        if self._ws_reconnect_attempt > WS_RECONNECT_MAX_ATTEMPTS:
            logger.error(f"[Mattermost] WS reconnect max attempts ({WS_RECONNECT_MAX_ATTEMPTS}) reached, giving up")
            self._status = ChannelStatus.ERROR
            self._ws_reconnect_task = None
            return

        delay = min(WS_RECONNECT_BASE_DELAY_S * (2 ** (self._ws_reconnect_attempt - 1)), WS_RECONNECT_MAX_DELAY_S)
        jitter = delay * WS_RECONNECT_JITTER * (2 * random.random() - 1)
        delay = max(0.5, delay + jitter)
        logger.info(
            f"[Mattermost] WebSocket reconnecting in {delay:.1f}s "
            f"(attempt {self._ws_reconnect_attempt}/{WS_RECONNECT_MAX_ATTEMPTS})"
        )

        await asyncio.sleep(delay)
        self._connected_event.clear()

        try:
            await self._start_ws_monitor()
            await asyncio.wait_for(self._connected_event.wait(), timeout=WS_CONNECT_TIMEOUT_S)
            logger.info("[Mattermost] WebSocket reconnected successfully")
            self._ws_reconnect_task = None
        except Exception as e:
            logger.error(f"[Mattermost] WebSocket reconnect failed: {e}")
            if self._status == ChannelStatus.CONNECTED:
                self._ws_reconnect_task = asyncio.create_task(self._ws_reconnect())
            else:
                self._ws_reconnect_task = None

    # ─── ChannelMessageActionProtocol ───────────────────────────────────────

    def supports_action(self, action: str) -> bool:
        return action in ("send", "react", "edit", "delete")

    def resolve_execution_mode(self, action: str) -> str:
        return "queue"

    async def handle_action(self, ctx) -> DeliveryResult:
        action = ctx.action
        if action == "react":
            return await self.send_reaction(ctx.chat_id, ctx.msg_id, ctx.get("emoji", ""))
        if action == "edit":
            return await self.edit_message(ctx.chat_id, ctx.msg_id, ctx.get("content", ""))
        if action == "delete":
            return await self.delete_message(ctx.chat_id, ctx.msg_id)
        return DeliveryResult(success=False, error=f"Unknown action: {action}")

    def extract_target_from_args(self, args: dict) -> dict | None:
        return {"chat_id": args.get("chat_id")}

    async def handle_poll_vote(self, poll_id: str, vote: str, user_id: str) -> dict:
        """处理投票交互。

        使用 PollResultTracker 跟踪投票结果并返回摘要。
        """
        if not self._is_connected():
            return {"error": "Not connected"}

        from .poll_handler import get_poll_tracker

        tracker = get_poll_tracker()
        recorded = tracker.record_vote(poll_id, vote, user_id)

        if not recorded:
            return {"status": "ok", "warning": "Poll not found or already ended"}

        results = tracker.get_results(poll_id)
        summary = tracker.format_results_message(poll_id) if results else ""

        try:
            self._driver.reactions.create_reaction(
                options={
                    "user_id": self._bot_user_id,
                    "post_id": poll_id,
                    "emoji_name": vote,
                }
            )
        except Exception as e:
            logger.error(f"[Mattermost] Poll vote reaction failed for {poll_id}: {e}")

        return {
            "status": "ok",
            "poll_id": poll_id,
            "vote": vote,
            "user_id": user_id,
            "summary": summary,
        }

    def describe_message_tool(self) -> dict:
        from .agent_tools import describe_mattermost_message_tool

        return describe_mattermost_message_tool()

    # ─── ChannelConfigProtocol ──────────────────────────────────────────────

    def resolve_account(self, account_id: str) -> dict | None:
        from .accounts import MultiAccountConfig

        ma = MultiAccountConfig.from_config(self.config)
        account = ma.resolve_account(account_id)
        if account is None:
            return None
        return {
            "account_id": account.account_id,
            "server_url": account.server_url,
            "enabled": account.enabled,
            "nick": account.nick,
        }

    def is_enabled(self) -> bool:
        from .accounts import MultiAccountConfig

        ma = MultiAccountConfig.from_config(self.config)
        return len(ma.list_configured_accounts()) > 0

    def is_configured(self) -> bool:
        server_url = self._resolve_server_url()
        bot_token = self._resolve_bot_token()
        return bool(server_url and bot_token)

    def list_account_ids(self) -> list[str]:
        from .accounts import MultiAccountConfig

        ma = MultiAccountConfig.from_config(self.config)
        return ma.list_account_ids()

    def default_account_id(self) -> str:
        from .accounts import MultiAccountConfig

        ma = MultiAccountConfig.from_config(self.config)
        return ma.default_account_id

    def disabled_reason(self) -> str:
        if self._status == ChannelStatus.DISABLED:
            return self._last_error or "Channel is disabled by configuration"
        return ""

    def unconfigured_reason(self) -> str:
        if not self.is_configured():
            return "Missing server_url or bot_token"
        return ""

    def describe_account(self) -> dict:
        return {
            "channel_id": self.channel_id,
            "channel_type": str(self.channel_type.value),
            "bot_username": self._bot_username,
            "server_url": self._server_url,
            "token_source": self._token_source,
            "dm_policy": self._security.dm_policy,
            "group_policy": self._security.group_policy,
        }

    def resolve_allow_from(self) -> list[str]:
        return list(self._security._config.allow_from)

    def has_configured_state(self) -> bool:
        return self.is_configured()

    def write_config(self, key: str, value: Any) -> bool:
        return self._config_writes.write_config(key, value)

    def add_to_allowlist(self, target: str, list_type: str = "dm") -> bool:
        return self._config_writes.add_to_allowlist(target, list_type)

    def remove_from_allowlist(self, target: str, list_type: str = "dm") -> bool:
        return self._config_writes.remove_from_allowlist(target, list_type)

    def get_writeable_config(self) -> dict[str, Any]:
        return self._config_writes.get_config()

    def resolve_agent_route(
        self,
        channel_id: str,
        team_id: str | None = None,
        user_id: str | None = None,
    ) -> dict[str, Any]:
        return resolve_agent_route(self.config, channel_id, team_id, user_id)

    def requires_approval(self, action: str) -> bool:
        return self._approval_manager.requires_approval(action)

    def create_approval_request(
        self,
        action: str,
        description: str,
        params: dict[str, Any],
        from_user_id: str = "",
        from_channel_id: str = "",
    ) -> ApprovalRequest:
        return self._approval_manager.create_request(action, description, params, from_user_id, from_channel_id)

    def process_approval(self, request_id: str, approved: bool) -> bool:
        if approved:
            return self._approval_manager.approve(request_id)
        return self._approval_manager.deny(request_id)

    def get_approval_request(self, request_id: str) -> ApprovalRequest | None:
        return self._approval_manager.get_request(request_id)

    # ─── ChannelDirectoryProtocol ───────────────────────────────────────────

    async def self_info(self) -> dict:
        return {
            "user_id": self._bot_user_id,
            "username": self._bot_username,
            "server_url": self._server_url,
        }

    async def list_peers(self, cached: bool = True) -> list[dict]:
        if not self._is_connected():
            return []
        try:
            teams = self._driver.teams.get_user_teams(user_id=self._bot_user_id)
            peers: dict[str, dict] = {}
            for team in teams:
                team_id = team.get("id", "")
                try:
                    users = self._driver.users.get_users(params={"in_team": team_id, "per_page": 200})
                    for u in users:
                        uid = u.get("id", "")
                        if uid and uid not in peers:
                            peers[uid] = {
                                "user_id": uid,
                                "username": u.get("username", ""),
                                "nickname": u.get("nickname", ""),
                                "email": u.get("email", ""),
                                "first_name": u.get("first_name", ""),
                                "last_name": u.get("last_name", ""),
                            }
                except Exception:
                    pass
            return list(peers.values())
        except Exception:
            return []

    async def list_groups(self, cached: bool = True) -> list[dict]:
        if not self._is_connected():
            return []
        try:
            teams = self._driver.teams.get_user_teams(user_id=self._bot_user_id)
            groups: dict[str, dict] = {}
            for team in teams:
                team_id = team.get("id", "")
                try:
                    channels = self._driver.channels.get_channels_for_user(
                        user_id=self._bot_user_id,
                        team_id=team_id,
                    )
                    for ch in channels:
                        cid = ch.get("id", "")
                        if cid and cid not in groups:
                            groups[cid] = {
                                "channel_id": cid,
                                "name": ch.get("name", ""),
                                "display_name": ch.get("display_name", ""),
                                "group_type": ch.get("type", "O"),
                                "purpose": ch.get("purpose", ""),
                            }
                except Exception:
                    pass
            return list(groups.values())
        except Exception:
            return []

    async def list_group_members(self, group_id: str) -> list[dict]:
        if not self._is_connected():
            return []
        try:
            members = self._driver.channels.get_channel_members(
                channel_id=group_id,
                params={"per_page": 200},
            )
            result = []
            for m in members:
                uid = m.get("user_id", "")
                if uid:
                    try:
                        user_info = self._driver.users.get_user(user_id=uid)
                        result.append(
                            {
                                "user_id": uid,
                                "username": user_info.get("username", ""),
                            }
                        )
                    except Exception:
                        result.append({"user_id": uid, "username": ""})
            return result
        except Exception:
            return []

    # ─── ChannelMessagingProtocol ───────────────────────────────────────────

    def normalize_target(self, raw: Any) -> str:
        from .target_resolution import parse_target

        return parse_target(raw)

    def resolve_inbound_conversation(self, from_: str, to: str, thread_id: str) -> dict:
        return {
            "from": from_,
            "to": to,
            "thread_id": thread_id,
            "chat_id": to or from_,
        }

    def resolve_delivery_target(self, conversation_id: str) -> dict:
        """解析投递目标 — 支持父/子会话路由。

        如果 conversation_id 包含线程信息（parentConversationId），
        则路由到父频道的线程回复。
        """
        result: dict[str, Any] = {"chat_id": conversation_id}

        parent_conv_id = self.config.get("parentConversationId", "") if self.config else ""
        if parent_conv_id and conversation_id.startswith("thread_"):
            result["chat_id"] = parent_conv_id
            result["thread_id"] = conversation_id

        return result

    def infer_target_chat_type(self, to: str) -> str:
        if to.startswith("user:"):
            return "direct"
        if to.startswith("channel:"):
            return "channel"
        if len(to) == 26:
            return "channel"
        return "direct"

    def parse_explicit_target(self, raw: str) -> dict:
        from .target_resolution import parse_target

        target = parse_target(raw)
        return {"chat_id": target, "raw": raw} if target else {}

    def transform_reply_payload(self, payload: dict) -> dict:
        return payload

    def resolve_outbound_session_route(self, target: dict) -> dict:
        return {"chat_id": target.get("chat_id", ""), "chat_type": target.get("chat_type", "direct")}

    # ─── ChannelSetupProtocol ───────────────────────────────────────────────

    async def apply_account_config(self, config: dict) -> None:
        self.config.update(config)

    async def validate_account_input(self, input_: dict) -> list[str]:
        from .config_schema import validate_config_schema

        return validate_config_schema(input_)

    async def after_config_written(self, config: dict) -> None:
        pass

    # ─── ChannelStatusProtocol ──────────────────────────────────────────────

    def snapshot(self) -> dict[str, Any]:
        return {
            "channel_id": self.channel_id,
            "status": str(self._status.value) if hasattr(self._status, "value") else str(self._status),
            "connected": self._is_connected(),
            "bot_username": self._bot_username,
            "bot_id": self._bot_user_id,
            "server_url": self._server_url,
            "token_source": self._token_source,
            "last_error": self._last_error,
            "last_disconnect": self._last_disconnect,
            "reconnect_attempts": self._ws_reconnect_attempt,
            "dm_policy": self._security.dm_policy,
            "group_policy": self._security.group_policy,
            "allow_from_count": self._security.allow_from_count,
            "sent_cache_size": self._sent_cache.size(),
            "debouncer_entries": len(self._inbound_debouncer._entries),
            "ws_events_captured": len(self._ws_event_capture),
            "debug_proxy_enabled": bool(self._debug_proxy_url),
            "approval_enabled": self._approval_manager.enabled,
            "config_writes_enabled": self._config_writes.is_config_writes_enabled(),
        }

    @property
    def status(self) -> str:
        return str(self._status.value) if hasattr(self._status, "value") else str(self._status)

    async def probe_account(self, account: dict, timeout_ms: int) -> dict:
        server_url = account.get("server_url", self._server_url)
        bot_token = account.get("bot_token", self._resolve_bot_token())
        if not server_url or not bot_token:
            return {"status": "error", "message": "Missing server_url or bot_token"}

        from .accounts import MattermostAccount

        acct = MattermostAccount.from_config_entry(account.get("account_id", "default"), account)
        return {
            "server_url": server_url,
            "configured": acct.configured,
            "enabled": acct.enabled,
        }

    async def build_account_snapshot(self, account: dict, probe: dict) -> ChannelAccountSnapshot:
        return ChannelAccountSnapshot(
            account_id=account.get("account_id", "default"),
            name=account.get("name", ""),
            configured=bool(account.get("server_url") and account.get("bot_token")),
            enabled=account.get("enabled", True),
            status_state="configured" if probe else "not-configured",
            bot_token_source=self._token_source,
            server_url=account.get("server_url", ""),
            dm_policy=account.get("dm_policy", "open"),
            group_policy=account.get("group_policy", "open"),
        )

    def build_channel_summary(self, account: dict, snapshot: dict) -> dict:
        return {
            "channel": "mattermost",
            "account_id": account.get("account_id", "default"),
            "connected": self._is_connected(),
            "bot_username": self._bot_username,
            "server_url": self._server_url,
        }

    async def audit_account(self, account: dict, timeout_ms: int) -> dict:
        return {
            "server_url": self._server_url,
            "token_source": self._token_source,
            "dm_policy": self._security.dm_policy,
            "group_policy": self._security.group_policy,
        }

    def resolve_account_state(self, configured: bool, enabled: bool) -> str:
        if not configured:
            return "not-configured"
        if not enabled:
            return "disabled"
        return "ready"

    def collect_status_issues(self, accounts: list) -> list[str]:
        issues = []
        if not accounts:
            issues.append("No accounts configured")
        if not self._is_connected():
            issues.append(f"Not connected (status: {self._status})")
        if self._last_error:
            issues.append(f"Last error: {self._last_error}")
        return issues

    # ─── ChannelThreadingProtocol ───────────────────────────────────────────

    def resolve_reply_mode(self, config: dict[str, Any], chat_type: str) -> str:
        return self._reply_manager.mode

    def resolve_thread_id(self, message: ChannelMessage) -> str | None:
        root_id = message.metadata.get("root_id") or message.reply_to_message_id
        if root_id:
            return f"thread_{root_id}"
        return None

    def build_tool_context(self, context: dict) -> dict:
        return {"reply_mode": self._reply_manager.mode, "thread_only": self._reply_manager.thread_only}

    def resolve_auto_thread_id(self, to: str, reply_to_id: str) -> str | None:
        if reply_to_id:
            return f"thread_{reply_to_id}"
        return None

    def resolve_reply_transport(self, thread_id: str, reply_to_id: str) -> dict:
        return {"thread_id": thread_id, "reply_to_message_id": reply_to_id}

    # ─── ChannelPairingProtocol ─────────────────────────────────────────────

    async def start_pairing(self, device_id: str) -> str:

        mgr = self._pairing_manager
        result = mgr.check_or_request(device_id)
        return result.code

    async def verify_pairing(self, device_id: str, code: str) -> bool:
        return self._pairing_manager.approve(device_id, code)

    async def revoke_pairing(self, device_id: str) -> None:
        self._pairing_manager.deny(device_id)

    async def list_paired_devices(self) -> list[dict]:
        approved = self._pairing_manager.list_approved()
        return [{"user_id": r.user_id, "code": r.code} for r in approved]