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
fix(web): restore entity type colors in knowledge graphs (#21443)
cht30359a7e8883
diff --git a/web/src/components/artifact-force-graph/__tests__/index.test.tsx b/web/src/components/artifact-force-graph/__tests__/index.test.tsxindex 285b69c3ea..b8e2be6aff 100644--- a/web/src/components/artifact-force-graph/__tests__/index.test.tsx+++ b/web/src/components/artifact-force-graph/__tests__/index.test.tsx@@ -1,23 +1,29 @@-import { render, screen } from '@testing-library/react';+import { act, render, screen } from '@testing-library/react';import { createElement } from 'react';+import { getKnowledgeGraphNodeLabel } from '@/components/structure-graph/use-knowledge-graph-node-style';import ArtifactForceGraph from '..';+const mockGraphRender = jest.fn();+const mockZoomToFit = jest.fn();+jest.mock('react-force-graph-2d', () => {const ReactLib = jest.requireActual<typeof import('react')>('react');const MockForceGraph = ReactLib.forwardRef<- HTMLDivElement,+ { zoomToFit: typeof mockZoomToFit },{graphData: { nodes: Array<{ description?: string }> };nodeLabel: (node: { description?: string }) => string;}- >(({ graphData, nodeLabel }, ref) => {+ >((props, ref) => {+ const { graphData, nodeLabel } = props;+ mockGraphRender(props);+ ReactLib.useImperativeHandle(ref, () => ({ zoomToFit: mockZoomToFit }));const label = nodeLabel(graphData.nodes[0]);if (!label) return null;// Match the graph library's HTML tooltip sink instead of rendering text.return ReactLib.createElement('div', {- ref,'data-testid': 'node-tooltip',dangerouslySetInnerHTML: { __html: label },});@@ -38,7 +44,10 @@ jest.mock('react-i18next', () => ({useTranslation: () => ({ t: (key: string) => key }),}));-function renderGraph(description: string) {+function renderGraph(+ description: string,+ props: Pick<import('../types').ArtifactForceGraphProps, 'getNodeLabel'> = {},+) {return render(createElement(ArtifactForceGraph, {data: {@@ -54,6 +63,7 @@ function renderGraph(description: string) {],relations: [],},+ ...props,}),);}@@ -76,4 +86,72 @@ describe('ArtifactForceGraph node tooltip', () => {expect(screen.queryByTestId('node-tooltip')).toBeNull();});++ it('escapes the type and description from a custom plain-text label once', () => {+ const type = '<img src=x onerror=alert(1)> <type>';+ const description = '<script>bad()</script> & 齿轮';+ renderGraph(description, {+ getNodeLabel: (node) => getKnowledgeGraphNodeLabel({ ...node, type }),+ });++ const tooltip = screen.getByTestId('node-tooltip');+ expect(tooltip.textContent).toBe(`${type} · ${description}`);+ expect(tooltip.querySelector('img, script')).toBeNull();+ });++ it('shows the knowledge graph type even without a description', () => {+ renderGraph('', { getNodeLabel: getKnowledgeGraphNodeLabel });+ expect(screen.getByTestId('node-tooltip')).toHaveTextContent('entity');+ });++ it('keeps graph objects and fitting stable across label, pinned and hover changes', () => {+ mockZoomToFit.mockClear();+ const data: import('@/interfaces/database/dataset').IArtifactGraph = {+ entities: ['a', 'b', 'c'].map((slug) => ({+ slug,+ name: slug,+ aliases: [],+ description: slug,+ type: 'entity',+ weight: 1,+ })),+ relations: [{ from: 'a', to: 'b' }],+ };+ const getNodeColor = () => '#4e79a7';+ const { rerender } = render(+ <ArtifactForceGraph data={data} getNodeColor={getNodeColor} />,+ );+ const initial = mockGraphRender.mock.calls.at(-1)![0];+ const [a, b, c] = initial.graphData.nodes;+ act(() => initial.onEngineStop());+ expect(mockZoomToFit).toHaveBeenCalledTimes(1);++ rerender(+ <ArtifactForceGraph+ data={data}+ getNodeColor={getNodeColor}+ getNodeLabel={getKnowledgeGraphNodeLabel}+ highlightNodeId="a"+ />,+ );+ const pinned = mockGraphRender.mock.calls.at(-1)![0];+ expect(pinned.graphData).toBe(initial.graphData);+ expect(pinned.graphData.nodes[0]).toBe(a);+ expect(pinned.nodeColor(a)).toBe('#4e79a7');+ expect(pinned.nodeColor(b)).toBe('#4e79a7');+ expect(pinned.nodeColor(c)).toBe('#4e79a733');+ act(() => pinned.onEngineStop());+ expect(mockZoomToFit).toHaveBeenCalledTimes(1);++ act(() => pinned.onNodeHover(c));+ const hovered = mockGraphRender.mock.calls.at(-1)![0];+ expect(hovered.graphData).toBe(initial.graphData);+ expect(hovered.nodeColor(c)).toBe('#4e79a7');+ expect(hovered.nodeColor(a)).toBe('#4e79a733');+ act(() => hovered.onNodeHover(null));+ const restored = mockGraphRender.mock.calls.at(-1)![0];+ expect(restored.graphData).toBe(initial.graphData);+ expect(restored.nodeColor(a)).toBe('#4e79a7');+ expect(restored.nodeColor(c)).toBe('#4e79a733');+ });});diff --git a/web/src/components/artifact-force-graph/index.tsx b/web/src/components/artifact-force-graph/index.tsxindex c3b36b4478..fc7b861291 100644--- a/web/src/components/artifact-force-graph/index.tsx+++ b/web/src/components/artifact-force-graph/index.tsx@@ -37,9 +37,17 @@ import { useGraphHighlight } from './use-graph-highlight';import { defaultMapNodeToValue } from './utils';const defaultGetNodeId = (node: IArtifactGraphEntity) => node.slug;+/** Returns the entity description as the default plain-text tooltip. */+const defaultGetNodeLabel = (node: IArtifactGraphEntity) =>+ node.description ?? '';const nodeCanvasObjectMode = () => 'after' as const;+/**+ * Renders an interactive force graph with configurable node styles and labels.+ * Escapes tooltip text and coordinates zoom-to-fit, hover and pinned-node+ * highlighting, and mapped node-click callbacks.+ */function ArtifactForceGraph<TNodeValue = IArtifactGraphEntity>({data,show = true,@@ -49,6 +57,7 @@ function ArtifactForceGraph<TNodeValue = IArtifactGraphEntity>({) => TNodeValue,getNodeId = defaultGetNodeId,getNodeColor = defaultGetNodeColor,+ getNodeLabel = defaultGetNodeLabel,getNodeRadius = defaultGetNodeRadius,highlightNodeId,totalEntities,@@ -113,10 +122,10 @@ function ArtifactForceGraph<TNodeValue = IArtifactGraphEntity>({[],);- // ForceGraph treats tooltip strings as HTML; descriptions are plain text.- const getNodeLabel = useCallback(- (node: ArtifactGraphNode) => escape(node.description ?? ''),- [],+ /** Escapes plain-text node labels for ForceGraph's HTML tooltip renderer. */+ const getEscapedNodeLabel = useCallback(+ (node: ArtifactGraphNode) => escape(getNodeLabel(node)),+ [getNodeLabel],);// Empty label hides the tooltip, so relations without a type show nothing@@ -140,7 +149,7 @@ function ArtifactForceGraph<TNodeValue = IArtifactGraphEntity>({nodeColor={nodeColor}nodeVal={nodeVal}cooldownTicks={100}- nodeLabel={getNodeLabel}+ nodeLabel={getEscapedNodeLabel}autoPauseRedraw={false}onEngineStop={handleEngineStop}onNodeClick={handleNodeClick}diff --git a/web/src/components/artifact-force-graph/types.ts b/web/src/components/artifact-force-graph/types.tsindex ede2787444..fc8b0656ac 100644--- a/web/src/components/artifact-force-graph/types.ts+++ b/web/src/components/artifact-force-graph/types.ts@@ -40,6 +40,8 @@ export interface ArtifactForceGraphProps<TNodeValue = IArtifactGraphEntity> {mapNodeToValue?: (node: IArtifactGraphEntity) => TNodeValue;getNodeId?: (node: IArtifactGraphEntity) => string;getNodeColor?: (node: IArtifactGraphEntity) => string;+ /** Plain tooltip text; escaped once by the graph before rendering as HTML. */+ getNodeLabel?: (node: IArtifactGraphEntity) => string;getNodeRadius?: (node: IArtifactGraphEntity,minWeight: number,diff --git a/web/src/components/structure-graph/__tests__/knowledge-graph-node-style.test.ts b/web/src/components/structure-graph/__tests__/knowledge-graph-node-style.test.tsnew file mode 100644index 0000000000..bb8d6377cd--- /dev/null+++ b/web/src/components/structure-graph/__tests__/knowledge-graph-node-style.test.ts@@ -0,0 +1,151 @@+import { renderHook } from '@testing-library/react';+import { readFileSync } from 'node:fs';+import { resolve } from 'node:path';+import { type IArtifactGraphEntity } from '@/interfaces/database/dataset';+import { withAlpha } from '@/components/artifact-force-graph/utils';+import {+ getKnowledgeGraphNodeLabel,+ useKnowledgeGraphNodeColor,+} from '../use-knowledge-graph-node-style';++const Css = readFileSync(+ resolve(__dirname, '../../../../tailwind.css'),+ 'utf8',+);+const Tokens = [+ ...Css.matchAll(/(--graph-node-(?:\d+|other)):\s*(#[\da-f]{6});/g),+];+const entity = (type: unknown, description = ''): IArtifactGraphEntity => ({+ slug: 'test',+ name: 'test',+ aliases: [],+ type: type as string,+ description,+ weight: 1,+});++beforeAll(() => {+ Tokens.forEach(([, name, color]) =>+ document.documentElement.style.setProperty(name, color),+ );+});+afterAll(() => {+ Tokens.forEach(([, name]) =>+ document.documentElement.style.removeProperty(name),+ );+});++describe('knowledge graph type colors', () => {+ it('uses concrete CSS palette colors compatible with existing dimming', () => {+ expect(Tokens).toHaveLength(11);+ const { result } = renderHook(useKnowledgeGraphNodeColor);+ const colors = Tokens.map(([, , color]) => color);+ const color = result.current(entity('person'));+ expect(colors).toContain(color);+ expect(withAlpha(color, 0.2)).toBe(`${color}33`);+ });++ it('stays stable for shuffled, filtered, expanded and newly mounted graphs', () => {+ const types = [+ 'person',+ 'organization',+ '地点',+ 'time',+ 'location',+ '任意类型',+ '🧭',+ ];+ const first = renderHook(useKnowledgeGraphNodeColor);+ const initial = new Map(+ types.map((type) => [type, first.result.current(entity(type))]),+ );+ for (const type of [...types].reverse()) {+ expect(first.result.current(entity(type))).toBe(initial.get(type));+ }+ first.result.current(entity('new type'));+ const second = renderHook(useKnowledgeGraphNodeColor);+ for (const type of types.slice(2, 5)) {+ expect(second.result.current(entity(type))).toBe(initial.get(type));+ }+ });++ it('normalizes only whitespace and case for colors, preserving original label text', () => {+ const { result } = renderHook(useKnowledgeGraphNodeColor);+ expect(result.current(entity(' Person '))).toBe(+ result.current(entity('person')),+ );+ const node = entity(' Person ', 'Original description');+ expect(getKnowledgeGraphNodeLabel(node)).toBe(+ ' Person · Original description',+ );+ expect(node.type).toBe(' Person ');+ expect(node.description).toBe('Original description');+ });++ it.each([undefined, null, '', ' ', 'other', ' OTHER ', {}, 42])(+ 'uses the default color for missing/other type %p',+ (type) => {+ const { result } = renderHook(useKnowledgeGraphNodeColor);+ const defaultColor = Tokens.find(+ ([, name]) => name === '--graph-node-other',+ )![2];+ expect(result.current(entity(type))).toBe(defaultColor);+ },+ );++ it('keeps arbitrary named types, including unknown, in the categorical palette', () => {+ const { result } = renderHook(useKnowledgeGraphNodeColor);+ const defaultColor = result.current(entity('other'));+ for (const type of ['unknown', 'custom type', '中文类型', '__proto__']) {+ expect(result.current(entity(type))).not.toBe(defaultColor);+ expect(getKnowledgeGraphNodeLabel(entity(type))).toBe(type);+ }+ });++ it('documents real hash collisions without changing or merging their labels', () => {+ const { result } = renderHook(useKnowledgeGraphNodeColor);+ // FNV-1a UTF-16 modulo 10 is deliberately bounded, including ordinary types.+ for (const [first, second] of [+ ['organization', '地点'],+ ['time', 'location'],+ ]) {+ expect(result.current(entity(first))).toBe(+ result.current(entity(second)),+ );+ expect(getKnowledgeGraphNodeLabel(entity(first))).not.toBe(+ getKnowledgeGraphNodeLabel(entity(second)),+ );+ }+ expect(result.current(entity('organization'))).toBe(+ Tokens.find(([, name]) => name === '--graph-node-3')![2],+ );+ expect(result.current(entity('time'))).toBe(+ Tokens.find(([, name]) => name === '--graph-node-7')![2],+ );+ // Supplementary characters hash both UTF-16 code units, not one code point.+ expect(result.current(entity('🧭'))).toBe(+ Tokens.find(([, name]) => name === '--graph-node-5')![2],+ );+ });++ it('reads the palette once and keeps the color callback stable on rerender', () => {+ const getStyle = jest.spyOn(window, 'getComputedStyle');+ const { result, rerender } = renderHook(useKnowledgeGraphNodeColor);+ const callback = result.current;+ const calls = getStyle.mock.calls.length;+ for (let index = 0; index < 100; index++) callback(entity(`type-${index}`));+ rerender();+ expect(result.current).toBe(callback);+ expect(getStyle.mock.calls).toHaveLength(calls);+ expect(calls).toBe(1);+ getStyle.mockRestore();+ });++ it('shows other for blank types and keeps descriptions without rewriting them', () => {+ expect(getKnowledgeGraphNodeLabel(entity(''))).toBe('other');+ expect(getKnowledgeGraphNodeLabel(entity(undefined, 'A & B'))).toBe(+ 'other · A & B',+ );+ expect(getKnowledgeGraphNodeLabel(entity('person'))).toBe('person');+ });+});diff --git a/web/src/components/structure-graph/__tests__/representation-renderer.test.tsx b/web/src/components/structure-graph/__tests__/representation-renderer.test.tsxnew file mode 100644index 0000000000..9243f2fa87--- /dev/null+++ b/web/src/components/structure-graph/__tests__/representation-renderer.test.tsx@@ -0,0 +1,66 @@+import { render } from '@testing-library/react';+import { CompilationTemplateKind } from '@/constants/compilation';+import { RepresentationRenderer } from '../representation-renderer';++const mockGraphRender = jest.fn();++jest.mock('@/components/artifact-force-graph', () => ({+ __esModule: true,+ default: (props: unknown) => {+ mockGraphRender(props);+ return null;+ },+}));+jest.mock('@/components/ui/tree-view', () => ({ TreeView: () => null }));+jest.mock('../mindmap-g6-graph', () => ({+ __esModule: true,+ default: () => null,+}));+jest.mock('../timeline-x6-graph', () => ({+ __esModule: true,+ default: () => null,+}));+jest.mock('react-i18next', () => ({+ useTranslation: () => ({ t: (key: string) => key }),+}));++const Template = {+ kind: CompilationTemplateKind.KnowledgeGraph,+ template_id: 'test',+ template_name: 'test',+ entities: [+ { id: 'Ada', name: 'Ada', type: 'Person', description: 'A mathematician' },+ ],+ relations: [],+};++describe('KnowledgeGraph styling scope', () => {+ it('keeps graph data and style callbacks stable when the highlighted node changes', () => {+ const { rerender } = render(<RepresentationRenderer template={Template} />);+ const initial = mockGraphRender.mock.calls.at(-1)![0];+ expect(initial.getNodeColor).toEqual(expect.any(Function));+ expect(initial.getNodeLabel(initial.data.entities[0])).toBe(+ 'Person · A mathematician',+ );+ expect(initial.data.entities[0].description).toBe('A mathematician');++ rerender(+ <RepresentationRenderer template={Template} highlightNodeId="Ada" />,+ );+ const highlighted = mockGraphRender.mock.calls.at(-1)![0];+ expect(highlighted.data).toBe(initial.data);+ expect(highlighted.getNodeColor).toBe(initial.getNodeColor);+ expect(highlighted.getNodeLabel).toBe(initial.getNodeLabel);+ expect(highlighted.highlightNodeId).toBe('Ada');+ });++ it.each([+ CompilationTemplateKind.SessionGraph,+ CompilationTemplateKind.Empty,+ ])('leaves %s on the default graph colors and tooltip', (kind) => {+ render(<RepresentationRenderer template={{ ...Template, kind }} />);+ const props = mockGraphRender.mock.calls.at(-1)![0];+ expect(props.getNodeColor).toBeUndefined();+ expect(props.getNodeLabel).toBeUndefined();+ });+});diff --git a/web/src/components/structure-graph/representation-renderer.tsx b/web/src/components/structure-graph/representation-renderer.tsxindex 6a6f0a90c8..62ac6b72a0 100644--- a/web/src/components/structure-graph/representation-renderer.tsx+++ b/web/src/components/structure-graph/representation-renderer.tsx@@ -36,6 +36,10 @@ import {} from './adapters';import MindMapG6Graph from './mindmap-g6-graph';import TimelineX6Graph from './timeline-x6-graph';+import {+ getKnowledgeGraphNodeLabel,+ useKnowledgeGraphNodeColor,+} from './use-knowledge-graph-node-style';export interface ClickableNode {id: string;@@ -73,6 +77,11 @@ function UnsupportedPlaceholder({ kind }: { kind: StructureTemplateKind }) {);}+/**+ * Renders a structure template and forwards supported node selections.+ * Knowledge graphs receive entity-type colors and labels; other graph views+ * retain the shared defaults.+ */export function RepresentationRenderer({template,onNodeClick,@@ -80,6 +89,7 @@ export function RepresentationRenderer({totalEntities,returnedEntities,}: RepresentationRendererProps) {+ const getKnowledgeGraphNodeColor = useKnowledgeGraphNodeColor();const handleTreeItemClick = useCallback((item: TreeDataItem | undefined) => {if (item?.source_chunk_ids?.length) {@@ -188,6 +198,8 @@ export function RepresentationRenderer({data={forceGraphData}showgetNodeId={getArtifactNodeName}+ getNodeColor={getKnowledgeGraphNodeColor}+ getNodeLabel={getKnowledgeGraphNodeLabel}onNodeClick={handleArtifactNodeClick}highlightNodeId={highlightNodeId}totalEntities={totalEntities}diff --git a/web/src/components/structure-graph/use-knowledge-graph-node-style.ts b/web/src/components/structure-graph/use-knowledge-graph-node-style.tsnew file mode 100644index 0000000000..27f45e5840--- /dev/null+++ b/web/src/components/structure-graph/use-knowledge-graph-node-style.ts@@ -0,0 +1,51 @@+import { EntityNodeColor } from '@/components/artifact-force-graph/node-style';+import { type IArtifactGraphEntity } from '@/interfaces/database/dataset';+import { useMemo } from 'react';++const KnowledgeGraphColorCount = 10;++/**+ * Returns plain tooltip text with the original entity type and description.+ * Blank types display as `other`; the graph handles HTML escaping.+ */+export const getKnowledgeGraphNodeLabel = (node: IArtifactGraphEntity) => {+ const type =+ typeof node.type === 'string' && node.type.trim() ? node.type : 'other';+ return node.description ? `${type} · ${node.description}` : type;+};++/**+ * Returns a stable node-color callback backed by the root CSS palette.+ * Trimmed, lowercase entity types select a color; blank and `other` types use+ * the neutral token. Different types can share one of the ten palette colors.+ */+export function useKnowledgeGraphNodeColor() {+ return useMemo(() => {+ // These root tokens use the same colors in both themes. Resolve them once,+ // outside node callbacks, so Canvas and withAlpha receive real hex colors.+ const style = getComputedStyle(document.documentElement);+ const otherColor =+ style.getPropertyValue('--graph-node-other').trim() || EntityNodeColor;+ const colors = Array.from(+ { length: KnowledgeGraphColorCount },+ (_, index) =>+ style.getPropertyValue(`--graph-node-${index + 1}`).trim() ||+ otherColor,+ );++ return (node: IArtifactGraphEntity): string => {+ // Normalize the color key only. Do not merge synonyms or mutate data.+ const type =+ typeof node.type === 'string' ? node.type.trim().toLowerCase() : '';+ if (!type || type === 'other') return otherColor;++ // FNV-1a over UTF-16 code units: stable across ordering and graph subsets.+ // Ten slots intentionally allow collisions; the tooltip identifies type.+ let hash = 2166136261;+ for (let index = 0; index < type.length; index++) {+ hash = Math.imul(hash ^ type.charCodeAt(index), 16777619);+ }+ return colors[(hash >>> 0) % KnowledgeGraphColorCount];+ };+ }, []);+}diff --git a/web/tailwind.css b/web/tailwind.cssindex a00a13cd27..7329b6eba3 100644--- a/web/tailwind.css+++ b/web/tailwind.css@@ -98,6 +98,18 @@--border-button: rgba(0, 0, 0, 0.1);/* Regulators, parsing, switches, variables */--accent-primary: 0 190 180;+ /* Categorical graph fills shared by light and dark themes. */+ --graph-node-1: #4e79a7;+ --graph-node-2: #b96b1d;+ --graph-node-3: #c44e52;+ --graph-node-4: #268985;+ --graph-node-5: #4e8638;+ --graph-node-6: #9a7b00;+ --graph-node-7: #9165a0;+ --graph-node-8: #b55b89;+ --graph-node-9: #8a6f55;+ --graph-node-10: #677d8d;+ --graph-node-other: #777777;/* Output Variables Box */--bg-accent: rgba(76, 164, 231, 0.05);