Skip to content

World's first open-source enterprise world model.

Graph answers cite the sentence each fact was read from (#968)

Maya Kid9a0145648bd9
diff --git a/crates/utopia-server/src/api/chat.rs b/crates/utopia-server/src/api/chat.rs
index 738662df..c5b3e65b 100644
--- a/crates/utopia-server/src/api/chat.rs
+++ b/crates/utopia-server/src/api/chat.rs
@@ -652,14 +652,17 @@ const SYSTEM_PROMPT: &str = "You are the assistant of Utopia, a temporal knowled
server reads the base as it stood strictly before that change. Never compute an earlier \
`as_of` yourself. Keep `at` for the world date asked about.\n\
2b. For \"what changed / what is new / what did we get wrong since <date>\", call changes — \
- it needs no entity. Name the document a correction came from in plain prose. Graph tools \
- return no [n] numbers and no URLs, so never write a bracketed citation or a placeholder \
- like [Link] after one — the document's name IS the attribution.\n\
+ it needs no entity. Name the document a correction came from in plain prose. changes \
+ returns no [n] numbers and no URLs, so never write a bracketed citation or a placeholder \
+ like [Link] after one of its lines — the document's name IS the attribution.\n\
3. Several entities can share one name — check the disambiguator and pick the right one; \
if genuinely ambiguous, ask the user which one they mean.\n\
4. Stop calling tools as soon as you have enough evidence. Then answer concisely: cite \
- document sources with [n] (numbers from search results) at the end of supported \
- sentences. If the evidence is insufficient, say so explicitly — never fabricate.\n\
+ with [n] at the end of supported sentences, using only numbers a tool printed. Search \
+ results carry them, and so does each fact line of entity_facts, neighbors, timeline and \
+ paths_between: its [n] opens the passage that fact was read from. A fact line without \
+ a number (a derived fact, or one whose documents are gone) is stated without a bracket. \
+ If the evidence is insufficient, say so explicitly — never fabricate.\n\
5. Always respond in the same language as the user's question.";
pub async fn chat(
diff --git a/crates/utopia-server/src/api/chat_empty_reply_tests.rs b/crates/utopia-server/src/api/chat_empty_reply_tests.rs
index 1c95954b..a4e0e317 100644
--- a/crates/utopia-server/src/api/chat_empty_reply_tests.rs
+++ b/crates/utopia-server/src/api/chat_empty_reply_tests.rs
@@ -375,6 +375,8 @@ async fn a_reply_that_stays_empty_is_an_error_after_one_retry() -> anyhow::Resul
mod error_code_tests;
#[path = "chat_fallback_tests.rs"]
mod fallback_tests;
+#[path = "chat_graph_citation_tests.rs"]
+mod graph_citation_tests;
#[path = "chat_history_tests.rs"]
mod history_tests;
#[path = "chat_lookup_tests.rs"]
diff --git a/crates/utopia-server/src/api/chat_finalization.rs b/crates/utopia-server/src/api/chat_finalization.rs
index 7805fa7c..4088810f 100644
--- a/crates/utopia-server/src/api/chat_finalization.rs
+++ b/crates/utopia-server/src/api/chat_finalization.rs
@@ -15,8 +15,9 @@ const ANSWER_ONLY_SYSTEM: &str = "Write the final answer to the current question
No tools are available; do not call or encode tool invocations. Preserve numbers, units, thresholds, \
ranges, conditions, and the distinction between plans, historical reports, and verified results. \
Distinguish world validity time from record time and preserve the stated precision of dates. \
- Use [n] citations only for the CURRENT sources registry. Graph evidence without citation numbers \
- must be attributed by the supplied document or fact names, never invented [n] references. \
+ Use [n] citations only for the CURRENT sources registry; a graph fact line that ends in [n] cites \
+ its evidence there. Evidence without a citation number (changes, a derived fact) must be attributed \
+ by the supplied document or fact names, never invented [n] references. \
Conversation context and prior-turn observations are background with a SEPARATE, UNMAPPED citation \
namespace: their [1] is not current [1]. Attribute them by document name or as a previous answer; \
never transfer their numeric citations to current sources. Prior assistant answers are not primary evidence. \
diff --git a/crates/utopia-server/src/api/chat_graph_citation_tests.rs b/crates/utopia-server/src/api/chat_graph_citation_tests.rs
new file mode 100644
index 00000000..24c571f1
--- /dev/null
+++ b/crates/utopia-server/src/api/chat_graph_citation_tests.rs
@@ -0,0 +1,325 @@
+//! 图谱答出来的回答点得开原句(#935)。
+//!
+//! 四个图谱工具(entity_facts、neighbors、timeline、paths_between)在对话里给每条显示出来
+//! 的事实印上它第一条有效证据的 `[n]`,证据块登进这一轮的来源清单,与检索结果共用一套号。
+//! 这里钉住:
+//!
+//! - 每个工具的号都指向那条事实的证据块;几条证据时取最早那篇文档的
+//! - 同一块在一轮里只有一个号,换一个工具再印还是它
+//! - 证据只在已删文档里的事实不带号;`as_of` 回到删除之前,它又带上号
+//! - 派生事实那一行不带号,它的前提各带各的
+//! - MCP 的文字一字不改,来源清单是空的(号码对没有清单的调用方没有意义)
+//! - 整条对话:工具印的号随 `sources` 帧发出去、跟着回答落库,模型读到的事实行带着号
+//!
+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
+use super::*;
+use crate::api::tools::{dispatch, ToolCtx, ToolSink};
+
+struct Seed {
+ /// 张三 leads Aurora 的两条证据:早的那篇(charter)与晚的那篇(recap)
+ charter: Uuid,
+ recap: Uuid,
+ /// 李四 leads Aurora 的证据
+ handover: Uuid,
+ /// 王五 advises Aurora 的唯一证据,在一篇删掉的文档里
+ deleted: Uuid,
+}
+
+/// 一个项目、三个人、四篇文档(一篇已删),外加一条对称规则推出来的事实
+async fn seed(pool: &sqlx::PgPool, kb: Uuid) -> anyhow::Result<Seed> {
+ let id = Uuid::now_v7;
+ let (person, project, leads, advises, works_with, rule) = (id(), id(), id(), id(), id(), id());
+ let (zhang, li, wang, aurora) = (id(), id(), id(), id());
+ let (d_charter, d_recap, d_handover, d_deleted) = (id(), id(), id(), id());
+ let (charter, recap, handover, deleted) = (id(), id(), id(), id());
+ let (f_zhang, f_li, f_wang, f_pair, derived) = (id(), id(), id(), id(), id());
+ // 插进去的只有本地生成的 UUID 和写死的日期
+ sqlx::raw_sql(&format!(
+ r#"
+ INSERT INTO entity_types(id,kb_id,key,label) VALUES
+ ('{person}','{kb}','person','Person'), ('{project}','{kb}','project','Project');
+ INSERT INTO relation_types(id,kb_id,key,label,temporal) VALUES
+ ('{leads}','{kb}','leads','leads','state'),
+ ('{advises}','{kb}','advises','advises','state'),
+ ('{works_with}','{kb}','works_with','works with','state');
+ INSERT INTO entities(id,kb_id,type_id,canonical_name,created_at) VALUES
+ ('{zhang}','{kb}','{person}','Zhang San','2026-01-01'),
+ ('{li}','{kb}','{person}','Li Si','2026-01-01'),
+ ('{wang}','{kb}','{person}','Wang Wu','2026-01-01'),
+ ('{aurora}','{kb}','{project}','Project Aurora','2026-01-01');
+ INSERT INTO documents(id,kb_id,filename,sha256,created_at,doc_time,deleted_at) VALUES
+ ('{d_charter}','{kb}','charter.md',repeat('1',64),'2026-01-01','2023-01-05',NULL),
+ ('{d_recap}','{kb}','recap.md',repeat('2',64),'2025-12-01','2025-01-01',NULL),
+ ('{d_handover}','{kb}','handover.md',repeat('3',64),'2026-01-01','2024-07-05',NULL),
+ ('{d_deleted}','{kb}','advisor-note.md',repeat('4',64),'2026-01-01','2023-03-02','2026-06-01');
+ INSERT INTO chunks(id,kb_id,document_id,seq,text,created_at) VALUES
+ ('{charter}','{kb}','{d_charter}',0,'Zhang San leads Project Aurora from 2023-01-10.','2026-01-01'),
+ ('{recap}','{kb}','{d_recap}',0,'Zhang San led Project Aurora until the handover.','2026-01-01'),
+ ('{handover}','{kb}','{d_handover}',0,'Li Si leads Project Aurora from 2024-07-05.','2026-01-01'),
+ ('{deleted}','{kb}','{d_deleted}',0,'Wang Wu advises Project Aurora.','2026-01-01');
+ INSERT INTO facts(id,kb_id,subject_id,predicate_id,object_id,valid_from,valid_from_precision,
+ valid_to,valid_to_precision,recorded_at,confidence) VALUES
+ ('{f_zhang}','{kb}','{zhang}','{leads}','{aurora}','2023-01-10','day','2024-07-05','day','2026-01-01',0.9),
+ ('{f_li}','{kb}','{li}','{leads}','{aurora}','2024-07-05','day',NULL,NULL,'2026-01-01',0.9),
+ ('{f_wang}','{kb}','{wang}','{advises}','{aurora}','2023-03-02','day',NULL,NULL,'2026-01-01',0.9),
+ ('{f_pair}','{kb}','{zhang}','{works_with}','{li}','2023-01-10','day',NULL,NULL,'2026-01-01',0.9);
+ -- 晚的那篇先插、也先入库:取哪条证据按文档自己的日期,不按插入或入库的先后
+ INSERT INTO fact_evidence(fact_id,chunk_id,document_id,doc_version,quote) VALUES
+ ('{f_zhang}','{recap}','{d_recap}',1,'Zhang San led Project Aurora until the handover.'),
+ ('{f_zhang}','{charter}','{d_charter}',1,'Zhang San leads Project Aurora from 2023-01-10.'),
+ ('{f_li}','{handover}','{d_handover}',1,'Li Si leads Project Aurora from 2024-07-05.'),
+ ('{f_wang}','{deleted}','{d_deleted}',1,'Wang Wu advises Project Aurora.'),
+ ('{f_pair}','{charter}','{d_charter}',1,'Zhang San leads Project Aurora from 2023-01-10.');
+ INSERT INTO rules(id,kb_id,predicate_id,kind) VALUES ('{rule}','{kb}','{works_with}','symmetric');
+ INSERT INTO derived_facts(id,kb_id,subject_id,predicate_id,object_id,rule_id,derived_at,
+ valid_from,valid_from_precision) VALUES
+ ('{derived}','{kb}','{li}','{works_with}','{zhang}','{rule}','2026-01-01','2023-01-10','day');
+ INSERT INTO fact_derivations(derived_fact_id,premise_fact_id,seq) VALUES ('{derived}','{f_pair}',0);
+ "#
+ ))
+ .execute(pool)
+ .await?;
+ Ok(Seed {
+ charter,
+ recap,
+ handover,
+ deleted,
+ })
+}
+
+fn ctx(f: &Fx, via_token: Option<Uuid>) -> ToolCtx<'_> {
+ ToolCtx {
+ state: &f.state,
+ kb_id: f.kb,
+ workspace_id: Uuid::nil(),
+ mounted_sources: &[],
+ can_write: false,
+ actor: Some(f.user.id),
+ via_token,
+ question: None,
+ }
+}
+
+/// 一段文字里的引用号:`[3]` 算,置信度 `[90%]` 和 `[rule: …]` 不算
+fn marks(text: &str) -> Vec<usize> {
+ text.match_indices('[')
+ .filter_map(|(at, _)| {
+ let rest = &text[at + 1..];
+ let end = rest.find(']')?;
+ rest[..end].parse().ok()
+ })
+ .collect()
+}
+
+/// 含 `needle` 的那一行。neighbors 把一组的几项写在同一行、用 ` · ` 隔开,取的是那一项
+fn line<'t>(text: &'t str, needle: &str) -> &'t str {
+ text.lines()
+ .flat_map(|l| l.split(" · "))
+ .find(|item| item.contains(needle))
+ .unwrap_or_else(|| panic!("no line with {needle:?} in:\n{text}"))
+}
+
+/// 号 `n` 在清单里登的是哪一块
+fn chunk_of(sink: &ToolSink, n: usize) -> Uuid {
+ sink.sources[n - 1]["chunk_id"]
+ .as_str()
+ .and_then(|s| s.parse().ok())
+ .unwrap_or_else(|| panic!("no source {n} in {:?}", sink.sources))
+}
+
+#[tokio::test]
+async fn each_graph_tool_cites_the_first_live_evidence_of_each_fact() -> 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 chat = ctx(&f, None);
+ let mut sink = ToolSink::default();
+
+ let facts = dispatch(
+ &chat,
+ &mut sink,
+ "entity_facts",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await;
+ let text = &facts.text;
+ let zhang = marks(line(text, "Zhang San"));
+ let li = marks(line(text, "Li Si"));
+ assert_eq!(zhang.len(), 1, "{text}");
+ assert_eq!(
+ chunk_of(&sink, zhang[0]),
+ s.charter,
+ "the earliest document's chunk, not the recap"
+ );
+ assert_eq!(li.len(), 1, "{text}");
+ assert_eq!(chunk_of(&sink, li[0]), s.handover);
+ assert!(
+ marks(line(text, "Wang Wu")).is_empty(),
+ "evidence only in a deleted document: {text}"
+ );
+ assert_eq!(sink.sources.len(), 2, "{:?}", sink.sources);
+ assert_eq!(sink.sources[zhang[0] - 1]["filename"], "charter.md");
+ assert!(
+ sink.sources
+ .iter()
+ .all(|x| x["chunk_id"] != s.recap.to_string()),
+ "one number per fact: the later evidence is not listed"
+ );
+
+ // 同一块同一个号:换一个工具再印,清单不长
+ let near = dispatch(
+ &chat,
+ &mut sink,
+ "neighbors",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await;
+ assert_eq!(marks(line(&near.text, "Zhang San")), zhang, "{}", near.text);
+ assert_eq!(marks(line(&near.text, "Li Si")), li, "{}", near.text);
+ let dated = dispatch(
+ &chat,
+ &mut sink,
+ "timeline",
+ &json!({"entity": "Project Aurora"}),
+ )
+ .await;
+ assert_eq!(
+ marks(line(&dated.text, "Zhang San")),
+ zhang,
+ "{}",
+ dated.text
+ );
+ assert_eq!(marks(line(&dated.text, "Li Si")), li, "{}", dated.text);
+ assert!(
+ marks(line(&dated.text, "Wang Wu")).is_empty(),
+ "{}",
+ dated.text
+ );
+ // 路径的每一跳是一条事实,各带各的号:王五那一跳的证据在删掉的文档里,不带
+ let path = dispatch(
+ &chat,
+ &mut sink,
+ "paths_between",
+ &json!({"from": "Wang Wu", "to": "Li Si"}),
+ )
+ .await;
+ let hops = line(&path.text, "—advises→");
+ assert_eq!(marks(hops), [li[0]], "{}", path.text);
+ assert_eq!(
+ sink.sources.len(),
+ 2,
+ "no chunk was numbered twice: {:?}",
+ sink.sources
+ );
+
+ // 派生那一行不带号;它的前提(张三 works with 李四)带着自己的号
+ let li_facts = dispatch(
+ &chat,
+ &mut sink,
+ "entity_facts",
+ &json!({"entity": "Li Si"}),
+ )
+ .await;
+ let derived = line(&li_facts.text, "[rule:");
+ assert!(marks(derived).is_empty(), "{}", li_facts.text);
+ let premise = marks(line(&li_facts.text, "Zhang San"));
+ assert_eq!(premise.len(), 1, "{}", li_facts.text);
+ assert_eq!(chunk_of(&sink, premise[0]), s.charter);
+
+ // 回到删除之前:那篇文档当时还在,王五的事实带上号
+ let mut before = ToolSink::default();
+ let then = dispatch(
+ &chat,
+ &mut before,
+ "entity_facts",
+ &json!({"entity": "Project Aurora", "as_of": "2026-03-01"}),
+ )
+ .await;
+ let wang = marks(line(&then.text, "Wang Wu"));
+ assert_eq!(wang.len(), 1, "{}", then.text);
+ assert_eq!(chunk_of(&before, wang[0]), s.deleted);
+
+ // MCP:文字与对话里去掉号之后一字不差,清单是空的
+ let mcp = ctx(&f, Some(Uuid::now_v7()));
+ for (tool, args) in [
+ ("entity_facts", json!({"entity": "Project Aurora"})),
+ ("neighbors", json!({"entity": "Project Aurora"})),
+ ("timeline", json!({"entity": "Project Aurora"})),
+ ("paths_between", json!({"from": "Wang Wu", "to": "Li Si"})),
+ ] {
+ let mut empty = ToolSink::default();
+ let plain = dispatch(&mcp, &mut empty, tool, &args).await.text;
+ let numbered = dispatch(&chat, &mut ToolSink::default(), tool, &args)
+ .await
+ .text;
+ let mut stripped = numbered.clone();
+ for n in 1..=2 {
+ stripped = stripped.replace(&format!(" [{n}]"), "");
+ }
+ assert_eq!(plain, stripped, "{tool} over MCP keeps its text");
+ assert!(marks(&plain).is_empty(), "{tool}: {plain}");
+ assert!(empty.sources.is_empty(), "{tool}: {:?}", empty.sources);
+ }
+ anyhow::Ok(())
+ }
+ .await;
+ f.cleanup().await?;
+ run
+}
+
+#[tokio::test]
+async fn a_graph_answer_publishes_and_stores_its_sources() -> anyhow::Result<()> {
+ let Some(f) = fixture(Scripted::new(vec![
+ Reply::Tool("entity_facts", r#"{"entity_id":"Project Aurora"}"#),
+ Reply::Text("Li Si leads Project Aurora."),
+ ]))
+ .await?
+ else {
+ return Ok(());
+ };
+ let run = async {
+ let s = seed(&f.pool, f.kb).await?;
+ let sse = f.ask("Who leads Project Aurora?").await?;
+ assert!(sse.contains("event: done"), "{sse}");
+
+ // `sources` 帧:两块证据,按印出来的顺序编号
+ 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();
+ let last = published.last().expect("a sources frame");
+ let chunks: Vec<&str> = last
+ .as_array()
+ .unwrap()
+ .iter()
+ .filter_map(|s| s["chunk_id"].as_str())
+ .collect();
+ assert_eq!(chunks.len(), 2, "{last}");
+ assert!(chunks.contains(&s.charter.to_string().as_str()), "{last}");
+ assert!(chunks.contains(&s.handover.to_string().as_str()), "{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);
+
+ // 模型读到的事实行带着号:置信度后面跟着它
+ let requests = f.requests();
+ let sent = requests[1]["messages"].to_string();
+ assert!(sent.contains("Li Si") && sent.contains("%] ["), "{sent}");
+ 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 c6f21452..144a8328 100644
--- a/crates/utopia-server/src/api/tools.rs
+++ b/crates/utopia-server/src/api/tools.rs
@@ -49,6 +49,13 @@ pub struct ToolCtx<'a> {
}
impl ToolCtx<'_> {
+ /// 这一轮有没有来源清单:对话有,MCP 没有(MCP 的调用总带着令牌)。
+ /// 图谱事实行上的 `[n]` 只在有清单时印(#935)——号码指向清单里的一条,
+ /// 对一个手里没有清单的调用方没有意义,它从 `structuredContent` 的 `document_ids` 取出处
+ pub fn has_source_list(&self) -> bool {
+ self.via_token.is_none()
+ }
+
/// 一段文字的向量,用这个工作区配的嵌入模型。没配、或调用失败时 None:
/// 图谱工具照常按子串走,向量只是第二阶段
pub async fn embed(&self, text: &str) -> Option<Vec<f32>> {
@@ -237,7 +244,11 @@ pub async fn dispatch(
/// 已经引过的给回原号,没引过的落一个新号。**同一个 chunk 在一轮对话里
/// 只能有一个号**,否则模型引 `[2]` 而界面上有两个 `[2]`。
-fn cite(sink: &mut ToolSink, key: String, make: impl FnOnce(usize) -> serde_json::Value) -> usize {
+pub(super) fn cite(
+ sink: &mut ToolSink,
+ key: String,
+ make: impl FnOnce(usize) -> serde_json::Value,
+) -> usize {
match sink.source_ids.iter().position(|id| *id == key) {
Some(i) => i + 1,
None => {
diff --git a/crates/utopia-server/src/api/tools_graph.rs b/crates/utopia-server/src/api/tools_graph.rs
index c5e411c3..80906902 100644
--- a/crates/utopia-server/src/api/tools_graph.rs
+++ b/crates/utopia-server/src/api/tools_graph.rs
@@ -203,6 +203,53 @@ fn contains_ci(haystack: Option<&str>, needle: &str) -> bool {
haystack.is_some_and(|h| h.to_lowercase().contains(&needle.to_lowercase()))
}
+// ---- evidence marks (#935) -------------------------------------------------------
+
+/// 这一次显示出来的事实各自的第一条有效证据(#935)。
+///
+/// 事实行上印它的 `[n]`,证据块登进这一轮的来源清单,界面上点开就是那句原话;从前
+/// 图谱答出来的回答一个号也没有,界面只能说「未引用任何来源」。印哪一行时才登记,
+/// 所以号码按出现的顺序排,与检索结果共用一套号(同一块只有一个号)。
+///
+/// 没有来源清单(MCP)、或证据读不出来时是空的:事实行照旧,不带号
+struct Evidence(HashMap<Uuid, utopia_core::models::ChunkView>);
+
+impl Evidence {
+ /// 事实 id 收成自有的 `Vec` 再传进来:借着显示列表的迭代器跨 await 持有,工具的
+ /// future 就不再对所有生命周期都是 `Send`(对话的钩子与 MCP 路由都要求它)
+ async fn load(
+ ctx: &ToolCtx<'_>,
+ fact_ids: Vec<Uuid>,
+ as_of: Option<chrono::DateTime<chrono::Utc>>,
+ ) -> Self {
+ if !ctx.has_source_list() {
+ return Self(HashMap::new());
+ }
+ 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()),
+ Err(e) => {
+ tracing::warn!(error = %e, "Evidence lookup for citation marks failed");
+ Self(HashMap::new())
+ }
+ }
+ }
+
+ /// ` [n]`:这条事实的证据登进清单后的号。没有有效证据的事实(派生事实也是)不带号
+ fn mark(&self, sink: &mut ToolSink, fact_id: Uuid) -> String {
+ match self.0.get(&fact_id) {
+ Some(chunk) => {
+ let n = super::tools::cite(sink, chunk.id.to_string(), |n| {
+ super::tools::source_json(n, chunk)
+ });
+ format!(" [{n}]")
+ }
+ None => String::new(),
+ }
+ }
+}
+
// ---- find_entities ---------------------------------------------------------------
pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
@@ -726,19 +773,23 @@ pub async fn entity_facts(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
));
}
lines.push(head);
+ let ids: Vec<Uuid> = shown.iter().map(|f| f.id).collect();
+ let evidence = Evidence::load(ctx, ids, m.as_of).await;
let shown_owned: Vec<EntityFact> = shown.iter().map(|f| (*f).clone()).collect();
for (key, group) in grouped(&shown_owned) {
lines.push(format!("## {key} ({})", group.len()));
for f in group {
lines.push(format!(
- "{}{}{} {}",
+ "{}{}{} {}{}",
other_text(f),
qualifiers_text(f),
range_text(f),
- confidence_text(f)
+ confidence_text(f),
+ evidence.mark(sink, f.id)
));
}
}
+ // 派生事实自己不带号:它是规则算出来的,出处在它的前提上,前提各带各的
lines.extend(derived_lines);
}
let detail = entity_facts_detail(shown.len(), m.at, m.as_of, m.before);
@@ -884,6 +935,8 @@ pub async fn neighbors(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) ->
}
));
} else {
+ let ids: Vec<Uuid> = shown.iter().map(|f| f.id).collect();
+ let evidence = Evidence::load(ctx, ids, m.as_of).await;
let groups = grouped(&shown);
// 数的是对端实体,不是事实:同一条边常是两条事实(一条带日期一条不带)
let entities: HashSet<Uuid> = linked.iter().filter_map(|f| f.other_id).collect();
@@ -910,11 +963,12 @@ pub async fn neighbors(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) ->
.map(|t| format!(" [{t}]"))
.unwrap_or_default();
format!(
- "{}{}{} {}",
+ "{}{}{} {}{}",
other_text(f),
ty,
range_text(f),
- confidence_text(f)
+ confidence_text(f),
+ evidence.mark(sink, f.id)
)
})
.collect();
@@ -1027,12 +1081,18 @@ pub async fn timeline(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> T
));
}
lines.push(head);
+ let ids: Vec<Uuid> = shown.iter().map(|f| f.id).collect();
+ let evidence = Evidence::load(ctx, ids, m.as_of).await;
for f in &shown {
let stamp = crate::time_text::world(
f.valid_from.expect("dated"),
f.valid_from_precision.as_deref(),
);
- lines.push(format!("{stamp} {}", fact_line(f)));
+ lines.push(format!(
+ "{stamp} {}{}",
+ fact_line(f),
+ evidence.mark(sink, f.id)
+ ));
}
}
let detail = format!("{} of {} dated", shown.len(), dated.len());
@@ -1077,10 +1137,16 @@ pub(super) fn edge_text(prev: Uuid, e: &PathEdge) -> String {
}
}
+#[cfg(test)]
pub(super) fn path_text(p: &Path) -> String {
+ path_text_marked(p, |_| String::new())
+}
+
+/// 一条路径,每一跳后面跟着 `mark` 给那条事实的东西(对话里是它证据的 `[n]`,#935)
+fn path_text_marked(p: &Path, mut mark: impl FnMut(Uuid) -> String) -> String {
let mut parts = Vec::new();
for (i, e) in p.edges.iter().enumerate() {
- parts.push(edge_text(p.nodes[i], e));
+ parts.push(format!("{}{}", edge_text(p.nodes[i], e), mark(e.fact_id)));
}
parts.join("; ")
}
@@ -1223,8 +1289,15 @@ pub async fn paths_between(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
from.name,
to.name
));
+ // 每一跳是一条事实,各带各的号
+ let hops: Vec<Uuid> = paths
+ .iter()
+ .flat_map(|p| p.edges.iter().map(|e| e.fact_id))
+ .collect();
+ let evidence = Evidence::load(ctx, hops, m.as_of).await;
for (i, p) in paths.iter().enumerate() {
- lines.push(format!("{}. {}", i + 1, path_text(p)));
+ let text = path_text_marked(p, |fact| evidence.mark(sink, fact));
+ lines.push(format!("{}. {}", i + 1, text));
}
if paths.len() >= limits.max_paths {
lines.push(format!(
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index 50d4c439..d77f7f72 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -1893,6 +1893,63 @@ pub async fn document_extractions(
Ok(rows)
}
+/// 每条事实第一条仍然有效的证据块(#935)。对话把它登进这一轮的来源清单、在事实行上
+/// 印它的 `[n]`,读的人点开就是那句原话。
+///
+/// 有效 = 分块是现行版本、文档没删;给了 `as_of` 就按那一刻判,与读事实的那一刻一致
+/// (record_axis)。几条都有效时取最早说出它的那篇文档里的第一块。一条有效证据都没有
+/// 的事实不在结果里——宁可不给号,也不给一个在读的那一刻已是旧版或已删文档的号
+/// (给了 `as_of` 时引的就是那一刻还在的段落,哪怕它后来被替换或删了)
+pub async fn first_live_evidence(
+ pool: &PgPool,
+ kb_id: Uuid,
+ fact_ids: &[Uuid],
+ as_of: Option<chrono::DateTime<chrono::Utc>>,
+) -> AppResult<Vec<(Uuid, utopia_core::models::ChunkView)>> {
+ if fact_ids.is_empty() {
+ return Ok(Vec::new());
+ }
+ #[derive(sqlx::FromRow)]
+ struct Row {
+ fact_id: Uuid,
+ id: Uuid,
+ document_id: Uuid,
+ seq: i32,
+ text: String,
+ filename: String,
+ }
+ 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
+ FROM fact_evidence fe
+ JOIN chunks c ON c.id = fe.chunk_id
+ JOIN documents d ON d.id = c.document_id
+ WHERE fe.fact_id = ANY($1) AND d.kb_id = $2 AND {chunk_live} AND {document_live}
+ ORDER BY fe.fact_id, COALESCE(d.doc_time, d.created_at), d.id, c.seq, c.id",
+ chunk_live = crate::record_axis::chunk_live_at("c", as_of.map(|_| 3)),
+ document_live = crate::record_axis::document_live_at("d", as_of.map(|_| 3)),
+ ))
+ .bind(fact_ids)
+ .bind(kb_id)
+ .bind(as_of)
+ .fetch_all(pool)
+ .await?;
+ Ok(rows
+ .into_iter()
+ .map(|r| {
+ (
+ r.fact_id,
+ utopia_core::models::ChunkView {
+ id: r.id,
+ document_id: r.document_id,
+ seq: r.seq,
+ text: r.text,
+ filename: r.filename,
+ },
+ )
+ })
+ .collect())
+}
+
/// 证据回放路径:不过滤 superseded——它的职责就是能看旧版。
/// stale = 证据版本落后于文档当前版本(UI 标 "from v{n}")。
pub async fn fact_evidence(pool: &PgPool, fact_id: Uuid) -> AppResult<Vec<EvidenceView>> {
diff --git a/docs/design/chat-and-mcp.md b/docs/design/chat-and-mcp.md
index 1632d45c..5fcdfe46 100644
--- a/docs/design/chat-and-mcp.md
+++ b/docs/design/chat-and-mcp.md
@@ -27,7 +27,11 @@ the conversation's last message and no answer is being written there (#936).
`find_entities`, `entity_facts` (names marked as names, derived rows with their rule, `as_of` and
`at` respected), `changes`, `list_rules`, `rule_matches`, `remember`; MCP results carry
`structuredContent` with ledger UUIDs and each evidence row's origin [0014, 0021, 0041, 0019,
-0022, 0040]. The previous turn's tool calls are replayed so the model knows what it did, not only
+0022, 0040]. In chat, `entity_facts`, `neighbors`, `timeline` and `paths_between` end each fact
+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
+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/scripts/bench/temporal.mjs b/scripts/bench/temporal.mjs
index 4a7dc0a1..c4710e6e 100644
--- a/scripts/bench/temporal.mjs
+++ b/scripts/bench/temporal.mjs
@@ -337,11 +337,12 @@ async function main() {
if (only && !only.has(r.id)) continue;
let reply;
let steps;
+ let sources;
try {
// `{wave-N}` 填成那一波灌完的时间戳:"as of the second ingest" 是卷子内部的
// 说法,模型无从知道它是哪一刻,只会反问;给它戳,量的才是工具那条路
const ask = r.ask.replace(/\{(wave-\d+)\}/g, (_, w) => stamps[w] ?? w);
- ({ answer: reply, steps } = await askChat(kb, ask));
+ ({ answer: reply, steps, sources } = await askChat(kb, ask));
} catch (e) {
// 接口本身失败不算答错,单独记 error——否则一个 500 会被记成
// 「对话答不出来」,而它答都没答
@@ -357,6 +358,10 @@ async function main() {
// 工具轨迹:模型有没有带 `at` / `as_of`、带的是哪个时刻,从 step 的 detail
// 上一眼能看出来("5 facts at 2024-08-01, as recorded by 2026-09-05")
steps,
+ // 回答里的 [n] 哪些点得开(#935):来源列表里有这个号,界面上它就是一个能
+ // 打开原句的链接;没有的号是模型编的,界面上只是方括号
+ sources: sources.map(({ n, filename }) => ({ n, filename })),
+ cites: citations(reply, sources),
};
}
}
@@ -395,6 +400,13 @@ async function main() {
const gaps = answered.filter((r) => r.known_gap);
const pass = rows.filter((r) => r.chat.outcome === "pass").length;
const errors = results.filter((r) => r.chat?.outcome === "error").length;
+ // 引用不分对错、不分缺口:问的是回答能不能点开原句,每个拿到回复的题都算。
+ // 走过图谱的单独一栏——#935 要变的正是它们
+ const cited = (rows) => ({
+ answers: rows.length,
+ cited: rows.filter((r) => r.chat.cites.resolved.length).length,
+ dangling: rows.filter((r) => r.chat.cites.dangling.length).length,
+ });
return {
asked: rows.length,
pass,
@@ -404,6 +416,10 @@ async function main() {
asked: gaps.length,
pass: gaps.filter((r) => r.chat.outcome === "pass").length,
},
+ citations: {
+ all: cited(answered),
+ graph: cited(answered.filter((r) => r.chat.steps.some(readsGraph))),
+ },
};
})()
: null,
@@ -418,6 +434,11 @@ async function main() {
? ` 已知缺口 ${report.ledger.known_gaps.pass}/${report.ledger.known_gaps.asked} 通过`
: "") +
(report.chat ? ` 对话:${report.chat.pass}/${report.chat.asked}` : "") +
+ (report.chat
+ ? `\n引用:${report.chat.citations.all.cited}/${report.chat.citations.all.answers} 个回答点得开原句` +
+ `(走过图谱的 ${report.chat.citations.graph.cited}/${report.chat.citations.graph.answers}),` +
+ `${report.chat.citations.all.dangling} 个带了点不开的号`
+ : "") +
`\n`,
);
}
@@ -509,6 +530,8 @@ async function askChat(kb, question) {
let answer = "";
let error = null;
const steps = [];
+ // 每个 `sources` 帧都是到那一刻为止的整张列表,留最后一个
+ let sources = [];
for (const frame of text.split("\n\n")) {
let event = "message";
let data = "";
@@ -529,12 +552,36 @@ async function askChat(kb, question) {
} catch {
/* 同上 */
}
+ } else if (event === "sources" && data) {
+ try {
+ sources = JSON.parse(data);
+ } catch {
+ /* 同上 */
+ }
} else if (event === "error") {
error = data;
}
}
if (error && !answer) throw new Error(`chat error frame: ${error.slice(0, 200)}`);
- return { answer, steps };
+ return { answer, steps, sources };
+}
+
+/// 回答里写到的 [n],按来源列表分成点得开的与点不开的。认的写法与界面画链接的
+/// 那一条一致(`web/src/citations.ts` 的 `citeRe`):`[1][3]`、`[1, 3]`、`[1,3]`
+function citations(reply, sources) {
+ const known = new Set(sources.map((s) => s.n));
+ const cited = new Set();
+ for (const [, inner] of reply.matchAll(/\[(\d+(?:\s*[,,]\s*\d+)*)\]/g)) {
+ for (const n of inner.split(/[,,]/)) cited.add(Number(n));
+ }
+ const all = [...cited].sort((a, b) => a - b);
+ return { resolved: all.filter((n) => known.has(n)), dangling: all.filter((n) => !known.has(n)) };
+}
+
+/// 这一步读的是图谱:四个图谱工具的 step(`tools_graph.rs`)。轨迹里每步是
+/// "kind · label · detail"
+function readsGraph(step) {
+ return ["facts", "neighbors", "timeline", "path"].includes(step.split(" · ")[0]);
}
/// 对话判分:子串匹配,只做一件归一——千位分隔符。模型写 "28,000 CNY",题上写