Skip to content

World's first open-source enterprise world model.

Preserve same-name entities with response-local extraction handles (#296)

livid arche9c0496e4a833
diff --git a/crates/utopia-extract/src/lib.rs b/crates/utopia-extract/src/lib.rs
index d731b9c8..ae962a7a 100644
--- a/crates/utopia-extract/src/lib.rs
+++ b/crates/utopia-extract/src/lib.rs
@@ -24,6 +24,10 @@ pub struct Extraction {
#[derive(Debug, Deserialize)]
pub struct ExtractedEntity {
+ /// Identifier scoped to this extraction response. It preserves mention identity while
+ /// facts are bound; it is not a persistent entity id or a resolution verdict.
+ #[serde(default)]
+ pub local_id: Option<String>,
pub name: String,
#[serde(rename = "type")]
pub type_key: String,
@@ -40,10 +44,16 @@ pub struct ExtractedEntity {
#[derive(Debug, Deserialize)]
pub struct ExtractedFact {
pub subject: String,
+ /// Response-local entity handle. When present, callers must bind through it rather than
+ /// guessing from the surface name.
+ #[serde(default)]
+ pub subject_ref: Option<String>,
pub predicate: String,
/// 关系事实的宾语实体名;属性事实为空
#[serde(default)]
pub object: Option<String>,
+ #[serde(default)]
+ pub object_ref: Option<String>,
/// 属性事实的字面值(谓词是 attribute 时)
#[serde(default)]
pub value: Option<serde_json::Value>,
@@ -73,6 +83,13 @@ pub struct PromptRelation {
pub signature: String,
}
+/// Response-scoped reference to a persistent entity; database UUIDs must never enter prompts.
+pub struct KnownEntity {
+ pub handle: String,
+ pub type_key: String,
+ pub name: String,
+}
+
/// 构造抽取提示词。`types` 为 (key, label, description) 三元组;
/// description 非空时按行列出——本体里的语义指引直接决定抽取质量。
/// `attributes` 为调用方预排版的属性行("person.salary (number, CNY): 月薪");
@@ -83,9 +100,9 @@ pub fn build_messages(
attributes: &[String],
doc_time: Option<&str>,
filename: &str,
- // 本文档前面几块已经认下的 (类型 key, 实体名),按首次出现排序。
+ // 本文档前面几块已经认下的实体,按首次出现排序。handle 只对这次回复有效。
// 第一块为空——那时还没有"前面"
- known: &[(String, String)],
+ known: &[KnownEntity],
chunk_text: &str,
) -> Vec<ChatMessage> {
// **有描述时不送 label**。label 是给人看的显示名,而且它跟界面无关、
@@ -203,17 +220,28 @@ pub fn build_messages(
{attr_section}\
\n\
Output format:\n\
- {{\"entities\":[{{\"name\":\"entity name\",\"type\":\"type key\",\"specific_type\":\"what you would call it\"}}],\n\
- \"facts\":[{{\"subject\":\"subject entity name\",\"predicate\":\"relation key\",\"object\":\"object entity name\",\n\
+ {{\"entities\":[{{\"local_id\":\"e1\",\"name\":\"entity name\",\"type\":\"type key\",\"specific_type\":\"what you would call it\"}}],\n\
+ \"facts\":[{{\"subject\":\"subject entity name\",\"subject_ref\":\"e1\",\"predicate\":\"relation key\",\"object\":\"object entity name\",\"object_ref\":\"e2\",\n\
\"valid_from\":\"2023-01\",\"valid_to\":null,\"confidence\":0.9,\"quote\":\"verbatim supporting quote\"}}]}}\n\
\n\
Rules:\n\
- 1. Use the canonical full name as written in the text, in the text's original language; \
+ 1. Give every newly listed entity a local_id unique within this response (e1, e2, ...). \
+ A local_id may define at most one entity. Reuse the same local_id when this response \
+ mentions the same entity again, including abbreviations; never allocate a new handle \
+ merely because a mention repeats. Different handles mean the mentions should be \
+ tracked separately for attribution, not that their permanent identity is proven. \
+ When the text clearly describes two different entities with the same surface name, \
+ list both under different local_ids. A shared name alone neither proves sameness nor \
+ requires a split.\n\
+ 1a. Use the canonical full name as written in the text, in the text's original language; \
list each entity once. Text introduces a full name and then shortens it — \
\"星云科技上海研究院\" becomes \"上海研究院\", \"Nebula Technologies Inc.\" becomes \
\"Nebula\" — and both forms mean one entity, listed once under the fuller form. \
Two names are two entities only when the text is talking about two things.\n\
- 2. Every fact's subject/object must appear in entities.\n\
+ 2. Every fact keeps its name fields and uses subject_ref; relation facts also use \
+ object_ref. Each ref must be either a local_id defined exactly once in \
+ entities or a known handle supplied with this text. An entity referenced by a known \
+ handle must not be copied into entities.\n\
3. Dates must be \"YYYY\", \"YYYY-MM\", \"YYYY-MM-DD\", or null — never invent dates.\n\
3a. valid_to takes a third value: \"unknown\". Use it when the text says the relation \
has ended but does not say when — \"former CEO of X\", \"stepped down\", \"left the \
@@ -275,37 +303,35 @@ const KNOWN_BUDGET_CHARS: usize = 1200;
/// 真正会打碎缓存的是把它塞在**中间**(本体之后、规则之前),那会把规则挤出前缀。
/// 缓存本身不归我们管——供应商开不开、报不报都由它,本部署实测 `cached=0`——
/// 我们只负责别把它弄碎。自部署 vLLM 默认开着自动前缀缓存,那省的是算力不是钱。
-fn known_block(known: &[(String, String)]) -> String {
+fn known_block(known: &[KnownEntity]) -> String {
if known.is_empty() {
return String::new();
}
- // 按类型分组:更紧凑,而且顺带压住跨块类型漂移
- //(同一个"沧海"在一块里是 product、另一块里是 project)
- let mut by_type: Vec<(&str, Vec<&str>)> = Vec::new();
+ let mut lines = Vec::new();
let mut used = 0usize;
- for (type_key, name) in known {
- used += name.chars().count() + 2;
+ for entity in known {
+ used += entity.handle.chars().count()
+ + entity.type_key.chars().count()
+ + entity.name.chars().count()
+ + 6;
if used > KNOWN_BUDGET_CHARS {
break;
}
- match by_type.iter_mut().find(|(k, _)| *k == type_key.as_str()) {
- Some((_, names)) => names.push(name),
- None => by_type.push((type_key, vec![name])),
- }
+ lines.push(format!(
+ " {} [{}]: {}",
+ entity.handle, entity.type_key, entity.name
+ ));
}
- if by_type.is_empty() {
+ if lines.is_empty() {
return String::new();
}
- let lines = by_type
- .iter()
- .map(|(k, names)| format!(" {k}: {}", names.join(", ")))
- .collect::<Vec<_>>()
- .join("\n");
+ let lines = lines.join("\n");
format!(
"\nAlready recorded from earlier parts of this same document:\n{lines}\n\
\n\
- If something in the text below refers to one of these, write that exact string as \
- the name, and give it that same type — documents abbreviate after first mention \
+ If something in the text below refers to one of these, use its k-handle in the fact's \
+ subject_ref/object_ref, write that exact string as the name, and give it that same \
+ type — documents abbreviate after first mention \
(\"星云科技上海研究院\" later becomes \"上海研究院\"), and the shortened form must \
not become a second entity. If it is a different thing, name it as the text does; \
do not force it onto this list.\n"
@@ -429,8 +455,30 @@ pub fn parse_response(raw: &str) -> anyhow::Result<Extraction> {
(out, skipped)
}
- let (entities, skipped_entities) = take::<ExtractedEntity>(&value, "entities");
+ let (mut entities, mut skipped_entities) = take::<ExtractedEntity>(&value, "entities");
let (facts, skipped_facts) = take::<ExtractedFact>(&value, "facts");
+
+ // A handle identifies exactly one entity definition within one response. Reject every
+ // definition participating in a duplicate (including identical duplicates): keeping the
+ // first or last would make fact attribution depend on array order. Empty handles are
+ // malformed too; legacy output is represented by an absent field, not an empty id.
+ let mut handle_counts = std::collections::HashMap::<String, usize>::new();
+ for entity in &entities {
+ if let Some(handle) = entity.local_id.as_deref() {
+ *handle_counts.entry(handle.trim().to_string()).or_default() += 1;
+ }
+ }
+ entities.retain(|entity| match entity.local_id.as_deref() {
+ None => true,
+ Some(handle) => {
+ let handle = handle.trim();
+ let valid = !handle.is_empty() && handle_counts.get(handle) == Some(&1);
+ if !valid {
+ skipped_entities += 1;
+ }
+ valid
+ }
+ });
Ok(Extraction {
entities,
facts,
@@ -693,17 +741,18 @@ mod prompt_shape_tests {
fn known_entities_stay_out_of_the_system_message() {
// 用一个规则 1 的例子里没有的名字:规则 1 也提"星云科技上海研究院",
// 拿它断言等于测不出清单到底在哪条消息里
- let known = vec![(
- "organization".to_string(),
- "华瑞集团智能制造研究院".to_string(),
- )];
+ let known = vec![KnownEntity {
+ handle: "k1".into(),
+ type_key: "organization".into(),
+ name: "华瑞集团智能制造研究院".into(),
+ }];
let msgs = build_messages(&[], &[], &[], None, "a.txt", &known, "text");
assert_eq!(msgs[0].role, "system");
assert!(!msgs[0].content.contains("Already recorded"));
assert!(!msgs[0].content.contains("华瑞集团智能制造研究院"));
assert!(msgs[1]
.content
- .contains("organization: 华瑞集团智能制造研究院"));
+ .contains("k1 [organization]: 华瑞集团智能制造研究院"));
}
/// 第一块没有"前面",那一段应当完全不出现——成本为零,而不是一段空标题
@@ -716,7 +765,11 @@ mod prompt_shape_tests {
/// 反向护栏必须在:给了参照物就会有人硬套(`concept` 那次的教训)
#[test]
fn the_block_tells_the_model_not_to_force_a_match() {
- let known = vec![("person".to_string(), "陈立".to_string())];
+ let known = vec![KnownEntity {
+ handle: "k1".into(),
+ type_key: "person".into(),
+ name: "陈立".into(),
+ }];
let msgs = build_messages(&[], &[], &[], None, "a.txt", &known, "text");
assert!(msgs[1].content.contains("do not force it onto this list"));
}
@@ -854,6 +907,43 @@ mod tests {
assert_eq!(e.entities[0].type_key, "person");
}
+ #[test]
+ fn handles_and_fact_refs_are_optional_and_legacy_compatible() {
+ let handled = parse_response(
+ r#"{"entities":[{"local_id":"e1","name":"Zhang Wei","type":"person"}],
+ "facts":[{"subject":"Zhang Wei","subject_ref":"e1","predicate":"leads",
+ "object":"Finance","object_ref":"e2"}]}"#,
+ )
+ .unwrap();
+ assert_eq!(handled.entities[0].local_id.as_deref(), Some("e1"));
+ assert_eq!(handled.facts[0].subject_ref.as_deref(), Some("e1"));
+ assert_eq!(handled.facts[0].object_ref.as_deref(), Some("e2"));
+
+ let legacy = parse_response(
+ r#"{"entities":[{"name":"Zhang Wei","type":"person"}],
+ "facts":[{"subject":"Zhang Wei","predicate":"leads","object":"Finance"}]}"#,
+ )
+ .unwrap();
+ assert_eq!(legacy.entities[0].local_id, None);
+ assert_eq!(legacy.facts[0].subject_ref, None);
+ assert_eq!(legacy.facts[0].object_ref, None);
+ }
+
+ #[test]
+ fn duplicate_handle_definitions_are_all_malformed() {
+ let x = parse_response(
+ r#"{"entities":[
+ {"local_id":"e1","name":"Zhang Wei","type":"person"},
+ {"local_id":"e1","name":"John Smith","type":"person"},
+ {"local_id":"e2","name":"Finance","type":"organization"}],
+ "facts":[]}"#,
+ )
+ .unwrap();
+ assert_eq!(x.skipped_entities, 2);
+ assert_eq!(x.entities.len(), 1);
+ assert_eq!(x.entities[0].local_id.as_deref(), Some("e2"));
+ }
+
/// specific_type 在骨架里、也在规则里,且两处都说"永远要填"。
///
/// 只写进骨架是不够的:**规则与骨架冲突时骨架赢**(语言那条就栽过一次)。
@@ -869,4 +959,37 @@ mod tests {
// 与 type 的关系必须说清楚,否则模型会把粗类抄一遍
assert!(sys.contains("narrower than"));
}
+
+ #[test]
+ fn extraction_contract_explains_handle_identity_without_forcing_splits() {
+ let msgs = build_messages(&[], &[], &[], None, "a.txt", &[], "text");
+ let system = &msgs[0].content;
+ assert!(system.contains("\"local_id\":\"e1\""));
+ assert!(system.contains("\"subject_ref\":\"e1\""));
+ assert!(system.contains("unique within this response"));
+ assert!(system.contains("Reuse the same local_id"));
+ assert!(system.contains("permanent identity is proven"));
+ assert!(system.contains("A shared name alone neither proves sameness nor requires a split"));
+ }
+
+ #[test]
+ fn same_name_known_entities_keep_distinct_response_handles() {
+ let known = vec![
+ KnownEntity {
+ handle: "k1".into(),
+ type_key: "person".into(),
+ name: "Zhang Wei".into(),
+ },
+ KnownEntity {
+ handle: "k2".into(),
+ type_key: "person".into(),
+ name: "Zhang Wei".into(),
+ },
+ ];
+ let msgs = build_messages(&[], &[], &[], None, "a.txt", &known, "text");
+ let user = &msgs[1].content;
+ assert!(user.contains("k1 [person]: Zhang Wei"));
+ assert!(user.contains("k2 [person]: Zhang Wei"));
+ assert!(user.contains("subject_ref/object_ref"));
+ }
}
diff --git a/crates/utopia-server/src/extraction.rs b/crates/utopia-server/src/extraction.rs
index 93dd141e..7888d9f1 100644
--- a/crates/utopia-server/src/extraction.rs
+++ b/crates/utopia-server/src/extraction.rs
@@ -5,6 +5,7 @@
use crate::llm_util;
use crate::predicate_match::PredicateIndex;
use crate::state::AppState;
+use sqlx::PgPool;
use std::collections::{HashMap, HashSet};
use std::time::Duration;
use uuid::Uuid;
@@ -311,7 +312,7 @@ pub async fn extract_document(
/// mention → 实体 id。同一文档内同名同类型直接复用(单文档语境里罕有同名不同人,
/// 也把消解调用摊薄到每个名字一次);跨文档歧义由 resolve_mention 的画像比对处理。
async fn resolve(
- state: &AppState,
+ pool: &PgPool,
kb_id: Uuid,
// None = 模型给的类型不在本体里,或这个库根本还没有类(0009)
type_id: Option<Uuid>,
@@ -327,25 +328,218 @@ async fn resolve(
if let Some(id) = doc_cache.get(&key) {
return Ok(*id);
}
+ let id = resolve_uncached(pool, kb_id, type_id, name, ctx, &[], needs_adjudication).await?;
+ doc_cache.insert(key, id);
+ Ok(id)
+}
+
+/// Resolve without the document's name cache. Handles use this path so two identities claimed
+/// separately in one response cannot collapse before their fact refs are bound.
+async fn resolve_uncached(
+ pool: &PgPool,
+ kb_id: Uuid,
+ type_id: Option<Uuid>,
+ name: &str,
+ ctx: Option<&[f32]>,
+ exclude: &[Uuid],
+ needs_adjudication: &mut bool,
+) -> anyhow::Result<Uuid> {
let r =
- utopia_store::resolution::resolve_mention(&state.pool, kb_id, type_id, name, ctx).await?;
+ utopia_store::resolution::resolve_mention(pool, kb_id, type_id, name, ctx, exclude).await?;
// 疑似重复对(同名灰区 / 类型漂移)入审核队列,攒批裁决任务收尾统一触发
for review in &r.reviews {
utopia_store::resolution::create_review(
- &state.pool,
+ pool,
kb_id,
r.entity_id,
review.other_id,
review.score,
&review.reason,
+ utopia_store::resolution::ReviewStage::Adjudicating,
)
.await?;
*needs_adjudication = true;
}
- doc_cache.insert(key, r.entity_id);
Ok(r.entity_id)
}
+async fn create_namesake_reviews(
+ pool: &PgPool,
+ kb_id: Uuid,
+ entity_id: Uuid,
+ others: &[Uuid],
+) -> anyhow::Result<bool> {
+ let mut created = false;
+ for other_id in others.iter().copied().filter(|id| *id != entity_id) {
+ utopia_store::resolution::create_review(
+ pool,
+ kb_id,
+ entity_id,
+ other_id,
+ 1.0,
+ "namesake",
+ utopia_store::resolution::ReviewStage::Human,
+ )
+ .await?;
+ created = true;
+ }
+ Ok(created)
+}
+
+#[derive(Clone, Copy)]
+struct BoundEntity {
+ id: Uuid,
+ type_id: Option<Uuid>,
+}
+
+fn referenced_entity(
+ ref_entities: &HashMap<String, BoundEntity>,
+ reference: &str,
+) -> Option<BoundEntity> {
+ ref_entities.get(reference.trim()).copied()
+}
+
+#[derive(Debug, PartialEq, Eq)]
+enum NoRefNameBinding {
+ Legacy(Uuid),
+ AmbiguousHandled,
+ Missing,
+}
+
+fn no_ref_name_binding(
+ entity_ids: &HashMap<String, Uuid>,
+ handled_by_name: &HashMap<String, Vec<Uuid>>,
+ name: &str,
+) -> NoRefNameBinding {
+ let normalized = utopia_store::resolution::normalize_name(name).to_lowercase();
+ if handled_by_name
+ .get(&normalized)
+ .is_some_and(|ids| ids.len() > 1)
+ {
+ NoRefNameBinding::AmbiguousHandled
+ } else {
+ entity_ids
+ .get(name)
+ .copied()
+ .map(NoRefNameBinding::Legacy)
+ .unwrap_or(NoRefNameBinding::Missing)
+ }
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn resolve_handle(
+ pool: &PgPool,
+ kb_id: Uuid,
+ type_id: Option<Uuid>,
+ name: &str,
+ ctx: Option<&[f32]>,
+ response_claims: &mut HashMap<String, Vec<Uuid>>,
+ handled_by_name: &mut HashMap<String, Vec<Uuid>>,
+ ambiguous_bare_cache: &mut HashMap<String, Uuid>,
+ needs_adjudication: &mut bool,
+ human_reviews_found: &mut bool,
+) -> anyhow::Result<Uuid> {
+ let normalized = utopia_store::resolution::normalize_name(name).to_lowercase();
+ let response_excluded = response_claims
+ .get(&normalized)
+ .cloned()
+ .unwrap_or_default();
+ let document_excluded = handled_by_name
+ .get(&normalized)
+ .filter(|ids| ids.len() > 1)
+ .cloned()
+ .unwrap_or_default();
+ let mut excluded = response_excluded.clone();
+ for id in &document_excluded {
+ if !excluded.contains(id) {
+ excluded.push(*id);
+ }
+ }
+ // A later response may allocate a fresh e-handle for an otherwise bare ambiguous name
+ // instead of choosing one of the supplied k-handles. That must still become/reuse C; a new
+ // response-local spelling is not permission to guess A or B.
+ let reuse_document_provisional = response_excluded.is_empty() && document_excluded.len() > 1;
+ let id = match reuse_document_provisional
+ .then(|| ambiguous_bare_cache.get(&normalized).copied())
+ .flatten()
+ {
+ Some(id) => id,
+ None => {
+ let id = resolve_uncached(
+ pool,
+ kb_id,
+ type_id,
+ name,
+ ctx,
+ &excluded,
+ needs_adjudication,
+ )
+ .await?;
+ if reuse_document_provisional {
+ ambiguous_bare_cache.insert(normalized.clone(), id);
+ }
+ id
+ }
+ };
+ if create_namesake_reviews(pool, kb_id, id, &excluded).await? {
+ *human_reviews_found = true;
+ }
+ response_claims
+ .entry(normalized.clone())
+ .or_default()
+ .push(id);
+ let document_claims = handled_by_name.entry(normalized).or_default();
+ if !document_claims.contains(&id) {
+ document_claims.push(id);
+ }
+ Ok(id)
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn resolve_bare(
+ pool: &PgPool,
+ kb_id: Uuid,
+ type_id: Option<Uuid>,
+ name: &str,
+ ctx: Option<&[f32]>,
+ doc_cache: &mut HashMap<(Option<Uuid>, String), Uuid>,
+ handled_by_name: &HashMap<String, Vec<Uuid>>,
+ ambiguous_bare_cache: &mut HashMap<String, Uuid>,
+ needs_adjudication: &mut bool,
+ human_reviews_found: &mut bool,
+) -> anyhow::Result<Uuid> {
+ let normalized = utopia_store::resolution::normalize_name(name).to_lowercase();
+ let claims = handled_by_name
+ .get(&normalized)
+ .filter(|ids| ids.len() > 1)
+ .cloned();
+ let Some(claims) = claims else {
+ return resolve(
+ pool,
+ kb_id,
+ type_id,
+ name,
+ ctx,
+ doc_cache,
+ needs_adjudication,
+ )
+ .await;
+ };
+ if let Some(id) = ambiguous_bare_cache.get(&normalized) {
+ return Ok(*id);
+ }
+
+ // The text supplies no evidence for choosing among the handled namesakes. Preserve the
+ // fact on one document-scoped provisional entity and expose every possible identity link
+ // to a person. Subsequent bare mentions in this document reuse this provisional entity.
+ let id = resolve_uncached(pool, kb_id, type_id, name, ctx, &claims, needs_adjudication).await?;
+ if create_namesake_reviews(pool, kb_id, id, &claims).await? {
+ *human_reviews_found = true;
+ }
+ ambiguous_bare_cache.insert(normalized, id);
+ Ok(id)
+}
+
async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) -> anyhow::Result<()> {
let doc = utopia_store::documents::get(&state.pool, document_id).await?;
// 排队之后被删了(#268):墓碑不抽——抽出来的事实会活在一个已删除的出处上
@@ -473,6 +667,12 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
let chunks = utopia_store::documents::chunks_for_extraction(&state.pool, document_id).await?;
let mut doc_cache: HashMap<(Option<Uuid>, String), Uuid> = HashMap::new();
+ // Identities introduced through handles, grouped only for detecting document-local
+ // namesake ambiguity. A later bare mention gets its own provisional entity instead of
+ // guessing among this group.
+ let mut handled_by_name: HashMap<String, Vec<Uuid>> = HashMap::new();
+ let mut ambiguous_bare_cache: HashMap<String, Uuid> = HashMap::new();
+ let mut touched_names: HashSet<String> = HashSet::new();
// 本文档已经认下的实体,按首次出现排序,送进后续分块的提示词。
//
// **按 entity_id 去重,不按名字**:第 3 块写"上海研究院"若消解到了第 1 块的
@@ -482,6 +682,7 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
// 整块没抽成的:(seq, 原因)。收尾时据此拒绝把这篇文档标成 done
let mut unextracted: Vec<(i32, String)> = Vec::new();
let mut needs_adjudication = false;
+ let mut human_reviews_found = false;
let mut conflicts_found = false;
let mut fact_count = 0usize;
// 不设分块上限:静默截断等于丢知识,长文档的成本由部署者自己权衡
@@ -509,9 +710,14 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
None
};
let lists = lists.as_ref().unwrap_or(&full);
- let known: Vec<(String, String)> = doc_entities
+ let known: Vec<utopia_extract::KnownEntity> = doc_entities
.iter()
- .map(|(_, k, n)| (k.clone(), n.clone()))
+ .enumerate()
+ .map(|(index, (_, type_key, name))| utopia_extract::KnownEntity {
+ handle: format!("k{}", index + 1),
+ type_key: type_key.clone(),
+ name: name.clone(),
+ })
.collect();
let messages = utopia_extract::build_messages(
&lists.types,
@@ -580,7 +786,29 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
let mut entity_ids: HashMap<String, Uuid> = HashMap::new();
// 名称 → 声明类型(属性 domain 校验用:salary 不能挂在 Organization 上)
let mut entity_type_of: HashMap<String, Option<Uuid>> = HashMap::new();
- for e in &extraction.entities {
+ let mut ref_entities: HashMap<String, BoundEntity> = doc_entities
+ .iter()
+ .enumerate()
+ .map(|(index, (id, type_key, _))| {
+ (
+ format!("k{}", index + 1),
+ BoundEntity {
+ id: *id,
+ type_id: type_ids.get(type_key.as_str()).copied(),
+ },
+ )
+ })
+ .collect();
+ let mut response_claims: HashMap<String, Vec<Uuid>> = HashMap::new();
+
+ // Resolve handled definitions first. This matters for a mixed response: a later
+ // handle-less same-name item must see the ambiguity rather than winning by array order.
+ for e in extraction
+ .entities
+ .iter()
+ .filter(|e| e.local_id.is_some())
+ .chain(extraction.entities.iter().filter(|e| e.local_id.is_none()))
+ {
let name = e.name.trim();
if !is_entity_name(name) {
// 从前这里是静默 `continue`——正是 `drop_signal` 当初为之而建的
@@ -608,6 +836,20 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
)
.await;
}
+ if let Some(handle) = e.local_id.as_deref().map(str::trim) {
+ if ref_entities.contains_key(handle) {
+ drop_signal(
+ state,
+ doc.kb_id,
+ document_id,
+ utopia_store::extraction_drops::reason::MALFORMED_ITEM,
+ "local_id collides with a known handle",
+ Some(handle),
+ )
+ .await;
+ continue;
+ }
+ }
// 降级时记住模型提议的那个词:本体装不下不等于它说错了。
// 只留计数的话,日后想加 model 类就找不出那 43 个实体——它们混在
// concept 里面,唯一的出路是整库重抽
@@ -632,16 +874,40 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
None
}
};
- let id = resolve(
- state,
- doc.kb_id,
- type_id,
- name,
- ctx,
- &mut doc_cache,
- &mut needs_adjudication,
- )
- .await?;
+ let normalized = utopia_store::resolution::normalize_name(name).to_lowercase();
+ touched_names.insert(normalized.clone());
+ let id = if let Some(handle) = e.local_id.as_deref() {
+ let handle = handle.trim();
+ let id = resolve_handle(
+ &state.pool,
+ doc.kb_id,
+ type_id,
+ name,
+ ctx,
+ &mut response_claims,
+ &mut handled_by_name,
+ &mut ambiguous_bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews_found,
+ )
+ .await?;
+ ref_entities.insert(handle.to_string(), BoundEntity { id, type_id });
+ id
+ } else {
+ resolve_bare(
+ &state.pool,
+ doc.kb_id,
+ type_id,
+ name,
+ ctx,
+ &mut doc_cache,
+ &handled_by_name,
+ &mut ambiguous_bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews_found,
+ )
+ .await?
+ };
if let Some(p) = proposed {
let _ = utopia_store::resolution::set_proposed_type(&state.pool, id, p).await;
}
@@ -670,6 +936,9 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
.unwrap_or("?");
doc_entities.push((id, tk.to_string(), name.to_string()));
}
+ // Legacy name maps retain their old last-write-wins behavior. Handled facts bind
+ // through ref_entities; inserting handled definitions here only supports mixed
+ // model output when the surface name is unambiguous.
entity_ids.insert(name.to_string(), id);
entity_type_of.insert(name.to_string(), type_id);
}
@@ -724,17 +993,55 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
// 主语没在 entities 里声明:类型不明,domain 无从校验,属性不落。
// 关系路径遇到同样的缺失会兜底按 concept 消解——这里学不来,
// 按 concept 解出来 domain 照样不匹配,只是从这里掉进下面那一档
- let Some((&subject_id, &subject_type)) = entity_ids
- .get(subject_name)
- .zip(entity_type_of.get(subject_name))
+ let bound = match f.subject_ref.as_deref().map(str::trim) {
+ Some(handle) => referenced_entity(&ref_entities, handle),
+ None => {
+ match no_ref_name_binding(&entity_ids, &handled_by_name, subject_name) {
+ NoRefNameBinding::Legacy(id) => entity_type_of
+ .get(subject_name)
+ .copied()
+ .map(|type_id| BoundEntity { id, type_id }),
+ NoRefNameBinding::Missing => None,
+ NoRefNameBinding::AmbiguousHandled => {
+ let type_id = entity_type_of.get(subject_name).copied().flatten();
+ touched_names.insert(
+ utopia_store::resolution::normalize_name(subject_name)
+ .to_lowercase(),
+ );
+ let id = resolve_bare(
+ &state.pool,
+ doc.kb_id,
+ type_id,
+ subject_name,
+ ctx,
+ &mut doc_cache,
+ &handled_by_name,
+ &mut ambiguous_bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews_found,
+ )
+ .await?;
+ Some(BoundEntity { id, type_id })
+ }
+ }
+ }
+ };
+ let Some(BoundEntity {
+ id: subject_id,
+ type_id: subject_type,
+ }) = bound
else {
drop_signal(
state,
doc.kb_id,
document_id,
- utopia_store::extraction_drops::reason::SUBJECT_NOT_DECLARED,
+ if f.subject_ref.is_some() {
+ utopia_store::extraction_drops::reason::MALFORMED_ITEM
+ } else {
+ utopia_store::extraction_drops::reason::SUBJECT_NOT_DECLARED
+ },
&attr.key,
- Some(subject_name),
+ Some(f.subject_ref.as_deref().unwrap_or(subject_name)),
)
.await;
continue;
@@ -1034,35 +1341,84 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
// 主宾未在 entities 中声明时先建出来(模型偶尔漏报)。没有 entities 那条
// 记录就没有类型可依,留空即可——0009 之前这里只能塞 concept
- let subject_id = match entity_ids.get(f.subject.trim()) {
- Some(id) => *id,
+ let subject_id = match f.subject_ref.as_deref().map(str::trim) {
+ Some(handle) => match referenced_entity(&ref_entities, handle) {
+ Some(bound) => bound.id,
+ None => {
+ drop_signal(
+ state,
+ doc.kb_id,
+ document_id,
+ utopia_store::extraction_drops::reason::MALFORMED_ITEM,
+ &f.predicate,
+ Some(handle),
+ )
+ .await;
+ continue;
+ }
+ },
None => {
- resolve(
- state,
- doc.kb_id,
- None,
- f.subject.trim(),
- ctx,
- &mut doc_cache,
- &mut needs_adjudication,
- )
- .await?
+ match no_ref_name_binding(&entity_ids, &handled_by_name, f.subject.trim()) {
+ NoRefNameBinding::Legacy(id) => id,
+ NoRefNameBinding::AmbiguousHandled | NoRefNameBinding::Missing => {
+ touched_names.insert(
+ utopia_store::resolution::normalize_name(f.subject.trim())
+ .to_lowercase(),
+ );
+ resolve_bare(
+ &state.pool,
+ doc.kb_id,
+ None,
+ f.subject.trim(),
+ ctx,
+ &mut doc_cache,
+ &handled_by_name,
+ &mut ambiguous_bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews_found,
+ )
+ .await?
+ }
+ }
}
};
- let object_id = match entity_ids.get(object_name) {
- Some(id) => *id,
- None => {
- resolve(
- state,
- doc.kb_id,
- None,
- object_name,
- ctx,
- &mut doc_cache,
- &mut needs_adjudication,
- )
- .await?
- }
+ let object_id = match f.object_ref.as_deref().map(str::trim) {
+ Some(handle) => match referenced_entity(&ref_entities, handle) {
+ Some(bound) => bound.id,
+ None => {
+ drop_signal(
+ state,
+ doc.kb_id,
+ document_id,
+ utopia_store::extraction_drops::reason::MALFORMED_ITEM,
+ &f.predicate,
+ Some(handle),
+ )
+ .await;
+ continue;
+ }
+ },
+ None => match no_ref_name_binding(&entity_ids, &handled_by_name, object_name) {
+ NoRefNameBinding::Legacy(id) => id,
+ NoRefNameBinding::AmbiguousHandled | NoRefNameBinding::Missing => {
+ touched_names.insert(
+ utopia_store::resolution::normalize_name(object_name).to_lowercase(),
+ );
+ resolve_bare(
+ &state.pool,
+ doc.kb_id,
+ None,
+ object_name,
+ ctx,
+ &mut doc_cache,
+ &handled_by_name,
+ &mut ambiguous_bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews_found,
+ )
+ .await?
+ }
+ },
};
if subject_id == object_id {
continue;
@@ -1286,9 +1642,8 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
}
// 消歧后缀在实体创建时算会早于其事实写入——收尾时对本文档涉及的名字统一刷新
- let names: std::collections::HashSet<&str> =
- doc_cache.keys().map(|(_, name)| name.as_str()).collect();
- for name in names {
+ touched_names.extend(doc_cache.keys().map(|(_, name)| name.clone()));
+ for name in &touched_names {
utopia_store::resolution::refresh_disambiguators(&state.pool, doc.kb_id, name).await?;
}
@@ -1358,7 +1713,7 @@ async fn run(state: &AppState, document_id: Uuid, proposed_by: Option<Uuid>) ->
)
.await?;
}
- if needs_adjudication || conflicts_found {
+ if needs_adjudication || human_reviews_found || conflicts_found {
state.emit_review(doc.kb_id);
}
// 类型消解排队自动跑(0016 C2):开关开着就排一个库级任务,同库已排着的不重复。
@@ -1725,7 +2080,12 @@ mod name_tests {
#[cfg(test)]
mod tests {
- use super::{incomplete_reason, looks_literal};
+ use super::{
+ incomplete_reason, looks_literal, no_ref_name_binding, referenced_entity, resolve_bare,
+ resolve_handle, BoundEntity, NoRefNameBinding,
+ };
+ use std::collections::HashMap;
+ use uuid::Uuid;
#[test]
fn only_numbers_and_dates_count_as_literals() {
@@ -1748,6 +2108,34 @@ mod tests {
}
}
+ #[test]
+ fn no_ref_names_bypass_legacy_map_only_after_two_handle_claims() {
+ let (a, b) = (Uuid::now_v7(), Uuid::now_v7());
+ let entity_ids = HashMap::from([("Zhang Wei".to_string(), b)]);
+ let normalized = utopia_store::resolution::normalize_name("Zhang Wei").to_lowercase();
+
+ assert_eq!(
+ no_ref_name_binding(&entity_ids, &HashMap::new(), "Zhang Wei"),
+ NoRefNameBinding::Legacy(b)
+ );
+ assert_eq!(
+ no_ref_name_binding(
+ &entity_ids,
+ &HashMap::from([(normalized.clone(), vec![a])]),
+ "Zhang Wei",
+ ),
+ NoRefNameBinding::Legacy(b)
+ );
+ assert_eq!(
+ no_ref_name_binding(
+ &entity_ids,
+ &HashMap::from([(normalized, vec![a, b])]),
+ "Zhang Wei",
+ ),
+ NoRefNameBinding::AmbiguousHandled
+ );
+ }
+
/// 这条判据存在的理由:一次网络抖动让六篇文档 60 块里只抽成 12 块,
/// 六篇**全部显示"抽取完成"**,八成的内容没进图,界面上没有任何东西说出来。
#[test]
@@ -1777,4 +2165,279 @@ mod tests {
let msg = incomplete_reason(&[(2, "x".into())], 3).unwrap();
assert!(msg.starts_with("本轮 3 个分块"), "{msg}");
}
+
+ #[tokio::test]
+ async fn namesake_handles_keep_fact_attribution_and_bare_mentions_get_c() -> anyhow::Result<()>
+ {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = sqlx::PgPool::connect(&url).await?;
+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'handle-runtime-test')")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'handle-runtime-test')",
+ )
+ .bind(ws)
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'handle-runtime-test')",
+ )
+ .bind(kb)
+ .bind(ws)
+ .execute(&pool)
+ .await?;
+ let person = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'person', 'Person')",
+ )
+ .bind(person)
+ .bind(kb)
+ .execute(&pool)
+ .await?;
+
+ let run = async {
+ let mut legacy_cache = HashMap::new();
+ let mut legacy_needs_adjudication = false;
+ let legacy_first = super::resolve(
+ &pool,
+ kb,
+ Some(person),
+ "Alice",
+ None,
+ &mut legacy_cache,
+ &mut legacy_needs_adjudication,
+ )
+ .await?;
+ let legacy_second = super::resolve(
+ &pool,
+ kb,
+ Some(person),
+ "Alice",
+ None,
+ &mut legacy_cache,
+ &mut legacy_needs_adjudication,
+ )
+ .await?;
+ assert_eq!(legacy_first, legacy_second, "legacy name cache is unchanged");
+
+ let mut response_claims = HashMap::new();
+ let mut document_claims = HashMap::new();
+ let mut bare_cache = HashMap::new();
+ let (mut needs_adjudication, mut human_reviews) = (false, false);
+ let a = resolve_handle(
+ &pool,
+ kb,
+ Some(person),
+ "Zhang Wei",
+ None,
+ &mut response_claims,
+ &mut document_claims,
+ &mut bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews,
+ )
+ .await?;
+ let b = resolve_handle(
+ &pool,
+ kb,
+ Some(person),
+ "Zhang Wei",
+ None,
+ &mut response_claims,
+ &mut document_claims,
+ &mut bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews,
+ )
+ .await?;
+ assert_ne!(a, b);
+ assert!(human_reviews);
+ assert!(
+ !needs_adjudication,
+ "namesakes must not wake the LLM worker"
+ );
+
+ let refs = HashMap::from([
+ (
+ "e1".to_string(),
+ BoundEntity {
+ id: a,
+ type_id: Some(person),
+ },
+ ),
+ (
+ "e2".to_string(),
+ BoundEntity {
+ id: b,
+ type_id: Some(person),
+ },
+ ),
+ ]);
+ assert_eq!(referenced_entity(&refs, "e1").map(|x| x.id), Some(a));
+ assert_eq!(referenced_entity(&refs, "e2").map(|x| x.id), Some(b));
+ assert!(referenced_entity(&refs, "missing").is_none());
+ let (finance, platform) = (Uuid::now_v7(), Uuid::now_v7());
+ let works_at = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO relation_types (id, kb_id, key, label) VALUES ($1, $2, 'works_at', 'works at')",
+ )
+ .bind(works_at)
+ .bind(kb)
+ .execute(&pool)
+ .await?;
+ for (id, name) in [(finance, "Finance"), (platform, "Platform Engineering")] {
+ sqlx::query("INSERT INTO entities (id, kb_id, canonical_name) VALUES ($1, $2, $3)")
+ .bind(id)
+ .bind(kb)
+ .bind(name)
+ .execute(&pool)
+ .await?;
+ }
+ for (handle, object) in [("e1", finance), ("e2", platform)] {
+ let subject = referenced_entity(&refs, handle).expect("valid ref").id;
+ utopia_store::graph::insert_fact(
+ &pool,
+ kb,
+ subject,
+ Some(works_at),
+ object,
+ utopia_store::graph::Validity::default(),
+ 0.9,
+ )
+ .await?;
+ }
+ let pairs: Vec<(Uuid, Uuid)> = sqlx::query_as(
+ "SELECT subject_id, object_id FROM facts WHERE kb_id = $1 ORDER BY subject_id",
+ )
+ .bind(kb)
+ .fetch_all(&pool)
+ .await?;
+ assert!(pairs.contains(&(a, finance)));
+ assert!(pairs.contains(&(b, platform)));
+ assert!(!pairs.contains(&(a, platform)));
+ assert!(!pairs.contains(&(b, finance)));
+ utopia_store::resolution::refresh_disambiguators(&pool, kb, "Zhang Wei").await?;
+ let labels: Vec<(Uuid, Option<String>)> = sqlx::query_as(
+ "SELECT id, disambiguator FROM entities WHERE id = ANY($1) ORDER BY id",
+ )
+ .bind(vec![a, b])
+ .fetch_all(&pool)
+ .await?;
+ assert!(labels.contains(&(a, Some("Finance".to_string()))));
+ assert!(labels.contains(&(b, Some("Platform Engineering".to_string()))));
+
+ let mut doc_cache = HashMap::new();
+ // The legacy surface map still ends on B, but a no-ref fact must not use that
+ // last-write-wins value once handles have claimed two distinct Zhang Weis.
+ let entity_ids = HashMap::from([("Zhang Wei".to_string(), b)]);
+ assert_eq!(entity_ids.get("Zhang Wei"), Some(&b));
+ assert_eq!(
+ super::no_ref_name_binding(&entity_ids, &document_claims, "Zhang Wei"),
+ super::NoRefNameBinding::AmbiguousHandled
+ );
+ let c = resolve_bare(
+ &pool,
+ kb,
+ Some(person),
+ "Zhang Wei",
+ None,
+ &mut doc_cache,
+ &document_claims,
+ &mut bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews,
+ )
+ .await?;
+ utopia_store::graph::insert_fact(
+ &pool,
+ kb,
+ c,
+ Some(works_at),
+ finance,
+ utopia_store::graph::Validity::default(),
+ 0.9,
+ )
+ .await?;
+ let c_again = resolve_bare(
+ &pool,
+ kb,
+ None,
+ "Zhang Wei",
+ None,
+ &mut doc_cache,
+ &document_claims,
+ &mut bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews,
+ )
+ .await?;
+ utopia_store::graph::insert_fact(
+ &pool,
+ kb,
+ c_again,
+ Some(works_at),
+ platform,
+ utopia_store::graph::Validity::default(),
+ 0.9,
+ )
+ .await?;
+ assert_ne!(c, a);
+ assert_ne!(c, b);
+ assert_eq!(
+ c_again, c,
+ "later bare mentions must reuse document-local C"
+ );
+ let c_objects: Vec<Uuid> = sqlx::query_scalar(
+ "SELECT object_id FROM facts WHERE kb_id = $1 AND subject_id = $2 ORDER BY object_id",
+ )
+ .bind(kb)
+ .bind(c)
+ .fetch_all(&pool)
+ .await?;
+ assert_eq!(c_objects.len(), 2);
+ assert!(c_objects.contains(&finance));
+ assert!(c_objects.contains(&platform));
+ let mut later_response_claims = HashMap::new();
+ let c_via_fresh_handle = resolve_handle(
+ &pool,
+ kb,
+ Some(person),
+ "Zhang Wei",
+ None,
+ &mut later_response_claims,
+ &mut document_claims,
+ &mut bare_cache,
+ &mut needs_adjudication,
+ &mut human_reviews,
+ )
+ .await?;
+ assert_eq!(
+ c_via_fresh_handle, c,
+ "a later response cannot evade A/B ambiguity by inventing a new e-handle"
+ );
+
+ let reviews = utopia_store::resolution::list_reviews(&pool, kb, 10, 0).await?;
+ assert_eq!(reviews.len(), 3, "A/B, C/A and C/B");
+ assert!(reviews.iter().all(|review| review.stage == "human"));
+ assert!(
+ utopia_store::resolution::pending_adjudications(&pool, kb, 10)
+ .await?
+ .is_empty()
+ );
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ let _ = sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(org)
+ .execute(&pool)
+ .await;
+ run
+ }
}
diff --git a/crates/utopia-server/src/mappings.rs b/crates/utopia-server/src/mappings.rs
index ec66432c..755f8912 100644
--- a/crates/utopia-server/src/mappings.rs
+++ b/crates/utopia-server/src/mappings.rs
@@ -167,6 +167,7 @@ pub async fn explore_mappings(state: &AppState, kb_id: Uuid) -> anyhow::Result<(
Some(type_id),
name,
None,
+ &[],
)
.await?;
diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rs
index 6d38a782..774d214a 100644
--- a/crates/utopia-store/src/resolution.rs
+++ b/crates/utopia-store/src/resolution.rs
@@ -197,6 +197,23 @@ pub struct ReviewRequest {
pub reason: String,
}
+/// 审核项由谁消费。普通画像灰区先交给批量裁决器;抽取器在同一回复里明确拆出的
+/// 同名实体只有人能判断,不能让几乎相同的画像触发自动合并。
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ReviewStage {
+ Adjudicating,
+ Human,
+}
+
+impl ReviewStage {
+ fn as_str(self) -> &'static str {
+ match self {
+ Self::Adjudicating => "adjudicating",
+ Self::Human => "human",
+ }
+ }
+}
+
/// 单条 mention 消解。`context` 为 mention 所在分块的向量(无 embedding 模型时为 None,
/// 退化为 v1 行为:同名归并到事实最多的候选)。
pub async fn resolve_mention(
@@ -206,6 +223,9 @@ pub async fn resolve_mention(
type_id: Option<Uuid>,
raw_name: &str,
context: Option<&[f32]>,
+ // Candidates already claimed by a different response-local handle. They remain stored
+ // and recallable on later calls, but this mention cannot attach to them.
+ exclude: &[Uuid],
) -> AppResult<Resolution> {
let name = normalize_name(raw_name);
// 召回键 = 本名 + 泛用后缀词干及其增广("星尘"↔"星尘项目"互为候选)。
@@ -225,12 +245,15 @@ pub async fn resolve_mention(
.bind(type_id)
.bind(&keys)
.fetch_all(pool)
- .await?;
+ .await?
+ .into_iter()
+ .filter(|candidate: &Candidate| !exclude.contains(&candidate.id))
+ .collect();
if candidates.is_empty() {
// 同类型无候选 ≠ 新名字:类型标签会漂(同一团队被抽成 organization/project/
// concept),先查其它类型下的同名实体,按类型对的互斥强度分流。
- return resolve_type_drift(pool, kb_id, type_id, &name, &keys, context).await;
+ return resolve_type_drift(pool, kb_id, type_id, &name, &keys, context, exclude).await;
}
let Some(ctx) = context else {
@@ -582,6 +605,7 @@ async fn resolve_type_drift(
name: &str,
keys: &[String],
context: Option<&[f32]>,
+ exclude: &[Uuid],
) -> AppResult<Resolution> {
// 这一侧也可能还没判出类型(0009),那时没有 key 可查
let mention_key: Option<String> = match type_id {
@@ -606,7 +630,10 @@ async fn resolve_type_drift(
.bind(type_id)
.bind(keys)
.fetch_all(pool)
- .await?;
+ .await?
+ .into_iter()
+ .filter(|candidate: &CrossCandidate| !exclude.contains(&candidate.id))
+ .collect();
// 本体声明了互斥的类,一次取出(含继承)。声明优先于下面所有启发式
let disjoint = declared_disjoint_from(pool, kb_id, type_id).await?;
@@ -848,13 +875,16 @@ pub async fn create_review(
right_id: Uuid,
score: f32,
reason: &str,
+ stage: ReviewStage,
) -> AppResult<()> {
sqlx::query(
- "INSERT INTO resolution_reviews (id, kb_id, left_id, right_id, score, reason)
- VALUES ($1, $2, $3, $4, $5, $6)
+ "INSERT INTO resolution_reviews AS existing
+ (id, kb_id, left_id, right_id, score, reason, stage)
+ VALUES ($1, $2, $3, $4, $5, $6, $7)
ON CONFLICT (kb_id, least(left_id, right_id), greatest(left_id, right_id))
WHERE status = 'pending'
- DO NOTHING",
+ DO UPDATE SET stage = 'human', reason = EXCLUDED.reason
+ WHERE EXCLUDED.stage = 'human' AND existing.stage = 'adjudicating'",
)
.bind(Uuid::now_v7())
.bind(kb_id)
@@ -862,6 +892,7 @@ pub async fn create_review(
.bind(right_id)
.bind(score)
.bind(reason)
+ .bind(stage.as_str())
.execute(pool)
.await?;
Ok(())
diff --git a/crates/utopia-store/tests/a_declared_disjointness_keeps_names_apart.rs b/crates/utopia-store/tests/a_declared_disjointness_keeps_names_apart.rs
index 1d49520b..e93b65ee 100644
--- a/crates/utopia-store/tests/a_declared_disjointness_keeps_names_apart.rs
+++ b/crates/utopia-store/tests/a_declared_disjointness_keeps_names_apart.rs
@@ -113,7 +113,7 @@ async fn drift_reviews(
name: &str,
type_id: Uuid,
) -> anyhow::Result<Vec<Uuid>> {
- let r = resolution::resolve_mention(pool, f.kb, Some(type_id), name, None).await?;
+ let r = resolution::resolve_mention(pool, f.kb, Some(type_id), name, None, &[]).await?;
assert!(
r.created,
"a cross-type same name is a new entity: keep apart, never merge"
diff --git a/crates/utopia-store/tests/human_type_decisions.rs b/crates/utopia-store/tests/human_type_decisions.rs
index be1392de..f51adf9c 100644
--- a/crates/utopia-store/tests/human_type_decisions.rs
+++ b/crates/utopia-store/tests/human_type_decisions.rs
@@ -227,6 +227,7 @@ async fn extraction_does_not_fill_in_a_type_a_human_left_empty() -> anyhow::Resu
Some(f.org_type),
&name,
Some(&ctx),
+ &[],
)
.await?;
}
diff --git a/crates/utopia-store/tests/review_stages.rs b/crates/utopia-store/tests/review_stages.rs
new file mode 100644
index 00000000..c396c670
--- /dev/null
+++ b/crates/utopia-store/tests/review_stages.rs
@@ -0,0 +1,130 @@
+//! 审核阶段是执行边界:human 项必须展示给人,但绝不能被自动裁决器捞走。
+
+use sqlx::PgPool;
+use utopia_store::resolution::{self, ReviewStage};
+use uuid::Uuid;
+
+#[tokio::test]
+async fn human_review_is_visible_but_never_pending_adjudication() -> anyhow::Result<()> {
+ let Some(url) = utopia_store::test_db::url() else {
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let (org, ws, kb, ty, left, right, third, existing) = (
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ Uuid::now_v7(),
+ );
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'review-stage-test')")
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'review-stage-test')")
+ .bind(ws)
+ .bind(org)
+ .execute(&pool)
+ .await?;
+ sqlx::query(
+ "INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'review-stage-test')",
+ )
+ .bind(kb)
+ .bind(ws)
+ .execute(&pool)
+ .await?;
+ sqlx::query("INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'org', 'Org')")
+ .bind(ty)
+ .bind(kb)
+ .execute(&pool)
+ .await?;
+ for (id, name) in [
+ (left, "Zhang Wei"),
+ (right, "Zhang Wei"),
+ (third, "Zhang W."),
+ (existing, "Acme"),
+ ] {
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, type_id, canonical_name) VALUES ($1, $2, $3, $4)",
+ )
+ .bind(id)
+ .bind(kb)
+ .bind(ty)
+ .bind(name)
+ .execute(&pool)
+ .await?;
+ }
+
+ let run = async {
+ let ordinary = resolution::resolve_mention(&pool, kb, Some(ty), "Acme", None, &[]).await?;
+ assert_eq!(ordinary.entity_id, existing);
+ assert!(!ordinary.created, "exclude=[] must retain ordinary recall");
+
+ let split =
+ resolution::resolve_mention(&pool, kb, Some(ty), "Acme", None, &[existing]).await?;
+ assert_ne!(split.entity_id, existing);
+ assert!(split.created, "the excluded candidate cannot be attached");
+ let recalled_split =
+ resolution::resolve_mention(&pool, kb, Some(ty), "Acme", None, &[existing]).await?;
+ assert_eq!(recalled_split.entity_id, split.entity_id);
+ assert!(
+ !recalled_split.created,
+ "re-extraction must reuse the non-excluded candidate"
+ );
+
+ resolution::create_review(&pool, kb, left, right, 1.0, "namesake", ReviewStage::Human)
+ .await?;
+ resolution::create_review(
+ &pool,
+ kb,
+ left,
+ third,
+ 0.42,
+ "ambiguous_name|0.42",
+ ReviewStage::Adjudicating,
+ )
+ .await?;
+
+ let visible = resolution::list_reviews(&pool, kb, 10, 0).await?;
+ assert_eq!(visible.len(), 2);
+ assert!(visible.iter().any(|r| r.stage == "human"));
+ let pending = resolution::pending_adjudications(&pool, kb, 10).await?;
+ assert_eq!(pending.len(), 1);
+ assert_eq!(pending[0].stage, "adjudicating");
+
+ // pending pair 的唯一索引不含 stage。后出现的 namesake 必须把已有行升级为
+ // human;反向的普通请求不得再把它降回自动裁决通道。
+ resolution::create_review(&pool, kb, left, third, 1.0, "namesake", ReviewStage::Human)
+ .await?;
+ resolution::create_review(
+ &pool,
+ kb,
+ left,
+ third,
+ 0.42,
+ "ambiguous_name|0.42",
+ ReviewStage::Adjudicating,
+ )
+ .await?;
+ assert!(resolution::pending_adjudications(&pool, kb, 10)
+ .await?
+ .is_empty());
+ let visible = resolution::list_reviews(&pool, kb, 10, 0).await?;
+ let upgraded = visible.iter().find(|r| {
+ (r.left.id == left && r.right.id == third) || (r.left.id == third && r.right.id == left)
+ });
+ assert_eq!(upgraded.map(|r| r.stage.as_str()), Some("human"));
+ assert_eq!(upgraded.and_then(|r| r.reason.as_deref()), Some("namesake"));
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ let _ = sqlx::query("DELETE FROM organizations WHERE id = $1")
+ .bind(org)
+ .execute(&pool)
+ .await;
+ run
+}