World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
//! 治理任务(0025):开关开着就把等人的重复对按先进先出过一遍,先读台账再裁。
//!
//! 人裁过的一对(同一对实体,或名字不同的同一对名字)照人的定,不问模型。
//! 其余两层。第一层是攒批:队头带着它的簇进一次模型调用,先例已经在提示词里;过闸的
//! 自己动手(合并可撤、分开可再合)。第二层(第二刀)只接第一层**判不定**的对:
//! 逐条带工具再看一遍——一侧的全部事实、原文片段、台账里人对这个名字的决定、
//! 同名的其他实体——看完要么 decide,要么 defer 留一个具体的问题给人。硬规则拦下
//! 的对(类型冲突、有撤回、与人对这一对的决定相反)不进第二层:再看也不会改规则。
//!
//! 两簇之间看一眼开关,关掉就停在这里——「关闭后队列自动终止」就是那一行。模型
//! 缺席时任务成功结束、什么都不动:没有依据的裁决不如不裁,队列原地等。
//!
//! 与攒批裁决器(`adjudication`)的分工:开关关着,那一档照旧独自判灰区对;
//! 开着,抽取结束排的是这里,灰区对与等人的对都从这条队列走。这里不读也不写
//! 裁决缓存——缓存键里没有先例,而这里的答案随先例变。
use crate::llm_util;
use crate::state::AppState;
use chrono::{Duration, Utc};
use futures_util::future::join_all;
use serde_json::{json, Value};
use std::collections::{HashMap, HashSet};
use utopia_core::models::{LlmSettings, ReviewItem, Role};
use utopia_core::AppError;
use utopia_extract::governor::{self, Step};
use utopia_llm::{tool_result_message, LlmClient};
use utopia_store::alerts;
use utopia_store::execution_gate;
use utopia_store::governance::{self as gov, Gate, NewDecision, Precedents, AUTO_CONF};
use uuid::Uuid;
/// 一次模型调用带几对:队头加它的簇
const BATCH_SIZE: i64 = 12;
/// 一个任务最多走几轮,之后再排一个接着走——让别的库的任务也轮得上
const MAX_ROUNDS: usize = 20;
/// 每库每天第二层最多花几次模型调用。用完了,判不定的对照第一刀写成建议。
/// 300 在一次 229 块的导入上第一轮就用光了(132 对花了 301 次),所以是 2000
const LOOP_DAILY_CALLS: i64 = 2000;
/// 一次工具结果最多给模型多少字:原文片段与事实列表都可能很长
const TOOL_OUTPUT_CHARS: usize = 3000;
/// 一轮任务里到处要带的东西
struct Ctx<'a> {
state: &'a AppState,
kb_id: Uuid,
run_id: Uuid,
client: &'a LlmClient,
settings: &'a Option<LlmSettings>,
}
/// 对一对的一次看法:第一层给的,或第二层看完改过的。裁决器(治理关着时)也用它:
/// 判不定的对走同一个第二层(0028)
pub(crate) struct Look {
pub(crate) same: Option<bool>,
pub(crate) conf: f32,
pub(crate) why: Option<String>,
/// defer 留下的问题
pub(crate) question: Option<String>,
/// 第二层看了什么
pub(crate) trace: Vec<Value>,
/// 第二层花的模型调用
pub(crate) calls: i32,
}
impl Look {
pub(crate) fn from_batch(same: Option<bool>, conf: f32, why: Option<String>) -> Self {
Look {
same,
conf,
why,
question: None,
trace: Vec::new(),
calls: 0,
}
}
/// 人裁过这一对:照人的定,不问模型
fn from_people(merged: bool) -> Self {
Look {
same: Some(merged),
conf: 1.0,
why: Some("a person decided this same pair before".into()),
question: None,
trace: Vec::new(),
calls: 0,
}
}
/// 第一层没定:没判决,或置信度不到线
fn uncertain(&self) -> bool {
self.same.is_none() || self.conf < AUTO_CONF
}
fn action(&self) -> &'static str {
match self.same {
Some(true) => "merge",
Some(false) => "keep",
None => "unsure",
}
}
}
pub async fn govern(state: &AppState, kb_id: Uuid) -> anyhow::Result<()> {
let kb = utopia_store::kbs::get(&state.pool, kb_id).await?;
if !kb.governance {
return Ok(());
}
let settings = utopia_store::settings::get(&state.pool, kb.workspace_id).await?;
let Some(client) = settings.as_ref().and_then(llm_util::chat_client) else {
tracing::info!(%kb_id, "治理:没有配聊天模型,队列原地等");
return Ok(());
};
// 一个库一次只跑一个治理任务。每篇文档抽完都排一个,而排队的去重只挡排着的、不挡在跑的:
// 抢不到锁就说明有人在治理这个库,它会把队列走完,走完还有积压会再排一个。它读完队头
// 之后才进来的对它看不见,所以这里隔一分钟再排一个——排着的至多一个,跑着的也只有它
let Some(base_lock) = gov::try_lock_base(&state.pool, kb_id).await? else {
tracing::info!(%kb_id, "治理:这个库已有任务在跑,一分钟后再看一眼");
utopia_store::jobs::enqueue_unless_queued_after(
&state.pool,
"govern",
json!({ "kb_id": kb_id }),
std::time::Duration::from_secs(60),
)
.await?;
return Ok(());
};
let ctx = Ctx {
state,
kb_id,
run_id: Uuid::now_v7(),
client: &client,
settings: &settings,
};
// 上一次任务半路留下的锁先放掉;跑完(不管怎么结束的)再放一次
gov::release_locks(&state.pool, kb_id).await?;
let outcome = rounds(&ctx).await;
if let Err(e) = gov::release_locks(&state.pool, kb_id).await {
tracing::warn!(%kb_id, error = %e, "治理:放锁失败");
}
base_lock.release().await;
state.emit_review(kb_id);
let more = outcome?;
// 轮数用完还有积压:再排一个,下一轮从队头接着走
if more {
utopia_store::jobs::enqueue_unless_queued(&state.pool, "govern", json!({ "kb_id": kb_id }))
.await?;
}
Ok(())
}
/// 一轮里并行裁几簇。只有互不共享实体、也不共享名字的簇才能同一轮:一簇里的合并
/// 会改另一簇看到的东西。模型那边的并发由 llm_util 的闸门限,这里只决定一次挂几个
const CLUSTERS_PER_ROUND: usize = 3;
/// 挑簇时从队头往后看多少对
const HEADS_TO_SCAN: i64 = 60;
/// 一簇:等人的对、各自的先例、给模型看的样子、已经有的看法(人定过的快路)
struct Cluster {
items: Vec<ReviewItem>,
precedents: Vec<Precedents>,
pairs: Vec<utopia_extract::AdjudicationPair>,
looks: Vec<Option<Look>>,
}
/// 一轮轮走到队列空、开关关或轮数用完。回 true = 轮数用完还有积压
async fn rounds(ctx: &Ctx<'_>) -> anyhow::Result<bool> {
let state = ctx.state;
let kb_id = ctx.kb_id;
let pool = &state.pool;
for _ in 0..MAX_ROUNDS {
// 关闭后队列自动终止:每一轮之前看一眼
if !utopia_store::kbs::get(pool, kb_id).await?.governance {
tracing::info!(%kb_id, "治理:开关已关,停在这里");
return Ok(false);
}
// 从队头起挑互不重叠的簇,最多 K 簇;和已取的簇有交集的头留到下一轮
let heads = gov::queue(pool, kb_id, HEADS_TO_SCAN).await?;
if heads.is_empty() {
return Ok(false);
}
let mut clusters: Vec<Vec<ReviewItem>> = Vec::new();
let mut taken_ids: HashSet<Uuid> = HashSet::new();
let mut taken_entities: HashSet<Uuid> = HashSet::new();
let mut taken_names: HashSet<String> = HashSet::new();
for head in heads {
if clusters.len() >= CLUSTERS_PER_ROUND {
break;
}
if taken_ids.contains(&head.id) {
continue;
}
let mut items = vec![head];
let siblings = gov::cluster_of(pool, kb_id, &items[0], BATCH_SIZE - 1).await?;
items.extend(siblings);
let overlaps = items.iter().any(|i| {
taken_ids.contains(&i.id)
|| taken_entities.contains(&i.left.id)
|| taken_entities.contains(&i.right.id)
|| taken_names.contains(&i.left.name.to_lowercase())
|| taken_names.contains(&i.right.name.to_lowercase())
});
if overlaps {
continue;
}
for i in &items {
taken_ids.insert(i.id);
taken_entities.insert(i.left.id);
taken_entities.insert(i.right.id);
taken_names.insert(i.left.name.to_lowercase());
taken_names.insert(i.right.name.to_lowercase());
}
clusters.push(items);
}
// 这几簇归 agent 了:人在这几分钟里不能裁它们,界面上看得见
let ids: Vec<Uuid> = taken_ids.into_iter().collect();
gov::lock(pool, kb_id, &ids).await?;
state.emit_review(kb_id);
// 先例与快路(库操作,顺序做)
let mut round: Vec<Cluster> = Vec::with_capacity(clusters.len());
for items in clusters {
let mut precedents = Vec::with_capacity(items.len());
for item in &items {
precedents.push(gov::precedents_for(pool, kb_id, item).await?);
}
let pairs: Vec<utopia_extract::AdjudicationPair> = items
.iter()
.zip(&precedents)
.map(|(item, p)| pair_of(item, p))
.collect();
let mut looks = Vec::with_capacity(items.len());
for (idx, item) in items.iter().enumerate() {
let prior = gov::decided_before(pool, kb_id, item.left.id, item.right.id).await?;
looks.push(
gov::settled_by_people(
&item.left.name,
&item.right.name,
&precedents[idx],
prior,
)
.map(Look::from_people),
);
}
round.push(Cluster {
items,
precedents,
pairs,
looks,
});
}
// 攒批:每簇一次调用,几簇同时挂。任何一次失败整轮失败,任务按退避重试;
// 重试耗尽后这些对留在队列里,人照样能裁
let batches = join_all(round.iter().map(|c| batch_looks(ctx, c))).await;
for (c, looks) in round.iter_mut().zip(batches) {
for (idx, look) in looks? {
c.looks[idx] = Some(look);
}
}
// 第二层:判不定的、同名却说不同的,带工具再看一遍——几对同时看,
// 模型那边由闸门限并发
let mut second: Vec<(usize, usize)> = Vec::new();
for (ci, c) in round.iter().enumerate() {
for (idx, look) in c.looks.iter().enumerate() {
if let Some(look) = look {
if wants_second_look(&c.items[idx], &c.precedents[idx], look) {
second.push((ci, idx));
}
}
}
}
let seen = join_all(second.iter().map(|&(ci, idx)| {
let c = &round[ci];
second_look(
ctx,
&c.items[idx],
&c.pairs[idx],
c.looks[idx].as_ref().expect("a look"),
)
}))
.await;
for (&(ci, idx), look) in second.iter().zip(seen) {
if let Some(look) = look {
round[ci].looks[idx] = Some(look);
}
}
// 落地:按簇、按对顺序写库——连锁合并要按顺序
for c in round.iter_mut() {
for idx in 0..c.items.len() {
let look = c.looks[idx]
.take()
.unwrap_or_else(|| Look::from_batch(None, 0.0, None));
apply(ctx, &c.items[idx], &c.precedents[idx], look).await?;
}
}
state.emit_review(kb_id);
}
Ok(!gov::queue(pool, kb_id, 1).await?.is_empty())
}
/// 一簇的攒批调用:人定过的不问,其余一次问完;回每对的看法
async fn batch_looks(ctx: &Ctx<'_>, c: &Cluster) -> anyhow::Result<Vec<(usize, Look)>> {
let asked: Vec<usize> = (0..c.items.len())
.filter(|&i| c.looks[i].is_none())
.collect();
if asked.is_empty() {
return Ok(Vec::new());
}
let batch: Vec<utopia_extract::AdjudicationPair> =
asked.iter().map(|&i| c.pairs[i].clone()).collect();
let messages = utopia_extract::build_adjudication_messages(&batch);
let reply = {
let _permit = permit(ctx).await;
ctx.client.chat(&messages).await?
};
let (verdicts, repaired) = utopia_extract::parse_adjudication_repairing(&reply)?;
if repaired {
// 模型在引号里的理由中间直接换行:修补后照读,但记下是哪一簇(#894/#895 同款)
tracing::warn!(
kb_id = %ctx.kb_id,
run_id = %ctx.run_id,
pairs = batch.len(),
first_pair = %crate::adjudication::batch_name(&batch),
"裁决回复的字符串里有裸控制字符,转义后才解开"
);
}
let by_i: HashMap<usize, &utopia_extract::AdjudicationVerdict> =
verdicts.iter().map(|v| (v.i, v)).collect();
Ok(asked
.iter()
.enumerate()
.map(|(n, &idx)| {
let look = match by_i.get(&n) {
Some(v) => Look::from_batch(
match v.verdict.as_str() {
"same" => Some(true),
"different" => Some(false),
_ => None,
},
v.confidence.unwrap_or(0.5).clamp(0.0, 1.0),
v.why.clone(),
),
None => Look::from_batch(None, 0.0, None),
};
(idx, look)
})
.collect())
}
async fn permit(ctx: &Ctx<'_>) -> Option<tokio::sync::OwnedSemaphorePermit> {
match ctx.settings.as_ref() {
Some(s) => llm_util::acquire_chat(ctx.state, s).await,
None => None,
}
}
fn pair_of(item: &ReviewItem, p: &Precedents) -> utopia_extract::AdjudicationPair {
// 同名且大类不冲突的对:两侧写同一个类型标签。抽取器给同一家公司的两条记录
// Store 与 Organization,模型就拿这个当「不同」的理由——把拐杖拿掉,让它看事实
// 只在两侧都归得到同一个大类(人、组织、地点、事件)时才共用:Periodical 对 Service、
// VideoGame 对没类型,那些标签是有信息的,留着
let same_kind = gov::name_shape(&item.left.name, &item.right.name) == gov::NameShape::Identical
&& matches!(
(
item.left.type_label.as_deref().and_then(gov::type_family),
item.right.type_label.as_deref().and_then(gov::type_family),
),
(Some(a), Some(b)) if a == b
);
let shared = item
.left
.type_label
.clone()
.or_else(|| item.right.type_label.clone())
.unwrap_or_else(|| "untyped".into());
let side = |s: &utopia_core::models::ReviewSide| utopia_extract::AdjudicationSide {
name: s.name.clone(),
type_label: if same_kind {
shared.clone()
} else {
s.type_label.clone().unwrap_or_else(|| "untyped".into())
},
facts: s.top_facts.clone(),
};
utopia_extract::AdjudicationPair {
left: side(&item.left),
right: side(&item.right),
precedents: gov::render_lines(p),
proposed_because: utopia_extract::proposed_because(
utopia_core::review_reasons::name_vector_cosine(item.reason.as_deref()),
),
}
}
/// 第一层没定(没判决、置信度不到线),或者同名、大类不冲突、模型却说不同——那是它
/// 最爱错的一种:都让第二层带着全部事实与原文再看一遍。名字的形状让人起疑的合并(版本
/// 尾巴、含着名字的一长串)也再看:名字只能让人起疑,定不了是不是一个东西——「Lease
/// Agreement dated May 16, 2016, as amended」与「Lease Agreement」形状上是一句话,事实上
/// 是同一份租约。类型冲突这条硬规则拦下的不进:再看也不会改规则
fn wants_second_look(item: &ReviewItem, p: &Precedents, look: &Look) -> bool {
let types_conflict = gov::types_conflict(
item.left.type_label.as_deref(),
item.right.type_label.as_deref(),
);
let shape = gov::name_shape(&item.left.name, &item.right.name);
let doubted_split = shape == gov::NameShape::Identical
&& !types_conflict
&& look.same == Some(false)
&& look.calls == 0;
let doubted_merge =
name_doubts(shape) && !types_conflict && look.same == Some(true) && look.calls == 0;
// 名字向量提的对说 same:不论把握多高都先带工具看一遍(与不带治理的裁决同一条规矩,
// `adjudication::batch_verdict_may_apply`);只看第一层的,第二层看过的不再看
let similarity_same =
!crate::adjudication::batch_verdict_may_apply(item, look.same) && look.calls == 0;
((gov::gate(look.same, look.conf, types_conflict, shape, p) == Gate::Propose
&& look.uncertain())
|| doubted_split
|| doubted_merge
|| similarity_same)
&& p.reverts.is_empty()
}
/// 名字形状让人起疑的合并:版本尾巴,或含着另一个名字的一长串
fn name_doubts(shape: gov::NameShape) -> bool {
matches!(shape, gov::NameShape::Version | gov::NameShape::Phrase)
}
/// 闸门看的名字形状。第二层带着两边的事实与原文看过、仍说是同一个的,形状的疑点已经由
/// 证据答过了,不再按形状拦——拦的只剩没看过证据的第一层
fn shape_for_gate(item: &ReviewItem, look: &Look) -> gov::NameShape {
settled_shape(
gov::name_shape(&item.left.name, &item.right.name),
look.calls > 0,
)
}
/// 形状的疑点在第二层读过证据之后就答完了
fn settled_shape(shape: gov::NameShape, evidence_read: bool) -> gov::NameShape {
if evidence_read && name_doubts(shape) {
gov::NameShape::Unrelated
} else {
shape
}
}
/// 裁决器的入口(0028):治理关着,攒批判不定的对也带工具再看一遍——同一个循环、
/// 同一份预算。每次调用一个 run_id:一次裁决任务就是一次 run
pub(crate) async fn look_again(
state: &AppState,
kb_id: Uuid,
client: &LlmClient,
settings: &Option<LlmSettings>,
item: &ReviewItem,
pair: &utopia_extract::AdjudicationPair,
earlier: &Look,
) -> Option<Look> {
let ctx = Ctx {
state,
kb_id,
run_id: Uuid::now_v7(),
client,
settings,
};
second_look(&ctx, item, pair, earlier).await
}
/// 第二层看一对:预算够就看,看完的看法替掉第一层的;看不成(预算用完、模型出错)回 None,
/// 照第一层的看法办
async fn second_look(
ctx: &Ctx<'_>,
item: &ReviewItem,
pair: &utopia_extract::AdjudicationPair,
look: &Look,
) -> Option<Look> {
let kb_id = ctx.kb_id;
let spent = match gov::loop_calls_today(&ctx.state.pool, kb_id).await {
Ok(n) => n,
Err(e) => {
tracing::warn!(%kb_id, error = %e, "治理:数循环预算失败");
return None;
}
};
if spent >= LOOP_DAILY_CALLS {
tracing::info!(%kb_id, spent, "治理:今天的循环预算用完,判不定的只写建议");
return None;
}
match investigate(ctx, item, pair, look).await {
Ok(l) => Some(l),
// 第二层失败不拖累第一层:这一对照第一层的看法写成建议
Err(e) => {
tracing::warn!(%kb_id, review = %item.id, error = %e, "治理:第二层没跑完");
None
}
}
}
/// 一对的判决落地:过闸就动手并记 applied,否则转人工并记 proposed(带着问题与轨迹)
async fn apply(ctx: &Ctx<'_>, item: &ReviewItem, p: &Precedents, look: Look) -> anyhow::Result<()> {
let pool = &ctx.state.pool;
let kb_id = ctx.kb_id;
let types_conflict = gov::types_conflict(
item.left.type_label.as_deref(),
item.right.type_label.as_deref(),
);
let shape = shape_for_gate(item, &look);
let action = look.action();
let precedents = gov::precedents_json(p);
let conf = look.conf;
let decision = |status: &'static str, merge_id: Option<Uuid>| NewDecision {
run_id: ctx.run_id,
target_id: item.id,
action,
confidence: conf,
reason: look.why.as_deref(),
precedents: precedents.clone(),
status,
merge_id,
question: look.question.as_deref(),
trace: Value::Array(look.trace.clone()),
calls: look.calls,
};
// 第二眼没跑成(预算用完、模型出错)的相似提的 same:过闸也不合,上交给人,
// 看法照记成建议——名字相近不是同一个东西的证据,事实才是
if look.same == Some(true)
&& look.calls == 0
&& !crate::adjudication::batch_verdict_may_apply(item, look.same)
{
utopia_store::resolution::escalate_review(
pool,
item.id,
crate::adjudication::SECOND_LOOK_UNAVAILABLE,
)
.await?;
gov::record(
pool,
kb_id,
NewDecision {
reason: Some("held for a person: the names are similar, not the same string, and the second look did not run"),
..decision("proposed", None)
},
)
.await?;
return Ok(());
}
match gov::gate(look.same, look.conf, types_conflict, shape, p) {
Gate::Apply if look.same == Some(true) => {
let reason = format!("governed|{conf:.2}");
// 同簇连锁:前一对合完,这一对的一侧可能已经并进了别人——合活着的那个
let (l, r) = (
utopia_store::resolution::survivor(pool, kb_id, item.left.id).await?,
utopia_store::resolution::survivor(pool, kb_id, item.right.id).await?,
);
if l == r {
// 两边已经是同一个实体:只剩把审核行关上。关不上是已经有人关了,不再记一条
let closed =
utopia_store::resolution::close_review_auto(pool, item.id, "merged", &reason)
.await?;
if closed > 0 {
let id = gov::record(pool, kb_id, decision("applied", None)).await?;
audit(ctx, "review.merge", item, conf, id).await;
}
return Ok(());
}
// 执行闸门(0027):合并会立刻送出图外的东西——违规、派生、答案——留给人,
// 把握再高也不动手。agent 的看法照记成建议,理由前面写明是闸门留下的
let impact = execution_gate::impact_of(pool, kb_id, l, r).await?;
if let Some(hold) = execution_gate::hold(&impact) {
utopia_store::resolution::escalate_review(
pool,
item.id,
&format!("escalate_impact|{hold}"),
)
.await?;
let held = match look.why.as_deref() {
Some(why) => format!("held for a person: {}; {why}", hold.explain()),
None => format!("held for a person: {}", hold.explain()),
};
gov::record(
pool,
kb_id,
NewDecision {
reason: Some(&held),
..decision("proposed", None)
},
)
.await?;
return Ok(());
}
let (target, source) = utopia_store::resolution::merge_direction(pool, l, r).await?;
match utopia_store::resolution::merge_entities(
pool, kb_id, source, target, None, &reason,
)
.await
{
Ok(merge_id) => {
utopia_store::resolution::close_review_auto(pool, item.id, "merged", &reason)
.await?;
let id = gov::record(pool, kb_id, decision("applied", Some(merge_id))).await?;
audit(ctx, "review.merge", item, conf, id).await;
}
// 同簇连锁合并已吞掉一方:留给人,并记一条 unsure 免得下一轮又撞上
Err(AppError::Conflict(_)) | Err(AppError::NotFound) => {
utopia_store::resolution::escalate_review(
pool,
item.id,
"escalate_entity_changed",
)
.await?;
gov::record(
pool,
kb_id,
NewDecision {
action: "unsure",
reason: Some("one side changed while this cluster was being decided"),
..decision("proposed", None)
},
)
.await?;
}
Err(e) => return Err(e.into()),
}
}
Gate::Apply => {
let reason = format!("governed|{conf:.2}");
// 关不上是这一对已经不是 pending(人裁了,或另一条路先到):不再记一条一样的裁决
let closed =
utopia_store::resolution::close_review_auto(pool, item.id, "kept", &reason).await?;
if closed > 0 {
let id = gov::record(pool, kb_id, decision("applied", None)).await?;
audit(ctx, "review.keep", item, conf, id).await;
}
}
Gate::Propose => {
utopia_store::resolution::escalate_review(pool, item.id, "proposed").await?;
gov::record(pool, kb_id, decision("proposed", None)).await?;
}
}
Ok(())
}
/// 第二层:带工具逐条再看。模型每回合要么查一样东西(查完把结果喂回去),要么
/// decide / defer 收尾。回合数封顶;模型不用工具收尾就提醒一次,再不收尾就当没定
async fn investigate(
ctx: &Ctx<'_>,
item: &ReviewItem,
pair: &utopia_extract::AdjudicationPair,
earlier: &Look,
) -> anyhow::Result<Look> {
let tools = governor::tools();
let mut messages = governor::messages(
pair,
&governor::EarlierLook {
verdict: match earlier.same {
Some(true) => "same",
Some(false) => "different",
None => "unsure",
},
confidence: earlier.conf,
why: earlier.why.as_deref(),
},
);
let mut trace: Vec<Value> = Vec::new();
let mut calls = 0;
let mut nudged = false;
let mut walls = 0;
let mut lookups = 0;
// 回合上限 = 查询次数 + 撞两次上限 + 一次提醒 + 收尾那一次。模型多半一回合只查一件事,
// 查够 MAX_STEPS 次常常还想再查:撞上限的那一回合得算在预算外,不然它连收尾的机会都没有
// (identity bench 上,第二眼「看了没收尾」九次里有五次是这么来的)
for _ in 0..(governor::MAX_STEPS + 4) {
let turn = {
let _permit = permit(ctx).await;
ctx.client.chat_tools(&messages, &tools).await?
};
calls += 1;
messages.push(turn.to_message());
if turn.tool_calls.is_empty() {
// 没调工具就说话:记下它说了什么,下次看轨迹能知道它卡在哪
trace.push(json!({ "said": turn.content.as_deref().unwrap_or("").chars().take(200).collect::<String>() }));
if nudged {
break;
}
nudged = true;
messages.push(json!({ "role": "user", "content": governor::NUDGE }));
continue;
}
for call in &turn.tool_calls {
match governor::read_step(&call.name, &call.arguments) {
Step::Decide {
same,
confidence,
why,
} => {
return Ok(Look {
same: Some(same),
conf: confidence,
why: Some(why).filter(|w| !w.is_empty()),
question: None,
trace,
calls,
});
}
Step::Defer { question } => {
return Ok(Look {
same: None,
conf: 0.0,
why: None,
question: Some(question),
trace,
calls,
});
}
Step::Lookup { tool, args } => {
let out = if lookups >= governor::MAX_STEPS {
walls += 1;
trace.push(
json!({ "tool": tool, "args": args, "note": "refused: lookup limit" }),
);
governor::LIMIT_REACHED.to_string()
} else {
lookups += 1;
let (out, note) = lookup(ctx, item, &tool, &args).await?;
trace.push(json!({ "tool": tool, "args": args, "note": note }));
out
};
messages.push(tool_result_message(&call.id, &out));
}
Step::Unknown(problem) => {
messages.push(tool_result_message(&call.id, &problem));
}
}
}
// 撞了两次上限还在查:不会收尾了,别再花回合
if walls >= 2 {
break;
}
}
// 看了,没收尾:当没定,轨迹留下
Ok(Look {
same: None,
conf: 0.0,
why: Some("the agent looked but did not conclude".into()),
question: None,
trace,
calls,
})
}
/// 跑一个工具:给模型的文本,以及写进轨迹的一句话
async fn lookup(
ctx: &Ctx<'_>,
item: &ReviewItem,
tool: &str,
args: &Value,
) -> anyhow::Result<(String, String)> {
let pool = &ctx.state.pool;
let kb_id = ctx.kb_id;
let side = |s: &str| {
if s == "A" {
&item.left
} else {
&item.right
}
};
let clip = |s: String| {
if s.chars().count() > TOOL_OUTPUT_CHARS {
let mut t: String = s.chars().take(TOOL_OUTPUT_CHARS).collect();
t.push_str("\n…");
t
} else {
s
}
};
let (out, note) = match tool {
"facts" => {
let s = args["side"].as_str().unwrap_or("A");
let e = side(s);
let lines = utopia_store::resolution::entity_fact_lines(pool, kb_id, e.id, 30).await?;
let n = lines.len();
let out = if lines.is_empty() {
"(no recorded facts)".to_string()
} else {
lines.join("\n")
};
(out, format!("{n} facts of {s} \"{}\"", e.name))
}
"quotes" => {
let s = args["side"].as_str().unwrap_or("A");
let e = side(s);
let rows = gov::quotes_of(pool, kb_id, e.id, 6).await?;
let n = rows.len();
let out = if rows.is_empty() {
"(no source passages)".to_string()
} else {
rows.iter()
.map(|(doc, q)| format!("[{doc}] {q}"))
.collect::<Vec<_>>()
.join("\n")
};
(out, format!("{n} passages about {s} \"{}\"", e.name))
}
"ledger" => {
let q = args["query"].as_str().unwrap_or("");
let rows = gov::ledger_search(pool, kb_id, q, 10).await?;
let n = rows.len();
let out = if rows.is_empty() {
"(no decisions by people about this name)".to_string()
} else {
rows.iter()
.map(|x| {
let verb = match x.action.as_str() {
"merge.revert" => "merge reverted",
"review.keep" => "kept apart",
_ => "merged",
};
// 人写的理由跟在后面:第二层去查台账,查到的该是「凭什么」
let because = x
.why
.as_deref()
.map(|w| format!("; they wrote: \"{w}\""))
.unwrap_or_default();
format!(
"\"{}\" ≟ \"{}\": {verb} by a person on {}{because}",
x.left,
x.right,
x.at.format("%Y-%m-%d")
)
})
.collect::<Vec<_>>()
.join("\n")
};
(out, format!("{n} decisions about \"{q}\""))
}
// 合并会牵动什么(0028):模型先看到闸门(0027)会看到的东西,再决定是裁还是问
"consequences" => {
let impact =
execution_gate::impact_of(pool, kb_id, item.left.id, item.right.id).await?;
let families = if gov::types_conflict(
item.left.type_label.as_deref(),
item.right.type_label.as_deref(),
) {
"\n- the two types belong to different families; the rules never merge across families"
} else {
""
};
let out = format!("{}{families}", impact.describe());
let held = execution_gate::hold(&impact)
.map(|h| h.to_string())
.unwrap_or_else(|| "nothing held".into());
(out, format!("what a merge would touch: {held}"))
}
"namesakes" => {
let q = args["query"].as_str().unwrap_or("");
let rows = gov::namesakes(pool, kb_id, q, 10).await?;
let n = rows.len();
let out = if rows.is_empty() {
"(no other entity with such a name)".to_string()
} else {
rows.iter()
.map(|x| {
format!(
"\"{}\" ({}) · {} facts{}",
x.name,
x.type_label.as_deref().unwrap_or("untyped"),
x.facts,
if x.merged {
" · merged into another"
} else {
""
}
)
})
.collect::<Vec<_>>()
.join("\n")
};
(out, format!("{n} entities named like \"{q}\""))
}
other => (
format!("no tool named {other}"),
format!("unknown tool {other}"),
),
};
Ok((clip(out), note))
}
/// 决策台账:actor 为空(机器),detail 里说是治理、置信度多少、对应哪条 agent 决定
async fn audit(ctx: &Ctx<'_>, action: &str, item: &ReviewItem, conf: f32, id: Uuid) {
let _ = utopia_store::audit::record_opt(
&ctx.state.pool,
Some(ctx.kb_id),
None,
action,
"review",
Some(item.id),
json!({
"left": item.left.name, "right": item.right.name, "score": item.score,
"confidence": conf, "via": "governor", "decision": id,
}),
)
.await;
}
/// 保险丝(0025 决定 9):这次打开以来、七天之内,人撤回 agent 的自动合并到了两次,
/// 开关自动关掉,发一条告警,台账记一笔。它替人做主做错了两回,该停下来等人再开;
/// 人再打开时 governance_since 更新,之前的撤回不再算
pub async fn fuse(state: &AppState, kb_id: Uuid) {
let pool = &state.pool;
let kb = match utopia_store::kbs::get(pool, kb_id).await {
Ok(kb) if kb.governance => kb,
_ => return,
};
let window = Utc::now() - Duration::days(gov::FUSE_WINDOW_DAYS);
let since = kb.governance_since.map_or(window, |s| s.max(window));
let reverts = match gov::reverts_since(pool, kb_id, since).await {
Ok(n) => n,
Err(e) => {
tracing::warn!(%kb_id, error = %e, "治理:数撤回失败");
return;
}
};
if reverts < gov::FUSE_REVERTS {
return;
}
match gov::trip(pool, kb_id).await {
Ok(true) => {}
Ok(false) => return,
Err(e) => {
tracing::warn!(%kb_id, error = %e, "治理:关开关失败");
return;
}
}
tracing::warn!(%kb_id, reverts, "治理:保险丝跳了,开关已关");
if let Err(e) = alerts::raise(
pool,
alerts::NewAlert {
kb_id: Some(kb_id),
severity: "warning",
kind: alerts::kind::GOVERNANCE_TRIPPED,
min_role: Role::Editor,
subject_type: Some("kb"),
subject_id: Some(kb_id),
detail: json!({
"kb": kb.name, "reverts": reverts, "window_days": gov::FUSE_WINDOW_DAYS,
}),
},
)
.await
{
tracing::warn!(%kb_id, error = %e, "上报 governance.tripped 失败");
}
let _ = utopia_store::audit::record_opt(
pool,
Some(kb_id),
None,
"kb.updated",
"kb",
Some(kb_id),
json!({ "governance": false, "via": "fuse", "reverts": reverts }),
)
.await;
state.emit_review(kb_id);
}
/// 人从合并历史撤回了一条合并:是 agent 自己裁的就记成 reverted,然后看保险丝
pub async fn after_revert(state: &AppState, kb_id: Uuid, merge_id: Uuid, user_id: Uuid) {
match gov::settle_by_merge(&state.pool, kb_id, merge_id, user_id).await {
Ok(Some(_)) => fuse(state, kb_id).await,
Ok(None) => {}
Err(e) => tracing::warn!(%kb_id, merge = %merge_id, error = %e, "治理:记撤回失败"),
}
}
/// 人裁了一对之后:这一对上开着的建议就是被回答了(与建议相同是接受,不同是改判);
/// 同名或同实体的对上的建议过时、那些对回到队列;开关开着就排一轮。
/// 人批量分开三对张伟,agent 顺着同一簇把剩下的照办——#428 要的自动处理就是这一步。
/// `action` 为 None 时不答本对的建议(Agent 队列那条路自己已经答过了)
pub async fn after_human_decision(
state: &AppState,
kb_id: Uuid,
review_ids: &[Uuid],
action: Option<&str>,
user_id: Uuid,
) {
for &id in review_ids {
if let Some(action) = action {
if let Err(e) = gov::answer_open(&state.pool, kb_id, id, action, user_id).await {
tracing::warn!(%kb_id, review = %id, error = %e, "治理:建议回答失败");
}
}
if let Err(e) = gov::supersede_siblings(&state.pool, kb_id, id).await {
tracing::warn!(%kb_id, review = %id, error = %e, "治理:建议作废失败");
}
}
match utopia_store::kbs::get(&state.pool, kb_id).await {
Ok(kb) if kb.governance => {
if let Err(e) = utopia_store::jobs::enqueue_unless_queued(
&state.pool,
"govern",
json!({ "kb_id": kb_id }),
)
.await
{
tracing::warn!(%kb_id, error = %e, "治理任务入队失败");
}
}
_ => {}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_doubtful_shape_stops_counting_once_the_evidence_was_read() {
let lease = gov::name_shape(
"Lease Agreement dated May 16, 2016, as amended",
"Lease Agreement",
);
assert!(name_doubts(lease), "{lease:?}");
assert_eq!(settled_shape(lease, false), lease);
assert_eq!(settled_shape(lease, true), gov::NameShape::Unrelated);
let version = gov::name_shape("Claude Mythos 5", "Claude Mythos");
assert!(name_doubts(version), "{version:?}");
assert_eq!(settled_shape(version, false), version);
// 形状本来就不起疑的,读没读过证据都照旧
let same = gov::name_shape("OpenAI", "OpenAI");
assert!(!name_doubts(same));
assert_eq!(settled_shape(same, true), same);
}
}