feat: show async DingTalk card progress

This commit is contained in:
姚章浩
2026-07-20 23:22:07 +08:00
parent 65967118a0
commit cda192b8ab
4 changed files with 397 additions and 3 deletions
+91
View File
@@ -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
}
@@ -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:
}
}
+98 -3
View File
@@ -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 {
@@ -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)
}
}