feat: add streaming DingTalk AI cards #1

Merged
zheromiku merged 10 commits from feature/dingtalk-ai-card-streaming into feature/dingtalk-image-ingress 2026-07-21 00:11:25 +08:00
14 changed files with 4002 additions and 19 deletions
+5
View File
@@ -15,5 +15,10 @@ DINGTALK_CLIENT_SECRET=
# Tenant key this DingTalk ingress serves (matches tenant_key used by QA).
DOBOTAI_TENANT_KEY=
# Optional DingTalk AI card template ID. Leave empty to use markdown-only replies.
# When set, a successful QA answer will be delivered as an AI card; markdown
# is only sent as a fallback when card delivery fails. Never commit real values.
DINGTALK_CARD_TEMPLATE_ID=
# Independent DobotAI PostgreSQL; never point this at WeKnora's database
DATABASE_URL=postgres://dobotai:replace-me@127.0.0.1:5432/dobotai?sslmode=disable
+10 -2
View File
@@ -72,11 +72,19 @@ func main() {
if err != nil {
log.Fatal(err)
}
handler, err := dingtalk.NewHandler(
var cardSender dingtalk.FinalCardSender
if cardTemplateID := strings.TrimSpace(os.Getenv("DINGTALK_CARD_TEMPLATE_ID")); cardTemplateID != "" {
cs, err := dingtalk.NewCardSender(dingCfg.ClientID, dingCfg.ClientSecret, cardTemplateID, nil)
if err != nil {
log.Fatalf("DingTalk card sender init failed: %v", err)
}
cardSender = cs
}
handler, err := dingtalk.NewHandlerWithOptions(
dingtalk.TenantConfig{TenantKey: dingCfg.TenantKey, Channel: "dingtalk"},
qaService,
sender,
downloader,
dingtalk.HandlerOptions{ImageDownloader: downloader, CardSender: cardSender},
)
if err != nil {
log.Fatal(err)
+351
View File
@@ -0,0 +1,351 @@
package dingtalk
import (
"bytes"
"context"
"crypto/rand"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"strings"
"sync"
"time"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
)
const (
cardCreateURL = "https://api.dingtalk.com/v1.0/card/instances/createAndDeliver"
cardStreamingURL = "https://api.dingtalk.com/v1.0/card/streaming"
)
// CardRequest is the input for sending a final AI card.
type CardRequest struct {
ConversationType core.ConversationType
ExternalUserID string
ExternalChatID string
Content string
}
// CardSender sends DingTalk AI cards via the OpenAPI.
type CardSender struct {
clientID string
clientSecret string
cardTemplateID string
tokenURL string
createURL string
streamURL string
apiClient *http.Client
allowTestURL bool
mu sync.Mutex
token string
tokenTill time.Time
}
// NewCardSender creates a CardSender. All three config values are required
// after trimming whitespace. A nil http.Client installs a hardened default
// (no redirects, Proxy=nil, 15s timeout).
func NewCardSender(clientID, clientSecret, cardTemplateID string, client *http.Client) (*CardSender, error) {
return newCardSender(clientID, clientSecret, cardTemplateID, client, oauthTokenURL, cardCreateURL, cardStreamingURL, false)
}
// newCardSenderForTest is used by tests to inject httptest URLs.
func newCardSenderForTest(clientID, clientSecret, cardTemplateID string, client *http.Client, tokenURL, createURL string) (*CardSender, error) {
streamURL := strings.TrimSuffix(createURL, "/create") + "/stream"
return newCardSender(clientID, clientSecret, cardTemplateID, client, tokenURL, createURL, streamURL, true)
}
func newCardSender(clientID, clientSecret, cardTemplateID string, client *http.Client, tokenURL, createURL, streamURL string, allowTest bool) (*CardSender, error) {
clientID = strings.TrimSpace(clientID)
clientSecret = strings.TrimSpace(clientSecret)
cardTemplateID = strings.TrimSpace(cardTemplateID)
if clientID == "" {
return nil, errors.New("dingtalk card sender: clientID is required")
}
if clientSecret == "" {
return nil, errors.New("dingtalk card sender: clientSecret is required")
}
if cardTemplateID == "" {
return nil, errors.New("dingtalk card sender: cardTemplateID is required")
}
base := &http.Client{Timeout: 15 * time.Second}
if client != nil {
copyClient := *client
base = &copyClient
if base.Timeout <= 0 {
base.Timeout = 15 * time.Second
}
}
apiClient := *base
apiClient.CheckRedirect = func(*http.Request, []*http.Request) error {
return errors.New("dingtalk API redirect refused")
}
if !allowTest {
transport := http.DefaultTransport.(*http.Transport).Clone()
transport.Proxy = nil
apiClient.Transport = transport
}
return &CardSender{
clientID: clientID,
clientSecret: clientSecret,
cardTemplateID: cardTemplateID,
tokenURL: tokenURL,
createURL: createURL,
streamURL: streamURL,
apiClient: &apiClient,
allowTestURL: allowTest,
}, nil
}
// SendFinalCard sends the AI card to DingTalk and returns the generated outTrackID.
// It is a thin wrapper: StartCard → UpdateCard(finalize=true).
func (s *CardSender) SendFinalCard(ctx context.Context, req CardRequest) (string, error) {
outTrackID, err := s.StartCard(ctx, req)
if err != nil {
return "", err
}
if err := s.UpdateCard(ctx, outTrackID, req.Content, true, false); err != nil {
return "", err
}
return outTrackID, nil
}
// StartCard creates a card instance via createAndDeliver and returns the
// generated outTrackID. It does NOT call the streaming finalize endpoint;
// callers must use UpdateCard to stream content.
func (s *CardSender) StartCard(ctx context.Context, req CardRequest) (string, error) {
// Validate conversation type before any API call
if req.ConversationType != core.ConversationDirect && req.ConversationType != core.ConversationGroup {
return "", fmt.Errorf("dingtalk card: unsupported conversation type %q", req.ConversationType)
}
// Validate content
req.Content = strings.TrimSpace(req.Content)
if req.Content == "" {
return "", errors.New("dingtalk card: content is required")
}
if len(req.Content) > 64*1024 {
return "", errors.New("dingtalk card: content exceeds 64 KiB")
}
// Validate identity fields
if req.ConversationType == core.ConversationDirect {
req.ExternalUserID = strings.TrimSpace(req.ExternalUserID)
if req.ExternalUserID == "" {
return "", errors.New("dingtalk card: ExternalUserID is required for direct conversations")
}
} else {
req.ExternalChatID = strings.TrimSpace(req.ExternalChatID)
if req.ExternalChatID == "" {
return "", errors.New("dingtalk card: ExternalChatID is required for group conversations")
}
}
// Generate outTrackID
outTrackID, err := generateUUID()
if err != nil {
return "", fmt.Errorf("dingtalk card: generate outTrackId: %w", err)
}
// Build card body
body := s.buildCardBody(req, outTrackID)
// Get access token
token, err := s.accessToken(ctx)
if err != nil {
return "", err
}
// Send card (create only, no finalize)
if err := s.postCard(ctx, body, token); err != nil {
return "", err
}
return outTrackID, nil
}
// UpdateCard sends a streaming update to an existing card. outTrackID and
// content must be non-empty after trimming; content must not exceed 64 KiB.
// Set isFinalize=true to close the card; set isError=true to mark the card
// as an error state.
func (s *CardSender) UpdateCard(ctx context.Context, outTrackID, content string, isFinalize, isError bool) error {
outTrackID = strings.TrimSpace(outTrackID)
if outTrackID == "" {
return errors.New("dingtalk card: outTrackID is required")
}
content = strings.TrimSpace(content)
if content == "" {
return errors.New("dingtalk card: content is required")
}
if len(content) > 64*1024 {
return errors.New("dingtalk card: content exceeds 64 KiB")
}
token, err := s.accessToken(ctx)
if err != nil {
return err
}
return s.finalizeCard(ctx, outTrackID, content, token, isFinalize, isError)
}
func (s *CardSender) buildCardBody(req CardRequest, outTrackID string) map[string]any {
body := map[string]any{
"cardTemplateId": s.cardTemplateID,
"outTrackId": outTrackID,
"callbackType": "STREAM",
"cardData": map[string]any{
"cardParamMap": map[string]any{
"content": req.Content,
},
},
"userIdType": 1,
}
if req.ConversationType == core.ConversationDirect {
body["openSpaceId"] = "dtv1.card//IM_ROBOT." + req.ExternalUserID
body["imRobotOpenSpaceModel"] = map[string]any{
"supportForward": true,
}
body["imRobotOpenDeliverModel"] = map[string]any{
"robotCode": s.clientID,
"spaceType": "IM_ROBOT",
"extension": map[string]any{},
}
} else {
body["openSpaceId"] = "dtv1.card//IM_GROUP." + req.ExternalChatID
body["imGroupOpenSpaceModel"] = map[string]any{
"supportForward": true,
}
body["imGroupOpenDeliverModel"] = map[string]any{
"robotCode": s.clientID,
"extension": map[string]any{},
}
}
return body
}
func (s *CardSender) accessToken(ctx context.Context) (string, error) {
s.mu.Lock()
defer s.mu.Unlock()
if s.token != "" && time.Now().Before(s.tokenTill) {
return s.token, nil
}
payload, err := s.postJSON(ctx, s.tokenURL, map[string]string{
"appKey": s.clientID,
"appSecret": s.clientSecret,
}, "")
if err != nil {
return "", err
}
var response struct {
AccessToken string `json:"accessToken"`
ExpireIn int64 `json:"expireIn"`
}
if json.Unmarshal(payload, &response) != nil || strings.TrimSpace(response.AccessToken) == "" {
return "", errors.New("dingtalk card: invalid OAuth response")
}
ttl := time.Duration(response.ExpireIn) * time.Second
refreshAfter := ttl - 5*time.Minute
if refreshAfter <= 0 {
refreshAfter = ttl / 2
}
if refreshAfter <= 0 {
refreshAfter = time.Minute
}
s.token = response.AccessToken
s.tokenTill = time.Now().Add(refreshAfter)
return s.token, nil
}
func (s *CardSender) postCard(ctx context.Context, body map[string]any, token string) error {
payload, err := s.postJSON(ctx, s.createURL, body, token)
if err != nil {
return err
}
// Discard successful response body
if len(payload) > 0 {
// Body is already bounded by postJSON→readBoundedAPIResponse; just discard
}
return nil
}
func (s *CardSender) finalizeCard(ctx context.Context, outTrackID, content, token string, isFinalize, isError bool) error {
guid, err := generateUUID()
if err != nil {
return errors.New("dingtalk card: generate stream guid failed")
}
body := map[string]any{
"outTrackId": outTrackID,
"guid": guid,
"key": "content",
"content": content,
"isFull": true,
"isFinalize": isFinalize,
"isError": isError,
}
_, err = s.doJSON(ctx, http.MethodPut, s.streamURL, body, token)
return err
}
func (s *CardSender) postJSON(ctx context.Context, endpoint string, value any, token string) ([]byte, error) {
return s.doJSON(ctx, http.MethodPost, endpoint, value, token)
}
func (s *CardSender) doJSON(ctx context.Context, method, endpoint string, value any, token string) ([]byte, error) {
body, err := json.Marshal(value)
if err != nil {
return nil, errors.New("dingtalk card: encode API request failed")
}
req, err := http.NewRequestWithContext(ctx, method, endpoint, bytes.NewReader(body))
if err != nil {
return nil, errors.New("dingtalk card: create API request failed")
}
req.Header.Set("Content-Type", "application/json")
if token != "" {
req.Header.Set("x-acs-dingtalk-access-token", token)
}
resp, err := s.apiClient.Do(req)
if err != nil {
if ctx.Err() != nil {
return nil, ctx.Err()
}
return nil, errors.New("dingtalk card: API request failed")
}
defer resp.Body.Close()
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
// Discard body without reading it
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, maxAPIResponseBytes))
return nil, fmt.Errorf("dingtalk card: API HTTP %d", resp.StatusCode)
}
return readBoundedAPIResponse(resp)
}
// generateUUID creates a UUID v4 (random) using crypto/rand, formatted as
// lowercase hex with dashes: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
func generateUUID() (string, error) {
var b [16]byte
if _, err := rand.Read(b[:]); err != nil {
return "", err
}
// Set version 4
b[6] = (b[6] & 0x0f) | 0x40
// Set variant bits (10xx)
b[8] = (b[8] & 0x3f) | 0x80
return fmt.Sprintf("%x-%x-%x-%x-%x",
b[0:4], b[4:6], b[6:8], b[8:10], b[10:16]), nil
}
+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:
}
}
File diff suppressed because it is too large Load Diff
+248 -12
View File
@@ -6,8 +6,10 @@ import (
"fmt"
"log"
"strings"
"time"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/weknora"
)
const (
@@ -21,6 +23,7 @@ const (
qaErrorReply = "抱歉,当前暂时无法完成回答,请稍后重试。"
imageErrorReply = "图片识别暂时不可用,请稍后重试或发送文字。"
imageQuery = "请描述并分析这张图片。"
streamingPlaceholder = "正在理解问题…"
)
type TenantConfig struct {
@@ -46,6 +49,18 @@ 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
}
@@ -54,16 +69,52 @@ 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
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")
}
@@ -76,14 +127,16 @@ func NewHandler(cfg TenantConfig, qa QAAsker, reply MarkdownSender, downloaders
if reply == nil {
return nil, errors.New("dingtalk handler: markdown sender is required")
}
if len(downloaders) > 1 {
return nil, errors.New("dingtalk handler: at most one image downloader is allowed")
}
var downloader ImageDownloader
if len(downloaders) == 1 {
downloader = downloaders[0]
}
return &Handler{cfg: cfg, qa: qa, reply: reply, downloader: downloader}, nil
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 {
@@ -160,6 +213,42 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
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 {
@@ -167,9 +256,156 @@ func (h *Handler) Handle(ctx context.Context, cb BotCallback) error {
}
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 {
File diff suppressed because it is too large Load Diff
+254
View File
@@ -0,0 +1,254 @@
package qa
import (
"context"
"errors"
"testing"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/core"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/session"
"gitea.zheromiku.top/Weknora/dobotai-platform/internal/weknora"
)
type fakeEventStreamingWeKnora struct {
*fakeWeKnora
events []weknora.StreamEvent
streamResult weknora.ChatResult
streamErr error
streamCalls int
}
func (f *fakeEventStreamingWeKnora) AgentChatEvents(_ context.Context, _ string, request weknora.AgentChatRequest, observer weknora.StreamObserver) (weknora.ChatResult, error) {
f.streamCalls++
f.mu.Lock()
f.queries = append(f.queries, request.Query)
f.requests = append(f.requests, request)
f.mu.Unlock()
for _, e := range f.events {
if observer != nil {
observer(e)
}
}
return f.streamResult, f.streamErr
}
func TestAskEventsStreamFakeSequencePassesThroughAndSuccess(t *testing.T) {
repo := newMemoryRepository()
client := &fakeEventStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{},
events: []weknora.StreamEvent{
{ResponseType: "thinking"},
{ResponseType: "tool_call", ToolName: "query_understand"},
{ResponseType: "tool_result", ToolName: "query_understand"},
{ResponseType: "tool_call", ToolName: "knowledge_search"},
{ResponseType: "references", ReferenceCount: 3},
{ResponseType: "answer", FullAnswer: "hello ", Done: false},
{ResponseType: "answer", FullAnswer: "hello world", Done: true},
},
streamResult: weknora.ChatResult{RequestID: "request-1", Answer: "hello world", References: []core.Reference{{KnowledgeID: "kb-1"}}},
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []weknora.StreamEvent
req := streamQARequest("message-events")
result, err := service.AskEvents(context.Background(), req, func(e weknora.StreamEvent) {
observed = append(observed, e)
})
if err != nil {
t.Fatalf("AskEvents: %v", err)
}
if result.Replayed {
t.Fatal("should not be replay")
}
if result.Answer != "hello world" {
t.Fatalf("expected 'hello world', got %q", result.Answer)
}
if client.streamCalls != 1 {
t.Fatalf("expected 1 stream call, got %d", client.streamCalls)
}
if len(observed) != 7 {
t.Fatalf("expected 7 events, got %d: %+v", len(observed), observed)
}
// Verify sequence
expectedTypes := []string{"thinking", "tool_call", "tool_result", "tool_call", "references", "answer", "answer"}
for i, want := range expectedTypes {
if observed[i].ResponseType != want {
t.Fatalf("event[%d] ResponseType: want %q, got %q", i, want, observed[i].ResponseType)
}
}
// Verify turn persisted
repo.mu.Lock()
stored := repo.turns["tenant:dingtalk:message-events"]
repo.mu.Unlock()
if stored.Status != "succeeded" || stored.Answer != "hello world" {
t.Fatalf("stored=%+v", stored)
}
}
func TestAskEventsEventStreamErrorTurnFailed(t *testing.T) {
repo := newMemoryRepository()
client := &fakeEventStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{},
events: []weknora.StreamEvent{
{ResponseType: "answer", FullAnswer: "partial"},
{ResponseType: "error", Done: true},
},
streamErr: errors.New("stream failed"),
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []weknora.StreamEvent
_, err = service.AskEvents(context.Background(), streamQARequest("message-events-error"), func(e weknora.StreamEvent) {
observed = append(observed, e)
})
if err == nil {
t.Fatal("expected error")
}
if len(observed) != 2 {
t.Fatalf("expected 2 events before error, got %d: %+v", len(observed), observed)
}
// Turn must be failed
repo.mu.Lock()
stored := repo.turns["tenant:dingtalk:message-events-error"]
repo.mu.Unlock()
if stored.Status != "failed" || stored.Answer != "" {
t.Fatalf("expected failed turn without answer, got %+v", stored)
}
}
func TestAskEventsLegacyFallbackSingleAnswerEvent(t *testing.T) {
repo := newMemoryRepository()
// fakeWeKnora only implements AgentChat (no AgentChatStream, no AgentChatEvents)
client := &fakeWeKnora{}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []weknora.StreamEvent
req := streamQARequest("message-legacy-events")
result, err := service.AskEvents(context.Background(), req, func(e weknora.StreamEvent) {
observed = append(observed, e)
})
if err != nil {
t.Fatalf("AskEvents legacy: %v", err)
}
if result.Answer != "answer" {
t.Fatalf("expected 'answer', got %q", result.Answer)
}
// Legacy fallback: single final answer event
if len(observed) != 1 {
t.Fatalf("expected 1 legacy event, got %d: %+v", len(observed), observed)
}
if observed[0].ResponseType != "answer" || observed[0].FullAnswer != "answer" || !observed[0].Done {
t.Fatalf("legacy event should be answer done: %+v", observed[0])
}
}
func TestAskEventsDuplicateReplayZeroEvents(t *testing.T) {
repo := newMemoryRepository()
client := &fakeEventStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{},
events: []weknora.StreamEvent{
{ResponseType: "answer", FullAnswer: "answer", Done: true},
},
streamResult: weknora.ChatResult{RequestID: "request-1", Answer: "answer"},
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
req := streamQARequest("message-events-replay")
// First call
firstEvents := 0
if _, err := service.AskEvents(context.Background(), req, func(weknora.StreamEvent) { firstEvents++ }); err != nil {
t.Fatalf("first AskEvents: %v", err)
}
// Second call — replay
secondEvents := 0
result, err := service.AskEvents(context.Background(), req, func(weknora.StreamEvent) { secondEvents++ })
if err != nil {
t.Fatalf("replay AskEvents: %v", err)
}
if !result.Replayed {
t.Fatal("expected replay")
}
if secondEvents != 0 {
t.Fatalf("replay must not notify events, got %d", secondEvents)
}
if firstEvents != 1 {
t.Fatalf("first call expected 1 event, got %d", firstEvents)
}
if client.streamCalls != 1 {
t.Fatalf("expected 1 weknora call, got %d", client.streamCalls)
}
}
func TestAskEventsStreamingFallbackFromAgentChatStream(t *testing.T) {
repo := newMemoryRepository()
// Client has AgentChatStream but not AgentChatEvents
client := &fakeStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{},
updates: []string{"hello ", "hello world"},
streamResult: weknora.ChatResult{RequestID: "request-1", Answer: "hello world", References: []core.Reference{{KnowledgeID: "kb-1"}}},
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []weknora.StreamEvent
req := streamQARequest("message-stream-fallback")
result, err := service.AskEvents(context.Background(), req, func(e weknora.StreamEvent) {
observed = append(observed, e)
})
if err != nil {
t.Fatalf("AskEvents stream fallback: %v", err)
}
if result.Answer != "hello world" {
t.Fatalf("expected 'hello world', got %q", result.Answer)
}
// Each answer observer callback becomes a StreamEvent with FullAnswer
if len(observed) != 2 {
t.Fatalf("expected 2 events from stream fallback, got %d: %+v", len(observed), observed)
}
if observed[0].ResponseType != "answer" || observed[0].FullAnswer != "hello " || observed[0].Done {
t.Fatalf("event[0]: %+v", observed[0])
}
if observed[1].ResponseType != "answer" || observed[1].FullAnswer != "hello world" || observed[1].Done {
t.Fatalf("event[1]: %+v", observed[1])
}
// Turn persisted
repo.mu.Lock()
stored := repo.turns["tenant:dingtalk:message-stream-fallback"]
repo.mu.Unlock()
if stored.Status != "succeeded" || stored.Answer != "hello world" {
t.Fatalf("stored=%+v", stored)
}
}
// TestAskStreamOldRegression verifies the old AskStream still works after refactoring.
func TestAskStreamOldRegression(t *testing.T) {
repo := newMemoryRepository()
client := &fakeStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{}, updates: []string{"hello ", "hello world"},
streamResult: weknora.ChatResult{RequestID: "request-stream", Answer: "hello world", References: []core.Reference{{KnowledgeID: "kb-1"}}},
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []string
result, err := service.AskStream(context.Background(), streamQARequest("message-stream-regression"), func(full string) { observed = append(observed, full) })
if err != nil {
t.Fatalf("AskStream: %v", err)
}
if len(observed) != 2 || observed[0] != "hello " || observed[1] != "hello world" {
t.Fatalf("observed=%v", observed)
}
if result.Answer != "hello world" || result.WeKnoraRequestID != "request-stream" || client.streamCalls != 1 {
t.Fatalf("result=%+v streamCalls=%d", result, client.streamCalls)
}
}
+66 -2
View File
@@ -22,6 +22,14 @@ type WeKnora interface {
AgentChat(ctx context.Context, sessionID string, request weknora.AgentChatRequest) (weknora.ChatResult, error)
}
type streamingWeKnora interface {
AgentChatStream(ctx context.Context, sessionID string, request weknora.AgentChatRequest, observer weknora.AnswerObserver) (weknora.ChatResult, error)
}
type eventStreamingWeKnora interface {
AgentChatEvents(ctx context.Context, sessionID string, request weknora.AgentChatRequest, observer weknora.StreamObserver) (weknora.ChatResult, error)
}
type Service struct {
repository core.Repository
agents AgentResolver
@@ -40,6 +48,18 @@ func New(repository core.Repository, agents AgentResolver, client WeKnora, group
}
func (s *Service) Ask(ctx context.Context, request core.QARequest) (core.QAResult, error) {
return s.ask(ctx, request, nil, nil)
}
func (s *Service) AskStream(ctx context.Context, request core.QARequest, observer weknora.AnswerObserver) (core.QAResult, error) {
return s.ask(ctx, request, observer, nil)
}
func (s *Service) AskEvents(ctx context.Context, request core.QARequest, observer weknora.StreamObserver) (core.QAResult, error) {
return s.ask(ctx, request, nil, observer)
}
func (s *Service) ask(ctx context.Context, request core.QARequest, answerObserver weknora.AnswerObserver, eventObserver weknora.StreamObserver) (core.QAResult, error) {
if err := validateRequest(request); err != nil {
return core.QAResult{}, err
}
@@ -102,10 +122,54 @@ func (s *Service) Ask(ctx context.Context, request core.QARequest) (core.QAResul
for _, image := range request.Images {
images = append(images, weknora.Image{Data: image.DataURI})
}
chat, err := s.weknora.AgentChat(ctx, sessionID, weknora.AgentChatRequest{
chatRequest := weknora.AgentChatRequest{
Query: query, AgentID: agentID, AgentEnabled: true, Channel: "im", EnableMemory: true,
Images: images,
})
}
var chat weknora.ChatResult
if eventObserver != nil {
// Prefer AgentChatEvents; fallback to AgentChatStream adaptation; then AgentChat.
if eventStream, ok := s.weknora.(eventStreamingWeKnora); ok {
chat, err = eventStream.AgentChatEvents(ctx, sessionID, chatRequest, eventObserver)
} else if streaming, ok := s.weknora.(streamingWeKnora); ok {
// Adapt AgentChatStream answer chunks to StreamEvent
chat, err = streaming.AgentChatStream(ctx, sessionID, chatRequest, func(full string) {
if answerObserver != nil {
answerObserver(full)
}
eventObserver(weknora.StreamEvent{
ResponseType: "answer",
FullAnswer: full,
})
})
} else {
chat, err = s.weknora.AgentChat(ctx, sessionID, chatRequest)
if err == nil && strings.TrimSpace(chat.Answer) != "" {
if answerObserver != nil {
answerObserver(chat.Answer)
}
eventObserver(weknora.StreamEvent{
ResponseType: "answer",
FullAnswer: chat.Answer,
Done: true,
})
}
}
} else if answerObserver != nil {
if streaming, ok := s.weknora.(streamingWeKnora); ok {
chat, err = streaming.AgentChatStream(ctx, sessionID, chatRequest, answerObserver)
} else {
chat, err = s.weknora.AgentChat(ctx, sessionID, chatRequest)
if err == nil && strings.TrimSpace(chat.Answer) != "" {
answerObserver(chat.Answer)
}
}
} else {
chat, err = s.weknora.AgentChat(ctx, sessionID, chatRequest)
}
if err == nil && strings.TrimSpace(chat.Answer) == "" {
err = weknora.ErrEmptyAnswer
}
if err != nil {
turn.Status, turn.ErrorMessage = "failed", err.Error()
_ = s.repository.FinishTurn(ctx, turn)
+123
View File
@@ -2,6 +2,7 @@ package qa
import (
"context"
"errors"
"sync"
"testing"
@@ -80,6 +81,28 @@ func (f *fakeWeKnora) AgentChat(_ context.Context, sessionID string, request wek
return weknora.ChatResult{RequestID: "request-1", Answer: "answer", References: []core.Reference{{KnowledgeID: "kb-1"}}}, nil
}
type fakeStreamingWeKnora struct {
*fakeWeKnora
updates []string
streamResult weknora.ChatResult
streamErr error
streamCalls int
}
func (f *fakeStreamingWeKnora) AgentChatStream(_ context.Context, _ string, request weknora.AgentChatRequest, observer weknora.AnswerObserver) (weknora.ChatResult, error) {
f.streamCalls++
f.mu.Lock()
f.queries = append(f.queries, request.Query)
f.requests = append(f.requests, request)
f.mu.Unlock()
for _, update := range f.updates {
if observer != nil {
observer(update)
}
}
return f.streamResult, f.streamErr
}
func TestAskUsesSharedGroupSessionAndReplaysDuplicate(t *testing.T) {
repo := newMemoryRepository()
client := &fakeWeKnora{}
@@ -238,3 +261,103 @@ func TestAskDuplicateReplayDoesNotCallWeKnoraAgain(t *testing.T) {
t.Fatalf("replay must preserve Turn.Media: %+v", stored.Media)
}
}
func streamQARequest(messageID string) core.QARequest {
return core.QARequest{
TenantKey: "tenant", Channel: "dingtalk", ConversationType: core.ConversationDirect,
ExternalUserID: "user-1", ExternalMessageID: messageID, Query: "question",
}
}
func TestAskStreamUsesStreamingObserverAndPersistsFinal(t *testing.T) {
repo := newMemoryRepository()
client := &fakeStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{}, updates: []string{"hello ", "hello world"},
streamResult: weknora.ChatResult{RequestID: "request-stream", Answer: "hello world", References: []core.Reference{{KnowledgeID: "kb-1"}}},
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []string
result, err := service.AskStream(context.Background(), streamQARequest("message-stream"), func(full string) { observed = append(observed, full) })
if err != nil {
t.Fatalf("AskStream: %v", err)
}
if len(observed) != 2 || observed[0] != "hello " || observed[1] != "hello world" {
t.Fatalf("observed=%v", observed)
}
if result.Answer != "hello world" || result.WeKnoraRequestID != "request-stream" || client.streamCalls != 1 {
t.Fatalf("result=%+v streamCalls=%d", result, client.streamCalls)
}
repo.mu.Lock()
stored := repo.turns["tenant:dingtalk:message-stream"]
repo.mu.Unlock()
if stored.Status != "succeeded" || stored.Answer != "hello world" {
t.Fatalf("stored=%+v", stored)
}
}
func TestAskStreamFailurePersistsFailedWithoutPartialAnswer(t *testing.T) {
repo := newMemoryRepository()
client := &fakeStreamingWeKnora{fakeWeKnora: &fakeWeKnora{}, updates: []string{"partial"}, streamErr: errors.New("stream failed")}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []string
_, err = service.AskStream(context.Background(), streamQARequest("message-stream-error"), func(full string) { observed = append(observed, full) })
if err == nil {
t.Fatal("expected stream error")
}
if len(observed) != 1 || observed[0] != "partial" {
t.Fatalf("observed=%v", observed)
}
repo.mu.Lock()
stored := repo.turns["tenant:dingtalk:message-stream-error"]
repo.mu.Unlock()
if stored.Status != "failed" || stored.Answer != "" {
t.Fatalf("partial answer must not be persisted as success: %+v", stored)
}
}
func TestAskStreamFallsBackToFinalObserverForLegacyClient(t *testing.T) {
repo := newMemoryRepository()
client := &fakeWeKnora{}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
var observed []string
result, err := service.AskStream(context.Background(), streamQARequest("message-legacy"), func(full string) { observed = append(observed, full) })
if err != nil {
t.Fatalf("AskStream: %v", err)
}
if result.Answer != "answer" || len(observed) != 1 || observed[0] != "answer" {
t.Fatalf("result=%+v observed=%v", result, observed)
}
}
func TestAskStreamDuplicateReplayDoesNotNotifyAgain(t *testing.T) {
repo := newMemoryRepository()
client := &fakeStreamingWeKnora{
fakeWeKnora: &fakeWeKnora{}, updates: []string{"answer"},
streamResult: weknora.ChatResult{RequestID: "request-stream", Answer: "answer"},
}
service, err := New(repo, fixedResolver{}, client, session.GroupShared)
if err != nil {
t.Fatal(err)
}
req := streamQARequest("message-stream-replay")
if _, err = service.AskStream(context.Background(), req, func(string) {}); err != nil {
t.Fatalf("first AskStream: %v", err)
}
secondCalls := 0
result, err := service.AskStream(context.Background(), req, func(string) { secondCalls++ })
if err != nil {
t.Fatalf("replay AskStream: %v", err)
}
if !result.Replayed || secondCalls != 0 || client.streamCalls != 1 {
t.Fatalf("result=%+v secondCalls=%d streamCalls=%d", result, secondCalls, client.streamCalls)
}
}
+111 -1
View File
@@ -17,6 +17,25 @@ import (
)
var ErrIncompleteStream = errors.New("weknora stream ended without a terminal event")
var ErrEmptyAnswer = errors.New("weknora stream completed with an empty answer")
// AnswerObserver is called with the accumulated full answer content after each
// answer chunk. The observer is purely a notification; its return is ignored.
type AnswerObserver func(fullContent string)
// StreamEvent is a safe, structured representation of a WeKnora streaming event.
// It deliberately does not expose raw Content, Data, or Reference content to
// prevent leaking internal thinking/tool details to external channels.
type StreamEvent struct {
ResponseType string
Done bool
FullAnswer string
ReferenceCount int
ToolName string
}
// StreamObserver is called with a safe StreamEvent for each SSE event.
type StreamObserver func(StreamEvent)
type Client struct {
baseURL string
@@ -78,6 +97,18 @@ func (c *Client) CreateSession(ctx context.Context, title, description string) (
}
func (c *Client) AgentChat(ctx context.Context, sessionID string, request AgentChatRequest) (ChatResult, error) {
return c.AgentChatStream(ctx, sessionID, request, nil)
}
func (c *Client) AgentChatStream(ctx context.Context, sessionID string, request AgentChatRequest, observer AnswerObserver) (ChatResult, error) {
return c.agentChat(ctx, sessionID, request, observer, nil)
}
func (c *Client) AgentChatEvents(ctx context.Context, sessionID string, request AgentChatRequest, observer StreamObserver) (ChatResult, error) {
return c.agentChat(ctx, sessionID, request, nil, observer)
}
func (c *Client) agentChat(ctx context.Context, sessionID string, request AgentChatRequest, answerObserver AnswerObserver, eventObserver StreamObserver) (ChatResult, error) {
if strings.TrimSpace(sessionID) == "" || strings.TrimSpace(request.AgentID) == "" || strings.TrimSpace(request.Query) == "" {
return ChatResult{}, errors.New("session id, agent id and query are required")
}
@@ -102,7 +133,7 @@ func (c *Client) AgentChat(ctx context.Context, sessionID string, request AgentC
message, _ := io.ReadAll(io.LimitReader(resp.Body, 32<<10))
return ChatResult{}, fmt.Errorf("weknora agent chat returned HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(message)))
}
return parseSSE(resp.Body)
return parseSSEWithEventObserver(resp.Body, answerObserver, eventObserver)
}
func (c *Client) doJSON(ctx context.Context, method, path string, input, output any) error {
@@ -132,12 +163,26 @@ func (c *Client) doJSON(ctx context.Context, method, path string, input, output
}
func parseSSE(reader io.Reader) (ChatResult, error) {
return parseSSEWithEventObserver(reader, nil, nil)
}
func parseSSEWithObserver(reader io.Reader, observer AnswerObserver) (ChatResult, error) {
return parseSSEWithEventObserver(reader, observer, nil)
}
func parseSSEWithEventObserver(reader io.Reader, answerObserver AnswerObserver, eventObserver StreamObserver) (ChatResult, error) {
scanner := bufio.NewScanner(reader)
scanner.Buffer(make([]byte, 64<<10), 2<<20)
var result ChatResult
var dataLines []string
terminal := false
notify := func(e StreamEvent) {
if eventObserver != nil {
eventObserver(e)
}
}
flush := func() error {
if len(dataLines) == 0 {
return nil
@@ -150,6 +195,7 @@ func parseSSE(reader io.Reader) (ChatResult, error) {
Content string `json:"content"`
Done bool `json:"done"`
KnowledgeReferences []core.Reference `json:"knowledge_references"`
Data json.RawMessage `json:"data"`
}
if err := json.Unmarshal([]byte(raw), &event); err != nil {
return fmt.Errorf("decode weknora SSE event: %w", err)
@@ -160,8 +206,21 @@ func parseSSE(reader io.Reader) (ChatResult, error) {
switch event.ResponseType {
case "references":
result.References = append([]core.Reference(nil), event.KnowledgeReferences...)
notify(StreamEvent{
ResponseType: "references",
ReferenceCount: len(event.KnowledgeReferences),
})
case "answer":
hasContent := strings.TrimSpace(event.Content) != ""
result.Answer += event.Content
if hasContent && answerObserver != nil {
answerObserver(result.Answer)
}
notify(StreamEvent{
ResponseType: "answer",
Done: event.Done,
FullAnswer: result.Answer,
})
if event.Done {
terminal = true
}
@@ -169,11 +228,37 @@ func parseSSE(reader io.Reader) (ChatResult, error) {
if event.Content == "" {
event.Content = "weknora returned an unspecified error"
}
// Notify with error type but no content, then return the error
notify(StreamEvent{
ResponseType: "error",
Done: true,
})
return errors.New(event.Content)
case "thinking", "reflection":
notify(StreamEvent{
ResponseType: event.ResponseType,
Done: event.Done,
})
case "tool_call", "tool_result":
toolName := extractToolName(event.Data)
notify(StreamEvent{
ResponseType: event.ResponseType,
Done: event.Done,
ToolName: toolName,
})
case "complete":
if event.Done {
terminal = true
}
notify(StreamEvent{
ResponseType: "complete",
Done: event.Done,
})
default:
notify(StreamEvent{
ResponseType: event.ResponseType,
Done: event.Done,
})
}
return nil
}
@@ -199,5 +284,30 @@ func parseSSE(reader io.Reader) (ChatResult, error) {
if !terminal {
return ChatResult{}, ErrIncompleteStream
}
if strings.TrimSpace(result.Answer) == "" {
return ChatResult{}, ErrEmptyAnswer
}
return result, nil
}
// extractToolName extracts the tool_name string from a JSON Data field.
// The Data may be any JSON shape; we look for the "tool_name" key and return
// its string value. Returns empty string if not found or not a string.
func extractToolName(data json.RawMessage) string {
if len(data) == 0 {
return ""
}
var m map[string]json.RawMessage
if err := json.Unmarshal(data, &m); err != nil {
return ""
}
v, ok := m["tool_name"]
if !ok {
return ""
}
var s string
if err := json.Unmarshal(v, &s); err != nil {
return ""
}
return s
}
+134
View File
@@ -84,6 +84,140 @@ func TestAgentChatRequestJSONSerializesImages(t *testing.T) {
}
}
func TestParseSSEWithObserverAnswerChunks(t *testing.T) {
stream := "data: {\"response_type\":\"answer\",\"content\":\"hello \",\"done\":false}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"world\",\"done\":true}\n\n"
var observed []string
result, err := parseSSEWithObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.Answer != "hello world" {
t.Fatalf("expected 'hello world', got %q", result.Answer)
}
if len(observed) != 2 || observed[0] != "hello " || observed[1] != "hello world" {
t.Fatalf("unexpected observed: %v", observed)
}
}
func TestParseSSEWithObserverReferencesDoesNotTrigger(t *testing.T) {
stream := "data: {\"response_type\":\"references\",\"knowledge_references\":[{\"knowledge_id\":\"kb-1\",\"content\":\"ref\"}]}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"x\",\"done\":true}\n\n"
var observed []string
_, err := parseSSEWithObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if len(observed) != 1 || observed[0] != "x" {
t.Fatalf("references should not trigger observer, got %v", observed)
}
}
func TestParseSSEWithObserverDoneEmptyChunk(t *testing.T) {
// done=true but content empty — should mark terminal but not trigger observer
stream := "data: {\"response_type\":\"answer\",\"content\":\"hello\",\"done\":false}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"\",\"done\":true}\n\n"
var observed []string
result, err := parseSSEWithObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.Answer != "hello" {
t.Fatalf("expected 'hello', got %q", result.Answer)
}
if len(observed) != 1 || observed[0] != "hello" {
t.Fatalf("done empty chunk should not trigger observer, got %v", observed)
}
}
func TestParseSSEWithObserverTerminalEmptyAnswer(t *testing.T) {
stream := "data: {\"response_type\":\"answer\",\"content\":\"\",\"done\":true}\n\n"
var observed []string
_, err := parseSSEWithObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
})
if !errors.Is(err, ErrEmptyAnswer) {
t.Fatalf("expected ErrEmptyAnswer, got %v", err)
}
if len(observed) != 0 {
t.Fatalf("empty answer should not trigger observer, got %v", observed)
}
}
func TestParseSSEWithObserverErrorDominatesPartial(t *testing.T) {
stream := "data: {\"response_type\":\"answer\",\"content\":\"partial\",\"done\":false}\n\n" +
"data: {\"response_type\":\"error\",\"content\":\"boom\",\"done\":true}\n\n"
var observed []string
_, err := parseSSEWithObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
})
if err == nil || !strings.Contains(err.Error(), "boom") {
t.Fatalf("expected error containing 'boom', got %v", err)
}
// observer should have been called once with "partial" before the error
if len(observed) != 1 || observed[0] != "partial" {
t.Fatalf("expected observer called with 'partial', got %v", observed)
}
}
func TestAgentChatStreamCallsObserver(t *testing.T) {
mux := http.NewServeMux()
mux.HandleFunc("/api/v1/agent-chat/session-1", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
_, _ = w.Write([]byte("data: {\"response_type\":\"answer\",\"content\":\"hello \",\"done\":false}\n\n"))
_, _ = w.Write([]byte("data: {\"response_type\":\"answer\",\"content\":\"world\",\"done\":true}\n\n"))
})
server := httptest.NewServer(mux)
defer server.Close()
client, err := NewClient(server.URL, "test-key", 5*time.Second)
if err != nil {
t.Fatalf("NewClient: %v", err)
}
var observed []string
result, err := client.AgentChatStream(context.Background(), "session-1",
AgentChatRequest{Query: "q", AgentID: "agent-1", Channel: "im"},
func(full string) { observed = append(observed, full) })
if err != nil {
t.Fatalf("AgentChatStream: %v", err)
}
if result.Answer != "hello world" {
t.Fatalf("expected 'hello world', got %q", result.Answer)
}
if len(observed) != 2 || observed[0] != "hello " || observed[1] != "hello world" {
t.Fatalf("unexpected observed: %v", observed)
}
}
func TestAgentChatStreamNilObserver(t *testing.T) {
mux := http.NewServeMux()
mux.HandleFunc("/api/v1/agent-chat/session-1", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
_, _ = w.Write([]byte("data: {\"response_type\":\"answer\",\"content\":\"hello\",\"done\":true}\n\n"))
})
server := httptest.NewServer(mux)
defer server.Close()
client, err := NewClient(server.URL, "test-key", 5*time.Second)
if err != nil {
t.Fatalf("NewClient: %v", err)
}
result, err := client.AgentChatStream(context.Background(), "session-1",
AgentChatRequest{Query: "q", AgentID: "agent-1", Channel: "im"}, nil)
if err != nil {
t.Fatalf("AgentChatStream with nil observer: %v", err)
}
if result.Answer != "hello" {
t.Fatalf("expected 'hello', got %q", result.Answer)
}
}
func TestAgentChatRequestJSONOmitsEmptyImages(t *testing.T) {
req := AgentChatRequest{
Query: "hello",
+269
View File
@@ -0,0 +1,269 @@
package weknora
import (
"context"
"errors"
"net/http"
"net/http/httptest"
"strings"
"testing"
"time"
)
// TestStreamEventSequence verifies the full event sequence:
// thinking → tool_call(query_understand) → tool_result → tool_call(knowledge_search) →
// references(count=3) → answer cumulative → answer done.
// It also asserts that no thinking/tool content leaks into StreamEvent (type has no Content field).
func TestStreamEventSequence(t *testing.T) {
stream := "data: {\"response_type\":\"thinking\",\"content\":\"inner monologue\",\"done\":false}\n\n" +
"data: {\"response_type\":\"tool_call\",\"data\":{\"tool_name\":\"query_understand\",\"arguments\":{\"query\":\"test\"}},\"done\":false}\n\n" +
"data: {\"response_type\":\"tool_result\",\"data\":{\"tool_name\":\"query_understand\",\"result\":\"understood\"},\"done\":false}\n\n" +
"data: {\"response_type\":\"tool_call\",\"data\":{\"tool_name\":\"knowledge_search\",\"arguments\":{\"query\":\"test\"}},\"done\":false}\n\n" +
"data: {\"response_type\":\"references\",\"knowledge_references\":[{\"knowledge_id\":\"kb-1\",\"content\":\"ref1\"},{\"knowledge_id\":\"kb-2\",\"content\":\"ref2\"},{\"knowledge_id\":\"kb-3\",\"content\":\"ref3\"}]}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"hello \",\"done\":false}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"world\",\"done\":true}\n\n"
var events []StreamEvent
result, err := parseSSEWithEventObserver(strings.NewReader(stream), nil, func(e StreamEvent) {
events = append(events, e)
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.Answer != "hello world" {
t.Fatalf("expected 'hello world', got %q", result.Answer)
}
if len(result.References) != 3 {
t.Fatalf("expected 3 references, got %d", len(result.References))
}
// Expected sequence: thinking, tool_call(query_understand), tool_result, tool_call(knowledge_search), references, answer(hello ), answer(hello world)
expectedTypes := []string{"thinking", "tool_call", "tool_result", "tool_call", "references", "answer", "answer"}
if len(events) != len(expectedTypes) {
t.Fatalf("expected %d events, got %d: %+v", len(expectedTypes), len(events), events)
}
for i, want := range expectedTypes {
if events[i].ResponseType != want {
t.Fatalf("event[%d] ResponseType: want %q, got %q", i, want, events[i].ResponseType)
}
}
// thinking: must not carry Content
if events[0].ToolName != "" || events[0].FullAnswer != "" || events[0].ReferenceCount != 0 {
t.Fatalf("thinking event must not leak content: %+v", events[0])
}
// tool_call(query_understand): ToolName must be "query_understand"
if events[1].ToolName != "query_understand" {
t.Fatalf("tool_call expected ToolName 'query_understand', got %q", events[1].ToolName)
}
if events[1].FullAnswer != "" || events[1].ReferenceCount != 0 {
t.Fatalf("tool_call must not leak other fields: %+v", events[1])
}
// tool_result: ToolName must be "query_understand"
if events[2].ToolName != "query_understand" {
t.Fatalf("tool_result expected ToolName 'query_understand', got %q", events[2].ToolName)
}
// tool_call(knowledge_search): ToolName must be "knowledge_search"
if events[3].ToolName != "knowledge_search" {
t.Fatalf("tool_call expected ToolName 'knowledge_search', got %q", events[3].ToolName)
}
// references: ReferenceCount must be 3
if events[4].ReferenceCount != 3 {
t.Fatalf("references expected ReferenceCount=3, got %d", events[4].ReferenceCount)
}
// answer(hello): Done=false, FullAnswer="hello "
if events[5].FullAnswer != "hello " || events[5].Done {
t.Fatalf("answer chunk 1: expected FullAnswer='hello ' Done=false, got %+v", events[5])
}
// answer(hello world): Done=true, FullAnswer="hello world"
if events[6].FullAnswer != "hello world" || !events[6].Done {
t.Fatalf("answer chunk 2: expected FullAnswer='hello world' Done=true, got %+v", events[6])
}
// Verify no event has any raw content field (StreamEvent struct has no Content/Data field)
// This is a compile-time guarantee — if StreamEvent had Content, we'd have a compilation error.
// Runtime: ensure events don't leak thinking content or tool Data content.
for i, e := range events {
if e.ResponseType == "thinking" && e.FullAnswer != "" {
t.Fatalf("event[%d]: thinking must not leak content", i)
}
}
}
// TestStreamEventErrorDoesNotLeakContent verifies error events notify but do not expose error content.
func TestStreamEventErrorDoesNotLeakContent(t *testing.T) {
stream := "data: {\"response_type\":\"answer\",\"content\":\"partial\",\"done\":false}\n\n" +
"data: {\"response_type\":\"error\",\"content\":\"secret internal error details\",\"done\":true}\n\n"
var events []StreamEvent
_, err := parseSSEWithEventObserver(strings.NewReader(stream), nil, func(e StreamEvent) {
events = append(events, e)
})
if err == nil {
t.Fatal("expected error from error event")
}
// The error event notification should have been sent before the error returned.
// It should only have ResponseType="error" and Done=true, no Content.
if len(events) < 2 {
t.Fatalf("expected at least 2 events (answer + error notification), got %d: %+v", len(events), events)
}
last := events[len(events)-1]
if last.ResponseType != "error" {
t.Fatalf("expected last event to be error, got %+v", last)
}
if !last.Done {
t.Fatal("error event should have Done=true")
}
// Error content must NOT leak into the event
if last.FullAnswer != "" || last.ToolName != "" || last.ReferenceCount != 0 {
t.Fatalf("error event must not leak content: %+v", last)
}
}
// TestStreamEventAnswerObserverRegression verifies the old AnswerObserver still works correctly.
func TestStreamEventAnswerObserverRegression(t *testing.T) {
stream := "data: {\"response_type\":\"answer\",\"content\":\"hello \",\"done\":false}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"world\",\"done\":true}\n\n"
var observed []string
result, err := parseSSEWithEventObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
}, nil)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.Answer != "hello world" {
t.Fatalf("expected 'hello world', got %q", result.Answer)
}
if len(observed) != 2 || observed[0] != "hello " || observed[1] != "hello world" {
t.Fatalf("unexpected observed: %v", observed)
}
}
// TestStreamEventAnswerObserverDoneEmptyChunk verifies done empty chunk
// notifies StreamEvent but does NOT trigger old AnswerObserver.
func TestStreamEventAnswerObserverDoneEmptyChunk(t *testing.T) {
stream := "data: {\"response_type\":\"answer\",\"content\":\"hello\",\"done\":false}\n\n" +
"data: {\"response_type\":\"answer\",\"content\":\"\",\"done\":true}\n\n"
var observed []string
var events []StreamEvent
result, err := parseSSEWithEventObserver(strings.NewReader(stream), func(full string) {
observed = append(observed, full)
}, func(e StreamEvent) {
events = append(events, e)
})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if result.Answer != "hello" {
t.Fatalf("expected 'hello', got %q", result.Answer)
}
// Old AnswerObserver: only called for non-empty content chunks
if len(observed) != 1 || observed[0] != "hello" {
t.Fatalf("old observer should only see non-empty chunks, got %v", observed)
}
// StreamEvent: should include the done empty chunk (FullAnswer is accumulated)
if len(events) < 2 {
t.Fatalf("expected at least 2 stream events, got %d: %+v", len(events), events)
}
last := events[len(events)-1]
if !last.Done || last.FullAnswer != "hello" {
t.Fatalf("last event should have Done=true FullAnswer='hello', got %+v", last)
}
}
// TestAgentChatEventsRunner verifies the AgentChatEvents HTTP method reuses HTTP logic.
func TestAgentChatEventsRunner(t *testing.T) {
mux := http.NewServeMux()
mux.HandleFunc("/api/v1/agent-chat/session-1", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
_, _ = w.Write([]byte("data: {\"response_type\":\"thinking\",\"content\":\"think\",\"done\":false}\n\n"))
_, _ = w.Write([]byte("data: {\"response_type\":\"tool_call\",\"data\":{\"tool_name\":\"knowledge_search\"},\"done\":false}\n\n"))
_, _ = w.Write([]byte("data: {\"response_type\":\"references\",\"knowledge_references\":[{\"knowledge_id\":\"kb-1\",\"content\":\"ref\"}]}\n\n"))
_, _ = w.Write([]byte("data: {\"response_type\":\"answer\",\"content\":\"hello\",\"done\":true}\n\n"))
})
server := httptest.NewServer(mux)
defer server.Close()
client, err := NewClient(server.URL, "test-key", 5*time.Second)
if err != nil {
t.Fatalf("NewClient: %v", err)
}
var events []StreamEvent
result, err := client.AgentChatEvents(context.Background(), "session-1",
AgentChatRequest{Query: "q", AgentID: "agent-1", Channel: "im"},
func(e StreamEvent) { events = append(events, e) })
if err != nil {
t.Fatalf("AgentChatEvents: %v", err)
}
if result.Answer != "hello" {
t.Fatalf("expected 'hello', got %q", result.Answer)
}
if len(events) != 4 {
t.Fatalf("expected 4 events, got %d: %+v", len(events), events)
}
}
// TestAgentChatEventsNilObserver verifies nil observer is safe.
func TestAgentChatEventsNilObserver(t *testing.T) {
mux := http.NewServeMux()
mux.HandleFunc("/api/v1/agent-chat/session-1", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
_, _ = w.Write([]byte("data: {\"response_type\":\"answer\",\"content\":\"ok\",\"done\":true}\n\n"))
})
server := httptest.NewServer(mux)
defer server.Close()
client, err := NewClient(server.URL, "test-key", 5*time.Second)
if err != nil {
t.Fatalf("NewClient: %v", err)
}
result, err := client.AgentChatEvents(context.Background(), "session-1",
AgentChatRequest{Query: "q", AgentID: "agent-1", Channel: "im"}, nil)
if err != nil {
t.Fatalf("AgentChatEvents with nil observer: %v", err)
}
if result.Answer != "ok" {
t.Fatalf("expected 'ok', got %q", result.Answer)
}
}
// TestAgentChatEventsErrorTurn verifies error event returns error but notifies first.
func TestAgentChatEventsErrorTurn(t *testing.T) {
mux := http.NewServeMux()
mux.HandleFunc("/api/v1/agent-chat/session-1", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "text/event-stream")
_, _ = w.Write([]byte("data: {\"response_type\":\"error\",\"content\":\"boom\",\"done\":true}\n\n"))
})
server := httptest.NewServer(mux)
defer server.Close()
client, err := NewClient(server.URL, "test-key", 5*time.Second)
if err != nil {
t.Fatalf("NewClient: %v", err)
}
var events []StreamEvent
_, err = client.AgentChatEvents(context.Background(), "session-1",
AgentChatRequest{Query: "q", AgentID: "agent-1", Channel: "im"},
func(e StreamEvent) { events = append(events, e) })
if err == nil {
t.Fatal("expected error")
}
if !errors.Is(err, errors.New("boom")) && !strings.Contains(err.Error(), "boom") {
t.Fatalf("expected error containing 'boom', got %v", err)
}
// error event should have notified with type="error", done=true, no content
if len(events) != 1 {
t.Fatalf("expected 1 error notification event, got %d: %+v", len(events), events)
}
if events[0].ResponseType != "error" || !events[0].Done {
t.Fatalf("expected error done event, got %+v", events[0])
}
}