Skip to content

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

Refine citation for agentic RAG (#19822)

Yingfenge84a0e2caabd
diff --git a/internal/rag/agentic-rag/agentic_rag.go b/internal/rag/agentic-rag/agentic_rag.go
index 53c5aef6e1..e455238087 100644
--- a/internal/rag/agentic-rag/agentic_rag.go
+++ b/internal/rag/agentic-rag/agentic_rag.go
@@ -1684,6 +1684,11 @@ func runOuterReact(ctx context.Context, deps RAGTools, req runtime.RunRequest, l
p.resp.Answer = answer
p.resp.Chunks = p.kb.Chunks
p.resp.DocAggs = p.kb.DocAggs
+ // The numbering the answer's [ID:n] markers were written with travels WITH those chunks:
+ // the chat pipeline resolves a marker by position in this list, so a response carrying the
+ // passages without their numbering leaves the list empty and every marker indexes the POOL
+ // instead — the citation then opens whatever passage happens to sit at that position.
+ p.resp.CiteChunkIDs = append([]string(nil), p.kb.CiteChunkIDs...)
p.resp.EmptyResult = len(p.kb.Chunks) == 0
loop.StageLine(logger, "Tool loop", outerLoopEndLine(session.ragCalls(), strings.TrimSpace(p.resp.Answer) != ""))
return p.resp
@@ -1765,6 +1770,11 @@ func runOuterReactStream(ctx context.Context, deps RAGTools, req runtime.RunRequ
// Keep only the evidence of the call that owns the answer (selectEvidence
// no-ops when the answer came from the outer model instead of a rag call).
session.selectEvidence(p.resp.Answer)
+ // Same as runOuterReact: the numbering the answer's [ID:n] markers were written with has to
+ // travel with the passages it numbers. Without it the chat pipeline's published list is
+ // empty, citePoolIdx falls back to pool order, and every marker opens whichever passage
+ // happens to sit at that position (rendered_blocks == pool size is the tell).
+ p.resp.CiteChunkIDs = append([]string(nil), p.kb.CiteChunkIDs...)
p.resp.Chunks = p.kb.Chunks
p.resp.DocAggs = p.kb.DocAggs
p.resp.EmptyResult = len(p.kb.Chunks) == 0
@@ -2215,6 +2225,11 @@ func (s *outerReactSession) selectEvidence(answer string) {
s.kb.DocAggs = append([]map[string]any(nil), r.kb.DocAggs...)
s.kb.Memory = append([]map[string]any(nil), r.kb.Memory...)
s.kb.PreSummary = r.kb.PreSummary
+ // The published evidence list belongs to THIS call too: the answer's [ID:n] markers
+ // were written against it, and the chat pipeline resolves them against whatever is on
+ // the response. Restoring the passages without their numbering leaves marker n pointing
+ // at another call's n-th passage — the citation opens a passage the answer never cited.
+ s.kb.CiteChunkIDs = append([]string(nil), r.kb.CiteChunkIDs...)
return
}
}
diff --git a/internal/rag/agentic-rag/agentic_rag_graph.go b/internal/rag/agentic-rag/agentic_rag_graph.go
index 5524c5c7ca..196c9815b9 100644
--- a/internal/rag/agentic-rag/agentic_rag_graph.go
+++ b/internal/rag/agentic-rag/agentic_rag_graph.go
@@ -2071,12 +2071,108 @@ func withCitedChunks(ranked []map[string]any, kb *runtime.Kbinfos, cap int) []ma
return cited
}
+// compactAnchored renders each anchored member's block from the quote the naming node matched it
+// to, leaving every other chunk as it is. The block is what the budget is spent on, so whole
+// passages put only the first handful of members inside the render — and a member outside it has
+// no block number the model could cite. The quote carries the same words the record already
+// states, so no evidence is lost: the passage keeps its place in the pool and in the reference.
+func compactAnchored(chunks []map[string]any, kb *runtime.Kbinfos) []map[string]any {
+ if kb == nil {
+ return chunks
+ }
+ quotes := map[string]string{}
+ for _, ref := range kb.AnchoredRefs() {
+ if ref.ChunkID == "" || ref.Quote == "" {
+ continue
+ }
+ if _, dup := quotes[ref.ChunkID]; !dup {
+ quotes[ref.ChunkID] = ref.Quote
+ }
+ }
+ if len(quotes) == 0 {
+ return chunks
+ }
+ out := make([]map[string]any, 0, len(chunks))
+ for _, c := range chunks {
+ q, ok := quotes[runtime.ChunkIDOf(c)]
+ if !ok {
+ out = append(out, c)
+ continue
+ }
+ cp := make(map[string]any, len(c)+1)
+ for k, v := range c {
+ cp[k] = v
+ }
+ cp["content"] = q
+ out = append(out, cp)
+ }
+ return out
+}
+
+// anchoredPoolEntries rebuilds a pool record for every enumerated member whose passage is NOT in
+// the pool, from the quote the naming node took from that passage.
+//
+// The citation chain is: marker number → position in the published list → the pool entry that id
+// resolves to. A member whose passage is gone therefore cannot be cited at all — the marker is
+// dropped (citePoolIdx answers -1) or opens nothing. Rebuilding the record from the member's own
+// quote keeps that chain whole, and the content it opens is exactly the text the answer states.
+func anchoredPoolEntries(kb *runtime.Kbinfos) []map[string]any {
+ if kb == nil {
+ return nil
+ }
+ var out []map[string]any
+ for _, r := range kb.AnchoredRefs() {
+ id := strings.TrimSpace(r.ChunkID)
+ quote := strings.TrimSpace(r.Quote)
+ if id == "" || quote == "" || kb.ChunkByID(id) != nil {
+ continue
+ }
+ out = append(out, map[string]any{
+ "chunk_id": id,
+ "content": quote,
+ "content_with_weight": quote,
+ })
+ }
+ return out
+}
+
+// appendMissingIDs appends the ids not already present, in order: a passage the render left out
+// (the budget admits only the first few whole chunks) still has to hold a position in the
+// published list, or nothing can cite it.
+func appendMissingIDs(ids, extra []string) []string {
+ seen := make(map[string]bool, len(ids))
+ for _, id := range ids {
+ seen[id] = true
+ }
+ for _, id := range extra {
+ if id = strings.TrimSpace(id); id == "" || seen[id] {
+ continue
+ }
+ seen[id] = true
+ ids = append(ids, id)
+ }
+ return ids
+}
+
// answerPromptWithEvidence renders the parts list in order: question, answer-target
// contract, optional no-evidence instruction, research summary, partial preamble,
// evidence. The no-evidence flag is `abstain or empty_result or not chunks`.
func (d AnswerDeps) answerPromptWithEvidence(kb *runtime.Kbinfos, question string, partial, noEvidence bool) answerPrompt {
chunks := []map[string]any{}
if kb != nil {
+ // An enumerated member whose passage is no longer in the pool is rebuilt from the quote the
+ // naming node took from it BEFORE anything is rendered or published: the marker's number
+ // indexes the published list and the client opens the pool entry behind it, so a member
+ // whose passage was evicted (the pool cap, or selectEvidence narrowing to another call)
+ // would otherwise lose its citation in the chat pipeline (citePoolIdx answers -1 and the
+ // marker is dropped).
+ if extra := anchoredPoolEntries(kb); len(extra) > 0 {
+ kb.Admit(func(p *runtime.PoolAdmitter) {
+ for _, c := range extra {
+ p.Add(c)
+ }
+ })
+ }
chunks = kb.Chunks
}
ranked := rankByScore(chunks)
@@ -2084,6 +2180,11 @@ func (d AnswerDeps) answerPromptWithEvidence(kb *runtime.Kbinfos, question strin
if len(citeChunks) == 0 {
citeChunks = chunks
}
+ // An anchored member's block is rendered from its QUOTE: the budget is spent per block, so a
+ // whole ~1200-char passage per member fits only the first handful of them, and every member
+ // past that one is a member neither the model nor the answer can cite. The quote is the same
+ // words the record states, and the passage itself stays in the pool and in the reference.
+ citeChunks = compactAnchored(citeChunks, kb)
maxTokens := d.MaxTokens
if maxTokens <= 0 {
maxTokens = evidenceBudgetTokens
@@ -2100,9 +2201,27 @@ func (d AnswerDeps) answerPromptWithEvidence(kb *runtime.Kbinfos, question strin
// The ids come from the render's SOURCE indices, not from citeChunks: a chunk
// with no content renders no block, so walking citeChunks would publish an id for
// the skipped chunk and put every marker past it one block off.
+ //
+ // The enumerated members then follow whether or not their block rendered: the evidence
+ // budget admits only the first few whole chunks, so a member past them holds no block
+ // number the model could write — and a member with no position is a member the answer
+ // cannot cite and the user cannot open. Appending keeps the rendered prefix intact
+ // (block n is still position n) and gives the completion its target
+ // (runtime.CiteAnchoredMembers).
blocks, sources := prompts.KBPromptZeroBasedWithSourceIndices(citeChunks, maxTokens)
if kb != nil {
- kb.CiteChunkIDs = citeChunkIDsAt(citeChunks, sources)
+ // Only ids the POOL still holds are appended: the chat pipeline resolves a marker by
+ // looking its chunk up in the pool, and a member whose passage is gone would publish a
+ // nil reference entry — the marker is then dropped and the line loses its citation
+ // entirely. A member the pool no longer holds must lose its citation, not break the one
+ // the user can open.
+ present := make([]string, 0, len(kb.CitedChunks()))
+ for _, id := range kb.CitedChunks() {
+ if kb.ChunkByID(id) != nil {
+ present = append(present, id)
+ }
+ }
+ kb.CiteChunkIDs = appendMissingIDs(citeChunkIDsAt(citeChunks, sources), present)
}
evidence := strings.Join(blocks, "\n")
diff --git a/internal/rag/agentic-rag/coverage_step.go b/internal/rag/agentic-rag/coverage_step.go
index 128a1f66ed..b548668829 100644
--- a/internal/rag/agentic-rag/coverage_step.go
+++ b/internal/rag/agentic-rag/coverage_step.go
@@ -74,13 +74,14 @@ func RunCoverageResolve(ctx context.Context, deps RAGTools, st *AgenticState, lo
if set.Empty() {
// Nothing to judge: no enumeration ran (no clock left, or the executor cannot search)
// and no probe reached a name the slots do not already hold.
- logger.Printf("[Coverage] resolve has nothing to judge: %d enumeration window(s), %d reached name(s), %d unjudged claim(s).", len(set.Windows), reached, claimed)
+ logger.Printf("[Coverage] resolve has nothing to judge: 0 line(s).")
return stats
}
if reached+claimed > 0 {
// The split is worth a line: it is the difference between a node that judges only what
// its own enumeration recalled and one that also judges what the run's search touched
- // and what the sessions ASSERTED but never showed a passage for.
+ // and what the sessions ASSERTED but never showed a passage for. Both numbers are READ
+ // from the one list (countSource), never kept beside it.
logger.Printf("[Coverage] resolve candidates: %d window(s) + %d reached name(s) + %d unjudged claim(s) = %d line(s)",
len(set.Windows)-reached-claimed, reached, claimed, len(set.Windows))
}
@@ -137,6 +138,10 @@ func RunCoverageResolve(ctx context.Context, deps RAGTools, st *AgenticState, lo
// prompt puts them in front of the answer, which must cite one passage per member and otherwise
// sees only the top-scoring handful.
st.KB.NoteCitedChunks(runtime.AnchoredItemChunks(&st.SlotTable))
+ // And the member↔passage table itself, so the compose can write the citation of every member
+ // the answer states (see runtime.CiteAnchoredMembers): which passage a member rests on is the
+ // naming node's finding, not a block number the model has to write out of a budgeted render.
+ st.KB.NoteAnchoredRefs(runtime.AnchoredItemRefs(&st.SlotTable))
if stats.Unknown > 0 {
// An enumeration that did not finish must not read as one that did. The windows with
// no verdict are members nobody judged, so the list above is a LOWER BOUND, and the
@@ -199,6 +204,14 @@ func coverageResolveCandidates(kb *runtime.Kbinfos, table *runtime.State, cov ru
for _, name := range runtime.AnchoredItems(table) {
known[strings.ToLower(strings.TrimSpace(name))] = true
}
+ // Everything below goes into ONE list, judged by ONE node under ONE budget; what differs is
+ // where a line came from, which is a field on the line (CoverageWindow.Source) rather than a
+ // pipeline with its own cap, its own dedup and its own counter.
+ //
+ // The two counters below count TERMS, not lines, because that is what the report says
+ // ("reached name(s)"): a name the pool carries three passages about is one name handed over.
+ // A count read off the lines instead would report three — measured by the test that pins the
+ // split (coverage_step_test.go: 于禁 has two passages in the pool and is ONE claim).
added := 0
for _, rt := range kb.ReachedTerms() {
term := strings.TrimSpace(rt.Term)
@@ -216,7 +229,7 @@ func coverageResolveCandidates(kb *runtime.Kbinfos, table *runtime.State, cov ru
if quote == "" {
continue
}
- set.Windows = append(set.Windows, runtime.CoverageWindow{ChunkID: rt.ChunkID, Quote: quote})
+ set.Windows = append(set.Windows, runtime.CoverageWindow{ChunkID: rt.ChunkID, Quote: quote, Source: runtime.CoverageSourceReached})
known[key] = true
added++
}
@@ -238,6 +251,7 @@ func coverageResolveCandidates(kb *runtime.Kbinfos, table *runtime.State, cov ru
if windowQuotesTerm(set.Windows, w.ChunkID, term) {
continue
}
+ w.Source = runtime.CoverageSourceClaim
set.Windows = append(set.Windows, w)
}
known[key] = true
diff --git a/internal/rag/agentic-rag/graph_compose.go b/internal/rag/agentic-rag/graph_compose.go
index fdf8e4a849..973d4eb082 100644
--- a/internal/rag/agentic-rag/graph_compose.go
+++ b/internal/rag/agentic-rag/graph_compose.go
@@ -371,7 +371,7 @@ func ComposeAnswerWith(ctx context.Context, deps AnswerDeps, kb *runtime.Kbinfos
logger.Printf("[Composing the answer] composition failed: %v", err)
return AnswerResult{Answer: answerErrorFallback, Failed: true}
}
- answer := cleanAnswer(reply.Content)
+ answer := citeAnchoredMembers(cleanAnswer(reply.Content), kb)
logComposeDone(logger, started, answer, len(chunks))
return AnswerResult{Answer: answer, Partial: partial}
}
@@ -521,11 +521,53 @@ func ComposeAnswerStream(ctx context.Context, deps AnswerDeps, model runtime.Str
if reply == nil {
return AnswerResult{Answer: "", Failed: true}, errors.New("streaming composition returned no reply")
}
- answer := cleanAnswer(reply.Content)
+ answer := citeAnchoredMembers(cleanAnswer(reply.Content), kb)
logComposeDone(logger, started, answer, len(chunks))
return AnswerResult{Answer: answer, Partial: partial}, nil
}
+// citeAnchoredMembers attaches the citation of every enumerated member the answer states without
+// one (see runtime.CiteAnchoredMembers). Nil-safe: a run that enumerated nothing, or whose members
+// never reached the published evidence list, comes back unchanged.
+func citeAnchoredMembers(answer string, kb *runtime.Kbinfos) string {
+ if kb == nil {
+ return answer
+ }
+ refs := kb.AnchoredRefs()
+ // textOf lets the step verify a citation against the passage it would open: a marker is
+ // written only for a passage that actually contains the words the answer quotes.
+ textOf := func(id string) string {
+ if c := kb.ChunkByID(id); c != nil {
+ return runtime.ChunkTextOf(c)
+ }
+ return ""
+ }
+ out, overridden := runtime.CitedAnchoredMembers(answer, refs, kb.CiteChunkIDs, textOf)
+ if len(refs) > 0 {
+ // One line per run that says which member was given which marker, and which passage that
+ // marker holds: "the citation opens a passage that does not state this member" is only
+ // answerable from this pairing, and without it a marker and its passage look the same
+ // whether or not they belong together.
+ pos := map[string]int{}
+ for i, id := range kb.CiteChunkIDs {
+ if _, dup := pos[id]; !dup {
+ pos[id] = i
+ }
+ }
+ pairs := make([]string, 0, len(refs))
+ for _, r := range refs {
+ if i, ok := pos[strings.TrimSpace(r.ChunkID)]; ok {
+ pairs = append(pairs, fmt.Sprintf("%s->%d(%s)", r.Name, i, r.ChunkID))
+ continue
+ }
+ pairs = append(pairs, fmt.Sprintf("%s->(not-published)", r.Name))
+ }
+ _LOG.Printf("[Citation] anchored %d member(s), rewrote %d line(s); %s",
+ len(refs), overridden, strings.Join(pairs, " "))
+ }
+ return out
+}
+
// composeSystem builds the system prompt, applying the precedence rules.
//
// LANGUAGE IS DELIBERATELY LEFT OVERRIDABLE: "answer in the same language as the
diff --git a/internal/rag/agentic-rag/runtime/coverage.go b/internal/rag/agentic-rag/runtime/coverage.go
index 1c1f92ba30..e5cb45fbf9 100644
--- a/internal/rag/agentic-rag/runtime/coverage.go
+++ b/internal/rag/agentic-rag/runtime/coverage.go
@@ -22,9 +22,7 @@ import (
"ragflow/internal/rag/agentic-rag/slots"
)
-// CoverageActWordsMax bounds the act words ONE slot may declare. Ten because a source
-// words one deed many ways (斩 / 杀 / 劈 / 挥为两段 …), and a phrasing no act word covers
-// is a passage no query ever names — which is why the planner is asked for several.
+// CoverageActWordsMax bounds the act words ONE slot may declare.
const CoverageActWordsMax = 10
// Coverage is what a question ASKS FOR when its answer is a SET OF NAMED MEMBERS: an
@@ -140,6 +138,13 @@ func (c Coverage) Ok() bool {
return c.Set && c.ItemKind != "" && len(c.Acts) > 0
}
+// ActsAll is the act vocabulary the enumeration filters by: the planner's declaration, and
+// nothing else. It is a named extension point rather than a constant (see coverage_enumerate.go,
+// which filters with it).
+func (c Coverage) ActsAll() []string {
+ return append([]string(nil), c.Acts...)
+}
+
// ItemsInValue reports whether the table's own slots HOLD items — the direction the run's output
// declares where the planner's word did not. The point-of-naming node reads it and nothing else
// does (see Coverage.itemsInValue for why the record and a session must not).
diff --git a/internal/rag/agentic-rag/runtime/coverage_enumerate.go b/internal/rag/agentic-rag/runtime/coverage_enumerate.go
index 09a94eb2c3..27b4639f21 100644
--- a/internal/rag/agentic-rag/runtime/coverage_enumerate.go
+++ b/internal/rag/agentic-rag/runtime/coverage_enumerate.go
@@ -29,7 +29,14 @@ import (
// of a passage a verdict is asked about, and the two caps keep the seed and the call list
// finite.
const (
- coverageRecallTopN = 200
+ // 200 was the HEAD OF A RANKING sold as a total (measured 2026-09-17, 三国, 1718 chunks:
+ // `operand "斩"/"杀": recall hit its bound (200 passage(s))`, both runs). A member stated
+ // in a passage ranked past 200 could then never become a window, never be judged, never be
+ // named — and the pass-through set came out as "the famous ones", which is why an answer
+ // named the right members while citing only a handful of them. The bound is per OPERAND
+ // (actor forms + act words, see Coverage.Operands), so this is a corpus-scale ask, not a
+ // per-pair one.
+ coverageRecallTopN = 1000
coverageWindowsPerChunk = 3
coverageWindowBefore = 80
coverageWindowAfter = 60
@@ -39,8 +46,18 @@ const (
// clock / a slow call × batch — so the two move together: a cap above the capacity is a
// ceiling that can never be reached, and the member set then moves with the provider's
// latency instead of with the corpus.
- coverageWindowsMax = 192
- coverageSeedMaxChars = 8000
+ //
+ // 288 is the capacity the resolve node already documents for itself (coverage_resolve.go:
+ // six workers × (CoverageResolveTimeoutS / a five-second call) × batch = 6 × 6 × 8 = 288).
+ // At 192 the cap was BELOW that capacity, and every window past it was reported as UNKNOWN
+ // (ResolveCoverage: "nobody judged them"), i.e. evidence the enumeration had paid a search
+ // for was dropped without ever being read.
+ coverageWindowsMax = 288
+ // coverageSeedMaxChars is the PROSE budget of the seed, not a cap on what a session can
+ // cite: past it the quote is dropped and the chunk id is still written (see Render), because
+ // a window omitted outright is a passage no session can name, and a member nothing can name
+ // is a member that only exists in the model's own memory.
+ coverageSeedMaxChars = 32000
)
// CoverageWindow is one place the corpus states the deed: the chunk it is in, the words
@@ -53,8 +70,28 @@ type CoverageWindow struct {
ChunkID string
Quote string
Act string
+ // Source is the line's PROVENANCE, and it is the whole difference between what used to be
+ // three pipelines (see CoverageSource): the enumeration's windows, the names a probe reached
+ // and the names a session asserted are judged side by side, in one list with one budget —
+ // not in three lists with three caps, three dedup rules and three counters.
+ Source CoverageSource
}
+// CoverageSource says where one ledger line came from. Nothing downstream may branch on it
+// except a report: a line is judged, or it is not, and a member named in it is a member.
+type CoverageSource string
+
+const (
+ // CoverageSourceEnumeration: a window this run's own enumeration built; it carries an Act.
+ CoverageSourceEnumeration CoverageSource = "enumeration"
+ // CoverageSourceReached: a name a probe asked about and DID reach, with the pool chunk that
+ // carries it (see Kbinfos.RecordReachedTerm).
+ CoverageSourceReached CoverageSource = "reached"
+ // CoverageSourceClaim: a name a session asserted with no passage. The pool is asked what it
+ // can show about it, so a claim the run can refute is refuted rather than counted.
+ CoverageSourceClaim CoverageSource = "claim"
+)
+
// CoverageSet is what one enumeration of the corpus produced: the operands it asked
// about, the windows the deed was stated in, and how many distinct passages came back.
//
@@ -136,6 +173,43 @@ func EnumerateCoverage(ctx context.Context, deps SearchDeps, cov Coverage, kb *K
}
set.Recalled = len(byID)
+ // The vocabulary the filter below asks about. The plan's words are a guess about a text
+ // nobody had read when they were written (see Coverage.ActsAll): the passages THIS recall just
+ // brought back through the actor's own name are read here, once, so that a death stated in a
+ // phrasing the plan had no word for — 第一回's "被云长刀起处,挥为两段" — becomes a window
+ // instead of being dropped before any node ever sees it.
+ acts := cov.ActsAll()
+ sampleIDs := make([]string, 0, len(byID))
+ for id := range byID {
+ sampleIDs = append(sampleIDs, id)
+ }
+ // Sorted by chunk id: which passages are sampled is what the induced vocabulary is read from,
+ // and that vocabulary becomes a filter, so it must not vary with the map's iteration order.
+ sort.Strings(sampleIDs)
+ var samples []string
+ var probe strings.Builder
+ probe.WriteString("Passages:\n")
+ for _, id := range sampleIDs {
+ if len(samples) >= coverageVocabSamples {
+ break
+ }
+ text := strings.Join(strings.Fields(ChunkTextOf(byID[id])), " ")
+ if text == "" || (len(actors) > 0 && !coverageMentionsAny(text, actors)) {
+ continue
+ }
+ if r := []rune(text); len(r) > coverageVocabSampleChars {
+ text = string(r[:coverageVocabSampleChars])
+ }
+ samples = append(samples, text)
+ fmt.Fprintf(&probe, "[%d] %s\n", len(samples), text)
+ }
+ if induced := induceActWords(ctx, deps.Model, cov.Acts, probe.String(), samples); len(induced) > 0 {
+ for _, w := range induced {
+ acts = appendUnique(acts, w)
+ }
+ _LOG.Printf("[Coverage] vocabulary probe: read %d word(s) out of the corpus that the plan had not declared (%s) — the filter knows them now.", len(induced), strings.Join(induced, " / "))
+ }
+
// Sorted by chunk id: these windows are rendered into EVERY session's seed (and the
// cap below keeps the first N), so walking the map made both the seed's wording and
// which windows survived the cap differ from run to run.
@@ -145,10 +219,30 @@ func EnumerateCoverage(ctx context.Context, deps SearchDeps, cov Coverage, kb *K
}
sort.Strings(ids)
+ // An actor form that matches NOTHING in what the recall just brought back is a suspect
+ // DECLARATION, not a fact about the corpus: 2026-09-18 the plan's subject came through as
+ // "None", the actor test rejected all 852 passages this recall had returned, and the run lost
+ // every citation it could have had (the point-of-naming node was handed no window at all). A
+ // test that rejects 100% of the recall has stopped being a filter, so the passages below are
+ // judged on the act words alone — the model is the node that decides whether the deed is
+ // stated — and the miss is said out loud instead of turning into silence.
+ if len(actors) > 0 {
+ matched := false
+ for _, id := range ids {
+ if coverageMentionsAny(strings.Join(strings.Fields(ChunkTextOf(byID[id])), " "), actors) {
+ matched = true
+ break
+ }
+ }
+ if !matched {
+ _LOG.Printf("[Coverage] actor %q matches NONE of the %d recalled passage(s): dropping the actor test (the declaration is suspect; the act words still stand) instead of judging nothing.", cov.Actor, len(ids))
+ actors = nil
+ }
+ }
for _, id := range ids {
c := byID[id]
text := strings.Join(strings.Fields(ChunkTextOf(c)), " ")
- act := coverageFirstAct(text, cov.Acts)
+ act := coverageFirstAct(text, acts)
if act == "" {
continue
}
@@ -158,12 +252,12 @@ func EnumerateCoverage(ctx context.Context, deps SearchDeps, cov Coverage, kb *K
if kb != nil {
kb.Admit(func(p *PoolAdmitter) { p.Add(c) })
}
- for _, w := range coverageWindows(text, cov.Acts, coverageWindowsPerChunk) {
+ for _, w := range coverageWindows(text, acts, coverageWindowsPerChunk) {
if len(set.Windows) >= coverageWindowsMax {
set.Truncated = true
break
}
- set.Windows = append(set.Windows, CoverageWindow{ChunkID: ChunkIDOf(c), Quote: w.quote, Act: w.act})
+ set.Windows = append(set.Windows, CoverageWindow{ChunkID: ChunkIDOf(c), Quote: w.quote, Act: w.act, Source: CoverageSourceEnumeration})
}
}
return set
@@ -188,7 +282,7 @@ func CoverageActsMeetActor(kb *Kbinfos, cov Coverage) bool {
actors := cov.Actors()
for _, c := range kb.Chunks {
text := ChunkTextOf(c)
- if coverageFirstAct(text, cov.Acts) == "" {
+ if coverageFirstAct(text, cov.ActsAll()) == "" {
continue
}
if len(actors) > 0 && !coverageMentionsAny(text, actors) {
@@ -221,14 +315,29 @@ func (s CoverageSet) Render() string {
b.WriteString("(nothing)\n")
return b.String()
}
+ quotesDropped, idsDropped := 0, 0
for _, w := range s.Windows {
line := fmt.Sprintf("- chunk_id=%s %q\n", w.ChunkID, w.Quote)
if b.Len()+len(line) > coverageSeedMaxChars {
- b.WriteString("(further windows omitted; all of them are in the pool)\n")
- break
+ // Over the prose budget: the passage is still NAMED, only its text is left out.
+ // Dropping the line outright would hide a window the enumeration already paid a
+ // search for, and a member that no line names is a member the session can only
+ // answer from its own memory — the very thing the seed exists to replace.
+ line = fmt.Sprintf("- chunk_id=%s\n", w.ChunkID)
+ if b.Len()+len(line) > coverageSeedMaxChars {
+ idsDropped++
+ continue
+ }
+ quotesDropped++
}
b.WriteString(line)
}
+ if quotesDropped > 0 {
+ fmt.Fprintf(&b, "(the %d window(s) above list a chunk id without its quote; the text is in the pool under that id)\n", quotesDropped)
+ }
+ if idsDropped > 0 {
+ fmt.Fprintf(&b, "(%d further window(s) are in the pool but are not listed here)\n", idsDropped)
+ }
if s.Truncated {
b.WriteString("(the enumeration ran out of clock; the corpus holds more than is shown here)\n")
}
diff --git a/internal/rag/agentic-rag/runtime/coverage_resolve.go b/internal/rag/agentic-rag/runtime/coverage_resolve.go
index 2063c1dc53..b66d733c6d 100644
--- a/internal/rag/agentic-rag/runtime/coverage_resolve.go
+++ b/internal/rag/agentic-rag/runtime/coverage_resolve.go
@@ -82,16 +82,13 @@ type batchResult struct {
// failure this node exists to remove: a single call that carries them all reaches its clock
// and answers nothing, losing a whole enumeration's worth of members to one timeout.
//
-// These bound ONE budget, not three independent knobs: this node has to be able to judge
+// These bound ONE budget, not independent knobs: this node has to be able to judge
// coverageWindowsMax windows inside CoverageResolveTimeoutS, and its capacity is
-// workers × (clock / the slowest call it can expect) × batch. At three workers and a
-// five-second call that is 144 windows — BELOW the 160 the enumeration is allowed to hand it,
-// i.e. a ceiling the point-of-naming step can never clear, which makes the member set a
-// function of provider latency instead of a function of the corpus. Six workers clear the
-// same cap with room to spare (6 × (30/5) × 8 = 288).
+// workers × (clock / the slowest call it can expect) × batch. The cap must stay BELOW that
+// capacity, with room for calls slower than the five seconds assumed here.
const (
coverageResolveBatch = 8
- coverageResolveWorkers = 6
+ coverageResolveWorkers = 8
coverageResolveQuoteChars = 300
// coverageResolvePasses bounds the re-asking: the first pass puts every window in front of
// the model, and each pass after it re-asks ONLY the windows that got no verdict — a call
@@ -216,6 +213,88 @@ func ResolveCoverage(ctx context.Context, model SessionModel, question string, c
return members, stats
}
+// CoverageVocabPrompt asks for the vocabulary of THE SOURCE, never for the vocabulary of the
+// language: the passages are what answers it, and a word that is not in them does not qualify.
+const CoverageVocabPrompt = `You are given passages from ONE source document.
+
+The direction under study is the deed named by these words — the act they stand for:
+%WORDS%
+
+List the words THIS SOURCE uses for that deed. A word qualifies only if it ACTUALLY APPEARS in the
+passages below: never list a word you know from the language but cannot see in the text. Include
+every distinct phrasing the passages use for it, including unusual and indirect ones — but give the
+ACT ITSELF: the verb or short phrase, never a phrase carrying a particular victim's name and never
+a whole clause.
+
+Answer with JSON only: {"words": ["<word>", "<word>"]}
+Every entry is copied EXACTLY as it appears in a passage, at most %MAX% entries. No prose.`
+
+// The probe's bounds: how many passages it reads, how much of each, and how many words it may
+// bring back. The call is small on purpose — it is read once per enumeration, against a point of
+// naming that judges hundreds of lines — and every word it reports is then checked against the
+// very passages it was shown.
+const (
+ coverageVocabSamples = 12
+ coverageVocabSampleChars = 320
+ coverageVocabWords = 24
+)
+
+// induceActWords reads the deed's vocabulary OUT OF THE CORPUS — one call, before the enumeration
+// filters with it.
+//
+// Why this exists: the planner declares the deed's words BEFORE any passage has been read (see the
+// initialize prompt's "the words the SOURCE itself uses for that deed" — asked of a text nobody
+// has looked at yet).
+func induceActWords(ctx context.Context, model SessionModel, declared []string, passages string, samples []string) []string {
+ if model == nil || len(declared) == 0 || passages == "" || len(samples) == 0 || ctx.Err() != nil {
+ return nil
+ }
+ head := strings.Replace(CoverageVocabPrompt, "%WORDS%", strings.Join(declared, " / "), 1)
+ head = strings.Replace(head, "%MAX%", fmt.Sprint(coverageVocabWords), 1)
+ reply, err := model.Complete(ctx, []schema.Message{
+ *schema.SystemMessage(head),
+ *schema.UserMessage(passages),
+ }, nil)
+ if err != nil || reply == nil {
+ return nil
+ }
+ obj := coverageJSONObject(reply.Content)
+ if obj == nil {
+ return nil
+ }
+ var out []string
+ for _, raw := range coverageAnyList(obj["words"]) {
+ w, _ := raw.(string)
+ w = strings.TrimSpace(w)
+ // A word, not a clause; and present in what the model was shown. the ACT with the victim inside it, which can only ever
+ // match the one passage it was read from, so it spends one of the entries to buy nothing.
+ // The prompt asks for the act itself; this is the mechanical backstop for it (a phrasing
+ // long enough to carry a name is not a vocabulary item).
+ if w == "" || len([]rune(w)) > 8 || strings.ContainsAny(w, " \t\n") {
+ continue
+ }
+ if !coverageCarriedByAny(samples, w) {
+ continue
+ }
+ out = appendUnique(out, w)
+ if len(out) >= coverageVocabWords {
+ break
+ }
+ }
+ return out
+}
+
+// coverageCarriedByAny reports whether one of the passages actually carries the word — the check
+// that makes the induced vocabulary a reading of the corpus instead of a claim about it.
+func coverageCarriedByAny(samples []string, word string) bool {
+ for _, s := range samples {
+ if strings.Contains(s, word) {
+ return true
+ }
+ }
+ return false
+}
+
// resolveCoverageBatch puts ONE batch of jobs in front of the model and returns the members
// it named out of that batch. The verdicts it reports are keyed by the CALLER's window
// indices, so the caller can re-ask exactly the jobs that came back with none.
diff --git a/internal/rag/agentic-rag/runtime/items.go b/internal/rag/agentic-rag/runtime/items.go
index 8687bcc177..b909c49258 100644
--- a/internal/rag/agentic-rag/runtime/items.go
+++ b/internal/rag/agentic-rag/runtime/items.go
@@ -17,6 +17,8 @@
package runtime
import (
+ "regexp"
+ "strconv"
"strings"
"unicode/utf8"
@@ -133,6 +135,155 @@ func AnchoredItemChunks(table *State) []string {
return out
}
+// AnchoredItemRefs is AnchoredItemChunks' pairing: every anchored item's value with the passage it
+// rests on, in table order and deduped by value. The naming node matched each member to the
+// passage that states its deed, so this is the member→passage table the answer's citations are
+// written from (see CiteAnchoredMembers).
+func AnchoredItemRefs(table *State) []AnchoredRef {
+ if table == nil {
+ return nil
+ }
+ var out []AnchoredRef
+ seen := map[string]bool{}
+ for _, v := range table.State {
+ for _, it := range v.Typed().Anchored() {
+ name := strings.TrimSpace(it.Value)
+ id := strings.TrimSpace(it.ChunkID)
+ if name == "" || id == "" {
+ continue
+ }
+ key := strings.ToLower(name)
+ if seen[key] {
+ continue
+ }
+ seen[key] = true
+ out = append(out, AnchoredRef{Name: name, ChunkID: id, Quote: strings.TrimSpace(it.Quote)})
+ }
+ }
+ return out
+}
+
+// citedMarkerPattern matches a citation marker the answer may already carry: the canonical
+// "[ID:n]" the rules prescribe, and the bare "[n]" a model writes on its own.
+var citedMarkerPattern = regexp.MustCompile(`\[(?:ID:\s*)?[0-9]+\]`)
+
+// CiteAnchoredMembers attaches the citation of every anchored member the answer states without
+// one: the line naming the member gets the marker of the passage that member rests on, taken from
+// citeIDs — the published evidence list, whose positions are what the client opens.
+//
+// The step is the RUNTIME's, not the model's: the naming node already matched each member to the
+// passage that names it, while a model can only cite the blocks it was shown — the evidence budget
+// admits the first few whole chunks, so a member past them has no block number it could write. A
+// member the answer never states is left alone, and a line that already carries a marker is kept
+// as written.
+func CiteAnchoredMembers(answer string, refs []AnchoredRef, citeIDs []string) string {
+ out, _ := CitedAnchoredMembers(answer, refs, citeIDs, nil)
+ return out
+}
+
+// answerQuote is the passage a line quotes: its first “…” span (or its first "…"), "" when the
+// line quotes nothing.
+func answerQuote(line string) string {
+ for _, pair := range [][2]string{{"“", "”"}, {"\"", "\""}} {
+ lo := strings.Index(line, pair[0])
+ if lo < 0 {
+ continue
+ }
+ rest := line[lo+len(pair[0]):]
+ hi := strings.Index(rest, pair[1])
+ if hi < 0 {
+ continue
+ }
+ if q := strings.TrimSpace(rest[:hi]); q != "" {
+ return q
+ }
+ }
+ return ""
+}
+
+// spaceLess drops the whitespace and quotation marks a passage and its quotation may differ by, so
+// "被云长 刀起处,挥为两段" still matches the corpus's own spelling.
+func spaceLess(s string) string {
+ return strings.NewReplacer(" ", "", "\t", "", "\n", "", "\u3000", "",
+ "“", "", "”", "", "\"", "", "…", "").Replace(s)
+}
+
+// CitedAnchoredMembers is CiteAnchoredMembers plus the number of LINES it rewrote, so a caller can
+// report whether the step touched the answer at all: a run whose members all carried markers
+// already is indistinguishable from one the step never reached otherwise.
+func CitedAnchoredMembers(answer string, refs []AnchoredRef, citeIDs []string, textOf func(string) string) (string, int) {
+ if strings.TrimSpace(answer) == "" || len(refs) == 0 || len(citeIDs) == 0 {
+ return answer, 0
+ }
+ pos := map[string]int{}
+ for i, id := range citeIDs {
+ if id = strings.TrimSpace(id); id == "" {
+ continue
+ }
+ if _, dup := pos[id]; !dup {
+ pos[id] = i
+ }
+ }
+ if len(pos) == 0 {
+ return answer, 0
+ }
+ overridden := 0
+ lines := strings.Split(answer, "\n")
+ for i, line := range lines {
+ // A line naming members is given the marker of EVERY member it names, and any marker the
+ // model wrote there is replaced by them: the model cites the blocks it read, so a line it
+ // grouped ("颜良…文丑" both [ID:5]) points at a passage that is not that member's, and a
+ // sentence naming nine members carries one marker for nine. Which member rests on which
+ // passage is the naming node's finding (refs × citeIDs), so the runtime's answer replaces
+ // the model's guess on exactly those lines; a line naming no member is left untouched.
+ var add []string
+ for _, r := range refs {
+ if !strings.Contains(line, r.Name) {
+ continue
+ }
+ id := strings.TrimSpace(r.ChunkID)
+ if textOf != nil {
+ // The marker must open the passage that STATES this member: the words the line
+ // quotes, or — when the answer states them in its own words — the quotation the
+ // naming node took from the passage in the first place. Only when NEITHER is in
+ // the anchored passage is another published passage tried, and only when none of
+ // them holds either is the line left uncited.
+ holds := func(cand, q string) bool {
+ return q != "" && strings.Contains(spaceLess(textOf(cand)), spaceLess(q))
+ }
+ asked, own := answerQuote(line), strings.TrimSpace(r.Quote)
+ if !holds(id, asked) && !holds(id, own) {
+ id = ""
+ for _, q := range []string{asked, own} {
+ for _, cand := range citeIDs {
+ if holds(cand, q) {
+ id = strings.TrimSpace(cand)
+ break
+ }
+ }
+ if id != "" {
+ break
+ }
+ }
+ }
+ }
+ if id == "" {
+ continue
+ }
+ if idx, ok := pos[id]; ok {
+ add = append(add, "[ID:"+strconv.Itoa(idx)+"]")
+ }
+ }
+ if len(add) == 0 {
+ continue
+ }
+ stripped := strings.TrimRight(strings.TrimSpace(citedMarkerPattern.ReplaceAllString(line, "")), " \t")
+ lines[i] = stripped + " " + strings.Join(add, "")
+ overridden++
+ }
+ return strings.Join(lines, "\n"), overridden
+}
+
// itemValuesWhere joins the items a picker selects ACROSS the table's slots, in ItemValues order,
// so every reading of the table agrees on WHICH values exist and in what order; only the picker
// differs.
diff --git a/internal/rag/agentic-rag/runtime/items_test.go b/internal/rag/agentic-rag/runtime/items_test.go
index 08d70acb26..26df833322 100644
--- a/internal/rag/agentic-rag/runtime/items_test.go
+++ b/internal/rag/agentic-rag/runtime/items_test.go
@@ -111,3 +111,44 @@ func TestAnchoredItemsIsEmptyWithoutItems(t *testing.T) {
t.Errorf("anchored(blank name) = %v, want nothing", got)
}
}
+
+// TestCiteAnchoredMembersFillsWhatTheModelLeftUncited pins the step's whole reason: which passage
+// a member rests on is the naming node's finding, so the runtime writes that member's citation
+// itself. A line that already carries a marker is kept verbatim, a member the answer never states
+// is left alone, and a member whose passage holds no published position cannot be pointed at.
+func TestCiteAnchoredMembersFillsWhatTheModelLeftUncited(t *testing.T) {
+ refs := []AnchoredRef{
+ {Name: "华雄", ChunkID: "c-hua"},
+ {Name: "管亥", ChunkID: "c-guan"},
+ {Name: "蔡阳", ChunkID: "c-cai"},
+ {Name: "不在答案里", ChunkID: "c-absent"},
+ {Name: "庞德", ChunkID: "c-unpublished"},
+ }
+ ids := []string{"c-hua", "c-guan", "c-cai"}
+ answer := strings.Join([]string{
+ "关羽所斩:",
+ "华雄——\"温酒斩华雄\"",
+ "管亥——\"劈管亥于马下\" [ID:1]",
+ "蔡阳——\"蔡阳头已落地\"",
+ "庞德——\"德引颈受刑\"",
+ "除上述数人外,另斩华雄、蔡阳等",
+ }, "\n")
+ got := CiteAnchoredMembers(answer, refs, ids)
+ want := strings.Join([]string{
+ "关羽所斩:",
+ "华雄——\"温酒斩华雄\" [ID:0]",
+ "管亥——\"劈管亥于马下\" [ID:1]",
+ "蔡阳——\"蔡阳头已落地\" [ID:2]",
+ "庞德——\"德引颈受刑\"",
+ "除上述数人外,另斩华雄、蔡阳等 [ID:0][ID:2]",
+ }, "\n")
+ if got != want {
+ t.Errorf("CiteAnchoredMembers =\n%s\nwant\n%s", got, want)
+ }
+ if got := CiteAnchoredMembers(answer, nil, ids); got != answer {
+ t.Errorf("no refs must change nothing, got %q", got)
+ }
+ if got := CiteAnchoredMembers(answer, refs, nil); got != answer {
+ t.Errorf("no published positions must change nothing, got %q", got)
+ }
+}
diff --git a/internal/rag/agentic-rag/runtime/kbinfos.go b/internal/rag/agentic-rag/runtime/kbinfos.go
index 7bd1ae64b6..361f58b556 100644
--- a/internal/rag/agentic-rag/runtime/kbinfos.go
+++ b/internal/rag/agentic-rag/runtime/kbinfos.go
@@ -143,6 +143,9 @@ type Kbinfos struct {
// citedChunks are the passages the enumerated items rest on (see NoteCitedChunks).
// Guarded by ledgerMu.
citedChunks []string
+ // anchoredRefs are the enumerated members with their passages (see NoteAnchoredRefs).
+ // Guarded by ledgerMu.
+ anchoredRefs []AnchoredRef
// sufficiencyUnchecked records that the completeness review never ran (see
// NoteSufficiencyUnchecked). Guarded by ledgerMu.
sufficiencyUnchecked bool
@@ -500,6 +503,45 @@ func (k *Kbinfos) CitedChunks() []string {
return append([]string(nil), k.citedChunks...)
}
+// AnchoredRef is one enumerated member and the passage it rests on: the name the answer
+// states, and the chunk the naming node matched that name to.
+type AnchoredRef struct {
+ Name string
+ ChunkID string
+ // Quote is the words the naming node matched the member to. The compose renders an anchored
+ // member's block from THIS rather than from the whole passage: the evidence budget is spent
+ // per block, so a ~1200-char chunk per member fits only the first handful of them, and the
+ // members past that are members the model cannot see (and so cannot cite).
+ Quote string
+}
+
+// NoteAnchoredRefs records the members behind the cited passages, in table order.
+//
+// The naming node has already matched every member to the passage that states its deed, so
+// the member→passage pointer is the RUNTIME's to know. The compose reads it back through
+// CiteAnchoredMembers to attach a citation to every member the answer states: a model that
+// cites only the handful of blocks it happened to read leaves the rest of the list
+// unreachable, and no prompt can make it cite a block it never saw (the evidence budget
+// admits only the first few whole chunks).
+func (k *Kbinfos) NoteAnchoredRefs(refs []AnchoredRef) {
+ if k == nil {
+ return
+ }
+ k.ledgerMu.Lock()
+ k.anchoredRefs = append([]AnchoredRef(nil), refs...)
+ k.ledgerMu.Unlock()
+}
+
+// AnchoredRefs is the list recorded by NoteAnchoredRefs, empty when nothing was enumerated.
+func (k *Kbinfos) AnchoredRefs() []AnchoredRef {
+ if k == nil {
+ return nil
+ }
+ k.ledgerMu.Lock()
+ defer k.ledgerMu.Unlock()
+ return append([]AnchoredRef(nil), k.anchoredRefs...)
+}
+
// StoreCoverageSet records what this question's enumeration found (see
// EnumerateCoverage / CoverageSet).
func (k *Kbinfos) StoreCoverageSet(set CoverageSet) {
diff --git a/internal/rag/prompts/action_initialize_state.md b/internal/rag/prompts/action_initialize_state.md
index 8b6ab7a873..2b7469433d 100644
--- a/internal/rag/prompts/action_initialize_state.md
+++ b/internal/rag/prompts/action_initialize_state.md
@@ -19,7 +19,8 @@ Rules:
- Order slots so the FIRST one holds the top-level requested fact; the later ones are its dependencies.
- Cover EVERY listed source: one or more slots per dataset, plus a "web" slot when Web is available and the question touches world knowledge or recent events.
- clues must be self-contained phrases usable as retrieval hints.
-- `"scan"` — ONLY for a slot whose answer is a SET or a COUNT of things that someone DID ("how many named people did X kill", "which awards did Y win"): the words the SOURCE itself uses for that deed. Give EVERY phrasing you can think of, including the unusual ones (斩 / 杀 / 诛 / 劈 / 砍 / 刺 / 挥为两段 / 手起刀落 / 斩于马下): a passage phrased in a way no term covers is a passage no query ever names. At most 10 terms.
+- `"scan"` — ONLY for a slot whose answer is the MEMBERS THEMSELVES: the set of things someone DID ("how many named people did X kill", "which awards did Y win"). Such a slot is typed `entity` (named people) or `list` / `set` — NEVER `count`, `number`, `web` or `dataset`, and it is a slot OF ITS OWN even when the question asks "how many": the words are the SOURCE's own for that deed. Give EVERY phrasing you can think of, including the unusual ones (斩 / 杀 / 诛 / 劈 / 砍 / 刺 / 挥为两段 / 手起刀落 / 斩于马下): a passage phrased in a way no term covers is a passage no query ever names. At most 10 terms.
+- A "how many <things> did X do" question therefore declares TWO slots: the `count` (the number that was asked for) and the member set above, its dependency. The member slot carries `scan` + `subject`; the count slot carries neither.
- `"subject"` — next to `scan`, WHO the act is about, as the names the source uses for them, alternated: `关羽|关公|云长`. Omit it only when the slot is not about one actor.
- 1-4 first_queries: direct keyword-style searches against the listed sources.
- No prose outside JSON.