Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(wiki): 整页重写被补全预算截断时续写,续写用尽则拒绝写回(长名单 146→119) (#3582)

linus-liu-web653307b5c72d
diff --git a/internal/agent/prompts_wiki.go b/internal/agent/prompts_wiki.go
index c98a1821a..57f773338 100644
--- a/internal/agent/prompts_wiki.go
+++ b/internal/agent/prompts_wiki.go
@@ -402,6 +402,27 @@ The <new_information> block above is assembled from VERBATIM source chunks alrea
Output the SUMMARY line first, then the updated Markdown content. Do not include any other preamble.`
+// WikiPageModifyContinuationPrompt resumes a page rewrite that the provider cut
+// off at the completion budget (finish_reason=length). Long enumerations are the
+// shape that hits the cap: a certificate ledger with a hundred-plus holder rows
+// is emitted row by row, and the provider stops the model mid-table, so the page
+// is persisted one third short. The partial page is replayed as an assistant
+// turn and this prompt asks for the remainder — WITHOUT the replay the model
+// answers the original question again from the top, which is the #3446 spiral
+// the agent loop works around.
+const WikiPageModifyContinuationPrompt = `Your previous message was cut off because it reached the ` +
+ `output length limit, so the page is incomplete.
+
+Continue the SAME message from exactly where it stopped:
+1. Do NOT repeat anything you already wrote — not the SUMMARY line, not the headings, not the ` +
+ `rows, not the opening of the row you were in the middle of.
+2. Your reply is appended verbatim to what you already wrote. Its first characters must be exactly ` +
+ `the characters that follow the last character of your previous message. If you stopped in the ` +
+ `middle of a Markdown table row, finish that row first.
+3. Keep the same structure, formatting, ordering, and language as the part you already wrote.
+4. Output the continuation ONLY: no preamble, no apology, no explanation, no closing code fence.
+5. If the page was in fact already complete, reply with exactly: (complete)`
+
// WikiIndexIntroPrompt generates the introduction for a NEW index page (first time only).
const WikiIndexIntroPrompt = `You are a wiki editor. Write a brief introduction for a wiki knowledge base index page.
diff --git a/internal/application/service/wiki_ingest.go b/internal/application/service/wiki_ingest.go
index 097d85f8a..2ebc2eb14 100644
--- a/internal/application/service/wiki_ingest.go
+++ b/internal/application/service/wiki_ingest.go
@@ -190,6 +190,25 @@ return proposed
// shorter replies still stop early via finish_reason=stop. See #2604.
wikiLLMMaxTokens = 32768
+ // wikiPageModifyMaxContinuations bounds how many extra LLM rounds a page
+ // rewrite may take when the provider stopped at the completion budget
+ // (finish_reason=length). A page body is the one artifact whose value IS
+ // the whole text, so a fragment is not a usable answer: the editor is asked
+ // for the tail instead. Tables are enumerated top-down, so each round makes
+ // forward progress; 3 rounds cover a 32768-token budget being clamped to
+ // roughly a quarter by a provider or by a nearly-full context window.
+ //
+ // This is deliberately NOT the general strategy for every wiki call — see
+ // the agent loop's reasoning in internal/agent/observe.go: a continuation
+ // nudge only helps when the caller can tell the model "you were cut off,
+ // keep going", which for a JSON extraction is already covered by the
+ // parse-failure path.
+ wikiPageModifyMaxContinuations = 3
+
+ // wikiPageModifyContinuationDone is the sentinel a model may reply with
+ // when a continuation round finds nothing left to write.
+ wikiPageModifyContinuationDone = "(complete)"
+
// wikiLLMBackoffBase is the base delay for the exponential backoff
// between retry attempts. The nth retry waits base << (n-1) — so with
// a 2s base we wait 2s, 4s, 8s between attempts.
@@ -2598,17 +2617,71 @@ func (s *wikiIngestService) deduplicateExtractedBatch(
// transient 504 from the upstream gateway used to drop the document's
// summary page permanently. Retries plus failedOps requeuing (see
// mapOneDocument) turn those events into at-most-a-few-minute hiccups.
+//
+// Callers that need the provider stop reason — or that write a page body and
+// therefore care whether the answer was cut off — use
+// generateWithTemplateResult instead.
func (s *wikiIngestService) generateWithTemplate(ctx context.Context, chatModel chat.Chat, promptTpl string, data map[string]string) (string, error) {
+ result, err := s.generateWithTemplateResult(ctx, chatModel, promptTpl, data)
+ if err != nil {
+ return "", err
+ }
+ return result.Content, nil
+}
+
+// wikiTemplateResult is one wiki LLM answer: the text plus the provider's stop
+// reason. The stop reason used to be dropped on the floor, which is why a page
+// rewrite cut off at the completion budget was stored verbatim with no trace.
+type wikiTemplateResult struct {
+ Content string
+ FinishReason string
+}
+
+// errWikiPageRewriteTruncated is returned when the editor model stopped at the
+// completion budget and every continuation round did too. The caller treats it
+// like any other reduce failure: it logs, keeps the existing page, and flags the
+// addition as failed — a truncated page is never written.
+var errWikiPageRewriteTruncated = errors.New("wiki page rewrite truncated at the completion budget")
+
+// isLengthStopFinishReason reports whether a provider finish reason means the
+// answer was cut off by the completion budget rather than finished. Same
+// vocabulary as the agent loop (internal/agent/observe.go, compaction/overflow.go).
+func isLengthStopFinishReason(reason string) bool {
+ switch strings.ToLower(strings.TrimSpace(reason)) {
+ case "length", "max_tokens", "max_output_tokens":
+ return true
+ default:
+ return false
+ }
+}
+
+// generateWithTemplateResult is generateWithTemplate plus the provider stop
+// reason, and it is where a truncated page rewrite is continued instead of
+// accepted.
+//
+// Why continuation lives here: reduce hands the editor the WHOLE page and takes
+// back a full rewrite (see reduceSlugUpdates), so the model's output is not a
+// summary of the page, it IS the page. Long enumerations — a certificate ledger
+// with a hundred-plus holder rows — are emitted row by row and the provider
+// stops the model mid-table. Before this, the fragment was persisted verbatim:
+// a 146-row source table became a 119-row page, the page history showed an
+// ordinary edit, and nothing in the logs said "truncated".
+func (s *wikiIngestService) generateWithTemplateResult(
+ ctx context.Context,
+ chatModel chat.Chat,
+ promptTpl string,
+ data map[string]string,
+) (wikiTemplateResult, error) {
tmpl, err := template.New("wiki").Parse(promptTpl)
if err != nil {
- return "", fmt.Errorf("parse template: %w", err)
+ return wikiTemplateResult{}, fmt.Errorf("parse template: %w", err)
}
maskedData, urlMap := maskTemplateDataImageURLs(data)
var buf strings.Builder
if err := tmpl.Execute(&buf, maskedData); err != nil {
- return "", fmt.Errorf("execute template: %w", err)
+ return wikiTemplateResult{}, fmt.Errorf("execute template: %w", err)
}
prompt := buf.String()
@@ -2661,41 +2734,106 @@ func (s *wikiIngestService) generateWithTemplate(ctx context.Context, chatModel
var warmupErr error
releaseWarmup, warmupErr = s.awaitWikiPromptWarmup(ctx, warmupKey)
if warmupErr != nil {
- return "", warmupErr
+ return wikiTemplateResult{}, warmupErr
}
}
defer releaseWarmup()
- var lastErr error
- for attempt := 1; attempt <= wikiLLMMaxAttempts; attempt++ {
- response, callErr := chatModel.Chat(ctx, messages, opts)
- if callErr == nil && response != nil {
- return response.Content, nil
- }
- if callErr == nil {
- callErr = errors.New("LLM returned nil response")
+ // call runs one LLM request under the bounded transient-error retry
+ // policy and hands back the full response (the caller needs
+ // FinishReason, which the old signature threw away).
+ call := func(msgs []chat.Message) (*types.ChatResponse, error) {
+ var lastErr error
+ for attempt := 1; attempt <= wikiLLMMaxAttempts; attempt++ {
+ response, callErr := chatModel.Chat(ctx, msgs, opts)
+ if callErr == nil && response != nil {
+ return response, nil
+ }
+ if callErr == nil {
+ callErr = errors.New("LLM returned nil response")
+ }
+ lastErr = callErr
+
+ if !isTransientLLMError(ctx, callErr) {
+ return nil, fmt.Errorf("LLM call failed: %w", callErr)
+ }
+ if attempt == wikiLLMMaxAttempts {
+ break
+ }
+
+ backoff := wikiLLMBackoffBase << (attempt - 1)
+ logger.Warnf(ctx, "wiki ingest: LLM call failed (attempt %d/%d), retrying in %s: %v",
+ attempt, wikiLLMMaxAttempts, backoff, callErr)
+ timer := time.NewTimer(backoff)
+ select {
+ case <-ctx.Done():
+ timer.Stop()
+ return nil, fmt.Errorf("LLM call aborted during backoff: %w", ctx.Err())
+ case <-timer.C:
+ }
}
- lastErr = callErr
+ return nil, fmt.Errorf("LLM call failed after %d attempts: %w", wikiLLMMaxAttempts, lastErr)
+ }
- if !isTransientLLMError(ctx, callErr) {
- return "", fmt.Errorf("LLM call failed: %w", callErr)
+ // A page rewrite is the one answer whose value is the whole text: a
+ // fragment is a broken page, not a shorter answer. So when the provider
+ // stops at the completion budget, replay the fragment as an assistant
+ // turn and ask for the tail. Everything else keeps the single-call
+ // behaviour (a truncated JSON extraction already fails its parse).
+ canContinue := promptTpl == agent.WikiPageModifyUserPrompt
+
+ var (
+ rewrite strings.Builder
+ finishReason string
+ conversation = messages
+ )
+ for round := 0; ; round++ {
+ response, callErr := call(conversation)
+ if callErr != nil {
+ return wikiTemplateResult{}, callErr
}
- if attempt == wikiLLMMaxAttempts {
+ finishReason = response.FinishReason
+
+ // A continuation round that has nothing left to add ends the loop
+ // without appending its sentinel to the page.
+ if round > 0 && strings.EqualFold(strings.TrimSpace(response.Content), wikiPageModifyContinuationDone) {
+ finishReason = "stop"
break
}
- backoff := wikiLLMBackoffBase << (attempt - 1)
- logger.Warnf(ctx, "wiki ingest: LLM call failed (attempt %d/%d), retrying in %s: %v",
- attempt, wikiLLMMaxAttempts, backoff, callErr)
- timer := time.NewTimer(backoff)
- select {
- case <-ctx.Done():
- timer.Stop()
- return "", fmt.Errorf("LLM call aborted during backoff: %w", ctx.Err())
- case <-timer.C:
+ rewrite.WriteString(response.Content)
+
+ if !canContinue || !isLengthStopFinishReason(finishReason) || round >= wikiPageModifyMaxContinuations {
+ break
}
+
+ logger.Warnf(ctx,
+ "wiki ingest: page rewrite %s hit the completion budget (finish_reason=%s, "+
+ "%d chars so far); requesting continuation %d/%d",
+ maskedData["PageSlug"], finishReason, rewrite.Len(), round+1, wikiPageModifyMaxContinuations)
+
+ conversation = append(
+ append([]chat.Message(nil), conversation...),
+ chat.Message{Role: "assistant", Content: response.Content},
+ chat.Message{Role: "user", Content: agent.WikiPageModifyContinuationPrompt},
+ )
}
- return "", fmt.Errorf("LLM call failed after %d attempts: %w", wikiLLMMaxAttempts, lastErr)
+
+ content := rewrite.String()
+ if canContinue && isLengthStopFinishReason(finishReason) {
+ // Out of continuation rounds and still cut off. Refuse the fragment:
+ // the caller keeps the existing page and flags the addition, which is
+ // recoverable; storing a half page is not.
+ logger.Warnf(ctx,
+ "wiki ingest: page rewrite %s still truncated after %d continuation rounds "+
+ "(finish_reason=%s, %d chars); refusing the partial page",
+ maskedData["PageSlug"], wikiPageModifyMaxContinuations, finishReason, len(content))
+ return wikiTemplateResult{}, fmt.Errorf(
+ "%w (finish_reason=%s after %d continuation rounds, %d chars)",
+ errWikiPageRewriteTruncated, finishReason, wikiPageModifyMaxContinuations, len(content))
+ }
+
+ return wikiTemplateResult{Content: content, FinishReason: finishReason}, nil
}
// Missing tenant context is unexpected for production Wiki work. Fail safe
@@ -2704,22 +2842,24 @@ func (s *wikiIngestService) generateWithTemplate(ctx context.Context, chatModel
if !tenantScoped {
value, executeErr := execute()
if executeErr != nil {
- return "", executeErr
+ return wikiTemplateResult{}, executeErr
}
- content, _ := value.(string)
- return unmaskImageURLs(content, urlMap), nil
+ result, _ := value.(wikiTemplateResult)
+ result.Content = unmaskImageURLs(result.Content, urlMap)
+ return result, nil
}
resultCh := s.llmRequests.DoChan(requestKey, execute)
select {
case <-ctx.Done():
- return "", ctx.Err()
+ return wikiTemplateResult{}, ctx.Err()
case result := <-resultCh:
if result.Err != nil {
- return "", result.Err
+ return wikiTemplateResult{}, result.Err
}
- content, _ := result.Val.(string)
- return unmaskImageURLs(content, urlMap), nil
+ rewritten, _ := result.Val.(wikiTemplateResult)
+ rewritten.Content = unmaskImageURLs(rewritten.Content, urlMap)
+ return rewritten, nil
}
}
diff --git a/internal/application/service/wiki_page_rewrite_continuation_test.go b/internal/application/service/wiki_page_rewrite_continuation_test.go
new file mode 100644
index 000000000..a38c68a33
--- /dev/null
+++ b/internal/application/service/wiki_page_rewrite_continuation_test.go
@@ -0,0 +1,227 @@
+package service
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/agent"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// scriptedTemplateChatModel replays a fixed sequence of responses, one per
+// Chat call, and records every request it was handed.
+type scriptedTemplateChatModel struct {
+ responses []*types.ChatResponse
+ calls [][]chat.Message
+}
+
+func (m *scriptedTemplateChatModel) Chat(
+ _ context.Context,
+ messages []chat.Message,
+ _ *chat.ChatOptions,
+) (*types.ChatResponse, error) {
+ m.calls = append(m.calls, append([]chat.Message(nil), messages...))
+ if len(m.responses) == 0 {
+ return nil, errors.New("scriptedTemplateChatModel: unexpected extra call")
+ }
+ next := m.responses[0]
+ m.responses = m.responses[1:]
+ return next, nil
+}
+
+func (m *scriptedTemplateChatModel) ChatStream(
+ context.Context,
+ []chat.Message,
+ *chat.ChatOptions,
+) (<-chan types.StreamResponse, error) {
+ return nil, nil
+}
+
+func (m *scriptedTemplateChatModel) GetModelName() string { return "scripted" }
+func (m *scriptedTemplateChatModel) GetModelID() string { return "scripted" }
+
+// certLedgerRows renders a Markdown table row.
+func certLedgerRow(i int) string {
+ return fmt.Sprintf("| %d | 持证人%d | 杭州安恒信息技术股份有限公司 | 2020-01-01 | 2099-01-01 |", i, i)
+}
+
+// certLedgerBlock renders the first n rows of a 146-row certificate ledger — the
+// shape of the production page that came back short.
+func certLedgerBlock(first, last int) string {
+ var b strings.Builder
+ b.WriteString("SUMMARY: 持证人台账\n# 持证人台账\n\n| 编号 | 姓名 | 所属公司 | 有效期起 | 有效期止 |\n")
+ b.WriteString("| --- | --- | --- | --- | --- |\n")
+ for i := first; i <= last; i++ {
+ b.WriteString(certLedgerRow(i))
+ b.WriteString("\n")
+ }
+ return b.String()
+}
+
+func countLedgerRows(s string) int {
+ n := 0
+ for _, line := range strings.Split(s, "\n") {
+ line = strings.TrimSpace(line)
+ if strings.HasPrefix(line, "|") && strings.Trim(line, "|-: \t") != "" {
+ n++
+ }
+ }
+ return n
+}
+
+func modifyTemplateData() map[string]string {
+ return map[string]string{
+ "HasAdditions": "1",
+ "PageSlug": "entity/cisp-pte",
+ "PageTitle": "CISP-PTE 持证人台账",
+ "PageType": "entity",
+ "ExistingContent": "(New page)",
+ "NewContent": certLedgerBlock(1, 146),
+ "AvailableSlugs": "",
+ "Language": "Chinese",
+ "InstructionScope": "wiki_content",
+ "SharedSourceContexts": "",
+ }
+}
+
+// TestPageRewriteContinuesWhenProviderHitsCompletionBudget is the regression
+// for the "long list comes back short" report: the editor emits a page top-down,
+// the provider stops it at the completion budget (finish_reason=length) and the
+// fragment used to be persisted verbatim — a 146-row source table became a
+// 119-row page with nothing in the logs saying "truncated".
+func TestPageRewriteContinuesWhenProviderHitsCompletionBudget(t *testing.T) {
+ model := &scriptedTemplateChatModel{responses: []*types.ChatResponse{
+ {Content: certLedgerBlock(1, 119), FinishReason: "length"},
+ {Content: certLedgerBlock(120, 146), FinishReason: "stop"},
+ }}
+ service := &wikiIngestService{}
+
+ result, err := service.generateWithTemplateResult(
+ context.Background(), model, agent.WikiPageModifyUserPrompt, modifyTemplateData())
+ if err != nil {
+ t.Fatalf("generateWithTemplateResult() error = %v", err)
+ }
+
+ if got := countLedgerRows(result.Content); got != 148 {
+ t.Fatalf("stitched page has %d table rows, want 148 (146 holders + header + separator)", got)
+ }
+ if !strings.Contains(result.Content, certLedgerRow(146)) {
+ t.Fatal("stitched page is missing the last holder row")
+ }
+ if strings.Contains(result.Content, wikiPageModifyContinuationDone) {
+ t.Fatal("continuation sentinel leaked into the page")
+ }
+ if len(model.calls) != 2 {
+ t.Fatalf("Chat called %d times, want 2 (initial + one continuation)", len(model.calls))
+ }
+
+ // The continuation must replay the partial page as an assistant turn and
+ // follow it with the continuation instruction — without that the model
+ // answers the original question again from the top (#3446).
+ second := model.calls[1]
+ if len(second) != 4 {
+ t.Fatalf("continuation request has %d messages, want 4 (system, user, assistant, user)", len(second))
+ }
+ if second[2].Role != "assistant" || second[2].Content != certLedgerBlock(1, 119) {
+ t.Fatal("continuation request did not replay the partial page as an assistant turn")
+ }
+ if second[3].Role != "user" || second[3].Content != agent.WikiPageModifyContinuationPrompt {
+ t.Fatalf("continuation request missing the continuation instruction: %q", second[3].Content)
+ }
+ // The evidence block must survive: the tail is written from the same source
+ // material, not from the model's memory of the fragment.
+ if !strings.Contains(second[1].Content, certLedgerRow(146)) {
+ t.Fatal("continuation request dropped the source evidence block")
+ }
+}
+
+// TestPageRewriteStopsAtContinuationCap keeps the loop bounded: a provider that
+// stops on length every single round must not be retried forever.
+func TestPageRewriteStopsAtContinuationCap(t *testing.T) {
+ responses := make([]*types.ChatResponse, 0, wikiPageModifyMaxContinuations+1)
+ for i := 0; i <= wikiPageModifyMaxContinuations; i++ {
+ responses = append(responses, &types.ChatResponse{
+ Content: certLedgerRow(i+1) + "\n",
+ FinishReason: "length",
+ })
+ }
+ model := &scriptedTemplateChatModel{responses: responses}
+ service := &wikiIngestService{}
+
+ _, err := service.generateWithTemplateResult(
+ context.Background(), model, agent.WikiPageModifyUserPrompt, modifyTemplateData())
+ if !errors.Is(err, errWikiPageRewriteTruncated) {
+ t.Fatalf("error = %v, want errWikiPageRewriteTruncated", err)
+ }
+ if len(model.calls) != wikiPageModifyMaxContinuations+1 {
+ t.Fatalf("Chat called %d times, want %d", len(model.calls), wikiPageModifyMaxContinuations+1)
+ }
+}
+
+// TestPageRewriteAcceptsCompletePageUnchanged pins the no-op path: a rewrite
+// that stops naturally is returned as-is, with a single call.
+func TestPageRewriteAcceptsCompletePageUnchanged(t *testing.T) {
+ page := certLedgerBlock(1, 146)
+ model := &scriptedTemplateChatModel{responses: []*types.ChatResponse{
+ {Content: page, FinishReason: "stop"},
+ }}
+ service := &wikiIngestService{}
+
+ result, err := service.generateWithTemplateResult(
+ context.Background(), model, agent.WikiPageModifyUserPrompt, modifyTemplateData())
+ if err != nil {
+ t.Fatalf("generateWithTemplateResult() error = %v", err)
+ }
+ if result.Content != page || result.FinishReason != "stop" {
+ t.Fatal("a naturally stopped rewrite must be returned verbatim")
+ }
+ if len(model.calls) != 1 {
+ t.Fatalf("Chat called %d times, want 1", len(model.calls))
+ }
+}
+
+// TestContinuationIsScopedToPageRewrites keeps the single-call behaviour for the
+// JSON-producing prompts: stitching a truncated JSON document is the parse
+// path's job, not this loop's.
+func TestContinuationIsScopedToPageRewrites(t *testing.T) {
+ model := &scriptedTemplateChatModel{responses: []*types.ChatResponse{
+ {Content: `{"entities":[`, FinishReason: "length"},
+ }}
+ service := &wikiIngestService{}
+
+ result, err := service.generateWithTemplateResult(
+ context.Background(), model, `Content={{.Content}}`, map[string]string{"Content": "hello"})
+ if err != nil {
+ t.Fatalf("generateWithTemplateResult() error = %v", err)
+ }
+ if result.Content != `{"entities":[` || result.FinishReason != "length" {
+ t.Fatalf("non-page prompt was altered: %#v", result)
+ }
+ if len(model.calls) != 1 {
+ t.Fatalf("Chat called %d times, want 1", len(model.calls))
+ }
+}
+
+// TestPageRewriteContinuationDoneSentinel checks that a model which reports the
+// page was already complete does not have its sentinel appended to the page.
+func TestPageRewriteContinuationDoneSentinel(t *testing.T) {
+ page := certLedgerBlock(1, 146)
+ model := &scriptedTemplateChatModel{responses: []*types.ChatResponse{
+ {Content: page, FinishReason: "length"},
+ {Content: " (complete) ", FinishReason: "length"},
+ }}
+ service := &wikiIngestService{}
+
+ result, err := service.generateWithTemplateResult(
+ context.Background(), model, agent.WikiPageModifyUserPrompt, modifyTemplateData())
+ if err != nil {
+ t.Fatalf("generateWithTemplateResult() error = %v", err)
+ }
+ if result.Content != page {
+ t.Fatalf("sentinel was appended to the page: %q", result.Content)
+ }
+}