World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
An agent can read a whole document after a search hit (#265)
chetanunadkat-lang11475a341997
diff --git a/crates/utopia-server/src/api/chat.rs b/crates/utopia-server/src/api/chat.rsindex f6ef8237..5c9546c4 100644--- a/crates/utopia-server/src/api/chat.rs+++ b/crates/utopia-server/src/api/chat.rs@@ -157,12 +157,13 @@ fn check_call(),));};- let required = tools+ let function = tools.as_array().into_iter().flatten().find(|t| t["function"]["name"] == name)- .and_then(|t| t["function"]["parameters"]["required"].as_array());+ .map(|t| &t["function"]);+ let required = function.and_then(|f| f["parameters"]["required"].as_array());for key in required.into_iter().flatten().filter_map(|k| k.as_str()) {// 空串与 null 都算没给:`{"query": ""}` 检索出来的东西与问题无关,// 而它同样会显示成一条正常的轨迹@@ -180,6 +181,24 @@ fn check_call(),));}+ // 判据同样取自工具表:schema 里写了 `format: uuid` 的参数,格式也在这一关挡。+ // 编出来的 id 到了工具里只能回「本库没有这篇文档」,模型会把它读成+ // 「库里真的没有」而放弃——那是又一个看起来没问题的错误答案+ let is_uuid =+ function.is_some_and(|f| f["parameters"]["properties"][key]["format"] == "uuid");+ if is_uuid+ && args[key]+ .as_str()+ .is_none_or(|s| s.trim().parse::<Uuid>().is_err())+ {+ return Err(refuse(+ &format!("invalid {key}"),+ format!(+ "{name} needs `{key}` to be a uuid returned by another tool, and it was \+ not, so the call was not run. Look the id up first, then call it again."+ ),+ ));+ }}Ok(args)}@@ -203,7 +222,10 @@ pub(super) fn base_tools() -> serde_json::Value {"function": {"name": "search_chunks","description": "Full-text + semantic search over the knowledge base documents. \- Returns numbered source excerpts you can cite as [n].",+ Returns numbered source excerpts you can cite as [n], each with the \+ document_id it came from. Excerpts are cut short and only the best-matching \+ sections come back, so when the answer may sit elsewhere in a hit, call \+ get_document with that document_id to read the whole document.","parameters": {"type": "object","properties": {@@ -213,17 +235,36 @@ pub(super) fn base_tools() -> serde_json::Value {}}},+ {+ "type": "function",+ "function": {+ "name": "get_document",+ "description": "Read the full text of ONE knowledge base document, all sections \+ in order, by the document_id shown in search_chunks results. Use it whenever \+ a search hit looks like the right document but the excerpt does not contain \+ the answer — action items, decisions and lists usually sit past the excerpt \+ or in a section that did not match the query.",+ "parameters": {+ "type": "object",+ "properties": {+ "document_id": {+ "type": "string",+ "format": "uuid",+ "description": "Document id (uuid) from a search_chunks result line."+ }+ },+ "required": ["document_id"]+ }+ }+ },{"type": "function","function": {"name": "search_docs",- "description": "Search Utopia's own user manual (the Charter): how the platform \- itself works — sources and ingestion, sync semantics (missing markers, \- tombstones, versions), the knowledge graph and review flow, roles and \- permissions, settings. Use ONLY for questions about using or understanding \- Utopia itself, or to explain platform concepts that appear in other tool \- results (e.g. why a document is marked missing). NEVER use it to answer \- questions about the content stored in the knowledge base.",+ "description": "Search the Utopia product manual (the \"Utopia Charter\") — how \+ the platform itself works (ingestion and sync, missing markers and versions, \+ the graph and review flow, roles, settings) — and never the user's own \+ documents, which live in search_chunks.","parameters": {"type": "object","properties": {@@ -308,9 +349,12 @@ pub(super) fn base_tools() -> serde_json::Value {}const SYSTEM_PROMPT: &str = "You are the assistant of Utopia, a temporal knowledge platform. \- You have tools: search_chunks (document search), find_entities, entity_facts and \- changes (a bi-temporal knowledge graph), and search_docs (Utopia's own manual, the \- Charter).\n\+ You have tools: search_chunks (document search) and get_document (the full text of one \+ document found by search), find_entities, entity_facts and changes (a bi-temporal \+ knowledge graph), and search_docs (Utopia's own manual, the Charter).\n\+ search_chunks returns short excerpts of the best-matching sections only. When a hit is \+ clearly the right document but the excerpt does not carry the answer, read the whole \+ document with get_document before saying the knowledge base does not have it.\n\The graph has TWO independent time axes, and each graph tool reads exactly one:\n\- World time — when something was true. Read with entity_facts (`at` = as of that date).\n\- Record time — when we came to believe it, and when we revised it. Read with changes.\n\@@ -1018,6 +1062,37 @@ mod tests {assert_eq!(args["at"], "2026-03-15", "可选参数不能在这一关被吃掉");}+ /// 全文只能按 id 读,而 id 是模型从检索结果里抄来的——抄错、抄漏+ /// 都得在这里停住+ #[test]+ fn get_document_without_an_id_does_not_run() {+ let tools = tools_schema(false, &[]);+ let err = check_call(&tools, "get_document", "{}").expect_err("缺 document_id 必须拒绝");+ assert_eq!(err.1["detail"], "missing document_id");+ }++ /// 不是 uuid 的 id 到了工具里只能回「本库没有这篇文档」——模型会把它读成+ /// 「库里真的没有」而收手,于是一次抄错的 id 变成一个否定的答案+ #[test]+ fn a_document_id_that_is_not_a_uuid_does_not_run() {+ let tools = tools_schema(false, &[]);+ for raw in [+ "{\"document_id\": \"Notes- 'Scrum' 3 Sept 2026.txt\"}",+ "{\"document_id\": \"1f8ac10b-58cc-4372\"}",+ ] {+ let Err(err) = check_call(&tools, "get_document", raw) else {+ panic!("{raw} 应当被拒");+ };+ assert_eq!(err.1["detail"], "invalid document_id", "{raw}");+ }+ check_call(+ &tools,+ "get_document",+ "{\"document_id\": \"1f8ac10b-58cc-4372-a567-0e02b2c3d479\"}",+ )+ .expect("真的 uuid 就该放行");+ }+/// `changes` 早就在自己那一支里拒绝缺失的 `since`——**它是唯一做对的一个**。/// 这条钉住两件事:新的统一关卡与它一致,而它自己那道对日期格式的检查/// (`2026-13-45` 这种)仍然要留着,因为 check_call 只看有没有、不看对不对diff --git a/crates/utopia-server/src/api/mcp.rs b/crates/utopia-server/src/api/mcp.rsindex 88bfafcc..1b85a1f4 100644--- a/crates/utopia-server/src/api/mcp.rs+++ b/crates/utopia-server/src/api/mcp.rs@@ -32,12 +32,18 @@ use crate::state::AppState;/// 规范要求服务端回自己支持的版本,由客户端决定接不接受const PROTOCOL_VERSION: &str = "2025-06-18";-/// 这一版放出去的工具。**只读四个**(0014):+/// 这一版放出去的工具。**只读五个**(0014):////// `query_data` 对生产库跑 SQL,`remember` 往账本里写,两者各自还有没答完的/// 问题——外部 agent 写进来的事实挂什么证据、跑 SQL 的审计怎么记。先把身份/// 这条路走通。-const EXPOSED: [&str; 4] = ["search_chunks", "search_docs", "find_entities", "changes"];+const EXPOSED: [&str; 5] = [+ "search_chunks",+ "get_document",+ "search_docs",+ "find_entities",+ "changes",+];/// `entity_facts` 也在内,单列是因为上面那个数组要定长const EXPOSED_EXTRA: &str = "entity_facts";diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rsindex 98a52a2c..1c4a414b 100644--- a/crates/utopia-server/src/api/tools.rs+++ b/crates/utopia-server/src/api/tools.rs@@ -17,6 +17,10 @@ use crate::state::AppState;const SEARCH_TOP_K: usize = 6;const TOOL_CHUNK_CHARS: usize = 800;+/// `get_document` 一次最多回多少字。检索那边的 800 字是为了让六条命中都装得下,+/// 这边只有一篇文档,而问的人已经知道要读哪一篇——截在答案前面才是这个工具+/// 要消灭的毛病+const DOCUMENT_CHARS: usize = 24_000;/// 一次 changes 最多回多少条。刚灌完的库里 asserted 是成百上千条,全发出去/// 只会把上下文填满而不增加信息——有信息量的是 corrected/rejected,那类事件/// 本来就稀少。截断时 detail 写 "40+",模型据此知道该收窄窗口@@ -64,6 +68,7 @@ pub async fn dispatch() -> ToolResult {match name {"search_chunks" => search_chunks(ctx, sink, args).await,+ "get_document" => get_document(ctx, sink, args).await,"search_docs" => search_docs(ctx, sink, args).await,"find_entities" => find_entities(ctx, sink, args).await,"entity_facts" => entity_facts(ctx, args).await,@@ -104,10 +109,12 @@ pub async fn search_chunks(let mut lines = Vec::new();for c in &chunks {let n = cite(sink, c.id.to_string(), |n| source_json(n, c));+ // 行里带 document_id:命中被切在 800 字上时,模型得有办法把整篇要回去lines.push(format!(- "[{n}] \"{}\" section {}:\n{}",+ "[{n}] \"{}\" section {} (document_id: {}):\n{}",c.filename,c.seq + 1,+ c.document_id,truncate(&c.text, TOOL_CHUNK_CHARS)));}@@ -122,6 +129,89 @@ pub async fn search_chunks()}+/// 一篇文档的全文。**search_chunks 够不到的东西全在这里**:它只回前六条命中、+/// 每条切在 800 字上,答案落在第 801 字或落在没排上的那一块时,检索本身没错,+/// 错在没有第二步。+pub async fn get_document(+ ctx: &ToolCtx<'_>,+ sink: &mut ToolSink,+ args: &serde_json::Value,+) -> ToolResult {+ let refuse = |detail: &str| {+ (+ "No document with that id in this knowledge base.".to_string(),+ json!({ "kind": "document", "label": "?", "detail": detail }),+ )+ };+ let Some(id) = args["document_id"]+ .as_str()+ .and_then(|s| s.trim().parse::<Uuid>().ok())+ else {+ return refuse("invalid id");+ };+ // 本库之外的 id 一律当作不存在——分不出「没有」和「不给你看」才是对的+ let Ok(Some(doc)) = utopia_store::documents::find_in_kb(&ctx.state.pool, ctx.kb_id, id).await+ else {+ return refuse("not found");+ };+ let chunks = utopia_store::documents::chunks_in_document(&ctx.state.pool, ctx.kb_id, id)+ .await+ .unwrap_or_default();++ let mut lines = Vec::new();+ let mut used = 0usize;+ let mut omitted = 0usize;+ for c in &chunks {+ let body = c.text.trim();+ let len = body.chars().count();+ let room = DOCUMENT_CHARS.saturating_sub(used);+ // 装不下的分块整块不发,也不引——发一个引证编号出去而正文不在,+ // 界面上落成一条指不到东西的引证+ if room == 0 {+ omitted += len;+ continue;+ }+ let body: String = if len > room {+ omitted += len - room;+ body.chars().take(room).collect()+ } else {+ body.to_string()+ };+ used += body.chars().count();+ let n = cite(sink, c.id.to_string(), |n| source_json(n, c));+ lines.push(format!(+ "[{n}] \"{}\" section {}:\n{body}",+ c.filename,+ c.seq + 1+ ));+ }+ if omitted > 0 {+ lines.push(format!("… truncated, {omitted} chars omitted"));+ }++ let when = doc+ .doc_time+ .map(|t| t.format("%Y-%m-%d").to_string())+ .unwrap_or_else(|| "no date".to_string());+ let header = format!(+ "\"{}\" ({when}) — {} section(s):",+ doc.filename,+ chunks.len()+ );+ let text = if lines.is_empty() {+ format!("{header}\n(no text)")+ } else {+ format!("{header}\n\n{}", lines.join("\n\n"))+ };+ (+ text,+ json!({+ "kind": "document", "label": doc.filename,+ "detail": format!("{} sections", chunks.len()),+ }),+ )+}+pub async fn search_docs(ctx: &ToolCtx<'_>,sink: &mut ToolSink,diff --git a/crates/utopia-store/src/documents.rs b/crates/utopia-store/src/documents.rsindex d55dcfbe..3b9f589f 100644--- a/crates/utopia-store/src/documents.rs+++ b/crates/utopia-store/src/documents.rs@@ -167,6 +167,18 @@ pub async fn get(pool: &PgPool, id: Uuid) -> AppResult<Document> {.ok_or(AppError::NotFound)}+/// 按 kb 收窄的取文档。**id 由模型给出时只能走这一支**:`get` 只按 id 查,+/// 一个别的库的 id 照样查得到。+pub async fn find_in_kb(pool: &PgPool, kb_id: Uuid, id: Uuid) -> AppResult<Option<Document>> {+ Ok(+ sqlx::query_as("SELECT * FROM documents WHERE id = $1 AND kb_id = $2")+ .bind(id)+ .bind(kb_id)+ .fetch_optional(pool)+ .await?,+ )+}+/// 按来源内逻辑身份查文档(同步三路判定用)。pub async fn find_by_external_key(pool: &PgPool,@@ -661,6 +673,24 @@ pub async fn chunks_by_ids(pool: &PgPool, kb_id: Uuid, ids: &[Uuid]) -> AppResulOk(ids.iter().filter_map(|id| by_id.remove(id)).collect())}+/// 一篇文档的现行分块(带文档名),按 seq 排。kb_id 进 WHERE 而不是查回来再比。+pub async fn chunks_in_document(+ pool: &PgPool,+ kb_id: Uuid,+ document_id: Uuid,+) -> AppResult<Vec<ChunkView>> {+ Ok(sqlx::query_as(+ "SELECT c.id, c.document_id, c.seq, c.text, d.filename+ FROM chunks c JOIN documents d ON d.id = c.document_id+ WHERE c.kb_id = $1 AND c.document_id = $2 AND c.superseded_at IS NULL+ ORDER BY c.seq",+ )+ .bind(kb_id)+ .bind(document_id)+ .fetch_all(pool)+ .await?)+}+/// 批量排队全量重抽:ready 文档清增量标记 → graph_status=queued → 建抽取任务,/// 返回待抽文档 id。`source_id` 给定则限定该来源,否则整库。///