Skip to content

World's first open-source enterprise world model.

64.3 KB
Raw Blame
//! 本体代理(0061 决定 2、3):对齐判成「没有」「没定」的短语形状与类别词,对着现有本体和
//! 能力问题交给模型,让它提该建的类与属性。提案进 `ontology_proposals`,**人采纳才成为本体**
//! (0012);采纳建出元素后排一次对齐,那些形状按 0053 的指纹自己重判。
//!
//! 形状的身份是短语加两端的类键加宾语是不是字面值——同 `phrase_bindings` 的键,只是用键
//! 而不是 id 存进提案,好让人读得懂

use std::collections::{HashMap, HashSet};

use chrono::{DateTime, Utc};
use serde::Deserialize;
use serde_json::{json, Value};
use sha2::{Digest, Sha256};
use sqlx::{Postgres, Transaction};
use utopia_core::models::{RelationAxioms, RelationTypeView};
use utopia_core::AppError;
use utopia_extract::ontology_agent as agent;
use utopia_store::agent_reviews::{self, Review};
use utopia_store::ontology::StoredProposal;
use utopia_store::phrase_bindings::PhraseSignature;
use utopia_store::type_bindings::KindWordSignature;
use utopia_store::{competency_questions, phrase_bindings, type_bindings};
use uuid::Uuid;

use crate::extraction::chat_retrying_rate_limits_at;
use crate::llm_util;
use crate::state::AppState;

/// 给没问题的库一次提这么多问题
pub(crate) const QUESTIONS_PER_ROUND: usize = 10;
/// 提问题时看多少条说得最多的形状 / 类别词 / 实体
const TOP_SIGNATURES: usize = 40;
const TOP_KIND_WORDS: usize = 20;
const TOP_ENTITIES: usize = 20;

/// 一条形状结构上对得上的属性多过这个数,就按向量只留最近的这么多带定义(同对齐的短名单)
const GLOSSARY_PER_SHAPE: usize = 10;
/// 每条形状按意思最近的这么多条属性,结构对不上也带定义
const GLOSSARY_NEAREST_ANYWAY: usize = 5;

/// 一次调用交给模型的形状数(0044 决定 3 的成本教训:词表每批只带一次)
pub(crate) const SIGNATURES_PER_CALL: usize = 12;
/// 每批跟着的类别词至多这么多
pub(crate) const KIND_WORDS_PER_CALL: usize = 6;
/// 一轮至多问这么多形状,按陈述数从多到少;其余等下一轮。界面上点一次也只花这么多
pub(crate) const SIGNATURES_PER_ROUND: usize = 120;
/// 对齐收尾时没绑上的形状够这么多,才叫代理来看(少于这个数人自己在审核页就处理了)
pub(crate) const TRIGGER_UNBOUND: usize = 20;

/// 形状写进提案里的样子
fn shape_of(sig: &PhraseSignature) -> Value {
    json!({
        "phrase": sig.phrase,
        "subject": sig.subject_type_key,
        "object": sig.object_type_key,
        "value": sig.object_is_value,
        // Proposals show the first example; keep its identity from the same read.
        "example_statement_ids": sig.example_statement_ids.first().into_iter().collect::<Vec<_>>(),
    })
}

/// 任务入口:一个库同时只跑一份(同两种对齐,并行会把端点打出 502)
#[cfg(test)]
pub async fn propose(state: &AppState, kb_id: Uuid) -> anyhow::Result<()> {
    propose_with(state, kb_id, false).await
}

/// `full_glossary` 是测量用的旋钮(`scripts/bench/agent.mjs`):每批都送全部属性的定义,
/// 好和按批裁过的词表在同一批形状上比失败率、重复提案和 token。产品路径不开它
pub async fn propose_with(
    state: &AppState,
    kb_id: Uuid,
    full_glossary: bool,
) -> 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 propose ontology"))?;
    // 提本体是判断题:按端点默认的强度想
    let client = llm_util::chat_client(&settings)
        .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot propose ontology"))?;
    let mut guard = pool.acquire().await?;
    let locked: bool = sqlx::query_scalar(
        "SELECT pg_try_advisory_lock(hashtext('propose_ontology'), hashtext($1))",
    )
    .bind(kb_id.to_string())
    .fetch_one(&mut *guard)
    .await?;
    if !locked {
        tracing::info!(%kb_id, "本体代理已有一份在跑,这次跳过");
        return Ok(());
    }
    let result = propose_locked(state, kb_id, &settings, &client, full_glossary).await;
    let _ = sqlx::query("SELECT pg_advisory_unlock(hashtext('propose_ontology'), hashtext($1))")
        .bind(kb_id.to_string())
        .execute(&mut *guard)
        .await;
    result
}

/// 一条合并后的提案:同一个键在几批里都被提了,形状、类别词、问题并起来,定义取第一次的
struct Merged {
    proposal: agent::Proposal,
    /// Some = 这是「本体里已经有」:relation | attribute | class,进 map_to。
    /// 方向记在每条形状上(同一个属性,"X wrote Y" 反着读、"Y's author X" 正着读)
    map_kind: Option<String>,
    shapes: Vec<Value>,
    phrases: Vec<String>,
    words: Vec<String>,
    /// 复用时代理读到每个类别词的判定是哪一刻定的,同形状上的 `seen_decided_at`
    words_seen: serde_json::Map<String, Value>,
    quotes: Vec<String>,
    serves: Vec<Uuid>,
}

async fn propose_locked(
    state: &AppState,
    kb_id: Uuid,
    settings: &utopia_core::models::LlmSettings,
    client: &utopia_llm::LlmClient,
    full_glossary: bool,
) -> anyhow::Result<()> {
    let pool = &state.pool;
    let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
    let props = utopia_store::ontology::relation_type_views(pool, kb_id).await?;
    let class_key: HashMap<Uuid, &str> = classes.iter().map(|c| (c.id, c.key.as_str())).collect();
    let class_keys: HashSet<&str> = classes.iter().map(|c| c.key.as_str()).collect();
    let prop_keys: HashSet<&str> = props.iter().map(|p| p.key.as_str()).collect();
    let prop_kind: HashMap<&str, &str> = props
        .iter()
        .map(|p| (p.key.as_str(), p.kind.as_str()))
        .collect();
    // 词表的指纹:类键 + 属性键。代理看过没提、或答「已有」的形状,词表不变就不再送
    let basis = {
        let mut keys: Vec<&str> = class_keys.iter().copied().collect();
        keys.sort_unstable();
        let mut pkeys: Vec<&str> = prop_keys.iter().copied().collect();
        pkeys.sort_unstable();
        let digest = Sha256::digest(format!("{}##{}", keys.join(" "), pkeys.join(" ")).as_bytes());
        digest
            .iter()
            .map(|b| format!("{b:02x}"))
            .collect::<String>()
    };

    // 已经提过的(不论表态与否)不再提:采纳的等对齐重判;拒绝的人已经说过不要;
    // 还开着的人还没看。看过没提的和答「已有」的,词表变了才再送(cut 1.1:第一次真跑
    // 120 条里 85 条没进提案,下一轮又排在最前)
    // 看过没提的形状记的是当时的陈述数(basis = "count:n"):陈述数翻倍了才再送——多了一个
    // 属性不必再问代理,对齐自己会拿新属性去重判(0053 指纹),问代理只会每次采纳后把全部
    // 没提的形状再烧一遍。答「已有」的记的是词表指纹:词表变了再送
    let mut proposed_shapes: HashSet<String> = HashSet::new();
    let mut proposed_words: HashSet<String> = HashSet::new();
    let mut declined_shapes: HashMap<String, i64> = HashMap::new();
    let mut declined_words: HashMap<String, i64> = HashMap::new();
    for r in agent_reviews::list(pool, kb_id).await? {
        let word = r.shape.get("kind_word").and_then(Value::as_str);
        if r.outcome == "declined" {
            let seen_count = r
                .basis
                .strip_prefix("count:")
                .and_then(|n| n.parse::<i64>().ok())
                .unwrap_or(1);
            match (r.kind.as_str(), word) {
                ("phrase", _) => {
                    declined_shapes.insert(shape_key(&r.shape), seen_count);
                }
                (_, Some(w)) => {
                    declined_words.insert(w.to_string(), seen_count);
                }
                _ => {}
            }
            continue;
        }
        if r.outcome != "proposed" && r.basis != basis {
            continue;
        }
        match (r.kind.as_str(), word) {
            ("phrase", _) => {
                proposed_shapes.insert(shape_key(&r.shape));
            }
            (_, Some(w)) => {
                proposed_words.insert(w.to_string());
            }
            _ => {}
        }
    }
    for s in utopia_store::ontology::signatures_already_proposed(pool, kb_id).await? {
        for p in s
            .get("phrases")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            proposed_shapes.insert(shape_key(p));
        }
        for w in s
            .get("kind_words")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            if let Some(w) = w.as_str() {
                proposed_words.insert(w.to_string());
            }
        }
    }

    // 没绑上的形状:对齐判成「没有」或「没定」的。还没判的等对齐,不在这里猜
    let sigs = phrase_bindings::signatures(pool, kb_id).await?;
    let bindings: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
        .await?
        .into_iter()
        .map(|b| (b.key(), b))
        .collect();
    let mut open: Vec<&PhraseSignature> = sigs
        .iter()
        .filter(|s| {
            matches!(
                bindings.get(&s.key()).map(|b| b.status.as_str()),
                Some("none" | "undecided")
            )
        })
        .filter(|s| {
            let key = shape_key(&shape_of(s));
            !proposed_shapes.contains(&key)
                && declined_shapes
                    .get(&key)
                    .is_none_or(|seen| s.count >= seen * 2)
        })
        .collect();
    open.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.phrase.cmp(&b.phrase)));
    open.truncate(SIGNATURES_PER_ROUND);

    // 没归类的类别词同理
    let words = type_bindings::signatures(pool, kb_id).await?;
    let word_bindings: HashMap<String, _> = type_bindings::bindings(pool, kb_id)
        .await?
        .into_iter()
        .map(|b| (b.kind_word.clone(), b))
        .collect();
    let mut open_words: Vec<&KindWordSignature> = words
        .iter()
        .filter(|w| {
            matches!(
                word_bindings.get(&w.kind_word).map(|b| b.status.as_str()),
                Some("none" | "undecided")
            )
        })
        .filter(|w| {
            !proposed_words.contains(&w.kind_word)
                && declined_words
                    .get(&w.kind_word)
                    .is_none_or(|seen| w.count >= seen * 2)
        })
        .collect();
    open_words.sort_by(|a, b| {
        b.count
            .cmp(&a.count)
            .then_with(|| a.kind_word.cmp(&b.kind_word))
    });
    let calls = open
        .len()
        .div_ceil(SIGNATURES_PER_CALL)
        .max(open_words.len().div_ceil(KIND_WORDS_PER_CALL));
    if calls == 0 {
        tracing::info!(%kb_id, "本体代理:没有新的形状要看");
        return Ok(());
    }
    open_words.truncate(calls * KIND_WORDS_PER_CALL);

    // 一条问题都没有的库(决定 1):先让代理提问题,人接受了下一轮才算数;这一轮照旧按说法提
    if competency_questions::list(pool, kb_id).await?.is_empty() {
        if let Err(e) = propose_questions_with(state, kb_id, settings, client).await {
            tracing::warn!(%kb_id, error = %e, "本体代理:提问题失败,这一轮不带问题");
        }
    }
    let questions = competency_questions::accepted(pool, kb_id).await?;
    let q_items: Vec<agent::QuestionItem<'_>> = questions
        .iter()
        .enumerate()
        .map(|(i, q)| agent::QuestionItem {
            id: i as i64,
            text: &q.question,
        })
        .collect();
    let q_ids: HashSet<i64> = (0..questions.len() as i64).collect();
    let keys_of = |ids: &[Uuid]| -> Vec<&str> {
        ids.iter()
            .filter_map(|id| class_key.get(id).copied())
            .collect()
    };
    // 词表按批裁(第一次真跑:98 条属性带定义每次调用 4k token,占一次调用的一半多)。
    // 每条形状只给结构对得上的属性定义;对得上的太多就按向量留最近的几条——判据和对齐的
    // 候选、短名单是同一套。其余属性只报键和标签,让模型知道它们在
    let closure =
        crate::phrase_alignment::closures(classes.iter().map(|c| (c.id, c.parents.as_slice())));
    let nearest: Vec<Vec<Uuid>> = {
        let queries: Vec<String> = open
            .iter()
            .map(|s| match (s.examples.first(), s.quotes.first()) {
                (Some(e), Some(q)) => format!("{} · {e} · {q}", s.phrase),
                (Some(e), None) => format!("{} · {e}", s.phrase),
                _ => s.phrase.clone(),
            })
            .collect();
        match crate::ontology_index::nearest_for_each(
            state,
            kb_id,
            &queries,
            GLOSSARY_PER_SHAPE as i64,
            crate::ontology_index::Target::Predicate(None),
        )
        .await
        {
            Ok(v) => v
                .into_iter()
                .map(|cands| cands.into_iter().map(|c| c.id).collect())
                .collect(),
            Err(e) => {
                tracing::warn!(%kb_id, error = %e, "本体代理:形状向量没算出来,词表按结构裁");
                vec![Vec::new(); open.len()]
            }
        }
    };
    let glossary_for = |ids: std::ops::Range<usize>| -> agent::Glossary<'_> {
        let mut full: HashSet<Uuid> = HashSet::new();
        if full_glossary {
            full.extend(props.iter().map(|p| p.id));
        }
        for i in ids {
            let (Some(s), near) = (open.get(i), nearest.get(i)) else {
                continue;
            };
            let fitting: Vec<&RelationTypeView> = props
                .iter()
                .filter(|p| crate::phrase_alignment::structurally_fits(p, s, &closure))
                .collect();
            // 意思最近的几条不管结构对不对得上都给定义:一端没类型、或宾语是字面值的形状,
            // 结构上对不上 positionHeld / workLocation,模型看不到定义就把它们又提了一遍
            // (受控对比里重复提案 1% → 6%,十条里七条是这样来的)
            if let Some(near) = near {
                full.extend(near.iter().take(GLOSSARY_NEAREST_ANYWAY).copied());
            }
            if fitting.len() > GLOSSARY_PER_SHAPE {
                if let Some(near) = near.filter(|n| !n.is_empty()) {
                    full.extend(
                        fitting
                            .iter()
                            .filter(|p| near.contains(&p.id))
                            .map(|p| p.id),
                    );
                    continue;
                }
            }
            full.extend(fitting.iter().map(|p| p.id));
        }
        agent::Glossary {
            classes: classes
                .iter()
                .map(|c| (c.key.as_str(), c.label.as_str(), c.description.as_str()))
                .collect(),
            properties: props
                .iter()
                .filter(|p| full.contains(&p.id))
                .map(|p| {
                    (
                        p.key.as_str(),
                        p.label.as_str(),
                        p.kind.as_str(),
                        keys_of(&p.domains),
                        keys_of(&p.ranges),
                        p.description.as_str(),
                    )
                })
                .collect(),
            others: props
                .iter()
                .filter(|p| !full.contains(&p.id))
                .map(|p| (p.key.as_str(), p.label.as_str()))
                .collect(),
        }
    };
    let sig_items: Vec<agent::OpenSignature<'_>> = open
        .iter()
        .enumerate()
        .map(|(i, s)| agent::OpenSignature {
            id: i as i64,
            phrase: &s.phrase,
            subject_class: s.subject_type_key.as_deref(),
            object_class: s.object_type_key.as_deref(),
            object_is_value: s.object_is_value,
            statement_count: s.count,
            examples: &s.examples,
            quotes: &s.quotes,
        })
        .collect();
    let word_items: Vec<agent::OpenKindWord<'_>> = open_words
        .iter()
        .enumerate()
        .map(|(i, w)| agent::OpenKindWord {
            id: i as i64,
            kind_word: &w.kind_word,
            count: w.count,
            examples: &w.examples,
            phrases: &w.phrases,
        })
        .collect();
    tracing::info!(%kb_id, shapes = open.len(), kind_words = open_words.len(), questions = questions.len(), calls, "本体代理开始");
    // 复用提案记下代理读到的判定是哪一刻定的:采纳时人的判定不是那一刻的,就是代理读过之后定的,
    // 复用不替人改。不拿提案行存入的时刻比:那在全部模型调用之后,下一轮并进同一行时还会再挪
    let seen_shape = |s: &PhraseSignature| bindings.get(&s.key()).map(|b| b.decided_at);
    let seen_word = |w: &KindWordSignature| word_bindings.get(&w.kind_word).map(|b| b.decided_at);

    let mut merged: HashMap<String, Merged> = HashMap::new();
    let mut order: Vec<String> = Vec::new();
    // 这一轮看过的每条形状的去向(调用失败的批次不记,下一轮再送)
    let mut reviews: Vec<Review> = Vec::new();
    let (mut failed, mut malformed, mut skipped_existing) = (0usize, 0usize, 0usize);
    for b in 0..calls {
        let sig_batch = sig_items
            .get(b * SIGNATURES_PER_CALL..)
            .map(|rest| &rest[..rest.len().min(SIGNATURES_PER_CALL)])
            .unwrap_or(&[]);
        let word_batch = word_items
            .get(b * KIND_WORDS_PER_CALL..)
            .map(|rest| &rest[..rest.len().min(KIND_WORDS_PER_CALL)])
            .unwrap_or(&[]);
        let sig_ids: HashSet<i64> = sig_batch.iter().map(|s| s.id).collect();
        let word_ids: HashSet<i64> = word_batch.iter().map(|w| w.id).collect();
        let glossary = glossary_for(b * SIGNATURES_PER_CALL..(b + 1) * SIGNATURES_PER_CALL);
        let messages = agent::build_proposal_messages(sig_batch, word_batch, &glossary, &q_items);
        let reply =
            match chat_retrying_rate_limits_at(state, settings, client, &messages, Some(0.0)).await
            {
                Ok(r) => r,
                Err(e) => {
                    if utopia_core::error::is_terminal(&e) {
                        return Err(e);
                    }
                    failed += 1;
                    tracing::warn!(%kb_id, batch = b, error = %e, "本体代理:这一批调用失败");
                    continue;
                }
            };
        let parsed = match agent::parse_proposal_response(&reply.text, &sig_ids, &word_ids, &q_ids)
        {
            Ok(p) => p,
            Err(e) => {
                failed += 1;
                tracing::warn!(%kb_id, batch = b, error = %e, "本体代理:回复读不出");
                continue;
            }
        };
        malformed += parsed.malformed;
        for why in &parsed.reasons {
            tracing::warn!(%kb_id, batch = b, why = %why, "本体代理:坏项");
        }
        let mut sig_outcome: HashMap<i64, (&str, String)> = HashMap::new();
        let mut word_outcome: HashMap<i64, (&str, String)> = HashMap::new();
        // 「本体里已经有」:存成 map_to 提案,人点「用已有的」就是一次人的绑定判定
        for e in &parsed.existing {
            let map_kind = if let Some(k) = prop_kind.get(e.key.as_str()) {
                (*k).to_string()
            } else if class_keys.contains(e.key.as_str()) {
                "class".to_string()
            } else {
                malformed += 1;
                tracing::warn!(%kb_id, batch = b, why = %format!("existing: no such key in the ontology: {}", e.key), "本体代理:坏项");
                continue;
            };
            let slot = format!("map_to:{}", e.key);
            let entry = merged.entry(slot.clone()).or_insert_with(|| {
                order.push(slot);
                Merged {
                    proposal: agent::Proposal {
                        kind: "existing".into(),
                        key: e.key.clone(),
                        label: e.key.clone(),
                        definition: String::new(),
                        value: false,
                        datatype: None,
                        domains: Vec::new(),
                        ranges: Vec::new(),
                        parents: Vec::new(),
                        signatures: Vec::new(),
                        kind_words: Vec::new(),
                        questions: Vec::new(),
                    },
                    map_kind: Some(map_kind),
                    shapes: Vec::new(),
                    phrases: Vec::new(),
                    words: Vec::new(),
                    words_seen: serde_json::Map::new(),
                    quotes: Vec::new(),
                    serves: Vec::new(),
                }
            });
            if map_kind_is_class(entry) {
                // 类接的是类别词;形状指给类是答错了格,不记
                for id in &e.kind_words {
                    if let Some(w) = open_words.get(*id as usize) {
                        push_word(entry, w, seen_word(w));
                        word_outcome.insert(*id, ("existing", e.key.clone()));
                    }
                }
            } else {
                for id in &e.signatures {
                    if let Some(sig) = open.get(*id as usize) {
                        push_shape(entry, sig, e.direction.as_deref(), seen_shape(sig));
                        sig_outcome.insert(*id, ("existing", e.key.clone()));
                    }
                }
            }
        }
        for p in parsed.proposals {
            // 模型被告知已有的不要提;还是提了就当它没说(对齐那边会把形状挂上去)
            let taken = match p.kind.as_str() {
                "class" => class_keys.contains(p.key.as_str()),
                _ => prop_keys.contains(p.key.as_str()),
            };
            if taken {
                skipped_existing += 1;
                continue;
            }
            let slot = format!("{}:{}", p.kind, p.key);
            let entry = merged.entry(slot.clone()).or_insert_with(|| {
                order.push(slot);
                Merged {
                    proposal: agent::Proposal {
                        signatures: Vec::new(),
                        kind_words: Vec::new(),
                        questions: Vec::new(),
                        ..p.clone()
                    },
                    map_kind: None,
                    shapes: Vec::new(),
                    phrases: Vec::new(),
                    words: Vec::new(),
                    words_seen: serde_json::Map::new(),
                    quotes: Vec::new(),
                    serves: Vec::new(),
                }
            });
            let target = format!("{}:{}", section_of(&p), p.key);
            // 新元素不记读到的时刻:采纳它不替换哪条判定,这一格没人读
            for id in p.signatures {
                let Some(s) = open.get(id as usize) else {
                    continue;
                };
                push_shape(entry, s, None, None);
                sig_outcome.insert(id, ("proposed", target.clone()));
            }
            for id in p.kind_words {
                let Some(w) = open_words.get(id as usize) else {
                    continue;
                };
                push_word(entry, w, None);
                word_outcome.insert(id, ("proposed", target.clone()));
            }
            for id in p.questions {
                let Some(q) = questions.get(id as usize) else {
                    continue;
                };
                if !entry.serves.contains(&q.id) {
                    entry.serves.push(q.id);
                }
            }
        }
        for si in sig_batch {
            let (outcome, target) = sig_outcome
                .get(&si.id)
                .map(|(o, t)| (*o, Some(t.clone())))
                .unwrap_or(("declined", None));
            reviews.push(Review {
                kind: "phrase".into(),
                shape: shape_of(open[si.id as usize]),
                outcome: outcome.into(),
                target,
                basis: if outcome == "declined" {
                    format!("count:{}", open[si.id as usize].count)
                } else {
                    basis.clone()
                },
            });
        }
        for wi in word_batch {
            let (outcome, target) = word_outcome
                .get(&wi.id)
                .map(|(o, t)| (*o, Some(t.clone())))
                .unwrap_or(("declined", None));
            reviews.push(Review {
                kind: "kind_word".into(),
                shape: json!({ "kind_word": wi.kind_word }),
                outcome: outcome.into(),
                target,
                basis: if outcome == "declined" {
                    format!("count:{}", wi.count)
                } else {
                    basis.clone()
                },
            });
        }
    }

    let items: Vec<utopia_store::ontology::AgentProposal> = order
        .iter()
        .filter_map(|slot| merged.get(slot))
        .filter(|m| !m.shapes.is_empty() || !m.words.is_empty())
        .map(|m| {
            let p = &m.proposal;
            if let Some(map_kind) = &m.map_kind {
                let label = if map_kind == "class" {
                    classes
                        .iter()
                        .find(|c| c.key == p.key)
                        .map(|c| c.label.as_str())
                } else {
                    props
                        .iter()
                        .find(|r| r.key == p.key)
                        .map(|r| r.label.as_str())
                };
                return utopia_store::ontology::AgentProposal {
                    section: "map_to".into(),
                    key: p.key.clone(),
                    payload: json!({
                        "key": p.key,
                        "label": label.unwrap_or(p.key.as_str()),
                        "kind": map_kind,
                        "forms": m.phrases,
                        "kind_words": m.words,
                        "examples": m.quotes,
                        "proposed_by": "agent",
                    }),
                    serves: Vec::new(),
                    signatures: json!({ "phrases": m.shapes, "kind_words": m.words,
                                        "kind_words_seen_decided_at": m.words_seen }),
                };
            }
            let section = section_of(p);
            let mut payload = json!({
                "key": p.key,
                "label": p.label,
                "description": p.definition,
                "forms": m.phrases,
                "kind_words": m.words,
                "examples": m.quotes,
                "proposed_by": "agent",
            });
            match section {
                "entity_types" => {
                    payload["parents"] = json!(p.parents);
                }
                "attribute_types" => {
                    payload["datatype"] = json!(datatype_or_text(p.datatype.as_deref()));
                    payload["domains"] = json!(p.domains);
                }
                _ => {
                    payload["temporal"] = json!("state");
                    payload["domains"] = json!(p.domains);
                    payload["ranges"] = json!(p.ranges);
                }
            }
            utopia_store::ontology::AgentProposal {
                section: section.to_string(),
                key: p.key.clone(),
                payload,
                serves: m.serves.clone(),
                signatures: json!({ "phrases": m.shapes, "kind_words": m.words }),
            }
        })
        .collect();
    // 同一个目标上一轮已经答过一批形状:并起来,不是盖掉(第一次真跑第三轮盖掉了第二轮的)
    let mut items = items;
    // 每条新元素带上本体里离它最近的两个已有元素(按向量,不问模型)。裁过的词表下模型看不到
    // 大部分属性的定义,受控对比里重复或反向已有属性的提案从 1% 升到 5%(awardReceived、
    // performer 这几条);审的人要在采纳前看见"它最像谁"
    for class_side in [false, true] {
        let idx: Vec<usize> = items
            .iter()
            .enumerate()
            .filter(|(_, it)| {
                it.section != "map_to" && (it.section == "entity_types") == class_side
            })
            .map(|(i, _)| i)
            .collect();
        let queries: Vec<String> = idx
            .iter()
            .map(|i| {
                let p = &items[*i].payload;
                format!(
                    "{} · {}",
                    p.get("label").and_then(Value::as_str).unwrap_or(""),
                    p.get("description").and_then(Value::as_str).unwrap_or("")
                )
            })
            .collect();
        let target = if class_side {
            crate::ontology_index::Target::Class
        } else {
            crate::ontology_index::Target::Predicate(None)
        };
        match crate::ontology_index::nearest_for_each(state, kb_id, &queries, 2, target).await {
            Ok(found) => {
                for (i, cands) in idx.into_iter().zip(found) {
                    items[i].payload["closest"] = json!(cands
                        .iter()
                        .map(|c| json!({ "key": c.key, "label": c.label, "distance": c.distance }))
                        .collect::<Vec<_>>());
                }
            }
            Err(e) => {
                tracing::warn!(%kb_id, error = %e, "本体代理:最近的已有元素没算出来,提案不带这一格");
            }
        }
    }
    for it in items.iter_mut().filter(|it| it.section == "map_to") {
        if let Some(prev) =
            utopia_store::ontology::open_proposal(pool, kb_id, "map_to", &it.key).await?
        {
            merge_map_to(it, &prev);
        }
    }
    utopia_store::ontology::save_agent_proposals(pool, kb_id, &items).await?;
    agent_reviews::record(pool, kb_id, &reviews).await?;
    tracing::info!(%kb_id, proposals = items.len(), failed, malformed, skipped_existing, calls, glossary = if full_glossary { "full" } else { "trimmed" }, "本体代理结束");
    if !items.is_empty() {
        state.emit_pending(kb_id);
    }
    Ok(())
}

fn section_of(p: &agent::Proposal) -> &'static str {
    match (p.kind.as_str(), p.value) {
        ("class", _) => "entity_types",
        (_, true) => "attribute_types",
        _ => "relation_types",
    }
}

fn map_kind_is_class(m: &Merged) -> bool {
    m.map_kind.as_deref() == Some("class")
}

/// 形状的身份写成一个键:短语 + 两端的类键 + 宾语是不是字面值(方向不算——
/// map_to 里的形状带方向,比身份时得去掉)
fn shape_key(v: &Value) -> String {
    json!({
        "phrase": v.get("phrase"),
        "subject": v.get("subject"),
        "object": v.get("object"),
        "value": v.get("value"),
    })
    .to_string()
}

/// 形状的身份:短语 + 两端的类键 + 宾语是不是字面值(方向不算)
fn same_shape(a: &Value, b: &Value) -> bool {
    ["phrase", "subject", "object", "value"]
        .iter()
        .all(|k| a.get(k) == b.get(k))
}

fn push_shape(
    entry: &mut Merged,
    s: &PhraseSignature,
    direction: Option<&str>,
    seen: Option<DateTime<Utc>>,
) {
    let mut shape = shape_of(s);
    if let Some(d) = direction {
        shape["direction"] = json!(d);
    }
    if let Some(at) = seen {
        shape["seen_decided_at"] = json!(at);
    }
    if entry.shapes.iter().any(|x| same_shape(x, &shape)) {
        return;
    }
    entry.shapes.push(shape);
    if !entry.phrases.contains(&s.phrase) {
        entry.phrases.push(s.phrase.clone());
    }
    for q in s.quotes.iter().take(1) {
        if entry.quotes.len() < 3 && !entry.quotes.contains(q) {
            entry.quotes.push(q.clone());
        }
    }
}

fn push_word(entry: &mut Merged, w: &KindWordSignature, seen: Option<DateTime<Utc>>) {
    if entry.words.contains(&w.kind_word) {
        return;
    }
    entry.words.push(w.kind_word.clone());
    if let Some(at) = seen {
        entry.words_seen.insert(w.kind_word.clone(), json!(at));
    }
    for e in w.examples.iter().take(1) {
        if entry.quotes.len() < 3 && !entry.quotes.contains(e) {
            entry.quotes.push(e.clone());
        }
    }
}

/// 把上一轮开着的 map_to 行并进这一轮的:形状、说法、类别词、例句取并集,先前的在前
fn merge_map_to(
    it: &mut utopia_store::ontology::AgentProposal,
    prev: &utopia_store::ontology::StoredProposal,
) {
    let mut shapes: Vec<Value> = prev
        .signatures
        .get("phrases")
        .and_then(Value::as_array)
        .cloned()
        .unwrap_or_default();
    for s in it
        .signatures
        .get("phrases")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        if !shapes.iter().any(|x| same_shape(x, s)) {
            shapes.push(s.clone());
        }
    }
    let union = |field: &str, from_payload: bool| -> Vec<String> {
        let (a, b) = if from_payload {
            (prev.payload.get(field), it.payload.get(field))
        } else {
            (prev.signatures.get(field), it.signatures.get(field))
        };
        let mut out = strings(a);
        for x in strings(b) {
            if !out.contains(&x) {
                out.push(x);
            }
        }
        out
    };
    let words = union("kind_words", false);
    let forms = union("forms", true);
    let examples: Vec<String> = union("examples", true).into_iter().take(3).collect();
    // 形状带着各自读到的时刻并过来了;类别词的另存一格,也要并。只留这一轮的,上一轮的词就
    // 没了读到的时刻,采纳时连代理读过的那个人的判定也不替换了
    let seen_of = |signatures: &Value| {
        signatures
            .get("kind_words_seen_decided_at")
            .and_then(Value::as_object)
            .cloned()
            .unwrap_or_default()
    };
    let mut words_seen = seen_of(&prev.signatures);
    for (w, at) in seen_of(&it.signatures) {
        words_seen.entry(w).or_insert(at);
    }
    it.payload["forms"] = json!(forms);
    it.payload["kind_words"] = json!(words);
    it.payload["examples"] = json!(examples);
    it.signatures = json!({ "phrases": shapes, "kind_words": words,
                            "kind_words_seen_decided_at": words_seen });
}

fn datatype_or_text(d: Option<&str>) -> &str {
    match d {
        Some(d @ ("text" | "number" | "date" | "bool")) => d,
        _ => "text",
    }
}

/// 采纳时人改过的几格。None = 照提案
#[derive(Debug, Default, Deserialize)]
pub struct AdoptEdits {
    pub label: Option<String>,
    pub description: Option<String>,
    pub datatype: Option<String>,
    pub domains: Option<Vec<String>>,
    pub ranges: Option<Vec<String>>,
    pub parents: Option<Vec<String>>,
}

fn strings(v: Option<&Value>) -> Vec<String> {
    v.and_then(Value::as_array)
        .into_iter()
        .flatten()
        .filter_map(|x| x.as_str().map(str::to_string))
        .collect()
}

/// 采纳的回执
#[derive(Debug)]
pub struct Adopted {
    /// 新元素的 id;复用时是目标的 id
    pub id: Uuid,
    /// 复用时留着没写的形状或类别词,各带人定成了什么:代理读过之后人另定了、和提案不一样的。
    /// 两个人的判断不一样,采纳的人得看见,所以列出来而不是悄悄跳过
    pub skipped: Vec<Value>,
}

/// 一条绑定此刻的判定:谁、什么时候定的、定成了什么(比的时候用 id,回执里写键)
#[derive(sqlx::FromRow)]
struct Decided {
    decided_by: String,
    decided_at: DateTime<Utc>,
    status: String,
    target_id: Option<Uuid>,
    target: Option<String>,
    #[sqlx(default)]
    direction: Option<String>,
}

impl Decided {
    /// 人在代理读过它之后定的。提案答的是代理读到的那个判定,那个照样替掉;之后人定的,提案和
    /// 采纳的人看的卡片都没见过,不替人改。只看是不是代理读到的那一刻,不比先后:`decided_at`
    /// 是定它的事务开始的时刻,先开始、后提交的人的判定,时刻会早于代理读到的那个。没记下读到
    /// 哪一刻的(这一格之前存的提案),人的判定一概不改
    fn by_person_after_read(&self, read: Option<DateTime<Utc>>) -> bool {
        self.decided_by == "person" && read.is_none_or(|at| at != self.decided_at)
    }

    /// 和提案定得一样:绑到同一个属性、同一个方向,或同一个类(类别词没有方向)
    fn agrees(&self, target: Uuid, direction: Option<&str>) -> bool {
        self.status == "bound"
            && self.target_id == Some(target)
            && self.direction.as_deref() == direction
    }
}

/// 代理读到这条判定时它的 `decided_at`(`push_shape`、`push_word` 记下的)
fn read_at(seen: Option<&Value>) -> Option<DateTime<Utc>> {
    seen.and_then(|v| serde_json::from_value(v.clone()).ok())
}

/// 采纳一条代理提案(0061 决定 3):锁住提案,在一个事务里重读并锁住它要的类或复用的目标,
/// 写元素(复用时写人的判定)、回归用例、采纳的状态和后续任务,一次提交。
///
/// 从前这几步各自提交:属性先落库,例句写回归用例时才发现宾语是实体(`bad_property_shape`),
/// 留下一个没有提案采纳过的属性、一份排着的对齐,和一条键已被占、再也采纳不了的提案
pub async fn adopt(
    state: &AppState,
    kb_id: Uuid,
    section: &str,
    key: &str,
    edits: AdoptEdits,
    actor: Uuid,
) -> Result<Adopted, AppError> {
    let pool = &state.pool;
    let mut tx = pool.begin().await?;
    let (adopted, detail) = match adopt_on(&mut tx, kb_id, section, key, edits, actor).await {
        Ok(done) => done,
        Err(error) => {
            // 回滚完再答:马上重试的请求不会撞上这次还没放掉的锁
            if let Err(rollback) = tx.rollback().await {
                return Err(AppError::Other(
                    anyhow::Error::new(error)
                        .context(format!("rolling back an adoption: {rollback}")),
                ));
            }
            return Err(busy(error));
        }
    };
    tx.commit().await?;
    let _ = utopia_store::audit::record(
        pool,
        Some(kb_id),
        actor,
        "ontology_proposal.adopted",
        section.trim_end_matches('s'),
        Some(adopted.id),
        detail,
    )
    .await;
    state.emit_graph(kb_id);
    if section == "map_to" {
        state.emit_review(kb_id);
    }
    Ok(adopted)
}

/// 采纳和别的写撞上、整个事务回滚了,什么都没留下,重试是安全的:答审核页认得、可以重试的
/// `alignment_busy`。死锁(40P01)在这个事务的哪一步碰上都这样答(比如复用类按词改实体时,
/// 和先改留下的、再改并掉的实体合并互相等),话里也不指认是谁在改。等锁超时(55P03)只出在
/// 复用类那一段(只有它设了 `lock_timeout`),照审核页定类别词时的话答
fn busy(error: AppError) -> AppError {
    if matches!(&error, AppError::Db(sqlx::Error::Database(e))
        if e.code().as_deref() == Some("40P01"))
    {
        return AppError::CodedConflict {
            code: "alignment_busy",
            message: "Another change touched what this adoption writes; nothing was saved. Please try again."
                .into(),
        };
    }
    type_bindings::busy_on_lock_timeout(error)
}

/// 按键找到这些类,锁住防删(FOR KEY SHARE),返回的 id 和键一一对应:采纳提交之前它们删不掉,
/// 正被删的等删完再答 `unknown_class`,不会写父类、定义域时才撞上外键答 500。按 id 的顺序锁。
///
/// 不用 FOR SHARE:那会挡住这几行上的每一次 UPDATE。补向量的任务(`set_type_embeddings`)在
/// 一个事务里按堆的顺序改一批类,和按 id 顺序的 FOR SHARE 互相等成死锁。采纳只读 id,防删就够了
async fn lock_classes(
    tx: &mut Transaction<'_, Postgres>,
    kb_id: Uuid,
    keys: &[String],
) -> Result<Vec<Uuid>, AppError> {
    let found: Vec<(String, Uuid)> = sqlx::query_as(
        "SELECT key, id FROM entity_types WHERE kb_id = $1 AND key = ANY($2)
          ORDER BY id FOR KEY SHARE",
    )
    .bind(kb_id)
    .bind(keys)
    .fetch_all(&mut **tx)
    .await?;
    keys.iter()
        .map(|k| {
            found
                .iter()
                .find(|(key, _)| key == k)
                .map(|(_, id)| *id)
                .ok_or_else(|| {
                    AppError::invalid("unknown_class", format!("class `{k}` does not exist"))
                })
        })
        .collect()
}

/// 采纳锁住的那一行
#[derive(sqlx::FromRow)]
struct Locked {
    id: Uuid,
    #[sqlx(flatten)]
    proposal: StoredProposal,
}

/// 采纳在事务里的全部;返回回执和审计要记的几格
async fn adopt_on(
    tx: &mut Transaction<'_, Postgres>,
    kb_id: Uuid,
    section: &str,
    key: &str,
    edits: AdoptEdits,
    actor: Uuid,
) -> Result<(Adopted, Value), AppError> {
    // 先锁提案:同一条的另一次采纳、拒绝和代理的刷新都等这次提交,提交后它已不再开着。
    // 只认代理提的:旧 Suggest 留下的提案没有采纳的入口
    let locked: Option<Locked> = sqlx::query_as(
        "SELECT id, section, key, payload, proposed_by, serves, signatures
           FROM ontology_proposals
          WHERE kb_id = $1 AND section = $2 AND key = $3 AND status = 'open' AND proposed_by = 'agent'
            FOR UPDATE",
    )
    .bind(kb_id)
    .bind(section)
    .bind(key)
    .fetch_optional(&mut **tx)
    .await?;
    let Some(locked) = locked else {
        return Err(AppError::NotFound);
    };
    let p = &locked.proposal;
    // 人改过几格:决定 5 的第二个数要它
    let edited = edits.label.is_some()
        || edits.description.is_some()
        || edits.datatype.is_some()
        || edits.domains.is_some()
        || edits.ranges.is_some()
        || edits.parents.is_some();
    let label = edits
        .label
        .as_deref()
        .map(str::trim)
        .filter(|s| !s.is_empty())
        .or_else(|| p.payload.get("label").and_then(Value::as_str))
        .unwrap_or(key)
        .to_string();
    let description = edits
        .description
        .as_deref()
        .or_else(|| p.payload.get("description").and_then(Value::as_str))
        .unwrap_or("")
        .trim()
        .to_string();
    let mut skipped = Vec::new();
    let id = match section {
        // 「用已有的」:形状各写一条人的绑定判定(同审核页),类别词各归到那个类
        "map_to" => adopt_map_to(tx, kb_id, p, &mut skipped).await?,
        "entity_types" => {
            let parents = lock_classes(
                tx,
                kb_id,
                &edits
                    .parents
                    .unwrap_or_else(|| strings(p.payload.get("parents"))),
            )
            .await?;
            let id = utopia_store::ontology::create_entity_type(
                &mut **tx,
                kb_id,
                key,
                &label,
                utopia_store::palette::color_for_key(key),
                "circle",
                &parents,
                &description,
            )
            .await?;
            // 多了一个类:类别词里「没有」「没定」的要重判,短语对齐跟在它后面
            embed_then_align(tx, kb_id, "align_types").await?;
            id
        }
        "relation_types" | "attribute_types" => {
            let kind = if section == "attribute_types" {
                "attribute"
            } else {
                "relation"
            };
            let domains = edits
                .domains
                .unwrap_or_else(|| strings(p.payload.get("domains")));
            let ranges = if kind == "relation" {
                edits
                    .ranges
                    .unwrap_or_else(|| strings(p.payload.get("ranges")))
            } else {
                Vec::new()
            };
            // 定义域和值域一次锁上,整批按 id 排序
            let classes = lock_classes(tx, kb_id, &[domains.as_slice(), &ranges].concat()).await?;
            let (domains, ranges) = classes.split_at(domains.len());
            let datatype = if kind == "attribute" {
                Some(
                    datatype_or_text(
                        edits
                            .datatype
                            .as_deref()
                            .or_else(|| p.payload.get("datatype").and_then(Value::as_str)),
                    )
                    .to_string(),
                )
            } else {
                None
            };
            let id = utopia_store::ontology::create_relation_type(
                &mut **tx,
                kb_id,
                key,
                &label,
                "state",
                RelationAxioms::default(),
                &description,
                kind,
                domains,
                ranges,
                datatype.as_deref(),
                None,
            )
            .await?;
            // 多了一个属性:判成 none / undecided 的形状也许对得上了(0053 的指纹变了)
            embed_then_align(tx, kb_id, "align_phrases").await?;
            id
        }
        _ => {
            return Err(AppError::invalid(
                "bad_section",
                "section 只能是 map_to、entity_types、relation_types 或 attribute_types",
            ))
        }
    };
    finish_adoption(tx, kb_id, &locked, id, actor, edited, &skipped).await?;
    let detail =
        json!({ "key": key, "label": label, "proposed_by": p.proposed_by, "serves": p.serves });
    Ok((Adopted { id, skipped }, detail))
}

/// 新元素的后续任务,和元素一起提交:先补向量、再对齐,同编辑器的次序。新元素要有向量,对齐
/// 的短名单才看得见它(候选多于短名单长度时按向量挑;没向量的属性永远进不了名单,形状的指纹
/// 就不变,采纳了也不重判——第一次真跑 bordered_by 就是这样)。从前采纳在请求里就地嵌
/// (cut 1.1),现在对齐开跑时看见补向量的还排着或跑着就等它(`align_*_reasking`)。
/// 两份都照排,不看有没有同样的排着:排着的那份可能在这次提交之前就被领走,读的是还没有这个
/// 元素的本体(0051)
async fn embed_then_align(
    tx: &mut Transaction<'_, Postgres>,
    kb_id: Uuid,
    align: &str,
) -> Result<(), AppError> {
    let payload = json!({ "kb_id": kb_id });
    utopia_store::jobs::enqueue_with_max_attempts_tx(tx, "embed_ontology", payload.clone(), 3)
        .await?;
    // 对齐晚几秒到期,同编辑器(补向量 2 秒后、对齐 5 秒后)。两份同时到期的话 worker 一起
    // 领走,对齐看见补向量正跑着,就把自己挪到半分钟后。补向量更慢时照样等它
    utopia_store::jobs::enqueue_with_max_attempts_after_tx(
        tx,
        align,
        payload,
        3,
        std::time::Duration::from_secs(5),
    )
    .await?;
    Ok(())
}

/// 回归用例和采纳的状态(决定 4),在采纳的事务里。人改过没有(决定 5 的第二个数)和状态同一条
/// UPDATE 写下:从前是采纳提交之后的另一条语句。复用留着没写的形状(`skipped`)不写用例:人定得
/// 和提案不一样;人后来定得一样的照写
async fn finish_adoption(
    tx: &mut Transaction<'_, Postgres>,
    kb_id: Uuid,
    locked: &Locked,
    property_id: Uuid,
    actor: Uuid,
    edited: bool,
    skipped: &[Value],
) -> Result<(), AppError> {
    let proposal = &locked.proposal;
    let mut examples = Vec::new();
    let property = matches!(
        proposal.section.as_str(),
        "relation_types" | "attribute_types"
    ) || (proposal.section == "map_to"
        && proposal.payload.get("kind").and_then(Value::as_str) != Some("class"));
    if property {
        for shape in proposal
            .signatures
            .get("phrases")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
            .filter(|shape| !skipped.iter().any(|s| same_shape(s, shape)))
        {
            let ids = match shape.get("example_statement_ids") {
                Some(ids) => serde_json::from_value::<Vec<Uuid>>(ids.clone()).map_err(|_| {
                    AppError::invalid("invalid_examples", "Invalid proposal statement identities.")
                })?,
                None => Vec::new(),
            };
            let direction = match shape.get("direction").and_then(Value::as_str) {
                Some("reverse") => "reverse",
                _ => "forward",
            };
            examples.extend(ids.into_iter().map(|statement| (statement, direction)));
        }
    }
    for (statement_id, direction) in examples {
        // Removed examples cannot be checked; never substitute another statement.
        let live: Option<Uuid> = sqlx::query_scalar("SELECT id FROM facts WHERE kb_id=$1 AND id=$2 AND layer='open' AND invalidated_at IS NULL FOR SHARE")
            .bind(kb_id).bind(statement_id).fetch_optional(&mut **tx).await?;
        if live.is_none() {
            continue;
        }
        utopia_store::ontology_regressions::add_on(
            tx,
            kb_id,
            utopia_store::ontology_regressions::NewCase {
                statement_id,
                expected_property_id: property_id,
                expected_direction: direction,
                created_by: actor,
                origin: "adoption",
            },
        )
        .await?;
    }
    sqlx::query(
        "UPDATE ontology_proposals SET status='adopted',decided_by=$2,decided_at=now(),edited=edited OR $3 WHERE id=$1",
    )
    .bind(locked.id)
    .bind(actor)
    .bind(edited)
    .execute(&mut **tx)
    .await?;
    Ok(())
}

/// map_to 的采纳,在采纳的事务里:目标是属性,提案里的每条形状写成人的绑定(属性 + 方向),
/// 投影跟着排(同审核页的 `decide_alignment_phrase`);目标是类,每个类别词归到它,短语对齐
/// 跟着排。返回目标的 id。
///
/// 代理读过之后人另定了的形状或类别词不写:和提案一样的算已写(形状照样有回归用例),不一样的
/// 原样留着、记进 `skipped`。一条也写不了的不算采纳
async fn adopt_map_to(
    tx: &mut Transaction<'_, Postgres>,
    kb_id: Uuid,
    p: &StoredProposal,
    skipped: &mut Vec<Value>,
) -> Result<Uuid, AppError> {
    let kind = p
        .payload
        .get("kind")
        .and_then(Value::as_str)
        .unwrap_or("relation");
    // 这次写下的;人在代理读过之后定得和提案一样、算作已写的
    let (mut written, mut agreed) = (0usize, 0usize);
    if kind == "class" {
        let class = lock_classes(tx, kb_id, std::slice::from_ref(&p.key)).await?[0];
        // 实体正被抽取或对齐改着时只等 2 秒,同审核页的类别词判定
        sqlx::query("SET LOCAL lock_timeout = '2s'")
            .execute(&mut **tx)
            .await?;
        let votes = json!({ "person": p.key, "via": "ontology_agent" });
        let seen = p.signatures.get("kind_words_seen_decided_at");
        for w in strings(p.signatures.get("kind_words")) {
            // 已有的绑定行先锁住再看:看过之后、写下之前,人改不了它。还没有这一行时锁不住,
            // 人第一次定它可能被这次写盖掉。类的键用子查询读,不连表:等到别人提交了这一行,
            // Postgres 拿新版本重算这条查询,连表连上的却还是等之前那一行(EvalPlanQual),
            // 回执里人刚定的类就成了空
            let now: Option<Decided> = sqlx::query_as(
                "SELECT b.decided_by, b.decided_at, b.status, b.type_id AS target_id,
                        (SELECT t.key FROM entity_types t WHERE t.id = b.type_id) AS target
                   FROM type_bindings b
                  WHERE b.kb_id = $1 AND b.kind_word = $2 FOR UPDATE OF b",
            )
            .bind(kb_id)
            .bind(type_bindings::normalize(&w))
            .fetch_optional(&mut **tx)
            .await?;
            let read = read_at(seen.and_then(|s| s.get(w.as_str())));
            if let Some(d) = now.filter(|d| d.by_person_after_read(read)) {
                if d.agrees(class, None) {
                    // 不重写:判定还是那个人的
                    agreed += 1;
                } else {
                    skipped.push(json!({ "kind_word": w,
                                         "person": { "status": d.status, "class": d.target } }));
                }
                continue;
            }
            if type_bindings::decide_and_apply_human_tx(tx, kb_id, &w, Some(class), &votes).await? {
                written += 1;
            }
        }
        if written + agreed == 0 {
            return Err(nothing_left());
        }
        // 换了类,这些实体的短语签名跟着变:短语对齐和判定一起提交,整次采纳排一份;一个词都没写
        // 就不排,人定的那次已经排过。照排,不看有没有同样的排着,理由同 `embed_then_align`:
        // 排着的那份可能在这次提交之前就被领走
        if written > 0 {
            utopia_store::jobs::enqueue_with_max_attempts_tx(
                tx,
                "align_phrases",
                json!({ "kb_id": kb_id }),
                3,
            )
            .await?;
        }
        return Ok(class);
    }
    // 目标在事务里重读并锁住防删(FOR KEY SHARE,理由同 `lock_classes`):采纳提交之前它删不掉
    let property: Option<Uuid> = sqlx::query_scalar(
        "SELECT id FROM relation_types WHERE kb_id = $1 AND key = $2 FOR KEY SHARE",
    )
    .bind(kb_id)
    .bind(&p.key)
    .fetch_optional(&mut **tx)
    .await?;
    let property = property
        .ok_or_else(|| AppError::invalid("unknown_property", "no property with that key"))?;
    let sigs = phrase_bindings::signatures(&mut **tx, kb_id).await?;
    for shape in p
        .signatures
        .get("phrases")
        .and_then(Value::as_array)
        .into_iter()
        .flatten()
    {
        // 此刻已经没有陈述的形状跳过。方向是这条形状自己的
        let Some(sig) = sigs.iter().find(|s| same_shape(&shape_of(s), shape)) else {
            continue;
        };
        let direction = match shape.get("direction").and_then(Value::as_str) {
            Some("reverse") => "reverse",
            _ => "forward",
        };
        // 已有的绑定行先锁住再看,属性的键用子查询读,同类别词
        let now: Option<Decided> = sqlx::query_as(
            "SELECT b.decided_by, b.decided_at, b.status, b.relation_type_id AS target_id,
                    (SELECT r.key FROM relation_types r WHERE r.id = b.relation_type_id) AS target,
                    b.direction
               FROM phrase_bindings b
              WHERE b.kb_id = $1 AND b.phrase = $2 AND b.subject_type_id IS NOT DISTINCT FROM $3
                AND b.object_type_id IS NOT DISTINCT FROM $4 AND b.object_is_value = $5
                FOR UPDATE OF b",
        )
        .bind(kb_id)
        .bind(phrase_bindings::normalize(&sig.phrase))
        .bind(sig.subject_type_id)
        .bind(sig.object_type_id.filter(|_| !sig.object_is_value))
        .bind(sig.object_is_value)
        .fetch_optional(&mut **tx)
        .await?;
        if let Some(d) =
            now.filter(|d| d.by_person_after_read(read_at(shape.get("seen_decided_at"))))
        {
            if d.agrees(property, Some(direction)) {
                // 不重写:判定还是那个人的,回归用例照写
                agreed += 1;
            } else {
                // 形状的四格同提案里那条:`finish_adoption` 凭它认出这条,不写回归用例
                skipped.push(json!({
                    "phrase": sig.phrase, "subject": sig.subject_type_key,
                    "object": sig.object_type_key, "value": sig.object_is_value,
                    "person": { "status": d.status, "property": d.target, "direction": d.direction } }));
            }
            continue;
        }
        let votes = json!({ "person": { "property": p.key, "direction": direction, "via": "ontology_agent" } });
        if phrase_bindings::decide_on(
            tx,
            kb_id,
            sig,
            phrase_bindings::Decision {
                relation_type_id: Some(property),
                direction: Some(direction),
                status: "bound",
                votes: &votes,
                decided_by: "person",
                basis: None,
                marks: None,
                marks_asked: false,
            },
        )
        .await?
        {
            written += 1;
        }
    }
    if written + agreed == 0 {
        return Err(nothing_left());
    }
    if written > 0 {
        // 判定和它的投影一起提交(0051)。整次提交排一份,不是一条形状一份:这些判定都和这一份
        // 同一次提交,它跑时读当下的绑定,0051 要的「每条判定都有和它一起提交的任务」照样成立
        utopia_store::jobs::enqueue_with_max_attempts_tx(
            tx,
            phrase_bindings::MATERIALIZE_KIND,
            json!({ "kb_id": kb_id }),
            3,
        )
        .await?;
    }
    Ok(property)
}

/// 复用的形状或类别词一条也写不了:都是人定得和提案不一样、照人留着的,或都没有陈述了。话里
/// 不说人是代理读过之后定的:没记下读到哪一刻的旧提案,人在提案之前定的也照留
fn nothing_left() -> AppError {
    AppError::CodedConflict {
        code: "proposal_stale",
        message: "Nothing in this proposal is left to write: each of its shapes or kind words is decided differently by a person or has no statements any more."
            .into(),
    }
}

/// 任务入口:给库提问题(决定 1 的"没有问题的库不被卡住")。界面上点、或本体代理发现库里
/// 一条问题都没有时走这里
pub async fn propose_questions(state: &AppState, kb_id: Uuid) -> anyhow::Result<usize> {
    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 propose questions"))?;
    let client = llm_util::chat_client(&settings)
        .ok_or_else(|| anyhow::anyhow!("Chat model not configured; cannot propose questions"))?;
    propose_questions_with(state, kb_id, &settings, &client).await
}

#[derive(sqlx::FromRow)]
struct EntityDegree {
    name: String,
    class: Option<String>,
    degree: i64,
}

async fn propose_questions_with(
    state: &AppState,
    kb_id: Uuid,
    settings: &utopia_core::models::LlmSettings,
    client: &utopia_llm::LlmClient,
) -> anyhow::Result<usize> {
    use utopia_extract::question_agent as qa;
    let pool = &state.pool;
    let classes = utopia_store::graph::entity_types(pool, kb_id).await?;
    let props = utopia_store::ontology::relation_type_views(pool, kb_id).await?;
    let class_key: HashMap<Uuid, &str> = classes.iter().map(|c| (c.id, c.key.as_str())).collect();
    let prop_key: HashMap<Uuid, &str> = props.iter().map(|p| (p.id, p.key.as_str())).collect();
    let keys_of = |ids: &[Uuid]| -> Vec<&str> {
        ids.iter()
            .filter_map(|id| class_key.get(id).copied())
            .collect()
    };
    let glossary = agent::Glossary {
        classes: classes
            .iter()
            .map(|c| (c.key.as_str(), c.label.as_str(), c.description.as_str()))
            .collect(),
        properties: props
            .iter()
            .map(|p| {
                (
                    p.key.as_str(),
                    p.label.as_str(),
                    p.kind.as_str(),
                    keys_of(&p.domains),
                    keys_of(&p.ranges),
                    p.description.as_str(),
                )
            })
            .collect(),
        others: Vec::new(),
    };
    // 说得最多的形状,带上对齐绑到的属性
    let mut sigs = phrase_bindings::signatures(pool, kb_id).await?;
    sigs.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.phrase.cmp(&b.phrase)));
    sigs.truncate(TOP_SIGNATURES);
    let bindings: HashMap<_, _> = phrase_bindings::bindings(pool, kb_id)
        .await?
        .into_iter()
        .map(|b| (b.key(), b))
        .collect();
    let top_sigs: Vec<qa::TopSignature<'_>> = sigs
        .iter()
        .map(|s| qa::TopSignature {
            phrase: &s.phrase,
            subject_class: s.subject_type_key.as_deref(),
            object_class: s.object_type_key.as_deref(),
            object_is_value: s.object_is_value,
            statement_count: s.count,
            property: bindings
                .get(&s.key())
                .filter(|b| b.status == "bound")
                .and_then(|b| b.relation_type_id)
                .and_then(|id| prop_key.get(&id).copied()),
            example: s.quotes.first().map(String::as_str),
        })
        .collect();
    let mut words = type_bindings::signatures(pool, kb_id).await?;
    words.sort_by(|a, b| {
        b.count
            .cmp(&a.count)
            .then_with(|| a.kind_word.cmp(&b.kind_word))
    });
    words.truncate(TOP_KIND_WORDS);
    let top_words: Vec<qa::TopKindWord<'_>> = words
        .iter()
        .map(|w| qa::TopKindWord {
            kind_word: &w.kind_word,
            count: w.count,
        })
        .collect();
    let degrees: Vec<EntityDegree> = sqlx::query_as(
        "SELECT e.canonical_name AS name, t.key AS class, count(f.id) AS degree
           FROM entities e
           LEFT JOIN entity_types t ON t.id = e.type_id
           JOIN facts f ON f.kb_id = e.kb_id AND (f.subject_id = e.id OR f.object_id = e.id)
                        AND f.invalidated_at IS NULL
          WHERE e.kb_id = $1
          GROUP BY e.id, e.canonical_name, t.key
          ORDER BY count(f.id) DESC, e.canonical_name
          LIMIT $2",
    )
    .bind(kb_id)
    .bind(TOP_ENTITIES as i64)
    .fetch_all(pool)
    .await?;
    let top_entities: Vec<qa::TopEntity<'_>> = degrees
        .iter()
        .map(|d| qa::TopEntity {
            name: &d.name,
            class: d.class.as_deref(),
            degree: d.degree,
        })
        .collect();
    let have = competency_questions::list(pool, kb_id).await?;
    let existing: Vec<&str> = have
        .iter()
        .filter(|q| q.status != "rejected")
        .map(|q| q.question.as_str())
        .collect();
    if top_sigs.is_empty() && top_words.is_empty() && top_entities.is_empty() {
        tracing::info!(%kb_id, "提问题:库里还没有东西可问");
        return Ok(0);
    }
    let messages = qa::build_question_messages(
        &top_sigs,
        &top_words,
        &top_entities,
        &glossary,
        &existing,
        QUESTIONS_PER_ROUND,
    );
    let reply = chat_retrying_rate_limits_at(state, settings, client, &messages, Some(0.0)).await?;
    let class_keys: HashSet<&str> = classes.iter().map(|c| c.key.as_str()).collect();
    let prop_keys: HashSet<&str> = props.iter().map(|p| p.key.as_str()).collect();
    let (proposed, malformed) = qa::parse_question_response(&reply.text, &class_keys, &prop_keys)?;
    let mut written = 0usize;
    for q in proposed.iter().take(QUESTIONS_PER_ROUND) {
        if competency_questions::exists_text(pool, kb_id, &q.question).await? {
            continue;
        }
        let needs = json!({ "classes": q.classes, "properties": q.properties });
        competency_questions::create(
            pool,
            kb_id,
            competency_questions::NewQuestion {
                question: &q.question,
                expected_answer: None,
                needs: Some(&needs),
                origin: "agent",
                status: "proposed",
                created_by: None,
            },
        )
        .await?;
        written += 1;
    }
    tracing::info!(%kb_id, proposed = proposed.len(), written, malformed, "提问题结束");
    if written > 0 {
        state.emit_pending(kb_id);
    }
    Ok(written)
}

#[cfg(test)]
#[path = "ontology_agent_tests.rs"]
mod tests;