Skip to content

World's first open-source enterprise world model.

A graph citation's source entry carries the sentence the fact was read from, and the preview and the document page mark it (#977)

Maya Kiddf7fce8f0c91
diff --git a/crates/utopia-server/src/api/chat.rs b/crates/utopia-server/src/api/chat.rs
index a3cb73eb..a05aa200 100644
--- a/crates/utopia-server/src/api/chat.rs
+++ b/crates/utopia-server/src/api/chat.rs
@@ -902,7 +902,7 @@ pub async fn chat(
let mut turn_published = 0usize;
let mut turn_holding = false;
let mut finished = false;
- let mut published_sources = 0;
+ let mut published_sources: Vec<serde_json::Value> = Vec::new();
let mut answer_requested = false;
while let Some(item) = run.next().await {
@@ -1001,12 +1001,14 @@ pub async fn chat(
steps_acc.push(step.clone());
published_step = Some(step);
}
- // cite() only appends: document reads can add citations too, regardless
- // of the UI step kind. Release the sink before yielding to subscribers.
+ // cite() appends, and a graph citation can add a quote to an entry a search
+ // registered (#968's follow-up): publish when the list changed at all, not
+ // only when it grew. Document reads can add citations too, regardless of the
+ // UI step kind. Release the sink before yielding to subscribers.
let sources = {
let sink = shared.sink.lock().await;
- if sink.sources.len() != published_sources {
- published_sources = sink.sources.len();
+ if sink.sources != published_sources {
+ published_sources = sink.sources.clone();
Some(sink.sources.clone())
} else {
None
diff --git a/crates/utopia-server/src/api/chat_graph_citation_tests.rs b/crates/utopia-server/src/api/chat_graph_citation_tests.rs
index 24c571f1..b1e7c200 100644
--- a/crates/utopia-server/src/api/chat_graph_citation_tests.rs
+++ b/crates/utopia-server/src/api/chat_graph_citation_tests.rs
@@ -10,6 +10,10 @@
//! - 派生事实那一行不带号,它的前提各带各的
//! - MCP 的文字一字不改,来源清单是空的(号码对没有清单的调用方没有意义)
//! - 整条对话:工具印的号随 `sources` 帧发出去、跟着回答落库,模型读到的事实行带着号
+//! - 号打开的是那句话(#968 的后续):条目带着块里说出这条事实的引文,一块被引几句就记
+//! 几句;块被新版本取代后换成仍有效的那一块,`as_of` 回到取代之前又是原来那块
+//! - 检索和图谱工具在一轮里共用一个号:图谱引到检索登过的块,号不变、补上那句话;只补了
+//! 引文、条数没变,来源帧也再发一次
//!
//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
use super::*;
@@ -323,3 +327,295 @@ async fn a_graph_answer_publishes_and_stores_its_sources() -> anyhow::Result<()>
f.cleanup().await?;
run
}
+
+/// 号 `n` 那一条带着的引文
+fn quotes_of(sink: &ToolSink, n: usize) -> Vec<String> {
+ sink.sources[n - 1]["quotes"]
+ .as_array()
+ .map(|q| {
+ q.iter()
+ .filter_map(|x| x.as_str().map(str::to_string))
+ .collect()
+ })
+ .unwrap_or_default()
+}
+
+/// 种子里还在的几篇文档进全文索引:检索要找得到它们
+async fn index_seed(f: &Fx) -> anyhow::Result<()> {
+ let rows: Vec<(Uuid, Uuid, String)> = sqlx::query_as(
+ "SELECT c.document_id, c.id, c.text FROM chunks c JOIN documents d ON d.id = c.document_id
+ WHERE c.kb_id = $1 AND d.deleted_at IS NULL ORDER BY c.document_id, c.seq",
+ )
+ .bind(f.kb)
+ .fetch_all(&f.pool)
+ .await?;
+ let mut by_doc: std::collections::BTreeMap<Uuid, Vec<(String, String)>> = Default::default();
+ for (doc, chunk, text) in rows {
+ by_doc
+ .entry(doc)
+ .or_default()
+ .push((chunk.to_string(), text));
+ }
+ for (doc, chunks) in by_doc {
+ f.state
+ .search
+ .reindex_document(&f.kb.to_string(), &doc.to_string(), &chunks)?;
+ }
+ Ok(())
+}
+
+/// 号打开的是说出这条事实的那一句:条目带着引文,同一块两条事实两句都在;块被取代后
+/// 换成仍有效的那一块和它那一句,`as_of` 回到取代之前又是原来的
+#[tokio::test]
+async fn a_graph_number_opens_the_sentence_it_was_read_from() -> anyhow::Result<()> {
+ let Some(f) = fixture(Scripted::new(vec![])).await? else {
+ return Ok(());
+ };
+ let run = async {
+ let s = seed(&f.pool, f.kb).await?;
+ let pair: Uuid = sqlx::query_scalar(
+ "SELECT f.id FROM facts f JOIN relation_types r ON r.id = f.predicate_id
+ WHERE f.kb_id = $1 AND r.key = 'works_with'",
+ )
+ .bind(f.kb)
+ .fetch_one(&f.pool)
+ .await?;
+ // 章程那一块说了两句,张三的两条事实各从一句读出来
+ sqlx::query("UPDATE chunks SET text = $2 WHERE id = $1")
+ .bind(s.charter)
+ .bind("Zhang San leads Project Aurora from 2023-01-10. Zhang San works with Li Si.")
+ .execute(&f.pool)
+ .await?;
+ sqlx::query(
+ "UPDATE fact_evidence SET quote = 'Zhang San works with Li Si.' WHERE fact_id = $1",
+ )
+ .bind(pair)
+ .execute(&f.pool)
+ .await?;
+ let chat = ctx(&f, None);
+ let mut sink = ToolSink::default();
+ let text = dispatch(
+ &chat,
+ &mut sink,
+ "entity_facts",
+ &json!({"entity": "Zhang San"}),
+ )
+ .await
+ .text;
+ // 张三 works with 李四有两行:断言的那行带号,规则推出来的那行(`[rule:`)不带
+ let works_line = text
+ .lines()
+ .flat_map(|l| l.split(" · "))
+ .find(|l| l.contains("Li Si") && !l.contains("[rule:"))
+ .unwrap_or_else(|| panic!("no stated works-with line in:\n{text}"));
+ let (leads, works) = (marks(line(&text, "Project Aurora")), marks(works_line));
+ assert_eq!(leads, works, "one chunk, one number: {text}");
+ assert_eq!(chunk_of(&sink, leads[0]), s.charter);
+ let mut quotes = quotes_of(&sink, leads[0]);
+ quotes.sort();
+ assert_eq!(
+ quotes,
+ [
+ "Zhang San leads Project Aurora from 2023-01-10.",
+ "Zhang San works with Li Si."
+ ],
+ "both sentences the chunk was cited for"
+ );
+
+ // 章程那一块被新版本取代:张三领 Aurora 那一条换成仍有效的回顾那一块、那一句
+ sqlx::query("UPDATE chunks SET superseded_at = now() WHERE id = $1")
+ .bind(s.charter)
+ .execute(&f.pool)
+ .await?;
+ let mut now = ToolSink::default();
+ let text = dispatch(
+ &chat,
+ &mut now,
+ "entity_facts",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await
+ .text;
+ let zhang = marks(line(&text, "Zhang San"));
+ assert_eq!(chunk_of(&now, zhang[0]), s.recap, "{text}");
+ assert_eq!(
+ quotes_of(&now, zhang[0]),
+ ["Zhang San led Project Aurora until the handover."]
+ );
+ // 回到取代之前:那时章程那一块还是现行的
+ let mut then = ToolSink::default();
+ let text = dispatch(
+ &chat,
+ &mut then,
+ "entity_facts",
+ &json!({"entity": "Project Aurora", "as_of": "2026-03-01"}),
+ )
+ .await
+ .text;
+ let zhang = marks(line(&text, "Zhang San"));
+ assert_eq!(chunk_of(&then, zhang[0]), s.charter, "{text}");
+ assert_eq!(
+ quotes_of(&then, zhang[0]),
+ ["Zhang San leads Project Aurora from 2023-01-10."]
+ );
+ // MCP 没有来源清单,也就没有引文
+ let mut empty = ToolSink::default();
+ dispatch(
+ &ctx(&f, Some(Uuid::now_v7())),
+ &mut empty,
+ "entity_facts",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await;
+ assert!(empty.sources.is_empty());
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ run
+}
+
+/// 一轮里检索和图谱工具共用一个号:检索先登了交接备忘录那一块,图谱引到它时号不变,
+/// 条目补上李四那句话;反过来也一样,检索不另起一个号,引文留着
+#[tokio::test]
+async fn a_search_and_a_graph_tool_share_one_number() -> anyhow::Result<()> {
+ let Some(f) = fixture(Scripted::new(vec![])).await? else {
+ return Ok(());
+ };
+ let run = async {
+ let s = seed(&f.pool, f.kb).await?;
+ index_seed(&f).await?;
+ let chat = ctx(&f, None);
+ let number_of = |sink: &ToolSink, chunk: Uuid| {
+ sink.sources
+ .iter()
+ .position(|x| x["chunk_id"] == chunk.to_string())
+ .map(|i| i + 1)
+ };
+ let li_says = "Li Si leads Project Aurora from 2024-07-05.";
+
+ let mut sink = ToolSink::default();
+ let found = dispatch(
+ &chat,
+ &mut sink,
+ "search_chunks",
+ &json!({"query": "Li Si leads Project Aurora"}),
+ )
+ .await
+ .text;
+ let n = number_of(&sink, s.handover).unwrap_or_else(|| panic!("the handover hit: {found}"));
+ assert!(
+ quotes_of(&sink, n).is_empty(),
+ "a search hit carries no quote"
+ );
+ let listed = sink.sources.len();
+ let text = dispatch(
+ &chat,
+ &mut sink,
+ "entity_facts",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await
+ .text;
+ assert_eq!(
+ marks(line(&text, "Li Si")),
+ [n],
+ "the search's number: {text}"
+ );
+ assert_eq!(
+ quotes_of(&sink, n),
+ [li_says],
+ "the entry gains the sentence"
+ );
+ assert_eq!(
+ number_of(&sink, s.handover),
+ Some(n),
+ "still one entry for the chunk"
+ );
+ assert!(sink.sources.len() >= listed);
+
+ let mut reverse = ToolSink::default();
+ let text = dispatch(
+ &chat,
+ &mut reverse,
+ "entity_facts",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await
+ .text;
+ let m = marks(line(&text, "Li Si"))[0];
+ let listed = reverse.sources.len();
+ dispatch(
+ &chat,
+ &mut reverse,
+ "search_chunks",
+ &json!({"query": "Li Si leads Project Aurora"}),
+ )
+ .await;
+ assert_eq!(
+ number_of(&reverse, s.handover),
+ Some(m),
+ "the graph's number"
+ );
+ assert_eq!(quotes_of(&reverse, m), [li_says], "the quote stays");
+ assert!(reverse.sources.len() >= listed);
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ run
+}
+
+/// 整条对话:检索登了三块,图谱再引其中两块,只补了引文、条数没变——来源帧照样再发
+/// 一次,存下的与最后一帧一致
+#[tokio::test]
+async fn a_quote_added_to_a_search_hit_is_published() -> anyhow::Result<()> {
+ let Some(f) = fixture(Scripted::new(vec![
+ Reply::Tool("search_chunks", r#"{"query":"Project Aurora"}"#),
+ Reply::Tool("entity_facts", r#"{"entity_id":"Li Si"}"#),
+ Reply::Text("Li Si leads Project Aurora."),
+ ]))
+ .await?
+ else {
+ return Ok(());
+ };
+ let run = async {
+ seed(&f.pool, f.kb).await?;
+ index_seed(&f).await?;
+ let sse = f.ask("Who leads Project Aurora?").await?;
+ assert!(sse.contains("event: done"), "{sse}");
+ let published: Vec<serde_json::Value> = sse
+ .split("\n\n")
+ .filter(|frame| frame.lines().any(|l| l == "event: sources"))
+ .filter_map(|frame| frame.lines().find_map(|l| l.strip_prefix("data: ")))
+ .filter_map(|data| serde_json::from_str(data).ok())
+ .collect();
+ assert!(published.len() >= 2, "{published:?}");
+ let (first, last) = (&published[0], published.last().unwrap());
+ assert_eq!(
+ first.as_array().map(Vec::len),
+ last.as_array().map(Vec::len),
+ "the graph step added no entry, only quotes: {published:?}"
+ );
+ assert!(
+ last.as_array()
+ .unwrap()
+ .iter()
+ .any(|x| x["quotes"].as_array().is_some_and(|q| !q.is_empty())),
+ "{last}"
+ );
+ let stored: serde_json::Value = sqlx::query_scalar(
+ "SELECT m.sources FROM conversation_messages m
+ JOIN conversations c ON c.id = m.conversation_id
+ WHERE c.kb_id = $1 AND m.role = 'assistant'",
+ )
+ .bind(f.kb)
+ .fetch_one(&f.pool)
+ .await?;
+ assert_eq!(&stored, last);
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ run
+}
diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rs
index f933bfba..c3f25293 100644
--- a/crates/utopia-server/src/api/tools.rs
+++ b/crates/utopia-server/src/api/tools.rs
@@ -275,6 +275,35 @@ pub(super) fn cite(
}
}
+const QUOTES_PER_SOURCE: usize = 8;
+const QUOTE_CHARS: usize = 400;
+
+/// 给第 `n` 条来源补一句它说出的话(#968 的后续):号打开的是那一块,`quotes` 是块里被
+/// 引到的那几句,界面按它们在原文里标出来。同一块一个号,块里被引到几句就记几句,去重、
+/// 按引用的先后;检索先登记的块没有这一格,图谱再引到它时补上
+///
+/// 两个上限:清单每调一次工具就整份重发一遍,收尾那次请求也带着它,一块里抽出几十条事实
+/// 不该让它跟着长。超长的一句整句不记而不是截断——界面按原文找这句话,截过的找不到
+pub(super) fn add_quote(sink: &mut ToolSink, n: usize, quote: &str) {
+ if quote.chars().count() > QUOTE_CHARS {
+ return;
+ }
+ let Some(entry) = n.checked_sub(1).and_then(|i| sink.sources.get_mut(i)) else {
+ return;
+ };
+ let Some(map) = entry.as_object_mut() else {
+ return;
+ };
+ let quotes = map
+ .entry("quotes")
+ .or_insert_with(|| serde_json::Value::Array(Vec::new()));
+ if let Some(list) = quotes.as_array_mut() {
+ if list.len() < QUOTES_PER_SOURCE && !list.iter().any(|q| q.as_str() == Some(quote)) {
+ list.push(serde_json::Value::String(quote.to_string()));
+ }
+ }
+}
+
pub async fn search_chunks(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
diff --git a/crates/utopia-server/src/api/tools_graph.rs b/crates/utopia-server/src/api/tools_graph.rs
index 08c16b00..0119d17a 100644
--- a/crates/utopia-server/src/api/tools_graph.rs
+++ b/crates/utopia-server/src/api/tools_graph.rs
@@ -211,8 +211,11 @@ fn contains_ci(haystack: Option<&str>, needle: &str) -> bool {
/// 图谱答出来的回答一个号也没有,界面只能说「未引用任何来源」。印哪一行时才登记,
/// 所以号码按出现的顺序排,与检索结果共用一套号(同一块只有一个号)。
///
-/// 没有来源清单(MCP)、或证据读不出来时是空的:事实行照旧,不带号
-struct Evidence(HashMap<Uuid, utopia_core::models::ChunkView>);
+/// 没有来源清单(MCP)、或证据读不出来时是空的:事实行照旧,不带号。
+///
+/// 每条事实还带着那条证据的引文(#968 的后续):号打开的是那一块,条目里的 `quotes`
+/// 是块里说出它的那一句,界面据此把那句话标出来
+struct Evidence(HashMap<Uuid, (utopia_core::models::ChunkView, Option<String>)>);
impl Evidence {
/// 事实 id 收成自有的 `Vec` 再传进来:借着显示列表的迭代器跨 await 持有,工具的
@@ -228,7 +231,11 @@ impl Evidence {
match utopia_store::graph::first_live_evidence(&ctx.state.pool, ctx.kb_id, &fact_ids, as_of)
.await
{
- Ok(rows) => Self(rows.into_iter().collect()),
+ Ok(rows) => Self(
+ rows.into_iter()
+ .map(|(fact, chunk, quote)| (fact, (chunk, quote)))
+ .collect(),
+ ),
Err(e) => {
tracing::warn!(error = %e, "Evidence lookup for citation marks failed");
Self(HashMap::new())
@@ -239,10 +246,13 @@ impl Evidence {
/// ` [n]`:这条事实的证据登进清单后的号。没有有效证据的事实(派生事实也是)不带号
fn mark(&self, sink: &mut ToolSink, fact_id: Uuid) -> String {
match self.0.get(&fact_id) {
- Some(chunk) => {
+ Some((chunk, quote)) => {
let n = super::tools::cite(sink, chunk.id.to_string(), |n| {
super::tools::source_json(n, chunk)
});
+ if let Some(quote) = quote {
+ super::tools::add_quote(sink, n, quote);
+ }
format!(" [{n}]")
}
None => String::new(),
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index d77f7f72..4d993d43 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -1905,7 +1905,7 @@ pub async fn first_live_evidence(
kb_id: Uuid,
fact_ids: &[Uuid],
as_of: Option<chrono::DateTime<chrono::Utc>>,
-) -> AppResult<Vec<(Uuid, utopia_core::models::ChunkView)>> {
+) -> AppResult<Vec<(Uuid, utopia_core::models::ChunkView, Option<String>)>> {
if fact_ids.is_empty() {
return Ok(Vec::new());
}
@@ -1917,9 +1917,13 @@ pub async fn first_live_evidence(
seq: i32,
text: String,
filename: String,
+ quote: Option<String>,
}
+ // 连同那条证据的引文一起取(#968 的后续):号打开的是那一块,引文是块里说出这条事实的
+ // 那句话。同一块里几条证据时取块里最靠前的那一句,排序到此为止才是确定的
let rows: Vec<Row> = sqlx::query_as(&format!(
- "SELECT DISTINCT ON (fe.fact_id) fe.fact_id, c.id, c.document_id, c.seq, c.text, d.filename
+ "SELECT DISTINCT ON (fe.fact_id) fe.fact_id, c.id, c.document_id, c.seq, c.text, d.filename,
+ NULLIF(btrim(fe.quote), '') AS quote
FROM fact_evidence fe
JOIN chunks c ON c.id = fe.chunk_id
JOIN documents d ON d.id = c.document_id
@@ -1945,6 +1949,7 @@ pub async fn first_live_evidence(
text: r.text,
filename: r.filename,
},
+ r.quote,
)
})
.collect())
diff --git a/docs/design/chat-and-mcp.md b/docs/design/chat-and-mcp.md
index 09a7cff8..0d30c91e 100644
--- a/docs/design/chat-and-mcp.md
+++ b/docs/design/chat-and-mcp.md
@@ -39,6 +39,10 @@ later turn [0063].
line with the `[n]` of its first live evidence chunk, registered in the turn's source list the way a
search hit is, so a graph answer opens to its sentence; a derived fact carries no number and its
premises carry theirs where they are shown; MCP text stays unnumbered, its evidence being `document_ids` (#935). The
+entry a graph fact cites carries the sentence the fact was read from (`quotes`, one chunk keeping
+one number however many of its sentences are cited, a search hit gaining the sentence when a graph
+tool cites it), and the preview and the document page mark it, so the number opens the sentence
+itself (#968's follow-up). The
previous turn's tool calls are replayed so the model knows what it did, not only
what it said [0015]; a turn that gathers nothing, such as a restatement, keeps the previous answer's
sources for the citation numbers it repeats (#943).
diff --git a/web/src/api.ts b/web/src/api.ts
index 07451958..abaf458f 100644
--- a/web/src/api.ts
+++ b/web/src/api.ts
@@ -1474,6 +1474,8 @@ export interface Source {
heading?: string;
filename: string;
excerpt: string;
+ /** 块里被引到的那几句(图谱事实的引文,#968 的后续):界面在原文里把它们标出来 */
+ quotes?: string[];
}
/** Agentic 对话的行动轨迹(工具调用一步一条)。 */
diff --git a/web/src/pages/DocViewer.tsx b/web/src/pages/DocViewer.tsx
index 41b5530d..4df88e18 100644
--- a/web/src/pages/DocViewer.tsx
+++ b/web/src/pages/DocViewer.tsx
@@ -7,6 +7,7 @@ import { useKbId } from "../kb";
import { originHint, originLabel } from "../origin";
import { fmtTime } from "../time";
import { GroupLabel, PageHeader, Pager, pageSlice } from "../ui";
+import { QuotedText } from "../ui/citation";
import { SourcesRail } from "./SourcesRail";
const DOC_PAGE = 12;
@@ -21,7 +22,7 @@ function factRange(f: ChunkFact): string | null {
export function DocViewer() {
const kbId = useKbId();
const { docId } = useParams({ from: "/app/kb/$kbId/doc/$docId" });
- const { chunk } = useSearch({ from: "/app/kb/$kbId/doc/$docId" });
+ const { chunk, quote } = useSearch({ from: "/app/kb/$kbId/doc/$docId" });
const navigate = useNavigate();
const detail = useQuery({
@@ -125,7 +126,8 @@ export function DocViewer() {
</span>
)}
</div>
- {c.text}
+ {/* 从一条图谱事实的号跳来时,标出说出它的那一句(#968 的后续) */}
+ {hit && quote ? <QuotedText text={c.text} quotes={[quote]} /> : c.text}
</div>
{/* 抽取对照栏:这个分块产出了哪些事实(实体可跳图谱)。
diff --git a/web/src/pages/chatCitations.tsx b/web/src/pages/chatCitations.tsx
index 19b91c83..395b942b 100644
--- a/web/src/pages/chatCitations.tsx
+++ b/web/src/pages/chatCitations.tsx
@@ -10,7 +10,8 @@ import { citeHref } from "../citations";
import { S } from "../i18n";
import { useKbId } from "../kb";
import { originLabel } from "../origin";
-import { CiteChip, CiteMark, CiteRow, PreviewCard } from "../ui/citation";
+import { quoteParam, sourceLead } from "../quotes";
+import { CiteChip, CiteMark, CiteRow, PreviewCard, QuotedText } from "../ui/citation";
import { CodeBlock } from "./chatCopy";
/** 这一轮回答的来源。
@@ -75,7 +76,7 @@ export function SourceList({ sources }: { sources: Source[] }) {
) : (
<span className="block truncate">
<span className="u-num text-accent">[{s.n}]</span> {s.filename} ·{" "}
- {s.excerpt.slice(0, 60)}…
+ {sourceLead(s).slice(0, 60)}…
</span>
)}
</CiteRow>
@@ -127,12 +128,12 @@ function SourcePreview({ s }: { s: Source }) {
<PreviewCard
title={s.filename}
meta={originLabel(chunk?.origin, chunk?.anchor) ?? undefined}
- body={chunk?.text ?? s.excerpt}
+ body={<QuotedText text={chunk?.text ?? s.excerpt} quotes={s.quotes} />}
action={
<Link
to="/kb/$kbId/doc/$docId"
params={{ kbId, docId: s.document_id! }}
- search={{ chunk: s.chunk_id }}
+ search={{ chunk: s.chunk_id, quote: quoteParam(s.quotes?.[0]) }}
className="u-card-link flex items-center gap-1 text-fine text-ink-2"
>
{S.ask.openOriginal}
diff --git a/web/src/quotes.test.ts b/web/src/quotes.test.ts
new file mode 100644
index 00000000..ed949df5
--- /dev/null
+++ b/web/src/quotes.test.ts
@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { QUOTE_PARAM_MAX, docSearch, quoteParam, quotePieces, sourceLead } from "./quotes";
+
+const text = "Project Aurora started on 2023-01-10.\n\nZhang San leads Project Aurora from 2023-01-10.";
+
+describe("the sentences a source quotes", () => {
+ it("are marked where they stand in the passage", () => {
+ expect(quotePieces(text, ["Zhang San leads Project Aurora from 2023-01-10."])).toEqual([
+ { text: "Project Aurora started on 2023-01-10.\n\n", quoted: false },
+ { text: "Zhang San leads Project Aurora from 2023-01-10.", quoted: true },
+ ]);
+ });
+
+ it("match across the passage's own line breaks", () => {
+ const pieces = quotePieces("Li Si leads\nProject Aurora.", ["Li Si leads Project Aurora."]);
+ expect(pieces).toEqual([{ text: "Li Si leads\nProject Aurora.", quoted: true }]);
+ });
+
+ it("leave the passage as it is when a quote is not in it", () => {
+ expect(quotePieces(text, ["Wang Wu advises Project Aurora."])).toEqual([
+ { text, quoted: false },
+ ]);
+ expect(quotePieces(text, undefined)).toEqual([{ text, quoted: false }]);
+ expect(quotePieces(text, [" "])).toEqual([{ text, quoted: false }]);
+ });
+
+ it("merge sentences that overlap, and keep two apart ones apart", () => {
+ const merged = quotePieces(text, ["Project Aurora started on", "started on 2023-01-10."]);
+ expect(merged[0]).toEqual({ text: "Project Aurora started on 2023-01-10.", quoted: true });
+ const both = quotePieces(text, [
+ "Zhang San leads Project Aurora from 2023-01-10.",
+ "Project Aurora started on 2023-01-10.",
+ ]);
+ expect(both.filter((p) => p.quoted).map((p) => p.text)).toEqual([
+ "Project Aurora started on 2023-01-10.",
+ "Zhang San leads Project Aurora from 2023-01-10.",
+ ]);
+ expect(both.map((p) => p.text).join("")).toBe(text);
+ });
+
+ it("read a quote with the characters a pattern would take as syntax", () => {
+ const pieces = quotePieces("Revenue (USD) rose 3.5% [est.]", ["(USD) rose 3.5% [est.]"]);
+ expect(pieces.filter((p) => p.quoted).map((p) => p.text)).toEqual(["(USD) rose 3.5% [est.]"]);
+ });
+});
+
+describe("a source's lead in the list", () => {
+ it("is its first quoted sentence, else the passage's opening", () => {
+ expect(sourceLead({ excerpt: "Project Aurora started", quotes: ["Zhang San leads"] })).toBe(
+ "Zhang San leads",
+ );
+ expect(sourceLead({ excerpt: "Project Aurora started" })).toBe("Project Aurora started");
+ });
+});
+
+describe("the document page's search", () => {
+ it("keeps the chunk and a non-blank quote", () => {
+ expect(docSearch({ chunk: "c1", quote: "Li Si leads" })).toEqual({
+ chunk: "c1",
+ quote: "Li Si leads",
+ });
+ expect(docSearch({ chunk: "c1", quote: " " })).toEqual({ chunk: "c1", quote: undefined });
+ expect(docSearch({ chunk: 3, quote: ["x"] })).toEqual({ chunk: undefined, quote: undefined });
+ });
+});
+
+describe("quoteParam", () => {
+ it("keeps a sentence short enough for the address bar and drops a longer one whole", () => {
+ expect(quoteParam("Li Si leads Project Aurora.")).toBe("Li Si leads Project Aurora.");
+ expect(quoteParam("界".repeat(QUOTE_PARAM_MAX))).toBe("界".repeat(QUOTE_PARAM_MAX));
+ expect(quoteParam("界".repeat(QUOTE_PARAM_MAX + 1))).toBeUndefined();
+ expect(quoteParam(" ")).toBeUndefined();
+ expect(docSearch({ chunk: "c", quote: "x".repeat(QUOTE_PARAM_MAX + 1) })).toEqual({
+ chunk: "c",
+ quote: undefined,
+ });
+ });
+});
diff --git a/web/src/quotes.ts b/web/src/quotes.ts
new file mode 100644
index 00000000..283e8dde
--- /dev/null
+++ b/web/src/quotes.ts
@@ -0,0 +1,67 @@
+// 原文里被引到的那几句(#968 的后续)。
+//
+// 图谱工具给一条事实印的号打开的是它第一条有效证据的那一块;来源条目的 `quotes` 是块里
+// 说出这条(或这几条)事实的那几句。预览浮窗和文档页据此把它们标出来,号打开的就是那句话。
+//
+// 每一句只找第一次出现;找不到的(引文与原文对不上)不标;重叠或相接的并成一段。
+// 空白按「一处或多处空白」对:引文里的一个空格对得上原文里的换行。
+
+export type QuotePiece = { text: string; quoted: boolean };
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** 一句引文在原文里第一次出现的位置,`[起, 止)`;对不上是 null */
+function locate(text: string, quote: string): [number, number] | null {
+ const words = quote.trim().split(/\s+/).filter(Boolean);
+ if (words.length === 0) return null;
+ const m = new RegExp(words.map(escape).join("\\s+")).exec(text);
+ return m ? [m.index, m.index + m[0].length] : null;
+}
+
+/** 把原文切成「普通」与「被引」两种片段,按原来的顺序 */
+export function quotePieces(text: string, quotes: readonly string[] | undefined): QuotePiece[] {
+ const spans = (quotes ?? [])
+ .map((q) => locate(text, q))
+ .filter((s): s is [number, number] => s !== null)
+ .sort((a, b) => a[0] - b[0]);
+ const merged: [number, number][] = [];
+ for (const [start, end] of spans) {
+ const last = merged[merged.length - 1];
+ if (last && start <= last[1]) last[1] = Math.max(last[1], end);
+ else merged.push([start, end]);
+ }
+ const out: QuotePiece[] = [];
+ let at = 0;
+ for (const [start, end] of merged) {
+ if (start > at) out.push({ text: text.slice(at, start), quoted: false });
+ out.push({ text: text.slice(start, end), quoted: true });
+ at = end;
+ }
+ if (at < text.length) out.push({ text: text.slice(at), quoted: false });
+ return out;
+}
+
+/** 落款行上那一条的摘要:有被引的句子就是第一句,否则是这一块的开头 */
+export function sourceLead(source: { excerpt: string; quotes?: string[] }): string {
+ return source.quotes?.[0] ?? source.excerpt;
+}
+
+/** 进地址栏的那一句最长多少字。地址会留在浏览器历史和代理的访问日志里,刷新时整条重发:
+ * 一个汉字编码后约九个字节,几百字就顶到常见的 8k 请求头上限。超长的一句不带——
+ * 截断了在原文里找不到,标不出来,不如不标 */
+export const QUOTE_PARAM_MAX = 300;
+
+/** 能进地址栏的一句:空白的、超长的都等于没给 */
+export function quoteParam(quote: unknown): string | undefined {
+ return typeof quote === "string" && quote.trim() && quote.length <= QUOTE_PARAM_MAX
+ ? quote
+ : undefined;
+}
+
+/** 文档页的查询参数:引用跳转到哪一块,块里标出哪一句 */
+export function docSearch(search: Record<string, unknown>): { chunk?: string; quote?: string } {
+ return {
+ chunk: typeof search.chunk === "string" ? search.chunk : undefined,
+ quote: quoteParam(search.quote),
+ };
+}
diff --git a/web/src/router.tsx b/web/src/router.tsx
index 18e2bac3..561474a1 100644
--- a/web/src/router.tsx
+++ b/web/src/router.tsx
@@ -1,4 +1,5 @@
import { ExpressionDraftLab } from "./pages/ExpressionDraftLab";
+import { docSearch } from "./quotes";
import {
createRootRoute,
createRoute,
@@ -119,9 +120,7 @@ const graphRoute = createRoute({
const docRoute = createRoute({
getParentRoute: () => kbRoute,
path: "doc/$docId",
- validateSearch: (search: Record<string, unknown>): { chunk?: string } => ({
- chunk: typeof search.chunk === "string" ? search.chunk : undefined,
- }),
+ validateSearch: docSearch,
component: DocViewer,
});
diff --git a/web/src/ui/citation.tsx b/web/src/ui/citation.tsx
index 872e45e8..3cbedb22 100644
--- a/web/src/ui/citation.tsx
+++ b/web/src/ui/citation.tsx
@@ -3,6 +3,7 @@
而跳转会把人从答案里带走,回来时答案已经滚上去了。 */
import { Popover as RadixPopover } from "radix-ui";
import type { ReactNode } from "react";
+import { quotePieces } from "../quotes";
/** 正文里的一个 `[n]`。流式中来源还没到的号用 {@link CiteMark} 画成静的 */
export function CiteChip({
@@ -79,6 +80,23 @@ function PreviewPortal({
}
/** 浮窗的样子:标题一行、原文一段、右上角一条出路 */
+/** 一段原文,被引到的那几句用检索命中的样子标出来(#968 的后续)。对不上的引文不标 */
+export function QuotedText({ text, quotes }: { text: string; quotes?: readonly string[] }) {
+ return (
+ <>
+ {quotePieces(text, quotes).map((p, i) =>
+ p.quoted ? (
+ <mark key={i} className="u-mark">
+ {p.text}
+ </mark>
+ ) : (
+ <span key={i}>{p.text}</span>
+ ),
+ )}
+ </>
+ );
+}
+
export function PreviewCard({
title,
meta,