Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(agent): reject marker-only citation grounding responses (#20685)

li8721aea9c6110bf
diff --git a/internal/agent/component/agent.go b/internal/agent/component/agent.go
index c764b8e10b..8b987a97bb 100644
--- a/internal/agent/component/agent.go
+++ b/internal/agent/component/agent.go
@@ -18,6 +18,7 @@ import (
"fmt"
"io"
"ragflow/internal/dao"
+ "regexp"
"sort"
"strings"
"time"
@@ -493,6 +494,21 @@ func addToolCallMemory(ctx context.Context, db *gorm.DB, p AgentParam, msg *sche
return strings.TrimSpace(resp.Content), nil
}
+// citationGroundingMarkerRe matches canonical [ID:…] / [ID: …] markers that
+// the grounding call is asked to insert. IDs may be numeric or non-numeric
+// (e.g. "simple-0", "ck-1"). Used only to decide whether a grounding
+// response still has answer text after the markers are removed. The ID:
+// prefix is required so bare brackets like [2026] are not treated as markers.
+var citationGroundingMarkerRe = regexp.MustCompile(`\[ID:\s*[^\]]+\]`)
+
+// citationGroundingHasSubstantiveText reports whether s contains any
+// non-whitespace text once citation markers are stripped. Marker-only
+// responses such as "[ID:0] [ID:1]" must not replace the first-pass answer.
+func citationGroundingHasSubstantiveText(s string) bool {
+ stripped := citationGroundingMarkerRe.ReplaceAllString(s, "")
+ return strings.TrimSpace(stripped) != ""
+}
+
// applyCitationGrounding is the post-stream citation grounding
// call. It reads the chunks recorded in state.Retrieval["chunks"]
// (populated by the Retrieval tool), renders
@@ -502,7 +518,9 @@ func addToolCallMemory(ctx context.Context, db *gorm.DB, p AgentParam, msg *sche
//
// Streams grounded deltas when the invoker supports streaming. Returns the
// original content when no chunks are available or the call fails before
-// emitting anything.
+// emitting anything. Marker-only grounding responses fall back to the
+// original answer; if invalid deltas were already streamed, an error is
+// returned so the caller does not append the first-pass text afterward.
func applyCitationGrounding(ctx context.Context, db *gorm.DB, p AgentParam, content string, chunks []prompts.CitationSource) (string, error) {
if !p.Cite {
return content, nil
@@ -528,6 +546,7 @@ func applyCitationGrounding(ctx context.Context, db *gorm.DB, p AgentParam, cont
}
var resp *ChatInvokeResponse
var err error
+ emittedVisible := false
if streamer, ok := inv.(chat.StreamingInvoker); ok {
var leadingWhitespace strings.Builder
emitting := false
@@ -546,6 +565,7 @@ func applyCitationGrounding(ctx context.Context, db *gorm.DB, p AgentParam, cont
delta = leadingWhitespace.String()
emitting = true
}
+ emittedVisible = true
runtime.EmitAgentMessage(ctx, delta, "")
return nil
})
@@ -564,6 +584,16 @@ func applyCitationGrounding(ctx context.Context, db *gorm.DB, p AgentParam, cont
if strings.TrimSpace(resp.Content) == "" {
return content, nil
}
+ // Marker-only grounding must not silently replace the first-pass answer
+ // (#20613). Non-stream (or stream that never emitted) can fall back.
+ // Once invalid deltas have already been streamed, surface an error so the
+ // caller does not append the original answer after the bad markers.
+ if !citationGroundingHasSubstantiveText(resp.Content) {
+ if emittedVisible {
+ return content, fmt.Errorf("citation grounding returned markers without answer text")
+ }
+ return content, nil
+ }
return resp.Content, nil
}
diff --git a/internal/agent/component/grounding_test.go b/internal/agent/component/grounding_test.go
index d9073d9139..cf66698ddf 100644
--- a/internal/agent/component/grounding_test.go
+++ b/internal/agent/component/grounding_test.go
@@ -25,6 +25,7 @@ package component
import (
"context"
"errors"
+ "strings"
"sync"
"testing"
@@ -244,6 +245,210 @@ func TestGrounding_EmptyContent(t *testing.T) {
}
}
+// TestCitationGroundingHasSubstantiveText: marker-only strings are rejected;
+// real answer text (with or without markers) is accepted.
+func TestCitationGroundingHasSubstantiveText(t *testing.T) {
+ cases := []struct {
+ in string
+ want bool
+ }{
+ {"", false},
+ {" ", false},
+ {"[ID:0]", false},
+ {"[ID:0] [ID:1]", false},
+ {"[ID: 0]\n[ID:1]", false},
+ {"[ID:simple-0]", false},
+ {"[ID:ck-1]", false},
+ {"[ID:simple-0] [ID:ck-1]", false},
+ {"[ID: simple-0]", false},
+ {"[2026]", true},
+ {" [2026] ", true},
+ {"The reimbursement request requires manager approval.", true},
+ {"The reimbursement request requires manager approval. [ID:0]", true},
+ {"The reimbursement request requires manager approval. [ID:simple-0]", true},
+ {"答案[ID:0]", true},
+ {"答案[ID:ck-1]", true},
+ }
+ for _, tc := range cases {
+ if got := citationGroundingHasSubstantiveText(tc.in); got != tc.want {
+ t.Errorf("citationGroundingHasSubstantiveText(%q)=%v, want %v", tc.in, got, tc.want)
+ }
+ }
+}
+
+// TestGrounding_MarkerOnlyFallsBack: non-streaming grounding that returns
+// only [ID:…] markers must keep the first-pass answer (#20613).
+func TestGrounding_MarkerOnlyFallsBack(t *testing.T) {
+ inv := &groundingTestInvoker{responses: []string{"[ID:0] [ID:1]"}}
+ prev := getDefaultChatInvoker()
+ SetDefaultChatInvoker(inv)
+ defer SetDefaultChatInvoker(prev)
+
+ withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
+ return &schema.Message{Role: schema.Assistant, Content: "The reimbursement request requires manager approval."}, nil
+ })
+
+ state := canvas.NewCanvasState("r1", "t1")
+ state.SetRetrievalChunks([]map[string]any{{"id": "0", "content": "policy text"}})
+ ctx := runtime.WithState(t.Context(), state)
+
+ c := NewAgentComponent(AgentParam{ModelID: "stub", Cite: true})
+ out, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "q"})
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ want := "The reimbursement request requires manager approval."
+ if got, _ := out["content"].(string); got != want {
+ t.Errorf("content=%q, want %q (marker-only grounding must not replace original)", got, want)
+ }
+ if got := out["grounding_status"]; got == "applied" {
+ t.Errorf("grounding_status=%v, want not applied for marker-only response", got)
+ }
+ if inv.calls != 1 {
+ t.Errorf("expected 1 grounding call, got %d", inv.calls)
+ }
+}
+
+// TestGrounding_MarkerOnlyStreamErrors: once marker-only deltas have been
+// streamed, grounding must surface an error rather than silently accepting
+// the markers or re-emitting the original answer afterward (#20613).
+func TestGrounding_MarkerOnlyStreamErrors(t *testing.T) {
+ inv := &groundingStreamingInvoker{groundingTestInvoker: groundingTestInvoker{responses: []string{"[ID:0] [ID:1]"}}}
+ prev := getDefaultChatInvoker()
+ SetDefaultChatInvoker(inv)
+ defer SetDefaultChatInvoker(prev)
+
+ withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
+ return &schema.Message{Role: schema.Assistant, Content: "The reimbursement request requires manager approval."}, nil
+ })
+
+ state := canvas.NewCanvasState("r1", "t1")
+ state.SetRetrievalChunks([]map[string]any{{"id": "0", "content": "policy text"}})
+ ctx := runtime.WithState(t.Context(), state)
+ var streamed string
+ ctx = runtime.WithAgentMessageEmitter(ctx, func(content, _ string) {
+ streamed += content
+ })
+
+ c := NewAgentComponent(AgentParam{ModelID: "stub", Cite: true})
+ _, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "q"})
+ if err == nil {
+ t.Fatal("Invoke: want error after marker-only grounding stream, got nil")
+ }
+ if !strings.Contains(err.Error(), "markers without answer text") {
+ t.Errorf("error=%v, want markers-without-answer-text", err)
+ }
+ if streamed == "" {
+ t.Error("expected marker deltas to have been emitted before the error")
+ }
+ if inv.streamCalls != 1 {
+ t.Errorf("expected 1 stream call, got %d", inv.streamCalls)
+ }
+}
+
+// TestGrounding_NonNumericMarkerOnlyFallsBack: retrieval chunk IDs may be
+// non-numeric (e.g. simple-0). Marker-only grounding with those IDs must still
+// keep the first-pass answer (#20685 review).
+func TestGrounding_NonNumericMarkerOnlyFallsBack(t *testing.T) {
+ inv := &groundingTestInvoker{responses: []string{"[ID:simple-0]"}}
+ prev := getDefaultChatInvoker()
+ SetDefaultChatInvoker(inv)
+ defer SetDefaultChatInvoker(prev)
+
+ withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
+ return &schema.Message{Role: schema.Assistant, Content: "The reimbursement request requires manager approval."}, nil
+ })
+
+ state := canvas.NewCanvasState("r1", "t1")
+ state.SetRetrievalChunks([]map[string]any{{"id": "simple-0", "content": "policy text"}})
+ ctx := runtime.WithState(t.Context(), state)
+
+ c := NewAgentComponent(AgentParam{ModelID: "stub", Cite: true})
+ out, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "q"})
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ want := "The reimbursement request requires manager approval."
+ if got, _ := out["content"].(string); got != want {
+ t.Errorf("content=%q, want %q (non-numeric marker-only grounding must not replace original)", got, want)
+ }
+ if got := out["grounding_status"]; got == "applied" {
+ t.Errorf("grounding_status=%v, want not applied for marker-only response", got)
+ }
+ if inv.calls != 1 {
+ t.Errorf("expected 1 grounding call, got %d", inv.calls)
+ }
+}
+
+// TestGrounding_NonNumericMarkerOnlyStreamErrors: streamed marker-only
+// responses with non-numeric IDs must error the same way as numeric ones.
+func TestGrounding_NonNumericMarkerOnlyStreamErrors(t *testing.T) {
+ inv := &groundingStreamingInvoker{groundingTestInvoker: groundingTestInvoker{responses: []string{"[ID:simple-0] [ID:ck-1]"}}}
+ prev := getDefaultChatInvoker()
+ SetDefaultChatInvoker(inv)
+ defer SetDefaultChatInvoker(prev)
+
+ withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
+ return &schema.Message{Role: schema.Assistant, Content: "The reimbursement request requires manager approval."}, nil
+ })
+
+ state := canvas.NewCanvasState("r1", "t1")
+ state.SetRetrievalChunks([]map[string]any{
+ {"id": "simple-0", "content": "policy text"},
+ {"id": "ck-1", "content": "more policy"},
+ })
+ ctx := runtime.WithState(t.Context(), state)
+ var streamed string
+ ctx = runtime.WithAgentMessageEmitter(ctx, func(content, _ string) {
+ streamed += content
+ })
+
+ c := NewAgentComponent(AgentParam{ModelID: "stub", Cite: true})
+ _, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "q"})
+ if err == nil {
+ t.Fatal("Invoke: want error after non-numeric marker-only grounding stream, got nil")
+ }
+ if !strings.Contains(err.Error(), "markers without answer text") {
+ t.Errorf("error=%v, want markers-without-answer-text", err)
+ }
+ if streamed == "" {
+ t.Error("expected marker deltas to have been emitted before the error")
+ }
+ if inv.streamCalls != 1 {
+ t.Errorf("expected 1 stream call, got %d", inv.streamCalls)
+ }
+}
+
+// TestGrounding_MarkersWithTextStillApplied: a grounded answer that keeps
+// substantive text plus markers is still accepted.
+func TestGrounding_MarkersWithTextStillApplied(t *testing.T) {
+ inv := &groundingTestInvoker{responses: []string{"The reimbursement request requires manager approval. [ID:0]"}}
+ prev := getDefaultChatInvoker()
+ SetDefaultChatInvoker(inv)
+ defer SetDefaultChatInvoker(prev)
+
+ withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
+ return &schema.Message{Role: schema.Assistant, Content: "The reimbursement request requires manager approval."}, nil
+ })
+
+ state := canvas.NewCanvasState("r1", "t1")
+ state.SetRetrievalChunks([]map[string]any{{"id": "0", "content": "policy text"}})
+ ctx := runtime.WithState(t.Context(), state)
+
+ c := NewAgentComponent(AgentParam{ModelID: "stub", Cite: true})
+ out, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "q"})
+ if err != nil {
+ t.Fatalf("Invoke: %v", err)
+ }
+ want := "The reimbursement request requires manager approval. [ID:0]"
+ if got, _ := out["content"].(string); got != want {
+ t.Errorf("content=%q, want %q", got, want)
+ }
+ if got := out["grounding_status"]; got != "applied" {
+ t.Errorf("grounding_status=%v, want applied", got)
+ }
+}
+
type errInvoker struct {
err error
}