World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A kind word binds to a class (#741)
WaylandYangfa6d4e9bf94b
diff --git a/crates/utopia-extract/src/align.rs b/crates/utopia-extract/src/align.rsnew file mode 100644index 00000000..b8cb76b1--- /dev/null+++ b/crates/utopia-extract/src/align.rs@@ -0,0 +1,563 @@+//! 种类词绑定到类(0044 决定 3–4 的第一步):类型化图谱是从开放图谱按签名的绑定算出来的,+//! 而种类词——开放抽取写下的「它是个什么」——是最简单的签名:一个词对一个类,或者+//! 对不上。绑定按库缓存、按词复用,所以代价随不同的说法增长,不随文档增长。+//!+//! 对齐读来源(决定 3):每个词带着文档里见过的拼写、这一类东西的例子(名字)和它们+//! 参与的关系短语进提示词,模型判的是「**每一个**这种东西都是这个类的实例吗」。类可以+//! 比词宽(面包房是组织),不能比词窄、也不能只是沾边(合同不是「文件」,如果类的定义+//! 说文件是一个 file)。角色词、描述词、一词两义都答 null。候选类的定义照库里的写法给+//! (中文或英文都行),答案里的键照抄。+//!+//! 回复是紧凑 JSON:`{"b": [[id, "key" | null]]}`。解析逐项宽容:坏的一对计数、不毁掉+//! 整批;键不在那一项的候选里、id 不在批里、同一个 id 的第二次都算坏;截断的回复退到+//! 最后一个完整的对。没答到的 id 就是没答到——调用方按 id 对账,缺席是「再问」,+//! 不是 null。++use std::collections::{HashMap, HashSet};++use serde_json::Value;+use utopia_llm::ChatMessage;++use crate::{json_block, json_text, open::repair_truncated_compact};++/// 一个候选类:键照抄进答案;标签与定义是模型判断的依据,照库里的语言给+#[derive(Debug, Clone, Copy)]+pub struct ClassCandidate<'a> {+ pub key: &'a str,+ pub label: &'a str,+ pub description: &'a str,+}++/// 一个待绑定的种类词签名:词、它在文档里的样子、这一类东西的例子与短语、候选类+#[derive(Debug, Clone)]+pub struct KindWordItem<'a> {+ pub id: i64,+ /// the normalised kind word ("company")+ pub kind_word: &'a str,+ /// spellings seen in documents ("Company", "company", "公司")+ pub spellings: &'a [String],+ /// example entity names of this kind ("Brightway Builders", "Harbor Estates")+ pub examples: &'a [String],+ /// relation phrases these things are subjects of ("is based in", "was founded by")+ pub phrases: &'a [String],+ pub candidates: Vec<ClassCandidate<'a>>,+}++/// 模型对一项的裁决:Some = 那个候选的键(从候选里抄的,不是模型写的);None = 不绑+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct KindWordChoice {+ pub id: i64,+ pub key: Option<String>,+}++/// 系统消息。例子是中性的(面包房、桥、镇议会),不出自任何测量语料;规则 1 的+/// 「每一个这种东西」是整条路的判据,宽可以、窄不行、沾边不行+const KIND_WORD_SYSTEM: &str = "\+You bind the words documents use for kinds of things to the classes of a knowledge base's \+ontology. Each numbered item is one kind word as the documents wrote it: the word, the \+spellings seen, some things of this kind by name, the phrases those things take part in, and \+the candidate classes, each with its key, its label and its definition. For each item, answer \+with the key of the one candidate class that every thing of this kind is an instance of, or \+null.\n\+\n\+Output exactly one JSON object and nothing else, one pair per item:\n\+{\"b\": [[12, \"organization\"], [13, null]]}\n\+The first element of a pair is the item's id; the second is the chosen key, copied exactly as \+listed under that item, or null.\n\+\n\+1. Choose a candidate only when every thing of this kind is an instance of that class by the \+class's definition. The class may be broader than the word: a bakery is an organization, a \+bridge is a structure. It is never narrower and never merely related: a contract is not a \+document when the definition says a document is a file; a town council is not a town; a \+bakery is not a building because bakeries are in buildings.\n\+2. Judge by the definition as given, not by the label or the key alone. Labels and \+definitions may be written in any language, and so may the kind word; a word in another \+script or language is the same word when it names the same kind.\n\+3. Answer null when no candidate fits; when the word names a role, a part or a description \+rather than a kind of thing (\"participants\", \"results\", \"the northern wing\"); or when the \+examples and phrases show two kinds of thing under one word (a \"bank\" that is a lender in one \+document and a riverbank in another).\n\+4. The spellings, examples and phrases are the evidence of what the word means in these \+documents: things that \"were founded by\" and \"are based in\" are organizations; things that \+\"were signed on\" and \"expire\" are agreements. Read them before the label.\n\+5. Never invent a key, never answer with a label or a word of your own, and never choose for \+an item a key that is not among its candidates. One pair per item, every item answered.";++/// 构造两条消息:常量系统消息 + 逐项的用户消息。每项:id、词、拼写、例子、短语、候选。+/// 空清单写 `(none)`,模型知道那一栏存在但这次没有证据+pub fn build_kind_word_messages(items: &[KindWordItem<'_>]) -> Vec<ChatMessage> {+ let mut user = String::new();+ for item in items {+ let candidates = if item.candidates.is_empty() {+ " (none)".to_string()+ } else {+ let lines: Vec<String> = item.candidates.iter().map(candidate_line).collect();+ format!("\n{}", lines.join("\n"))+ };+ user.push_str(&format!(+ "Item {}: \"{}\"\nSpellings: {}\nExamples: {}\nPhrases: {}\nCandidates:{candidates}\n\n",+ item.id,+ item.kind_word,+ quoted_list(item.spellings),+ quoted_list(item.examples),+ quoted_list(item.phrases),+ ));+ }+ vec![+ ChatMessage {+ role: "system".into(),+ content: KIND_WORD_SYSTEM.to_string(),+ },+ ChatMessage {+ role: "user".into(),+ content: user.trim_end().to_string(),+ },+ ]+}++/// `"a", "b", "c"`;空清单是 `(none)`。带引号是因为名字里可能有逗号+fn quoted_list(values: &[String]) -> String {+ if values.is_empty() {+ return "(none)".to_string();+ }+ values+ .iter()+ .map(|v| format!("\"{}\"", v.trim()))+ .collect::<Vec<_>>()+ .join(", ")+}++/// `- key: label — description`。标签与键相同就不重复;定义为空就不写破折号+fn candidate_line(c: &ClassCandidate<'_>) -> String {+ let key = c.key.trim();+ let mut line = format!("- {key}");+ let label = c.label.trim();+ if !label.is_empty() && label != key {+ line.push_str(&format!(": {label}"));+ }+ let description = c.description.trim();+ if !description.is_empty() {+ line.push_str(&format!(" — {description}"));+ }+ line+}++/// 逐项宽容地解回复。返回(裁决,坏项数)。+///+/// 一对坏在:不是数组、不足两格、id 不是整数、id 不在这批里、键不是 null 也不是+/// 字符串、键不在那一项的候选里、同一个 id 已经答过(留第一次)。键先按原样对候选,+/// 对不上再不分大小写对——对上了写回的是候选自己的键,不是模型写的那个。+/// 截断的回复先退到最后一个完整的对;连一对都没有才报错+pub fn parse_kind_word_response(+ raw: &str,+ items: &[KindWordItem<'_>],+) -> anyhow::Result<(Vec<KindWordChoice>, usize)> {+ let value = parse_value(raw)?;+ let by_id: HashMap<i64, &KindWordItem<'_>> = items.iter().map(|i| (i.id, i)).collect();+ let mut choices = Vec::new();+ let mut malformed = 0usize;+ let mut seen = HashSet::new();+ for pair in pairs(&value) {+ match parse_pair(pair, &by_id) {+ Some(choice) if seen.insert(choice.id) => choices.push(choice),+ _ => malformed += 1,+ }+ }+ Ok((choices, malformed))+}++/// 先按常规取块(第一个 `{` 到最后一个 `}`);解不开才从第一个 `{` 取到结尾去修补。+/// 取块与修补的分工同 `open.rs`:紧凑回复里 `}` 只在结尾出现,截断的回复要么没有 `}`,+/// 要么最后一个 `}` 不是结尾+fn parse_value(raw: &str) -> anyhow::Result<Value> {+ let block = json_block(raw)+ .and_then(|b| serde_json::from_str::<Value>(&b).map_err(anyhow::Error::from));+ match block {+ Ok(v) => Ok(v),+ Err(e) => {+ let text = json_text(raw);+ let fixed = text+ .find('{')+ .map(|s| &text[s..])+ .and_then(repair_truncated_compact)+ .ok_or_else(|| anyhow::anyhow!("Failed to parse kind-word binding JSON: {e}"))?;+ serde_json::from_str::<Value>(&fixed)+ .map_err(|e| anyhow::anyhow!("Failed to parse kind-word binding JSON: {e}"))+ }+ }+}++/// 顶层 `b` 下的数组;缺了或不是数组就当空——那不是坏项,是一项都没答+fn pairs(value: &Value) -> &[Value] {+ value+ .get("b")+ .and_then(Value::as_array)+ .map_or(&[], Vec::as_slice)+}++/// `[id, key | null]`+fn parse_pair(v: &Value, by_id: &HashMap<i64, &KindWordItem<'_>>) -> Option<KindWordChoice> {+ let arr = v.as_array()?;+ if arr.len() < 2 {+ return None;+ }+ let id = item_id(&arr[0])?;+ let item = by_id.get(&id)?;+ let key = match &arr[1] {+ Value::Null => None,+ Value::String(written) => Some(candidate_key(item, written)?),+ _ => return None,+ };+ Some(KindWordChoice { id, key })+}++/// id 是 JSON 整数;模型偶尔把它写成字符串,照数字读+fn item_id(v: &Value) -> Option<i64> {+ match v {+ Value::Number(n) => n.as_i64(),+ Value::String(s) => s.trim().parse().ok(),+ _ => None,+ }+}++/// 模型写的键对回这一项的候选:先原样,再不分大小写(只在唯一命中时);返回的是+/// 候选自己的键。空串与不在候选里的都是 None,由调用方计入坏项+fn candidate_key(item: &KindWordItem<'_>, written: &str) -> Option<String> {+ let written = written.trim();+ if written.is_empty() {+ return None;+ }+ let keys = || item.candidates.iter().map(|c| c.key.trim());+ if let Some(exact) = keys().find(|k| *k == written) {+ return Some(exact.to_string());+ }+ let lower = written.to_lowercase();+ let mut hits = keys().filter(|k| k.to_lowercase() == lower);+ let first = hits.next()?;+ hits.next().is_none().then(|| first.to_string())+}++#[cfg(test)]+mod tests {+ use super::*;++ fn strings(values: &[&str]) -> Vec<String> {+ values.iter().map(|s| s.to_string()).collect()+ }++ /// 三项:公司(应绑组织)、参与者(角色词,应 null)、桥(候选里有结构)+ struct Fixture {+ company_spellings: Vec<String>,+ company_examples: Vec<String>,+ company_phrases: Vec<String>,+ participant_spellings: Vec<String>,+ bridge_spellings: Vec<String>,+ bridge_examples: Vec<String>,+ bridge_phrases: Vec<String>,+ }++ impl Fixture {+ fn new() -> Self {+ Fixture {+ company_spellings: strings(&["Company", "company", "公司"]),+ company_examples: strings(&["Brightway Builders", "Harbor Estates"]),+ company_phrases: strings(&["is based in", "was founded by"]),+ participant_spellings: strings(&["participants"]),+ bridge_spellings: strings(&["bridge", "Bridge"]),+ bridge_examples: strings(&["Harbor Bridge"]),+ bridge_phrases: strings(&["spans", "was completed"]),+ }+ }++ fn items(&self) -> Vec<KindWordItem<'_>> {+ let organization = ClassCandidate {+ key: "organization",+ label: "Organization",+ description: "An organized group of people with a shared purpose, such as a company, a council or a club.",+ };+ let person = ClassCandidate {+ key: "person",+ label: "Person",+ description: "A human being.",+ };+ let structure = ClassCandidate {+ key: "structure",+ label: "建筑物",+ description: "人建造的固定物:桥、楼、水坝。",+ };+ vec![+ KindWordItem {+ id: 12,+ kind_word: "company",+ spellings: &self.company_spellings,+ examples: &self.company_examples,+ phrases: &self.company_phrases,+ candidates: vec![organization, person],+ },+ KindWordItem {+ id: 13,+ kind_word: "participant",+ spellings: &self.participant_spellings,+ examples: &[],+ phrases: &[],+ candidates: vec![person, organization],+ },+ KindWordItem {+ id: 14,+ kind_word: "bridge",+ spellings: &self.bridge_spellings,+ examples: &self.bridge_examples,+ phrases: &self.bridge_phrases,+ candidates: vec![structure],+ },+ ]+ }+ }++ const FULL: &str = r#"{"b": [[12, "organization"], [13, null], [14, "structure"]]}"#;++ fn choice(id: i64, key: Option<&str>) -> KindWordChoice {+ KindWordChoice {+ id,+ key: key.map(str::to_string),+ }+ }++ #[test]+ fn a_full_reply_parses_with_keys_and_nulls() {+ let f = Fixture::new();+ let items = f.items();+ let (choices, malformed) = parse_kind_word_response(FULL, &items).unwrap();+ assert_eq!(malformed, 0);+ assert_eq!(+ choices,+ vec![+ choice(12, Some("organization")),+ choice(13, None),+ choice(14, Some("structure")),+ ]+ );+ }++ /// 围栏与前后废话照旧容忍(走的是同一个 json_block)+ #[test]+ fn a_fenced_reply_parses() {+ let f = Fixture::new();+ let items = f.items();+ let raw = format!("Here you go:\n```json\n{FULL}\n```\nDone.");+ let (choices, malformed) = parse_kind_word_response(&raw, &items).unwrap();+ assert_eq!(malformed, 0);+ assert_eq!(choices.len(), 3);+ }++ /// 键不在那一项的候选里就是坏项:别的项有这个候选也不算+ #[test]+ fn a_key_not_among_the_items_candidates_is_malformed() {+ let f = Fixture::new();+ let items = f.items();+ let raw = r#"{"b": [[12, "place"], [14, "organization"], [13, "person"]]}"#;+ let (choices, malformed) = parse_kind_word_response(raw, &items).unwrap();+ assert_eq!(malformed, 2);+ assert_eq!(choices, vec![choice(13, Some("person"))]);+ }++ #[test]+ fn an_unknown_id_is_malformed() {+ let f = Fixture::new();+ let items = f.items();+ let raw = r#"{"b": [[99, "organization"], [12, "organization"]]}"#;+ let (choices, malformed) = parse_kind_word_response(raw, &items).unwrap();+ assert_eq!(malformed, 1);+ assert_eq!(choices, vec![choice(12, Some("organization"))]);+ }++ /// 截在第三对的键中间:前两对留下,第三项缺席(不是 null,也不算坏)+ #[test]+ fn a_truncated_reply_is_repaired_to_the_last_complete_pair() {+ let f = Fixture::new();+ let items = f.items();+ let cut = FULL.find("\"struc").unwrap();+ let (choices, malformed) = parse_kind_word_response(&FULL[..cut], &items).unwrap();+ assert_eq!(malformed, 0);+ assert_eq!(+ choices,+ vec![choice(12, Some("organization")), choice(13, None)]+ );+ }++ /// 截在一对的 id 之后(`[14`):退到上一个完整的 `]`+ #[test]+ fn a_reply_cut_inside_a_pair_keeps_the_pairs_before_it() {+ let f = Fixture::new();+ let items = f.items();+ let raw = r#"{"b": [[12, "organization"], [13, null], [14"#;+ let (choices, malformed) = parse_kind_word_response(raw, &items).unwrap();+ assert_eq!(malformed, 0);+ assert_eq!(choices.len(), 2);+ }++ /// 连一对都没有时仍然报失败——容错不是把空结果说成成功+ #[test]+ fn a_reply_with_nothing_complete_still_fails() {+ let f = Fixture::new();+ let items = f.items();+ assert!(parse_kind_word_response(r#"{"b": [[12, "org"#, &items).is_err());+ assert!(parse_kind_word_response("no json here", &items).is_err());+ }++ /// 没有 `b` 或不是数组:一项都没答,不是坏项+ #[test]+ fn a_reply_without_pairs_gives_no_choices() {+ let f = Fixture::new();+ let items = f.items();+ let (choices, malformed) = parse_kind_word_response(r#"{"b": {}}"#, &items).unwrap();+ assert!(choices.is_empty());+ assert_eq!(malformed, 0);+ let (choices, malformed) = parse_kind_word_response(r#"{"x": 1}"#, &items).unwrap();+ assert!(choices.is_empty());+ assert_eq!(malformed, 0);+ }++ /// 同一个 id 答了两次:留第一次,第二次计入坏项+ #[test]+ fn a_duplicate_id_keeps_the_first() {+ let f = Fixture::new();+ let items = f.items();+ let raw = r#"{"b": [[12, "organization"], [12, null], [12, "person"]]}"#;+ let (choices, malformed) = parse_kind_word_response(raw, &items).unwrap();+ assert_eq!(choices, vec![choice(12, Some("organization"))]);+ assert_eq!(malformed, 2);+ }++ /// 坏项逐个计数:不是数组、只有一格、键是数字、键是空串、id 是对象;+ /// id 写成字符串照数字读+ #[test]+ fn malformed_pairs_are_counted_not_fatal() {+ let f = Fixture::new();+ let items = f.items();+ let raw = r#"{"b": ["not a pair", [12], [13, 7], [14, ""], [{"id": 12}, null], ["12", "organization"]]}"#;+ let (choices, malformed) = parse_kind_word_response(raw, &items).unwrap();+ assert_eq!(malformed, 5);+ assert_eq!(choices, vec![choice(12, Some("organization"))]);+ }++ /// 键的大小写写错了:对回候选自己的键;首尾空白也去掉+ #[test]+ fn a_key_in_the_wrong_case_is_read_back_as_the_candidates_key() {+ let f = Fixture::new();+ let items = f.items();+ let raw = r#"{"b": [[12, "Organization"], [14, " structure "]]}"#;+ let (choices, malformed) = parse_kind_word_response(raw, &items).unwrap();+ assert_eq!(malformed, 0);+ assert_eq!(+ choices,+ vec![+ choice(12, Some("organization")),+ choice(14, Some("structure"))+ ]+ );+ }++ /// 提示词列出每一项的 id、词、拼写、例子、短语、候选键与定义,并带着「每一个+ /// 这种东西」的判据;空清单写 `(none)`+ #[test]+ fn the_prompt_lists_every_item_and_carries_the_rule() {+ let f = Fixture::new();+ let items = f.items();+ let msgs = build_kind_word_messages(&items);+ assert_eq!(msgs.len(), 2);+ assert_eq!(msgs[0].role, "system");+ assert_eq!(msgs[1].role, "user");+ let system = &msgs[0].content;+ let user = &msgs[1].content;++ assert!(system.contains("every thing of this kind is an instance of that class"));+ assert!(system.contains("{\"b\": [[12, \"organization\"], [13, null]]}"));+ assert!(system.contains("never merely related"));+ assert!(system.contains("Never invent a key"));++ assert!(user.contains("Item 12: \"company\"\n"));+ assert!(user.contains("Spellings: \"Company\", \"company\", \"公司\"\n"));+ assert!(user.contains("Examples: \"Brightway Builders\", \"Harbor Estates\"\n"));+ assert!(user.contains("Phrases: \"is based in\", \"was founded by\"\n"));+ assert!(user.contains(+ "- organization: Organization — An organized group of people with a shared purpose"+ ));+ assert!(user.contains("- person: Person — A human being."));++ assert!(user.contains("Item 13: \"participant\"\n"));+ assert!(user.contains("Spellings: \"participants\"\nExamples: (none)\nPhrases: (none)\n"));++ assert!(user.contains("Item 14: \"bridge\"\n"));+ assert!(user.contains("Examples: \"Harbor Bridge\"\n"));+ assert!(user.contains("Phrases: \"spans\", \"was completed\"\n"));+ assert!(+ user.contains("- structure: 建筑物 — 人建造的固定物:桥、楼、水坝。"),+ "候选的标签与定义照库里的语言给: {user}"+ );++ let a = user.find("Item 12").unwrap();+ let b = user.find("Item 13").unwrap();+ let c = user.find("Item 14").unwrap();+ assert!(a < b && b < c);+ assert!(!user.ends_with('\n'));+ }++ /// 标签与键相同不重复;定义为空不写破折号;没有候选写 `(none)`+ #[test]+ fn a_candidate_line_omits_what_is_empty() {+ let f = Fixture::new();+ let spellings = strings(&["council"]);+ let mut items = f.items();+ items.truncate(1);+ items[0].candidates = vec![+ ClassCandidate {+ key: "organization",+ label: "organization",+ description: "",+ },+ ClassCandidate {+ key: "place",+ label: "",+ description: "A location.",+ },+ ];+ items.push(KindWordItem {+ id: 15,+ kind_word: "council",+ spellings: &spellings,+ examples: &[],+ phrases: &[],+ candidates: vec![],+ });+ let user = &build_kind_word_messages(&items)[1].content;+ assert!(user.contains("Candidates:\n- organization\n- place — A location.\n"));+ assert!(user.contains("Item 15: \"council\"\n"));+ assert!(user.ends_with("Candidates: (none)"));+ }++ /// 提示词的例子是中性的:不出现任何测量语料的名字+ #[test]+ fn the_prompt_names_no_benchmark_corpus() {+ let f = Fixture::new();+ let items = f.items();+ let msgs = build_kind_word_messages(&items);+ for m in &msgs {+ for name in [+ "NVIDIA",+ "Nvidia",+ "EDGAR",+ "CUAD",+ "DocRED",+ "Holmes",+ "Wikidata",+ "ai-timeline",+ "OpenAI",+ "Pfizer",+ "State of the Union",+ ] {+ assert!(!m.content.contains(name), "{name} in prompt: {}", m.content);+ }+ }+ }+}diff --git a/crates/utopia-extract/src/lib.rs b/crates/utopia-extract/src/lib.rsindex deb97afa..cb53522c 100644--- a/crates/utopia-extract/src/lib.rs+++ b/crates/utopia-extract/src/lib.rs@@ -9,6 +9,7 @@ use chrono::{DateTime, NaiveDate, TimeZone, Utc};use serde::Deserialize;use utopia_llm::ChatMessage;+pub mod align;pub mod governor;pub mod open;pub mod time;diff --git a/crates/utopia-server/src/api/ontology_routes.rs b/crates/utopia-server/src/api/ontology_routes.rsindex 3ed5e64e..ea124b0b 100644--- a/crates/utopia-server/src/api/ontology_routes.rs+++ b/crates/utopia-server/src/api/ontology_routes.rs@@ -138,6 +138,13 @@ pub async fn create_entity_type(json!({ "key": key, "label": req.label.trim() }),).await;+ // 本体多了一个类:类别词的绑定里那些「没有」和「没定」的要重判(0044 对齐第一片)+ let _ = utopia_store::jobs::enqueue_unless_queued(+ &state.pool,+ "align_types",+ json!({ "kb_id": kb_id }),+ )+ .await;Ok(Json(json!({ "id": id })))}@@ -176,6 +183,13 @@ pub async fn update_entity_type("description": req.description }),).await;+ // 类的定义改了:绑到它的类别词过期,重判+ let _ = utopia_store::jobs::enqueue_unless_queued(+ &state.pool,+ "align_types",+ json!({ "kb_id": kb_id }),+ )+ .await;Ok(Json(json!({ "ok": true })))}diff --git a/crates/utopia-server/src/extraction_open.rs b/crates/utopia-server/src/extraction_open.rsindex 4ba92617..a5b94f8c 100644--- a/crates/utopia-server/src/extraction_open.rs+++ b/crates/utopia-server/src/extraction_open.rs@@ -149,6 +149,8 @@ pub(crate) async fn run_open(// 陈述按名字指它们。被描述的东西不进清单:「一家医院」在下一块里指的未必是同一家let mut doc_entities: Vec<(Uuid, String, String)> = Vec::new();let mut known_by_name: HashMap<String, Uuid> = HashMap::new();+ // 类别词已经绑到类的(0044 对齐第一片):提及带着类去消解,同名不同类才分得开+ let bound_types = utopia_store::type_bindings::bound_map(pool, kb_id).await?;// 被描述的东西按描述文字在本文档内复用:同一块里「the northern wing」说了三次是一个东西let mut described: HashMap<String, Uuid> = HashMap::new();let mut handled_by_name: HashMap<String, Vec<Uuid>> = HashMap::new();@@ -249,10 +251,13 @@ pub(crate) async fn run_open(continue;}let id = if e.named {+ let bound = bound_types+ .get(&utopia_store::type_bindings::normalize(kind))+ .copied();let id = resolve_handle(pool,kb_id,- None,+ bound,name,ctx,Some(&chunk.text),@@ -658,6 +663,13 @@ pub(crate) async fn run_open(serde_json::json!({ "document_id": document_id }),).await?;+ // 新出现的类别词绑到类(0044 对齐第一片):库级,同库排着就不重复+ utopia_store::jobs::enqueue_unless_queued(+ pool,+ "align_types",+ serde_json::json!({ "kb_id": kb_id }),+ )+ .await?;// 队列里多了东西才叫醒人:Review 的计数与对话里那张确认卡都靠这一声if pending_count > 0 {tracing::info!(%document_id, pending_count, "记忆抽出的陈述进了待确认队列");diff --git a/crates/utopia-server/src/main.rs b/crates/utopia-server/src/main.rsindex e23da3e8..3087e44d 100644--- a/crates/utopia-server/src/main.rs+++ b/crates/utopia-server/src/main.rs@@ -34,6 +34,7 @@ mod rss_full_content;mod state;mod time_resolution;mod time_text;+mod type_alignment;mod type_resolution;mod webdav;@@ -495,6 +496,16 @@ async fn dispatch(st: &state::AppState, job: &utopia_store::jobs::Job) -> anyhowOk(())}// 时间提及按文档解析(0045):抽完一篇排一个,重排一次就是重新解析+ // 类别词绑到类(0044 对齐的第一片):库级任务,抽完一篇排一个,本体改了再排+ "align_types" => {+ let kb_id: Uuid = job+ .payload+ .get("kb_id")+ .and_then(|v| v.as_str())+ .and_then(|s| s.parse().ok())+ .ok_or_else(|| anyhow::anyhow!("payload 缺少 kb_id"))?;+ type_alignment::align_types(st, kb_id).await+ }"resolve_time" => {let id = payload_document_id(&job.payload)?;time_resolution::resolve_document(st, id).awaitdiff --git a/crates/utopia-server/src/type_alignment.rs b/crates/utopia-server/src/type_alignment.rsnew file mode 100644index 00000000..a032db48--- /dev/null+++ b/crates/utopia-server/src/type_alignment.rs@@ -0,0 +1,307 @@+//! 类别词绑到类(0044 决定 3–4 的第一片:按签名绑定,签名 = 实体的类别词)。+//!+//! 开放抽取只记文档自己的类别词(`entities.specific_type`:company、person、「指标」),+//! 不选类。类是本体的事,绑定是对齐的事:一个库里 distinct 的类别词就几十上百个,每个+//! 只判一次——例句、它参与的关系短语、候选类的定义一起给模型,**两票一致**才绑,不一致+//! 记成 undecided 留给审核(#725 队列 2),没有类对得上的记成 none 并按老流程提成+//! 「建议加类」(`proposed_type` → 本体页采纳)。绑定存在 `type_bindings`,按类的+//! `updated_at` 与库里最新的类判过期,本体一改只重判过期的(决策记录里说的「版本」就是+//! 这两个时间戳)。绑上的类写到该类别词下每个实体的 `type_id`(`type_source = 'aligned'`,+//! 人定过类的不动),身份消解的按类圈范围随之恢复。+//!+//! 候选类怎么来:库配了嵌入模型就按类别词加例名检索最近的类;没配就在类不多时整表给;+//! 类太多又没嵌入时不判——瞎判比不判糟。++use crate::extraction::chat_retrying_rate_limits_at;+use crate::llm_util;+use crate::ontology_index::{self, Target};+use crate::state::AppState;+use std::collections::{HashMap, HashSet};+use utopia_core::models::EntityType;+use utopia_extract::align::{+ build_kind_word_messages, parse_kind_word_response, ClassCandidate, KindWordItem,+};+use utopia_store::type_bindings::{self, KindWordSignature};+use uuid::Uuid;++/// 一次问多少个类别词。+const BATCH: usize = 20;+/// 每个类别词给几个候选类。+const CANDIDATES: i64 = 10;+/// 没有嵌入模型时,类不超过这个数就整表给。+const WHOLE_LIST_LIMIT: usize = 60;++/// 一票:这个类别词选了哪个键(None = 没有类对得上)。+type Vote = Option<String>;++/// 给一批类别词找候选类:有嵌入就检索,没有就整表(类少时)。返回每个签名的候选 id 列表。+async fn candidates_for(+ state: &AppState,+ kb_id: Uuid,+ sigs: &[&KindWordSignature],+ classes: &[EntityType],+) -> anyhow::Result<Vec<Vec<Uuid>>> {+ let queries: Vec<String> = sigs+ .iter()+ .map(|s| format!("{}: {}", s.kind_word, s.examples.join(", ")))+ .collect();+ let nearest =+ ontology_index::nearest_for_each(state, kb_id, &queries, CANDIDATES, Target::ClassLabel)+ .await+ .unwrap_or_default();+ let mut out = Vec::with_capacity(sigs.len());+ for (i, _) in sigs.iter().enumerate() {+ let found: Vec<Uuid> = nearest+ .get(i)+ .map(|v| v.iter().map(|c| c.id).collect())+ .unwrap_or_default();+ if !found.is_empty() {+ out.push(found);+ } else if classes.len() <= WHOLE_LIST_LIMIT {+ out.push(classes.iter().map(|c| c.id).collect());+ } else {+ out.push(Vec::new());+ }+ }+ Ok(out)+}++/// 两票是否一致:都选同一个键,或都说没有。+fn agree(a: &Vote, b: &Vote) -> bool {+ a == b+}++/// 对一个库跑一遍:新出现的和过期的类别词各判一次,绑上的写类,没有的提成建议。+pub async fn align_types(state: &AppState, kb_id: Uuid) -> anyhow::Result<()> {+ let pool = &state.pool;+ let kb = utopia_store::kbs::get(pool, kb_id).await?;+ let settings = utopia_store::settings::get(pool, kb.workspace_id)+ .await?+ .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align kind words"))?;+ let client = llm_util::chat_client(&settings)+ .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot align kind words"))?;+ // 一个库同时只跑一份:抽完每篇、建每个类都会排一次,排队去重只挡「排队中」的,+ // 后一个开跑时前一个还在跑就并行了——实测种 14 个类跑出 14 份并行任务,把模型端点+ // 打出 502。拿不到锁的直接退出,正在跑的那份会看到同一批词;本轮没判到的下一轮再来+ let mut guard = pool.acquire().await?;+ let locked: bool =+ sqlx::query_scalar("SELECT pg_try_advisory_lock(hashtext('align_types'), hashtext($1))")+ .bind(kb_id.to_string())+ .fetch_one(&mut *guard)+ .await?;+ if !locked {+ tracing::info!(%kb_id, "类别词对齐已有一份在跑,这次跳过");+ return Ok(());+ }+ let result = align_types_locked(state, kb_id, &settings, &client).await;+ let _ = sqlx::query("SELECT pg_advisory_unlock(hashtext('align_types'), hashtext($1))")+ .bind(kb_id.to_string())+ .execute(&mut *guard)+ .await;+ result+}++async fn align_types_locked(+ state: &AppState,+ kb_id: Uuid,+ settings: &utopia_core::models::LlmSettings,+ client: &utopia_llm::LlmClient,+) -> anyhow::Result<()> {+ let pool = &state.pool;+ let classes = utopia_store::graph::entity_types(pool, kb_id).await?;+ let by_id: HashMap<Uuid, &EntityType> = classes.iter().map(|c| (c.id, c)).collect();+ let by_key: HashMap<&str, &EntityType> = classes.iter().map(|c| (c.key.as_str(), c)).collect();+ let sigs = type_bindings::signatures(pool, kb_id).await?;+ let existing: HashMap<String, utopia_store::type_bindings::Binding> =+ type_bindings::bindings(pool, kb_id)+ .await?+ .into_iter()+ .map(|b| (b.kind_word.clone(), b))+ .collect();+ let stale: HashSet<String> = type_bindings::stale(pool, kb_id)+ .await?+ .into_iter()+ .collect();+ let todo: Vec<&KindWordSignature> = sigs+ .iter()+ .filter(|s| match existing.get(&s.kind_word) {+ None => true,+ Some(b) => b.decided_by != "person" && stale.contains(&s.kind_word),+ })+ .collect();+ tracing::info!(%kb_id, kind_words = sigs.len(), to_decide = todo.len(), classes = classes.len(), "类别词对齐开始");++ // 没有类可绑:每个词都是「没有」,并提成建议;类出现后 `stale` 会把它们再交回来+ if classes.is_empty() {+ for s in &todo {+ type_bindings::decide(+ pool,+ kb_id,+ &s.kind_word,+ &s.words,+ None,+ "none",+ &serde_json::json!({ "reason": "no classes" }),+ "agent",+ )+ .await?;+ type_bindings::propose(+ pool,+ kb_id,+ &s.kind_word,+ s.words.first().unwrap_or(&s.kind_word),+ )+ .await?;+ }+ return Ok(());+ }++ let (mut bound, mut none, mut undecided, mut skipped) = (0usize, 0usize, 0usize, 0usize);+ for batch in todo.chunks(BATCH) {+ let cands = candidates_for(state, kb_id, batch, &classes).await?;+ // 两票:第二票把候选倒过来给,防止「选第一个」这种顺序偏好冒充一致+ let mut votes: Vec<(Vote, Vote)> = vec![(None, None); batch.len()];+ let mut answered = vec![(false, false); batch.len()];+ for pass in 0..2 {+ let items: Vec<KindWordItem<'_>> = batch+ .iter()+ .enumerate()+ .filter(|(i, _)| !cands[*i].is_empty())+ .map(|(i, s)| {+ let mut ids: Vec<Uuid> = cands[i].clone();+ if pass == 1 {+ ids.reverse();+ }+ KindWordItem {+ id: i as i64,+ kind_word: &s.kind_word,+ spellings: &s.words,+ examples: &s.examples,+ phrases: &s.phrases,+ candidates: ids+ .iter()+ .filter_map(|id| by_id.get(id))+ .map(|c| ClassCandidate {+ key: &c.key,+ label: &c.label,+ description: &c.description,+ })+ .collect(),+ }+ })+ .collect();+ if items.is_empty() {+ continue;+ }+ let messages = build_kind_word_messages(&items);+ let reply =+ match chat_retrying_rate_limits_at(state, settings, client, &messages, Some(0.0))+ .await+ {+ Ok(r) => r,+ Err(e) => {+ tracing::warn!(%kb_id, error = %e, "类别词对齐调用失败,这一批留到下次");+ continue;+ }+ };+ let (choices, malformed) = match parse_kind_word_response(&reply, &items) {+ Ok(x) => x,+ Err(e) => {+ tracing::warn!(%kb_id, error = %e, "类别词对齐回复解析失败,这一批留到下次");+ continue;+ }+ };+ skipped += malformed;+ for c in choices {+ let Ok(i) = usize::try_from(c.id) else {+ continue;+ };+ if let Some(slot) = votes.get_mut(i) {+ if pass == 0 {+ slot.0 = c.key;+ answered[i].0 = true;+ } else {+ slot.1 = c.key;+ answered[i].1 = true;+ }+ }+ }+ }+ for (i, s) in batch.iter().enumerate() {+ if cands[i].is_empty() {+ skipped += 1;+ continue;+ }+ let (a, b) = &votes[i];+ let (ans_a, ans_b) = answered[i];+ if !ans_a || !ans_b {+ // 有一票没答到:不下结论,下次再问+ continue;+ }+ let record = serde_json::json!({ "first": a, "second": b });+ if !agree(a, b) {+ type_bindings::decide(+ pool,+ kb_id,+ &s.kind_word,+ &s.words,+ None,+ "undecided",+ &record,+ "agent",+ )+ .await?;+ undecided += 1;+ continue;+ }+ match a.as_deref().and_then(|k| by_key.get(k)) {+ Some(class) => {+ if type_bindings::decide(+ pool,+ kb_id,+ &s.kind_word,+ &s.words,+ Some(class.id),+ "bound",+ &record,+ "agent",+ )+ .await?+ {+ type_bindings::apply(pool, kb_id, &s.kind_word, class.id).await?;+ bound += 1;+ }+ }+ None => {+ if type_bindings::decide(+ pool,+ kb_id,+ &s.kind_word,+ &s.words,+ None,+ "none",+ &record,+ "agent",+ )+ .await?+ {+ type_bindings::unapply(pool, kb_id, &s.kind_word).await?;+ type_bindings::propose(+ pool,+ kb_id,+ &s.kind_word,+ s.words.first().unwrap_or(&s.kind_word),+ )+ .await?;+ none += 1;+ }+ }+ }+ }+ }+ tracing::info!(%kb_id, bound, none, undecided, skipped, "类别词对齐完成");+ if bound > 0 {+ state.emit_graph(kb_id);+ }+ Ok(())+}diff --git a/crates/utopia-store/src/lib.rs b/crates/utopia-store/src/lib.rsindex 5301b4b0..bafa7f74 100644--- a/crates/utopia-store/src/lib.rs+++ b/crates/utopia-store/src/lib.rs@@ -40,6 +40,7 @@ pub mod temporal;pub mod test_db;pub mod time_mentions;pub mod tokens;+pub mod type_bindings;pub mod vector_index;pub mod workspaces;pub mod world_axis;diff --git a/crates/utopia-store/src/ontology.rs b/crates/utopia-store/src/ontology.rsindex 90ef42c9..cc425e41 100644--- a/crates/utopia-store/src/ontology.rs+++ b/crates/utopia-store/src/ontology.rs@@ -193,7 +193,7 @@ pub async fn update_entity_type(validate_shape(shape)?;let res = sqlx::query("UPDATE entity_types SET label = $3, color = COALESCE($4, color), shape = $5,- description = $6+ description = $6, updated_at = now()WHERE id = $2 AND kb_id = $1",).bind(kb_id)@@ -892,7 +892,8 @@ pub async fn update_type_from_import(SET label = $3,-- 空描述不覆盖已有的:上游可能没写 rdfs:comment,而本地可能-- 已经被人按自己的语料调过,那份调整比空值有价值- description = CASE WHEN $4 = '' THEN description ELSE $4 END+ description = CASE WHEN $4 = '' THEN description ELSE $4 END,+ updated_at = now()WHERE kb_id = $1 AND iri = $2 RETURNING id",).bind(kb_id)@@ -1496,7 +1497,7 @@ pub async fn adopt_iri_onto_key(iri: &str,) -> AppResult<Option<Uuid>> {let row: Option<(Uuid,)> = sqlx::query_as(- "UPDATE entity_types SET iri = $3, shape = 'square'+ "UPDATE entity_types SET iri = $3, shape = 'square', updated_at = now()WHERE kb_id = $1 AND key = $2 AND iri IS NULLRETURNING id",)diff --git a/crates/utopia-store/src/type_bindings.rs b/crates/utopia-store/src/type_bindings.rsnew file mode 100644index 00000000..fe473e31--- /dev/null+++ b/crates/utopia-store/src/type_bindings.rs@@ -0,0 +1,296 @@+//! 类别词绑到类的账本侧(0044 决定 3–4 的第一片,见 0065)。+//!+//! 开放抽取只记文档自己的类别词(`entities.specific_type`),不选类。这里做三件事:+//! 数出一个库里有哪些类别词、各带什么例子与关系短语(签名);记下每个类别词判成了+//! 什么(绑定)并判哪些过期了;把绑上的类写到该类别词下的实体上(`type_source =+//! 'aligned'`),或者在没有类对得上时按老流程提成「建议加类」。判定本身——问模型、+//! 两票一致才绑——在 server 的 `type_alignment` 里,这里不认识模型。+//!+//! 类别词在 Rust 与 SQL 两侧用同一种归一:空白折成一个空格、去两端、小写。+//! [`normalize`] 与 [`KIND_WORD_SQL`] 必须说同一件事,否则 `signatures` 数出来的词+//! `apply` 找不着。++use chrono::{DateTime, Utc};+use sqlx::PgPool;+use std::collections::HashMap;+use utopia_core::{AppError, AppResult};+use uuid::Uuid;++/// SQL 侧的归一:与 [`normalize`] 一致。`$col` 由调用处替换成列名。+const KIND_WORD_SQL: &str = "lower(btrim(regexp_replace($col, '\\s+', ' ', 'g')))";++fn kind_word_sql(col: &str) -> String {+ KIND_WORD_SQL.replace("$col", col)+}++/// 归一一个类别词:空白折成一个空格、去两端、小写。"Company " 与 "company" 是一个词。+pub fn normalize(kind_word: &str) -> String {+ kind_word+ .split_whitespace()+ .collect::<Vec<_>>()+ .join(" ")+ .to_lowercase()+}++/// 一个类别词的签名:判它该绑到哪个类时给模型看的全部。+#[derive(Debug, Clone, sqlx::FromRow)]+pub struct KindWordSignature {+ /// 归一过的词+ pub kind_word: String,+ /// 文档里见过的写法(最多 3 个,按出现次数)+ pub words: Vec<String>,+ /// 这个词下活着的实体数+ pub count: i64,+ /// 例名(最多 3 个,有名字的在前,再按创建先后)+ pub examples: Vec<String>,+ /// 以这些实体为主语的开放陈述里最常见的关系短语(最多 3 个)+ pub phrases: Vec<String>,+}++/// 库里每个 distinct 的类别词:活着的(`merged_into` 空)、带类别词的实体。+pub async fn signatures(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<KindWordSignature>> {+ let sql = format!(+ "WITH live AS (+ SELECT e.id, e.canonical_name, e.description, e.created_at,+ btrim(regexp_replace(e.specific_type, '\\s+', ' ', 'g')) AS spelling,+ {kind} AS kind_word+ FROM entities e+ WHERE e.kb_id = $1 AND e.merged_into IS NULL+ AND e.specific_type IS NOT NULL AND btrim(e.specific_type) <> ''+ ),+ grouped AS (+ SELECT kind_word, count(*) AS count FROM live GROUP BY kind_word+ )+ SELECT g.kind_word,+ g.count,+ ARRAY(SELECT s.spelling FROM (+ SELECT l.spelling, count(*) AS n FROM live l+ WHERE l.kind_word = g.kind_word+ GROUP BY l.spelling ORDER BY n DESC, l.spelling LIMIT 3) s+ ) AS words,+ ARRAY(SELECT l.canonical_name FROM live l+ WHERE l.kind_word = g.kind_word+ ORDER BY (l.description IS NOT NULL), l.created_at, l.id LIMIT 3+ ) AS examples,+ ARRAY(SELECT s.phrase FROM (+ SELECT f.phrase, count(*) AS n+ FROM facts f JOIN live l ON l.id = f.subject_id+ WHERE f.kb_id = $1 AND f.layer = 'open' AND f.invalidated_at IS NULL+ AND f.phrase IS NOT NULL AND l.kind_word = g.kind_word+ GROUP BY f.phrase ORDER BY n DESC, f.phrase LIMIT 3) s+ ) AS phrases+ FROM grouped g+ ORDER BY g.count DESC, g.kind_word",+ kind = kind_word_sql("e.specific_type")+ );+ Ok(sqlx::query_as(&sql).bind(kb_id).fetch_all(pool).await?)+}++/// 一个类别词判成了什么。+#[derive(Debug, Clone, sqlx::FromRow)]+pub struct Binding {+ pub kind_word: String,+ /// `status = 'bound'` 时有值+ pub type_id: Option<Uuid>,+ /// bound / none / undecided+ pub status: String,+ pub decided_at: DateTime<Utc>,+ /// agent / person+ pub decided_by: String,+}++/// 库里全部绑定,按词序。+pub async fn bindings(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<Binding>> {+ Ok(sqlx::query_as(+ "SELECT kind_word, type_id, status, decided_at, decided_by+ FROM type_bindings WHERE kb_id = $1 ORDER BY kind_word",+ )+ .bind(kb_id)+ .fetch_all(pool)+ .await?)+}++/// 不再成立的绑定:绑到的类在判定之后改过;或判成 none / undecided 之后库里长出了+/// 新类(也许对得上)。绑到的类被删了的,行已随级联消失,这里不会出现。+pub async fn stale(pool: &PgPool, kb_id: Uuid) -> AppResult<Vec<String>> {+ Ok(sqlx::query_scalar(+ "SELECT b.kind_word+ FROM type_bindings b+ LEFT JOIN entity_types t ON t.id = b.type_id+ WHERE b.kb_id = $1+ AND ((b.status = 'bound' AND t.updated_at > b.decided_at)+ OR (b.status IN ('none', 'undecided')+ AND b.decided_at < (SELECT max(created_at) FROM entity_types+ WHERE kb_id = $1)))+ ORDER BY b.kind_word",+ )+ .bind(kb_id)+ .fetch_all(pool)+ .await?)+}++/// 记下一个类别词的判定(有则改)。返回是否写入了。+///+/// **人的判定不被代理覆盖**:已有行是人判的而这次是代理,原样留着、返回 false。+/// 反过来人可以改代理的。`words` 传空时保留已有的写法——人在界面上拍板时手里+/// 未必有签名。+#[allow(clippy::too_many_arguments)]+pub async fn decide(+ pool: &PgPool,+ kb_id: Uuid,+ kind_word: &str,+ words: &[String],+ type_id: Option<Uuid>,+ status: &str,+ votes: &serde_json::Value,+ decided_by: &str,+) -> AppResult<bool> {+ if !matches!(status, "bound" | "none" | "undecided") {+ return Err(AppError::Validation(format!(+ "unknown binding status {status:?}"+ )));+ }+ if (status == "bound") != type_id.is_some() {+ return Err(AppError::Validation(+ "a bound kind word needs a class and an unbound one must not have one".into(),+ ));+ }+ if !matches!(decided_by, "agent" | "person") {+ return Err(AppError::Validation(format!(+ "unknown decider {decided_by:?}"+ )));+ }+ let kind_word = normalize(kind_word);+ if kind_word.is_empty() {+ return Err(AppError::Validation(+ "an empty kind word binds nothing".into(),+ ));+ }+ let res = sqlx::query(+ "INSERT INTO type_bindings+ (id, kb_id, kind_word, words, type_id, status, votes, decided_at, decided_by)+ VALUES ($1, $2, $3, $4, $5, $6, $7, now(), $8)+ ON CONFLICT (kb_id, kind_word) DO UPDATE+ SET words = CASE WHEN cardinality(EXCLUDED.words) = 0+ THEN type_bindings.words ELSE EXCLUDED.words END,+ type_id = EXCLUDED.type_id,+ status = EXCLUDED.status,+ votes = EXCLUDED.votes,+ decided_at = now(),+ decided_by = EXCLUDED.decided_by+ WHERE NOT (type_bindings.decided_by = 'person' AND EXCLUDED.decided_by = 'agent')",+ )+ .bind(Uuid::now_v7())+ .bind(kb_id)+ .bind(&kind_word)+ .bind(words)+ .bind(type_id)+ .bind(status)+ .bind(votes)+ .bind(decided_by)+ .execute(pool)+ .await?;+ Ok(res.rows_affected() > 0)+}++/// 把绑上的类写到这个类别词下每个活着的、人没定过类的实体上。返回改动数。+///+/// 已在这个类上的不算改动(`IS DISTINCT FROM`:`type_id` 可能是 NULL)。有了类,+/// 「建议加类」就不再是建议,`proposed_type` 一并清掉——否则本体页会继续为一个+/// 已经有类的词喊着要建类。+pub async fn apply(pool: &PgPool, kb_id: Uuid, kind_word: &str, type_id: Uuid) -> AppResult<u64> {+ let sql = format!(+ "UPDATE entities+ SET type_id = $3, type_source = 'aligned', proposed_type = NULL, updated_at = now()+ WHERE kb_id = $1 AND merged_into IS NULL AND type_source <> 'human'+ AND specific_type IS NOT NULL AND {kind} = $2+ AND type_id IS DISTINCT FROM $3",+ kind = kind_word_sql("specific_type")+ );+ let res = sqlx::query(&sql)+ .bind(kb_id)+ .bind(normalize(kind_word))+ .bind(type_id)+ .execute(pool)+ .await?;+ Ok(res.rows_affected())+}++/// 绑定变成 none 或失效时:按它对齐上去的实体失去那个类。只动 `aligned` 的行——+/// 抽取判的、引擎猜的、人拍的都不是这条绑定给的。返回改动数。+pub async fn unapply(pool: &PgPool, kb_id: Uuid, kind_word: &str) -> AppResult<u64> {+ let sql = format!(+ "UPDATE entities+ SET type_id = NULL, type_source = 'extracted', updated_at = now()+ WHERE kb_id = $1 AND merged_into IS NULL AND type_source = 'aligned'+ AND specific_type IS NOT NULL AND {kind} = $2",+ kind = kind_word_sql("specific_type")+ );+ let res = sqlx::query(&sql)+ .bind(kb_id)+ .bind(normalize(kind_word))+ .execute(pool)+ .await?;+ Ok(res.rows_affected())+}++/// 抽取时用的绑定表:归一过的类别词 → 类 id,只有绑上的。+pub async fn bound_map(pool: &PgPool, kb_id: Uuid) -> AppResult<HashMap<String, Uuid>> {+ let rows: Vec<(String, Uuid)> = sqlx::query_as(+ "SELECT kind_word, type_id FROM type_bindings+ WHERE kb_id = $1 AND status = 'bound' AND type_id IS NOT NULL",+ )+ .bind(kb_id)+ .fetch_all(pool)+ .await?;+ Ok(rows.into_iter().collect())+}++/// 没有类对得上的类别词:按老流程提到本体页(`proposed_type` → `adopt_proposed_types`)。+///+/// 守 `set_proposed_type` 的约:只写第一次、最长 60 字;只提活着的、还没类的、人没+/// 定过的实体——采纳时人定过的不会被认领,数进「将重新归类 N 个」里就是虚的。+/// 返回写上的行数。+pub async fn propose(+ pool: &PgPool,+ kb_id: Uuid,+ kind_word: &str,+ spelling: &str,+) -> AppResult<u64> {+ let spelling = spelling.trim();+ if spelling.is_empty() {+ return Err(AppError::Validation(+ "a proposal needs the document's spelling".into(),+ ));+ }+ let sql = format!(+ "UPDATE entities SET proposed_type = left($3, 60)+ WHERE kb_id = $1 AND merged_into IS NULL AND type_id IS NULL+ AND type_source <> 'human' AND proposed_type IS NULL+ AND specific_type IS NOT NULL AND {kind} = $2",+ kind = kind_word_sql("specific_type")+ );+ let res = sqlx::query(&sql)+ .bind(kb_id)+ .bind(normalize(kind_word))+ .bind(spelling)+ .execute(pool)+ .await?;+ Ok(res.rows_affected())+}++#[cfg(test)]+mod tests {+ use super::normalize;++ #[test]+ fn a_kind_word_is_one_word_however_spaced_or_cased() {+ assert_eq!(+ normalize(" Stockholder Proposal "),+ "stockholder proposal"+ );+ assert_eq!(normalize("Company"), "company");+ assert_eq!(normalize("指标"), "指标");+ assert_eq!(normalize(" "), "");+ }+}diff --git a/crates/utopia-store/tests/a_kind_word_binds_to_a_class.rs b/crates/utopia-store/tests/a_kind_word_binds_to_a_class.rsnew file mode 100644index 00000000..2a2d69ad--- /dev/null+++ b/crates/utopia-store/tests/a_kind_word_binds_to_a_class.rs@@ -0,0 +1,488 @@+//! 一个类别词绑到一个类(0044 决定 3–4 的第一片,账本侧,见 0065)。+//!+//! 开放抽取只记文档自己的类别词,不选类。库要能数出每个类别词的签名("Company" 与+//! "company" 是一个词:两个写法、两个实体、它们参与的关系短语);绑定判了之后写到该+//! 类别词下每个实体的 `type_id`(`type_source = 'aligned'`),人定过的不动;绑定按类的+//! `updated_at` 与库里最新的类判过期;人的判定不被代理覆盖,反过来可以;解绑只动+//! `aligned` 的行;没有类对得上的按老流程提成「建议加类」。+//!+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。++use sqlx::PgPool;+use std::collections::HashSet;+use std::time::Duration;+use utopia_store::graph::{self, FactObject};+use utopia_store::{ontology, resolution, type_bindings};+use uuid::Uuid;++const ORG: &str = "kind-word-binding-test";+const PROPOSAL: &str = "the stockholder proposal on declassifying the board";++struct Fixture {+ kb: Uuid,+ organization: Uuid,+ person: Uuid,+ acme: Uuid,+ beta: Uuid,+ carol: Uuid,+ dave: Uuid,+ proposal: Uuid,+}++async fn seed(pool: &PgPool) -> anyhow::Result<Fixture> {+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());+ let (organization, person) = (Uuid::now_v7(), Uuid::now_v7());+ let (acme, beta, carol, dave, proposal) = (+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ Uuid::now_v7(),+ );+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, $2)")+ .bind(org)+ .bind(ORG)+ .execute(pool)+ .await?;+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, $3)")+ .bind(ws)+ .bind(org)+ .bind(ORG)+ .execute(pool)+ .await?;+ sqlx::query("INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, $3)")+ .bind(kb)+ .bind(ws)+ .bind(ORG)+ .execute(pool)+ .await?;+ for (id, key, label) in [+ (organization, "organization", "Organization"),+ (person, "person", "Person"),+ ] {+ sqlx::query("INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, $3, $4)")+ .bind(id)+ .bind(kb)+ .bind(key)+ .bind(label)+ .execute(pool)+ .await?;+ }+ // 有名字的:类别词照文档的写法,类空着+ for (id, name, kind) in [+ (acme, "Acme", "Company"),+ (beta, "Beta", "company"),+ (carol, "Carol", "person"),+ ] {+ sqlx::query(+ "INSERT INTO entities (id, kb_id, canonical_name, specific_type)+ VALUES ($1, $2, $3, $4)",+ )+ .bind(id)+ .bind(kb)+ .bind(name)+ .bind(kind)+ .execute(pool)+ .await?;+ }+ // 人看过、说没有合适的类:type_id 空、type_source = human+ sqlx::query(+ "INSERT INTO entities (id, kb_id, canonical_name, specific_type, type_source)+ VALUES ($1, $2, 'Dave', 'person', 'human')",+ )+ .bind(dave)+ .bind(kb)+ .execute(pool)+ .await?;+ // 一个被描述、没有名字的东西+ sqlx::query(+ "INSERT INTO entities (id, kb_id, canonical_name, description, specific_type)+ VALUES ($1, $2, $3, $3, 'stockholder proposal')",+ )+ .bind(proposal)+ .bind(kb)+ .bind(PROPOSAL)+ .execute(pool)+ .await?;+ // 几条开放陈述:主语是公司的+ for (subject, phrase, object) in [+ (acme, "acquired", FactObject::Entity(beta)),+ (+ acme,+ "acquired",+ FactObject::Value(&serde_json::json!({ "value": "a rival" })),+ ),+ (+ beta,+ "is headquartered in",+ FactObject::Value(&serde_json::json!({ "value": "Austin" })),+ ),+ ] {+ graph::insert_open_statement(pool, kb, subject, phrase, object, None, 0.9).await?;+ }+ Ok(Fixture {+ kb,+ organization,+ person,+ acme,+ beta,+ carol,+ dave,+ proposal,+ })+}++#[derive(Debug, PartialEq, sqlx::FromRow)]+struct Typed {+ type_id: Option<Uuid>,+ type_source: String,+ proposed_type: Option<String>,+}++async fn typed(pool: &PgPool, id: Uuid) -> anyhow::Result<Typed> {+ Ok(+ sqlx::query_as("SELECT type_id, type_source, proposed_type FROM entities WHERE id = $1")+ .bind(id)+ .fetch_one(pool)+ .await?,+ )+}++/// 两次 `now()` 要分得开:过期靠时间戳的先后+async fn tick() {+ tokio::time::sleep(Duration::from_millis(5)).await;+}++#[tokio::test]+async fn a_kind_word_is_counted_once_bound_once_and_applied_to_its_entities() -> anyhow::Result<()>+{+ let Some(url) = utopia_store::test_db::url() else {+ return Ok(());+ };+ let pool = PgPool::connect(&url).await?;+ sqlx::query("DELETE FROM organizations WHERE name = $1")+ .bind(ORG)+ .execute(&pool)+ .await?;+ let f = seed(&pool).await?;++ let run = async {+ // 1. 签名:"Company" 与 "company" 是一个词+ let sigs = type_bindings::signatures(&pool, f.kb).await?;+ let words: Vec<&str> = sigs.iter().map(|s| s.kind_word.as_str()).collect();+ assert_eq!(+ words,+ ["company", "person", "stockholder proposal"],+ "按实体数再按词序:{sigs:?}"+ );+ let company = &sigs[0];+ assert_eq!(company.count, 2);+ assert_eq!(+ company.words.iter().map(String::as_str).collect::<HashSet<_>>(),+ HashSet::from(["Company", "company"]),+ "两种写法都留着"+ );+ assert_eq!(+ company.examples.iter().map(String::as_str).collect::<HashSet<_>>(),+ HashSet::from(["Acme", "Beta"])+ );+ assert_eq!(+ company.phrases,+ ["acquired", "is headquartered in"],+ "以公司为主语的开放陈述的短语,按次数"+ );+ let proposal = &sigs[2];+ assert_eq!(proposal.count, 1);+ assert_eq!(proposal.words, ["stockholder proposal"]);+ assert_eq!(proposal.examples, [PROPOSAL], "没有名字的以描述为例");+ assert!(proposal.phrases.is_empty());+ assert_eq!(sigs[1].count, 2, "Carol 与 Dave");++ // 2. 绑上并写到实体上:两个公司都成了 organization,人定过的不动+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "company",+ &company.words,+ Some(f.organization),+ "bound",+ &serde_json::json!({ "votes": ["organization", "organization"] }),+ "agent",+ )+ .await?+ );+ assert_eq!(+ type_bindings::apply(&pool, f.kb, "company", f.organization).await?,+ 2+ );+ for id in [f.acme, f.beta] {+ assert_eq!(+ typed(&pool, id).await?,+ Typed {+ type_id: Some(f.organization),+ type_source: "aligned".into(),+ proposed_type: None,+ }+ );+ }+ assert_eq!(+ type_bindings::apply(&pool, f.kb, "company", f.organization).await?,+ 0,+ "再写一次没有改动"+ );+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "Person",+ &[],+ Some(f.person),+ "bound",+ &serde_json::json!({}),+ "agent",+ )+ .await?,+ "写法归一后是同一个词"+ );+ assert_eq!(+ type_bindings::apply(&pool, f.kb, "person", f.person).await?,+ 1,+ "只有 Carol;Dave 是人定的"+ );+ assert_eq!(typed(&pool, f.carol).await?.type_id, Some(f.person));+ assert_eq!(+ typed(&pool, f.dave).await?,+ Typed {+ type_id: None,+ type_source: "human".into(),+ proposed_type: None,+ },+ "人说没有类,就没有类"+ );++ // 3. 抽取时用的表+ let bound = type_bindings::bound_map(&pool, f.kb).await?;+ assert_eq!(bound.get("company"), Some(&f.organization));+ assert_eq!(bound.get("person"), Some(&f.person));+ assert_eq!(bound.len(), 2);++ // 4. 过期:绑到的类改了+ assert!(type_bindings::stale(&pool, f.kb).await?.is_empty());+ tick().await;+ ontology::update_entity_type(+ &pool,+ f.kb,+ f.organization,+ "Organisation",+ None,+ "square",+ &[],+ "a company or any other body",+ )+ .await?;+ assert_eq!(type_bindings::stale(&pool, f.kb).await?, ["company"]);+ tick().await;+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "company",+ &company.words,+ Some(f.organization),+ "bound",+ &serde_json::json!({ "votes": ["organization", "organization"] }),+ "agent",+ )+ .await?,+ "代理可以改代理的"+ );+ assert!(type_bindings::stale(&pool, f.kb).await?.is_empty());++ // 5. 没有类对得上:记 none,按老流程提成建议加类+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "stockholder proposal",+ &proposal.words,+ None,+ "none",+ &serde_json::json!({ "votes": [null, null] }),+ "agent",+ )+ .await?+ );+ assert_eq!(+ type_bindings::propose(&pool, f.kb, "stockholder proposal", "stockholder proposal")+ .await?,+ 1+ );+ assert_eq!(+ typed(&pool, f.proposal).await?.proposed_type.as_deref(),+ Some("stockholder proposal")+ );+ assert_eq!(+ type_bindings::propose(&pool, f.kb, "stockholder proposal", "Stockholder Proposal")+ .await?,+ 0,+ "只写第一次,与 set_proposed_type 同一条"+ );+ let proposed = resolution::proposed_types(&pool, f.kb).await?;+ let p = proposed+ .iter()+ .find(|p| p.form == "stockholder proposal")+ .expect("the ontology page offers it");+ assert_eq!(p.entity_count, 1);+ assert_eq!(p.example.as_deref(), Some(PROPOSAL));+ // 绑定的形状:绑上了就得有类+ assert!(type_bindings::decide(+ &pool,+ f.kb,+ "thing",+ &[],+ None,+ "bound",+ &serde_json::json!({}),+ "agent",+ )+ .await+ .is_err());++ // 6. 过期:判成 none 之后库里长出了新类+ assert!(type_bindings::stale(&pool, f.kb).await?.is_empty());+ tick().await;+ sqlx::query(+ "INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, 'proposal', 'Proposal')",+ )+ .bind(Uuid::now_v7())+ .bind(f.kb)+ .execute(&pool)+ .await?;+ assert_eq!(+ type_bindings::stale(&pool, f.kb).await?,+ ["stockholder proposal"],+ "绑上的不受新类影响,none 的要重判"+ );+ tick().await;+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "stockholder proposal",+ &[],+ None,+ "none",+ &serde_json::json!({ "votes": [null, null] }),+ "agent",+ )+ .await?+ );+ assert!(type_bindings::stale(&pool, f.kb).await?.is_empty());++ // 7. 人的判定不被代理覆盖,反过来可以+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "company",+ &[],+ Some(f.organization),+ "bound",+ &serde_json::json!({ "by": "a person" }),+ "person",+ )+ .await?+ );+ assert!(+ !type_bindings::decide(+ &pool,+ f.kb,+ "company",+ &[],+ None,+ "none",+ &serde_json::json!({}),+ "agent",+ )+ .await?,+ "代理改不了人的"+ );+ let b = type_bindings::bindings(&pool, f.kb).await?;+ let company_b = b.iter().find(|b| b.kind_word == "company").unwrap();+ assert_eq!(+ (company_b.status.as_str(), company_b.type_id, company_b.decided_by.as_str()),+ ("bound", Some(f.organization), "person")+ );+ assert_eq!(+ b.iter().map(|b| b.kind_word.as_str()).collect::<Vec<_>>(),+ ["company", "person", "stockholder proposal"]+ );+ assert!(+ type_bindings::decide(+ &pool,+ f.kb,+ "company",+ &[],+ None,+ "none",+ &serde_json::json!({}),+ "person",+ )+ .await?,+ "人可以改人的"+ );+ let b = type_bindings::bindings(&pool, f.kb).await?;+ let company_b = b.iter().find(|b| b.kind_word == "company").unwrap();+ assert_eq!((company_b.status.as_str(), company_b.type_id), ("none", None));+ assert!(!type_bindings::bound_map(&pool, f.kb)+ .await?+ .contains_key("company"));++ // 8. 解绑只动 aligned 的行+ sqlx::query("UPDATE entities SET type_source = 'human' WHERE id = $1")+ .bind(f.beta)+ .execute(&pool)+ .await?;+ assert_eq!(+ type_bindings::unapply(&pool, f.kb, "company").await?,+ 1,+ "Beta 已被人认下,留着"+ );+ assert_eq!(+ typed(&pool, f.acme).await?,+ Typed {+ type_id: None,+ type_source: "extracted".into(),+ proposed_type: None,+ }+ );+ assert_eq!(typed(&pool, f.beta).await?.type_id, Some(f.organization));+ assert_eq!(typed(&pool, f.carol).await?.type_id, Some(f.person));+ assert_eq!(type_bindings::unapply(&pool, f.kb, "company").await?, 0);+ // 绑上的类之后有了 → 对齐时把建议清掉+ assert_eq!(+ type_bindings::apply(&pool, f.kb, "stockholder proposal", f.organization).await?,+ 1+ );+ assert_eq!(typed(&pool, f.proposal).await?.proposed_type, None);++ // 9. 类删了,绑定跟着走+ assert_eq!(type_bindings::unapply(&pool, f.kb, "person").await?, 1);+ sqlx::query("DELETE FROM entity_types WHERE id = $1")+ .bind(f.person)+ .execute(&pool)+ .await?;+ let b = type_bindings::bindings(&pool, f.kb).await?;+ assert!(b.iter().all(|b| b.kind_word != "person"));+ assert!(type_bindings::stale(&pool, f.kb).await?.is_empty());+ Ok::<(), anyhow::Error>(())+ }+ .await;++ sqlx::query("DELETE FROM organizations WHERE name = $1")+ .bind(ORG)+ .execute(&pool)+ .await?;+ run+}diff --git a/migrations/0065_a_kind_word_binds_to_a_class.sql b/migrations/0065_a_kind_word_binds_to_a_class.sqlnew file mode 100644index 00000000..ee58a440--- /dev/null+++ b/migrations/0065_a_kind_word_binds_to_a_class.sql@@ -0,0 +1,44 @@+-- 一个类别词绑到一个类(0044 决定 3–4 的第一片:类型化图谱是按签名绑定从开放图谱+-- 算出来的视图;这一片的签名 = 实体的类别词)。+--+-- 开放抽取只记文档自己的类别词(`entities.specific_type`:company、person、+-- stockholder proposal、「指标」),不选类(`type_id` 空着)。类是本体的事——包、+-- 工作台建出来的。一个库里 distinct 的类别词就几十上百个,每个只判一次:判了记在+-- `type_bindings` 里,本体一改只重判过期的。绑上的类写到该类别词下每个实体的+-- `type_id`,来源记 `aligned`——它不是抽取判的、不是引擎按相似度猜的,也不是人拍的,+-- 是按签名绑定算出来的视图;人定过类的实体不动。身份消解的按类圈范围随之恢复。+-- 没有类对得上的类别词按老流程提成「建议加类」(`proposed_type` → 本体页采纳)。+--+-- 过期怎么判:绑到的类在判定之后改过(`entity_types.updated_at`),或者判成 none /+-- undecided 之后库里长出了新类(`entity_types.created_at`)。类被删了,绑定随之级联。++-- 类改过没有,从前谁也答不上来——只有 created_at。绑定要靠它判过期,每条 UPDATE+-- entity_types 都得摸一下+ALTER TABLE entity_types ADD COLUMN updated_at TIMESTAMPTZ NOT NULL DEFAULT now();++ALTER TABLE entities DROP CONSTRAINT entities_type_source_check;+ALTER TABLE entities ADD CONSTRAINT entities_type_source_check+ CHECK (type_source IN ('extracted', 'human', 'inferred', 'aligned'));++CREATE TABLE type_bindings (+ id UUID PRIMARY KEY,+ kb_id UUID NOT NULL REFERENCES knowledge_bases(id) ON DELETE CASCADE,+ -- 归一过的:空白折成一个空格、小写、去两端空白。"Company" 与 "company" 是一个词+ kind_word TEXT NOT NULL,+ -- 文档里见过的写法+ words TEXT[] NOT NULL DEFAULT '{}',+ -- status 为 none / undecided 时为空;类删了绑定跟着走+ type_id UUID REFERENCES entity_types(id) ON DELETE CASCADE,+ -- bound 绑上了+ -- none 没有类对得上(已按老流程提成建议加类)+ -- undecided 两票不一致,留给审核+ status TEXT NOT NULL CHECK (status IN ('bound', 'none', 'undecided')),+ -- 得出这个判定的那几票+ votes JSONB,+ decided_at TIMESTAMPTZ NOT NULL DEFAULT now(),+ -- 人的判定不被代理覆盖+ decided_by TEXT NOT NULL DEFAULT 'agent' CHECK (decided_by IN ('agent', 'person')),+ UNIQUE (kb_id, kind_word),+ -- 绑上了就得有类,没绑就不能有+ CONSTRAINT type_bindings_shape CHECK ((status = 'bound') = (type_id IS NOT NULL))+);