fix(citations): 修复原文定位、高亮范围与 DocReader 启动失败 (#3794)

* fix(citations): verify source locations and recover document previews

* chore: exclude local research notes from pull request
main
lyingbug 2026-09-27 20:32:26 +08:00 committed by GitHub
parent 4df7ccbb4f
commit 9114e4e4f9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
73 changed files with 3483 additions and 708 deletions

View File

@ -155,5 +155,8 @@ RUN mkdir -p /tmp/docreader
# 暴露 gRPC 端口
EXPOSE 50051
# 直接运行 Python 服务(日志输出到 stdout/stderr)
CMD ["uv", "run", "-m", "docreader.main"]
# Probe ARM crypto instructions before importing native dependencies. The
# entrypoint only enables portable OpenSSL implementations after a SIGILL.
ENTRYPOINT ["/app/.venv/bin/python", "-m", "docreader.container_entrypoint"]
# Dependencies are installed from uv.lock at build time; do not mutate them at boot.
CMD ["/app/.venv/bin/python", "-m", "docreader.main"]

View File

@ -0,0 +1,49 @@
"""Keep ARM virtual machines with incomplete CPU support from crashing at boot.
Probe in a child: SIGILL cannot be caught as a Python exception. Only that
specific failure permits the OpenSSL portable path; other failures stay fatal.
OPENSSL_armcap is documented at https://docs.openssl.org/master/man3/OPENSSL_armcap/
"""
import os
import platform
import signal
import subprocess
import sys
PROBE = """
import resource
resource.setrlimit(resource.RLIMIT_CORE, (0, 0))
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
cipher = AESGCM(bytes(32))
nonce = bytes(12)
encrypted = cipher.encrypt(nonce, b'docreader startup probe', b'probe')
assert cipher.decrypt(nonce, encrypted, b'probe') == b'docreader startup probe'
"""
def runtime_environment():
env = os.environ.copy()
if platform.machine().lower() not in {"arm64", "aarch64"} or "OPENSSL_armcap" in env:
return env
command = [sys.executable, "-c", PROBE]
result = subprocess.run(command, env=env, capture_output=True, timeout=30)
if result.returncode == -signal.SIGILL:
env["OPENSSL_armcap"] = "0"
result = subprocess.run(command, env=env, capture_output=True, timeout=30)
if result.returncode == 0:
print("DocReader: ARM OpenSSL probe raised SIGILL; using portable CPU implementations (OPENSSL_armcap=0).", file=sys.stderr, flush=True)
if result.returncode != 0:
raise RuntimeError(f"DocReader crypto startup probe failed ({result.returncode}): {result.stderr.decode(errors='replace')}")
return env
def main():
if len(sys.argv) < 2:
raise SystemExit("DocReader entrypoint requires a command")
os.execvpe(sys.argv[1], sys.argv[1:], runtime_environment())
if __name__ == "__main__":
main()

View File

@ -17,6 +17,7 @@ self-sufficient using pypdfium2 + the Go-side OCR that already exists.
"""
import base64
from collections import Counter
import io
import logging
import os
@ -647,7 +648,14 @@ def _page_chars(textpage, page, raw, loose: bool = False) -> tuple:
n = textpage.count_chars()
if n <= 0:
return [], 0.0
width, height = page.get_size()
# Glyph coordinates are unrotated PDF user space. get_size() reports
# rotated dimensions and would discard valid text on cropped/rotated pages.
try:
crop_left, crop_bottom, crop_right, crop_top = page.get_cropbox()
except Exception:
width, height = page.get_size()
crop_left, crop_bottom, crop_right, crop_top = 0, 0, width, height
width = crop_right - crop_left
invisible = _collect_invisible_boxes(page, raw) if FILTER_HIDDEN_TEXT else []
chars: list = []
@ -662,7 +670,7 @@ def _page_chars(textpage, page, raw, loose: bool = False) -> tuple:
x0, x1 = (left, right) if left <= right else (right, left)
y0, y1 = (bottom, top) if bottom <= top else (top, bottom)
if FILTER_HIDDEN_TEXT:
if x1 < 0 or x0 > width or y1 < 0 or y0 > height:
if x1 < crop_left or x0 > crop_right or y1 < crop_bottom or y0 > crop_top:
continue # off-page glyph
if invisible and _point_in_boxes((x0 + x1) / 2, (y0 + y1) / 2, invisible):
continue # covered by an invisible text object
@ -947,6 +955,11 @@ def _should_prefer_plain(plain: str, layout: str) -> bool:
return True
if not plain:
return False
# Geometry must never change numeric evidence (1.5 -> 1 5, -5 -> 5).
# Compare a multiset so legitimate column reordering is still allowed.
numbers = re.compile(r"[+−-]?\d+(?:[.,:/]\d+)*(?:[%‰])?")
if Counter(numbers.findall(plain)) != Counter(numbers.findall(layout)):
return True
n, single, punct_only = _layout_line_stats(layout)
if n == 0:
return True
@ -1489,7 +1502,7 @@ class PDFScannedParser(BaseParser):
{
"start": offset,
"end": offset + len(line),
"locator": {"type": "pdf", "page": i + 1},
"locator": {"type": "pdf", "page": i + 1, "mapping": "exact"},
}
)
offset += len(line)
@ -1694,7 +1707,7 @@ class PDFParser(BaseParser):
return start
for i in range(page_count):
page_only = {"type": "pdf", "page": i + 1}
page_only = {"type": "pdf", "page": i + 1, "mapping": "exact"}
if classes[i] == "scanned":
page_filename = f"{base_name}_page_{i+1}.jpg"
part = f"![{page_filename}](images/{page_filename})"

View File

@ -11,14 +11,13 @@ the origin at its top-left corner, so viewers can draw it at any zoom.
from __future__ import annotations
import re
from collections import Counter
import statistics
import unicodedata
from typing import Iterable, List, Optional, Sequence, Tuple
# How far past the cursor a line is searched for, in normalized characters.
_SEARCH_WINDOW = 6000
# How much of a line's normalized text is searched for.
_KEY_CHARS = 24
# Lines shorter than this (normalized) are too ambiguous to place.
_MIN_KEY_CHARS = 2
# Lines shorter than this are placed only when their text is unique on the
@ -54,7 +53,22 @@ def normalize_with_positions(text: str) -> Tuple[str, List[int]]:
out: List[str] = []
pos: List[int] = []
for i, ch in enumerate(text):
value = unicodedata.normalize("NFKC", ch)
folded = _fold(ch)
if value in ".,:/+−-%‰<>=≤≥≠":
before, after = i - 1, i + 1
while before >= 0 and text[before] in " \t":
before -= 1
while after < len(text) and text[after] in " \t":
after += 1
prev = before >= 0 and text[before].isdigit()
next_digit = after < len(text) and text[after].isdigit()
semantic = ((value in ".,/:" and prev and next_digit)
or (value in "+-−" and next_digit)
or (value in "%‰" and prev)
or value in "<>=≤≥≠")
if semantic:
folded = value.replace("−", "-")
for f in folded:
out.append(f)
pos.append(i)
@ -62,7 +76,7 @@ def normalize_with_positions(text: str) -> Tuple[str, List[int]]:
def normalize(text: str) -> str:
return "".join(_fold(ch) for ch in text)
return normalize_with_positions(text)[0]
def _key_weight(key: str) -> int:
@ -81,6 +95,23 @@ def _column_cursor(boxes, idx: int, ends: List[Optional[int]]) -> Optional[int]:
return None
def _numeric_safe_matches(text: str, key: str) -> List[int]:
out = []
if not key:
return out
start = 0
while (at := text.find(key, start)) >= 0:
before = text[at - 1] if at else ""
end = at + len(key)
after = text[end] if end < len(text) else ""
left = key[0].isdigit() and bool(before) and (before.isdigit() or before in ".,:/+−-")
right = key[-1].isdigit() and bool(after) and (after.isdigit() or after in ".,:/%‰")
if not left and not right:
out.append(at)
start = at + 1
return out
def locate_lines(
page_text: str,
line_texts: Sequence[str],
@ -100,10 +131,12 @@ def locate_lines(
hits: List[Optional[int]] = []
ends: List[Optional[int]] = []
cursor = 0
counts = Counter(normalize(line) for line in line_texts)
occurrences = {key: _numeric_safe_matches(norm, key) for key in counts}
for idx, line in enumerate(line_texts):
key = normalize(line)[:_KEY_CHARS]
if len(key) < _MIN_KEY_CHARS or (
_key_weight(key) < _SHORT_KEY_WEIGHT and norm.count(key) > 1
key = normalize(line)
if len(key) < _MIN_KEY_CHARS or len(occurrences[key]) != counts[key] or (
_key_weight(key) < _SHORT_KEY_WEIGHT and len(occurrences[key]) > 1
):
hits.append(None)
ends.append(None)
@ -115,11 +148,11 @@ def locate_lines(
cursors.insert(0, column)
at = -1
for start_at in cursors:
at = norm.find(key, start_at, start_at + _SEARCH_WINDOW + len(key))
at = next((hit for hit in occurrences[key] if start_at <= hit <= start_at + _SEARCH_WINDOW), -1)
if at >= 0:
break
if at < 0:
at = norm.find(key)
at = occurrences[key][0] if len(occurrences[key]) == 1 else -1
if at < 0:
hits.append(None)
ends.append(None)
@ -232,13 +265,12 @@ def page_blocks(
``lines`` are visual lines ``{"text", "bbox"}`` (bbox in PDF points). Lines
are placed in ``page_text``, grouped into paragraphs by geometry, and each
paragraph becomes a block spanning from its first line to the next
paragraph, boxed by the union of its lines. Text before the first placed
line, or a page with no placeable lines, gets a page-only block, so the
blocks always tile the page's text.
paragraph becomes a block spanning only its matched lines, boxed by their
union. Unmatched gaps keep page-only provenance and never inherit the
previous paragraph's geometry.
"""
end = offset + len(page_text)
page_only = {"type": "pdf", "page": page_number}
page_only = {"type": "pdf", "page": page_number, "mapping": "exact"}
if not page_text:
return []
placed = []
@ -264,30 +296,49 @@ def page_blocks(
for g in (_line_gap(a[1], b[1]) for a, b in zip(placed, placed[1:]))
if g is not None and g >= 0
]
usual_gap = statistics.median(gaps) if gaps else line_h * 0.5
usual_gap = min(statistics.median(gaps), line_h * 1.5) if gaps else line_h * 0.5
norm, positions = normalize_with_positions(page_text)
def line_end(at, line):
key = normalize(line["text"])
norm_start = next((i for i, p in enumerate(positions) if p >= at), len(norm))
hit = norm.find(key, norm_start)
if hit < 0:
return at
end_at = positions[hit + len(key) - 1] + 1
while end_at < len(page_text) and not page_text[end_at].isalnum():
if page_text[end_at] == "\n":
return end_at + 1
end_at += 1
return end_at
paragraphs: List[Tuple[int, List[dict]]] = []
for at, ln in placed:
ln = {**ln, "_source_end": line_end(at, ln)}
if paragraphs:
prev = paragraphs[-1][1][-1]
col_right = max(p["bbox"][2] for p in paragraphs[-1][1])
col_right = max(col_right, ln["bbox"][2])
if not _starts_paragraph(prev, ln, line_h, usual_gap, col_right):
previous_end = prev["_source_end"]
gap_is_empty = not normalize(page_text[previous_end:at])
if gap_is_empty and not _starts_paragraph(prev, ln, line_h, usual_gap, col_right):
paragraphs[-1][1].append(ln)
continue
paragraphs.append((at, [ln]))
blocks: List[dict] = []
first_at = paragraphs[0][0]
if first_at > 0 and page_text[:first_at].strip():
blocks.append({"start": offset, "end": offset + first_at, "locator": dict(page_only)})
for i, (at, members) in enumerate(paragraphs):
stop = paragraphs[i + 1][0] if i + 1 < len(paragraphs) else len(page_text)
if i == 0:
at = 0 if not blocks else at
cursor = 0
for at, members in paragraphs:
stop = members[-1]["_source_end"]
if stop <= at:
continue
if at > cursor and page_text[cursor:at].strip():
blocks.append({"start": offset + cursor, "end": offset + at, "locator": dict(page_only)})
locator = dict(page_only)
locator["bbox"] = geometry.bbox(_union(m["bbox"] for m in members))
locator["source_id"] = f"pdf:{page_number}:{at}:{stop}"
blocks.append({"start": offset + at, "end": offset + stop, "locator": locator})
cursor = stop
if cursor < len(page_text) and page_text[cursor:].strip():
blocks.append({"start": offset + cursor, "end": end, "locator": dict(page_only)})
return blocks

View File

@ -0,0 +1,41 @@
"""Regenerate browser fixtures with the actual builtin PDF parser.
Run from the repository root:
docreader/.venv/bin/python -m docreader.tests.generate_source_location_browser_fixtures
"""
import base64
import json
from pathlib import Path
from unittest.mock import patch
from docreader.parser.pdf_parser import PDFParser
from docreader.tests.test_source_locator_pdf import pdf_fixture
def main():
cases = [{"name": "PDFium lower paragraph with decimal evidence", "page": 2,
"needle": "Second page lower evidence", "pages": [
{"lines": [("First page has independent original evidence.", 60, 700)]},
{"lines": [("Second page upper paragraph is unrelated.", 60, 700),
("Second page lower evidence: the limit is 1.5 mm.", 60, 400)]}]}]
for rotation in (0, 90, 180, 270):
cases.append({"name": f"PDFium CropBox and rotation {rotation}", "page": 1,
"needle": "Cropped and rotated", "pages": [
{"rotation": rotation, "crop": "/CropBox [100 100 500 700]",
"lines": [("Cropped and rotated source evidence.", 150, 600)]}]})
output = []
for case in cases:
data = pdf_fixture(case["pages"])
with patch("docreader.parser.pdf_parser.SOURCE_BOXES", True):
doc = PDFParser(file_name="fixture.pdf", pdf_force_scanned=False).parse_into_text(data)
at = doc.content.index(case["needle"])
block = next(b for b in doc.source_blocks if b["start"] <= at < b["end"])
locator = {**block["locator"], "quote": doc.content[block["start"]:block["end"]].strip()}
assert locator.get("bbox"), case["name"]
output.append({"name": case["name"], "page": case["page"], "pdf": base64.b64encode(data).decode(), "locator": locator})
target = Path(__file__).resolve().parents[2] / "frontend/tests/source-locate/parsedFixtures.json"
target.write_text(json.dumps(output, ensure_ascii=False, indent=2) + "\n")
if __name__ == "__main__":
main()

View File

@ -0,0 +1,64 @@
import os
import signal
import subprocess
import unittest
from unittest.mock import patch
from docreader.container_entrypoint import runtime_environment
class ContainerEntrypointTest(unittest.TestCase):
def setUp(self):
env = patch.dict(os.environ, {"PATH": "/app/.venv/bin"}, clear=True)
env.start()
self.addCleanup(env.stop)
machine = patch("docreader.container_entrypoint.platform.machine", return_value="aarch64")
machine.start()
self.addCleanup(machine.stop)
@patch("docreader.container_entrypoint.subprocess.run")
def test_healthy_arm_keeps_acceleration(self, run):
run.return_value = subprocess.CompletedProcess([], 0, b"", b"")
self.assertNotIn("OPENSSL_armcap", runtime_environment())
self.assertEqual(run.call_count, 1)
@patch("docreader.container_entrypoint.subprocess.run")
def test_sigill_retries_and_verifies_portable_crypto(self, run):
run.side_effect = [subprocess.CompletedProcess([], -signal.SIGILL, b"", b""), subprocess.CompletedProcess([], 0, b"", b"")]
self.assertEqual(runtime_environment()["OPENSSL_armcap"], "0")
self.assertEqual(run.call_count, 2)
self.assertNotIn("OPENSSL_armcap", os.environ)
@patch("docreader.container_entrypoint.subprocess.run")
def test_other_failure_is_not_masked(self, run):
run.return_value = subprocess.CompletedProcess([], 1, b"", b"missing dependency")
with self.assertRaisesRegex(RuntimeError, "missing dependency"):
runtime_environment()
self.assertEqual(run.call_count, 1)
@patch("docreader.container_entrypoint.subprocess.run")
def test_failed_portable_probe_stays_fatal(self, run):
run.side_effect = [subprocess.CompletedProcess([], -signal.SIGILL, b"", b""), subprocess.CompletedProcess([], 1, b"", b"encryption failed")]
with self.assertRaisesRegex(RuntimeError, "encryption failed"):
runtime_environment()
@patch("docreader.container_entrypoint.subprocess.run")
def test_operator_override_is_preserved(self, run):
os.environ["OPENSSL_armcap"] = "0x1"
self.assertEqual(runtime_environment()["OPENSSL_armcap"], "0x1")
run.assert_not_called()
@patch("docreader.container_entrypoint.platform.machine", return_value="x86_64")
@patch("docreader.container_entrypoint.subprocess.run")
def test_other_architectures_are_unchanged(self, run, machine):
self.assertNotIn("OPENSSL_armcap", runtime_environment())
run.assert_not_called()
@patch("docreader.container_entrypoint.subprocess.run", side_effect=subprocess.TimeoutExpired("probe", 30))
def test_probe_has_bounded_startup(self, run):
with self.assertRaises(subprocess.TimeoutExpired):
runtime_environment()
if __name__ == "__main__":
unittest.main()

View File

@ -63,7 +63,7 @@ class PageBlocksTest(unittest.TestCase):
def test_page_without_lines_gets_page_block(self):
blocks = page_blocks("文字", 5, 2, [], None)
self.assertEqual(blocks, [{"start": 5, "end": 7, "locator": {"type": "pdf", "page": 2}}])
self.assertEqual(blocks, [{"start": 5, "end": 7, "locator": {"type": "pdf", "page": 2, "mapping": "exact"}}])
class WireTest(unittest.TestCase):
@ -139,5 +139,41 @@ class SplitLineAtGapsTest(unittest.TestCase):
self.assertEqual(len(_split_line_at_gaps(self._line(chars))), 1)
class PrecisionRegressionTest(unittest.TestCase):
def test_common_prefix_cannot_place_a_different_conclusion(self):
prefix = "Common opening repeated before the important conclusion "
self.assertEqual(locate_lines(prefix + "failed", [prefix + "passed"]), [None])
def test_numeric_meaning_is_preserved(self):
for source, quote in [("limit 15 mm", "limit 1.5 mm"), ("temperature 5 C", "temperature -5 C"), ("rate 5", "rate 5%")]:
self.assertEqual(locate_lines(source, [quote]), [None])
def test_unaccounted_duplicate_does_not_take_first_region(self):
quote = "A repeated paragraph with enough text"
self.assertEqual(locate_lines(quote + "\n" + quote, [quote]), [None])
def test_unmatched_text_never_inherits_previous_geometry(self):
page = "First matched line.\nUnmatched evidence in between.\nLast matched line."
lines = [_ln("First matched line.", 50, 700, 300, 712), _ln("Last matched line.", 50, 668, 300, 680)]
blocks = page_blocks(page, 0, 2, lines, PageGeometry((0, 0, 600, 800)))
at = page.index("Unmatched")
covering = [b for b in blocks if b["start"] <= at < b["end"]]
self.assertEqual(len(covering), 1)
self.assertNotIn("bbox", covering[0]["locator"])
self.assertEqual(covering[0]["locator"]["page"], 2)
def test_trailing_unmatched_text_has_only_page_provenance(self):
page = "Matched paragraph.\nUnrecognized trailing evidence."
blocks = page_blocks(page, 0, 7, [_ln("Matched paragraph.", 50, 700, 300, 712)], PageGeometry((0, 0, 600, 800)))
self.assertEqual(blocks[0]["end"], page.index("Unrecognized"))
self.assertNotIn("bbox", blocks[-1]["locator"])
def test_wire_preserves_verified_geometry_and_identity(self):
from docreader.source_wire import source_blocks_to_proto
locator = {"type": "pdf", "page": 501, "mapping": "exact", "source_id": "pdf:501:0:3", "bbox": [.1, .2, .8, .4]}
wire = source_blocks_to_proto(Document(content="abc", source_blocks=[{"start": 0, "end": 3, "locator": locator}]))
self.assertEqual(json.loads(wire[0].locator_json), locator)
if __name__ == "__main__":
unittest.main()

View File

@ -0,0 +1,78 @@
"""Actual PDFium parsing through source blocks and the protobuf JSON boundary."""
import json
import unittest
from unittest.mock import patch
from docreader.parser.pdf_parser import PDFParser
from docreader.source_wire import source_blocks_to_proto
from docreader.tests.test_pdf_embedded_images import _pdf_from_objects
def pdf_fixture(pages):
objects = [
b"<< /Type /Catalog /Pages 2 0 R >>",
("<< /Type /Pages /Count %d /Kids [%s] >>" % (
len(pages), " ".join(f"{4+i*2} 0 R" for i in range(len(pages)))
)).encode(),
b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
]
for i, page in enumerate(pages):
stream = "\n".join(f"BT /F1 14 Tf {x} {y} Td ({text}) Tj ET" for text, x, y in page["lines"]).encode()
objects.extend([
(f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 600 800] /Rotate {page.get('rotation', 0)} "
f"{page.get('crop', '')} /Resources << /Font << /F1 3 0 R >> >> /Contents {5+i*2} 0 R >>").encode(),
f"<< /Length {len(stream)} >>\nstream\n".encode() + stream + b"\nendstream",
])
return _pdf_from_objects(objects)
class NativePDFSourceTest(unittest.TestCase):
def parse(self, pages):
with patch("docreader.parser.pdf_parser.SOURCE_BOXES", True):
doc = PDFParser(file_name="source-regression.pdf", file_type="pdf", pdf_force_scanned=False).parse_into_text(pdf_fixture(pages))
self.assertFalse(doc.metadata.get("scanned_page_count"))
return doc
def test_page_and_region_survive_actual_parser_and_wire(self):
doc = self.parse([
{"lines": [("First page has independent original evidence.", 60, 700)]},
{"lines": [("Second page upper paragraph is unrelated.", 60, 700),
("Second page lower evidence: the limit is 1.5 mm.", 60, 400)]},
])
at = doc.content.index("Second page lower evidence")
source = [b for b in doc.source_blocks if b["start"] <= at < b["end"]]
self.assertEqual(len(source), 1)
loc = source[0]["locator"]
self.assertEqual(loc["page"], 2)
self.assertEqual(loc["mapping"], "exact")
self.assertGreater(loc["bbox"][1], .45)
self.assertLess(loc["bbox"][3], .55)
self.assertIn("1.5 mm", doc.content[source[0]["start"]:source[0]["end"]])
self.assertIn(loc, [json.loads(b.locator_json) for b in source_blocks_to_proto(doc)])
def test_cropbox_and_rotation_use_displayed_page_coordinates(self):
for rotation in (0, 90, 180, 270):
with self.subTest(rotation=rotation):
doc = self.parse([{"rotation": rotation, "crop": "/CropBox [100 100 500 700]",
"lines": [("Cropped and rotated source evidence.", 150, 600)]}])
loc = next(b["locator"] for b in doc.source_blocks if b["locator"].get("bbox"))
x0, y0, x1, y1 = loc["bbox"]
self.assertTrue(0 <= x0 < x1 <= 1 and 0 <= y0 < y1 <= 1)
if rotation == 0: self.assertLess(y1, .2)
elif rotation == 90: self.assertGreater(x0, .8)
elif rotation == 180: self.assertGreater(y0, .8)
else: self.assertLess(x1, .2)
def test_identical_paragraphs_keep_distinct_vertical_regions(self):
text = "Repeated paragraph with identical original evidence."
doc = self.parse([{"lines": [(text, 60, 700), (text, 60, 400)]}])
boxed = [b for b in doc.source_blocks if b["locator"].get("bbox")]
self.assertEqual(len(boxed), 2)
self.assertNotEqual(boxed[0]["locator"]["source_id"], boxed[1]["locator"]["source_id"])
self.assertLess(boxed[0]["locator"]["bbox"][1], .2)
self.assertGreater(boxed[1]["locator"]["bbox"][1], .45)
self.assertIn(text.rstrip('.'), doc.content[boxed[1]["start"]:boxed[1]["end"]])
if __name__ == "__main__":
unittest.main()

View File

@ -58,6 +58,8 @@
</template>
<script setup lang="ts">
import { sourceImageDigest } from '@/utils/sourceImage'
import { buildProtectedFileRequest, resolveProtectedFileAccess } from '@/utils/protectedFileAccess'
import { computed, reactive, ref, watch } from 'vue'
import { useI18n } from 'vue-i18n'
import { useRouter } from 'vue-router'
@ -71,6 +73,9 @@ import {
parseSourceLocators,
selectLocatorsForSentence,
selectQuoteForSentence,
sourceQuoteText,
sourceImageContext,
quotedSourceExcerpt,
textFragmentUrl,
type SourceLocateRequest,
type SourceLocator,
@ -90,7 +95,7 @@ const { t } = useI18n()
const router = useRouter()
type Mode = 'loading' | 'file' | 'web' | 'none'
type Status = 'idle' | 'locating' | 'found' | 'page' | 'missing'
type Status = 'idle' | 'locating' | 'found' | 'page' | 'block' | 'ambiguous' | 'stale' | 'missing' | 'partial'
const mode = ref<Mode>('loading')
const toolbarSlot = ref<HTMLElement | null>(null)
@ -100,6 +105,11 @@ const locate = ref<SourceLocateRequest | null>(null)
const locators = ref<SourceLocator[]>([])
const chunkContent = ref('')
const chunkType = ref('')
const sourceHash = ref('')
const edited = ref(false)
const imageDigest = ref<string>()
const imageContext = ref<SourceLocateRequest['imageContext']>()
let locateToken = 0
const meta = reactive({ fileName: '', fileType: '', knowledgeSource: '', knowledgeType: '', title: '' })
let loadVersion = 0
/** The knowledge whose file the preview currently shows. */
@ -121,7 +131,15 @@ const statusText = computed(() => {
case 'locating':
return t('chat.referenceSourceLocating')
case 'found':
return locatedPage.value ? t('chat.referenceSourceFoundPage', { page: locatedPage.value }) : ''
return t('chat.referenceSourceExact')
case 'partial':
return t('chat.referenceSourcePartial')
case 'block':
return t('chat.referenceSourceBlock')
case 'ambiguous':
return t('chat.referenceSourceAmbiguous')
case 'stale':
return t('chat.referenceSourceStale')
case 'page':
return t('chat.referenceSourceFoundPage', { page: locatedPage.value })
case 'missing':
@ -146,11 +164,12 @@ async function loadMeta(version: number) {
meta.knowledgeSource = props.target.knowledgeSource || ''
meta.knowledgeType = ''
meta.title = props.target.title || ''
if (meta.fileName && meta.knowledgeSource) return
sourceHash.value = ''
try {
const res: any = await getKnowledgeDetails(props.target.knowledgeId)
if (version !== loadVersion) return
const data = res?.data || {}
sourceHash.value = data.file_hash || ''
meta.fileName = meta.fileName || data.file_name || ''
meta.fileType = data.file_type || ''
meta.knowledgeSource = meta.knowledgeSource || data.source || ''
@ -163,19 +182,83 @@ async function loadMeta(version: number) {
async function loadChunk(version: number) {
locators.value = parseSourceLocators(props.target.locators)
chunkContent.value = ''
chunkContent.value = props.target.content || ''
edited.value = false
imageContext.value = undefined
imageDigest.value = undefined
chunkType.value = props.target.chunkType || ''
if (locators.value.length) return
let loadedCurrent = false
// Old conversations and agent tool results carry no locators; the chunk
// itself has them (and its own, unexpanded text for matching).
try {
const res: any = await getChunkByIdOnly(props.target.chunkId)
if (version !== loadVersion) return
locators.value = parseSourceLocators(res?.data?.source_locators)
chunkContent.value = String(res?.data?.content || '')
chunkType.value = chunkType.value || String(res?.data?.chunk_type || '')
// The current chunk overrides snapshots embedded in historical answers.
// In particular, an edit must invalidate even previously cached locators.
const current = res?.data
if (!current || current.knowledge_id !== props.target.knowledgeId) {
edited.value = true
locators.value = []
return
}
loadedCurrent = true
locators.value = parseSourceLocators(current.source_locators)
edited.value = (current.content_revision || 0) > 0 && !locators.value.length
chunkContent.value = String(current.content || '')
chunkType.value = String(current.chunk_type || '')
const chunk = res?.data
if (!edited.value && chunk?.chunk_type?.startsWith('image_')) {
let info = chunk.image_info
try { if (typeof info === 'string') info = JSON.parse(info) } catch { info = [] }
if (Array.isArray(info) && info.length === 1) {
const digest = info[0].sha256
if (typeof digest === 'string' && /^[a-f0-9]{64}$/.test(digest)) imageDigest.value = digest
else {
const request = buildProtectedFileRequest(info[0].url || '', resolveProtectedFileAccess({ mode: 'knowledgeBase', kbId: props.target.knowledgeBaseId || '' }))
if (request) {
try {
const response = await fetch(request.url, { headers: request.headers, credentials: 'include' })
if (response.ok) {
const hash = await sourceImageDigest(await response.arrayBuffer())
if (version !== loadVersion) return
imageDigest.value = hash
}
} catch { /* Existing structural locators may still locate the image. */ }
}
}
}
}
// Legacy expanded contexts were cited under a child ID. Only recover a
// verbatim quotation in its verified parent, never search the whole file
// for a merely similar answer or silently select a neighbouring chunk.
if (!edited.value && chunk?.chunk_type === 'text' && chunk.parent_chunk_id &&
!quotedSourceExcerpt(chunkContent.value, props.target.anchorText || '')) {
const parent: any = await getChunkByIdOnly(chunk.parent_chunk_id)
if (version !== loadVersion) return
const p = parent?.data
if (p?.knowledge_id === props.target.knowledgeId && p.chunk_type === 'parent_text' && !p.content_revision &&
quotedSourceExcerpt(p.content || '', props.target.anchorText || '')) {
const parentLocators = parseSourceLocators(p.source_locators)
if (parentLocators.length && parentLocators.every(l => l.mapping === 'exact' && l.source_hash)) {
chunkContent.value = p.content
locators.value = parentLocators
}
}
}
if (!edited.value && chunk?.chunk_type?.startsWith('image_') && chunk.parent_chunk_id) {
const parent: any = await getChunkByIdOnly(chunk.parent_chunk_id)
if (version !== loadVersion) return
if (parent?.data?.knowledge_id === props.target.knowledgeId && !parent.data.content_revision) {
let info = chunk.image_info
try { if (typeof info === 'string') info = JSON.parse(info) } catch { info = [] }
const urls = Array.isArray(info) ? info.flatMap(i => [i.url, i.original_url].filter(Boolean)) : []
imageContext.value = sourceImageContext(parent.data.content || '', urls)
}
}
} catch {
chunkContent.value = props.target.content || ''
if (version !== loadVersion) return
if (!loadedCurrent) chunkContent.value = props.target.content || ''
}
}
@ -191,8 +274,9 @@ function buildLocate(): SourceLocateRequest {
const anchor = props.target.anchorText || ''
const selected = selectLocatorsForSentence(locators.value, anchor)
const quotes = chunkContent.value ? selectQuoteForSentence(chunkContent.value, anchor) : []
const scope = chunkContent.value || props.target.content || ''
return { locators: selected, quotes, token: Date.now(), sentence: anchor, scope }
const scope = sourceQuoteText(chunkContent.value || props.target.content || '')
const unavailable = edited.value || locators.value.some((loc) => loc.source_hash && sourceHash.value && loc.source_hash !== sourceHash.value)
return { locators: unavailable ? [] : selected, quotes: unavailable ? [] : quotes, token: ++locateToken, sentence: anchor, sourceMarkdown: unavailable ? undefined : chunkContent.value, imageDigest: unavailable ? undefined : imageDigest.value, imageContext: unavailable ? undefined : imageContext.value, scope: unavailable ? '' : scope, unavailable }
}
async function load() {
@ -215,20 +299,25 @@ async function load() {
}
// A summary speaks for the whole document: open it without hunting for a passage.
if (next === 'file' && chunkType.value !== 'summary') {
status.value = 'locating'
locate.value = buildLocate()
status.value = locate.value.unavailable ? 'stale' : 'locating'
}
}
function relocate() {
if (!locate.value) return
status.value = 'locating'
locate.value = { ...locate.value, token: Date.now() }
locate.value = { ...locate.value, token: ++locateToken }
}
function onLocated(result: { found: boolean; precise: boolean; page?: number }) {
function onLocated(result: { found: boolean; precise: boolean; page?: number; granularity?: string; reason?: string }) {
if (locate.value?.unavailable) { status.value = 'stale'; return }
locatedPage.value = result.page || locatorPages(locate.value?.locators || [])[0] || 0
if (!result.found) status.value = 'missing'
if (result.reason === 'ambiguous') status.value = 'ambiguous'
else if (result.reason === 'partial' && result.found) status.value = 'partial'
else if (result.reason) status.value = 'missing'
else if (!result.found) status.value = 'missing'
else if (result.granularity === 'block') status.value = 'block'
else if (!result.precise && locatedPage.value) status.value = 'page'
else status.value = 'found'
}

View File

@ -9,6 +9,18 @@
role="complementary"
:aria-label="panelTitle"
>
<PanelResizeHandle
v-if="maxPanelWidth > minPanelWidth"
:key="sourceTarget ? 'source' : 'list'"
edge="left"
:label="t('knowledgeStages.resizeDrawer')"
:value="panelWidth"
:min="minPanelWidth"
:max="maxPanelWidth"
@start="resizeStartWidth = panelWidth"
@resize="resizePanel"
@end="savePanelWidths"
/>
<header class="chat-references-panel__header">
<div class="chat-references-panel__heading">
<button
@ -172,6 +184,7 @@ import { useRouter } from 'vue-router'
import { REFERENCES_PANEL_WIDTH, useChatReferencesDrawer } from '@/composables/useChatReferencesDrawer'
import ArtifactFileIcon from '@/views/chat/components/ArtifactFileIcon.vue'
import ChatReferenceSourceView from '@/components/ChatReferenceSourceView.vue'
import PanelResizeHandle from '@/components/PanelResizeHandle.vue'
import {
buildReferenceSections,
formatReferenceSnippet,
@ -207,14 +220,18 @@ const onViewportResize = () => {
onMounted(() => window.addEventListener('resize', onViewportResize))
onBeforeUnmount(() => window.removeEventListener('resize', onViewportResize))
// Reading an original document needs more room than the source list.
const panelWidth = computed(() => {
if (!sourceTarget.value) return REFERENCES_PANEL_WIDTH
return Math.max(480, Math.min(780, Math.round(viewportWidth.value * 0.46)))
})
watchEffect(() => {
if (drawer) drawer.panelWidth.value = panelWidth.value
const WIDTH_STORAGE_KEY = 'weknora.references-panel-widths'
const preferredWidths = reactive<{ source?: number; list?: number }>({})
let resizeStartWidth = 0
onMounted(() => {
try {
const stored = JSON.parse(localStorage.getItem(WIDTH_STORAGE_KEY) || '{}')
for (const key of ['source', 'list'] as const) {
if (typeof stored?.[key] === 'number' && Number.isFinite(stored[key]) && stored[key] > 0) {
preferredWidths[key] = stored[key]
}
}
} catch { /* Storage can be unavailable in embedded/private contexts. */ }
})
const useOverlay = computed(() => {
@ -222,10 +239,32 @@ const useOverlay = computed(() => {
return viewportWidth.value < (props.overlayBreakpoint ?? 960)
})
const panelStyle = computed(() => {
if (!sourceTarget.value) return undefined
return { width: useOverlay.value ? 'min(760px, 100vw)' : `${panelWidth.value}px` }
const maxPanelWidth = computed(() => useOverlay.value
? viewportWidth.value
: Math.min(1400, Math.max(360, viewportWidth.value - 560)))
const minPanelWidth = computed(() => Math.min(sourceTarget.value ? 360 : 320, maxPanelWidth.value))
const clampPanelWidth = (width: number) => Math.max(minPanelWidth.value, Math.min(maxPanelWidth.value, width))
// Preserve independent preferences when switching between the list and original.
const panelWidth = computed(() => {
const preferred = sourceTarget.value ? preferredWidths.source : preferredWidths.list
const initial = sourceTarget.value
? (useOverlay.value ? 760 : Math.max(480, Math.min(780, Math.round(viewportWidth.value * 0.46))))
: REFERENCES_PANEL_WIDTH
return clampPanelWidth(preferred ?? initial)
})
const panelStyle = computed(() => ({ width: `${panelWidth.value}px` }))
watchEffect(() => {
if (drawer) drawer.panelWidth.value = panelWidth.value
})
function resizePanel(delta: number) {
preferredWidths[sourceTarget.value ? 'source' : 'list'] = clampPanelWidth(resizeStartWidth - delta)
}
function savePanelWidths() {
try { localStorage.setItem(WIDTH_STORAGE_KEY, JSON.stringify(preferredWidths)) } catch { /* Optional preference. */ }
}
function canOpenSource(item: ReferenceListItem) {
return !props.embeddedMode && item.kind === 'document' && !!item.knowledgeId && !!item.chunkId

View File

@ -1,5 +1,6 @@
// @ts-nocheck
<script setup lang="ts">
import { indexEmbeddedSourceImages } from '@/utils/sourceImage';
import { ref, shallowRef, watch, onMounted, onUnmounted, nextTick, defineAsyncComponent } from 'vue';
import { previewKnowledgeFile } from '@/api/knowledge-base/index';
import { previewTemporaryAttachment } from '@/api/chat/temporary-attachments';
@ -10,6 +11,7 @@ import 'katex/dist/katex.min.css';
import { useI18n } from 'vue-i18n';
import { sanitizeHTML, sanitizeMarkdownHTML } from '@/utils/security';
import { preparePptxPreview, isCompletePptxRender } from '@/utils/pptxPreview';
import { findMarkdownSourceRange } from '@/utils/markdownSourceLocate';
import { renderDocumentPreviewMarkdown } from '@/utils/documentPreviewMarkdown';
import { buildHtmlPreview } from '@/utils/htmlPreview';
import { openMermaidFullscreen } from '@/utils/mermaidViewer';
@ -27,12 +29,9 @@ import {
type FilePreviewKind,
} from '@/utils/filePreview';
import {
narrowTextLines,
ngramOverlap,
normalizeForMatch,
pickBestTexts,
findInText,
sourceQuoteText,
type SourceLocateRequest,
type SourceLocator,
} from '@/utils/sourceLocator';
import {
buildTextIndex,
@ -72,7 +71,7 @@ const props = defineProps<{
locate?: SourceLocateRequest | null;
}>();
export type SourceLocateResult = { found: boolean; precise: boolean };
export type SourceLocateResult = { found: boolean; precise: boolean; granularity?: string; reason?: string };
const emit = defineEmits<{
located: [result: SourceLocateResult];
@ -264,6 +263,7 @@ async function renderDocx(blob: Blob) {
trimXmlDeclaration: true,
useBase64URL: true,
});
if (docxContainer.value) await indexEmbeddedSourceImages(docxContainer.value);
}
}
@ -575,11 +575,7 @@ watch(
const NOT_FOUND: SourceLocateResult = { found: false, precise: false };
function locatorQuotes(request: SourceLocateRequest, locators: SourceLocator[] = request.locators): string[] {
return [...locators.map((l) => l.quote || '').filter(Boolean), ...request.quotes];
}
function findQuoteRange(root: Element | null | undefined, quotes: string[]): Range | null {
function findQuoteRange(root: Node | null | undefined, quotes: string[]): Range | null {
if (!root) return null;
const index = buildTextIndex(root);
for (const quote of quotes) {
@ -608,91 +604,95 @@ function locateQuote(root: Element | null | undefined, container: Element | null
return { found: true, precise: true };
}
/** The element among `blocks` near index `at` whose text best matches `quote`. */
function pickNearby(blocks: Element[], at: number, quote?: string): Element | null {
if (!blocks.length) return null;
const center = Math.max(0, Math.min(blocks.length - 1, at));
const needle = normalizeForMatch(quote || '').slice(0, 120);
if (needle.length < 4) return blocks[center];
let best = { el: blocks[center], score: -1 };
for (let i = Math.max(0, center - 4); i <= Math.min(blocks.length - 1, center + 4); i++) {
const score = ngramOverlap(needle, normalizeForMatch(blocks[i].textContent || ''));
if (score > best.score) best = { el: blocks[i], score };
}
return best.score >= 0.4 ? best.el : blocks[center];
}
/** The candidates that best match the cited sentence, or all of them when none aligns. */
function narrowToSentence(candidates: Element[], request: SourceLocateRequest): Element[] {
const picked = pickBestTexts(candidates.map((el) => el.textContent || ''), request.sentence || '');
return picked.length ? picked.map((i) => candidates[i]) : candidates;
}
function contentsRange(el: Element): Range {
const range = el.ownerDocument.createRange();
range.selectNodeContents(el);
return range;
/** Only exact evidence may narrow a structural source region. */
function evidenceQuotes(request: SourceLocateRequest): string[] {
return request.scope ? [request.scope] : request.quotes;
}
function locateDocx(request: SourceLocateRequest): SourceLocateResult {
const root = docxContainer.value;
if (!root) return NOT_FOUND;
const locators = request.locators.filter((l) => l.type === 'docx' && l.block);
if (locators.length) {
// Body paragraphs and tables in order, the unit the backend counts.
const blocks = Array.from(root.querySelectorAll('section > article')).flatMap((article) =>
Array.from(article.children).filter((c) => c.tagName === 'P' || c.tagName === 'TABLE'),
);
const targets: Element[] = [];
for (const loc of locators) {
const el = pickNearby(blocks, (loc.block as number) - 1, loc.quote);
if (el && !targets.includes(el)) targets.push(el);
}
if (targets.length) {
const range = findQuoteRange(targets[0], locatorQuotes(request, locators));
commitMarks(range ? [range] : [], targets);
reveal(root, range || targets[0]);
return { found: true, precise: true };
}
const blocks = Array.from(root.querySelectorAll('section > article')).flatMap((article) =>
Array.from(article.children).filter((c) => c.tagName === 'P' || c.tagName === 'TABLE'),
);
if (request.imageDigest) {
const images = [...root.querySelectorAll('img')].filter(image => image.dataset.sourceImageDigest === request.imageDigest);
if (images.length !== 1) return { ...NOT_FOUND, ...(images.length > 1 ? { reason: 'ambiguous' } : {}) };
commitMarks([], images); reveal(root, images[0]);
return { found: true, precise: false, granularity: 'block' };
}
return locateQuote(root, root, request.quotes);
if (request.imageContext) {
const { before: beforeQuote, after: afterQuote } = request.imageContext;
const before = beforeQuote ? findQuoteRange(root, [beforeQuote]) : null;
const after = afterQuote ? findQuoteRange(root, [afterQuote]) : null;
if ((beforeQuote && !before) || (afterQuote && !after) || (!before && !after)) return NOT_FOUND;
const from = before?.cloneRange() || document.createRange();
const to = after?.cloneRange() || document.createRange();
if (before) from.collapse(false);
else { from.selectNodeContents(root); from.collapse(true); }
if (after) to.collapse(true);
else { to.selectNodeContents(root); to.collapse(false); }
// A chunk can end immediately after its image. In that case bound the
// search by the next nonempty original paragraph, not the document end.
for (const block of blocks) {
if (!block.textContent?.trim()) continue;
const range = document.createRange(); range.selectNodeContents(block);
if (!after && range.compareBoundaryPoints(Range.START_TO_START, from) >= 0) { to.setStartBefore(block); to.collapse(true); break; }
if (!before && range.compareBoundaryPoints(Range.END_TO_END, to) <= 0) { from.setStartAfter(block); from.collapse(true); }
}
const images = [...root.querySelectorAll('img')].filter(image => {
const range = document.createRange(); range.selectNode(image);
return range.compareBoundaryPoints(Range.START_TO_START, from) >= 0 &&
range.compareBoundaryPoints(Range.END_TO_END, to) <= 0;
});
if (images.length !== 1) return NOT_FOUND;
commitMarks([], images); reveal(root, images[0]);
return { found: true, precise: false, granularity: 'block' };
}
const excerpt = request.quotes.length === 1 ? request.quotes[0] : '';
if (excerpt && request.scope && excerpt !== request.scope && findInText(request.scope, excerpt)) {
const range = findQuoteRange(root, [excerpt]);
if (range) { commitMarks([range], []); reveal(root, range); return { found: true, precise: true }; }
}
const ranges: Range[] = [];
let missed = false, partial = false, narrowed = false;
for (const loc of request.locators.filter((l) => l.type === 'docx' && l.mapping === 'exact' && l.block)) {
const el = blocks[(loc.block as number) - 1];
const quote = sourceQuoteText(loc.quote || '');
const sentence = request.sentence && findInText(quote, request.sentence) ? request.sentence : '';
// Pagination may split Word paragraphs. Revalidate the complete quote
// globally before accepting a shifted block, and reject duplicate matches.
const region = quote ? findQuoteRange(el, [quote]) || findQuoteRange(root, [quote]) : null;
if (!region) { missed = true; continue; }
const range = sentence ? findQuoteRange(region.commonAncestorContainer.nodeType === Node.TEXT_NODE ? region.commonAncestorContainer.parentElement : region.commonAncestorContainer, [sentence]) : region;
ranges.push(range || region);
narrowed ||= !!sentence && !!range;
partial ||= !!loc.partial;
}
if (!ranges.length) return locateQuote(root, root, evidenceQuotes(request));
const complete = !missed && (!partial || narrowed || !!findQuoteRange(root, evidenceQuotes(request)));
commitMarks(ranges, []);
reveal(root, ranges[0]);
return { found: true, precise: complete, ...(!complete ? { reason: 'partial' } : {}) };
}
function locatePptx(request: SourceLocateRequest): SourceLocateResult {
const box = previewContent.value;
if (!box) return NOT_FOUND;
const slides = Array.from(box.querySelectorAll('.pptx-preview-slide-wrapper'));
const locators = request.locators.filter((l) => l.type === 'slide' && l.slide);
if (locators.length) {
const slide = slides[(locators[0].slide as number) - 1];
if (slide) {
// Master and layout text repeats on every slide; match the slide's own.
const own = slide.querySelector('.slide-wrapper') || slide;
// A slide locator covers the whole slide; the cited bullet is narrower.
const paragraphs = Array.from(own.querySelectorAll('p')).filter((p) => (p.textContent || '').trim());
const cited = narrowToSentence(paragraphs, request);
if (paragraphs.length && cited.length < paragraphs.length) {
const ranges = cited.map(contentsRange);
commitMarks(ranges, []);
reveal(box, ranges[0]);
return { found: true, precise: true };
}
const range = findQuoteRange(own, locatorQuotes(request, locators));
commitMarks(range ? [range] : [], range ? [] : [slide]);
reveal(box, range || slide);
return { found: true, precise: !!range };
}
}
for (const slide of slides) {
const locators = request.locators.filter((l) => l.type === 'slide' && l.mapping === 'exact' && !l.partial && l.slide);
if (!locators.length) return locateQuote(box, box, evidenceQuotes(request));
const ranges: Range[] = [], regions: Element[] = [];
for (const loc of locators) {
const slide = slides[(loc.slide as number) - 1];
if (!slide) return NOT_FOUND;
const own = slide.querySelector('.slide-wrapper') || slide;
const range = findQuoteRange(own, request.quotes);
if (range) {
commitMarks([range], []);
reveal(box, range);
return { found: true, precise: true };
}
const range = loc.quote ? findQuoteRange(own, [loc.quote]) : null;
if (range) ranges.push(range); else regions.push(slide);
}
return NOT_FOUND;
commitMarks(ranges, regions);
reveal(box, ranges[0] || regions[0]);
return { found: true, precise: !regions.length, granularity: regions.length ? 'block' : 'text' };
}
/** Map sheet row numbers to table rows using the cell ids SheetJS emits. */
@ -709,11 +709,12 @@ function sheetRows(table: Element): Map<number, Element> {
function locateExcel(request: SourceLocateRequest): SourceLocateResult {
const box = previewContent.value;
if (!box) return NOT_FOUND;
const locators = request.locators.filter((l) => l.type === 'sheet' && l.row_start);
const locators = request.locators.filter((l) => l.type === 'sheet' && l.mapping === 'exact' && !l.partial && l.row_start);
const targets: Element[] = [];
for (const loc of locators) {
const byName = loc.sheet ? excelSheetNames.indexOf(loc.sheet) : -1;
const sheetIdx = byName >= 0 ? byName : 0;
if (byName < 0) continue;
const sheetIdx = byName;
const table = box.querySelector(`#user-content-sheet-${sheetIdx}`) || box.querySelector(`#sheet-${sheetIdx}`);
if (!table) continue;
const rows = sheetRows(table);
@ -724,104 +725,69 @@ function locateExcel(request: SourceLocateRequest): SourceLocateResult {
}
}
if (targets.length) {
// A chunk often spans many rows; keep the ones the sentence is about.
// Header rows repeat the column names every answer mentions.
const body = targets.filter((tr) => tr.parentElement?.firstElementChild !== tr);
const cited = body.length > 1 ? narrowToSentence(body, request) : targets;
const rows = cited.length < body.length ? cited : targets;
commitMarks([], rows);
reveal(box, rows[0]);
return { found: true, precise: true };
commitMarks([], targets);
reveal(box, targets[0]);
return { found: true, precise: false, granularity: 'block' };
}
return locateQuote(box, box, request.quotes);
return locateQuote(box, box, evidenceQuotes(request));
}
function locateEpub(request: SourceLocateRequest): SourceLocateResult {
const box = previewContent.value;
if (!box) return NOT_FOUND;
const locators = request.locators.filter((l) => l.type === 'section' && l.section);
const section = locators.length
? box.querySelector(`[data-epub-section="${locators[0].section}"]`)
: null;
if (section) {
// A section locator covers the whole chapter; the cited paragraph is narrower.
const paragraphs = Array.from(section.querySelectorAll('p, li, h1, h2, h3, h4, h5, h6')).filter(
(el) => (el.textContent || '').trim(),
);
const cited = narrowToSentence(paragraphs, request);
if (paragraphs.length && cited.length < paragraphs.length) {
const ranges = cited.map(contentsRange);
commitMarks(ranges, []);
reveal(box, ranges[0]);
return { found: true, precise: true };
}
const range = findQuoteRange(section, locatorQuotes(request, locators));
if (range) commitMarks([range], []);
reveal(box, range || section);
return { found: true, precise: !!range };
const locators = request.locators.filter((l) => l.type === 'section' && l.mapping === 'exact' && !l.partial && l.section);
if (!locators.length) return locateQuote(box, box, evidenceQuotes(request));
const ranges: Range[] = [], regions: Element[] = [];
for (const loc of locators) {
const section = box.querySelector(`[data-epub-section="${loc.section}"]`);
if (!section) return NOT_FOUND;
const range = loc.quote ? findQuoteRange(section, [loc.quote]) : null;
if (range) ranges.push(range); else regions.push(section);
}
return locateQuote(box, box, request.quotes);
commitMarks(ranges, regions);
reveal(box, ranges[0] || regions[0]);
return { found: true, precise: !regions.length, granularity: regions.length ? 'block' : 'text' };
}
function locateText(request: SourceLocateRequest): SourceLocateResult {
const box = previewContent.value;
const code = box?.querySelector('code') || box;
if (!box || !code) return NOT_FOUND;
// Offsets index the original file; pretty-printed JSON no longer matches it.
const locators = request.locators.filter((l) => l.type === 'text' && (l.end || 0) > (l.start || 0));
// Validate stored offsets against their full quote. A manual edit or a
// pretty-printed JSON document must not reuse offsets from another version.
const locators = request.locators.filter((l) => l.type === 'text' && !l.partial && (l.end || 0) > (l.start || 0));
if (locators.length && previewType.value === 'text' && !shouldPrettyPrintJson(previewExt)) {
const spans = locators.map((l): [number, number] => [l.start || 0, l.end || 0]);
// A chunk spans several paragraphs; keep the lines the sentence is about.
const cited = narrowTextLines(code.textContent || '', spans, request.sentence || '');
const ranges = (cited.length ? cited : spans)
.map(([start, end]) => rangeForOffsets(code, start, end))
.filter((r): r is Range => !!r && !r.collapsed);
if (ranges.length) {
commitMarks(ranges, []);
const ranges = locators.map((l) => rangeForOffsets(code, l.start || 0, l.end || 0));
if (ranges.every((r, i) => r && locators[i].quote && findInText(r.toString(), locators[i].quote!))) {
commitMarks(ranges as Range[], []);
reveal(box, ranges[0]);
return { found: true, precise: true };
}
}
return locateQuote(code, box, locatorQuotes(request));
return locateQuote(code, box, evidenceQuotes(request));
}
const MARKDOWN_BLOCKS = 'p, li, tr, h1, h2, h3, h4, h5, h6, pre, blockquote, dt, dd';
/**
* Rendered Markdown has no offsets back into the file, so the cited chunk's
* text bounds the candidate blocks and the sentence picks among them.
*/
function locateMarkdown(request: SourceLocateRequest): SourceLocateResult {
const box = previewContent.value;
if (!box) return NOT_FOUND;
const scope = normalizeForMatch(request.scope || '');
if (scope && request.sentence) {
const blocks = Array.from(box.querySelectorAll(MARKDOWN_BLOCKS)).filter((el) => {
if (el.querySelector(MARKDOWN_BLOCKS)) return false;
const text = normalizeForMatch(el.textContent || '');
return text.length >= 4 && scope.includes(text);
});
const cited = pickBestTexts(blocks.map((el) => el.textContent || ''), request.sentence);
if (cited.length) {
const ranges = cited.map((i) => contentsRange(blocks[i]));
commitMarks(ranges, []);
reveal(box, ranges[0]);
return { found: true, precise: true };
}
}
return locateQuote(box, box, locatorQuotes(request));
const markdown = request.sourceMarkdown ?? request.scope ?? request.quotes[0] ?? '';
const match = findMarkdownSourceRange(box, markdown, request.sentence);
if (!match) return NOT_FOUND;
commitMarks(match.ranges || [match.range], []);
reveal(box, match.range);
return { found: true, precise: match.exact, ...(!match.exact ? { granularity: 'block' } : {}) };
}
function locateImage(request: SourceLocateRequest): SourceLocateResult {
const boxes = request.locators
.filter((l) => l.type === 'pdf' && (l.page || 1) === 1 && l.bbox?.length === 4)
.filter((l) => l.type === 'pdf' && l.mapping === 'exact' && !l.partial && (l.page || 1) === 1 && l.bbox?.length === 4)
.map((l) => {
const [x0, y0, x1, y1] = l.bbox as number[];
return { left: x0, top: y0, width: x1 - x0, height: y1 - y0 };
});
imageMarks.value = boxes;
// Without regions the whole image is the cited source.
return { found: true, precise: boxes.length > 0 };
return { found: true, precise: false, granularity: 'block' };
}
function formatClock(ms: number): string {
@ -856,6 +822,7 @@ function applyLocate() {
clearLocateMarks();
// The pdf.js viewer locates on its own and reports through @located.
if (!request || previewType.value === 'pdf') return;
if (request.unavailable) { emit('located', { ...NOT_FOUND, reason: 'unavailable' }); return; }
let result = NOT_FOUND;
try {
switch (previewType.value) {

View File

@ -10,7 +10,7 @@ import {
summarizePostprocessTasks,
type KnowledgeTraceNode,
} from '@/utils/knowledgeTrace'
import { resolveTimelineHeaderStatus } from '@/utils/knowledgeProcessingStatus'
import { resolveTimelineHeaderStatus, shouldShowProcessingError } from '@/utils/knowledgeProcessingStatus'
import { shownStall, stalledMinutes, STALLED_POLL_INTERVAL_MS } from '@/utils/knowledgeProcessingStall'
import { axisGridStepPct, buildAxisTicks, computeTraceAxis } from '@/utils/traceAxis'
import type { KnowledgeProcessOverrides } from '@/types/knowledgeProcess'
@ -1237,7 +1237,7 @@ const headerStatusTheme = computed(() => {
})
const showLastError = computed(() =>
Boolean(data.value?.last_error && data.value?.parse_status === 'failed'),
shouldShowProcessingError(Boolean(data.value?.last_error), data.value?.parse_status, data.value?.trace?.status),
)
const failedStage = computed<SpanNode | null>(
@ -1695,7 +1695,7 @@ const processConfigLines = computed<string[]>(() => {
<div v-if="localizedErrorSuggestion(data.last_error.error_code)" class="kp-err-hint">
{{ localizedErrorSuggestion(data.last_error.error_code) }}
</div>
<div class="kp-err-actions">
<div v-if="data.parse_status === 'failed'" class="kp-err-actions">
<button type="button" class="kp-err-btn" @click="onRetry">
<t-icon name="refresh" size="14px" />
<span>{{ t('knowledgeStages.retry') }}</span>

View File

@ -1,9 +1,9 @@
<script setup lang="ts">
import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref, shallowRef, watch } from 'vue'
import { useI18n } from 'vue-i18n'
import type { SourceLocateRequest, SourceLocator } from '@/utils/sourceLocator'
import { findInText } from '@/utils/sourceLocator'
import { findTextRange } from '@/utils/sourceLocatorDom'
import type { SourceLocateRequest } from '@/utils/sourceLocator'
import { resolvePdfSource, mergeSourceRects, type PdfTarget } from '@/utils/pdfSourceLocate'
import { findTextRanges } from '@/utils/sourceLocatorDom'
import { loadPdfJs, type PdfJs } from './pdfjsLoader'
type PdfDocument = Awaited<ReturnType<PdfJs['getDocument']>['promise']>
@ -12,7 +12,7 @@ type PdfPage = Awaited<ReturnType<PdfDocument['getPage']>>
/** A highlight drawn on a page, in fractions of the page box. */
type Mark = { left: number; top: number; width: number; height: number; kind: 'box' | 'text' | 'page' }
export type PdfLocateResult = { found: boolean; precise: boolean; page?: number }
export type PdfLocateResult = { found: boolean; precise: boolean; page?: number; granularity?: string; reason?: string }
const props = defineProps<{
data: ArrayBuffer | null
@ -113,7 +113,9 @@ async function renderPage(pageNumber: number): Promise<void> {
const doc = pdf.value
const el = pageElements.get(pageNumber)
if (!doc || !el || !pdfjs) return
const page = await doc.getPage(pageNumber)
let page: PdfPage
try { page = await doc.getPage(pageNumber) } catch { return }
if (disposed || pdf.value !== doc) return
const scale = renderScale(page)
const existing = rendered.get(pageNumber)
if (existing && Math.abs(existing.scale - scale) < 0.01) {
@ -274,130 +276,92 @@ async function pageText(pageNumber: number): Promise<string> {
return text
}
/** Draw the match for one of `quotes` on `pageNumber`; returns the top fraction or null. */
async function markQuoteOnPage(pageNumber: number, quotes: string[], version: number): Promise<number | null> {
const text = await pageText(pageNumber)
const quote = quotes.find((q) => findInText(text, q))
if (!quote || version !== locateVersion) return null
/** Refine only within the recorded region, or at a verified text occurrence. */
async function markTarget(target: PdfTarget, version: number): Promise<number | null> {
const pageNumber = target.page
await renderPage(pageNumber)
// A concurrent render may have replaced the one awaited; wait for the live one.
await rendered.get(pageNumber)?.done
await nextTick()
if (version !== locateVersion) return null
const el = pageElements.get(pageNumber)
const layer = el?.querySelector('.textLayer')
if (!el || !layer) return null
const range = findTextRange(layer, quote)
if (!range) return null
if (!el || !layer || !target.quote) return null
const pageBox = el.getBoundingClientRect()
const lines = mergeLineRects([...range.getClientRects()])
let top: number | null = null
const ranges = findTextRanges(layer, target.quote)
const candidates = ranges.map((range) => mergeSourceRects([...range.getClientRects()]))
const inside = (rects: ReturnType<typeof mergeSourceRects>) => {
if (!rects.length) return false
if (!target.bbox) return true
const [x0, y0, x1, y1] = target.bbox
return rects.every((r) => {
const x = (r.left + r.width / 2 - pageBox.left) / pageBox.width
const y = (r.top + r.height / 2 - pageBox.top) / pageBox.height
return x >= x0 && x <= x1 && y >= y0 && y <= y1
})
}
const eligible = target.bbox ? candidates.filter(inside) : candidates
const lines = target.bbox ? (eligible.length === 1 ? eligible[0] : undefined)
: (target.occurrence !== undefined && target.occurrence >= 0 ? eligible[target.occurrence] : eligible.length === 1 ? eligible[0] : undefined)
if (!lines?.length) return null
let top = 1
for (const r of lines) {
const mark: Mark = {
kind: 'text',
left: (r.left - pageBox.left) / pageBox.width,
top: (r.top - pageBox.top) / pageBox.height,
width: r.width / pageBox.width,
height: r.height / pageBox.height,
}
if (mark.width <= 0 || mark.height <= 0) continue
const mark: Mark = { kind: 'text', left: (r.left - pageBox.left) / pageBox.width,
top: (r.top - pageBox.top) / pageBox.height, width: r.width / pageBox.width, height: r.height / pageBox.height }
addMark(pageNumber, mark)
top = top === null ? mark.top : Math.min(top, mark.top)
top = Math.min(top, mark.top)
}
return top
}
/** Merge the per-glyph-run rects of a range into one rect per visual line. */
function mergeLineRects(rects: DOMRect[]): Array<{ left: number; top: number; width: number; height: number }> {
const lines: Array<{ left: number; top: number; right: number; bottom: number }> = []
for (const r of rects) {
if (r.width < 0.5 || r.height < 0.5) continue
const line = lines.find((l) => Math.min(l.bottom, r.bottom) - Math.max(l.top, r.top) > Math.min(r.height, l.bottom - l.top) * 0.5)
if (line) {
line.left = Math.min(line.left, r.left)
line.right = Math.max(line.right, r.right)
line.top = Math.min(line.top, r.top)
line.bottom = Math.max(line.bottom, r.bottom)
} else {
lines.push({ left: r.left, top: r.top, right: r.right, bottom: r.bottom })
}
}
return lines.map((l) => ({ left: l.left - 2, top: l.top - 1, width: l.right - l.left + 4, height: l.bottom - l.top + 2 }))
}
async function applyLocate(request: SourceLocateRequest | null | undefined) {
const version = ++locateVersion
clearMarks()
locatedTargets.value = []
if (!request || !pdf.value) return
const total = pageCount.value
const pdfLocators = request.locators.filter((l): l is SourceLocator & { page: number } =>
l.type === 'pdf' && !!l.page && l.page >= 1 && l.page <= total)
let firstPage = 0
let firstTop = 0
let precise = false
const note = (page: number, top: number) => {
if (!firstPage) {
firstPage = page
firstTop = top
}
}
// Regions reported by the parser are drawn as they are.
for (const loc of pdfLocators) {
if (loc.bbox && loc.bbox.length === 4) {
const [x0, y0, x1, y1] = loc.bbox
addMark(loc.page, { kind: 'box', left: x0, top: y0, width: x1 - x0, height: y1 - y0 })
note(loc.page, y0)
precise = true
}
}
// Pages without a region: find the quoted text on the page.
if (!precise) {
const pages = [...new Set(pdfLocators.map((l) => l.page))]
for (const page of pages) {
const quotes = [
...pdfLocators.filter((l) => l.page === page && l.quote).map((l) => l.quote as string),
...request.quotes,
]
const top = quotes.length ? await markQuoteOnPage(page, quotes, version) : null
try {
const result = await resolvePdfSource(request, pageCount.value, pageText, () => version !== locateVersion)
if (version !== locateVersion) return
const destinations: Array<{ page: number; top: number }> = []
const levels: string[] = []
for (const target of result.targets) {
let top = await markTarget(target, version)
if (version !== locateVersion) return
if (top !== null) {
note(page, top)
precise = true
} else {
// Scanned pages have no text: outline the page itself.
addMark(page, { kind: 'page', left: 0, top: 0, width: 1, height: 1 })
note(page, 0)
if (top !== null) levels.push('text')
else if (target.bbox) {
const [x0, y0, x1, y1] = target.bbox
addMark(target.page, { kind: 'box', left: x0, top: y0, width: x1 - x0, height: y1 - y0 })
top = y0
levels.push('block')
} else if (target.granularity === 'page') {
top = 0
levels.push('page')
addMark(target.page, { kind: 'page', left: 0, top: 0, width: 1, height: 1 })
}
if (top !== null) destinations.push({ page: target.page, top })
}
await nextTick()
if (version !== locateVersion) return
locatedTargets.value = destinations
selectedTarget.value = 0
if (destinations.length) jumpToTarget(0)
const granularity = levels.includes('page') ? 'page' : levels.includes('block') ? 'block' : 'text'
emit('located', { found: destinations.length > 0, precise: destinations.length === result.targets.length && levels.every((l) => l === 'text') && !result.reason,
page: destinations[0]?.page, granularity, reason: result.reason || (destinations.length < result.targets.length ? 'missing' : undefined) })
} catch {
if (version !== locateVersion) return
clearMarks()
emit('located', { found: false, precise: false, reason: 'unavailable' })
}
}
// No page at all: search the document for the quote.
if (!firstPage && request.quotes.length) {
const limit = Math.min(total, 500)
for (let page = 1; page <= limit; page++) {
const text = await pageText(page)
if (version !== locateVersion) return
if (request.quotes.some((q) => findInText(text, q))) {
const top = await markQuoteOnPage(page, request.quotes, version)
if (version !== locateVersion) return
if (top !== null) {
note(page, top)
precise = true
}
break
}
}
}
await nextTick()
if (version !== locateVersion) return
if (firstPage) {
scrollToPageFraction(firstPage, firstTop)
currentPage.value = firstPage
}
emit('located', { found: !!firstPage, precise, page: firstPage || undefined })
const locatedTargets = ref<Array<{ page: number; top: number }>>([])
const selectedTarget = ref(0)
function jumpToTarget(index: number) {
const target = locatedTargets.value[index]
if (!target) return
selectedTarget.value = index
scrollToPageFraction(target.page, target.top)
currentPage.value = target.page
}
watch(
@ -420,6 +384,7 @@ async function load() {
console.error('PDF preview failed:', err)
error.value = t('preview.loadFailed')
emit('error', error.value)
emit('located', { found: false, precise: false, reason: 'unavailable' })
} finally {
loading.value = false
}
@ -446,7 +411,7 @@ onBeforeUnmount(() => {
resizeObserver?.disconnect()
for (const p of [...rendered.keys()]) unrenderPage(p)
// Destroying the loading task also destroys the document and its worker.
void loadingTask?.destroy()
void loadingTask?.destroy().catch(() => {})
})
const pageLabel = computed(() => (pageCount.value ? `${currentPage.value} / ${pageCount.value}` : ''))
@ -492,6 +457,11 @@ defineExpose({ relocate: () => applyLocate(props.locate) })
</div>
</div>
<div v-if="pageCount" class="pdf-source-viewer__bar">
<template v-if="locatedTargets.length > 1">
<t-button variant="text" size="small" :disabled="selectedTarget === 0" :aria-label="t('chat.referenceSourcePrevious')" @click="jumpToTarget(selectedTarget - 1)">‹</t-button>
<span>{{ selectedTarget + 1 }} / {{ locatedTargets.length }}</span>
<t-button variant="text" size="small" :disabled="selectedTarget === locatedTargets.length - 1" :aria-label="t('chat.referenceSourceNext')" @click="jumpToTarget(selectedTarget + 1)">›</t-button>
</template>
<span class="pdf-source-viewer__page">{{ pageLabel }}</span>
<t-button
theme="default" variant="text" size="small" shape="square"

View File

@ -1,19 +1,19 @@
// Bundled as a worker chunk with a .js name, so any static server hands it
// out with a JavaScript MIME type (module workers refuse anything else).
import PdfWorker from 'pdfjs-dist/legacy/build/pdf.worker.min.mjs?worker'
import pdfWorkerUrl from 'pdfjs-dist/legacy/build/pdf.worker.min.mjs?worker&url'
export type PdfJs = typeof import('pdfjs-dist/legacy/build/pdf.mjs')
let loading: Promise<PdfJs> | null = null
/**
* Load pdf.js once per page. Every document shares one worker: pdf.js keeps
* a caller-provided port alive when a document is destroyed.
* Load the library once, but let each document own its worker. Reusing a port
* while the previous loading task is being destroyed can break rapid navigation.
*/
export function loadPdfJs(): Promise<PdfJs> {
if (!loading) {
loading = import('pdfjs-dist/legacy/build/pdf.mjs').then((lib) => {
lib.GlobalWorkerOptions.workerPort = new PdfWorker()
lib.GlobalWorkerOptions.workerSrc = pdfWorkerUrl
return lib
})
loading.catch(() => {

View File

@ -5,6 +5,7 @@ import {
setCitationChunkCache,
} from '@/utils/citationChunkCache'
import { useChatReferencesDrawer } from '@/composables/useChatReferencesDrawer'
import type { ReferenceHighlightTarget } from '@/utils/referenceSources'
import { citationAnchorText } from '@/utils/citationAnchor'
export type CitationFloatState = {
@ -171,7 +172,7 @@ export function useCitationPopover(rootRef: Ref<HTMLElement | null>, options: Ci
scheduleClose()
}
const openDrawerForCitation = (payload: { url?: string; chunkId?: string; anchorText?: string; openSource?: boolean }) => {
const openDrawerForCitation = (payload: ReferenceHighlightTarget) => {
const refs = options?.getKnowledgeReferences?.() || []
if (!referencesDrawer || !refs.length) return false
referencesDrawer.open({
@ -200,7 +201,8 @@ export function useCitationPopover(rootRef: Ref<HTMLElement | null>, options: Ci
const chunkId = resolveChunkId(kbEl)
// Chat opens the cited document at the cited passage; the embed has no
// access to original files and keeps the reference list.
const source = isChat ? { anchorText: citationAnchorText(kbEl), openSource: true } : {}
const source = isChat ? { anchorText: citationAnchorText(kbEl), openSource: true,
documentTitle: kbEl.getAttribute('data-doc') || '', knowledgeBaseId: kbEl.getAttribute('data-kb-id') || '' } : {}
if (openDrawerForCitation({ chunkId, ...source })) return
void openKb(kbEl)
return

View File

@ -1168,6 +1168,12 @@ export default {
cancelled: 'Cancelled'
},
errorCode: {
DOCREADER_UNAVAILABLE: "Document parsing service unavailable",
DOCREADER_UNAVAILABLE_SUGGESTION: "Cannot connect to DocReader, or the connection was interrupted. Check service health, restart loops, and network access. Retry after recovery; uploading the file again is unnecessary.",
DOCREADER_TIMEOUT: "Document parsing timed out",
DOCREADER_TIMEOUT_SUGGESTION: "Check DocReader health and load before retrying. Split large files if needed.",
DOCREADER_PARSE_FAILED: "Document parsing failed",
DOCREADER_PARSE_FAILED_SUGGESTION: "Check the file format and ask an administrator to inspect the DocReader logs for this attempt.",
TASK_STALLED: 'Stopped after no progress',
TASK_STALLED_SUGGESTION: 'Processing made no progress past the time limit and had no task left in the queue, so it was marked as failed. Click Retry; if this keeps happening, check the service this stage depends on (document parsing, model, or vector store).',
UNKNOWN_SUGGESTION: 'Check the application logs for details.'
@ -4075,6 +4081,13 @@ export default {
referenceSourceView: 'View in original',
referenceSourceRelocate: 'Locate again',
referenceSourceLocating: 'Locating the cited passage…',
referenceSourceExact: "Located the source passage",
referenceSourcePartial: "Verified source passages highlighted; part of the citation remains unmatched",
referenceSourceBlock: "Located the source region; exact text not confirmed",
referenceSourceAmbiguous: "Multiple matching passages; the location is ambiguous",
referenceSourceStale: "The source or content changed; this citation cannot be located precisely",
referenceSourcePrevious: "Previous citation location",
referenceSourceNext: "Next citation location",
referenceSourceFoundPage: 'Found on page {page}',
referenceSourceNotFound: 'Could not pinpoint the cited passage; the original is open',
referenceSourceOpenWeb: 'Open the web page at this passage',

View File

@ -1168,6 +1168,12 @@ export default {
cancelled: 'キャンセル済み'
},
errorCode: {
DOCREADER_UNAVAILABLE: "文書解析サービスを利用できません",
DOCREADER_UNAVAILABLE_SUGGESTION: "DocReader に接続できないか、接続が切断されました。サービスの稼働状態、再起動の繰り返し、ネットワークを確認し、復旧後に再試行してください。再アップロードは不要です。",
DOCREADER_TIMEOUT: "文書解析がタイムアウトしました",
DOCREADER_TIMEOUT_SUGGESTION: "DocReader の稼働状態と負荷を確認してから再試行してください。必要に応じて大きなファイルを分割してください。",
DOCREADER_PARSE_FAILED: "文書解析に失敗しました",
DOCREADER_PARSE_FAILED_SUGGESTION: "ファイル形式を確認し、管理者に今回の DocReader ログの確認を依頼してください。",
TASK_STALLED: '進捗がないため自動停止しました',
TASK_STALLED_SUGGESTION: 'しきい値を超えても進捗がなく、キューにも対応するタスクがないため失敗としてマークされました。「再試行」を押してください。繰り返し発生する場合は、この段階が依存するサービス(文書解析、モデル、ベクトルストア)を確認してください。',
UNKNOWN_SUGGESTION: '詳細はアプリケーションログを確認してください。'
@ -4075,6 +4081,13 @@ export default {
referenceSourceView: '原文を表示',
referenceSourceRelocate: '再度位置を特定',
referenceSourceLocating: '引用箇所を特定しています…',
referenceSourceExact: "原文の該当箇所を特定しました",
referenceSourcePartial: "確認できた原文を強調表示しています。引用の一部は未照合です",
referenceSourceBlock: "原文の領域を表示しています。文字の完全一致は未確認です",
referenceSourceAmbiguous: "一致する箇所が複数あり、特定できません",
referenceSourceStale: "原文または内容が更新され、引用箇所を特定できません",
referenceSourcePrevious: "前の引用箇所",
referenceSourceNext: "次の引用箇所",
referenceSourceFoundPage: '{page} ページで見つかりました',
referenceSourceNotFound: '引用箇所を特定できなかったため、原文を開きました',
referenceSourceOpenWeb: '元の Web ページで該当箇所を開く',

View File

@ -3963,6 +3963,13 @@ export default {
referenceSourceView: '원문 보기',
referenceSourceRelocate: '다시 찾기',
referenceSourceLocating: '인용 위치를 찾는 중…',
referenceSourceExact: "원문 구절을 정확히 찾았습니다",
referenceSourcePartial: "확인된 원문을 강조했습니다. 인용 일부는 아직 일치하지 않습니다",
referenceSourceBlock: "원문 영역을 찾았습니다. 정확한 텍스트 일치는 확인되지 않았습니다",
referenceSourceAmbiguous: "일치하는 구절이 여러 개여서 위치를 특정할 수 없습니다",
referenceSourceStale: "원문 또는 내용이 변경되어 정확히 찾을 수 없습니다",
referenceSourcePrevious: "이전 인용 위치",
referenceSourceNext: "다음 인용 위치",
referenceSourceFoundPage: '{page}페이지에서 찾았습니다',
referenceSourceNotFound: '인용 위치를 정확히 찾지 못해 원문을 열었습니다',
referenceSourceOpenWeb: '원본 웹페이지에서 해당 위치 열기',
@ -6892,6 +6899,12 @@ export default {
noActivity: '파싱 활동 없음',
totalDuration: '총 소요시간: {d}',
errorCode: {
DOCREADER_UNAVAILABLE: "문서 분석 서비스를 사용할 수 없습니다",
DOCREADER_UNAVAILABLE_SUGGESTION: "DocReader에 연결할 수 없거나 연결이 끊겼습니다. 서비스 상태, 반복 재시작, 네트워크를 확인한 후 다시 시도하세요. 파일을 다시 업로드할 필요는 없습니다.",
DOCREADER_TIMEOUT: "문서 분석 시간 초과",
DOCREADER_TIMEOUT_SUGGESTION: "DocReader 상태와 부하를 확인한 후 다시 시도하세요. 필요한 경우 큰 파일을 나누세요.",
DOCREADER_PARSE_FAILED: "문서 분석 실패",
DOCREADER_PARSE_FAILED_SUGGESTION: "파일 형식을 확인하고 관리자에게 이번 DocReader 로그 확인을 요청하세요.",
TASK_STALLED: '진행이 없어 자동 중단됨',
TASK_STALLED_SUGGESTION: '임계 시간을 넘도록 진행이 없고 대기열에도 해당 작업이 없어 실패로 표시되었습니다. 「다시 시도」를 누르세요. 반복되면 이 단계가 의존하는 서비스(문서 파싱, 모델, 벡터 저장소)를 확인하세요.',
UNKNOWN_SUGGESTION: '자세한 내용은 애플리케이션 로그를 확인하세요.'

View File

@ -3963,6 +3963,13 @@ export default {
referenceSourceView: 'Открыть оригинал',
referenceSourceRelocate: 'Найти снова',
referenceSourceLocating: 'Поиск цитируемого фрагмента…',
referenceSourceExact: "Фрагмент источника найден",
referenceSourcePartial: "Проверенные фрагменты выделены; часть цитаты не сопоставлена",
referenceSourceBlock: "Найдена область источника; точное совпадение текста не подтверждено",
referenceSourceAmbiguous: "Найдено несколько совпадений; точное место неизвестно",
referenceSourceStale: "Источник или содержимое изменены; точное место цитаты недоступно",
referenceSourcePrevious: "Предыдущее место цитирования",
referenceSourceNext: "Следующее место цитирования",
referenceSourceFoundPage: 'Найдено на странице {page}',
referenceSourceNotFound: 'Не удалось точно найти фрагмент; открыт оригинал',
referenceSourceOpenWeb: 'Открыть веб-страницу на этом фрагменте',
@ -6892,6 +6899,12 @@ export default {
noActivity: 'Нет активности парсинга',
totalDuration: 'Всего: {d}',
errorCode: {
DOCREADER_UNAVAILABLE: "Сервис обработки документов недоступен",
DOCREADER_UNAVAILABLE_SUGGESTION: "Не удалось подключиться к DocReader или соединение прервано. Проверьте состояние сервиса, повторные перезапуски и сеть. Повторите попытку после восстановления; загружать файл заново не нужно.",
DOCREADER_TIMEOUT: "Превышено время обработки документа",
DOCREADER_TIMEOUT_SUGGESTION: "Проверьте состояние и нагрузку DocReader перед повторной попыткой. При необходимости разделите большой файл.",
DOCREADER_PARSE_FAILED: "Ошибка обработки документа",
DOCREADER_PARSE_FAILED_SUGGESTION: "Проверьте формат файла и попросите администратора изучить журналы DocReader для этой попытки.",
TASK_STALLED: 'Остановлено из-за отсутствия прогресса',
TASK_STALLED_SUGGESTION: 'Обработка не продвигалась дольше порога, и в очереди не осталось задач, поэтому она помечена как ошибочная. Нажмите «Повторить»; если это повторяется, проверьте сервис, от которого зависит этап (разбор документов, модель или векторное хранилище).',
UNKNOWN_SUGGESTION: 'Проверьте логи приложения для подробностей.'

View File

@ -3965,6 +3965,13 @@ export default {
referenceSourceView: '查看原文',
referenceSourceRelocate: '重新定位',
referenceSourceLocating: '正在定位引用位置…',
referenceSourceExact: "已精确定位原文片段",
referenceSourcePartial: "已高亮核验通过的原文片段,部分引用内容尚未匹配",
referenceSourceBlock: "已定位到来源区域,尚未精确匹配文字",
referenceSourceAmbiguous: "原文有多处相同内容,无法唯一定位",
referenceSourceStale: "原文或内容已更新,当前引用无法精确定位",
referenceSourcePrevious: "上一处引用",
referenceSourceNext: "下一处引用",
referenceSourceFoundPage: '已定位到第 {page} 页',
referenceSourceNotFound: '未能精确定位引用内容,已为你打开原文',
referenceSourceOpenWeb: '打开原网页并定位',
@ -6894,6 +6901,12 @@ export default {
noActivity: '暂无解析记录',
totalDuration: '总耗时:{d}',
errorCode: {
DOCREADER_UNAVAILABLE: "文档解析服务不可用",
DOCREADER_UNAVAILABLE_SUGGESTION: "无法连接 DocReader,或连接已中断。请检查解析服务是否启动、是否反复重启以及网络是否正常;服务恢复后再重试,无需重复上传文件。",
DOCREADER_TIMEOUT: "文档解析超时",
DOCREADER_TIMEOUT_SUGGESTION: "请检查 DocReader 的健康状态和负载;服务正常后再重试,必要时拆分大文件。",
DOCREADER_PARSE_FAILED: "文档解析失败",
DOCREADER_PARSE_FAILED_SUGGESTION: "请检查文件格式,并让管理员查看本次解析对应的 DocReader 日志。",
TASK_STALLED: '长时间无进展,已自动终止',
TASK_STALLED_SUGGESTION: '处理超过阈值仍没有任何进展,且队列中已无对应任务,已被系统标记为失败。请点击「重试」;如反复出现,请检查该阶段依赖的服务(文档解析、模型、向量库)是否正常。',
UNKNOWN_SUGGESTION: '请查看应用日志获取详细信息。'

View File

@ -1,7 +1,7 @@
/**
* The answer sentence a citation marker supports: the text of the marker's
* The answer passage a citation marker supports: the text of the marker's
* block (paragraph, list item, table cell) up to the marker, without other
* citation markers, trimmed to its last sentence. A marker on a line of its
* citation markers, starting after the preceding marker. A marker on a line of its
* own ("依据:[1]") borrows the blocks just before it.
*/
@ -73,10 +73,23 @@ export function citationAnchorText(marker: Element): string {
if (!block) return ''
const range = marker.ownerDocument.createRange()
range.setStart(block, 0)
// A citation covers the preceding passage since the previous citation,
// which can contain multiple sentences within the same paragraph.
range.setEndBefore(marker)
const preceding = [...block.querySelectorAll(CITATION_SELECTOR)]
.filter(previous => previous.compareDocumentPosition(marker) & Node.DOCUMENT_POSITION_FOLLOWING)
for (const previous of preceding.reverse()) {
const candidate = range.cloneRange()
candidate.setStartAfter(previous)
// Adjacent citations support the same passage; skip citation-only gaps.
if (letterCount(textWithoutCitations(candidate.cloneContents())) > 0) {
range.setStartAfter(previous)
break
}
}
const own = textWithoutCitations(range.cloneContents())
const enough = letterCount(lastSentence(own)) >= MIN_SENTENCE
return anchorWithContext(own, enough ? [] : previousBlockTexts(block))
return enough ? own.replace(/\s+/g, ' ').trim().slice(-300) : anchorWithContext(own, previousBlockTexts(block))
} catch {
// Alignment only narrows the highlight; without a sentence the whole chunk is shown.
return ''

View File

@ -47,7 +47,8 @@ function parseTagAttributes(attrString: string): Record<string, string> {
ATTRIBUTE_REGEX.lastIndex = 0
let match: RegExpExecArray | null
while ((match = ATTRIBUTE_REGEX.exec(attrString)) !== null) {
attributes[match[1]] = match[2]
attributes[match[1]] = match[2].replace(/&(amp|quot|apos|lt|gt|#39|#34);/g, (_, entity: string) =>
({ amp: '&', quot: '"', apos: "'", lt: '<', gt: '>', '#39': "'", '#34': '"' })[entity] || _)
}
return attributes
}

View File

@ -0,0 +1,77 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import { findSourceFragments } from './fragmentedSource'
import { resolvePdfSource } from './pdfSourceLocate'
import { sourceImageContext, sourceQuoteText } from './sourceLocator'
import { mergeDocumentReferences, resolveReferenceSource } from './referenceSources'
import { preprocessCitationTags } from './citationMarkdown'
test('Agent grouping retains every cited chunk identity and resolves the exact document', () => {
const refs = mergeDocumentReferences([
{ id: 'first', knowledge_id: 'doc', knowledge_title: '微信&企微.docx', content: 'first evidence' },
{ id: 'second', knowledge_id: 'doc', knowledge_title: '微信&企微.docx', content: 'second evidence' },
])
assert.deepEqual(refs[0]?.chunk_ids, ['first', 'second'])
const source = resolveReferenceSource(refs, { chunkId: 'second', openSource: true })
assert.equal(source?.knowledgeId, 'doc')
assert.equal(source?.chunkId, 'second')
assert.equal(source?.content, undefined, 'grouped content must be fetched for the cited chunk')
})
test('encoded citation titles are decoded once before HTML escaping', () => {
const html = preprocessCitationTags('<kb doc="微信&amp;企微.docx" id="kb" chunk_id="chunk"/>')
assert.ok(!html.includes('&amp;amp;'))
assert.ok(html.includes('微信&amp;企微.docx'))
})
test('column-serialized table identifies a row-serialized page by independent cells', async () => {
const pages = ['机器人研究社(周四) 张老师 教室A\n天文观测社(周四) 李老师 教室B', '机器人研究社(周四) 张老师 操场']
const scope = '|课程|老师|地点|\n|机器人研究社(周四) 天文观测社(周四)|张老师 李老师|教室A 教室B|'
const result = await resolvePdfSource({ token: 1, quotes: [], locators: [], scope, sentence: '天文观测社每周四开课。' }, pages.length, async p => pages[p - 1]!)
assert.equal(result.reason, 'partial')
assert.equal(result.targets[0]?.page, 1)
assert.ok(result.targets[0]?.quote?.includes('天文观测社'))
assert.ok(result.targets.every(t => t.page === 1))
})
test('a conjunction of repeated cells must identify a unique page', () => {
const scope = '|机器人研究社(周四) 天文观测社(周四)|'
const pages = ['机器人研究社(周四) 张老师 天文观测社(周四) 李老师', '机器人研究社(周四)', '天文观测社(周四)']
assert.equal(findSourceFragments(pages, scope).length, 2)
assert.deepEqual(findSourceFragments([pages[0]!, pages[0]!], scope), [])
})
test('fragment recovery cannot claim a missing numeric value or a coincidental opening', () => {
assert.deepEqual(findSourceFragments(['Shared opening. Different conclusion.'], 'Shared opening. Missing conclusion.'), [])
assert.deepEqual(findSourceFragments(['甲项目温度15度\n乙项目限值20毫米'], '|甲项目温度1.5度|乙项目限值2.0毫米|'), [])
})
test('parser artifacts retain only verified sentences and explicitly report partial coverage', async () => {
const scope = '绑定手机:点击账号à选择个人中心。\n\n学生选课开始时间为周一上午十一点。小学部高年级选课在周一下午一点开始。'
const pages = ['绑定手机:点击账号→选择个人中心。学生选课开始时间为周一上午十一点。小学部高年级选课在周一下午一点开始。']
const result = await resolvePdfSource({ token: 1, quotes: [], locators: [], scope }, 1, async () => pages[0]!)
assert.equal(result.reason, 'partial')
assert.equal(result.targets.length, 3)
assert.ok(result.targets.every(t => !t.quote?.includes('à')))
assert.ok(result.targets.some(t => t.quote === '绑定手机:点击账号'))
})
test('OCR image context requires exact resource identity and at least one neighboring paragraph', () => {
const md = '前一段明确来源。\n\n![descript](resource://image)\n\n后一段明确来源。'
assert.deepEqual(sourceImageContext(md, ['resource://image']), { before: '前一段明确来源。', after: '后一段明确来源。' })
assert.equal(sourceImageContext(md, ['resource://another-image']), undefined)
assert.deepEqual(sourceImageContext(md.replace('后一段明确来源。', ''), ['resource://image']), { before: '前一段明确来源。', after: '' })
assert.equal(sourceImageContext(md + '\n\n' + md, ['resource://image']), undefined)
assert.equal(sourceQuoteText(md).includes('descript'), false)
})
test('title fallback rejects duplicate document titles even within one knowledge base', () => {
const refs = ['doc-one', 'doc-two'].map(knowledge_id => ({ id: knowledge_id, knowledge_id, knowledge_title: 'Same.docx', knowledge_base_id: 'kb' }))
assert.equal(resolveReferenceSource(refs, { chunkId: 'missing-chunk', documentTitle: 'Same.docx', knowledgeBaseId: 'kb' }), null)
})
test('decoding a citation attribute never turns encoded markup into active HTML', () => {
const html = preprocessCitationTags('<kb doc="&lt;img src=x onerror=alert(1)&gt;.docx" chunk_id="chunk"/>')
assert.ok(html.includes('data-doc="&lt;img'))
assert.ok(!html.includes('<img'))
})

View File

@ -0,0 +1,74 @@
import { findTextMatches, normalizeForMatch, type TextMatch } from './sourceLocator'
/** Exact fragments for parsers that serialize table columns in a different order.
* Every returned range is independently checked. Callers must report partial
* coverage; unmatched text is never included in a highlight.
*/
export function findSourceFragments(pages: string[], scope: string): Array<TextMatch & { page: number; quote: string }> {
const table = scope.includes('|')
const parts = table ? scope.split(/[|\n]/u) : scope.split(/(?<=[。!?;!?;])|\n+|(?<=[\p{Script=Han}】)])\s*[à→\uE000-\uF8FF]\s*/u)
const candidates = new Set<string>()
for (const part of parts) {
const clean = part.trim()
if (!clean || /^[-: ]+$/.test(clean)) continue
if (!table) { candidates.add(clean); continue }
// Preserve whole cells first. Flattened cells may hold a list of courses;
// use complete whitespace-delimited entries, never arbitrary n-grams.
candidates.add(clean)
const words = clean.split(/\s+/u)
if (words.length > 1) for (const word of words) candidates.add(word)
}
const evidence = [...candidates].filter(q => normalizeForMatch(q).length >= (table ? 5 : 8))
.map(quote => ({ quote, hits: pages.flatMap((text, i) => findTextMatches(text, quote).map(hit => ({ ...hit, page: i + 1 }))) }))
const unique = evidence.filter(e => e.hits.length === 1)
// Require independent anchors. A shared opening alone is not a location.
const anchors = unique.filter(e => !unique.some(other => other !== e && normalizeForMatch(other.quote).includes(normalizeForMatch(e.quote))))
let anchorPages = new Set(anchors.map(e => e.hits[0]!.page))
if (anchors.length < 2) {
// Repeated table entries can still identify a page by their intersection:
// all matching cells must agree, not merely the highest-scoring page.
const present = evidence.filter(e => e.hits.length)
if (!table || present.length < 2) return []
let common = new Set(present[0]!.hits.map(hit => hit.page))
for (const entry of present.slice(1)) common = new Set([...common].filter(page => entry.hits.some(hit => hit.page === page)))
if (common.size !== 1) return []
anchorPages = common
}
const ranges: Array<TextMatch & { page: number; quote: string }> = []
for (const { quote, hits } of evidence) {
const scoped = hits.length === 1 ? hits : hits.filter(hit => anchorPages.has(hit.page))
if (scoped.length !== 1) continue
const hit = scoped[0]!
ranges.push({ ...hit, quote: pages[hit.page - 1]!.slice(hit.start, hit.end) })
}
const nonOverlapping = ranges.filter((hit, i) => !ranges.some((other, j) => j !== i && other.page === hit.page &&
other.start <= hit.start && other.end >= hit.end && (other.start < hit.start || other.end > hit.end || j < i)))
if (!table) {
// Images and OCR artifacts can occupy most of a chunk. Coverage percentage
// is not evidence of location: require multiple complete, unique sentences
// in the same local source order, and report the result as partial.
for (let i = 1; i < nonOverlapping.length; i++) {
const previous = nonOverlapping[i - 1]!, current = nonOverlapping[i]!
if (current.page < previous.page || (current.page === previous.page && current.start < previous.end)) return []
}
if (nonOverlapping.length < 2 || nonOverlapping.at(-1)!.page - nonOverlapping[0]!.page > 2) return []
}
return nonOverlapping.sort((a, b) => a.page - b.page || a.start - b.start)
}
/** Rank already verified ranges by verbatim overlap with the cited sentence.
* This changes navigation order only; it cannot create a match or resolve ambiguity.
*/
export function sourceOverlapLength(quote: string, sentence: string): number {
const source = normalizeForMatch(quote), answer = normalizeForMatch(sentence)
let previous = new Uint32Array(answer.length + 1), best = 0
for (const character of source) {
const current = new Uint32Array(answer.length + 1)
for (let j = 0; j < answer.length; j++) if (character === answer[j]) {
current[j + 1] = previous[j]! + 1
best = Math.max(best, current[j + 1]!)
}
previous = current
}
return best
}

View File

@ -4,8 +4,16 @@ import assert from 'node:assert/strict'
import {
parseStatusToTimelineStatus,
resolveTimelineHeaderStatus,
shouldShowProcessingError,
} from './knowledgeProcessingStatus.ts'
test('failed attempts expose their cause while awaiting an automatic retry', () => {
assert.equal(shouldShowProcessingError(true, 'processing', 'failed'), true)
assert.equal(shouldShowProcessingError(true, 'failed', 'done'), true)
assert.equal(shouldShowProcessingError(true, 'processing', 'running'), false)
assert.equal(shouldShowProcessingError(false, 'failed', 'failed'), false)
})
test('latest attempt uses failed knowledge status even when root span is done', () => {
assert.equal(resolveTimelineHeaderStatus({
parseStatus: 'failed',

View File

@ -4,6 +4,11 @@ export type TimelineStatusInput = {
isLatestAttempt: boolean
}
/** A failed attempt remains actionable while the queue waits to retry it. */
export function shouldShowProcessingError(hasError: boolean, parseStatus?: string, traceStatus?: string): boolean {
return hasError && (parseStatus === 'failed' || traceStatus === 'failed')
}
/**
* Convert the knowledge-level parse status to the span status vocabulary used
* by the processing timeline.

View File

@ -0,0 +1,60 @@
import { renderDocumentPreviewMarkdown } from './documentPreviewMarkdown'
import { buildTextIndex, findTextRange } from './sourceLocatorDom'
import { findInText, normalizeForMatch, quotedSourceExcerpt } from './sourceLocator'
import { sourceOverlapLength } from './fragmentedSource'
/** Match the same rendered text on both sides, including fenced/inline code.
* Markdown syntax and fence languages are not visible source text. Rendering
* into an inert template also preserves code containing HTML-like text.
*/
export function findMarkdownSourceRange(root: Element, markdown: string, sentence = ''): { range: Range; ranges?: Range[]; narrowed: boolean; exact: boolean } | null {
const template = root.ownerDocument.createElement('template')
template.innerHTML = renderDocumentPreviewMarkdown(markdown)
const source = buildTextIndex(template.content).text
// Establish the complete source region before narrowing. A similar paragraph
// elsewhere in the document cannot rescue a missing or ambiguous source.
const region = findTextRange(root, source)
if (!region) return null
const excerpt = quotedSourceExcerpt(source, sentence) || sentence
if (excerpt && findInText(source, excerpt)) {
const exact = findTextRange(root, excerpt)
if (exact && region.isPointInRange(exact.startContainer, exact.startOffset) && region.isPointInRange(exact.endContainer, exact.endOffset)) {
return { range: exact, narrowed: true, exact: true }
}
}
// Recover paragraph boundaries from the original DOM, not the rendered
// chunk. A child can end halfway through an original paragraph. Its complete
// unique match above establishes the occurrence; only intersecting blocks
// may provide surrounding context, never a similar neighbouring paragraph.
const blocks = [...root.querySelectorAll('p, li, pre, td, th')]
.filter(e => !e.querySelector('p, li, pre, td, th') && region.intersectsNode(e))
.flatMap(element => {
const quote = buildTextIndex(element).text.trim()
const range = findTextRange(element, quote)
if (!range) return []
const overlap = range.cloneRange()
if (overlap.compareBoundaryPoints(Range.START_TO_START, region) < 0) overlap.setStart(region.startContainer, region.startOffset)
if (overlap.compareBoundaryPoints(Range.END_TO_END, region) > 0) overlap.setEnd(region.endContainer, region.endOffset)
// A delimiter or a couple of boundary characters cannot attach an
// otherwise unsupported paragraph to the cited source.
if (normalizeForMatch(overlap.toString()).length < 8) return []
return [{ quote, range }]
})
// Chinese clauses provide stronger anchors than repeated command names.
// Accept complete source runs only, not fuzzy substrings of a guessed block.
const clauses = blocks.filter(({ quote }) => [...quote.matchAll(/[\p{Script=Han}]{8,}/gu)]
.some(m => findInText(sentence, m[0])))
if (clauses.length && clauses.length <= 3) {
const ranges = clauses.map(block => block.range)
return { range: ranges[0]!, ranges, narrowed: true, exact: false }
}
// Verbatim overlap only ranks paragraphs tied to the verified source. The
// paragraph context is not a claim of word-for-word quotation coverage.
const ranked = blocks.map(block => ({ ...block, score: sourceOverlapLength(block.quote, sentence.slice(-300)) }))
.sort((a, b) => b.score - a.score)
const best = ranked[0]
if (best && best.score >= 8 && best.score >= (ranked[1]?.score || 0) + 4) {
return { range: best.range, narrowed: true, exact: false }
}
return { range: region, narrowed: false, exact: true }
}

View File

@ -0,0 +1,148 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import { resolvePdfSource, mergeSourceRects } from './pdfSourceLocate.ts'
import { findInText, findTextMatches, normalizeForMatch, selectQuoteForSentence, parseSourceLocators, sourceQuoteText } from './sourceLocator.ts'
const resolve = (pages: string[], request: Partial<Parameters<typeof resolvePdfSource>[0]>) =>
resolvePdfSource({ locators: [], quotes: [], token: 1, ...request }, pages.length, async (p) => pages[p - 1]!)
test('decimal, negative, percentage and comparison differences never match', () => {
for (const [source, quote] of [
['限值为15毫米', '限值为1.5毫米'], ['温度为5度', '温度为-5度'],
['增长为5', '增长为5%'], ['值小于<5', '值小于>5'], ['时间12:30', '时间1230'],
['比例为1/2', '比例为12'], ['阈值≤5', '阈值≥5'],
]) assert.equal(findInText(source!, quote!), null, `${source} / ${quote}`)
assert.ok(findInText('限值为1.5毫米', '限值为1.5毫米'))
})
test('partial common opening does not manufacture a full quote', () => {
const common = '设备进入施工现场以后必须按照规定检查所有安全措施'
assert.equal(findInText(common + '本次验收没有通过', common + '本次验收已经通过'), null)
})
test('duplicates are ambiguous and supplementary characters have correct UTF-16 ranges', () => {
assert.equal(findInText('重复原文。重复原文。', '重复原文'), null)
assert.equal(findTextMatches('重复原文。重复原文。', '重复原文').length, 2)
const text = '前文𠀀原文片段𠀁后文'
const hit = findInText(text, '𠀀原文片段𠀁')!
assert.equal(text.slice(hit.start, hit.end), '𠀀原文片段𠀁')
})
test('a paraphrase retains full source context rather than an unrelated opening', () => {
const source = '第一部分讨论背景。第二部分试验失败。'
assert.deepEqual(selectQuoteForSentence(source, 'The experiment failed.'), [source])
})
test('malformed pages and boxes cannot be drawn', () => {
assert.deepEqual(parseSourceLocators([{ type: 'pdf', page: 0 }, { type: 'pdf', page: 1.5 }]), [])
for (const bbox of [[NaN, 0, 1, 1], [0, 0, Infinity, 1], [0, 0, 2, 1], [0.8, 0, 0.2, 1]]) {
assert.equal(parseSourceLocators([{ type: 'pdf', page: 1, bbox }])[0]?.bbox, undefined)
}
})
test('all pages are considered, including page 501', async () => {
const pages = Array.from({ length: 501 }, (_, i) => `Page ${i + 1} unrelated.`)
pages[500] = 'The uniquely cited passage.'
const result = await resolve(pages, { scope: pages[500] })
assert.equal(result.targets[0]?.page, 501)
})
test('duplicate passages on different pages are not silently selected', async () => {
const result = await resolve(['设备验收合格后方可使用。', '设备验收合格后方可使用。'], { scope: '设备验收合格后方可使用。' })
assert.deepEqual(result, { targets: [], reason: 'ambiguous' })
})
test('full chunk context disambiguates a repeated sentence and retains occurrence', async () => {
const result = await resolve(['第一章。设备验收合格后方可使用。第二章。设备验收合格后方可使用。'], {
scope: '第二章。设备验收合格后方可使用。', sentence: '设备验收合格后方可使用。',
})
assert.equal(result.targets[0]?.page, 1)
assert.equal(result.targets[0]?.occurrence, 1)
})
test('legacy wrong-page bbox is revalidated against original text', async () => {
const result = await resolve(['第一段正确文本。', '第二段实际内容。'], {
scope: '第二段实际内容。', locators: [{ type: 'pdf', page: 1, bbox: [0, 0, 1, 1], quote: '第二段实际内容。' }],
})
assert.equal(result.targets[0]?.page, 2)
assert.equal(result.targets[0]?.bbox, undefined)
})
test('legacy matching page does not override ambiguity elsewhere', async () => {
const result = await resolve(['相同的原文段落。', '相同的原文段落。'], {
locators: [{ type: 'pdf', page: 1, quote: '相同的原文段落。' }], scope: '相同的原文段落。',
})
assert.equal(result.reason, 'ambiguous')
})
test('mixed bbox and page targets are both resolved', async () => {
const result = await resolve(['', '第二页的引用文本。'], { locators: [
{ type: 'pdf', page: 1, mapping: 'exact', bbox: [0.1, 0.2, 0.9, 0.4], quote: '扫描页的原文' },
{ type: 'pdf', page: 2, mapping: 'exact', quote: '第二页的引用文本。' },
] })
assert.deepEqual(result.targets.map((t) => [t.page, t.granularity]), [[1, 'block'], [2, 'text']])
})
test('scanned page without text retains verified block geometry', async () => {
const result = await resolve([''], { locators: [{ type: 'pdf', page: 1, mapping: 'exact', bbox: [0.1, 0.2, 0.8, 0.5], quote: 'OCR 文本' }] })
assert.equal(result.targets[0]?.granularity, 'block')
})
test('cross-page quote produces separate source fragments', async () => {
const result = await resolve(['The first part of', 'the cited passage ends here.'], { scope: 'The first part of the cited passage ends here.' })
assert.deepEqual(result.targets.map((t) => t.page), [1, 2])
assert.equal(normalizeForMatch(result.targets.map((t) => t.quote).join('')), normalizeForMatch('The first part of the cited passage ends here.'))
})
test('missing full chunk cannot fall back to a coincidental opening', async () => {
const result = await resolve(['Shared opening. Completely different conclusion.'], { scope: 'Shared opening. Unique result absent.', quotes: ['Shared opening.'] })
assert.deepEqual(result, { targets: [], reason: 'missing' })
})
test('unavailable revision does not read or highlight a replacement document', async () => {
const result = await resolvePdfSource({ token: 1, quotes: ['old quote'], locators: [], unavailable: true }, 2, async () => { throw new Error('must not read') })
assert.equal(result.reason, 'unavailable')
})
test('rapid citation switch cancels before consuming a stale page result', async () => {
let cancelled = false
const result = await resolvePdfSource({ token: 1, quotes: [], locators: [], scope: 'old citation' }, 20, async () => { cancelled = true; return 'old citation' }, () => cancelled)
assert.deepEqual(result, { targets: [], reason: 'cancelled' })
})
test('same-height columns remain distinct while adjacent glyph runs merge', () => {
const rects = mergeSourceRects([
{ left: 10, top: 10, width: 30, height: 12 }, { left: 42, top: 10, width: 30, height: 12 },
{ left: 250, top: 10, width: 80, height: 12 },
])
assert.equal(rects.length, 2)
assert.equal(rects[0]?.width, 62)
})
test('native DOMRect prototype getters survive rectangle merging', () => {
// Browser DOMRect coordinates are getters on the prototype, not own fields.
const nativeLike = Object.create({ left: 20, top: 30, width: 40, height: 12 })
assert.deepEqual(mergeSourceRects([nativeLike]), [{ left: 20, top: 30, width: 40, height: 12 }])
})
test('a number cannot match part of a different numeric value', () => {
for (const [source, quote] of [['增长为5%', '增长为5'], ['115', '15'], ['1.5', '15'], ['15.5', '15'], ['-15', '15']]) {
assert.equal(findInText(source!, quote!), null, `${source} / ${quote}`)
}
})
test('partially mapped chunks cannot claim complete precise evidence', async () => {
const result = await resolve(['Known paragraph.', 'Actual important conclusion.'], {
scope: 'Known paragraph. Missing important conclusion.',
locators: [{ type: 'pdf', page: 1, mapping: 'exact', partial: true, quote: 'Known paragraph.' }],
})
assert.equal(result.reason, 'missing')
})
test('HTML entities preserve comparisons and are decoded only once', () => {
assert.equal(sourceQuoteText('<td>限值&#x3c;1.5</td>'), '限值<1.5')
assert.equal(sourceQuoteText('&amp;lt;'), '&lt;')
assert.equal(findInText('temperature 5 C', 'temperature - 5 C'), null)
assert.ok(findInText('temperature - 5 C', 'temperature -5 C'))
})

View File

@ -0,0 +1,126 @@
import { findTableSource, tableFragmentPages } from './tableSource'
import { findSourceFragments, sourceOverlapLength } from './fragmentedSource'
import { findInText, findTextMatches, normalizeForMatch, parseSourceLocators, validSourceBox, type SourceLocateRequest } from './sourceLocator'
export type PdfTarget = {
page: number
quote?: string
occurrence?: number
bbox?: [number, number, number, number]
granularity: 'text' | 'block' | 'page'
}
export type PdfResolution = { targets: PdfTarget[]; reason?: 'ambiguous' | 'missing' | 'unavailable' | 'cancelled' | 'partial' }
/** Resolve evidence before touching the DOM. Never choose the first duplicate. */
export async function resolvePdfSource(
request: SourceLocateRequest,
pageCount: number,
getText: (page: number) => Promise<string>,
cancelled: () => boolean = () => false,
): Promise<PdfResolution> {
if (request.unavailable) return { targets: [], reason: 'unavailable' }
const locators = parseSourceLocators(request.locators).filter((l) => l.type === 'pdf' && l.page! <= pageCount)
const invalidLocators = request.locators.filter((l) => l.type === 'pdf').length !== locators.length
const targets: PdfTarget[] = []
for (const loc of locators) {
if (cancelled()) return { targets: [], reason: 'cancelled' }
// Historical boxes were produced by heuristic alignment and may point
// to another page. Revalidate them against the entire source document.
if (loc.mapping !== 'exact') continue
const page = loc.page!
const quote = loc.quote || ''
const sentence = request.sentence && findInText(quote, request.sentence) ? request.sentence : ''
if (loc.mapping === 'exact' && validSourceBox(loc.bbox)) {
// Text refinement happens inside this known region. Scanned pages can
// still use the parser's geometry without a PDF text layer.
targets.push({ page, bbox: loc.bbox, quote: sentence || quote, granularity: 'block' })
continue
}
const text = await getText(page)
if (cancelled()) return { targets: [], reason: 'cancelled' }
const scope = quote ? findInText(text, quote) : null
if (scope) {
const sub = sentence ? findInText(text.slice(scope.start, scope.end), sentence) : null
const actual = sub ? text.slice(scope.start + sub.start, scope.start + sub.end) : text.slice(scope.start, scope.end)
const at = sub ? scope.start + sub.start : scope.start
const occurrence = findTextMatches(text, actual).findIndex((hit) => hit.start === at)
targets.push({ page, quote: actual, occurrence, granularity: 'text' })
} else if (loc.mapping === 'exact') {
targets.push({ page, granularity: 'page' })
}
}
if (targets.length === locators.length && targets.length && !invalidLocators && !locators.some((l) => l.partial)) return { targets }
// Legacy records may contain a wrong page. Verify their full chunk against
// the original, including every page and cross-page excerpts. A document
// search must inspect all occurrences before declaring a unique match.
const pages: string[] = []
const starts: number[] = []
let full = ''
for (let page = 1; page <= pageCount; page++) {
if (cancelled()) return { targets: [], reason: 'cancelled' }
const text = await getText(page)
starts.push(full.length)
pages.push(text)
full += text + '\n'
}
if (cancelled()) return { targets: [], reason: 'cancelled' }
// The whole chunk disambiguates repeated sentences; do not replace a
// missing full scope with an unrelated opening or a shorter fuzzy anchor.
const candidates = request.scope ? [request.scope] : request.quotes.length ? request.quotes : locators.map((l) => l.quote || '')
let ambiguous = false
for (const quote of candidates) {
if (normalizeForMatch(quote).length < 4) continue
const matches = findTextMatches(full, quote)
if (matches.length > 1) { ambiguous = true; continue }
if (matches.length !== 1) continue
let { start, end } = matches[0]!
const sentence = request.sentence ? findInText(full.slice(start, end), request.sentence) : null
if (sentence) { end = start + sentence.end; start += sentence.start }
const resolved: PdfTarget[] = []
for (let i = 0; i < pages.length; i++) {
const lo = Math.max(start, starts[i]!), hi = Math.min(end, starts[i]! + pages[i]!.length)
if (hi <= lo) continue
const actual = full.slice(lo, hi)
if (normalizeForMatch(actual).length < 2) continue
const occurrence = findTextMatches(pages[i]!, actual).findIndex((m) => m.start === lo - starts[i]!)
resolved.push({ page: i + 1, quote: actual, occurrence, granularity: 'text' })
}
if (resolved.length) return { targets: resolved }
}
if (!ambiguous && request.scope) {
const table = findTableSource(pages, request.scope)
// Individual fragments must respect the same grade/section constraint.
// They can verify partial text when parser artifacts prevent full columns.
const fragments = table.length ? table : findSourceFragments(tableFragmentPages(pages, request.scope), request.scope)
if (request.sentence) fragments.sort((a, b) => sourceOverlapLength(b.quote, request.sentence!) - sourceOverlapLength(a.quote, request.sentence!))
if (fragments.length) return { targets: fragments.map(hit => ({
page: hit.page, quote: hit.quote, granularity: 'text' as const,
occurrence: findTextMatches(pages[hit.page - 1]!, hit.quote).findIndex(m => m.start === hit.start),
})), reason: 'partial' }
}
// Keep independently verified regions, but expose the incomplete result.
return { targets, reason: ambiguous ? 'ambiguous' : 'missing' }
}
export type SourceRect = { left: number; top: number; width: number; height: number }
/** Merge adjacent glyph runs only; never bridge the gutter between columns. */
export function mergeSourceRects(rects: SourceRect[]): SourceRect[] {
const lines: SourceRect[] = []
for (const r of [...rects].sort((a, b) => a.top - b.top || a.left - b.left)) {
if (r.width < 0.5 || r.height < 0.5) continue
const line = lines.find((l) => {
const overlap = Math.min(l.top + l.height, r.top + r.height) - Math.max(l.top, r.top)
const gap = Math.max(r.left - l.left - l.width, l.left - r.left - r.width)
return overlap > Math.min(l.height, r.height) * 0.5 && gap <= Math.min(l.height, r.height) * 0.5
})
if (line) {
const right = Math.max(line.left + line.width, r.left + r.width)
const bottom = Math.max(line.top + line.height, r.top + r.height)
line.left = Math.min(line.left, r.left); line.top = Math.min(line.top, r.top)
line.width = right - line.left; line.height = bottom - line.top
} else lines.push({ left: r.left, top: r.top, width: r.width, height: r.height })
}
return lines
}

View File

@ -216,7 +216,7 @@ function getDocumentGroupKey(item: KnowledgeReferenceLike, index: number): strin
)
}
function mergeDocumentReferences(refs: KnowledgeReferenceLike[]): KnowledgeReferenceLike[] {
export function mergeDocumentReferences(refs: KnowledgeReferenceLike[]): KnowledgeReferenceLike[] {
const groups = new Map<string, KnowledgeReferenceLike & { content_parts?: string[] }>()
refs.forEach((item, index) => {
@ -431,10 +431,9 @@ export function resolveReferenceHighlightKey(
(item) => item.kind === 'document' && item.title.trim().toLowerCase() === title,
)
const scoped = target.knowledgeBaseId
? candidates.find((item) => item.knowledgeBaseId === target.knowledgeBaseId)
: undefined
if (scoped) return scoped.key
if (candidates.length === 1) return candidates[0].key
? candidates.filter((item) => item.knowledgeBaseId === target.knowledgeBaseId)
: candidates
if (scoped.length === 1) return scoped[0]!.key
}
return null

View File

@ -0,0 +1,22 @@
import { test } from 'node:test'
import assert from 'node:assert/strict'
import { quotedSourceExcerpt, selectLocatorsForSentence, selectQuoteForSentence } from './sourceLocator.ts'
import { sourceImageDigest } from './sourceImage.ts'
test('a paraphrase with a verbatim quotation selects only supporting evidence', () => {
const quote = '小家团圆美满,大国繁荣昌盛'
const sentence = `物业在双节期间向业主致以节日祝福,倡导“${quote}”的家国情怀`
const source = `开头问候。\n\n愿家国同辉:${quote},双喜临门。`
assert.equal(quotedSourceExcerpt(source, sentence), quote)
assert.deepEqual(selectQuoteForSentence(source, sentence), [quote])
const locs = [{ type: 'docx', quote: '开头问候。' }, { type: 'docx', quote: source.split('\n\n')[1] }]
assert.deepEqual(selectLocatorsForSentence(locs, sentence), [locs[1]])
assert.equal(quotedSourceExcerpt('其他内容。', sentence), undefined)
assert.equal(quotedSourceExcerpt(`${source}\n${source}`, sentence), undefined)
})
test('quotation does not relax numeric matching', () => {
assert.equal(quotedSourceExcerpt('The cited limit is 1.5 millimeters.', 'Claim: "The cited limit is 15 millimeters."'), undefined)
})
test('source image SHA256 identifies exact bytes', async () => {
assert.equal(await sourceImageDigest(new TextEncoder().encode('abc').buffer), 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad')
assert.notEqual(await sourceImageDigest(new TextEncoder().encode('abd').buffer), await sourceImageDigest(new TextEncoder().encode('abc').buffer))
})

View File

@ -0,0 +1,17 @@
/** Byte identity: never infer an embedded image's position from its filename or OCR. */
export async function sourceImageDigest(bytes: ArrayBuffer): Promise<string> {
const hash = await crypto.subtle.digest('SHA-256', bytes)
return [...new Uint8Array(hash)].map(b => b.toString(16).padStart(2, '0')).join('')
}
export async function indexEmbeddedSourceImages(root: Element): Promise<void> {
await Promise.all([...root.querySelectorAll<HTMLImageElement>('img')].map(async image => {
// Only bytes embedded by docx-preview; never fetch remote document links.
const match = /^data:(?:image\/[^;,]+|application\/octet-stream);base64,([A-Za-z0-9+/=\s]+)$/.exec(image.src)
if (!match) return
try {
const bytes = Uint8Array.from(atob(match[1]!), c => c.charCodeAt(0))
image.dataset.sourceImageDigest = await sourceImageDigest(bytes.buffer)
} catch { /* An unsupported image cannot establish identity. */ }
}))
}

View File

@ -5,11 +5,8 @@ import {
findInText,
findNormalized,
locatorPages,
narrowTextLines,
ngramOverlap,
normalizeForMatch,
parseSourceLocators,
pickBestTexts,
selectLocatorsForSentence,
selectQuoteForSentence,
textFragmentUrl,
@ -19,8 +16,8 @@ import { resolveReferenceSource } from './referenceSources.ts'
import { resolveEpubPath } from './epubPreview.ts'
import { resolvePreviewKind } from './filePreview.ts'
test('normalization keeps letters and digits only, folding width and case', () => {
assert.equal(normalizeForMatch('8.14 索夹,Hello!'), '814索夹hello')
test('normalization preserves numeric symbols while folding width and case', () => {
assert.equal(normalizeForMatch('8.14 索夹,Hello!'), '8.14索夹hello')
})
test('findInText maps a normalized match back to the raw text', () => {
@ -30,7 +27,7 @@ test('findInText maps a normalized match back to the raw text', () => {
assert.equal(text.slice(hit.start, hit.end), '在满足施工需要的前提下,应减小猫道面层开孔面积')
})
test('findNormalized tolerates a differing opening via mid and tail anchors', () => {
test('findNormalized tolerates only an omitted leading list label', () => {
const hay = normalizeForMatch('前文。紧固同一索夹的螺栓时,各螺栓受力应均匀,并应按规定顺序施拧。后文')
const m = findNormalized(hay, '(二)紧固同一索夹的螺栓时,各螺栓受力应均匀,并应按规定顺序施拧')
assert.ok(m)
@ -38,10 +35,7 @@ test('findNormalized tolerates a differing opening via mid and tail anchors', ()
assert.equal(findNormalized(hay, '完全无关的一段内容不应该被匹配到这里来吧'), null)
})
test('ngramOverlap scores shared bigrams', () => {
assert.equal(ngramOverlap('abcd', 'xxabcdxx'), 1)
assert.equal(ngramOverlap('abcd', 'wxyz'), 0)
})
test('selectLocatorsForSentence narrows to the locator that supports the sentence', () => {
const locs = [
@ -58,8 +52,8 @@ test('selectLocatorsForSentence narrows to the locator that supports the sentenc
test('selectQuoteForSentence prefers the supporting sentence of the chunk', () => {
const content = '索夹在主缆上定位后,应紧固螺栓。吊运物体时,作业人员不得沿主缆顶面行走。'
const [first] = selectQuoteForSentence(content, '吊运物体时作业人员不得沿主缆顶面行走')
assert.equal(first, '吊运物体时,作业人员不得沿主缆顶面行走。')
assert.equal(selectQuoteForSentence(content, '')[0], '索夹在主缆上定位后,应紧固螺栓。')
assert.equal(first, '吊运物体时,作业人员不得沿主缆顶面行走')
assert.equal(selectQuoteForSentence(content, '')[0], content)
})
test('parseSourceLocators and locatorPages', () => {
@ -78,20 +72,9 @@ test('textFragmentUrl builds a scroll-to-text link', () => {
assert.match(long, /#:~:text=x+,.*y+$/)
})
test('pickBestTexts narrows a slide or sheet to the cited line', () => {
const bullets = ['风险与对策', '台风季可能影响高空作业:已准备应急停工预案', '钢材价格上涨8%:已锁定四季度采购价']
assert.deepEqual(pickBestTexts(bullets, '应对措施:已准备应急停工预案。依据:'), [1])
const rows = ['液压拉伸器 HT-300 6 张工 在用', '超声波轴力计 UB-20 2 李工 送检', '缆索吊机 CL-500 1 赵工 维修中']
assert.deepEqual(pickBestTexts(rows, '状态:维修中 负责人:赵工 依据:'), [2])
assert.deepEqual(pickBestTexts(bullets, '完全无关的一句话内容'), [])
})
test('narrowTextLines keeps the cited lines of a text range', () => {
const text = '一、安全方面\n上周共排查隐患17项,剩余2项为临边防护网破损。\n二、进度方面\n主缆猫道铺设滞后1天。'
const [[start, end]] = narrowTextLines(text, [[0, Array.from(text).length]], '临边防护网破损需要在周五前整改')
assert.equal(Array.from(text).slice(start, end).join(''), '上周共排查隐患17项,剩余2项为临边防护网破损。')
assert.deepEqual(narrowTextLines(text, [[0, 5]], '完全无关的内容句子'), [])
})
test('lastSentence keeps the cited sentence and extends short ones', () => {
assert.equal(lastSentence('第一句很长很长的内容。第二句也是完整的句子。'), '第二句也是完整的句子。')

View File

@ -8,6 +8,10 @@ export type SourceLocatorType = 'pdf' | 'docx' | 'slide' | 'sheet' | 'text' | 't
export type SourceLocator = {
type: SourceLocatorType | string
mapping?: string
partial?: boolean
source_id?: string
source_hash?: string
page?: number
bbox?: [number, number, number, number] | number[]
block?: number
@ -36,10 +40,16 @@ export type SourceLocateRequest = {
sentence?: string
/** The cited chunk's text, bounding where a narrowed match may come from. */
scope?: string
/** Original Markdown, before stripping markup; code may contain literal tags. */
sourceMarkdown?: string
unavailable?: boolean
/** Neighboring source paragraphs bracketing one embedded OCR image. */
imageContext?: { before: string; after: string }
imageDigest?: string
}
// ---------------------------------------------------------------------------
// Normalization: letters and digits only, lower-cased, full-width folded. The
// Normalization keeps letters, digits and numeric symbols, and folds case/width. The
// same projection the backend aligner uses, so Markdown syntax, whitespace and
// punctuation differences between parsed text and the rendered original do not
// break matching.
@ -51,200 +61,133 @@ export function foldChar(ch: string): string {
return ch.normalize('NFKC').toLowerCase()
}
/** Normalize layout differences while preserving numbers and comparisons. */
export function normalizeForMatch(text: string): string {
let out = ''
for (const ch of String(text || '')) out += foldChar(ch)
return out
return normalizeWithPositions(text).norm
}
/**
* Normalized projection of `text` with, for each normalized character, the
* UTF-16 offset in `text` of the character it came from.
*/
export function normalizeWithPositions(text: string): { norm: string; pos: number[] } {
const chars = Array.from(String(text || ''))
let norm = ''
const pos: number[] = []
let i = 0
for (const ch of String(text || '')) {
const folded = foldChar(ch)
for (const f of folded) {
norm += f
pos.push(i)
let offset = 0
for (let i = 0; i < chars.length; i++) {
const ch = chars[i]!
const value = ch.normalize('NFKC')
const digit = (v: string | undefined) => !!v && /^\p{N}$/u.test(v.normalize('NFKC'))
let folded = foldChar(ch)
if (/^[.,/:+−%‰<>=≤≥≠-]$/u.test(value)) {
let before = i - 1, after = i + 1
while (before >= 0 && /^[ \t]$/.test(chars[before]!)) before--
while (after < chars.length && /^[ \t]$/.test(chars[after]!)) after++
const prev = digit(chars[before]), next = digit(chars[after])
const symbol = (/[.,/:]/.test(value) && prev && next) ||
(/^[+−-]$/.test(value) && next) || (/^[%‰]$/.test(value) && prev) || /^[<>=≤≥≠]$/.test(value)
if (symbol) folded = value.replace('−', '-')
}
i += ch.length
norm += folded
// Offsets throughout this module are UTF-16, including supplementary letters.
for (let j = 0; j < folded.length; j++) pos.push(offset)
offset += ch.length
}
return { norm, pos }
}
// ---------------------------------------------------------------------------
// Fuzzy location of a quote inside a normalized haystack.
const KEY_LEN = 24
export type NormalizedMatch = { start: number; end: number; score: number }
export type TextMatch = { start: number; end: number }
/**
* Find `quote` (raw text) inside `haystack` (already normalized). Tries the
* whole quote, then anchors from its head, middle and tail, and extends the
* match to the quote's length. Returns normalized offsets or null.
*/
export function findNormalized(haystack: string, quote: string): NormalizedMatch | null {
const needle = normalizeForMatch(quote)
if (needle.length < 2 || !haystack) return null
const whole = haystack.indexOf(needle)
if (whole >= 0) return { start: whole, end: whole + needle.length, score: 1 }
if (needle.length <= KEY_LEN) return null
const anchors: Array<{ offset: number; key: string }> = [
{ offset: 0, key: needle.slice(0, KEY_LEN) },
{ offset: Math.floor(needle.length / 2), key: needle.slice(Math.floor(needle.length / 2), Math.floor(needle.length / 2) + KEY_LEN) },
{ offset: needle.length - KEY_LEN, key: needle.slice(-KEY_LEN) },
]
let best: NormalizedMatch | null = null
for (const anchor of anchors) {
let from = 0
// Every occurrence of the anchor is a candidate; score by how much of
// the quote agrees around it.
for (let guard = 0; guard < 50; guard++) {
const at = haystack.indexOf(anchor.key, from)
/** All exact candidates; callers must disambiguate before selecting one. */
export function findNormalizedMatches(haystack: string, quote: string): NormalizedMatch[] {
let needle = normalizeForMatch(quote)
if (needle.length < 2 || !haystack) return []
const search = (key: string) => {
const matches: NormalizedMatch[] = []
const first = Array.from(key)[0]!, last = Array.from(key).at(-1)!
for (let from = 0; from <= haystack.length - key.length;) {
const at = haystack.indexOf(key, from)
if (at < 0) break
const end = at + key.length
// A quoted number must not be a prefix/suffix of a different number.
const before = haystack.slice(Math.max(0, at - 2), at), after = haystack.slice(end, end + 2)
const startsInsideNumber = /\p{N}/u.test(first) && /[\p{N}.,:/+−-]$/u.test(before)
const endsInsideNumber = /\p{N}/u.test(last) && /^[\p{N}.,:/%‰]/u.test(after)
if (!startsInsideNumber && !endsInsideNumber) matches.push({ start: at, end, score: 1 })
from = at + 1
const start = Math.max(0, at - anchor.offset)
const end = Math.min(haystack.length, start + needle.length)
const score = ngramOverlap(needle, haystack.slice(start, end))
if (!best || score > best.score) best = { start, end, score }
}
return matches
}
return best && best.score >= 0.5 ? best : null
const exact = search(needle)
if (exact.length) return exact
// A source list label may have been omitted by a renderer. This is the
// only tolerated prefix difference; never extend a short fuzzy anchor.
const withoutLabel = quote.replace(/^\s*[((][一二三四五六七八九十百\d]+[))]\s*/u, '')
if (withoutLabel === quote) return []
needle = normalizeForMatch(withoutLabel)
return needle.length >= 8 ? search(needle) : []
}
/** Share of the character bigrams of `a` that also occur in `b`. */
export function ngramOverlap(a: string, b: string): number {
if (a.length < 2 || b.length < 2) return a && b && a === b ? 1 : 0
const counts = new Map<string, number>()
for (let i = 0; i + 1 < b.length; i++) {
const g = b.slice(i, i + 2)
counts.set(g, (counts.get(g) || 0) + 1)
}
let hit = 0
for (let i = 0; i + 1 < a.length; i++) {
const g = a.slice(i, i + 2)
const n = counts.get(g) || 0
if (n > 0) {
hit++
counts.set(g, n - 1)
}
}
return hit / (a.length - 1)
export function findNormalized(haystack: string, quote: string): NormalizedMatch | null {
const matches = findNormalizedMatches(haystack, quote)
return matches.length === 1 ? matches[0]! : null
}
export function findTextMatches(text: string, quote: string): TextMatch[] {
const { norm, pos } = normalizeWithPositions(text)
return findNormalizedMatches(norm, quote).map((m) => {
const start = pos[m.start]!, last = pos[m.end - 1]!
return { start, end: last + (text.codePointAt(last)! > 0xffff ? 2 : 1) }
})
}
/** Locate a quote in raw text; returns UTF-16 offsets into `text`. */
export function findInText(text: string, quote: string): { start: number; end: number } | null {
const { norm, pos } = normalizeWithPositions(text)
const m = findNormalized(norm, quote)
if (!m || !pos.length) return null
const start = pos[m.start]
const lastIdx = Math.min(m.end, pos.length) - 1
const last = pos[lastIdx]
// Extend to cover the whole last character (surrogate pairs included).
const end = last + (text.codePointAt(last)! > 0xffff ? 2 : 1)
return { start, end }
const hits = findTextMatches(text, quote)
return hits.length === 1 ? hits[0]! : null
}
// ---------------------------------------------------------------------------
// Picking what to reveal for a citation.
/** Split text into sentence-sized pieces for alignment. */
export function splitSentences(text: string): string[] {
return String(text || '')
.split(/(?<=[。!?!?;;])\s*|\n+/u)
.map((s) => s.trim())
.filter((s) => normalizeForMatch(s).length >= 4)
/** Explicit quotations can survive a paraphrased sentence without fuzzy matching. */
export function quotedSourceExcerpt(content: string, sentence: string): string | undefined {
const source = sourceQuoteText(content)
const candidates = [...sentence.matchAll(/[“「『"]([^”」』"\n]{8,})[”」』"]/gu)]
.map(m => m[1]!).filter(q => normalizeForMatch(q).length >= 8 && findInText(source, q))
return candidates.length === 1 ? candidates[0] : undefined
}
const ALIGN_THRESHOLD = 0.35
/**
* Narrow a chunk's locators to the ones that support the cited sentence. The
* answer paraphrases the source, so each locator's quote is scored by how
* many of the sentence's character bigrams it contains; locators well below
* the best are dropped. When nothing scores, every locator is kept.
*/
/** Narrow only when the answer contains an exact excerpt of the source. */
export function selectLocatorsForSentence(locators: SourceLocator[], sentence: string): SourceLocator[] {
const list = Array.isArray(locators) ? locators.filter(Boolean) : []
sentence = quotedSourceExcerpt(list.map(l => l.quote || '').join('\n'), sentence) || sentence
const needle = normalizeForMatch(sentence)
if (list.length <= 1 || needle.length < 4) return list
const scored = list.map((loc) => ({ loc, score: ngramOverlap(needle, normalizeForMatch(loc.quote || '')) }))
const best = Math.max(...scored.map((s) => s.score))
if (best < ALIGN_THRESHOLD) return list
return scored.filter((s) => s.score >= best * 0.8).map((s) => s.loc)
const exact = list.filter((loc) => findTextMatches(loc.quote || '', sentence).length > 0)
return exact.length ? exact : list
}
/**
* Indices of the texts that best support `sentence`: every text within 80% of
* the best once it clears the alignment threshold, or else the single best
* when it clearly stands out (table rows share few bigrams with prose).
* Empty when nothing aligns, so the caller keeps the whole region.
*/
export function pickBestTexts(texts: string[], sentence: string): number[] {
const needle = normalizeForMatch(sentence || '')
if (needle.length < 4 || texts.length < 2) return []
const scores = texts.map((t) => ngramOverlap(needle, normalizeForMatch(t)))
const best = Math.max(...scores)
if (best >= ALIGN_THRESHOLD) return scores.flatMap((s, i) => (s >= best * 0.8 ? [i] : []))
const top = scores.indexOf(best)
const second = Math.max(0, ...scores.filter((_, i) => i !== top))
return best >= 0.2 && second <= best * 0.5 ? [top] : []
}
/**
* Code point ranges of the lines within `spans` of `text` that best support
* `sentence`, or empty when none aligns. Offsets are code points, the unit
* text locators use.
*/
export function narrowTextLines(text: string, spans: Array<[number, number]>, sentence: string): Array<[number, number]> {
const chars = Array.from(text || '')
const lines: Array<{ text: string; start: number; end: number }> = []
for (const [from, to] of spans) {
const stop = Math.min(to, chars.length)
let lineStart = Math.max(0, from)
for (let i = lineStart; i <= stop; i++) {
if (i < stop && chars[i] !== '\n') continue
const line = chars.slice(lineStart, i).join('')
if (line.trim()) lines.push({ text: line, start: lineStart, end: i })
lineStart = i + 1
}
}
return pickBestTexts(
lines.map((l) => l.text),
sentence,
).map((i) => [lines[i].start, lines[i].end])
}
/**
* The piece of a chunk's text that best supports the cited sentence, used as
* the quote to search when there are no locators. Falls back to the chunk's
* opening when the sentence matches nothing.
*/
/** Use an exact excerpt, or retain the complete cited source as context. */
export function selectQuoteForSentence(content: string, sentence: string): string[] {
const pieces = splitSentences(content)
if (!pieces.length) return content ? [content.slice(0, 200)] : []
const needle = normalizeForMatch(sentence)
if (needle.length >= 4) {
let best = { piece: '', score: 0 }
for (const piece of pieces) {
const score = ngramOverlap(needle, normalizeForMatch(piece))
if (score > best.score) best = { piece, score }
}
if (best.score >= ALIGN_THRESHOLD) return [best.piece, pieces[0]]
}
return [pieces[0], pieces.slice(0, 3).join('')]
const source = sourceQuoteText(content)
if (!source) return []
// Refine only using text that actually occurs in this source. A paraphrase
// still opens its cited chunk; it must not select an unrelated first line.
sentence = quotedSourceExcerpt(content, sentence) || sentence
const hit = sentence ? findInText(source, sentence) : null
return hit ? [source.slice(hit.start, hit.end)] : [source]
}
/** Normalize locator payloads from the API, dropping malformed entries. */
export function parseSourceLocators(raw: unknown): SourceLocator[] {
if (!Array.isArray(raw)) return []
return raw.filter((item): item is SourceLocator => !!item && typeof item === 'object' && typeof (item as SourceLocator).type === 'string')
return raw.filter((item): item is SourceLocator => {
if (!item || typeof item !== 'object' || typeof item.type !== 'string') return false
if (item.type === 'pdf' && (!Number.isSafeInteger(item.page) || item.page < 1)) return false
return true
}).map((loc) => {
if (loc.bbox && !validSourceBox(loc.bbox)) { const { bbox, ...rest } = loc; return rest }
return loc
})
}
/** 1-based pages targeted by PDF locators, in first-seen order. */
@ -279,3 +222,36 @@ export function textFragmentUrl(url: string, quote: string): string {
function encodeTextFragment(text: string): string {
return encodeURIComponent(text).replace(/-/g, '%2D').replace(/,/g, '%2C').replace(/&/g, '%26')
}
export function validSourceBox(box: unknown): box is [number, number, number, number] {
return Array.isArray(box) && box.length === 4 && box.every((n) => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1) && box[0] < box[2] && box[1] < box[3]
}
/** Source text, excluding Markdown destinations and HTML presentation tags. */
export function sourceQuoteText(content: string): string {
return String(content || '').replace(/!\[[^\]\n]*\]\([^\n)]*\)/g, ' ')
.replace(/\[([^\]\n]+)\]\([^\n)]*\)/g, '$1')
.replace(/<\/?[a-zA-Z][^>\n]*>/g, ' ')
.replace(/&(#x[\da-f]+|#\d+|nbsp|amp|lt|gt|quot|apos);/gi, (raw, entity: string) => {
const named: Record<string, string> = { nbsp: ' ', amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }
if (!entity.startsWith('#')) return named[entity.toLowerCase()] || raw
const hex = entity[1]?.toLowerCase() === 'x'
const point = Number.parseInt(entity.slice(hex ? 2 : 1), hex ? 16 : 10)
return Number.isFinite(point) && point > 0 && point <= 0x10ffff ? String.fromCodePoint(point) : raw
})
.trim()
}
/** Locate an embedded image by its exact resource identity in the parent chunk. */
export function sourceImageContext(markdown: string, urls: string[]): SourceLocateRequest['imageContext'] {
const images = [...markdown.matchAll(/!\[[^\]\n]*\]\(([^\n)]*)\)/g)]
const selected = images.filter(m => urls.includes(m[1]!))
if (selected.length !== 1) return undefined
const match = selected[0]!, index = images.indexOf(match)
const previous = images[index - 1], next = images[index + 1]
const prefix = markdown.slice(previous ? previous.index! + previous[0].length : 0, match.index)
const suffix = markdown.slice(match.index! + match[0].length, next?.index ?? markdown.length)
const before = sourceQuoteText(prefix).trim().split(/\n\s*\n/).at(-1)?.trim() || ''
const after = sourceQuoteText(suffix).trim().split(/\n\s*\n/)[0]?.trim() || ''
return before || after ? { before, after } : undefined
}

View File

@ -1,4 +1,4 @@
import { findInText } from './sourceLocator'
import { findInText, findTextMatches } from './sourceLocator'
/** Name of the CSS custom highlight used for cited text. */
export const SOURCE_HIGHLIGHT_NAME = 'source-locate'
@ -56,6 +56,15 @@ function pointAt(index: TextIndex, offset: number): { node: Text; offset: number
export function findTextRange(root: Node, quote: string, index = buildTextIndex(root)): Range | null {
const hit = findInText(index.text, quote)
if (!hit) return null
return rangeAt(root, hit, index)
}
export function findTextRanges(root: Node, quote: string): Range[] {
const index = buildTextIndex(root)
return findTextMatches(index.text, quote).map((hit) => rangeAt(root, hit, index)).filter((r): r is Range => !!r)
}
function rangeAt(root: Node, hit: { start: number; end: number }, index: TextIndex): Range | null {
const from = pointAt(index, hit.start)
const to = pointAt(index, hit.end)
if (!from || !to) return null

View File

@ -0,0 +1,66 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import { findTableSource } from './tableSource'
import { resolvePdfSource } from './pdfSourceLocate'
const courses = '数据实验 数据实验 数据实验 音乐创编(初级) 舞蹈 A 团(周一) 天文观测'
const teachers = '李欣 何逸群 张健 袁亦佳 周孟影 刘佳文'
const scope = `|五 年 级|周一 周二|${courses}|${teachers}|`
const original = '五年级 综合课程表\n数据实验 李欣 教室\n数据实验 何逸群 教室\n数据实验 张健 教室\n音乐创编(初级) 袁亦佳 音乐室\n舞蹈 A 团(周一) 周孟影 礼堂\n天文观测 刘佳文 科学室'
test('paired column sequences resolve repeated courses to their original rows', () => {
const nearbyGrade = original.replace('五年级', '六年级').replace('何逸群', '杨群英')
const hits = findTableSource([nearbyGrade, original, nearbyGrade], scope)
assert.equal(hits.length, 12)
assert.ok(hits.every(h => h.page === 2))
assert.equal(hits.filter(h => h.quote === '数据实验').length, 3)
assert.ok(hits.some(h => h.quote.includes('舞蹈 A 团')))
})
test('identical tables in two places remain unresolved', () => {
assert.deepEqual(findTableSource([original, original], scope), [])
})
test('matching names in the wrong rows cannot satisfy paired columns', () => {
assert.deepEqual(findTableSource([original.replace('数据实验 李欣', '数据实验 袁亦佳').replace('初级) 袁亦佳', '初级) 李欣')], scope), [])
})
test('a spanning label cannot resolve to another grade with the same courses and teachers', () => {
assert.deepEqual(findTableSource([original.replace('五年级', '六年级')], scope), [])
})
test('individual cell fallback cannot bypass the table grade constraint', async () => {
const wrong = original.replace('五年级', '六年级')
const result = await resolvePdfSource({ token: 1, locators: [], quotes: [], scope }, 1, async () => wrong)
assert.deepEqual(result.targets, [])
assert.equal(result.reason, 'missing')
})
test('a sequence cannot splice rows across an intervening mismatched table row', () => {
const lines = original.split('\n')
lines.splice(3, 0, '数据实验 李欣 教室')
assert.deepEqual(findTableSource([lines.join('\n')], scope), [])
})
test('ordered rows can cross a PDF page boundary', () => {
const lines = original.split('\n')
const hits = findTableSource([lines.slice(0, 4).join('\n'), lines.slice(4).join('\n')], scope)
assert.equal(hits.length, 12)
assert.deepEqual([...new Set(hits.map(h => h.page))], [1, 2])
})
test('a changed numeric cell is not accepted as a prefix of the original', () => {
const numerical = '|检测一批(1.5) 检测二批(2.5) 检测三批(3.5) 检测四批(4.5)|负责人甲 负责人乙 负责人丙 负责人丁|'
const page = '检测一批(15) 负责人甲\n检测二批(2.5) 负责人乙\n检测三批(3.5) 负责人丙\n检测四批(4.5) 负责人丁'
assert.deepEqual(findTableSource([page], numerical), [])
})
test('image-heavy steps recover exact instructions around font arrows and page gaps', async () => {
const text = '第二步:设置默认页面并点击确认按钮。\n第三步:进入桌面打开选修课应用。\na) 首页进入【选修课】à②左上角【选课报名】à③滑动找到待选课程,单击【申请选修】按钮\n' + '图片识别产生的额外说明文字'.repeat(30)
const pages = ['第二步:设置默认页面并点击确认按钮。', '图片内容\n第三步:进入桌面打开选修课应用。\na) 首页进入【选修课】→②左上角【选课报名】→③滑动找到待选课程,单击【申请选修】按钮']
const r = await resolvePdfSource({token: 1, locators: [], quotes: [], scope: text, sentence: '进入【选修课】,找到课程后点击【申请选修】。'}, 2, async p => pages[p-1]!)
assert.equal(r.reason, 'partial')
assert.equal(r.targets[0]?.page, 2)
assert.ok(r.targets.some(t => t.quote?.includes('申请选修')))
assert.ok(r.targets.every(t => !t.quote?.includes('额外说明')))
})

View File

@ -0,0 +1,138 @@
import { findNormalizedMatches, normalizeForMatch, normalizeWithPositions, type TextMatch } from './sourceLocator'
export type TableSourceMatch = TextMatch & { page: number; quote: string }
type Column = { text: string; ends: number[] }
type Row = { text: string; page: number; start: number; norm: string; pos: number[] }
type Step = { row: number; hits: TableSourceMatch[] }
function columns(scope: string): Column[] {
return scope.split(/[|\n]/u).flatMap(cell => {
const words = cell.trim().split(/\s+/u).map(normalizeForMatch).filter(Boolean)
if (words.length < 4 || new Set(words.filter(w => w.length >= 2)).size < 3) return []
let text = ''; const ends: number[] = []
for (const word of words) { text += word; ends.push(text.length) }
return text.length >= 12 ? [{ text, ends }] : []
})
}
function spanningLabel(scope: string): string {
const firstCell = scope.trim().split('|')[1]?.trim() || ''
return /^(?:\p{Script=Han}\s+){1,7}\p{Script=Han}$/u.test(firstCell) ? normalizeForMatch(firstCell) : ''
}
/** Independent fragments still have to belong to the cited spanning label.
* Preserve offsets while hiding rows in other sections from fallback matching.
*/
export function tableFragmentPages(pages: string[], scope: string): string[] {
const qualifier = spanningLabel(scope)
if (!scope.includes('|') || !qualifier) return pages
const ordinal = qualifier.match(/^[一二三四五六七八九十百]+(.+)$/u)
const heading = ordinal ? new RegExp(`^[一二三四五六七八九十百]+${ordinal[1]}`) : null
let active = false
return pages.map(page => page.split('\n').map(line => {
const norm = normalizeForMatch(line)
const label = heading ? norm.match(heading)?.[0] : norm.startsWith(qualifier) ? qualifier : undefined
if (label) active = label === qualifier
return active ? line : ' '.repeat(line.length)
}).join('\n'))
}
/** Recover column-serialized tables using paired values on the same original
* row, in the same order. Repeated course names alone never determine a row.
* Only complete column sequences are accepted; no similarity or skipped source
* values. Multiple row sequences remain unresolved.
*/
export function findTableSource(pages: string[], scope: string): TableSourceMatch[] {
if (!scope.includes('|')) return []
// A vertically laid out spanning label is serialized as separate glyphs
// (for example a department or grade). Keep it as a scope constraint.
const qualifier = spanningLabel(scope)
const cols = columns(scope)
if (cols.length < 2 || cols.length > 12) return []
let operations = 0
const rows: Row[] = pages.flatMap((page, i) => {
let start = 0
return page.split('\n').map(text => {
const row = { text, page: i + 1, start, ...normalizeWithPositions(text) }
start += text.length + 1
return row
})
})
const ordinalLabel = qualifier.match(/^[一二三四五六七八九十百]+(.+)$/u)
const heading = ordinalLabel ? new RegExp(`^[一二三四五六七八九十百]+${ordinalLabel[1]}`) : null
let active = !qualifier
const allowed = rows.map(row => {
const label = heading ? row.norm.match(heading)?.[0] : row.norm.startsWith(qualifier) ? qualifier : undefined
if (label) active = label === qualifier
return active
})
const solutions: Array<{ steps: Step[]; weight: number }> = []
for (let a = 0; a < cols.length; a++) for (let b = a + 1; b < cols.length; b++) {
const first = cols[a]!, second = cols[b]!
let states = new Map<string, Step[][]>([['0:0', [[]]]])
let overflow = false
for (let r = 0; r < rows.length; r++) {
const row = rows[r]!
if (row.norm.length < 4 || (qualifier && !allowed[r])) continue
const prefix = (column: Column, offset: number) => {
// End only at a source token boundary, including multiword cell values.
for (let i = column.ends.length - 1; i >= 0; i--) {
const end = column.ends[i]!, size = end - offset
if (size < 2 || size > row.norm.length) continue
const hits = findNormalizedMatches(row.norm, column.text.slice(offset, end))
if (hits.length !== 1) continue
const hit = hits[0]!, start = row.pos[hit.start]!, last = row.pos[hit.end - 1]!
const finish = last + (row.text.codePointAt(last)! > 0xffff ? 2 : 1)
return { end, hit: { page: row.page, start: row.start + start, end: row.start + finish, quote: row.text.slice(start, finish) } }
}
return null
}
const left = new Map<number, ReturnType<typeof prefix>>(), right = new Map<number, ReturnType<typeof prefix>>()
const containsValue = (column: Column) => column.ends.some((end, i) => {
const word = column.text.slice(column.ends[i - 1] || 0, end)
return word.length >= 2 && findNormalizedMatches(row.norm, word).length > 0
})
const dataRow = containsValue(first) && containsValue(second)
const nextStates = new Map<string, Step[][]>()
const put = (key: string, paths: Step[][]) => {
const list = nextStates.get(key) || []
for (const path of paths) {
if (!list.some(have => have.map(s => s.row).join(',') === path.map(s => s.row).join(','))) list.push(path)
if (list.length >= 2) break
}
nextStates.set(key, list.slice(0, 2))
}
for (const [key, paths] of states) {
if (++operations > 100000) return []
const [x, y] = key.split(':').map(Number) as [number, number]
if ((x === 0 && y === 0) || !dataRow || (x === first.text.length && y === second.text.length)) put(key, paths)
if (x === first.text.length || y === second.text.length) continue
if (!left.has(x)) left.set(x, prefix(first, x))
if (!right.has(y)) right.set(y, prefix(second, y))
const p = left.get(x), q = right.get(y)
if (!p || !q) continue
// Distinct columns must occupy distinct cells, not the same repeated text.
if (p.hit.start < q.hit.end && q.hit.start < p.hit.end) continue
put(`${p.end}:${q.end}`, paths.map(path => [...path, { row: r, hits: [p.hit, q.hit] }]))
}
states = nextStates
// Bound pathological/repetitive inputs. A budget limit never chooses a guess.
if (states.size > 4096) { overflow = true; break }
}
const complete = states.get(`${first.text.length}:${second.text.length}`) || []
if (!overflow && complete.length === 1 && complete[0]!.length >= 3) {
const opening = rows[complete[0]![0]!.row]!
if (qualifier && !normalizeForMatch(pages[opening.page - 1]!.slice(0, opening.start)).includes(qualifier)) continue
solutions.push({ steps: complete[0]!, weight: first.text.length + second.text.length })
}
}
if (!solutions.length) return []
solutions.sort((a, b) => b.steps.length - a.steps.length || b.weight - a.weight)
const best = solutions[0]!
// Independent complete column pairs must agree on the row sequence. Shorter
// sequences may describe a subset, but cannot move the source to other rows.
const selectedRows = new Set(best.steps.map(step => step.row))
if (solutions.some(s => s.steps.some(step => !selectedRows.has(step.row)))) return []
const hits = best.steps.flatMap(step => step.hits)
return hits.sort((a, b) => a.page - b.page || a.start - b.start)
}

View File

@ -652,7 +652,7 @@ import { getKnowledgeChunksSummaryHtml } from '@/utils/knowledgeChunksDisplay';
import { getAttachmentParsingSummaryHtml } from '@/utils/attachmentParsingDisplay';
import { useChatCitationPopover } from '@/composables/useChatCitationPopover';
import { useChatReferencesDrawer } from '@/composables/useChatReferencesDrawer';
import type { KnowledgeReferenceLike, ReferenceHighlightTarget } from '@/utils/referenceSources';
import { mergeDocumentReferences, type KnowledgeReferenceLike, type ReferenceHighlightTarget } from '@/utils/referenceSources';
import { resolveCitationChunkId } from '@/utils/citationMarkdown';
import { citationAnchorText } from '@/utils/citationAnchor';
import { getWikiPage, type WikiPage } from '@/api/wiki';
@ -1160,35 +1160,6 @@ const openReferencesDrawer = (
return true
}
const mergeDocumentReferences = (refs: KnowledgeReferenceLike[]): KnowledgeReferenceLike[] => {
const merged = new Map<string, KnowledgeReferenceLike & { contentParts?: string[] }>();
for (const ref of refs) {
if (ref.chunk_type === 'web_search') continue;
const key = ref.knowledge_id || ref.knowledge_title || ref.id;
if (!key) continue;
const existing = merged.get(key);
const content = String(ref.content || '').trim();
if (!existing) {
merged.set(key, {
...ref,
id: ref.knowledge_id || ref.id || key,
content,
contentParts: content ? [content] : [],
});
continue;
}
if (content && !existing.contentParts?.includes(content)) {
existing.contentParts = [...(existing.contentParts || []), content];
existing.content = existing.contentParts.slice(0, 3).join('\n\n');
}
}
return Array.from(merged.values()).map(({ contentParts, ...ref }) => ref);
};
const cleanToolOutputContent = (output: unknown): string => {
const raw = typeof output === 'string' ? output : '';
return raw

View File

@ -0,0 +1,283 @@
<script setup lang="ts">
import { citationAnchorText } from '../../src/utils/citationAnchor'
import { sourceImageDigest } from '../../src/utils/sourceImage'
import { nextTick, onMounted, ref } from 'vue'
import PdfSourceViewer, { type PdfLocateResult } from '../../src/components/source-preview/PdfSourceViewer.vue'
import { sourceQuoteText, type SourceLocateRequest } from '../../src/utils/sourceLocator'
import { fixturePdf } from './pdfFixture'
import parsedFixtures from './parsedFixtures.json'
import DocumentPreview from '../../src/components/document-preview.vue'
import { docxFixture, docxImageFixture, sheetFixture, epubFixture } from './officeFixtures'
const otherBlob = ref<Blob | null>(null)
const otherExt = ref('')
const data = ref<ArrayBuffer | null>(null)
const locate = ref<SourceLocateRequest | null>(null)
const instance = ref(0)
const results = ref<string[]>([])
const finished = ref(false)
let done: ((r: PdfLocateResult) => void) | undefined
function assert(value: unknown, message: string) { if (!value) throw new Error(message) }
async function run(name: string, pages: Parameters<typeof fixturePdf>[0], request: Partial<SourceLocateRequest>, verify: (r: PdfLocateResult) => void | Promise<void>, documentData?: ArrayBuffer) {
try {
const result = new Promise<PdfLocateResult>((resolve, reject) => {
const timer = setTimeout(() => reject(new Error('render timed out')), 20000)
done = (r) => { clearTimeout(timer); resolve(r) }
})
data.value = documentData || fixturePdf(pages)
locate.value = { token: instance.value + 1, quotes: [], locators: [], ...request }
instance.value++
await nextTick()
const r = await result
await nextTick()
for (const mark of document.querySelectorAll<HTMLElement>('.pdf-source-mark')) {
for (const attr of ['left', 'top', 'width', 'height'] as const) assert(Number.isFinite(parseFloat(mark.style[attr])), `invalid ${attr}: ${mark.style.cssText}`)
assert(parseFloat(mark.style.width) > 0 && parseFloat(mark.style.height) > 0, 'empty highlight')
}
await verify(r)
results.value.push(`PASS ${name}`)
} catch (e) { results.value.push(`FAIL ${name}: ${String(e)}`) }
}
async function runOther(name: string, blob: Blob, ext: string, request: Partial<SourceLocateRequest>, verify: (r: PdfLocateResult) => void) {
try {
const result = new Promise<PdfLocateResult>((resolve, reject) => {
const timer = setTimeout(() => reject(new Error('preview timed out')), 20000)
done = (r) => { clearTimeout(timer); resolve(r) }
})
data.value = null
otherBlob.value = blob
otherExt.value = ext
locate.value = { token: ++instance.value, quotes: [], locators: [], ...request }
await nextTick()
const r = await result
await nextTick()
verify(r)
results.value.push(`PASS ${name}`)
} catch (e) { results.value.push(`FAIL ${name}: ${String(e)}`) }
}
const marks = () => [...document.querySelectorAll<HTMLElement>('.pdf-source-mark--text')]
onMounted(async () => {
if (new URLSearchParams(location.search).has('local')) {
const cases = await fetch('./local/manifest.json').then(r => r.json())
for (const fixture of cases) {
const blob = await fetch('./local/' + fixture.file).then(r => r.blob())
fixture.request.scope = sourceQuoteText(fixture.request.scope)
if (fixture.ext === 'pdf') {
otherBlob.value = null
await run(fixture.name, [], fixture.request, r => {
assert(r.found && r.precise === fixture.precise, JSON.stringify(r))
if (fixture.firstPage) assert(r.page === fixture.firstPage, 'navigation must prioritize the cited instruction')
const pages = [...new Set(marks().map(m => Number(m.closest('[data-page]')?.getAttribute('data-page'))))].sort((a, b) => a - b)
assert(JSON.stringify(pages) === JSON.stringify(fixture.pages), `wrong highlighted pages: ${pages}`)
}, await blob.arrayBuffer())
} else await runOther(fixture.name, blob, fixture.ext, fixture.request, r => {
assert(r.found && r.precise === fixture.precise, JSON.stringify(r))
if (fixture.imageDigest) {
const images = [...document.querySelectorAll<HTMLElement>('img.source-locate-block')]
assert(images.length === 1 && images[0]!.dataset.sourceImageDigest === fixture.imageDigest, 'wrong source image')
}
if (fixture.highlightText) {
const highlight = (CSS as any).highlights?.get('source-locate')
const text = highlight ? [...highlight].map((range: Range) => range.toString()).join('') : [...document.querySelectorAll('.source-locate-mark')].map(e => e.textContent).join('')
assert(text === fixture.highlightText, 'highlight must contain only the exact cited quotation')
}
})
}
finished.value = true
return
}
for (const fixture of [
{ name: 'citation anchor retains all sentences preceding the marker', html: '<p>第一句说明原目录保留文件。第二句说明回到主仓库开发。<span class="citation">[1]</span></p>', want: '第一句说明原目录保留文件。第二句说明回到主仓库开发。' },
{ name: 'citation anchor stops at the previous citation', html: '<p>先前的内容属于另一个来源。<span class="citation">[1]</span>本条引用包括操作原理。以及后续开发所在的目录。<span class="citation">[2]</span></p>', want: '本条引用包括操作原理。以及后续开发所在的目录。' },
{ name: 'adjacent citations share the same preceding passage', html: '<p>两个来源共同支撑这段完整的解释。<span class="citation">[1]</span> <span class="citation">[2]</span></p>', want: '两个来源共同支撑这段完整的解释。' },
{ name: 'citation anchor retains inline code without citation labels', html: '<p><code>git switch --detach</code> 让原目录停在当前提交。后续开发在主仓库进行即可。<span class="citation-kb">filename.md</span></p>', want: 'git switch --detach 让原目录停在当前提交。后续开发在主仓库进行即可。' },
]) {
try {
const root = document.createElement('div')
root.className = 'markdown-content'
root.innerHTML = fixture.html
const markers = root.querySelectorAll('.citation, .citation-kb')
assert(citationAnchorText(markers[markers.length - 1]!) === fixture.want, 'wrong answer passage')
results.value.push(`PASS ${fixture.name}`)
} catch (e) { results.value.push(`FAIL ${fixture.name}: ${String(e)}`) }
}
const imageBytes = Uint8Array.from(atob('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII='), c => c.charCodeAt(0))
const imageDigest = await sourceImageDigest(imageBytes.buffer)
await runOther('DOCX identifies image bytes without any text anchor', await docxImageFixture(), 'docx', { imageDigest }, r => {
assert(r.found && !r.precise && r.granularity === 'block', JSON.stringify(r))
assert(document.querySelectorAll('img.source-locate-block').length === 1, 'exactly one image must be marked')
})
await runOther('DOCX rejects duplicate embedded image identities', await docxImageFixture(2), 'docx', { imageDigest }, r => assert(!r.found && r.reason === 'ambiguous', JSON.stringify(r)))
await runOther('DOCX rejects a different image identity', await docxImageFixture(), 'docx', { imageDigest: '0'.repeat(64) }, r => assert(!r.found, JSON.stringify(r)))
const fenced = '# Source document\n\nOpening unrelated paragraph.\n\n- **Explanation**: Releasing the branch preserves the current commit and files.\n\n```bash\ngit -C /example/tree switch --detach\n```'
const highlightedText = () => {
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('')
}
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))
assert(highlightedText() === 'Explanation: Releasing the branch preserves the current commit and files', highlightedText())
})
await runOther('Markdown exact code citation narrows to the command', new Blob([fenced]), 'md', { sourceMarkdown: fenced, sentence: 'git -C /example/tree switch --detach' }, r => {
assert(r.precise, JSON.stringify(r)); assert(highlightedText() === 'git -C /example/tree switch --detach', highlightedText())
})
await runOther('Markdown duplicate complete sources stay ambiguous', new Blob([fenced + '\n\n' + fenced]), 'md', { sourceMarkdown: fenced }, r => assert(!r.found, JSON.stringify(r)))
await runOther('Markdown missing scope cannot match a similar paragraph', new Blob([fenced]), 'md', { sourceMarkdown: fenced + '\nMissing required evidence.', sentence: 'preserves the current commit and files' }, r => assert(!r.found, JSON.stringify(r)))
const htmlCode = 'Literal code: `<Widget>` and `x < 1.5`.\n\n~~~html\n<section>example</section>\n~~~'
await runOther('Markdown literal tags and tilde code fences survive projection', new Blob([htmlCode]), 'md', { sourceMarkdown: htmlCode }, r => assert(r.precise, JSON.stringify(r)))
await runOther('Markdown changed numeric evidence is rejected', new Blob([htmlCode]), 'md', { sourceMarkdown: htmlCode.replace('1.5', '15') }, r => assert(!r.found, JSON.stringify(r)))
const multiParagraph = '- **操作**:在原目录执行 `git switch --detach` 释放分支。\n- **原理**:`--detach` 让工作目录保留当前提交,现有文件仍然保留。\n- **后续**:完成操作以后可以回到主仓库继续开发。'
await runOther('Markdown multi-sentence paraphrase locates both supported paragraphs', new Blob([multiParagraph]), 'md', {
sourceMarkdown: multiParagraph, sentence: 'git switch --detach 让工作目录保留当前提交(detached HEAD),文件内容仍然保留。完成操作以后可以回到主仓库继续开发即可。',
}, r => {
assert(r.found && !r.precise && r.granularity === 'block', JSON.stringify(r))
assert(highlightedText() === '原理:--detach 让工作目录保留当前提交,现有文件仍然保留后续:完成操作以后可以回到主仓库继续开发', highlightedText())
})
const boundaryParagraph = 'Client only uses `api.example.test` for read-only requests. Tokens stay in the local keychain and never sync to the cloud.'
const boundaryPrefix = '# Account settings\n\nChoose the personal repository.\n\nClient only uses `api.example.test`'
const boundaryDocument = '# Account settings\n\nChoose the personal repository.\n\n' + boundaryParagraph + '\n\nUnrelated backup and restore instructions.'
const completeBoundaryText = 'Client only uses api.example.test for read-only requests. Tokens stay in the local keychain and never sync to the cloud'
await runOther('Markdown child ending mid-paragraph reveals the original complete paragraph', new Blob([boundaryDocument]), 'md', {
sourceMarkdown: boundaryPrefix, sentence: 'Use api.example.test for read-only requests and keep tokens in the local keychain.',
}, r => {
assert(r.found && !r.precise && r.granularity === 'block', JSON.stringify(r))
assert(highlightedText() === completeBoundaryText, highlightedText())
})
await runOther('Markdown child starting mid-paragraph restores its opening without the next paragraph', new Blob([boundaryDocument]), 'md', {
sourceMarkdown: 'Tokens stay in the local keychain and never sync to the cloud.', sentence: 'Credentials stay in the local keychain with no cloud synchronization.',
}, r => {
assert(r.found && !r.precise, JSON.stringify(r))
assert(highlightedText() === completeBoundaryText, highlightedText())
})
await runOther('Markdown a complete explicit quotation remains narrowly highlighted', new Blob([boundaryDocument]), 'md', {
sourceMarkdown: boundaryParagraph, sentence: 'The source says “Tokens stay in the local keychain and never sync to the cloud”.',
}, r => {
assert(r.precise, JSON.stringify(r))
assert(highlightedText() === 'Tokens stay in the local keychain and never sync to the cloud', highlightedText())
})
await runOther('Markdown boundary completion cannot bypass duplicate source ambiguity', new Blob([boundaryDocument + '\n\n' + boundaryDocument]), 'md', {
sourceMarkdown: boundaryPrefix, sentence: 'Use api.example.test for read-only requests.',
}, r => assert(!r.found, JSON.stringify(r)))
await runOther('Markdown boundary completion cannot rescue a changed source value', new Blob([boundaryDocument]), 'md', {
sourceMarkdown: boundaryPrefix.replace('api.example.test', 'api.other.test'), sentence: 'Tokens stay in the local keychain.',
}, r => assert(!r.found, JSON.stringify(r)))
await runOther('Markdown an adjacent paragraph cannot be pulled in by answer similarity', new Blob([boundaryDocument]), 'md', {
sourceMarkdown: boundaryPrefix, sentence: 'Unrelated backup and restore instructions.',
}, r => {
assert(r.found, JSON.stringify(r))
assert(!highlightedText().includes('backup'), highlightedText())
})
const repeatedBoundary = '# First occurrence\n\n' + boundaryParagraph + '\n\n# Second occurrence\n\n' + boundaryParagraph
await runOther('Markdown verified scope preserves the occurrence of a repeated paragraph', new Blob([repeatedBoundary]), 'md', {
sourceMarkdown: '# Second occurrence\n\nClient only uses `api.example.test`', sentence: 'Use api.example.test for read-only requests and keep tokens in the local keychain.',
}, r => {
assert(r.found && !r.precise, JSON.stringify(r))
assert(highlightedText() === completeBoundaryText, highlightedText())
const range = [...(CSS as any).highlights.get('source-locate')][0] as Range
assert(range.startContainer.parentElement?.closest('p')?.previousElementSibling?.textContent === 'Second occurrence', 'wrong repeated paragraph occurrence')
})
const docx = await docxFixture()
await runOther('DOCX verifies the indexed paragraph', docx, 'docx', { locators: [{ type: 'docx', mapping: 'exact', block: 2, quote: 'The cited limit is 1.5 millimeters.' }] }, r => assert(r.precise, JSON.stringify(r)))
await runOther('DOCX revalidates a legacy wrong block', docx, 'docx', { scope: 'The cited limit is 1.5 millimeters.', locators: [{ type: 'docx', block: 1 }] }, r => assert(r.precise, JSON.stringify(r)))
await runOther('DOCX rejects a different numeric value', docx, 'docx', { scope: 'The cited limit is 15 millimeters.', locators: [{ type: 'docx', block: 2 }] }, r => assert(!r.found, JSON.stringify(r)))
await runOther('DOCX partial locator still verifies the exact cited sentence', docx, 'docx', {
scope: 'The cited limit is 1.5 millimeters. Unmapped image placeholder.', sentence: 'The cited limit is 1.5 millimeters.',
locators: [{ type: 'docx', mapping: 'exact', partial: true, block: 2, quote: 'The cited limit is 1.5 millimeters.' }],
}, r => assert(r.precise, JSON.stringify(r)))
const imageContext = { before: 'The cited limit is 1.5 millimeters.', after: 'Verified paragraph after the image.' }
await runOther('DOCX OCR citation highlights its unique bracketed image', await docxImageFixture(), 'docx', { imageContext }, r => {
assert(r.found && !r.precise && r.granularity === 'block', JSON.stringify(r))
assert(document.querySelectorAll('img.source-locate-block').length === 1, 'wrong image region')
})
await runOther('DOCX multiple bracketed images cannot silently choose the first', await docxImageFixture(2), 'docx', { imageContext }, r => assert(!r.found, JSON.stringify(r)))
await runOther('DOCX missing image context cannot highlight another image', await docxImageFixture(), 'docx', { imageContext: { ...imageContext, after: 'Missing paragraph.' } }, r => assert(!r.found, JSON.stringify(r)))
await runOther('DOCX image at chunk end stops before the next original paragraph', await docxImageFixture(), 'docx', { imageContext: { ...imageContext, after: '' } }, r => assert(r.found && !r.precise, JSON.stringify(r)))
await runOther('DOCX image at chunk start uses its following original paragraph', await docxImageFixture(), 'docx', { imageContext: { ...imageContext, before: '' } }, r => assert(r.found && !r.precise, JSON.stringify(r)))
const sheet = sheetFixture()
await runOther('spreadsheet shows verified rows as a region', sheet, 'xlsx', { locators: [{ type: 'sheet', mapping: 'exact', sheet: 'Inspection', row_start: 2, row_end: 2, quote: 'Anchor 1.5 mm' }] }, r => {
assert(r.found && !r.precise && r.granularity === 'block', JSON.stringify(r))
assert(document.querySelector('tr.source-locate-block')?.textContent?.includes('Anchor'), 'wrong row')
})
await runOther('spreadsheet missing sheet cannot select first sheet', sheet, 'xlsx', { locators: [{ type: 'sheet', mapping: 'exact', sheet: 'Missing', row_start: 2 }] }, r => assert(!r.found, JSON.stringify(r)))
const epub = await epubFixture()
await runOther('EPUB exact section disambiguates repeated text', epub, 'epub', { locators: [{ type: 'section', mapping: 'exact', section: 2, quote: 'Repeated cited passage.' }] }, r => assert(r.precise, JSON.stringify(r)))
await runOther('EPUB legacy duplicates cannot choose first chapter', epub, 'epub', { scope: 'Repeated cited passage.', locators: [{ type: 'section', section: 1 }] }, r => assert(!r.found, JSON.stringify(r)))
await runOther('Markdown repeated evidence is not silently selected', new Blob(['First chapter.\n\nRepeated cited passage.\n\nSecond chapter.\n\nRepeated cited passage.']), 'md', { scope: 'Repeated cited passage.' }, r => assert(!r.found, JSON.stringify(r)))
await runOther('plain text revalidates stale character offsets', new Blob(['Wrong opening.\nUnique cited passage.']), 'txt', { scope: 'Unique cited passage.', locators: [{ type: 'text', start: 0, end: 10, quote: 'Unique cited passage.' }] }, r => assert(r.precise, JSON.stringify(r)))
await runOther('edited evidence cannot reuse an original text location', new Blob(['Unique cited passage.']), 'txt', { unavailable: true, scope: 'Unique cited passage.' }, r => assert(!r.found && r.reason === 'unavailable', JSON.stringify(r)))
otherBlob.value = null
await run('legacy wrong page resolves to page 2', [
{ lines: [['Unrelated first page.', 60, 620]] }, { lines: [['Unique cited source passage.', 60, 620]] },
], { scope: 'Unique cited source passage.', locators: [{ type: 'pdf', page: 1, bbox: [0, 0, 1, 1], quote: 'Unique cited source passage.' }] }, (r) => {
assert(r.page === 2 && r.precise, JSON.stringify(r))
assert(marks().every((m) => m.closest('[data-page]')?.getAttribute('data-page') === '2'), 'wrong page highlight')
})
await run('table columns verify repeated course names against the paired teacher rows', [
{ lines: [['Drawing Bob RoomA', 60, 650], ['Drawing Alice RoomB', 60, 620], ['Robotics Carol RoomC', 60, 590], ['Dance David RoomD', 60, 560], ['Music Ellen RoomE', 60, 530], ['Chess Frank RoomF', 60, 500]] },
{ lines: [['Drawing Alice RoomA', 60, 650], ['Drawing Bob RoomB', 60, 620], ['Robotics Carol RoomC', 60, 590], ['Dance David RoomD', 60, 560], ['Music Ellen RoomE', 60, 530], ['Chess Frank RoomF', 60, 500]] },
], { scope: '|Drawing Drawing Robotics Dance Music Chess|Alice Bob Carol David Ellen Frank|' }, r => {
assert(r.found && r.page === 2 && r.reason === 'partial', JSON.stringify(r))
assert(marks().length >= 12 && marks().every(m => m.closest('[data-page]')?.getAttribute('data-page') === '2'), 'table paired to the wrong rows')
})
await run('image-heavy cross-page instructions retain verified excerpts', [
{ lines: [['Step two: choose the desktop view.', 60, 650]] },
{ lines: [['Step three: open the application.', 60, 650], ['Select the application form.', 60, 600]] },
], { scope: 'Step two: choose the desktop view.\nStep three: open the application.\nSelect the application form.\n' + 'Unmatched image OCR details. '.repeat(30), sentence: 'Select the application form.' }, r => {
assert(r.found && r.page === 2 && r.reason === 'partial', JSON.stringify(r))
assert(document.querySelector('[data-page="2"] .pdf-source-mark--text'), 'missing actual instruction')
})
await run('duplicate text reports ambiguity', [{ lines: [['Repeated source passage.', 60, 620], ['Repeated source passage.', 60, 420]] }], { scope: 'Repeated source passage.' }, (r) => {
assert(r.reason === 'ambiguous' && !r.found && marks().length === 0, JSON.stringify(r))
})
await run('decimal mismatch has no highlight', [{ lines: [['The limit is 15 millimeters.', 60, 620]] }], { scope: 'The limit is 1.5 millimeters.' }, (r) => assert(!r.found && !marks().length, JSON.stringify(r)))
await run('bbox disambiguates the lower repeated paragraph', [{ lines: [['Repeated source passage.', 60, 620], ['Repeated source passage.', 60, 420]] }], {
locators: [{ type: 'pdf', mapping: 'exact', page: 1, quote: 'Repeated source passage.', bbox: [0.09, 0.44, 0.8, 0.5] }],
}, (r) => { assert(r.precise, JSON.stringify(r)); assert(marks().every((m) => parseFloat(m.style.top) > 40), 'upper duplicate highlighted') })
await run('mixed scanned region and text page retain both', [{ lines: [] }, { lines: [['Second page source passage.', 60, 620]] }], {
locators: [{ type: 'pdf', mapping: 'exact', page: 1, bbox: [0.1, 0.2, 0.8, 0.4], quote: 'Scanned text' }, { type: 'pdf', mapping: 'exact', page: 2, quote: 'Second page source passage.' }],
}, (r) => {
assert(r.found && !r.precise && r.granularity === 'block', JSON.stringify(r))
assert(document.querySelector('[data-page="1"] .pdf-source-mark--box'), 'missing scan region')
assert(document.querySelector('[data-page="2"] .pdf-source-mark--text'), 'missing second page')
})
await run('rotated page text uses rendered geometry', [{ rotation: 90, lines: [['Rotated cited passage.', 60, 620]] }], { scope: 'Rotated cited passage.' }, (r) => {
assert(r.precise && marks().length > 0, JSON.stringify(r))
assert(marks().every((m) => parseFloat(m.style.top) >= 0 && parseFloat(m.style.left) >= 0), 'invalid rotated geometry')
})
await run('cross-page evidence highlights both pages', [{ lines: [['First half of the', 60, 620]] }, { lines: [['source continues here.', 60, 620]] }], { scope: 'First half of the source continues here.' }, (r) => {
assert(r.precise, JSON.stringify(r))
assert(document.querySelector('[data-page="1"] .pdf-source-mark--text') && document.querySelector('[data-page="2"] .pdf-source-mark--text'), 'missing cross-page evidence')
})
for (const fixture of parsedFixtures) {
const buffer = Uint8Array.from(atob(fixture.pdf), (c) => c.charCodeAt(0)).buffer
await run(fixture.name, [], { locators: [fixture.locator] }, (r) => {
assert(r.precise && r.page === fixture.page, JSON.stringify(r))
assert(marks().length > 0, 'missing parser-derived highlight')
for (const mark of marks()) {
const left = parseFloat(mark.style.left) / 100, top = parseFloat(mark.style.top) / 100
const width = parseFloat(mark.style.width) / 100, height = parseFloat(mark.style.height) / 100
const [x0, y0, x1, y1] = fixture.locator.bbox
assert(left + width / 2 >= x0 && left + width / 2 <= x1 && top + height / 2 >= y0 && top + height / 2 <= y1, 'highlight outside parser source region')
}
}, buffer)
}
finished.value = true
})
</script>
<template>
<main>
<h1>Source location: document rendering regression</h1>
<p id="summary">{{ finished ? `${results.filter((r) => r.startsWith('PASS')).length}/${results.length} passed` : 'Running…' }}</p>
<details :open="!finished"><summary>Case results</summary><ul><li v-for="r in results" :key="r">{{ r }}</li></ul></details>
<div class="viewer"><DocumentPreview v-if="otherBlob" :key="instance" :source-blob="otherBlob" :file-type="otherExt" :file-name="`fixture.${otherExt}`" :active="true" source-mode fill-height :locate="locate" @located="(r) => done?.(r)" /><PdfSourceViewer v-if="data" :key="instance" :data="data" :locate="locate" @located="(r) => done?.(r)" /></div>
</main>
</template>
<style>
body { margin: 24px; font: 14px system-ui; --app-source-highlight: #ffc400; }
.viewer { width: min(760px, 100%); height: 600px; border: 1px solid #ddd; }
li { margin: 5px 0; }
</style>

View File

@ -0,0 +1,60 @@
# Source location rendering regressions
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,
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.
The five `parsedFixtures.json` cases are generated by the real Python PDFium
parser. Regenerate from the repository root after changing parsing or geometry:
```sh
docreader/.venv/bin/python -m docreader.tests.generate_source_location_browser_fixtures
```
The fixtures contain only generated test text. No user documents or remote
parser services are needed. Assertions check page identity, ambiguity rejection,
nonempty finite geometry, region containment, all fragments of cross-page
citations, stale evidence, and rapid document destruction/recreation.
The pure resolver's separate Node tests cover page 501, cancellation, partial
mapping, numeric meaning, and DOMRect prototype properties. Python tests cover
native PDF parsing, crop/rotation, duplicate paragraphs and protobuf transport.
## Private local replay
Open the same page with `?local=1` to replay `local/manifest.json`. The `local/`
directory ignores all fixture files, so uploaded documents and query logs are
never added to Git. Each manifest entry provides `name`, `file`, `ext`,
`request` (a `SourceLocateRequest`), expected `precise`, and expected PDF
`pages`, and optional `firstPage` for the initial navigation target. Files are served only by the local development server. The replay
checks actual highlighted pages and precision status, not merely whether a
preview opened. Keep real user files out of `parsedFixtures.json`.
The generated DOCX cases also check an OCR image bracketed by unique source
paragraphs, missing/duplicate image contexts, images at chunk boundaries,
and a valid sentence within a partially mapped chunk.
PDF cases include column-serialized tables with repeated course names and
paired row values, and image-heavy cross-page instructions with corrupted font
arrows. Separate resolver tests reject wrong grades, mismatched rows, duplicate
tables, and numeric changes. Partial highlights never claim full chunk coverage.
DOCX regressions also verify exact image-byte identity, ambiguous duplicate images,
and private replay assertions for the exact highlighted excerpt and image digest.
Markdown regressions render cited raw Markdown using the same sanitized renderer
as the preview. They cover fenced language names, literal tags inside code,
exact commands, paragraph-level paraphrases, multi-paragraph citations, ambiguous
duplicate sources, missing source scopes, and changed numeric values. DOM anchor
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.
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
source scopes, modified values and unrelated adjacent paragraphs cannot use this
completion path. A repeated paragraph keeps the occurrence established by the
full source scope. Exact explicit quotations still retain their narrow range.

View File

@ -0,0 +1,3 @@
<!doctype html>
<html lang="en"><head><meta charset="UTF-8"><title>Source location regression tests</title></head>
<body><div id="app"></div><script type="module" src="./main.ts"></script></body></html>

View File

@ -0,0 +1,2 @@
*
!.gitignore

View File

@ -0,0 +1,9 @@
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'
import { Button, Loading } from 'tdesign-vue-next'
import { Icon } from 'tdesign-icons-vue-next'
import Harness from './Harness.vue'
createApp(Harness).component('t-button', Button).component('t-loading', Loading).component('t-icon', Icon).use(createI18n({ legacy: false, locale: 'en', messages: { en: {
preview: { zoomOut: 'Zoom out', zoomIn: 'Zoom in', loadFailed: 'Load failed' },
chat: { referenceSourcePrevious: 'Previous location', referenceSourceNext: 'Next location' },
} } })).mount('#app')

View File

@ -0,0 +1,36 @@
import JSZip from 'jszip'
import * as XLSX from 'xlsx'
export async function docxFixture(): Promise<Blob> {
const zip = new JSZip()
zip.file('[Content_Types].xml', '<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>')
zip.file('_rels/.rels', '<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>')
zip.file('word/document.xml', '<?xml version="1.0"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p><w:r><w:t>Unrelated first paragraph.</w:t></w:r></w:p><w:p><w:r><w:t>The cited limit is 1.5 millimeters.</w:t></w:r></w:p></w:body></w:document>')
return zip.generateAsync({ type: 'blob', mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' })
}
export function sheetFixture(): Blob {
const book = XLSX.utils.book_new()
XLSX.utils.book_append_sheet(book, XLSX.utils.aoa_to_sheet([['Equipment', 'Limit'], ['Anchor', '1.5 mm'], ['Cable', '15 mm']]), 'Inspection')
return new Blob([XLSX.write(book, { type: 'array', bookType: 'xlsx' })])
}
export async function epubFixture(): Promise<Blob> {
const zip = new JSZip()
zip.file('mimetype', 'application/epub+zip')
zip.file('META-INF/container.xml', '<container xmlns="urn:oasis:names:tc:opendocument:xmlns:container" version="1.0"><rootfiles><rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/></rootfiles></container>')
zip.file('OEBPS/content.opf', '<package xmlns="http://www.idpf.org/2007/opf" version="3.0"><metadata/><manifest><item id="ch1" href="one.xhtml" media-type="application/xhtml+xml"/><item id="ch2" href="two.xhtml" media-type="application/xhtml+xml"/></manifest><spine><itemref idref="ch1"/><itemref idref="ch2"/></spine></package>')
zip.file('OEBPS/one.xhtml', '<html xmlns="http://www.w3.org/1999/xhtml"><body><p>Repeated cited passage.</p></body></html>')
zip.file('OEBPS/two.xhtml', '<html xmlns="http://www.w3.org/1999/xhtml"><body><p>Repeated cited passage.</p></body></html>')
return zip.generateAsync({ type: 'blob', mimeType: 'application/epub+zip' })
}
export async function docxImageFixture(count = 1): Promise<Blob> {
const zip = await JSZip.loadAsync(await (await docxFixture()).arrayBuffer())
zip.file('word/_rels/document.xml.rels', '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="image1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image.png"/></Relationships>')
zip.file('word/media/image.png', 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jRZkAAAAASUVORK5CYII=', { base64: true })
const drawing = '<w:p><w:r><w:drawing><wp:inline xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"><wp:extent cx="914400" cy="914400"/><wp:docPr id="1" name="Evidence"/><a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"><a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"><pic:blipFill><a:blip xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" r:embed="image1"/></pic:blipFill><pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="914400" cy="914400"/></a:xfrm></pic:spPr></pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r></w:p>'
const xml = await zip.file('word/document.xml')!.async('string')
zip.file('word/document.xml', xml.replace('</w:body>', drawing.repeat(count) + '<w:p><w:r><w:t>Verified paragraph after the image.</w:t></w:r></w:p></w:body>'))
return zip.generateAsync({ type: 'blob' })
}

View File

@ -0,0 +1,92 @@
[
{
"name": "PDFium lower paragraph with decimal evidence",
"page": 2,
"pdf": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAyIC9LaWRzIFs0IDAgUiA2IDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago0IDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgNjAwIDgwMF0gL1JvdGF0ZSAwICAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSAzIDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjUgMCBvYmoKPDwgL0xlbmd0aCA3NiA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDYwIDcwMCBUZCAoRmlyc3QgcGFnZSBoYXMgaW5kZXBlbmRlbnQgb3JpZ2luYWwgZXZpZGVuY2UuKSBUaiBFVAplbmRzdHJlYW0KZW5kb2JqCjYgMCBvYmoKPDwgL1R5cGUgL1BhZ2UgL1BhcmVudCAyIDAgUiAvTWVkaWFCb3ggWzAgMCA2MDAgODAwXSAvUm90YXRlIDAgIC9SZXNvdXJjZXMgPDwgL0ZvbnQgPDwgL0YxIDMgMCBSID4+ID4+IC9Db250ZW50cyA3IDAgUiA+PgplbmRvYmoKNyAwIG9iago8PCAvTGVuZ3RoIDE1MiA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDYwIDcwMCBUZCAoU2Vjb25kIHBhZ2UgdXBwZXIgcGFyYWdyYXBoIGlzIHVucmVsYXRlZC4pIFRqIEVUCkJUIC9GMSAxNCBUZiA2MCA0MDAgVGQgKFNlY29uZCBwYWdlIGxvd2VyIGV2aWRlbmNlOiB0aGUgbGltaXQgaXMgMS41IG1tLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgOAowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1OCAwMDAwMCBuIAowMDAwMDAwMTIxIDAwMDAwIG4gCjAwMDAwMDAxOTEgMDAwMDAgbiAKMDAwMDAwMDMyOCAwMDAwMCBuIAowMDAwMDAwNDU0IDAwMDAwIG4gCjAwMDAwMDA1OTEgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA4IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo3OTQKJSVFT0YK",
"locator": {
"type": "pdf",
"page": 2,
"mapping": "exact",
"bbox": [
0.1,
0.4842,
0.6071,
0.5037
],
"source_id": "pdf:2:42:90",
"quote": "Second page lower evidence: the limit is 1.5 mm."
}
},
{
"name": "PDFium CropBox and rotation 0",
"page": 1,
"pdf": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFs0IDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago0IDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgNjAwIDgwMF0gL1JvdGF0ZSAwIC9Dcm9wQm94IFsxMDAgMTAwIDUwMCA3MDBdIC9SZXNvdXJjZXMgPDwgL0ZvbnQgPDwgL0YxIDMgMCBSID4+ID4+IC9Db250ZW50cyA1IDAgUiA+PgplbmRvYmoKNSAwIG9iago8PCAvTGVuZ3RoIDY4ID4+CnN0cmVhbQpCVCAvRjEgMTQgVGYgMTUwIDYwMCBUZCAoQ3JvcHBlZCBhbmQgcm90YXRlZCBzb3VyY2UgZXZpZGVuY2UuKSBUaiBFVAplbmRzdHJlYW0KZW5kb2JqCnhyZWYKMCA2CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKMDAwMDAwMDE4NSAwMDAwMCBuIAowMDAwMDAwMzQ4IDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgNiAvUm9vdCAxIDAgUiA+PgpzdGFydHhyZWYKNDY2CiUlRU9GCg==",
"locator": {
"type": "pdf",
"page": 1,
"mapping": "exact",
"bbox": [
0.125,
0.1456,
0.7203,
0.1716
],
"source_id": "pdf:1:0:36",
"quote": "Cropped and rotated source evidence."
}
},
{
"name": "PDFium CropBox and rotation 90",
"page": 1,
"pdf": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFs0IDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago0IDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgNjAwIDgwMF0gL1JvdGF0ZSA5MCAvQ3JvcEJveCBbMTAwIDEwMCA1MDAgNzAwXSAvUmVzb3VyY2VzIDw8IC9Gb250IDw8IC9GMSAzIDAgUiA+PiA+PiAvQ29udGVudHMgNSAwIFIgPj4KZW5kb2JqCjUgMCBvYmoKPDwgL0xlbmd0aCA2OCA+PgpzdHJlYW0KQlQgL0YxIDE0IFRmIDE1MCA2MDAgVGQgKENyb3BwZWQgYW5kIHJvdGF0ZWQgc291cmNlIGV2aWRlbmNlLikgVGogRVQKZW5kc3RyZWFtCmVuZG9iagp4cmVmCjAgNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMDkgMDAwMDAgbiAKMDAwMDAwMDA1OCAwMDAwMCBuIAowMDAwMDAwMTE1IDAwMDAwIG4gCjAwMDAwMDAxODUgMDAwMDAgbiAKMDAwMDAwMDM0OSAwMDAwMCBuIAp0cmFpbGVyCjw8IC9TaXplIDYgL1Jvb3QgMSAwIFIgPj4Kc3RhcnR4cmVmCjQ2NwolJUVPRgo=",
"locator": {
"type": "pdf",
"page": 1,
"mapping": "exact",
"bbox": [
0.8284,
0.125,
0.8544,
0.7203
],
"source_id": "pdf:1:0:36",
"quote": "Cropped and rotated source evidence."
}
},
{
"name": "PDFium CropBox and rotation 180",
"page": 1,
"pdf": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFs0IDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago0IDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgNjAwIDgwMF0gL1JvdGF0ZSAxODAgL0Nyb3BCb3ggWzEwMCAxMDAgNTAwIDcwMF0gL1Jlc291cmNlcyA8PCAvRm9udCA8PCAvRjEgMyAwIFIgPj4gPj4gL0NvbnRlbnRzIDUgMCBSID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjggPj4Kc3RyZWFtCkJUIC9GMSAxNCBUZiAxNTAgNjAwIFRkIChDcm9wcGVkIGFuZCByb3RhdGVkIHNvdXJjZSBldmlkZW5jZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMTg1IDAwMDAwIG4gCjAwMDAwMDAzNTAgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0NjgKJSVFT0YK",
"locator": {
"type": "pdf",
"page": 1,
"mapping": "exact",
"bbox": [
0.2797,
0.8284,
0.875,
0.8544
],
"source_id": "pdf:1:0:36",
"quote": "Cropped and rotated source evidence."
}
},
{
"name": "PDFium CropBox and rotation 270",
"page": 1,
"pdf": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9Db3VudCAxIC9LaWRzIFs0IDAgUl0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL0ZvbnQgL1N1YnR5cGUgL1R5cGUxIC9CYXNlRm9udCAvSGVsdmV0aWNhID4+CmVuZG9iago0IDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMiAwIFIgL01lZGlhQm94IFswIDAgNjAwIDgwMF0gL1JvdGF0ZSAyNzAgL0Nyb3BCb3ggWzEwMCAxMDAgNTAwIDcwMF0gL1Jlc291cmNlcyA8PCAvRm9udCA8PCAvRjEgMyAwIFIgPj4gPj4gL0NvbnRlbnRzIDUgMCBSID4+CmVuZG9iago1IDAgb2JqCjw8IC9MZW5ndGggNjggPj4Kc3RyZWFtCkJUIC9GMSAxNCBUZiAxNTAgNjAwIFRkIChDcm9wcGVkIGFuZCByb3RhdGVkIHNvdXJjZSBldmlkZW5jZS4pIFRqIEVUCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDYKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDA5IDAwMDAwIG4gCjAwMDAwMDAwNTggMDAwMDAgbiAKMDAwMDAwMDExNSAwMDAwMCBuIAowMDAwMDAwMTg1IDAwMDAwIG4gCjAwMDAwMDAzNTAgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSA2IC9Sb290IDEgMCBSID4+CnN0YXJ0eHJlZgo0NjgKJSVFT0YK",
"locator": {
"type": "pdf",
"page": 1,
"mapping": "exact",
"bbox": [
0.1456,
0.2797,
0.1716,
0.875
],
"source_id": "pdf:1:0:36",
"quote": "Cropped and rotated source evidence."
}
}
]

View File

@ -0,0 +1,20 @@
/** Tiny real PDF fixture, generated without a PDF library or network service. */
export function fixturePdf(pages: Array<{ lines: Array<[string, number, number]>; rotation?: number }>): ArrayBuffer {
const objects: string[] = []
objects[0] = '<< /Type /Catalog /Pages 2 0 R >>'
objects[1] = `<< /Type /Pages /Count ${pages.length} /Kids [${pages.map((_, i) => `${4 + i * 2} 0 R`).join(' ')}] >>`
objects[2] = '<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>'
pages.forEach((page, i) => {
const stream = page.lines.map(([text, x, y]) => `BT /F1 14 Tf ${x} ${y} Td (${text.replace(/[\\()]/g, '\\$&')}) Tj ET`).join('\n')
objects[3 + i * 2] = `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 600 800] /Rotate ${page.rotation || 0} /Resources << /Font << /F1 3 0 R >> >> /Contents ${5 + i * 2} 0 R >>`
objects[4 + i * 2] = `<< /Length ${stream.length} >>\nstream\n${stream}\nendstream`
})
let pdf = '%PDF-1.4\n'
const offsets = [0]
objects.forEach((object, i) => { offsets.push(pdf.length); pdf += `${i + 1} 0 obj\n${object}\nendobj\n` })
const xref = pdf.length
pdf += `xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`
pdf += offsets.slice(1).map((offset) => `${String(offset).padStart(10, '0')} 00000 n \n`).join('')
pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF`
return new TextEncoder().encode(pdf).buffer
}

View File

@ -414,6 +414,7 @@ func (r *chunkRepository) SaveChunkRevision(
Updates(map[string]interface{}{
"content": common.CleanInvalidUTF8(chunk.Content),
"source_content": common.CleanInvalidUTF8(chunk.SourceContent),
"source_locators": chunk.SourceLocators,
"content_revision": chunk.ContentRevision,
"is_enabled": chunk.IsEnabled,
"metadata": chunk.Metadata,

View File

@ -23,9 +23,20 @@ func TestSaveChunkRevisionIsAtomicAndOptimistic(t *testing.T) {
chunk := &types.Chunk{
ID: uuid.NewString(), TenantID: 1, KnowledgeBaseID: "kb", KnowledgeID: "knowledge",
Content: "before", SourceContent: "before", ChunkType: types.ChunkTypeText,
SourceLocators: types.SourceLocators{{
Type: "pdf",
Page: 1,
Mapping: "exact",
SourceID: "block:1",
SourceHash: "revision-one",
Partial: true,
}},
IsEnabled: true, IndexStatus: "ready", CreatedAt: now, UpdatedAt: now,
}
require.NoError(t, repo.CreateChunks(ctx, []*types.Chunk{chunk}))
initial, err := repo.GetChunkByID(ctx, 1, chunk.ID)
require.NoError(t, err)
require.Equal(t, chunk.SourceLocators, initial.SourceLocators)
snapshot := &types.ChunkRevision{
ID: uuid.NewString(), TenantID: 1, KnowledgeBaseID: "kb", KnowledgeID: "knowledge",
@ -33,12 +44,14 @@ func TestSaveChunkRevisionIsAtomicAndOptimistic(t *testing.T) {
EditSource: "user", EditedAt: now, CreatedAt: now,
}
chunk.Content = "after"
chunk.SourceLocators = nil
chunk.ContentRevision = 1
require.NoError(t, repo.SaveChunkRevision(ctx, chunk, snapshot, 0))
stored, err := repo.GetChunkByID(ctx, 1, chunk.ID)
require.NoError(t, err)
require.Equal(t, "after", stored.Content)
require.Empty(t, stored.SourceLocators)
require.Equal(t, 1, stored.ContentRevision)
revisions, err := repo.ListChunkRevisions(ctx, 1, chunk.ID)
require.NoError(t, err)
@ -55,6 +68,7 @@ func TestSaveChunkRevisionIsAtomicAndOptimistic(t *testing.T) {
stored, err = repo.GetChunkByID(ctx, 1, chunk.ID)
require.NoError(t, err)
require.Equal(t, "after", stored.Content)
require.Empty(t, stored.SourceLocators)
count := int64(0)
require.NoError(t, db.Model(&types.ChunkRevision{}).Count(&count).Error)
require.Equal(t, int64(1), count)

View File

@ -0,0 +1,192 @@
package chatpipeline
import (
"context"
"sort"
"strings"
"github.com/Tencent/WeKnora/internal/searchutil"
"github.com/Tencent/WeKnora/internal/types"
)
// Ranking works on expanded contexts. The model must instead see every source
// body under its own ID; a parent's neighbouring paragraph is not child evidence.
func (p *PluginMerge) attachCitationSources(ctx context.Context, results []*types.SearchResult) {
if p.chunkRepo == nil {
return
}
ids := map[string]bool{}
for _, r := range results {
if len(r.SubChunkID) > 0 {
r.ContentRewritten = true
}
if r.ContentRewritten {
ids[r.ID] = true
for _, id := range r.SubChunkID {
ids[id] = true
}
}
}
if len(ids) == 0 {
return
}
keys := make([]string, 0, len(ids))
for id := range ids {
keys = append(keys, id)
}
chunks, err := p.chunkRepo.ListChunksByIDOnly(ctx, keys)
if err != nil {
return
}
byID := map[string]*types.Chunk{}
parents := map[string]bool{}
for _, c := range chunks {
byID[c.ID] = c
if c.ParentChunkID != "" {
parents[c.ParentChunkID] = true
}
}
keys = nil
for id := range parents {
keys = append(keys, id)
}
// Image -> text -> parent_text. Fetch the intermediate text parent before
// collecting siblings. All IDs originate in authorized retrieval results.
if len(keys) > 0 {
ancestors, e := p.chunkRepo.ListChunksByIDOnly(ctx, keys)
if e == nil {
for _, c := range ancestors {
byID[c.ID] = c
if c.ParentChunkID != "" {
parents[c.ParentChunkID] = true
}
}
}
}
keys = nil
for id := range parents {
keys = append(keys, id)
}
if len(keys) > 0 {
siblings, e := p.chunkRepo.ListChunksByParentIDsOnly(ctx, keys)
if e == nil {
for _, c := range siblings {
byID[c.ID] = c
}
}
}
// Fetch actual image children too: enrichment may have placed their OCR in
// a text result, but that OCR needs the image child's own citation identity.
textIDs := []string{}
for _, c := range byID {
if c.ChunkType == types.ChunkTypeText {
textIDs = append(textIDs, c.ID)
}
}
if len(textIDs) > 0 {
images, e := p.chunkRepo.ListChunksByParentIDsOnly(ctx, textIDs)
if e == nil {
for _, c := range images {
if c.ChunkType == types.ChunkTypeImageOCR || c.ChunkType == types.ChunkTypeImageCaption {
byID[c.ID] = c
}
}
}
}
for _, r := range results {
if !r.ContentRewritten {
continue
}
allowedParents := map[string]bool{}
for _, id := range append([]string{r.ID}, r.SubChunkID...) {
if c := byID[id]; c != nil {
allowedParents[c.ParentChunkID] = true
if parent := byID[c.ParentChunkID]; parent != nil && parent.ChunkType == types.ChunkTypeText {
allowedParents[parent.ParentChunkID] = true
}
}
}
candidates := []*types.Chunk{}
for _, c := range byID {
if !c.IsEnabled ||
c.KnowledgeID != r.KnowledgeID ||
c.KnowledgeBaseID != r.KnowledgeBaseID ||
c.Content == "" ||
c.ChunkType == types.ChunkTypeParentText {
continue
}
related := c.ID == r.ID || containsID(r.SubChunkID, c.ID) || allowedParents[c.ParentChunkID]
if parent := byID[c.ParentChunkID]; parent != nil && (c.ChunkType == types.ChunkTypeImageOCR ||
c.ChunkType == types.ChunkTypeImageCaption) {
related = related || allowedParents[parent.ParentChunkID]
}
if !related {
continue
}
body := searchutil.PruneMarkdownImagesByImageInfo(c.Content, r.ImageInfo)
imageHit := false
if c.ChunkType == types.ChunkTypeImageOCR || c.ChunkType == types.ChunkTypeImageCaption {
imageHit = searchutil.FilterImageInfoByContentURLs(r.Content, c.ImageInfo) != ""
}
if c.ID == r.ID ||
containsID(r.SubChunkID,
c.ID) ||
imageHit ||
(strings.TrimSpace(body) != "" && strings.Contains(r.Content,
body)) {
candidates = append(candidates, c)
}
}
sort.Slice(candidates, func(i, j int) bool {
if candidates[i].ChunkIndex != candidates[j].ChunkIndex {
return candidates[i].ChunkIndex < candidates[j].ChunkIndex
}
return candidates[i].ID < candidates[j].ID
})
for _, c := range candidates {
source := *r
source.ID = c.ID
source.Content = c.Content
source.ChunkIndex = c.ChunkIndex
source.ChunkType = string(c.ChunkType)
source.ParentChunkID = c.ParentChunkID
source.SourceLocators = c.SourceLocators
source.ImageInfo = c.ImageInfo
source.StartAt = c.StartAt
source.EndAt = c.EndAt
source.ContentRevision = c.ContentRevision
source.ContextHeader = c.ContextHeader
source.ChunkMetadata = c.Metadata
source.MatchedContent = ""
source.ContentRewritten = false
source.SubChunkID = nil
source.CitationSources = nil
r.CitationSources = append(r.CitationSources, &source)
}
}
}
func expandCitationSources(results []*types.SearchResult) []*types.SearchResult {
out := make([]*types.SearchResult, 0, len(results))
seen := map[string]bool{}
for _, r := range results {
if r == nil {
continue
}
sources := r.CitationSources
if len(sources) == 0 && r.ContentRewritten {
// A failed source lookup must not relabel expanded context as evidence.
continue
}
if len(sources) == 0 {
sources = []*types.SearchResult{r}
}
for _, s := range sources {
if !seen[s.ID] {
seen[s.ID] = true
out = append(out, s)
}
}
}
return out
}

View File

@ -0,0 +1,138 @@
package chatpipeline
import (
"context"
"testing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
func TestExpandedContextHasSeparateCitationBodies(t *testing.T) {
a := &types.Chunk{
ID: "a",
KnowledgeID: "doc",
KnowledgeBaseID: "kb",
Content: "Opening greeting.",
ParentChunkID: "p",
ChunkType: types.ChunkTypeText,
IsEnabled: true,
}
b := &types.Chunk{
ID: "b",
KnowledgeID: "doc",
KnowledgeBaseID: "kb",
Content: "Exact later quotation.",
ParentChunkID: "p",
ChunkType: types.ChunkTypeText,
IsEnabled: true,
ChunkIndex: 1,
}
disabled := &types.Chunk{
ID: "disabled",
KnowledgeID: "doc",
KnowledgeBaseID: "kb",
Content: "Exact later quotation.",
ParentChunkID: "p",
ChunkType: types.ChunkTypeText,
}
foreign := &types.Chunk{
ID: "foreign",
KnowledgeID: "other",
KnowledgeBaseID: "kb",
Content: "Opening greeting.",
IsEnabled: true,
}
repo := &expandChunkRepo{
chunks: map[string]*types.Chunk{
"a": a,
"p": {
ID: "p",
ChunkType: types.ChunkTypeParentText,
},
},
children: map[string][]*types.Chunk{"p": {
a,
b,
disabled,
foreign,
}},
}
p := &PluginMerge{chunkRepo: repo}
merged := &types.SearchResult{
ID: "a",
KnowledgeID: "doc",
KnowledgeBaseID: "kb",
Content: "Opening greeting.\n\nExact later quotation.",
ContentRewritten: true,
}
p.attachCitationSources(context.Background(), []*types.SearchResult{merged})
got := expandCitationSources([]*types.SearchResult{merged, merged})
require.Len(t, got, 2)
require.Equal(t, "a", got[0].ID)
require.Equal(t, a.Content, got[0].Content)
require.Equal(t, "b", got[1].ID)
require.Equal(t, b.Content, got[1].Content)
require.Empty(t, got[0].SubChunkID)
}
func TestExpandedEvidenceFailsClosedAndPreservesPlainSources(t *testing.T) {
got := expandCitationSources([]*types.SearchResult{
{
ID: "expanded",
Content: "parent text under child ID",
ContentRewritten: true,
},
{
ID: "plain",
Content: "actual source",
},
})
require.Len(t, got, 1)
require.Equal(t, "plain", got[0].ID)
}
func TestModelHandlesReferenceTheActualExpandedChild(t *testing.T) {
a := &types.SearchResult{
ID: "opening",
KnowledgeID: "doc",
KnowledgeBaseID: "kb",
KnowledgeTitle: "Report",
Content: "Opening greeting.",
}
b := &types.SearchResult{
ID: "later",
KnowledgeID: "doc",
KnowledgeBaseID: "kb",
KnowledgeTitle: "Report",
ChunkIndex: 1,
Content: "Exact later quotation.",
}
rendered := "old expanded context"
manage := &types.ChatManage{
PipelineRequest: types.PipelineRequest{
Query: "question",
SummaryConfig: types.SummaryConfig{Prompt: "system"},
},
PipelineState: types.PipelineState{
RenderedContexts: rendered,
UserContent: rendered,
MergeResult: []*types.SearchResult{{
ID: "opening",
ContentRewritten: true,
CitationSources: []*types.SearchResult{
a,
b,
},
}},
},
}
messages, registry := prepareMessagesWithModelContext(context.Background(), manage)
require.Contains(t, messages[1].Content, `<chunk id="c2"`)
require.Contains(t, registry.DecodeOutputText(`<ref id="c2"/>`), `chunk_id="later"`)
require.Contains(t, registry.DecodeOutputText(`<ref id="c1"/>`), `chunk_id="opening"`)
manage.MergeResult[0].CitationSources = nil
messages, _ = prepareMessagesWithModelContext(context.Background(), manage)
require.NotContains(t, messages[1].Content, rendered)
require.Contains(t, messages[1].Content, "could not be verified")
}

View File

@ -92,6 +92,7 @@ func (p *PluginMerge) OnEvent(ctx context.Context,
mergedChunks = p.dedup(ctx, "final_dedup", mergedChunks)
mergedChunks = removePartialOverlaps(ctx, mergedChunks)
p.attachCitationSources(ctx, mergedChunks)
chatManage.MergeResult = mergedChunks
return next()
}

View File

@ -30,7 +30,7 @@ func prepareMessagesWithModelContext(
return messages, registry
}
ordered := orderedPipelineReferences(chatManage)
ordered := expandCitationSources(orderedPipelineReferences(chatManage))
knowledgeResults := make([]*types.SearchResult, 0, len(ordered))
knowledgeRows := make([]map[string]interface{}, 0, len(ordered))
webRows := make([]map[string]interface{}, 0)
@ -80,7 +80,8 @@ func prepareMessagesWithModelContext(
}
modelContexts := strings.Join(contextParts, "\n")
if strings.TrimSpace(modelContexts) == "" {
return messages, registry
modelContexts = "Retrieved source bodies could not be verified. Do not cite or infer facts from " +
"unavailable retrieval evidence."
}
last := len(messages) - 1

View File

@ -568,6 +568,10 @@ func (s *chunkService) UpdateDocumentChunk(
chunk.SourceContent = chunk.Content
}
bodyChanged := newContent != chunk.Content
if bodyChanged {
// Edited evidence no longer maps to the uploaded original.
chunk.SourceLocators = nil
}
chunk.Content = newContent
chunk.IsEnabled = newEnabled
chunk.ContentRevision++
@ -747,6 +751,7 @@ func (s *chunkService) rebuildParentContent(ctx context.Context, edited *types.C
for _, repl := range replacements {
baseRunes = append(append(append([]rune{}, baseRunes[:repl.start]...), []rune(repl.content)...), baseRunes[repl.end:]...)
}
parent.SourceLocators = nil // Child edits invalidate the original parent evidence.
parent.Content = string(baseRunes)
for _, conflict := range conflicts {
parent.Content = searchutil.JoinChunkContent(parent.Content, conflict.content, "\n\n")

View File

@ -157,7 +157,8 @@ func TestUpdateDocumentChunkPreservesGeneratedQuestionsAcrossRevision(t *testing
repo := &editableChunkRepo{chunk: &types.Chunk{
ID: "chunk", TenantID: 1, KnowledgeID: "knowledge", KnowledgeBaseID: "kb",
Content: "old body", SourceContent: "old body", ContentRevision: 0,
ChunkType: types.ChunkTypeText, IsEnabled: true, IndexStatus: "ready", Metadata: metadataJSON,
SourceLocators: types.SourceLocators{{Type: "pdf", Page: 1, Mapping: "exact", Quote: "old body"}},
ChunkType: types.ChunkTypeText, IsEnabled: true, IndexStatus: "ready", Metadata: metadataJSON,
}}
service := &chunkService{
chunkRepository: repo,
@ -182,6 +183,9 @@ func TestUpdateDocumentChunkPreservesGeneratedQuestionsAcrossRevision(t *testing
if err != nil {
t.Fatalf("update chunk: %v", err)
}
if len(updated.SourceLocators) != 0 {
t.Fatal("edited content retained source positions from the original")
}
updatedMetadata, err := updated.DocumentMetadata()
if err != nil {
t.Fatal(err)
@ -219,6 +223,7 @@ func TestRebuildParentContentPreservesConflictingEdits(t *testing.T) {
parent: &types.Chunk{
ID: "parent", TenantID: 1, ChunkType: types.ChunkTypeParentText,
SourceContent: "abcdefghij", Content: "abcdefghij", StartAt: 0, EndAt: 10,
SourceLocators: types.SourceLocators{{Type: "pdf", Page: 1}},
},
children: []*types.Chunk{
{
@ -240,6 +245,9 @@ func TestRebuildParentContentPreservesConflictingEdits(t *testing.T) {
if repo.updated == nil {
t.Fatal("parent was not updated")
}
if len(repo.updated.SourceLocators) != 0 {
t.Fatal("rebuilt parent retained stale source positions")
}
for _, want := range []string{"OLDER EDIT BODY", "NEWER EDIT BODY"} {
if !strings.Contains(repo.updated.Content, want) {
t.Fatalf("rebuilt parent lost %q: %q", want, repo.updated.Content)

View File

@ -0,0 +1,30 @@
package service
import (
"context"
"errors"
"net"
"strings"
werrors "github.com/Tencent/WeKnora/internal/errors"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
// Keep actionable public messages separate from raw transport diagnostics,
// which may contain internal addresses or credentials and belong in error_detail.
func docReaderFailure(err error) (code, message string) {
if errors.Is(err, context.DeadlineExceeded) || status.Code(err) == codes.DeadlineExceeded ||
strings.Contains(err.Error(), "docreader call timeout") {
return werrors.ErrCodeDocReaderTimeout,
"Document parsing service timed out. Check service health and load before retrying."
}
var networkError *net.OpError
if status.Code(err) == codes.Unavailable || errors.As(err, &networkError) {
return werrors.ErrCodeDocReaderUnavailable,
"Cannot connect to the document parsing service, or the connection was interrupted. " +
"Check that DocReader is running and healthy, then retry."
}
return werrors.ErrCodeDocReaderParseFailed,
"Document parsing failed. Check the file format and the DocReader logs for this attempt."
}

View File

@ -0,0 +1,52 @@
package service
import (
"context"
"errors"
"fmt"
"net"
"strings"
"testing"
werrors "github.com/Tencent/WeKnora/internal/errors"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
func TestDocReaderFailure(t *testing.T) {
for _, tc := range []struct {
name string
err error
code string
}{
{
"scanned PDF wrapped connection failure",
fmt.Errorf("anydoc fallback: %w",
fmt.Errorf("read stream: %w",
status.Error(codes.Unavailable,
"private-address secret-token"))),
werrors.ErrCodeDocReaderUnavailable,
},
{
"HTTP connection failure",
&net.OpError{
Op: "dial",
Err: errors.New("private-address secret-token"),
},
werrors.ErrCodeDocReaderUnavailable,
},
{"context timeout", fmt.Errorf("parse: %w", context.DeadlineExceeded), werrors.ErrCodeDocReaderTimeout},
{"RPC timeout", status.Error(codes.DeadlineExceeded, "private-address"), werrors.ErrCodeDocReaderTimeout},
{"parser failure", errors.New("private-address secret-token"), werrors.ErrCodeDocReaderParseFailed},
} {
t.Run(tc.name, func(t *testing.T) {
code, message := docReaderFailure(tc.err)
if code != tc.code || message == "" {
t.Fatalf("got %q %q, want code %q", code, message, tc.code)
}
if strings.Contains(message, "private-address") || strings.Contains(message, "secret-token") {
t.Fatal("raw transport diagnostics leaked into public message")
}
})
}
}

View File

@ -0,0 +1,24 @@
package service
import (
"github.com/Tencent/WeKnora/internal/searchutil"
"github.com/Tencent/WeKnora/internal/types"
)
// A missing association is preferable to attaching evidence to an unrelated
// first paragraph. Exact Markdown targets also avoid URL-prefix collisions.
func imageChunkOwner(url string, chunks []types.ParsedChunk) string {
if url == "" {
return ""
}
owner := ""
for _, c := range chunks {
if c.ChunkID != "" && searchutil.ImageURLsInContent(c.Content)[url] {
if owner != "" && owner != c.ChunkID {
return ""
}
owner = c.ChunkID
}
}
return owner
}

View File

@ -0,0 +1,41 @@
package service
import (
"testing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
func TestImageChunkOwnerUsesExactTargets(t *testing.T) {
chunks := []types.ParsedChunk{
{
ChunkID: "first",
Content: "unrelated",
},
{
ChunkID: "prefix",
Content: "![image](resource://abc-more)",
},
{
ChunkID: "actual",
Content: "![image](resource://abc)",
},
}
require.Equal(t, "actual", imageChunkOwner("resource://abc", chunks))
require.Empty(t, imageChunkOwner("resource://missing", chunks))
require.Empty(t, imageChunkOwner("", chunks))
require.Empty(t,
imageChunkOwner("resource://abc",
append(chunks,
types.ParsedChunk{
ChunkID: "duplicate",
Content: "![same](resource://abc)",
})))
require.Empty(t,
imageChunkOwner("resource://abc",
[]types.ParsedChunk{{
ChunkID: "prose",
Content: "resource://abc",
}}))
}

View File

@ -2,6 +2,7 @@ package service
import (
"context"
"crypto/sha256"
"encoding/json"
"errors"
"fmt"
@ -317,11 +318,13 @@ func (s *ImageMultimodalService) processImage(
logger.Errorf(ctx, "[ImageMultimodal] Skip unreadable image %s: %v", payload.ImageURL, readErr)
out["skipped"] = "unreadable_image"
out["read_error"] = readErr.Error()
return nil
handleErr = fmt.Errorf("read source image: %w", readErr)
return handleErr
}
out["image_bytes"] = len(imgBytes)
imageInfo := types.ImageInfo{
SHA256: fmt.Sprintf("%x", sha256.Sum256(imgBytes)),
URL: payload.ImageURL,
OriginalURL: payload.ImageURL,
}

View File

@ -3,7 +3,9 @@ package service
import (
"bytes"
"context"
"crypto/sha256"
"encoding/json"
"errors"
"fmt"
"io"
"strings"
@ -333,6 +335,15 @@ func TestProcessImageObservesAndDescribes(t *testing.T) {
if len(repo.created) != 2 {
t.Fatalf("persisted chunks = %d, want OCR + caption", len(repo.created))
}
for _, chunk := range repo.created {
var images []types.ImageInfo
if err := json.Unmarshal([]byte(chunk.ImageInfo), &images); err != nil || len(images) != 1 {
t.Fatalf("invalid image info: %v", err)
}
if images[0].SHA256 != fmt.Sprintf("%x", sha256.Sum256(fileSvc.body)) {
t.Fatal("stored image fingerprint does not identify the bytes sent to OCR")
}
}
if got := persistedAttrCounts(t, repo.created, "contain.text"); !equalCounts(got, map[string]int{"block": 2}) {
t.Errorf("persisted contain.text = %v, want block on both chunks", got)
}
@ -553,6 +564,15 @@ func TestProcessImageProseAnswerIsStillCaptionedAndOCRed(t *testing.T) {
if len(repo.created) != 2 {
t.Fatalf("persisted chunks = %d, want OCR + caption", len(repo.created))
}
for _, chunk := range repo.created {
var images []types.ImageInfo
if err := json.Unmarshal([]byte(chunk.ImageInfo), &images); err != nil || len(images) != 1 {
t.Fatalf("invalid image info: %v", err)
}
if images[0].SHA256 != fmt.Sprintf("%x", sha256.Sum256(fileSvc.body)) {
t.Fatal("stored image fingerprint does not identify the bytes sent to OCR")
}
}
}
// TestProcessImageLabelOnlyAnswerKeepsAttrsWithoutCaption covers the one reply
@ -654,11 +674,19 @@ func TestProcessImageCaptionOCRPipeline(t *testing.T) {
if len(repo.created) != 2 {
t.Fatalf("persisted chunks = %d, want OCR + caption", len(repo.created))
}
for _, chunk := range repo.created {
var images []types.ImageInfo
if err := json.Unmarshal([]byte(chunk.ImageInfo), &images); err != nil || len(images) != 1 {
t.Fatalf("invalid image info: %v", err)
}
if images[0].SHA256 != fmt.Sprintf("%x", sha256.Sum256(fileSvc.body)) {
t.Fatal("stored image fingerprint does not identify the bytes sent to OCR")
}
}
}
// TestProcessImageSkipsUnreadableImage checks that an unreadable object is
// reported and counted rather than failing the task.
func TestProcessImageSkipsUnreadableImage(t *testing.T) {
// Unreadable storage must return its cause so Handle retries before finalizing.
func TestProcessImageReturnsUnreadableImageError(t *testing.T) {
t.Parallel()
fileSvc := &attrsFileService{err: fmt.Errorf("object is gone")}
@ -678,7 +706,12 @@ func TestProcessImageSkipsUnreadableImage(t *testing.T) {
ImageActions: types.DefaultImageActions(),
}
out := runProcessImage(t, svc, payload, fake)
out := types.JSONMap{}
err := svc.processImage(context.Background(), payload, fake, types.VLMConfig{}, noopSpanTracker{}, out)
if !errors.Is(err, fileSvc.err) {
t.Fatalf("storage error was swallowed: %v", err)
}
if got := out["skipped"]; got != "unreadable_image" {
t.Errorf("skipped = %v, want unreadable_image", got)
}

View File

@ -3872,6 +3872,9 @@ func (s *knowledgeService) ProcessDocument(ctx context.Context, t *asynq.Task) e
if convertResult != nil {
parsedMarkdown = convertResult.MarkdownContent
sourceBlocks = convertResult.SourceBlocks
for i := range sourceBlocks {
sourceBlocks[i].Locator.SourceHash = knowledge.FileHash
}
}
sanitizeReadResult(convertResult)
if convertResult != nil {
@ -4109,16 +4112,11 @@ func (s *knowledgeService) convert(
result, err := s.callDocReaderWithTimeout(ctx, reader, req)
if err != nil {
// Distinguish DocReader timeout (a knowable user-facing
// failure) from generic read errors so the UI can suggest
// "split this large file" specifically when relevant.
code := werrors.ErrCodeDocReaderParseFailed
if errors.Is(err, context.DeadlineExceeded) || strings.Contains(err.Error(), "docreader call timeout") {
code = werrors.ErrCodeDocReaderTimeout
}
code, message := docReaderFailure(err)
logger.Errorf(ctx, "[convert] DocReader failed knowledge=%s code=%s: %v", knowledge.ID, code, err)
s.failStage(ctx, knowledge.ID, types.StageDocReader,
code, "document read failed", err)
return s.failKnowledge(ctx, knowledge, isLastRetry, "document read failed: %v", err)
code, message, err)
return s.failKnowledge(ctx, knowledge, isLastRetry, "%s", message)
}
sanitizeReadResult(result)
if result.Error != "" {
@ -4292,15 +4290,9 @@ func (s *knowledgeService) enqueueImageMultimodalTasks(
for idx, img := range images {
// Match image to the ParsedChunk whose content contains the image URL.
// ChunkID was populated by processChunks with the real DB UUID.
chunkID := ""
for _, c := range chunks {
if strings.Contains(c.Content, img.ServingURL) {
chunkID = c.ChunkID
break
}
}
if chunkID == "" && len(chunks) > 0 {
chunkID = chunks[0].ChunkID
chunkID := imageChunkOwner(img.ServingURL, chunks)
if chunkID == "" {
logger.Warnf(ctx, "Image has no owning text chunk: knowledge=%s image=%s", knowledge.ID, img.ServingURL)
}
payload := types.ImageMultimodalPayload{

View File

@ -105,7 +105,7 @@ func (p *GRPCDocumentReader) Close() error {
return nil
}
var errNotConnected = fmt.Errorf("docreader service not connected")
var errNotConnected = status.Error(codes.Unavailable, "docreader service not connected")
func (p *GRPCDocumentReader) Read(ctx context.Context, req *types.ReadRequest) (*types.ReadResult, error) {
p.mu.RLock()

View File

@ -4,6 +4,9 @@ import (
"archive/zip"
"bytes"
"encoding/json"
"fmt"
"html"
"math"
"regexp"
"sort"
"strings"
@ -20,7 +23,7 @@ const minerUBBoxScale = 1000.0
type minerUContentItem struct {
Type string `json:"type"`
Text string `json:"text"`
PageIdx int `json:"page_idx"`
PageIdx *int `json:"page_idx"`
BBox []float64 `json:"bbox"`
TableBody string `json:"table_body"`
TableCaption json.RawMessage `json:"table_caption"`
@ -82,8 +85,8 @@ func decodeMinerUContentList(raw []byte) []minerUContentItem {
return items
}
// minerUContentListFromZip returns the shallowest *content_list.json of a
// MinerU result package, or nil.
// minerUContentListFromZip prefers supported MiddleJson 2.0 geometry and
// falls back to legacy content_list.json for older MinerU packages.
func minerUContentListFromZip(zipData []byte) []byte {
zr, err := zip.NewReader(bytes.NewReader(zipData), int64(len(zipData)))
if err != nil {
@ -92,7 +95,7 @@ func minerUContentListFromZip(zipData []byte) []byte {
var candidates []*zip.File
for _, f := range zr.File {
name := strings.ToLower(f.Name)
if strings.HasSuffix(name, "content_list.json") && !strings.Contains(name, "content_list_v2") {
if strings.HasSuffix(name, "middle_json.json") || strings.HasSuffix(name, "content_list.json") {
candidates = append(candidates, f)
}
}
@ -100,13 +103,34 @@ func minerUContentListFromZip(zipData []byte) []byte {
return nil
}
sort.Slice(candidates, func(i, j int) bool {
return strings.Count(candidates[i].Name, "/") < strings.Count(candidates[j].Name, "/")
mi,
mj := strings.HasSuffix(strings.ToLower(candidates[i].Name),
"middle_json.json"),
strings.HasSuffix(strings.ToLower(candidates[j].Name),
"middle_json.json")
if mi != mj {
return mi
}
di, dj := strings.Count(candidates[i].Name, "/"), strings.Count(candidates[j].Name, "/")
if di != dj {
return di < dj
}
return candidates[i].Name < candidates[j].Name
})
data, err := readZipEntryBytes(candidates[0])
if err != nil {
return nil
for _, candidate := range candidates {
data, err := readZipEntryBytes(candidate)
if err != nil {
continue
}
if strings.HasSuffix(strings.ToLower(candidate.Name), "middle_json.json") {
var doc minerUMiddle
if json.Unmarshal(data, &doc) != nil || doc.Schema != "docvortex.middle" || doc.Version != "2.0" {
continue
}
}
return data
}
return data
return nil
}
// minerUSourceBlocks aligns MinerU's layout blocks against its markdown so
@ -119,13 +143,26 @@ func minerUSourceBlocks(markdown string, contentList []byte, fileType string) []
if ft != "pdf" && !IsImageFormat(ft) {
return nil
}
raw := bytes.TrimSpace(contentList)
if len(raw) > 0 && raw[0] == '{' {
return minerUMiddleSourceBlocks(markdown, raw)
}
items := decodeMinerUContentList(contentList)
if len(items) == 0 {
return nil
}
units := make([]sourceloc.Unit, 0, len(items))
for _, it := range items {
loc := types.SourceLocator{Type: types.SourceLocatorPDF, Page: it.PageIdx + 1}
for i, it := range items {
if it.PageIdx == nil || *it.PageIdx < 0 {
continue
}
loc := types.SourceLocator{
Type: types.SourceLocatorPDF,
Page: *it.PageIdx + 1,
SourceID: fmt.Sprintf("mineru:legacy:%d:%d",
*it.PageIdx,
i),
}
if bbox, ok := minerUBBox(it.BBox); ok {
loc.BBox = bbox
}
@ -142,7 +179,7 @@ func minerUBBox(b []float64) ([]float64, bool) {
return nil, false
}
for _, v := range b {
if v < 0 || v > minerUBBoxScale {
if math.IsNaN(v) || math.IsInf(v, 0) || v < 0 || v > minerUBBoxScale {
return nil, false
}
}
@ -152,3 +189,110 @@ func minerUBBox(b []float64) ([]float64, bool) {
}
return out, true
}
// MiddleJson 2.0 uses [0,1] normalized boxes (NOT legacy 0..1000).
// Child annotations keep their own geometry. Inline spans have no geometry.
type minerUMiddleBlock struct {
Type string `json:"type"`
Index *int `json:"index"`
BBox []float64 `json:"bbox"`
Content json.RawMessage `json:"content"`
}
type minerUMiddle struct {
Schema string `json:"schema"`
Version string `json:"schema_version"`
Pages []struct {
PageIdx *int `json:"page_idx"`
Blocks []minerUMiddleBlock `json:"blocks"`
} `json:"pages"`
}
func minerUMiddleSourceBlocks(markdown string, raw []byte) []types.SourceBlock {
var doc minerUMiddle
if json.Unmarshal(raw, &doc) != nil || doc.Schema != "docvortex.middle" || doc.Version != "2.0" {
return nil
}
var units []sourceloc.Unit
previousPage := -1
for _, page := range doc.Pages {
if page.PageIdx == nil || *page.PageIdx <= previousPage {
return nil
}
previousPage = *page.PageIdx
previousBlock := -1
for _, block := range page.Blocks {
if block.Index == nil || *block.Index <= previousBlock {
return nil
}
previousBlock = *block.Index
ref := fmt.Sprintf("mineru:2:%d:%d", *page.PageIdx, *block.Index)
units = append(units, minerUMiddleUnits(block, *page.PageIdx+1, ref, nil)...)
}
}
return sourceloc.Align(markdown, units)
}
func minerUMiddleUnits(block minerUMiddleBlock, page int, ref string, parentBox []float64) []sourceloc.Unit {
box := block.BBox
if len(box) == 0 {
box = parentBox
}
loc := types.SourceLocator{Type: types.SourceLocatorPDF, Page: page, SourceID: ref}
if normalizedMinerUBox(box) {
loc.BBox = append([]float64(nil), box...)
}
// These containers contain blocks; text and hyperlinks contain inline spans.
switch block.Type {
case "list", "index", "table", "image", "chart", "code":
var children []minerUMiddleBlock
if json.Unmarshal(block.Content, &children) != nil {
return nil
}
var out []sourceloc.Unit
for i, child := range children {
out = append(out, minerUMiddleUnits(child, page, fmt.Sprintf("%s/%d", ref, i), box)...)
}
return out
default:
text := minerUMiddleText(block.Content)
if block.Type == "table_body" || block.Type == "chart_body" {
text = html.UnescapeString(minerUHTMLTagRe.ReplaceAllString(text, " "))
}
if strings.TrimSpace(text) == "" {
return nil
}
return []sourceloc.Unit{{Text: text, Locator: loc}}
}
}
func minerUMiddleText(raw json.RawMessage) string {
var text string
if json.Unmarshal(raw, &text) == nil {
return text
}
var spans []struct {
Type string `json:"type"`
Content json.RawMessage `json:"content"`
}
if json.Unmarshal(raw, &spans) != nil {
return ""
}
var out strings.Builder
for _, span := range spans {
out.WriteString(minerUMiddleText(span.Content))
}
return out.String()
}
func normalizedMinerUBox(box []float64) bool {
if len(box) != 4 || box[0] >= box[2] || box[1] >= box[3] {
return false
}
for _, v := range box {
if math.IsNaN(v) || math.IsInf(v, 0) || v < 0 || v > 1 {
return false
}
}
return true
}

View File

@ -0,0 +1,172 @@
package docparser
import (
"archive/zip"
"bytes"
"encoding/json"
"math"
"testing"
"github.com/stretchr/testify/require"
)
// Contract fixture for DocVortex MiddleJson 2.0. Bboxes are normalized
// fractions, page indices are original source indices, and captions are
// child blocks. This is deliberately not a legacy content_list payload.
const middleFixture = `{
"schema": "docvortex.middle",
"schema_version": "2.0",
"is_full_document": true,
"metadata": {
"file_suffix": "pdf",
"producer": {
"name": "mineru",
"version": "4.0.0"
}
},
"pages": [
{
"page_idx": 4,
"blocks": [
{
"type": "text",
"index": 0,
"bbox": [
0.1,
0.2,
0.9,
0.3
],
"content": [
{
"type": "text",
"content": "设备"
},
{
"type": "hyperlink",
"url": "https://example.org",
"content": [
{
"type": "text",
"content": "验收合格"
}
]
}
]
},
{
"type": "table",
"index": 1,
"bbox": [
0.1,
0.4,
0.9,
0.8
],
"content": [
{
"type": "table_caption",
"bbox": [
0.1,
0.4,
0.9,
0.45
],
"content": [
{
"type": "text",
"content": "设备参数表"
}
]
},
{
"type": "table_body",
"bbox": [
0.1,
0.46,
0.9,
0.8
],
"content": "<table><tr><td>限值</td><td>1.5毫米</td></tr></table>"
}
]
}
]
}
]
}`
func TestMinerUMiddleNormalizedGeometryAndNestedBlocks(t *testing.T) {
blocks := minerUSourceBlocks("设备验收合格\n\n设备参数表\n\n|限值|1.5毫米|", []byte(middleFixture), "pdf")
require.Len(t, blocks, 3)
require.Equal(t, 5, blocks[0].Locator.Page)
require.Equal(t, []float64{0.1, 0.2, 0.9, 0.3}, blocks[0].Locator.BBox)
require.Equal(t, "mineru:2:4:0", blocks[0].Locator.SourceID)
require.Equal(t, "exact", blocks[0].Locator.Mapping)
require.Equal(t, []float64{0.1, 0.46, 0.9, 0.8}, blocks[2].Locator.BBox)
}
func TestMinerUMiddleZIPPreferredToLegacy(t *testing.T) {
var buf bytes.Buffer
z := zip.NewWriter(&buf)
for name, body := range map[string]string{
"markdown.md": "设备验收合格",
"middle_json.json": middleFixture,
"doc_content_list.json": "[]",
} {
w, err := z.Create(name)
require.NoError(t, err)
_, err = w.Write([]byte(body))
require.NoError(t, err)
}
require.NoError(t, z.Close())
require.JSONEq(t, middleFixture, string(minerUContentListFromZip(buf.Bytes())))
}
func TestMinerUMiddleRejectsUnknownSchemaAndInvalidIndices(t *testing.T) {
for _, mutate := range []func(map[string]any){
func(d map[string]any) { d["schema"] = "docvortex.model" },
func(d map[string]any) { d["schema_version"] = "9.0" },
func(d map[string]any) { delete(d["pages"].([]any)[0].(map[string]any), "page_idx") },
func(d map[string]any) { d["pages"].([]any)[0].(map[string]any)["page_idx"] = -1 },
} {
var d map[string]any
require.NoError(t, json.Unmarshal([]byte(middleFixture), &d))
mutate(d)
raw, err := json.Marshal(d)
require.NoError(t, err)
require.Empty(t, minerUSourceBlocks("设备验收合格", raw, "pdf"))
}
}
func TestMinerULegacyMissingPageIsNotPageOne(t *testing.T) {
require.Empty(t, minerUSourceBlocks("设备验收合格", []byte(`[{"type":"text","text":"设备验收合格"}]`), "pdf"))
}
func TestMinerUBoxesRejectNonFiniteAndWrongUnits(t *testing.T) {
for _, box := range [][]float64{{0, 0, math.NaN(), 1}, {0, 0, math.Inf(1), 1}, {0, 0, 900, 600}, {.9, 0, .1, 1}} {
require.False(t, normalizedMinerUBox(box))
}
_, ok := minerUBBox([]float64{0, 0, math.NaN(), 100})
require.False(t, ok)
}
func TestMinerULegacyZIPWithUnsupportedMiddleKeepsContentList(t *testing.T) {
var buf bytes.Buffer
z := zip.NewWriter(&buf)
legacy := `[{"type":"text","text":"设备验收合格","page_idx":1,"bbox":[100,200,900,300]}]`
for name, body := range map[string]string{
"doc_middle_json.json": `{"pdf_info":[]}`,
"doc_content_list.json": legacy,
} {
w, err := z.Create(name)
require.NoError(t, err)
_, err = w.Write([]byte(body))
require.NoError(t, err)
}
require.NoError(t, z.Close())
blocks := minerUSourceBlocks("设备验收合格", minerUContentListFromZip(buf.Bytes()), "pdf")
require.Len(t, blocks, 1)
require.Equal(t, 2, blocks[0].Locator.Page)
require.Equal(t, []float64{.1, .2, .9, .3}, blocks[0].Locator.BBox)
}

View File

@ -22,6 +22,11 @@ const citationEnabledProtocolPrompt = `
- Source citations are enabled for this answer. Cite a knowledge chunk with exactly <ref id="cN"/> and a web page with exactly <ref id="wN"/>.
- Cite only cN/wN handles backed by tool results for the current task, and only when that source supports the adjacent
claim. Never cite dN/bN.
- Each cN covers only its own supplied text or image evidence, not every chunk of the same document.
For a direct quotation, verify that the quoted words occur in the cited cN. Use the later chunk's handle
when the words occur there; never reuse a document's first handle for unrelated passages.
- OCR watermarks, timestamps and image captions are observations of an image. Do not turn a watermark slogan
into a verified service commitment or a caption into a factual document statement without supporting text.
- Handles in historical answers, tool arguments, or the bound knowledge-base directory are for navigation, not current
evidence. Retrieve the relevant source before citing it.
- MCP results are external sources. Use the wN handle for the matching URL in the system-provided

View File

@ -1,6 +1,7 @@
package sourceloc
import (
"html"
"sort"
"strings"
"unicode"
@ -16,69 +17,95 @@ type Unit struct {
Locator types.SourceLocator
}
const (
// alignKeyRunes is how much of a unit's normalized text is searched for.
alignKeyRunes = 32
// alignMinRunes skips units too short to place reliably.
alignMinRunes = 2
// alignWindowRunes bounds how far past the cursor a unit is searched, so
// a unit the parser dropped cannot drag the cursor across the document.
alignWindowRunes = 20000
)
// Skip units too short to place reliably.
const alignMinRunes = 2
// Align places units, which are in document order, into markdown and returns
// one block per placed unit. A block runs from where its unit was found to
// where the next placed unit starts, so the blocks tile the markdown from the
// first placed unit on. Units are matched on letters and digits only, which
// makes the match indifferent to Markdown syntax, whitespace and
// punctuation the parser added or dropped.
// Align maps complete source units, never extending a hit through unmatched
// content. Unknown gaps must stay unknown: assigning them to the preceding
// block can point a citation at an entirely different page.
func Align(markdown string, units []Unit) []types.SourceBlock {
norm := normalizeMarkdown(markdown)
if norm.text == "" || len(units) == 0 {
return nil
runes := []rune(markdown)
var blocks []types.SourceBlock
cursor, floor := 0, 0
counts := make(map[string]int)
matches := make(map[string][]int)
for _, u := range units {
counts[normalizeKey(u.Text)]++
}
type hit struct {
pos int // rune offset in markdown
unit int
}
var hits []hit
cursor := 0 // byte offset into norm.text
for i, u := range units {
for _, u := range units {
key := normalizeKey(u.Text)
if utf8.RuneCountInString(key) < alignMinRunes {
continue
}
at, width := norm.find(key, cursor)
if at < 0 {
// Repeated source text is safe only when every occurrence is accounted
// for by a source unit in reading order (not a TOC or an omitted block).
positions, known := matches[key]
if !known {
positions = normalizedMatches(norm.text, key)
matches[key] = positions
}
if len(positions) != counts[key] {
continue
}
hits = append(hits, hit{pos: norm.pos[at], unit: i})
cursor = at + width
}
if len(hits) == 0 {
return nil
}
runes := []rune(markdown)
prev := 0
for i := range hits {
hits[i].pos = lineLeadStart(runes, hits[i].pos, prev)
prev = hits[i].pos
}
total := len(runes)
blocks := make([]types.SourceBlock, 0, len(hits))
for i, h := range hits {
end := total
if i+1 < len(hits) {
end = hits[i+1].pos
}
if end <= h.pos {
matchIndex := sort.SearchInts(positions, cursor)
if matchIndex == len(positions) {
continue
}
blocks = append(blocks, types.SourceBlock{Start: h.pos, End: end, Locator: units[h.unit].Locator})
at := positions[matchIndex]
endByte := at + len(key)
start := lineLeadStart(runes, norm.pos[at], floor)
end := norm.end[endByte-1]
// Include trailing markup/URLs on the matched line and blank lines,
// but stop before the next visible text's line. This also preserves
// an image's destination without swallowing another paragraph.
if endByte == len(norm.text) {
end = len(runes)
} else {
next := norm.pos[endByte]
lead := next
for lead > 0 && runes[lead-1] != '\n' {
lead--
}
if lead >= end {
end = lead
}
}
loc := u.Locator
loc.Mapping = "exact"
blocks = append(blocks, types.SourceBlock{Start: start, End: end, Locator: loc})
cursor, floor = endByte, end
}
return blocks
}
// normalizedMatches rejects a number embedded in a different numeric value.
func normalizedMatches(text, key string) []int {
var out []int
if key == "" {
return out
}
first, _ := utf8.DecodeRuneInString(key)
last, _ := utf8.DecodeLastRuneInString(key)
for from := 0; from <= len(text)-len(key); {
i := strings.Index(text[from:], key)
if i < 0 {
break
}
at := from + i
before, _ := utf8.DecodeLastRuneInString(text[:at])
after, _ := utf8.DecodeRuneInString(text[at+len(key):])
left := unicode.IsDigit(first) && (unicode.IsDigit(before) || strings.ContainsRune(".,:/+−-", before))
right := unicode.IsDigit(last) && (unicode.IsDigit(after) || strings.ContainsRune(".,:/%‰", after))
if !left && !right {
out = append(out, at)
}
_, size := utf8.DecodeRuneInString(text[at:])
from = at + size
}
return out
}
// lineLeadStart moves pos back to the start of its line when everything
// before it on the line is markup or numbering ("## ", "| ", "1. ", "(2) "),
// which belongs to the unit but was not part of its text. It never crosses
@ -95,45 +122,13 @@ func lineLeadStart(runes []rune, pos, floor int) int {
return start
}
// normalized is the letters-and-digits projection of a text: text holds the
// normalized retains letters, digits and numeric symbols: text holds the
// kept runes, pos[b] the rune offset in the source of the rune starting at
// byte b of text.
type normalized struct {
text string
pos []int
}
// find searches key (already normalized) at or after byte offset from,
// within the search window. It tries the key's head first and falls back to
// a slice from its middle, so a unit whose opening differs (a list number
// the parser rendered, a leading image) still lands. It returns the byte
// offset of the match and how far the cursor should advance.
func (n normalized) find(key string, from int) (int, int) {
limit := len(n.text)
if w := from + alignWindowRunes*3; w < limit {
limit = w
}
window := n.text[from:limit]
head := firstRunes(key, alignKeyRunes)
if idx := strings.Index(window, head); idx >= 0 {
return from + idx, len(head)
}
runes := []rune(key)
if len(runes) < alignKeyRunes*2 {
return -1, 0
}
mid := string(runes[len(runes)/2 : len(runes)/2+alignKeyRunes])
if idx := strings.Index(window, mid); idx >= 0 {
// Aim at where the unit should begin, not at its middle.
back := len(string(runes[:len(runes)/2]))
start := from + idx - back
start = max(start, from)
for start < from+idx && !utf8.RuneStart(n.text[start]) {
start++
}
return start, idx + len(mid) - (start - from)
}
return -1, 0
end []int
}
// normalizeMarkdown projects markdown onto its letters and digits, skipping
@ -143,6 +138,15 @@ func normalizeMarkdown(markdown string) normalized {
var b strings.Builder
b.Grow(len(markdown))
pos := make([]int, 0, len(markdown))
ends := make([]int, 0, len(markdown))
emit := func(r rune, start, end int) {
before := b.Len()
b.WriteRune(r)
for k := before; k < b.Len(); k++ {
pos = append(pos, start)
ends = append(ends, end)
}
}
runes := []rune(markdown)
for i := 0; i < len(runes); i++ {
r := runes[i]
@ -158,29 +162,77 @@ func normalizeMarkdown(markdown string) normalized {
continue
}
}
if nr, ok := foldRune(r); ok {
start := b.Len()
b.WriteRune(nr)
for k := start; k < b.Len(); k++ {
pos = append(pos, i)
if r == '&' {
if end := indexRune(runes, ';', i+1, 32); end > 0 {
raw := string(runes[i : end+1])
if decoded := html.UnescapeString(raw); decoded != raw {
context := []rune{' '}
if i > 0 {
context[0] = runes[i-1]
}
context = append(context, []rune(decoded)...)
context = append(context, ' ')
if end+1 < len(runes) {
context[len(context)-1] = runes[end+1]
}
for j := 1; j+1 < len(context); j++ {
if nr, ok := matchRune(context, j); ok {
emit(nr, i, end+1)
}
}
i = end
continue
}
}
}
if nr, ok := matchRune(runes, i); ok {
emit(nr, i, i+1)
}
}
return normalized{text: b.String(), pos: pos}
return normalized{text: b.String(), pos: pos, end: ends}
}
// normalizeKey projects plain text onto its letters and digits.
func normalizeKey(text string) string {
var b strings.Builder
b.Grow(len(text))
for _, r := range text {
if nr, ok := foldRune(r); ok {
b.WriteRune(nr)
runes := []rune(text)
for i := range runes {
if r, ok := matchRune(runes, i); ok {
b.WriteRune(r)
}
}
return b.String()
}
// Preserve distinctions such as 1.5/15, -5/5, 5%/5 and <5/>5.
func matchRune(rs []rune, i int) (rune, bool) {
r := rs[i]
if r >= 0xFF01 && r <= 0xFF5E {
r -= 0xFEE0
}
if !strings.ContainsRune(".,:/+−-%‰<>=≤≥≠", r) {
return foldRune(r)
}
before, after := i-1, i+1
for before >= 0 && (rs[before] == ' ' || rs[before] == '\t') {
before--
}
for after < len(rs) && (rs[after] == ' ' || rs[after] == '\t') {
after++
}
prevDigit := before >= 0 && unicode.IsDigit(rs[before])
nextDigit := after < len(rs) && unicode.IsDigit(rs[after])
if ((r == '.' || r == ',' || r == '/' || r == ':') && prevDigit && nextDigit) ||
((r == '-' || r == '+' || r == '−') && nextDigit) ||
((r == '%' || r == '‰') && prevDigit) || strings.ContainsRune("<>=≤≥≠", r) {
if r == '−' {
r = '-'
}
return r, true
}
return foldRune(r)
}
// foldRune keeps letters and digits, lower-cased and with full-width ASCII
// folded to its half-width form.
func foldRune(r rune) (rune, bool) {
@ -212,17 +264,6 @@ func indexRune(runes []rune, r rune, from, limit int) int {
return -1
}
func firstRunes(s string, n int) string {
i := 0
for idx := range s {
if i == n {
return s[:idx]
}
i++
}
return s
}
// SortBlocks orders blocks by start offset.
func SortBlocks(blocks []types.SourceBlock) {
sort.SliceStable(blocks, func(i, j int) bool { return blocks[i].Start < blocks[j].Start })

View File

@ -1,6 +1,7 @@
package sourceloc
import (
"html"
"regexp"
"sort"
"strings"
@ -9,10 +10,6 @@ import (
"github.com/Tencent/WeKnora/internal/types"
)
// MaxLocatorsPerChunk caps how many locators one chunk (or merged search
// result) carries.
const MaxLocatorsPerChunk = 64
// Index answers "which source positions does this range of the final
// Markdown cover" for the chunker's output.
type Index struct {
@ -51,13 +48,18 @@ func (x *Index) Locators(start, end int) types.SourceLocators {
// Blocks before i all end at or before start.
i := sort.Search(len(x.blocks), func(k int) bool { return x.maxEnd[k] > start })
var out types.SourceLocators
covered, partial := start, false
for ; i < len(x.blocks) && x.blocks[i].Start < end; i++ {
b := x.blocks[i]
lo, hi := max(b.Start, start), min(b.End, end)
if hi <= lo {
continue
}
quote := CleanQuote(string(x.runes[lo:hi]))
if lo > covered && normalizeMarkdown(fullQuote(string(x.runes[covered:lo]))).text != "" {
partial = true
}
covered = max(covered, hi)
quote := fullQuote(string(x.runes[lo:hi]))
if quote == "" && b.Locator.Type != types.SourceLocatorPDF {
continue
}
@ -66,8 +68,13 @@ func (x *Index) Locators(start, end int) types.SourceLocators {
loc.Quote = quote
out = AppendLocator(out, loc)
}
if len(out) > MaxLocatorsPerChunk {
out = out[:MaxLocatorsPerChunk]
if covered < end && normalizeMarkdown(fullQuote(string(x.runes[covered:end]))).text != "" {
partial = true
}
if partial {
for i := range out {
out[i].Partial = true
}
}
return out
}
@ -101,7 +108,11 @@ func AppendLocator(list types.SourceLocators, loc types.SourceLocator) types.Sou
}
func foldInto(last *types.SourceLocator, loc types.SourceLocator) bool {
if last.Type != loc.Type {
if last.Type != loc.Type ||
last.Partial != loc.Partial ||
last.Mapping != loc.Mapping ||
last.SourceHash != loc.SourceHash ||
last.SourceID != loc.SourceID {
return false
}
switch loc.Type {
@ -158,14 +169,19 @@ func MergeLocators(a, b types.SourceLocators) types.SourceLocators {
out = append(out, loc)
}
}
if len(out) > MaxLocatorsPerChunk {
out = out[:MaxLocatorsPerChunk]
}
return out
}
func sameLocator(a, b types.SourceLocator) bool {
if a.Type != b.Type || a.Page != b.Page || a.Block != b.Block || a.Slide != b.Slide ||
if a.Partial != b.Partial ||
a.Quote != b.Quote ||
a.SourceID != b.SourceID ||
a.SourceHash != b.SourceHash ||
a.Mapping != b.Mapping ||
a.Type != b.Type ||
a.Page != b.Page ||
a.Block != b.Block ||
a.Slide != b.Slide ||
a.Sheet != b.Sheet || a.RowStart != b.RowStart || a.RowEnd != b.RowEnd ||
a.Start != b.Start || a.End != b.End || a.StartMs != b.StartMs || a.EndMs != b.EndMs ||
a.Section != b.Section || len(a.BBox) != len(b.BBox) {
@ -190,21 +206,27 @@ var (
// text, collapses whitespace, and caps it at types.SourceLocatorQuoteMax
// runes.
func CleanQuote(text string) string {
return capRunes(fullQuote(text), types.SourceLocatorQuoteMax)
}
// fullQuote keeps the complete evidence; truncation can hide a citation near its end.
func fullQuote(text string) string {
text = quoteImageRe.ReplaceAllString(text, " ")
text = quoteLinkRe.ReplaceAllString(text, "$1")
text = quoteTagRe.ReplaceAllString(text, " ")
text = html.UnescapeString(text)
text = strings.TrimSpace(quoteSpaceRe.ReplaceAllString(text, " "))
return capRunes(text, types.SourceLocatorQuoteMax)
return text
}
func joinQuote(a, b string) string {
if a == "" {
return b
}
if b == "" || utf8.RuneCountInString(a) >= types.SourceLocatorQuoteMax {
if b == "" {
return a
}
return capRunes(a+" "+b, types.SourceLocatorQuoteMax)
return a + " " + b
}
func capRunes(s string, n int) string {

View File

@ -0,0 +1,177 @@
package sourceloc
import (
"strings"
"testing"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
func TestAlignNeverAttributesMissingBlockToPreviousPage(t *testing.T) {
md := "第一段正确文本。\n第二段实际内容没有匹配。\n第三段正确文本。"
units := []Unit{
{Text: "第一段正确文本", Locator: types.SourceLocator{Type: "pdf", Page: 1}},
{Text: "第二段OCR错误内容", Locator: types.SourceLocator{Type: "pdf", Page: 2}},
{Text: "第三段正确文本", Locator: types.SourceLocator{Type: "pdf", Page: 3}},
}
index := NewIndex(md, Align(md, units))
at := runeIndex(md, "第二段")
require.Empty(t, index.Locators(at, at+5))
require.Equal(t, 3, index.Locators(runeIndex(md, "第三段"), len([]rune(md)))[0].Page)
}
func TestAlignRequiresFullUnitNotCommonPrefix(t *testing.T) {
prefix := strings.Repeat("共同前缀", 12)
require.Empty(t,
Align(prefix+"验收不合格",
[]Unit{{
Text: prefix + "验收合格",
Locator: types.SourceLocator{
Type: "pdf",
Page: 1,
},
}}))
}
func TestAlignPreservesNumericMeaning(t *testing.T) {
for _, pair := range [][2]string{{"数值15毫米", "数值1.5毫米"}, {"温度5度", "温度-5度"}, {"比例5", "比例5%"}, {"值≤5", "值≥5"}} {
require.Empty(t,
Align(pair[0],
[]Unit{{
Text: pair[1],
Locator: types.SourceLocator{
Type: "pdf",
Page: 1,
},
}}),
pair)
}
}
func TestAlignRejectsUnaccountedDuplicate(t *testing.T) {
require.Empty(t,
Align("目录:设备验收合格。\n正文:设备验收合格。",
[]Unit{{
Text: "设备验收合格",
Locator: types.SourceLocator{
Type: "pdf",
Page: 9,
},
}}))
units := []Unit{
{
Text: "相同段落内容",
Locator: types.SourceLocator{
Type: "pdf",
Page: 1,
},
},
{
Text: "相同段落内容",
Locator: types.SourceLocator{
Type: "pdf",
Page: 2,
},
},
}
blocks := Align("相同段落内容\n相同段落内容", units)
require.Len(t, blocks, 2)
require.Equal(t, 2, blocks[1].Locator.Page)
}
func TestRemapNeverInterpolatesChangedText(t *testing.T) {
old := "第一段\n已通过验收\n末段"
blocks := []types.SourceBlock{{Start: 4, End: 9, Locator: types.SourceLocator{Type: "pdf", Page: 2}}}
require.Empty(t, RemapBlocks(blocks, old, "第一段\n未通过检查\n末段"))
}
func TestMergeKeepsDistinctExcerptsOfSameRegion(t *testing.T) {
a := types.SourceLocator{Type: "pdf", Page: 2, BBox: []float64{0, 0, 1, 1}, Quote: "第一句"}
b := a
b.Quote = "另一句"
require.Len(t, MergeLocators(types.SourceLocators{a}, types.SourceLocators{a, b}), 2)
}
func TestLocatorsPreserveLongEvidenceAndAllRegions(t *testing.T) {
text := strings.Repeat("完整原文", 100) + "末尾引用的关键结论"
index := NewIndex(text,
[]types.SourceBlock{{
Start: 0,
End: len([]rune(text)),
Locator: types.SourceLocator{
Type: "pdf",
Page: 1,
},
}})
require.Equal(t, text, index.Locators(0, len([]rune(text)))[0].Quote)
var blocks []types.SourceBlock
for i := 0; i < 80; i++ {
blocks = append(blocks,
types.SourceBlock{
Start: i,
End: i + 1,
Locator: types.SourceLocator{
Type: "pdf",
Page: i + 1,
},
})
}
locs := NewIndex(strings.Repeat("文", 80), blocks).Locators(0, 80)
require.Len(t, locs, 80)
require.Len(t, MergeLocators(locs[:40], locs[40:]), 80)
}
func TestFoldingCannotMixRevisionsOrMappingQuality(t *testing.T) {
first := types.SourceLocator{Type: "pdf", Page: 1, Mapping: "exact", SourceHash: "original", Quote: "第一段"}
second := first
second.Mapping = ""
require.Len(t, AppendLocator(types.SourceLocators{first}, second), 2)
second = first
second.SourceHash = "replacement"
require.Len(t, AppendLocator(types.SourceLocators{first}, second), 2)
}
func TestAlignRejectsPartialNumericValues(t *testing.T) {
for _, pair := range [][2]string{{"增长为5%", "增长为5"}, {"115", "15"}, {"15.5", "15"}, {"-15", "15"}} {
require.Empty(t,
Align(pair[0], []Unit{{Text: pair[1], Locator: types.SourceLocator{Type: "pdf", Page: 1}}}),
pair,
)
}
}
func TestChunkWithUnmappedEvidenceIsMarkedPartial(t *testing.T) {
md := "匹配的原文。\n未匹配的关键结论。"
index := NewIndex(md, Align(md, []Unit{{Text: "匹配的原文", Locator: types.SourceLocator{Type: "pdf", Page: 1}}}))
locs := index.Locators(0, len([]rune(md)))
require.Len(t, locs, 1)
require.True(t, locs[0].Partial)
require.False(t, index.Locators(0, 5)[0].Partial)
}
func TestAlignmentDecodesTableEntitiesWithoutLosingOffsets(t *testing.T) {
md := "<table><tr><td>限值</td><td>&lt;1.5</td></tr></table>"
loc := types.SourceLocator{Type: "pdf", Page: 2}
blocks := Align(md, []Unit{{Text: "限值 <1.5", Locator: loc}})
require.Len(t, blocks, 1)
quotes := NewIndex(md, blocks).Locators(0, len([]rune(md)))
require.False(t, quotes[0].Partial)
require.Equal(t, "限值 <1.5", quotes[0].Quote)
remapped := RemapBlocks(blocks, md, "|限值|<1.5|")
require.Len(t, remapped, 1)
require.Equal(t, 2, remapped[0].Locator.Page)
}
func TestImagePlaceholderDoesNotInvalidateVerifiedTextLocators(t *testing.T) {
md := "第一段完整的原文。\n\n![descript](resource://image)\n\n第二段完整的原文。"
blocks := Align(md, []Unit{
{Text: "第一段完整的原文。", Locator: types.SourceLocator{Type: "docx", Block: 1}},
{Text: "第二段完整的原文。", Locator: types.SourceLocator{Type: "docx", Block: 3}},
})
locs := NewIndex(md, blocks).Locators(0, len([]rune(md)))
require.Len(t, locs, 2)
for _, loc := range locs {
require.False(t, loc.Partial)
}
}

View File

@ -28,7 +28,8 @@ type Remapper struct {
pair []int // pair[i] = new line index matched to old line i, or -1
}
// NewRemapper prepares a mapping from oldText to newText.
// NewRemapper prepares a best-effort offset mapping.
// Deprecated: source positions must use RemapBlocks, which verifies full text.
func NewRemapper(oldText, newText string) *Remapper {
oldKeys, oldStarts, oldLen := splitLines(oldText)
newKeys, newStarts, newLen := splitLines(newText)
@ -120,17 +121,18 @@ func RemapBlocks(blocks []types.SourceBlock, oldText, newText string) []types.So
if len(blocks) == 0 || oldText == newText {
return blocks
}
r := NewRemapper(oldText, newText)
out := make([]types.SourceBlock, 0, len(blocks))
// Re-align full block text after markup/URL rewrites. Proportional
// interpolation can manufacture a location for deleted or changed content.
oldRunes := []rune(oldText)
units := make([]Unit, 0, len(blocks))
for _, b := range blocks {
start, end := r.Map(b.Start), r.Map(b.End)
if end <= start {
if b.Start < 0 || b.End > len(oldRunes) || b.End <= b.Start {
continue
}
b.Start, b.End = start, end
out = append(out, b)
text := normalizeMarkdown(string(oldRunes[b.Start:b.End])).text
units = append(units, Unit{Text: text, Locator: b.Locator})
}
return out
return Align(newText, units)
}
// splitLines returns each line's comparison key (without its line break or a

View File

@ -14,7 +14,7 @@ func TextBlocks(content string) []types.SourceBlock {
if start >= 0 && end > start {
blocks = append(blocks, types.SourceBlock{
Start: start, End: end,
Locator: types.SourceLocator{Type: types.SourceLocatorText, Start: start, End: end},
Locator: types.SourceLocator{Type: types.SourceLocatorText, Mapping: "exact", Start: start, End: end},
})
}
start = -1

View File

@ -84,6 +84,8 @@ func (f ChunkFlags) ToggleFlag(flag ChunkFlags) ChunkFlags {
// ImageInfo 表示与 Chunk 关联的图片信息
type ImageInfo struct {
// SHA256 identifies the exact stored image bytes across parser and preview.
SHA256 string `json:"sha256,omitempty"`
// 图片URL(COS)
URL string `json:"url" gorm:"type:text"`
// 原始图片URL

View File

@ -149,6 +149,8 @@ func (st SearchTargets) ContainsKB(kbID string) bool {
// SearchResult represents the search result
type SearchResult struct {
// CitationSources retains independently citeable bodies after context expansion.
CitationSources []*SearchResult `json:"-" gorm:"-"`
// ID
ID string `gorm:"column:id" json:"id"`
// Content

View File

@ -26,13 +26,21 @@ const (
SourceLocatorSection = "section"
)
// SourceLocatorQuoteMax caps the quote stored per locator, in runes.
// SourceLocatorQuoteMax caps display snippets, not stored source evidence.
const SourceLocatorQuoteMax = 300
// SourceLocator is one position in an original file. Only the fields of its
// Type are set; zero values are omitted from JSON and read back as zero.
type SourceLocator struct {
Type string `json:"type"`
// Mapping records verified text-to-source alignment. Empty means legacy.
Mapping string `json:"mapping,omitempty"`
// Partial means some of the chunk has no source mapping.
Partial bool `json:"partial,omitempty"`
// SourceID identifies a block within the parser result, not a rendered item.
SourceID string `json:"source_id,omitempty"`
// SourceHash binds the locator to the knowledge record’s source revision hash.
SourceHash string `json:"source_hash,omitempty"`
// Page is the 1-based PDF page.
Page int `json:"page,omitempty"`
// BBox is [x0, y0, x1, y1] as fractions of the page width and height,
@ -57,8 +65,8 @@ type SourceLocator struct {
Section int `json:"section,omitempty"`
// Title names the section or slide when the source has one.
Title string `json:"title,omitempty"`
// Quote is the cited text as parsed, capped at SourceLocatorQuoteMax
// runes. Viewers match it inside the rendered original and against the
// Quote is the complete cited overlap as parsed. Viewers match it
// inside the rendered original and against the
// answer sentence that cites the chunk.
Quote string `json:"quote,omitempty"`
}