utopia 治理体系扩展:每一个 Review 队列都有人治理 —— 决策记录 0043 深度解读
utopia 治理体系扩展:每一个 Review 队列都有人治理 —— 决策记录 0043 深度解读
本指南围绕 utopia 仓库中的决策记录 0043-every-review-queue-is-governed.md 展开,结合 0025-governance-reads-the-ledger-before-it-decides.md、docs/design/governance.md 以及治理器源码进行印证与扩展。读完你将理解:为什么一个知识库的"除点头(nods)以外的每一条 Review 队列"都应该交给同一个治理器(governor),各队列如何保留属于自己的动作、模型如何裁决而服务器如何校验、以及每一个自动动作如何被撤销——即"每一条队列都有人治理"这一架构决策的完整理由、落地形状与当前进度。
问题的起点:0025 只治理了一条队列
0025 给出了 utopia 的第一个治理器:把"重复名字对"(duplicate pairs)交给一个先读台账(ledger)再裁决的 Agent。它带来了一套可复用的机制——按库开关(knowledge_bases.governance)、govern 任务、先例(precedents)注入提示词、置信度闸门(gate)、agent_decisions 记录表、保险丝(fuse)——但当时只覆盖了一类队列:重复对。
其余队列一直在等人:时间冲突(temporal conflicts)、低置信度事实(low-confidence facts)、证据被新版本替换的事实(stale facts)、公理违规(axiom violations)、本体缺陷(ontology defects)、概念映射(concept mappings)。决策 0025 的"Open questions"里明确留下了这个问题——"Other queues"。
文档开篇用 Blackbaud 租赁基准(lease bench)上的一个真实例子点出代价:
时间线上有一个截止日被往回压了,因为模型把修订后的新日期标成了 0.7(低置信度)。一个冲突在等一个人,而"as-of"问题带着两个答案回来了。重复队列有一个 Agent,冲突队列和低置信度队列只有一位永远不会来的真人。
关键机制在于:低置信度的继任事实不能接管它的前任(见 0022),所以图会同时给出两个答案——一个知识库在无人打理(uncrated)的基座上,这些队列只会越积越多,而被它们压住的东西是真实的业务事实。2026-09-14 的决策就此定下:除 nods 以外,每一条队列都被治理。
决策总览
| 决策 | 主题 | 一句话摘要 |
|---|---|---|
| 1 | 一个治理器,除 nods 外所有队列 | govern 任务先跑 0025 的重复对轮次,再跑事实队列,最后跑冲突;顺序是因果性的 |
| 2 | 每队列保留自己的动作 | 事实:confirm / reject;冲突:close_old / retime_new / keep_both / reject_new;动作就是人点击时调用的同一个 store 函数 |
| 3 | 模型决定、服务器校验 | 每批八个、带证据与先例;服务器能查的绝不轻信模型 |
| 4 | 每个动作可撤销 | agent_decisions.detail 记录撤销所需的一切,人可从 Agent 队列一键 Revert |
| 5 | 置信度是时间线的一部分 | set_confidence 像撤回一样锁定时间线、改值并重算 |
决策 1:一个治理器,除 nods 外每一条队列
govern 任务的轮次顺序是因果性的,不能随意调换:
- 先跑 0025 的重复对轮次(duplicate rounds);
- 再跑事实队列(fact queues:低置信度、陈旧);
- 最后跑冲突(conflicts)。
为什么顺序如此严格?一次合并(merge)会改变哪些事实共享同一条时间线;而一条被确认的事实会撤掉它被卷入的冲突(决策 5)——如果先处理冲突、后处理合并,冲突的裁决基于的是合并之前的图,落地后可能已经过时。
工程约束与 0025 完全一致:同一个开关启动和停止它(开关关闭时任务在下一个簇边界停下,已裁决的不回滚);同一个保险丝(0025 决策 9)把任何种类的撤回都计入触发条件;同一个小时级扫描(hourly sweep)找出有积压(backlog)的基座;并且抽取(extraction)在治理基座上的每一份文档结束后都会入队一次 govern 任务——因为冲突和低置信度事实正是从抽取中产生的,而不只是重复对。
nods 留在队列之外(pending_facts,见 0015):一句被记住的话要在说出它的那个人点头之后才成为事实,Agent 替人点头会把一句随口之言变成断言。0025 说过同样的话,0043 重申了它。
决策 2:每条队列保留自己的动作,而它们是人的动作
各队列的动作各不相同,因为它们对图(graph)做的事本来就不同:
| 队列 | 动作 | 含义 |
|---|---|---|
| 事实(facts) | confirm |
确认低置信度/陈旧事实 |
| 事实(facts) | reject |
拒绝该事实 |
| 冲突(conflicts) | close_old |
关闭旧值,让新值接管 |
| 冲突(conflicts) | retime_new |
修正新值的时间,保留双方 |
| 冲突(conflicts) | keep_both |
两个都保留 |
| 冲突(conflicts) | reject_new |
拒绝新值,保留旧值 |
关键设计:每个动作调用的是真人点击时调用的同一个 store 函数——temporal::set_confidence、temporal::retract、temporal::resolve_conflict、temporal::correct_interval。因此 Agent 的裁决与人的裁决在图中留下完全相同的形状(the same shape),审计、时间线重算、后续读取都不会因为"这是机器裁的"而走另一条路径。
retime_new 是唯一一个真人通常通过区间编辑器(interval editor)而非冲突卡片(conflict card)触发的动作。它存在的原因很具体:合同链(contract chains)上最常见的并发冲突,是继任事实的起始时间被模型取错了日期——不是该不该接管的问题,而是时间写错了的问题,所以需要"重新定时间"而不是"关旧值"或"拒新值"。
决策行(decision row)落在 agent_decisions 表中,用 target_kind 表明它属于哪条队列。两个字段承担了关键职责:
summary记录被裁决对象在裁决时刻的样子:一个事实或一条冲突没有"一对名字"可以在日后用来连接(不像重复对有 left/right 两个名字),而且它的行之后会被重写,所以必须把裁决时的快照留在这里;detail记录动作的参数,以及撤销它需要的一切(见决策 4)。
决策 3:模型决定,服务器检查一切可检查的
调用形状:每批八个(a batch of eight)一次模型调用,每个条目携带自己的证据——所属文档、文档自身的日期、引文(quote)——以及该队列近期的人类决定作为先例。先例规则沿用 0025 与 0026:只有带 actor(真人)的行才算数,Agent 自己的行永远不能引用自己;人接受过的提案算,因为接受走的是人的裁决路径、记为人的决定。
模型返回一个动作、一个置信度和一句话理由。达到 AUTO_CONF 就落地(applied),低于它则成为提案(proposal)。当前仓库中重复对队列的 AUTO_CONF = 0.85(见 crates/utopia-store/src/governance.rs),比批量裁决器的 0.8 高一点——"那一档只看这一对,这里是替人做主"。
凡服务器能核验的,模型对世界的说法一律不被信任:
close_old或retime_new的日期必须出现在证据里:事实的起始时间、某份文档的自身日期、或引文明确写出的某一天。日期是继任事实证据唯一可对照的东西,而"取错日期"恰恰是冲突最常见的来源——所以这条是硬校验。- 确认一条陈旧事实,必须引用其文档的当前版本,并且该引文必须真的出现在当前版本中。随后这段引文被附为证据(evidence)——正是"附上证据"这一动作把该事实从陈旧队列里取出来。
一条校验失败,会把自信的裁决降级为提案(proposal),并说明为什么被拦下——不是静默地丢弃,而是变成一行带着理由、等人回答的记录。
决策 4:每一个动作都可以被撤销
已落地(applied)的决策在 detail 中记录它的撤销方式。原文的撤销表必须完整保留:
| 动作 | 撤销(Undo) |
|---|---|
| 确认低置信度事实(Confirm a low-confidence fact) | 恢复其先前的置信度 |
| 确认陈旧事实(Confirm a stale fact) | 移除附上的证据 |
| 拒绝事实(Reject a fact) | 恢复该事实(temporal::restore) |
close_old、retime_new |
使重写的行失效并恢复原行(temporal::undo_rewrite);原行再次到达,因此它的冲突会被再次记录 |
keep_both |
重新打开冲突 |
reject_new |
恢复事实并重新打开冲突 |
人在 Agent 队列中作答:接受或改判一条提案,或者撤销(Revert)一条已落地的决策。一次改判(override)走与人的点击完全相同的路径,因此成为下一次裁决的先例——决策理由的沉淀由此闭环。
决策 5:置信度是时间线的一部分
确认一条事实会改变它是否能够接管(may take over),因此 set_confidence 必须像撤回(retraction)一样:锁定该事实的时间线 → 改值 → 重算时间线。这不是一次普通更新,而是与时间引擎联动的一次结构性操作。
由此带来的级联效果:一条"低置信度冲突"(low-confidence conflict),如果重算之后它的那一对已经不再成立,就会被撤销——它曾经提出的问题"这个可疑的值能否接管",已经得到了回答。确认与重算解耦的设计在"死胡同"一节有更充分的论证。
读者(人)在界面上看到什么
- 事实与冲突的 Agent 行,以
summary取代"两个名字"来呈现被裁决对象; - 一条提案用该队列自己的动作来回答(不是通用的 approve/dismiss);
- 一条已落地决策提供 Revert,撤销它做过的一切;
- 台账行(ledger rows)是队列自己的动作(
fact.confirm、conflict.close_old、……),没有 actor(机器所为),与重复对治理器的记账方式一致——机器决策在台账中同样是匿名、可审计、可追溯的事件。
死胡同:三条被明确拒绝的设计
决策记录的价值一半在于记录"为什么不做"。0043 记录了三条:
- 给所有队列一个通用的"批准 / 驳回"动作。 被拒绝,因为各队列的决策对图做的是不同的事:关掉一个值(close a value)与两个都保留(keep both)是不同的图。通用批准最终还是要映射回各队列自己的动作上,而模型在裁决时根本不知道自己在选哪一个——让模型为一个不存在的抽象负责,只会更糟。
- 让模型自由设置关闭日期。 被拒绝,因为日期是继任事实证据唯一可以对照的东西,而模型最常犯的错恰好就是冲突产生的那一个(取错日期)。放开这个口子等于让最容易出错的一步失去校验。
- 在确认事实时顺带解决它被卷入的冲突。 被拒绝,因为确认动作不知道自己回答了哪些冲突;重算(recompute)才知道——正是重算这个机制"握着"那一对。让确认去解决冲突,是让错误的层做决定。
开放问题:cut 2 与后续
- Cut 2:违规(violations)、本体缺陷(ontology defects)、概念映射(concept mappings)。 文档指出:违规的
fact_retracted与fact_closed适配 0043 的形状;但axiom_relaxed会改变本体,而缺陷的fixed意味着"人改过了"——这两类在 Agent 可以落地之前都需要一道闸门(a gate)。 - 第二层(the second look)。 事实与冲突队列还没有工具循环(0025 决策 5 的第二层)。当前批处理直接看证据;当提案反复追问批处理看不到的东西时,再给这两条队列加工具循环。
- 界面。 Agent 队列以最小改动呈现这些行;但队列卡片本身还没有像重复对卡片那样内联展示 Agent 的提案。
与当前仓库源码的对应:决策已定,代码曾建又被撤回
0043 的状态行是一份罕见的"决策与代码不同步"的诚实记录:
- Cut 1 曾建于 PR #699:迁移 0058 将
agent_decisions拓宽到fact与conflict(新增summary、detail),queue_agent行走低置信度与陈旧事实、随后在同一个govern任务的重复对轮次之后处理时间冲突,Agent 队列中每个已落地的动作都可撤销。 - 该 PR 于 2026-09-17 关闭,等待 0044 cut 2(开放图 + 对齐)稳定后再重新落地。违规、本体缺陷与概念映射属于 cut 2。
- 2026-09-20 记录被恢复回 dev:文件曾随 PR #699 离开 dev,但其编号被保留并被 docs/design/governance.md 与 docs/design/time.md 引用。"记录是推理,推理从未被撤回,所以这份文件理应在这里,无论分支发生了什么"——只有状态行被重写。
因此,从当前仓库源码看,治理器仍只处理重复对队列:govern 任务的实现位于 crates/utopia-server/src/governance.rs,其中 apply 落地路径写的是 review.merge / review.keep,决策行写入时 target_kind = 'review';队列、先例、闸门与保险丝位于 crates/utopia-store/src/governance.rs,AUTO_CONF、SUPPORTED_CONF、TYPE_PAIR_MIN 等常量、gate 纯函数与 name_shape / type_family 两条不靠模型的硬规则都在这里,并有完整的单元测试覆盖(如 the_agent_judges_and_history_moves_the_bar、hard_rules_come_first、a_version_or_a_phrase_never_merges_on_its_own)。时间引擎侧,crates/utopia-store/src/temporal.rs 当前提供 retract、correct_interval、resolve_conflict 等动作;set_confidence、restore、undo_rewrite 属于 0043 蓝图中描述的 store 函数,随 PR #699 的撤回暂不在 dev 分支上。
这份"决策超前于代码"的状态本身正是决策记录机制的体现(见 docs/decisions/README.md 的约定:修订留在原地、改结论要记下为什么、实现 PR 必须更新状态行)。对阅读者而言,docs/design/governance.md 将 0043 列为"Proposed and not built",并把 #725 提到的拆分方案一并记录:时间修复先合入,冲突动作成为冲突队列,低置信度处理被移除——后续落地顺序有据可查。
延伸阅读
- 0025-governance-reads-the-ledger-before-it-decides.md:治理器的原始设计,0043 的直接前身(先例、开关、闸门、第二层、保险丝、身份规则)。
- 0026-a-decision-records-why.md:人的"为什么"成为先例。
- 0027-an-automatic-merge-is-gated-by-what-it-can-undo.md:自动合并的执行闸门——"只能动可撤销的东西"。
- 0022-an-unknown-date-is-not-an-open-one.md:0043 所治理的时间冲突背后的时间引擎。
- 0015-recording-a-sentence-is-not-asserting-a-fact.md:nods 为什么留在人手里。
- docs/design/governance.md:治理域的浓缩设计,含 0043 的落地状态与 #725 拆分。