feat(chat): add citation popover and chunk caching

Introduce ChatCitationFloat hover UI, session-scoped citation chunk cache,
and unified citation markdown handling for main chat and embed views.
This commit is contained in:
wizardchen
2026-06-16 00:49:25 +08:00
committed by lyingbug
parent ee1c3c732c
commit 05f39b859f
13 changed files with 909 additions and 482 deletions
+62
View File
@@ -1,6 +1,9 @@
import i18n from '@/i18n';
import { buildMermaidBlockHtml, buildMermaidLoadingHtml } from '@/utils/markdownEnhancements';
const STREAMING_IMAGE_PLACEHOLDER = '<span class="streaming-image-loading"><span class="streaming-image-loading__skeleton"></span></span>';
const STREAMING_MERMAID_PLACEHOLDER = buildMermaidLoadingHtml();
const MERMAID_FENCE_START = '```mermaid';
export const replaceIncompleteImageWithPlaceholder = (content: string): string => {
if (!content) return '';
@@ -23,6 +26,65 @@ export const replaceIncompleteImageWithPlaceholder = (content: string): string =
return content;
};
/** Hide an unclosed trailing ```mermaid fence while streaming to avoid layout jitter. */
export const replaceIncompleteMermaidWithPlaceholder = (content: string): string => {
if (!content) return '';
const start = content.lastIndexOf(MERMAID_FENCE_START);
if (start < 0) return content;
const tail = content.slice(start + MERMAID_FENCE_START.length);
if (tail.includes('```')) return content;
return content.slice(0, start) + STREAMING_MERMAID_PLACEHOLDER;
};
const MERMAID_BLOCK_RE = /```mermaid[\s\S]*?```/;
/** Keep mermaid as a stable placeholder for the whole stream; render once at the end. */
export const maskMermaidBlocksForStreaming = (content: string): string => {
if (!content) return '';
const masked = content.replace(MERMAID_BLOCK_RE, STREAMING_MERMAID_PLACEHOLDER);
return replaceIncompleteMermaidWithPlaceholder(masked);
};
export const hasCompleteMermaidBlock = (content: string): boolean => {
return MERMAID_BLOCK_RE.test(content);
};
/** While streaming: loading placeholder for mermaid; swap to cached SVG after sanitize. */
export const prepareStreamingMermaidMarkdown = (
content: string,
_cachedSvgHtml?: string | null,
): string => {
if (!content) return '';
if (hasCompleteMermaidBlock(content)) {
return maskMermaidBlocksForStreaming(content);
}
return replaceIncompleteMermaidWithPlaceholder(content);
};
export const extractFirstMermaidCode = (content: string): string | null => {
const match = content.match(/```mermaid([\s\S]*?)```/);
return match?.[1]?.trim() || null;
};
const STREAMING_MERMAID_LOADING_RE = /<div class="chat-mermaid-block[^"]*"[^>]*>[\s\S]*?<div class="streaming-mermaid-loading"[^>]*>[\s\S]*?<\/div>[\s\S]*?<\/div>/g;
/** Inject trusted Mermaid SVG after DOMPurify, replacing the streaming loading shell. */
export const injectCachedMermaidSvg = (
html: string,
cachedSvgHtml: string | null | undefined,
): string => {
if (!html || !cachedSvgHtml) return html;
return html.replace(
STREAMING_MERMAID_LOADING_RE,
buildMermaidBlockHtml(cachedSvgHtml, 'data-mermaid="cached"'),
);
};
export const formatManualTitle = (question?: string): string => {
if (!question) {
return i18n.global.t('chat.sessionExcerpt');
@@ -0,0 +1,38 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import {
clearCitationChunkCache,
getCitationChunkCache,
makeCitationCacheKey,
setCitationChunkCache,
} from './citationChunkCache.ts'
test('makeCitationCacheKey combines scope and chunkId', () => {
assert.equal(makeCitationCacheKey('session-1', 'chunk-a'), 'session-1::chunk-a')
assert.equal(
makeCitationCacheKey('embed:ch:tok', 'chunk-b'),
'embed:ch:tok::chunk-b',
)
})
test('get/set are isolated per scope', () => {
clearCitationChunkCache()
setCitationChunkCache('session-1', 'chunk-a', { content: 'one' })
setCitationChunkCache('session-2', 'chunk-a', { content: 'two' })
assert.equal(getCitationChunkCache('session-1', 'chunk-a')?.content, 'one')
assert.equal(getCitationChunkCache('session-2', 'chunk-a')?.content, 'two')
})
test('clearCitationChunkCache clears one scope or all', () => {
clearCitationChunkCache()
setCitationChunkCache('session-1', 'chunk-a', { content: 'one' })
setCitationChunkCache('session-2', 'chunk-a', { content: 'two' })
clearCitationChunkCache('session-1')
assert.equal(getCitationChunkCache('session-1', 'chunk-a'), undefined)
assert.equal(getCitationChunkCache('session-2', 'chunk-a')?.content, 'two')
clearCitationChunkCache()
assert.equal(getCitationChunkCache('session-2', 'chunk-a'), undefined)
})
+35
View File
@@ -0,0 +1,35 @@
export type CitationChunkCacheValue = { content: string; error?: string }
const chunkCache = new Map<string, CitationChunkCacheValue>()
export function makeCitationCacheKey(scope: string, chunkId: string): string {
return `${scope}::${chunkId}`
}
export function getCitationChunkCache(
scope: string,
chunkId: string,
): CitationChunkCacheValue | undefined {
return chunkCache.get(makeCitationCacheKey(scope, chunkId))
}
export function setCitationChunkCache(
scope: string,
chunkId: string,
value: CitationChunkCacheValue,
): void {
chunkCache.set(makeCitationCacheKey(scope, chunkId), value)
}
export function clearCitationChunkCache(scope?: string): void {
if (scope === undefined) {
chunkCache.clear()
return
}
const prefix = `${scope}::`
for (const key of chunkCache.keys()) {
if (key.startsWith(prefix)) {
chunkCache.delete(key)
}
}
}
+163 -10
View File
@@ -1,6 +1,22 @@
/** Shared citation tag preprocessing for chat markdown (QA + agent). */
/** Self-closing or unclosed `<kb/>` / `<web/>` tags from model output. */
export const KB_WEB_TAG_RE = /<(?:kb|web)\b[^>]*?\s*\/?>/g
const KB_TAG_ATTR_RE = /<kb\b([^>]*?)\s*\/?>/g
const WEB_TAG_ATTR_RE = /<web\b([^>]*?)\s*\/?>/g
const ATTRIBUTE_REGEX = /([\w-]+)\s*=\s*"([^"]*)"/g
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
export type CitationKnowledgeRef = {
id?: string
knowledge_id?: string
knowledge_title?: string
knowledge_filename?: string
chunk_index?: number
chunk_type?: string
knowledge_base_id?: string
}
function parseTagAttributes(attrString: string): Record<string, string> {
const attributes: Record<string, string> = {}
@@ -30,12 +46,88 @@ function truncateMiddle(text: string, maxLength = 13): string {
return `${start}...${end}`
}
function normalizeDocTitle(title: string): string {
return title.trim().toLowerCase()
}
function docTitlesMatch(a: string, b: string): boolean {
if (!a || !b) return false
const na = normalizeDocTitle(a)
const nb = normalizeDocTitle(b)
return na === nb || na.includes(nb) || nb.includes(na)
}
/** Map model context index (1, FAQ-1, DOC-2) to the real chunk UUID from retrieval results. */
export function resolveCitationChunkId(
rawChunkId: string,
attrs: { doc?: string; kbId?: string },
refs?: CitationKnowledgeRef[] | null,
): string {
const raw = String(rawChunkId || '').trim()
if (!raw || UUID_RE.test(raw)) return raw
const list = (refs || []).filter((r) => r && r.chunk_type !== 'web_search')
if (!list.length) return raw
const doc = (attrs.doc || '').trim()
const kbId = (attrs.kbId || '').trim()
if (doc) {
const byDoc = list.find(
(r) =>
docTitlesMatch(doc, r.knowledge_title || '') ||
docTitlesMatch(doc, r.knowledge_filename || ''),
)
if (byDoc?.id) return byDoc.id
}
const faqMatch = raw.match(/^FAQ-(\d+)$/i)
if (faqMatch) {
const faqRefs = list.filter((r) => r.chunk_type === 'faq')
const hit = faqRefs[parseInt(faqMatch[1], 10) - 1]
if (hit?.id) return hit.id
}
const docMatch = raw.match(/^DOC-(\d+)$/i)
if (docMatch) {
const docRefs = list.filter((r) => r.chunk_type !== 'faq')
const hit = docRefs[parseInt(docMatch[1], 10) - 1]
if (hit?.id) return hit.id
}
const num = parseInt(raw, 10)
if (!Number.isNaN(num) && String(num) === raw) {
const byPos = list[num - 1]
if (byPos?.id) return byPos.id
const byChunkIndex = list.find((r) => r.chunk_index === num || r.chunk_index === num - 1)
if (byChunkIndex?.id) return byChunkIndex.id
}
if (kbId) {
const scoped = list.filter((r) => r.knowledge_base_id === kbId)
if (doc) {
const byDoc = scoped.find(
(r) =>
docTitlesMatch(doc, r.knowledge_title || '') ||
docTitlesMatch(doc, r.knowledge_filename || ''),
)
if (byDoc?.id) return byDoc.id
}
if (scoped.length === 1 && scoped[0].id) return scoped[0].id
}
return raw
}
/** Convert <web/> / <kb/> / [[wiki]] tags into inline citation HTML. */
export function preprocessCitationTags(contentStr: string): string {
export function preprocessCitationTags(
contentStr: string,
refs?: CitationKnowledgeRef[] | null,
): string {
if (!contentStr.trim()) return ''
return contentStr
.replace(/<web\b([^>]*)\/>/g, (_m, attrString: string) => {
.replace(WEB_TAG_ATTR_RE, (_m, attrString: string) => {
const attrs = parseTagAttributes(attrString)
const url = attrs.url || ''
const title = attrs.title || ''
@@ -52,20 +144,21 @@ export function preprocessCitationTags(contentStr: string): string {
}
const safeTitle = escapeHtml(title)
const safeUrl = escapeHtml(url)
return `<a class="citation citation-web" data-url="${safeUrl}" href="${safeUrl}" target="_blank" rel="noopener noreferrer"><span class="citation-icon web"></span><span class="citation-domain">${domain}</span><span class="citation-tip"><span class="tip-title">${safeTitle}</span><span class="tip-url">${safeUrl}</span></span></a>`
return `<a class="citation citation-web" data-url="${safeUrl}" href="${safeUrl}" target="_blank" rel="noopener noreferrer"><span class="citation-icon citation-icon--web" aria-hidden="true"></span><span class="citation-domain">${domain}</span><span class="citation-tip"><span class="tip-title">${safeTitle}</span><span class="tip-url">${safeUrl}</span></span></a>`
})
.replace(/<kb\b([^>]*)\/>/g, (_m, attrString: string) => {
.replace(KB_TAG_ATTR_RE, (_m, attrString: string) => {
const attrs = parseTagAttributes(attrString)
const doc = attrs.doc || ''
const chunkId = attrs.chunk_id || attrs.chunkId || ''
const rawChunkId = attrs.chunk_id || attrs.chunkId || ''
const kbId = attrs.kb_id || attrs.kbId || ''
const chunkId = resolveCitationChunkId(rawChunkId, { doc, kbId }, refs)
if (!doc || !chunkId) return ''
const safeDoc = escapeHtml(doc)
const safeKbId = escapeHtml(kbId)
const safeChunkId = escapeHtml(chunkId)
const displayDoc = escapeHtml(truncateMiddle(doc))
return `<span class="citation citation-kb" data-kb-id="${safeKbId}" data-chunk-id="${safeChunkId}" data-doc="${safeDoc}" role="button" tabindex="0"><span class="citation-icon kb"></span><span class="citation-text">${displayDoc}</span><span class="citation-tip"><span class="tip-loading">…</span></span></span>`
return `<span class="citation citation-kb" data-kb-id="${safeKbId}" data-chunk-id="${safeChunkId}" data-doc="${safeDoc}" role="button" tabindex="0"><span class="citation-icon citation-icon--book" aria-hidden="true"></span><span class="citation-text">${displayDoc}</span><span class="citation-tip"><span class="tip-loading">…</span></span></span>`
})
.replace(/\[\[([^\]]+)\]\]/g, (match, inner: string) => {
const pipeIdx = inner.indexOf('|')
@@ -85,7 +178,10 @@ export function preprocessCitationTags(contentStr: string): string {
const HTML_PLACEHOLDER_RE = /@@WEKNORA_HTML_PLACEHOLDER_(\d+)@@/g
/** Protect citation HTML from markdown parser; restore after marked.parse. */
export function extractCitationHtmlPlaceholders(contentStr: string): { content: string; htmlSnippets: string[] } {
export function extractCitationHtmlPlaceholders(
contentStr: string,
refs?: CitationKnowledgeRef[] | null,
): { content: string; htmlSnippets: string[] } {
const htmlSnippets: string[] = []
const storeHtml = (html: string): string => {
const idx = htmlSnippets.length
@@ -94,8 +190,8 @@ export function extractCitationHtmlPlaceholders(contentStr: string): { content:
}
const content = contentStr
.replace(/<(?:kb|web)\b[^>]*\/>/g, (match) => storeHtml(preprocessCitationTags(match)))
.replace(/\[\[([^\]]+)\]\]/g, (match) => storeHtml(preprocessCitationTags(match)))
.replace(KB_WEB_TAG_RE, (match) => storeHtml(preprocessCitationTags(match, refs)))
.replace(/\[\[([^\]]+)\]\]/g, (match) => storeHtml(preprocessCitationTags(match, refs)))
return { content, htmlSnippets }
}
@@ -105,10 +201,67 @@ export function restoreCitationHtmlPlaceholders(html: string, htmlSnippets: stri
return html.replace(HTML_PLACEHOLDER_RE, (_match, idx) => htmlSnippets[Number(idx)] || '')
}
/** Collapse newlines around <kb/> / <web/> so marked keeps citations inline. */
export function joinCitationTagsToPreviousLine(content: string): string {
if (!content) return content
let result = content
// Newlines between consecutive citation tags
let prev = ''
while (result !== prev) {
prev = result
result = result.replace(
/(<(?:kb|web)\b[^>]*?\s*\/?>)\s*\n+\s*(<(?:kb|web)\b)/gi,
'$1 $2',
)
}
// Blank lines before citations: join to previous prose, but keep a break after lists
result = result.replace(/\n[ \t]*\n+([ \t]*<(?:kb|web)\b)/gi, (match, kbStart, offset, full) => {
const before = full.slice(0, offset)
const lastLine = before.split('\n').filter((line) => line.trim()).pop() || ''
const isListItem = /^\s*(\d+\.|[-*+])\s+\S/.test(lastLine)
return isListItem ? `\n\n${kbStart}` : ` ${kbStart}`
})
// Single newline before citation when it follows text or another citation (not after a blank line)
result = result.replace(
/(?<!\n)(<(?:kb|web)\b[^>]*?\s*\/?>|[ \t]*\S[^\n]*?)\n([ \t]*<(?:kb|web)\b)/g,
'$1 $2',
)
return result
}
const CITATION_HTML_FRAGMENT =
'(?:<span class="citation\\b[^]*?</span>|<a class="citation\\b[^]*?</a>)'
/** Merge citation-only <p> blocks into the preceding paragraph (marked splits on newlines). */
export function collapseStandaloneCitationParagraphs(html: string): string {
if (!html || !html.includes('citation')) return html
const mergePattern = new RegExp(
`(<\\/(?:p|li)>)\\s*(?:<p>\\s*<\\/p>\\s*)*<p>\\s*(${CITATION_HTML_FRAGMENT})\\s*<\\/p>`,
'g',
)
let result = html
let prev = ''
while (result !== prev) {
prev = result
result = result.replace(mergePattern, (_match, closeTag: string, citation: string) => {
return ` ${citation}${closeTag}`
})
}
return result
}
/** Preserve raw <kb>/<web> tags before sanitizers that would strip them. */
export function preserveCitationTags(contentStr: string): { text: string; tags: string[] } {
const tags: string[] = []
const text = contentStr.replace(/<(?:kb|web)\b[^>]*\/>/g, (match) => {
const text = contentStr.replace(KB_WEB_TAG_RE, (match) => {
const idx = tags.length
tags.push(match)
return `\x00TAG${idx}\x00`