Skip to content

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

feat(dataflow): cap debug-run chunk preview and surface run limits in tooltip (#18881)

xugangqiangb0feec834589
diff --git a/internal/ingestion/component/chunker/image_upload_test.go b/internal/ingestion/component/chunker/image_upload_test.go
index 261b105bb1..0527a507c7 100644
--- a/internal/ingestion/component/chunker/image_upload_test.go
+++ b/internal/ingestion/component/chunker/image_upload_test.go
@@ -25,7 +25,11 @@ import (
"testing"
"time"
+ "ragflow/internal/agent/runtime"
"ragflow/internal/common"
+ "ragflow/internal/ingestion/component/globals"
+
+ "gorm.io/gorm"
)
const (
@@ -321,3 +325,87 @@ func TestImageUploadDecorator_DebugSkipsUpload(t *testing.T) {
t.Errorf("img_id should not be set in debug run, got %q", id)
}
}
+
+// stubChunker is a deterministic fake runtime.Component used to exercise the
+// imageUploadDecorator without depending on a real chunker variant's slicing
+// behaviour. It returns exactly the chunks it was constructed with.
+type stubChunker struct {
+ chunks []map[string]any
+}
+
+func (s *stubChunker) Invoke(_ context.Context, _ *gorm.DB, _ map[string]any) (map[string]any, error) {
+ return map[string]any{"chunks": s.chunks}, nil
+}
+
+// TestImageUploadDecorator_DebugCapsChunks pins the canvas-debug chunk cap:
+// when CanvasState.Globals carries debug_chunk_cap (>=1), the decorator
+// truncates the chunker output to the leading N chunks for preview. This is
+// the single choke point that every chunker variant flows through, so the cap
+// applies regardless of which chunker variant produced the chunks. The test
+// drives a stub chunker (deterministic output) through the decorator with a
+// ctx that has the cap set, and asserts only the first N chunks survive.
+func TestImageUploadDecorator_DebugCapsChunks(t *testing.T) {
+ const capN = 3
+ src := make([]map[string]any, 0, 6)
+ for i := 0; i < 6; i++ {
+ src = append(src, map[string]any{
+ "content_with_weight": fmt.Sprintf("chunk-%d", i),
+ })
+ }
+ decorated := &imageUploadDecorator{inner: &stubChunker{chunks: src}}
+
+ inputs := map[string]any{
+ "name": "doc.pdf",
+ "kb_id": "", // debug run
+ "doc_id": testDocID,
+ }
+
+ st := &runtime.CanvasState{Globals: map[string]any{globals.DebugChunkCapKey: capN}}
+ ctx := runtime.WithState(context.Background(), st)
+
+ out, err := decorated.Invoke(ctx, nil, inputs)
+ if err != nil {
+ t.Fatalf("decorated Invoke: %v", err)
+ }
+ chunks, ok := out["chunks"].([]map[string]any)
+ if !ok {
+ t.Fatalf("chunks missing or wrong type: %#v", out["chunks"])
+ }
+ if len(chunks) != capN {
+ t.Fatalf("len(chunks) = %d, want %d (debug chunk cap not applied)", len(chunks), capN)
+ }
+ for i, ck := range chunks {
+ want := fmt.Sprintf("chunk-%d", i)
+ if got, _ := ck["content_with_weight"].(string); got != want {
+ t.Errorf("chunks[%d].content_with_weight = %q, want %q (wrong chunk kept after truncation)", i, got, want)
+ }
+ }
+}
+
+// TestImageUploadDecorator_NoCapKeepsAll asserts that without debug_chunk_cap
+// in globals the decorator leaves every chunk intact — the cap is opt-in via
+// the global, so persist runs and chunker-less debug runs are untouched.
+func TestImageUploadDecorator_NoCapKeepsAll(t *testing.T) {
+ src := make([]map[string]any, 0, 5)
+ for i := 0; i < 5; i++ {
+ src = append(src, map[string]any{
+ "content_with_weight": fmt.Sprintf("chunk-%d", i),
+ })
+ }
+ decorated := &imageUploadDecorator{inner: &stubChunker{chunks: src}}
+
+ inputs := map[string]any{
+ "name": "doc.pdf",
+ "kb_id": "",
+ "doc_id": testDocID,
+ }
+ // No CanvasState in ctx → DebugChunkCap returns 0 → no truncation.
+ out, err := decorated.Invoke(context.Background(), nil, inputs)
+ if err != nil {
+ t.Fatalf("decorated Invoke: %v", err)
+ }
+ chunks, ok := out["chunks"].([]map[string]any)
+ if !ok || len(chunks) != 5 {
+ t.Fatalf("len(chunks) = %d, want 5 (no cap should keep all)", len(chunks))
+ }
+}
diff --git a/internal/ingestion/component/chunker/register.go b/internal/ingestion/component/chunker/register.go
index 3c26c1f258..a17292ae1b 100644
--- a/internal/ingestion/component/chunker/register.go
+++ b/internal/ingestion/component/chunker/register.go
@@ -30,6 +30,7 @@ import (
"ragflow/internal/agent/runtime"
"ragflow/internal/common"
+ "ragflow/internal/ingestion/component/globals"
"gorm.io/gorm"
)
@@ -71,6 +72,20 @@ func (d *imageUploadDecorator) Invoke(ctx context.Context, db *gorm.DB, inputs m
if !ok || len(chunks) == 0 {
return out, nil
}
+
+ // Canvas-debug (dry-run) chunk cap: when set (>=1), keep only the leading
+ // N chunks for preview. This is the single choke point every chunker
+ // variant flows through, so the cap applies regardless of variant, and it
+ // also limits downstream compiler/tokenizer work in the debug run — the
+ // intended cost saving. Truncation happens FIRST, before any per-chunk
+ // work below: dropped chunks get no id computation and no image upload /
+ // byte dropping, so a chunk can never be persisted to storage and then
+ // discarded by this cap. No chunker node (or cap == 0) → untouched.
+ if chunkCap := globals.DebugChunkCap(ctx); chunkCap > 0 && len(chunks) > chunkCap {
+ chunks = chunks[:chunkCap]
+ out["chunks"] = chunks
+ }
+
kbID, docID := resolveImageUploadContext(ctx, inputs)
// Compute and write the deterministic chunk id (component.ChunkID) for
diff --git a/internal/ingestion/component/globals/globals.go b/internal/ingestion/component/globals/globals.go
index 3b744a8d2d..cdf5c1cdbe 100644
--- a/internal/ingestion/component/globals/globals.go
+++ b/internal/ingestion/component/globals/globals.go
@@ -66,6 +66,39 @@ var GlobalMetadataKeys = []string{
"tenant_id",
"kb_id",
"lang",
+ // debug_chunk_cap is debug-only (canvas dry-run). Production pipeline
+ // inputs never set it, and no component outputs it, so SeedIngestionGlobals
+ // / PublishGlobals only ever propagate it in a debug run — where the
+ // chunker decorator reads it to limit preview chunks.
+ DebugChunkCapKey,
+}
+
+// DebugChunkCapKey is the run-input key (seeded into CanvasState.Globals)
+// carrying the canvas-debug (dry-run) chunk cap: when >= 1, a chunker node in
+// a debug run emits at most this many leading chunks for preview. 0 means "no
+// cap" (no chunker, or cap disabled). The chunker decorator reads it via
+// DebugChunkCap; the executor seeds the default into run inputs only in the
+// debug branch of runPipelineWithDSL.
+const DebugChunkCapKey = "debug_chunk_cap"
+
+// DebugChunkCap reads the canvas-debug chunk cap from CanvasState.Globals.
+// Returns 0 when no cap is set (no debug run, no chunker node, or cap
+// disabled). The stored value is normally an int (Go-side default); a
+// JSON-decoded override may arrive as float64, both are accepted.
+func DebugChunkCap(ctx context.Context) int {
+ if st := canvasStateFromContext(ctx); st != nil {
+ if v, ok := st.GetGlobal(DebugChunkCapKey); ok {
+ switch n := v.(type) {
+ case int:
+ return n
+ case int64:
+ return int(n)
+ case float64:
+ return int(n)
+ }
+ }
+ }
+ return 0
}
// SeedIngestionGlobals copies the whitelisted run-level metadata from `in`
diff --git a/internal/ingestion/component/globals/globals_test.go b/internal/ingestion/component/globals/globals_test.go
new file mode 100644
index 0000000000..c418a42fc1
--- /dev/null
+++ b/internal/ingestion/component/globals/globals_test.go
@@ -0,0 +1,85 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package globals
+
+import (
+ "context"
+ "testing"
+
+ "ragflow/internal/agent/runtime"
+)
+
+// withChunkCap attaches a CanvasState carrying debug_chunk_cap to ctx.
+func withChunkCap(t *testing.T, cap int) context.Context {
+ t.Helper()
+ st := &runtime.CanvasState{Globals: map[string]any{DebugChunkCapKey: cap}}
+ return runtime.WithState(context.Background(), st)
+}
+
+// TestDebugChunkCap_DefaultZero asserts the cap reads 0 when no state is
+// attached (headless unit tests) or when the key is absent — 0 means "no cap".
+func TestDebugChunkCap_DefaultZero(t *testing.T) {
+ if got := DebugChunkCap(context.Background()); got != 0 {
+ t.Errorf("DebugChunkCap(nil ctx) = %d, want 0", got)
+ }
+ st := &runtime.CanvasState{Globals: map[string]any{}}
+ if got := DebugChunkCap(runtime.WithState(context.Background(), st)); got != 0 {
+ t.Errorf("DebugChunkCap(empty globals) = %d, want 0", got)
+ }
+}
+
+// TestDebugChunkCap_ReadsFromGlobals asserts the cap is read from
+// CanvasState.Globals, in all numeric shapes a run input may carry (int from a
+// Go-side default, float64 from a JSON-decoded override).
+func TestDebugChunkCap_ReadsFromGlobals(t *testing.T) {
+ cases := []struct {
+ name string
+ cap any
+ want int
+ }{
+ {"int default", 3, 3},
+ {"int64", int64(5), 5},
+ {"float64 from json", float64(7), 7},
+ }
+ for _, c := range cases {
+ t.Run(c.name, func(t *testing.T) {
+ ctx := runtime.WithState(context.Background(), &runtime.CanvasState{
+ Globals: map[string]any{DebugChunkCapKey: c.cap},
+ })
+ if got := DebugChunkCap(ctx); got != c.want {
+ t.Errorf("DebugChunkCap = %d, want %d", got, c.want)
+ }
+ })
+ }
+}
+
+// TestSeedIngestionGlobals_PicksUpDebugChunkCap asserts that adding
+// DebugChunkCapKey to GlobalMetadataKeys makes SeedIngestionGlobals copy the
+// run-input value into CanvasState.Globals — the link the executor relies on
+// to deliver the cap to the chunker decorator. Production inputs never set
+// this key, so persist runs are unaffected.
+func TestSeedIngestionGlobals_PicksUpDebugChunkCap(t *testing.T) {
+ st := &runtime.CanvasState{Globals: map[string]any{}}
+ ctx := runtime.WithState(context.Background(), st)
+ SeedIngestionGlobals(ctx, map[string]any{
+ "name": "doc.pdf",
+ DebugChunkCapKey: 3,
+ })
+ if got, ok := st.GetGlobal(DebugChunkCapKey); !ok || got != 3 {
+ t.Errorf("after SeedIngestionGlobals, globals[%q] = %v (ok=%v), want 3", DebugChunkCapKey, got, ok)
+ }
+}
diff --git a/internal/ingestion/knowledge_compile/scheduler.go b/internal/ingestion/knowledge_compile/scheduler.go
index 229cbcdb74..76430c9af8 100644
--- a/internal/ingestion/knowledge_compile/scheduler.go
+++ b/internal/ingestion/knowledge_compile/scheduler.go
@@ -787,6 +787,19 @@ func (f *FakeScheduler) Publish(_ context.Context, tenantID, datasetID, docID, e
return f.publishEntry(tenantID, datasetID, BacklogEntry{DocID: docID, EventType: eventType, Variants: variants})
}
+// PublishedCount returns the total number of backlog events published across
+// all datasets. Tests use it to assert that a code path did not trigger a
+// dataset-level knowledge-compile rebuild (PublishCompleted).
+func (f *FakeScheduler) PublishedCount() int {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ n := 0
+ for _, r := range f.rows {
+ n += len(r.backlog)
+ }
+ return n
+}
+
func (f *FakeScheduler) publishEntry(tenantID, datasetID string, entry BacklogEntry) error {
f.mu.Lock()
defer f.mu.Unlock()
diff --git a/internal/ingestion/task/debug.go b/internal/ingestion/task/debug.go
index b1e6ab5cbc..37ef9e08c6 100644
--- a/internal/ingestion/task/debug.go
+++ b/internal/ingestion/task/debug.go
@@ -23,6 +23,15 @@ import (
"ragflow/internal/entity"
)
+// DebugChunkCapDefault is the number of leading chunks a canvas-debug
+// (dataflow dry-run) keeps for preview when the pipeline contains a chunker
+// node. The debug run is a fast, side-effect-free check, so it surfaces only
+// the first few chunks rather than the whole document. The cap travels via
+// run inputs → CanvasState.Globals → the chunker decorator (globals.DebugChunkCap),
+// and is injected by the executor only in the debug branch. An explicit
+// caller-supplied cap is respected (see injectDebugChunkCap).
+const DebugChunkCapDefault = 3
+
// NewDebugTaskContext builds an in-memory TaskContext for a canvas-debug
// (dataflow dry-run) request. The returned context is intentionally
// side-effect free:
diff --git a/internal/ingestion/task/debug_test.go b/internal/ingestion/task/debug_test.go
index ed028d68d0..972f016f61 100644
--- a/internal/ingestion/task/debug_test.go
+++ b/internal/ingestion/task/debug_test.go
@@ -32,6 +32,8 @@ import (
"ragflow/internal/common"
"ragflow/internal/entity"
"ragflow/internal/ingestion/component"
+ "ragflow/internal/ingestion/component/globals"
+ "ragflow/internal/ingestion/knowledge_compile"
"ragflow/internal/ingestion/pipeline"
)
@@ -267,6 +269,91 @@ func TestInjectDebugPageCap(t *testing.T) {
})
}
+// TestInjectDebugChunkCap pins the canvas-debug chunk cap on the run inputs.
+// The cap travels via pipeline inputs → CanvasState.Globals (seeded by
+// globals.SeedIngestionGlobals) → the chunker decorator reads it through
+// globals.DebugChunkCap. It is injected only in the debug branch of
+// runPipelineWithDSL (mirroring the page-cap override). The default is
+// DebugChunkCapDefault (3); an explicit caller-supplied value is respected,
+// exactly like a caller-supplied page cap.
+func TestInjectDebugChunkCap(t *testing.T) {
+ t.Run("defaults to DebugChunkCapDefault when absent", func(t *testing.T) {
+ inputs := injectDebugChunkCap(map[string]any{"name": "doc.pdf"})
+ got, ok := inputs[globals.DebugChunkCapKey].(int)
+ if !ok {
+ t.Fatalf("inputs[%q] missing or wrong type: %#v", globals.DebugChunkCapKey, inputs[globals.DebugChunkCapKey])
+ }
+ if got != DebugChunkCapDefault {
+ t.Errorf("inputs[%q] = %d, want %d", globals.DebugChunkCapKey, got, DebugChunkCapDefault)
+ }
+ })
+
+ t.Run("respects explicit caller-supplied cap", func(t *testing.T) {
+ inputs := injectDebugChunkCap(map[string]any{
+ "name": "doc.pdf",
+ globals.DebugChunkCapKey: 9,
+ })
+ if got, _ := inputs[globals.DebugChunkCapKey].(int); got != 9 {
+ t.Errorf("inputs[%q] = %d, want 9 (explicit cap must be respected)", globals.DebugChunkCapKey, got)
+ }
+ })
+
+ t.Run("nil inputs is safe", func(t *testing.T) {
+ inputs := injectDebugChunkCap(nil)
+ if got, _ := inputs[globals.DebugChunkCapKey].(int); got != DebugChunkCapDefault {
+ t.Errorf("inputs[%q] = %d, want %d (nil inputs must be initialized)", globals.DebugChunkCapKey, got, DebugChunkCapDefault)
+ }
+ })
+}
+
+// TestExecute_DebugViaEntry_NoKnowledgeCompilePublish pins requirement #2:
+// a canvas-debug (dry-run) run must NOT trigger a dataset-level
+// knowledge-compile rebuild (no PublishCompleted / no notification), even when
+// the pipeline contains a knowledge-compiler node that completes. The debug
+// path returns via collectDebugOutput and never reaches processOutput (the
+// only caller of knowledge_compile.PublishCompleted), so a FakeScheduler
+// records zero publishes. The compiler component itself is structurally free
+// of any publish call (verified by grep), so this test locks the executor's
+// routing rather than the component.
+func TestExecute_DebugViaEntry_NoKnowledgeCompilePublish(t *testing.T) {
+ fake := knowledge_compile.NewFakeScheduler()
+ prev := knowledge_compile.DefaultPublisher()
+ knowledge_compile.SetScheduler(fake)
+ t.Cleanup(func() { knowledge_compile.SetScheduler(prev) })
+
+ taskCtx := NewDebugTaskContext("t1", "canvas-1", "doc.pdf", []byte("page one\fpage two\fpage three"))
+
+ exec, err := NewPipelineExecutor(taskCtx, "canvas-1", 0)
+ if err != nil {
+ t.Fatalf("NewPipelineExecutor: %v", err)
+ }
+ exec.
+ WithLoadDSLFunc(func(ctx context.Context, canvasID string) (string, string, error) {
+ return "dsl", "canvas-1", nil
+ }).
+ WithRunPipelineFunc(func(ctx context.Context, dsl string) (map[string]any, string, error) {
+ // Simulate a completed knowledge-compiler node plus chunks.
+ return map[string]any{
+ "chunks": []map[string]any{
+ {"text": "c1"},
+ {"text": "c2"},
+ },
+ "state": map[string]any{
+ "KnowledgeCompiler:Abc": map[string]any{
+ "compile_kwd": map[string]any{"structure": true},
+ },
+ },
+ }, dsl, nil
+ })
+
+ if _, err := exec.Execute(context.Background()); err != nil {
+ t.Fatalf("Execute: %v", err)
+ }
+ if n := fake.PublishedCount(); n != 0 {
+ t.Errorf("debug run published %d knowledge-compile event(s); want 0 (no dataset rebuild in debug)", n)
+ }
+}
+
// TestWarnUnknownComponentParamsDetectsUnknownCPNFromEnvelope pins the fix for
// the enveloped-DSL no-op bug: warnUnknownComponentParams previously passed the
// raw (enveloped) DSL straight to ExtractAllComponentParams, whose "components"
diff --git a/internal/ingestion/task/pipeline_executor.go b/internal/ingestion/task/pipeline_executor.go
index 3b5404d48e..a34eb590b2 100644
--- a/internal/ingestion/task/pipeline_executor.go
+++ b/internal/ingestion/task/pipeline_executor.go
@@ -32,6 +32,7 @@ import (
enginetypes "ragflow/internal/engine/types"
"ragflow/internal/entity"
"ragflow/internal/ingestion/component"
+ "ragflow/internal/ingestion/component/globals"
kccommon "ragflow/internal/ingestion/component/knowledge_compiler/common"
"ragflow/internal/ingestion/knowledge_compile"
pipelinepkg "ragflow/internal/ingestion/pipeline"
@@ -959,6 +960,14 @@ func (s *PipelineExecutor) runPipelineWithDSL(ctx context.Context, dsl string) (
if s.taskCtx.Doc.Type != "" {
inputs["file_type"] = s.taskCtx.Doc.Type
}
+ // A debug (dry-run) run with a chunker node keeps only the leading
+ // N chunks for preview. The cap is delivered through pipeline inputs
+ // (seeded into CanvasState.Globals by the pipeline run, read by the
+ // chunker decorator via globals.DebugChunkCap) — the same run-level
+ // channel as the other shared metadata, not override_params (the
+ // decorator is built at compile time and cannot read run-time
+ // override_params). An explicit caller-supplied cap is respected.
+ inputs = injectDebugChunkCap(inputs)
} else {
if s.taskCtx.File != nil {
inputs["file"] = s.taskCtx.File
@@ -1039,3 +1048,20 @@ func (s *PipelineExecutor) buildLogDSL(dsl string, output map[string]any) string
// inclusive range [1, debugPageCapPages], matching the production
// ParserConfig[cpnID][filetype]["pages"] shape (see NormalizeParserConfigPages).
const debugPageCapPages = 2
+
+// injectDebugChunkCap sets the canvas-debug chunk cap on the run inputs when
+// not already present. The cap is read by the chunker decorator (via
+// CanvasState.Globals / globals.DebugChunkCap) and limits a debug (dry-run)
+// preview to the leading N chunks. An existing value (a future caller-supplied
+// override) is respected, mirroring BuildParserPageCapOverride's respect for an
+// explicit page cap. A nil inputs map is initialized, so callers may pass a
+// concrete or nil map.
+func injectDebugChunkCap(inputs map[string]any) map[string]any {
+ if inputs == nil {
+ inputs = map[string]any{}
+ }
+ if _, ok := inputs[globals.DebugChunkCapKey]; !ok {
+ inputs[globals.DebugChunkCapKey] = DebugChunkCapDefault
+ }
+ return inputs
+}
diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts
index 3c8a68c6d1..f9710b7c21 100644
--- a/web/src/locales/en.ts
+++ b/web/src/locales/en.ts
@@ -3133,6 +3133,8 @@ Best for: Documents with flowing, contextually connected content — such as boo
optional: 'Optional',
pasteFileLink: 'Paste file link',
testRun: 'Test run',
+ debugRunLimits:
+ 'A debug run verifies that the flow executes without errors: PDF parses only the first 2 pages (other formats parse all pages); if a chunker node is present, only the first 3 chunks are previewed; if a knowledge-compiler node is present, it runs locally only and does not trigger a dataset rebuild or notification.',
template: 'Template',
templateDescription:
'A component that formats the output of other components.1. Supports Jinja2 templates, will first convert the input to an object and then render the template, 2. Simultaneously retains the original method of using {parameter} string replacement',
diff --git a/web/src/locales/zh.ts b/web/src/locales/zh.ts
index 665f2295fb..b8813f87db 100644
--- a/web/src/locales/zh.ts
+++ b/web/src/locales/zh.ts
@@ -2752,6 +2752,8 @@ NER:使用 spaCy NER 和基于规则的关键词提取来抽取 Entities 和 R
optional: '可选项',
pasteFileLink: '粘贴文件链接',
testRun: '试运行',
+ debugRunLimits:
+ '调试运行用于验证流程能否正常执行:PDF 仅解析前 2 页(其他格式解析全部);若含分块节点,仅取前 3 个分块预览;若含知识编译节点,仅本地验证、不会触发知识库重建或通知。',
template: '模板转换',
templateDescription:
'该组件用于排版各种组件的输出。1、支持 Jinja2 模板,会先将输入转为对象后进行模版渲染2、同时保留原使用{参数}字符串替换的方式',
diff --git a/web/src/pages/agent/flow-tooltip.tsx b/web/src/pages/agent/flow-tooltip.tsx
index 801b675b5e..f5b9efe468 100644
--- a/web/src/pages/agent/flow-tooltip.tsx
+++ b/web/src/pages/agent/flow-tooltip.tsx
@@ -6,13 +6,22 @@ import {
import { PropsWithChildren } from 'react';
import { useTranslation } from 'react-i18next';
-export const RunTooltip = ({ children }: PropsWithChildren) => {
+export interface RunTooltipProps extends PropsWithChildren {
+ /**
+ * i18n key for the tooltip copy. Defaults to "flow.testRun" (the existing
+ * test-run tooltip). The canvas "Run" button passes "flow.debugRunLimits"
+ * to describe the Go-side debug (dry-run) preview limits.
+ */
+ tooltip?: string;
+}
+
+export const RunTooltip = ({ children, tooltip = 'flow.testRun' }: RunTooltipProps) => {
const { t } = useTranslation();
return (
<Tooltip>
<TooltipTrigger asChild>{children}</TooltipTrigger>
<TooltipContent>
- <p>{t('flow.testRun')}</p>
+ <p>{t(tooltip)}</p>
</TooltipContent>
</Tooltip>
);
diff --git a/web/src/pages/agent/index.tsx b/web/src/pages/agent/index.tsx
index 69d8e6de7c..a2445bd2cd 100644
--- a/web/src/pages/agent/index.tsx
+++ b/web/src/pages/agent/index.tsx
@@ -40,6 +40,7 @@ import {
} from 'lucide-react';
import { ComponentPropsWithoutRef, useCallback, useMemo } from 'react';
import { useTranslation } from 'react-i18next';
+import { useSyncExternalStore } from 'react';
import { useParams } from 'react-router';
import AgentCanvas from './canvas';
import { DropdownProvider } from './canvas/context';
@@ -72,6 +73,12 @@ import useGraphStore from './store';
import { useAgentHistoryManager } from './use-agent-history-manager';
import { VersionDialog } from './version-dialog';
import WebhookSheet from './webhook-sheet';
+import { RunTooltip } from './flow-tooltip';
+import {
+ debugRunLimitsTooltipKey,
+ isGoBackend,
+ subscribeBackendLanguage,
+} from '@/utils/backend-runtime';
/**
* Standardizes dropdown menu item styling for agent management actions.
@@ -103,6 +110,14 @@ export default function Agent() {
} = useSetModalState();
const { t } = useTranslation();
useAgentHistoryManager();
+ // Resolves (and re-renders when it resolves) the i18n key for the canvas
+ // "Run" tooltip describing the Go-side debug preview limits. It is shown
+ // ONLY for a dataflow (ingestion pipeline) canvas on the golang backend —
+ // an agent canvas runs the agent, not an ingestion debug preview, so it
+ // must never show this tooltip.
+ const runTooltipKey = useSyncExternalStore(subscribeBackendLanguage, () =>
+ debugRunLimitsTooltipKey(isGoBackend(), isPipeline),
+ );
const { handleExportJson } = useHandleExportJsonFile();
const { saveGraph, loading } = useSaveGraph();
@@ -228,6 +243,19 @@ export default function Agent() {
showWebhookTestSheet,
]);
+ // Single source for the Run button so the tooltip gating in the JSX below
+ // doesn't duplicate it.
+ const runButton = (
+ <Button
+ data-testid="agent-run"
+ variant={'secondary'}
+ onClick={handleButtonRunClick}
+ >
+ <CirclePlay />
+ {t('flow.run')}
+ </Button>
+ );
+
const {
run: runPipeline,
loading: pipelineRunning,
@@ -294,14 +322,11 @@ export default function Agent() {
>
<LaptopMinimalCheck /> {t('flow.save')}
</ButtonLoading>
- <Button
- data-testid="agent-run"
- variant={'secondary'}
- onClick={handleButtonRunClick}
- >
- <CirclePlay />
- {t('flow.run')}
- </Button>
+ {runTooltipKey ? (
+ <RunTooltip tooltip={runTooltipKey}>{runButton}</RunTooltip>
+ ) : (
+ runButton
+ )}
{isConversationMode && (
<Button
variant={'secondary'}
diff --git a/web/src/utils/__tests__/backend-runtime.test.ts b/web/src/utils/__tests__/backend-runtime.test.ts
new file mode 100644
index 0000000000..70f77b4e34
--- /dev/null
+++ b/web/src/utils/__tests__/backend-runtime.test.ts
@@ -0,0 +1,19 @@
+import { debugRunLimitsTooltipKey } from '@/utils/backend-runtime';
+
+describe('debugRunLimitsTooltipKey', () => {
+ it('returns the key only for a dataflow (ingestion pipeline) canvas on golang', () => {
+ expect(debugRunLimitsTooltipKey(true, true)).toBe('flow.debugRunLimits');
+ });
+
+ it('returns null for an agent canvas even on golang (no ingestion debug preview)', () => {
+ expect(debugRunLimitsTooltipKey(true, false)).toBeNull();
+ });
+
+ it('returns null on the python backend even for a dataflow canvas', () => {
+ expect(debugRunLimitsTooltipKey(false, true)).toBeNull();
+ });
+
+ it('returns null when neither condition holds', () => {
+ expect(debugRunLimitsTooltipKey(false, false)).toBeNull();
+ });
+});
diff --git a/web/src/utils/backend-runtime.ts b/web/src/utils/backend-runtime.ts
index 298c280961..f7bddd9757 100644
--- a/web/src/utils/backend-runtime.ts
+++ b/web/src/utils/backend-runtime.ts
@@ -50,6 +50,29 @@ export const getBackendLanguage = (): string | null => backendLanguage;
export const isGoBackend = (): boolean => backendLanguage === 'go';
+/**
+ * debugRunLimitsTooltipKey returns the i18n key for the canvas "Run" button
+ * tooltip describing the debug (dry-run) preview limits, or null when the
+ * tooltip should not be shown.
+ *
+ * The tooltip applies ONLY to a dataflow (ingestion pipeline) canvas on the
+ * golang backend. An agent canvas runs the agent/chat, not an ingestion
+ * debug preview, so it must never show this tooltip. The python backend's
+ * debug semantics also differ and are out of scope.
+ *
+ * It is a pure function of (backend language, is-pipeline) so it can be
+ * unit-tested without mocking, and the Agent derives it via
+ * useSyncExternalStore(subscribeBackendLanguage, () =>
+ * debugRunLimitsTooltipKey(isGoBackend(), isPipeline)).
+ *
+ * The tooltip copy itself never names the backend language; only its
+ * visibility is gated on these conditions.
+ */
+export const debugRunLimitsTooltipKey = (
+ isGo: boolean,
+ isPipeline: boolean,
+): string | null => (isGo && isPipeline ? 'flow.debugRunLimits' : null);
+
export const subscribeBackendLanguage = (listener: Listener): (() => void) => {
listeners.add(listener);
return () => {