World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 七个工具的**执行**,与谁在调用它们无关。
//!
//! 从前这些是 `chat.rs` 里一个 `match` 的七条分支,每条 20–70 行,闭包捕获着
//! 流式循环的局部变量。那样写在只有对话一个调用方时没问题——**而 MCP 是第二个**。
//! 抽出来之后两边共用同一份实现,不会出现「对话里的 entity_facts 和 MCP 里的
//! 不是同一个东西」。
//!
//! 工具定义(给模型看的 JSON schema)仍在 `chat.rs`:那是提示词的一部分,
//! 随对话策略走;这里只管拿到参数之后干什么。
use serde_json::json;
use utopia_core::models::{ChunkView, DataSourceView, EntityFact, GraphChange};
use uuid::Uuid;
use crate::retrieval;
use crate::state::AppState;
const SEARCH_TOP_K: usize = 6;
const TOOL_CHUNK_CHARS: usize = 800;
/// `get_document` 每页的正文预算;超出的部分用字符 offset 续读,不把上下文塞满。
const DOCUMENT_CHARS: usize = 24_000;
/// 一次 changes 最多回多少条。刚灌完的库里 asserted 是成百上千条,全发出去
/// 只会把上下文填满而不增加信息——有信息量的是 corrected/rejected,那类事件
/// 本来就稀少。截断时正文末尾写明,模型据此收窄窗口:界面上那一步的 "40+"
/// 只给人看,模型读不到
const CHANGES_LIMIT: i64 = 40;
/// 一次工具调用看得见的世界。**只读**——工具改不了它。
pub struct ToolCtx<'a> {
pub state: &'a AppState,
pub kb_id: Uuid,
pub workspace_id: Uuid,
/// 本库挂载的数据源。**`query_data` 的安全边界就是这个列表**:
/// 凭据不出服务端,模型只能按名字点单
pub mounted_sources: &'a [DataSourceView],
/// editor 及以上才有 `remember`
pub can_write: bool,
/// 在说话的人。`remember` 把它记成「谁说的」,一路跟到待确认队列(0015)。
/// 对话里恒有值;MCP 也有——令牌以人的身份行事(0014)
pub actor: Option<Uuid>,
/// 经 MCP 时,是哪一枚令牌在说话。**人之外还要记它**:一个人可以同时挂
/// 三个 agent,审核卡上只写人名分不出是哪一个记的(0026)。对话里为 None
pub via_token: Option<Uuid>,
/// 用户这一轮的原话。图谱工具拿它消歧:同名候选按「谁的上下文画像离这个问题近」排。
/// MCP 没有它(agent 的意图不在请求里),那边按事实数排
pub question: Option<&'a str>,
}
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>> {
let settings = utopia_store::settings::get(&self.state.pool, self.workspace_id)
.await
.ok()
.flatten()?;
let client = crate::llm_util::embed_client(&settings)?;
match client.embed(&[text.to_string()]).await {
Ok(mut v) if !v.is_empty() => Some(v.remove(0)),
Ok(_) => None,
Err(e) => {
tracing::warn!(error = %e, "嵌入失败,图谱工具按子串匹配");
None
}
}
}
/// [`Self::embed`],同一轮里同样的文字只嵌一次(见 [`ToolSink::embeddings`])
pub async fn embed_once(&self, sink: &mut ToolSink, text: &str) -> Option<Vec<f32>> {
if let Some(vec) = sink.embeddings.get(text) {
return Some(vec.clone());
}
let vec = self.embed(text).await?;
sink.embeddings.insert(text.to_string(), vec.clone());
Some(vec)
}
}
/// 工具执行过程中往外攒的东西。
///
/// **引用编号是有状态的**:`[3]` 里的 3 取决于这一轮之前已经引过几个,
/// 所以不能让每个工具各算各的再合并——那样同一个 chunk 会拿到两个号。
#[derive(Default)]
pub struct ToolSink {
/// 去重键(chunk uuid,或 `charter:{slug}#{anchor}`),下标 +1 就是引用号
pub source_ids: Vec<String>,
/// 发给前端的引用清单,与 `source_ids` 同序
pub sources: Vec<serde_json::Value>,
/// 这一轮认下的实体,落进会话供下一轮回放
pub resolved: Vec<serde_json::Value>,
/// 这一轮嵌过的文字与它的向量,不落库。同名实体每按名字查一次,都拿同一句问题去比
/// 画像;谓词对不上时,同一个词也会再嵌。一轮之内文字与模型都不变,嵌一次就够:
/// 对话一轮一个 sink,MCP 一次调用一个。只记成功的,失败了下次照样再试。
/// 挑口径(`mapping_index::relevant`)与检索分块(`search_chunks`)也从这里拿问题的
/// 向量、往这里记(#971 的后续)
pub embeddings: crate::llm_util::EmbedCache,
}
/// 界面上的一步(#942)。
///
/// `kind` 与 `label`(数据:查询、实体名、来源名)照旧;`detail` 是给存量消息和不做
/// 本地化的读者的英文。界面按结构化字段用读者的语言说(0004):`status`、`count` /
/// `total`、时间点,以及个别步骤自己的几样。**成功的一步也写 `status: ok`**——有
/// status 的按字段说,没有的(这之前存下的消息)退回 detail
pub(crate) struct Step(serde_json::Map<String, serde_json::Value>);
impl Step {
pub(crate) fn new(
kind: &str,
label: impl Into<serde_json::Value>,
detail: impl Into<String>,
) -> Self {
let mut step = serde_json::Map::new();
step.insert("kind".into(), json!(kind));
step.insert("label".into(), label.into());
step.insert("detail".into(), json!(detail.into()));
step.insert("status".into(), json!("ok"));
Self(step)
}
/// `ok | failed | not_found | invalid`
pub(crate) fn status(self, status: &'static str) -> Self {
self.field("status", status)
}
pub(crate) fn count(self, n: usize) -> Self {
self.field("count", n)
}
/// 列出来的少于有的:`count` of `total`
pub(crate) fn total(self, n: usize) -> Self {
self.field("total", n)
}
/// 参数不对,这次调用什么也没做。`param` 是哪一个——参数名是数据,界面照写
pub(crate) fn invalid(self, param: &str) -> Self {
self.status("invalid").field("param", param)
}
/// 参数没给,或给的是空的
pub(crate) fn missing(self, param: &str) -> Self {
self.invalid(param).field("missing", true)
}
/// 截在上限、总数不知道(「40+」)
pub(crate) fn more(self, more: bool) -> Self {
if more {
self.field("more", true)
} else {
self
}
}
/// 世界轴的时刻写作 `valid_at`,记录轴写 `before` 或 `as_of`。给了 before 就只写
/// before:那是人问的那一刻,as_of 是从它减了一微秒算出来的。
///
/// **世界轴那个不能叫 `at`**:对话落库的每一步都有 `at`——这一步发生时正文已有多长
/// (UTF-16 码元),回放靠它把轨迹穿回正文;写进来会被它覆盖
pub(crate) fn moments(
mut self,
at: Option<chrono::DateTime<chrono::Utc>>,
as_of: Option<chrono::DateTime<chrono::Utc>>,
before: Option<chrono::DateTime<chrono::Utc>>,
) -> Self {
use crate::time_text::instant;
if let Some(t) = at {
self = self.field("valid_at", instant(t));
}
match (before, as_of) {
(Some(b), _) => self.field("before", instant(b)),
(None, Some(r)) => self.field("as_of", instant(r)),
(None, None) => self,
}
}
pub(crate) fn field(mut self, key: &str, value: impl serde::Serialize) -> Self {
self.0.insert(
key.into(),
serde_json::to_value(value).unwrap_or(serde_json::Value::Null),
);
self
}
pub(crate) fn json(self) -> serde_json::Value {
serde_json::Value::Object(self.0)
}
}
/// 一次调用的文本、界面步骤与可选机器读取结果;不放进跨调用累计的 ToolSink。
pub struct ToolResult {
pub text: String,
pub step: serde_json::Value,
pub structured_content: Option<serde_json::Value>,
pub is_error: bool,
}
impl ToolResult {
pub fn new(text: String, step: serde_json::Value) -> Self {
Self {
text,
step,
structured_content: None,
is_error: false,
}
}
pub fn structured(mut self, content: serde_json::Value) -> Self {
self.structured_content = Some(content);
self
}
pub fn error(mut self) -> Self {
self.is_error = true;
self
}
}
/// 按名字派发。**未知工具不是错误**——模型偶尔会编一个名字出来,
/// 告诉它没有这个工具,它下一轮就换一个,比中断整场对话好。
pub async fn dispatch(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
name: &str,
args: &serde_json::Value,
) -> 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" => super::tools_graph::find_entities(ctx, sink, args).await,
"entity_facts" => super::tools_graph::entity_facts(ctx, sink, args).await,
"neighbors" => super::tools_graph::neighbors(ctx, sink, args).await,
"timeline" => super::tools_graph::timeline(ctx, sink, args).await,
"paths_between" => super::tools_graph::paths_between(ctx, sink, args).await,
"changes" => changes(ctx, args).await,
// 业务规则只读(0021):判据要看得见,但**写规则不开给模型**——
// 「推理的判据由人写」是 0002 与 0021 共同的那条线,而一个工具调用
// 分不出「人口述、agent 代打」与「模型自己编了一条」
"list_rules" => list_rules(ctx).await,
"rule_matches" => rule_matches(ctx, args).await,
"query_data" if !ctx.mounted_sources.is_empty() => query_data(ctx, args).await,
"remember" if ctx.can_write => remember(ctx, args).await,
other => ToolResult::new(
format!("Unknown tool: {other}"),
Step::new("tool", other, "unknown")
.status("not_found")
.json(),
),
}
}
/// 已经引过的给回原号,没引过的落一个新号。**同一个 chunk 在一轮对话里
/// 只能有一个号**,否则模型引 `[2]` 而界面上有两个 `[2]`。
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 => {
sink.source_ids.push(key);
sink.sources.push(make(sink.source_ids.len()));
sink.source_ids.len()
}
}
}
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,
args: &serde_json::Value,
) -> ToolResult {
// 必填参数由 `chat::check_call` 在派发之前挡下,所以这里不再回落到
// 用户那句原话——回落产出的是一个看起来没问题的错误答案
let q = args["query"].as_str().unwrap_or_default().to_string();
// 记录轴(0019 / #347):只搜那一刻库里有的东西。全文那一路仍是"现在",
// 命中不会错但会缺——retrieval.rs 的头上写了
let as_of = args["as_of"].as_str().and_then(parse_when);
let chunks = match retrieval::hybrid(
ctx.state,
ctx.kb_id,
ctx.workspace_id,
&q,
SEARCH_TOP_K,
as_of,
Some(&mut sink.embeddings),
)
.await
{
Ok(chunks) => chunks,
Err(e) => {
tracing::warn!(error = %e, "MCP chunk search failed");
return ToolResult::new(
"Could not search the documents.".into(),
Step::new("search", q, "failed").status("failed").json(),
)
.error();
}
};
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 {} (document_id: {}):\n{}",
c.filename,
c.seq + 1,
c.document_id,
truncate(&c.text, TOOL_CHUNK_CHARS)
));
}
let text = if lines.is_empty() {
"No results.".to_string()
} else {
lines.join("\n\n")
};
ToolResult::new(
text,
Step::new("search", q.as_str(), format!("{} sources", chunks.len()))
.count(chunks.len())
.json(),
)
.structured(json!({
"kb_id": ctx.kb_id, "as_of": as_of,
"limit": SEARCH_TOP_K, "limit_reached": chunks.len() == SEARCH_TOP_K,
"chunks": chunks.iter().map(|c| json!({
"chunk_id": c.id, "document_id": c.document_id,
"seq": c.seq, "filename": c.filename,
"text": truncate(&c.text, TOOL_CHUNK_CHARS),
"truncated": c.text.trim().chars().count() > TOOL_CHUNK_CHARS,
})).collect::<Vec<_>>()
}))
}
/// 一篇文档的全文。**search_chunks 够不到的东西全在这里**:它只回前六条命中、
/// 每条切在 800 字上,答案落在第 801 字或落在没排上的那一块时,检索本身没错,
/// 错在没有第二步。
pub async fn get_document(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
args: &serde_json::Value,
) -> ToolResult {
let refuse = |step: Step| {
ToolResult::new(
"No document with that id in this knowledge base.".to_string(),
step.json(),
)
};
let Some(id) = args["document_id"]
.as_str()
.and_then(|s| s.trim().parse::<Uuid>().ok())
else {
return refuse(Step::new("document", "?", "invalid id").invalid("document_id"));
};
let offset = match args.get("offset") {
None => 0,
Some(value) => {
let Some(offset) = value.as_u64().and_then(|n| usize::try_from(n).ok()) else {
return ToolResult::new(
"get_document needs `offset` to be a non-negative integer character position."
.into(),
Step::new("document", "?", "invalid offset")
.invalid("offset")
.json(),
)
.error();
};
offset
}
};
// 本库之外的 id 一律当作不存在——分不出「没有」和「不给你看」才是对的
let doc = match utopia_store::documents::find_in_kb(&ctx.state.pool, ctx.kb_id, id).await {
Ok(Some(doc)) => doc,
Ok(None) => return refuse(Step::new("document", "?", "not found").status("not_found")),
Err(e) => {
tracing::warn!(error = %e, "MCP document lookup failed");
return ToolResult::new(
"Could not read the document.".into(),
Step::new("document", "?", "failed").status("failed").json(),
)
.error();
}
};
let chunks =
match utopia_store::documents::chunks_in_document(&ctx.state.pool, ctx.kb_id, id).await {
Ok(chunks) => chunks,
Err(e) => {
tracing::warn!(error = %e, "MCP document chunk read failed");
return ToolResult::new(
"Could not read the document.".into(),
Step::new("document", doc.filename, "failed")
.status("failed")
.json(),
)
.error();
}
};
let mut lines = Vec::new();
let mut skip = offset;
let mut used = 0usize;
let mut omitted = 0usize;
for c in &chunks {
let body = c.text.trim();
let len = body.chars().count();
// offset 只数按顺序拼接的正文,不数标题、引证和分块之间的排版。
if offset > 0 && skip >= len {
skip -= len;
continue;
}
let remaining = len - skip;
let room = DOCUMENT_CHARS.saturating_sub(used);
// 装不下的分块整块不发,也不引——发一个引证编号出去而正文不在,
// 界面上落成一条指不到东西的引证
if room == 0 {
omitted += remaining;
continue;
}
let read = remaining.min(room);
let body: String = if skip > 0 || remaining > room {
body.chars().skip(skip).take(read).collect()
} else {
body.to_string()
};
skip = 0;
omitted += remaining - read;
used += read;
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; call get_document with document_id: {id}, offset: {} to continue",
offset + used
));
}
let when = doc
.doc_time
.map(crate::time_text::instant)
.unwrap_or_else(|| "no date".to_string());
let header = format!(
"\"{}\" ({when}) — {} section(s):",
doc.filename,
chunks.len()
);
let text = if lines.is_empty() && offset > 0 {
format!("{header}\n(no text remaining at offset {offset})")
} else if lines.is_empty() {
format!("{header}\n(no text)")
} else {
format!("{header}\n\n{}", lines.join("\n\n"))
};
ToolResult::new(
text,
Step::new(
"document",
doc.filename.as_str(),
format!("{} sections", chunks.len()),
)
.count(chunks.len())
.json(),
)
}
pub async fn search_docs(
ctx: &ToolCtx<'_>,
sink: &mut ToolSink,
args: &serde_json::Value,
) -> ToolResult {
// 必填参数由 `chat::check_call` 在派发之前挡下,所以这里不再回落到
// 用户那句原话——回落产出的是一个看起来没问题的错误答案
let q = args["query"].as_str().unwrap_or_default().to_string();
// Tantivy 是同步的,放到阻塞线程池上,别占 runtime 线程(#515,与 retrieval.rs 同理)
let hits = {
let docs = ctx.state.docs.clone();
let q = q.clone();
tokio::task::spawn_blocking(move || docs.search(&q, 4))
.await
.ok()
.and_then(Result::ok)
.unwrap_or_default()
};
let mut lines = Vec::new();
for h in &hits {
let key = format!("charter:{}#{}", h.slug, h.anchor);
let n = cite(sink, key, |n| charter_source_json(n, h));
lines.push(format!(
"[{n}] Utopia Charter — {} › {}:\n{}",
h.title,
h.heading,
truncate(&h.body, 1600)
));
}
let text = if lines.is_empty() {
"No matching manual sections.".to_string()
} else {
lines.join("\n\n")
};
ToolResult::new(
text,
Step::new("docs", q.as_str(), format!("{} sections", hits.len()))
.count(hits.len())
.json(),
)
}
/// 这个库的判据。**把阈值原样给出来**——模型要能解释「凭什么算含气井」,
/// 而不是猜一个听起来合理的门槛。
pub async fn list_rules(ctx: &ToolCtx<'_>) -> ToolResult {
let Ok(rules) = utopia_store::business_rules::list(&ctx.state.pool, ctx.kb_id).await else {
return ToolResult::new(
"Could not read the rules.".to_string(),
Step::new("tool", "list_rules", "failed")
.status("failed")
.json(),
)
.error();
};
if rules.is_empty() {
return ToolResult::new(
"This base has no business rules.".to_string(),
Step::new("tool", "list_rules", "none").count(0).json(),
);
}
let expressions: Vec<_> = rules
.iter()
.filter(|r| r["conclusion"] == "computed")
.map(|r| &r["conclude_expr"])
.collect();
let Ok(descriptions) = utopia_store::business_rules::describe_expressions(
&ctx.state.pool,
ctx.kb_id,
&expressions,
)
.await
else {
return ToolResult::new(
"Could not read the rules.".to_string(),
Step::new("tool", "list_rules", "failed")
.status("failed")
.json(),
)
.error();
};
let mut descriptions = descriptions.into_iter();
let text = rules
.iter()
.map(|r| {
let conditions = r["conditions"]
.as_array()
.map(|cs| {
// The store orders conditions by group and sequence. Keep that
// order while showing the same OR-of-ANDs the evaluator uses.
let mut groups: Vec<(i64, Vec<String>)> = Vec::new();
for c in cs {
let group = c["group"].as_i64().unwrap_or(0);
// Legacy conditions have no side and mean the subject;
// keep their familiar unprefixed text while disambiguating Y.
let side = if c["side"] == "y" { "Y." } else { "" };
let condition = format!(
"{side}{} {} {}",
c["predicate_label"].as_str().unwrap_or("?"),
c["op"].as_str().unwrap_or("?"),
c["operand"]
.as_str()
.map(str::to_string)
.unwrap_or_else(|| c["operand"].to_string()),
);
if let Some((_, conditions)) =
groups.last_mut().filter(|(g, _)| *g == group)
{
conditions.push(condition);
} else {
groups.push((group, vec![condition]));
}
}
let alternatives = groups.len() > 1;
groups
.into_iter()
.map(|(_, conditions)| {
let text = conditions.join(" AND ");
if alternatives && conditions.len() > 1 {
format!("({text})")
} else {
text
}
})
.collect::<Vec<_>>()
.join(" OR ")
})
.unwrap_or_default();
let concludes = if r["conclusion"] == "typing" {
r["conclude_type_label"].as_str().unwrap_or("?").to_string()
} else if r["conclusion"] == "computed" {
format!(
"{} = {}",
r["conclude_predicate_label"].as_str().unwrap_or("?"),
descriptions
.next()
.flatten()
.unwrap_or_else(|| "(expression unavailable)".to_string()),
)
} else if r["conclusion"] == "relation" {
format!(
"{} from X to the Y reached by {}",
r["conclude_predicate_label"].as_str().unwrap_or("?"),
r["join_predicate_label"].as_str().unwrap_or("?"),
)
} else {
format!(
"{} = {}",
r["conclude_predicate_label"].as_str().unwrap_or("?"),
r["conclude_value"]
)
};
format!(
"{} [{}] — applies to {} where {} ⇒ {} · marks {} now · id {}",
r["name"].as_str().unwrap_or("?"),
if r["enabled"] == true { "on" } else { "off" },
r["subject_label"].as_str().unwrap_or("?"),
conditions,
concludes,
r["derived_count"],
r["id"].as_str().unwrap_or("?"),
)
})
.collect::<Vec<_>>()
.join("\n");
let n = rules.len();
ToolResult::new(
text,
Step::new("tool", "list_rules", format!("{n} rules"))
.count(n)
.json(),
)
}
/// 一条规则此刻标了谁。**前提一起给**:结论没有前提就跟一条凭空的断言没区别。
pub async fn rule_matches(ctx: &ToolCtx<'_>, args: &serde_json::Value) -> ToolResult {
let Some(rule_id) = args["rule_id"]
.as_str()
.and_then(|s| s.parse::<Uuid>().ok())
else {
return ToolResult::new(
"Invalid rule_id (expected the uuid returned by list_rules).".to_string(),
Step::new("tool", "rule_matches", "invalid id")
.invalid("rule_id")
.json(),
);
};
let limit = args["limit"].as_i64().unwrap_or(50).clamp(1, 200);
let Ok((rows, total)) =
utopia_store::business_rules::matches(&ctx.state.pool, ctx.kb_id, rule_id, limit, 0).await
else {
return ToolResult::new(
"Could not read what that rule marks.".to_string(),
Step::new("tool", "rule_matches", "failed")
.status("failed")
.json(),
)
.error();
};
if rows.is_empty() {
return ToolResult::new(
"That rule marks nothing right now.".to_string(),
Step::new("tool", "rule_matches", "0").count(0).json(),
);
}
let text = rows
.iter()
.map(|m| {
let premises = m["premises"]
.as_array()
.map(|p| {
p.iter()
.filter_map(|x| x.as_str())
.collect::<Vec<_>>()
.join(", ")
})
.unwrap_or_default();
// This query includes historical conclusions. A missing bound does
// not establish that the conclusion holds now.
let bound = |key: &str, precision: &str, unknown: &str| {
m[key]
.as_str()
.and_then(|s| s.parse().ok())
.map(|t| crate::time_text::world(t, m[precision].as_str()))
.unwrap_or_else(|| unknown.to_string())
};
let from = bound("valid_from", "valid_from_precision", "unknown start");
let to = bound("valid_to", "valid_to_precision", "unknown end");
let concluded = if m["object_entity"].is_null() {
m["concluded"]
.as_str()
.map(str::to_string)
.unwrap_or_else(|| m["concluded"].to_string())
} else {
format!(
"{} {}",
m["relation_predicate"]
.as_str()
.unwrap_or_else(|| m["concluded"].as_str().unwrap_or("?")),
m["object_entity"].as_str().unwrap_or("?"),
)
};
format!(
"{} ⇒ {concluded} (because {}) [validity: {from} → {to}] [{}]",
m["entity"].as_str().unwrap_or("?"),
premises,
m["entity_id"].as_str().unwrap_or("?"),
)
})
.collect::<Vec<_>>()
.join("\n");
// 截断要说出来:模型看到 50 条会当成全部,而库里可能有两百
let text = if total > rows.len() as i64 {
format!("{text}\n(showing {} of {total} matches)", rows.len())
} else {
text
};
ToolResult::new(
text,
Step::new("tool", "rule_matches", format!("{total} matches"))
.field("count", total)
.json(),
)
}
pub async fn changes(ctx: &ToolCtx<'_>, args: &serde_json::Value) -> ToolResult {
// 两端与 `at` 同一种写法:YYYY / YYYY-MM / YYYY-MM-DD。`since` 取那一段的第一天,
// `until` 取最后一天——「2023 年有什么变化」不该逼模型编一个 12 月 31 日
let since = args["since"]
.as_str()
.and_then(utopia_extract::parse_time)
.map(|(t, _)| t.date_naive());
let until = args["until"]
.as_str()
.and_then(utopia_extract::parse_time)
.map(|(t, p)| period_last_day(t.date_naive(), p));
// 窗口的两头按问的那天交给界面:label 里的 "now" 是英文
let (since_day, until_day) = (since, until);
let Some((since, until, window)) = changes_window(since, until, chrono::Utc::now()) else {
return ToolResult::new(
"Invalid or missing `since` (expected YYYY-MM-DD).".to_string(),
Step::new("changes", "?", "invalid since")
.invalid("since")
.json(),
)
.error();
};
let entity = args["entity_id"]
.as_str()
.and_then(|s| s.parse::<Uuid>().ok());
let kinds: Option<Vec<String>> = args["kinds"].as_array().map(|a| {
a.iter()
.filter_map(|v| v.as_str().map(str::to_string))
.collect()
});
let kinds = kinds.filter(|k: &Vec<String>| !k.is_empty());
let rows = match utopia_store::graph::graph_changes(
&ctx.state.pool,
ctx.kb_id,
since,
until,
entity,
kinds.as_deref(),
CHANGES_LIMIT,
)
.await
{
Ok(rows) => rows,
Err(e) => {
tracing::warn!(error = %e, "Graph changes lookup failed");
return ToolResult::new(
"Could not read the graph changes.".into(),
Step::new("changes", window, "failed")
.status("failed")
.json(),
)
.error();
}
};
let text = if rows.is_empty() {
format!("No recorded changes in {window}.")
} else {
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")
} else {
format!("{} changes", rows.len())
};
let mut step = Step::new("changes", window.as_str(), detail)
.count(rows.len())
.more(rows.len() as i64 == CHANGES_LIMIT);
if let Some(day) = since_day {
step = step.field("since", day.to_string());
}
if let Some(day) = until_day {
step = step.field("until", day.to_string());
}
ToolResult::new(text, step.json()).structured(json!({
"kb_id": ctx.kb_id, "since": since, "until": until,
"limit": CHANGES_LIMIT, "limit_reached": rows.len() as i64 == CHANGES_LIMIT,
"changes": rows.iter().map(|r| json!({
"fact_id": r.fact_id, "at": r.at, "kind": r.kind,
"subject_id": r.subject_id, "subject_name": r.subject_name,
"predicate_label": r.predicate_label, "object_name": r.object_name,
"object_value": r.object_value, "confidence": r.confidence,
"valid_from": r.valid_from, "valid_to": r.valid_to,
"valid_from_precision": r.valid_from_precision,
"valid_to_precision": r.valid_to_precision,
"document_id": r.document_id, "filename": r.filename, "quote": r.quote,
"quote_origin": r.quote_origin,
})).collect::<Vec<_>>()
}))
}
pub async fn query_data(ctx: &ToolCtx<'_>, args: &serde_json::Value) -> ToolResult {
let ds_name = args["data_source"].as_str().map(str::trim).unwrap_or("");
let sql = args["sql"].as_str().map(str::trim).unwrap_or("");
let purpose = args["purpose"].as_str().map(str::trim).unwrap_or("");
// 安全边界:只允许本 KB 挂载的源(凭据不出服务端)
let found = ctx
.mounted_sources
.iter()
.find(|d| d.name.eq_ignore_ascii_case(ds_name));
let detail = if purpose.is_empty() {
sql.chars().take(60).collect::<String>()
} else {
purpose.to_string()
};
// 界面上的这一步带着写下的那条 SQL(#936):读者能展开看到数是怎么算出来的;
// 查询出错、源不存在各是一种结果,不再和「查到了」长得一样
let step = Step::new("query", ds_name, detail).field("sql", sql);
let (text, step) = match found {
None => (
format!(
"Unknown data source '{ds_name}'. Mounted sources: {}",
ctx.mounted_sources
.iter()
.map(|d| d.name.as_str())
.collect::<Vec<_>>()
.join(", ")
),
step.status("not_found"),
),
Some(ds) => match execute_query(ctx.state, ds.id, sql).await {
Ok(result) => (
query_text(&result),
step.count(result.rows.len()).more(result.truncated),
),
// 错误透传:模型可据此修正 SQL 重试
Err(e) => (format!("Query failed: {e}"), step.status("failed")),
},
};
ToolResult::new(text, step.json())
}
pub async fn remember(ctx: &ToolCtx<'_>, args: &serde_json::Value) -> ToolResult {
// NUL 在入口就剥(#665):`append_episode` 自己也剥,但这里拼的回复与卡片详情
// 用的是同一份文本——对话里它们要落进会话记录,Postgres 的 TEXT 与 JSONB 一样
// 不收 0x00,一轮对话会因为回显了几个字节而存不下来
let text = utopia_core::without_nul(args["text"].as_str().unwrap_or(""));
let text = text.trim();
// 与 `at` 同一种写法:YYYY / YYYY-MM / YYYY-MM-DD 或 RFC3339。日期落在那段第一天的
// 正午——离两边的日界都最远;时刻照给的。回显按给的精度写,不把「2023 年」说成 1 月 1 日
let (occurred_at, occurred_text) = match args["occurred_at"].as_str().map(str::trim) {
Some(s) if !s.is_empty() => match utopia_extract::parse_time(s) {
Some((d, precision)) => (
if matches!(precision, "year" | "month" | "day") {
d + chrono::Duration::hours(12)
} else {
d
},
crate::time_text::world(d, Some(precision)),
),
None => match parse_when(s) {
Some(at) => (at, crate::time_text::instant(at)),
None => {
let now = chrono::Utc::now();
(now, crate::time_text::instant(now))
}
},
},
_ => {
let now = chrono::Utc::now();
(now, crate::time_text::instant(now))
}
};
if text.is_empty() {
return ToolResult::new(
"remember requires non-empty text.".to_string(),
Step::new("tool", "remember", "empty")
.missing("text")
.json(),
)
.error();
}
match utopia_store::memory::append_episode(&ctx.state.pool, ctx.kb_id, text, occurred_at).await
{
Ok((doc_id, chunk_id)) => {
// 摄入(embedding/索引/增量抽取)异步走队列,不阻塞对话。
// 抽出来的事实**先等人点头**(0015)——所以这里只能如实说「记下了这句话」,
// 说不出抽出了几条:抽取还没跑。卡片在任务完成时长到对话里
let _ = utopia_store::jobs::enqueue(
&ctx.state.pool,
"memory_ingest",
json!({
"document_id": doc_id,
"proposed_by": ctx.actor,
"proposed_token": ctx.via_token,
}),
)
.await;
ctx.state.emit_document(ctx.kb_id, doc_id);
ToolResult::new(
format!(
"Recorded the sentence (effective {}): {text}\n\
Facts extracted from it will be shown to the user for confirmation \
before entering the graph. Tell the user exactly that: the sentence is \
recorded, and the extracted facts await their confirmation. Do not claim \
any fact has been added to the knowledge graph.",
occurred_text
),
// 对话里那张确认卡按 chunk_id 取待确认项;回放时也据此重画
Step::new(
"tool",
"remember",
text.chars().take(60).collect::<String>(),
)
.field("chunk_id", chunk_id)
.json(),
)
}
Err(e) => ToolResult::new(
format!("Failed to record: {e}"),
Step::new("tool", "remember", "failed")
.status("failed")
.json(),
)
.error(),
}
}
// ---------------------------------------------------------------------------
// 排版与执行的辅助。**对话降级路径也用它们**,所以是 pub(super) 而不是私有
// ---------------------------------------------------------------------------
pub(super) fn source_json(n: usize, c: &ChunkView) -> serde_json::Value {
json!({
"n": n,
"chunk_id": c.id,
"document_id": c.document_id,
"filename": c.filename,
"excerpt": truncate(&c.text, 160),
})
}
/// Charter 引用:前端渲染成手册行,链到 /docs/{slug}#{anchor}。
pub(super) fn charter_source_json(n: usize, h: &utopia_search::DocsSection) -> serde_json::Value {
json!({
"n": n,
"kind": "charter",
"slug": h.slug,
"anchor": h.anchor,
"heading": h.heading,
"filename": h.title,
"excerpt": truncate(&h.body, 160),
})
}
/// 问数执行:安全闸(解析白名单)→ 引擎执行(只读会话 + 强制 LIMIT + 超时)→ JSON 行。
pub(crate) async fn run_query(state: &AppState, ds_id: Uuid, sql: &str) -> anyhow::Result<String> {
Ok(query_text(&execute_query(state, ds_id, sql).await?))
}
/// 同 `run_query`,但交回行与截断标记本身:对话里那一步要行数和截断(#936)
async fn execute_query(
state: &AppState,
ds_id: Uuid,
sql: &str,
) -> anyhow::Result<crate::query_engine::QueryResult> {
let (engine, conn) = utopia_store::datasources::engine_and_conn(&state.pool, ds_id).await?;
// 闸门按引擎选方言:Databricks 的反引号、Snowflake 的 :: 转型都得先过得了解析
let guarded = crate::query_engine::guard_sql_for(&engine, sql)?;
crate::query_engine::engine_for(&engine, &conn)?
.execute(&guarded)
.await
}
/// 结果给模型读的样子:每行一个 JSON 对象,末尾是行数与截断说明
fn query_text(result: &crate::query_engine::QueryResult) -> String {
let mut out = String::new();
if result.rows.is_empty() {
out.push_str("(no rows)");
} else {
out.push_str(&result.rows.join("\n"));
out.push_str(&format!("\n({} rows", result.rows.len()));
if result.truncated {
out.push_str(&format!(
", truncated at {} — aggregate in SQL for totals",
crate::query_engine::ROW_CAP
));
}
out.push(')');
}
out
}
/// 时间线关上一行时接任的那一端怎么写(#970 第二步):接任者或新宾语的名字,属性事实是
/// 新的值,写法同事实行上的字面值(`literal_text`)
pub(super) fn successor_text(
name: Option<&str>,
value: Option<&serde_json::Value>,
) -> Option<String> {
name.map(str::to_string)
.or_else(|| value.and_then(literal_text))
}
/// 事实行:"works at → 星云科技 (2023-08 → now) [90%]",in 方向用 ←。`closer_mark` 是关上
/// 它的那一行证据的号(对话里 ` [n]`,MCP 与没有证据时为空)
pub(super) fn fact_line(f: &EntityFact, closer_mark: &str) -> String {
// 属性事实没有对端实体,值在 `object_value` 里(0004)。从前这里只看 `other_name`,
// 于是薪资、职位到了模型眼前是 `salary → ?`——区间和置信度都在,唯独值没到,
// 模型只能说"没有薪资信息"(#348)。渲染规则与客户端 `fmtObjectValue` 一致
let literal = f
.object_value
.as_ref()
.and_then(literal_text)
.filter(|_| f.other_name.is_none());
let other = f
.other_name
.as_deref()
.or(literal.as_deref())
.unwrap_or("?");
// 边上的属性(0037)跟在对端后面:`invested_in → Kestrel [amount: 4000000000 $]`。
// 模型读事实行时最常问的就是"投了多少",数不在行里它就答"没有金额信息"
let quals: Vec<String> = f
.qualifiers
.iter()
.map(|q| {
let v = q
.value
.as_ref()
.and_then(literal_text)
.or_else(|| q.entity_name.clone())
.unwrap_or_else(|| "?".to_string());
format!("{}: {v}", q.key)
})
.collect();
let other = if quals.is_empty() {
other.to_string()
} else {
format!("{other} [{}]", quals.join(", "))
};
// 本体没认下、原文说法也没留下时用 "?"——与 other 同一个约定。
// 不编一个"相关"出来:那正是删掉 related_to 要消灭的东西
let pred = f.predicate_label.as_deref().unwrap_or("?");
let core = if f.direction == "out" {
format!("{pred} → {other}")
} else {
format!("{pred} ← {other}")
};
// 两端各按自己的精度写;没起点的从证据起,结束了不知哪天的到说出它的那份文档为止
//(time_text,0022)。从前一律 %Y-%m-%d,年精度印成 1 月 1 日、结束未知印成 now
let successor = successor_text(f.closed_by.as_deref(), f.closed_by_value.as_ref());
let range = crate::time_text::span(crate::time_text::Span {
valid_from: f.valid_from,
from_precision: f.valid_from_precision.as_deref(),
valid_to: f.valid_to,
to_precision: f.valid_to_precision.as_deref(),
holds_from: f.holds_from,
holds_to: f.holds_to,
end_derived: f.end_derived,
corrected: f.corrected_ends.as_deref(),
closed_by: successor.as_deref().map(|who| (who, closer_mark)),
correction_note: f.correction_note.as_deref(),
});
let range = if range.is_empty() {
range
} else {
format!(" ({range})")
};
format!("{core}{range} [{}%]", (f.confidence * 100.0).round() as i32)
}
// 记录轴上的两次更正可以发生在同一秒;输出必须能原样交回 as_of,不能截到天或秒。
fn record_stamp(time: chrono::DateTime<chrono::Utc>) -> String {
crate::time_text::instant(time)
}
/// 严格早于 T,按账本的分辨率(timestamptz 是微秒):不晚于 T − 1µs。
/// `recorded_at <= T−1µs` 恰好是 `recorded_at < T`,`invalidated_at > T−1µs` 恰好是
/// `invalidated_at >= T`——0019 的 held_at 一个字不用改
pub(super) fn just_before(t: chrono::DateTime<chrono::Utc>) -> chrono::DateTime<chrono::Utc> {
t - chrono::Duration::microseconds(1)
}
pub(super) fn entity_facts_detail(
count: usize,
at: Option<chrono::DateTime<chrono::Utc>>,
as_of: Option<chrono::DateTime<chrono::Utc>>,
before: Option<chrono::DateTime<chrono::Utc>>,
) -> String {
// 记录轴那半句:给了 before 就说「before T」,是人问的那个时刻,不是减过一微秒的
let record = match (before, as_of) {
(Some(b), _) => Some(format!("as recorded before {}", record_stamp(b))),
(None, Some(r)) => Some(format!("as recorded by {}", record_stamp(r))),
(None, None) => None,
};
match (at, record) {
(Some(t), Some(r)) => format!("{count} facts at {}, {r}", record_stamp(t)),
(Some(t), None) => format!("{count} facts as of {}", record_stamp(t)),
(None, Some(r)) => format!("{count} facts {r}"),
(None, None) => format!("{count} facts"),
}
}
/// 时刻参数:`YYYY-MM-DD` 或 RFC3339。`at` 与 `as_of` 共用一个解析——记录轴上的
/// 时刻常常是一个带时间的戳("第一波灌完那一刻"),日期粒度装不下它
pub(super) fn parse_when(raw: &str) -> Option<chrono::DateTime<chrono::Utc>> {
let s = raw.trim();
// 完整的 RFC3339 时刻原样收下,小数秒也留着——记录轴上同一秒内可以先录入再更正
// (#351),这里截掉一位就把两次认知叠回一起。日期形式(YYYY / YYYY-MM / YYYY-MM-DD,
// 或带时区的缩略钟点)才交给抽取端同一个解析,取那一段的开头
if let Ok(t) = chrono::DateTime::parse_from_rfc3339(s) {
return Some(t.with_timezone(&chrono::Utc));
}
utopia_extract::parse_time(s).map(|(d, _)| d)
}
/// 字面值宾语给模型看的样子:`{value, unit}` → "28000 CNY",布尔 → ✓/✗,
/// 映射那类 `{summary}` → 摘要本身。与 `web/src/pages/Graph.tsx::fmtObjectValue` 同一条规则,
/// 两边分叉的话,人看到的和模型看到的就不是同一个值
pub(super) fn literal_text(v: &serde_json::Value) -> Option<String> {
// 裸标量(`changes` 那头的旧数据长这样):字符串读成它自己,不带引号
match v {
serde_json::Value::Null => return None,
serde_json::Value::String(s) => return Some(s.clone()),
serde_json::Value::Bool(_) | serde_json::Value::Number(_) => return Some(v.to_string()),
_ => {}
}
if let Some(val) = v.get("value") {
let text = match val {
serde_json::Value::Bool(true) => "✓".to_string(),
serde_json::Value::Bool(false) => "✗".to_string(),
serde_json::Value::String(s) => s.clone(),
serde_json::Value::Null => return None,
other => other.to_string(),
};
return Some(
match v
.get("unit")
.and_then(|u| u.as_str())
.filter(|u| !u.is_empty())
{
Some(unit) => format!("{text} {unit}"),
None => text,
},
);
}
if let Some(summary) = v.get("summary").and_then(|s| s.as_str()) {
return Some(summary.to_string());
}
Some(v.to_string())
}
/// changes 的时间窗:把两个可选日期变成 (SQL 用的半开区间, 展示用的窗口串)。
///
/// **抽成纯函数是因为这里出过一次错。** `until` 进 SQL 前要加一天(说"到 3 月 31 日
/// 为止"的人要的是含 31 日,而 SQL 那头是 `< $3`),第一版把加过一天的值也印进了
/// 展示串,模型于是照着答"截至 8 月 30 日"——问的是 29 日。两个值必须一起算、
/// 一起被测住;分在两处写,迟早再次分叉。
///
/// `now` 从外面传进来而不是在里面取,纯粹是为了这个函数测得动。
/// 一段(年 / 月 / 日)的最后一天:`until=2023` 是到 12 月 31 日为止,含那一整天。
fn period_last_day(first: chrono::NaiveDate, precision: &str) -> chrono::NaiveDate {
use chrono::Datelike;
match precision {
"year" => chrono::NaiveDate::from_ymd_opt(first.year(), 12, 31).unwrap_or(first),
"month" => {
let (y, m) = if first.month() == 12 {
(first.year() + 1, 1)
} else {
(first.year(), first.month() + 1)
};
chrono::NaiveDate::from_ymd_opt(y, m, 1)
.and_then(|d| d.pred_opt())
.unwrap_or(first)
}
_ => first,
}
}
fn changes_window(
since: Option<chrono::NaiveDate>,
until: Option<chrono::NaiveDate>,
now: chrono::DateTime<chrono::Utc>,
) -> Option<(
chrono::DateTime<chrono::Utc>,
chrono::DateTime<chrono::Utc>,
String,
)> {
let from = since?;
let start = from.and_hms_opt(0, 0, 0).unwrap().and_utc();
let end = until
.and_then(|d| d.succ_opt())
.map(|d| d.and_hms_opt(0, 0, 0).unwrap().and_utc())
.unwrap_or(now);
// 展示用的是**问的那天**,没问就写 now——绝不是 end
let label = format!(
"{} → {}",
from.format("%Y-%m-%d"),
match until {
Some(d) => d.format("%Y-%m-%d").to_string(),
None => "now".to_string(),
}
);
Some((start, end, label))
}
/// 认知轴上的一行。
///
/// 排版把两根轴**分开写**:`at` 前面标事件类型,世界轴的区间夹在括号里跟在断言后。
/// 若把它们排成一串日期,模型会把"2026 年记下的"读成"2026 年发生的"——那正是
/// 这个工具要防的误读。
fn change_line(c: &GraphChange) -> String {
// 字面值宾语与 `fact_line` 同一条规则(`literal_text`):两个工具看到的
// 不能是两种写法,否则 `{value, unit}` 在这里会印成一段 JSON
let object = match (&c.object_name, &c.object_value) {
(Some(name), _) => name.clone(),
(None, Some(v)) => literal_text(v).unwrap_or_else(|| "?".to_string()),
(None, None) => "?".to_string(),
};
// 世界轴两端按自己的精度写(time_text);事件行上没有锚点,结束未知只能写成话
let range = crate::time_text::span(crate::time_text::Span {
valid_from: c.valid_from,
from_precision: c.valid_from_precision.as_deref(),
valid_to: c.valid_to,
to_precision: c.valid_to_precision.as_deref(),
holds_from: None,
holds_to: None,
// 记录轴上的一次变更,不是事实行:它自己就说了改的是什么
end_derived: false,
corrected: None,
closed_by: None,
correction_note: None,
});
let range = if range.is_empty() {
range
} else {
format!(" [valid {range}]")
};
// 文件名不带 [n]:引证编号是 chunk 的,这里只有 document,发一个编号出去
// 会在界面上落成一条指不到东西的引证
let src = match (&c.filename, &c.quote) {
(Some(f), Some(q)) => format!(" — from \"{f}\": \"{}\"", truncate(q, 160)),
(Some(f), None) => format!(" — from \"{f}\""),
_ => String::new(),
};
format!(
"{} {}: {} {} {}{}{}",
record_stamp(c.at),
c.kind,
c.subject_name,
c.predicate_label.as_deref().unwrap_or("?"),
object,
range,
src
)
}
pub(super) fn truncate(text: &str, max_chars: usize) -> String {
let t = text.trim();
if t.chars().count() <= max_chars {
t.to_string()
} else {
let cut: String = t.chars().take(max_chars).collect();
format!("{cut}…")
}
}
#[cfg(test)]
mod tests {
use super::*;
fn d(s: &str) -> chrono::NaiveDate {
chrono::NaiveDate::parse_from_str(s, "%Y-%m-%d").unwrap()
}
fn t(s: &str) -> chrono::DateTime<chrono::Utc> {
s.parse().unwrap()
}
// --- parse_when -------------------------------------------------------------
/// `at` 与 `as_of` 共用一个解析:日期按当天零点,RFC3339 原样;别的一律 None,
/// 不猜——猜出来的时刻会安静地把问题答到另一天上
#[test]
fn a_moment_is_a_date_or_an_rfc3339_stamp_and_nothing_else() {
assert_eq!(parse_when("2024-08-01"), Some(t("2024-08-01T00:00:00Z")));
assert_eq!(
parse_when(" 2026-09-05T02:43:24.197Z "),
Some(t("2026-09-05T02:43:24.197Z"))
);
assert_eq!(parse_when("August 2024"), None);
assert_eq!(parse_when(""), None);
}
// --- changes_window -----------------------------------------------------
/// 说"到 3 月 31 日为止"的人要的是**含 31 日**。SQL 那头是 `< end`,
/// 所以 end 必须落在 4 月 1 日零点——差这一天,问 31 日会安静地丢掉 31 日
#[test]
fn until_names_a_day_the_window_must_contain() {
let (start, end, label) = changes_window(
Some(d("2026-03-01")),
Some(d("2026-03-31")),
t("2026-06-01T00:00:00Z"),
)
.unwrap();
assert_eq!(start, t("2026-03-01T00:00:00Z"));
assert_eq!(end, t("2026-04-01T00:00:00Z"));
// 但**展示串里绝不能出现 04-01**:那是半开区间的内部细节,
// 印出去等于告诉模型窗口比它要的宽一天,模型会照着答(这条真的发生过)
assert_eq!(label, "2026-03-01 → 2026-03-31");
}
/// 没给 until 时,展示串写 now。写成 end 的格式化结果就等于把服务器时钟
/// 当成用户问的边界——看着像个精确答案,其实只是"现在几点"
#[test]
fn an_open_window_says_now_rather_than_the_clock() {
let now = t("2026-06-01T13:45:00Z");
let (_, end, label) = changes_window(Some(d("2026-03-01")), None, now).unwrap();
assert_eq!(end, now);
assert_eq!(label, "2026-03-01 → now");
}
#[test]
fn without_since_there_is_no_window() {
assert!(changes_window(None, Some(d("2026-03-31")), t("2026-06-01T00:00:00Z")).is_none());
}
// --- change_line --------------------------------------------------------
/// 年精度的起点写成年,不再印成 1 月 1 日;结束了不知哪天绝不写 now
#[test]
fn a_change_line_shows_each_end_at_its_precision() {
let mut c = change("asserted");
c.valid_from = Some(t("2019-01-01T00:00:00Z"));
c.valid_from_precision = Some("year".into());
assert!(
change_line(&c).contains("[valid 2019 → now]"),
"{}",
change_line(&c)
);
c.valid_to_precision = Some("unknown".into());
assert!(
change_line(&c).contains("[valid 2019 → ended, date unknown]"),
"{}",
change_line(&c)
);
}
#[test]
fn a_window_end_covers_the_whole_period_named() {
assert_eq!(period_last_day(d("2023-01-01"), "year"), d("2023-12-31"));
assert_eq!(period_last_day(d("2024-02-01"), "month"), d("2024-02-29"));
assert_eq!(period_last_day(d("2023-12-01"), "month"), d("2023-12-31"));
assert_eq!(period_last_day(d("2023-06-15"), "day"), d("2023-06-15"));
// parse_when 与 at 同一种写法
assert_eq!(parse_when("2023"), Some(t("2023-01-01T00:00:00Z")));
assert_eq!(parse_when("2023-06"), Some(t("2023-06-01T00:00:00Z")));
}
fn change(kind: &str) -> GraphChange {
GraphChange {
fact_id: Uuid::nil(),
at: t("2026-08-28T10:00:00Z"),
kind: kind.to_string(),
subject_id: Uuid::nil(),
subject_name: "Acme".to_string(),
predicate_label: Some("founded in".to_string()),
object_name: None,
object_value: None,
valid_from: None,
valid_to: None,
// 两端都没日期就没有精度——夹具也得守这条不变量(见 `facts.valid_from_precision`)
// 两端都没日期,所以两端都没有精度(见 facts 的两个精度列)
valid_from_precision: None,
valid_to_precision: None,
confidence: 0.9,
document_id: None,
filename: None,
quote: None,
quote_origin: None,
}
}
// 同一秒内也能先录入再更正;截到整秒会把这两次认知重新叠在一起。
#[test]
fn change_stamps_round_trip_without_losing_the_record_clock() {
let mut c = change("corrected");
for stamp in [
"2026-09-05T02:43:53Z",
"2026-09-05T02:43:53.382Z",
"2026-09-05T02:43:53.382001Z",
"2026-09-05T02:43:53.382002Z",
] {
c.at = t(stamp);
let line = change_line(&c);
let printed = line.split_whitespace().next().unwrap();
assert_eq!(printed, stamp);
assert_eq!(parse_when(printed), Some(c.at));
}
}
/// `before` 减的是账本分辨率的一微秒——不是一秒、不是一天;摘要里写的是人问的那个时刻
#[test]
fn before_is_the_microsecond_before_at_the_ledgers_resolution() {
let t0 = t("2026-09-05T02:43:53.382Z");
assert_eq!(just_before(t0), t("2026-09-05T02:43:53.381999Z"));
assert_eq!(
just_before(t("2026-09-05T02:43:53Z")),
t("2026-09-05T02:43:52.999999Z"),
"小数为零要向秒借位——正是不该让模型算的那一步"
);
assert_eq!(
entity_facts_detail(2, None, Some(just_before(t0)), Some(t0)),
"2 facts as recorded before 2026-09-05T02:43:53.382Z"
);
}
#[test]
fn fact_details_keep_the_record_instant_beside_the_world_date() {
let at = Some(t("2024-08-01T00:00:00Z"));
let as_of = Some(t("2026-09-05T02:43:53.382001Z"));
assert_eq!(
entity_facts_detail(2, at, as_of, None),
"2 facts at 2024-08-01T00:00:00Z, as recorded by 2026-09-05T02:43:53.382001Z"
);
assert_eq!(
entity_facts_detail(2, None, as_of, None),
"2 facts as recorded by 2026-09-05T02:43:53.382001Z"
);
assert_eq!(
entity_facts_detail(2, at, None, None),
"2 facts as of 2024-08-01T00:00:00Z"
);
assert_eq!(entity_facts_detail(0, None, None, None), "0 facts");
}
fn attribute_fact(value: serde_json::Value) -> EntityFact {
EntityFact {
said_as: None,
recorded_at: chrono::Utc::now(),
invalidated_at: None,
supersedes: None,
document_ids: vec![],
id: Uuid::nil(),
direction: "out".into(),
predicate_key: Some("salary".into()),
predicate_label: Some("salary".into()),
inferred: false,
temporal: Some("state".into()),
other_id: None,
other_name: None,
other_type: None,
qualifiers: Vec::new(),
statement_qualifiers: Vec::new(),
object_value: Some(value),
valid_from: Some(t("2023-06-01T00:00:00Z")),
valid_to: Some(t("2024-02-20T00:00:00Z")),
valid_from_precision: Some("day".into()),
valid_to_precision: Some("day".into()),
holds_from: Some(t("2023-06-01T00:00:00Z")),
holds_to: Some(t("2024-02-20T00:00:00Z")),
attested_by: None,
confidence: 0.9,
evidence_count: 1,
stale: false,
corrected: false,
end_derived: false,
end_after_period: false,
time_corrected: false,
corrected_ends: None,
closed_by_id: None,
closed_by: None,
closed_by_value: None,
correction_note: None,
last_evidence_time: None,
contested: None,
}
}
/// 属性事实的值要到模型眼前(#348)。从前这里是 `salary → ? (2023-06-01 → 2024-02-20)`:
/// 区间和置信度都在,唯独值没到,模型只能说"没有薪资信息"——而账本里明明有
#[test]
fn an_attribute_fact_shows_the_model_its_value() {
let line = fact_line(
&attribute_fact(serde_json::json!({ "value": 28000, "unit": "CNY" })),
"",
);
assert!(line.starts_with("salary → 28000 CNY"), "{line}");
assert!(line.contains("(2023-06-01 → 2024-02-20)"), "{line}");
// 与客户端 fmtObjectValue 同一条规则:布尔画成 ✓/✗,映射摘要读摘要本身
let flag = fact_line(&attribute_fact(serde_json::json!({ "value": true })), "");
assert!(flag.starts_with("salary → ✓"), "{flag}");
let mapped = fact_line(
&attribute_fact(serde_json::json!({ "summary": "orders.total" })),
"",
);
assert!(mapped.starts_with("salary → orders.total"), "{mapped}");
}
/// 本体没接住的关系仍然是 "?":那个问号是给「没有谓词」留的,不是给「有值」用的
#[test]
fn a_missing_object_still_reads_as_a_question_mark() {
let mut f = attribute_fact(serde_json::json!(null));
f.object_value = None;
assert!(
fact_line(&f, "").starts_with("salary → ?"),
"{}",
fact_line(&f, "")
);
}
/// 字面值要读成它自己。走 `Value::to_string()` 会把字符串连引号一起印出来,
/// 模型于是把 `"1993"` 当成答案的一部分
#[test]
fn a_literal_value_reads_as_itself_not_as_json() {
let mut c = change("asserted");
c.object_value = Some(serde_json::json!("1993"));
assert!(
change_line(&c).ends_with("Acme founded in 1993"),
"{}",
change_line(&c)
);
}
/// 两根轴必须在同一行里**看得出是两样东西**:记录时刻在前、无标签,
/// 世界轴区间在后、带 `valid` 字样。排成一串裸日期,模型会把
/// "2026 年记下的"读成"2026 年发生的"——这个工具存在的理由就是防这个
#[test]
fn the_record_time_and_the_valid_range_do_not_read_as_one_date_run() {
let mut c = change("corrected");
c.object_name = Some("Berlin".to_string());
c.predicate_label = Some("headquartered in".to_string());
c.valid_from = Some(t("2019-01-01T00:00:00Z"));
c.valid_from_precision = Some("day".into());
let line = change_line(&c);
assert!(
line.starts_with("2026-08-28T10:00:00Z corrected: "),
"{line}"
);
assert!(line.contains("[valid 2019-01-01 → now]"), "{line}");
}
/// 没有证据就什么都别说。凭空补一句 from "…" 会让一条无出处的断言
/// 看起来有出处
#[test]
fn a_fact_with_no_evidence_claims_no_document() {
let mut c = change("rejected");
c.object_name = Some("Berlin".to_string());
assert!(!change_line(&c).contains("from"), "{}", change_line(&c));
}
#[test]
fn evidence_carries_the_filename_and_the_quote() {
let mut c = change("corrected");
c.object_name = Some("Berlin".to_string());
c.filename = Some("annual-report.pdf".to_string());
c.quote = Some("moved its head office to Berlin".to_string());
let line = change_line(&c);
assert!(line.contains("from \"annual-report.pdf\""), "{line}");
assert!(
line.contains("\"moved its head office to Berlin\""),
"{line}"
);
}
}