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:
@@ -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)
|
||||
})
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user