Skip to content

World's first open-source enterprise world 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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]) -> AppResul
Ok(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` 给定则限定该来源,否则整库。
///