Skip to content

World's first open-source enterprise world 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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) -> anyhow
Ok(())
}
// 时间提及按文档解析(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).await
diff --git a/crates/utopia-server/src/type_alignment.rs b/crates/utopia-server/src/type_alignment.rs
new file mode 100644
index 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.rs
index 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.rs
index 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 NULL
RETURNING id",
)
diff --git a/crates/utopia-store/src/type_bindings.rs b/crates/utopia-store/src/type_bindings.rs
new file mode 100644
index 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.rs
new file mode 100644
index 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.sql
new file mode 100644
index 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))
+);