Skip to content

World's first open-source enterprise world model.

Tell the model when changes, find_entities or paths_between stopped at their limits (#941)

Maya Kid376cff2fc41d
diff --git a/crates/utopia-server/src/api/mcp_tests.rs b/crates/utopia-server/src/api/mcp_tests.rs
index 57fa1cff..40d9578f 100644
--- a/crates/utopia-server/src/api/mcp_tests.rs
+++ b/crates/utopia-server/src/api/mcp_tests.rs
@@ -2740,3 +2740,158 @@ async fn rdf_export_preserves_unbound_literal_objects() -> anyhow::Result<()> {
let cleanup = f.clean().await;
result.and(cleanup)
}
+
+/// A list cut at its limit says so in the text the model reads. `changes` lists the newest
+/// 40 events, `find_entities` reads the first 8 names, `paths_between` keeps 10 paths; a
+/// model shown a full list takes it for all there is. `structuredContent` keeps its own
+/// `limit_reached`. Each full case is paired with one that fits and must stay quiet.
+#[tokio::test]
+async fn a_list_cut_at_its_limit_says_so() -> anyhow::Result<()> {
+ let Some(f) = Fixture::new().await? else {
+ return Ok(());
+ };
+ async fn entity(f: &Fixture, ty: Uuid, name: &str) -> anyhow::Result<Uuid> {
+ let id = Uuid::now_v7();
+ sqlx::query("INSERT INTO entities(id,kb_id,type_id,canonical_name) VALUES ($1,$2,$3,$4)")
+ .bind(id)
+ .bind(f.kb)
+ .bind(ty)
+ .bind(name)
+ .execute(&f.state.pool)
+ .await?;
+ Ok(id)
+ }
+ async fn link(
+ f: &Fixture,
+ rel: Uuid,
+ from: Uuid,
+ to: Uuid,
+ recorded: &str,
+ ) -> anyhow::Result<()> {
+ let recorded: chrono::DateTime<chrono::Utc> = recorded.parse()?;
+ sqlx::query(
+ "INSERT INTO facts(id,kb_id,subject_id,predicate_id,object_id,recorded_at)
+ VALUES ($1,$2,$3,$4,$5,$6)",
+ )
+ .bind(Uuid::now_v7())
+ .bind(f.kb)
+ .bind(from)
+ .bind(rel)
+ .bind(to)
+ .bind(recorded)
+ .execute(&f.state.pool)
+ .await?;
+ Ok(())
+ }
+ fn text(result: &Value) -> &str {
+ result["content"][0]["text"].as_str().unwrap_or_default()
+ }
+ async fn check(f: &Fixture) -> anyhow::Result<()> {
+ let (ty, rel) = (Uuid::now_v7(), Uuid::now_v7());
+ sqlx::query("INSERT INTO entity_types(id,kb_id,key,label) VALUES ($1,$2,'probe','Probe')")
+ .bind(ty)
+ .bind(f.kb)
+ .execute(&f.state.pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO relation_types(id,kb_id,key,label,kind)
+ VALUES ($1,$2,'links','links','relation')",
+ )
+ .bind(rel)
+ .bind(f.kb)
+ .execute(&f.state.pool)
+ .await?;
+
+ // changes: 41 events in January, 3 in March
+ let (a, b) = (
+ entity(f, ty, "Ledger A").await?,
+ entity(f, ty, "Ledger B").await?,
+ );
+ for i in 0..41 {
+ link(
+ f,
+ rel,
+ a,
+ b,
+ &format!("2025-01-{:02}T08:00:00Z", 1 + i % 28),
+ )
+ .await?;
+ }
+ for day in 1..=3 {
+ link(f, rel, a, b, &format!("2025-03-{day:02}T08:00:00Z")).await?;
+ }
+ let full = f
+ .call("changes", json!({"since":"2025-01","until":"2025-01"}))
+ .await?;
+ anyhow::ensure!(
+ text(&full).contains("Only the 40 most recent changes in this window are listed"),
+ "a full window must say it was cut: {full}"
+ );
+ anyhow::ensure!(full["structuredContent"]["limit_reached"] == true, "{full}");
+ anyhow::ensure!(
+ full["structuredContent"]["changes"]
+ .as_array()
+ .map(Vec::len)
+ == Some(40),
+ "{full}"
+ );
+ let few = f
+ .call("changes", json!({"since":"2025-03","until":"2025-03"}))
+ .await?;
+ anyhow::ensure!(!text(&few).contains("most recent changes"), "{few}");
+ anyhow::ensure!(few["structuredContent"]["limit_reached"] == false, "{few}");
+
+ // find_entities: ten widgets, three gadgets
+ for i in 1..=10 {
+ entity(f, ty, &format!("Widget {i}")).await?;
+ }
+ for i in 1..=3 {
+ entity(f, ty, &format!("Gadget {i}")).await?;
+ }
+ let widgets = f.call("find_entities", json!({"name":"Widget"})).await?;
+ anyhow::ensure!(
+ text(&widgets).contains(
+ "10 entities have a name containing \"Widget\"; only the first 8 were read"
+ ),
+ "a search that read only the first names must say so: {widgets}"
+ );
+ let gadgets = f.call("find_entities", json!({"name":"Gadget"})).await?;
+ anyhow::ensure!(!text(&gadgets).contains("were read"), "{gadgets}");
+
+ // paths_between: eleven two-hop paths, then two
+ let (start, end) = (
+ entity(f, ty, "Path Start").await?,
+ entity(f, ty, "Path End").await?,
+ );
+ for i in 1..=11 {
+ let via = entity(f, ty, &format!("Via {i}")).await?;
+ link(f, rel, start, via, "2025-06-01T08:00:00Z").await?;
+ link(f, rel, via, end, "2025-06-01T08:00:00Z").await?;
+ }
+ let (near, far) = (
+ entity(f, ty, "Short Start").await?,
+ entity(f, ty, "Short End").await?,
+ );
+ for i in 1..=2 {
+ let hop = entity(f, ty, &format!("Hop {i}")).await?;
+ link(f, rel, near, hop, "2025-06-01T08:00:00Z").await?;
+ link(f, rel, hop, far, "2025-06-01T08:00:00Z").await?;
+ }
+ let many = f
+ .call("paths_between", json!({"from":start,"to":end}))
+ .await?;
+ anyhow::ensure!(
+ text(&many).contains("Only the first 10 paths, shortest first, are listed"),
+ "a capped path list must say so: {many}"
+ );
+ let two = f
+ .call("paths_between", json!({"from":near,"to":far}))
+ .await?;
+ anyhow::ensure!(text(&two).starts_with("2 paths between"), "{two}");
+ anyhow::ensure!(!text(&two).contains("are listed"), "{two}");
+ Ok(())
+ }
+ let result = check(&f).await;
+ let cleanup = f.clean().await;
+ result.and(cleanup)
+}
diff --git a/crates/utopia-server/src/api/tools.rs b/crates/utopia-server/src/api/tools.rs
index 017a264b..48f3ed20 100644
--- a/crates/utopia-server/src/api/tools.rs
+++ b/crates/utopia-server/src/api/tools.rs
@@ -23,7 +23,8 @@ const TOOL_CHUNK_CHARS: usize = 800;
const DOCUMENT_CHARS: usize = 24_000;
/// 一次 changes 最多回多少条。刚灌完的库里 asserted 是成百上千条,全发出去
/// 只会把上下文填满而不增加信息——有信息量的是 corrected/rejected,那类事件
-/// 本来就稀少。截断时 detail 写 "40+",模型据此知道该收窄窗口
+/// 本来就稀少。截断时正文末尾写明,模型据此收窄窗口:界面上那一步的 "40+"
+/// 只给人看,模型读不到
const CHANGES_LIMIT: i64 = 40;
/// 一次工具调用看得见的世界。**只读**——工具改不了它。
@@ -620,7 +621,17 @@ pub async fn changes(ctx: &ToolCtx<'_>, args: &serde_json::Value) -> ToolResult
let text = if rows.is_empty() {
format!("No recorded changes in {window}.")
} else {
- rows.iter().map(change_line).collect::<Vec<_>>().join("\n")
+ let mut lines: Vec<String> = rows.iter().map(change_line).collect();
+ // 取的是**最近**的四十条,更早的被截掉。不说的话模型会把这四十条当成窗口的
+ // 全部,而要找的那次更正可能正好在更早的地方
+ if rows.len() as i64 == CHANGES_LIMIT {
+ lines.push(format!(
+ "(Only the {CHANGES_LIMIT} most recent changes in this window are listed; it may \
+ hold more. Narrow since/until, or pass kinds such as [\"corrected\", \
+ \"rejected\"], to see the rest.)"
+ ));
+ }
+ lines.join("\n")
};
let detail = if rows.len() as i64 == CHANGES_LIMIT {
format!("{CHANGES_LIMIT}+ changes")
diff --git a/crates/utopia-server/src/api/tools_graph.rs b/crates/utopia-server/src/api/tools_graph.rs
index 13f82e7c..3de81450 100644
--- a/crates/utopia-server/src/api/tools_graph.rs
+++ b/crates/utopia-server/src/api/tools_graph.rs
@@ -122,7 +122,7 @@ async fn resolve(
note: None,
});
}
- let hits = lookup(ctx, raw).await.map_err(|e| {
+ let (hits, _) = lookup(ctx, raw).await.map_err(|e| {
tracing::warn!(error = %e, "Entity lookup failed");
ResolveError::ReadFailed
})?;
@@ -203,8 +203,8 @@ fn contains_ci(haystack: Option<&str>, needle: &str) -> bool {
pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value) -> ToolResult {
let name = args["name"].as_str().unwrap_or("").to_string();
- let hits = match lookup(ctx, &name).await {
- Ok(hits) => hits,
+ let (hits, total) = match lookup(ctx, &name).await {
+ Ok(found) => found,
Err(e) => {
tracing::warn!(error = %e, "Entity lookup failed");
return ToolResult::new(
@@ -214,9 +214,10 @@ pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
.error();
}
};
+ let read = hits.len();
let (ranked, by_question) = rank_by_question(ctx, rank(hits, &name), &name).await;
let clear = by_question || dominant(&ranked, &name);
- let text = if ranked.is_empty() {
+ let mut text = if ranked.is_empty() {
"No matching entities.".to_string()
} else if clear {
let mut lines = vec![format!("Best match: {}", node_line(&ranked[0]))];
@@ -232,6 +233,14 @@ pub async fn find_entities(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
lines.extend(ranked.iter().map(node_line));
lines.join("\n")
};
+ // 截断要说出来(与 `rule_matches` 同一条):只读了前几个,模型会把它们当成这个
+ // 名字的全部,然后告诉人「库里只有这几个」
+ if let Some(total) = total.filter(|t| *t > read as i64) {
+ text.push_str(&format!(
+ "\n({total} entities have a name containing \"{name}\"; only the first {read} were \
+ read. A longer or more exact name narrows the search.)"
+ ));
+ }
// 同名歧义时候选只是搜索结果,不是认下的实体。从前这里全记,下一轮就收到一串
// 同名的 id 和一句「直接用这些」,没选的那个还常常排在前面。选中的那个在它被
// 读的时候记(entity_facts / neighbors / timeline);上一轮的候选另有工具往返
@@ -363,18 +372,24 @@ pub(super) fn predicates_of(facts: &[EntityFact]) -> String {
/// 子串找不到时按词找:每个词各去库里捞一把,名字里含的词数达到「全部减一、至少两个」
/// 的候选算命中("OpenAI board members" → "OpenAI's board of directors")。
/// 模型给的名字常带一个库里没有的词(members、公司、这个),全词命中会把它们全漏掉
-async fn lookup(ctx: &ToolCtx<'_>, raw: &str) -> utopia_core::AppResult<Vec<GraphNode>> {
+///
+/// 回的是查到的实体,以及这个名字一共命中几个。只读前八个,总数用来告诉模型这不是
+/// 全部;按词拼凑的那一路没有总数
+async fn lookup(
+ ctx: &ToolCtx<'_>,
+ raw: &str,
+) -> utopia_core::AppResult<(Vec<GraphNode>, Option<i64>)> {
// 工具调用来自聊天 / MCP:当下的问题,不在回放里。传 None 让 `degree` 按
// 现在算——和现状一致,回放图上的搜索框另走 `/kbs/{id}/entities` 自己挂
// 时刻
- let (hits, _) =
+ let (hits, total) =
utopia_store::graph::search_entities(&ctx.state.pool, ctx.kb_id, raw, 8, 0, None).await?;
if !hits.is_empty() {
- return Ok(hits);
+ return Ok((hits, Some(total)));
}
let words: Vec<&str> = raw.split_whitespace().filter(|w| w.len() >= 2).collect();
if words.len() < 2 {
- return Ok(hits);
+ return Ok((hits, Some(total)));
}
let mut pool: Vec<GraphNode> = Vec::new();
for w in &words {
@@ -394,7 +409,7 @@ async fn lookup(ctx: &ToolCtx<'_>, raw: &str) -> utopia_core::AppResult<Vec<Grap
.filter(|(s, _)| *s >= need)
.collect();
scored.sort_by(|a, b| b.0.cmp(&a.0).then(b.1.degree.cmp(&a.1.degree)));
- Ok(scored.into_iter().map(|(_, n)| n).take(8).collect())
+ Ok((scored.into_iter().map(|(_, n)| n).take(8).collect(), None))
}
/// 名字里含了几个词(大小写不敏感)
@@ -1132,6 +1147,12 @@ pub async fn paths_between(ctx: &ToolCtx<'_>, sink: &mut ToolSink, args: &Value)
for (i, p) in paths.iter().enumerate() {
lines.push(format!("{}. {}", i + 1, path_text(p)));
}
+ if paths.len() >= limits.max_paths {
+ lines.push(format!(
+ "(Only the first {} paths, shortest first, are listed; there may be more.)",
+ limits.max_paths
+ ));
+ }
let detail = format!(
"{} path{}, shortest {shortest} hop{}",
paths.len(),