DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
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.yamlindex 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 theysee the evidence as they read your answer. Use it freely — one call perpassage 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. Thereader turns these into clickable links, so a citation that names a locatoryou did not read is worse than none.diff --git a/deeptutor/capabilities/reading/prompts/zh/reading.yaml b/deeptutor/capabilities/reading/prompts/zh/reading.yamlindex 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.tsindex 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.tsindex 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).`,);});