RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Refine citation for agentic RAG (#19822)
Yingfenge84a0e2caabd
diff --git a/internal/rag/agentic-rag/agentic_rag.go b/internal/rag/agentic-rag/agentic_rag.goindex 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, lp.resp.Answer = answerp.resp.Chunks = p.kb.Chunksp.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) == 0loop.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.Chunksp.resp.DocAggs = p.kb.DocAggsp.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.goindex 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) []mareturn 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 strinif 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.MaxTokensif 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.goindex 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, loif 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 rufor _, 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 := 0for _, rt := range kb.ReachedTerms() {term := strings.TrimSpace(rt.Term)@@ -216,7 +229,7 @@ func coverageResolveCandidates(kb *runtime.Kbinfos, table *runtime.State, cov ruif 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] = trueadded++}@@ -238,6 +251,7 @@ func coverageResolveCandidates(kb *runtime.Kbinfos, table *runtime.State, cov ruif windowQuotesTerm(set.Windows, w.ChunkID, term) {continue}+ w.Source = runtime.CoverageSourceClaimset.Windows = append(set.Windows, w)}known[key] = truediff --git a/internal/rag/agentic-rag/graph_compose.go b/internal/rag/agentic-rag/graph_compose.goindex 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.Kbinfoslogger.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.Strif 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 thediff --git a/internal/rag/agentic-rag/runtime/coverage.go b/internal/rag/agentic-rag/runtime/coverage.goindex 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.goindex 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 = 1000coverageWindowsPerChunk = 3coverageWindowBefore = 80coverageWindowAfter = 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 stringQuote stringAct 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 *Kif 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 = truebreak}- 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, 0for _, 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.goindex 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 = 8coverageResolveQuoteChars = 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, creturn 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.goindex 8687bcc177..b909c49258 100644--- a/internal/rag/agentic-rag/runtime/items.go+++ b/internal/rag/agentic-rag/runtime/items.go@@ -17,6 +17,8 @@package runtimeimport (+ "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.goindex 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.goindex 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.mdindex 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.