From 4a5fc4487b85dfdc9c6f0a1bdbfd5e83de4e5c9f Mon Sep 17 00:00:00 2001 From: wizardchen Date: Mon, 27 Jul 2026 13:21:27 +0800 Subject: [PATCH] fix(agent): keep batched wiki_read_page results within output budget Batch wiki reads used to lose middle pages when the registry applied head/tail truncation to the combined output. wiki_read_page now budgets per page, caps neighbour link summaries, and names omitted slugs explicitly. Also align registry truncation with rune-based limits and raise the default tool output ceiling to 24k characters. --- internal/agent/tools/output_budget.go | 71 +++++ internal/agent/tools/output_budget_test.go | 109 ++++++++ internal/agent/tools/registry.go | 13 +- internal/agent/tools/truncate.go | 2 +- .../agent/tools/wiki_read_page_budget_test.go | 161 +++++++++++ internal/agent/tools/wiki_tools.go | 260 +++++++++++++----- 6 files changed, 548 insertions(+), 68 deletions(-) create mode 100644 internal/agent/tools/output_budget.go create mode 100644 internal/agent/tools/output_budget_test.go create mode 100644 internal/agent/tools/wiki_read_page_budget_test.go diff --git a/internal/agent/tools/output_budget.go b/internal/agent/tools/output_budget.go new file mode 100644 index 00000000..bc80e0b9 --- /dev/null +++ b/internal/agent/tools/output_budget.go @@ -0,0 +1,71 @@ +package tools + +import "context" + +type outputBudgetKey struct{} + +// WithOutputBudget publishes the registry's output ceiling to the tool being +// executed. Tools that render several independent records in one result use it +// to shape their own output: the registry's fallback truncation keeps the head +// and tail of the whole blob, which for a batched result deletes the records in +// the middle and leaves the surviving ones cut mid-tag. +func WithOutputBudget(ctx context.Context, maxChars int) context.Context { + if ctx == nil || maxChars <= 0 { + return ctx + } + return context.WithValue(ctx, outputBudgetKey{}, maxChars) +} + +// OutputBudget returns the ceiling published by the registry, in runes, falling +// back to DefaultMaxToolOutput for callers that execute a tool directly. +func OutputBudget(ctx context.Context) int { + if ctx != nil { + if budget, ok := ctx.Value(outputBudgetKey{}).(int); ok && budget > 0 { + return budget + } + } + return DefaultMaxToolOutput +} + +// splitBudgetFairly performs max-min fair (water-filling) allocation of total +// across sizes: entries smaller than an equal share keep their full size and +// donate the slack to the larger entries. A batched result therefore degrades +// by trimming its biggest records rather than by dropping whole ones. +// +// The returned caps are never larger than the corresponding size, and their sum +// never exceeds total. +func splitBudgetFairly(total int, sizes []int) []int { + caps := make([]int, len(sizes)) + if len(sizes) == 0 || total <= 0 { + return caps + } + settled := make([]bool, len(sizes)) + remaining, unsettled := total, len(sizes) + for unsettled > 0 { + share := remaining / unsettled + if share <= 0 { + break + } + progressed := false + for i, size := range sizes { + if settled[i] || size > share { + continue + } + caps[i], settled[i] = size, true + remaining -= size + unsettled-- + progressed = true + } + if !progressed { + // Every entry still unsettled exceeds the fair share, so the + // remainder splits evenly and the allocation is complete. + for i := range sizes { + if !settled[i] { + caps[i] = share + } + } + break + } + } + return caps +} diff --git a/internal/agent/tools/output_budget_test.go b/internal/agent/tools/output_budget_test.go new file mode 100644 index 00000000..a4cb6cfa --- /dev/null +++ b/internal/agent/tools/output_budget_test.go @@ -0,0 +1,109 @@ +package tools + +import ( + "context" + "encoding/json" + "strings" + "testing" + "unicode/utf8" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// budgetProbeTool records the budget it observed and returns a caller-supplied +// output, so registry-level plumbing can be asserted end to end. +type budgetProbeTool struct { + observedBudget int + output string +} + +func (b *budgetProbeTool) Name() string { return "budget_probe" } +func (b *budgetProbeTool) Description() string { return "probe" } +func (b *budgetProbeTool) Parameters() json.RawMessage { return json.RawMessage(`{"type":"object"}`) } + +func (b *budgetProbeTool) Execute(ctx context.Context, _ json.RawMessage) (*types.ToolResult, error) { + b.observedBudget = OutputBudget(ctx) + return &types.ToolResult{Success: true, Output: b.output}, nil +} + +func TestOutputBudgetDefaultsWhenUnset(t *testing.T) { + var missingCtx context.Context + assert.Equal(t, DefaultMaxToolOutput, OutputBudget(context.Background())) + assert.Equal(t, DefaultMaxToolOutput, OutputBudget(missingCtx)) + assert.Equal(t, DefaultMaxToolOutput, OutputBudget(WithOutputBudget(context.Background(), 0))) +} + +// The registry owns the output ceiling, so a tool that wants to shape its own +// result has no other way to learn what it is. +func TestExecuteToolPublishesConfiguredBudget(t *testing.T) { + registry := NewToolRegistry() + registry.SetMaxToolOutputSize(1234) + probe := &budgetProbeTool{output: "ok"} + registry.RegisterTool(probe) + + _, err := registry.ExecuteTool(context.Background(), "budget_probe", json.RawMessage(`{}`)) + require.NoError(t, err) + assert.Equal(t, 1234, probe.observedBudget) +} + +// The ceiling is documented as a rune count. Comparing bytes here used to let +// CJK output through untouched, because 16000 runes of Chinese are ~48000 +// bytes: the byte check fired, then TruncateToolOutput saw a rune count under +// the limit and returned the blob unchanged. +func TestExecuteToolTruncatesCJKOutputByRuneCount(t *testing.T) { + registry := NewToolRegistry() + registry.SetMaxToolOutputSize(1000) + registry.RegisterTool(&budgetProbeTool{output: strings.Repeat("你", 5000)}) + + result, err := registry.ExecuteTool(context.Background(), "budget_probe", json.RawMessage(`{}`)) + require.NoError(t, err) + require.NotNil(t, result) + assert.Contains(t, result.Output, "output truncated") + assert.LessOrEqual(t, utf8.RuneCountInString(result.Output), 1000) +} + +func TestExecuteToolLeavesOutputWithinBudgetUntouched(t *testing.T) { + registry := NewToolRegistry() + registry.SetMaxToolOutputSize(1000) + output := strings.Repeat("你", 900) + registry.RegisterTool(&budgetProbeTool{output: output}) + + result, err := registry.ExecuteTool(context.Background(), "budget_probe", json.RawMessage(`{}`)) + require.NoError(t, err) + assert.Equal(t, output, result.Output) +} + +func TestSplitBudgetFairly(t *testing.T) { + t.Run("everything fits", func(t *testing.T) { + assert.Equal(t, []int{10, 20, 30}, splitBudgetFairly(100, []int{10, 20, 30})) + }) + + t.Run("small entries keep full size and donate slack", func(t *testing.T) { + // An equal split would be 30 each, but the 5-rune entry only needs 5, + // so its 25 spare runes are redistributed to the two large entries. + caps := splitBudgetFairly(90, []int{5, 1000, 1000}) + assert.Equal(t, 5, caps[0]) + assert.Equal(t, caps[1], caps[2]) + assert.Greater(t, caps[1], 30) + assert.LessOrEqual(t, caps[0]+caps[1]+caps[2], 90) + }) + + t.Run("never exceeds total or per-entry size", func(t *testing.T) { + sizes := []int{700, 20, 5000, 120} + caps := splitBudgetFairly(1000, sizes) + sum := 0 + for i, c := range caps { + assert.LessOrEqual(t, c, sizes[i], "cap must not exceed the entry size") + sum += c + } + assert.LessOrEqual(t, sum, 1000) + }) + + t.Run("degenerate inputs", func(t *testing.T) { + assert.Empty(t, splitBudgetFairly(100, nil)) + assert.Equal(t, []int{0, 0}, splitBudgetFairly(0, []int{10, 10})) + assert.Equal(t, []int{0, 0}, splitBudgetFairly(-5, []int{10, 10})) + }) +} diff --git a/internal/agent/tools/registry.go b/internal/agent/tools/registry.go index 3ef3d03a..53b70147 100644 --- a/internal/agent/tools/registry.go +++ b/internal/agent/tools/registry.go @@ -5,6 +5,7 @@ import ( "encoding/json" "fmt" "sort" + "unicode/utf8" "github.com/Tencent/WeKnora/internal/common" "github.com/Tencent/WeKnora/internal/logger" @@ -140,11 +141,15 @@ func (r *ToolRegistry) ExecuteTool( }, nil } - result, execErr := tool.Execute(ctx, args) - - // Truncate large tool outputs to prevent context window poisoning. + // Publish the ceiling so budget-aware tools can shape a batched result + // themselves; the truncation below stays as the fallback for the rest. maxOutput := r.getMaxToolOutput() - if result != nil && len(result.Output) > maxOutput { + result, execErr := tool.Execute(WithOutputBudget(ctx, maxOutput), args) + + // Truncate large tool outputs to prevent context window poisoning. The + // limit is counted in runes to match TruncateToolOutput; comparing bytes + // here would leave CJK output effectively uncapped. + if result != nil && utf8.RuneCountInString(result.Output) > maxOutput { result.Output = TruncateToolOutput(result.Output, maxOutput) } diff --git a/internal/agent/tools/truncate.go b/internal/agent/tools/truncate.go index 3021cc86..8b767603 100644 --- a/internal/agent/tools/truncate.go +++ b/internal/agent/tools/truncate.go @@ -9,7 +9,7 @@ const ( // DefaultMaxToolOutput is the default maximum character (rune) count for tool output. // Outputs exceeding this limit are truncated with head + tail preservation. // This counts Unicode characters (runes), not bytes, so CJK text is treated fairly. - DefaultMaxToolOutput = 16000 + DefaultMaxToolOutput = 24000 // headRatio controls the head/tail split when truncating (70% head, 30% tail). headRatio = 0.7 diff --git a/internal/agent/tools/wiki_read_page_budget_test.go b/internal/agent/tools/wiki_read_page_budget_test.go new file mode 100644 index 00000000..05949c34 --- /dev/null +++ b/internal/agent/tools/wiki_read_page_budget_test.go @@ -0,0 +1,161 @@ +package tools + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "testing" + "unicode/utf8" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// newBulkyWikiPage builds a page whose body alone is larger than a fair share +// of the default output budget. +func newBulkyWikiPage(kbID, slug string, bodyRunes int) *types.WikiPage { + page := newTestWikiPage(kbID, slug) + page.Summary = "summary of " + slug + page.Content = slug + " body " + strings.Repeat("x", bodyRunes) + return page +} + +func readPageOutput(t *testing.T, ctx context.Context, tool types.Tool, slugs []string) *types.ToolResult { + t.Helper() + args, err := json.Marshal(map[string]any{"slugs": slugs}) + require.NoError(t, err) + result, err := tool.Execute(ctx, args) + require.NoError(t, err) + require.NotNil(t, result) + require.True(t, result.Success, "wiki_read_page failed: %s", result.Error) + return result +} + +// assertWellFormedPages guards the property the old tail truncation broke: the +// UI pairs with , so an unbalanced block is dropped +// entirely rather than shown partially. +func assertWellFormedPages(t *testing.T, output string, want int) { + t.Helper() + assert.Equal(t, want, strings.Count(output, ""), "opening tags") + assert.Equal(t, want, strings.Count(output, ""), "closing tags") + assert.Equal(t, want, strings.Count(output, ""), "content sections") +} + +// A batch read used to lose its middle pages: the pages were concatenated and +// then cut to a head/tail window by the registry, so slugs 3..5 of a 5-slug +// call disappeared without any signal to the model. +func TestWikiReadPageKeepsEveryRequestedSlugWithinBudget(t *testing.T) { + slugs := []string{ + "concept/open-source-accessibility", + "entity/open-source-accessibility-community-day", + "concept/assistive-technology", + "entity/github-multilingual-repositories-dataset", + "concept/multilingual-ai", + } + pages := map[string]*types.WikiPage{} + for _, slug := range slugs { + pages[wikiPageKey("kb-1", slug)] = newBulkyWikiPage("kb-1", slug, 8000) + } + service := &fakeWikiPageService{pages: pages} + tool := NewWikiReadPageTool(service, nil, NewWikiScopesFromKBIDs([]string{"kb-1"}), NewWikiRouteResolver()) + + result := readPageOutput(t, context.Background(), tool, slugs) + + assertWellFormedPages(t, result.Output, len(slugs)) + for _, slug := range slugs { + assert.Contains(t, result.Output, fmt.Sprintf("[[%s|%s]]", slug, slug), + "every requested slug must still be rendered") + } + assert.LessOrEqual(t, utf8.RuneCountInString(result.Output), DefaultMaxToolOutput) + assert.NotContains(t, result.Output, " 0, nil } +const ( + // wikiMaxLinkSummaries bounds how many neighbour summaries are inlined per + // link section, and wikiLinkSummaryMaxRunes bounds each one. A hub page can + // carry dozens of links, and inlining every full summary used to spend more + // of the output budget than the page bodies the caller asked for. + wikiMaxLinkSummaries = 20 + wikiLinkSummaryMaxRunes = 150 + + // wikiMinPageBody is the smallest body slice worth rendering. When the + // budget cannot give every resolved page at least this much, trailing pages + // are named in instead of being cut mid-tag: a half-rendered + // is unparseable for the UI and silently misleading to the model. + wikiMinPageBody = 400 + + // wikiBudgetReserve holds back room for the and + // trailers appended after the pages are rendered. + wikiBudgetReserve = 600 +) + +// pendingWikiPage is a resolved page whose neighbour summaries, sources and +// body have been gathered but whose rendered size is not yet decided. +type pendingWikiPage struct { + page *types.WikiPage + kbID string + outLinks []string + inLinks []string + sources []string + body string +} + +func (p pendingWikiPage) render(body string) string { + return fmt.Sprintf(` + +%s +[[%s|%s]] +%s +%s + + +%s +%s + + +%s + + +%s + + +%s + +`, + p.kbID, + p.page.Slug, p.page.Title, p.page.PageType, + strings.Join(p.page.Aliases, ", "), + strings.Join(p.outLinks, ", "), + strings.Join(p.inLinks, ", "), + strings.Join(p.sources, "\n"), + p.page.Summary, + body, + ) +} + +// renderWikiPagesWithinBudget renders a batch of pages so that the result fits +// the tool output ceiling with every page still well-formed. Pages are trimmed +// by fair-sharing the body budget, and only when even a minimal body no longer +// fits are trailing pages dropped — by name, so the model knows to re-read them. +// +// It returns the joined output plus the slugs whose body was trimmed and the +// slugs that were not rendered at all. +func renderWikiPagesWithinBudget(pages []pendingWikiPage, budget int) (string, []string, []string) { + if len(pages) == 0 { + return "", nil, nil + } + + const separator = "\n\n" + separatorCost := utf8.RuneCountInString(separator) + + rendered := make([]string, len(pages)) + bodySizes := make([]int, len(pages)) + overheads := make([]int, len(pages)) + total := separatorCost * (len(pages) - 1) + for i, p := range pages { + rendered[i] = p.render(p.body) + size := utf8.RuneCountInString(rendered[i]) + bodySizes[i] = utf8.RuneCountInString(p.body) + overheads[i] = size - bodySizes[i] + total += size + } + + usable := budget - wikiBudgetReserve + if usable <= 0 || total <= usable { + return strings.Join(rendered, separator), nil, nil + } + + fixedCost := func(keep int) int { + cost := separatorCost * (keep - 1) + for i := 0; i < keep; i++ { + cost += overheads[i] + } + return cost + } + + keep := len(pages) + for keep > 1 && fixedCost(keep)+keep*wikiMinPageBody > usable { + keep-- + } + var omitted []string + for _, p := range pages[keep:] { + omitted = append(omitted, p.page.Slug) + } + + caps := splitBudgetFairly(usable-fixedCost(keep), bodySizes[:keep]) + outputs := make([]string, keep) + var truncated []string + for i := 0; i < keep; i++ { + if caps[i] >= bodySizes[i] { + outputs[i] = rendered[i] + continue + } + body := "(body omitted: output budget exhausted)" + if caps[i] > 0 { + body = TruncateToolOutput(pages[i].body, caps[i]) + } + outputs[i] = pages[i].render(body) + truncated = append(truncated, pages[i].page.Slug) + } + return strings.Join(outputs, separator), truncated, omitted +} + type wikiReadPageTool struct { BaseTool wikiService interfaces.WikiPageService @@ -381,12 +512,15 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* var slugsToFetch []string slugsToFetch = append(slugsToFetch, parseStringOrArray(params.Slugs)...) slugsToFetch = append(slugsToFetch, parseStringOrArray(params.Slug)...) + // A slug repeated inside `slugs`, or echoed in both `slug` and `slugs`, + // would otherwise be rendered twice and spend budget a distinct page needs. + slugsToFetch = dedupNonEmptyStrings(slugsToFetch) if len(slugsToFetch) == 0 { return &types.ToolResult{Success: false, Error: "Missing 'slugs' parameter"}, nil } - var outputs []string + var pending []pendingWikiPage var errs []string // Per-slug list of KB IDs where the slug was found. A slug may exist in // multiple KBs when the agent has several wiki KBs in scope. @@ -394,23 +528,39 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* formatLinks := func(slugs []string, kbID string) []string { var descs []string + inlined := 0 for _, s := range slugs { + if s == "" { + continue + } + // Past the cap the slug alone is enough: the model can always read + // a neighbour explicitly, whereas an unbounded link section costs + // one query per entry and crowds out the bodies actually requested. + if inlined >= wikiMaxLinkSummaries { + descs = append(descs, fmt.Sprintf("[[%s]]", s)) + continue + } + key := seenLinkKey(kbID, s) t.mu.Lock() seen := t.seenLinks[key] - t.seenLinks[key] = true t.mu.Unlock() - if seen { // We already injected the summary for this link in this session (within the same KB) descs = append(descs, fmt.Sprintf("[[%s]] (summary omitted, already seen)", s)) - } else { - if linkPage, err := t.wikiService.GetPageBySlug(ctx, kbID, s); err == nil && linkPage != nil { - descs = append(descs, fmt.Sprintf("[[%s]] (%s)", s, linkPage.Summary)) - } else { - descs = append(descs, fmt.Sprintf("[[%s]]", s)) - } + continue } + + linkPage, err := t.wikiService.GetPageBySlug(ctx, kbID, s) + if err != nil || linkPage == nil || linkPage.Summary == "" { + descs = append(descs, fmt.Sprintf("[[%s]]", s)) + continue + } + descs = append(descs, fmt.Sprintf("[[%s]] (%s)", s, truncateRunes(linkPage.Summary, wikiLinkSummaryMaxRunes))) + inlined++ + t.mu.Lock() + t.seenLinks[key] = true + t.mu.Unlock() } if len(descs) == 0 { return []string{"(none)"} @@ -418,26 +568,30 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* return descs } - renderPage := func(page *types.WikiPage, kbID string) string { - outLinksDesc := formatLinks(page.OutLinks, kbID) - inLinksDesc := formatLinks(page.InLinks, kbID) + // resolvePage gathers everything needed to render a page except its final + // size. Rendering is deferred until every requested slug has been resolved + // so the output budget can be shared across the whole batch. + resolvePage := func(page *types.WikiPage, kbID string) pendingWikiPage { + resolved := pendingWikiPage{ + page: page, + kbID: kbID, + outLinks: formatLinks(page.OutLinks, kbID), + inLinks: formatLinks(page.InLinks, kbID), + body: page.Content, + } - // Render source refs - var sourcesDesc []string - if len(page.SourceRefs) > 0 { - for _, ref := range page.SourceRefs { - // SourceRefs might be "knowledgeID" or "knowledgeID|Title" - kid := ref - title := "" - if pipeIdx := strings.Index(ref, "|"); pipeIdx > 0 { - kid = ref[:pipeIdx] - title = ref[pipeIdx+1:] - } - if title != "" { - sourcesDesc = append(sourcesDesc, fmt.Sprintf(`%s`, kid, title)) - } else { - sourcesDesc = append(sourcesDesc, fmt.Sprintf(``, kid)) - } + for _, ref := range page.SourceRefs { + // SourceRefs might be "knowledgeID" or "knowledgeID|Title" + kid := ref + title := "" + if pipeIdx := strings.Index(ref, "|"); pipeIdx > 0 { + kid = ref[:pipeIdx] + title = ref[pipeIdx+1:] + } + if title != "" { + resolved.sources = append(resolved.sources, fmt.Sprintf(`%s`, kid, title)) + } else { + resolved.sources = append(resolved.sources, fmt.Sprintf(``, kid)) } } @@ -449,10 +603,9 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* // top-K overview so the agent still sees the wiki's shape // without overflowing its context window — the explicit hint // steers the model to wiki_search for deeper exploration. - contentBody := page.Content if page.PageType == types.WikiPageTypeIndex { if overview, err := t.wikiService.GetIndexView(ctx, kbID, nil, wikiIndexAgentTopK, ""); err == nil && overview != nil { - contentBody = renderIndexOverviewForAgent(overview) + resolved.body = renderIndexOverviewForAgent(overview) for _, group := range overview.Groups { for _, item := range group.Items { t.routes.remember(item.Slug, kbID) @@ -461,36 +614,7 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* } } - return fmt.Sprintf(` - -%s -[[%s|%s]] -%s -%s - - -%s -%s - - -%s - - -%s - - -%s - -`, - kbID, - page.Slug, page.Title, page.PageType, - strings.Join(page.Aliases, ", "), - strings.Join(outLinksDesc, ", "), - strings.Join(inLinksDesc, ", "), - strings.Join(sourcesDesc, "\n"), - page.Summary, - contentBody, - ) + return resolved } // Track slugs that were found in the raw lookup but filtered out by a @@ -587,15 +711,23 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* // When routing remains ambiguous, emit every matched page so the model // can use or compare them explicitly. for _, h := range hits { - outputs = append(outputs, renderPage(h.page, h.kbID)) + pending = append(pending, resolvePage(h.page, h.kbID)) } } - if len(outputs) == 0 { + if len(pending) == 0 { return &types.ToolResult{Success: false, Error: strings.Join(errs, "; ")}, nil } - finalOutput := strings.Join(outputs, "\n\n") + finalOutput, truncatedSlugs, omittedSlugs := renderWikiPagesWithinBudget(pending, OutputBudget(ctx)) + if len(omittedSlugs) > 0 { + finalOutput += fmt.Sprintf( + "\n\n\n%s\n"+ + "\nThese pages were resolved but not rendered. "+ + "Call wiki_read_page again with fewer slugs to read them.", + strings.Join(omittedSlugs, "\n"), + ) + } if len(errs) > 0 { finalOutput += fmt.Sprintf("\n\n\n%s\n", strings.Join(errs, "\n")) } @@ -615,6 +747,8 @@ func (t *wikiReadPageTool) Execute(ctx context.Context, args json.RawMessage) (* Data: map[string]interface{}{ "found_kbs": foundKBs, "ambiguous_slugs": ambiguous, + "truncated_slugs": truncatedSlugs, + "omitted_slugs": omittedSlugs, }, }, nil }