feat(channel): add cron job message delivery via DingTalk/Feishu channels (#142)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: tptpp

packages/derisk-core/src/derisk/channel/__init__.py

@@ -6,6 +6,7 @@
 - Channel configuration
 - Channel message format
 - Channel handler interface
+- Message router for agent integration
 
 Example:
     ```python
@@ -31,11 +32,15 @@
 from .base import (
     ChannelCapabilities,
     ChannelConfig,
+    ChannelConnectionState,
     ChannelHandler,
     ChannelMessage,
     ChannelSender,
     ChannelType,
+    SendMessageResult,
 )
+from .registry import ChannelHandlerRegistry
+from .router import ChannelMessageRouter
 from .schemas import DingTalkConfig, FeishuConfig
 
 __all__ = [
@@ -45,9 +50,15 @@
     "ChannelSender",
     "ChannelMessage",
     "ChannelCapabilities",
+    "ChannelConnectionState",
+    "SendMessageResult",
     # Interfaces
     "ChannelHandler",
+    # Registry
+    "ChannelHandlerRegistry",
+    # Router
+    "ChannelMessageRouter",
     # Platform configs
     "DingTalkConfig",
     "FeishuConfig",
-]
+]

packages/derisk-core/src/derisk/channel/base.py

@@ -12,6 +12,39 @@
 from derisk._private.pydantic import BaseModel, ConfigDict, Field
 
 
+class ChannelConnectionState(str, Enum):
+    """Channel connection state enumeration."""
+
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    ERROR = "error"
+    RECONNECTING = "reconnecting"
+
+
+class SendMessageResult(BaseModel):
+    """Result of sending a message through a channel."""
+
+    model_config = ConfigDict(title="SendMessageResult")
+
+    success: bool = Field(
+        ...,
+        description="Whether the message was sent successfully",
+    )
+    message_id: Optional[str] = Field(
+        default=None,
+        description="Message ID returned by the channel platform",
+    )
+    error: Optional[str] = Field(
+        default=None,
+        description="Error message if sending failed",
+    )
+    timestamp: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp when the message was sent",
+    )
+
+
 class ChannelType(str, Enum):
     """Channel type enumeration."""
 
@@ -83,7 +116,7 @@ class ChannelCapabilities(BaseModel):
 class ChannelConfig(BaseModel):
     """Base channel configuration."""
 
-    model_config = ConfigDict(title="ChannelConfig")
+    model_config = ConfigDict(title="ChannelConfig", extra="allow")
 
     enabled: bool = Field(
         default=True,
@@ -97,6 +130,10 @@ class ChannelConfig(BaseModel):
         default=None,
         description="Channel description",
     )
+    platform_config: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Platform-specific configuration (FeishuConfig, DingTalkConfig, etc.)",
+    )
 
 
 class ChannelMessage(BaseModel):
@@ -161,6 +198,88 @@ class ChannelHandler(ABC):
     They handle message processing, signature validation, and capability reporting.
     """
 
+    def __init__(self, channel_id: str, config: "ChannelConfig"):
+        """Initialize the channel handler.
+
+        Args:
+            channel_id: The unique identifier for this channel.
+            config: The channel configuration.
+        """
+        self._channel_id = channel_id
+        self._config = config
+        self._connection_state: ChannelConnectionState = (
+            ChannelConnectionState.DISCONNECTED
+        )
+
+    @classmethod
+    def get_default_capabilities(cls) -> ChannelCapabilities:
+        """Get default capabilities for this channel type.
+
+        This class method can be called without instantiating the handler.
+        Subclasses should override this to return their specific capabilities.
+
+        Returns:
+            ChannelCapabilities instance with default values.
+        """
+        return ChannelCapabilities()
+
+    @property
+    def channel_id(self) -> str:
+        """Get the channel ID."""
+        return self._channel_id
+
+    @property
+    def connection_state(self) -> ChannelConnectionState:
+        """Get the current connection state."""
+        return self._connection_state
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start the channel handler.
+
+        This should establish the connection to the platform (WebSocket, Stream, etc.)
+        and start listening for incoming messages.
+        """
+        pass
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the channel handler.
+
+        This should close all connections and stop listening for messages.
+        """
+        pass
+
+    @abstractmethod
+    async def send_message(
+        self,
+        receiver_id: str,
+        content: str,
+        content_type: str = "text",
+        **kwargs,
+    ) -> SendMessageResult:
+        """Send a message to a receiver through this channel.
+
+        Args:
+            receiver_id: The ID of the receiver (user or group).
+            content: The message content.
+            content_type: The content type (text, markdown, etc.).
+            **kwargs: Additional parameters (reply_to, mentions, etc.).
+
+        Returns:
+            SendMessageResult indicating success or failure.
+        """
+        pass
+
+    @abstractmethod
+    def get_connection_url(self) -> Optional[str]:
+        """Get the webhook URL for setting up the channel integration.
+
+        Returns:
+            The webhook URL if applicable, None if using WebSocket/Stream mode.
+        """
+        pass
+
     @abstractmethod
     async def process_message(
         self,
@@ -220,4 +339,4 @@ async def test_connection(self, channel_id: str) -> bool:
         Returns:
             True if the connection is successful, False otherwise.
         """
-        pass
+        pass