Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(chat): locate citations in manual Markdown documents (#4278)

lyingbug76ff398e0153
diff --git a/frontend/src/components/ChatReferenceSourceView.test.ts b/frontend/src/components/ChatReferenceSourceView.test.ts
new file mode 100644
index 000000000..9f7081868
--- /dev/null
+++ b/frontend/src/components/ChatReferenceSourceView.test.ts
@@ -0,0 +1,121 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { runInNewContext } from 'node:vm'
+import test from 'node:test'
+import { compileScript, parse } from '@vue/compiler-sfc'
+import ts from 'typescript'
+import { createRenderer, defineComponent, h, nextTick, reactive } from 'vue'
+import { resolveReferenceSource, type ReferenceSourceTarget } from '../utils/referenceSources.ts'
+
+const require = createRequire(import.meta.url)
+const { descriptor } = parse(readFileSync(new URL('./ChatReferenceSourceView.vue', import.meta.url), 'utf8'))
+const compiled = ts.transpileModule(compileScript(descriptor, {
+ id: 'reference-source-test', inlineTemplate: true,
+}).content, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 } }).outputText
+const flush = async () => { await new Promise(resolve => setImmediate(resolve)); await nextTick() }
+const citedMarkdown = '| Model | Flagged as AI | Judged human |\n| --- | --- | --- |\n| v2 | 11 / 210 (5%) | 95% |\n\nFlagged less than half as often as the previous release.'
+const refs = [{ id: 'chunk-1', knowledge_id: 'manual-doc', knowledge_title: 'Model card', knowledge_source: 'manual', chunk_type: 'text', content: citedMarkdown }]
+const target = resolveReferenceSource(refs, { chunkId: 'chunk-1', anchorText: '本次版本被标记的次数不到上一版本的一半。', openSource: true })!
+
+async function fixture(options: { details?: Record<string, unknown>; chunk?: Record<string, unknown>; target?: ReferenceSourceTarget } = {}) {
+ const props = reactive({ target: options.target || target, active: true })
+ const requests: string[] = [], events: string[] = []
+ let preview: any, mounts = 0
+ const exports: any = {}
+ const Preview = defineComponent({
+ props: { knowledgeId: String, fileType: String, fileName: String, locate: Object, sourceMode: Boolean, active: Boolean, toolbarTarget: Object, fillHeight: Boolean },
+ setup(p) { preview = p; mounts++; return () => h('preview') },
+ })
+ runInNewContext(compiled, { exports, console, require(name: string) {
+ if (name === 'vue') return require('vue')
+ if (name === 'vue-i18n') return { useI18n: () => ({ t: (key: string) => key }) }
+ if (name === 'vue-router') return { useRouter: () => ({ resolve: () => ({ href: '/knowledge' }) }) }
+ if (name === '@/api/knowledge-base/index') return {
+ getKnowledgeDetails: async (id: string) => {
+ requests.push(`details:${id}`)
+ return { data: { type: 'manual', source: 'manual', file_type: 'manual', file_name: 'Model card.md', file_path: '', ...options.details } }
+ },
+ getChunkByIdOnly: async (id: string) => {
+ requests.push(`chunk:${id}`)
+ return { data: { knowledge_id: props.target.knowledgeId, chunk_type: 'text', content_revision: 0, content: id === 'chunk-2' ? 'The second cited paragraph.' : citedMarkdown, source_locators: null, ...options.chunk } }
+ },
+ }
+ if (name === '@/components/document-preview.vue') return Preview
+ if (name.endsWith('.vue')) return { render: () => null }
+ if (name.startsWith('@/utils/')) return require(`../utils/${name.slice('@/utils/'.length)}.ts`)
+ throw new Error(`Unexpected import: ${name}`)
+ } })
+ type Host = { parent?: Host; children: Host[] }
+ const node = (): Host => ({ children: [] })
+ const renderer = createRenderer<Host, Host>({
+ createElement: node, createText: node, createComment: node,
+ insert(child, parent) { child.parent = parent; parent.children.push(child) },
+ remove(child) { const siblings = child.parent?.children; if (siblings) siblings.splice(siblings.indexOf(child), 1) },
+ setElementText() {}, setText() {}, patchProp() {}, parentNode: el => el.parent || null, nextSibling: () => null,
+ })
+ const app = renderer.createApp({ setup: () => () => h(exports.default, { ...props, onUnavailable: () => events.push('unavailable') }) })
+ for (const name of ['t-button', 't-icon', 't-loading']) app.component(name, { render: () => null })
+ app.mount(node())
+ await flush()
+ return { props, requests, events, preview: () => preview, mounts: () => mounts, dispose: () => app.unmount() }
+}
+
+test('manual citation opens Markdown with raw chunk evidence even without source locators', async t => {
+ const f = await fixture(); t.after(f.dispose)
+ assert.deepEqual(f.events, [])
+ const preview = f.preview()
+ assert.ok(preview, 'manual entries must not fall back to the reference list')
+ assert.equal(preview.knowledgeId, 'manual-doc', 'use the existing authenticated preview endpoint')
+ assert.equal(preview.fileType, 'md', 'manual is a storage type, not a preview extension')
+ assert.equal(preview.sourceMode, true)
+ assert.equal(preview.locate.sourceMarkdown, citedMarkdown)
+ assert.equal(preview.locate.sentence, target.anchorText)
+ assert.equal(preview.locate.unavailable, false)
+ assert.equal(preview.locate.locators.length, 0)
+})
+
+test('another citation in the same manual document updates location without remounting', async t => {
+ const f = await fixture(); t.after(f.dispose)
+ const firstToken = f.preview().locate.token
+ f.props.target = { ...target, chunkId: 'chunk-2', anchorText: 'The second cited paragraph.' }
+ await flush()
+ assert.equal(f.mounts(), 1)
+ assert.equal(f.requests.filter(r => r.startsWith('details:')).length, 1)
+ assert.equal(f.preview().locate.sourceMarkdown, 'The second cited paragraph.')
+ assert.ok(f.preview().locate.token > firstToken)
+})
+
+test('manual documents without a file name still open as Markdown', async t => {
+ const f = await fixture({ details: { file_name: '' } }); t.after(f.dispose)
+ assert.equal(f.preview().fileName, 'Model card')
+ assert.equal(f.preview().fileType, 'md')
+})
+
+for (const chunk of [{ content_revision: 1 }, { knowledge_id: 'another-document' }]) {
+ test(`manual citations reject stale or mismatched evidence: ${JSON.stringify(chunk)}`, async t => {
+ const f = await fixture({ chunk }); t.after(f.dispose)
+ assert.equal(f.preview().locate.unavailable, true)
+ assert.equal(f.preview().locate.sourceMarkdown, undefined)
+ assert.equal(f.preview().locate.quotes.length, 0)
+ })
+}
+
+test('manual document cards and summaries open without inventing a passage', async t => {
+ for (const options of [{ target: { ...target, chunkId: undefined } }, { chunk: { chunk_type: 'summary' } }]) {
+ const f = await fixture(options); t.after(f.dispose)
+ assert.ok(f.preview())
+ assert.equal(f.preview().locate, null)
+ }
+})
+
+test('FAQ still falls back to the source list even with manual source metadata', async t => {
+ const f = await fixture({ details: { type: 'faq' } }); t.after(f.dispose)
+ assert.equal(f.preview(), undefined)
+ assert.deepEqual(f.events, ['unavailable'])
+})
+
+test('uploaded files keep their original preview format', async t => {
+ const f = await fixture({ details: { type: 'file', source: 'upload', file_type: 'pdf', file_name: 'Report.pdf' }, target: { ...target, knowledgeSource: 'upload' } }); t.after(f.dispose)
+ assert.equal(f.preview().fileType, 'pdf')
+})
diff --git a/frontend/src/components/ChatReferenceSourceView.vue b/frontend/src/components/ChatReferenceSourceView.vue
index 557102786..bbd867c63 100644
--- a/frontend/src/components/ChatReferenceSourceView.vue
+++ b/frontend/src/components/ChatReferenceSourceView.vue
@@ -36,8 +36,8 @@
v-else-if="mode === 'file'"
class="reference-source__preview"
:knowledge-id="target.knowledgeId"
- :file-type="meta.fileType"
- :file-name="meta.fileName"
+ :file-type="isManual ? 'md' : meta.fileType"
+ :file-name="meta.fileName || displayName"
:active="active"
source-mode
fill-height
@@ -117,6 +117,10 @@ let shownKnowledgeId = ''
const displayName = computed(() => meta.fileName || props.target.fileName || props.target.title || '')
const displayTitle = computed(() => props.target.title || meta.title || displayName.value)
+// The preview endpoint streams manual metadata.content as Markdown, even
+// though these entries have file_type="manual" and no physical file path.
+const isManual = computed(() => meta.knowledgeSource === 'manual' ||
+ (meta.knowledgeType || meta.fileType).toLowerCase() === 'manual')
const documentHref = computed(() => {
if (!props.target.knowledgeBaseId) return ''
@@ -266,7 +270,8 @@ async function loadChunk(version: number) {
function resolveMode(): Mode {
const type = (meta.knowledgeType || meta.fileType || '').toLowerCase()
- if (meta.knowledgeSource === 'manual' || type === 'manual' || type === 'faq' || props.target.chunkType === 'faq') return 'none'
+ if (type === 'faq' || props.target.chunkType === 'faq') return 'none'
+ if (isManual.value) return 'file'
if (meta.fileName && isKnownPreviewableFile(meta.fileName, meta.fileType)) return 'file'
if (isWebUrl(meta.knowledgeSource)) return 'web'
return 'none'
diff --git a/frontend/src/components/ChatReferencesDrawer.vue b/frontend/src/components/ChatReferencesDrawer.vue
index 1d1de33c6..18b914a63 100644
--- a/frontend/src/components/ChatReferencesDrawer.vue
+++ b/frontend/src/components/ChatReferencesDrawer.vue
@@ -287,7 +287,7 @@ function backToList() {
}
function onSourceUnavailable() {
- // No original file to show (manual entry, FAQ, deleted file): fall back
+ // No original document to show (FAQ or unsupported source): fall back
// to the list with the cited card highlighted.
backToList()
}
diff --git a/frontend/tests/source-locate/Harness.vue b/frontend/tests/source-locate/Harness.vue
index c56edc0af..e35eace91 100644
--- a/frontend/tests/source-locate/Harness.vue
+++ b/frontend/tests/source-locate/Harness.vue
@@ -114,6 +114,24 @@ onMounted(async () => {
const highlight = (CSS as any).highlights?.get('source-locate')
return highlight ? [...highlight].map((r: Range) => r.toString()).join('') : [...document.querySelectorAll('.source-locate-mark')].map(e => e.textContent).join('')
}
+ // Manual/clipped documents have no source_locators. Match their raw chunk
+ // Markdown against the complete document returned by the preview endpoint.
+ const manualChunk = '| Model | Flagged as AI | Judged human |\n| --- | --- | --- |\n| v2 | 11 / 210 (5%) | 95% |\n\nFlagged less than half as often as the previous release.'
+ const manualDocument = '# Model card\n\n' + 'Unrelated introduction.\n\n'.repeat(60) + manualChunk + '\n\nUnrelated appendix.'
+ const manualRequest = { sourceMarkdown: manualChunk, sentence: '本次版本被标记的次数不到上一版本的一半。' }
+ await runOther('Manual Markdown without locators highlights the cited table and paragraph and scrolls to them', new Blob([manualDocument]), 'md', manualRequest, r => {
+ assert(r.found && r.precise, JSON.stringify(r))
+ const text = highlightedText()
+ assert(text.includes('11 / 210 (5%)') && text.includes('95%') && text.includes('Flagged less than half'), text)
+ assert(!text.includes('Unrelated'), 'unrelated paragraphs must not be highlighted')
+ const box = document.querySelector<HTMLElement>('.preview-markdown')!
+ assert(box.scrollTop > 0, 'the cited passage must be scrolled into view')
+ })
+ await runOther('Manual Markdown rejects changed source evidence', new Blob([manualDocument.replace('11 / 210', '15 / 210')]), 'md', manualRequest, r => {
+ assert(!r.found, JSON.stringify(r))
+ assert(!highlightedText(), 'missing evidence must not leave stale highlights')
+ })
+ await runOther('Manual Markdown rejects duplicate source passages', new Blob([manualDocument + '\n\n' + manualChunk]), 'md', manualRequest, r => assert(!r.found, JSON.stringify(r)))
await runOther('Markdown fenced language is not treated as visible evidence', new Blob([fenced]), 'md', { sourceMarkdown: fenced }, r => assert(r.found && r.precise, JSON.stringify(r)))
await runOther('Markdown paraphrase narrows within its verified source block', new Blob([fenced]), 'md', { sourceMarkdown: fenced, sentence: 'This operation preserves the current commit and files, freeing the branch.' }, r => {
assert(r.found && !r.precise, JSON.stringify(r))
diff --git a/frontend/tests/source-locate/README.md b/frontend/tests/source-locate/README.md
index ac02ee404..b14852231 100644
--- a/frontend/tests/source-locate/README.md
+++ b/frontend/tests/source-locate/README.md
@@ -2,7 +2,7 @@
From `frontend`, run `npm run dev -- --host 127.0.0.1 --port 5199`, then open
`http://127.0.0.1:5199/tests/source-locate/index.html` in a browser.
-The page runs 52 cases against the actual Vue previews, PDF.js, docx-preview,
+The page runs 55 cases against the actual Vue previews, PDF.js, docx-preview,
SheetJS and EPUB renderer. Each result is displayed as PASS/FAIL. The page is
outside the production entry point and is not included in the app build.
@@ -52,6 +52,12 @@ cases verify that a citation keeps all preceding sentences since the previous
citation. Private Markdown fixtures must provide `request.sourceMarkdown` before
markup stripping; `highlightText` asserts the exact highlighted source paragraphs.
+Manual Markdown cases cover table-and-paragraph citations without source locators,
+scrolling to the highlighted passage, and rejecting changed or duplicate evidence.
+Run `npm test -- src/components/ChatReferenceSourceView.test.ts` to also verify
+manual citation routing, Markdown preview type, same-document citation changes,
+summary/card behavior, and stale or mismatched chunk rejection.
+
Chunk-boundary cases assert complete original paragraph context when a child
ends or starts mid-paragraph. Candidate paragraphs must intersect a uniquely
verified source region with at least eight normalized characters. Duplicate