Merge pull request #1480 from trheyi/main

feat: support Telegram, Discord, Feishu, and DingTalk integrations

.gitignore

@@ -69,3 +69,6 @@ sandbox/DESIGN-REMOTE.md
 event/DESIGN.md
 event/TODO.md
 agent/robot/DESIGN-V2.md
+tg-session.json
+tg-login
+tg-send

Makefile

@@ -11,14 +11,14 @@ OS := $(shell uname)
 
 # ROOT_DIR := $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
 TESTFOLDER := $(shell $(GO) list ./... | grep -vE 'examples|openai|aigc|neo|twilio|share*' | awk '!/\/tests\// || /openapi\/tests/')
-# Core tests (exclude AI-related: agent, aigc, openai, KB, and sandbox which requires Docker)
-TESTFOLDER_CORE := $(shell $(GO) list ./... | grep -vE 'examples|openai|aigc|neo|twilio|share*|agent|kb|sandbox' | awk '!/\/tests\// || /openapi\/tests/')
+# Core tests (exclude AI-related: agent, aigc, openai, KB, sandbox, and integrations which require external services)
+TESTFOLDER_CORE := $(shell $(GO) list ./... | grep -vE 'examples|openai|aigc|neo|twilio|share*|agent|kb|sandbox|integrations' | awk '!/\/tests\// || /openapi\/tests/')
 # Agent tests (agent, aigc) - exclude agent/search/handlers/web (requires external API keys) and robot packages (tested in robot job)
 TESTFOLDER_AGENT := $(shell $(GO) list ./agent/... ./aigc/... | grep -vE 'agent/search/handlers/web|agent/robot/')
 # KB tests (kb)
 TESTFOLDER_KB := $(shell $(GO) list ./kb/...)
-# Robot tests (all agent/robot/... packages) - runs ALL tests (unit + E2E) with real LLM calls
-TESTFOLDER_ROBOT := $(shell $(GO) list ./agent/robot/...)
+# Robot tests (agent/robot/... packages, excluding events/integrations which require Telegram etc.)
+TESTFOLDER_ROBOT := $(shell $(GO) list ./agent/robot/... | grep -vE 'agent/robot/events')
 # Sandbox tests (requires Docker)
 TESTFOLDER_SANDBOX := $(shell $(GO) list ./sandbox/...)
 TESTTAGS ?= ""

agent/robot/api/lifecycle.go

@@ -1,18 +1,40 @@
 package api
 
 import (
+	"context"
 	"fmt"
 	"sync"
 
+	robotevents "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/agent/robot/events/integrations"
+	dtadapter "github.com/yaoapp/yao/agent/robot/events/integrations/dingtalk"
+	dcadapter "github.com/yaoapp/yao/agent/robot/events/integrations/discord"
+	fsadapter "github.com/yaoapp/yao/agent/robot/events/integrations/feishu"
+	"github.com/yaoapp/yao/agent/robot/events/integrations/telegram"
+	"github.com/yaoapp/yao/agent/robot/logger"
 	"github.com/yaoapp/yao/agent/robot/manager"
+	"github.com/yaoapp/yao/agent/robot/types"
 )
 
+var log = logger.New("robot")
+
+func init() {
+	robotevents.RegisterTriggerFunc(func(ctx *types.Context, memberID string, triggerType types.TriggerType, data interface{}) (string, bool, error) {
+		result, err := TriggerManual(ctx, memberID, triggerType, data)
+		if err != nil {
+			return "", false, err
+		}
+		return result.ExecutionID, result.Accepted, nil
+	})
+}
+
 // ==================== Lifecycle API ====================
 // These functions manage the robot agent system lifecycle
 
 var (
-	globalManager *manager.Manager
-	managerMu     sync.RWMutex
+	globalManager    *manager.Manager
+	globalDispatcher *integrations.Dispatcher
+	managerMu        sync.RWMutex
 )
 
 // Start starts the robot agent system
@@ -33,7 +55,23 @@ func Start() error {
 		globalManager = manager.New()
 	}
 
-	return globalManager.Start()
+	if err := globalManager.Start(); err != nil {
+		return err
+	}
+
+	// Start integration dispatcher (Telegram polling, webhook subscriptions, etc.)
+	adapters := map[string]integrations.Adapter{
+		"telegram": telegram.NewAdapter(),
+		"feishu":   fsadapter.NewAdapter(),
+		"dingtalk": dtadapter.NewAdapter(),
+		"discord":  dcadapter.NewAdapter(),
+	}
+	globalDispatcher = integrations.NewDispatcher(globalManager.Cache(), adapters)
+	if err := globalDispatcher.Start(context.Background()); err != nil {
+		log.Error("failed to start integration dispatcher: %v", err)
+	}
+
+	return nil
 }
 
 // StartWithConfig starts the robot agent system with custom configuration
@@ -63,12 +101,16 @@ func Stop() error {
 		return nil
 	}
 
+	if globalDispatcher != nil {
+		globalDispatcher.Stop()
+		globalDispatcher = nil
+	}
+
 	err := globalManager.Stop()
 	if err != nil {
 		return err
 	}
 
-	// Reset global manager
 	globalManager = nil
 	return nil
 }

agent/robot/api/robot.go

@@ -8,8 +8,10 @@ import (
 	gonanoid "github.com/matoous/go-nanoid/v2"
 	"github.com/yaoapp/gou/model"
 	"github.com/yaoapp/kun/maps"
+	robotevents "github.com/yaoapp/yao/agent/robot/events"
 	"github.com/yaoapp/yao/agent/robot/store"
 	"github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/event"
 )
 
 // ==================== Robot Query API ====================
@@ -420,6 +422,12 @@ func CreateRobot(ctx *types.Context, req *CreateRobotRequest) (*RobotResponse, e
 		_ = mgr.Cache().Refresh(ctx, req.MemberID)
 	}
 
+	// Notify integrations of new robot config
+	event.Push(context.Background(), robotevents.RobotConfigCreated, robotevents.RobotConfigPayload{
+		MemberID: req.MemberID,
+		TeamID:   req.TeamID,
+	})
+
 	// Return the created robot as response
 	return GetRobotResponse(ctx, req.MemberID)
 }
@@ -532,6 +540,12 @@ func UpdateRobot(ctx *types.Context, memberID string, req *UpdateRobotRequest) (
 		_ = mgr.Cache().Refresh(ctx, memberID) // Ignore error, database is already saved
 	}
 
+	// Notify integrations of updated robot config
+	event.Push(context.Background(), robotevents.RobotConfigUpdated, robotevents.RobotConfigPayload{
+		MemberID: memberID,
+		TeamID:   existing.TeamID,
+	})
+
 	// Return the updated robot as response
 	return GetRobotResponse(ctx, memberID)
 }
@@ -572,6 +586,12 @@ func RemoveRobot(ctx *types.Context, memberID string) error {
 		mgr.Cache().Remove(memberID)
 	}
 
+	// Notify integrations of deleted robot config
+	event.Push(context.Background(), robotevents.RobotConfigDeleted, robotevents.RobotConfigPayload{
+		MemberID: memberID,
+		TeamID:   existing.TeamID,
+	})
+
 	return nil
 }
 

agent/robot/events/delivery.go

@@ -0,0 +1,502 @@
+package events
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/yaoapp/gou/process"
+	"github.com/yaoapp/gou/text"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/attachment"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	"github.com/yaoapp/yao/messenger"
+	messengerTypes "github.com/yaoapp/yao/messenger/types"
+)
+
+// handleDelivery routes delivery content to configured channels (email, webhook, process).
+func (h *robotHandler) handleDelivery(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	var payload DeliveryPayload
+	if err := ev.Should(&payload); err != nil {
+		log.Error("delivery handler: invalid payload: %v", err)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Err: err}
+		}
+		return
+	}
+
+	log.Info("delivery handler: execution=%s member=%s", payload.ExecutionID, payload.MemberID)
+
+	content := payload.Content
+	prefs := payload.Preferences
+	if content == nil {
+		log.Warn("delivery handler: nil content for execution=%s", payload.ExecutionID)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Data: "no content"}
+		}
+		return
+	}
+	if prefs == nil {
+		if ev.IsCall {
+			resp <- eventtypes.Result{Data: "no preferences, skipped"}
+		}
+		return
+	}
+
+	deliveryCtx := &robottypes.DeliveryContext{
+		MemberID:    payload.MemberID,
+		ExecutionID: payload.ExecutionID,
+		TeamID:      payload.TeamID,
+	}
+
+	var results []robottypes.ChannelResult
+	var lastErr error
+
+	if prefs.Email != nil && prefs.Email.Enabled {
+		for _, target := range prefs.Email.Targets {
+			r := h.sendEmail(ctx, content, target, deliveryCtx)
+			results = append(results, r)
+			if !r.Success && lastErr == nil {
+				lastErr = fmt.Errorf("email delivery failed: %s", r.Error)
+			}
+		}
+	}
+
+	if prefs.Webhook != nil && prefs.Webhook.Enabled {
+		for _, target := range prefs.Webhook.Targets {
+			r := h.postWebhook(ctx, content, target, deliveryCtx)
+			results = append(results, r)
+			if !r.Success && lastErr == nil {
+				lastErr = fmt.Errorf("webhook delivery failed: %s", r.Error)
+			}
+		}
+	}
+
+	if prefs.Process != nil && prefs.Process.Enabled {
+		for _, target := range prefs.Process.Targets {
+			r := h.callProcess(ctx, content, target, deliveryCtx)
+			results = append(results, r)
+			if !r.Success && lastErr == nil {
+				lastErr = fmt.Errorf("process delivery failed: %s", r.Error)
+			}
+		}
+	}
+
+	// Push delivery to integration channels (Telegram, etc.) via ReplyFunc
+	if reply := getReplyFunc(); reply != nil {
+		msg := buildDeliveryMessage(content)
+		if msg != nil {
+			channel, chatID := splitChannelChatID(payload.ChatID)
+			extra := map[string]any{
+				"member_id":    payload.MemberID,
+				"execution_id": payload.ExecutionID,
+			}
+			for k, v := range payload.Extra {
+				extra[k] = v
+			}
+			metadata := &MessageMetadata{
+				Channel: channel,
+				ChatID:  chatID,
+				Extra:   extra,
+			}
+			if err := reply(ctx, msg, metadata); err != nil {
+				log.Error("delivery handler: integration reply failed execution=%s: %v", payload.ExecutionID, err)
+			}
+		}
+	}
+
+	if lastErr != nil {
+		log.Error("delivery handler: partial failure execution=%s: %v", payload.ExecutionID, lastErr)
+	}
+
+	if ev.IsCall {
+		resp <- eventtypes.Result{
+			Data: map[string]interface{}{
+				"execution_id": payload.ExecutionID,
+				"results":      results,
+			},
+			Err: lastErr,
+		}
+	}
+}
+
+// buildDeliveryMessage converts DeliveryContent into a standard assistant Message.
+func buildDeliveryMessage(content *robottypes.DeliveryContent) *agentcontext.Message {
+	if content == nil {
+		return nil
+	}
+
+	var parts []interface{}
+
+	text := content.Body
+	if text == "" {
+		text = content.Summary
+	}
+	if text != "" {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": text,
+		})
+	}
+
+	for _, att := range content.Attachments {
+		if att.File == "" {
+			continue
+		}
+		part := map[string]interface{}{
+			"type": "file",
+			"file": map[string]interface{}{
+				"url":      att.File,
+				"filename": att.Title,
+			},
+		}
+		parts = append(parts, part)
+	}
+
+	if len(parts) == 0 {
+		return nil
+	}
+
+	var msgContent interface{}
+	if len(parts) == 1 {
+		if tp, ok := parts[0].(map[string]interface{}); ok && tp["type"] == "text" {
+			msgContent = tp["text"]
+		} else {
+			msgContent = parts
+		}
+	} else {
+		msgContent = parts
+	}
+
+	return &agentcontext.Message{
+		Role:    agentcontext.RoleAssistant,
+		Content: msgContent,
+	}
+}
+
+// ============================================================================
+// Email
+// ============================================================================
+
+func (h *robotHandler) sendEmail(
+	ctx context.Context,
+	content *robottypes.DeliveryContent,
+	target robottypes.EmailTarget,
+	deliveryCtx *robottypes.DeliveryContext,
+) robottypes.ChannelResult {
+	now := time.Now()
+	targetID := strings.Join(target.To, ",")
+	if targetID == "" {
+		targetID = "no-recipients"
+	}
+
+	result := robottypes.ChannelResult{
+		Type:   robottypes.DeliveryEmail,
+		Target: targetID,
+		SentAt: &now,
+	}
+
+	svc := messenger.Instance
+	if svc == nil {
+		result.Error = "messenger service not available"
+		return result
+	}
+
+	htmlBody, plainBody := buildEmailBody(target.Template, content)
+	msg := &messengerTypes.Message{
+		To:      target.To,
+		Subject: buildEmailSubject(target.Subject, target.Template, content, deliveryCtx),
+		Body:    plainBody,
+		HTML:    htmlBody,
+		Type:    messengerTypes.MessageTypeEmail,
+	}
+
+	attachments := convertAttachments(ctx, content.Attachments)
+	if len(attachments) > 0 {
+		msg.Attachments = attachments
+	}
+
+	channel := robottypes.DefaultEmailChannel()
+	if err := svc.Send(ctx, channel, msg); err != nil {
+		result.Error = err.Error()
+		return result
+	}
+
+	result.Success = true
+	result.Recipients = target.To
+	return result
+}
+
+// ============================================================================
+// Webhook
+// ============================================================================
+
+func (h *robotHandler) postWebhook(
+	ctx context.Context,
+	content *robottypes.DeliveryContent,
+	target robottypes.WebhookTarget,
+	deliveryCtx *robottypes.DeliveryContext,
+) robottypes.ChannelResult {
+	now := time.Now()
+	result := robottypes.ChannelResult{
+		Type:   robottypes.DeliveryWebhook,
+		Target: target.URL,
+		SentAt: &now,
+	}
+
+	payload := map[string]interface{}{
+		"event":        "robot.delivery",
+		"timestamp":    now.Format(time.RFC3339),
+		"execution_id": deliveryCtx.ExecutionID,
+		"member_id":    deliveryCtx.MemberID,
+		"team_id":      deliveryCtx.TeamID,
+		"trigger_type": deliveryCtx.TriggerType,
+		"content": map[string]interface{}{
+			"summary": content.Summary,
+			"body":    content.Body,
+		},
+	}
+
+	if len(content.Attachments) > 0 {
+		info := make([]map[string]interface{}, 0, len(content.Attachments))
+		for _, att := range content.Attachments {
+			info = append(info, map[string]interface{}{
+				"title":       att.Title,
+				"description": att.Description,
+				"task_id":     att.TaskID,
+				"file":        att.File,
+			})
+		}
+		payload["attachments"] = info
+	}
+
+	payloadBytes, err := json.Marshal(payload)
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to marshal payload: %v", err)
+		return result
+	}
+
+	method := target.Method
+	if method == "" {
+		method = "POST"
+	}
+
+	req, err := http.NewRequestWithContext(ctx, method, target.URL, bytes.NewReader(payloadBytes))
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to create request: %v", err)
+		return result
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	for key, value := range target.Headers {
+		req.Header.Set(key, value)
+	}
+
+	if target.Secret != "" {
+		signature := ComputeHMACSignature(payloadBytes, target.Secret)
+		req.Header.Set("X-Yao-Signature", signature)
+		req.Header.Set("X-Yao-Signature-Algorithm", "HMAC-SHA256")
+	}
+
+	httpResp, err := h.httpClient.Do(req)
+	if err != nil {
+		result.Error = fmt.Sprintf("request failed: %v", err)
+		return result
+	}
+	defer httpResp.Body.Close()
+
+	body, _ := io.ReadAll(httpResp.Body)
+
+	if httpResp.StatusCode < 200 || httpResp.StatusCode >= 300 {
+		result.Error = fmt.Sprintf("webhook returned status %d: %s", httpResp.StatusCode, string(body))
+		return result
+	}
+
+	result.Success = true
+	result.Details = map[string]interface{}{
+		"status_code": httpResp.StatusCode,
+		"response":    string(body),
+	}
+	return result
+}
+
+// ============================================================================
+// Process
+// ============================================================================
+
+func (h *robotHandler) callProcess(
+	ctx context.Context,
+	content *robottypes.DeliveryContent,
+	target robottypes.ProcessTarget,
+	deliveryCtx *robottypes.DeliveryContext,
+) robottypes.ChannelResult {
+	now := time.Now()
+	result := robottypes.ChannelResult{
+		Type:   robottypes.DeliveryProcess,
+		Target: target.Process,
+		SentAt: &now,
+	}
+
+	args := make([]interface{}, 0, 1+len(target.Args))
+	args = append(args, map[string]interface{}{
+		"content": map[string]interface{}{
+			"summary":     content.Summary,
+			"body":        content.Body,
+			"attachments": content.Attachments,
+		},
+		"context": map[string]interface{}{
+			"execution_id": deliveryCtx.ExecutionID,
+			"member_id":    deliveryCtx.MemberID,
+			"team_id":      deliveryCtx.TeamID,
+			"trigger_type": deliveryCtx.TriggerType,
+		},
+	})
+	args = append(args, target.Args...)
+
+	proc, err := process.Of(target.Process, args...)
+	if err != nil {
+		result.Error = fmt.Sprintf("failed to create process: %v", err)
+		return result
+	}
+	proc.Context = ctx
+
+	if err = proc.Execute(); err != nil {
+		result.Error = err.Error()
+		return result
+	}
+
+	result.Success = true
+	result.Details = toJSONSerializable(proc.Value)
+	return result
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+func toJSONSerializable(v interface{}) interface{} {
+	if v == nil {
+		return nil
+	}
+	if _, err := json.Marshal(v); err != nil {
+		return fmt.Sprintf("%v", v)
+	}
+	return v
+}
+
+func buildEmailSubject(subject, template string, content *robottypes.DeliveryContent, ctx *robottypes.DeliveryContext) string {
+	if subject != "" {
+		return subject
+	}
+	if content.Summary != "" {
+		return content.Summary
+	}
+	return fmt.Sprintf("Execution %s Complete", ctx.ExecutionID)
+}
+
+func buildEmailBody(template string, content *robottypes.DeliveryContent) (string, string) {
+	markdown := content.Body
+	if markdown == "" {
+		markdown = content.Summary
+	}
+	html, err := text.MarkdownToHTML(markdown)
+	if err != nil {
+		return markdown, markdown
+	}
+	return html, markdown
+}
+
+func convertAttachments(ctx context.Context, attachments []robottypes.DeliveryAttachment) []messengerTypes.Attachment {
+	if len(attachments) == 0 {
+		return nil
+	}
+
+	result := make([]messengerTypes.Attachment, 0, len(attachments))
+	for _, att := range attachments {
+		uploader, fileID, isWrapper := attachment.Parse(att.File)
+		if !isWrapper {
+			log.Warn("convertAttachments: skipping non-wrapper file value=%q title=%q", att.File, att.Title)
+			continue
+		}
+		manager, ok := attachment.Managers[uploader]
+		if !ok {
+			log.Warn("convertAttachments: manager not found uploader=%q file=%q title=%q (available: %v)",
+				uploader, att.File, att.Title, attachmentManagerKeys())
+			continue
+		}
+		info, err := manager.Info(ctx, fileID)
+		if err != nil {
+			log.Warn("convertAttachments: failed to get file info fileID=%q uploader=%q: %v", fileID, uploader, err)
+			continue
+		}
+		content, err := manager.Read(ctx, fileID)
+		if err != nil {
+			log.Warn("convertAttachments: failed to read file fileID=%q uploader=%q: %v", fileID, uploader, err)
+			continue
+		}
+
+		filename := info.Filename
+		if att.Title != "" {
+			ext := ""
+			if idx := strings.LastIndex(info.Filename, "."); idx >= 0 {
+				ext = info.Filename[idx:]
+			}
+			titleExt := ""
+			if idx := strings.LastIndex(att.Title, "."); idx >= 0 {
+				titleExt = att.Title[idx:]
+			}
+			if titleExt != "" {
+				filename = att.Title
+			} else {
+				filename = att.Title + ext
+			}
+		}
+
+		log.Info("convertAttachments: added attachment filename=%q contentType=%q size=%d", filename, info.ContentType, len(content))
+		result = append(result, messengerTypes.Attachment{
+			Filename:    filename,
+			ContentType: info.ContentType,
+			Content:     content,
+		})
+	}
+	return result
+}
+
+func attachmentManagerKeys() []string {
+	keys := make([]string, 0, len(attachment.Managers))
+	for k := range attachment.Managers {
+		keys = append(keys, k)
+	}
+	return keys
+}
+
+// ComputeHMACSignature computes HMAC-SHA256 signature for webhook payload.
+func ComputeHMACSignature(payload []byte, secret string) string {
+	mac := hmac.New(sha256.New, []byte(secret))
+	mac.Write(payload)
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+// VerifyHMACSignature verifies the HMAC-SHA256 signature of a webhook payload.
+func VerifyHMACSignature(payload []byte, secret, signature string) bool {
+	expected := ComputeHMACSignature(payload, secret)
+	return hmac.Equal([]byte(expected), []byte(signature))
+}
+
+// splitChannelChatID splits a composite "channel:chatID" string (e.g. "telegram:8134167376")
+// into its channel and chatID parts. If no colon is present, channel is empty.
+func splitChannelChatID(composite string) (channel, chatID string) {
+	if idx := strings.Index(composite, ":"); idx >= 0 {
+		return composite[:idx], composite[idx+1:]
+	}
+	return "", composite
+}

agent/robot/events/events.go

@@ -1,6 +1,60 @@
 package events
 
-import robottypes "github.com/yaoapp/yao/agent/robot/types"
+import (
+	"context"
+	"strings"
+	"sync"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+)
+
+// TriggerFunc is the callback for triggering a robot execution.
+// Injected by the api package at startup to break the import cycle.
+// Returns (executionID, accepted, error).
+type TriggerFunc func(ctx *robottypes.Context, memberID string, triggerType robottypes.TriggerType, data interface{}) (string, bool, error)
+
+// ReplyFunc is the callback for replying to the originating channel.
+// Injected by the dispatcher at startup. The implementation routes the
+// reply to the correct adapter based on metadata.Channel.
+// msg is the standard assistant message (text, Content Parts, media, etc.).
+type ReplyFunc func(ctx context.Context, msg *agentcontext.Message, metadata *MessageMetadata) error
+
+var (
+	triggerFn   TriggerFunc
+	triggerFnMu sync.RWMutex
+
+	replyFn   ReplyFunc
+	replyFnMu sync.RWMutex
+)
+
+// RegisterTriggerFunc sets the function used by handleMessage to trigger
+// robot execution when a confirmed action is detected.
+func RegisterTriggerFunc(fn TriggerFunc) {
+	triggerFnMu.Lock()
+	defer triggerFnMu.Unlock()
+	triggerFn = fn
+}
+
+func getTriggerFunc() TriggerFunc {
+	triggerFnMu.RLock()
+	defer triggerFnMu.RUnlock()
+	return triggerFn
+}
+
+// RegisterReplyFunc sets the function used by handleMessage to reply
+// to the originating channel after processing.
+func RegisterReplyFunc(fn ReplyFunc) {
+	replyFnMu.Lock()
+	defer replyFnMu.Unlock()
+	replyFn = fn
+}
+
+func getReplyFunc() ReplyFunc {
+	replyFnMu.RLock()
+	defer replyFnMu.RUnlock()
+	return replyFn
+}
 
 // Robot event type constants for event.Push integration.
 // Events are fire-and-forget; handlers are registered via event.Register().
@@ -14,6 +68,14 @@ const (
 	ExecFailed    = "robot.exec.failed"
 	ExecCancelled = "robot.exec.cancelled"
 	Delivery      = "robot.delivery"
+	Message       = "robot.message"
+)
+
+// Robot configuration change events (used by integrations Receiver).
+const (
+	RobotConfigCreated = "robot.config.created"
+	RobotConfigUpdated = "robot.config.updated"
+	RobotConfigDeleted = "robot.config.deleted"
 )
 
 // NeedInputPayload is the event payload for TaskNeedInput / ExecWaiting events.
@@ -54,4 +116,79 @@ type DeliveryPayload struct {
 	ChatID      string                          `json:"chat_id,omitempty"`
 	Content     *robottypes.DeliveryContent     `json:"content,omitempty"`
 	Preferences *robottypes.DeliveryPreferences `json:"preferences,omitempty"`
+	Extra       map[string]any                  `json:"extra,omitempty"`
+}
+
+// MessagePayload is the event payload for Message events (external channel messages).
+type MessagePayload struct {
+	RobotID  string                 `json:"robot_id"`
+	Messages []agentcontext.Message `json:"messages"`
+	Metadata *MessageMetadata       `json:"metadata"`
+}
+
+// MessageMetadata carries channel-specific information for routing and deduplication.
+type MessageMetadata struct {
+	Channel    string         `json:"channel"`
+	MessageID  string         `json:"message_id,omitempty"`
+	AppID      string         `json:"app_id,omitempty"`
+	ChatID     string         `json:"chat_id,omitempty"`
+	SenderID   string         `json:"sender_id,omitempty"`
+	SenderName string         `json:"sender_name,omitempty"`
+	Locale     string         `json:"locale,omitempty"`
+	ReplyTo    string         `json:"reply_to,omitempty"`
+	Extra      map[string]any `json:"extra,omitempty"`
+}
+
+// MessageResult is the result returned from handleMessage via event.Call.
+type MessageResult struct {
+	Message     *agentcontext.Message `json:"message,omitempty"`
+	Action      *ActionResult         `json:"action,omitempty"`
+	ExecutionID string                `json:"execution_id,omitempty"`
+	Metadata    *MessageMetadata      `json:"metadata,omitempty"`
+}
+
+// ActionResult describes a detected action from the Host Agent's Next hook.
+type ActionResult struct {
+	Name    string `json:"name"`
+	Payload any    `json:"payload,omitempty"`
+}
+
+// RobotConfigPayload is the event payload for robot.config.* events.
+type RobotConfigPayload struct {
+	MemberID string `json:"member_id"`
+	TeamID   string `json:"team_id"`
+}
+
+// NormalizeLocale converts various language code formats (IETF BCP 47, etc.)
+// into the lowercase hyphenated form used by agentcontext (e.g. "zh-cn", "en-us").
+//
+// Mapping rules:
+//
+//	"zh-hans", "zh-cn"           → "zh-cn"
+//	"zh-hant", "zh-tw", "zh-hk" → "zh-tw"
+//	"zh"                         → "zh-cn"
+//	"en-us"                      → "en-us"
+//	"en-gb"                      → "en-gb"
+//	"en"                         → "en"
+//	""                           → "en"  (default)
+//	other                        → lowercased as-is
+func NormalizeLocale(raw string) string {
+	code := strings.ToLower(strings.TrimSpace(raw))
+	if code == "" {
+		return "en"
+	}
+
+	// Normalize underscore to hyphen (e.g. zh_CN → zh-cn)
+	code = strings.ReplaceAll(code, "_", "-")
+
+	switch code {
+	case "zh-hans", "zh-cn":
+		return "zh-cn"
+	case "zh-hant", "zh-tw", "zh-hk":
+		return "zh-tw"
+	case "zh":
+		return "zh-cn"
+	default:
+		return code
+	}
 }

agent/robot/events/handlers.go

@@ -1,27 +1,12 @@
 package events
 
 import (
-	"bytes"
 	"context"
-	"crypto/hmac"
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"fmt"
-	"io"
 	"net/http"
-	"strings"
 	"time"
 
-	"github.com/yaoapp/gou/process"
-	"github.com/yaoapp/gou/text"
-	"github.com/yaoapp/kun/log"
-	robottypes "github.com/yaoapp/yao/agent/robot/types"
-	"github.com/yaoapp/yao/attachment"
 	"github.com/yaoapp/yao/event"
 	eventtypes "github.com/yaoapp/yao/event/types"
-	"github.com/yaoapp/yao/messenger"
-	messengerTypes "github.com/yaoapp/yao/messenger/types"
 )
 
 func init() {
@@ -40,6 +25,8 @@ func (h *robotHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp ch
 	switch ev.Type {
 	case Delivery:
 		h.handleDelivery(ctx, ev, resp)
+	case Message:
+		h.handleMessage(ctx, ev, resp)
 	default:
 		log.Debug("robot handler: unhandled event type=%s id=%s", ev.Type, ev.ID)
 	}
@@ -49,403 +36,3 @@ func (h *robotHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp ch
 func (h *robotHandler) Shutdown(ctx context.Context) error {
 	return nil
 }
-
-// handleDelivery routes delivery content to configured channels (email, webhook, process).
-func (h *robotHandler) handleDelivery(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
-	var payload DeliveryPayload
-	if err := ev.Should(&payload); err != nil {
-		log.Error("delivery handler: invalid payload: %v", err)
-		if ev.IsCall {
-			resp <- eventtypes.Result{Err: err}
-		}
-		return
-	}
-
-	log.Info("delivery handler: execution=%s member=%s", payload.ExecutionID, payload.MemberID)
-
-	content := payload.Content
-	prefs := payload.Preferences
-	if content == nil {
-		log.Warn("delivery handler: nil content for execution=%s", payload.ExecutionID)
-		if ev.IsCall {
-			resp <- eventtypes.Result{Data: "no content"}
-		}
-		return
-	}
-	if prefs == nil {
-		if ev.IsCall {
-			resp <- eventtypes.Result{Data: "no preferences, skipped"}
-		}
-		return
-	}
-
-	deliveryCtx := &robottypes.DeliveryContext{
-		MemberID:    payload.MemberID,
-		ExecutionID: payload.ExecutionID,
-		TeamID:      payload.TeamID,
-	}
-
-	var results []robottypes.ChannelResult
-	var lastErr error
-
-	if prefs.Email != nil && prefs.Email.Enabled {
-		for _, target := range prefs.Email.Targets {
-			r := h.sendEmail(ctx, content, target, deliveryCtx)
-			results = append(results, r)
-			if !r.Success && lastErr == nil {
-				lastErr = fmt.Errorf("email delivery failed: %s", r.Error)
-			}
-		}
-	}
-
-	if prefs.Webhook != nil && prefs.Webhook.Enabled {
-		for _, target := range prefs.Webhook.Targets {
-			r := h.postWebhook(ctx, content, target, deliveryCtx)
-			results = append(results, r)
-			if !r.Success && lastErr == nil {
-				lastErr = fmt.Errorf("webhook delivery failed: %s", r.Error)
-			}
-		}
-	}
-
-	if prefs.Process != nil && prefs.Process.Enabled {
-		for _, target := range prefs.Process.Targets {
-			r := h.callProcess(ctx, content, target, deliveryCtx)
-			results = append(results, r)
-			if !r.Success && lastErr == nil {
-				lastErr = fmt.Errorf("process delivery failed: %s", r.Error)
-			}
-		}
-	}
-
-	if lastErr != nil {
-		log.Error("delivery handler: partial failure execution=%s: %v", payload.ExecutionID, lastErr)
-	}
-
-	if ev.IsCall {
-		resp <- eventtypes.Result{
-			Data: map[string]interface{}{
-				"execution_id": payload.ExecutionID,
-				"results":      results,
-			},
-			Err: lastErr,
-		}
-	}
-}
-
-// ============================================================================
-// Email
-// ============================================================================
-
-func (h *robotHandler) sendEmail(
-	ctx context.Context,
-	content *robottypes.DeliveryContent,
-	target robottypes.EmailTarget,
-	deliveryCtx *robottypes.DeliveryContext,
-) robottypes.ChannelResult {
-	now := time.Now()
-	targetID := strings.Join(target.To, ",")
-	if targetID == "" {
-		targetID = "no-recipients"
-	}
-
-	result := robottypes.ChannelResult{
-		Type:   robottypes.DeliveryEmail,
-		Target: targetID,
-		SentAt: &now,
-	}
-
-	svc := messenger.Instance
-	if svc == nil {
-		result.Error = "messenger service not available"
-		return result
-	}
-
-	htmlBody, plainBody := buildEmailBody(target.Template, content)
-	msg := &messengerTypes.Message{
-		To:      target.To,
-		Subject: buildEmailSubject(target.Subject, target.Template, content, deliveryCtx),
-		Body:    plainBody,
-		HTML:    htmlBody,
-		Type:    messengerTypes.MessageTypeEmail,
-	}
-
-	attachments := convertAttachments(ctx, content.Attachments)
-	if len(attachments) > 0 {
-		msg.Attachments = attachments
-	}
-
-	channel := robottypes.DefaultEmailChannel()
-	if err := svc.Send(ctx, channel, msg); err != nil {
-		result.Error = err.Error()
-		return result
-	}
-
-	result.Success = true
-	result.Recipients = target.To
-	return result
-}
-
-// ============================================================================
-// Webhook
-// ============================================================================
-
-func (h *robotHandler) postWebhook(
-	ctx context.Context,
-	content *robottypes.DeliveryContent,
-	target robottypes.WebhookTarget,
-	deliveryCtx *robottypes.DeliveryContext,
-) robottypes.ChannelResult {
-	now := time.Now()
-	result := robottypes.ChannelResult{
-		Type:   robottypes.DeliveryWebhook,
-		Target: target.URL,
-		SentAt: &now,
-	}
-
-	payload := map[string]interface{}{
-		"event":        "robot.delivery",
-		"timestamp":    now.Format(time.RFC3339),
-		"execution_id": deliveryCtx.ExecutionID,
-		"member_id":    deliveryCtx.MemberID,
-		"team_id":      deliveryCtx.TeamID,
-		"trigger_type": deliveryCtx.TriggerType,
-		"content": map[string]interface{}{
-			"summary": content.Summary,
-			"body":    content.Body,
-		},
-	}
-
-	if len(content.Attachments) > 0 {
-		info := make([]map[string]interface{}, 0, len(content.Attachments))
-		for _, att := range content.Attachments {
-			info = append(info, map[string]interface{}{
-				"title":       att.Title,
-				"description": att.Description,
-				"task_id":     att.TaskID,
-				"file":        att.File,
-			})
-		}
-		payload["attachments"] = info
-	}
-
-	payloadBytes, err := json.Marshal(payload)
-	if err != nil {
-		result.Error = fmt.Sprintf("failed to marshal payload: %v", err)
-		return result
-	}
-
-	method := target.Method
-	if method == "" {
-		method = "POST"
-	}
-
-	req, err := http.NewRequestWithContext(ctx, method, target.URL, bytes.NewReader(payloadBytes))
-	if err != nil {
-		result.Error = fmt.Sprintf("failed to create request: %v", err)
-		return result
-	}
-
-	req.Header.Set("Content-Type", "application/json")
-	for key, value := range target.Headers {
-		req.Header.Set(key, value)
-	}
-
-	if target.Secret != "" {
-		signature := ComputeHMACSignature(payloadBytes, target.Secret)
-		req.Header.Set("X-Yao-Signature", signature)
-		req.Header.Set("X-Yao-Signature-Algorithm", "HMAC-SHA256")
-	}
-
-	resp, err := h.httpClient.Do(req)
-	if err != nil {
-		result.Error = fmt.Sprintf("request failed: %v", err)
-		return result
-	}
-	defer resp.Body.Close()
-
-	body, _ := io.ReadAll(resp.Body)
-
-	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
-		result.Error = fmt.Sprintf("webhook returned status %d: %s", resp.StatusCode, string(body))
-		return result
-	}
-
-	result.Success = true
-	result.Details = map[string]interface{}{
-		"status_code": resp.StatusCode,
-		"response":    string(body),
-	}
-	return result
-}
-
-// ============================================================================
-// Process
-// ============================================================================
-
-func (h *robotHandler) callProcess(
-	ctx context.Context,
-	content *robottypes.DeliveryContent,
-	target robottypes.ProcessTarget,
-	deliveryCtx *robottypes.DeliveryContext,
-) robottypes.ChannelResult {
-	now := time.Now()
-	result := robottypes.ChannelResult{
-		Type:   robottypes.DeliveryProcess,
-		Target: target.Process,
-		SentAt: &now,
-	}
-
-	args := make([]interface{}, 0, 1+len(target.Args))
-	args = append(args, map[string]interface{}{
-		"content": map[string]interface{}{
-			"summary":     content.Summary,
-			"body":        content.Body,
-			"attachments": content.Attachments,
-		},
-		"context": map[string]interface{}{
-			"execution_id": deliveryCtx.ExecutionID,
-			"member_id":    deliveryCtx.MemberID,
-			"team_id":      deliveryCtx.TeamID,
-			"trigger_type": deliveryCtx.TriggerType,
-		},
-	})
-	args = append(args, target.Args...)
-
-	proc, err := process.Of(target.Process, args...)
-	if err != nil {
-		result.Error = fmt.Sprintf("failed to create process: %v", err)
-		return result
-	}
-	proc.Context = ctx
-
-	if err = proc.Execute(); err != nil {
-		result.Error = err.Error()
-		return result
-	}
-
-	result.Success = true
-	result.Details = toJSONSerializable(proc.Value)
-	return result
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-func toJSONSerializable(v interface{}) interface{} {
-	if v == nil {
-		return nil
-	}
-	if _, err := json.Marshal(v); err != nil {
-		return fmt.Sprintf("%v", v)
-	}
-	return v
-}
-
-func buildEmailSubject(subject, template string, content *robottypes.DeliveryContent, ctx *robottypes.DeliveryContext) string {
-	if subject != "" {
-		return subject
-	}
-	if content.Summary != "" {
-		return content.Summary
-	}
-	return fmt.Sprintf("Execution %s Complete", ctx.ExecutionID)
-}
-
-func buildEmailBody(template string, content *robottypes.DeliveryContent) (string, string) {
-	markdown := content.Body
-	if markdown == "" {
-		markdown = content.Summary
-	}
-	html, err := text.MarkdownToHTML(markdown)
-	if err != nil {
-		return markdown, markdown
-	}
-	return html, markdown
-}
-
-func convertAttachments(ctx context.Context, attachments []robottypes.DeliveryAttachment) []messengerTypes.Attachment {
-	if len(attachments) == 0 {
-		return nil
-	}
-
-	result := make([]messengerTypes.Attachment, 0, len(attachments))
-	for _, att := range attachments {
-		uploader, fileID, isWrapper := attachment.Parse(att.File)
-		if !isWrapper {
-			log.Warn("convertAttachments: skipping non-wrapper file value=%q title=%q", att.File, att.Title)
-			continue
-		}
-		manager, ok := attachment.Managers[uploader]
-		if !ok {
-			log.Warn("convertAttachments: manager not found uploader=%q file=%q title=%q (available: %v)",
-				uploader, att.File, att.Title, attachmentManagerKeys())
-			continue
-		}
-		info, err := manager.Info(ctx, fileID)
-		if err != nil {
-			log.Warn("convertAttachments: failed to get file info fileID=%q uploader=%q: %v", fileID, uploader, err)
-			continue
-		}
-		content, err := manager.Read(ctx, fileID)
-		if err != nil {
-			log.Warn("convertAttachments: failed to read file fileID=%q uploader=%q: %v", fileID, uploader, err)
-			continue
-		}
-
-		// Prefer the semantic title from the delivery agent over the raw storage filename.
-		// The storage filename may be an auto-generated zip name (e.g. output_xxx.zip),
-		// while att.Title is the human-readable name set by the delivery agent.
-		filename := info.Filename
-		if att.Title != "" {
-			// Keep the original file extension from storage so the email client
-			// knows how to open it, but use the human-readable title as the base name.
-			ext := ""
-			if idx := strings.LastIndex(info.Filename, "."); idx >= 0 {
-				ext = info.Filename[idx:]
-			}
-			titleExt := ""
-			if idx := strings.LastIndex(att.Title, "."); idx >= 0 {
-				titleExt = att.Title[idx:]
-			}
-			if titleExt != "" {
-				// Title already has an extension — use it as-is.
-				filename = att.Title
-			} else {
-				// Title has no extension — append the storage extension.
-				filename = att.Title + ext
-			}
-		}
-
-		log.Info("convertAttachments: added attachment filename=%q contentType=%q size=%d", filename, info.ContentType, len(content))
-		result = append(result, messengerTypes.Attachment{
-			Filename:    filename,
-			ContentType: info.ContentType,
-			Content:     content,
-		})
-	}
-	return result
-}
-
-// attachmentManagerKeys returns registered attachment manager names for debug logging.
-func attachmentManagerKeys() []string {
-	keys := make([]string, 0, len(attachment.Managers))
-	for k := range attachment.Managers {
-		keys = append(keys, k)
-	}
-	return keys
-}
-
-// ComputeHMACSignature computes HMAC-SHA256 signature for webhook payload.
-func ComputeHMACSignature(payload []byte, secret string) string {
-	mac := hmac.New(sha256.New, []byte(secret))
-	mac.Write(payload)
-	return hex.EncodeToString(mac.Sum(nil))
-}
-
-// VerifyHMACSignature verifies the HMAC-SHA256 signature of a webhook payload.
-func VerifyHMACSignature(payload []byte, secret, signature string) bool {
-	expected := ComputeHMACSignature(payload, secret)
-	return hmac.Equal([]byte(expected), []byte(signature))
-}

agent/robot/events/integrations/dingtalk/dedup.go

@@ -0,0 +1,44 @@
+package dingtalk
+
+import (
+	"sync"
+	"time"
+)
+
+const (
+	dedupTTL           = 24 * time.Hour
+	dedupCleanInterval = time.Hour
+)
+
+type dedupStore struct {
+	m sync.Map
+}
+
+func newDedupStore() *dedupStore {
+	return &dedupStore{}
+}
+
+func (d *dedupStore) markSeen(key string) bool {
+	now := time.Now().Unix()
+	_, loaded := d.m.LoadOrStore(key, now)
+	return !loaded
+}
+
+func (d *dedupStore) cleaner(stopCh <-chan struct{}) {
+	ticker := time.NewTicker(dedupCleanInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-stopCh:
+			return
+		case <-ticker.C:
+			cutoff := time.Now().Add(-dedupTTL).Unix()
+			d.m.Range(func(key, value any) bool {
+				if ts, ok := value.(int64); ok && ts < cutoff {
+					d.m.Delete(key)
+				}
+				return true
+			})
+		}
+	}
+}

agent/robot/events/integrations/dingtalk/dingtalk.go

@@ -0,0 +1,139 @@
+package dingtalk
+
+import (
+	"context"
+	"sync"
+
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	dtapi "github.com/yaoapp/yao/integrations/dingtalk"
+)
+
+var log = logger.New("dingtalk")
+
+// Adapter implements the integrations.Adapter interface for DingTalk.
+//
+// Architecture:
+//   - One DingTalk Stream client per registered bot for real-time message reception
+//   - One dedup cleaner goroutine removes expired keys every hour
+type Adapter struct {
+	mu     sync.RWMutex
+	bots   map[string]*botEntry // robotID -> *botEntry
+	appIdx map[string]string    // clientID -> robotID
+	dedup  *dedupStore
+	stopCh chan struct{}
+}
+
+// botEntry holds the state for one robot's DingTalk integration.
+type botEntry struct {
+	robotID  string
+	clientID string
+	bot      *dtapi.Bot
+	cancelFn context.CancelFunc
+}
+
+// NewAdapter creates a new DingTalk adapter.
+func NewAdapter() *Adapter {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	go a.dedup.cleaner(a.stopCh)
+	return a
+}
+
+// Apply is called by the Dispatcher when a robot config is created or updated.
+func (a *Adapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	dtConf := extractConfig(robot)
+	log.Debug("Apply robot=%s dtConf=%v", robot.MemberID, dtConf != nil)
+
+	if dtConf == nil || !dtConf.Enabled || dtConf.ClientID == "" || dtConf.ClientSecret == "" {
+		a.removeBot(robot.MemberID)
+		return
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if existing, ok := a.bots[robot.MemberID]; ok {
+		if existing.clientID == dtConf.ClientID {
+			return
+		}
+		a.removeBotLocked(robot.MemberID)
+	}
+
+	bot := dtapi.NewBot(dtConf.ClientID, dtConf.ClientSecret)
+
+	streamCtx, streamCancel := context.WithCancel(context.Background())
+	entry := &botEntry{
+		robotID:  robot.MemberID,
+		clientID: dtConf.ClientID,
+		bot:      bot,
+		cancelFn: streamCancel,
+	}
+	a.bots[robot.MemberID] = entry
+	a.appIdx[dtConf.ClientID] = robot.MemberID
+
+	go a.streamLoop(streamCtx, entry)
+
+	log.Info("dingtalk adapter: registered robot=%s client=%s", robot.MemberID, dtConf.ClientID)
+}
+
+// Remove is called by the Dispatcher when a robot is deleted.
+func (a *Adapter) Remove(ctx context.Context, robotID string) {
+	a.removeBot(robotID)
+}
+
+// Shutdown stops all stream connections and dedup cleaner.
+func (a *Adapter) Shutdown() {
+	close(a.stopCh)
+	a.mu.Lock()
+	for _, entry := range a.bots {
+		if entry.cancelFn != nil {
+			entry.cancelFn()
+		}
+	}
+	a.mu.Unlock()
+	log.Info("dingtalk adapter: shutdown complete")
+}
+
+func (a *Adapter) removeBot(robotID string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.removeBotLocked(robotID)
+}
+
+func (a *Adapter) removeBotLocked(robotID string) {
+	entry, ok := a.bots[robotID]
+	if !ok {
+		return
+	}
+	if entry.cancelFn != nil {
+		entry.cancelFn()
+	}
+	if entry.clientID != "" {
+		delete(a.appIdx, entry.clientID)
+	}
+	delete(a.bots, robotID)
+	log.Info("dingtalk adapter: unregistered robot=%s", robotID)
+}
+
+func (a *Adapter) resolveByClientID(clientID string) (*botEntry, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	robotID, ok := a.appIdx[clientID]
+	if !ok {
+		return nil, false
+	}
+	entry, ok := a.bots[robotID]
+	return entry, ok
+}
+
+func extractConfig(robot *robottypes.Robot) *robottypes.DingTalkConfig {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return nil
+	}
+	return robot.Config.Integrations.DingTalk
+}

agent/robot/events/integrations/dingtalk/e2e_test.go

@@ -0,0 +1,217 @@
+package dingtalk
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	dtapi "github.com/yaoapp/yao/integrations/dingtalk"
+)
+
+var (
+	dtClientID     string
+	dtClientSecret string
+)
+
+func TestMain(m *testing.M) {
+	dtClientID = os.Getenv("DINGTALK_TEST_CLIENT_ID")
+	dtClientSecret = os.Getenv("DINGTALK_TEST_CLIENT_SECRET")
+	os.Exit(m.Run())
+}
+
+func skipIfNoCreds(t *testing.T) {
+	t.Helper()
+	if dtClientID == "" || dtClientSecret == "" {
+		t.Skip("DINGTALK_TEST_CLIENT_ID or DINGTALK_TEST_CLIENT_SECRET not set")
+	}
+}
+
+// TestE2E_Adapter_Apply verifies that Apply correctly registers a bot.
+func TestE2E_Adapter_Apply(t *testing.T) {
+	skipIfNoCreds(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_dt_adapter",
+		TeamID:   "team_e2e_dt",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				DingTalk: &robottypes.DingTalkConfig{
+					Enabled:      true,
+					ClientID:     dtClientID,
+					ClientSecret: dtClientSecret,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+
+	a.mu.RLock()
+	entry, ok := a.bots["robot_e2e_dt_adapter"]
+	a.mu.RUnlock()
+
+	require.True(t, ok, "bot should be registered")
+	assert.Equal(t, dtClientID, entry.clientID)
+	assert.NotNil(t, entry.bot)
+
+	t.Logf("OK  Apply: dingtalk bot registered robot=%s client=%s", robot.MemberID, entry.clientID)
+}
+
+// TestE2E_Adapter_Apply_Update verifies re-Apply with same clientID is a no-op.
+func TestE2E_Adapter_Apply_Update(t *testing.T) {
+	skipIfNoCreds(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_dt_update",
+		TeamID:   "team_e2e_dt",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				DingTalk: &robottypes.DingTalkConfig{
+					Enabled:      true,
+					ClientID:     dtClientID,
+					ClientSecret: dtClientSecret,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_dt_update"]
+	a.mu.RUnlock()
+	require.True(t, ok)
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	assert.Len(t, a.bots, 1)
+	a.mu.RUnlock()
+
+	a.Remove(context.Background(), "robot_e2e_dt_update")
+	a.mu.RLock()
+	_, ok = a.bots["robot_e2e_dt_update"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "bot should be removed")
+	t.Log("OK  Apply/Remove lifecycle verified")
+}
+
+// TestE2E_Adapter_Dedup verifies deduplication works.
+func TestE2E_Adapter_Dedup(t *testing.T) {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	key := "dt:test-robot:msg-12345"
+	assert.True(t, a.dedup.markSeen(key), "first time should return true")
+	assert.False(t, a.dedup.markSeen(key), "second time should return false (dedup)")
+	t.Log("OK  dedup working correctly")
+}
+
+// TestE2E_Adapter_HandleMessages verifies message handling through the adapter.
+func TestE2E_Adapter_HandleMessages(t *testing.T) {
+	skipIfNoCreds(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	entry := &botEntry{
+		robotID:  "robot_e2e_dt_handle",
+		clientID: dtClientID,
+		bot:      dtapi.NewBot(dtClientID, dtClientSecret),
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cms := []*dtapi.ConvertedMessage{
+		{
+			MessageID:        "test_msg_1",
+			ConversationID:   "test_conv_1",
+			ConversationType: "1",
+			SenderID:         "test_sender_1",
+			SenderNick:       "Test User",
+			Text:             "Hello from E2E test",
+			SessionWebhook:   "https://oapi.dingtalk.com/robot/sendBySession/xxx",
+		},
+	}
+
+	a.handleMessages(ctx, entry, cms)
+
+	assert.False(t, a.dedup.markSeen("dt:robot_e2e_dt_handle:test_msg_1"),
+		"message should be marked as seen after handleMessages")
+	t.Log("OK  handleMessages processed 1 message")
+}
+
+// TestE2E_Adapter_ApplyDisabled verifies Apply removes bot when disabled.
+func TestE2E_Adapter_ApplyDisabled(t *testing.T) {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_dt_disabled",
+		TeamID:   "team_e2e_dt",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				DingTalk: &robottypes.DingTalkConfig{
+					Enabled:      false,
+					ClientID:     "some_id",
+					ClientSecret: "some_secret",
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_dt_disabled"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "disabled bot should not be registered")
+	t.Log("OK  disabled config not registered")
+}
+
+// TestE2E_Adapter_GetAccessToken verifies real DingTalk credentials work.
+func TestE2E_Adapter_GetAccessToken(t *testing.T) {
+	skipIfNoCreds(t)
+
+	b := dtapi.NewBot(dtClientID, dtClientSecret)
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	token, err := b.GetAccessToken(ctx)
+	require.NoError(t, err)
+	assert.NotEmpty(t, token)
+	t.Logf("OK  DingTalk access token obtained, len=%d", len(token))
+}

agent/robot/events/integrations/dingtalk/message.go

@@ -0,0 +1,126 @@
+package dingtalk
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/event"
+	dtapi "github.com/yaoapp/yao/integrations/dingtalk"
+)
+
+// handleMessages processes a batch of DingTalk messages.
+func (a *Adapter) handleMessages(ctx context.Context, entry *botEntry, cms []*dtapi.ConvertedMessage) {
+	if len(cms) == 0 {
+		return
+	}
+
+	var allParts []interface{}
+	var lastCM *dtapi.ConvertedMessage
+
+	for _, cm := range cms {
+		if cm == nil {
+			continue
+		}
+
+		dedupKey := fmt.Sprintf("dt:%s:%s", entry.robotID, cm.MessageID)
+		if !a.dedup.markSeen(dedupKey) {
+			continue
+		}
+
+		parts := buildContentParts(cm)
+		if len(parts) == 0 {
+			continue
+		}
+
+		allParts = append(allParts, parts...)
+		lastCM = cm
+	}
+
+	if len(allParts) == 0 || lastCM == nil {
+		return
+	}
+
+	content := mergeContentParts(allParts)
+
+	msgPayload := events.MessagePayload{
+		RobotID: entry.robotID,
+		Messages: []agentcontext.Message{
+			{Role: agentcontext.RoleUser, Content: content},
+		},
+		Metadata: &events.MessageMetadata{
+			Channel:    "dingtalk",
+			MessageID:  lastCM.MessageID,
+			AppID:      entry.clientID,
+			ChatID:     lastCM.ConversationID,
+			SenderID:   lastCM.SenderID,
+			SenderName: lastCM.SenderNick,
+			Locale:     "zh-cn",
+			Extra: map[string]any{
+				"session_webhook":   lastCM.SessionWebhook,
+				"conversation_type": lastCM.ConversationType,
+				"dt_message_id":     lastCM.MessageID,
+			},
+		},
+	}
+
+	if _, err := event.Push(ctx, events.Message, msgPayload); err != nil {
+		log.Error("dingtalk adapter: event.Push robot.message failed robot=%s: %v", entry.robotID, err)
+	}
+}
+
+func buildContentParts(cm *dtapi.ConvertedMessage) []interface{} {
+	var parts []interface{}
+
+	if cm.HasText() {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": cm.Text,
+		})
+	}
+
+	for _, mi := range cm.MediaItems {
+		if mi.Wrapper == "" && mi.URL == "" {
+			continue
+		}
+		url := mi.Wrapper
+		if url == "" {
+			url = mi.URL
+		}
+		parts = append(parts, map[string]interface{}{
+			"type":      "file",
+			"file_url":  url,
+			"mime_type": mi.MimeType,
+			"file_name": mi.FileName,
+		})
+	}
+
+	return parts
+}
+
+func mergeContentParts(parts []interface{}) interface{} {
+	allText := true
+	for _, p := range parts {
+		m, ok := p.(map[string]interface{})
+		if !ok || m["type"] != "text" {
+			allText = false
+			break
+		}
+	}
+
+	if allText {
+		var buf strings.Builder
+		for i, p := range parts {
+			if i > 0 {
+				buf.WriteString("\n")
+			}
+			m := p.(map[string]interface{})
+			buf.WriteString(m["text"].(string))
+		}
+		return buf.String()
+	}
+
+	return parts
+}

agent/robot/events/integrations/dingtalk/reply.go

@@ -0,0 +1,146 @@
+package dingtalk
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	dtapi "github.com/yaoapp/yao/integrations/dingtalk"
+)
+
+// Reply sends the assistant message back to the originating DingTalk conversation.
+func (a *Adapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if msg == nil || metadata == nil {
+		return fmt.Errorf("nil message or metadata")
+	}
+
+	var sessionWebhook string
+	if metadata.Extra != nil {
+		if v, ok := metadata.Extra["session_webhook"]; ok {
+			if s, ok := v.(string); ok {
+				sessionWebhook = s
+			}
+		}
+	}
+
+	if sessionWebhook == "" {
+		return fmt.Errorf("no session_webhook in metadata for dingtalk reply")
+	}
+
+	return sendContent(ctx, sessionWebhook, msg.Content)
+}
+
+func sendContent(ctx context.Context, sessionWebhook string, content interface{}) error {
+	switch c := content.(type) {
+	case string:
+		if strings.TrimSpace(c) == "" {
+			return nil
+		}
+		return dtapi.SendMarkdownMessage(ctx, sessionWebhook, "Reply", dtapi.FormatDingTalkMarkdown(c))
+
+	case []interface{}:
+		return sendParts(ctx, sessionWebhook, c)
+
+	default:
+		parts, ok := toContentParts(content)
+		if ok {
+			return sendPartsTyped(ctx, sessionWebhook, parts)
+		}
+		return dtapi.SendTextMessage(ctx, sessionWebhook, fmt.Sprintf("%v", content))
+	}
+}
+
+func sendParts(ctx context.Context, sessionWebhook string, parts []interface{}) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		m, ok := part.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		partType, _ := m["type"].(string)
+		switch partType {
+		case "text":
+			if text, ok := m["text"].(string); ok {
+				textBuf.WriteString(text)
+			}
+		case "image_url":
+			if err := flushText(ctx, sessionWebhook, &textBuf); err != nil {
+				return err
+			}
+			if imgMap, ok := m["image_url"].(map[string]interface{}); ok {
+				if url, ok := imgMap["url"].(string); ok {
+					if strings.HasPrefix(url, "http") {
+						textBuf.WriteString(fmt.Sprintf("\n![image](%s)\n", url))
+					}
+				}
+			}
+		case "file":
+			if err := flushText(ctx, sessionWebhook, &textBuf); err != nil {
+				return err
+			}
+			fileURL, _ := m["file_url"].(string)
+			fileName, _ := m["file_name"].(string)
+			if fileURL == "" {
+				if fileMap, ok := m["file"].(map[string]interface{}); ok {
+					fileURL, _ = fileMap["url"].(string)
+					if fn, ok := fileMap["filename"].(string); ok && fn != "" {
+						fileName = fn
+					}
+				}
+			}
+			if fileURL != "" && strings.HasPrefix(fileURL, "http") {
+				label := fileName
+				if label == "" {
+					label = "file"
+				}
+				textBuf.WriteString(fmt.Sprintf("\n[%s](%s)\n", label, fileURL))
+			}
+		}
+	}
+	return flushText(ctx, sessionWebhook, &textBuf)
+}
+
+func sendPartsTyped(ctx context.Context, sessionWebhook string, parts []agentcontext.ContentPart) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		switch part.Type {
+		case agentcontext.ContentText:
+			textBuf.WriteString(part.Text)
+		case agentcontext.ContentImageURL:
+			if err := flushText(ctx, sessionWebhook, &textBuf); err != nil {
+				return err
+			}
+			if part.ImageURL != nil && strings.HasPrefix(part.ImageURL.URL, "http") {
+				textBuf.WriteString(fmt.Sprintf("\n![image](%s)\n", part.ImageURL.URL))
+			}
+		case agentcontext.ContentFile:
+			if err := flushText(ctx, sessionWebhook, &textBuf); err != nil {
+				return err
+			}
+			if part.File != nil && part.File.URL != "" && strings.HasPrefix(part.File.URL, "http") {
+				label := part.File.Filename
+				if label == "" {
+					label = "file"
+				}
+				textBuf.WriteString(fmt.Sprintf("\n[%s](%s)\n", label, part.File.URL))
+			}
+		}
+	}
+	return flushText(ctx, sessionWebhook, &textBuf)
+}
+
+func flushText(ctx context.Context, sessionWebhook string, buf *strings.Builder) error {
+	if buf.Len() == 0 {
+		return nil
+	}
+	text := buf.String()
+	buf.Reset()
+	return dtapi.SendMarkdownMessage(ctx, sessionWebhook, "Reply", dtapi.FormatDingTalkMarkdown(text))
+}
+
+func toContentParts(content interface{}) ([]agentcontext.ContentPart, bool) {
+	parts, ok := content.([]agentcontext.ContentPart)
+	return parts, ok
+}

agent/robot/events/integrations/dingtalk/stream.go

@@ -0,0 +1,98 @@
+package dingtalk
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	dingstream "github.com/open-dingtalk/dingtalk-stream-sdk-go/chatbot"
+	dingclient "github.com/open-dingtalk/dingtalk-stream-sdk-go/client"
+	dtapi "github.com/yaoapp/yao/integrations/dingtalk"
+)
+
+const reconnectDelay = 5 * time.Second
+
+// streamLoop starts the DingTalk Stream client for a single bot.
+// It automatically reconnects on failure.
+func (a *Adapter) streamLoop(ctx context.Context, entry *botEntry) {
+	log.Info("dingtalk streamLoop started robot=%s client=%s", entry.robotID, entry.clientID)
+
+	for {
+		select {
+		case <-ctx.Done():
+			log.Info("dingtalk streamLoop stopped robot=%s", entry.robotID)
+			return
+		case <-a.stopCh:
+			return
+		default:
+		}
+
+		err := a.runStreamClient(ctx, entry)
+		if err != nil {
+			log.Error("dingtalk stream disconnected robot=%s: %v, reconnecting in %s", entry.robotID, err, reconnectDelay)
+		}
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-a.stopCh:
+			return
+		case <-time.After(reconnectDelay):
+		}
+	}
+}
+
+func (a *Adapter) runStreamClient(ctx context.Context, entry *botEntry) error {
+	cli := dingclient.NewStreamClient(
+		dingclient.WithAppCredential(dingclient.NewAppCredentialConfig(entry.clientID, entry.bot.ClientSecret())),
+	)
+
+	cli.RegisterChatBotCallbackRouter(func(c context.Context, data *dingstream.BotCallbackDataModel) ([]byte, error) {
+		return a.onBotCallback(c, entry, data)
+	})
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- cli.Start(ctx)
+	}()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-a.stopCh:
+		return nil
+	case err := <-errCh:
+		return err
+	}
+}
+
+func (a *Adapter) onBotCallback(ctx context.Context, entry *botEntry, data *dingstream.BotCallbackDataModel) ([]byte, error) {
+	if data == nil {
+		return nil, nil
+	}
+
+	cm := &dtapi.ConvertedMessage{
+		MessageID:        data.MsgId,
+		ConversationID:   data.ConversationId,
+		ConversationType: data.ConversationType,
+		SenderID:         data.SenderId,
+		SenderNick:       data.SenderNick,
+		SenderStaffID:    data.SenderStaffId,
+		ChatbotUserID:    data.ChatbotUserId,
+		IsInAtList:       data.IsInAtList,
+		SessionWebhook:   data.SessionWebhook,
+	}
+
+	switch data.Msgtype {
+	case "text":
+		cm.Text = strings.TrimSpace(data.Text.Content)
+	}
+
+	if cm.HasMedia() {
+		groups := []string{"dingtalk", entry.robotID}
+		dtapi.ResolveMedia(ctx, cm, groups)
+	}
+
+	a.handleMessages(ctx, entry, []*dtapi.ConvertedMessage{cm})
+	return nil, nil
+}

agent/robot/events/integrations/discord/dedup.go

@@ -0,0 +1,44 @@
+package discord
+
+import (
+	"sync"
+	"time"
+)
+
+const (
+	dedupTTL           = 24 * time.Hour
+	dedupCleanInterval = time.Hour
+)
+
+type dedupStore struct {
+	m sync.Map
+}
+
+func newDedupStore() *dedupStore {
+	return &dedupStore{}
+}
+
+func (d *dedupStore) markSeen(key string) bool {
+	now := time.Now().Unix()
+	_, loaded := d.m.LoadOrStore(key, now)
+	return !loaded
+}
+
+func (d *dedupStore) cleaner(stopCh <-chan struct{}) {
+	ticker := time.NewTicker(dedupCleanInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-stopCh:
+			return
+		case <-ticker.C:
+			cutoff := time.Now().Add(-dedupTTL).Unix()
+			d.m.Range(func(key, value any) bool {
+				if ts, ok := value.(int64); ok && ts < cutoff {
+					d.m.Delete(key)
+				}
+				return true
+			})
+		}
+	}
+}

agent/robot/events/integrations/discord/discord.go

@@ -0,0 +1,151 @@
+package discord
+
+import (
+	"context"
+	"sync"
+
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	dcapi "github.com/yaoapp/yao/integrations/discord"
+)
+
+var log = logger.New("discord")
+
+// Adapter implements the integrations.Adapter interface for Discord.
+//
+// Architecture:
+//   - One WebSocket Gateway connection per registered bot via discordgo
+//   - One dedup cleaner goroutine removes expired keys every hour
+type Adapter struct {
+	mu     sync.RWMutex
+	bots   map[string]*botEntry // robotID -> *botEntry
+	appIdx map[string]string    // appID  -> robotID
+	dedup  *dedupStore
+	stopCh chan struct{}
+}
+
+// botEntry holds the state for one robot's Discord integration.
+type botEntry struct {
+	robotID  string
+	appID    string
+	bot      *dcapi.Bot
+	cancelFn context.CancelFunc
+}
+
+// NewAdapter creates a new Discord adapter.
+func NewAdapter() *Adapter {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	go a.dedup.cleaner(a.stopCh)
+	return a
+}
+
+// Apply is called by the Dispatcher when a robot config is created or updated.
+func (a *Adapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	dcConf := extractConfig(robot)
+	log.Debug("Apply robot=%s dcConf=%v", robot.MemberID, dcConf != nil)
+
+	if dcConf == nil || !dcConf.Enabled || dcConf.BotToken == "" {
+		a.removeBot(robot.MemberID)
+		return
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if existing, ok := a.bots[robot.MemberID]; ok {
+		if existing.bot.Token() == dcConf.BotToken {
+			return
+		}
+		a.removeBotLocked(robot.MemberID)
+	}
+
+	bot, err := dcapi.NewBot(dcConf.BotToken, dcConf.AppID)
+	if err != nil {
+		log.Error("discord adapter: create bot failed robot=%s: %v", robot.MemberID, err)
+		return
+	}
+
+	gwCtx, gwCancel := context.WithCancel(context.Background())
+	entry := &botEntry{
+		robotID:  robot.MemberID,
+		appID:    dcConf.AppID,
+		bot:      bot,
+		cancelFn: gwCancel,
+	}
+	a.bots[robot.MemberID] = entry
+	if dcConf.AppID != "" {
+		a.appIdx[dcConf.AppID] = robot.MemberID
+	}
+
+	go a.gatewayLoop(gwCtx, entry)
+
+	log.Info("discord adapter: registered robot=%s app=%s", robot.MemberID, dcConf.AppID)
+}
+
+// Remove is called by the Dispatcher when a robot is deleted.
+func (a *Adapter) Remove(ctx context.Context, robotID string) {
+	a.removeBot(robotID)
+}
+
+// Shutdown stops all gateway connections and dedup cleaner.
+func (a *Adapter) Shutdown() {
+	close(a.stopCh)
+	a.mu.Lock()
+	for _, entry := range a.bots {
+		if entry.cancelFn != nil {
+			entry.cancelFn()
+		}
+		if entry.bot != nil && entry.bot.Session() != nil {
+			entry.bot.Session().Close()
+		}
+	}
+	a.mu.Unlock()
+	log.Info("discord adapter: shutdown complete")
+}
+
+func (a *Adapter) removeBot(robotID string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.removeBotLocked(robotID)
+}
+
+func (a *Adapter) removeBotLocked(robotID string) {
+	entry, ok := a.bots[robotID]
+	if !ok {
+		return
+	}
+	if entry.cancelFn != nil {
+		entry.cancelFn()
+	}
+	if entry.bot != nil && entry.bot.Session() != nil {
+		entry.bot.Session().Close()
+	}
+	if entry.appID != "" {
+		delete(a.appIdx, entry.appID)
+	}
+	delete(a.bots, robotID)
+	log.Info("discord adapter: unregistered robot=%s", robotID)
+}
+
+func (a *Adapter) resolveByAppID(appID string) (*botEntry, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	robotID, ok := a.appIdx[appID]
+	if !ok {
+		return nil, false
+	}
+	entry, ok := a.bots[robotID]
+	return entry, ok
+}
+
+func extractConfig(robot *robottypes.Robot) *robottypes.DiscordConfig {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return nil
+	}
+	return robot.Config.Integrations.Discord
+}

agent/robot/events/integrations/discord/e2e_test.go

@@ -0,0 +1,218 @@
+package discord
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	dcapi "github.com/yaoapp/yao/integrations/discord"
+)
+
+var (
+	dcBotToken string
+	dcAppID    string
+)
+
+func TestMain(m *testing.M) {
+	dcBotToken = os.Getenv("DISCORD_TEST_BOT_TOKEN")
+	dcAppID = os.Getenv("DISCORD_TEST_APP_ID")
+	os.Exit(m.Run())
+}
+
+func skipIfNoToken(t *testing.T) {
+	t.Helper()
+	if dcBotToken == "" {
+		t.Skip("DISCORD_TEST_BOT_TOKEN not set")
+	}
+}
+
+// TestE2E_Adapter_Apply verifies that Apply correctly registers a bot.
+func TestE2E_Adapter_Apply(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_dc_adapter",
+		TeamID:   "team_e2e_dc",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Discord: &robottypes.DiscordConfig{
+					Enabled:  true,
+					BotToken: dcBotToken,
+					AppID:    dcAppID,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+
+	a.mu.RLock()
+	entry, ok := a.bots["robot_e2e_dc_adapter"]
+	a.mu.RUnlock()
+
+	require.True(t, ok, "bot should be registered")
+	assert.Equal(t, dcBotToken, entry.bot.Token())
+	assert.Equal(t, dcAppID, entry.appID)
+
+	t.Logf("OK  Apply: discord bot registered robot=%s app=%s", robot.MemberID, entry.appID)
+}
+
+// TestE2E_Adapter_Apply_Update verifies re-Apply with same token is a no-op.
+func TestE2E_Adapter_Apply_Update(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_dc_update",
+		TeamID:   "team_e2e_dc",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Discord: &robottypes.DiscordConfig{
+					Enabled:  true,
+					BotToken: dcBotToken,
+					AppID:    dcAppID,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_dc_update"]
+	a.mu.RUnlock()
+	require.True(t, ok)
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	assert.Len(t, a.bots, 1)
+	a.mu.RUnlock()
+
+	a.Remove(context.Background(), "robot_e2e_dc_update")
+	a.mu.RLock()
+	_, ok = a.bots["robot_e2e_dc_update"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "bot should be removed")
+	t.Log("OK  Apply/Remove lifecycle verified")
+}
+
+// TestE2E_Adapter_Dedup verifies deduplication works.
+func TestE2E_Adapter_Dedup(t *testing.T) {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	key := "dc:test-robot:msg-12345"
+	assert.True(t, a.dedup.markSeen(key), "first time should return true")
+	assert.False(t, a.dedup.markSeen(key), "second time should return false (dedup)")
+	t.Log("OK  dedup working correctly")
+}
+
+// TestE2E_Adapter_HandleMessages verifies message handling.
+func TestE2E_Adapter_HandleMessages(t *testing.T) {
+	skipIfNoToken(t)
+
+	bot, err := dcapi.NewBot(dcBotToken, dcAppID)
+	require.NoError(t, err)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	entry := &botEntry{
+		robotID: "robot_e2e_dc_handle",
+		appID:   dcAppID,
+		bot:     bot,
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cms := []*dcapi.ConvertedMessage{
+		{
+			MessageID:  "test_msg_1",
+			ChannelID:  "test_ch_1",
+			AuthorID:   "test_user_1",
+			AuthorName: "TestUser",
+			Text:       "Hello from E2E test",
+		},
+	}
+
+	a.handleMessages(ctx, entry, cms)
+
+	assert.False(t, a.dedup.markSeen("dc:robot_e2e_dc_handle:test_msg_1"),
+		"message should be marked as seen after handleMessages")
+	t.Log("OK  handleMessages processed 1 message")
+}
+
+// TestE2E_Adapter_ApplyDisabled verifies Apply removes bot when disabled.
+func TestE2E_Adapter_ApplyDisabled(t *testing.T) {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_dc_disabled",
+		TeamID:   "team_e2e_dc",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Discord: &robottypes.DiscordConfig{
+					Enabled:  false,
+					BotToken: "some_token",
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_dc_disabled"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "disabled bot should not be registered")
+	t.Log("OK  disabled config not registered")
+}
+
+// TestE2E_BotUser verifies real Discord credentials.
+func TestE2E_BotUser(t *testing.T) {
+	skipIfNoToken(t)
+
+	bot, err := dcapi.NewBot(dcBotToken, dcAppID)
+	require.NoError(t, err)
+
+	user, err := bot.BotUser()
+	require.NoError(t, err)
+	assert.NotEmpty(t, user.ID)
+	assert.NotEmpty(t, user.Username)
+	assert.True(t, user.Bot)
+	t.Logf("OK  Discord bot verified: id=%s username=%s", user.ID, user.Username)
+}

agent/robot/events/integrations/discord/gateway.go

@@ -0,0 +1,84 @@
+package discord
+
+import (
+	"context"
+	"time"
+
+	"github.com/bwmarrin/discordgo"
+	dcapi "github.com/yaoapp/yao/integrations/discord"
+)
+
+const reconnectDelay = 5 * time.Second
+
+// gatewayLoop starts the Discord WebSocket Gateway for a single bot.
+// It automatically reconnects on failure.
+func (a *Adapter) gatewayLoop(ctx context.Context, entry *botEntry) {
+	log.Info("discord gatewayLoop started robot=%s app=%s", entry.robotID, entry.appID)
+
+	for {
+		select {
+		case <-ctx.Done():
+			log.Info("discord gatewayLoop stopped robot=%s", entry.robotID)
+			return
+		case <-a.stopCh:
+			return
+		default:
+		}
+
+		err := a.runGateway(ctx, entry)
+		if err != nil {
+			log.Error("discord gateway disconnected robot=%s: %v, reconnecting in %s", entry.robotID, err, reconnectDelay)
+		}
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-a.stopCh:
+			return
+		case <-time.After(reconnectDelay):
+		}
+	}
+}
+
+func (a *Adapter) runGateway(ctx context.Context, entry *botEntry) error {
+	session := entry.bot.Session()
+
+	session.AddHandler(func(s *discordgo.Session, m *discordgo.MessageCreate) {
+		a.onMessageCreate(ctx, entry, m)
+	})
+
+	if err := session.Open(); err != nil {
+		return err
+	}
+
+	// Block until context is cancelled or stop signal
+	select {
+	case <-ctx.Done():
+	case <-a.stopCh:
+	}
+
+	return session.Close()
+}
+
+func (a *Adapter) onMessageCreate(ctx context.Context, entry *botEntry, m *discordgo.MessageCreate) {
+	if m == nil || m.Author == nil {
+		return
+	}
+
+	// Ignore bot's own messages
+	if m.Author.Bot {
+		return
+	}
+
+	cm := dcapi.ConvertMessageCreate(m)
+	if cm == nil {
+		return
+	}
+
+	if cm.HasMedia() {
+		groups := []string{"discord", entry.robotID}
+		dcapi.ResolveMedia(ctx, cm, groups)
+	}
+
+	a.handleMessages(ctx, entry, []*dcapi.ConvertedMessage{cm})
+}

agent/robot/events/integrations/discord/message.go

@@ -0,0 +1,138 @@
+package discord
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/event"
+	dcapi "github.com/yaoapp/yao/integrations/discord"
+)
+
+// handleMessages processes a batch of Discord messages.
+func (a *Adapter) handleMessages(ctx context.Context, entry *botEntry, cms []*dcapi.ConvertedMessage) {
+	if len(cms) == 0 {
+		return
+	}
+
+	var allParts []interface{}
+	var lastCM *dcapi.ConvertedMessage
+
+	for _, cm := range cms {
+		if cm == nil {
+			continue
+		}
+
+		// Skip bot commands (messages starting with /)
+		if strings.HasPrefix(strings.TrimSpace(cm.Text), "/") && !cm.HasMedia() {
+			continue
+		}
+
+		dedupKey := fmt.Sprintf("dc:%s:%s", entry.robotID, cm.MessageID)
+		if !a.dedup.markSeen(dedupKey) {
+			continue
+		}
+
+		parts := buildContentParts(cm)
+		if len(parts) == 0 {
+			continue
+		}
+
+		allParts = append(allParts, parts...)
+		lastCM = cm
+	}
+
+	if len(allParts) == 0 || lastCM == nil {
+		return
+	}
+
+	content := mergeContentParts(allParts)
+
+	msgPayload := events.MessagePayload{
+		RobotID: entry.robotID,
+		Messages: []agentcontext.Message{
+			{Role: agentcontext.RoleUser, Content: content},
+		},
+		Metadata: &events.MessageMetadata{
+			Channel:    "discord",
+			MessageID:  lastCM.MessageID,
+			AppID:      entry.appID,
+			ChatID:     lastCM.ChannelID,
+			SenderID:   lastCM.AuthorID,
+			SenderName: lastCM.AuthorName,
+			Locale:     events.NormalizeLocale(discordLocale(lastCM.Locale)),
+			Extra: map[string]any{
+				"discord_message_id": lastCM.MessageID,
+				"guild_id":           lastCM.GuildID,
+				"is_dm":              lastCM.IsDM,
+			},
+		},
+	}
+
+	if _, err := event.Push(ctx, events.Message, msgPayload); err != nil {
+		log.Error("discord adapter: event.Push robot.message failed robot=%s: %v", entry.robotID, err)
+	}
+}
+
+func buildContentParts(cm *dcapi.ConvertedMessage) []interface{} {
+	var parts []interface{}
+
+	if cm.HasText() {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": cm.Text,
+		})
+	}
+
+	for _, mi := range cm.MediaItems {
+		url := mi.Wrapper
+		if url == "" {
+			url = mi.URL
+		}
+		if url == "" {
+			continue
+		}
+		parts = append(parts, map[string]interface{}{
+			"type":      "file",
+			"file_url":  url,
+			"mime_type": mi.ContentType,
+			"file_name": mi.FileName,
+		})
+	}
+
+	return parts
+}
+
+func mergeContentParts(parts []interface{}) interface{} {
+	allText := true
+	for _, p := range parts {
+		m, ok := p.(map[string]interface{})
+		if !ok || m["type"] != "text" {
+			allText = false
+			break
+		}
+	}
+
+	if allText {
+		var buf strings.Builder
+		for i, p := range parts {
+			if i > 0 {
+				buf.WriteString("\n")
+			}
+			m := p.(map[string]interface{})
+			buf.WriteString(m["text"].(string))
+		}
+		return buf.String()
+	}
+
+	return parts
+}
+
+func discordLocale(locale string) string {
+	if locale == "" {
+		return "en"
+	}
+	return locale
+}

agent/robot/events/integrations/discord/reply.go

@@ -0,0 +1,179 @@
+package discord
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	dcapi "github.com/yaoapp/yao/integrations/discord"
+)
+
+// Reply sends the assistant message back to the originating Discord channel.
+func (a *Adapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if msg == nil || metadata == nil {
+		return fmt.Errorf("nil message or metadata")
+	}
+
+	entry := a.resolveByChat(metadata)
+	if entry == nil {
+		return fmt.Errorf("no bot registered for discord metadata (appID=%s)", metadata.AppID)
+	}
+
+	var replyToID string
+	if metadata.Extra != nil {
+		if v, ok := metadata.Extra["discord_message_id"]; ok {
+			if s, ok := v.(string); ok {
+				replyToID = s
+			}
+		}
+	}
+
+	return a.sendContent(ctx, entry, metadata.ChatID, replyToID, msg.Content)
+}
+
+func (a *Adapter) sendContent(ctx context.Context, entry *botEntry, channelID, replyToID string, content interface{}) error {
+	switch c := content.(type) {
+	case string:
+		if strings.TrimSpace(c) == "" {
+			return nil
+		}
+		formatted := dcapi.FormatDiscordMarkdown(c)
+		if replyToID != "" {
+			_, err := entry.bot.SendMessageReply(channelID, formatted, replyToID)
+			return err
+		}
+		_, err := entry.bot.SendMessage(channelID, formatted)
+		return err
+
+	case []interface{}:
+		return a.sendParts(ctx, entry, channelID, replyToID, c)
+
+	default:
+		parts, ok := toContentParts(content)
+		if ok {
+			return a.sendPartsTyped(ctx, entry, channelID, replyToID, parts)
+		}
+		_, err := entry.bot.SendMessage(channelID, fmt.Sprintf("%v", content))
+		return err
+	}
+}
+
+func (a *Adapter) sendParts(ctx context.Context, entry *botEntry, channelID, replyToID string, parts []interface{}) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		m, ok := part.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		partType, _ := m["type"].(string)
+		switch partType {
+		case "text":
+			if text, ok := m["text"].(string); ok {
+				textBuf.WriteString(text)
+			}
+		case "image_url":
+			if err := a.flushText(entry, channelID, replyToID, &textBuf); err != nil {
+				return err
+			}
+			if imgMap, ok := m["image_url"].(map[string]interface{}); ok {
+				if url, ok := imgMap["url"].(string); ok {
+					if err := sendFileOrWrapper(entry, channelID, url, ""); err != nil {
+						log.Error("discord reply: send image: %v", err)
+					}
+				}
+			}
+		case "file":
+			if err := a.flushText(entry, channelID, replyToID, &textBuf); err != nil {
+				return err
+			}
+			fileURL, _ := m["file_url"].(string)
+			if fileURL == "" {
+				if fileMap, ok := m["file"].(map[string]interface{}); ok {
+					fileURL, _ = fileMap["url"].(string)
+				}
+			}
+			if fileURL != "" {
+				if err := sendFileOrWrapper(entry, channelID, fileURL, ""); err != nil {
+					log.Error("discord reply: send file: %v", err)
+				}
+			}
+		}
+	}
+	return a.flushText(entry, channelID, replyToID, &textBuf)
+}
+
+func (a *Adapter) sendPartsTyped(ctx context.Context, entry *botEntry, channelID, replyToID string, parts []agentcontext.ContentPart) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		switch part.Type {
+		case agentcontext.ContentText:
+			textBuf.WriteString(part.Text)
+		case agentcontext.ContentImageURL:
+			if err := a.flushText(entry, channelID, replyToID, &textBuf); err != nil {
+				return err
+			}
+			if part.ImageURL != nil {
+				if err := sendFileOrWrapper(entry, channelID, part.ImageURL.URL, ""); err != nil {
+					log.Error("discord reply: send image: %v", err)
+				}
+			}
+		case agentcontext.ContentFile:
+			if err := a.flushText(entry, channelID, replyToID, &textBuf); err != nil {
+				return err
+			}
+			if part.File != nil {
+				if err := sendFileOrWrapper(entry, channelID, part.File.URL, part.File.Filename); err != nil {
+					log.Error("discord reply: send file: %v", err)
+				}
+			}
+		}
+	}
+	return a.flushText(entry, channelID, replyToID, &textBuf)
+}
+
+func (a *Adapter) flushText(entry *botEntry, channelID, replyToID string, buf *strings.Builder) error {
+	if buf.Len() == 0 {
+		return nil
+	}
+	text := dcapi.FormatDiscordMarkdown(buf.String())
+	buf.Reset()
+
+	if replyToID != "" {
+		_, err := entry.bot.SendMessageReply(channelID, text, replyToID)
+		return err
+	}
+	_, err := entry.bot.SendMessage(channelID, text)
+	return err
+}
+
+func sendFileOrWrapper(entry *botEntry, channelID, url, caption string) error {
+	if strings.Contains(url, "://") && !strings.HasPrefix(url, "http") {
+		return entry.bot.SendMediaFromWrapper(channelID, url, caption)
+	}
+	if strings.HasPrefix(url, "http") {
+		_, err := entry.bot.SendMessage(channelID, url)
+		return err
+	}
+	return fmt.Errorf("unsupported file URL scheme: %s", url)
+}
+
+func toContentParts(content interface{}) ([]agentcontext.ContentPart, bool) {
+	parts, ok := content.([]agentcontext.ContentPart)
+	return parts, ok
+}
+
+func (a *Adapter) resolveByChat(metadata *events.MessageMetadata) *botEntry {
+	if metadata.AppID != "" {
+		if entry, ok := a.resolveByAppID(metadata.AppID); ok {
+			return entry
+		}
+	}
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	for _, entry := range a.bots {
+		return entry
+	}
+	return nil
+}

agent/robot/events/integrations/dispatcher.go

@@ -0,0 +1,235 @@
+package integrations
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/yaoapp/gou/model"
+	"github.com/yaoapp/kun/maps"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robotcache "github.com/yaoapp/yao/agent/robot/cache"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+)
+
+var log = logger.New("dispatcher")
+
+// Adapter is the interface each platform adapter implements.
+type Adapter interface {
+	Apply(ctx context.Context, robot *robottypes.Robot)
+	Remove(ctx context.Context, robotID string)
+	Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error
+}
+
+// Dispatcher distributes Robot integration configs to platform adapters.
+type Dispatcher struct {
+	robotCache *robotcache.Cache
+	adapters   map[string]Adapter // key matches Integrations field: "telegram", "discord", etc.
+	stopCh     chan struct{}
+	subID      string
+}
+
+// NewDispatcher creates a Dispatcher.
+// Each adapter has a fixed key matching the field name in robottypes.Integrations.
+func NewDispatcher(cache *robotcache.Cache, adapters map[string]Adapter) *Dispatcher {
+	return &Dispatcher{
+		robotCache: cache,
+		adapters:   adapters,
+		stopCh:     make(chan struct{}),
+	}
+}
+
+// Start loads all robots and subscribes to config change events.
+func (d *Dispatcher) Start(ctx context.Context) error {
+	d.loadAll(ctx)
+
+	events.RegisterReplyFunc(d.reply)
+
+	ch := make(chan *eventtypes.Event, 64)
+	d.subID = event.Subscribe("robot.config.*", ch)
+	go d.watch(ctx, ch)
+
+	log.Info("integration dispatcher: started with %d adapters", len(d.adapters))
+	return nil
+}
+
+// reply routes a reply to the correct adapter based on channel.
+// When channel is empty (e.g. delivery), broadcasts to all adapters.
+func (d *Dispatcher) reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if metadata == nil {
+		return fmt.Errorf("no metadata in reply")
+	}
+
+	if metadata.Channel != "" {
+		adapter, ok := d.adapters[metadata.Channel]
+		if !ok {
+			return fmt.Errorf("no adapter for channel: %s", metadata.Channel)
+		}
+		return adapter.Reply(ctx, msg, metadata)
+	}
+
+	var lastErr error
+	for name, adapter := range d.adapters {
+		if err := adapter.Reply(ctx, msg, metadata); err != nil {
+			log.Error("dispatcher reply: broadcast to %s failed: %v", name, err)
+			lastErr = err
+		}
+	}
+	return lastErr
+}
+
+// Stop unsubscribes from events.
+func (d *Dispatcher) Stop() {
+	close(d.stopCh)
+	if d.subID != "" {
+		event.Unsubscribe(d.subID)
+	}
+	log.Info("integration dispatcher: stopped")
+}
+
+func (d *Dispatcher) loadAll(ctx context.Context) {
+	robots := d.loadIntegrationRobots()
+	for _, robot := range robots {
+		d.robotCache.Add(robot)
+		d.apply(ctx, robot)
+	}
+	log.Info("integration dispatcher: initial load complete, %d robots with integrations", len(robots))
+}
+
+// loadIntegrationRobots queries all active robots that have a non-null
+// robot_config (which may contain integrations). This is independent of
+// autonomous_mode so non-autonomous robots with Telegram etc. are included.
+func (d *Dispatcher) loadIntegrationRobots() []*robottypes.Robot {
+	m := model.Select("__yao.member")
+	fields := []interface{}{
+		"id", "member_id", "team_id", "display_name", "bio",
+		"system_prompt", "robot_status", "autonomous_mode",
+		"robot_config", "robot_email", "agents", "mcp_servers",
+		"manager_id", "language_model",
+	}
+
+	page := 1
+	pageSize := 100
+	var result []*robottypes.Robot
+
+	for {
+		res, err := m.Paginate(model.QueryParam{
+			Select: fields,
+			Wheres: []model.QueryWhere{
+				{Column: "member_type", Value: "robot"},
+				{Column: "status", Value: "active"},
+			},
+		}, page, pageSize)
+		if err != nil {
+			log.Error("loadIntegrationRobots: query failed page=%d: %v", page, err)
+			break
+		}
+
+		data, ok := res.Get("data").([]maps.MapStr)
+		if !ok || len(data) == 0 {
+			break
+		}
+
+		for _, record := range data {
+			robot, err := robottypes.NewRobotFromMap(map[string]interface{}(record))
+			if err != nil {
+				continue
+			}
+			if robot.Config != nil && robot.Config.Integrations != nil && len(parseIntegrations(robot.Config.Integrations)) > 0 {
+				result = append(result, robot)
+			}
+		}
+
+		total, _ := res.Get("total").(int)
+		if page*pageSize >= total {
+			break
+		}
+		page++
+	}
+
+	return result
+}
+
+// apply parses which integrations the robot has configured,
+// and calls the matching adapter for each one.
+func (d *Dispatcher) apply(ctx context.Context, robot *robottypes.Robot) {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return
+	}
+	for _, key := range parseIntegrations(robot.Config.Integrations) {
+		if adapter, ok := d.adapters[key]; ok {
+			adapter.Apply(ctx, robot)
+		}
+	}
+}
+
+func (d *Dispatcher) remove(ctx context.Context, robotID string) {
+	for _, adapter := range d.adapters {
+		adapter.Remove(ctx, robotID)
+	}
+}
+
+// parseIntegrations returns the keys of integrations present in the config.
+func parseIntegrations(intg *robottypes.Integrations) []string {
+	var keys []string
+	if intg.Telegram != nil {
+		keys = append(keys, "telegram")
+	}
+	if intg.Feishu != nil {
+		keys = append(keys, "feishu")
+	}
+	if intg.DingTalk != nil {
+		keys = append(keys, "dingtalk")
+	}
+	if intg.Discord != nil {
+		keys = append(keys, "discord")
+	}
+	return keys
+}
+
+func (d *Dispatcher) watch(ctx context.Context, ch <-chan *eventtypes.Event) {
+	for {
+		select {
+		case <-d.stopCh:
+			return
+		case <-ctx.Done():
+			return
+		case ev, ok := <-ch:
+			if !ok {
+				return
+			}
+			d.dispatch(ctx, ev)
+		}
+	}
+}
+
+func (d *Dispatcher) dispatch(ctx context.Context, ev *eventtypes.Event) {
+	var payload events.RobotConfigPayload
+	if err := ev.Should(&payload); err != nil {
+		log.Error("integration dispatcher: invalid config event: %v", err)
+		return
+	}
+
+	switch ev.Type {
+	case events.RobotConfigCreated, events.RobotConfigUpdated:
+		robot := d.robotCache.Get(payload.MemberID)
+		if robot == nil {
+			rCtx := robottypes.NewContext(ctx, nil)
+			loaded, err := d.robotCache.LoadByID(rCtx, payload.MemberID)
+			if err != nil {
+				log.Warn("integration dispatcher: failed to load robot from DB member=%s: %v", payload.MemberID, err)
+				return
+			}
+			d.robotCache.Add(loaded)
+			robot = loaded
+			log.Info("integration dispatcher: loaded robot from DB member=%s", payload.MemberID)
+		}
+		d.apply(ctx, robot)
+
+	case events.RobotConfigDeleted:
+		d.remove(ctx, payload.MemberID)
+	}
+}

agent/robot/events/integrations/dispatcher_test.go

@@ -0,0 +1,282 @@
+package integrations
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robotcache "github.com/yaoapp/yao/agent/robot/cache"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+)
+
+// mockAdapter records Apply/Remove calls for assertions.
+type mockAdapter struct {
+	mu      sync.Mutex
+	applied []*robottypes.Robot
+	removed []string
+}
+
+func (m *mockAdapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.applied = append(m.applied, robot)
+}
+
+func (m *mockAdapter) Remove(ctx context.Context, robotID string) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.removed = append(m.removed, robotID)
+}
+
+func (m *mockAdapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	return nil
+}
+
+func (m *mockAdapter) getApplied() []*robottypes.Robot {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	cp := make([]*robottypes.Robot, len(m.applied))
+	copy(cp, m.applied)
+	return cp
+}
+
+func (m *mockAdapter) getRemoved() []string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	cp := make([]string, len(m.removed))
+	copy(cp, m.removed)
+	return cp
+}
+
+// noopHandler satisfies event.Handler so we can register "robot" prefix for Push/Call.
+type noopHandler struct{}
+
+func (h *noopHandler) Handle(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	if ev.IsCall {
+		resp <- eventtypes.Result{}
+	}
+}
+func (h *noopHandler) Shutdown(ctx context.Context) error { return nil }
+
+var eventOnce sync.Once
+
+func setupEventBus(t *testing.T) {
+	t.Helper()
+	eventOnce.Do(func() {
+		event.Register("robot", &noopHandler{})
+	})
+	if err := event.Start(); err != nil && err != event.ErrAlreadyStart {
+		t.Fatalf("event.Start: %v", err)
+	}
+	t.Cleanup(func() { _ = event.Stop(context.Background()) })
+}
+
+func newRobot(memberID, teamID string, intg *robottypes.Integrations) *robottypes.Robot {
+	return &robottypes.Robot{
+		MemberID:       memberID,
+		TeamID:         teamID,
+		AutonomousMode: true,
+		Config: &robottypes.Config{
+			Integrations: intg,
+		},
+	}
+}
+
+func TestLoadAll_OnlyTelegramConfigured(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	tgRobot := newRobot("r-tg", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "tok"},
+	})
+	noIntgRobot := newRobot("r-plain", "team1", nil)
+	cache.Add(tgRobot)
+	cache.Add(noIntgRobot)
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	applied := tgAdapter.getApplied()
+	assert.Len(t, applied, 1)
+	assert.Equal(t, "r-tg", applied[0].MemberID)
+}
+
+func TestLoadAll_NoIntegrations(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	cache.Add(newRobot("r1", "team1", nil))
+	cache.Add(&robottypes.Robot{MemberID: "r2", TeamID: "team1"})
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Empty(t, tgAdapter.getApplied())
+}
+
+func TestLoadAll_MultipleAdapters(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	// Only Telegram configured, no Discord
+	robot := newRobot("r-multi", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "tok"},
+	})
+	cache.Add(robot)
+
+	tgAdapter := &mockAdapter{}
+	discordAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{
+		"telegram": tgAdapter,
+		"discord":  discordAdapter,
+	})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Len(t, tgAdapter.getApplied(), 1)
+	assert.Empty(t, discordAdapter.getApplied(), "discord adapter should not be called")
+}
+
+func TestConfigCreated_TriggersApply(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Empty(t, tgAdapter.getApplied())
+
+	// Simulate: robot created with Telegram config, added to cache, event pushed
+	robot := newRobot("r-new", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "new-tok"},
+	})
+	cache.Add(robot)
+	event.Push(context.Background(), events.RobotConfigCreated, events.RobotConfigPayload{
+		MemberID: "r-new", TeamID: "team1",
+	})
+
+	assert.Eventually(t, func() bool {
+		return len(tgAdapter.getApplied()) == 1
+	}, 2*time.Second, 50*time.Millisecond)
+
+	assert.Equal(t, "r-new", tgAdapter.getApplied()[0].MemberID)
+}
+
+func TestConfigUpdated_TriggersApply(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	robot := newRobot("r-upd", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "old-tok"},
+	})
+	cache.Add(robot)
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	// Initial load
+	assert.Len(t, tgAdapter.getApplied(), 1)
+
+	// Update config in cache
+	robot.Config.Integrations.Telegram.BotToken = "new-tok"
+	event.Push(context.Background(), events.RobotConfigUpdated, events.RobotConfigPayload{
+		MemberID: "r-upd", TeamID: "team1",
+	})
+
+	assert.Eventually(t, func() bool {
+		return len(tgAdapter.getApplied()) == 2
+	}, 2*time.Second, 50*time.Millisecond)
+
+	assert.Equal(t, "new-tok", tgAdapter.getApplied()[1].Config.Integrations.Telegram.BotToken)
+}
+
+func TestConfigDeleted_TriggersRemove(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	robot := newRobot("r-del", "team1", &robottypes.Integrations{
+		Telegram: &robottypes.TelegramConfig{Enabled: true, BotToken: "tok"},
+	})
+	cache.Add(robot)
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	assert.Len(t, tgAdapter.getApplied(), 1)
+
+	event.Push(context.Background(), events.RobotConfigDeleted, events.RobotConfigPayload{
+		MemberID: "r-del", TeamID: "team1",
+	})
+
+	assert.Eventually(t, func() bool {
+		return len(tgAdapter.getRemoved()) == 1
+	}, 2*time.Second, 50*time.Millisecond)
+
+	assert.Equal(t, "r-del", tgAdapter.getRemoved()[0])
+}
+
+func TestConfigCreated_RobotNotInCache(t *testing.T) {
+	setupEventBus(t)
+	cache := robotcache.New()
+
+	tgAdapter := &mockAdapter{}
+	d := NewDispatcher(cache, map[string]Adapter{"telegram": tgAdapter})
+
+	require.NoError(t, d.Start(context.Background()))
+	defer d.Stop()
+
+	// Push event but don't add robot to cache
+	event.Push(context.Background(), events.RobotConfigCreated, events.RobotConfigPayload{
+		MemberID: "r-ghost", TeamID: "team1",
+	})
+
+	time.Sleep(200 * time.Millisecond)
+	assert.Empty(t, tgAdapter.getApplied())
+}
+
+func TestParseIntegrations(t *testing.T) {
+	tests := []struct {
+		name     string
+		intg     *robottypes.Integrations
+		expected []string
+	}{
+		{"nil", nil, nil},
+		{"empty", &robottypes.Integrations{}, nil},
+		{"telegram only", &robottypes.Integrations{
+			Telegram: &robottypes.TelegramConfig{Enabled: true},
+		}, []string{"telegram"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.intg == nil {
+				return
+			}
+			result := parseIntegrations(tt.intg)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}

agent/robot/events/integrations/feishu/dedup.go

@@ -0,0 +1,44 @@
+package feishu
+
+import (
+	"sync"
+	"time"
+)
+
+const (
+	dedupTTL           = 24 * time.Hour
+	dedupCleanInterval = time.Hour
+)
+
+type dedupStore struct {
+	m sync.Map
+}
+
+func newDedupStore() *dedupStore {
+	return &dedupStore{}
+}
+
+func (d *dedupStore) markSeen(key string) bool {
+	now := time.Now().Unix()
+	_, loaded := d.m.LoadOrStore(key, now)
+	return !loaded
+}
+
+func (d *dedupStore) cleaner(stopCh <-chan struct{}) {
+	ticker := time.NewTicker(dedupCleanInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-stopCh:
+			return
+		case <-ticker.C:
+			cutoff := time.Now().Add(-dedupTTL).Unix()
+			d.m.Range(func(key, value any) bool {
+				if ts, ok := value.(int64); ok && ts < cutoff {
+					d.m.Delete(key)
+				}
+				return true
+			})
+		}
+	}
+}

agent/robot/events/integrations/feishu/e2e_test.go

@@ -0,0 +1,205 @@
+package feishu
+
+import (
+	"context"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	fsapi "github.com/yaoapp/yao/integrations/feishu"
+)
+
+var (
+	fsAppID     string
+	fsAppSecret string
+)
+
+func TestMain(m *testing.M) {
+	fsAppID = os.Getenv("FEISHU_TEST_APP_ID")
+	fsAppSecret = os.Getenv("FEISHU_TEST_APP_SECRET")
+	os.Exit(m.Run())
+}
+
+func skipIfNoCreds(t *testing.T) {
+	t.Helper()
+	if fsAppID == "" || fsAppSecret == "" {
+		t.Skip("FEISHU_TEST_APP_ID or FEISHU_TEST_APP_SECRET not set")
+	}
+}
+
+// TestE2E_Adapter_Apply verifies that Apply correctly registers a bot.
+func TestE2E_Adapter_Apply(t *testing.T) {
+	skipIfNoCreds(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_feishu_adapter",
+		TeamID:   "team_e2e_fs",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Feishu: &robottypes.FeishuConfig{
+					Enabled:   true,
+					AppID:     fsAppID,
+					AppSecret: fsAppSecret,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+
+	a.mu.RLock()
+	entry, ok := a.bots["robot_e2e_feishu_adapter"]
+	a.mu.RUnlock()
+
+	require.True(t, ok, "bot should be registered")
+	assert.Equal(t, fsAppID, entry.appID)
+	assert.NotNil(t, entry.bot)
+
+	t.Logf("OK  Apply: feishu bot registered robot=%s app=%s", robot.MemberID, entry.appID)
+}
+
+// TestE2E_Adapter_Apply_Update verifies re-Apply with same appID is a no-op.
+func TestE2E_Adapter_Apply_Update(t *testing.T) {
+	skipIfNoCreds(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_feishu_update",
+		TeamID:   "team_e2e_fs",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Feishu: &robottypes.FeishuConfig{
+					Enabled:   true,
+					AppID:     fsAppID,
+					AppSecret: fsAppSecret,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_feishu_update"]
+	a.mu.RUnlock()
+	require.True(t, ok)
+
+	// Apply again — should be no-op
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	assert.Len(t, a.bots, 1)
+	a.mu.RUnlock()
+
+	// Remove
+	a.Remove(context.Background(), "robot_e2e_feishu_update")
+	a.mu.RLock()
+	_, ok = a.bots["robot_e2e_feishu_update"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "bot should be removed")
+	t.Log("OK  Apply/Remove lifecycle verified")
+}
+
+// TestE2E_Adapter_Dedup verifies deduplication works.
+func TestE2E_Adapter_Dedup(t *testing.T) {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	key := "fs:test-robot:msg-12345"
+	assert.True(t, a.dedup.markSeen(key), "first time should return true")
+	assert.False(t, a.dedup.markSeen(key), "second time should return false (dedup)")
+	t.Log("OK  dedup working correctly")
+}
+
+// TestE2E_Adapter_HandleMessages verifies message handling through the adapter.
+func TestE2E_Adapter_HandleMessages(t *testing.T) {
+	skipIfNoCreds(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	entry := &botEntry{
+		robotID: "robot_e2e_feishu_handle",
+		appID:   fsAppID,
+		bot:     fsapi.NewBot(fsAppID, fsAppSecret),
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cms := []*fsapi.ConvertedMessage{
+		{
+			MessageID: "test_msg_1",
+			ChatID:    "test_chat_1",
+			ChatType:  "p2p",
+			SenderID:  "test_sender_1",
+			Text:      "Hello from E2E test",
+		},
+	}
+
+	// This should not panic even without event bus running
+	a.handleMessages(ctx, entry, cms)
+
+	// Verify dedup: should be marked as seen
+	assert.False(t, a.dedup.markSeen("fs:robot_e2e_feishu_handle:test_msg_1"),
+		"message should be marked as seen after handleMessages")
+	t.Log("OK  handleMessages processed 1 message")
+}
+
+// TestE2E_Adapter_ApplyDisabled verifies Apply removes bot when disabled.
+func TestE2E_Adapter_ApplyDisabled(t *testing.T) {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_feishu_disabled",
+		TeamID:   "team_e2e_fs",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Feishu: &robottypes.FeishuConfig{
+					Enabled:   false,
+					AppID:     "some_app",
+					AppSecret: "some_secret",
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_feishu_disabled"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "disabled bot should not be registered")
+	t.Log("OK  disabled config not registered")
+}

agent/robot/events/integrations/feishu/feishu.go

@@ -0,0 +1,139 @@
+package feishu
+
+import (
+	"context"
+	"sync"
+
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	fsapi "github.com/yaoapp/yao/integrations/feishu"
+)
+
+var log = logger.New("feishu")
+
+// Adapter implements the integrations.Adapter interface for Feishu (Lark).
+//
+// Architecture:
+//   - One event subscription per registered bot via Feishu SDK's long-poll/callback mechanism
+//   - One dedup cleaner goroutine removes expired keys every hour
+type Adapter struct {
+	mu     sync.RWMutex
+	bots   map[string]*botEntry // robotID -> *botEntry
+	appIdx map[string]string    // appID  -> robotID
+	dedup  *dedupStore
+	stopCh chan struct{}
+}
+
+// botEntry holds the state for one robot's Feishu integration.
+type botEntry struct {
+	robotID  string
+	appID    string
+	bot      *fsapi.Bot
+	cancelFn context.CancelFunc // cancels the event subscription goroutine
+}
+
+// NewAdapter creates a new Feishu adapter.
+func NewAdapter() *Adapter {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	go a.dedup.cleaner(a.stopCh)
+	return a
+}
+
+// Apply is called by the Dispatcher when a robot config is created or updated.
+func (a *Adapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	fsConf := extractConfig(robot)
+	log.Debug("Apply robot=%s fsConf=%v", robot.MemberID, fsConf != nil)
+
+	if fsConf == nil || !fsConf.Enabled || fsConf.AppID == "" || fsConf.AppSecret == "" {
+		a.removeBot(robot.MemberID)
+		return
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if existing, ok := a.bots[robot.MemberID]; ok {
+		if existing.appID == fsConf.AppID {
+			return
+		}
+		a.removeBotLocked(robot.MemberID)
+	}
+
+	bot := fsapi.NewBot(fsConf.AppID, fsConf.AppSecret)
+
+	streamCtx, streamCancel := context.WithCancel(context.Background())
+	entry := &botEntry{
+		robotID:  robot.MemberID,
+		appID:    fsConf.AppID,
+		bot:      bot,
+		cancelFn: streamCancel,
+	}
+	a.bots[robot.MemberID] = entry
+	a.appIdx[fsConf.AppID] = robot.MemberID
+
+	go a.eventLoop(streamCtx, entry)
+
+	log.Info("feishu adapter: registered robot=%s app=%s", robot.MemberID, fsConf.AppID)
+}
+
+// Remove is called by the Dispatcher when a robot is deleted.
+func (a *Adapter) Remove(ctx context.Context, robotID string) {
+	a.removeBot(robotID)
+}
+
+// Shutdown stops all event subscriptions and dedup cleaner.
+func (a *Adapter) Shutdown() {
+	close(a.stopCh)
+	a.mu.Lock()
+	for _, entry := range a.bots {
+		if entry.cancelFn != nil {
+			entry.cancelFn()
+		}
+	}
+	a.mu.Unlock()
+	log.Info("feishu adapter: shutdown complete")
+}
+
+func (a *Adapter) removeBot(robotID string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.removeBotLocked(robotID)
+}
+
+func (a *Adapter) removeBotLocked(robotID string) {
+	entry, ok := a.bots[robotID]
+	if !ok {
+		return
+	}
+	if entry.cancelFn != nil {
+		entry.cancelFn()
+	}
+	if entry.appID != "" {
+		delete(a.appIdx, entry.appID)
+	}
+	delete(a.bots, robotID)
+	log.Info("feishu adapter: unregistered robot=%s", robotID)
+}
+
+func (a *Adapter) resolveByAppID(appID string) (*botEntry, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	robotID, ok := a.appIdx[appID]
+	if !ok {
+		return nil, false
+	}
+	entry, ok := a.bots[robotID]
+	return entry, ok
+}
+
+func extractConfig(robot *robottypes.Robot) *robottypes.FeishuConfig {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return nil
+	}
+	return robot.Config.Integrations.Feishu
+}

agent/robot/events/integrations/feishu/message.go

@@ -0,0 +1,120 @@
+package feishu
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/event"
+	fsapi "github.com/yaoapp/yao/integrations/feishu"
+)
+
+// handleMessages processes a batch of Feishu messages for one chat.
+func (a *Adapter) handleMessages(ctx context.Context, entry *botEntry, cms []*fsapi.ConvertedMessage) {
+	if len(cms) == 0 {
+		return
+	}
+
+	var allParts []interface{}
+	var lastCM *fsapi.ConvertedMessage
+
+	for _, cm := range cms {
+		if cm == nil {
+			continue
+		}
+
+		dedupKey := fmt.Sprintf("fs:%s:%s", entry.robotID, cm.MessageID)
+		if !a.dedup.markSeen(dedupKey) {
+			continue
+		}
+
+		parts := buildContentParts(cm)
+		if len(parts) == 0 {
+			continue
+		}
+
+		allParts = append(allParts, parts...)
+		lastCM = cm
+	}
+
+	if len(allParts) == 0 || lastCM == nil {
+		return
+	}
+
+	content := mergeContentParts(allParts)
+
+	msgPayload := events.MessagePayload{
+		RobotID: entry.robotID,
+		Messages: []agentcontext.Message{
+			{Role: agentcontext.RoleUser, Content: content},
+		},
+		Metadata: &events.MessageMetadata{
+			Channel:    "feishu",
+			MessageID:  lastCM.MessageID,
+			AppID:      entry.appID,
+			ChatID:     lastCM.ChatID,
+			SenderID:   lastCM.SenderID,
+			SenderName: lastCM.SenderName,
+			Locale:     events.NormalizeLocale(lastCM.LanguageCode),
+			Extra: map[string]any{
+				"feishu_message_id": lastCM.MessageID,
+			},
+		},
+	}
+
+	if _, err := event.Push(ctx, events.Message, msgPayload); err != nil {
+		log.Error("feishu adapter: event.Push robot.message failed robot=%s: %v", entry.robotID, err)
+	}
+}
+
+func buildContentParts(cm *fsapi.ConvertedMessage) []interface{} {
+	var parts []interface{}
+
+	if cm.HasText() {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": cm.Text,
+		})
+	}
+
+	for _, mi := range cm.MediaItems {
+		if mi.Wrapper == "" {
+			continue
+		}
+		parts = append(parts, map[string]interface{}{
+			"type":      "file",
+			"file_url":  mi.Wrapper,
+			"mime_type": mi.MimeType,
+			"file_name": mi.FileName,
+		})
+	}
+
+	return parts
+}
+
+func mergeContentParts(parts []interface{}) interface{} {
+	allText := true
+	for _, p := range parts {
+		m, ok := p.(map[string]interface{})
+		if !ok || m["type"] != "text" {
+			allText = false
+			break
+		}
+	}
+
+	if allText {
+		var buf strings.Builder
+		for i, p := range parts {
+			if i > 0 {
+				buf.WriteString("\n")
+			}
+			m := p.(map[string]interface{})
+			buf.WriteString(m["text"].(string))
+		}
+		return buf.String()
+	}
+
+	return parts
+}

agent/robot/events/integrations/feishu/reply.go

@@ -0,0 +1,200 @@
+package feishu
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	fsapi "github.com/yaoapp/yao/integrations/feishu"
+)
+
+// Reply sends the assistant message back to the originating Feishu chat.
+func (a *Adapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if msg == nil || metadata == nil {
+		return fmt.Errorf("nil message or metadata")
+	}
+
+	entry := a.resolveByChat(metadata)
+	if entry == nil {
+		return fmt.Errorf("no bot registered for feishu metadata (appID=%s)", metadata.AppID)
+	}
+
+	var replyToMsgID string
+	if metadata.Extra != nil {
+		if v, ok := metadata.Extra["feishu_message_id"]; ok {
+			if s, ok := v.(string); ok {
+				replyToMsgID = s
+			}
+		}
+	}
+
+	return a.sendContent(ctx, entry, metadata.ChatID, replyToMsgID, msg.Content)
+}
+
+func (a *Adapter) sendContent(ctx context.Context, entry *botEntry, chatID, replyToMsgID string, content interface{}) error {
+	switch c := content.(type) {
+	case string:
+		if strings.TrimSpace(c) == "" {
+			return nil
+		}
+		return a.sendMarkdown(ctx, entry, chatID, replyToMsgID, c)
+
+	case []interface{}:
+		return a.sendParts(ctx, entry, chatID, replyToMsgID, c)
+
+	default:
+		parts, ok := toContentParts(content)
+		if ok {
+			return a.sendPartsTyped(ctx, entry, chatID, replyToMsgID, parts)
+		}
+		return a.sendMarkdown(ctx, entry, chatID, replyToMsgID, fmt.Sprintf("%v", content))
+	}
+}
+
+// sendMarkdown converts standard Markdown to Feishu lark_md and sends as an interactive card.
+func (a *Adapter) sendMarkdown(ctx context.Context, entry *botEntry, chatID, replyToMsgID, text string) error {
+	formatted := fsapi.FormatFeishuMarkdown(text)
+	if replyToMsgID != "" {
+		_, err := entry.bot.ReplyCardMessage(ctx, replyToMsgID, formatted)
+		return err
+	}
+	_, err := entry.bot.SendCardMessage(ctx, chatID, formatted)
+	return err
+}
+
+func (a *Adapter) sendParts(ctx context.Context, entry *botEntry, chatID, replyToMsgID string, parts []interface{}) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		m, ok := part.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		partType, _ := m["type"].(string)
+		switch partType {
+		case "text":
+			if text, ok := m["text"].(string); ok {
+				textBuf.WriteString(text)
+			}
+		case "image_url":
+			if err := a.flushText(ctx, entry, chatID, replyToMsgID, &textBuf); err != nil {
+				return err
+			}
+			if imgMap, ok := m["image_url"].(map[string]interface{}); ok {
+				if url, ok := imgMap["url"].(string); ok {
+					if err := sendImageOrWrapper(ctx, entry, chatID, url, ""); err != nil {
+						log.Error("feishu reply: send image: %v", err)
+					}
+				}
+			}
+		case "file":
+			if err := a.flushText(ctx, entry, chatID, replyToMsgID, &textBuf); err != nil {
+				return err
+			}
+			fileURL, _ := m["file_url"].(string)
+			if fileURL == "" {
+				if fileMap, ok := m["file"].(map[string]interface{}); ok {
+					fileURL, _ = fileMap["url"].(string)
+				}
+			}
+			if fileURL != "" {
+				if err := sendFileOrWrapper(ctx, entry, chatID, fileURL, ""); err != nil {
+					log.Error("feishu reply: send file: %v", err)
+				}
+			}
+		}
+	}
+	return a.flushText(ctx, entry, chatID, replyToMsgID, &textBuf)
+}
+
+func (a *Adapter) sendPartsTyped(ctx context.Context, entry *botEntry, chatID, replyToMsgID string, parts []agentcontext.ContentPart) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		switch part.Type {
+		case agentcontext.ContentText:
+			textBuf.WriteString(part.Text)
+		case agentcontext.ContentImageURL:
+			if err := a.flushText(ctx, entry, chatID, replyToMsgID, &textBuf); err != nil {
+				return err
+			}
+			if part.ImageURL != nil {
+				if err := sendImageOrWrapper(ctx, entry, chatID, part.ImageURL.URL, ""); err != nil {
+					log.Error("feishu reply: send image: %v", err)
+				}
+			}
+		case agentcontext.ContentFile:
+			if err := a.flushText(ctx, entry, chatID, replyToMsgID, &textBuf); err != nil {
+				return err
+			}
+			if part.File != nil {
+				if err := sendFileOrWrapper(ctx, entry, chatID, part.File.URL, part.File.Filename); err != nil {
+					log.Error("feishu reply: send file: %v", err)
+				}
+			}
+		}
+	}
+	return a.flushText(ctx, entry, chatID, replyToMsgID, &textBuf)
+}
+
+func (a *Adapter) flushText(ctx context.Context, entry *botEntry, chatID, replyToMsgID string, buf *strings.Builder) error {
+	if buf.Len() == 0 {
+		return nil
+	}
+	text := buf.String()
+	buf.Reset()
+	return a.sendMarkdown(ctx, entry, chatID, replyToMsgID, text)
+}
+
+func sendImageOrWrapper(ctx context.Context, entry *botEntry, chatID, url, caption string) error {
+	if isWrapper(url) {
+		return entry.bot.SendImageFromWrapper(ctx, chatID, url, caption)
+	}
+	if strings.HasPrefix(url, "http") {
+		text := url
+		if caption != "" {
+			text = caption + "\n" + url
+		}
+		_, err := entry.bot.SendTextMessage(ctx, chatID, text)
+		return err
+	}
+	return fmt.Errorf("unsupported image URL scheme: %s", url)
+}
+
+func sendFileOrWrapper(ctx context.Context, entry *botEntry, chatID, url, caption string) error {
+	if isWrapper(url) {
+		return entry.bot.SendFileFromWrapper(ctx, chatID, url, caption)
+	}
+	if strings.HasPrefix(url, "http") {
+		text := url
+		if caption != "" {
+			text = caption + "\n" + url
+		}
+		_, err := entry.bot.SendTextMessage(ctx, chatID, text)
+		return err
+	}
+	return fmt.Errorf("unsupported file URL scheme: %s", url)
+}
+
+func isWrapper(url string) bool {
+	return strings.Contains(url, "://") && !strings.HasPrefix(url, "http")
+}
+
+func toContentParts(content interface{}) ([]agentcontext.ContentPart, bool) {
+	parts, ok := content.([]agentcontext.ContentPart)
+	return parts, ok
+}
+
+func (a *Adapter) resolveByChat(metadata *events.MessageMetadata) *botEntry {
+	if metadata.AppID != "" {
+		if entry, ok := a.resolveByAppID(metadata.AppID); ok {
+			return entry
+		}
+	}
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	for _, entry := range a.bots {
+		return entry
+	}
+	return nil
+}

agent/robot/events/integrations/feishu/stream.go

@@ -0,0 +1,116 @@
+package feishu
+
+import (
+	"context"
+	"time"
+
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+	"github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
+	larkws "github.com/larksuite/oapi-sdk-go/v3/ws"
+	fsapi "github.com/yaoapp/yao/integrations/feishu"
+)
+
+const reconnectDelay = 5 * time.Second
+
+// eventLoop starts the Feishu WebSocket event subscription for a single bot.
+// It automatically reconnects on failure.
+func (a *Adapter) eventLoop(ctx context.Context, entry *botEntry) {
+	log.Info("feishu eventLoop started robot=%s app=%s", entry.robotID, entry.appID)
+
+	for {
+		select {
+		case <-ctx.Done():
+			log.Info("feishu eventLoop stopped robot=%s", entry.robotID)
+			return
+		case <-a.stopCh:
+			return
+		default:
+		}
+
+		err := a.runWSClient(ctx, entry)
+		if err != nil {
+			log.Error("feishu ws disconnected robot=%s: %v, reconnecting in %s", entry.robotID, err, reconnectDelay)
+		}
+
+		select {
+		case <-ctx.Done():
+			return
+		case <-a.stopCh:
+			return
+		case <-time.After(reconnectDelay):
+		}
+	}
+}
+
+func (a *Adapter) runWSClient(ctx context.Context, entry *botEntry) error {
+	eventHandler := dispatcher.NewEventDispatcher("", "")
+	eventHandler.OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
+		return a.onMessageReceive(ctx, entry, event)
+	})
+
+	cli := larkws.NewClient(entry.bot.AppID(), entry.bot.AppSecret(),
+		larkws.WithEventHandler(eventHandler),
+		larkws.WithLogLevel(larkcore.LogLevelWarn),
+	)
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- cli.Start(ctx)
+	}()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-a.stopCh:
+		return nil
+	case err := <-errCh:
+		return err
+	}
+}
+
+func (a *Adapter) onMessageReceive(ctx context.Context, entry *botEntry, event *larkim.P2MessageReceiveV1) error {
+	if event == nil || event.Event == nil || event.Event.Message == nil {
+		return nil
+	}
+
+	msg := event.Event.Message
+	sender := event.Event.Sender
+
+	msgType := derefStr(msg.MessageType)
+	content := derefStr(msg.Content)
+	messageID := derefStr(msg.MessageId)
+	chatID := derefStr(msg.ChatId)
+	chatType := derefStr(msg.ChatType)
+
+	text, media := fsapi.ParseMessageContent(msgType, content)
+
+	cm := &fsapi.ConvertedMessage{
+		MessageID:    messageID,
+		ChatID:       chatID,
+		ChatType:     chatType,
+		Text:         text,
+		MediaItems:   media,
+		EventID:      event.EventV2Base.Header.EventID,
+		LanguageCode: "zh",
+	}
+
+	if sender != nil && sender.SenderId != nil {
+		cm.SenderID = derefStr(sender.SenderId.OpenId)
+	}
+
+	if cm.HasMedia() {
+		groups := []string{"feishu", entry.robotID}
+		entry.bot.ResolveMedia(ctx, cm, groups)
+	}
+
+	a.handleMessages(ctx, entry, []*fsapi.ConvertedMessage{cm})
+	return nil
+}
+
+func derefStr(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}

agent/robot/events/integrations/telegram/dedup.go

@@ -0,0 +1,48 @@
+package telegram
+
+import (
+	"sync"
+	"time"
+)
+
+const (
+	dedupTTL           = 24 * time.Hour
+	dedupCleanInterval = time.Hour
+)
+
+// dedupStore is a lightweight in-memory deduplication store with TTL.
+// Used for message-level dedup (same update_id won't be processed twice).
+type dedupStore struct {
+	m sync.Map // key -> int64 (unix timestamp)
+}
+
+func newDedupStore() *dedupStore {
+	return &dedupStore{}
+}
+
+// markSeen returns true if this is the first time the key is seen.
+func (d *dedupStore) markSeen(key string) bool {
+	now := time.Now().Unix()
+	_, loaded := d.m.LoadOrStore(key, now)
+	return !loaded
+}
+
+// cleaner periodically removes expired entries. Runs until stopCh is closed.
+func (d *dedupStore) cleaner(stopCh <-chan struct{}) {
+	ticker := time.NewTicker(dedupCleanInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-stopCh:
+			return
+		case <-ticker.C:
+			cutoff := time.Now().Add(-dedupTTL).Unix()
+			d.m.Range(func(key, value any) bool {
+				if ts, ok := value.(int64); ok && ts < cutoff {
+					d.m.Delete(key)
+				}
+				return true
+			})
+		}
+	}
+}

agent/robot/events/integrations/telegram/e2e_test.go

@@ -0,0 +1,354 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/yaoapp/gou/model"
+	"github.com/yaoapp/xun/capsule"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	"github.com/yaoapp/yao/agent/testutils"
+	"github.com/yaoapp/yao/event"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+var (
+	tgBotToken string
+	tgHost     string
+)
+
+func TestMain(m *testing.M) {
+	tgBotToken = os.Getenv("TELEGRAM_TEST_BOT_TOKEN")
+	tgHost = os.Getenv("TELEGRAM_TEST_HOST")
+	os.Exit(m.Run())
+}
+
+func skipIfNoToken(t *testing.T) {
+	t.Helper()
+	if tgBotToken == "" {
+		t.Skip("TELEGRAM_TEST_BOT_TOKEN not set")
+	}
+}
+
+func newTestBot() *tgapi.Bot {
+	var opts []tgapi.BotOption
+	if tgHost != "" {
+		opts = append(opts, tgapi.WithAPIBase(tgHost))
+	}
+	return tgapi.NewBot(tgBotToken, "", opts...)
+}
+
+// confirmPendingUpdates checks if there are pending updates from previous seeds.
+func confirmPendingUpdates(t *testing.T) []*tgapi.ConvertedMessage {
+	t.Helper()
+	b := newTestBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	msgs, err := b.GetUpdates(ctx, 0, 5, nil)
+	require.NoError(t, err)
+	return msgs
+}
+
+// TestE2E_Adapter_Apply verifies that Apply correctly registers a bot.
+func TestE2E_Adapter_Apply(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_tg_adapter",
+		TeamID:   "team_e2e_tg",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Telegram: &robottypes.TelegramConfig{
+					Enabled:  true,
+					BotToken: tgBotToken,
+					Host:     tgHost,
+					AppID:    "e2e-test-app",
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+
+	a.mu.RLock()
+	entry, ok := a.bots["robot_e2e_tg_adapter"]
+	a.mu.RUnlock()
+
+	require.True(t, ok, "bot should be registered")
+	assert.Equal(t, tgBotToken, entry.bot.Token())
+	assert.Equal(t, "e2e-test-app", entry.appID)
+
+	// Verify GetMe works through the registered bot
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	me, err := entry.bot.GetMe(ctx)
+	require.NoError(t, err)
+	assert.True(t, me.IsBot)
+	t.Logf("OK  Apply: bot registered id=%d username=%s", me.ID, me.Username)
+
+	// Verify ResolveBot
+	resolved := a.ResolveBot("e2e-test-app")
+	require.NotNil(t, resolved)
+	assert.Equal(t, tgBotToken, resolved.Token())
+}
+
+// TestE2E_Adapter_Apply_Update verifies that Apply with a different token replaces the bot.
+func TestE2E_Adapter_Apply_Update(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	robot := &robottypes.Robot{
+		MemberID: "robot_e2e_tg_update",
+		TeamID:   "team_e2e_tg",
+		Config: &robottypes.Config{
+			Integrations: &robottypes.Integrations{
+				Telegram: &robottypes.TelegramConfig{
+					Enabled:  true,
+					BotToken: tgBotToken,
+					Host:     tgHost,
+				},
+			},
+		},
+	}
+
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	_, ok := a.bots["robot_e2e_tg_update"]
+	a.mu.RUnlock()
+	require.True(t, ok)
+
+	// Apply again with same token — should be a no-op
+	a.Apply(context.Background(), robot)
+	a.mu.RLock()
+	assert.Len(t, a.bots, 1)
+	a.mu.RUnlock()
+
+	// Remove
+	a.Remove(context.Background(), "robot_e2e_tg_update")
+	a.mu.RLock()
+	_, ok = a.bots["robot_e2e_tg_update"]
+	a.mu.RUnlock()
+	assert.False(t, ok, "bot should be removed")
+	t.Log("OK  Apply/Remove lifecycle verified")
+}
+
+// TestE2E_Adapter_PollAll verifies that pollAll fetches updates from Telegram
+// and processes them through handleMessages.
+func TestE2E_Adapter_PollAll(t *testing.T) {
+	skipIfNoToken(t)
+	testutils.Prepare(t)
+	defer testutils.Clean(t)
+
+	pending := confirmPendingUpdates(t)
+	if len(pending) == 0 {
+		t.Skip("no pending updates; run integrations/telegram seed first")
+	}
+	t.Logf("found %d pending updates", len(pending))
+
+	// Create adapter WITHOUT auto-starting pollLoop
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	memberID := "robot_e2e_tg_poll"
+	setupTestRobot(t, memberID)
+	defer cleanupTestRobots(t)
+
+	var opts []tgapi.BotOption
+	if tgHost != "" {
+		opts = append(opts, tgapi.WithAPIBase(tgHost))
+	}
+	a.bots[memberID] = &botEntry{
+		robotID: memberID,
+		appID:   "e2e-poll-app",
+		bot:     tgapi.NewBot(tgBotToken, "", opts...),
+	}
+
+	// Start event bus so event.Push works
+	if err := event.Start(); err != nil && err != event.ErrAlreadyStart {
+		t.Fatalf("event.Start: %v", err)
+	}
+	defer func() { _ = event.Stop(context.Background()) }()
+
+	// Manually trigger one poll cycle
+	a.pollAll()
+
+	// Verify offset advanced (meaning updates were processed)
+	a.mu.RLock()
+	entry := a.bots[memberID]
+	a.mu.RUnlock()
+	assert.Greater(t, entry.offset, int64(0), "offset should have advanced after processing updates")
+	t.Logf("OK  pollAll: offset advanced to %d", entry.offset)
+}
+
+// TestE2E_Adapter_Dedup verifies that duplicate messages are not processed twice.
+func TestE2E_Adapter_Dedup(t *testing.T) {
+	skipIfNoToken(t)
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	key := "tg:test-robot:12345"
+	assert.True(t, a.dedup.markSeen(key), "first time should return true")
+	assert.False(t, a.dedup.markSeen(key), "second time should return false (dedup)")
+	t.Log("OK  dedup working correctly")
+}
+
+// TestE2E_Adapter_HandleMessages_Integration verifies the full flow:
+// GetUpdates → ConvertedMessage → handleMessages → event.Push
+func TestE2E_Adapter_HandleMessages_Integration(t *testing.T) {
+	skipIfNoToken(t)
+	testutils.Prepare(t)
+	defer testutils.Clean(t)
+
+	b := newTestBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	msgs, err := b.GetUpdates(ctx, 0, 5, nil)
+	require.NoError(t, err)
+	if len(msgs) == 0 {
+		t.Skip("no pending updates; run integrations/telegram seed first")
+	}
+
+	memberID := "robot_e2e_tg_handle"
+	setupTestRobot(t, memberID)
+	defer cleanupTestRobots(t)
+
+	if err := event.Start(); err != nil && err != event.ErrAlreadyStart {
+		t.Fatalf("event.Start: %v", err)
+	}
+	defer func() { _ = event.Stop(context.Background()) }()
+
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	defer close(a.stopCh)
+
+	entry := &botEntry{
+		robotID: memberID,
+		appID:   "e2e-handle-app",
+		bot:     b,
+	}
+
+	// Group all messages by chatID (like pollAll does) and process each group
+	grouped := groupByChatID(msgs)
+	for chatID, chatMsgs := range grouped {
+		t.Logf("processing chat=%d messages=%d", chatID, len(chatMsgs))
+		for _, cm := range chatMsgs {
+			t.Logf("  update_id=%d msg_id=%d text=%q media=%d",
+				cm.UpdateID, cm.MessageID, truncate(cm.Text, 40), len(cm.MediaItems))
+		}
+		a.handleMessages(ctx, entry, chatMsgs)
+	}
+
+	// Verify dedup: all updates should be marked as seen
+	cm := msgs[0]
+	assert.False(t, a.dedup.markSeen(fmt.Sprintf("tg:%s:%d", memberID, cm.UpdateID)),
+		"update should be marked as seen after handleMessages")
+
+	// Second call with same messages should be fully deduped (no-op)
+	a.handleMessages(ctx, entry, msgs)
+	t.Logf("OK  handleMessages processed %d updates across %d chats", len(msgs), len(grouped))
+}
+
+// ==================== Helpers ====================
+
+func setupTestRobot(t *testing.T, memberID string) {
+	t.Helper()
+	m := model.Select("__yao.member")
+	if m == nil {
+		t.Skip("__yao.member model not loaded")
+	}
+	qb := capsule.Query()
+
+	robotConfig := map[string]interface{}{
+		"identity": map[string]interface{}{
+			"role":   "Telegram E2E Test Robot",
+			"duties": []string{"Process Telegram messages"},
+		},
+		"integrations": map[string]interface{}{
+			"telegram": map[string]interface{}{
+				"enabled":   true,
+				"bot_token": tgBotToken,
+				"host":      tgHost,
+				"app_id":    "e2e-tg-app-" + memberID,
+			},
+		},
+		"resources": map[string]interface{}{
+			"phases": map[string]interface{}{
+				"host": "robot.host",
+			},
+		},
+	}
+	configJSON, _ := json.Marshal(robotConfig)
+
+	err := qb.Table(m.MetaData.Table.Name).Insert([]map[string]interface{}{
+		{
+			"member_id":       memberID,
+			"team_id":         "team_e2e_tg",
+			"member_type":     "robot",
+			"display_name":    "E2E TG Adapter Test " + memberID,
+			"system_prompt":   "You are a test robot for Telegram adapter E2E testing.",
+			"status":          "active",
+			"role_id":         "member",
+			"autonomous_mode": false,
+			"robot_status":    "idle",
+			"robot_config":    string(configJSON),
+		},
+	})
+	if err != nil {
+		t.Fatalf("setup robot %s: %v", memberID, err)
+	}
+}
+
+func cleanupTestRobots(t *testing.T) {
+	t.Helper()
+	m := model.Select("__yao.member")
+	if m == nil {
+		return
+	}
+	qb := capsule.Query()
+	_, _ = qb.Table(m.MetaData.Table.Name).Where("member_id", "like", "robot_e2e_tg%").Delete()
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}

agent/robot/events/integrations/telegram/message.go

@@ -0,0 +1,136 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	"github.com/yaoapp/yao/event"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+// handleMessages builds a single event payload from a batch of ConvertedMessages
+// belonging to the same chat. Consecutive user messages are merged into one to
+// keep the messages array clean for the LLM.
+func (a *Adapter) handleMessages(ctx context.Context, entry *botEntry, cms []*tgapi.ConvertedMessage) {
+	if len(cms) == 0 {
+		return
+	}
+
+	var allParts []interface{}
+	var lastCM *tgapi.ConvertedMessage
+
+	for _, cm := range cms {
+		if cm == nil {
+			continue
+		}
+
+		if isBotCommand(cm) {
+			continue
+		}
+
+		dedupKey := fmt.Sprintf("tg:%s:%d", entry.robotID, cm.UpdateID)
+		if !a.dedup.markSeen(dedupKey) {
+			continue
+		}
+
+		parts := buildContentParts(cm)
+		if len(parts) == 0 {
+			continue
+		}
+
+		allParts = append(allParts, parts...)
+		lastCM = cm
+	}
+
+	if len(allParts) == 0 || lastCM == nil {
+		return
+	}
+
+	content := mergeContentParts(allParts)
+
+	msgPayload := events.MessagePayload{
+		RobotID: entry.robotID,
+		Messages: []agentcontext.Message{
+			{Role: agentcontext.RoleUser, Content: content},
+		},
+		Metadata: &events.MessageMetadata{
+			Channel:    "telegram",
+			MessageID:  strconv.FormatInt(lastCM.UpdateID, 10),
+			AppID:      entry.appID,
+			ChatID:     strconv.FormatInt(lastCM.ChatID, 10),
+			SenderID:   strconv.FormatInt(lastCM.SenderID, 10),
+			SenderName: lastCM.SenderName,
+			Locale:     events.NormalizeLocale(lastCM.LanguageCode),
+			Extra: map[string]any{
+				"tg_message_id": lastCM.MessageID,
+			},
+		},
+	}
+
+	if _, err := event.Push(ctx, events.Message, msgPayload); err != nil {
+		log.Error("telegram adapter: event.Push robot.message failed robot=%s: %v", entry.robotID, err)
+	}
+}
+
+// buildContentParts extracts content parts from a single ConvertedMessage.
+func buildContentParts(cm *tgapi.ConvertedMessage) []interface{} {
+	var parts []interface{}
+
+	if cm.HasText() {
+		parts = append(parts, map[string]interface{}{
+			"type": "text",
+			"text": cm.Text,
+		})
+	}
+
+	for _, mi := range cm.MediaItems {
+		if mi.Wrapper == "" {
+			continue
+		}
+		parts = append(parts, map[string]interface{}{
+			"type":      "file",
+			"file_url":  mi.Wrapper,
+			"mime_type": mi.MimeType,
+			"file_name": mi.FileName,
+		})
+	}
+
+	return parts
+}
+
+// mergeContentParts merges collected parts into a single content value.
+// If all parts are text-only, they are joined with newlines into a plain string.
+// Otherwise the full parts array is returned.
+func mergeContentParts(parts []interface{}) interface{} {
+	allText := true
+	for _, p := range parts {
+		m, ok := p.(map[string]interface{})
+		if !ok || m["type"] != "text" {
+			allText = false
+			break
+		}
+	}
+
+	if allText {
+		var buf strings.Builder
+		for i, p := range parts {
+			if i > 0 {
+				buf.WriteString("\n")
+			}
+			m := p.(map[string]interface{})
+			buf.WriteString(m["text"].(string))
+		}
+		return buf.String()
+	}
+
+	return parts
+}
+
+// isBotCommand returns true if the message is a Telegram bot command (text starting with "/").
+func isBotCommand(cm *tgapi.ConvertedMessage) bool {
+	return !cm.HasMedia() && strings.HasPrefix(strings.TrimSpace(cm.Text), "/")
+}

agent/robot/events/integrations/telegram/polling.go

@@ -0,0 +1,89 @@
+package telegram
+
+import (
+	"context"
+	"time"
+
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+const (
+	pollInterval = 60 * time.Second
+	pollTimeout  = 30 // seconds, Telegram long-polling timeout per request
+)
+
+// pollLoop runs a single goroutine that iterates all registered bots
+// every pollInterval, calling getUpdates for each one sequentially.
+func (a *Adapter) pollLoop() {
+	log.Info("pollLoop started, interval=%s", pollInterval)
+	a.pollAll()
+
+	ticker := time.NewTicker(pollInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-a.stopCh:
+			log.Info("pollLoop stopped")
+			return
+		case <-ticker.C:
+			a.pollAll()
+		}
+	}
+}
+
+func (a *Adapter) pollAll() {
+	entries := a.snapshot()
+	log.Debug("pollAll bots=%d", len(entries))
+	if len(entries) == 0 {
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), pollInterval)
+	defer cancel()
+
+	for _, entry := range entries {
+		select {
+		case <-a.stopCh:
+			return
+		default:
+		}
+
+		log.Debug("polling robot=%s offset=%d", entry.robotID, entry.offset)
+		groups := []string{"telegram", entry.robotID}
+		msgs, err := entry.bot.GetUpdates(ctx, entry.offset, pollTimeout, groups)
+		if err != nil {
+			log.Error("getUpdates failed robot=%s: %v", entry.robotID, err)
+			continue
+		}
+
+		if len(msgs) == 0 {
+			continue
+		}
+
+		// Advance offset for all received messages
+		for _, cm := range msgs {
+			if cm.UpdateID >= entry.offset {
+				entry.offset = cm.UpdateID + 1
+			}
+		}
+
+		// Group by chatID, preserving order
+		grouped := groupByChatID(msgs)
+		log.Info("robot=%s got %d updates in %d chats", entry.robotID, len(msgs), len(grouped))
+
+		for chatID, chatMsgs := range grouped {
+			log.Debug("robot=%s chat=%d messages=%d", entry.robotID, chatID, len(chatMsgs))
+			a.handleMessages(ctx, entry, chatMsgs)
+		}
+	}
+}
+
+// groupByChatID groups messages by chat ID, preserving chronological order.
+func groupByChatID(msgs []*tgapi.ConvertedMessage) map[int64][]*tgapi.ConvertedMessage {
+	grouped := make(map[int64][]*tgapi.ConvertedMessage)
+	for _, cm := range msgs {
+		grouped[cm.ChatID] = append(grouped[cm.ChatID], cm)
+	}
+	return grouped
+}

agent/robot/events/integrations/telegram/reply.go

@@ -0,0 +1,181 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"strings"
+
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	events "github.com/yaoapp/yao/agent/robot/events"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+// Reply sends the assistant message back to the originating Telegram chat.
+// Content may be a plain string or []ContentPart (text, image_url, file, etc.).
+// Each adapter is responsible for interpreting the standard message format.
+func (a *Adapter) Reply(ctx context.Context, msg *agentcontext.Message, metadata *events.MessageMetadata) error {
+	if msg == nil || metadata == nil {
+		return fmt.Errorf("nil message or metadata")
+	}
+
+	chatID, err := strconv.ParseInt(metadata.ChatID, 10, 64)
+	if err != nil {
+		return fmt.Errorf("invalid chat_id %q: %w", metadata.ChatID, err)
+	}
+
+	var replyTo int64
+	if metadata.Extra != nil {
+		if v, ok := metadata.Extra["tg_message_id"]; ok {
+			switch id := v.(type) {
+			case int64:
+				replyTo = id
+			case float64:
+				replyTo = int64(id)
+			}
+		}
+	}
+
+	entry := a.resolveByChat(metadata)
+	if entry == nil {
+		return fmt.Errorf("no bot registered for channel metadata (appID=%s)", metadata.AppID)
+	}
+
+	return a.sendContent(ctx, entry.bot, chatID, replyTo, msg.Content)
+}
+
+// sendContent dispatches based on the Content type.
+func (a *Adapter) sendContent(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, content interface{}) error {
+	switch c := content.(type) {
+	case string:
+		if strings.TrimSpace(c) == "" {
+			return nil
+		}
+		return bot.SendMessage(ctx, chatID, c, replyTo)
+
+	case []interface{}:
+		return a.sendParts(ctx, bot, chatID, replyTo, c)
+
+	default:
+		parts, ok := toContentParts(content)
+		if ok {
+			return a.sendPartsTyped(ctx, bot, chatID, replyTo, parts)
+		}
+		return bot.SendMessage(ctx, chatID, fmt.Sprintf("%v", content), replyTo)
+	}
+}
+
+// sendParts handles []interface{} content parts (common from JSON unmarshalling).
+func (a *Adapter) sendParts(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, parts []interface{}) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		m, ok := part.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		partType, _ := m["type"].(string)
+		switch partType {
+		case "text":
+			if text, ok := m["text"].(string); ok {
+				textBuf.WriteString(text)
+			}
+		case "image_url":
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if imgMap, ok := m["image_url"].(map[string]interface{}); ok {
+				if url, ok := imgMap["url"].(string); ok {
+					if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, url, ""); err != nil {
+						log.Error("telegram reply: send image: %v", err)
+					}
+				}
+			}
+		case "file":
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if fileMap, ok := m["file"].(map[string]interface{}); ok {
+				url, _ := fileMap["url"].(string)
+				filename, _ := fileMap["filename"].(string)
+				if url != "" {
+					if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, url, filename); err != nil {
+						log.Error("telegram reply: send file: %v", err)
+					}
+				}
+			}
+		}
+	}
+	return a.flushText(ctx, bot, chatID, replyTo, &textBuf)
+}
+
+// sendPartsTyped handles typed []agentcontext.ContentPart slices.
+func (a *Adapter) sendPartsTyped(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, parts []agentcontext.ContentPart) error {
+	var textBuf strings.Builder
+	for _, part := range parts {
+		switch part.Type {
+		case agentcontext.ContentText:
+			textBuf.WriteString(part.Text)
+		case agentcontext.ContentImageURL:
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if part.ImageURL != nil {
+				if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, part.ImageURL.URL, ""); err != nil {
+					log.Error("telegram reply: send image: %v", err)
+				}
+			}
+		case agentcontext.ContentFile:
+			if err := a.flushText(ctx, bot, chatID, replyTo, &textBuf); err != nil {
+				return err
+			}
+			if part.File != nil {
+				if err := sendFileOrWrapper(ctx, bot, chatID, replyTo, part.File.URL, part.File.Filename); err != nil {
+					log.Error("telegram reply: send file: %v", err)
+				}
+			}
+		}
+	}
+	return a.flushText(ctx, bot, chatID, replyTo, &textBuf)
+}
+
+func (a *Adapter) flushText(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, buf *strings.Builder) error {
+	if buf.Len() == 0 {
+		return nil
+	}
+	err := bot.SendMessage(ctx, chatID, buf.String(), replyTo)
+	buf.Reset()
+	return err
+}
+
+// sendFileOrWrapper sends a file from a wrapper (__yao.attachment://xxx) or URL.
+func sendFileOrWrapper(ctx context.Context, bot *tgapi.Bot, chatID, replyTo int64, url, caption string) error {
+	if strings.Contains(url, "://") && !strings.HasPrefix(url, "http") {
+		return bot.SendMedia(ctx, chatID, url, caption, replyTo)
+	}
+	if strings.HasPrefix(url, "http") {
+		mediaType := tgapi.DetectMediaType("")
+		return bot.SendMediaByURL(ctx, chatID, mediaType, url, caption, replyTo)
+	}
+	return fmt.Errorf("unsupported file URL scheme: %s", url)
+}
+
+// toContentParts tries to type-assert content to []agentcontext.ContentPart.
+func toContentParts(content interface{}) ([]agentcontext.ContentPart, bool) {
+	parts, ok := content.([]agentcontext.ContentPart)
+	return parts, ok
+}
+
+// resolveByChat finds the bot entry matching the metadata.
+func (a *Adapter) resolveByChat(metadata *events.MessageMetadata) *botEntry {
+	if metadata.AppID != "" {
+		if entry, ok := a.resolveByAppID(metadata.AppID); ok {
+			return entry
+		}
+	}
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	for _, entry := range a.bots {
+		return entry
+	}
+	return nil
+}

agent/robot/events/integrations/telegram/telegram.go

@@ -0,0 +1,159 @@
+package telegram
+
+import (
+	"context"
+	"sync"
+
+	"github.com/yaoapp/yao/agent/robot/logger"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+)
+
+var log = logger.New("telegram")
+
+// Adapter implements the integrations.Adapter interface for Telegram Bot API.
+//
+// Architecture:
+//   - One polling goroutine (ticker) iterates all registered bots every 60s
+//   - One webhook goroutine listens to integration.webhook.telegram events
+//   - One dedup cleaner goroutine removes expired keys every hour
+type Adapter struct {
+	mu      sync.RWMutex
+	bots    map[string]*botEntry // robotID -> *botEntry
+	appIdx  map[string]string    // appID  -> robotID (webhook routing)
+	dedup   *dedupStore
+	webhSub string
+	stopCh  chan struct{}
+}
+
+// botEntry holds the state for one robot's Telegram integration.
+type botEntry struct {
+	robotID string
+	appID   string
+	bot     *tgapi.Bot // bound to this robot's token
+	offset  int64      // polling offset
+}
+
+// NewAdapter creates a new Telegram adapter.
+func NewAdapter() *Adapter {
+	a := &Adapter{
+		bots:   make(map[string]*botEntry),
+		appIdx: make(map[string]string),
+		dedup:  newDedupStore(),
+		stopCh: make(chan struct{}),
+	}
+	go a.dedup.cleaner(a.stopCh)
+	go a.pollLoop()
+	return a
+}
+
+// Apply is called by the Dispatcher when a robot config is created or updated.
+func (a *Adapter) Apply(ctx context.Context, robot *robottypes.Robot) {
+	tgConf := extractConfig(robot)
+	log.Debug("Apply robot=%s tgConf=%v", robot.MemberID, tgConf != nil)
+	if tgConf != nil {
+		log.Debug("Apply robot=%s enabled=%v token_len=%d host=%q",
+			robot.MemberID, tgConf.Enabled, len(tgConf.BotToken), tgConf.Host)
+	}
+
+	if tgConf == nil || !tgConf.Enabled || tgConf.BotToken == "" {
+		a.removeBot(robot.MemberID)
+		return
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	if existing, ok := a.bots[robot.MemberID]; ok {
+		if existing.bot.Token() == tgConf.BotToken {
+			return
+		}
+		a.removeBotLocked(robot.MemberID)
+	}
+
+	var opts []tgapi.BotOption
+	if tgConf.Host != "" {
+		opts = append(opts, tgapi.WithAPIBase(tgConf.Host))
+	}
+	entry := &botEntry{
+		robotID: robot.MemberID,
+		appID:   tgConf.AppID,
+		bot:     tgapi.NewBot(tgConf.BotToken, tgConf.WebhookSecret, opts...),
+	}
+	a.bots[robot.MemberID] = entry
+	if tgConf.AppID != "" {
+		a.appIdx[tgConf.AppID] = robot.MemberID
+	}
+	log.Info("telegram adapter: registered robot=%s", robot.MemberID)
+}
+
+// Remove is called by the Dispatcher when a robot is deleted.
+func (a *Adapter) Remove(ctx context.Context, robotID string) {
+	a.removeBot(robotID)
+}
+
+// Shutdown stops the polling loop, webhook subscription, and dedup cleaner.
+func (a *Adapter) Shutdown() {
+	close(a.stopCh)
+	a.StopWebhookSubscription()
+	log.Info("telegram adapter: shutdown complete")
+}
+
+// ResolveBot returns the tgapi.Bot for a given appID, used by the webhook
+// verification layer. Returns nil if not found.
+func (a *Adapter) ResolveBot(appID string) *tgapi.Bot {
+	entry, ok := a.resolveByAppID(appID)
+	if !ok {
+		return nil
+	}
+	return entry.bot
+}
+
+// --- Bot registry ---
+
+func (a *Adapter) removeBot(robotID string) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	a.removeBotLocked(robotID)
+}
+
+func (a *Adapter) removeBotLocked(robotID string) {
+	entry, ok := a.bots[robotID]
+	if !ok {
+		return
+	}
+	if entry.appID != "" {
+		delete(a.appIdx, entry.appID)
+	}
+	delete(a.bots, robotID)
+	log.Info("telegram adapter: unregistered robot=%s", robotID)
+}
+
+// snapshot returns a copy of all bot entries for safe iteration outside the lock.
+func (a *Adapter) snapshot() []*botEntry {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	list := make([]*botEntry, 0, len(a.bots))
+	for _, entry := range a.bots {
+		list = append(list, entry)
+	}
+	return list
+}
+
+func (a *Adapter) resolveByAppID(appID string) (*botEntry, bool) {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	robotID, ok := a.appIdx[appID]
+	if !ok {
+		return nil, false
+	}
+	entry, ok := a.bots[robotID]
+	return entry, ok
+}
+
+func extractConfig(robot *robottypes.Robot) *robottypes.TelegramConfig {
+	if robot.Config == nil || robot.Config.Integrations == nil {
+		return nil
+	}
+	return robot.Config.Integrations.Telegram
+}

agent/robot/events/integrations/telegram/webhook.go

@@ -0,0 +1,65 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/go-telegram/bot/models"
+	"github.com/yaoapp/yao/event"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	tgapi "github.com/yaoapp/yao/integrations/telegram"
+	webhooktypes "github.com/yaoapp/yao/openapi/integrations"
+)
+
+// StartWebhookSubscription subscribes to integration.webhook.telegram events.
+// Call once after event.Start().
+func (a *Adapter) StartWebhookSubscription() {
+	ch := make(chan *eventtypes.Event, 128)
+	a.webhSub = event.Subscribe("integration.webhook.telegram", ch)
+	go a.handleWebhooks(ch)
+	log.Info("telegram adapter: webhook subscription started")
+}
+
+// StopWebhookSubscription unsubscribes from webhook events.
+func (a *Adapter) StopWebhookSubscription() {
+	if a.webhSub != "" {
+		event.Unsubscribe(a.webhSub)
+		a.webhSub = ""
+	}
+}
+
+func (a *Adapter) handleWebhooks(ch <-chan *eventtypes.Event) {
+	for ev := range ch {
+		var payload webhooktypes.WebhookPayload
+		if err := ev.Should(&payload); err != nil {
+			log.Error("telegram adapter: invalid webhook event: %v", err)
+			continue
+		}
+
+		entry, ok := a.resolveByAppID(payload.AppID)
+		if !ok {
+			log.Warn("telegram adapter: unknown app_id=%s", payload.AppID)
+			continue
+		}
+
+		headerSecret := payload.Headers["X-Telegram-Bot-Api-Secret-Token"]
+		if !entry.bot.VerifyWebhook(headerSecret) {
+			log.Warn("telegram adapter: webhook secret mismatch app_id=%s", payload.AppID)
+			continue
+		}
+
+		var update models.Update
+		if err := json.Unmarshal(payload.Body, &update); err != nil {
+			log.Error("telegram adapter: webhook unmarshal failed: %v", err)
+			continue
+		}
+
+		cm := tgapi.ConvertUpdate(&update)
+		if cm != nil && cm.HasMedia() {
+			groups := []string{"telegram", entry.robotID}
+			ctx := context.Background()
+			entry.bot.ResolveMedia(ctx, cm, groups)
+		}
+		a.handleMessages(context.Background(), entry, []*tgapi.ConvertedMessage{cm})
+	}
+}

agent/robot/events/log.go

@@ -0,0 +1,5 @@
+package events
+
+import "github.com/yaoapp/yao/agent/robot/logger"
+
+var log = logger.New("events")

agent/robot/events/message.go

@@ -0,0 +1,240 @@
+package events
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	agent "github.com/yaoapp/yao/agent"
+	"github.com/yaoapp/yao/agent/assistant"
+	agentcontext "github.com/yaoapp/yao/agent/context"
+	robotstore "github.com/yaoapp/yao/agent/robot/store"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
+	eventtypes "github.com/yaoapp/yao/event/types"
+	oauthtypes "github.com/yaoapp/yao/openapi/oauth/types"
+)
+
+// handleMessage processes messages from external integrations (Telegram, etc.).
+// It calls the Host Agent with the provided messages and returns a MessageResult.
+// Action detection is done via the Host Agent's Next hook return value.
+func (h *robotHandler) handleMessage(ctx context.Context, ev *eventtypes.Event, resp chan<- eventtypes.Result) {
+	var payload MessagePayload
+	if err := ev.Should(&payload); err != nil {
+		log.Error("message handler: invalid payload: %v", err)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Err: err}
+		}
+		return
+	}
+
+	log.Info("message handler: robot=%s channel=%s msg_id=%s",
+		payload.RobotID, payload.Metadata.Channel, payload.Metadata.MessageID)
+
+	result, err := callHostAgent(ctx, &payload)
+	if err != nil {
+		log.Error("message handler: host agent call failed robot=%s: %v", payload.RobotID, err)
+		if ev.IsCall {
+			resp <- eventtypes.Result{Err: err}
+		}
+		return
+	}
+
+	if reply := getReplyFunc(); reply != nil && result.Message != nil {
+		if err := reply(ctx, result.Message, payload.Metadata); err != nil {
+			log.Error("message handler: reply failed robot=%s channel=%s: %v",
+				payload.RobotID, payload.Metadata.Channel, err)
+		}
+	}
+
+	if ev.IsCall {
+		resp <- eventtypes.Result{Data: result}
+	}
+}
+
+// callHostAgent resolves the Host Agent for the robot and calls it with messages.
+// This avoids importing executor/standard to prevent import cycles; instead it
+// calls the assistant directly via assistant.Get + ast.Stream (same as AgentCaller.Call).
+func callHostAgent(ctx context.Context, payload *MessagePayload) (*MessageResult, error) {
+	hostID, record, err := resolveHostAssistantID(ctx, payload.RobotID)
+	if err != nil {
+		return nil, fmt.Errorf("failed to resolve host agent: %w", err)
+	}
+
+	ast, err := assistant.Get(hostID)
+	if err != nil {
+		return nil, fmt.Errorf("assistant not found: %s: %w", hostID, err)
+	}
+
+	opts := &agentcontext.Options{
+		Skip: &agentcontext.Skip{
+			Search: false,
+		},
+	}
+
+	authorized := &oauthtypes.AuthorizedInfo{
+		UserID: payload.Metadata.SenderID,
+	}
+	chatID := fmt.Sprintf("%s:%s", payload.Metadata.Channel, payload.Metadata.ChatID)
+	agentCtx := agentcontext.New(ctx, authorized, chatID)
+	agentCtx.AssistantID = hostID
+	agentCtx.Referer = "integration"
+	agentCtx.Locale = payload.Metadata.Locale
+	agentCtx.Metadata = map[string]interface{}{
+		"robot_id": payload.RobotID,
+		"channel":  payload.Metadata.Channel,
+	}
+
+	if dsl := agent.GetAgent(); dsl != nil {
+		if cache, err := dsl.GetCacheStore(); err == nil {
+			agentCtx.Cache = cache
+		}
+	}
+
+	defer agentCtx.Release()
+
+	response, err := ast.Stream(agentCtx, payload.Messages, opts)
+	if err != nil {
+		return nil, fmt.Errorf("host agent call failed: %w", err)
+	}
+
+	result := &MessageResult{
+		Metadata: payload.Metadata,
+	}
+
+	if response.Completion != nil {
+		result.Message = &agentcontext.Message{
+			Role:    agentcontext.RoleAssistant,
+			Content: response.Completion.Content,
+		}
+	}
+
+	// Detect action from Next hook return value
+	log.Debug("response.Next type=%T value=%+v", response.Next, response.Next)
+	if action := detectAction(response.Next); action != nil {
+		log.Info("action detected: name=%s payload=%+v", action.Name, action.Payload)
+		result.Action = action
+		if action.Name == "robot.execute" {
+			if execID := executeAction(ctx, payload, record, action); execID != "" {
+				result.ExecutionID = execID
+				result.Message = &agentcontext.Message{
+					Role:    agentcontext.RoleAssistant,
+					Content: taskDeployedMessage(execID, payload.Metadata.Locale),
+				}
+			}
+		}
+	} else {
+		log.Debug("no action detected from response.Next")
+	}
+
+	return result, nil
+}
+
+// executeAction triggers robot execution when the Host Agent returns a
+// confirmed action. Uses the injected TriggerFunc to call robotapi.TriggerManual
+// without creating a circular import.
+func executeAction(ctx context.Context, payload *MessagePayload, record *robotstore.RobotRecord, action *ActionResult) string {
+	trigger := getTriggerFunc()
+	if trigger == nil {
+		log.Warn("message handler: trigger func not registered, cannot execute action for robot=%s", payload.RobotID)
+		return ""
+	}
+
+	data, _ := action.Payload.(map[string]interface{})
+	goals, _ := data["goals"].(string)
+	if goals == "" {
+		log.Warn("message handler: confirmed action has no goals, robot=%s", payload.RobotID)
+		return ""
+	}
+
+	triggerData := &robottypes.TriggerInput{
+		Data: map[string]interface{}{
+			"goals":   goals,
+			"channel": payload.Metadata.Channel,
+			"chat_id": payload.Metadata.ChatID,
+			"extra":   payload.Metadata.Extra,
+		},
+	}
+
+	authorized := &oauthtypes.AuthorizedInfo{
+		UserID: record.MemberID,
+		TeamID: record.TeamID,
+	}
+	rCtx := robottypes.NewContext(ctx, authorized)
+
+	execID, accepted, err := trigger(rCtx, payload.RobotID, robottypes.TriggerHuman, triggerData)
+	if err != nil {
+		log.Error("message handler: execute action failed robot=%s: %v", payload.RobotID, err)
+		return ""
+	}
+	if !accepted {
+		log.Warn("message handler: execute action not accepted robot=%s", payload.RobotID)
+		return ""
+	}
+
+	log.Info("message handler: execution triggered robot=%s exec_id=%s", payload.RobotID, execID)
+	return execID
+}
+
+// detectAction checks the Next hook return value for a confirmed action.
+// The Host Agent returns { data: { confirmed: true, robot_id: "...", goals: "..." } }
+// when it detects a confirm_task tool call.
+func detectAction(next interface{}) *ActionResult {
+	if next == nil {
+		return nil
+	}
+
+	m, ok := next.(map[string]interface{})
+	if !ok {
+		return nil
+	}
+
+	// Next hook may return { data: { confirmed, ... } } or flat { confirmed, ... }
+	data, _ := m["data"].(map[string]interface{})
+	if data == nil {
+		data = m
+	}
+
+	confirmed, _ := data["confirmed"].(bool)
+	if !confirmed {
+		return nil
+	}
+
+	return &ActionResult{
+		Name:    "robot.execute",
+		Payload: data,
+	}
+}
+
+// resolveHostAssistantID resolves the host assistant ID from a robot member ID.
+// Mirrors the logic in openapi/agent/robot/completions.go.
+func resolveHostAssistantID(ctx context.Context, memberID string) (string, *robotstore.RobotRecord, error) {
+	store := robotstore.NewRobotStore()
+	record, err := store.Get(ctx, memberID)
+	if err != nil {
+		return "", nil, fmt.Errorf("failed to get robot: %w", err)
+	}
+	if record == nil {
+		return "", nil, fmt.Errorf("robot not found: %s", memberID)
+	}
+
+	config, err := robottypes.ParseConfig(record.RobotConfig)
+	if err != nil {
+		return "", nil, fmt.Errorf("failed to parse robot config: %w", err)
+	}
+
+	var hostID string
+	if config != nil && config.Resources != nil {
+		hostID = config.Resources.GetPhaseAgent(robottypes.PhaseHost)
+	} else {
+		hostID = "__yao." + string(robottypes.PhaseHost)
+	}
+
+	return hostID, record, nil
+}
+
+func taskDeployedMessage(execID string, locale string) string {
+	if strings.HasPrefix(locale, "zh") {
+		return fmt.Sprintf("任务已部署（执行编号: %s），完成后会将结果发送给你。", execID)
+	}
+	return fmt.Sprintf("Task deployed (execution: %s). You will receive results once completed.", execID)
+}

agent/robot/executor/standard/delivery.go

@@ -7,7 +7,7 @@ import (
 	"time"
 
 	"github.com/yaoapp/gou/model"
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	robotevents "github.com/yaoapp/yao/agent/robot/events"
 	robottypes "github.com/yaoapp/yao/agent/robot/types"
 	"github.com/yaoapp/yao/event"
@@ -82,16 +82,31 @@ func (e *Executor) RunDelivery(ctx *robottypes.Context, exec *robottypes.Executi
 // Registered handlers (see events/handlers.go) route to email/webhook/process channels.
 func (e *Executor) pushDeliveryEvent(ctx *robottypes.Context, exec *robottypes.Execution, robot *robottypes.Robot) error {
 	prefs := buildDeliveryPreferences(robot)
+
+	chatID := exec.ChatID
+	var extra map[string]any
+	if exec.Input != nil && exec.Input.Data != nil {
+		if sourceChatID, ok := exec.Input.Data["chat_id"].(string); ok && sourceChatID != "" {
+			if channel, ok := exec.Input.Data["channel"].(string); ok && channel != "" {
+				chatID = channel + ":" + sourceChatID
+			}
+		}
+		if e, ok := exec.Input.Data["extra"].(map[string]any); ok {
+			extra = e
+		}
+	}
+
 	_, err := event.Push(ctx.Context, robotevents.Delivery, robotevents.DeliveryPayload{
 		ExecutionID: exec.ID,
 		MemberID:    exec.MemberID,
 		TeamID:      exec.TeamID,
-		ChatID:      exec.ChatID,
+		ChatID:      chatID,
 		Content:     exec.Delivery.Content,
 		Preferences: prefs,
+		Extra:       extra,
 	})
 	if err != nil {
-		log.Error("delivery event push failed: execution=%s error=%v", exec.ID, err)
+		kunlog.Error("delivery event push failed: execution=%s error=%v", exec.ID, err)
 	}
 	return nil
 }

agent/robot/executor/standard/executor.go

@@ -6,7 +6,7 @@ import (
 	"sync/atomic"
 	"time"
 
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	agentcontext "github.com/yaoapp/yao/agent/context"
 	robotevents "github.com/yaoapp/yao/agent/robot/events"
 	"github.com/yaoapp/yao/agent/robot/executor/types"
@@ -122,7 +122,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		record := store.FromExecution(exec)
 		if err := e.store.Save(ctx.Context, record); err != nil {
 			// Log warning but don't fail execution
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"member_id":    exec.MemberID,
 				"error":        err,
@@ -132,7 +132,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		// If goals were pre-injected, persist them and update the execution title
 		if exec.Goals != nil && exec.Goals.Content != "" {
 			if err := e.store.UpdatePhase(ctx.Context, exec.ID, robottypes.PhaseGoals, exec.Goals); err != nil {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"member_id":    exec.MemberID,
 					"error":        err,
@@ -147,7 +147,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 
 	// Acquire execution slot
 	if !robot.TryAcquireSlot(exec) {
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"member_id":    exec.MemberID,
 		}).Warn("Execution quota exceeded")
@@ -163,7 +163,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		// Update robot status to idle if no more running executions
 		if robot.RunningCount() == 0 && !e.config.SkipPersistence && e.robotStore != nil {
 			if err := e.robotStore.UpdateStatus(ctx.Context, robot.MemberID, robottypes.RobotIdle); err != nil {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"member_id": robot.MemberID,
 					"error":     err,
 				}).Warn("Failed to update robot status to idle: %v", err)
@@ -186,7 +186,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 
 	// Update status to running
 	exec.Status = robottypes.ExecRunning
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"trigger_type": string(exec.TriggerType),
@@ -195,7 +195,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	// Persist running status
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateStatus(ctx.Context, exec.ID, robottypes.ExecRunning, ""); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist running status: %v", err)
@@ -205,7 +205,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	// Update robot status to working (when execution starts)
 	if !e.config.SkipPersistence && e.robotStore != nil {
 		if err := e.robotStore.UpdateStatus(ctx.Context, robot.MemberID, robottypes.RobotWorking); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"member_id": robot.MemberID,
 				"error":     err,
 			}).Warn("Failed to update robot status to working: %v", err)
@@ -216,7 +216,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	if dataStr, ok := data.(string); ok && dataStr == "simulate_failure" {
 		exec.Status = robottypes.ExecFailed
 		exec.Error = "simulated failure"
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"member_id":    exec.MemberID,
 		}).Warn("Simulated failure triggered")
@@ -239,7 +239,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 		if err := e.runPhase(ctx, exec, phase, data, control); err != nil {
 			// Check if execution was suspended (needs human input)
 			if err == robottypes.ErrExecutionSuspended {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"member_id":    exec.MemberID,
 					"phase":        string(phase),
@@ -257,7 +257,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 				// Update UI field for cancellation with i18n
 				e.updateUIFields(ctx, exec, "", getLocalizedMessage(locale, "cancelled"))
 
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"member_id":    exec.MemberID,
 					"phase":        string(phase),
@@ -280,7 +280,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 			failureMsg := failedPrefix + phaseName
 			e.updateUIFields(ctx, exec, "", failureMsg)
 
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"member_id":    exec.MemberID,
 				"phase":        string(phase),
@@ -303,7 +303,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	e.updateUIFields(ctx, exec, "", getLocalizedMessage(locale, "completed"))
 
 	duration := now.Sub(exec.StartTime)
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"duration_ms":  duration.Milliseconds(),
@@ -312,7 +312,7 @@ func (e *Executor) ExecuteWithControl(ctx *robottypes.Context, robot *robottypes
 	// Persist completed status
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateStatus(ctx.Context, exec.ID, robottypes.ExecCompleted, ""); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist completed status: %v", err)
@@ -348,7 +348,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 
 	exec.Phase = phase
 
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"phase":        string(phase),
@@ -357,7 +357,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 	// Persist phase change immediately (so frontend sees current phase)
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdatePhase(ctx.Context, exec.ID, phase, nil); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"phase":        string(phase),
 				"error":        err,
@@ -390,14 +390,14 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 
 	if err != nil {
 		if err == robottypes.ErrExecutionSuspended {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"member_id":    exec.MemberID,
 				"phase":        string(phase),
 			}).Info("Phase suspended: %s (waiting for human input)", phase)
 			return err
 		}
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"member_id":    exec.MemberID,
 			"phase":        string(phase),
@@ -412,7 +412,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 		if phaseData != nil {
 			if err := e.store.UpdatePhase(ctx.Context, exec.ID, phase, phaseData); err != nil {
 				// Log warning but don't fail execution
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"execution_id": exec.ID,
 					"phase":        string(phase),
 					"error":        err,
@@ -426,7 +426,7 @@ func (e *Executor) runPhase(ctx *robottypes.Context, exec *robottypes.Execution,
 	}
 
 	phaseDuration := time.Since(phaseStart).Milliseconds()
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"phase":        string(phase),
@@ -613,7 +613,7 @@ func (e *Executor) updateUIFields(ctx *robottypes.Context, exec *robottypes.Exec
 	// Persist to database
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateUIFields(ctx.Context, exec.ID, name, currentTaskName); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to update UI fields: %v", err)
@@ -638,7 +638,7 @@ func (e *Executor) updateTasksState(ctx *robottypes.Context, exec *robottypes.Ex
 	}
 
 	if err := e.store.UpdateTasks(ctx.Context, exec.ID, exec.Tasks, current); err != nil {
-		log.With(log.F{
+		kunlog.With(kunlog.F{
 			"execution_id": exec.ID,
 			"error":        err,
 		}).Warn("Failed to update tasks state: %v", err)
@@ -759,14 +759,14 @@ func (e *Executor) Suspend(ctx *robottypes.Context, exec *robottypes.Execution,
 		e.updateTasksState(ctx, exec)
 		// Persist P3 results so UI can show completed tasks while waiting (§16.26)
 		if err := e.store.UpdatePhase(ctx.Context, exec.ID, robottypes.PhaseRun, exec.Results); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist partial results on suspend: %v", err)
 		}
 		// Persist suspend state atomically
 		if err := e.store.UpdateSuspendState(ctx.Context, exec.ID, taskID, question, exec.ResumeContext); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"task_id":      taskID,
 				"error":        err,
@@ -774,7 +774,7 @@ func (e *Executor) Suspend(ctx *robottypes.Context, exec *robottypes.Execution,
 		}
 	}
 
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"task_id":      taskID,
@@ -854,7 +854,7 @@ func (e *Executor) Resume(ctx *robottypes.Context, execID string, reply string)
 		robot.RemoveExecution(exec.ID)
 		if robot.RunningCount() == 0 && !e.config.SkipPersistence && e.robotStore != nil {
 			if err := e.robotStore.UpdateStatus(ctx.Context, robot.MemberID, robottypes.RobotIdle); err != nil {
-				log.With(log.F{
+				kunlog.With(kunlog.F{
 					"member_id": robot.MemberID,
 					"error":     err,
 				}).Warn("Failed to update robot status to idle after resume: %v", err)
@@ -901,14 +901,14 @@ func (e *Executor) Resume(ctx *robottypes.Context, execID string, reply string)
 
 	if !e.config.SkipPersistence && e.store != nil {
 		if err := e.store.UpdateResumeState(ctx.Context, exec.ID); err != nil {
-			log.With(log.F{
+			kunlog.With(kunlog.F{
 				"execution_id": exec.ID,
 				"error":        err,
 			}).Warn("Failed to persist resume state: %v", err)
 		}
 	}
 
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"execution_id": exec.ID,
 		"member_id":    exec.MemberID,
 		"reply_len":    len(reply),

agent/robot/executor/standard/host.go

@@ -4,7 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	robottypes "github.com/yaoapp/yao/agent/robot/types"
 )
 
@@ -31,7 +31,7 @@ func (e *Executor) CallHostAgent(ctx *robottypes.Context, robot *robottypes.Robo
 		return nil, fmt.Errorf("failed to marshal host input: %w", err)
 	}
 
-	log.Info("calling Host Agent %s for scenario=%s chatID=%s", agentID, input.Scenario, chatID)
+	kunlog.Info("calling Host Agent %s for scenario=%s chatID=%s", agentID, input.Scenario, chatID)
 
 	caller := NewConversationCaller(chatID)
 	result, err := caller.CallWithMessages(ctx, agentID, string(inputJSON))
@@ -42,7 +42,7 @@ func (e *Executor) CallHostAgent(ctx *robottypes.Context, robot *robottypes.Robo
 	data, err := result.GetJSON()
 	if err != nil {
 		text := result.GetText()
-		log.Warn("Host Agent returned non-JSON response, treating as confirm: %s", text)
+		kunlog.Warn("Host Agent returned non-JSON response, treating as confirm: %s", text)
 		return &robottypes.HostOutput{
 			Reply:  text,
 			Action: robottypes.HostActionConfirm,

agent/robot/executor/standard/log.go

@@ -5,19 +5,15 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/yaoapp/kun/log"
+	kunlog "github.com/yaoapp/kun/log"
 	"github.com/yaoapp/yao/config"
 
+	"github.com/yaoapp/yao/agent/robot/logger"
 	robottypes "github.com/yaoapp/yao/agent/robot/types"
 )
 
-// execLogger provides structured, developer-facing logging for a single Robot execution.
-// Each execution (Executor.ExecuteWithControl) creates one instance; it is passed to
-// RunTasks (P2) and Runner (P3) so every log line carries the same identity.
-//
-// Output routing:
-//   - development mode (config.IsDevelopment): human-readable console via fmt.Printf
-//   - production mode: structured fields via kun/log
+var log = logger.New("exec")
+
 type execLogger struct {
 	robot  *robottypes.Robot
 	execID string
@@ -42,15 +38,14 @@ func (l *execLogger) connector() string {
 }
 
 // ---------------------------------------------------------------------------
-// P2: Task Overview — called once after RunTasks successfully generates tasks
+// P2: Task Overview
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logTaskOverview(tasks []robottypes.Task) {
 	if config.IsDevelopment() {
 		l.devTaskOverview(tasks)
 	}
-	// Always emit structured log (Info level, hidden in prod unless needed)
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"phase":          "tasks",
@@ -60,11 +55,21 @@ func (l *execLogger) logTaskOverview(tasks []robottypes.Task) {
 }
 
 func (l *execLogger) devTaskOverview(tasks []robottypes.Task) {
+	w := logger.Gray
+	h := logger.BoldCyan
+	v := logger.White
+	r := logger.Reset
+
 	var sb strings.Builder
-	sb.WriteString(fmt.Sprintf("%s ══════ P2: Task Overview ══════\n", l.prefix()))
+	sb.WriteString(fmt.Sprintf("\n%s%s%s\n", h, strings.Repeat("═", 60), r))
+	sb.WriteString(fmt.Sprintf("%s  TASK OVERVIEW%s\n", h, r))
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", h, strings.Repeat("─", 60), r))
+	sb.WriteString(fmt.Sprintf("%s  Robot:     %s%s%s\n", w, v, l.robotID(), r))
+	sb.WriteString(fmt.Sprintf("%s  Exec:      %s%s%s\n", w, v, l.execID, r))
 	if l.connector() != "" {
-		sb.WriteString(fmt.Sprintf("  Language Model: %s\n", l.connector()))
+		sb.WriteString(fmt.Sprintf("%s  Model:     %s%s%s\n", w, v, l.connector(), r))
 	}
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", w, strings.Repeat("─", 60), r))
 	for i, t := range tasks {
 		desc := t.Description
 		if desc == "" && len(t.Messages) > 0 {
@@ -72,22 +77,26 @@ func (l *execLogger) devTaskOverview(tasks []robottypes.Task) {
 				desc = s
 			}
 		}
-		desc = truncate(desc, 80)
-		sb.WriteString(fmt.Sprintf("  #%d %s [%s:%s] %q\n", i+1, t.ID, t.ExecutorType, t.ExecutorID, desc))
+		desc = truncate(desc, 72)
+		sb.WriteString(fmt.Sprintf("%s  #%d %s%s%s [%s:%s]\n", w, i+1, v, t.ID, r, t.ExecutorType, t.ExecutorID))
+		sb.WriteString(fmt.Sprintf("%s     %s%s\n", w, desc, r))
 	}
-	sb.WriteString(fmt.Sprintf("  Total: %d tasks\n", len(tasks)))
-	fmt.Print(sb.String())
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", w, strings.Repeat("─", 60), r))
+	sb.WriteString(fmt.Sprintf("%s  Total: %s%d tasks%s\n", w, v, len(tasks), r))
+	sb.WriteString(fmt.Sprintf("%s%s%s\n", h, strings.Repeat("═", 60), r))
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------
-// P3: Task Input — called before each task execution with the full prompt
+// P3: Task Input
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logTaskInput(task *robottypes.Task, prompt string) {
 	if config.IsDevelopment() {
 		l.devTaskInput(task, prompt)
 	}
-	log.With(log.F{
+	kunlog.With(kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"task_id":        task.ID,
@@ -99,14 +108,19 @@ func (l *execLogger) logTaskInput(task *robottypes.Task, prompt string) {
 }
 
 func (l *execLogger) devTaskInput(task *robottypes.Task, prompt string) {
-	sep := strings.Repeat("─", 40)
-	fmt.Printf("%s ▶ Task %s [%s:%s]\n", l.prefix(), task.ID, task.ExecutorType, task.ExecutorID)
-	fmt.Printf("  Prompt (%d chars):\n  %s\n%s\n  %s\n",
-		len(prompt), sep, indentText(prompt, "  "), sep)
+	w := logger.Gray
+	v := logger.White
+	r := logger.Reset
+
+	var sb strings.Builder
+	sb.WriteString(fmt.Sprintf("%s  ▶ Task %s%s%s [%s:%s]  Prompt: %d chars%s\n",
+		w, v, task.ID, w, task.ExecutorType, task.ExecutorID, len(prompt), r))
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------
-// P3: Task Output — called after each task execution with the result
+// P3: Task Output
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logTaskOutput(task *robottypes.Task, result *robottypes.TaskResult) {
@@ -114,7 +128,7 @@ func (l *execLogger) logTaskOutput(task *robottypes.Task, result *robottypes.Tas
 		l.devTaskOutput(task, result)
 	}
 
-	fields := log.F{
+	fields := kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"task_id":        result.TaskID,
@@ -130,24 +144,39 @@ func (l *execLogger) logTaskOutput(task *robottypes.Task, result *robottypes.Tas
 		fields["error"] = result.Error
 	}
 	if result.Success {
-		log.With(fields).Info("Task completed: %s (%dms)", result.TaskID, result.Duration)
+		kunlog.With(fields).Info("Task completed: %s (%dms)", result.TaskID, result.Duration)
 	} else {
-		log.With(fields).Warn("Task failed: %s (%dms) %s", result.TaskID, result.Duration, result.Error)
+		kunlog.With(fields).Warn("Task failed: %s (%dms) %s", result.TaskID, result.Duration, result.Error)
 	}
 }
 
 func (l *execLogger) devTaskOutput(task *robottypes.Task, result *robottypes.TaskResult) {
+	w := logger.Gray
+	v := logger.White
+	g := logger.BoldGreen
+	rd := logger.BoldRed
+	r := logger.Reset
+
+	var sb strings.Builder
 	if result.Success {
-		fmt.Printf("%s ✓ Task %s completed (%dms)\n", l.prefix(), result.TaskID, result.Duration)
-		fmt.Printf("  Output: %s\n", outputSummary(result.Output))
+		sb.WriteString(fmt.Sprintf("%s  ✓ %s%s%s completed %s(%dms)%s\n",
+			g, v, result.TaskID, g, w, result.Duration, r))
+		out := outputSummary(result.Output)
+		if len(out) > 120 {
+			out = out[:120] + "..."
+		}
+		sb.WriteString(fmt.Sprintf("%s    Output: %s%s%s\n", w, v, out, r))
 	} else {
-		fmt.Printf("%s ✗ Task %s failed (%dms)\n", l.prefix(), result.TaskID, result.Duration)
-		fmt.Printf("  Error: %s\n", result.Error)
+		sb.WriteString(fmt.Sprintf("%s  ✗ %s%s%s failed %s(%dms)%s\n",
+			rd, v, result.TaskID, rd, w, result.Duration, r))
+		sb.WriteString(fmt.Sprintf("%s    Error:  %s%s%s\n", w, logger.Red, result.Error, r))
 	}
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------
-// Agent Call — called after every AgentCaller.Call returns
+// Agent Call
 // ---------------------------------------------------------------------------
 
 func (l *execLogger) logAgentCall(agentID string, result *CallResult) {
@@ -158,7 +187,7 @@ func (l *execLogger) logAgentCall(agentID string, result *CallResult) {
 		l.devAgentCall(agentID, result)
 	}
 
-	fields := log.F{
+	fields := kunlog.F{
 		"robot_id":       l.robotID(),
 		"execution_id":   l.execID,
 		"agent_id":       agentID,
@@ -169,16 +198,25 @@ func (l *execLogger) logAgentCall(agentID string, result *CallResult) {
 		fields["next_type"] = fmt.Sprintf("%T", result.Next)
 		fields["next_len"] = outputLen(result.Next)
 	}
-	log.With(fields).Info("Agent call: %s (content=%d, next=%T)", agentID, len(result.Content), result.Next)
+	kunlog.With(fields).Info("Agent call: %s (content=%d, next=%T)", agentID, len(result.Content), result.Next)
 }
 
 func (l *execLogger) devAgentCall(agentID string, result *CallResult) {
-	nextInfo := "<nil>"
+	w := logger.Gray
+	v := logger.White
+	c := logger.Cyan
+	r := logger.Reset
+
+	nextInfo := "—"
 	if result.Next != nil {
-		nextInfo = fmt.Sprintf("%T(len=%d)", result.Next, outputLen(result.Next))
+		nextInfo = fmt.Sprintf("%T (len=%d)", result.Next, outputLen(result.Next))
 	}
-	fmt.Printf("%s   Agent(%s) → Content(len=%d) Next=%s\n",
-		l.prefix(), agentID, len(result.Content), nextInfo)
+
+	var sb strings.Builder
+	sb.WriteString(fmt.Sprintf("%s  → Agent(%s%s%s) Content: %s%d%s chars  Next: %s%s%s\n",
+		c, v, agentID, c, v, len(result.Content), w, v, nextInfo, r))
+
+	logger.Raw(sb.String())
 }
 
 // ---------------------------------------------------------------------------

agent/robot/logger/logger.go

@@ -0,0 +1,100 @@
+package logger
+
+import (
+	"fmt"
+
+	kunlog "github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/config"
+)
+
+const (
+	Reset     = "\033[0m"
+	Red       = "\033[31m"
+	Green     = "\033[32m"
+	Yellow    = "\033[33m"
+	Cyan      = "\033[36m"
+	White     = "\033[37m"
+	Gray      = "\033[90m"
+	BoldCyan  = "\033[1;36m"
+	BoldGreen = "\033[1;32m"
+	BoldRed   = "\033[1;31m"
+
+	reset  = Reset
+	red    = Red
+	yellow = Yellow
+	cyan   = Cyan
+	gray   = Gray
+)
+
+// Logger provides robot-level structured logging. All integration adapters,
+// dispatchers, event handlers, etc. share this implementation.
+//
+// Dev mode  → colored stdout + kun/log.Trace (unified).
+// Prod mode → kun/log at matching level.
+type Logger struct {
+	tag string
+}
+
+// New creates a Logger tagged with the given component name
+// (e.g. "telegram", "dispatcher", "message", "delivery").
+func New(tag string) *Logger {
+	return &Logger{tag: tag}
+}
+
+func (l *Logger) prefix() string {
+	return fmt.Sprintf("[robot:%s]", l.tag)
+}
+
+func (l *Logger) Trace(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  → %s %s%s\n", gray, l.prefix(), msg, reset)
+	}
+	kunlog.Trace("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Debug(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  • %s %s%s\n", gray, l.prefix(), msg, reset)
+	}
+	kunlog.Debug("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Info(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  ℹ %s %s%s\n", cyan, l.prefix(), msg, reset)
+	}
+	kunlog.Info("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Warn(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  ⚠ %s %s%s\n", yellow, l.prefix(), msg, reset)
+	}
+	kunlog.Warn("%s %s", l.prefix(), msg)
+}
+
+func (l *Logger) Error(format string, args ...interface{}) {
+	msg := fmt.Sprintf(format, args...)
+	if config.IsDevelopment() {
+		fmt.Printf("%s  ✗ %s %s%s\n", red, l.prefix(), msg, reset)
+	}
+	kunlog.Error("%s %s", l.prefix(), msg)
+}
+
+// IsDev returns true when running in development mode.
+func IsDev() bool {
+	return config.IsDevelopment()
+}
+
+// Raw writes pre-formatted text directly to stdout in dev mode only.
+// Use for rich multi-line output (box-style logs, tables, etc.)
+// that should bypass the standard single-line prefix format.
+func Raw(s string) {
+	if config.IsDevelopment() {
+		fmt.Print(s)
+	}
+}

agent/robot/pool/worker.go

@@ -1,13 +1,15 @@
 package pool
 
 import (
-	"fmt"
 	"sync"
 	"time"
 
+	"github.com/yaoapp/yao/agent/robot/logger"
 	"github.com/yaoapp/yao/agent/robot/types"
 )
 
+var log = logger.New("pool")
+
 // Worker represents a worker goroutine that processes jobs
 type Worker struct {
 	id       int
@@ -96,13 +98,13 @@ func (w *Worker) execute(item *QueueItem) {
 		// so that Resume can find it later (§16.1).
 		if err == types.ErrExecutionSuspended {
 			if execution != nil {
-				fmt.Printf("Worker %d: Execution %s suspended for robot %s (waiting for input)\n",
+				log.Info("Worker %d: Execution %s suspended for robot %s (waiting for input)",
 					w.id, execution.ID, item.Robot.MemberID)
 			}
 			return
 		}
 
-		fmt.Printf("Worker %d: Execution failed for robot %s: %v\n",
+		log.Error("Worker %d: Execution failed for robot %s: %v",
 			w.id, item.Robot.MemberID, err)
 		// Notify completion callback with appropriate status
 		if w.pool.onComplete != nil {
@@ -116,7 +118,7 @@ func (w *Worker) execute(item *QueueItem) {
 	}
 
 	if execution != nil {
-		fmt.Printf("Worker %d: Execution %s completed for robot %s (status: %s)\n",
+		log.Info("Worker %d: Execution %s completed for robot %s (status: %s)",
 			w.id, execution.ID, item.Robot.MemberID, execution.Status)
 		// Notify completion callback
 		if w.pool.onComplete != nil {
@@ -131,8 +133,7 @@ func (w *Worker) requeue(item *QueueItem, reason string) {
 	// - If queue has space: task waits for robot quota
 	// - If queue is full: system is overloaded, drop task
 	if !w.pool.queue.Enqueue(item) {
-		// Queue full = system overloaded, drop task (protective discard)
-		fmt.Printf("Worker %d: Task for robot %s dropped (queue full, %s)\n",
+		log.Warn("Worker %d: Task for robot %s dropped (queue full, %s)",
 			w.id, item.Robot.MemberID, reason)
 	}
 }

agent/robot/robot.go

@@ -1,51 +1,66 @@
 package robot
 
 import (
+	"context"
+
 	"github.com/yaoapp/yao/agent/robot/cache"
 	"github.com/yaoapp/yao/agent/robot/dedup"
+	"github.com/yaoapp/yao/agent/robot/events/integrations"
+	"github.com/yaoapp/yao/agent/robot/events/integrations/telegram"
 	"github.com/yaoapp/yao/agent/robot/executor"
+	"github.com/yaoapp/yao/agent/robot/logger"
 	"github.com/yaoapp/yao/agent/robot/manager"
 	"github.com/yaoapp/yao/agent/robot/plan"
 	"github.com/yaoapp/yao/agent/robot/pool"
 	"github.com/yaoapp/yao/agent/robot/store"
+	robottypes "github.com/yaoapp/yao/agent/robot/types"
 )
 
 var (
-	// Global instances (will be initialized in Init)
-	globalManager  *manager.Manager
-	globalCache    *cache.Cache
-	globalPool     *pool.Pool
-	globalDedup    *dedup.Dedup
-	globalStore    *store.Store
-	globalExecutor executor.Executor
-	globalPlan     *plan.Plan
+	log = logger.New("robot")
+
+	globalManager    *manager.Manager
+	globalCache      *cache.Cache
+	globalPool       *pool.Pool
+	globalDedup      *dedup.Dedup
+	globalStore      *store.Store
+	globalExecutor   executor.Executor
+	globalPlan       *plan.Plan
+	globalDispatcher *integrations.Dispatcher
 )
 
 // Init initializes the robot agent system
-// Stub: placeholder (will be implemented in Phase 3)
 func Init() error {
-	// Initialize global instances
 	globalCache = cache.New()
 	globalDedup = dedup.New()
 	globalStore = store.New()
-	globalPool = pool.New() // Default pool size
+	globalPool = pool.New()
 	globalExecutor = executor.New()
 	globalManager = manager.New()
 	globalPlan = plan.New()
 
-	// TODO Phase 3: Start manager and pool
-	// return globalManager.Start()
+	// Load robots into cache from database before starting dispatcher
+	rCtx := robottypes.NewContext(context.Background(), nil)
+	if err := globalCache.Load(rCtx); err != nil {
+		log.Warn("robot.Init: cache load failed (will rely on config events): %v", err)
+	}
+
+	adapters := map[string]integrations.Adapter{
+		"telegram": telegram.NewAdapter(),
+	}
+	globalDispatcher = integrations.NewDispatcher(globalCache, adapters)
+	if err := globalDispatcher.Start(context.Background()); err != nil {
+		return err
+	}
 
 	return nil
 }
 
 // Shutdown gracefully shuts down the robot agent system
-// Stub: placeholder (will be implemented in Phase 3)
 func Shutdown() error {
-	// TODO Phase 3: Stop manager and pool
-	// if globalManager != nil {
-	//     return globalManager.Stop()
-	// }
+	if globalDispatcher != nil {
+		globalDispatcher.Stop()
+	}
 	return nil
 }
 

agent/robot/types/config.go

@@ -19,6 +19,46 @@ type Config struct {
 	Events        []Event              `json:"events,omitempty"`
 	Executor      *ExecutorConfig      `json:"executor,omitempty"`       // executor mode settings
 	DefaultLocale string               `json:"default_locale,omitempty"` // default language for clock/event triggers ("en", "zh")
+	Integrations  *Integrations        `json:"integrations,omitempty"`   // external channel integrations (telegram, etc.)
+}
+
+// Integrations holds configuration for external platform integrations.
+type Integrations struct {
+	Telegram *TelegramConfig `json:"telegram,omitempty"`
+	Feishu   *FeishuConfig   `json:"feishu,omitempty"`
+	DingTalk *DingTalkConfig `json:"dingtalk,omitempty"`
+	Discord  *DiscordConfig  `json:"discord,omitempty"`
+}
+
+// TelegramConfig holds Telegram Bot integration settings.
+type TelegramConfig struct {
+	Enabled       bool   `json:"enabled"`
+	BotToken      string `json:"bot_token"`
+	Host          string `json:"host,omitempty"`           // custom Bot API server, defaults to https://api.telegram.org
+	AppID         string `json:"app_id,omitempty"`         // auto-generated, used for webhook URL routing
+	ChatID        string `json:"chat_id,omitempty"`        // default reply chat
+	WebhookSecret string `json:"webhook_secret,omitempty"` // sent with SetWebhook, verified on incoming webhooks
+}
+
+// FeishuConfig holds Feishu (Lark) Bot integration settings.
+type FeishuConfig struct {
+	Enabled   bool   `json:"enabled"`
+	AppID     string `json:"app_id"`
+	AppSecret string `json:"app_secret"`
+}
+
+// DingTalkConfig holds DingTalk Bot integration settings.
+type DingTalkConfig struct {
+	Enabled      bool   `json:"enabled"`
+	ClientID     string `json:"client_id"`
+	ClientSecret string `json:"client_secret"`
+}
+
+// DiscordConfig holds Discord Bot integration settings.
+type DiscordConfig struct {
+	Enabled  bool   `json:"enabled"`
+	BotToken string `json:"bot_token"`
+	AppID    string `json:"app_id,omitempty"`
 }
 
 // ExecutorConfig - executor settings

agent/search/handlers/db/handler.go

@@ -164,10 +164,13 @@ func (h *Handler) SearchWithContext(ctx *agentContext.Context, req *types.Reques
 		}, nil
 	}
 
-	// 3. Merge preset conditions into generated DSL
+	// 3. Sanitize generated DSL (remove unsupported wildcards like "*")
+	h.sanitizeDSL(result.DSL)
+
+	// 4. Merge preset conditions into generated DSL
 	h.mergeDSLConditions(result.DSL, req)
 
-	// 4. Execute QueryDSL using gou query engine
+	// 5. Execute QueryDSL using gou query engine
 	records, err := h.executeDSL(result.DSL)
 	if err != nil {
 		return &types.Result{
@@ -181,7 +184,7 @@ func (h *Handler) SearchWithContext(ctx *agentContext.Context, req *types.Reques
 		}, nil
 	}
 
-	// 5. Determine the primary model for result formatting
+	// 6. Determine the primary model for result formatting
 	// Use the "from" table from DSL, or first model
 	primaryModelID := modelIDs[0]
 	if result.DSL.From != nil && result.DSL.From.Name != "" {
@@ -199,7 +202,7 @@ func (h *Handler) SearchWithContext(ctx *agentContext.Context, req *types.Reques
 		primaryModel, _ = model.Get(primaryModelID) // May be nil, that's ok
 	}
 
-	// 6. Convert records to ResultItems
+	// 7. Convert records to ResultItems
 	items := h.convertToResultItems(records, primaryModelID, primaryModel, req.Source)
 
 	// Apply limit
@@ -207,7 +210,7 @@ func (h *Handler) SearchWithContext(ctx *agentContext.Context, req *types.Reques
 		items = items[:maxResults]
 	}
 
-	// 7. Convert DSL to map for storage
+	// 8. Convert DSL to map for storage
 	dslMap := h.dslToMap(result.DSL)
 
 	return &types.Result{
@@ -282,31 +285,52 @@ func (h *Handler) buildModelSchema(mod *model.Model) map[string]interface{} {
 	}
 }
 
-// executeDSL executes the QueryDSL and returns records
-func (h *Handler) executeDSL(dsl interface{}) ([]map[string]interface{}, error) {
-	// Get the default query engine
+// sanitizeDSL cleans up LLM-generated DSL to remove unsupported constructs.
+// The QueryDSL engine does not support wildcard "*" in select fields;
+// an empty select list naturally returns all columns.
+func (h *Handler) sanitizeDSL(dsl *gou.QueryDSL) {
+	if dsl == nil {
+		return
+	}
+
+	if len(dsl.Select) > 0 {
+		cleaned := make([]gou.Expression, 0, len(dsl.Select))
+		for _, expr := range dsl.Select {
+			if expr.Field != "*" {
+				cleaned = append(cleaned, expr)
+			}
+		}
+		dsl.Select = cleaned
+	}
+}
+
+// executeDSL executes the QueryDSL and returns records.
+// Uses recover to convert panics from MustGet into errors.
+func (h *Handler) executeDSL(dsl interface{}) (records []map[string]interface{}, err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			err = fmt.Errorf("query execution panic: %v", r)
+		}
+	}()
+
 	engine, err := query.Select("default")
 	if err != nil {
 		return nil, fmt.Errorf("query engine not found: %w", err)
 	}
 
-	// Marshal DSL to JSON
 	dslJSON, err := json.Marshal(dsl)
 	if err != nil {
 		return nil, fmt.Errorf("failed to marshal DSL: %w", err)
 	}
 
-	// Load and execute the query
 	q, err := engine.Load(json.RawMessage(dslJSON))
 	if err != nil {
 		return nil, fmt.Errorf("failed to load DSL: %w", err)
 	}
 
-	// Execute query
 	rawRecords := q.Get(nil)
 
-	// Convert to map[string]interface{}
-	records := make([]map[string]interface{}, 0, len(rawRecords))
+	records = make([]map[string]interface{}, 0, len(rawRecords))
 	for _, rec := range rawRecords {
 		records = append(records, map[string]interface{}(rec))
 	}

agent/store/xun/message.go

@@ -140,20 +140,26 @@ func (store *Xun) GetMessages(chatID string, filter types.MessageFilter) ([]*typ
 		qb.Where("type", filter.Type)
 	}
 
-	// Apply pagination (MySQL requires LIMIT when using OFFSET)
-	if filter.Limit > 0 {
+	// When Limit is specified WITHOUT Offset, we want the N most-recent
+	// messages.  Strategy: query DESC to get the latest rows, then reverse
+	// the slice so the caller receives them in chronological (ASC) order.
+	// When Offset is also present, the caller is doing forward pagination,
+	// so we keep ASC order and apply Limit+Offset normally.
+	needReverse := false
+	if filter.Limit > 0 && filter.Offset <= 0 {
 		qb.Limit(filter.Limit)
+		qb.OrderBy("id", "desc")
+		needReverse = true
+	} else if filter.Limit > 0 && filter.Offset > 0 {
+		qb.Limit(filter.Limit).Offset(filter.Offset)
+		qb.OrderBy("id", "asc")
+	} else {
 		if filter.Offset > 0 {
-			qb.Offset(filter.Offset)
+			qb.Limit(1000000).Offset(filter.Offset)
 		}
-	} else if filter.Offset > 0 {
-		// If only offset is specified, use a large limit
-		qb.Limit(1000000).Offset(filter.Offset)
+		qb.OrderBy("id", "asc")
 	}
 
-	// Order by created_at first, then by sequence within the same request
-	qb.OrderBy("created_at", "asc").OrderBy("sequence", "asc")
-
 	rows, err := qb.Get()
 	if err != nil {
 		return nil, err
@@ -173,6 +179,12 @@ func (store *Xun) GetMessages(chatID string, filter types.MessageFilter) ([]*typ
 		messages = append(messages, msg)
 	}
 
+	if needReverse {
+		for i, j := 0, len(messages)-1; i < j; i, j = i+1, j-1 {
+			messages[i], messages[j] = messages[j], messages[i]
+		}
+	}
+
 	return messages, nil
 }
 

go.mod

@@ -9,6 +9,8 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/s3 v1.79.3
 	github.com/blang/semver v3.5.1+incompatible
 	github.com/caarlos0/env/v6 v6.10.1
+	github.com/charmbracelet/bubbletea v1.3.10
+	github.com/charmbracelet/lipgloss v1.1.0
 	github.com/dchest/captcha v1.1.0
 	github.com/docker/docker v28.5.2+incompatible
 	github.com/docker/go-connections v0.5.0
@@ -22,12 +24,14 @@ require (
 	github.com/golang-jwt/jwt/v4 v4.5.2
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
+	github.com/gotd/td v0.140.0
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/joho/godotenv v1.5.1
 	github.com/json-iterator/go v1.1.12
 	github.com/kaptinlin/jsonrepair v0.1.1
 	github.com/kaptinlin/jsonschema v0.6.1
 	github.com/matoous/go-nanoid/v2 v2.1.0
+	github.com/mattn/go-isatty v0.0.20
 	github.com/mozillazg/go-pinyin v0.20.0
 	github.com/pkoukk/tiktoken-go v0.1.7
 	github.com/pquerna/otp v1.5.0
@@ -40,9 +44,9 @@ require (
 	github.com/yaoapp/kun v0.9.0
 	github.com/yaoapp/xun v0.9.0
 	go.mongodb.org/mongo-driver v1.17.3
-	golang.org/x/crypto v0.45.0
-	golang.org/x/net v0.47.0
-	golang.org/x/text v0.31.0
+	golang.org/x/crypto v0.48.0
+	golang.org/x/net v0.50.0
+	golang.org/x/text v0.34.0
 	gopkg.in/natefinch/lumberjack.v2 v2.2.1
 	gopkg.in/yaml.v3 v3.0.1
 	rogchap.com/v8go v0.9.0
@@ -54,6 +58,7 @@ require (
 	github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0 // indirect
 	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/TylerBrock/colorjson v0.0.0-20200706003622-8a50f05110d2 // indirect
+	github.com/aliyun/credentials-go v1.4.6 // indirect
 	github.com/andybalholm/cascadia v1.3.3 // indirect
 	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.6.10 // indirect
 	github.com/aws/aws-sdk-go-v2/internal/configsources v1.3.34 // indirect
@@ -67,16 +72,18 @@ require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/blang/semver/v4 v4.0.0 // indirect
 	github.com/boombuler/barcode v1.0.1-0.20190219062509-6c824513bacc // indirect
+	github.com/bwmarrin/discordgo v0.29.0 // indirect
 	github.com/bytedance/sonic v1.13.2 // indirect
 	github.com/bytedance/sonic/loader v0.2.4 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
-	github.com/charmbracelet/bubbletea v1.3.10 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
-	github.com/charmbracelet/lipgloss v1.1.0 // indirect
 	github.com/charmbracelet/x/ansi v0.10.1 // indirect
 	github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd // indirect
 	github.com/charmbracelet/x/term v0.2.1 // indirect
+	github.com/clbanning/mxj/v2 v2.5.5 // indirect
 	github.com/cloudwego/base64x v0.1.5 // indirect
+	github.com/coder/websocket v1.8.14 // indirect
 	github.com/containerd/errdefs v1.0.0 // indirect
 	github.com/containerd/errdefs/pkg v0.3.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
@@ -88,8 +95,13 @@ require (
 	github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/gabriel-vasile/mimetype v1.4.9 // indirect
+	github.com/ghodss/yaml v1.0.0 // indirect
 	github.com/gin-contrib/sse v1.1.0 // indirect
 	github.com/go-errors/errors v1.5.1 // indirect
+	github.com/go-faster/errors v0.7.1 // indirect
+	github.com/go-faster/jx v1.2.0 // indirect
+	github.com/go-faster/xor v1.0.0 // indirect
+	github.com/go-faster/yaml v0.4.6 // indirect
 	github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
@@ -99,12 +111,16 @@ require (
 	github.com/go-redis/redis/v8 v8.11.5 // indirect
 	github.com/go-sourcemap/sourcemap v2.1.4+incompatible // indirect
 	github.com/go-sql-driver/mysql v1.9.2 // indirect
+	github.com/go-telegram/bot v1.19.0 // indirect
 	github.com/goccy/go-json v0.10.5 // indirect
 	github.com/goccy/go-yaml v1.18.0 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/golang/snappy v1.0.0 // indirect
 	github.com/google/go-github/v30 v30.1.0 // indirect
 	github.com/google/go-querystring v1.1.0 // indirect
+	github.com/gotd/ige v0.2.2 // indirect
+	github.com/gotd/neo v0.1.5 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-hclog v1.6.3 // indirect
 	github.com/hashicorp/go-plugin v1.6.3 // indirect
@@ -119,14 +135,14 @@ require (
 	github.com/kaptinlin/go-i18n v0.2.0 // indirect
 	github.com/kaptinlin/jsonpointer v0.4.6 // indirect
 	github.com/kaptinlin/messageformat-go v0.4.6 // indirect
-	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/klauspost/compress v1.18.4 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.10 // indirect
+	github.com/larksuite/oapi-sdk-go/v3 v3.5.3 // indirect
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/lib/pq v1.10.9 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
 	github.com/mark3labs/mcp-go v0.32.0 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mattn/go-sqlite3 v1.14.28 // indirect
@@ -140,7 +156,9 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/neo4j/neo4j-go-driver/v5 v5.28.1 // indirect
+	github.com/ogen-go/ogen v1.19.0 // indirect
 	github.com/oklog/run v1.1.0 // indirect
+	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.0 // indirect
 	github.com/pdfcpu/pdfcpu v0.11.0 // indirect
@@ -153,7 +171,9 @@ require (
 	github.com/richardlehane/msoleps v1.0.4 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/robfig/cron/v3 v3.0.1 // indirect
+	github.com/segmentio/asm v1.2.1 // indirect
 	github.com/sergi/go-diff v1.4.0 // indirect
+	github.com/shopspring/decimal v1.4.0 // indirect
 	github.com/sirupsen/logrus v1.9.4 // indirect
 	github.com/spf13/pflag v1.0.6 // indirect
 	github.com/tcnksm/go-gitconfig v0.1.2 // indirect
@@ -166,6 +186,7 @@ require (
 	github.com/tidwall/rtred v0.1.2 // indirect
 	github.com/tidwall/tinyqueue v0.1.1 // indirect
 	github.com/tiendc/go-deepcopy v1.6.0 // indirect
+	github.com/tjfoc/gmsm v1.4.1 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	github.com/ulikunitz/xz v0.5.14 // indirect
@@ -183,21 +204,26 @@ require (
 	go.opentelemetry.io/otel v1.40.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.40.0 // indirect
 	go.opentelemetry.io/otel/metric v1.40.0 // indirect
-	go.opentelemetry.io/otel/sdk/metric v1.40.0 // indirect
 	go.opentelemetry.io/otel/trace v1.40.0 // indirect
 	go.opentelemetry.io/proto/otlp v1.9.0 // indirect
+	go.uber.org/atomic v1.11.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	go.uber.org/zap v1.27.1 // indirect
 	golang.org/x/arch v0.17.0 // indirect
+	golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 // indirect
 	golang.org/x/image v0.29.0 // indirect
-	golang.org/x/mod v0.29.0 // indirect
+	golang.org/x/mod v0.33.0 // indirect
 	golang.org/x/oauth2 v0.30.0 // indirect
-	golang.org/x/sync v0.18.0 // indirect
-	golang.org/x/sys v0.40.0 // indirect
-	golang.org/x/tools v0.38.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/tools v0.42.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5 // indirect
 	google.golang.org/grpc v1.75.1 // indirect
 	google.golang.org/protobuf v1.36.11 // indirect
+	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gotest.tools/v3 v3.5.2 // indirect
+	rsc.io/qr v0.2.0 // indirect
 )
 
 // go env -w GOPRIVATE=github.com/yaoapp/*

go.sum

@@ -1,8 +1,10 @@
+cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
 filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw=
 filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
 github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 h1:UQHMgLO+TxOElx5B5HZ4hJQsoJ/PvUvKRhJHDQXO8P8=
 github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
 github.com/JohannesKaufmann/dom v0.2.0 h1:1bragmEb19K8lHAqgFgqCpiPCFEZMTXzOIEjuxkUfLQ=
 github.com/JohannesKaufmann/dom v0.2.0/go.mod h1:57iSUl5RKric4bUkgos4zu6Xt5LMHUnw3TF1l5CbGZo=
 github.com/JohannesKaufmann/html-to-markdown/v2 v2.5.0 h1:mklaPbT4f/EiDr1Q+zPrEt9lgKAkVrIBtWf33d9GpVA=
@@ -13,6 +15,50 @@ github.com/PuerkitoBio/goquery v1.10.3 h1:pFYcNSqHxBD06Fpj/KsbStFRsgRATgnf3LeXiU
 github.com/PuerkitoBio/goquery v1.10.3/go.mod h1:tMUX0zDMHXYlAQk6p35XxQMqMweEKB7iK7iLNd4RH4Y=
 github.com/TylerBrock/colorjson v0.0.0-20200706003622-8a50f05110d2 h1:ZBbLwSJqkHBuFDA6DUhhse0IGJ7T5bemHyNILUjvOq4=
 github.com/TylerBrock/colorjson v0.0.0-20200706003622-8a50f05110d2/go.mod h1:VSw57q4QFiWDbRnjdX8Cb3Ow0SFncRw+bA/ofY6Q83w=
+github.com/alibabacloud-go/alibabacloud-gateway-pop v0.0.6/go.mod h1:4EUIoxs/do24zMOGGqYVWgw0s9NtiylnJglOeEB5UJo=
+github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.4/go.mod h1:sCavSAvdzOjul4cEqeVtvlSaSScfNsTQ+46HwlTL1hc=
+github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.5 h1:zE8vH9C7JiZLNJJQ5OwjU9mSi4T9ef9u3BURT6LCLC8=
+github.com/alibabacloud-go/alibabacloud-gateway-spi v0.0.5/go.mod h1:tWnyE9AjF8J8qqLk645oUmVUnFybApTQWklQmi5tY6g=
+github.com/alibabacloud-go/darabonba-array v0.1.0/go.mod h1:BLKxr0brnggqOJPqT09DFJ8g3fsDshapUD3C3aOEFaI=
+github.com/alibabacloud-go/darabonba-encode-util v0.0.2/go.mod h1:JiW9higWHYXm7F4PKuMgEUETNZasrDM6vqVr/Can7H8=
+github.com/alibabacloud-go/darabonba-map v0.0.2/go.mod h1:28AJaX8FOE/ym8OUFWga+MtEzBunJwQGceGQlvaPGPc=
+github.com/alibabacloud-go/darabonba-openapi/v2 v2.0.12 h1:Dqhik/9iK3/ltjMuVy2kkuuWK3KPRes2vSzxnrehT74=
+github.com/alibabacloud-go/darabonba-openapi/v2 v2.0.12/go.mod h1:cgtLEj8i4ddXMcQgq4PnpVQvlzS+y5B+QtdSfmcLM3A=
+github.com/alibabacloud-go/darabonba-signature-util v0.0.7/go.mod h1:oUzCYV2fcCH797xKdL6BDH8ADIHlzrtKVjeRtunBNTQ=
+github.com/alibabacloud-go/darabonba-string v1.0.2/go.mod h1:93cTfV3vuPhhEwGGpKKqhVW4jLe7tDpo3LUM0i0g6mA=
+github.com/alibabacloud-go/debug v0.0.0-20190504072949-9472017b5c68/go.mod h1:6pb/Qy8c+lqua8cFpEy7g39NRRqOWc3rOwAy8m5Y2BY=
+github.com/alibabacloud-go/debug v1.0.0/go.mod h1:8gfgZCCAC3+SCzjWtY053FrOcd4/qlH6IHTI4QyICOc=
+github.com/alibabacloud-go/debug v1.0.1 h1:MsW9SmUtbb1Fnt3ieC6NNZi6aEwrXfDksD4QA6GSbPg=
+github.com/alibabacloud-go/debug v1.0.1/go.mod h1:8gfgZCCAC3+SCzjWtY053FrOcd4/qlH6IHTI4QyICOc=
+github.com/alibabacloud-go/dingtalk v1.6.98 h1:7EBiJvGgzm2uT44B5VDMBGC5zdx8co7CNuLr0fafCP8=
+github.com/alibabacloud-go/dingtalk v1.6.98/go.mod h1:mUcgNRgMGQzABtiZtTK8a3b6LwQBQ8t9WsDKzklqVpg=
+github.com/alibabacloud-go/endpoint-util v1.1.0/go.mod h1:O5FuCALmCKs2Ff7JFJMudHs0I5EBgecXXxZRyswlEjE=
+github.com/alibabacloud-go/gateway-dingtalk v1.0.2 h1:+etjmc64QTmYvHlc6eFkH9y2DOc3UPcyD2nF3IXsVqw=
+github.com/alibabacloud-go/gateway-dingtalk v1.0.2/go.mod h1:JUvHpkJtlPFpgJcfXqc9Y4mk2JnoRn5XpKbRz38jJho=
+github.com/alibabacloud-go/openapi-util v0.1.0/go.mod h1:sQuElr4ywwFRlCCberQwKRFhRzIyG4QTP/P4y1CJ6Ws=
+github.com/alibabacloud-go/openapi-util v0.1.1 h1:ujGErJjG8ncRW6XtBBMphzHTvCxn4DjrVw4m04HsS28=
+github.com/alibabacloud-go/openapi-util v0.1.1/go.mod h1:/UehBSE2cf1gYT43GV4E+RxTdLRzURImCYY0aRmlXpw=
+github.com/alibabacloud-go/tea v1.1.0/go.mod h1:IkGyUSX4Ba1V+k4pCtJUc6jDpZLFph9QMy2VUPTwukg=
+github.com/alibabacloud-go/tea v1.1.7/go.mod h1:/tmnEaQMyb4Ky1/5D+SE1BAsa5zj/KeGOFfwYm3N/p4=
+github.com/alibabacloud-go/tea v1.1.8/go.mod h1:/tmnEaQMyb4Ky1/5D+SE1BAsa5zj/KeGOFfwYm3N/p4=
+github.com/alibabacloud-go/tea v1.1.11/go.mod h1:/tmnEaQMyb4Ky1/5D+SE1BAsa5zj/KeGOFfwYm3N/p4=
+github.com/alibabacloud-go/tea v1.1.17/go.mod h1:nXxjm6CIFkBhwW4FQkNrolwbfon8Svy6cujmKFUq98A=
+github.com/alibabacloud-go/tea v1.1.20/go.mod h1:nXxjm6CIFkBhwW4FQkNrolwbfon8Svy6cujmKFUq98A=
+github.com/alibabacloud-go/tea v1.2.2 h1:aTsR6Rl3ANWPfqeQugPglfurloyBJY85eFy7Gc1+8oU=
+github.com/alibabacloud-go/tea v1.2.2/go.mod h1:CF3vOzEMAG+bR4WOql8gc2G9H3EkH3ZLAQdpmpXMgwk=
+github.com/alibabacloud-go/tea-utils v1.3.1 h1:iWQeRzRheqCMuiF3+XkfybB3kTgUXkXX+JMrqfLeB2I=
+github.com/alibabacloud-go/tea-utils v1.3.1/go.mod h1:EI/o33aBfj3hETm4RLiAxF/ThQdSngxrpF8rKUDJjPE=
+github.com/alibabacloud-go/tea-utils/v2 v2.0.1/go.mod h1:U5MTY10WwlquGPS34DOeomUGBB0gXbLueiq5Trwu0C4=
+github.com/alibabacloud-go/tea-utils/v2 v2.0.5/go.mod h1:dL6vbUT35E4F4bFTHL845eUloqaerYBYPsdWR2/jhe4=
+github.com/alibabacloud-go/tea-utils/v2 v2.0.6 h1:ZkmUlhlQbaDC+Eba/GARMPy6hKdCLiSke5RsN5LcyQ0=
+github.com/alibabacloud-go/tea-utils/v2 v2.0.6/go.mod h1:qxn986l+q33J5VkialKMqT/TTs3E+U9MJpd001iWQ9I=
+github.com/alibabacloud-go/tea-xml v1.1.3 h1:7LYnm+JbOq2B+T/B0fHC4Ies4/FofC4zHzYtqw7dgt0=
+github.com/alibabacloud-go/tea-xml v1.1.3/go.mod h1:Rq08vgCcCAjHyRi/M7xlHKUykZCEtyBy9+DPF6GgEu8=
+github.com/aliyun/credentials-go v1.1.2/go.mod h1:ozcZaMR5kLM7pwtCMEpVmQ242suV6qTJya2bDq4X1Tw=
+github.com/aliyun/credentials-go v1.3.1/go.mod h1:8jKYhQuDawt8x2+fusqa1Y6mPxemTsBEN04dgcAcYz0=
+github.com/aliyun/credentials-go v1.3.6/go.mod h1:1LxUuX7L5YrZUWzBrRyk0SwSdH4OmPrib8NVePL3fxM=
+github.com/aliyun/credentials-go v1.4.6 h1:CG8rc/nxCNKfXbZWpWDzI9GjF4Tuu3Es14qT8Y0ClOk=
+github.com/aliyun/credentials-go v1.4.6/go.mod h1:Jm6d+xIgwJVLVWT561vy67ZRP4lPTQxMbEYRuT2Ti1U=
 github.com/andybalholm/cascadia v1.3.3 h1:AG2YHrzJIm4BZ19iwJ/DAua6Btl3IwJX+VI4kktS1LM=
 github.com/andybalholm/cascadia v1.3.3/go.mod h1:xNd9bqTn98Ln4DwST8/nG+H0yuB8Hmgu1YHNnWw0GeA=
 github.com/aws/aws-sdk-go-v2 v1.36.3 h1:mJoei2CxPutQVxaATCzDUjcZEjVRdpsiiXi2o38yqWM=
@@ -53,6 +99,8 @@ github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
 github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
 github.com/bufbuild/protocompile v0.4.0 h1:LbFKd2XowZvQ/kajzguUp2DC9UEIQhIq77fZZlaQsNA=
 github.com/bufbuild/protocompile v0.4.0/go.mod h1:3v93+mbWn/v3xzN+31nwkJfrEpAUwp+BagBSZWx+TP8=
+github.com/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+EgjDno=
+github.com/bwmarrin/discordgo v0.29.0/go.mod h1:NJZpH+1AfhIcyQsPeuBKsUtYrRnjkyu0kIVMCHkZtRY=
 github.com/bytedance/sonic v1.13.2 h1:8/H1FempDZqC4VqjptGo14QQlJx8VdZJegxs6wwfqpQ=
 github.com/bytedance/sonic v1.13.2/go.mod h1:o68xyaF9u2gvVBuGHPlUVCy+ZfmNNO5ETf1+KgkJhz4=
 github.com/bytedance/sonic/loader v0.1.1/go.mod h1:ncP89zfokxS5LZrJxl5z0UJcsk4M4yY2JpfqGeCtNLU=
@@ -60,8 +108,9 @@ github.com/bytedance/sonic/loader v0.2.4 h1:ZWCw4stuXUsn1/+zQDqeE7JKP+QO47tz7QCN
 github.com/bytedance/sonic/loader v0.2.4/go.mod h1:N8A3vUdtUebEY2/VQC0MyhYeKUFosQU6FxH2JmUe6VI=
 github.com/caarlos0/env/v6 v6.10.1 h1:t1mPSxNpei6M5yAeu1qtRdPAK29Nbcf/n3G7x+b3/II=
 github.com/caarlos0/env/v6 v6.10.1/go.mod h1:hvp/ryKXKipEkcuYjs9mI4bBCg+UI0Yhgm5Zu0ddvwc=
-github.com/cenkalti/backoff/v4 v4.2.1 h1:y4OZtCnogmCPw98Zjyt5a6+QwPLGkiQsYW5oUqylYbM=
-github.com/cenkalti/backoff/v4 v4.2.1/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/charmbracelet/bubbletea v1.3.10 h1:otUDHWMMzQSB0Pkc87rm691KZ3SWa4KUlvF9nRvCICw=
@@ -76,9 +125,15 @@ github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd h1:vy0G
 github.com/charmbracelet/x/cellbuf v0.0.13-0.20250311204145-2c3ea96c31dd/go.mod h1:xe0nKWGd3eJgtqZRaN9RjMtK7xUYchjzPr7q6kcvCCs=
 github.com/charmbracelet/x/term v0.2.1 h1:AQeHeLZ1OqSXhrAWpYUtZyX1T3zVxfpZuEQMIQaGIAQ=
 github.com/charmbracelet/x/term v0.2.1/go.mod h1:oQ4enTYFV7QN4m0i9mzHrViD7TQKvNEEkHUMCmsxdUg=
+github.com/clbanning/mxj/v2 v2.5.5 h1:oT81vUeEiQQ/DcHbzSytRngP6Ky9O+L+0Bw0zSJag9E=
+github.com/clbanning/mxj/v2 v2.5.5/go.mod h1:hNiWqW14h+kc+MdF9C6/YoRfjEJoR3ou6tn/Qo+ve2s=
+github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cloudwego/base64x v0.1.5 h1:XPciSp1xaq2VCSt6lF0phncD4koWyULpl5bUxbfCyP4=
 github.com/cloudwego/base64x v0.1.5/go.mod h1:0zlkT4Wn5C6NdauXdJRhSKRlJvmclQ1hhJgA0rcu/8w=
 github.com/cloudwego/iasm v0.2.0/go.mod h1:8rXZaNYT2n95jn+zTI1sDr+IgcD2GVs0nlbbQPiEFhY=
+github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
 github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
 github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
@@ -112,6 +167,9 @@ github.com/emersion/go-sasl v0.0.0-20200509203442-7bfe0ed36a21/go.mod h1:iL2twTe
 github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 h1:oP4q0fw+fOSWn3DfFi4EXdT+B+gTtzx8GC9xsc26Znk=
 github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6/go.mod h1:iL2twTeMvZnrg54ZoPDNfJaJaqy0xIQFuBdrLsmspwQ=
 github.com/emersion/go-textwrapper v0.0.0-20200911093747-65d896831594/go.mod h1:aqO8z8wPrjkscevZJFVE1wXJrLpC5LtJG7fqLOsPb2U=
+github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
+github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
+github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
 github.com/evanw/esbuild v0.25.4 h1:k1bTSim+usBG27w7BfOCorhgx3tO+6bAfMj5pR+6SKg=
@@ -130,12 +188,23 @@ github.com/fsnotify/fsnotify v1.9.0 h1:2Ml+OJNzbYCTzsxtv8vKSFD9PbJjmhYF14k/jKC7S
 github.com/fsnotify/fsnotify v1.9.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/gabriel-vasile/mimetype v1.4.9 h1:5k+WDwEsD9eTLL8Tz3L0VnmVh9QxGjRmjBvAG7U/oYY=
 github.com/gabriel-vasile/mimetype v1.4.9/go.mod h1:WnSQhFKJuBlRyLiKohA/2DtIlPFAbguNaG7QCHcyGok=
+github.com/ghodss/yaml v1.0.0 h1:wQHKEahhL6wmXdzwWG11gIVCkOv05bNOh+Rxn0yngAk=
+github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
 github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
 github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
 github.com/gin-gonic/gin v1.10.1 h1:T0ujvqyCSqRopADpgPgiTT63DUQVSfojyME59Ei63pQ=
 github.com/gin-gonic/gin v1.10.1/go.mod h1:4PMNQiOhvDRa013RKVbsiNwoyezlm2rm0uX/T7kzp5Y=
 github.com/go-errors/errors v1.5.1 h1:ZwEMSLRCapFLflTpT7NKaAc7ukJ8ZPEjzlxt8rPN8bk=
 github.com/go-errors/errors v1.5.1/go.mod h1:sIVyrIiJhuEF+Pj9Ebtd6P/rEYROXFi3BopGUQ5a5Og=
+github.com/go-faster/errors v0.7.1 h1:MkJTnDoEdi9pDabt1dpWf7AA8/BaSYZqibYyhZ20AYg=
+github.com/go-faster/errors v0.7.1/go.mod h1:5ySTjWFiphBs07IKuiL69nxdfd5+fzh1u7FPGZP2quo=
+github.com/go-faster/jx v1.2.0 h1:T2YHJPrFaYu21fJtUxC9GzmluKu8rVIFDwwGBKTDseI=
+github.com/go-faster/jx v1.2.0/go.mod h1:UWLOVDmMG597a5tBFPLIWJdUxz5/2emOpfsj9Neg0PE=
+github.com/go-faster/xor v0.3.0/go.mod h1:x5CaDY9UKErKzqfRfFZdfu+OSTfoZny3w5Ak7UxcipQ=
+github.com/go-faster/xor v1.0.0 h1:2o8vTOgErSGHP3/7XwA5ib1FTtUsNtwCoLLBjl31X38=
+github.com/go-faster/xor v1.0.0/go.mod h1:x5CaDY9UKErKzqfRfFZdfu+OSTfoZny3w5Ak7UxcipQ=
+github.com/go-faster/yaml v0.4.6 h1:lOK/EhI04gCpPgPhgt0bChS6bvw7G3WwI8xxVe0sw9I=
+github.com/go-faster/yaml v0.4.6/go.mod h1:390dRIvV4zbnO7qC9FGo6YYutc+wyyUSHBgbXL52eXk=
 github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
 github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
@@ -158,18 +227,35 @@ github.com/go-sourcemap/sourcemap v2.1.4+incompatible/go.mod h1:F8jJfvm2KbVjc5Nq
 github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg=
 github.com/go-sql-driver/mysql v1.9.2 h1:4cNKDYQ1I84SXslGddlsrMhc8k4LeDVj6Ad6WRjiHuU=
 github.com/go-sql-driver/mysql v1.9.2/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU=
+github.com/go-telegram/bot v1.19.0 h1:tuvTQhgNietHFRN0HUDhuXsgfgkGSaO8WWwZQW3DMQg=
+github.com/go-telegram/bot v1.19.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM=
 github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
 github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
 github.com/goccy/go-yaml v1.18.0 h1:8W7wMFS12Pcas7KU+VVkaiCng+kG8QiFeFwzFb+rwuw=
 github.com/goccy/go-yaml v1.18.0/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/golang-jwt/jwt/v4 v4.5.2 h1:YtQM7lnr8iZ+j5q71MGKkNw9Mn7AjHM68uc9g5fXeUI=
 github.com/golang-jwt/jwt/v4 v4.5.2/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
+github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
+github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.3/go.mod h1:vzj43D7+SQXF/4pzW/hwtAqwc6iTitCiVSaWz5lYuqw=
+github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
+github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
+github.com/golang/protobuf v1.4.0-rc.2/go.mod h1:LlEzMj4AhA7rCAGe4KMBDvJI+AwstrUpVNzEA03Pprs=
+github.com/golang/protobuf v1.4.0-rc.4.0.20200313231945-b860323f09d0/go.mod h1:WU3c8KckQ9AFe+yFwt9sWVRKCVIyN9cPHBJSNnbL67w=
+github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvqG2KuDX0=
+github.com/golang/protobuf v1.4.2/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI=
 github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/golang/snappy v1.0.0 h1:Oy607GVXHs7RtbggtPBnr2RmDArIsAefDwvrdWvRhGs=
 github.com/golang/snappy v1.0.0/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q=
+github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
+github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
+github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
@@ -182,8 +268,18 @@ github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
+github.com/gopherjs/gopherjs v0.0.0-20200217142428-fce0ec30dd00/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
+github.com/gorilla/websocket v1.4.2/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/gorilla/websocket v1.5.0/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/gotd/ige v0.2.2 h1:XQ9dJZwBfDnOGSTxKXBGP4gMud3Qku2ekScRjDWWfEk=
+github.com/gotd/ige v0.2.2/go.mod h1:tuCRb+Y5Y3eNTo3ypIfNpQ4MFjrnONiL2jN2AKZXmb0=
+github.com/gotd/neo v0.1.5 h1:oj0iQfMbGClP8xI59x7fE/uHoTJD7NZH9oV1WNuPukQ=
+github.com/gotd/neo v0.1.5/go.mod h1:9A2a4bn9zL6FADufBdt7tZt+WMhvZoc5gWXihOPoiBQ=
+github.com/gotd/td v0.140.0 h1:trNBzTnhNtNwHsFp5qwKnNxQRAZJ6/BRE+uH3Lojauk=
+github.com/gotd/td v0.140.0/go.mod h1:0ZkRxG7N+5ooG7/zdRXcnGautGPM6IKmyPQvdsAeF20=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 h1:8Tjv8EJ+pM1xP8mK6egEbD1OgnVTyacbefKhmbLhIhU=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2/go.mod h1:pkJQ2tZHJ0aFOVEEot6oZmaVEZcRme73eIFmhiVuRWs=
 github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
@@ -218,8 +314,10 @@ github.com/jmoiron/sqlx v1.4.0 h1:1PLqN7S1UYp5t4SrVVnt4nUVNemrDAtxlulVe+Qgm3o=
 github.com/jmoiron/sqlx v1.4.0/go.mod h1:ZrZ7UsYB/weZdl2Bxg6jCRO9c3YHl8r3ahlKmRT4JLY=
 github.com/joho/godotenv v1.5.1 h1:7eLL/+HRGLY0ldzfGMeQkb7vMd0as4CfYvUVzLqw0N0=
 github.com/joho/godotenv v1.5.1/go.mod h1:f4LDr5Voq0i2e/R5DDNOoa2zzDfwtkZa6DnEwAbqwq4=
+github.com/json-iterator/go v1.1.10/go.mod h1:KdQUCv79m/52Kvf8AW2vK1V8akMuk1QjK/uOdHXbAo4=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/jtolds/gls v4.20.0+incompatible/go.mod h1:QJZ7F/aHp+rZTRtaJ1ow/lLfFfVYBRgL+9YlvaHOwJU=
 github.com/kaptinlin/go-i18n v0.2.0 h1:8iwjAERQbCVF78c3HxC4MxUDxDRFvQVQlMDvlsO43hU=
 github.com/kaptinlin/go-i18n v0.2.0/go.mod h1:gRHEMrTHtQLsAFwulPbJG71TwHjXxkagn88O8FI8FuA=
 github.com/kaptinlin/jsonpointer v0.4.6 h1:hAett1YROLwxAOKZS08hsJueXr1w0fTMSvWq2x1IoUA=
@@ -230,8 +328,10 @@ github.com/kaptinlin/jsonschema v0.6.1 h1:RNUQ11ZCHTtM80YcVwRm033H5OJS+MpO06d9x7
 github.com/kaptinlin/jsonschema v0.6.1/go.mod h1:T8SNWNTRLDS1w+ogMZpGYqIfUXn/8DK9r06mf8XbNLE=
 github.com/kaptinlin/messageformat-go v0.4.6 h1:57DUC9en40mGZR7MvqOS+5EYogAl465fjo+loAA1KPg=
 github.com/kaptinlin/messageformat-go v0.4.6/go.mod h1:r0PH7FsxJX8jS/n6LAYZon5w3X+yfCLUrquqYd2H7ks=
-github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
-github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
+github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
 github.com/klauspost/cpuid/v2 v2.0.9/go.mod h1:FInQzS24/EEf25PyTYn52gqo7WaD8xa0213Md/qVLRg=
 github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
 github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
@@ -243,6 +343,8 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
 github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.3 h1:xvf8Dv29kBXC5/DNDCLhHkAFW8l/0LlQJimO5Zn+JUk=
+github.com/larksuite/oapi-sdk-go/v3 v3.5.3/go.mod h1:ZEplY+kwuIrj/nqw5uSCINNATcH3KdxSN7y+UxYY5fI=
 github.com/leodido/go-urn v1.4.0 h1:WT9HwE9SGECu3lg4d/dIA+jxlljEa1/ffXKmRjqdmIQ=
 github.com/leodido/go-urn v1.4.0/go.mod h1:bvxc+MVxLKB4z00jd1z+Dvzr47oO32F/QSNjSBOlFxI=
 github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
@@ -281,6 +383,8 @@ github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
 github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v0.0.0-20180701023420-4b7aa43c6742/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
+github.com/modern-go/reflect2 v1.0.1/go.mod h1:bx2lNnkwVCuqBIxFjflWJWanXIb3RllmbCylyMrvgv0=
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/montanaflynn/stats v0.7.1 h1:etflOAAHORrCC44V+aR6Ftzort912ZU+YLiSTuV8eaE=
@@ -297,8 +401,11 @@ github.com/muesli/termenv v0.16.0 h1:S5AlUN9dENB57rsbnkPyfdGuWIlkmzJjbFf0Tf5FWUc
 github.com/muesli/termenv v0.16.0/go.mod h1:ZRfOIKPFDYQoDFF4Olj7/QJbW60Ol/kL1pU3VfY/Cnk=
 github.com/neo4j/neo4j-go-driver/v5 v5.28.1 h1:RKWQW7wTgYAY2fU9S+9LaJ9OwRPbRc0I17tlT7nDmAY=
 github.com/neo4j/neo4j-go-driver/v5 v5.28.1/go.mod h1:Vff8OwT7QpLm7L2yYr85XNWe9Rbqlbeb9asNXJTHO4k=
+github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
 github.com/nxadm/tail v1.4.8 h1:nPr65rt6Y5JFSKQO7qToXr7pePgD6Gwiw05lkbyAQTE=
 github.com/nxadm/tail v1.4.8/go.mod h1:+ncqLTQzXmGhMZNUePPaPqPvBxHAIsmXswZKocGu+AU=
+github.com/ogen-go/ogen v1.19.0 h1:YvdNpeQJ8A8dLLpS6Vs4WxXL53BT6tBPxH0VSjfALhA=
+github.com/ogen-go/ogen v1.19.0/go.mod h1:DeShwO+TEpLYXNCuZliSAedphphXsJaTGGbmSomWUjE=
 github.com/oklog/run v1.1.0 h1:GEenZ1cK0+q0+wsJew9qUg/DyD8k3JzYsZAi5gYi2mA=
 github.com/oklog/run v1.1.0/go.mod h1:sVPdnTZT1zYwAJeCMu2Th4T21pA3FPOQRfWjQlk7DVU=
 github.com/onsi/ginkgo v1.6.0/go.mod h1:lLunBs/Ym6LB5Z9jYTR76FiuTmxDTDusOGeTQH+WWjE=
@@ -307,6 +414,8 @@ github.com/onsi/ginkgo v1.16.5/go.mod h1:+E8gABHa3K6zRBolWtd+ROzc/U5bkGt0FwiG042
 github.com/onsi/gomega v1.4.2/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY=
 github.com/onsi/gomega v1.18.1 h1:M1GfJqGRrBrrGGsbxzV5dqM2U2ApXefZCQpkukxYRLE=
 github.com/onsi/gomega v1.18.1/go.mod h1:0q+aL8jAiMXy9hbwj2mr5GziHiwhAIQpFmmtT5hitRs=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 h1:Lb/Uzkiw2Ugt2Xf03J5wmv81PdkYOiWbI8CNBi1boC8=
+github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
 github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/opencontainers/image-spec v1.1.0 h1:8SG7/vwALn54lVB/0yZ/MMwhFrPYtpEHQb2IpWsCzug=
@@ -323,6 +432,7 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pquerna/otp v1.5.0 h1:NMMR+WrmaqXU4EzdGJEE1aUUI0AMRzsp96fFFWNPwxs=
 github.com/pquerna/otp v1.5.0/go.mod h1:dkJfzwRKNiegxyNb54X/3fLwhCynbMspSyWKnvi1AEg=
+github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
 github.com/qdrant/go-client v1.14.0 h1:cyz9OOooAexudw5w69LRe9vKCQFYJvaFvt9icOciI1U=
 github.com/qdrant/go-client v1.14.0/go.mod h1:iO8ts78jL4x6LDHFOViyYWELVtIBDTjOykBmiOTHLnQ=
 github.com/redis/go-redis/v9 v9.17.2 h1:P2EGsA4qVIM3Pp+aPocCJ7DguDHhqrXNhVcEp4ViluI=
@@ -344,10 +454,17 @@ github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sebdah/goldie/v2 v2.8.0 h1:dZb9wR8q5++oplmEiJT+U/5KyotVD+HNGCAc5gNr8rc=
 github.com/sebdah/goldie/v2 v2.8.0/go.mod h1:oZ9fp0+se1eapSRjfYbsV/0Hqhbuu3bJVvKI/NNtssI=
+github.com/segmentio/asm v1.2.1 h1:DTNbBqs57ioxAD4PrArqftgypG4/qNpXoJx8TVXxPR0=
+github.com/segmentio/asm v1.2.1/go.mod h1:BqMnlJP91P8d+4ibuonYZw9mfnzI9HfxselHZr5aAcs=
 github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw=
 github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4=
+github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
+github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
 github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w=
 github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g=
+github.com/smartystreets/assertions v0.0.0-20180927180507-b2de0cb4f26d/go.mod h1:OnSkiWE9lh6wB0YB77sQom3nweQdgAjqCqsofrRNTgc=
+github.com/smartystreets/assertions v1.1.0/go.mod h1:tcbTF8ujkAEcZ8TElKY+i30BzYlVhC/LOxJk7iOWnoo=
+github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9QV7WQ/tjFTllLA=
 github.com/spf13/cast v1.9.2 h1:SsGfm7M8QOFtEzumm7UZrZdLLquNdzFYfIbEXntcFbE=
 github.com/spf13/cast v1.9.2/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo=
 github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
@@ -355,10 +472,12 @@ github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wx
 github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
 github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.2.0/go.mod h1:qt09Ya8vawLte6SNmTgCsAVtYtaKzEcn8ATUoHMkEqE=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4=
+github.com/stretchr/testify v1.5.1/go.mod h1:5W2xD1RspED5o8YsWQXVCued0rvSQ+mT+I5cxcmMvtA=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.2/go.mod h1:R6va5+xMeoiuVRoj+gSkQ7d3FALtqAAGI1FQKckRals=
@@ -392,6 +511,9 @@ github.com/tidwall/tinyqueue v0.1.1 h1:SpNEvEggbpyN5DIReaJ2/1ndroY8iyEGxPYxoSaym
 github.com/tidwall/tinyqueue v0.1.1/go.mod h1:O/QNHwrnjqr6IHItYrzoHAKYhBkLI67Q096fQP5zMYw=
 github.com/tiendc/go-deepcopy v1.6.0 h1:0UtfV/imoCwlLxVsyfUd4hNHnB3drXsfle+wzSCA5Wo=
 github.com/tiendc/go-deepcopy v1.6.0/go.mod h1:toXoeQoUqXOOS/X4sKuiAoSk6elIdqc0pN7MTgOOo2I=
+github.com/tjfoc/gmsm v1.3.2/go.mod h1:HaUcFuY0auTiaHB9MHFGCPx5IaLhTUd2atbCFBQXn9w=
+github.com/tjfoc/gmsm v1.4.1 h1:aMe1GlZb+0bLjn+cKTPEvvn9oUEBlJitaZiiBwsbgho=
+github.com/tjfoc/gmsm v1.4.1/go.mod h1:j4INPkHWMrhJb38G+J6W4Tw0AbuN8Thu3PbdVYhVcTE=
 github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
@@ -417,6 +539,9 @@ github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zI
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
+github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.1.30/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 github.com/yuin/goldmark v1.7.16 h1:n+CJdUxaFMiDUNnWC3dMWCIQJSkxH4uz3ZwQBkAlVNE=
 github.com/yuin/goldmark v1.7.16/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
@@ -442,60 +567,105 @@ go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZY
 go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
 go.opentelemetry.io/proto/otlp v1.9.0 h1:l706jCMITVouPOqEnii2fIAuO3IVGBRPV5ICjceRb/A=
 go.opentelemetry.io/proto/otlp v1.9.0/go.mod h1:xE+Cx5E/eEHw+ISFkwPLwCZefwVjY+pqKg1qcK03+/4=
+go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE=
+go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
+go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
 golang.org/x/arch v0.17.0 h1:4O3dfLzd+lQewptAHqjewQZQDyEdejz3VwgeYwkZneU=
 golang.org/x/arch v0.17.0/go.mod h1:bdwinDaKcfZUGpH09BB7ZmOfhalA8lQdzl62l8gGWsk=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20191219195013-becbf705a915/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20200510223506-06a226fb4e37/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/crypto v0.0.0-20201012173705-84dcc777aaee/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
 golang.org/x/crypto v0.0.0-20201221181555-eec23a3978ad/go.mod h1:jdWPYTVW3xRLrWPugEBEK3UY2ZEsg3UU495nc5E+M+I=
+golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
+golang.org/x/crypto v0.14.0/go.mod h1:MVFd36DqK4CsrnJYDkBA3VC4m2GkXAM0PvzMCn4JQf4=
+golang.org/x/crypto v0.18.0/go.mod h1:R0j02AL6hcrfOiy9T4ZYp/rcWeMxM3L6QYxlOuEG1mg=
 golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
+golang.org/x/crypto v0.21.0/go.mod h1:0BP7YvVV9gBbVKyeTG0Gyn+gZm94bibOW5BjDEYAOMs=
 golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
 golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
-golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
-golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
+golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 h1:Di6/M8l0O2lCLc6VVRWhgCiApHV8MnQurBnFSHsQtNY=
+golang.org/x/exp v0.0.0-20230725093048-515e97ebf090/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc=
 golang.org/x/image v0.29.0 h1:HcdsyR4Gsuys/Axh0rDEmlBmB68rW1U9BUdB3UVHsas=
 golang.org/x/image v0.29.0/go.mod h1:RVJROnf3SLK8d26OW91j4FrIHGbsJ8QnbEocVTOWQDA=
+golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
+golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
+golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
+golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
-golang.org/x/mod v0.29.0 h1:HV8lRxZC4l2cr3Zq1LvtOsi/ThTgWnUk/y64QSs8GwA=
-golang.org/x/mod v0.29.0/go.mod h1:NyhrlYXJ2H4eJiRy/WDBO6HMqZQ6q9nk4JzS3NuCK+w=
+golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
+golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
 golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200226121028-0de0cce0169b/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20200506145744-7e3656a0809f/go.mod h1:qpuaurCH72eLCgpAm/N6yyVIVM9cpaDIP3A8BGJEC5A=
+golang.org/x/net v0.0.0-20201010224723-4f7140c49acb/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
+golang.org/x/net v0.7.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
+golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
+golang.org/x/net v0.20.0/go.mod h1:z8BVo6PvndSri0LbOE3hAn0apkU+1YvI6E70E9jsnvY=
 golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
+golang.org/x/net v0.23.0/go.mod h1:JKghWKKOSdJwpW2GEx0Ja7fmaKnMsbu+MWVZTokSYmg=
 golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
 golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
-golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
-golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
 golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.0.0-20181106182150-f42d05182288/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
 golang.org/x/oauth2 v0.30.0 h1:dnDm7JmhM45NNpd8FDDeLhK6FwqbOf4MLCM9zb1BOHI=
 golang.org/x/oauth2 v0.30.0/go.mod h1:B++QgG3ZKulg6sRPGD/mqlHQs5rB3Ml9erfeDY7xKlU=
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20200317015054-43a5402ce75a/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201207232520-09787c993a3a/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
 golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
-golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
-golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200116001909-b77594299b42/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20200223170610-d5e6a3e2c0ae/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200509044756-6aff5f38e54f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
@@ -509,11 +679,14 @@ golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.16.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.18.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
-golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
 golang.org/x/term v0.0.0-20201117132131-f5c789dd3221/go.mod h1:Nr5EML6q2oocZ2LXRh80K7BxOlk5/8JxuGnuhpl+muw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
@@ -521,10 +694,14 @@ golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuX
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
 golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
+golang.org/x/term v0.13.0/go.mod h1:LTmsnFJwVN6bCy1rVCoS+qHT1HhALEFxKncY3WNNh4U=
+golang.org/x/term v0.16.0/go.mod h1:yn7UURbUtPyrVJPGPq404EukNFxcm/foM+bV/bfcDsY=
 golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
+golang.org/x/term v0.18.0/go.mod h1:ILwASektA3OnRv7amZ1xhE/KTR+u50pbXfZ03+6Nx58=
 golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
 golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.5/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
@@ -536,44 +713,72 @@ golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
-golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
-golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
 golang.org/x/time v0.3.0 h1:rg5rLMjNzMS1RkNLzCG38eapWhnYLFYXDXj2gOlr8j4=
 golang.org/x/time v0.3.0/go.mod h1:tRJNPiyCQ0inRvYxbN9jk5I+vvW/OXSQhTDSoE431IQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
+golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20200509030707-2212a7e161a5/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20200619180055-7c47624df98f/go.mod h1:EkVYQZoAsY45+roYkvgYkIh4xh/qjgUK9TdY2XT94GE=
+golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
 golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
-golang.org/x/tools v0.38.0 h1:Hx2Xv8hISq8Lm16jvBZ2VQf+RLmbd7wVUsALibYI/IQ=
-golang.org/x/tools v0.38.0/go.mod h1:yEsQ/d/YK8cjh0L6rZlY8tgtlKiBNTL14pGDJPJpYQs=
+golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
+golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
 gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
 google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
 google.golang.org/appengine v1.3.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
+google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
+google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
+google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
 google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5 h1:BIRfGDEjiHRrk0QKZe3Xv2ieMhtgRGeLcZQ0mIVn4EY=
 google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5/go.mod h1:j3QtIyytwqGr1JUDtYXwtMXWPKsEa5LtzIFN1Wn5WvE=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5 h1:eaY8u2EuxbRv7c3NiGK0/NedzVsCcV6hDuU5qPX5EGE=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5/go.mod h1:M4/wBTSeyLxupu3W3tJtOgB14jILAS/XWPSSa3TAlJc=
+google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
+google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
+google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY=
+google.golang.org/grpc v1.31.0/go.mod h1:N36X2cJ7JwdamYAgDz+s+rVMFjt3numwzf/HckM8pak=
 google.golang.org/grpc v1.75.1 h1:/ODCNEuf9VghjgO3rqLcfg8fiOP0nSluljWFlDxELLI=
 google.golang.org/grpc v1.75.1/go.mod h1:JtPAzKiq4v1xcAB2hydNlWI2RnF85XXcV0mhKXr2ecQ=
+google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8=
+google.golang.org/protobuf v0.0.0-20200221191635-4d8936d0db64/go.mod h1:kwYJMbMJ01Woi6D6+Kah6886xMZcty6N08ah7+eCXa0=
+google.golang.org/protobuf v0.0.0-20200228230310-ab0ca4ff8a60/go.mod h1:cfTl7dwQJ+fmap5saPgwCLgHXTUD7jkjRqWcaiX5VyM=
+google.golang.org/protobuf v1.20.1-0.20200309200217-e05f789c0967/go.mod h1:A+miEFZTKqfCUM6K7xSMQL9OKL/b6hQv+e19PK+JZNE=
+google.golang.org/protobuf v1.21.0/go.mod h1:47Nbq4nVaFHyn7ilMalzfO3qCViNmqZ2kzikPIcrTAo=
+google.golang.org/protobuf v1.23.0/go.mod h1:EGpADcykh3NcUnDUJcl1+ZksZNG86OlYog2l/sGQquU=
 google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
 google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/fsnotify.v1 v1.4.7/go.mod h1:Tz8NjZHkW78fSQdbUxIjBTcgA1z1m8ZHf0WmKUhAMys=
+gopkg.in/ini.v1 v1.56.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
+gopkg.in/ini.v1 v1.67.0 h1:Dgnx+6+nfE+IfzjUEISNeydPJh9AXNNsWbGP9KzCsOA=
+gopkg.in/ini.v1 v1.67.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc=
 gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkepLTh2hOroT7a+7czfdQ=
 gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw=
 gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.2.8/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
@@ -581,4 +786,10 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
 gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
+honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
+honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
+nhooyr.io/websocket v1.8.17 h1:KEVeLJkUywCKVsnLIDlD/5gtayKp8VoCkksHCGGfT9Y=
+nhooyr.io/websocket v1.8.17/go.mod h1:rN9OFWIUwuxg4fR5tELlYC04bXYowCP9GX47ivo2l+c=
 nullprogram.com/x/optparse v1.0.0/go.mod h1:KdyPE+Igbe0jQUrVfMqDMeJQIJZEuyV7pjYmp6pbG50=
+rsc.io/qr v0.2.0 h1:6vBLea5/NRMVTz8V66gipeLycZMl/+UlFmk8DvqQ6WY=
+rsc.io/qr v0.2.0/go.mod h1:IF+uZjkb9fqyeF/4tlBoynqmQxUoPfWEKh921coOuXs=

integrations/dingtalk/bot.go

@@ -0,0 +1,133 @@
+package dingtalk
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+const (
+	apiBase   = "https://api.dingtalk.com"
+	oauthBase = "https://api.dingtalk.com/v1.0/oauth2/accessToken"
+)
+
+// Bot represents a DingTalk bot instance.
+type Bot struct {
+	clientID     string
+	clientSecret string
+	httpClient   *http.Client
+
+	accessToken  string
+	tokenExpires time.Time
+}
+
+// NewBot creates a Bot bound to DingTalk app credentials.
+func NewBot(clientID, clientSecret string) *Bot {
+	return &Bot{
+		clientID:     clientID,
+		clientSecret: clientSecret,
+		httpClient:   &http.Client{Timeout: 30 * time.Second},
+	}
+}
+
+// ClientID returns the client ID.
+func (b *Bot) ClientID() string { return b.clientID }
+
+// ClientSecret returns the client secret.
+func (b *Bot) ClientSecret() string { return b.clientSecret }
+
+// GetAccessToken returns a valid access token, refreshing if necessary.
+func (b *Bot) GetAccessToken(ctx context.Context) (string, error) {
+	if b.accessToken != "" && time.Now().Before(b.tokenExpires) {
+		return b.accessToken, nil
+	}
+
+	body, _ := json.Marshal(map[string]string{
+		"appKey":    b.clientID,
+		"appSecret": b.clientSecret,
+	})
+
+	req, err := http.NewRequestWithContext(ctx, "POST", oauthBase, bytes.NewReader(body))
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("dingtalk get token: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("read token response: %w", err)
+	}
+
+	var result struct {
+		AccessToken string `json:"accessToken"`
+		ExpireIn    int    `json:"expireIn"`
+	}
+	if err := json.Unmarshal(respBody, &result); err != nil {
+		return "", fmt.Errorf("unmarshal token: %w", err)
+	}
+	if result.AccessToken == "" {
+		return "", fmt.Errorf("dingtalk token empty, body=%s", string(respBody))
+	}
+
+	b.accessToken = result.AccessToken
+	b.tokenExpires = time.Now().Add(time.Duration(result.ExpireIn-60) * time.Second)
+	return b.accessToken, nil
+}
+
+// GetBotInfo verifies the bot credentials by fetching the access token.
+func (b *Bot) GetBotInfo(ctx context.Context) error {
+	_, err := b.GetAccessToken(ctx)
+	return err
+}
+
+// apiRequest makes an authenticated API call to DingTalk.
+func (b *Bot) apiRequest(ctx context.Context, method, path string, body interface{}) ([]byte, error) {
+	token, err := b.GetAccessToken(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	var bodyReader io.Reader
+	if body != nil {
+		data, err := json.Marshal(body)
+		if err != nil {
+			return nil, err
+		}
+		bodyReader = bytes.NewReader(data)
+	}
+
+	url := apiBase + path
+	req, err := http.NewRequestWithContext(ctx, method, url, bodyReader)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("x-acs-dingtalk-access-token", token)
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("dingtalk api: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read api response: %w", err)
+	}
+
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("dingtalk api error: status=%d body=%s", resp.StatusCode, string(respBody))
+	}
+
+	return respBody, nil
+}

integrations/dingtalk/bot_test.go

@@ -0,0 +1,15 @@
+package dingtalk
+
+import (
+	"testing"
+)
+
+func TestNewBot(t *testing.T) {
+	b := NewBot("client_id", "client_secret")
+	if b.ClientID() != "client_id" {
+		t.Fatalf("expected ClientID client_id, got %s", b.ClientID())
+	}
+	if b.ClientSecret() != "client_secret" {
+		t.Fatalf("expected ClientSecret client_secret, got %s", b.ClientSecret())
+	}
+}

integrations/dingtalk/convert.go

@@ -0,0 +1,142 @@
+package dingtalk
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// ConvertedMessage is the unified output after parsing a DingTalk message.
+type ConvertedMessage struct {
+	MessageID        string      `json:"message_id"`
+	ConversationID   string      `json:"conversation_id"`
+	ConversationType string      `json:"conversation_type"` // "1" = private, "2" = group
+	SenderID         string      `json:"sender_id"`
+	SenderNick       string      `json:"sender_nick,omitempty"`
+	SenderStaffID    string      `json:"sender_staff_id,omitempty"`
+	Text             string      `json:"text,omitempty"`
+	MediaItems       []MediaItem `json:"media,omitempty"`
+	ChatbotUserID    string      `json:"chatbot_user_id,omitempty"`
+	IsInAtList       bool        `json:"is_in_at_list,omitempty"`
+	SessionWebhook   string      `json:"session_webhook,omitempty"`
+}
+
+// MediaItem describes a single attachment in a DingTalk message.
+type MediaItem struct {
+	Type     MediaType `json:"type"`
+	URL      string    `json:"url,omitempty"`
+	MimeType string    `json:"mime_type,omitempty"`
+	FileName string    `json:"file_name,omitempty"`
+	Wrapper  string    `json:"wrapper,omitempty"`
+}
+
+// MediaType indicates the attachment type.
+type MediaType string
+
+const (
+	MediaImage    MediaType = "image"
+	MediaFile     MediaType = "file"
+	MediaAudio    MediaType = "audio"
+	MediaVideo    MediaType = "video"
+	MediaRichText MediaType = "richText"
+)
+
+// HasMedia returns true if the message contains media.
+func (cm *ConvertedMessage) HasMedia() bool { return len(cm.MediaItems) > 0 }
+
+// HasText returns true if the message contains text.
+func (cm *ConvertedMessage) HasText() bool { return cm.Text != "" }
+
+// StreamCallbackData is the data structure from DingTalk stream callback.
+type StreamCallbackData struct {
+	ConversationID            string          `json:"conversationId"`
+	ConversationType          string          `json:"conversationType"`
+	AtUsers                   []AtUser        `json:"atUsers"`
+	ChatbotCorpID             string          `json:"chatbotCorpId"`
+	ChatbotUserID             string          `json:"chatbotUserId"`
+	MsgID                     string          `json:"msgId"`
+	SenderID                  string          `json:"senderId"`
+	SenderNick                string          `json:"senderNick"`
+	SenderCorpID              string          `json:"senderCorpId"`
+	SenderStaffID             string          `json:"senderStaffId"`
+	SessionWebhook            string          `json:"sessionWebhook"`
+	SessionWebhookExpiredTime int64           `json:"sessionWebhookExpiredTime"`
+	IsAdmin                   bool            `json:"isAdmin"`
+	IsInAtList                bool            `json:"isInAtList"`
+	Text                      *TextContent    `json:"text,omitempty"`
+	Msgtype                   string          `json:"msgtype"`
+	RichText                  json.RawMessage `json:"richText,omitempty"`
+}
+
+// AtUser represents a mentioned user in a DingTalk message.
+type AtUser struct {
+	DingtalkID string `json:"dingtalkId"`
+	StaffID    string `json:"staffId,omitempty"`
+}
+
+// TextContent holds plain text content.
+type TextContent struct {
+	Content string `json:"content"`
+}
+
+// ConvertStreamData transforms a DingTalk stream callback into a ConvertedMessage.
+func ConvertStreamData(data *StreamCallbackData) *ConvertedMessage {
+	if data == nil {
+		return nil
+	}
+
+	cm := &ConvertedMessage{
+		MessageID:        data.MsgID,
+		ConversationID:   data.ConversationID,
+		ConversationType: data.ConversationType,
+		SenderID:         data.SenderID,
+		SenderNick:       data.SenderNick,
+		SenderStaffID:    data.SenderStaffID,
+		ChatbotUserID:    data.ChatbotUserID,
+		IsInAtList:       data.IsInAtList,
+		SessionWebhook:   data.SessionWebhook,
+	}
+
+	switch data.Msgtype {
+	case "text":
+		if data.Text != nil {
+			text := strings.TrimSpace(data.Text.Content)
+			cm.Text = text
+		}
+	case "richText":
+		if len(data.RichText) > 0 {
+			text, media := parseRichText(data.RichText)
+			cm.Text = text
+			cm.MediaItems = media
+		}
+	case "picture":
+		cm.MediaItems = append(cm.MediaItems, MediaItem{Type: MediaImage})
+	}
+
+	return cm
+}
+
+func parseRichText(raw json.RawMessage) (string, []MediaItem) {
+	var richText struct {
+		RichText []struct {
+			Text    string `json:"text,omitempty"`
+			PicURL  string `json:"pictureDownloadUrl,omitempty"`
+			Type    string `json:"type,omitempty"`
+			DownURL string `json:"downloadCode,omitempty"`
+		} `json:"richText"`
+	}
+	if err := json.Unmarshal(raw, &richText); err != nil {
+		return "", nil
+	}
+
+	var text string
+	var media []MediaItem
+	for _, item := range richText.RichText {
+		if item.Text != "" {
+			text += item.Text
+		}
+		if item.PicURL != "" {
+			media = append(media, MediaItem{Type: MediaImage, URL: item.PicURL, MimeType: "image/jpeg"})
+		}
+	}
+	return text, media
+}

integrations/dingtalk/convert_test.go

@@ -0,0 +1,67 @@
+package dingtalk
+
+import (
+	"testing"
+)
+
+func TestConvertStreamData_Text(t *testing.T) {
+	data := &StreamCallbackData{
+		MsgID:            "msg_001",
+		ConversationID:   "cid_001",
+		ConversationType: "1",
+		SenderID:         "user_001",
+		SenderNick:       "Test User",
+		SessionWebhook:   "https://oapi.dingtalk.com/robot/sendBySession/xxx",
+		Msgtype:          "text",
+		Text:             &TextContent{Content: " Hello World "},
+	}
+
+	cm := ConvertStreamData(data)
+	if cm == nil {
+		t.Fatal("expected non-nil ConvertedMessage")
+	}
+	if cm.MessageID != "msg_001" {
+		t.Errorf("expected msg_001, got %s", cm.MessageID)
+	}
+	if cm.Text != "Hello World" {
+		t.Errorf("expected 'Hello World', got %q", cm.Text)
+	}
+	if cm.ConversationID != "cid_001" {
+		t.Errorf("expected cid_001, got %s", cm.ConversationID)
+	}
+	if cm.SenderNick != "Test User" {
+		t.Errorf("expected 'Test User', got %s", cm.SenderNick)
+	}
+	if cm.SessionWebhook == "" {
+		t.Error("expected non-empty SessionWebhook")
+	}
+}
+
+func TestConvertStreamData_Nil(t *testing.T) {
+	cm := ConvertStreamData(nil)
+	if cm != nil {
+		t.Error("nil input should return nil")
+	}
+}
+
+func TestConvertedMessage_HasText(t *testing.T) {
+	cm := &ConvertedMessage{}
+	if cm.HasText() {
+		t.Error("empty should not have text")
+	}
+	cm.Text = "hello"
+	if !cm.HasText() {
+		t.Error("should have text")
+	}
+}
+
+func TestConvertedMessage_HasMedia(t *testing.T) {
+	cm := &ConvertedMessage{}
+	if cm.HasMedia() {
+		t.Error("empty should not have media")
+	}
+	cm.MediaItems = append(cm.MediaItems, MediaItem{Type: MediaImage, URL: "http://example.com/img.jpg"})
+	if !cm.HasMedia() {
+		t.Error("should have media")
+	}
+}

integrations/dingtalk/dingtalk_test.go

@@ -0,0 +1,28 @@
+package dingtalk
+
+import (
+	"os"
+	"testing"
+)
+
+var (
+	testClientID     string
+	testClientSecret string
+)
+
+func TestMain(m *testing.M) {
+	testClientID = os.Getenv("DINGTALK_TEST_CLIENT_ID")
+	testClientSecret = os.Getenv("DINGTALK_TEST_CLIENT_SECRET")
+	os.Exit(m.Run())
+}
+
+func skipIfNoCreds(t *testing.T) {
+	t.Helper()
+	if testClientID == "" || testClientSecret == "" {
+		t.Skip("DINGTALK_TEST_CLIENT_ID or DINGTALK_TEST_CLIENT_SECRET not set")
+	}
+}
+
+func testBotInstance() *Bot {
+	return NewBot(testClientID, testClientSecret)
+}

integrations/dingtalk/e2e_test.go

@@ -0,0 +1,57 @@
+package dingtalk
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// TestE2E_01_GetAccessToken verifies the DingTalk credentials by requesting an access token.
+func TestE2E_01_GetAccessToken(t *testing.T) {
+	skipIfNoCreds(t)
+	b := testBotInstance()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	token, err := b.GetAccessToken(ctx)
+	if err != nil {
+		t.Fatalf("GetAccessToken: %v", err)
+	}
+	if token == "" {
+		t.Fatal("access token should not be empty")
+	}
+	t.Logf("OK  access_token=%s... (truncated)", token[:min(20, len(token))])
+
+	// Verify token caching
+	token2, err := b.GetAccessToken(ctx)
+	if err != nil {
+		t.Fatalf("GetAccessToken (cached): %v", err)
+	}
+	if token2 != token {
+		t.Error("cached token should be the same")
+	}
+	t.Log("OK  token caching verified")
+}
+
+// TestE2E_02_BotInfo verifies bot credentials via GetBotInfo.
+func TestE2E_02_BotInfo(t *testing.T) {
+	skipIfNoCreds(t)
+	b := testBotInstance()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	err := b.GetBotInfo(ctx)
+	if err != nil {
+		t.Fatalf("GetBotInfo: %v", err)
+	}
+	t.Log("OK  bot credentials verified")
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}

integrations/dingtalk/file.go

@@ -0,0 +1,123 @@
+package dingtalk
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/textproto"
+	"strings"
+
+	"github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/attachment"
+)
+
+const defaultUploader = "__yao.attachment"
+
+// FileResult holds attachment wrapper and metadata.
+type FileResult struct {
+	Wrapper  string
+	MimeType string
+	FileName string
+}
+
+// DownloadAndStoreURL downloads a file from URL and stores it through the
+// attachment manager. Uses the URL as fingerprint for dedup.
+func DownloadAndStoreURL(ctx context.Context, url, mimeType, fileName string, groups []string) (*FileResult, error) {
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		return nil, fmt.Errorf("attachment manager %s not found", defaultUploader)
+	}
+
+	fingerprint := url
+	probeID := fingerprintKey(fingerprint, groups)
+	if manager.Exists(ctx, probeID) {
+		wrapper := fmt.Sprintf("%s://%s", defaultUploader, probeID)
+		return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: fileName}, nil
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download: %w", err)
+	}
+	defer resp.Body.Close()
+
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+
+	if mimeType == "" {
+		mimeType = resp.Header.Get("Content-Type")
+		if mimeType == "" {
+			mimeType = "application/octet-stream"
+		}
+	}
+	if fileName == "" {
+		fileName = "file"
+	}
+
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: fileName,
+			Size:     int64(len(data)),
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", mimeType)
+	header.Header.Set("Content-Fingerprint", fingerprint)
+
+	option := attachment.UploadOption{
+		OriginalFilename: fileName,
+		Groups:           groups,
+	}
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), option)
+	if err != nil {
+		return nil, fmt.Errorf("attachment upload: %w", err)
+	}
+
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: fileName}, nil
+}
+
+// ResolveMedia downloads and stores all media items in a ConvertedMessage.
+func ResolveMedia(ctx context.Context, cm *ConvertedMessage, groups []string) {
+	if cm == nil {
+		return
+	}
+	for i := range cm.MediaItems {
+		mi := &cm.MediaItems[i]
+		if mi.URL == "" {
+			continue
+		}
+		result, err := DownloadAndStoreURL(ctx, mi.URL, mi.MimeType, mi.FileName, groups)
+		if err != nil {
+			log.Error("dingtalk ResolveMedia: %s %s: %v", mi.Type, mi.URL, err)
+			continue
+		}
+		mi.Wrapper = result.Wrapper
+		if result.MimeType != "" {
+			mi.MimeType = result.MimeType
+		}
+	}
+}
+
+func fingerprintKey(key string, groups []string) string {
+	parts := make([]string, 0, len(groups)+1)
+	parts = append(parts, groups...)
+	parts = append(parts, key)
+	storagePath := strings.Join(parts, "/")
+	hash := md5.Sum([]byte(storagePath))
+	return hex.EncodeToString(hash[:])
+}

integrations/dingtalk/format.go

@@ -0,0 +1,170 @@
+package dingtalk
+
+import (
+	"regexp"
+	"strings"
+)
+
+// FormatDingTalkMarkdown converts standard Markdown to DingTalk's Markdown subset.
+//
+// DingTalk webhook Markdown supports:
+//   - # headings (1-6)
+//   - **bold**, *italic*
+//   - > blockquote
+//   - - unordered list
+//   - [link](url)
+//   - ![image](url)
+//   - ---  divider
+//
+// NOT supported (must be degraded):
+//   - ~~strikethrough~~  → plain text
+//   - ``` code blocks    → indented text
+//   - `inline code`      → plain text
+//   - tables             → pre-formatted text
+//   - ordered lists      → "N. " text (passthrough, may not render)
+func FormatDingTalkMarkdown(md string) string {
+	md = strings.ReplaceAll(md, "\r\n", "\n")
+
+	var out strings.Builder
+	lines := strings.Split(md, "\n")
+
+	inCodeBlock := false
+	var codeLines []string
+
+	inTable := false
+	var tableRows [][]string
+
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+
+		if strings.HasPrefix(line, "```") {
+			if !inCodeBlock {
+				inCodeBlock = true
+				codeLines = nil
+			} else {
+				inCodeBlock = false
+				out.WriteString("\n")
+				for _, cl := range codeLines {
+					out.WriteString("    " + cl + "\n")
+				}
+				out.WriteString("\n")
+			}
+			continue
+		}
+		if inCodeBlock {
+			codeLines = append(codeLines, line)
+			continue
+		}
+
+		if dtIsTableRow(line) {
+			if !inTable {
+				inTable = true
+				tableRows = nil
+			}
+			if dtIsTableSep(line) {
+				continue
+			}
+			tableRows = append(tableRows, dtParseTableRow(line))
+			continue
+		}
+		if inTable {
+			dtFlushTable(&out, tableRows)
+			inTable = false
+			tableRows = nil
+		}
+
+		line = dtReStrikethrough.ReplaceAllString(line, "$1")
+		line = dtReInlineCode.ReplaceAllString(line, "$1")
+
+		out.WriteString(line + "\n")
+	}
+
+	if inCodeBlock && len(codeLines) > 0 {
+		out.WriteString("\n")
+		for _, cl := range codeLines {
+			out.WriteString("    " + cl + "\n")
+		}
+		out.WriteString("\n")
+	}
+	if inTable {
+		dtFlushTable(&out, tableRows)
+	}
+
+	return strings.TrimRight(out.String(), "\n")
+}
+
+var (
+	dtReStrikethrough = regexp.MustCompile(`~~(.+?)~~`)
+	dtReInlineCode    = regexp.MustCompile("`([^`]+)`")
+	dtReTableRow      = regexp.MustCompile(`^\|.*\|$`)
+	dtReTableSep      = regexp.MustCompile(`^\|[\s\-:|]+\|$`)
+)
+
+func dtIsTableRow(line string) bool {
+	return dtReTableRow.MatchString(strings.TrimSpace(line))
+}
+
+func dtIsTableSep(line string) bool {
+	return dtReTableSep.MatchString(strings.TrimSpace(line))
+}
+
+func dtParseTableRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	cells := strings.Split(line, "|")
+	for i := range cells {
+		cells[i] = strings.TrimSpace(cells[i])
+	}
+	return cells
+}
+
+func dtFlushTable(out *strings.Builder, rows [][]string) {
+	if len(rows) == 0 {
+		return
+	}
+	colWidths := make([]int, len(rows[0]))
+	for _, row := range rows {
+		for i, cell := range row {
+			if i < len(colWidths) && len([]rune(cell)) > colWidths[i] {
+				colWidths[i] = len([]rune(cell))
+			}
+		}
+	}
+	out.WriteString("\n")
+	for ri, row := range rows {
+		for ci, cell := range row {
+			if ci > 0 {
+				out.WriteString(" | ")
+			}
+			w := 0
+			if ci < len(colWidths) {
+				w = colWidths[ci]
+			}
+			out.WriteString(dtPadRight(cell, w))
+		}
+		out.WriteString("\n")
+		if ri == 0 && len(rows) > 1 {
+			for ci := range row {
+				if ci > 0 {
+					out.WriteString("-+-")
+				}
+				w := 0
+				if ci < len(colWidths) {
+					w = colWidths[ci]
+				}
+				out.WriteString(strings.Repeat("-", w))
+			}
+			out.WriteString("\n")
+		}
+	}
+	out.WriteString("\n")
+}
+
+func dtPadRight(s string, width int) string {
+	runes := []rune(s)
+	if len(runes) >= width {
+		return s
+	}
+	return s + strings.Repeat(" ", width-len(runes))
+}

integrations/dingtalk/message.go

@@ -0,0 +1,117 @@
+package dingtalk
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+)
+
+// SendTextMessage sends a text message to a conversation using the session webhook.
+func SendTextMessage(ctx context.Context, sessionWebhook, text string) error {
+	body, _ := json.Marshal(map[string]interface{}{
+		"msgtype": "text",
+		"text": map[string]string{
+			"content": text,
+		},
+	})
+	return postWebhook(ctx, sessionWebhook, body)
+}
+
+// SendMarkdownMessage sends a markdown message via session webhook.
+func SendMarkdownMessage(ctx context.Context, sessionWebhook, title, text string) error {
+	body, _ := json.Marshal(map[string]interface{}{
+		"msgtype": "markdown",
+		"markdown": map[string]string{
+			"title": title,
+			"text":  text,
+		},
+	})
+	return postWebhook(ctx, sessionWebhook, body)
+}
+
+// SendImageMessage sends an image via session webhook using media_id.
+func SendImageMessage(ctx context.Context, sessionWebhook, mediaID string) error {
+	body, _ := json.Marshal(map[string]interface{}{
+		"msgtype": "image",
+		"image": map[string]string{
+			"mediaId": mediaID,
+		},
+	})
+	return postWebhook(ctx, sessionWebhook, body)
+}
+
+// SendFileMessage sends a file via session webhook using media_id.
+func SendFileMessage(ctx context.Context, sessionWebhook, mediaID, fileName, fileType string) error {
+	body, _ := json.Marshal(map[string]interface{}{
+		"msgtype": "file",
+		"file": map[string]string{
+			"mediaId":  mediaID,
+			"fileName": fileName,
+			"fileType": fileType,
+		},
+	})
+	return postWebhook(ctx, sessionWebhook, body)
+}
+
+// ReplyText sends a text reply to a conversation using the Robot OpenAPI.
+func (b *Bot) ReplyText(ctx context.Context, openConversationID, text string) error {
+	token, err := b.GetAccessToken(ctx)
+	if err != nil {
+		return err
+	}
+
+	body, _ := json.Marshal(map[string]interface{}{
+		"robotCode":          b.clientID,
+		"openConversationId": openConversationID,
+		"msgKey":             "sampleText",
+		"msgParam":           fmt.Sprintf(`{"content":"%s"}`, text),
+	})
+
+	req, err := http.NewRequestWithContext(ctx, "POST",
+		apiBase+"/v1.0/robot/oToMessages/batchSend", bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("x-acs-dingtalk-access-token", token)
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("dingtalk reply: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("dingtalk reply: status=%d body=%s", resp.StatusCode, string(respBody))
+	}
+	return nil
+}
+
+func postWebhook(ctx context.Context, webhookURL string, body []byte) error {
+	if webhookURL == "" {
+		return fmt.Errorf("empty session webhook URL")
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", webhookURL, bytes.NewReader(body))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	if err != nil {
+		return fmt.Errorf("dingtalk webhook post: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode >= 400 {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("dingtalk webhook: status=%d body=%s", resp.StatusCode, string(respBody))
+	}
+	return nil
+}

integrations/discord/bot.go

@@ -0,0 +1,44 @@
+package discord
+
+import (
+	"fmt"
+
+	"github.com/bwmarrin/discordgo"
+)
+
+// Bot represents a single Discord bot instance bound to a token.
+type Bot struct {
+	token   string
+	appID   string
+	session *discordgo.Session
+}
+
+// NewBot creates a Bot bound to the given Discord bot token.
+func NewBot(token, appID string) (*Bot, error) {
+	session, err := discordgo.New("Bot " + token)
+	if err != nil {
+		return nil, fmt.Errorf("create discord session: %w", err)
+	}
+	session.Identify.Intents = discordgo.IntentsGuildMessages |
+		discordgo.IntentsDirectMessages |
+		discordgo.IntentMessageContent
+	return &Bot{
+		token:   token,
+		appID:   appID,
+		session: session,
+	}, nil
+}
+
+// Token returns the raw bot token.
+func (b *Bot) Token() string { return b.token }
+
+// AppID returns the application ID.
+func (b *Bot) AppID() string { return b.appID }
+
+// Session returns the underlying discordgo session.
+func (b *Bot) Session() *discordgo.Session { return b.session }
+
+// BotUser returns the bot's own user information (verifies token).
+func (b *Bot) BotUser() (*discordgo.User, error) {
+	return b.session.User("@me")
+}

integrations/discord/bot_test.go

@@ -0,0 +1,21 @@
+package discord
+
+import (
+	"testing"
+)
+
+func TestNewBot(t *testing.T) {
+	bot, err := NewBot("test-token", "test-app-id")
+	if err != nil {
+		t.Fatalf("NewBot: %v", err)
+	}
+	if bot.Token() != "test-token" {
+		t.Fatalf("expected token test-token, got %s", bot.Token())
+	}
+	if bot.AppID() != "test-app-id" {
+		t.Fatalf("expected appID test-app-id, got %s", bot.AppID())
+	}
+	if bot.Session() == nil {
+		t.Fatal("Session() should not be nil")
+	}
+}

integrations/discord/convert.go

@@ -0,0 +1,110 @@
+package discord
+
+import (
+	"github.com/bwmarrin/discordgo"
+)
+
+// ConvertedMessage is the unified output after parsing a Discord message event.
+type ConvertedMessage struct {
+	MessageID  string      `json:"message_id"`
+	ChannelID  string      `json:"channel_id"`
+	GuildID    string      `json:"guild_id,omitempty"`
+	AuthorID   string      `json:"author_id"`
+	AuthorName string      `json:"author_name,omitempty"`
+	IsBot      bool        `json:"is_bot"`
+	Text       string      `json:"text,omitempty"`
+	MediaItems []MediaItem `json:"media,omitempty"`
+	Locale     string      `json:"locale,omitempty"`
+	ReplyTo    string      `json:"reply_to,omitempty"`
+	IsDM       bool        `json:"is_dm"`
+}
+
+// MediaItem describes a single attachment from a Discord message.
+type MediaItem struct {
+	Type        MediaType `json:"type"`
+	URL         string    `json:"url"`
+	ProxyURL    string    `json:"proxy_url,omitempty"`
+	FileName    string    `json:"file_name"`
+	ContentType string    `json:"content_type,omitempty"`
+	Size        int       `json:"size,omitempty"`
+	Wrapper     string    `json:"wrapper,omitempty"`
+}
+
+// MediaType indicates the attachment type.
+type MediaType string
+
+const (
+	MediaImage    MediaType = "image"
+	MediaVideo    MediaType = "video"
+	MediaAudio    MediaType = "audio"
+	MediaDocument MediaType = "document"
+)
+
+// HasMedia returns true if the message contains media.
+func (cm *ConvertedMessage) HasMedia() bool { return len(cm.MediaItems) > 0 }
+
+// HasText returns true if the message contains text.
+func (cm *ConvertedMessage) HasText() bool { return cm.Text != "" }
+
+// ConvertMessageCreate transforms a discordgo MessageCreate event into a ConvertedMessage.
+func ConvertMessageCreate(m *discordgo.MessageCreate) *ConvertedMessage {
+	if m == nil || m.Message == nil {
+		return nil
+	}
+	return ConvertMessage(m.Message)
+}
+
+// ConvertMessage transforms a discordgo Message into a ConvertedMessage.
+func ConvertMessage(m *discordgo.Message) *ConvertedMessage {
+	if m == nil {
+		return nil
+	}
+
+	cm := &ConvertedMessage{
+		MessageID: m.ID,
+		ChannelID: m.ChannelID,
+		GuildID:   m.GuildID,
+		Text:      m.Content,
+		IsDM:      m.GuildID == "",
+	}
+
+	if m.Author != nil {
+		cm.AuthorID = m.Author.ID
+		cm.AuthorName = m.Author.Username
+		cm.IsBot = m.Author.Bot
+		cm.Locale = m.Author.Locale
+	}
+
+	if m.MessageReference != nil {
+		cm.ReplyTo = m.MessageReference.MessageID
+	}
+
+	for _, att := range m.Attachments {
+		cm.MediaItems = append(cm.MediaItems, MediaItem{
+			Type:        detectMediaType(att.ContentType),
+			URL:         att.URL,
+			ProxyURL:    att.ProxyURL,
+			FileName:    att.Filename,
+			ContentType: att.ContentType,
+			Size:        att.Size,
+		})
+	}
+
+	return cm
+}
+
+func detectMediaType(contentType string) MediaType {
+	if contentType == "" {
+		return MediaDocument
+	}
+	switch {
+	case len(contentType) > 6 && contentType[:6] == "image/":
+		return MediaImage
+	case len(contentType) > 6 && contentType[:6] == "video/":
+		return MediaVideo
+	case len(contentType) > 6 && contentType[:6] == "audio/":
+		return MediaAudio
+	default:
+		return MediaDocument
+	}
+}

integrations/discord/convert_test.go

@@ -0,0 +1,173 @@
+package discord
+
+import (
+	"testing"
+
+	"github.com/bwmarrin/discordgo"
+)
+
+func TestConvertMessage_Text(t *testing.T) {
+	m := &discordgo.Message{
+		ID:        "msg_001",
+		ChannelID: "ch_001",
+		GuildID:   "guild_001",
+		Content:   "Hello World",
+		Author: &discordgo.User{
+			ID:       "user_001",
+			Username: "TestUser",
+			Bot:      false,
+		},
+	}
+	cm := ConvertMessage(m)
+	if cm == nil {
+		t.Fatal("expected non-nil ConvertedMessage")
+	}
+	if cm.MessageID != "msg_001" {
+		t.Errorf("expected msg_001, got %s", cm.MessageID)
+	}
+	if cm.Text != "Hello World" {
+		t.Errorf("expected 'Hello World', got %q", cm.Text)
+	}
+	if cm.AuthorID != "user_001" {
+		t.Errorf("expected user_001, got %s", cm.AuthorID)
+	}
+	if cm.AuthorName != "TestUser" {
+		t.Errorf("expected TestUser, got %s", cm.AuthorName)
+	}
+	if cm.IsBot {
+		t.Error("expected IsBot=false")
+	}
+	if cm.IsDM {
+		t.Error("expected IsDM=false for guild message")
+	}
+	if !cm.HasText() {
+		t.Error("expected HasText=true")
+	}
+	if cm.HasMedia() {
+		t.Error("expected HasMedia=false")
+	}
+}
+
+func TestConvertMessage_DM(t *testing.T) {
+	m := &discordgo.Message{
+		ID:        "msg_002",
+		ChannelID: "ch_dm",
+		Content:   "DM message",
+		Author: &discordgo.User{
+			ID:       "user_002",
+			Username: "DMUser",
+		},
+	}
+	cm := ConvertMessage(m)
+	if cm == nil {
+		t.Fatal("expected non-nil")
+	}
+	if !cm.IsDM {
+		t.Error("expected IsDM=true for message without GuildID")
+	}
+}
+
+func TestConvertMessage_WithAttachments(t *testing.T) {
+	m := &discordgo.Message{
+		ID:        "msg_003",
+		ChannelID: "ch_003",
+		Content:   "Check this out",
+		Author: &discordgo.User{
+			ID:       "user_003",
+			Username: "FileUser",
+		},
+		Attachments: []*discordgo.MessageAttachment{
+			{
+				ID:          "att_001",
+				URL:         "https://cdn.discordapp.com/attachments/test.png",
+				ProxyURL:    "https://media.discordapp.net/attachments/test.png",
+				Filename:    "test.png",
+				ContentType: "image/png",
+				Size:        1024,
+			},
+			{
+				ID:          "att_002",
+				URL:         "https://cdn.discordapp.com/attachments/report.pdf",
+				Filename:    "report.pdf",
+				ContentType: "application/pdf",
+				Size:        2048,
+			},
+		},
+	}
+	cm := ConvertMessage(m)
+	if cm == nil {
+		t.Fatal("expected non-nil")
+	}
+	if !cm.HasText() {
+		t.Error("expected HasText=true")
+	}
+	if !cm.HasMedia() {
+		t.Error("expected HasMedia=true")
+	}
+	if len(cm.MediaItems) != 2 {
+		t.Fatalf("expected 2 media items, got %d", len(cm.MediaItems))
+	}
+	if cm.MediaItems[0].Type != MediaImage {
+		t.Errorf("expected image type, got %s", cm.MediaItems[0].Type)
+	}
+	if cm.MediaItems[0].FileName != "test.png" {
+		t.Errorf("expected test.png, got %s", cm.MediaItems[0].FileName)
+	}
+	if cm.MediaItems[1].Type != MediaDocument {
+		t.Errorf("expected document type, got %s", cm.MediaItems[1].Type)
+	}
+}
+
+func TestConvertMessage_WithReply(t *testing.T) {
+	m := &discordgo.Message{
+		ID:        "msg_004",
+		ChannelID: "ch_004",
+		Content:   "Replying",
+		Author:    &discordgo.User{ID: "user_004"},
+		MessageReference: &discordgo.MessageReference{
+			MessageID: "msg_original",
+			ChannelID: "ch_004",
+		},
+	}
+	cm := ConvertMessage(m)
+	if cm == nil {
+		t.Fatal("expected non-nil")
+	}
+	if cm.ReplyTo != "msg_original" {
+		t.Errorf("expected ReplyTo=msg_original, got %s", cm.ReplyTo)
+	}
+}
+
+func TestConvertMessage_Nil(t *testing.T) {
+	cm := ConvertMessage(nil)
+	if cm != nil {
+		t.Error("nil input should return nil")
+	}
+}
+
+func TestConvertMessageCreate_Nil(t *testing.T) {
+	cm := ConvertMessageCreate(nil)
+	if cm != nil {
+		t.Error("nil input should return nil")
+	}
+}
+
+func TestDetectMediaType(t *testing.T) {
+	cases := []struct {
+		input    string
+		expected MediaType
+	}{
+		{"image/png", MediaImage},
+		{"image/jpeg", MediaImage},
+		{"video/mp4", MediaVideo},
+		{"audio/mpeg", MediaAudio},
+		{"application/pdf", MediaDocument},
+		{"", MediaDocument},
+	}
+	for _, tc := range cases {
+		got := detectMediaType(tc.input)
+		if got != tc.expected {
+			t.Errorf("detectMediaType(%q) = %q, want %q", tc.input, got, tc.expected)
+		}
+	}
+}

integrations/discord/discord_test.go

@@ -0,0 +1,33 @@
+package discord
+
+import (
+	"os"
+	"testing"
+)
+
+var (
+	testBotToken string
+	testAppID    string
+)
+
+func TestMain(m *testing.M) {
+	testBotToken = os.Getenv("DISCORD_TEST_BOT_TOKEN")
+	testAppID = os.Getenv("DISCORD_TEST_APP_ID")
+	os.Exit(m.Run())
+}
+
+func skipIfNoToken(t *testing.T) {
+	t.Helper()
+	if testBotToken == "" {
+		t.Skip("DISCORD_TEST_BOT_TOKEN not set")
+	}
+}
+
+func testBot(t *testing.T) *Bot {
+	t.Helper()
+	bot, err := NewBot(testBotToken, testAppID)
+	if err != nil {
+		t.Fatalf("NewBot: %v", err)
+	}
+	return bot
+}

integrations/discord/e2e_test.go

@@ -0,0 +1,27 @@
+package discord
+
+import (
+	"testing"
+)
+
+// TestE2E_01_BotUser verifies the Discord bot token by fetching bot user info.
+func TestE2E_01_BotUser(t *testing.T) {
+	skipIfNoToken(t)
+	bot := testBot(t)
+
+	user, err := bot.BotUser()
+	if err != nil {
+		t.Fatalf("BotUser: %v", err)
+	}
+	if user.ID == "" {
+		t.Error("user.ID should not be empty")
+	}
+	if user.Username == "" {
+		t.Error("user.Username should not be empty")
+	}
+	if !user.Bot {
+		t.Error("user.Bot should be true")
+	}
+	t.Logf("OK  id=%s username=%s discriminator=%s bot=%v",
+		user.ID, user.Username, user.Discriminator, user.Bot)
+}

integrations/discord/file.go

@@ -0,0 +1,122 @@
+package discord
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/textproto"
+	"strings"
+
+	"github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/attachment"
+)
+
+const defaultUploader = "__yao.attachment"
+
+// FileResult holds attachment wrapper and metadata.
+type FileResult struct {
+	Wrapper  string
+	MimeType string
+	FileName string
+}
+
+// DownloadAndStoreURL downloads a file from URL and stores it through
+// the attachment manager. Uses the URL as fingerprint for dedup.
+func DownloadAndStoreURL(ctx context.Context, url, contentType, fileName string, groups []string) (*FileResult, error) {
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		return nil, fmt.Errorf("attachment manager %s not found", defaultUploader)
+	}
+
+	probeID := fingerprintKey(url, groups)
+	if manager.Exists(ctx, probeID) {
+		wrapper := fmt.Sprintf("%s://%s", defaultUploader, probeID)
+		return &FileResult{Wrapper: wrapper, MimeType: contentType, FileName: fileName}, nil
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+
+	client := &http.Client{}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("download: %w", err)
+	}
+	defer resp.Body.Close()
+
+	data, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+
+	if contentType == "" {
+		contentType = resp.Header.Get("Content-Type")
+		if contentType == "" {
+			contentType = "application/octet-stream"
+		}
+	}
+	if fileName == "" {
+		fileName = "file"
+	}
+
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: fileName,
+			Size:     int64(len(data)),
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", contentType)
+	header.Header.Set("Content-Fingerprint", url)
+
+	option := attachment.UploadOption{
+		OriginalFilename: fileName,
+		Groups:           groups,
+	}
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), option)
+	if err != nil {
+		return nil, fmt.Errorf("attachment upload: %w", err)
+	}
+
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	return &FileResult{Wrapper: wrapper, MimeType: contentType, FileName: fileName}, nil
+}
+
+// ResolveMedia downloads and stores all media items in a ConvertedMessage.
+func ResolveMedia(ctx context.Context, cm *ConvertedMessage, groups []string) {
+	if cm == nil {
+		return
+	}
+	for i := range cm.MediaItems {
+		mi := &cm.MediaItems[i]
+		if mi.URL == "" {
+			continue
+		}
+		result, err := DownloadAndStoreURL(ctx, mi.URL, mi.ContentType, mi.FileName, groups)
+		if err != nil {
+			log.Error("discord ResolveMedia: %s %s: %v", mi.Type, mi.URL, err)
+			continue
+		}
+		mi.Wrapper = result.Wrapper
+		if result.MimeType != "" {
+			mi.ContentType = result.MimeType
+		}
+	}
+}
+
+func fingerprintKey(key string, groups []string) string {
+	parts := make([]string, 0, len(groups)+1)
+	parts = append(parts, groups...)
+	parts = append(parts, key)
+	storagePath := strings.Join(parts, "/")
+	hash := md5.Sum([]byte(storagePath))
+	return hex.EncodeToString(hash[:])
+}

integrations/discord/format.go

@@ -0,0 +1,151 @@
+package discord
+
+import (
+	"regexp"
+	"strings"
+)
+
+// FormatDiscordMarkdown converts standard Markdown to Discord-compatible Markdown.
+//
+// Discord supports most standard Markdown:
+//   - **bold**, *italic*, ~~strikethrough~~
+//   - `inline code`, ``` code blocks ```
+//   - > blockquote
+//   - - unordered list, 1. ordered list
+//   - [link](url) (auto-embeds)
+//   - # heading (rendered as large bold text)
+//
+// NOT supported (must be degraded):
+//   - tables          → pre-formatted code block
+//   - ![image](url)   → just the URL (Discord auto-embeds images from URLs)
+//
+// Discord has a 2000 character message limit; this function does not truncate.
+func FormatDiscordMarkdown(md string) string {
+	md = strings.ReplaceAll(md, "\r\n", "\n")
+
+	var out strings.Builder
+	lines := strings.Split(md, "\n")
+
+	inCodeBlock := false
+	inTable := false
+	var tableRows [][]string
+
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+
+		if strings.HasPrefix(line, "```") {
+			inCodeBlock = !inCodeBlock
+			out.WriteString(line + "\n")
+			continue
+		}
+		if inCodeBlock {
+			out.WriteString(line + "\n")
+			continue
+		}
+
+		if dcIsTableRow(line) {
+			if !inTable {
+				inTable = true
+				tableRows = nil
+			}
+			if dcIsTableSep(line) {
+				continue
+			}
+			tableRows = append(tableRows, dcParseTableRow(line))
+			continue
+		}
+		if inTable {
+			dcFlushTable(&out, tableRows)
+			inTable = false
+			tableRows = nil
+		}
+
+		if m := dcReImage.FindStringSubmatch(line); m != nil {
+			out.WriteString(m[2] + "\n")
+			continue
+		}
+
+		out.WriteString(line + "\n")
+	}
+
+	if inTable {
+		dcFlushTable(&out, tableRows)
+	}
+
+	return strings.TrimRight(out.String(), "\n")
+}
+
+var (
+	dcReImage    = regexp.MustCompile(`^!\[([^\]]*)\]\(([^)]+)\)$`)
+	dcReTableRow = regexp.MustCompile(`^\|.*\|$`)
+	dcReTableSep = regexp.MustCompile(`^\|[\s\-:|]+\|$`)
+)
+
+func dcIsTableRow(line string) bool {
+	return dcReTableRow.MatchString(strings.TrimSpace(line))
+}
+
+func dcIsTableSep(line string) bool {
+	return dcReTableSep.MatchString(strings.TrimSpace(line))
+}
+
+func dcParseTableRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	cells := strings.Split(line, "|")
+	for i := range cells {
+		cells[i] = strings.TrimSpace(cells[i])
+	}
+	return cells
+}
+
+func dcFlushTable(out *strings.Builder, rows [][]string) {
+	if len(rows) == 0 {
+		return
+	}
+	colWidths := make([]int, len(rows[0]))
+	for _, row := range rows {
+		for i, cell := range row {
+			if i < len(colWidths) && len([]rune(cell)) > colWidths[i] {
+				colWidths[i] = len([]rune(cell))
+			}
+		}
+	}
+	out.WriteString("```\n")
+	for ri, row := range rows {
+		for ci, cell := range row {
+			if ci > 0 {
+				out.WriteString(" | ")
+			}
+			w := 0
+			if ci < len(colWidths) {
+				w = colWidths[ci]
+			}
+			out.WriteString(dcPadRight(cell, w))
+		}
+		out.WriteString("\n")
+		if ri == 0 && len(rows) > 1 {
+			for ci := range row {
+				if ci > 0 {
+					out.WriteString("-+-")
+				}
+				w := 0
+				if ci < len(colWidths) {
+					w = colWidths[ci]
+				}
+				out.WriteString(strings.Repeat("-", w))
+			}
+			out.WriteString("\n")
+		}
+	}
+	out.WriteString("```\n")
+}
+
+func dcPadRight(s string, width int) string {
+	runes := []rune(s)
+	if len(runes) >= width {
+		return s
+	}
+	return s + strings.Repeat(" ", width-len(runes))
+}

integrations/discord/message.go

@@ -0,0 +1,78 @@
+package discord
+
+import (
+	"fmt"
+	"io"
+
+	"github.com/bwmarrin/discordgo"
+	"github.com/yaoapp/yao/attachment"
+)
+
+// SendMessage sends a text message to a channel.
+func (b *Bot) SendMessage(channelID, text string) (*discordgo.Message, error) {
+	return b.session.ChannelMessageSend(channelID, text)
+}
+
+// SendMessageReply sends a text message as a reply to another message.
+func (b *Bot) SendMessageReply(channelID, text, replyToID string) (*discordgo.Message, error) {
+	return b.session.ChannelMessageSendReply(channelID, text, &discordgo.MessageReference{
+		MessageID: replyToID,
+		ChannelID: channelID,
+	})
+}
+
+// SendComplex sends a complex message with embeds, files, etc.
+func (b *Bot) SendComplex(channelID string, data *discordgo.MessageSend) (*discordgo.Message, error) {
+	return b.session.ChannelMessageSendComplex(channelID, data)
+}
+
+// SendFile sends a file to a channel.
+func (b *Bot) SendFile(channelID, filename string, reader io.Reader) (*discordgo.Message, error) {
+	return b.session.ChannelFileSend(channelID, filename, reader)
+}
+
+// SendFileWithMessage sends a file with an accompanying text message.
+func (b *Bot) SendFileWithMessage(channelID, text, filename string, reader io.Reader) (*discordgo.Message, error) {
+	return b.session.ChannelFileSendWithMessage(channelID, text, filename, reader)
+}
+
+// SendMediaFromWrapper sends a media file from a Yao attachment wrapper.
+func (b *Bot) SendMediaFromWrapper(channelID, wrapper, caption string) error {
+	managerName, fileID, err := parseWrapper(wrapper)
+	if err != nil {
+		return err
+	}
+
+	manager, exists := attachment.Managers[managerName]
+	if !exists {
+		return fmt.Errorf("attachment manager %s not found", managerName)
+	}
+
+	resp, err := manager.Download(nil, fileID)
+	if err != nil {
+		return fmt.Errorf("attachment download %s: %w", fileID, err)
+	}
+	defer resp.Reader.Close()
+
+	filename := fileID + resp.Extension
+	if caption != "" {
+		_, err = b.SendFileWithMessage(channelID, caption, filename, resp.Reader)
+	} else {
+		_, err = b.SendFile(channelID, filename, resp.Reader)
+	}
+	return err
+}
+
+func parseWrapper(wrapper string) (managerName string, fileID string, err error) {
+	idx := 0
+	for i := range wrapper {
+		if wrapper[i] == ':' && i+2 < len(wrapper) && wrapper[i+1] == '/' && wrapper[i+2] == '/' {
+			idx = i
+			break
+		}
+	}
+	if idx == 0 {
+		return "", "", fmt.Errorf("invalid attachment wrapper: %s", wrapper)
+	}
+	return wrapper[:idx], wrapper[idx+3:], nil
+}

integrations/discord/message_test.go

@@ -0,0 +1,34 @@
+package discord
+
+import (
+	"testing"
+)
+
+func TestParseWrapper(t *testing.T) {
+	cases := []struct {
+		input   string
+		manager string
+		fileID  string
+		wantErr bool
+	}{
+		{"__yao.attachment://abc123", "__yao.attachment", "abc123", false},
+		{"__custom.uploader://xyz", "__custom.uploader", "xyz", false},
+		{"no-separator", "", "", true},
+	}
+	for _, tc := range cases {
+		manager, fileID, err := parseWrapper(tc.input)
+		if tc.wantErr {
+			if err == nil {
+				t.Errorf("parseWrapper(%q) expected error, got nil", tc.input)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("parseWrapper(%q) unexpected error: %v", tc.input, err)
+			continue
+		}
+		if manager != tc.manager || fileID != tc.fileID {
+			t.Errorf("parseWrapper(%q) = (%q, %q), want (%q, %q)", tc.input, manager, fileID, tc.manager, tc.fileID)
+		}
+	}
+}

integrations/feishu/bot.go

@@ -0,0 +1,41 @@
+package feishu
+
+import (
+	lark "github.com/larksuite/oapi-sdk-go/v3"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+)
+
+// Bot represents a single Feishu bot instance bound to an app.
+type Bot struct {
+	appID     string
+	appSecret string
+	client    *lark.Client
+}
+
+// NewBot creates a Bot bound to the given Feishu app credentials.
+func NewBot(appID, appSecret string) *Bot {
+	client := lark.NewClient(appID, appSecret,
+		lark.WithLogLevel(larkcore.LogLevelWarn),
+	)
+	return &Bot{
+		appID:     appID,
+		appSecret: appSecret,
+		client:    client,
+	}
+}
+
+// AppID returns the app ID.
+func (b *Bot) AppID() string { return b.appID }
+
+// AppSecret returns the app secret (needed for WS client).
+func (b *Bot) AppSecret() string { return b.appSecret }
+
+// Client returns the underlying Lark SDK client.
+func (b *Bot) Client() *lark.Client { return b.client }
+
+func derefStr(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}

integrations/feishu/bot_test.go

@@ -0,0 +1,18 @@
+package feishu
+
+import (
+	"testing"
+)
+
+func TestNewBot(t *testing.T) {
+	b := NewBot("cli_xxx", "secret_yyy")
+	if b.AppID() != "cli_xxx" {
+		t.Fatalf("expected AppID cli_xxx, got %s", b.AppID())
+	}
+	if b.AppSecret() != "secret_yyy" {
+		t.Fatalf("expected AppSecret secret_yyy, got %s", b.AppSecret())
+	}
+	if b.Client() == nil {
+		t.Fatal("Client() should not be nil")
+	}
+}

integrations/feishu/convert.go

@@ -0,0 +1,154 @@
+package feishu
+
+import (
+	"encoding/json"
+)
+
+// ConvertedMessage is the unified output after parsing a Feishu event message.
+type ConvertedMessage struct {
+	MessageID    string      `json:"message_id"`
+	ChatID       string      `json:"chat_id"`
+	ChatType     string      `json:"chat_type"` // p2p, group
+	SenderID     string      `json:"sender_id"`
+	SenderName   string      `json:"sender_name,omitempty"`
+	Text         string      `json:"text,omitempty"`
+	MediaItems   []MediaItem `json:"media,omitempty"`
+	MentionBot   bool        `json:"mention_bot,omitempty"`
+	EventID      string      `json:"event_id,omitempty"`
+	LanguageCode string      `json:"language_code,omitempty"`
+}
+
+// MediaItem describes a single media attachment from the message.
+type MediaItem struct {
+	Type     MediaType `json:"type"`
+	Key      string    `json:"key"`
+	MimeType string    `json:"mime_type,omitempty"`
+	FileName string    `json:"file_name,omitempty"`
+	FileSize int64     `json:"file_size,omitempty"`
+	Wrapper  string    `json:"wrapper,omitempty"`
+}
+
+// MediaType indicates the attachment type.
+type MediaType string
+
+const (
+	MediaImage MediaType = "image"
+	MediaFile  MediaType = "file"
+	MediaAudio MediaType = "audio"
+	MediaVideo MediaType = "video"
+	MediaMedia MediaType = "media"
+)
+
+// HasMedia returns true if the message contains any media.
+func (cm *ConvertedMessage) HasMedia() bool { return len(cm.MediaItems) > 0 }
+
+// HasText returns true if the message contains text.
+func (cm *ConvertedMessage) HasText() bool { return cm.Text != "" }
+
+// feishuTextContent is the JSON structure of a text-type message body.
+type feishuTextContent struct {
+	Text string `json:"text"`
+}
+
+// feishuImageContent is the JSON structure of an image-type message body.
+type feishuImageContent struct {
+	ImageKey string `json:"image_key"`
+}
+
+// feishuFileContent is the JSON structure of a file-type message body.
+type feishuFileContent struct {
+	FileKey  string `json:"file_key"`
+	FileName string `json:"file_name"`
+}
+
+// feishuAudioContent is the JSON structure of an audio-type message body.
+type feishuAudioContent struct {
+	FileKey  string `json:"file_key"`
+	Duration int    `json:"duration"`
+}
+
+// feishuMediaContent is the JSON structure of a media-type message body.
+type feishuMediaContent struct {
+	FileKey  string `json:"file_key"`
+	FileName string `json:"file_name"`
+	ImageKey string `json:"image_key"`
+}
+
+// ParseMessageContent parses a Feishu message body (JSON string) based on its type.
+func ParseMessageContent(msgType, content string) (text string, media []MediaItem) {
+	switch msgType {
+	case "text":
+		var tc feishuTextContent
+		if err := json.Unmarshal([]byte(content), &tc); err == nil {
+			text = tc.Text
+		}
+	case "image":
+		var ic feishuImageContent
+		if err := json.Unmarshal([]byte(content), &ic); err == nil && ic.ImageKey != "" {
+			media = append(media, MediaItem{Type: MediaImage, Key: ic.ImageKey, MimeType: "image/jpeg"})
+		}
+	case "file":
+		var fc feishuFileContent
+		if err := json.Unmarshal([]byte(content), &fc); err == nil && fc.FileKey != "" {
+			media = append(media, MediaItem{Type: MediaFile, Key: fc.FileKey, FileName: fc.FileName})
+		}
+	case "audio":
+		var ac feishuAudioContent
+		if err := json.Unmarshal([]byte(content), &ac); err == nil && ac.FileKey != "" {
+			media = append(media, MediaItem{Type: MediaAudio, Key: ac.FileKey, MimeType: "audio/ogg"})
+		}
+	case "media":
+		var mc feishuMediaContent
+		if err := json.Unmarshal([]byte(content), &mc); err == nil && mc.FileKey != "" {
+			media = append(media, MediaItem{Type: MediaVideo, Key: mc.FileKey, FileName: mc.FileName})
+		}
+	case "post":
+		var post map[string]interface{}
+		if err := json.Unmarshal([]byte(content), &post); err == nil {
+			text = extractPostText(post)
+		}
+	}
+	return
+}
+
+// extractPostText extracts plain text from a rich-text (post) message.
+func extractPostText(post map[string]interface{}) string {
+	for _, langContent := range post {
+		lc, ok := langContent.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		contentArr, ok := lc["content"].([]interface{})
+		if !ok {
+			continue
+		}
+		var result string
+		for _, para := range contentArr {
+			paraArr, ok := para.([]interface{})
+			if !ok {
+				continue
+			}
+			for _, elem := range paraArr {
+				elemMap, ok := elem.(map[string]interface{})
+				if !ok {
+					continue
+				}
+				tag, _ := elemMap["tag"].(string)
+				if tag == "text" {
+					if t, ok := elemMap["text"].(string); ok {
+						result += t
+					}
+				} else if tag == "a" {
+					if t, ok := elemMap["text"].(string); ok {
+						result += t
+					}
+				}
+			}
+			result += "\n"
+		}
+		if result != "" {
+			return result
+		}
+	}
+	return ""
+}

integrations/feishu/convert_test.go

@@ -0,0 +1,126 @@
+package feishu
+
+import (
+	"testing"
+)
+
+func TestParseMessageContent_Text(t *testing.T) {
+	text, media := ParseMessageContent("text", `{"text":"Hello World"}`)
+	if text != "Hello World" {
+		t.Errorf("expected 'Hello World', got %q", text)
+	}
+	if len(media) != 0 {
+		t.Errorf("expected 0 media, got %d", len(media))
+	}
+}
+
+func TestParseMessageContent_Image(t *testing.T) {
+	text, media := ParseMessageContent("image", `{"image_key":"img_abc123"}`)
+	if text != "" {
+		t.Errorf("expected empty text, got %q", text)
+	}
+	if len(media) != 1 {
+		t.Fatalf("expected 1 media, got %d", len(media))
+	}
+	if media[0].Type != MediaImage {
+		t.Errorf("expected type %s, got %s", MediaImage, media[0].Type)
+	}
+	if media[0].Key != "img_abc123" {
+		t.Errorf("expected key img_abc123, got %s", media[0].Key)
+	}
+}
+
+func TestParseMessageContent_File(t *testing.T) {
+	text, media := ParseMessageContent("file", `{"file_key":"file_xyz","file_name":"report.pdf"}`)
+	if text != "" {
+		t.Errorf("expected empty text, got %q", text)
+	}
+	if len(media) != 1 {
+		t.Fatalf("expected 1 media, got %d", len(media))
+	}
+	if media[0].Type != MediaFile {
+		t.Errorf("expected type %s, got %s", MediaFile, media[0].Type)
+	}
+	if media[0].FileName != "report.pdf" {
+		t.Errorf("expected filename report.pdf, got %s", media[0].FileName)
+	}
+}
+
+func TestParseMessageContent_Audio(t *testing.T) {
+	text, media := ParseMessageContent("audio", `{"file_key":"audio_key","duration":30}`)
+	if text != "" {
+		t.Errorf("expected empty text, got %q", text)
+	}
+	if len(media) != 1 {
+		t.Fatalf("expected 1 media, got %d", len(media))
+	}
+	if media[0].Type != MediaAudio {
+		t.Errorf("expected type %s, got %s", MediaAudio, media[0].Type)
+	}
+}
+
+func TestParseMessageContent_Media(t *testing.T) {
+	text, media := ParseMessageContent("media", `{"file_key":"media_key","file_name":"video.mp4","image_key":"cover"}`)
+	if text != "" {
+		t.Errorf("expected empty text, got %q", text)
+	}
+	if len(media) != 1 {
+		t.Fatalf("expected 1 media, got %d", len(media))
+	}
+	if media[0].Type != MediaVideo {
+		t.Errorf("expected type %s, got %s", MediaVideo, media[0].Type)
+	}
+}
+
+func TestParseMessageContent_Post(t *testing.T) {
+	content := `{"zh_cn":{"title":"Test","content":[[{"tag":"text","text":"Hello "},{"tag":"a","text":"World","href":"https://example.com"}]]}}`
+	text, media := ParseMessageContent("post", content)
+	if text == "" {
+		t.Error("expected non-empty text from post message")
+	}
+	if len(media) != 0 {
+		t.Errorf("expected 0 media from text-only post, got %d", len(media))
+	}
+}
+
+func TestParseMessageContent_InvalidJSON(t *testing.T) {
+	text, media := ParseMessageContent("text", "not json")
+	if text != "" {
+		t.Errorf("expected empty text for invalid JSON, got %q", text)
+	}
+	if len(media) != 0 {
+		t.Errorf("expected 0 media for invalid JSON, got %d", len(media))
+	}
+}
+
+func TestParseMessageContent_UnknownType(t *testing.T) {
+	text, media := ParseMessageContent("unknown", `{"text":"Hello"}`)
+	if text != "" {
+		t.Errorf("expected empty text for unknown type, got %q", text)
+	}
+	if len(media) != 0 {
+		t.Errorf("expected 0 media for unknown type, got %d", len(media))
+	}
+}
+
+func TestConvertedMessage_HasMedia(t *testing.T) {
+	cm := &ConvertedMessage{}
+	if cm.HasMedia() {
+		t.Error("empty message should not have media")
+	}
+	cm.MediaItems = append(cm.MediaItems, MediaItem{Type: MediaImage, Key: "test"})
+	if !cm.HasMedia() {
+		t.Error("message with media should report HasMedia=true")
+	}
+}
+
+func TestConvertedMessage_HasText(t *testing.T) {
+	cm := &ConvertedMessage{}
+	if cm.HasText() {
+		t.Error("empty message should not have text")
+	}
+	cm.Text = "hello"
+	if !cm.HasText() {
+		t.Error("message with text should report HasText=true")
+	}
+}

integrations/feishu/e2e_test.go

@@ -0,0 +1,70 @@
+package feishu
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// TestE2E_01_BotCredentials verifies the Feishu app credentials by
+// sending a simple text message send request (if a chat_id is available).
+func TestE2E_01_BotCredentials(t *testing.T) {
+	skipIfNoCreds(t)
+	b := testBot()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	// Verify credentials by attempting to send a message.
+	// This will fail with a descriptive error if credentials are invalid.
+	_, err := b.sendMessage(ctx, "open_id", "test_invalid_open_id", "text", `{"text":"e2e test"}`)
+	if err == nil {
+		t.Log("message send succeeded (unexpected, but credentials are valid)")
+		return
+	}
+
+	// We expect a Feishu API error (not a network error), which proves
+	// the credentials were accepted and the API was reached.
+	t.Logf("API response (expected error for invalid open_id): %v", err)
+}
+
+// TestE2E_02_SendMessage tests sending a real message if FEISHU_TEST_CHAT_ID is set.
+func TestE2E_02_SendMessage(t *testing.T) {
+	skipIfNoCreds(t)
+
+	chatID := getChatID(t)
+	if chatID == "" {
+		t.Skip("no chat_id available for send test")
+	}
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	msgID, err := b.SendTextMessage(ctx, chatID, "E2E test from Yao integration at "+time.Now().Format(time.RFC3339))
+	if err != nil {
+		t.Fatalf("SendTextMessage: %v", err)
+	}
+	t.Logf("OK  sent message_id=%s to chat=%s", msgID, chatID)
+}
+
+// TestE2E_03_SendImage tests sending an image message.
+func TestE2E_03_SendImage(t *testing.T) {
+	skipIfNoCreds(t)
+
+	chatID := getChatID(t)
+	if chatID == "" {
+		t.Skip("no chat_id available for image send test")
+	}
+
+	// Would need an uploaded image_key. Skip if not available.
+	t.Skip("image_key upload not implemented yet in test suite")
+}
+
+// getChatID attempts to retrieve a test chat ID from environment or skip.
+func getChatID(t *testing.T) string {
+	t.Helper()
+	// For now we don't have a chat_id mechanism like Telegram's getUpdates.
+	// A chat_id can be obtained by having the bot in a group or by user messaging the bot first.
+	return ""
+}

integrations/feishu/feishu_test.go

@@ -0,0 +1,28 @@
+package feishu
+
+import (
+	"os"
+	"testing"
+)
+
+var (
+	testAppID     string
+	testAppSecret string
+)
+
+func TestMain(m *testing.M) {
+	testAppID = os.Getenv("FEISHU_TEST_APP_ID")
+	testAppSecret = os.Getenv("FEISHU_TEST_APP_SECRET")
+	os.Exit(m.Run())
+}
+
+func skipIfNoCreds(t *testing.T) {
+	t.Helper()
+	if testAppID == "" || testAppSecret == "" {
+		t.Skip("FEISHU_TEST_APP_ID or FEISHU_TEST_APP_SECRET not set")
+	}
+}
+
+func testBot() *Bot {
+	return NewBot(testAppID, testAppSecret)
+}

integrations/feishu/file.go

@@ -0,0 +1,169 @@
+package feishu
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/textproto"
+	"strings"
+
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
+	"github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/attachment"
+)
+
+const defaultUploader = "__yao.attachment"
+
+// FileResult holds the attachment wrapper and metadata for a stored file.
+type FileResult struct {
+	Wrapper  string
+	MimeType string
+	FileName string
+}
+
+// DownloadAndStoreImage downloads a Feishu image by image_key and stores it
+// through the attachment manager. Uses image_key as the fingerprint for dedup.
+func (b *Bot) DownloadAndStoreImage(ctx context.Context, messageID, imageKey string, groups []string) (*FileResult, error) {
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		return nil, fmt.Errorf("attachment manager %s not found", defaultUploader)
+	}
+
+	probeID := fingerprintKey(imageKey, groups)
+	if manager.Exists(ctx, probeID) {
+		wrapper := fmt.Sprintf("%s://%s", defaultUploader, probeID)
+		return &FileResult{Wrapper: wrapper, MimeType: "image/jpeg", FileName: imageKey + ".jpg"}, nil
+	}
+
+	req := larkim.NewGetMessageResourceReqBuilder().
+		MessageId(messageID).
+		FileKey(imageKey).
+		Type("image").
+		Build()
+
+	resp, err := b.client.Im.MessageResource.Get(ctx, req)
+	if err != nil {
+		return nil, fmt.Errorf("feishu get image resource: %w", err)
+	}
+	if !resp.Success() {
+		return nil, fmt.Errorf("feishu get image resource: code=%d", resp.Code)
+	}
+
+	data, err := io.ReadAll(resp.File)
+	if err != nil {
+		return nil, fmt.Errorf("read image body: %w", err)
+	}
+
+	return storeData(ctx, manager, imageKey, "image/jpeg", imageKey+".jpg", data, groups)
+}
+
+// DownloadAndStoreFile downloads a Feishu file by file_key and stores it.
+func (b *Bot) DownloadAndStoreFile(ctx context.Context, messageID, fileKey, mimeType, fileName string, groups []string) (*FileResult, error) {
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		return nil, fmt.Errorf("attachment manager %s not found", defaultUploader)
+	}
+
+	probeID := fingerprintKey(fileKey, groups)
+	if manager.Exists(ctx, probeID) {
+		wrapper := fmt.Sprintf("%s://%s", defaultUploader, probeID)
+		return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: fileName}, nil
+	}
+
+	req := larkim.NewGetMessageResourceReqBuilder().
+		MessageId(messageID).
+		FileKey(fileKey).
+		Type("file").
+		Build()
+
+	resp, err := b.client.Im.MessageResource.Get(ctx, req)
+	if err != nil {
+		return nil, fmt.Errorf("feishu get file resource: %w", err)
+	}
+	if !resp.Success() {
+		return nil, fmt.Errorf("feishu get file resource: code=%d", resp.Code)
+	}
+
+	data, err := io.ReadAll(resp.File)
+	if err != nil {
+		return nil, fmt.Errorf("read file body: %w", err)
+	}
+
+	if mimeType == "" {
+		mimeType = "application/octet-stream"
+	}
+	if fileName == "" {
+		fileName = resp.FileName
+		if fileName == "" {
+			fileName = fileKey
+		}
+	}
+
+	return storeData(ctx, manager, fileKey, mimeType, fileName, data, groups)
+}
+
+// ResolveMedia downloads and stores all media items in a ConvertedMessage.
+func (b *Bot) ResolveMedia(ctx context.Context, cm *ConvertedMessage, groups []string) {
+	if cm == nil {
+		return
+	}
+	for i := range cm.MediaItems {
+		mi := &cm.MediaItems[i]
+		var result *FileResult
+		var err error
+
+		switch mi.Type {
+		case MediaImage:
+			result, err = b.DownloadAndStoreImage(ctx, cm.MessageID, mi.Key, groups)
+		default:
+			result, err = b.DownloadAndStoreFile(ctx, cm.MessageID, mi.Key, mi.MimeType, mi.FileName, groups)
+		}
+
+		if err != nil {
+			log.Error("feishu ResolveMedia: %s %s: %v", mi.Type, mi.Key, err)
+			continue
+		}
+		mi.Wrapper = result.Wrapper
+		if result.MimeType != "" {
+			mi.MimeType = result.MimeType
+		}
+	}
+}
+
+func storeData(ctx context.Context, manager *attachment.Manager, fingerprint, mimeType, fileName string, data []byte, groups []string) (*FileResult, error) {
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: fileName,
+			Size:     int64(len(data)),
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", mimeType)
+	header.Header.Set("Content-Fingerprint", fingerprint)
+
+	option := attachment.UploadOption{
+		OriginalFilename: fileName,
+		Groups:           groups,
+	}
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), option)
+	if err != nil {
+		return nil, fmt.Errorf("attachment upload: %w", err)
+	}
+
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: fileName}, nil
+}
+
+func fingerprintKey(key string, groups []string) string {
+	parts := make([]string, 0, len(groups)+1)
+	parts = append(parts, groups...)
+	parts = append(parts, key)
+	storagePath := strings.Join(parts, "/")
+	hash := md5.Sum([]byte(storagePath))
+	return hex.EncodeToString(hash[:])
+}

integrations/feishu/format.go

@@ -0,0 +1,193 @@
+package feishu
+
+import (
+	"regexp"
+	"strings"
+)
+
+// FormatFeishuMarkdown converts standard Markdown to Feishu's lark_md subset.
+//
+// Feishu lark_md (in card div elements) supports:
+//   - **bold**, *italic*, ~~strikethrough~~
+//   - `inline code`
+//   - [link](url)
+//   - ---  (divider)
+//
+// NOT supported (must be converted/degraded):
+//   - # headings        → **bold text**
+//   - ``` code blocks   → plain text indented
+//   - > blockquotes     → text with "│ " prefix
+//   - tables            → pre-formatted text
+//   - - list items      → "• " prefixed text
+//   - 1. ordered list   → "N. " prefixed text
+//   - ![](url) images   → [image](url) link
+func FormatFeishuMarkdown(md string) string {
+	md = strings.ReplaceAll(md, "\r\n", "\n")
+
+	var out strings.Builder
+	lines := strings.Split(md, "\n")
+
+	inCodeBlock := false
+	var codeLines []string
+
+	inTable := false
+	var tableRows [][]string
+
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+
+		if strings.HasPrefix(line, "```") {
+			if !inCodeBlock {
+				inCodeBlock = true
+				codeLines = nil
+			} else {
+				inCodeBlock = false
+				for _, cl := range codeLines {
+					out.WriteString("    " + cl + "\n")
+				}
+			}
+			continue
+		}
+		if inCodeBlock {
+			codeLines = append(codeLines, line)
+			continue
+		}
+
+		if fmtIsTableRow(line) {
+			if !inTable {
+				inTable = true
+				tableRows = nil
+			}
+			if fmtIsTableSep(line) {
+				continue
+			}
+			tableRows = append(tableRows, fmtParseTableRow(line))
+			continue
+		}
+		if inTable {
+			fmtFlushTable(&out, tableRows)
+			inTable = false
+			tableRows = nil
+		}
+
+		if line == "---" || line == "***" || line == "___" {
+			out.WriteString("---\n")
+			continue
+		}
+
+		if m := fmtReHeading.FindStringSubmatch(line); m != nil {
+			out.WriteString("**" + m[2] + "**\n")
+			continue
+		}
+
+		if m := fmtReBlockquote.FindStringSubmatch(line); m != nil {
+			out.WriteString("│ " + m[1] + "\n")
+			continue
+		}
+
+		if m := fmtReUnorderedList.FindStringSubmatch(line); m != nil {
+			out.WriteString("• " + m[1] + "\n")
+			continue
+		}
+
+		if m := fmtReOrderedList.FindStringSubmatch(line); m != nil {
+			out.WriteString(m[1] + ". " + m[2] + "\n")
+			continue
+		}
+
+		if m := fmtReImage.FindStringSubmatch(line); m != nil {
+			out.WriteString("[" + m[1] + "](" + m[2] + ")\n")
+			continue
+		}
+
+		out.WriteString(line + "\n")
+	}
+
+	if inCodeBlock && len(codeLines) > 0 {
+		for _, cl := range codeLines {
+			out.WriteString("    " + cl + "\n")
+		}
+	}
+	if inTable {
+		fmtFlushTable(&out, tableRows)
+	}
+
+	return strings.TrimRight(out.String(), "\n")
+}
+
+var (
+	fmtReHeading       = regexp.MustCompile(`^(#{1,6})\s+(.+)$`)
+	fmtReBlockquote    = regexp.MustCompile(`^>\s*(.*)$`)
+	fmtReUnorderedList = regexp.MustCompile(`^[\s]*[-*+]\s+(.+)$`)
+	fmtReOrderedList   = regexp.MustCompile(`^[\s]*(\d+)[.)]\s+(.+)$`)
+	fmtReImage         = regexp.MustCompile(`^!\[([^\]]*)\]\(([^)]+)\)$`)
+	fmtReTableRow      = regexp.MustCompile(`^\|.*\|$`)
+	fmtReTableSep      = regexp.MustCompile(`^\|[\s\-:|]+\|$`)
+)
+
+func fmtIsTableRow(line string) bool {
+	return fmtReTableRow.MatchString(strings.TrimSpace(line))
+}
+
+func fmtIsTableSep(line string) bool {
+	return fmtReTableSep.MatchString(strings.TrimSpace(line))
+}
+
+func fmtParseTableRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	cells := strings.Split(line, "|")
+	for i := range cells {
+		cells[i] = strings.TrimSpace(cells[i])
+	}
+	return cells
+}
+
+func fmtFlushTable(out *strings.Builder, rows [][]string) {
+	if len(rows) == 0 {
+		return
+	}
+	colWidths := make([]int, len(rows[0]))
+	for _, row := range rows {
+		for i, cell := range row {
+			if i < len(colWidths) && len([]rune(cell)) > colWidths[i] {
+				colWidths[i] = len([]rune(cell))
+			}
+		}
+	}
+	for ri, row := range rows {
+		for ci, cell := range row {
+			if ci > 0 {
+				out.WriteString(" | ")
+			}
+			w := 0
+			if ci < len(colWidths) {
+				w = colWidths[ci]
+			}
+			out.WriteString(fmtPadRight(cell, w))
+		}
+		out.WriteString("\n")
+		if ri == 0 && len(rows) > 1 {
+			for ci := range row {
+				if ci > 0 {
+					out.WriteString("-+-")
+				}
+				w := 0
+				if ci < len(colWidths) {
+					w = colWidths[ci]
+				}
+				out.WriteString(strings.Repeat("-", w))
+			}
+			out.WriteString("\n")
+		}
+	}
+}
+
+func fmtPadRight(s string, width int) string {
+	runes := []rune(s)
+	if len(runes) >= width {
+		return s
+	}
+	return s + strings.Repeat(" ", width-len(runes))
+}

integrations/feishu/message.go

@@ -0,0 +1,277 @@
+package feishu
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"path/filepath"
+	"strings"
+
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
+	"github.com/yaoapp/yao/attachment"
+)
+
+// SendTextMessage sends a text message to a chat.
+func (b *Bot) SendTextMessage(ctx context.Context, chatID, text string) (string, error) {
+	content, _ := json.Marshal(map[string]string{"text": text})
+	return b.sendMessage(ctx, "chat_id", chatID, "text", string(content))
+}
+
+// SendTextToUser sends a text message to a user by open_id.
+func (b *Bot) SendTextToUser(ctx context.Context, openID, text string) (string, error) {
+	content, _ := json.Marshal(map[string]string{"text": text})
+	return b.sendMessage(ctx, "open_id", openID, "text", string(content))
+}
+
+// SendCardMessage sends a Markdown-rendered interactive card message to a chat.
+// Feishu's text type doesn't render Markdown; the interactive card type does.
+func (b *Bot) SendCardMessage(ctx context.Context, chatID, markdown string) (string, error) {
+	card := buildMarkdownCard(markdown)
+	content, _ := json.Marshal(card)
+	return b.sendMessage(ctx, "chat_id", chatID, "interactive", string(content))
+}
+
+// ReplyCardMessage replies with a Markdown-rendered interactive card.
+func (b *Bot) ReplyCardMessage(ctx context.Context, messageID, markdown string) (string, error) {
+	card := buildMarkdownCard(markdown)
+	content, _ := json.Marshal(card)
+	return b.replyMessage(ctx, messageID, "interactive", string(content))
+}
+
+// buildMarkdownCard constructs a Feishu interactive card with lark_md content.
+// Uses the non-template card structure: config + elements (div with lark_md).
+func buildMarkdownCard(markdown string) map[string]interface{} {
+	return map[string]interface{}{
+		"config": map[string]interface{}{
+			"wide_screen_mode": true,
+		},
+		"elements": []interface{}{
+			map[string]interface{}{
+				"tag": "div",
+				"text": map[string]interface{}{
+					"tag":     "lark_md",
+					"content": markdown,
+				},
+			},
+		},
+	}
+}
+
+// SendImageMessage sends an image by image_key to a chat.
+func (b *Bot) SendImageMessage(ctx context.Context, chatID, imageKey string) (string, error) {
+	content, _ := json.Marshal(map[string]string{"image_key": imageKey})
+	return b.sendMessage(ctx, "chat_id", chatID, "image", string(content))
+}
+
+// SendFileMessage sends a file by file_key to a chat.
+func (b *Bot) SendFileMessage(ctx context.Context, chatID, fileKey string) (string, error) {
+	content, _ := json.Marshal(map[string]string{"file_key": fileKey})
+	return b.sendMessage(ctx, "chat_id", chatID, "file", string(content))
+}
+
+// ReplyTextMessage replies to a message with text.
+func (b *Bot) ReplyTextMessage(ctx context.Context, messageID, text string) (string, error) {
+	content, _ := json.Marshal(map[string]string{"text": text})
+	return b.replyMessage(ctx, messageID, "text", string(content))
+}
+
+func (b *Bot) sendMessage(ctx context.Context, receiveIDType, receiveID, msgType, content string) (string, error) {
+	req := larkim.NewCreateMessageReqBuilder().
+		ReceiveIdType(receiveIDType).
+		Body(larkim.NewCreateMessageReqBodyBuilder().
+			ReceiveId(receiveID).
+			MsgType(msgType).
+			Content(content).
+			Build()).
+		Build()
+
+	resp, err := b.client.Im.Message.Create(ctx, req)
+	if err != nil {
+		return "", fmt.Errorf("feishu send message: %w", err)
+	}
+	if !resp.Success() {
+		return "", fmt.Errorf("feishu send message: code=%d msg=%s", resp.Code, resp.Msg)
+	}
+	if resp.Data != nil && resp.Data.MessageId != nil {
+		return *resp.Data.MessageId, nil
+	}
+	return "", nil
+}
+
+// UploadImage uploads an image to Feishu and returns the image_key.
+func (b *Bot) UploadImage(ctx context.Context, filename string, reader io.Reader) (string, error) {
+	req := larkim.NewCreateImageReqBuilder().
+		Body(larkim.NewCreateImageReqBodyBuilder().
+			ImageType("message").
+			Image(reader).
+			Build()).
+		Build()
+
+	resp, err := b.client.Im.Image.Create(ctx, req)
+	if err != nil {
+		return "", fmt.Errorf("feishu upload image: %w", err)
+	}
+	if !resp.Success() {
+		return "", fmt.Errorf("feishu upload image: code=%d msg=%s", resp.Code, resp.Msg)
+	}
+	if resp.Data == nil || resp.Data.ImageKey == nil {
+		return "", fmt.Errorf("feishu upload image: empty image_key in response")
+	}
+	return *resp.Data.ImageKey, nil
+}
+
+// UploadFile uploads a file to Feishu and returns the file_key.
+// fileType must be one of: opus, mp4, pdf, doc, xls, ppt, stream.
+func (b *Bot) UploadFile(ctx context.Context, filename, fileType string, reader io.Reader) (string, error) {
+	req := larkim.NewCreateFileReqBuilder().
+		Body(larkim.NewCreateFileReqBodyBuilder().
+			FileType(fileType).
+			FileName(filename).
+			File(reader).
+			Build()).
+		Build()
+
+	resp, err := b.client.Im.File.Create(ctx, req)
+	if err != nil {
+		return "", fmt.Errorf("feishu upload file: %w", err)
+	}
+	if !resp.Success() {
+		return "", fmt.Errorf("feishu upload file: code=%d msg=%s", resp.Code, resp.Msg)
+	}
+	if resp.Data == nil || resp.Data.FileKey == nil {
+		return "", fmt.Errorf("feishu upload file: empty file_key in response")
+	}
+	return *resp.Data.FileKey, nil
+}
+
+// SendImageFromWrapper sends an image from a Yao attachment wrapper (e.g. "__yao.attachment://xxx").
+func (b *Bot) SendImageFromWrapper(ctx context.Context, chatID, wrapper, caption string) error {
+	managerName, fileID, ok := attachment.Parse(wrapper)
+	if !ok {
+		return fmt.Errorf("invalid attachment wrapper: %s", wrapper)
+	}
+
+	manager, exists := attachment.Managers[managerName]
+	if !exists {
+		return fmt.Errorf("attachment manager %s not found", managerName)
+	}
+
+	resp, err := manager.Download(ctx, fileID)
+	if err != nil {
+		return fmt.Errorf("attachment download %s: %w", fileID, err)
+	}
+	defer resp.Reader.Close()
+
+	filename := fileID + resp.Extension
+	imageKey, err := b.UploadImage(ctx, filename, resp.Reader)
+	if err != nil {
+		return err
+	}
+
+	if caption != "" {
+		if _, err := b.SendTextMessage(ctx, chatID, caption); err != nil {
+			return err
+		}
+	}
+	_, err = b.SendImageMessage(ctx, chatID, imageKey)
+	return err
+}
+
+// SendFileFromWrapper sends a file from a Yao attachment wrapper (e.g. "__yao.attachment://xxx").
+func (b *Bot) SendFileFromWrapper(ctx context.Context, chatID, wrapper, caption string) error {
+	managerName, fileID, ok := attachment.Parse(wrapper)
+	if !ok {
+		return fmt.Errorf("invalid attachment wrapper: %s", wrapper)
+	}
+
+	manager, exists := attachment.Managers[managerName]
+	if !exists {
+		return fmt.Errorf("attachment manager %s not found", managerName)
+	}
+
+	resp, err := manager.Download(ctx, fileID)
+	if err != nil {
+		return fmt.Errorf("attachment download %s: %w", fileID, err)
+	}
+	defer resp.Reader.Close()
+
+	filename := fileID + resp.Extension
+	fileType := detectFeishuFileType(resp.ContentType, resp.Extension)
+
+	fileKey, err := b.UploadFile(ctx, filename, fileType, resp.Reader)
+	if err != nil {
+		return err
+	}
+
+	if caption != "" {
+		if _, err := b.SendTextMessage(ctx, chatID, caption); err != nil {
+			return err
+		}
+	}
+	_, err = b.SendFileMessage(ctx, chatID, fileKey)
+	return err
+}
+
+// detectFeishuFileType maps a MIME type / extension to a Feishu file type.
+func detectFeishuFileType(contentType, ext string) string {
+	lower := strings.ToLower(contentType)
+	switch {
+	case strings.Contains(lower, "audio/ogg"), strings.Contains(lower, "audio/opus"):
+		return "opus"
+	case strings.HasPrefix(lower, "video/"):
+		return "mp4"
+	case strings.Contains(lower, "pdf"):
+		return "pdf"
+	case strings.Contains(lower, "msword"),
+		strings.Contains(lower, "wordprocessingml"),
+		strings.Contains(lower, "opendocument.text"):
+		return "doc"
+	case strings.Contains(lower, "ms-excel"),
+		strings.Contains(lower, "spreadsheetml"),
+		strings.Contains(lower, "opendocument.spreadsheet"):
+		return "xls"
+	case strings.Contains(lower, "ms-powerpoint"),
+		strings.Contains(lower, "presentationml"),
+		strings.Contains(lower, "opendocument.presentation"):
+		return "ppt"
+	}
+
+	switch strings.ToLower(filepath.Ext(ext)) {
+	case ".pdf":
+		return "pdf"
+	case ".doc", ".docx":
+		return "doc"
+	case ".xls", ".xlsx":
+		return "xls"
+	case ".ppt", ".pptx":
+		return "ppt"
+	case ".mp4", ".mov", ".avi":
+		return "mp4"
+	case ".opus", ".ogg":
+		return "opus"
+	}
+	return "stream"
+}
+
+func (b *Bot) replyMessage(ctx context.Context, messageID, msgType, content string) (string, error) {
+	req := larkim.NewReplyMessageReqBuilder().
+		MessageId(messageID).
+		Body(larkim.NewReplyMessageReqBodyBuilder().
+			MsgType(msgType).
+			Content(content).
+			Build()).
+		Build()
+
+	resp, err := b.client.Im.Message.Reply(ctx, req)
+	if err != nil {
+		return "", fmt.Errorf("feishu reply message: %w", err)
+	}
+	if !resp.Success() {
+		return "", fmt.Errorf("feishu reply message: code=%d msg=%s", resp.Code, resp.Msg)
+	}
+	if resp.Data != nil && resp.Data.MessageId != nil {
+		return *resp.Data.MessageId, nil
+	}
+	return "", nil
+}

integrations/telegram/bot.go

@@ -0,0 +1,83 @@
+package telegram
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-telegram/bot"
+)
+
+const defaultAPIBase = "https://api.telegram.org"
+
+// Bot represents a single Telegram bot instance bound to a specific token.
+// Each registered robot gets its own Bot. All API methods live on Bot so
+// callers never need to pass the token around.
+type Bot struct {
+	token       string
+	secretToken string // for webhook X-Telegram-Bot-Api-Secret-Token verification
+	apiBase     string // e.g. "https://api.telegram.org" or "http://localhost:3001"
+	httpClient  *http.Client
+}
+
+// BotOption configures optional Bot parameters.
+type BotOption func(*Bot)
+
+// WithAPIBase sets a custom Bot API server URL (e.g. a local telegram-bot-api instance).
+func WithAPIBase(url string) BotOption {
+	return func(b *Bot) {
+		b.apiBase = strings.TrimRight(url, "/")
+	}
+}
+
+// NewBot creates a Bot bound to the given token.
+// secretToken is optional — when set it is sent with SetWebhook and used by
+// VerifyWebhook to authenticate incoming requests.
+func NewBot(token string, secretToken string, opts ...BotOption) *Bot {
+	b := &Bot{
+		token:       token,
+		secretToken: secretToken,
+		apiBase:     defaultAPIBase,
+		httpClient:  &http.Client{Timeout: 90 * time.Second},
+	}
+	for _, o := range opts {
+		o(b)
+	}
+	return b
+}
+
+// Token returns the raw bot token.
+func (b *Bot) Token() string { return b.token }
+
+// SecretToken returns the webhook secret (may be empty).
+func (b *Bot) SecretToken() string { return b.secretToken }
+
+// APIBase returns the API server base URL.
+func (b *Bot) APIBase() string { return b.apiBase }
+
+// botURL builds the bot-method base URL: {apiBase}/bot{token}
+func (b *Bot) botURL() string {
+	return b.apiBase + "/bot" + b.token
+}
+
+// fileURL builds the file download URL: {apiBase}/file/bot{token}/{path}
+func (b *Bot) fileURL(filePath string) string {
+	return b.apiBase + "/file/bot" + b.token + "/" + filePath
+}
+
+// sdk returns a go-telegram/bot.Bot instance for typed method calls.
+func (b *Bot) sdk() (*bot.Bot, error) {
+	opts := []bot.Option{
+		bot.WithSkipGetMe(),
+		bot.WithHTTPClient(90*time.Second, b.httpClient),
+	}
+	if b.apiBase != defaultAPIBase {
+		opts = append(opts, bot.WithServerURL(b.apiBase))
+	}
+	sdkBot, err := bot.New(b.token, opts...)
+	if err != nil {
+		return nil, fmt.Errorf("create bot sdk: %w", err)
+	}
+	return sdkBot, nil
+}

integrations/telegram/bot_test.go

@@ -0,0 +1,22 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestNewBot(t *testing.T) {
+	b := NewBot("123:ABC", "my-secret")
+	if b.Token() != "123:ABC" {
+		t.Fatalf("expected token 123:ABC, got %s", b.Token())
+	}
+	if b.SecretToken() != "my-secret" {
+		t.Fatalf("expected secret my-secret, got %s", b.SecretToken())
+	}
+}
+
+func TestNewBot_EmptySecret(t *testing.T) {
+	b := NewBot("123:ABC", "")
+	if b.SecretToken() != "" {
+		t.Fatalf("expected empty secret, got %s", b.SecretToken())
+	}
+}

integrations/telegram/convert.go

@@ -0,0 +1,298 @@
+package telegram
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/go-telegram/bot/models"
+)
+
+// ConvertedMessage is the unified output of ConvertUpdate, usable by any
+// consumer regardless of whether the Update came from GetUpdates or a webhook.
+type ConvertedMessage struct {
+	UpdateID     int64          `json:"update_id"`
+	MessageID    int64          `json:"message_id"`
+	ChatID       int64          `json:"chat_id"`
+	ChatType     string         `json:"chat_type"`
+	SenderID     int64          `json:"sender_id,omitempty"`
+	SenderName   string         `json:"sender_name,omitempty"`
+	LanguageCode string         `json:"language_code,omitempty"`
+	Date         int            `json:"date"`
+	Text         string         `json:"text,omitempty"`
+	MediaItems   []MediaItem    `json:"media,omitempty"`
+	ReplyTo      *ReplyInfo     `json:"reply_to,omitempty"`
+	Raw          *models.Update `json:"-"`
+}
+
+// MediaItem describes a single media attachment extracted from the message.
+type MediaItem struct {
+	Type         MediaType `json:"type"`
+	FileID       string    `json:"file_id"`
+	FileUniqueID string    `json:"file_unique_id"`
+	MimeType     string    `json:"mime_type"`
+	FileName     string    `json:"file_name,omitempty"`
+	FileSize     int64     `json:"file_size,omitempty"`
+	Wrapper      string    `json:"wrapper,omitempty"` // __yao.attachment://xxx after ResolveMedia
+}
+
+// ReplyInfo holds info about the message being replied to.
+type ReplyInfo struct {
+	MessageID int64 `json:"message_id"`
+	ChatID    int64 `json:"chat_id,omitempty"`
+}
+
+// ConvertUpdate transforms a raw Telegram Update into a ConvertedMessage.
+// Returns nil if the update contains no processable message.
+func ConvertUpdate(u *models.Update) *ConvertedMessage {
+	msg := u.Message
+	if msg == nil {
+		return nil
+	}
+
+	cm := &ConvertedMessage{
+		UpdateID:  int64(u.ID),
+		MessageID: int64(msg.ID),
+		ChatID:    msg.Chat.ID,
+		ChatType:  string(msg.Chat.Type),
+		Date:      msg.Date,
+		Raw:       u,
+	}
+
+	if msg.From != nil {
+		cm.SenderID = msg.From.ID
+		cm.SenderName = buildSenderName(msg.From)
+		cm.LanguageCode = msg.From.LanguageCode
+	}
+
+	if msg.Text != "" {
+		cm.Text = ApplyEntities(msg.Text, msg.Entities)
+	} else if msg.Caption != "" {
+		cm.Text = ApplyEntities(msg.Caption, msg.CaptionEntities)
+	}
+
+	cm.MediaItems = extractMedia(msg)
+
+	if msg.ReplyToMessage != nil {
+		cm.ReplyTo = &ReplyInfo{
+			MessageID: int64(msg.ReplyToMessage.ID),
+			ChatID:    msg.ReplyToMessage.Chat.ID,
+		}
+	}
+
+	return cm
+}
+
+// HasMedia returns true if the message contains any media attachments.
+func (cm *ConvertedMessage) HasMedia() bool {
+	return len(cm.MediaItems) > 0
+}
+
+// HasText returns true if the message contains text content.
+func (cm *ConvertedMessage) HasText() bool {
+	return cm.Text != ""
+}
+
+func buildSenderName(u *models.User) string {
+	name := u.FirstName
+	if u.LastName != "" {
+		name += " " + u.LastName
+	}
+	return name
+}
+
+func extractMedia(msg *models.Message) []MediaItem {
+	var items []MediaItem
+
+	if len(msg.Photo) > 0 {
+		best := pickBestPhoto(msg.Photo)
+		items = append(items, MediaItem{
+			Type:         MediaPhoto,
+			FileID:       best.FileID,
+			FileUniqueID: best.FileUniqueID,
+			MimeType:     "image/jpeg",
+			FileName:     "photo.jpg",
+			FileSize:     int64(best.FileSize),
+		})
+	}
+
+	if msg.Document != nil {
+		d := msg.Document
+		mime := d.MimeType
+		if mime == "" {
+			mime = "application/octet-stream"
+		}
+		name := d.FileName
+		if name == "" {
+			name = "document"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaDocument,
+			FileID:       d.FileID,
+			FileUniqueID: d.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(d.FileSize),
+		})
+	}
+
+	if msg.Audio != nil {
+		a := msg.Audio
+		mime := a.MimeType
+		if mime == "" {
+			mime = "audio/mpeg"
+		}
+		name := a.FileName
+		if name == "" {
+			name = "audio.mp3"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaAudio,
+			FileID:       a.FileID,
+			FileUniqueID: a.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(a.FileSize),
+		})
+	}
+
+	if msg.Voice != nil {
+		v := msg.Voice
+		mime := v.MimeType
+		if mime == "" {
+			mime = "audio/ogg"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaVoice,
+			FileID:       v.FileID,
+			FileUniqueID: v.FileUniqueID,
+			MimeType:     mime,
+			FileName:     "voice.ogg",
+			FileSize:     int64(v.FileSize),
+		})
+	}
+
+	if msg.Video != nil {
+		v := msg.Video
+		mime := v.MimeType
+		if mime == "" {
+			mime = "video/mp4"
+		}
+		name := v.FileName
+		if name == "" {
+			name = "video.mp4"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaVideo,
+			FileID:       v.FileID,
+			FileUniqueID: v.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(v.FileSize),
+		})
+	}
+
+	if msg.Animation != nil {
+		a := msg.Animation
+		mime := a.MimeType
+		if mime == "" {
+			mime = "video/mp4"
+		}
+		name := a.FileName
+		if name == "" {
+			name = "animation.mp4"
+		}
+		items = append(items, MediaItem{
+			Type:         MediaAnimation,
+			FileID:       a.FileID,
+			FileUniqueID: a.FileUniqueID,
+			MimeType:     mime,
+			FileName:     name,
+			FileSize:     int64(a.FileSize),
+		})
+	}
+
+	if msg.Sticker != nil {
+		s := msg.Sticker
+		items = append(items, MediaItem{
+			Type:         MediaSticker,
+			FileID:       s.FileID,
+			FileUniqueID: s.FileUniqueID,
+			MimeType:     "image/webp",
+			FileName:     "sticker.webp",
+			FileSize:     int64(s.FileSize),
+		})
+	}
+
+	return items
+}
+
+func pickBestPhoto(photos []models.PhotoSize) models.PhotoSize {
+	if len(photos) == 0 {
+		return models.PhotoSize{}
+	}
+	sorted := make([]models.PhotoSize, len(photos))
+	copy(sorted, photos)
+	sort.Slice(sorted, func(i, j int) bool {
+		return sorted[i].Width*sorted[i].Height > sorted[j].Width*sorted[j].Height
+	})
+	return sorted[0]
+}
+
+// ApplyEntities converts Telegram MessageEntity formatting to Markdown.
+func ApplyEntities(text string, entities []models.MessageEntity) string {
+	if len(entities) == 0 {
+		return text
+	}
+
+	runes := []rune(text)
+
+	sorted := make([]models.MessageEntity, len(entities))
+	copy(sorted, entities)
+	sort.Slice(sorted, func(i, j int) bool {
+		return sorted[i].Offset > sorted[j].Offset
+	})
+
+	for _, e := range sorted {
+		start := e.Offset
+		end := e.Offset + e.Length
+		if start < 0 || end > len(runes) {
+			continue
+		}
+		segment := string(runes[start:end])
+
+		var replacement string
+		switch e.Type {
+		case "bold":
+			replacement = "**" + segment + "**"
+		case "italic":
+			replacement = "_" + segment + "_"
+		case "underline":
+			replacement = "__" + segment + "__"
+		case "strikethrough":
+			replacement = "~~" + segment + "~~"
+		case "code":
+			replacement = "`" + segment + "`"
+		case "pre":
+			lang := ""
+			if e.Language != "" {
+				lang = e.Language
+			}
+			replacement = "```" + lang + "\n" + segment + "\n```"
+		case "text_link":
+			replacement = "[" + segment + "](" + e.URL + ")"
+		case "text_mention":
+			if e.User != nil {
+				replacement = "[" + segment + "](tg://user?id=" + strconv.FormatInt(e.User.ID, 10) + ")"
+			} else {
+				replacement = segment
+			}
+		default:
+			continue
+		}
+
+		runes = append(runes[:start], append([]rune(replacement), runes[end:]...)...)
+	}
+
+	return strings.TrimSpace(string(runes))
+}

integrations/telegram/e2e_test.go

@@ -0,0 +1,416 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"image"
+	"image/color"
+	"image/png"
+	"io"
+	"mime/multipart"
+	"net/textproto"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/yaoapp/yao/attachment"
+)
+
+// TestE2E_00_Seed must run first (go test runs in lexical order).
+// It sends a text + photo to the bot via MTProto so later tests have data.
+func TestE2E_00_Seed(t *testing.T) {
+	skipIfNoToken(t)
+	seedBotMessages(t)
+}
+
+func TestE2E_01_GetMe(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	user, err := b.GetMe(ctx)
+	if err != nil {
+		t.Fatalf("GetMe failed: %v", err)
+	}
+
+	if user.ID == 0 {
+		t.Error("user.ID should not be 0")
+	}
+	if !user.IsBot {
+		t.Error("user.IsBot should be true")
+	}
+	if user.FirstName == "" {
+		t.Error("user.FirstName should not be empty")
+	}
+	if user.Username == "" {
+		t.Error("user.Username should not be empty")
+	}
+
+	expected := os.Getenv("TG_TEST_BOT_USERNAME")
+	if expected != "" && user.Username != expected {
+		t.Errorf("username mismatch: got %q, want %q", user.Username, expected)
+	}
+
+	if !user.CanJoinGroups {
+		t.Log("warning: bot cannot join groups (CanJoinGroups=false)")
+	}
+	t.Logf("OK  id=%d username=%s first_name=%s can_read_all=%v",
+		user.ID, user.Username, user.FirstName, user.CanReadAllGroupMessages)
+}
+
+func TestE2E_02_GetUpdates(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	updates, err := b.GetRawUpdates(ctx, 0, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=0): %v", err)
+	}
+	if len(updates) == 0 {
+		t.Fatal("expected at least 1 update after seed, got 0")
+	}
+
+	var prevID int64
+	for i, u := range updates {
+		if u.ID == 0 {
+			t.Errorf("updates[%d].ID should not be 0", i)
+		}
+		if u.ID < 0 {
+			t.Errorf("updates[%d].ID=%d is negative", i, u.ID)
+		}
+		if i > 0 && int64(u.ID) <= prevID {
+			t.Errorf("update_id not increasing: updates[%d].ID=%d <= prev=%d", i, u.ID, prevID)
+		}
+		prevID = int64(u.ID)
+
+		if u.Message != nil {
+			msg := u.Message
+			if msg.ID == 0 {
+				t.Errorf("updates[%d].Message.ID should not be 0", i)
+			}
+			if msg.Date == 0 {
+				t.Errorf("updates[%d].Message.Date should not be 0", i)
+			}
+			if msg.Chat.ID == 0 {
+				t.Errorf("updates[%d].Message.Chat.ID should not be 0", i)
+			}
+			if msg.Chat.Type == "" {
+				t.Errorf("updates[%d].Message.Chat.Type should not be empty", i)
+			}
+			if msg.From != nil && msg.From.ID == 0 {
+				t.Errorf("updates[%d].Message.From.ID should not be 0", i)
+			}
+
+			t.Logf("  update[%d] id=%d msg_id=%d chat=%d from=%d text=%q has_photo=%v has_doc=%v",
+				i, u.ID, msg.ID, msg.Chat.ID, safeUserID(msg.From), truncate(msg.Text, 40),
+				len(msg.Photo) > 0, msg.Document != nil)
+		}
+	}
+
+	firstID := int64(updates[0].ID)
+	lastID := int64(updates[len(updates)-1].ID)
+
+	// offset = first_id: non-destructive, returns from first_id onwards
+	updates2, err := b.GetRawUpdates(ctx, firstID, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=first_id=%d): %v", firstID, err)
+	}
+	if len(updates2) == 0 {
+		t.Error("offset=first_id returned 0 updates, expected >= 1")
+	}
+	if len(updates2) > 0 && int64(updates2[0].ID) != firstID {
+		t.Errorf("offset=first_id: first returned update_id=%d, want %d", updates2[0].ID, firstID)
+	}
+	for _, u2 := range updates2 {
+		if int64(u2.ID) < firstID {
+			t.Errorf("offset=first_id: got update_id=%d < offset=%d", u2.ID, firstID)
+		}
+	}
+
+	t.Logf("OK  total=%d first_id=%d last_id=%d monotonic=true offset_filter=ok",
+		len(updates), firstID, lastID)
+}
+
+func TestE2E_03_GetFile_Download(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+
+	var fileID string
+	for i := 0; i < 3 && fileID == ""; i++ {
+		if i > 0 {
+			time.Sleep(time.Second)
+		}
+		fileID = findFileID(t, b, ctx)
+	}
+	if fileID == "" {
+		t.Fatal("expected a photo/file from seed, got none")
+	}
+
+	fileMeta, err := b.GetFile(ctx, fileID)
+	if err != nil {
+		t.Fatalf("GetFile failed: %v", err)
+	}
+	if fileMeta.FileID == "" {
+		t.Error("fileMeta.FileID should not be empty")
+	}
+	if fileMeta.FileID != fileID {
+		t.Errorf("fileMeta.FileID=%q should match requested %q", fileMeta.FileID, fileID)
+	}
+	if fileMeta.FilePath == "" {
+		t.Fatal("fileMeta.FilePath should not be empty")
+	}
+	if fileMeta.FileSize <= 0 {
+		t.Error("fileMeta.FileSize should be > 0")
+	}
+
+	body, contentType, size, err := b.DownloadFile(ctx, fileMeta.FilePath)
+	if err != nil {
+		t.Fatalf("DownloadFile failed: %v", err)
+	}
+	defer body.Close()
+
+	data, err := io.ReadAll(body)
+	if err != nil {
+		t.Fatalf("read body: %v", err)
+	}
+	if len(data) == 0 {
+		t.Fatal("downloaded file has 0 bytes")
+	}
+	if contentType == "" {
+		t.Error("content-type should not be empty")
+	}
+
+	t.Logf("OK  file_id=%s path=%s api_size=%d content_type=%s downloaded=%d",
+		fileMeta.FileID, fileMeta.FilePath, size, contentType, len(data))
+}
+
+func TestE2E_04_DownloadAndStore(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	photoFileID, photoUniqueID := findPhotoIDs(t, b, ctx)
+	if photoFileID == "" {
+		t.Fatal("expected a photo from seed, got none")
+	}
+
+	groups := []string{"telegram", "e2e-test"}
+
+	result, err := b.DownloadAndStore(ctx, photoFileID, photoUniqueID, "image/jpeg", "test_photo.jpg", groups)
+	if err != nil {
+		t.Fatalf("DownloadAndStore failed: %v", err)
+	}
+	if result.Wrapper == "" {
+		t.Fatal("wrapper should not be empty")
+	}
+	if !strings.HasPrefix(result.Wrapper, defaultUploader+"://") {
+		t.Errorf("wrapper should start with %s://, got %s", defaultUploader, result.Wrapper)
+	}
+	if result.MimeType == "" {
+		t.Error("mime_type should not be empty")
+	}
+	if result.FileName == "" {
+		t.Error("file_name should not be empty")
+	}
+
+	manager := attachment.Managers[defaultUploader]
+	_, fileID, _ := attachment.Parse(result.Wrapper)
+	resp, err := manager.Download(ctx, fileID)
+	if err != nil {
+		t.Fatalf("attachment.Download failed: %v", err)
+	}
+	defer resp.Reader.Close()
+	stored, err := io.ReadAll(resp.Reader)
+	if err != nil {
+		t.Fatalf("read stored: %v", err)
+	}
+	if len(stored) == 0 {
+		t.Fatal("stored file has 0 bytes")
+	}
+	t.Logf("OK  wrapper=%s stored_bytes=%d content_type=%s", result.Wrapper, len(stored), resp.ContentType)
+
+	result2, err := b.DownloadAndStore(ctx, photoFileID, photoUniqueID, "image/jpeg", "test_photo.jpg", groups)
+	if err != nil {
+		t.Fatalf("DownloadAndStore (dedup) failed: %v", err)
+	}
+	if result2.Wrapper != result.Wrapper {
+		t.Errorf("dedup failed: first=%s second=%s", result.Wrapper, result2.Wrapper)
+	}
+	t.Log("OK  dedup verified")
+}
+
+func TestE2E_05_SendMessage(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("expected chat_id from seed, got 0")
+	}
+
+	err := b.SendMessage(ctx, chatID, fmt.Sprintf("*E2E test* at `%s`", time.Now().Format(time.RFC3339)), 0)
+	if err != nil {
+		t.Fatalf("SendMessage failed: %v", err)
+	}
+	t.Logf("OK  sent text message to chat=%d", chatID)
+}
+
+func TestE2E_06_SendMedia_Wrapper(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("expected chat_id from seed, got 0")
+	}
+
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		t.Fatal("attachment manager not found")
+	}
+
+	imgData := generateTestPNG()
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: "e2e_test.png",
+			Size:     int64(len(imgData)),
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", "image/png")
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(imgData), attachment.UploadOption{
+		OriginalFilename: "e2e_test.png",
+		Groups:           []string{"telegram", "e2e-test"},
+	})
+	if err != nil {
+		t.Fatalf("attachment upload failed: %v", err)
+	}
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	if uploaded.Bytes <= 0 {
+		t.Error("uploaded.Bytes should be > 0")
+	}
+	t.Logf("uploaded wrapper=%s bytes=%d", wrapper, uploaded.Bytes)
+
+	err = b.SendMedia(ctx, chatID, wrapper, "E2E attachment test", 0)
+	if err != nil {
+		t.Fatalf("SendMedia(wrapper) failed: %v", err)
+	}
+	t.Logf("OK  sent media via wrapper to chat=%d", chatID)
+}
+
+func TestE2E_07_SendMediaByReader(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("expected chat_id from seed, got 0")
+	}
+
+	imgData := generateTestPNG()
+	err := b.SendMediaByReader(ctx, chatID, MediaPhoto, "e2e_test.png", bytes.NewReader(imgData), "E2E reader test", 0)
+	if err != nil {
+		t.Fatalf("SendMediaByReader failed: %v", err)
+	}
+	t.Logf("OK  sent photo via reader to chat=%d", chatID)
+}
+
+// --------------- helpers ---------------
+
+func fetchUpdates(t *testing.T, b *Bot, ctx context.Context) []*ConvertedMessage {
+	t.Helper()
+	updates, err := b.GetUpdates(ctx, 0, 5, nil)
+	if err != nil {
+		t.Fatalf("GetUpdates: %v", err)
+	}
+	return updates
+}
+
+func findChatID(t *testing.T, b *Bot, ctx context.Context) int64 {
+	t.Helper()
+	for _, cm := range fetchUpdates(t, b, ctx) {
+		if cm != nil && cm.ChatID != 0 {
+			return cm.ChatID
+		}
+	}
+	return 0
+}
+
+func findFileID(t *testing.T, b *Bot, ctx context.Context) string {
+	t.Helper()
+	for _, cm := range fetchUpdates(t, b, ctx) {
+		if cm == nil {
+			continue
+		}
+		for _, m := range cm.MediaItems {
+			if m.Type == MediaPhoto || m.Type == MediaDocument {
+				return m.FileID
+			}
+		}
+	}
+	return ""
+}
+
+func findPhotoIDs(t *testing.T, b *Bot, ctx context.Context) (fileID, uniqueID string) {
+	t.Helper()
+	for _, cm := range fetchUpdates(t, b, ctx) {
+		if cm == nil {
+			continue
+		}
+		for _, m := range cm.MediaItems {
+			if m.Type == MediaPhoto {
+				return m.FileID, m.FileUniqueID
+			}
+		}
+	}
+	return "", ""
+}
+
+func safeUserID(u *User) int64 {
+	if u == nil {
+		return 0
+	}
+	return u.ID
+}
+
+func truncate(s string, max int) string {
+	if len(s) <= max {
+		return s
+	}
+	return s[:max] + "..."
+}
+
+// generateTestPNG produces a 100x100 red PNG that Telegram will accept.
+func generateTestPNG() []byte {
+	img := image.NewRGBA(image.Rect(0, 0, 100, 100))
+	red := color.RGBA{R: 255, A: 255}
+	for y := 0; y < 100; y++ {
+		for x := 0; x < 100; x++ {
+			img.Set(x, y, red)
+		}
+	}
+	var buf bytes.Buffer
+	_ = png.Encode(&buf, img)
+	return buf.Bytes()
+}

integrations/telegram/file.go

@@ -0,0 +1,206 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/textproto"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/go-telegram/bot/models"
+	"github.com/yaoapp/kun/log"
+	"github.com/yaoapp/yao/attachment"
+)
+
+const defaultUploader = "__yao.attachment"
+
+// FileResult holds the attachment wrapper and metadata for a downloaded
+// Telegram file that has been stored via the attachment manager.
+type FileResult struct {
+	Wrapper  string // e.g. __yao.attachment://ccd472d11feb96e03a3fc468f494045c
+	MimeType string
+	FileName string
+}
+
+// GetFile retrieves file metadata (including download path) for a given file_id.
+// Uses raw HTTP for compatibility with both official and local Bot API servers.
+func (b *Bot) GetFile(ctx context.Context, fileID string) (*models.File, error) {
+	body, err := json.Marshal(map[string]string{"file_id": fileID})
+	if err != nil {
+		return nil, fmt.Errorf("marshal: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", b.botURL()+"/getFile", bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	var result struct {
+		OK     bool        `json:"ok"`
+		Result models.File `json:"result"`
+	}
+	if err := json.Unmarshal(respBody, &result); err != nil {
+		return nil, fmt.Errorf("unmarshal: %w", err)
+	}
+	if !result.OK {
+		return nil, fmt.Errorf("getFile: API returned ok=false, body=%s", string(respBody))
+	}
+	return &result.Result, nil
+}
+
+// DownloadFile downloads a file given its file_path from GetFile.
+// Returns the response body (caller must close), content type, and file size.
+// When file_path is an absolute path (local Bot API server --local mode),
+// the file is read directly from disk instead of HTTP download.
+func (b *Bot) DownloadFile(ctx context.Context, filePath string) (io.ReadCloser, string, int64, error) {
+	if strings.HasPrefix(filePath, "/") {
+		f, err := os.Open(filePath)
+		if err != nil {
+			return nil, "", 0, fmt.Errorf("open local file: %w", err)
+		}
+		info, _ := f.Stat()
+		var size int64
+		if info != nil {
+			size = info.Size()
+		}
+		return f, "application/octet-stream", size, nil
+	}
+
+	url := b.fileURL(filePath)
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return nil, "", 0, err
+	}
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, "", 0, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		resp.Body.Close()
+		return nil, "", 0, fmt.Errorf("download file: status %d", resp.StatusCode)
+	}
+	return resp.Body, resp.Header.Get("Content-Type"), resp.ContentLength, nil
+}
+
+// DownloadAndStore downloads a Telegram file by file_id, stores it through the
+// attachment manager, and returns the wrapper string. Uses file_unique_id as
+// the Content-Fingerprint so that the same Telegram file is never downloaded
+// and stored twice — attachment's built-in fingerprint dedup handles it.
+func (b *Bot) DownloadAndStore(ctx context.Context, tgFileID, fileUniqueID, mimeType, filename string, groups []string) (*FileResult, error) {
+
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		return nil, fmt.Errorf("attachment manager %s not found", defaultUploader)
+	}
+
+	probeID := fingerprintFileID(fileUniqueID, groups)
+	if manager.Exists(ctx, probeID) {
+		wrapper := fmt.Sprintf("%s://%s", defaultUploader, probeID)
+		log.Trace("telegram file: cache hit file_unique_id=%s wrapper=%s", fileUniqueID, wrapper)
+		return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: filename}, nil
+	}
+
+	fileMeta, err := b.GetFile(ctx, tgFileID)
+	if err != nil {
+		return nil, fmt.Errorf("getFile: %w", err)
+	}
+
+	body, contentType, size, err := b.DownloadFile(ctx, fileMeta.FilePath)
+	if err != nil {
+		return nil, fmt.Errorf("download: %w", err)
+	}
+	defer body.Close()
+
+	if contentType != "" && mimeType == "application/octet-stream" {
+		mimeType = contentType
+	}
+
+	data, err := io.ReadAll(body)
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+	if size <= 0 {
+		size = int64(len(data))
+	}
+
+	ext := filepath.Ext(filename)
+
+	header := &attachment.FileHeader{
+		FileHeader: &multipart.FileHeader{
+			Filename: filename,
+			Size:     size,
+			Header:   make(textproto.MIMEHeader),
+		},
+	}
+	header.Header.Set("Content-Type", mimeType)
+	header.Header.Set("Content-Fingerprint", fileUniqueID)
+	if ext != "" {
+		header.Header.Set("Content-Extension", ext)
+	}
+
+	option := attachment.UploadOption{
+		OriginalFilename: filename,
+		Groups:           groups,
+	}
+
+	uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), option)
+	if err != nil {
+		return nil, fmt.Errorf("attachment upload: %w", err)
+	}
+
+	wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+	return &FileResult{Wrapper: wrapper, MimeType: mimeType, FileName: filename}, nil
+}
+
+// ResolveMedia downloads and stores all media items in the ConvertedMessage,
+// filling each MediaItem.Wrapper with the attachment wrapper string.
+// Items that fail to download are logged and left with an empty Wrapper.
+func (b *Bot) ResolveMedia(ctx context.Context, cm *ConvertedMessage, groups []string) {
+	if cm == nil {
+		return
+	}
+	for i := range cm.MediaItems {
+		mi := &cm.MediaItems[i]
+		result, err := b.DownloadAndStore(ctx, mi.FileID, mi.FileUniqueID, mi.MimeType, mi.FileName, groups)
+		if err != nil {
+			log.Error("telegram ResolveMedia: %s %s: %v", mi.Type, mi.FileID, err)
+			continue
+		}
+		mi.Wrapper = result.Wrapper
+		if result.MimeType != "" {
+			mi.MimeType = result.MimeType
+		}
+	}
+}
+
+// fingerprintFileID reproduces the file_id that attachment.Manager would
+// generate when Content-Fingerprint is set, so we can probe Exists() before
+// downloading anything.
+func fingerprintFileID(fileUniqueID string, groups []string) string {
+	parts := make([]string, 0, len(groups)+1)
+	parts = append(parts, groups...)
+	parts = append(parts, fileUniqueID)
+	storagePath := strings.Join(parts, "/")
+	hash := md5.Sum([]byte(storagePath))
+	return hex.EncodeToString(hash[:])
+}

integrations/telegram/file_test.go

@@ -0,0 +1,35 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestFingerprintFileID(t *testing.T) {
+	id1 := fingerprintFileID("unique1", []string{"telegram", "bot123"})
+	id2 := fingerprintFileID("unique1", []string{"telegram", "bot123"})
+	if id1 != id2 {
+		t.Fatalf("same input should produce same fingerprint, got %s vs %s", id1, id2)
+	}
+
+	id3 := fingerprintFileID("unique2", []string{"telegram", "bot123"})
+	if id1 == id3 {
+		t.Fatalf("different file_unique_id should produce different fingerprint")
+	}
+
+	id4 := fingerprintFileID("unique1", []string{"telegram", "bot456"})
+	if id1 == id4 {
+		t.Fatalf("different groups should produce different fingerprint")
+	}
+
+	id5 := fingerprintFileID("unique1", nil)
+	if id5 == "" {
+		t.Fatal("nil groups should still produce a valid fingerprint")
+	}
+	if id5 == id1 {
+		t.Fatal("nil groups vs non-nil groups should differ")
+	}
+
+	if len(id1) != 32 {
+		t.Fatalf("fingerprint should be 32 hex chars (md5), got length %d", len(id1))
+	}
+}

integrations/telegram/format.go

@@ -0,0 +1,219 @@
+package telegram
+
+import (
+	"html"
+	"regexp"
+	"strings"
+)
+
+// FormatTelegramHTML converts standard Markdown to the HTML subset supported by
+// Telegram's Bot API. Unsupported constructs (tables, images, etc.) are
+// gracefully degraded to plain text.
+//
+// Supported Telegram HTML tags: <b>, <i>, <u>, <s>, <code>, <pre>, <a>, <blockquote>
+func FormatTelegramHTML(md string) string {
+	md = strings.ReplaceAll(md, "\r\n", "\n")
+
+	var out strings.Builder
+	lines := strings.Split(md, "\n")
+
+	inCodeBlock := false
+	var codeLang string
+	var codeLines []string
+
+	inTable := false
+	var tableRows [][]string
+
+	for i := 0; i < len(lines); i++ {
+		line := lines[i]
+
+		if strings.HasPrefix(line, "```") {
+			if !inCodeBlock {
+				inCodeBlock = true
+				codeLang = strings.TrimSpace(strings.TrimPrefix(line, "```"))
+				codeLines = nil
+			} else {
+				inCodeBlock = false
+				if codeLang != "" {
+					out.WriteString("<pre><code class=\"language-" + html.EscapeString(codeLang) + "\">")
+				} else {
+					out.WriteString("<pre>")
+				}
+				out.WriteString(html.EscapeString(strings.Join(codeLines, "\n")))
+				if codeLang != "" {
+					out.WriteString("</code></pre>\n")
+				} else {
+					out.WriteString("</pre>\n")
+				}
+			}
+			continue
+		}
+		if inCodeBlock {
+			codeLines = append(codeLines, line)
+			continue
+		}
+
+		if isTableRow(line) {
+			if !inTable {
+				inTable = true
+				tableRows = nil
+			}
+			if isTableSeparator(line) {
+				continue
+			}
+			tableRows = append(tableRows, parseTableRow(line))
+			continue
+		}
+		if inTable {
+			flushTable(&out, tableRows)
+			inTable = false
+			tableRows = nil
+		}
+
+		if line == "---" || line == "***" || line == "___" {
+			out.WriteString("——————\n")
+			continue
+		}
+
+		if m := reHeading.FindStringSubmatch(line); m != nil {
+			out.WriteString("<b>" + formatInline(html.EscapeString(m[2])) + "</b>\n")
+			continue
+		}
+
+		if m := reBlockquote.FindStringSubmatch(line); m != nil {
+			out.WriteString("<blockquote>" + formatInline(html.EscapeString(m[1])) + "</blockquote>\n")
+			continue
+		}
+
+		if m := reUnorderedList.FindStringSubmatch(line); m != nil {
+			out.WriteString("• " + formatInline(html.EscapeString(m[1])) + "\n")
+			continue
+		}
+
+		if m := reOrderedList.FindStringSubmatch(line); m != nil {
+			out.WriteString(m[1] + ". " + formatInline(html.EscapeString(m[2])) + "\n")
+			continue
+		}
+
+		out.WriteString(formatInline(html.EscapeString(line)) + "\n")
+	}
+
+	if inCodeBlock && len(codeLines) > 0 {
+		out.WriteString("<pre>" + html.EscapeString(strings.Join(codeLines, "\n")) + "</pre>\n")
+	}
+	if inTable {
+		flushTable(&out, tableRows)
+	}
+
+	return strings.TrimRight(out.String(), "\n")
+}
+
+var (
+	reHeading       = regexp.MustCompile(`^(#{1,6})\s+(.+)$`)
+	reBlockquote    = regexp.MustCompile(`^>\s*(.*)$`)
+	reUnorderedList = regexp.MustCompile(`^[\s]*[-*+]\s+(.+)$`)
+	reOrderedList   = regexp.MustCompile(`^[\s]*(\d+)[.)]\s+(.+)$`)
+
+	reBold          = regexp.MustCompile(`\*\*(.+?)\*\*`)
+	reBoldAlt       = regexp.MustCompile(`__(.+?)__`)
+	reItalic        = regexp.MustCompile(`(?:^|[^*])\*([^*]+?)\*(?:[^*]|$)`)
+	reItalicAlt     = regexp.MustCompile(`(?:^|[^_])_([^_]+?)_(?:[^_]|$)`)
+	reStrikethrough = regexp.MustCompile(`~~(.+?)~~`)
+	reCode          = regexp.MustCompile("`([^`]+)`")
+	reLink          = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`)
+
+	reTableRow = regexp.MustCompile(`^\|.*\|$`)
+	reTableSep = regexp.MustCompile(`^\|[\s\-:|]+\|$`)
+)
+
+// formatInline applies inline Markdown formatting to already HTML-escaped text.
+// Order matters: code first (to protect its content), then links, bold, italic, etc.
+func formatInline(escaped string) string {
+	escaped = reCode.ReplaceAllString(escaped, "<code>$1</code>")
+
+	escaped = reLink.ReplaceAllStringFunc(escaped, func(match string) string {
+		m := reLink.FindStringSubmatch(match)
+		if len(m) < 3 {
+			return match
+		}
+		return `<a href="` + unescapeHTML(m[2]) + `">` + m[1] + `</a>`
+	})
+
+	escaped = reBold.ReplaceAllString(escaped, "<b>$1</b>")
+	escaped = reBoldAlt.ReplaceAllString(escaped, "<b>$1</b>")
+	escaped = reStrikethrough.ReplaceAllString(escaped, "<s>$1</s>")
+
+	return escaped
+}
+
+func unescapeHTML(s string) string {
+	return html.UnescapeString(s)
+}
+
+func isTableRow(line string) bool {
+	return reTableRow.MatchString(strings.TrimSpace(line))
+}
+
+func isTableSeparator(line string) bool {
+	return reTableSep.MatchString(strings.TrimSpace(line))
+}
+
+func parseTableRow(line string) []string {
+	line = strings.TrimSpace(line)
+	line = strings.TrimPrefix(line, "|")
+	line = strings.TrimSuffix(line, "|")
+	cells := strings.Split(line, "|")
+	for i := range cells {
+		cells[i] = strings.TrimSpace(cells[i])
+	}
+	return cells
+}
+
+func flushTable(out *strings.Builder, rows [][]string) {
+	if len(rows) == 0 {
+		return
+	}
+	out.WriteString("<pre>")
+	colWidths := make([]int, len(rows[0]))
+	for _, row := range rows {
+		for i, cell := range row {
+			if i < len(colWidths) && len(cell) > colWidths[i] {
+				colWidths[i] = len(cell)
+			}
+		}
+	}
+	for ri, row := range rows {
+		for ci, cell := range row {
+			if ci > 0 {
+				out.WriteString(" | ")
+			}
+			w := 0
+			if ci < len(colWidths) {
+				w = colWidths[ci]
+			}
+			out.WriteString(html.EscapeString(padRight(cell, w)))
+		}
+		out.WriteString("\n")
+		if ri == 0 && len(rows) > 1 {
+			for ci := range row {
+				if ci > 0 {
+					out.WriteString("-+-")
+				}
+				w := 0
+				if ci < len(colWidths) {
+					w = colWidths[ci]
+				}
+				out.WriteString(strings.Repeat("-", w))
+			}
+			out.WriteString("\n")
+		}
+	}
+	out.WriteString("</pre>\n")
+}
+
+func padRight(s string, width int) string {
+	if len(s) >= width {
+		return s
+	}
+	return s + strings.Repeat(" ", width-len(s))
+}

integrations/telegram/media_e2e_test.go

@@ -0,0 +1,299 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/textproto"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/yaoapp/yao/attachment"
+)
+
+type mediaTestCase struct {
+	name      string
+	file      string // relative to testdata/
+	mimeType  string
+	mediaType MediaType
+}
+
+var mediaTestCases = []mediaTestCase{
+	{"jpg", "test.jpg", "image/jpeg", MediaPhoto},
+	{"png", "test.png", "image/png", MediaPhoto},
+	{"gif", "test.gif", "image/gif", MediaAnimation},
+	{"webp", "test.webp", "image/webp", MediaSticker},
+	{"mp3", "test.mp3", "audio/mpeg", MediaAudio},
+	{"ogg", "test.ogg", "audio/ogg", MediaVoice},
+	{"mp4", "test.mp4", "video/mp4", MediaVideo},
+	{"pdf", "test.pdf", "application/pdf", MediaDocument},
+	{"docx", "test.docx", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", MediaDocument},
+	{"pptx", "test.pptx", "application/vnd.openxmlformats-officedocument.presentationml.presentation", MediaDocument},
+}
+
+func readTestFile(t *testing.T, name string) []byte {
+	t.Helper()
+	data, err := os.ReadFile("../testdata/" + name)
+	if err != nil {
+		t.Fatalf("read ../testdata/%s: %v", name, err)
+	}
+	if len(data) == 0 {
+		t.Fatalf("../testdata/%s is empty", name)
+	}
+	return data
+}
+
+func TestE2E_08_SendMediaByReader_MultiType(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("no chat_id")
+	}
+
+	for _, tc := range mediaTestCases {
+		t.Run(tc.name, func(t *testing.T) {
+			data := readTestFile(t, tc.file)
+
+			detected := DetectMediaType(tc.mimeType)
+			if detected != tc.mediaType {
+				t.Errorf("DetectMediaType(%q) = %q, want %q", tc.mimeType, detected, tc.mediaType)
+			}
+
+			err := b.SendMediaByReader(ctx, chatID, tc.mediaType, tc.file, bytes.NewReader(data), fmt.Sprintf("E2E %s %d bytes", tc.name, len(data)), 0)
+			if err != nil {
+				t.Fatalf("SendMediaByReader(%s) failed: %v", tc.name, err)
+			}
+			t.Logf("OK  %s %s %d bytes -> chat=%d", tc.name, tc.mimeType, len(data), chatID)
+		})
+	}
+}
+
+func TestE2E_09_SendMedia_Wrapper_MultiType(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
+	defer cancel()
+
+	chatID := findChatID(t, b, ctx)
+	if chatID == 0 {
+		t.Fatal("no chat_id")
+	}
+
+	manager, exists := attachment.Managers[defaultUploader]
+	if !exists {
+		t.Fatal("attachment manager not found")
+	}
+
+	for _, tc := range mediaTestCases {
+		t.Run(tc.name, func(t *testing.T) {
+			data := readTestFile(t, tc.file)
+
+			header := &attachment.FileHeader{
+				FileHeader: &multipart.FileHeader{
+					Filename: tc.file,
+					Size:     int64(len(data)),
+					Header:   make(textproto.MIMEHeader),
+				},
+			}
+			header.Header.Set("Content-Type", tc.mimeType)
+
+			uploaded, err := manager.Upload(ctx, header, bytes.NewReader(data), attachment.UploadOption{
+				OriginalFilename: tc.file,
+				Groups:           []string{"telegram", "e2e-media"},
+			})
+			if err != nil {
+				t.Fatalf("upload %s: %v", tc.name, err)
+			}
+
+			wrapper := fmt.Sprintf("%s://%s", defaultUploader, uploaded.ID)
+
+			err = b.SendMedia(ctx, chatID, wrapper, fmt.Sprintf("E2E wrapper %s", tc.name), 0)
+			if err != nil {
+				t.Fatalf("SendMedia(%s) failed: %v", tc.name, err)
+			}
+			t.Logf("OK  %s -> %s -> chat=%d", tc.name, wrapper, chatID)
+		})
+	}
+}
+
+// TestE2E_10_Receive_DownloadAndStore_Dedup pulls updates from the bot,
+// finds media messages (seeded by TestE2E_00_Seed), and for each one:
+//  1. DownloadAndStore -> verify wrapper format + stored bytes > 0
+//  2. Read back from attachment manager -> verify content non-empty
+//  3. Call DownloadAndStore again -> verify same wrapper (fingerprint dedup)
+func TestE2E_10_Receive_DownloadAndStore_Dedup(t *testing.T) {
+	skipIfNoToken(t)
+	prepare(t)
+	defer cleanup()
+
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	updates := fetchUpdates(t, b, ctx)
+	if len(updates) == 0 {
+		t.Fatal("no updates")
+	}
+
+	groups := []string{"telegram", "e2e-recv"}
+	manager := attachment.Managers[defaultUploader]
+	if manager == nil {
+		t.Fatal("attachment manager not found")
+	}
+
+	type mediaHit struct {
+		kind         string
+		fileID       string
+		fileUniqueID string
+		mimeType     string
+		filename     string
+	}
+
+	var hits []mediaHit
+	for _, cm := range updates {
+		if cm == nil || !cm.HasMedia() {
+			continue
+		}
+		for _, m := range cm.MediaItems {
+			mime := m.MimeType
+			if mime == "" {
+				mime = "application/octet-stream"
+			}
+			name := m.FileName
+			if name == "" {
+				name = string(m.Type)
+			}
+			hits = append(hits, mediaHit{string(m.Type), m.FileID, m.FileUniqueID, mime, name})
+		}
+	}
+
+	if len(hits) == 0 {
+		t.Fatal("no media messages found in updates")
+	}
+	t.Logf("found %d media items in updates", len(hits))
+
+	for i, h := range hits {
+		t.Run(fmt.Sprintf("%s_%d", h.kind, i), func(t *testing.T) {
+			// 1. DownloadAndStore
+			result, err := b.DownloadAndStore(ctx, h.fileID, h.fileUniqueID, h.mimeType, h.filename, groups)
+			if err != nil {
+				t.Fatalf("DownloadAndStore: %v", err)
+			}
+			if result.Wrapper == "" {
+				t.Fatal("wrapper is empty")
+			}
+			if !strings.HasPrefix(result.Wrapper, defaultUploader+"://") {
+				t.Errorf("wrapper format: %s", result.Wrapper)
+			}
+			if result.FileName == "" {
+				t.Error("filename is empty")
+			}
+
+			// 2. Read back from attachment
+			_, fileID, ok := attachment.Parse(result.Wrapper)
+			if !ok {
+				t.Fatalf("failed to parse wrapper: %s", result.Wrapper)
+			}
+			resp, err := manager.Download(ctx, fileID)
+			if err != nil {
+				t.Fatalf("attachment Download: %v", err)
+			}
+			stored, err := io.ReadAll(resp.Reader)
+			resp.Reader.Close()
+			if err != nil {
+				t.Fatalf("read stored: %v", err)
+			}
+			if len(stored) == 0 {
+				t.Fatal("stored file is 0 bytes")
+			}
+
+			// 3. Dedup: same file_unique_id -> same wrapper
+			result2, err := b.DownloadAndStore(ctx, h.fileID, h.fileUniqueID, h.mimeType, h.filename, groups)
+			if err != nil {
+				t.Fatalf("DownloadAndStore dedup: %v", err)
+			}
+			if result2.Wrapper != result.Wrapper {
+				t.Errorf("dedup failed: %s vs %s", result.Wrapper, result2.Wrapper)
+			}
+
+			t.Logf("OK  %s unique=%s wrapper=%s stored=%d dedup=ok",
+				h.kind, h.fileUniqueID, result.Wrapper, len(stored))
+		})
+	}
+}
+
+// TestE2E_99_Offset_Confirm runs last (highest number, file sorted after e2e_test.go).
+// It validates offset-based acknowledgement and confirm semantics:
+//  1. offset=last_id returns from last_id onwards (confirms ids < last_id)
+//  2. offset=last_id+1 confirms all, subsequent offset=0 returns nothing old
+func TestE2E_99_Offset_Confirm(t *testing.T) {
+	skipIfNoToken(t)
+	b := testBot()
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	updates, err := b.GetRawUpdates(ctx, 0, 1)
+	if err != nil {
+		t.Fatalf("initial pull: %v", err)
+	}
+	if len(updates) == 0 {
+		t.Skip("no pending updates to test offset confirm")
+	}
+	firstID := int64(updates[0].ID)
+	lastID := int64(updates[len(updates)-1].ID)
+	t.Logf("pending updates: count=%d first_id=%d last_id=%d", len(updates), firstID, lastID)
+
+	// offset = last_id: confirms everything with id < last_id, returns from last_id
+	partial, err := b.GetRawUpdates(ctx, lastID, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=last_id=%d): %v", lastID, err)
+	}
+	if len(partial) == 0 {
+		t.Error("offset=last_id returned 0 updates, expected at least 1")
+	}
+	if len(partial) > 0 && int64(partial[0].ID) != lastID {
+		t.Errorf("offset=last_id: first_id=%d, want %d", partial[0].ID, lastID)
+	}
+	for _, p := range partial {
+		if int64(p.ID) < lastID {
+			t.Errorf("offset=last_id: got update_id=%d < %d", p.ID, lastID)
+		}
+	}
+	t.Logf("offset=last_id(%d): returned=%d, first_id=%d", lastID, len(partial), partial[0].ID)
+
+	// offset = last_id+1: confirms all remaining updates
+	confirmOffset := lastID + 1
+	afterConfirm, err := b.GetRawUpdates(ctx, confirmOffset, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=%d): %v", confirmOffset, err)
+	}
+	for _, ac := range afterConfirm {
+		if int64(ac.ID) <= lastID {
+			t.Errorf("post-confirm: got update_id=%d <= %d", ac.ID, lastID)
+		}
+	}
+	t.Logf("confirm offset=%d: returned=%d new", confirmOffset, len(afterConfirm))
+
+	// Re-pull offset=0: old updates should be purged
+	repull, err := b.GetRawUpdates(ctx, 0, 1)
+	if err != nil {
+		t.Fatalf("GetUpdates(offset=0 post-confirm): %v", err)
+	}
+	for _, r := range repull {
+		if int64(r.ID) <= lastID {
+			t.Errorf("post-confirm offset=0: stale update_id=%d (expected > %d)", r.ID, lastID)
+		}
+	}
+	t.Logf("post-confirm offset=0: returned=%d (old updates purged)", len(repull))
+}

integrations/telegram/message.go

@@ -0,0 +1,200 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/go-telegram/bot"
+	"github.com/go-telegram/bot/models"
+	"github.com/yaoapp/yao/attachment"
+)
+
+// SendMessage sends a message to a chat. If the text contains Markdown formatting,
+// it is automatically converted to Telegram-compatible HTML.
+func (b *Bot) SendMessage(ctx context.Context, chatID int64, text string, replyTo int64) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+
+	formatted := FormatTelegramHTML(text)
+	params := &bot.SendMessageParams{
+		ChatID:    chatID,
+		Text:      formatted,
+		ParseMode: models.ParseModeHTML,
+	}
+	if replyTo > 0 {
+		params.ReplyParameters = &models.ReplyParameters{MessageID: int(replyTo)}
+	}
+	_, err = sdk.SendMessage(ctx, params)
+	return err
+}
+
+// MediaType indicates which Telegram send method to use.
+type MediaType string
+
+const (
+	MediaPhoto     MediaType = "photo"
+	MediaDocument  MediaType = "document"
+	MediaAudio     MediaType = "audio"
+	MediaVideo     MediaType = "video"
+	MediaVoice     MediaType = "voice"
+	MediaAnimation MediaType = "animation"
+	MediaSticker   MediaType = "sticker"
+)
+
+// SendMedia sends a media message from a Yao attachment wrapper
+// (e.g. "__yao.attachment://ccd472d11feb96e03a3fc468f494045c").
+// It reads the file from the attachment manager, detects the media type from
+// the stored content type, and uploads it to the Telegram chat.
+func (b *Bot) SendMedia(ctx context.Context, chatID int64, wrapper string, caption string, replyTo int64) error {
+	managerName, fileID, err := parseWrapper(wrapper)
+	if err != nil {
+		return err
+	}
+
+	manager, exists := attachment.Managers[managerName]
+	if !exists {
+		return fmt.Errorf("attachment manager %s not found", managerName)
+	}
+
+	resp, err := manager.Download(ctx, fileID)
+	if err != nil {
+		return fmt.Errorf("attachment download %s: %w", fileID, err)
+	}
+	defer resp.Reader.Close()
+
+	mediaType := DetectMediaType(resp.ContentType)
+	filename := fileID + resp.Extension
+
+	file := &models.InputFileUpload{Filename: filename, Data: resp.Reader}
+	return b.sendMedia(ctx, chatID, mediaType, file, caption, replyTo)
+}
+
+// SendMediaByURL sends a media message from a public URL.
+// Telegram downloads the file directly from the URL.
+func (b *Bot) SendMediaByURL(ctx context.Context, chatID int64, mediaType MediaType, url string, caption string, replyTo int64) error {
+	file := &models.InputFileString{Data: url}
+	return b.sendMedia(ctx, chatID, mediaType, file, caption, replyTo)
+}
+
+// SendMediaByReader sends a media message by uploading raw bytes.
+func (b *Bot) SendMediaByReader(ctx context.Context, chatID int64, mediaType MediaType, filename string, data io.Reader, caption string, replyTo int64) error {
+	file := &models.InputFileUpload{Filename: filename, Data: data}
+	return b.sendMedia(ctx, chatID, mediaType, file, caption, replyTo)
+}
+
+// DetectMediaType guesses the MediaType from a MIME string.
+// Falls back to MediaDocument for unknown types.
+func DetectMediaType(mimeType string) MediaType {
+	lower := strings.ToLower(mimeType)
+	switch {
+	case strings.HasPrefix(lower, "image/webp"):
+		return MediaSticker
+	case strings.HasPrefix(lower, "image/gif"):
+		return MediaAnimation
+	case strings.HasPrefix(lower, "image/"):
+		return MediaPhoto
+	case strings.HasPrefix(lower, "video/"):
+		return MediaVideo
+	case strings.HasPrefix(lower, "audio/ogg"):
+		return MediaVoice
+	case strings.HasPrefix(lower, "audio/"):
+		return MediaAudio
+	default:
+		return MediaDocument
+	}
+}
+
+// parseWrapper splits "__yao.attachment://fileID" into manager name and file ID.
+func parseWrapper(wrapper string) (managerName string, fileID string, err error) {
+	idx := strings.Index(wrapper, "://")
+	if idx < 0 {
+		return "", "", fmt.Errorf("invalid attachment wrapper: %s", wrapper)
+	}
+	return wrapper[:idx], wrapper[idx+3:], nil
+}
+
+func (b *Bot) sendMedia(ctx context.Context, chatID int64, mediaType MediaType, file models.InputFile, caption string, replyTo int64) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+
+	var replyParams *models.ReplyParameters
+	if replyTo > 0 {
+		replyParams = &models.ReplyParameters{MessageID: int(replyTo)}
+	}
+
+	htmlCaption := FormatTelegramHTML(caption)
+
+	switch mediaType {
+	case MediaPhoto:
+		_, err = sdk.SendPhoto(ctx, &bot.SendPhotoParams{
+			ChatID:          chatID,
+			Photo:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaDocument:
+		_, err = sdk.SendDocument(ctx, &bot.SendDocumentParams{
+			ChatID:          chatID,
+			Document:        file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaAudio:
+		_, err = sdk.SendAudio(ctx, &bot.SendAudioParams{
+			ChatID:          chatID,
+			Audio:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaVideo:
+		_, err = sdk.SendVideo(ctx, &bot.SendVideoParams{
+			ChatID:          chatID,
+			Video:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaVoice:
+		_, err = sdk.SendVoice(ctx, &bot.SendVoiceParams{
+			ChatID:          chatID,
+			Voice:           file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaAnimation:
+		_, err = sdk.SendAnimation(ctx, &bot.SendAnimationParams{
+			ChatID:          chatID,
+			Animation:       file,
+			Caption:         htmlCaption,
+			ParseMode:       models.ParseModeHTML,
+			ReplyParameters: replyParams,
+		})
+
+	case MediaSticker:
+		_, err = sdk.SendSticker(ctx, &bot.SendStickerParams{
+			ChatID:          chatID,
+			Sticker:         file,
+			ReplyParameters: replyParams,
+		})
+
+	default:
+		return fmt.Errorf("unsupported media type: %s", mediaType)
+	}
+
+	return err
+}

integrations/telegram/message_test.go

@@ -0,0 +1,64 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestDetectMediaType(t *testing.T) {
+	cases := []struct {
+		mime     string
+		expected MediaType
+	}{
+		{"image/jpeg", MediaPhoto},
+		{"image/png", MediaPhoto},
+		{"IMAGE/PNG", MediaPhoto},
+		{"image/gif", MediaAnimation},
+		{"image/webp", MediaSticker},
+		{"video/mp4", MediaVideo},
+		{"video/webm", MediaVideo},
+		{"audio/mpeg", MediaAudio},
+		{"audio/mp3", MediaAudio},
+		{"audio/ogg", MediaVoice},
+		{"audio/ogg; codecs=opus", MediaVoice},
+		{"application/pdf", MediaDocument},
+		{"application/octet-stream", MediaDocument},
+		{"text/plain", MediaDocument},
+		{"", MediaDocument},
+	}
+	for _, tc := range cases {
+		got := DetectMediaType(tc.mime)
+		if got != tc.expected {
+			t.Errorf("DetectMediaType(%q) = %q, want %q", tc.mime, got, tc.expected)
+		}
+	}
+}
+
+func TestParseWrapper(t *testing.T) {
+	cases := []struct {
+		input   string
+		manager string
+		fileID  string
+		wantErr bool
+	}{
+		{"__yao.attachment://abc123", "__yao.attachment", "abc123", false},
+		{"__custom.uploader://xyz", "__custom.uploader", "xyz", false},
+		{"no-separator", "", "", true},
+		{"://empty-manager", "", "empty-manager", false},
+	}
+	for _, tc := range cases {
+		manager, fileID, err := parseWrapper(tc.input)
+		if tc.wantErr {
+			if err == nil {
+				t.Errorf("parseWrapper(%q) expected error, got nil", tc.input)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("parseWrapper(%q) unexpected error: %v", tc.input, err)
+			continue
+		}
+		if manager != tc.manager || fileID != tc.fileID {
+			t.Errorf("parseWrapper(%q) = (%q, %q), want (%q, %q)", tc.input, manager, fileID, tc.manager, tc.fileID)
+		}
+	}
+}

integrations/telegram/polling.go

@@ -0,0 +1,81 @@
+package telegram
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-telegram/bot/models"
+)
+
+// GetUpdates fetches new updates via long polling and returns them as
+// ConvertedMessages ready for consumption. Non-message updates (e.g.
+// callback_query without a message) are silently skipped.
+// When groups is non-nil, media attachments are automatically downloaded
+// and stored via DownloadAndStore, filling each MediaItem.Wrapper.
+func (b *Bot) GetUpdates(ctx context.Context, offset int64, timeout int, groups []string) ([]*ConvertedMessage, error) {
+	raw, err := b.GetRawUpdates(ctx, offset, timeout)
+	if err != nil {
+		return nil, err
+	}
+	var msgs []*ConvertedMessage
+	for i := range raw {
+		if cm := ConvertUpdate(&raw[i]); cm != nil {
+			if groups != nil && cm.HasMedia() {
+				b.ResolveMedia(ctx, cm, groups)
+			}
+			msgs = append(msgs, cm)
+		}
+	}
+	return msgs, nil
+}
+
+// GetRawUpdates fetches raw Telegram updates without conversion.
+// Use this when you need access to the original models.Update (e.g. for
+// offset tracking). Uses raw HTTP because the SDK keeps getUpdates private.
+func (b *Bot) GetRawUpdates(ctx context.Context, offset int64, timeout int) ([]models.Update, error) {
+	params := map[string]interface{}{
+		"offset":  offset,
+		"timeout": timeout,
+		"limit":   100,
+	}
+	body, err := json.Marshal(params)
+	if err != nil {
+		return nil, fmt.Errorf("marshal params: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", b.botURL()+"/getUpdates", bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("telegram API error status=%d body=%s", resp.StatusCode, string(respBody))
+	}
+
+	var result struct {
+		OK     bool            `json:"ok"`
+		Result []models.Update `json:"result"`
+	}
+	if err := json.Unmarshal(respBody, &result); err != nil {
+		return nil, fmt.Errorf("unmarshal response: %w", err)
+	}
+	if !result.OK {
+		return nil, fmt.Errorf("telegram API returned ok=false")
+	}
+	return result.Result, nil
+}

integrations/telegram/telegram_test.go

@@ -0,0 +1,177 @@
+package telegram
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/gotd/td/session"
+	"github.com/gotd/td/telegram"
+	"github.com/gotd/td/telegram/uploader"
+	"github.com/gotd/td/tg"
+	"github.com/yaoapp/yao/attachment"
+	"github.com/yaoapp/yao/config"
+	"github.com/yaoapp/yao/test"
+)
+
+var testBotToken string
+
+func TestMain(m *testing.M) {
+	testBotToken = os.Getenv("TELEGRAM_TEST_BOT_TOKEN")
+	os.Exit(m.Run())
+}
+
+func prepare(t *testing.T) {
+	t.Helper()
+	test.Prepare(t, config.Conf)
+	if err := attachment.Load(config.Conf); err != nil {
+		t.Fatalf("load attachment: %v", err)
+	}
+}
+
+func cleanup() {
+	test.Clean()
+}
+
+func skipIfNoToken(t *testing.T) {
+	t.Helper()
+	if testBotToken == "" {
+		t.Skip("TELEGRAM_TEST_BOT_TOKEN not set, skipping E2E test")
+	}
+}
+
+func testBot(opts ...BotOption) *Bot {
+	if host := os.Getenv("TELEGRAM_TEST_HOST"); host != "" {
+		opts = append([]BotOption{WithAPIBase(host)}, opts...)
+	}
+	return NewBot(testBotToken, "", opts...)
+}
+
+// seedBotMessages uses the persisted MTProto user session to send a text
+// message and a small PNG photo to the test bot, so that subsequent
+// GetUpdates calls have real data to work with.
+// Requires TG_TEST_SESSION and TG_TEST_BOT_USERNAME env vars.
+func seedBotMessages(t *testing.T) {
+	t.Helper()
+
+	sessionPath := os.Getenv("TG_TEST_SESSION")
+	botUsername := os.Getenv("TG_TEST_BOT_USERNAME")
+	if sessionPath == "" || botUsername == "" {
+		t.Skip("TG_TEST_SESSION or TG_TEST_BOT_USERNAME not set, cannot seed messages")
+	}
+
+	if !filepath.IsAbs(sessionPath) {
+		if root := os.Getenv("YAO_DEV"); root != "" {
+			sessionPath = filepath.Join(root, sessionPath)
+		}
+	}
+
+	if _, err := os.Stat(sessionPath); os.IsNotExist(err) {
+		t.Skipf("session file %s not found, run tg-login first", sessionPath)
+	}
+	t.Logf("seed: using session %s, bot @%s", sessionPath, botUsername)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	storage := &session.FileStorage{Path: sessionPath}
+	client := telegram.NewClient(17349, "344583e45741c457fe1862106095a5eb", telegram.Options{
+		SessionStorage: storage,
+	})
+
+	err := client.Run(ctx, func(ctx context.Context) error {
+		status, err := client.Auth().Status(ctx)
+		if err != nil {
+			return fmt.Errorf("auth status: %w", err)
+		}
+		if !status.Authorized {
+			return fmt.Errorf("not authorized — run tg-login first")
+		}
+
+		api := client.API()
+		resolved, err := api.ContactsResolveUsername(ctx, &tg.ContactsResolveUsernameRequest{
+			Username: botUsername,
+		})
+		if err != nil {
+			return fmt.Errorf("resolve @%s: %w", botUsername, err)
+		}
+		if len(resolved.Users) == 0 {
+			return fmt.Errorf("bot @%s not found", botUsername)
+		}
+		u, ok := resolved.Users[0].(*tg.User)
+		if !ok {
+			return fmt.Errorf("resolved entity is not a user")
+		}
+		peer := &tg.InputPeerUser{UserID: u.ID, AccessHash: u.AccessHash}
+
+		tag := time.Now().Format("15:04:05")
+		_, err = api.MessagesSendMessage(ctx, &tg.MessagesSendMessageRequest{
+			Peer:     peer,
+			Message:  fmt.Sprintf("[e2e-test] hello at %s", tag),
+			RandomID: mtpRandID(),
+		})
+		if err != nil {
+			return fmt.Errorf("send text: %w", err)
+		}
+		t.Log("seed: sent text")
+
+		up := uploader.NewUploader(api)
+
+		seedFiles := []struct {
+			path  string
+			photo bool
+			attrs []tg.DocumentAttributeClass
+		}{
+			{"../testdata/test.jpg", true, nil},
+			{"../testdata/test.mp3", false, []tg.DocumentAttributeClass{
+				&tg.DocumentAttributeAudio{Duration: 5, Title: "e2e-test"},
+			}},
+			{"../testdata/test.pdf", false, []tg.DocumentAttributeClass{
+				&tg.DocumentAttributeFilename{FileName: "test.pdf"},
+			}},
+		}
+
+		for _, sf := range seedFiles {
+			f, err := up.FromPath(ctx, sf.path)
+			if err != nil {
+				return fmt.Errorf("upload %s: %w", sf.path, err)
+			}
+			var media tg.InputMediaClass
+			if sf.photo {
+				media = &tg.InputMediaUploadedPhoto{File: f}
+			} else {
+				media = &tg.InputMediaUploadedDocument{
+					File:       f,
+					Attributes: sf.attrs,
+				}
+			}
+			_, err = api.MessagesSendMedia(ctx, &tg.MessagesSendMediaRequest{
+				Peer:     peer,
+				Media:    media,
+				Message:  fmt.Sprintf("[e2e-test] %s at %s", filepath.Base(sf.path), tag),
+				RandomID: mtpRandID(),
+			})
+			if err != nil {
+				return fmt.Errorf("send %s: %w", sf.path, err)
+			}
+			t.Logf("seed: sent %s", filepath.Base(sf.path))
+		}
+
+		time.Sleep(time.Second)
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("seedBotMessages: %v", err)
+	}
+}
+
+func mtpRandID() int64 {
+	var b [8]byte
+	_, _ = rand.Read(b[:])
+	return int64(binary.LittleEndian.Uint64(b[:]))
+}

integrations/telegram/types.go

@@ -0,0 +1,21 @@
+package telegram
+
+import "github.com/go-telegram/bot/models"
+
+// Re-export SDK types so adapter code imports from one place.
+// When the SDK upgrades, any breaking field changes surface here at compile time.
+type (
+	Update    = models.Update
+	Message   = models.Message
+	User      = models.User
+	Chat      = models.Chat
+	PhotoSize = models.PhotoSize
+	Document  = models.Document
+	Voice     = models.Voice
+	Video     = models.Video
+	Sticker   = models.Sticker
+	Audio     = models.Audio
+	Animation = models.Animation
+
+	MessageEntity = models.MessageEntity
+)

integrations/telegram/verify.go

@@ -0,0 +1,53 @@
+package telegram
+
+import (
+	"context"
+	"crypto/subtle"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-telegram/bot/models"
+)
+
+// GetMe calls the getMe endpoint to verify the bot token is valid.
+// Uses raw HTTP for compatibility with both official and local Bot API servers.
+func (b *Bot) GetMe(ctx context.Context) (*models.User, error) {
+	req, err := http.NewRequestWithContext(ctx, "GET", b.botURL()+"/getMe", nil)
+	if err != nil {
+		return nil, fmt.Errorf("create request: %w", err)
+	}
+	resp, err := b.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	var result struct {
+		OK     bool        `json:"ok"`
+		Result models.User `json:"result"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("unmarshal: %w", err)
+	}
+	if !result.OK {
+		return nil, fmt.Errorf("getMe: API returned ok=false")
+	}
+	return &result.Result, nil
+}
+
+// VerifyWebhook checks the X-Telegram-Bot-Api-Secret-Token header value
+// against the bot's configured secret_token using constant-time comparison.
+// Returns true if the secret matches or if no secret was configured.
+func (b *Bot) VerifyWebhook(headerSecret string) bool {
+	if b.secretToken == "" {
+		return true
+	}
+	return subtle.ConstantTimeCompare([]byte(b.secretToken), []byte(headerSecret)) == 1
+}

integrations/telegram/verify_test.go

@@ -0,0 +1,32 @@
+package telegram
+
+import (
+	"testing"
+)
+
+func TestVerifyWebhook_NoSecret(t *testing.T) {
+	b := NewBot("token", "")
+	if !b.VerifyWebhook("anything") {
+		t.Fatal("should pass when no secret configured")
+	}
+	if !b.VerifyWebhook("") {
+		t.Fatal("should pass with empty header when no secret configured")
+	}
+}
+
+func TestVerifyWebhook_CorrectSecret(t *testing.T) {
+	b := NewBot("token", "s3cr3t-t0ken")
+	if !b.VerifyWebhook("s3cr3t-t0ken") {
+		t.Fatal("should pass with matching secret")
+	}
+}
+
+func TestVerifyWebhook_WrongSecret(t *testing.T) {
+	b := NewBot("token", "s3cr3t-t0ken")
+	if b.VerifyWebhook("wrong") {
+		t.Fatal("should reject mismatched secret")
+	}
+	if b.VerifyWebhook("") {
+		t.Fatal("should reject empty header when secret configured")
+	}
+}

integrations/telegram/webhook.go

@@ -0,0 +1,82 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+
+	"github.com/go-telegram/bot"
+	"github.com/go-telegram/bot/models"
+)
+
+// SetWebhook registers a webhook URL with Telegram. The configured
+// secret_token (if any) is sent along so Telegram includes it in every
+// webhook request header for verification.
+func (b *Bot) SetWebhook(ctx context.Context, url string, allowedUpdates []string) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+	params := &bot.SetWebhookParams{
+		URL:            url,
+		AllowedUpdates: allowedUpdates,
+		SecretToken:    b.secretToken,
+	}
+	if _, err := sdk.SetWebhook(ctx, params); err != nil {
+		return fmt.Errorf("setWebhook: %w", err)
+	}
+	return nil
+}
+
+// DeleteWebhook removes the webhook configuration from Telegram.
+func (b *Bot) DeleteWebhook(ctx context.Context, dropPending bool) error {
+	sdk, err := b.sdk()
+	if err != nil {
+		return err
+	}
+	if _, err := sdk.DeleteWebhook(ctx, &bot.DeleteWebhookParams{
+		DropPendingUpdates: dropPending,
+	}); err != nil {
+		return fmt.Errorf("deleteWebhook: %w", err)
+	}
+	return nil
+}
+
+// ParseWebhookPayload reads and parses a Telegram webhook request body,
+// verifies the secret header, and returns a ConvertedMessage ready for use.
+// Returns nil message (no error) if the update contains no processable message.
+// When groups is non-nil, media attachments are automatically resolved.
+func (b *Bot) ParseWebhookPayload(ctx context.Context, r *http.Request, groups []string) (*ConvertedMessage, error) {
+	update, err := b.ParseRawWebhookPayload(r)
+	if err != nil {
+		return nil, err
+	}
+	cm := ConvertUpdate(update)
+	if cm != nil && groups != nil && cm.HasMedia() {
+		b.ResolveMedia(ctx, cm, groups)
+	}
+	return cm, nil
+}
+
+// ParseRawWebhookPayload reads and parses a Telegram webhook request body
+// into a raw models.Update. It also verifies the X-Telegram-Bot-Api-Secret-Token
+// header when a secret is configured.
+func (b *Bot) ParseRawWebhookPayload(r *http.Request) (*models.Update, error) {
+	if !b.VerifyWebhook(r.Header.Get("X-Telegram-Bot-Api-Secret-Token")) {
+		return nil, fmt.Errorf("webhook secret mismatch")
+	}
+
+	body, err := io.ReadAll(r.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read body: %w", err)
+	}
+	defer r.Body.Close()
+
+	var update models.Update
+	if err := json.Unmarshal(body, &update); err != nil {
+		return nil, fmt.Errorf("unmarshal update: %w", err)
+	}
+	return &update, nil
+}

integrations/telegram/webhook_e2e_test.go

@@ -0,0 +1,280 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"sync"
+	"testing"
+	"time"
+)
+
+// TestE2E_Webhook requires a local telegram-bot-api server (TELEGRAM_TEST_HOST)
+// because the official Telegram API only accepts HTTPS webhooks on public IPs.
+// A local Bot API server can deliver webhooks to http://127.0.0.1.
+//
+// Flow:
+//  1. Start a local HTTP server on a random port
+//  2. SetWebhook to http://127.0.0.1:{port}/webhook with a secret token
+//  3. Seed a message via MTProto
+//  4. Wait for the webhook to deliver the Update
+//  5. Verify: ParseWebhookPayload succeeds, secret header correct, Update fields valid
+//  6. DeleteWebhook to restore polling mode
+func TestE2E_Webhook(t *testing.T) {
+	skipIfNoToken(t)
+
+	host := os.Getenv("TELEGRAM_TEST_HOST")
+	if host == "" {
+		t.Skip("TELEGRAM_TEST_HOST not set — need local bot-api server for webhook test")
+	}
+
+	const secret = "e2e-webhook-test-secret"
+	b := testBot(WithAPIBase(host))
+	bWithSecret := NewBot(testBotToken, secret, WithAPIBase(host))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	// --- 1. Start local webhook receiver ---
+	var (
+		mu          sync.Mutex
+		received    []webhookHit
+		wrongSecret int
+	)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
+		headerSec := r.Header.Get("X-Telegram-Bot-Api-Secret-Token")
+		cm, err := bWithSecret.ParseWebhookPayload(r.Context(), r, nil)
+
+		mu.Lock()
+		defer mu.Unlock()
+
+		if err != nil {
+			wrongSecret++
+			t.Logf("webhook: rejected request (secret=%q err=%v)", headerSec, err)
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+
+		received = append(received, webhookHit{
+			secret: headerSec,
+			cm:     cm,
+		})
+		if cm != nil {
+			t.Logf("webhook: accepted update_id=%d secret=%q", cm.UpdateID, headerSec)
+		} else {
+			t.Logf("webhook: accepted (no processable message) secret=%q", headerSec)
+		}
+		w.WriteHeader(http.StatusOK)
+	})
+
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	port := listener.Addr().(*net.TCPAddr).Port
+	server := &http.Server{Handler: mux}
+	go server.Serve(listener)
+	defer server.Close()
+	t.Logf("webhook server listening on 127.0.0.1:%d", port)
+
+	// --- 2. SetWebhook ---
+	webhookURL := fmt.Sprintf("http://127.0.0.1:%d/webhook", port)
+	if err := bWithSecret.SetWebhook(ctx, webhookURL, []string{"message"}); err != nil {
+		t.Fatalf("SetWebhook: %v", err)
+	}
+	t.Logf("SetWebhook -> %s", webhookURL)
+
+	defer func() {
+		cleanCtx, cleanCancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cleanCancel()
+		if err := b.DeleteWebhook(cleanCtx, true); err != nil {
+			t.Logf("warning: DeleteWebhook failed: %v", err)
+		} else {
+			t.Log("DeleteWebhook -> ok (polling restored)")
+		}
+	}()
+
+	// --- 3. Seed a message ---
+	seedBotMessages(t)
+
+	// --- 4. Wait for webhook delivery ---
+	deadline := time.After(30 * time.Second)
+	ticker := time.NewTicker(500 * time.Millisecond)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-deadline:
+			mu.Lock()
+			count := len(received)
+			mu.Unlock()
+			if count == 0 {
+				t.Fatal("timeout: no webhook updates received within 30s")
+			}
+			goto verify
+		case <-ticker.C:
+			mu.Lock()
+			count := len(received)
+			mu.Unlock()
+			if count >= 2 {
+				time.Sleep(2 * time.Second)
+				goto verify
+			}
+		}
+	}
+
+verify:
+	mu.Lock()
+	defer mu.Unlock()
+
+	if len(received) == 0 {
+		t.Fatal("no webhook updates received")
+	}
+	t.Logf("total webhook hits: %d (rejected: %d)", len(received), wrongSecret)
+
+	// --- 5. Validate received updates ---
+	for i, hit := range received {
+		t.Run(fmt.Sprintf("update_%d", i), func(t *testing.T) {
+			if hit.secret != secret {
+				t.Errorf("secret header = %q, want %q", hit.secret, secret)
+			}
+
+			cm := hit.cm
+			if cm == nil {
+				t.Log("webhook hit has no processable message (cm nil)")
+				return
+			}
+
+			if cm.UpdateID == 0 {
+				t.Error("ConvertedMessage.UpdateID should not be 0")
+			}
+			if cm.MessageID == 0 {
+				t.Error("ConvertedMessage.MessageID should not be 0")
+			}
+			if cm.ChatID == 0 {
+				t.Error("ConvertedMessage.ChatID should not be 0")
+			}
+			if cm.Date == 0 {
+				t.Error("ConvertedMessage.Date should not be 0")
+			}
+			if cm.SenderID == 0 {
+				t.Error("ConvertedMessage.SenderID should not be 0")
+			}
+			if cm.SenderName == "" {
+				t.Error("ConvertedMessage.SenderName should not be empty")
+			}
+			if !cm.HasText() && !cm.HasMedia() {
+				t.Error("message has neither text nor media")
+			}
+
+			for j, mi := range cm.MediaItems {
+				if mi.FileID == "" {
+					t.Errorf("media[%d].FileID should not be empty", j)
+				}
+				if mi.FileUniqueID == "" {
+					t.Errorf("media[%d].FileUniqueID should not be empty", j)
+				}
+				if mi.MimeType == "" {
+					t.Errorf("media[%d].MimeType should not be empty", j)
+				}
+				if mi.Type == "" {
+					t.Errorf("media[%d].Type should not be empty", j)
+				}
+			}
+
+			t.Logf("webhook update[%d] id=%d msg=%d chat=%d sender=%q text=%q media=%d",
+				i, cm.UpdateID, cm.MessageID, cm.ChatID, cm.SenderName,
+				truncate(cm.Text, 40), len(cm.MediaItems))
+		})
+	}
+
+	// --- 6. Compare with GetUpdates ---
+	// Delete webhook first, then seed + poll to verify ConvertUpdate consistency.
+	t.Run("convert_consistency", func(t *testing.T) {
+		delCtx, delCancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer delCancel()
+		if err := b.DeleteWebhook(delCtx, true); err != nil {
+			t.Fatalf("DeleteWebhook for polling: %v", err)
+		}
+		time.Sleep(time.Second)
+
+		seedBotMessages(t)
+		time.Sleep(2 * time.Second)
+
+		pollCtx, pollCancel := context.WithTimeout(context.Background(), 15*time.Second)
+		defer pollCancel()
+		polled := fetchUpdates(t, b, pollCtx)
+		if len(polled) == 0 {
+			t.Skip("no polled updates to compare")
+		}
+
+		polledCM := polled[0]
+		if polledCM == nil {
+			t.Skip("polled update has no message")
+		}
+
+		var webhookCM *ConvertedMessage
+		for _, hit := range received {
+			if hit.cm != nil {
+				webhookCM = hit.cm
+				break
+			}
+		}
+		if webhookCM == nil {
+			t.Skip("no webhook update with message")
+		}
+
+		if webhookCM.ChatID == 0 || polledCM.ChatID == 0 {
+			t.Error("both sources should have non-zero ChatID")
+		}
+		if webhookCM.SenderID == 0 || polledCM.SenderID == 0 {
+			t.Error("both sources should have non-zero SenderID")
+		}
+		if webhookCM.Date == 0 || polledCM.Date == 0 {
+			t.Error("both sources should have non-zero Date")
+		}
+		if webhookCM.ChatType != polledCM.ChatType {
+			t.Errorf("ChatType mismatch: webhook=%q polled=%q", webhookCM.ChatType, polledCM.ChatType)
+		}
+
+		webhookHasContent := webhookCM.HasText() || webhookCM.HasMedia()
+		polledHasContent := polledCM.HasText() || polledCM.HasMedia()
+		if !webhookHasContent {
+			t.Error("webhook ConvertUpdate produced no content")
+		}
+		if !polledHasContent {
+			t.Error("polled ConvertUpdate produced no content")
+		}
+
+		t.Logf("consistency OK: webhook(text=%v media=%d) polled(text=%v media=%d) chat_type=%s",
+			webhookCM.HasText(), len(webhookCM.MediaItems),
+			polledCM.HasText(), len(polledCM.MediaItems),
+			polledCM.ChatType)
+	})
+
+	// Verify ParseWebhookPayload rejects wrong secrets
+	t.Run("wrong_secret_rejected", func(t *testing.T) {
+		fakeReq, _ := http.NewRequest("POST", "/webhook", nil)
+		fakeReq.Header.Set("X-Telegram-Bot-Api-Secret-Token", "wrong-secret")
+		_, err := bWithSecret.ParseWebhookPayload(fakeReq.Context(), fakeReq, nil)
+		if err == nil {
+			t.Error("expected error for wrong secret, got nil")
+		}
+	})
+}
+
+type webhookHit struct {
+	secret string
+	cm     *ConvertedMessage
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}