Skip to content

World's first open-source enterprise world model.

A type a person decided should not be re-decided by the engine (#114)

WaylandYangcced132f1293
diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rs
index a575271f..92b79855 100644
--- a/crates/utopia-store/src/graph.rs
+++ b/crates/utopia-store/src/graph.rs
@@ -794,9 +794,17 @@ pub async fn update_entity(
}
sqlx::query(
+ // 改了类型才标 human——这个端点也用来改名字,只改名不该顺手把类型
+ // 的来源盖成人工。`$3 IS NULL` 在这个接口里表示「本次没提供类型」,
+ // 不是「把类型清空」:路由层要求两个字段至少给一个,给不出三态。
+ //
+ // 于是有一件今天做不到的事:0009 之后「没有类型」可能是人的决定
+ //(看过了,本体里没有合适的类),而这个接口表达不了它。要补得让
+ // 请求体区分「未提供」与「显式置空」,那是另一件事
"UPDATE entities
SET type_id = COALESCE($3, type_id),
canonical_name = COALESCE($4, canonical_name),
+ type_source = CASE WHEN $3::uuid IS NULL THEN type_source ELSE 'human' END,
updated_at = now()
WHERE id = $1 AND kb_id = $2 AND merged_into IS NULL",
)
diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rs
index d95f2656..56341e33 100644
--- a/crates/utopia-store/src/resolution.rs
+++ b/crates/utopia-store/src/resolution.rs
@@ -442,6 +442,8 @@ struct CrossCandidate {
canonical_name: String,
// None = 这个候选还没判出类型(0009)
type_key: Option<String>,
+ // 抽取升格要看它:人说过「就是没有类型」时,那也是一个决定
+ type_source: String,
profile_embedding: Option<Vector>,
profile_n: i32,
}
@@ -505,7 +507,8 @@ async fn resolve_type_drift(
None => None,
};
let cross: Vec<CrossCandidate> = sqlx::query_as(
- "SELECT e.id, e.canonical_name, t.key AS type_key, e.profile_embedding, e.profile_n
+ "SELECT e.id, e.canonical_name, t.key AS type_key, e.type_source,
+ e.profile_embedding, e.profile_n
FROM entities e LEFT JOIN entity_types t ON t.id = e.type_id
-- IS DISTINCT FROM 而不是 <>:后者遇 NULL 返回 NULL,被 WHERE 当假,
-- 未分类实体会被整个漏掉(0009)
@@ -544,9 +547,15 @@ async fn resolve_type_drift(
update_profile(pool, best.id, best.profile_n, ctx).await?;
// 候选还没判出类型而这次抽取判出来了 → 升格。
// 不是合并(没有第二个实体),不入 entity_merges;本体页可手工改回
- if best.type_key.is_none() && type_id.is_some() {
+ //
+ // **人说过的「没有类型」不算「还没判出来」。** 0009 之后两者都是
+ // NULL,只看 type_key.is_none() 分不出——于是一个人看过、认为
+ // 本体里没有合适类的实体,会在下一次抽取时被安上一个类型
+ if best.type_key.is_none() && best.type_source != "human" && type_id.is_some() {
sqlx::query(
- "UPDATE entities SET type_id = $2, updated_at = now() WHERE id = $1",
+ "UPDATE entities
+ SET type_id = $2, type_source = 'extracted', updated_at = now()
+ WHERE id = $1",
)
.bind(best.id)
.bind(type_id)
@@ -1540,6 +1549,9 @@ pub async fn adopt_proposed_types(
let targets: Vec<(Uuid, Option<Uuid>, String)> = sqlx::query_as(
"SELECT id, type_id, canonical_name FROM entities
WHERE kb_id = $1 AND merged_into IS NULL
+ -- 人拍过板的不认领。**这一行顺带让 unadopt 天然正确**:human 行
+ -- 永远不进采纳批次,撤销时也就不会遇到它们,不必额外还原 type_source
+ AND type_source <> 'human'
AND proposed_type = ANY($2) AND type_id IS DISTINCT FROM $3",
)
.bind(kb_id)
@@ -1553,11 +1565,16 @@ pub async fn adopt_proposed_types(
for (entity_id, from_type, name) in targets {
let mut tx = pool.begin().await?;
sqlx::query(
- "UPDATE entities SET type_id = $2, proposed_type = NULL, updated_at = now()
+ // actor 有值 = 人在界面上点的批准,他背书了这个类型 → 受保护。
+ // 无值 = 本体长出新类之后的收尾认领,没人在按
+ "UPDATE entities
+ SET type_id = $2, proposed_type = NULL, updated_at = now(),
+ type_source = CASE WHEN $3::uuid IS NULL THEN 'inferred' ELSE 'human' END
WHERE id = $1",
)
.bind(entity_id)
.bind(type_id)
+ .bind(actor)
.execute(&mut *tx)
.await?;
sqlx::query(
@@ -1864,6 +1881,15 @@ pub async fn entities_for_type_resolution(
FROM entities e
LEFT JOIN entity_types t ON t.id = e.type_id
WHERE e.kb_id = $1 AND e.merged_into IS NULL
+ -- **人拍过板的不再重判。**
+ --
+ -- 少了这一行,下面第三种条件会把它们全都捞回来:一个人工定成
+ -- organization 的实体,只要 organization 有子类就够格,于是引擎
+ -- 每一轮都去重新裁决一遍人已经决定过的事,而账本事后才看得出是谁改的。
+ --
+ -- 「不落库」不等于「不许说话」:引擎若认为人定错了,该走 Review 队列,
+ -- 而不是直接改掉。憋着不说和直接改掉都是失真,只是方向相反
+ AND e.type_source <> 'human'
-- 值得看的三种:**还没有类的**、模型报过词表外类型的、
-- **以及现类本身还有子类的**。第三种是主力:抽取只认基类之后,
-- organization 下面挂着一大批更具体的类,那才是导进来的本体
@@ -2010,7 +2036,8 @@ pub async fn retype_entities(
WHERE id = $1 AND kb_id = $3 AND merged_into IS NULL
AND type_id IS DISTINCT FROM $2
)
- UPDATE entities e SET type_id = $2, updated_at = now()
+ UPDATE entities e SET type_id = $2, updated_at = now(),
+ type_source = CASE WHEN $4::uuid IS NULL THEN 'inferred' ELSE 'human' END
FROM before
WHERE e.id = before.id
RETURNING before.type_id, before.canonical_name",
@@ -2018,6 +2045,7 @@ pub async fn retype_entities(
.bind(entity_id)
.bind(type_id)
.bind(kb_id)
+ .bind(actor)
.fetch_optional(&mut *tx)
.await?;
let Some((from_type, name)) = row else {
diff --git a/crates/utopia-store/tests/human_type_decisions.rs b/crates/utopia-store/tests/human_type_decisions.rs
new file mode 100644
index 00000000..6a718fe5
--- /dev/null
+++ b/crates/utopia-store/tests/human_type_decisions.rs
@@ -0,0 +1,312 @@
+//! 人拍过板的类型,引擎不许改——打在真库上。
+//!
+//! 这一整条防线活在 SQL 的 `WHERE` 子句里:三处读侧各加一句
+//! `type_source <> 'human'`,漏一处就是静默失效。`cargo check` 一个字看不见,
+//! 而 0009 刚在同一片区域踩过 `NULL <> uuid` 的坑——类型系统数得清 Rust,
+//! 数不到 SQL 里去。
+//!
+//! 四条断言对应四条路径:
+//!
+//! - 类型消解取材(`entities_for_type_resolution`)不该捞人拍过板的
+//! - 本体长出新类后的认领(`adopt_proposed_types`)不该盖掉人拍过板的
+//! - 抽取升格不该给「人说过就是没有类型」的实体安一个类型 ← 0009 × P4 的交叉
+//! - `retype_entities` 用现成的 `actor` 参数区分 human / inferred
+//!
+//! 没有 `UTOPIA_DATABASE_URL` 时跳过而不是失败。自建自拆,绝不碰已有的库。
+
+use sqlx::PgPool;
+use uuid::Uuid;
+
+struct Fx {
+ org: Uuid,
+ kb: Uuid,
+ org_type: Uuid,
+ sub_type: Uuid,
+}
+
+/// 造一个刚好能触发「第三种取材条件」的本体:`organization` 有子类 `startup`。
+/// 人把实体定成 `organization` 之后,正是这个子类让它够格被重判。
+async fn seed(pool: &PgPool) -> anyhow::Result<Fx> {
+ let (org, ws, kb) = (Uuid::now_v7(), Uuid::now_v7(), Uuid::now_v7());
+ let (org_type, sub_type) = (Uuid::now_v7(), Uuid::now_v7());
+
+ sqlx::query("INSERT INTO organizations (id, name) VALUES ($1, 'p4a-test')")
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query("INSERT INTO workspaces (id, org_id, name) VALUES ($1, $2, 'p4a-test')")
+ .bind(ws)
+ .bind(org)
+ .execute(pool)
+ .await?;
+ sqlx::query("INSERT INTO knowledge_bases (id, workspace_id, name) VALUES ($1, $2, 'p4a-test')")
+ .bind(kb)
+ .bind(ws)
+ .execute(pool)
+ .await?;
+ for (id, key) in [(org_type, "organization"), (sub_type, "startup")] {
+ sqlx::query("INSERT INTO entity_types (id, kb_id, key, label) VALUES ($1, $2, $3, $3)")
+ .bind(id)
+ .bind(kb)
+ .bind(key)
+ .execute(pool)
+ .await?;
+ }
+ sqlx::query("INSERT INTO entity_type_parents (child_id, parent_id) VALUES ($1, $2)")
+ .bind(sub_type)
+ .bind(org_type)
+ .execute(pool)
+ .await?;
+ Ok(Fx {
+ org,
+ kb,
+ org_type,
+ sub_type,
+ })
+}
+
+async fn entity(
+ pool: &PgPool,
+ f: &Fx,
+ name: &str,
+ type_id: Option<Uuid>,
+ source: &str,
+) -> anyhow::Result<Uuid> {
+ let id = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO entities (id, kb_id, type_id, canonical_name, type_source)
+ VALUES ($1, $2, $3, $4, $5)",
+ )
+ .bind(id)
+ .bind(f.kb)
+ .bind(type_id)
+ .bind(name)
+ .bind(source)
+ .execute(pool)
+ .await?;
+ Ok(id)
+}
+
+async fn source_of(pool: &PgPool, id: Uuid) -> anyhow::Result<String> {
+ Ok(
+ sqlx::query_scalar("SELECT type_source FROM entities WHERE id = $1")
+ .bind(id)
+ .fetch_one(pool)
+ .await?,
+ )
+}
+
+/// 主战场:取材条件里的「现类还有子类就纳入」会把人拍过板的实体一并捞回来。
+#[tokio::test]
+async fn type_resolution_leaves_human_decisions_alone() -> anyhow::Result<()> {
+ let Ok(url) = std::env::var("UTOPIA_DATABASE_URL") else {
+ eprintln!("跳过:未设 UTOPIA_DATABASE_URL");
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let f = seed(&pool).await?;
+
+ let run = async {
+ let by_human = entity(&pool, &f, "Acme", Some(f.org_type), "human").await?;
+ let by_engine = entity(&pool, &f, "Globex", Some(f.org_type), "extracted").await?;
+
+ let picked = utopia_store::resolution::entities_for_type_resolution(&pool, f.kb, 100)
+ .await?
+ .into_iter()
+ .map(|c| c.id)
+ .collect::<std::collections::HashSet<_>>();
+
+ assert!(
+ picked.contains(&by_engine),
+ "抽取定的类型该被重判——organization 有子类 startup,这正是消解的用武之地"
+ );
+ assert!(!picked.contains(&by_human), "人拍过板的不该被拿去重判");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ run
+}
+
+/// 本体长出新类之后的认领,同样不该盖掉人的决定。
+///
+/// 这一条顺带保证了 `unadopt_types` 的正确性:human 行永远不进采纳批次,
+/// 撤销时也就不会遇到它们,不必额外还原 `type_source`。
+#[tokio::test]
+async fn adopting_a_new_class_does_not_claim_human_typed_entities() -> anyhow::Result<()> {
+ let Ok(url) = std::env::var("UTOPIA_DATABASE_URL") else {
+ eprintln!("跳过:未设 UTOPIA_DATABASE_URL");
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let f = seed(&pool).await?;
+
+ let run = async {
+ // 两个实体都被模型提议过 startup,但一个的类型是人定的
+ for (name, source) in [("Acme", "human"), ("Globex", "extracted")] {
+ let id = entity(&pool, &f, name, Some(f.org_type), source).await?;
+ sqlx::query("UPDATE entities SET proposed_type = 'startup' WHERE id = $1")
+ .bind(id)
+ .execute(&pool)
+ .await?;
+ }
+
+ let (_, moved) = utopia_store::resolution::adopt_proposed_types(
+ &pool,
+ f.kb,
+ f.sub_type,
+ &["startup".to_string()],
+ None,
+ )
+ .await?;
+ assert_eq!(moved, 1, "只该认领那个不是人定的");
+
+ let human: Option<Uuid> = sqlx::query_scalar(
+ "SELECT type_id FROM entities WHERE kb_id = $1 AND canonical_name = 'Acme'",
+ )
+ .bind(f.kb)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(human, Some(f.org_type), "人定的类型原样未动");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ run
+}
+
+/// **0009 × P4 的交叉,最容易漏的一条。**
+///
+/// 0009 之后「没有类型」可能是人的决定——他看过这个实体,认为本体里没有合适的类。
+/// 而抽取升格的守卫原本只看 `type_key.is_none()`,分不出「还没判」和「人判了,
+/// 就是没有」,于是下一次抽取会给它安一个类型。
+#[tokio::test]
+async fn extraction_does_not_fill_in_a_type_a_human_left_empty() -> anyhow::Result<()> {
+ let Ok(url) = std::env::var("UTOPIA_DATABASE_URL") else {
+ eprintln!("跳过:未设 UTOPIA_DATABASE_URL");
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let f = seed(&pool).await?;
+
+ let run = async {
+ // 人看过它,认为本体里没有合适的类 → 没有类型,且这是个决定
+ let decided = entity(&pool, &f, "Ambiguous Thing", None, "human").await?;
+ // 还没轮到判的那个
+ let pending = entity(&pool, &f, "Other Thing", None, "extracted").await?;
+
+ // **升格分支要画像相似度才走得到**:ctx 为空时 best 是 None,整段被跳过。
+ // 第一版就是这么写的,撤掉守卫也没有测试失败——测试没测到它要测的东西
+ let ctx: Vec<f32> = vec![1.0, 0.0, 0.0];
+ for id in [decided, pending] {
+ sqlx::query(
+ "UPDATE entities SET profile_embedding = $2::vector, profile_n = 1 WHERE id = $1",
+ )
+ .bind(id)
+ .bind("[1,0,0]")
+ .execute(&pool)
+ .await?;
+ }
+
+ // 抽取再次遇到同名 mention,判出 organization。余弦 = 1.0,远高于 SIM_ATTACH
+ for id in [decided, pending] {
+ let name: String =
+ sqlx::query_scalar("SELECT canonical_name FROM entities WHERE id = $1")
+ .bind(id)
+ .fetch_one(&pool)
+ .await?;
+ let _ = utopia_store::resolution::resolve_mention(
+ &pool,
+ f.kb,
+ Some(f.org_type),
+ &name,
+ Some(&ctx),
+ )
+ .await?;
+ }
+
+ // 对照:没有人拍过板的那个**应该**被升格,否则这个测试证明不了守卫在起作用
+ let after_pending: Option<Uuid> =
+ sqlx::query_scalar("SELECT type_id FROM entities WHERE id = $1")
+ .bind(pending)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(
+ after_pending,
+ Some(f.org_type),
+ "还没判过的该被抽取升格——不然下面那条断言是空的"
+ );
+
+ let after_decided: Option<Uuid> =
+ sqlx::query_scalar("SELECT type_id FROM entities WHERE id = $1")
+ .bind(decided)
+ .fetch_one(&pool)
+ .await?;
+ assert_eq!(
+ after_decided, None,
+ "人说过「就是没有类型」,抽取不该替他填一个"
+ );
+ assert_eq!(source_of(&pool, decided).await?, "human");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ run
+}
+
+/// `retype_entities` 用现成的 `actor` 参数区分来源:人点的批准是背书,受保护;
+/// 引擎自动裁决的不是。不必为此加新参数——#112 加 actor 时它就已经在那儿了。
+#[tokio::test]
+async fn who_approved_a_retype_decides_whether_it_is_protected() -> anyhow::Result<()> {
+ let Ok(url) = std::env::var("UTOPIA_DATABASE_URL") else {
+ eprintln!("跳过:未设 UTOPIA_DATABASE_URL");
+ return Ok(());
+ };
+ let pool = PgPool::connect(&url).await?;
+ let f = seed(&pool).await?;
+ let actor = Uuid::now_v7();
+ sqlx::query(
+ "INSERT INTO users (id, org_id, email, display_name, password_hash)
+ VALUES ($1, $2, $1 || '@p4a.test', 'p4a', 'x')",
+ )
+ .bind(actor)
+ .bind(f.org)
+ .execute(&pool)
+ .await?;
+
+ let run = async {
+ let a = entity(&pool, &f, "Approved", Some(f.org_type), "extracted").await?;
+ let b = entity(&pool, &f, "Auto", Some(f.org_type), "extracted").await?;
+
+ utopia_store::resolution::retype_entities(&pool, f.kb, &[(a, f.sub_type)], Some(actor))
+ .await?;
+ utopia_store::resolution::retype_entities(&pool, f.kb, &[(b, f.sub_type)], None).await?;
+
+ assert_eq!(source_of(&pool, a).await?, "human", "人点的批准是背书");
+ assert_eq!(source_of(&pool, b).await?, "inferred", "引擎自动裁决的不是");
+ Ok::<_, anyhow::Error>(())
+ }
+ .await;
+
+ sqlx::query("DELETE FROM knowledge_bases WHERE id = $1")
+ .bind(f.kb)
+ .execute(&pool)
+ .await?;
+ sqlx::query("DELETE FROM users WHERE id = $1")
+ .bind(actor)
+ .execute(&pool)
+ .await?;
+ run
+}
diff --git a/migrations/0051_type_source.sql b/migrations/0051_type_source.sql
new file mode 100644
index 00000000..9ae58547
--- /dev/null
+++ b/migrations/0051_type_source.sql
@@ -0,0 +1,43 @@
+-- 人定过的类型,引擎不许改。
+--
+-- `entity_retypes` 记得住「谁改的」(0048 加的 `actor_id`),但那是**事后**的账。
+-- 保护要**事前**:实体身上得有一位说明这个类型是怎么来的,否则每一条读路径都
+-- 只能看见 `type_id`,看不见它背后有没有人拍过板。
+--
+-- 今天的漏在类型消解那条路上。`entities_for_type_resolution` 的取材条件是:
+--
+-- AND (e.type_id IS NULL OR e.proposed_type IS NOT NULL
+-- OR e.specific_type IS NOT NULL
+-- OR EXISTS (SELECT 1 FROM entity_type_parents p WHERE p.parent_id = t.id))
+--
+-- 最后那行意味着:**人工定成 `organization` 的实体,只要 `organization` 有子类,
+-- 下一轮消解照样把它拿去重判。** 抽取那条路有守卫(`resolve_type_drift` 只在
+-- `type_key.is_none()` 时升格),消解这条没有。
+--
+-- 0009 之后还多了一种情形:「没有类型」现在可能是**人的决定**——他看过这个实体,
+-- 认为本体里没有合适的类。而 `type_id IS NULL` 分不出「还没判」和「人判了,
+-- 就是没有」,于是下一次抽取会给它安一个类型。这一条 0001 写不出来,因为 0009
+-- 比它晚三天。
+--
+-- 三个取值的分工:
+--
+-- extracted 抽取判出来的(`resolve_type_drift` 的升格)
+-- inferred 引擎裁决的(类型消解、本体长出新类后的认领)
+-- human 人拍板的(实体面板直改、审核队列里点批准)
+--
+-- `inferred` 与 `extracted` 分开而不是合成一个「非人」:它们的可信度不同,
+-- 将来若要「引擎可以改引擎的,但不能改抽取的」,判据现成。
+
+ALTER TABLE entities ADD COLUMN type_source TEXT NOT NULL DEFAULT 'extracted'
+ CHECK (type_source IN ('extracted', 'human', 'inferred'));
+
+-- 回填**不靠猜**:审计台账里的 entity.retyped 带 actor_id 与 target_id,
+-- 那是人在实体面板上改类型时留下的唯一痕迹(那条路至今不写 entity_retypes)。
+--
+-- 更早的引擎改类无从追溯——`entity_retypes.actor_id` 是 0048 才有的,之前的行
+-- 分不出人机。所以默认值取 `extracted`:**承认不知道,而不是断言没人碰过**。
+UPDATE entities e SET type_source = 'human'
+ WHERE EXISTS (
+ SELECT 1 FROM audit_events a
+ WHERE a.action = 'entity.retyped' AND a.target_id = e.id
+ );