Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

fix(reading): unwrap backticked locator citations and split multi-locator links

李晨2a68d2405f4a
diff --git a/deeptutor/capabilities/reading/prompts/en/reading.yaml b/deeptutor/capabilities/reading/prompts/en/reading.yaml
index 13622208a..dc9db5323 100644
--- a/deeptutor/capabilities/reading/prompts/en/reading.yaml
+++ b/deeptutor/capabilities/reading/prompts/en/reading.yaml
@@ -26,9 +26,9 @@ playbook: |
verbatim quote. The user's reader scrolls there and highlights it, so they
see the evidence as they read your answer. Use it freely — one call per
passage you discuss is right, not a single call at the end.
- 4. Cite as `[p.12]` right after the claim it supports. Always that exact form,
- whatever the document's units are called (write `[p.12]` even for a chapter
- or a slide). Use `[p.12,17]` for several and `[p.12-14]` for a range. The
+ 4. Cite as [p.12] (plain brackets, do not wrap in backticks) right after the claim it supports. Always that exact form,
+ whatever the document's units are called (write [p.12] even for a chapter
+ or a slide). Use [p.12,17] for several and [p.12-14] for a range. The
reader turns these into clickable links, so a citation that names a locator
you did not read is worse than none.
diff --git a/deeptutor/capabilities/reading/prompts/zh/reading.yaml b/deeptutor/capabilities/reading/prompts/zh/reading.yaml
index e8183bd14..82d3a3761 100644
--- a/deeptutor/capabilities/reading/prompts/zh/reading.yaml
+++ b/deeptutor/capabilities/reading/prompts/zh/reading.yaml
@@ -21,8 +21,8 @@ playbook: |
3. 每当你引用某个具体段落,调用 `reader_goto` 并传入逐字原文。用户的阅读器会
滚动到那里并高亮,让他们边读你的回答边看到依据。放心多次调用 —— 讨论几处
就调几次才对,不要攒到最后只调一次。
- 4. 在正文里紧跟着被支撑的论断写 `[p.12]`。无论该文档的单元叫什么(章、页、
- 幻灯片),都统一写成 `[p.12]`。多个用 `[p.12,17]`,范围用 `[p.12-14]`。
+ 4. 在正文里紧跟着被支撑的论断写 [p.12](直接写方括号,不要用反引号包裹)。无论该文档的单元叫什么(章、页、
+ 幻灯片),都统一写成 [p.12]。多个用 [p.12,17],范围用 [p.12-14]。
阅读器会把它们变成可点击的链接,所以引用一个你没读过的定位号比不引用更糟。
音视频是唯一的例外,下面的文档信息会说明何时适用:那里改用该段自己的时间戳
diff --git a/web/lib/reading-citations.ts b/web/lib/reading-citations.ts
index 4a7b5f023..0acda1f80 100644
--- a/web/lib/reading-citations.ts
+++ b/web/lib/reading-citations.ts
@@ -28,6 +28,8 @@ export interface LocatorCitation {
raw: string;
/** Locators in ascending order, de-duplicated. */
locators: number[];
+ /** Raw comma/dash body inside the citation, e.g. `"12,17"`. */
+ body?: string;
/** Character offsets of `raw` within the input. */
start: number;
end: number;
@@ -57,8 +59,9 @@ interface ReadingEvidenceEvent {
const MAX_RANGE_SPAN = 40;
// `[p.` then digits with , - – separators, then `]` — but not when followed by
-// `(`, which would mean it is already a Markdown link's label.
-const CITATION = /\[p\.\s*(\d[\d\s,–—-]*)\]/gi;
+// `(`, which would mean it is already a Markdown link's label. Optionally wrapped
+// in balanced backticks (e.g. `[p.12]`) from prompt formatting artifacts.
+const CITATION = /(`?\[p\.\s*(\d[\d\s,–—-]*)\]`?)/gi;
/**
* Character ranges occupied by fenced blocks or inline code.
@@ -82,6 +85,12 @@ export function codeRanges(text: string): Array<[number, number]> {
const inline = /(`+)(?:[^`]|(?!\1)`)*?\1/g;
while ((match = inline.exec(text)) !== null) {
if (!inFence(match.index)) {
+ // Standalone locator citations wrapped in backticks (e.g. `[p.12]`)
+ // are formatting artifacts from prompts rather than code snippets.
+ // Do not treat them as protected code so they can be linkified.
+ if (/^`[ \t]*\[p\.\s*\d[\d\s,–—-]*(?:\])[ \t]*`$/i.test(match[0])) {
+ continue;
+ }
ranges.push([match.index, match.index + match[0].length]);
}
}
@@ -198,17 +207,20 @@ export function findLocatorCitations(text: string): LocatorCitation[] {
CITATION.lastIndex = 0;
let match: RegExpExecArray | null;
while ((match = CITATION.exec(text)) !== null) {
+ const raw = match[1];
+ if (raw.startsWith("`") !== raw.endsWith("`")) continue;
const start = match.index;
if (masked(start)) continue;
// Already a Markdown link label — leave it alone.
- if (text[start + match[0].length] === "(") continue;
- const locators = parseLocatorList(match[1]);
+ if (text[start + raw.length] === "(") continue;
+ const locators = parseLocatorList(match[2]);
if (!locators.length) continue;
out.push({
- raw: match[0],
+ raw,
locators,
+ body: match[2],
start,
- end: start + match[0].length,
+ end: start + raw.length,
});
}
return out;
@@ -256,13 +268,16 @@ export function linkifyLocatorCitations(
continue;
}
- const revisionAddress =
- Number.isSafeInteger(materialRevision) && Number(materialRevision) >= 1
- ? `-revision-${materialRevision}`
- : "";
- const href = materialId
- ? `${MATERIAL_LOCATOR_HREF_PREFIX}${encodeURIComponent(materialId)}${revisionAddress}-locator-${locators[0]}`
- : `${LOCATOR_HREF_PREFIX}${locators[0]}`;
+ const buildLocatorHref = (locator: number) => {
+ const revisionAddress =
+ Number.isSafeInteger(materialRevision) && Number(materialRevision) >= 1
+ ? `-revision-${materialRevision}`
+ : "";
+ return materialId
+ ? `${MATERIAL_LOCATOR_HREF_PREFIX}${encodeURIComponent(materialId)}${revisionAddress}-locator-${locator}`
+ : `${LOCATOR_HREF_PREFIX}${locator}`;
+ };
+
const absorbed =
locators.length === citation.locators.length
? findAbsorbablePhrase(text, citation, skip)
@@ -273,7 +288,7 @@ export function linkifyLocatorCitations(
// so the sentence closes cleanly: "…located on [page 3](…) of the
// document." rather than "…of the document ."
out += text.slice(cursor, absorbed.start);
- out += `[${absorbed.label}](${href})`;
+ out += `[${absorbed.label}](${buildLocatorHref(locators[0])})`;
const between = text.slice(absorbed.end, citation.start);
out += between.replace(/\s+$/, "");
cursor = citation.end;
@@ -281,7 +296,41 @@ export function linkifyLocatorCitations(
}
out += text.slice(cursor, citation.start);
- out += `[p.${locators.join(",")}](${href})`;
+ if (citation.body && citation.body.includes(",")) {
+ const chunks = citation.body.split(",");
+ const parts: string[] = [];
+ for (let i = 0; i < chunks.length; i += 1) {
+ const piece = chunks[i].trim();
+ if (!piece) continue;
+ const rangeMatch = /^(\d+)\s*[–—-]\s*(\d+)$/.exec(piece);
+ let target = 0;
+ if (rangeMatch) {
+ target = Math.min(Number(rangeMatch[1]), Number(rangeMatch[2]));
+ } else {
+ const singleMatch = /^(\d+)$/.exec(piece);
+ if (singleMatch) target = Number(singleMatch[1]);
+ }
+ if (!target) continue;
+ if (
+ typeof maxLocator === "number" &&
+ maxLocator > 0 &&
+ target > maxLocator
+ ) {
+ continue;
+ }
+ const label = parts.length === 0 ? `p.${piece}` : piece;
+ parts.push(`[${label}](${buildLocatorHref(target)})`);
+ }
+ out +=
+ parts.length > 0
+ ? parts.join(", ")
+ : `[p.${locators.join(",")}](${buildLocatorHref(locators[0])})`;
+ } else {
+ const label = citation.body?.trim()
+ ? `p.${citation.body.trim()}`
+ : `p.${locators.join(",")}`;
+ out += `[${label}](${buildLocatorHref(locators[0])})`;
+ }
cursor = citation.end;
}
return out + text.slice(cursor);
diff --git a/web/tests/reading-citations.test.ts b/web/tests/reading-citations.test.ts
index 121280aab..960dc1993 100644
--- a/web/tests/reading-citations.test.ts
+++ b/web/tests/reading-citations.test.ts
@@ -53,6 +53,14 @@ test("rejects locator zero", () => {
assert.deepEqual(findLocatorCitations("[p.0]"), []);
});
+test("parses locator citation wrapped in backticks", () => {
+ const text = "Grounded `[p.12]` claim.";
+ const found = findLocatorCitations(text);
+ assert.equal(found.length, 1);
+ assert.deepEqual(found[0].locators, [12]);
+ assert.equal(found[0].raw, "`[p.12]`");
+});
+
test("does not touch citations inside inline code", () => {
const text = "Use `arr[p.12]` as the index.";
assert.deepEqual(findLocatorCitations(text), []);
@@ -117,6 +125,28 @@ test("linkify rewrites to an anchor the reader can intercept", () => {
);
});
+test("linkify rewrites backticked citations to clean anchors without backticks", () => {
+ assert.equal(
+ linkifyLocatorCitations("Grounded `[p.12]` claim."),
+ `Grounded [p.12](${LOCATOR_HREF_PREFIX}12) claim.`,
+ );
+ assert.equal(
+ linkifyLocatorCitations("Both `[p.12,17]` agree."),
+ `Both [p.12](${LOCATOR_HREF_PREFIX}12), [17](${LOCATOR_HREF_PREFIX}17) agree.`,
+ );
+});
+
+test("absorbs spelled-out phrase before backticked citation and drops backticks", () => {
+ assert.equal(
+ linkifyLocatorCitations("该节位于第 3 页 `[p.3]`。"),
+ `该节位于[第 3 页](${LOCATOR_HREF_PREFIX}3)。`,
+ );
+ assert.equal(
+ linkifyLocatorCitations("It appears on page 7 `[p.7]`."),
+ `It appears on [page 7](${LOCATOR_HREF_PREFIX}7).`,
+ );
+});
+
test("linkify binds a citation to its turn material", () => {
assert.equal(
linkifyLocatorCitations("Grounded [p.12] claim.", {
@@ -144,10 +174,21 @@ test("unsupported citations remain plain text instead of blind links", () => {
);
});
-test("linkify keeps a multi-locator label but targets the first", () => {
+test("linkify splits comma-separated multi-locator citations into independent links", () => {
assert.equal(
linkifyLocatorCitations("Both [p.12,17] agree."),
- `Both [p.12,17](${LOCATOR_HREF_PREFIX}12) agree.`,
+ `Both [p.12](${LOCATOR_HREF_PREFIX}12), [17](${LOCATOR_HREF_PREFIX}17) agree.`,
+ );
+ assert.equal(
+ linkifyLocatorCitations("Multiple [p.12, 15, 18] points."),
+ `Multiple [p.12](${LOCATOR_HREF_PREFIX}12), [15](${LOCATOR_HREF_PREFIX}15), [18](${LOCATOR_HREF_PREFIX}18) points.`,
+ );
+});
+
+test("linkify keeps range citations targeting the range start locator", () => {
+ assert.equal(
+ linkifyLocatorCitations("Read [p.12-14] carefully."),
+ `Read [p.12-14](${LOCATOR_HREF_PREFIX}12) carefully.`,
);
});
@@ -369,10 +410,10 @@ test("does not absorb from inside code", () => {
});
test("leaves a multi-locator citation as a marker", () => {
- // There is no single phrase for "[p.3,7]" to absorb.
+ // There is no single phrase for "[p.3,7]" to absorb, and multi-locators split into independent links.
assert.equal(
linkifyLocatorCitations("Both places discuss it on page 3 [p.3,7]."),
- `Both places discuss it on page 3 [p.3,7](${LOCATOR_HREF_PREFIX}3).`,
+ `Both places discuss it on page 3 [p.3](${LOCATOR_HREF_PREFIX}3), [7](${LOCATOR_HREF_PREFIX}7).`,
);
});