Skip to content

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

Fix: An additional retrieval node has appeared in the agent created using the CAJAL Scientific Paper Assistant template. (#21079)

balibabufb015ecfb712
diff --git a/internal/agent/templates/cajal_scientific_paper_agent.json b/internal/agent/templates/cajal_scientific_paper_agent.json
index 235c4a8b82..c5cb3a77a8 100644
--- a/internal/agent/templates/cajal_scientific_paper_agent.json
+++ b/internal/agent/templates/cajal_scientific_paper_agent.json
@@ -157,6 +157,13 @@
"targetHandle": "end",
"type": "buttonEdge",
"zIndex": 1001
+ },
+ {
+ "id": "xy-edge__Agent:NewPumasLicktool-Tool:QuietPapersCiteend",
+ "source": "Agent:NewPumasLick",
+ "sourceHandle": "tool",
+ "target": "Tool:QuietPapersCite",
+ "targetHandle": "end"
}
],
"nodes": [
@@ -295,6 +302,30 @@
"sourcePosition": "right",
"targetPosition": "left",
"type": "agentNode"
+ },
+ {
+ "data": {
+ "form": {
+ "description": "This is an agent for a specific task.",
+ "user_prompt": "This is the order you need to send to the agent."
+ },
+ "label": "Tool",
+ "name": "flow.tool_0"
+ },
+ "dragging": false,
+ "id": "Tool:QuietPapersCite",
+ "measured": {
+ "height": 48,
+ "width": 200
+ },
+ "position": {
+ "x": 265.00048227952215,
+ "y": 326.49109364794631
+ },
+ "selected": false,
+ "sourcePosition": "right",
+ "targetPosition": "left",
+ "type": "toolNode"
}
]
},
diff --git a/web/src/components/next-markdown-content/__tests__/index.test.tsx b/web/src/components/next-markdown-content/__tests__/index.test.tsx
new file mode 100644
index 0000000000..ed2f21356f
--- /dev/null
+++ b/web/src/components/next-markdown-content/__tests__/index.test.tsx
@@ -0,0 +1,213 @@
+import { render, screen } from '@testing-library/react';
+
+import MarkdownContent from '..';
+
+jest.mock('react-i18next', () => ({
+ useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+jest.mock('@/hooks/use-document-request', () => ({
+ useFetchDocumentThumbnailsByIds: () => ({
+ setDocumentIds: jest.fn(),
+ data: {},
+ }),
+}));
+
+jest.mock('@/hooks/use-loading-pause', () => ({
+ useLoadingPause: () => false,
+}));
+
+// Only the artifact download handlers use these; mocking them keeps the
+// file-util → service → i18n-config import chain out of the suite.
+jest.mock('@/utils/file-util', () => ({
+ downloadFileFromBlob: jest.fn(),
+}));
+
+jest.mock('@/utils/request', () => ({
+ __esModule: true,
+ default: jest.fn(),
+}));
+
+// Render the highlighter as a plain <pre>: the assertions target citation
+// resolution, not code highlighting.
+jest.mock('react-syntax-highlighter', () => ({
+ __esModule: true,
+ default: ({ children }: any) => {
+ const ReactLib = jest.requireActual('react');
+ return ReactLib.createElement('pre', null, children);
+ },
+}));
+
+// react-markdown and the remark/rehype packages are ESM-only and jest does
+// not transform node_modules, so the real parser cannot run here. The
+// production pipeline wraps every text node in <custom-typography>; this
+// mock feeds the full content string through that same component, which is
+// where citation markers are replaced.
+jest.mock('react-markdown', () => ({
+ __esModule: true,
+ default: ({ children, components }: any) => {
+ const ReactLib = jest.requireActual('react');
+ const CustomTypography = components['custom-typography'];
+ return ReactLib.createElement(CustomTypography, null, String(children));
+ },
+}));
+
+jest.mock('rehype-katex', () => jest.fn());
+jest.mock('rehype-raw', () => jest.fn());
+jest.mock('unist-util-visit-parents', () => ({ visitParents: jest.fn() }));
+jest.mock('@/constants/markdown-remark-plugins', () => ({
+ MarkdownRemarkPlugins: [],
+ MarkdownRemarkPluginsLite: [],
+}));
+jest.mock('@/constants/markdown-rehype-plugins', () => ({
+ RehypeSanitizeAssistantMarkdown: jest.fn(),
+}));
+
+// Radix HoverCard only mounts its content on hover; render eagerly so the
+// resolved chunk content is assertable in the DOM.
+jest.mock('@/components/ui/hover-card', () => ({
+ HoverCard: ({ children }: any) => {
+ const ReactLib = jest.requireActual('react');
+ return ReactLib.createElement(
+ 'div',
+ { 'data-testid': 'citation' },
+ children,
+ );
+ },
+ HoverCardTrigger: ({ children }: any) => {
+ const ReactLib = jest.requireActual('react');
+ return ReactLib.createElement('span', { 'data-testid': 'chip' }, children);
+ },
+ HoverCardContent: ({ children }: any) => {
+ const ReactLib = jest.requireActual('react');
+ return ReactLib.createElement(
+ 'div',
+ { 'data-testid': 'popover' },
+ children,
+ );
+ },
+}));
+
+jest.mock('@/components/svg-icon', () => ({
+ __esModule: true,
+ default: () => {
+ const ReactLib = jest.requireActual('react');
+ return ReactLib.createElement('span');
+ },
+}));
+
+jest.mock('@/components/image', () => ({
+ __esModule: true,
+ default: () => null,
+ AuthenticatedImg: () => null,
+}));
+
+const buildChunk = (id: string, content: string, documentId: string) => ({
+ id,
+ chunk_id: id,
+ content,
+ content_with_weight: content,
+ document_id: documentId,
+ doc_id: documentId,
+ image_id: '',
+ img_id: '',
+});
+
+const HappyPrince = buildChunk(
+ 'a2d067519c9e0db1',
+ 'HAPPY_PRINCE_CHUNK_CONTENT',
+ 'doc-happy-prince',
+);
+const Nightingale = buildChunk(
+ 'b3e178620da1fc42',
+ 'NIGHTINGALE_CHUNK_CONTENT',
+ 'doc-nightingale',
+);
+
+// reference.chunks ships in retrieval order — Happy Prince ranked first —
+// while the answer cites Nightingale first. The array shape is what the Go
+// agent run actually sends on the wire.
+const buildReference = () =>
+ ({
+ chunks: [HappyPrince, Nightingale],
+ doc_aggs: {
+ 'doc-happy-prince': {
+ doc_id: 'doc-happy-prince',
+ doc_name: 'The Happy Prince.txt',
+ count: 1,
+ },
+ 'doc-nightingale': {
+ doc_id: 'doc-nightingale',
+ doc_name: 'The Nightingale and the Rose.txt',
+ count: 1,
+ },
+ },
+ total: 2,
+ }) as any;
+
+const chipTexts = () =>
+ screen.getAllByTestId('chip').map((chip) => chip.textContent);
+const popoverTexts = () =>
+ screen.getAllByTestId('popover').map((popover) => popover.textContent);
+
+describe('MarkdownContent citations', () => {
+ it('resolves agent [ID:<chunkId>] markers by chunk id, not citation order', () => {
+ render(
+ <MarkdownContent
+ content={
+ 'The same volume includes The Nightingale and the Rose [ID:b3e178620da1fc42] and the tears of the prince [ID:a2d067519c9e0db1].'
+ }
+ loading={false}
+ reference={buildReference()}
+ />,
+ );
+
+ expect(chipTexts()).toEqual(['[1]', '[2]']);
+ const popovers = popoverTexts();
+ expect(popovers[0]).toContain('NIGHTINGALE_CHUNK_CONTENT');
+ expect(popovers[0]).toContain('The Nightingale and the Rose.txt');
+ expect(popovers[1]).toContain('HAPPY_PRINCE_CHUNK_CONTENT');
+ expect(popovers[1]).toContain('The Happy Prince.txt');
+ });
+
+ it('resolves numeric markers by the index they carry, not citation order', () => {
+ render(
+ <MarkdownContent
+ content={'Cites the second chunk first [ID:1] then the first [ID:0].'}
+ loading={false}
+ reference={buildReference()}
+ />,
+ );
+
+ expect(chipTexts()).toEqual(['[1]', '[2]']);
+ const popovers = popoverTexts();
+ expect(popovers[0]).toContain('NIGHTINGALE_CHUNK_CONTENT');
+ expect(popovers[1]).toContain('HAPPY_PRINCE_CHUNK_CONTENT');
+ });
+
+ it('keeps an unresolvable marker as literal text once loading finished', () => {
+ const { container } = render(
+ <MarkdownContent
+ content={'A hallucinated source [ID:ffffffffffffffff] stays text.'}
+ loading={false}
+ reference={buildReference()}
+ />,
+ );
+
+ expect(screen.queryByTestId('chip')).toBeNull();
+ expect(container.textContent).toContain('[ID:ffffffffffffffff]');
+ });
+
+ it('renders the chip without popover while the reference is still streaming', () => {
+ render(
+ <MarkdownContent
+ content={'Sources arriving [ID:b3e178620da1fc42] soon.'}
+ loading={true}
+ reference={undefined}
+ />,
+ );
+
+ expect(chipTexts()).toEqual(['[1]']);
+ expect(screen.queryByTestId('popover')).toBeNull();
+ });
+});
diff --git a/web/src/components/next-markdown-content/index.tsx b/web/src/components/next-markdown-content/index.tsx
index 23a43ffae1..827db3ab92 100644
--- a/web/src/components/next-markdown-content/index.tsx
+++ b/web/src/components/next-markdown-content/index.tsx
@@ -49,8 +49,10 @@ import {
replaceRetrievingToSection,
replaceTextByOldReg,
replaceThinkToSection,
+ resolveCitationChunk,
unescapeAngleBrackets,
} from '@/utils/chat';
+import type { CitationKey } from '@/utils/citation-utils';
import { getDirAttribute } from '@/utils/text-direction';
import { useFetchDocumentThumbnailsByIds } from '@/hooks/use-document-request';
@@ -72,6 +74,11 @@ import styles from './index.module.less';
const getChunkKey = (match: string) => parseCitationIndex(match);
+// react-string-replace hands the callback the LAST capture group, not the
+// full match — citationMarkerReg groups only the id, so replacing with it
+// would strip the brackets. This group wraps the whole marker, letting an
+// unresolved marker be returned unchanged.
+const WholeMarkerReg = /(\[(?:ID:)?[0-9a-fA-F\u0660-\u0669\u06F0-\u06F9]+\])/g;
const isArtifactUrl = (url?: string) =>
Boolean(url && url.includes('/api/v1/documents/artifact/'));
@@ -278,12 +285,10 @@ function MarkdownContent({
};
const getReferenceInfo = useCallback(
- (chunkIndex: number) => {
- const chunks = reference?.chunks ?? {};
- // Agent reference.chunks is a Record keyed by the original citation ID
- // (e.g. "3092e7ae6831b877"); the caller maps those IDs to a positional
- // display index, so look up the N-th entry by insertion order.
- const chunkItem = Object.values(chunks)[chunkIndex];
+ (chunkKey: CitationKey) => {
+ // The marker itself selects the chunk: a numeric key indexes the
+ // payload, an agent [ID:<chunkId>] key matches the chunk's own id.
+ const chunkItem = resolveCitationChunk(reference?.chunks, chunkKey);
const documentList = Object.values(reference?.doc_aggs ?? {});
const document = documentList.find(
@@ -309,7 +314,7 @@ function MarkdownContent({
);
const renderPopoverContent = useCallback(
- (chunkIndex: number) => {
+ (chunkKey: CitationKey) => {
const {
documentUrl,
fileThumbnail,
@@ -318,10 +323,16 @@ function MarkdownContent({
chunkItem,
documentId,
document,
- } = getReferenceInfo(chunkIndex);
+ } = getReferenceInfo(chunkKey);
+
+ // The citation chip already gates on the chunk being found; this narrows
+ // chunkItem for the handlers below.
+ if (!chunkItem) {
+ return null;
+ }
return (
- <div key={chunkItem?.id} className="flex gap-2">
+ <div key={chunkItem.id} className="flex gap-2">
{imageId && (
<HoverCard>
<HoverCardTrigger>
@@ -385,14 +396,24 @@ function MarkdownContent({
const renderReference = useCallback(
(text: string) => {
- // Assign each unique citation marker a stable display number based on
- // its first occurrence, so the same ID always renders as the same [N]
- // chip. The actual chunk lookup uses that index against the positional
- // order of IReferenceObject.chunks (see getReferenceInfo).
+ // Chip numbers follow each unique marker's first occurrence, so the
+ // same citation always renders as the same [N] chip. That numbering is
+ // display-only: the chunk behind a marker is resolved from the marker
+ // itself (position for numeric markers, chunk id for agent
+ // [ID:<chunkId>] markers), never from the display position — the
+ // payload ships in retrieval order, which is unrelated to the order
+ // the answer cites passages in.
const keyToDisplay = buildCitationDisplayMap(text);
- const replacedText = reactStringReplace(text, currentReg, (match) => {
+ const replacedText = reactStringReplace(text, WholeMarkerReg, (match) => {
const chunkKey = getChunkKey(match);
const displayIndex = keyToDisplay.get(chunkKey) ?? 0;
+ const chunkItem = resolveCitationChunk(reference?.chunks, chunkKey);
+ // The reference lands at message_end, after the answer stream, so an
+ // unresolved marker keeps its chip while loading. Afterwards it
+ // stays as literal text rather than pointing at the wrong chunk.
+ if (!chunkItem && !loading) {
+ return match;
+ }
return (
<HoverCard key={`${String(chunkKey)}-${displayIndex}`}>
@@ -401,16 +422,18 @@ function MarkdownContent({
[{displayIndex + 1}]
</bdi>
</HoverCardTrigger>
- <HoverCardContent className="max-w-3xl">
- {renderPopoverContent(displayIndex)}
- </HoverCardContent>
+ {chunkItem && (
+ <HoverCardContent className="max-w-3xl">
+ {renderPopoverContent(chunkKey)}
+ </HoverCardContent>
+ )}
</HoverCard>
);
});
return replacedText;
},
- [renderPopoverContent],
+ [loading, reference?.chunks, renderPopoverContent],
);
const dir = getDirAttribute(content?.replace(currentReg, ''));
diff --git a/web/src/components/next-message-item/reference-image-list.tsx b/web/src/components/next-message-item/reference-image-list.tsx
index b9a6c45449..9aacd9c1d3 100644
--- a/web/src/components/next-message-item/reference-image-list.tsx
+++ b/web/src/components/next-message-item/reference-image-list.tsx
@@ -26,9 +26,8 @@ import {
import { useSetModalState } from '@/hooks/common-hooks';
import { IReferenceChunk } from '@/interfaces/database/chat';
import PdfDrawer from '@/pages/next-search/document-preview-modal';
-import { buildCitationDisplayMap } from '@/utils/chat';
+import { buildCitationDisplayMap, resolveCitationChunk } from '@/utils/chat';
import { middleEllipsis } from '@/utils/common-util';
-import { isPlainObject } from 'lodash';
import { RotateCw, ZoomIn, ZoomOut } from 'lucide-react';
import { useMemo } from 'react';
import { PhotoProvider, PhotoView } from 'react-photo-view';
@@ -182,28 +181,15 @@ export function ReferenceImageList({
messageContent,
}: IProps) {
const images = useMemo(() => {
- // In plain chat the body chips (markdown-content) treat a numeric marker
- // [n] as the 0-based index into the full retrieved chunks array and render
- // [n + 1], so the carousel must index chunks by that same key and label
- // it n + 1 — indexing by first-occurrence position would show unrelated
- // chunks whenever retrieval returns more chunks than the model cited.
- // Agent markers are [ID:<chunkId>] strings; those keep the positional
- // ordering (matched by chunk.id first, when possible).
+ // The marker itself selects the chunk: plain-chat numeric markers index
+ // the retrieved chunks array (chip renders n + 1); agent [ID:<chunkId>]
+ // markers match the chunk's own id. Either way a citation lands on its
+ // own chunk regardless of the payload's retrieval order.
const keyToPosition = buildCitationDisplayMap(messageContent);
- const chunkList = Array.isArray(referenceChunks)
- ? referenceChunks
- : isPlainObject(referenceChunks)
- ? Object.values(referenceChunks ?? {})
- : [];
return [...keyToPosition.entries()]
.map(([key, position]) => {
- const chunk =
- typeof key === 'number'
- ? chunkList[key]
- : ((Array.isArray(referenceChunks)
- ? referenceChunks.find((item) => item.id === String(key))
- : referenceChunks?.[String(key)]) ?? chunkList[position]);
+ const chunk = resolveCitationChunk(referenceChunks, key);
if (!chunk?.image_id || !chunk?.document_id) {
return null;
}
diff --git a/web/src/pages/agent/hooks/use-add-node.test.tsx b/web/src/pages/agent/hooks/use-add-node.test.tsx
index a115c3e577..ac36b264c3 100644
--- a/web/src/pages/agent/hooks/use-add-node.test.tsx
+++ b/web/src/pages/agent/hooks/use-add-node.test.tsx
@@ -139,6 +139,43 @@ describe('useAddNode', () => {
});
});
+ it('adds a tool node only once when the same stale callback fires twice', () => {
+ // Mirrors the React StrictMode double-invoked mount effect in
+ // ToolPopover: both invocations share one render's closure, so the
+ // second call must consult fresh store state to see the edge the
+ // first call just committed. Otherwise two tool nodes stack at the
+ // same position below the agent.
+ const agentNode = {
+ id: 'Agent:0',
+ type: 'agentNode',
+ position: { x: 100, y: 100 },
+ data: {
+ label: Operator.Agent,
+ name: 'agent_0',
+ form: { tools: [{ component_name: Operator.Retrieval }] },
+ },
+ };
+ useGraphStore.setState({ nodes: [agentNode], edges: [] });
+
+ const { result } = renderHook(() => useAddNode());
+
+ const addTool = result.current.addCanvasNode(Operator.Tool, {
+ nodeId: 'Agent:0',
+ position: Position.Bottom,
+ });
+
+ act(() => {
+ addTool();
+ addTool();
+ });
+
+ const { nodes, edges } = useGraphStore.getState();
+ expect(nodes.filter((x) => x.data.label === Operator.Tool)).toHaveLength(1);
+ expect(
+ edges.filter((x) => x.sourceHandle === NodeHandleId.Tool),
+ ).toHaveLength(1);
+ });
+
it('adds an iteration node again after the previous one was deleted', () => {
useGraphStore.setState({ nodes: [createSwitchNode()], edges: [] });
diff --git a/web/src/pages/agent/hooks/use-add-node.ts b/web/src/pages/agent/hooks/use-add-node.ts
index 27804925d8..16044ca2fd 100644
--- a/web/src/pages/agent/hooks/use-add-node.ts
+++ b/web/src/pages/agent/hooks/use-add-node.ts
@@ -337,15 +337,20 @@ function useAddChildEdge() {
}
function useAddToolNode() {
- const { nodes, edges, addEdge, getNode, addNode } = useGraphStore(
- (state) => state,
- );
+ const { addEdge, getNode, addNode } = useGraphStore((state) => state);
const addToolNode = useCallback(
(newNode: Node<any>, nodeId?: string): boolean => {
const agentNode = getNode(nodeId);
if (agentNode) {
+ // Read edges/nodes from the store at call time, not from the
+ // render-time snapshot: React StrictMode double-invokes the mount
+ // effect that auto-adds this node (ToolPopover), and the second
+ // invocation must see the edge the first one just committed —
+ // otherwise both pass the guard and stack a duplicate tool node at
+ // the same position.
+ const { nodes, edges } = useGraphStore.getState();
const childToolNodeIds = edges
.filter(
(x) => x.source === nodeId && x.sourceHandle === NodeHandleId.Tool,
@@ -377,7 +382,7 @@ function useAddToolNode() {
}
return false;
},
- [addEdge, addNode, edges, getNode, nodes],
+ [addEdge, addNode, getNode],
);
return { addToolNode };
diff --git a/web/src/utils/__tests__/citation-utils.test.ts b/web/src/utils/__tests__/citation-utils.test.ts
new file mode 100644
index 0000000000..99bb9737ec
--- /dev/null
+++ b/web/src/utils/__tests__/citation-utils.test.ts
@@ -0,0 +1,91 @@
+import type { IReferenceChunk } from '@/interfaces/database/chat';
+import {
+ buildCitationDisplayMap,
+ parseCitationIndex,
+ resolveCitationChunk,
+} from '../citation-utils';
+
+const buildChunk = (id: string): IReferenceChunk => ({
+ id,
+ content: null,
+ document_id: `doc-${id}`,
+ document_name: `${id}.txt`,
+ dataset_id: 'kb-1',
+ image_id: '',
+ similarity: 1,
+ vector_similarity: 1,
+ term_similarity: 1,
+ positions: [],
+});
+
+const HappyPrince = buildChunk('a2d067519c9e0db1');
+const Nightingale = buildChunk('b3e178620da1fc42');
+
+describe('parseCitationIndex', () => {
+ it('parses numeric markers as numbers', () => {
+ expect(parseCitationIndex('[ID:2]')).toBe(2);
+ expect(parseCitationIndex('[3]')).toBe(3);
+ });
+
+ it('parses hex chunk-id markers as strings', () => {
+ expect(parseCitationIndex('[ID:a2d067519c9e0db1]')).toBe(
+ 'a2d067519c9e0db1',
+ );
+ });
+});
+
+describe('resolveCitationChunk', () => {
+ // The payload ships in retrieval order: Happy Prince ranked first.
+ const chunks = [HappyPrince, Nightingale];
+
+ it('resolves a numeric key positionally', () => {
+ expect(resolveCitationChunk(chunks, 0)).toBe(HappyPrince);
+ expect(resolveCitationChunk(chunks, 1)).toBe(Nightingale);
+ });
+
+ it('returns undefined for an out-of-range numeric key', () => {
+ expect(resolveCitationChunk(chunks, 5)).toBeUndefined();
+ });
+
+ it('resolves a chunk-id key by id, not by citation order', () => {
+ // The answer cites Nightingale first; the chunk must still be the one
+ // the marker names, not chunks[0] (the mis-citation regression).
+ expect(resolveCitationChunk(chunks, 'b3e178620da1fc42')).toBe(Nightingale);
+ expect(resolveCitationChunk(chunks, 'a2d067519c9e0db1')).toBe(HappyPrince);
+ });
+
+ it('falls back to chunk_id when the id field is absent', () => {
+ const legacy = [
+ { chunk_id: 'b3e178620da1fc42' } as unknown as IReferenceChunk,
+ ];
+ expect(resolveCitationChunk(legacy, 'b3e178620da1fc42')).toBe(legacy[0]);
+ });
+
+ it('returns undefined for an unknown chunk id instead of guessing positionally', () => {
+ expect(resolveCitationChunk(chunks, 'ffffffffffffffff')).toBeUndefined();
+ });
+
+ it('resolves ids inside a Record-shaped payload', () => {
+ const record = {
+ a2d067519c9e0db1: HappyPrince,
+ b3e178620da1fc42: Nightingale,
+ };
+ expect(resolveCitationChunk(record, 'b3e178620da1fc42')).toBe(Nightingale);
+ });
+
+ it('tolerates an empty payload', () => {
+ expect(resolveCitationChunk(undefined, 0)).toBeUndefined();
+ expect(resolveCitationChunk(null, 'a2d067519c9e0db1')).toBeUndefined();
+ });
+});
+
+describe('buildCitationDisplayMap', () => {
+ it('numbers unique markers by first occurrence, whatever their key', () => {
+ const map = buildCitationDisplayMap(
+ 'nightingale [ID:b3e178620da1fc42] then happy prince [ID:a2d067519c9e0db1] again [ID:b3e178620da1fc42]',
+ );
+ expect(map.get('b3e178620da1fc42')).toBe(0);
+ expect(map.get('a2d067519c9e0db1')).toBe(1);
+ expect(map.size).toBe(2);
+ });
+});
diff --git a/web/src/utils/chat.ts b/web/src/utils/chat.ts
index ccf0dbbcb9..095cd8a8f5 100644
--- a/web/src/utils/chat.ts
+++ b/web/src/utils/chat.ts
@@ -27,6 +27,7 @@ import {
citationMarkerReg,
normalizeCitationDigits,
parseCitationIndex,
+ resolveCitationChunk,
} from './citation-utils';
export const isConversationIdExist = (conversationId: string) => {
@@ -256,7 +257,13 @@ export function setChatVariableEnabledFieldValuePage() {
const oldReg = /(#{2}[0-9\u0660-\u0669\u06F0-\u06F9]+\${2})/g;
export const currentReg = citationMarkerReg;
-export { buildCitationDisplayMap, normalizeCitationDigits, parseCitationIndex };
+export {
+ buildCitationDisplayMap,
+ normalizeCitationDigits,
+ parseCitationIndex,
+ resolveCitationChunk,
+};
+export type { CitationKey } from './citation-utils';
// To be compatible with the old index matching mode
export const replaceTextByOldReg = (text: string) => {
diff --git a/web/src/utils/citation-utils.ts b/web/src/utils/citation-utils.ts
index 4387834654..10e0af20c4 100644
--- a/web/src/utils/citation-utils.ts
+++ b/web/src/utils/citation-utils.ts
@@ -14,6 +14,8 @@
* limitations under the License.
*/
+import type { IReferenceChunk } from '@/interfaces/database/chat';
+
export const normalizeCitationDigits = (text: string) => {
if (!text) return text;
return text.replace(/[٠-٩۰-۹]/g, (char) => {
@@ -46,10 +48,38 @@ export const parseCitationIndex = (value: string): CitationKey => {
export const citationMarkerReg =
/\[(?:ID:)?([0-9a-fA-F\u0660-\u0669\u06F0-\u06F9]+)\]/g;
+// Resolve the chunk a citation marker points at. A numeric key is the
+// chunk's position in the payload — the plain-chat contract, where the
+// backend numbers each marker by its index into reference.chunks. A string
+// key is the chunk id an agent answer embeds in its [ID:<chunkId>] markers;
+// match it against the chunk's own id, never positionally: the payload
+// ships in retrieval order, which is unrelated to the order the answer
+// cites passages in, so a positional read permutes the sources. A chunk id
+// is 16 hex chars — an all-digit id would parse as a position (~0.05% per
+// id), accepted and recorded here so it is not rediscovered as a mystery.
+export const resolveCitationChunk = (
+ chunks:
+ | IReferenceChunk[]
+ | Record<string, IReferenceChunk>
+ | null
+ | undefined,
+ key: CitationKey,
+): IReferenceChunk | undefined => {
+ const list = Array.isArray(chunks) ? chunks : Object.values(chunks ?? {});
+ if (typeof key === 'number') {
+ return list[key];
+ }
+ return list.find(
+ (chunk) =>
+ chunk?.id === key ||
+ (chunk as { chunk_id?: string } | undefined)?.chunk_id === key,
+ );
+};
+
// Map each unique citation marker ([n] or [ID:<chunkId>]) to its stable
-// 0-based display position by first occurrence. The chip renders position + 1
-// and the chunk is looked up positionally via Object.values(chunks)[position].
-// Works for both plain chat (numeric markers) and agents ([ID:<chunkId>]).
+// 0-based display position by first occurrence; the chip renders
+// position + 1. This numbering is display-only — the chunk behind a marker
+// is resolved by resolveCitationChunk, never by this position.
export const buildCitationDisplayMap = (
content: string,
): Map<CitationKey, number> => {