diff --git a/internal/channels/dingtalk/card_pump.go b/internal/channels/dingtalk/card_pump.go new file mode 100644 index 0000000..dcdd22a --- /dev/null +++ b/internal/channels/dingtalk/card_pump.go @@ -0,0 +1,91 @@ +package dingtalk + +import ( + "context" + "log" + "sync" + "time" +) + +type cardPumpUpdate func(context.Context, string) error + +type cardUpdatePump struct { + updates chan string + stop chan struct{} + done chan struct{} + once sync.Once +} + +func newCardUpdatePump(ctx context.Context, interval time.Duration, update cardPumpUpdate) *cardUpdatePump { + if interval <= 0 { + interval = 500 * time.Millisecond + } + ticker := time.NewTicker(interval) + return newCardUpdatePumpWithTicks(ctx, ticker.C, ticker.Stop, update) +} + +func newCardUpdatePumpWithTicks(ctx context.Context, ticks <-chan time.Time, stopTicks func(), update cardPumpUpdate) *cardUpdatePump { + p := &cardUpdatePump{ + updates: make(chan string, 1), + stop: make(chan struct{}), + done: make(chan struct{}), + } + go p.run(ctx, ticks, stopTicks, update) + return p +} + +func (p *cardUpdatePump) run(ctx context.Context, ticks <-chan time.Time, stopTicks func(), update cardPumpUpdate) { + defer close(p.done) + if stopTicks != nil { + defer stopTicks() + } + for { + select { + case <-ctx.Done(): + return + case <-p.stop: + return + case <-ticks: + var latest string + select { + case latest = <-p.updates: + default: + continue + } + if err := update(ctx, latest); err != nil { + log.Printf("DingTalk async card update failed, continuing") + } + } + } +} + +// Offer replaces any pending content with the newest full card state. It never +// waits for DingTalk I/O, so the WeKnora SSE reader cannot be back-pressured by +// card delivery latency. +func (p *cardUpdatePump) Offer(content string) { + select { + case <-p.stop: + return + default: + } + select { + case p.updates <- content: + return + default: + } + select { + case <-p.updates: + default: + } + select { + case p.updates <- content: + case <-p.stop: + } +} + +// Stop prevents stale non-final updates from racing with the synchronous final +// card update and waits for any in-flight DingTalk request to finish. +func (p *cardUpdatePump) Stop() { + p.once.Do(func() { close(p.stop) }) + <-p.done +} diff --git a/internal/channels/dingtalk/card_pump_test.go b/internal/channels/dingtalk/card_pump_test.go new file mode 100644 index 0000000..4e4859b --- /dev/null +++ b/internal/channels/dingtalk/card_pump_test.go @@ -0,0 +1,109 @@ +package dingtalk + +import ( + "context" + "errors" + "testing" + "time" +) + +func waitPumpUpdate(t *testing.T, updates <-chan string) string { + t.Helper() + select { + case got := <-updates: + return got + case <-time.After(time.Second): + t.Fatal("timed out waiting for card pump update") + return "" + } +} + +func TestCardUpdatePumpCoalescesToLatestWithoutBlockingOffer(t *testing.T) { + ticks := make(chan time.Time, 2) + observed := make(chan string, 2) + pump := newCardUpdatePumpWithTicks(context.Background(), ticks, nil, func(_ context.Context, content string) error { + observed <- content + return nil + }) + defer pump.Stop() + + pump.Offer("one") + pump.Offer("two") + pump.Offer("latest") + ticks <- time.Now() + if got := waitPumpUpdate(t, observed); got != "latest" { + t.Fatalf("update=%q want latest", got) + } +} + +func TestCardUpdatePumpCoalescesWhileDingTalkRequestIsBlocked(t *testing.T) { + ticks := make(chan time.Time, 3) + started := make(chan string, 2) + release := make(chan struct{}) + pump := newCardUpdatePumpWithTicks(context.Background(), ticks, nil, func(_ context.Context, content string) error { + started <- content + <-release + return nil + }) + + pump.Offer("first") + ticks <- time.Now() + if got := waitPumpUpdate(t, started); got != "first" { + t.Fatalf("first update=%q", got) + } + + // These offers must not block behind the in-flight HTTP request and only the + // newest state should survive. + pump.Offer("second") + pump.Offer("third") + pump.Offer("newest") + close(release) + ticks <- time.Now() + if got := waitPumpUpdate(t, started); got != "newest" { + t.Fatalf("coalesced update=%q want newest", got) + } + pump.Stop() +} + +func TestCardUpdatePumpContinuesAfterUpdateError(t *testing.T) { + ticks := make(chan time.Time, 2) + calls := make(chan string, 2) + count := 0 + pump := newCardUpdatePumpWithTicks(context.Background(), ticks, nil, func(_ context.Context, content string) error { + count++ + calls <- content + if count == 1 { + return errors.New("token and content must not be logged") + } + return nil + }) + defer pump.Stop() + + pump.Offer("first") + ticks <- time.Now() + _ = waitPumpUpdate(t, calls) + pump.Offer("second") + ticks <- time.Now() + if got := waitPumpUpdate(t, calls); got != "second" { + t.Fatalf("second update=%q", got) + } +} + +func TestCardUpdatePumpStopDropsPendingAndIsIdempotent(t *testing.T) { + ticks := make(chan time.Time, 1) + observed := make(chan string, 1) + pump := newCardUpdatePumpWithTicks(context.Background(), ticks, nil, func(_ context.Context, content string) error { + observed <- content + return nil + }) + pump.Offer("stale") + pump.Stop() + pump.Stop() + pump.Offer("after-stop") + + select { + case got := <-observed: + t.Fatalf("unexpected update after stop: %q", got) + default: + } +} diff --git a/internal/channels/dingtalk/handler.go b/internal/channels/dingtalk/handler.go index 66d88c4..7a80145 100644 --- a/internal/channels/dingtalk/handler.go +++ b/internal/channels/dingtalk/handler.go @@ -23,7 +23,7 @@ const ( qaErrorReply = "抱歉,当前暂时无法完成回答,请稍后重试。" imageErrorReply = "图片识别暂时不可用,请稍后重试或发送文字。" imageQuery = "请描述并分析这张图片。" - streamingPlaceholder = "正在处理中…" + streamingPlaceholder = "正在理解问题…" ) type TenantConfig struct { @@ -55,6 +55,12 @@ type StreamingQAAsker interface { 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 } @@ -127,7 +133,7 @@ func NewHandlerWithOptions(cfg TenantConfig, qa QAAsker, reply MarkdownSender, o downloader: opts.ImageDownloader, card: opts.CardSender, now: time.Now, - cardUpdateInterval: 750 * time.Millisecond, + cardUpdateInterval: 500 * time.Millisecond, }, nil } @@ -205,7 +211,10 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error { return h.sendReply(ctx, webhookURL, unsupportedMessageReply) } - // Check streaming capability + 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) @@ -213,6 +222,18 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error { 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 { @@ -309,6 +330,80 @@ func (h *Handler) handleStreaming(ctx context.Context, webhookURL string, req co return nil } +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() + + finalCtx, cancelFinal := context.WithTimeout(context.WithoutCancel(ctx), defaultHTTPTimeout) + defer cancelFinal() + if err != nil || strings.TrimSpace(result.Answer) == "" { + if updateErr := streamingCard.UpdateCard(finalCtx, outTrackID, qaErrorReply, true, true); updateErr != nil { + return h.sendReply(finalCtx, webhookURL, qaErrorReply) + } + return nil + } + if updateErr := streamingCard.UpdateCard(finalCtx, outTrackID, result.Answer, true, false); updateErr != nil { + return h.sendReply(finalCtx, webhookURL, result.Answer) + } + return nil +} + +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 { diff --git a/internal/channels/dingtalk/handler_test.go b/internal/channels/dingtalk/handler_test.go index 8bf4477..e745992 100644 --- a/internal/channels/dingtalk/handler_test.go +++ b/internal/channels/dingtalk/handler_test.go @@ -1497,3 +1497,102 @@ func TestHandleStreamingGroupWithCard(t *testing.T) { t.Fatal("SendMarkdown must not be called") } } + +// --- A3.3: safe progress events + asynchronous card coalescing --- + +type fakeEventQA struct { + fakeStreamingQA + events []weknora.StreamEvent + eventCalled bool +} + +func (f *fakeEventQA) AskEvents(_ context.Context, req core.QARequest, observer weknora.StreamObserver) (core.QAResult, error) { + f.eventCalled = true + f.lastReq = req + for _, event := range f.events { + if observer != nil { + observer(event) + } + } + return f.result, f.err +} + +func TestRenderProgressEventUsesOnlySafeFixedText(t *testing.T) { + tests := []struct { + name string + event weknora.StreamEvent + want string + }{ + {"understanding", weknora.StreamEvent{ResponseType: "tool_call", ToolName: "query_understand"}, "正在理解问题…"}, + {"understood", weknora.StreamEvent{ResponseType: "tool_result", ToolName: "query_understand"}, "问题理解完成\n\n正在检索知识库…"}, + {"searching", weknora.StreamEvent{ResponseType: "tool_call", ToolName: "knowledge_search"}, "正在检索知识库…"}, + {"searched", weknora.StreamEvent{ResponseType: "tool_result", ToolName: "knowledge_search"}, "知识库检索完成\n\n正在生成答案…"}, + {"references", weknora.StreamEvent{ResponseType: "references", ReferenceCount: 7}, "已找到 7 篇相关文档\n\n正在生成答案…"}, + {"thinking hidden", weknora.StreamEvent{ResponseType: "thinking"}, ""}, + {"unknown tool hidden", weknora.StreamEvent{ResponseType: "tool_call", ToolName: "secret_tool"}, ""}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := renderProgressEvent(tt.event); got != tt.want { + t.Fatalf("renderProgressEvent=%q want %q", got, tt.want) + } + }) + } +} + +func TestHandleEventStreamingFinalizesLatestAnswerWithoutMarkdown(t *testing.T) { + card := &fakeStreamingCard{startID: "track-events"} + qa := &fakeEventQA{ + fakeStreamingQA: fakeStreamingQA{result: core.QAResult{Answer: "完整答案"}}, + events: []weknora.StreamEvent{ + {ResponseType: "tool_call", ToolName: "query_understand"}, + {ResponseType: "tool_call", ToolName: "knowledge_search"}, + {ResponseType: "references", ReferenceCount: 3}, + {ResponseType: "answer", FullAnswer: "部分"}, + {ResponseType: "answer", FullAnswer: "完整答案", Done: true}, + }, + } + reply := &fakeReply{} + h := newTestHandlerWithStreaming(t, qa, reply, card) + h.cardUpdateInterval = time.Hour + if err := h.Handle(context.Background(), directTextCallback()); err != nil { + t.Fatalf("Handle: %v", err) + } + if !qa.eventCalled || qa.streamCalled { + t.Fatalf("eventCalled=%v streamCalled=%v", qa.eventCalled, qa.streamCalled) + } + if card.startReq.Content != streamingPlaceholder { + t.Fatalf("placeholder=%q", card.startReq.Content) + } + if len(card.updates) != 1 { + t.Fatalf("stale async updates must be dropped before final: %+v", card.updates) + } + last := card.updates[0] + if last.content != "完整答案" || !last.isFinalize || last.isError { + t.Fatalf("final update=%+v", last) + } + if reply.called { + t.Fatal("SendMarkdown must not be called") + } +} + +func TestHandleEventStreamingErrorConvergesCard(t *testing.T) { + card := &fakeStreamingCard{startID: "track-event-error"} + qa := &fakeEventQA{ + fakeStreamingQA: fakeStreamingQA{err: errors.New("private upstream failure")}, + events: []weknora.StreamEvent{{ResponseType: "tool_call", ToolName: "knowledge_search"}, {ResponseType: "error", Done: true}}, + } + reply := &fakeReply{} + h := newTestHandlerWithStreaming(t, qa, reply, card) + h.cardUpdateInterval = time.Hour + if err := h.Handle(context.Background(), directTextCallback()); err != nil { + t.Fatalf("Handle: %v", err) + } + last := card.updates[len(card.updates)-1] + if last.content != qaErrorReply || !last.isFinalize || !last.isError { + t.Fatalf("error final=%+v", last) + } + if strings.Contains(last.content, "private") || reply.called { + t.Fatalf("error leaked or markdown duplicated: content=%q markdown=%v", last.content, reply.called) + } +}