World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-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.rsindex 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.rsindex 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, 原因)。收尾时据此拒绝把这篇文档标成 donelet 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,+ }) = boundelse {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.rsindex 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.rsindex 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.rsindex 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.rsindex 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::ResuSome(f.org_type),&name,Some(&ctx),+ &[],).await?;}diff --git a/crates/utopia-store/tests/review_stages.rs b/crates/utopia-store/tests/review_stages.rsnew file mode 100644index 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+}