Files
dobotai-platform/internal/channels/dingtalk/handler.go
T
2026-07-21 00:08:01 +08:00

436 lines
15 KiB
Go

package dingtalk
import (
"context"
"errors"
"fmt"
"log"
"strings"
"time"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/weknora"
)
const (
msgTypeText = "text"
msgTypePicture = "picture"
conversationTypeDirect = "1"
conversationTypeGroup = "2"
replyTitle = "DobotAI"
unsupportedMessageReply = "当前版本暂仅支持文字消息。"
qaErrorReply = "抱歉,当前暂时无法完成回答,请稍后重试。"
imageErrorReply = "图片识别暂时不可用,请稍后重试或发送文字。"
imageQuery = "请描述并分析这张图片。"
streamingPlaceholder = "正在理解问题…"
)
type TenantConfig struct {
TenantKey string
Channel string
}
type BotCallback struct {
ConversationType string
ConversationID string
Msgtype string
MsgID string
SenderNick string
SenderStaffID string
SenderID string
IsInAtList bool
SessionWebhook string
Text string
DownloadCode string
}
type QAAsker interface {
Ask(ctx context.Context, req core.QARequest) (core.QAResult, error)
}
// StreamingQAAsker asks the QA backend with streaming observer support.
type StreamingQAAsker interface {
QAAsker
AskStream(ctx context.Context, req core.QARequest, observer weknora.AnswerObserver) (core.QAResult, error)
}
// EventQAAsker exposes safe stage metadata without thinking/tool payloads.
type EventQAAsker interface {
QAAsker
AskEvents(ctx context.Context, req core.QARequest, observer weknora.StreamObserver) (core.QAResult, error)
}
type MarkdownSender interface {
SendMarkdown(ctx context.Context, webhookURL, title, text string) error
}
type ImageDownloader interface {
Download(ctx context.Context, downloadCode string) (core.ImageInput, error)
}
// FinalCardSender sends an AI card as the final reply. Implementations must
// not log err, outTrackID, or content at any level.
type FinalCardSender interface {
SendFinalCard(context.Context, CardRequest) (string, error)
}
// StreamingCardSender supports streaming card lifecycle: start, update, and finalize.
type StreamingCardSender interface {
FinalCardSender
StartCard(ctx context.Context, req CardRequest) (string, error)
UpdateCard(ctx context.Context, id, content string, isFinalize, isError bool) error
}
type HandlerOptions struct {
ImageDownloader ImageDownloader
CardSender FinalCardSender
}
type Handler struct {
cfg TenantConfig
qa QAAsker
reply MarkdownSender
downloader ImageDownloader
card FinalCardSender
now func() time.Time
cardUpdateInterval time.Duration
finalDeliveryTimeout time.Duration
}
// NewHandler accepts at most one image downloader. A nil/omitted downloader
// keeps text ingress available while picture messages fail closed.
func NewHandler(cfg TenantConfig, qa QAAsker, reply MarkdownSender, downloaders ...ImageDownloader) (*Handler, error) {
var downloader ImageDownloader
if len(downloaders) > 1 {
return nil, errors.New("dingtalk handler: at most one image downloader is allowed")
}
if len(downloaders) == 1 {
downloader = downloaders[0]
}
return NewHandlerWithOptions(cfg, qa, reply, HandlerOptions{ImageDownloader: downloader})
}
// NewHandlerWithOptions creates a Handler with an optional image downloader
// and optional card sender. Passing nil for either option is equivalent to
// omitting the feature.
func NewHandlerWithOptions(cfg TenantConfig, qa QAAsker, reply MarkdownSender, opts HandlerOptions) (*Handler, error) {
if strings.TrimSpace(cfg.TenantKey) == "" {
return nil, errors.New("dingtalk handler: tenant key is required")
}
if strings.TrimSpace(cfg.Channel) == "" {
return nil, errors.New("dingtalk handler: channel is required")
}
if qa == nil {
return nil, errors.New("dingtalk handler: QA asker is required")
}
if reply == nil {
return nil, errors.New("dingtalk handler: markdown sender is required")
}
return &Handler{
cfg: cfg,
qa: qa,
reply: reply,
downloader: opts.ImageDownloader,
card: opts.CardSender,
now: time.Now,
cardUpdateInterval: 500 * time.Millisecond,
finalDeliveryTimeout: defaultHTTPTimeout,
}, nil
}
func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
// Admission comes first: a group message without @ must have zero side effects.
if cb.ConversationType == conversationTypeGroup && !cb.IsInAtList {
return nil
}
// Validate the only reply destination before downloading media or spending a
// model call. Webhook errors never include its query string.
webhookURL := strings.TrimSpace(cb.SessionWebhook)
if webhookURL == "" {
return errors.New("dingtalk handler: sessionWebhook is required to reply")
}
if err := ValidateWebhookURL(webhookURL); err != nil {
return fmt.Errorf("dingtalk handler: invalid sessionWebhook: %w", err)
}
if strings.TrimSpace(cb.MsgID) == "" {
return errors.New("dingtalk handler: msgId is required")
}
externalUserID := strings.TrimSpace(cb.SenderStaffID)
if externalUserID == "" {
externalUserID = strings.TrimSpace(cb.SenderID)
}
if externalUserID == "" {
return errors.New("dingtalk handler: sender staffId/senderId is required")
}
req := core.QARequest{
TenantKey: h.cfg.TenantKey,
Channel: h.cfg.Channel,
ExternalUserID: externalUserID,
ExternalMessageID: strings.TrimSpace(cb.MsgID),
SenderName: cb.SenderNick,
}
switch cb.ConversationType {
case conversationTypeGroup:
if strings.TrimSpace(cb.ConversationID) == "" {
return errors.New("dingtalk handler: conversationId is required for group messages")
}
req.ConversationType = core.ConversationGroup
req.ExternalChatID = strings.TrimSpace(cb.ConversationID)
default:
req.ConversationType = core.ConversationDirect
}
switch strings.ToLower(strings.TrimSpace(cb.Msgtype)) {
case msgTypeText:
req.Query = strings.TrimSpace(cb.Text)
if req.Query == "" {
return errors.New("dingtalk handler: text message content is empty")
}
case msgTypePicture:
if strings.TrimSpace(cb.DownloadCode) == "" {
log.Printf("DingTalk image preparation failed: stage=missing_download_code")
return h.sendReply(ctx, webhookURL, imageErrorReply)
}
if h.downloader == nil {
log.Printf("DingTalk image preparation failed: stage=downloader_unavailable")
return h.sendReply(ctx, webhookURL, imageErrorReply)
}
image, err := h.downloader.Download(ctx, strings.TrimSpace(cb.DownloadCode))
if err != nil {
log.Printf("DingTalk image preparation failed: stage=%s", imageFailureStage(err))
return h.sendReply(ctx, webhookURL, imageErrorReply)
}
req.Query = strings.TrimSpace(cb.Text)
if req.Query == "" {
req.Query = imageQuery
}
req.Images = []core.ImageInput{image}
default:
return h.sendReply(ctx, webhookURL, unsupportedMessageReply)
}
if eventCard, eventQA := h.eventStreamingCapable(); eventCard != nil && eventQA != nil {
return h.handleEventStreaming(ctx, webhookURL, req, eventCard, eventQA)
}
// Backward-compatible A3.2 answer-only streaming capability.
streamingCard, streamingQA := h.streamingCapable()
if streamingCard != nil && streamingQA != nil {
return h.handleStreaming(ctx, webhookURL, req, streamingCard, streamingQA)
}
return h.handleNonStreaming(ctx, webhookURL, req)
}
func (h *Handler) eventStreamingCapable() (StreamingCardSender, EventQAAsker) {
sc, ok := h.card.(StreamingCardSender)
if !ok {
return nil, nil
}
eq, ok := h.qa.(EventQAAsker)
if !ok {
return nil, nil
}
return sc, eq
}
func (h *Handler) streamingCapable() (StreamingCardSender, StreamingQAAsker) {
sc, ok := h.card.(StreamingCardSender)
if !ok {
return nil, nil
}
sq, ok := h.qa.(StreamingQAAsker)
if !ok {
return nil, nil
}
return sc, sq
}
func (h *Handler) handleNonStreaming(ctx context.Context, webhookURL string, req core.QARequest) error {
result, err := h.qa.Ask(ctx, req)
if err != nil {
if replyErr := h.sendReply(ctx, webhookURL, qaErrorReply); replyErr != nil {
return replyErr
}
return nil
}
if h.card != nil {
cardReq := CardRequest{
ConversationType: req.ConversationType,
ExternalUserID: req.ExternalUserID,
ExternalChatID: req.ExternalChatID,
Content: result.Answer,
}
if _, cardErr := h.card.SendFinalCard(ctx, cardReq); cardErr == nil {
return nil
}
log.Printf("DingTalk card delivery failed, falling back to markdown")
}
return h.sendReply(ctx, webhookURL, result.Answer)
}
func (h *Handler) handleStreaming(ctx context.Context, webhookURL string, req core.QARequest, streamingCard StreamingCardSender, streamingQA StreamingQAAsker) error {
cardReq := CardRequest{
ConversationType: req.ConversationType,
ExternalUserID: req.ExternalUserID,
ExternalChatID: req.ExternalChatID,
Content: streamingPlaceholder,
}
outTrackID, err := streamingCard.StartCard(ctx, cardReq)
if err != nil {
log.Printf("DingTalk streaming card start failed, falling back to non-streaming")
// Fallback: Ask → Markdown only (no SendFinalCard, no AskStream)
result, askErr := h.qa.Ask(ctx, req)
if askErr != nil {
if replyErr := h.sendReply(ctx, webhookURL, qaErrorReply); replyErr != nil {
return replyErr
}
return nil
}
return h.sendReply(ctx, webhookURL, result.Answer)
}
// Streaming observer with the configured update throttle (500ms by default).
var lastUpdate time.Time
observer := func(fullContent string) {
if strings.TrimSpace(fullContent) == "" {
return
}
now := h.now()
if lastUpdate.IsZero() || now.Sub(lastUpdate) >= h.cardUpdateInterval {
// Advance the throttle window before I/O so a failing DingTalk API
// cannot be hammered once per model chunk. The final update below is
// always attempted regardless of this timestamp.
lastUpdate = now
if updateErr := streamingCard.UpdateCard(ctx, outTrackID, fullContent, false, false); updateErr != nil {
log.Printf("DingTalk streaming card update failed, continuing")
}
}
}
result, err := streamingQA.AskStream(ctx, req, observer)
if err != nil || strings.TrimSpace(result.Answer) == "" {
return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, qaErrorReply, true)
}
return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, result.Answer, false)
}
func (h *Handler) handleEventStreaming(ctx context.Context, webhookURL string, req core.QARequest, streamingCard StreamingCardSender, eventQA EventQAAsker) error {
cardReq := CardRequest{
ConversationType: req.ConversationType,
ExternalUserID: req.ExternalUserID,
ExternalChatID: req.ExternalChatID,
Content: streamingPlaceholder,
}
outTrackID, err := streamingCard.StartCard(ctx, cardReq)
if err != nil {
log.Printf("DingTalk event card start failed, falling back to markdown")
result, askErr := h.qa.Ask(ctx, req)
if askErr != nil {
return h.sendReply(ctx, webhookURL, qaErrorReply)
}
return h.sendReply(ctx, webhookURL, result.Answer)
}
pump := newCardUpdatePump(ctx, h.cardUpdateInterval, func(updateCtx context.Context, content string) error {
return streamingCard.UpdateCard(updateCtx, outTrackID, content, false, false)
})
answerStarted := false
result, err := eventQA.AskEvents(ctx, req, func(event weknora.StreamEvent) {
if event.ResponseType == "answer" && strings.TrimSpace(event.FullAnswer) != "" {
answerStarted = true
pump.Offer(event.FullAnswer)
return
}
if answerStarted {
return
}
if content := renderProgressEvent(event); content != "" {
pump.Offer(content)
}
})
// Stop and drain the asynchronous worker before the synchronous final update
// so no stale progress/partial answer can overwrite the terminal card state.
pump.Stop()
if err != nil || strings.TrimSpace(result.Answer) == "" {
return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, qaErrorReply, true)
}
return h.finalizeCardOrMarkdown(ctx, webhookURL, streamingCard, outTrackID, result.Answer, false)
}
func (h *Handler) finalizeCardOrMarkdown(ctx context.Context, webhookURL string, streamingCard StreamingCardSender, outTrackID, content string, isError bool) error {
timeout := h.finalDeliveryTimeout
if timeout <= 0 {
timeout = defaultHTTPTimeout
}
// Final card convergence must still be attempted when the QA context was
// canceled or timed out; otherwise the card can remain "processing".
finalCtx, cancelFinal := context.WithTimeout(context.WithoutCancel(ctx), timeout)
updateErr := streamingCard.UpdateCard(finalCtx, outTrackID, content, true, isError)
cancelFinal()
if updateErr == nil {
return nil
}
// The card attempt may have consumed its entire deadline. Markdown must get
// a fresh delivery window rather than reusing the expired finalCtx.
fallbackCtx, cancelFallback := context.WithTimeout(context.WithoutCancel(ctx), timeout)
defer cancelFallback()
return h.sendReply(fallbackCtx, webhookURL, content)
}
func renderProgressEvent(event weknora.StreamEvent) string {
switch event.ResponseType {
case "tool_call":
switch strings.TrimSpace(event.ToolName) {
case "query_understand":
return "正在理解问题…"
case "knowledge_search":
return "正在检索知识库…"
}
case "tool_result":
switch strings.TrimSpace(event.ToolName) {
case "query_understand":
return "问题理解完成\n\n正在检索知识库…"
case "knowledge_search":
return "知识库检索完成\n\n正在生成答案…"
}
case "references":
return fmt.Sprintf("检索到 %d 条相关内容\n\n正在生成答案…", event.ReferenceCount)
}
return ""
}
func imageFailureStage(err error) string {
message := strings.ToLower(err.Error())
switch {
case strings.Contains(message, "oauth"):
return "oauth"
case strings.Contains(message, "api"):
return "file_api"
case strings.Contains(message, "unsafe") || strings.Contains(message, "destination"):
return "unsafe_url"
case strings.Contains(message, "format") || strings.Contains(message, "image data") || strings.Contains(message, "dimensions") || strings.Contains(message, "size limit"):
return "image_validation"
case strings.Contains(message, "request") || strings.Contains(message, "http") || strings.Contains(message, "read"):
return "image_fetch"
default:
return "unknown"
}
}
func (h *Handler) sendReply(ctx context.Context, webhookURL, text string) error {
if strings.TrimSpace(webhookURL) == "" {
return errors.New("dingtalk handler: sessionWebhook is required to reply")
}
if err := h.reply.SendMarkdown(ctx, webhookURL, replyTitle, text); err != nil {
return fmt.Errorf("dingtalk handler: send reply: %w", err)
}
return nil
}