World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
The records catch up with the code, and say what comes next (#188)
WaylandYang9446f8255006
diff --git a/Cargo.lock b/Cargo.lockindex afdd530a..1710a8ee 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -4734,10 +4734,6 @@ version = "1.0.4"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"-[[package]]-name = "utopia-connectors"-version = "0.1.0"-[[package]]name = "utopia-core"version = "0.1.0"@@ -4765,10 +4761,6 @@ dependencies = ["utopia-llm",]-[[package]]-name = "utopia-graph"-version = "0.1.0"-[[package]]name = "utopia-ingest"version = "0.1.0"@@ -4806,10 +4798,6 @@ dependencies = ["tracing",]-[[package]]-name = "utopia-mcp"-version = "0.1.0"-[[package]]name = "utopia-reason"version = "0.1.0"diff --git a/Cargo.toml b/Cargo.tomlindex af52b8aa..36502a06 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -6,12 +6,9 @@ members = ["crates/utopia-server","crates/utopia-ingest","crates/utopia-extract",- "crates/utopia-graph","crates/utopia-reason","crates/utopia-search","crates/utopia-llm",- "crates/utopia-mcp",- "crates/utopia-connectors",][workspace.package]diff --git a/crates/utopia-connectors/Cargo.toml b/crates/utopia-connectors/Cargo.tomldeleted file mode 100644index c7916a4c..00000000--- a/crates/utopia-connectors/Cargo.toml+++ /dev/null@@ -1,7 +0,0 @@-[package]-name = "utopia-connectors"-version.workspace = true-edition.workspace = true-license.workspace = true--[dependencies]diff --git a/crates/utopia-connectors/src/lib.rs b/crates/utopia-connectors/src/lib.rsdeleted file mode 100644index f1171457..00000000--- a/crates/utopia-connectors/src/lib.rs+++ /dev/null@@ -1,3 +0,0 @@-//! utopia-connectors: placeholder. External source connectors (S3/WebDAV, Notion,-//! Feishu) live here once built; today's web and RSS sync is in utopia-server.-//! See the Roadmap in README.md.diff --git a/crates/utopia-graph/Cargo.toml b/crates/utopia-graph/Cargo.tomldeleted file mode 100644index 22901933..00000000--- a/crates/utopia-graph/Cargo.toml+++ /dev/null@@ -1,7 +0,0 @@-[package]-name = "utopia-graph"-version.workspace = true-edition.workspace = true-license.workspace = true--[dependencies]diff --git a/crates/utopia-graph/src/lib.rs b/crates/utopia-graph/src/lib.rsdeleted file mode 100644index 9c14917b..00000000--- a/crates/utopia-graph/src/lib.rs+++ /dev/null@@ -1,3 +0,0 @@-//! utopia-graph: placeholder. Graph traversal and neighborhood queries currently-//! live in utopia-store; this crate is where they land once they outgrow it.-//! See the Roadmap in README.md.diff --git a/crates/utopia-mcp/Cargo.toml b/crates/utopia-mcp/Cargo.tomldeleted file mode 100644index 3e404620..00000000--- a/crates/utopia-mcp/Cargo.toml+++ /dev/null@@ -1,7 +0,0 @@-[package]-name = "utopia-mcp"-version.workspace = true-edition.workspace = true-license.workspace = true--[dependencies]diff --git a/crates/utopia-mcp/src/lib.rs b/crates/utopia-mcp/src/lib.rsdeleted file mode 100644index f599daef..00000000--- a/crates/utopia-mcp/src/lib.rs+++ /dev/null@@ -1,3 +0,0 @@-//! utopia-mcp: placeholder. MCP server exposing knowledge and agent memory as-//! tools (add_memory / search_memory / get_entity_timeline).-//! See the Roadmap in README.md.diff --git a/crates/utopia-server/src/bootstrap_ontology.rs b/crates/utopia-server/src/bootstrap_ontology.rsindex 0f566c3f..3b76f7a2 100644--- a/crates/utopia-server/src/bootstrap_ontology.rs+++ b/crates/utopia-server/src/bootstrap_ontology.rs@@ -1,8 +1,9 @@//! 自动扩本体:抽取遇到本体外的说法时,把它补进本体并改写等它的那些事实。//!-//! 新建的库只有 10 个默认关系——那不是任何人选的,是种子数据。传进第一批-//! 文档,里面的关系大半不在这 10 个里,于是大量事实降级成 related_to,-//! 图基本没法用,直到有人坐下来点 Suggest、看提案、逐条 Add。+//! 新建的库不种任何关系,起点是用户挑的本体包(0008)或者空着。包再大也装不下+//! 一份语料的全部说法:落不上本体的事实谓词留空、原词记在证据上(0010),+//! 图上这些边只有原文措辞、没有词表语义,直到有人坐下来点 Suggest、看提案、逐条 Add。+//! 这个模块把那件事自动化:说法够普遍就建成关系,并把等着它的事实改写过去。//!//! 敢这么做的前提是采纳可撤销(见 graph::unadopt):错了点一下就回去,//! 旧事实从来没被销毁过。所以判断轴不是"有多确信"而是"错了有多贵"。diff --git a/crates/utopia-store/src/graph.rs b/crates/utopia-store/src/graph.rsindex 41652dba..50f5d553 100644--- a/crates/utopia-store/src/graph.rs+++ b/crates/utopia-store/src/graph.rs@@ -310,31 +310,6 @@ pub async fn insert_value_fact(.await}-/// 已确认(置信 ≥ threshold)的问数映射:概念名 + 定义。问数 prompt 注入用。-pub async fn confirmed_mappings(- pool: &PgPool,- kb_id: Uuid,- threshold: f32,- limit: i64,-) -> AppResult<Vec<(String, serde_json::Value)>> {- let rows: Vec<(String, serde_json::Value)> = sqlx::query_as(- "SELECT s.canonical_name, f.object_value- FROM facts f- JOIN relation_types r ON r.id = f.predicate_id AND r.key = 'mapped_to'- JOIN entities s ON s.id = f.subject_id- WHERE f.kb_id = $1 AND f.invalidated_at IS NULL AND f.valid_to IS NULL- AND f.object_value IS NOT NULL AND f.confidence >= $2- ORDER BY s.canonical_name- LIMIT $3",- )- .bind(kb_id)- .bind(threshold)- .bind(limit)- .fetch_all(pool)- .await?;- Ok(rows)-}-/// `proposed`:模型在这一块里实际提议的谓词。命中本体时它等于 key,/// 本体外的谓词不落到关系上时,它是唯一还留着原意的东西——事实行上只剩/// "有关联",原文说的"runs on"就靠这里活下来。@@ -806,23 +781,8 @@ pub async fn confirm_fact(pool: &PgPool, kb_id: Uuid, fact_id: Uuid) -> AppResulif res.rows_affected() == 0 {return Err(AppError::NotFound);}- // 问数映射的口径唯一性:确认 (概念, 源) 的新定义 = 背书替换,同源旧映射作废。- // 认知轴修正(旧口径是"我们当时的理解",不是世界里结束的状态);- // 唯一性只活在这条确认流里,时态引擎保持领域无关。- sqlx::query(- "UPDATE facts f SET invalidated_at = now()- FROM facts nf- JOIN relation_types r ON r.id = nf.predicate_id- WHERE nf.id = $1 AND r.key = 'mapped_to'- AND f.kb_id = $2 AND f.id <> nf.id- AND f.subject_id = nf.subject_id AND f.predicate_id = nf.predicate_id- AND f.invalidated_at IS NULL- AND f.object_value->>'source' = nf.object_value->>'source'",- )- .bind(fact_id)- .bind(kb_id)- .execute(pool)- .await?;+ // 从前这里还有一段:确认 `mapped_to` 事实时把同 (概念, 源) 的旧映射作废。+ // 映射已搬出账本(0011,`concept_mappings` 自己管唯一性),那段 SQL 恒匹配零行,删了。Ok(())}diff --git a/crates/utopia-store/src/reasoning.rs b/crates/utopia-store/src/reasoning.rsindex 15b39ff8..56db5af4 100644--- a/crates/utopia-store/src/reasoning.rs+++ b/crates/utopia-store/src/reasoning.rs@@ -456,7 +456,7 @@ async fn compile_rules(if a.symmetric {want.push((pred, "symmetric"));}- // 后两种是 0017 补上的规则源。**规则挂在「有声明的那一侧」**——+ // 后两种是迁移 0016(a_relation_can_name_its_inverse)补上的规则源。**规则挂在「有声明的那一侧」**——// 归一化过的逆两边都有声明,所以两个方向各得一条规则,与它们各自// 推出的派生对得上if a.inverse_of.is_some() {diff --git a/crates/utopia-store/src/resolution.rs b/crates/utopia-store/src/resolution.rsindex 8376ba68..e794f31d 100644--- a/crates/utopia-store/src/resolution.rs+++ b/crates/utopia-store/src/resolution.rs@@ -106,8 +106,11 @@ pub fn recall_keys(name: &str) -> Vec<String> {/// 易混具体类型:抽取常在这几类间摇摆(一个团队算组织还是项目?平台算项目还是产品?)。/// 同名跨这组类型 → 照建实体(宁分勿合),但入队审核对交 LLM/人工裁决。-/// DESIGN.md §3.2 的 disjoint 公理目前只是设计面(0005 仅落了 subClassOf 数据面),-/// 公理落库后这张表应改从本体读取。+///+/// **这张表该从本体读,今天还没有。** `owl:disjointWith` 已经落库(`entity_type_disjoint`,+/// 有导入有编辑),但消费者只有推理机的本体自检;消解这边仍按这三个硬编码的 key 判。+/// 没装包的库里这三个 key 不存在,于是这一档永不命中,所有跨类型同名判 `Disjoint`——+/// 变严不变松,不会错合。改从本体读是 0016 的 B3。pub const CONFUSABLE_TYPE_KEYS: &[&str] = &["organization", "project", "product"];/// 单次消解最多入队的漂移审核对(防同名大组刷爆审核队列)。diff --git a/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs b/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rsindex 870eda7e..51b32441 100644--- a/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs+++ b/crates/utopia-store/tests/a_token_is_the_person_but_not_all_of_them.rs@@ -1,4 +1,4 @@-//! 个人访问令牌(0014 / 迁移 0015)。+//! 个人访问令牌(0014 / 迁移 0017)。//!//! 这一枚令牌是给 MCP 客户端用的:长命、配在别人机器上的一个文件里、以发它的//! 人的身份行事。所以它必须撤得掉、过得了期、而且**范围只能比这个人更小**。diff --git a/docs/decisions/0001-ontology-import-and-governance.md b/docs/decisions/0001-ontology-import-and-governance.mdindex c709bcf5..c63cf84d 100644--- a/docs/decisions/0001-ontology-import-and-governance.md+++ b/docs/decisions/0001-ontology-import-and-governance.md@@ -1,6 +1,6 @@# 0001 · 本体导入与治理路线-- **状态**:进行中 · P0(实体可编辑)、P1(停止静默丢弃)、P2(OWL 导入)、P2c(属性落库 / 关联表 / 类型签名 / 多继承)已建成;P3a(类型消解)已建成但检索命中率不足以自动跑,见下方修订记录;P3b 部分建成,见 [0003](0003-ontology-growth-loop.md);**P4a(决策不可被遗忘)已建成,P4b/P4c 待做**;P5 由 [0002](0002-reasoning-engine.md) 取代+- **状态**:进行中 · P0 / P1 / P2 / P2c 全部建成;P3 的「按预算切换」已落地(部署级 `ontology_prompt_budget`,缺省 24,000 字符,超了按块检索),P3a 建成但**只能手动触发**、没有类数阈值这根轴;P3b 两条腿都建成但形态与本文不同(原词落 `fact_evidence.proposed_predicate`,映射由 `predicate_match` + [0003](0003-ontology-growth-loop.md) 的采纳回路承担);**P4a 已建成,P4b / P4c 仍待做**;**P5 已由 [0002](0002-reasoning-engine.md) 落地,`utopia-reason` 不再是空壳**;判据 2 关于「参数顺序」的那一半已被 [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 推翻。2026-09-02 对照代码复核,修订就地- **成文**:2026-08-27 / 28,随调研持续修订(约定见 [README](README.md))> 理由比清单重要——清单会过期,理由决定以后遇到新情况怎么判。所以本文把「贯穿性判据」放在分阶段之前,且推翻过的判断就地留痕(见 P1、P3 的修订记录)。@@ -51,6 +51,7 @@1. **不是"OWL 有没有",是"我们有没有机器消费它"**——但要加时间维度:**丢弃不可逆,保存近乎免费**。所以原文一律保真,投影只覆盖当下用得上的。推论:**保留了原文,投影就不必语义完整**——简化是 UI/提示词层的取舍,不是数据损失。2. **本体是引导,不是执法**。声明可能是错的(`part_of` 就是),所以本体应当影响提示词与候选排序,而不是驱动丢弃、覆盖、自动改写。错误的引导模型能靠原文覆盖;错误的执法会系统性地毁数据。+ > **修订(2026-09-02,据 [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md))**:这条要拆成两半。**哪些类型能参与**仍是引导——本体可能写错,原文说西雅图就写西雅图。**参数顺序**改成执法:它不是关于世界的断言,是这个 key 的编码约定,原文从来没有「说了别的方向」。主语违反 domain 而宾语符合时按签名对调,留 `direction_corrected` 痕迹;对调也不合法则丢掉谓词、保留主宾与证据。留痕的自动动作不属于本条反对的那一类。实测五轮:违反率 57% → 4%,真·反向 39 → 0。3. **提示词大小必须与本体规模脱钩**。把 N 个类塞进每个分块的提示词,成本是 O(分块 × 本体),而且模型从 800 个选项里挑反而更差。规模问题用检索解,不用"少列几个"解。4. **同名不能传递任何结论**。判定为同一实体 → 本来就一个类型,无所谓传递;判定为不同 → 名字正是我们刻意不信任的信号(两个张伟)。能携带信息的是上下文。5. **不确定性浮到人面前**,不要悄悄猜。分层阈值 + 灰区进 Review,与消解的"宁分勿合"同源。@@ -96,9 +97,9 @@| 269 | 既无 `value` 也无 `object` | 真丢弃 || 274 | datatype 归一化失败 | 有 `debug!` 日志,但用户不可见 |-关系路径另有两条值得记:`confidence < 0.6`(第 234 行,设计阈值,但同样不可见——用户无从知道"抽到了但不够自信")与 `related_to` 不在本体时**整条事实消失**(第 380 行,删掉默认关系就会踩到)。+关系路径另有两条值得记:`confidence < 0.6`(第 234 行,设计阈值,但同样不可见——用户无从知道"抽到了但不够自信")与 `related_to` 不在本体时**整条事实消失**(第 380 行,删掉默认关系就会踩到)。〔**后者已不可能发生**:`related_to` 整个删掉,落不上就是 `predicate_id = NULL`,见 [0010](0010-no-relation-is-no-relation.md)。〕-**顺带发现一个不一致**:关系路径上主宾未声明时会**兜底按 `concept` 消解**(332-362 行),属性路径上同样的缺失却直接丢(255 行)。同一个原因,一边宽容一边静默丢弃。要么两边都兜底,要么两边都记信号——不能一边一个样。+**顺带发现一个不一致**:关系路径上主宾未声明时会**兜底按 `concept` 消解**(332-362 行),属性路径上同样的缺失却直接丢(255 行)。同一个原因,一边宽容一边静默丢弃。要么两边都兜底,要么两边都记信号——不能一边一个样。〔**已消除**:`concept` 兜底类随 [0009](0009-no-type-is-a-type.md) 删掉,两条路径现在都记 `subject_not_declared`。丢弃原因码今天有 12 个(`extraction_drops::reason`),含 `truncated_reply`、`malformed_item`、`not_an_entity_name`、`direction_corrected`,比本节设想的多一倍。〕**做**- 新表 `extraction_drops (kb_id, document_id, reason, detail, count, example, updated_at)`,PK `(kb_id, document_id, reason, detail)`,抽取开始时按 document 清空@@ -179,7 +180,7 @@ v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_membe**个体(ABox)永不作为事实导入**——不是能力问题,是原则:每条事实必须有证据链和出处,凭空塞进来的实例破坏的正是这个地基。它们随原文件保存,将来推理机可当背景知识读。-**依赖**:`oxttl` + `oxrdfxml`(Oxigraph 那套小而专的 crate)。不引 `horned-owl`,我们不需要推理。工作区目前无任何 RDF 依赖。+**依赖**:`oxttl` + `oxrdfxml`(Oxigraph 那套小而专的 crate)。不引 `horned-owl`,我们不需要推理。工作区目前无任何 RDF 依赖。〔已引入,住在 `utopia-ingest`。〕> **修订记录 · P2a + P2b 已落地**(`feat/owl-import`)>@@ -199,8 +200,10 @@ v2: http://acme.com/hr#Employee rdfs:label "Staff Member" → key = staff_membe> 哪个**——这正是本文论证 IRI 必要性时用的那个例子,只是换了个方向出现。所以:> 报告,不解决。想要导入的那份,先给现有的改名。>+> 〔**后来改了一半**(#78、#145):本地同名行**没有 IRI**时被认领——它是种子或手工建的占位者,被词表接管否则整棵树是断的;认领时形状跟着改成「方」(词表声明的)。两边都有 IRI 而 key 撞车的仍然报告不解决。〕+>> **暂未落地的三件**——属性落库、domain/range 关联表与类型签名、多继承 DAG——-> 照着 P2b 的产物重新算过账,独立成节:见下方 **P2c**。初稿在这里写的依赖顺序+> 照着 P2b 的产物重新算过账,独立成节:见下方 **P2c**。〔四件均已落地,见 P2c 末尾。〕初稿在这里写的依赖顺序> 有一处高估了(属性落库要等的那个映射,P2b 里已经建好了),那节里就地留痕。>> **一个自己犯的错值得记**:`OntologyImportView` 的字段叫 `imported_at`,前端类型@@ -342,6 +345,10 @@ OWL 里一个属性有多个 domain 是常态。`datatype` 仍留在 `relation_t前三项是一条链,第四项可以并行。+> **修订记录(2026-09-02):四项全部建成。** 属性由导入器建(`create_attribute_with_iri`);`relation_type_domains` / `relation_type_ranges` 建表;+> 签名进提示词(`works_at (person → organization)`),且只提铺出去的类,整侧没选中退回 `*`;`parent_id` 单列**已不存在**,多父落 `entity_type_parents`(带 `is_primary` 供左栏画树),+> 判定改成广度优先加访问集。另一处与本文不同:`update_relation_type` 现在**允许改 domain / range**——签名不是身份,`kind` 仍不可变。+> 全部 OWL 公理的投影现状见 P5 的修订。---@@ -379,6 +386,9 @@ OWL 里一个属性有多个 domain 是常态。`datatype` 仍留在 `relation_t> 跟着裁。预算按 token 数而不是类数量——类描述长度差着数量级。**预算定在哪还没量**,> 那需要把内联类数从 12 逐级加到 968,看事实数与耗时在哪一档开始掉。>+> 〔**已落地**,见 [0006](0006-ontology-scale-and-the-prompt.md):预算按**字符**而非 token,落在 `deployment_settings.ontology_prompt_budget`(24,000),每块 40 类 / 30 关系 / 30 属性,三个数都标着「待测」。+> 「种子基类永远在场」在 #128 之后失效(没有种子了),换成**祖先补齐**:命中什么就把它的祖先一起铺出去。本文下方与开放问题里的「阈值 30」这根轴**从未存在过**。〕+>> **三、第二层建成了,但比原文写的复杂**,见下。#### P3a · 类型消解实测(已建成)@@ -470,7 +480,7 @@ related_to 事实 359 条**放在 `fact_evidence` 上,不是 `facts` 上**:`insert_fact_inner`(`graph.rs:164-175`)按 `(kb_id, subject_id, predicate_id, object_id)` 对存活事实去重,所以一条 `(A, related_to, B)` 会吸收多个分块——甲块说 "runs on"、乙块说 "optimized for",合并成同一行。放 `facts` 上就是**先写者胜、其余静默丢弃**,正是本条要修的毛病。`fact_evidence` 每分块一行、已带 `quote`(该块的原文佐证),表层谓词是同一种东西:每次观察的原始形态。粒度对,且无需新增语义。-加 `fact_evidence.surface_predicate TEXT`,两条路径都写(关系路径写降级前的 `f.predicate`;正常命中时写模型实际给的那个词,因为它可能是别名)。不等映射落地就有独立价值——Review 与实体面板可直接展示"原文说的是 available from,被降级成 related to",而今天前端对 `related_to` 无任何特殊处理(`web/src/` 里零命中),降级对用户完全不可见。+加 `fact_evidence.surface_predicate TEXT`〔落地时列名叫 **`proposed_predicate`**,下同〕,两条路径都写(关系路径写降级前的 `f.predicate`;正常命中时写模型实际给的那个词,因为它可能是别名)。不等映射落地就有独立价值——Review 与实体面板可直接展示"原文说的是 available from,被降级成 related to",而今天前端对 `related_to` 无任何特殊处理(`web/src/` 里零命中),降级对用户完全不可见。**映射不取代 miss 报表**:反复出现又映射不上的(`available_from ×9`)正是"本体该加这个关系"的治理信号(P4 燃料)。映射只吃高置信的那部分,其余留在 miss 里变建议。@@ -486,6 +496,10 @@ related_to 事实 359 条**第一次抽取一定有类型**:`entities.type_id NOT NULL`,没有"未分类"状态。粗类是真类型不是占位符,小本体下它就是最终类型。升格挂在文档抽取完成的同一条任务链上(与攒批裁决并列),窗口是秒级。+> **修订记录(2026-09-02):这一段两句都反了。** `type_id` 已改为可空([0009](0009-no-type-is-a-type.md)),「没有类型」就是没有类型,且可能是**人的决定**(`type_source = human`)。+> 「升格挂在同一条任务链上」**没有实现**:抽取结束只入队 `bootstrap_ontology` 与 `adjudicate_entities`,类型消解今天只能在本体页手动跑 preview → apply。+> 原因见 P3a——检索命中率不足以自动跑。这是一个真缺口,不是取舍:**大本体下新实体的细化依赖人记得去点一下**。+---### P4 · 治理即经验@@ -532,7 +546,7 @@ related_to 事实 359 条> **排期已由 [0002](0002-reasoning-engine.md) 取代**。本节列的"届时能消费什么"仍然成立,但顺序变了:0002 实测发现语料第一天就带 `part_of` 环(传递闭包在深度 5 起振荡不收敛),所以推理机的第一交付是**一致性检查**而非推导——同一套求值引擎反过来用,零风险,且现存 11 处矛盾立刻可查出。-`utopia-reason` 目前是 3 行空壳。它上线后能消费的,正是 P2 保留而未投影的那些公理:+`utopia-reason` 目前是 3 行空壳〔**已建成**,近两千行:R0 一致性检查与本体自检、R1 物化推导带开关,见 [0002](0002-reasoning-engine.md) 的修订〕。它上线后能消费的,正是 P2 保留而未投影的那些公理:- `TransitiveProperty` → "NVIDIA 名下所有东西"(现在只能靠 hops 逐跳猜)- 非 1 的基数被违反 → **一致性告警进 Review 队列**,本体成为数据质量规则@@ -542,14 +556,19 @@ related_to 事实 359 条**这些今天全部读不了,但 P2 的原文保真保证了届时无需用户重新上传。**+> **修订记录(2026-09-02):大半已经读得了。** 投影落库的公理:`TransitiveProperty` / `SymmetricProperty` / `AsymmetricProperty` / `IrreflexiveProperty` / `FunctionalProperty` / `InverseFunctionalProperty` / `disjointWith` / `inverseOf` / `subPropertyOf`。+> 仍在「暂未投影」里的:`equivalentClass`、`someValuesFrom` 与类表达式、属性链。+> 上面五条的兑现情况:Transitive 进 R1 规则(带环检测与每谓词封顶);基数违反进 `axiom_violations` 由 Review 裁;`equivalentClass` / 类表达式未做;`inverseOf` 与 `subPropertyOf` 进 R1(#177 / #179);+> **`disjointWith` 只兑现一半**——导入落了 `entity_type_disjoint`,消费者只有 R0 的本体自检(类不可满足),消解侧的 `classify_type_drift` 仍用硬编码的 `CONFUSABLE_TYPE_KEYS`,[0009](0009-no-type-is-a-type.md) 点名的「改从本体读」没做。+---## 开放问题- **升格准确率给不出数**——需要真实企业本体做小样本评测,现在只有推演- **`active` 标记的定位**:原本当规模解药(错,规模应由 P3 的检索解),现在只剩治理用途(弃用的旧类不参与分配)。是否值得单独做,等有真实大本体再定-- **阈值 30 是拍的**——类数超过多少才启用类型消解,需要实测校准-- **`disjointWith` 与 `SymmetricProperty` 收益中等**:前者剪枝防错误合并;后者去重(新语料里测得 8 对互为反向的重复事实,占 910 条的 1%)。排在 P2 之后按需+- **阈值 30 是拍的**——类数超过多少才启用类型消解,需要实测校准〔这根轴不存在,换成了字符预算;新的待测量是每块 40 / 30 / 30,见 [0006](0006-ontology-scale-and-the-prompt.md)〕+- **`disjointWith` 与 `SymmetricProperty` 收益中等**:前者剪枝防错误合并;后者去重(新语料里测得 8 对互为反向的重复事实,占 910 条的 1%)。排在 P2 之后按需〔Symmetric 已进 R0 检查与 R1 规则;disjointWith 进了本体自检,**消解侧剪枝仍未做**〕---@@ -557,4 +576,6 @@ related_to 事实 359 条`Industry Corpus` 库保留着(NVIDIA 博客 18 篇 + 微软新闻室 10 篇,RSS 摄入),是上面所有数字的来源,也是后续所有评测的基线——改动前后跑同一个库,数字才可比。别在它上面做破坏性实验。+〔**2026-09-02**:基线已换。种子本体退场后这个库的起点不可复现,现在的基准是 `scripts/bench/` 上可重跑的语料,本体侧用 `ai-timeline-ends × schema.org + W3C Org`([0012](0012-the-ontology-is-a-contract-not-a-suggestion.md))。本文的数字仍是当时的真实测量,只是不再能与今天对比。〕+分支状态不记在这里:git 自己知道,写进文档只会过期。diff --git a/docs/decisions/0002-reasoning-engine.md b/docs/decisions/0002-reasoning-engine.mdindex f3f844bc..a953cf70 100644--- a/docs/decisions/0002-reasoning-engine.md+++ b/docs/decisions/0002-reasoning-engine.md@@ -1,6 +1,6 @@# 0002 · 推理机-- **状态**:规划中 · `utopia-reason` 目前是 3 行占位+- **状态**:R0 已建成(事实层四类违规 + 本体自检八类缺陷,两张表两个 Review 页签);R1 已建成,受 KB 开关 `materialize_inferences` 约束、**默认关**,四种公理规则都编得出(#132、#177、#179);R2 只做了一层直接前提,证明树 API / UI 未建;R3 未做,每次全量重推,靠 `inference_interval_minutes`(缺省 60)定时兜着。2026-09-02 对照代码复核,修订见各节- **成文**:2026-08-28- **相关**:[0001](0001-ontology-import-and-governance.md) 的 P5(该节保留原判断,本文取代其排期)@@ -54,6 +54,11 @@ CREATE TABLE fact_derivations (这同时是 "with explanations" 的落点:**解释 = 前提集 + 规则**,递归展开成证明树,叶子才是真正的 chunk。`facts.derived_by_rule` 列在 `0004_graph.sql:71` 就留好了,至今零使用——它等的就是这个。+> **修订记录(2026-09-02):形状不是这样,而且那一列没等到。** 落地时**派生事实不进 `facts`**,另建 `derived_facts`,迁移 `0013_reasoning.sql` 给了三条理由:+> 四十多处读 `facts` 的查询只有一处认识那个标记,新写一条查询默认就把派生当断言看,**失败方向反了**——分开之后忘了 UNION 的后果是看不见派生,而不是混进去;列本来就不一样;数量级差一档。+> `fact_derivations` 的实际列是 `(derived_fact_id, premise_fact_id, seq)`,规则挂在 `derived_facts.rule_id` 上。`facts.derived_by_rule` 今天仍然零写入,唯一引用是 Review 的一处过滤。+> 这条「失败方向」的判据后来被 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 原样引用去否掉了 `facts.nod` 列。+### 2. 派生事实绝不能闭合断言事实`reconcile_new_fact`(`temporal.rs:49`)对 functional 谓词会自动闭合旧事实。派生事实若走同一条路,**一条错规则就能系统性闭掉人工断言的事实**——`part_of` 那个坑的十倍版,而且这次是自动化的。@@ -68,12 +73,19 @@ CREATE TABLE fact_derivations (这是 0001 判据 2「本体是引导不是执法」在推理层的同一条:**声明可能是错的,所以它不能驱动对既有数据的改写。**+> **修订记录(2026-09-02)**:表格三行里只有第一行的前半兑现了——`asserted` 硬性优先,已断言的三元组不再派生(`derive.rs`)。+> 「记一条规则与事实矛盾的信号」**没有**,「派生 vs 派生进 Review」**没有**(同一三元组的多条推导只留第一条证明)。两者都还是待做。+### 3. 前提撤回时——双时态是最优解,不是负担不能 UPDATE(append-only 是地基)。做法是置 `invalidated_at`,与拒绝一条事实**完全同构**。派生事实的记录轴上于是留下"我们曾据此推出,后来前提没了"。真值维护在别的系统里是苦活(要么标记删除要么重算全量),在这个数据模型里是既有机制的自然延伸——**而且实体历史页面(PR #37)直接就能展示它**,不需要新 UI。+> **修订记录(2026-09-02)**:「实体历史直接能展示」**没兑现**——`entity_history` 的 UNION 只有 facts / merges / retypes 三段,不含 `derived_facts`。+> 派生的可见性落在别处:实体面板单独一档「推出来的」、图上金色专属边(派生为零时开关整个不出现、逆关系推出来的边并到同一条弧上)。+> 而且今天没有「前提撤回」这个增量动作,R3 未做,每次全量重推并整体对账。+---## 分步@@ -87,6 +99,13 @@ CREATE TABLE fact_derivations (价值在于:引擎的难点(规则表示、求值、终止)全部建成并验证,而风险面为零——它不写 `facts` 表。+> **修订记录(2026-09-02):R0 建成,四处与上面写的不同。**+> 一、**四类不是三类,且不是那三类**:`self_loop` / `asymmetry` / `cycle` / `functional`(兼含 inverse_functional)。**事实层的 disjointWith 违反没有做**——disjoint 只进了本体自检。+> 二、**不进 `fact_conflicts`,另建 `axiom_violations`**:那张表问的是「哪条对」,公理违规问的是「错在数据还是错在定义」,出路是 `fact_retracted` / `axiom_relaxed` / `accepted`。「零新界面」也没守住,Review 页多了 `violations` 与 `defects` 两个页签。+> 三、**多出另一半:本体自身的自洽性**(`ontology_defects`,八类:symmetric 且 asymmetric、transitive 且 functional、子类成环、与祖先 disjoint、继承来的 disjoint、自逆、逆没指回来、子属性成环)。理由是自相矛盾的本体会让事实层的结论全部可疑,所以缺陷优先于违规展示。+> 四、环检测是深度优先不是半朴素——闭包只告诉你 A 推出了 A,人要的是**路径**;半朴素在 R1。+> 另:没装本体包的库跑出来是零,那是实情不是故障——没有公理就没有判据。本文「现存 11 处矛盾」的前提(种子本体带 `functional` 声明)已不存在。导入本体后会自动跑一次检查:公理刚变,正是最该重算的时刻。+### R1 · 物化推导(打开开关)- `rules` 表 + `fact_derivations` 表@@ -95,19 +114,24 @@ CREATE TABLE fact_derivations (- 深度上限 + 环检测(实测必需)- 派生事实在图上可视觉区分,且可整体过滤+> **修订记录(2026-09-02):R1 建成。** `rules` / `derived_facts` / `fact_derivations` 三张表;开关 `materialize_inferences` 默认 FALSE,`inference_interval_minutes` 默认 60,调度器每分钟扫到期库入队,作业里**先记时间再推**防失败循环;开关关着时端点回明确错误而非静默跳过。+> 规则从四种公理编译:Transitive / Symmetric(#132)、inverseOf / subPropertyOf(#177 / #179,投影侧在迁移 `0016`)。逆的归一化放在载入公理那一处,只补空缺不覆盖人写的,两边指得不一样留给 R0 报 `inverse_not_mutual`。+> **单谓词封顶 20,000 条,被截掉必须说出来**(`capped`);另有一个正常恒为零的 `unruled` 计数器,记录的是一个真踩过的 bug(落库曾按谓词而非 `via` 查规则,跨谓词规则一加就静默丢弃)。+> `rules` 的身份是 `(kb, 谓词, 种类)`,公理撤了也不删行——否则每跑一次 `rule_id` 就换新,历史全断。+> 冷启动自动扩本体现在**一位公理都不替人声明**(`Axioms::default()`):推理机的判据必须是人写下来的。### R2 · 解释-证明树 API + UI。展开到叶子(chunk)为止,中间节点是派生事实与规则。+证明树 API + UI。展开到叶子(chunk)为止,中间节点是派生事实与规则。〔**只做了一层**:`derived_for_entity` 把直接前提展开成文本。递归到叶子的 API 与 UI 未建,数据结构已足够支撑。〕### R3 · 增量维护-前提失效 → 派生失效。半朴素增量而非全量重算。放最后是因为前面三步都能靠"重算整个 KB"活着,而增量的正确性最难验。+前提失效 → 派生失效。半朴素增量而非全量重算。放最后是因为前面三步都能靠"重算整个 KB"活着,而增量的正确性最难验。〔**未做**,每次全量重算并整体对账,迁移注释明写「在增量维护做出来之前每次都是全库重算」。〕---## 开放问题-- **有效时间的交集语义**:前提 A `[2020,2023)`、前提 B `[2022,∞)` → 派生 `[2022,2023)`。属性事实的字面值宾语怎么参与?闭区间与开区间混合时的边界?-- **物化 vs 查询时求值的临界点**:实测 4.5 倍膨胀(185 → 828)。大语料上这个倍数会怎么变,什么规模该切换?+- **有效时间的交集语义**:前提 A `[2020,2023)`、前提 B `[2022,∞)` → 派生 `[2022,2023)`。属性事实的字面值宾语怎么参与?闭区间与开区间混合时的边界?〔**已答**:半开区间取交集、空交集不推、端点相接不算重叠;精度取最粗、置信度取前提最小;**字面值宾语不参与**——取边与推导都要求 `object_id IS NOT NULL`。〕+- **物化 vs 查询时求值的临界点**:实测 4.5 倍膨胀(185 → 828)。大语料上这个倍数会怎么变,什么规模该切换?〔未定。实际做法是每谓词封顶 + 定时全量重推。〕- **`related_to` 39% 是推理的前置障碍**:推理机面对的图有近四成的边语义是空的。这把 0001 P3b 的优先级顶了上来——**推理机的输入质量取决于它**。补充实测:359 条里只有约 38 条是词表外降级,**321 条是模型自己从提示词清单里挑的 `related_to`**——它就在本体里,被当合法选项列了出去。所以修法是两条腿:**先撤掉提示词里这个逃生舱**,再做映射。细节见 0001 P3b 的修订记录。-- **环该怎么处置**:检测出来只是第一步。自动拒绝哪一条?还是全部进 Review 让人判?倾向后者——两条都是模型抽的,没有先验理由信任其一。+- **环该怎么处置**:检测出来只是第一步。自动拒绝哪一条?还是全部进 Review 让人判?倾向后者——两条都是模型抽的,没有先验理由信任其一。〔**已按倾向落地**:`cycle` 违规带完整 `path` 进 Review;R1 一律不推自环。`related_to` 那条前置障碍也随 [0010](0010-no-relation-is-no-relation.md) 消失——空谓词边天然不进推理。〕diff --git a/docs/decisions/0003-ontology-growth-loop.md b/docs/decisions/0003-ontology-growth-loop.mdindex 50eef7bf..c9b85f2a 100644--- a/docs/decisions/0003-ontology-growth-loop.md+++ b/docs/decisions/0003-ontology-growth-loop.md@@ -1,6 +1,6 @@# 0003 · 本体从语料里长出来,人站在哪一环-- **状态**:已建成(#44 + `feat/ontology-auto-extend-switch`);末节列出已知缺口+- **状态**:已建成且仍在跑(#44 + 自动扩展开关);**本文的起点已被 [0010](0010-no-relation-is-no-relation.md)(`related_to` 删除)与 #125 / #128(种子退场)改写**;「拒绝有记忆」一节的实现被 [0007](0007-who-decides-what-becomes-a-relation.md) 推翻重做;末节三条缺口两条已补,「新说法提醒」仍待做(2026-09-02 核)- **成文**:2026-08-28- **相关**:[0001](0001-ontology-import-and-governance.md) 的 P3b 与 P4——那两节是计划,本文是实际长出来的东西,两者不一样@@ -14,7 +14,11 @@而新建的知识库只有 10 个默认关系,那不是任何人选的,是种子数据。所以每一个新库开局都是这个状态:**图里近一半的边没有语义,直到有人坐下来一条条补本体。**-抽取侧的修法(撤掉逃生舱、加提示词规则 8、把原词存进 `fact_evidence.surface_predicate`)见 0001 的 P3b。本文接着往下——**原词留住之后,怎么把它变回本体里的关系。**+抽取侧的修法(撤掉逃生舱、加提示词规则 8、把原词存进 `fact_evidence.surface_predicate`〔落地列名 `proposed_predicate`〕)见 0001 的 P3b。本文接着往下——**原词留住之后,怎么把它变回本体里的关系。**++> **修订记录(2026-09-02):上面两段的世界不在了。** `related_to` 整个删掉,落不上就是空谓词,显示时由 `fact_surface_predicate()` 取回原文说法;新建的库**一个关系都没有**,起点改为预制本体包([0008](0008-ontology-packs-as-cold-start.md))。+> 40.5% 是当时的数;[0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 在 ai-timeline-ends × schema.org 上量到空谓词 25.6%,而且 41 个关系全部来自本体包,**自动扩本体一条都没长出来**。+> 所以这条回路的角色变了:冷启动的主力是「先装一份词表」,本文的机制负责「长出来的补缺口」。回路本身一字未改,仍然默认开着。---@@ -62,12 +66,17 @@ Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实**判据一句话:可逆的可以自动,触发级联写入的不行。**+〔后来扩大到全部公理:冷启动路径传 `Axioms::default()`,八位全 false——推理机([0002](0002-reasoning-engine.md))的判据必须是人写下来的。〕+### 拒绝有记忆`dismiss` 此前是 `DELETE FROM ontology_misses`,下一次抽取遇到同一个词原样插回——**用户的"不要"活不过一轮抽取**。开关关着时这只是恼人;开着时它变成系统覆盖人的明确决定。改成标记(`dismissed_at`):`record_miss` 不再累加已标记的,人工与自动两条路都跳过。顺带修好了"dismiss 是暂时的"这个现存 bug。+> **修订记录(据 [0007](0007-who-decides-what-becomes-a-relation.md) 缺陷五)**:「不再累加」这一半**又被推翻**。它把「忽略」做成了单向门:用户看着「出现 1 次」做的判断被记成对所有时间的判断,后面二十篇都在用它,计数仍停在 1,没有人看得见。+> 现在 `record_miss` 照样累加,抑制移到读取侧——已忽略的连同更新后的计数单列一处,可撤回。「拒绝有记忆」仍然成立,只是记忆的是**态度**不是**计数**。+### 自动采纳的门槛只采纳出现在 **≥2 篇文档**里的说法。理由不是安全(有撤销),是质量:**本体会反馈进抽取提示词,一次偶然用词会变成长期指令。** 副作用正好——单篇文档什么都够不着门槛,于是什么也不做,下一篇再议。@@ -125,6 +134,8 @@ Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实一个**负面结果,而它证明了设计**:建议把 `optimized_for` 并进了 `runs_on`——"为 RTX 优化"不等于"跑在 RTX 上"。归并的写法在 tooltip 里可见,过并能被人抓出来。**这就是我不建议全自动归并的最直接证据。**+〔上表四行都基于已不存在的 `related_to` 与种子本体,是历史记录,不要再当基线引用。采纳路径后来多了两样本文没写的东西:整组说法先过 `predicate_match`,本体里已有等价关系(含 `_by` 反向)就落到它上面并对调主宾(#109);门槛按「谓词 + 类型」合起来算 `MIN_SIGNALS = 3`,此前只数谓词,一个只缺实体类型的语料会被整个跳过。规范 key 不问模型取名,取组内事实最多的那个真实措辞。〕+---## 已知缺口@@ -135,7 +146,7 @@ Suggest 面板此前就能提案并一键 Add,但**只建关系、不动事实当时列的实测数据(`General` 库里 "rust" 分在 5 个类、`Industry Corpus` 里`product` 占 37.1%)仍是这条路要解的问题,见 0001 P3 的三层拆解。- **关掉开关后没有"自上次以来有 88 个新说法"的提醒**,信号在 Unmatched 面板里但没人主动看。- **待做。**+ **待做。**〔2026-09-02 核:仍未做。`ontology_proposals_open_idx` 的建表注释把这条缺口原样抄了一遍——索引铺好了,提醒没做。今天只有 `last_auto_extension` 横幅,讲的是「最近一次自动扩本体做了什么」。〕- ~~**提案不持久化**~~ **已修**(2026-08-30,#112):`ontology_proposals` 表落库。丢的从来不是原材料(那在 `ontology_misses` 里),是**聚类结果**——哪些说法被归到同一条提议底下,而那正是唯一能查证过并的东西。diff --git a/docs/decisions/0004-language-and-localization.md b/docs/decisions/0004-language-and-localization.mdindex 1b3238e9..0b7c9dfa 100644--- a/docs/decisions/0004-language-and-localization.md+++ b/docs/decisions/0004-language-and-localization.md@@ -1,9 +1,9 @@# 0004 · 语言:哪些字跟着看的人走,哪些跟着语料走-- **状态**:已建成 · 五种文本各就各位:界面词汇在 `web/src/i18n/`、服务端错误已改成 key、+- **状态**:已建成 · L0–L3 全部落地:界面词汇在 `web/src/i18n/`(约 950 条,含 108 个函数)、服务端错误改成带 `code` 的 `AppError::Invalid`(81 处;23 处 API 契约守卫刻意留英文 `Validation`)、本体 `description` 跟 `knowledge_bases.ontology_lang`(带部署默认值)、LLM 面向人的输出- 由调用方在请求里传 `locale`、抽出来的数据逐字跟文档-- **成文**:2026-08-29(状态于 2026-08-30 更正:文档一直写着「规划中」,而索引与代码都说已建成)+ 由调用方在请求里传 `locale`、抽出来的数据逐字跟文档。**两处与本文写的不同**,见 2026-09-02 的修订记录:界面首次访问刻意不猜浏览器语言;「中文内置本体」那一支随播种机制退场而作废+- **成文**:2026-08-29(状态于 2026-08-30 更正:文档一直写着「规划中」,而索引与代码都说已建成;2026-09-02 对照代码复核)- **相关**:[0001](0001-ontology-import-and-governance.md) 论证过 `description` 是承重字段——本文把「它该用什么语言」补上;[0003](0003-ontology-growth-loop.md) 的 `reason` 与 `description` 之分是本文分界线的起点> 触发:产品要面向中文企业出中文版。但「加个语言开关」这句话底下藏着**五种性质不同的文本**,它们的正确语言互不相同,用一个开关管必然有一半是错的。@@ -34,6 +34,12 @@`localStorage` + [wsStore.ts:22](../../web/src/wsStore.ts) 已有的 `makeStore` 模式,多一行 `makeStore("utopia.lang")`。首次访问按 `navigator.language` 猜一次,之后以人选的为准。+> **修订记录(2026-09-02)**:「按 `navigator.language` 猜一次」**没有落地,而且是刻意的**。+> `web/src/i18n/index.ts` 的 `detect()` 只读 `localStorage`,否则一律 `"en"`,注释写着+> 「等 zh 追平了再把 navigator.language 那一句加回来」。原因是下文「已知会疼的地方」第一条:+> 中文包在追英文包,漏译的那部分会静默回落成英文。于是把「漂移」的代价换成了+> 「中文用户默认先看英文」——这是个取舍,不是遗漏,追平之后该把那一句加回来。+> **修订记录**:本文初稿把界面语言放在**部署级管理员设置**里,理由是"和并发上限一样,DB 存、即时生效"。那个类比是错的——并发上限是**部署的属性**(供应商速率限制),界面语言是**读者的属性**。判断一个设置该放哪,问的不是"改起来方不方便",是"它描述的是谁"。中文包写成 `const zh: typeof S = { … }`。**不用 `Partial` + 逐键回退**:那样漏译不报错,只是某一行悄悄变回英文,而这种缺口只有用户会发现。`typeof S` 让漏一条就编译不过——512 条字符串 + 44 个函数,靠人眼对不齐。@@ -42,7 +48,7 @@界面语言在客户端之后,**后端不再拥有任何 locale**。所以留在 Rust 里的字符串是**永久不可翻译**的,不是"以后再补"。-`AppError::Validation` 目前 75 处。分两类处理:+`AppError::Validation` 目前 75 处〔**已做完**(2026-09-02 核):能撞到的改成了带 `code` 的 `AppError::Invalid`,81 处,前端 `err.*` 表 48 条;留下的 23 处 `Validation` 全是契约守卫。`Invalid` 还多带一个 `detail`——机器给的补充(cron 解析器的报错之类)与措辞分离;`message` 仍是英文原句且刻意保留,给不做本地化的客户端(MCP、CLI)与日志用〕。分两类处理:- **用户正常操作能撞到的**(密码规则、邮箱格式、空文件、日期格式等)→ 改成 key,前端查表。这样全部措辞收进 `i18n.ts` 一个文件,而不是前端一半后端一半。- **API 契约守卫**(`role must be admin, editor or viewer`——只有调错接口才会碰到)→ 留英文。它的读者是开发者,永久英文正是它该有的样子。@@ -63,19 +69,24 @@`label` 存在库里,跟不了客户端的开关。**而这是对的**:它是那个团队写下的本体。一个中国团队建的库里类叫 `人物`,用英文界面的同事看到的也该是 `人物`——那是他同事定义的概念,不是界面元素。翻译它反而错。-内置的 9 个类只在**播种那一刻**是应用词汇,落库之后就是这个库的数据,可编辑。+内置的 9 个类只在**播种那一刻**是应用词汇,落库之后就是这个库的数据,可编辑。〔**已作废**:[0009](0009-no-type-is-a-type.md)、[0010](0010-no-relation-is-no-relation.md)、#125、#128 之后不再有内置类、种子关系与播种函数。冷启动改由英文预制包提供([0008](0008-ontology-packs-as-cold-start.md)),于是「label 是数据」这条的实际后果是:**中文库装到的是纯英文本体**,`ontology_lang = zh` 只影响将来由 LLM 提案长出来的词。见 0008 开放问题。〕**`key` 永不翻译**:它是标识符(`[a-z0-9_]`,最长 40),是模型读写的令牌,也是 `type_ids` 的查找键。-**一个连带修改**:提示词现在排成 `- {key} ({label}): {description}`([lib.rs:61](../../crates/utopia-extract/src/lib.rs))。界面语言与语料语言不一致时,这一行会中英混排。`Person` 相对 `person` 本来就近乎零信息量,所以**提示词只送 `key` + `description`,`label` 仅在 description 为空时兜底**。+**一个连带修改**:提示词当时排成 `- {key} ({label}): {description}`([lib.rs](../../crates/utopia-extract/src/lib.rs),已按下句改掉)。界面语言与语料语言不一致时,这一行会中英混排。`Person` 相对 `person` 本来就近乎零信息量,所以**提示词只送 `key` + `description`,`label` 仅在 description 为空时兜底**。### LLM 当场生成给人看的 → 调用方在请求里说-`reason` 是人点 "Suggest with AI" 当场生成、当场显示、接受或忽略后就没了——`suggest` **即时返回不存库**([ontology_routes.rs:328](../../crates/utopia-server/src/api/ontology_routes.rs))。调用者就在现场,那就让请求自己说要什么语言,而不是让后端记一个设置。+`reason` 是人点 "Suggest with AI" 当场生成、当场显示、接受或忽略后就没了——`suggest` **即时返回不存库**([ontology_routes.rs](../../crates/utopia-server/src/api/ontology_routes.rs))。调用者就在现场,那就让请求自己说要什么语言,而不是让后端记一个设置。++> **修订记录(2026-09-02)**:「不存库」已不成立——#112 之后 `suggest` 算完会写进 `ontology_proposals`,+> 因为丢掉的不是原材料而是**聚类结果**(见 [0003](0003-ontology-growth-loop.md) 已知缺口)。+> 但语言的结论不变:`reason` 仍按请求里的 `locale` 生成,label / description 则跟 `kb.ontology_lang`,+> 两者在**同一次调用**里表达,提示词里写明后者覆盖英文骨架。冷启动自动扩本体走同一条路但没有人类调用者。它生成的 `reason` 本来就被丢掉(`lastAutoExtension` 只回 relations / classes / facts_remapped / batches),所以那条路不需要 locale。-**今天真正的毛病不是语言错,是语言没定**:[bootstrap_ontology.rs](../../crates/utopia-server/src/bootstrap_ontology.rs) 的提示词压根没说输出用什么语言,模型看心情。+**今天真正的毛病不是语言错,是语言没定**:[bootstrap_ontology.rs](../../crates/utopia-server/src/bootstrap_ontology.rs) 的提示词压根没说输出用什么语言,模型看心情。〔**已修**:提示词末尾有一整段 Language 指令,`lang_name()` 把 `zh` 写成 `Chinese` 再送进去——模型认得懂 Chinese,未必认得懂 zh;冷启动那条路显式传 `en`。〕### 抽出来的数据 → 逐字跟文档,连开关都不给@@ -119,6 +130,10 @@ locale 必须**在一个函数里解析出来**,其余全部消费它,不各**L2 里最实的一块不是加列,是重写内置本体的描述**——9 个类 + 14 个关系。它们当初是斟酌着写的(负面例子那部分尤其:「不是角色、职位或团队,那些归 concept 或 organization」——错误聚集在边界上,负面例子才是干活的那半)。**翻译不能敷衍,得按同样的思路用中文重写一遍。**+> **修订记录(2026-09-02)**:这一块**已无对象**——种子本体整个退场(见上文「label」一节的作废注)。+> L0、L1、L3 与 L2 的「加列 + 部署默认值」都已建成;中文本体这件事换了形态:+> 要么用户导入自己的中文词表,要么等本体包有中文标签(0008 开放问题),代码里没有第三条路。+---## 已知会疼的地方@@ -126,3 +141,4 @@ locale 必须**在一个函数里解析出来**,其余全部消费它,不各- **中文包与英文包漂移**。`typeof S` 挡住"漏一条",挡不住"英文改了措辞、中文还是旧的"——两边都合法。目前没有好办法,只能靠改文案时同时改两处。- **一个库里中英文档混放**时,`description` 该用哪种语言没有正确答案。本文选了「知识库单语」,因为混放本身就会让抽取质量下降(不只是描述的问题)。真遇到了再说,别提前设计。- **中文分词与检索**。Tantivy 那边已经用了 `tantivy-jieba`,不在本文范围,但中文版上线后会被更认真地检验。+- **(2026-09-02 补)中文包追不上英文包的期间,界面默认英文**。见「界面词汇」一节的修订记录:`detect()` 暂不猜浏览器语言。追平的标志是 `zh.ts` 不再靠 `typeof S` 之外的任何东西撑着,那时把 `navigator.language` 加回去。diff --git a/docs/decisions/0005-alert-center.md b/docs/decisions/0005-alert-center.mdindex 42d8a5ea..ca44ecb9 100644--- a/docs/decisions/0005-alert-center.md+++ b/docs/decisions/0005-alert-center.md@@ -1,7 +1,7 @@# 0005 · 告警中心-- **状态**:第一刀已建成(`source.sync_failed` + `llm.unreachable`)。- 三个决定里第 1、2 条在实现过程中被推翻,就地留痕见下+- **状态**:已建成 · 五种告警在线(`source.sync_failed`、`llm.unreachable`、`llm.rate_limited` #160、`llm.out_of_credit` #182、`data_source.schema_sync_failed`),面板带搜索与按组分页;+ 三个决定里第 1、2 条在实现过程中被推翻,就地留痕见下;`document.no_text_layer` 仍未接(2026-09-02 核)- **成文**:2026-08-29- **相关**:与 Review 队列(0001 P4)职责相邻,本文划边界@@ -13,14 +13,14 @@| 位置 | 记的是 ||---|---|-| `jobs.status='failed'` + `jobs.last_error` | 任务失败 —— **没有任何界面** |+| `jobs.status='failed'` + `jobs.last_error` | 任务失败 —— **没有任何界面**〔现在:任务**最终**失败(`attempts >= max_attempts`)且错误可分类时,经 `observe_job_failure` 变成告警;重试期间不报,重试本就是为了不惊动人〕 || `documents.status='failed'` | 摄入失败 || `documents.graph_status='failed'` | 抽取失败 || `sources.last_sync_status='failed'` | 源的最近一次同步失败 || `source_sync_runs.status='failed'` | 单次同步失败 || 日志 | 其余一切 |-而且这个问题**已经被局部修过一次**。迁移 `0021_graph_error.sql` 的第一句是:+而且这个问题**已经被局部修过一次**。当时的迁移 `0021_graph_error.sql`(#130/#131 折叠后落在 `0002_ingest.sql` 的 `graph_error` 列)的第一句是:> 抽取失败的原因此前只进日志与 `jobs.last_error`,文档上什么都不留,界面无从显示。@@ -129,7 +129,7 @@`kb_id` 可空,两种语义:```-kb_id IS NULL 系统级:LLM 端点不可达、数据库连接池打满、镜像版本不一致+kb_id IS NULL 系统级:LLM 端点不可达(今天实际是三条 LLM 告警:不可达 / 限流 / 欠费)→ 仅 users.is_adminkb_id 有值 知识库级:解析失败、抽取失败、源同步失败@@ -138,6 +138,11 @@ kb_id 有值 知识库级:解析失败、抽取失败、源同步失败**不新写权限逻辑**:`access::kb_role()` 第一句就是 `if user.is_admin { return Ok(Some(Role::Owner)) }`,告警的可见性判定直接复用它,和 KB 路由走同一条鉴权链。系统管理员因此对知识库级告警也全通。+> **修订记录(2026-09-02)**:结论(admin 全通、按 `min_role` 比大小)成立,「不新写」没做到。+> 列表要一条 SQL 里按人过滤,于是走的是 `access::visible_kb_roles()` 加 `alerts.rs` 里一段 `VISIBLE` CASE+> 加一个 `rank()`——代码自己承认「跟 `Role` 的 `PartialOrd` 同序,也跟 `VISIBLE` 里那个 CASE 同序,三处必须一致」。+> 记在这里是因为这正是本仓库最怕的那种隐形规则:改角色顺序时得记得改三处。+`min_role` 存在 alert 上而不是按 kind 硬编码,因为同一类告警在不同场景下该找的人不同:- **配置类**(端点、权限、配额)→ admin@@ -194,6 +199,20 @@ kb_id 有值 知识库级:解析失败、抽取失败、源同步失败| `source.sync_failed` | KB 级 | 聚合、自愈、`min_role=editor` | 聚合改到视图层;自愈作废;权限如设计 || `llm.unreachable` | 系统级 | `kb_id IS NULL` 那条路径、`is_admin` 可见性 | 它没有成功信号,就是这一条逼出了第 2 节的推翻 |+> **后续(2026-09-02 核)**:第一刀之后又接了三条,**没有一条需要新的检测逻辑**,都是把已有的错误分类接上来:+> `llm.rate_limited`(#160,退避用尽仍过不去)、`llm.out_of_credit`(#182,402 或「余额不足」文案,与限流分开——该找的人不同)、+> `data_source.schema_sync_failed`(源挂上了但表结构没摄进来)。分类做成纯函数 `alert_for` 并有单测,+> 因为判据是错误的**类型**不是文本。最后一条值得记:它报的是「留下的状态」不是「那次失败」,+> 是第一条不由一次执行失败直接触发的告警,与上文「任何执行路径在失败时上报」的表述有出入。+>+> 面板顺带长出了搜索与按组分页(每页 8 组、每组最多 5 条明细)。搜索**刻意搜不到标题**——+> 标题是前端按 kind 查表拼的([0004](0004-language-and-localization.md):服务端不产出展示文案),+> 服务端只能匹配库名、detail、kind 代号。+>+> **一条本文该划而没划的边界**:`extraction_drops`(11 种丢弃原因,读者是上传文档的人)是另一条完全独立的失败信号通道,+> 它与告警的分工是「这份文档里有东西没落地」对「系统某处坏了」——前者按文档聚在文库行上,后者进铃铛。+> 两者都不进 Review:Review 管知识的对错。+**如果设计有错,这一刀就会暴露** —— 确实暴露了,见上面两条修订记录。`llm.unreachable` 的判据在实现中也放宽过一次:起初只认传输层失败(连不上),diff --git a/docs/decisions/0006-ontology-scale-and-the-prompt.md b/docs/decisions/0006-ontology-scale-and-the-prompt.mdindex cfe6be8e..75855dae 100644--- a/docs/decisions/0006-ontology-scale-and-the-prompt.md+++ b/docs/decisions/0006-ontology-scale-and-the-prompt.md@@ -1,6 +1,6 @@# 0006 · 本体规模与抽取提示词-- **状态**:已建成 · 预算与按块检索已上线;预算的具体数值仍待更好的语料来定+- **状态**:已建成 · 预算(24,000 字符)与按块检索在线,数值未动;「内置类恒在」那道地板已被**祖先补齐**取代(见文末修订);预算的具体数值仍待更好的语料来定——外部语料已入库,答案键仍是人填的(2026-09-02 核)- **成文**:2026-08-29(约定见 [README](README.md))> 这一篇比别的多一样东西:**数字**。它们来自 `scripts/bench/`,任何人都能重跑。@@ -22,7 +22,7 @@ token**。这个数字不是某个设计的代价,**是没有设计的结果****按预算切换,不按类数量。**- 装得下 → 全量铺,行为一字不变。四十个类的本体约 2k 字符,检索反而是多余的往返。-- 装不下 → **每块用它自己的向量检索候选**,内置类恒在,检索不出来就退回全量。+- 装不下 → **每块用它自己的向量检索候选**,内置类恒在〔已换成祖先补齐,见文末〕,检索不出来就退回全量。预算按**字符**而不是类数量:类描述的长度差着数量级(`SoftwareApplication` 的描述是一句话,FIBO 的能有一整段)。判据量的是**实际要排的那段字**(`build_lists` 自己数),@@ -97,6 +97,29 @@ token 限额(429),同一份本体检索组跑得下来。这不是"慢一都是拍的,代码里标着。上面的曲线说它偏保守,但在语料这一关过掉之前,按那条曲线去调只是把过拟合调得更紧。+## 修订记录(2026-09-02):地板换了材料,索引付了代价++**「内置类恒在」失效了。** 它的前提是种子类正好是那几个通用类,而 #128 之后建库不种任何类,+`seed_classes` 恒为空。症状在 [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 里量过:向量检索偏爱字面出现在正文里的叶子类+(976 个类里 `researcher` 第 4、`corporation` 第 27,`organization` 第 177、`person` 第 359,前 40 名里一个泛化基类都没有),+于是实体判成 `researcher`,`employee (organization → person)` 的签名退化成 `(* → *)`。++**改成:命中什么,就把它的祖先一起铺出去。** 沿 `subClassOf` 上溯,广度优先加访问集(菱形继承会从两条路到达同一祖先)。+比维护一张「通用类」清单好——继承链本来就是本体自己声明的泛化关系,谁是谁的上位不用我们再判一次。+代价是每块多铺几层祖先。这是「三个细节」之外的第四个,也是唯一由真实数据逼出来的。++**本体向量索引本身也有两个实测常量**,本文当初只谈了提示词的规模:`BATCH = 64`(曾改成 16,因为拿合成短文本量的「每条更快」,+改回后吞吐翻倍)、`EMBED_JOBS = 4`(曾用 `join_all` 挂 31 批,把共享的 `model_concurrency` 闸门占死——五篇文档全卡在 embedding,抽取十五分钟零进展)。+索引陈旧靠「当时嵌的原文与模型名跟现在对不对得上」自愈,不挂钩子。++**按块检索的系统级代价**:每块一次向量检索砸向数据库,并发数由 `worker_concurrency` 决定,而它的上限已从 32 提到 256(#133)。+连接池是 32。这条账本文没记,迁移 `0011` 的注释记了。++**测量台已经能测 0008 那个开放问题**:`run.mjs --packs schema-org,prov-o` 走产品真实的冷启动路径。工具就位,对照仍未跑。++**语料那一半**:语料从 2 份涨到 8 份,新增的都不是手写的(维基历史快照带可重建的 manifest、公有领域国情咨文、福尔摩斯),+生成脚本一并入库。但「标准答案由外部数据推导」没做——`scripts/bench/truth/` 仍只有 pharma / tech 两份人填答案,没有任何 Wikidata `P31` 代码。+## 撤回> **「108k 的提示词吃掉了 5 个实体」不成立。** 那条结论来自测量台的默认次序diff --git a/docs/decisions/0007-who-decides-what-becomes-a-relation.md b/docs/decisions/0007-who-decides-what-becomes-a-relation.mdindex 5f398365..9b50c7c4 100644--- a/docs/decisions/0007-who-decides-what-becomes-a-relation.md+++ b/docs/decisions/0007-who-decides-what-becomes-a-relation.md@@ -1,6 +1,6 @@# 0007 · 谁来决定一个说法值不值得成为关系-- **状态**:已建成 · 采纳改由计数决定;「叙述动词进了本体」这一条未解+- **状态**:已建成 · 采纳改由计数决定;六条缺陷的修法全部在线;「叙述动词进了本体」与 `merge_key` 不折 `_by` 两条仍未解;**本文的起点(10 个种子关系、`related_to` 占比)已不存在**,见文末修订(2026-09-02 核)- **成文**:2026-08-30(约定见 [README](README.md))> 跟 [0006](0006-ontology-scale-and-the-prompt.md) 一样带数字,也一样标明每个数字@@ -134,6 +134,25 @@ criticizes/criticized 6 · published/publishes 6 · accused/accuses 6`related_to` 已整个删掉,见 [0010](0010-no-relation-is-no-relation.md)。这条未决项本身仍然成立:叙述动词进本体的问题与谓词兜底无关。〕+## 修订记录(2026-09-02):起点没了,结论还在++本文的问题陈述是「新建的库只有 10 个种子关系,大半说法降级成 `related_to`」。**两个前提今天都不成立**:+种子关系分三次退场(`related_to` 见 [0010](0010-no-relation-is-no-relation.md),另外八条 #125,`mapped_to` 见 [0011](0011-a-mapping-is-not-a-fact.md)),播种函数随之消失(#128);+新库的起点是预制包([0008](0008-ontology-packs-as-cold-start.md)),默认 schema.org,1010 类 / 1676 属性。++**于是「量到了什么」那张表的可比性也没了**:A / B / B3 / 计数采纳四组都是从 10 个种子起跑的。+今天同一份语料从 schema.org 起跑,`related_to` 这个指标本身已经不存在(事实可以没有谓词,原词落 `fact_evidence.proposed_predicate`),+对应的指标变成「空谓词占比」——[0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 在 ai-timeline-ends 上量到 25.6%,+与本文 B3 + 计数采纳的 25.8% 是两个不同起点、不同定义下的数,**不要拿来对比**。++**决定本身不受影响。** 采纳由计数决定、`merge_key` 归并、文档并集、`MIN_DOCS = 2`——全部在线,另加一条本文没写的 `MIN_SIGNALS = 3`(够格信号不足三个就不跑 LLM)。+提案现在落库到 `ontology_proposals`(#112),表过态的不被下一轮刷回。++**起点从 10 变 1500 对采纳回路意味着什么,仍然没人量过**——0008 开放问题最后一条。阈值一个没动。++**`_by` 的下游后果有了结构上的解**:本体现在能声明 inverse(#177/#179),方向由本体签名声明并在写入时掰正(#138,留 `direction_corrected` 痕迹)。+但那不替代 `merge_key` 折 `_by` 这个缺口——两个方向都不在本体里时,仍会建出两条相反的关系。+## 走过的死路留着它们,因为每一个当时看起来都很合理。diff --git a/docs/decisions/0008-ontology-packs-as-cold-start.md b/docs/decisions/0008-ontology-packs-as-cold-start.mdindex 132d2c06..7d75652f 100644--- a/docs/decisions/0008-ontology-packs-as-cold-start.md+++ b/docs/decisions/0008-ontology-packs-as-cold-start.md@@ -1,6 +1,6 @@# 0008 · 预制本体包作为冷启动-- **状态**:规划中 · 建库仍只发 10 个种子关系+- **状态**:已建成 · 五个包内嵌进二进制、建库时多选(schema.org 默认勾选)、对齐表 22 条静态维护;**建库不再发任何种子关系**——包不是补充,是本体的全部来源;三个开放问题全部仍然开放,且「中文标签」那条变严重了(2026-09-02 核,修订见文末)- **成文**:2026-08-30(约定见 [README](README.md))- **相关**:[0001](0001-ontology-import-and-governance.md) 定了 IRI/key 分工与贯穿性判据;[0006](0006-ontology-scale-and-the-prompt.md) 拆掉了大本体的提示词障碍;@@ -13,7 +13,7 @@## 问题-新建的库只发 10 个种子关系(`graph.rs:290` 的 `RELATION_TEXT_ZH`)。这 10 个里+新建的库只发 10 个种子关系(成文时 `graph.rs` 的 `RELATION_TEXT_ZH`;今天那张表、`localized()` 与 `ensure_default_ontology` 都不存在,`graph.rs` 开头留了三次退场的理由)。这 10 个里**零个带类型签名**——没有 domain,没有 range。抽取提示词是支持签名的(`extract/lib.rs:498` 的测试:`- buys_from (employee|team → *)`),@@ -29,7 +29,7 @@**这正是问题所在**:用散文补方向,每个谓语都要单独踩一次坑,而且补丁只在那一条下面生效——`part_of` 警告过的"能在某服务上玩",换个谓语照样踩。-`graph.rs:4` 的自陈说明这不是个别谓语的事:+`graph.rs` 开头的自陈(今天挪到了 `bootstrap_ontology.rs` 开头,**内容已过时**,仍写着 10 个默认关系与降级 `related_to`)说明这不是个别谓语的事:> 文档,里面的关系大半不在这 10 个里,于是大量事实降级成 related_to@@ -60,9 +60,9 @@ schema:worksFor Person → Organization| 包 | 体积 | 类 | 属性 | domain | range | 补什么 ||---|---|---|---|---|---|---|-| **schema.org** | 1078 KB | 1010 | 1521 | 1521 | 1521 | 通用:人、组织、产品、事件、创作 |+| **schema.org** | 1078 KB | 1010 | 1521〔发货的包记 1676〕 | 1521 | 1521 | 通用:人、组织、产品、事件、创作 || **W3C Org** | 82 KB | 13 | 34 | 36 | 32 | **组织架构**:Unit、Post、Membership、Role、任期 |-| **PROV-O** | 110 KB | 62 | 69 | 63 | 62 | 溯源:Activity、Agent、wasDerivedFrom |+| **PROV-O** | 110 KB | 62〔发货的包记 49〕 | 69 | 63 | 62 | 溯源:Activity、Agent、wasDerivedFrom || **FOAF** | 43 KB | 12 | 62 | 60 | 57 | 社交关系 || **IOF Core** | 394 KB | 294 | 75 | 94 | 94 | 工业制造 |@@ -117,8 +117,8 @@ schema:worksFor Person → Organization### 2. 不做导入撤销-`ON DELETE RESTRICT`(`0004_graph.sql:41`)加应用层计数(`ontology.rs:232`)加-`NOT builtin` 三道防线,已经保证了安全边界:**有实体挂着的类型删不掉**。+`ON DELETE RESTRICT`(今天在 `0003_graph.sql`)加应用层计数(`ontology.rs` 的删类 / 删关系两处)加+`NOT builtin` 三道防线〔第三道现在是空条件:没有 builtin 行了〕,已经保证了安全边界:**有实体挂着的类型删不掉**。所以"选错了怎么办"的实际路径是:没被用到的类型直接删,被用到的删不掉——**而删不掉恰恰是对的**,那些类型上挂着真实知识。@@ -139,6 +139,34 @@ schema:worksFor Person → Organization只有五六套,两两重叠有限且可穷举。**把无限的对齐问题缩成一张静态表**,这与判据 6「治理经验固化进 schema,不要固化成隐形规则」一致。+## 修订记录(2026-09-02):建成之后对照本文++**三个决定的落地情况。** 多选建库已做(`CreateKbReq.ontology_packs`,前端多选卡片,无任何组合预设);+**「跟已选项的重叠率」没做**,而且方向反了——`2fa8d57` 把碰撞提示整个拿掉了,因为对齐表已经处理了它们,报给用户等于让人裁一件没得裁的事。+不做导入撤销守住了,但**替代品「批量视图:这次导入建了 294 个类、12 个在用、282 个空着,一键删空的」没做**,`ImportPanel` 只有导入历史与 plan。+对齐表 22 条(本文估「约 20 行」),`SameAs` / `Rename` 两类,`org:Role → org_role`、`foaf:status → foaf_status` 都在。++**对齐表长出了三样本文没预见的东西。**+一是第三种处置 `Aligned`:同义命中记作「已对齐」而不是「冲突」,与 `Create` / `Update` / `KeyTaken` 并列。+二是**方向敏感**:表是 `(进来的 IRI, 已占的 IRI)`,装包顺序不同命中的是不同条目——直接推出界面上「勾选顺序即安装顺序」这条用户可见语义。+三是它需要一道防腐:一个跑真包的测试把五个包全投影一遍逐条核对 IRI,防的是写错一个字符静默失效,以及上游改前缀(schema.org 从 `http://` 迁到 `https://` 就发生过)。++**两条推论落在了代码里**:一个包失败不回滚已装的(本体是加法,装了一半的库仍然可用;回滚要撤已建好的类,正是本文不做导入撤销的理由);+包按 gzip 内嵌、每次建库现解压(1.7 MB → 316 KB,离线内网承诺 + clone 体积)。++**本文没讨论的第三种起点:从 0 开始。** 不装任何包是合法的,空库能用,实体 `type_id` 为 NULL([0009](0009-no-type-is-a-type.md))。本文假定包把起点从 10 变成 1500,实际多了一档「0」。++**「本体是引导不是执法」在包上被推翻了一半。** [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 拿真语料第一次问了「大本体顶不顶用」:词汇量确实接住了东西(215 条有谓词的事实、41 个关系全部来自包),+但声明的方向一条没被执行,130 条可校验的里 102 条反着落库。修法是写入时按签名掰正并留痕。**包的代价不在提示词长度,在选择难度**:+包里很多名字通用、含义狭窄的词(`affectedBy` 是医学检验的、`competitor` 是体育赛事的),按名字或向量挑必然撞上。这条该记进本文的成本项。++**开放问题的现状**:+- 混装准确率——**工具就位、对照未跑**。`run.mjs --packs` 走真实冷启动路径,`truth/` 里仍只有 pharma / tech。+- schema.org 面向网页——仍然如此。README 把「按行业要包」做成了 issue 模板链接,把这条缺口转成了用户输入通道。+- 中文标签——**变严重了**。种子那 14 个带中文名的关系没了,五个包全英文,所以今天一个中文库拿到的是**纯英文本体**。+ [0004](0004-language-and-localization.md) 的分工在这里的实际结果是:`ontology_lang = zh` 只影响将来由 LLM 提案长出来的词,对已装的包一个字不动,且没有任何地方提示这一点。+- 起点规模——未研究。`MIN_DOCS = 2`、`MIN_SIGNALS = 3` 全部没随起点从 10 变 1500 而调。+## 开放问题- **混装的抽取准确率没人测过。** 0006 的数据是单一本体下的。全选之后本体约 2400 类,diff --git a/docs/decisions/0009-no-type-is-a-type.md b/docs/decisions/0009-no-type-is-a-type.mdindex 9850030c..b01c1fc7 100644--- a/docs/decisions/0009-no-type-is-a-type.md+++ b/docs/decisions/0009-no-type-is-a-type.md@@ -1,6 +1,6 @@# 0009 · 「还没判出来」不该是一个类-- **状态**:已实施+- **状态**:已实施 · `entities.type_id` / `entity_retypes.from_type_id` 可空;内置九类与播种函数已连同种子关系一起退场(#110 / #125 / #128 / [0011](0011-a-mapping-is-not-a-fact.md));两个开放问题仍开放,第二个已有可见代价(2026-09-02 核)- **成文**:2026-08-30(约定见 [README](README.md))- **相关**:[0008](0008-ontology-packs-as-cold-start.md) 让真词表成为可选起点,本文把内置的那套拆掉;[0001](0001-ontology-import-and-governance.md) 的 IRI/key 分工是本文撞名论证的前提@@ -128,6 +128,8 @@ Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被它的正解仍然是注释里写的那条——等 `disjointWith` 落库后改从本体读,即 0008 的 R0 第三阶段。本文不动它。+〔**2026-09-02**:前提已经成立,动作仍未做。`owl:disjointWith` 有表(`entity_type_disjoint`)、有导入、有编辑接口,消费者只有 R0 的本体自检;`CONFUSABLE_TYPE_KEYS` 仍是硬编码三个 key,且它上面的注释还停留在旧世界。〕+## 空白库删光之后,不选任何包的库是**真的空**:抽出来的实体 `type_id` 为 NULL,事实照常落库,@@ -136,6 +138,8 @@ Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被**所以"先建库后建模"是受支持的路径,不是将就。**+〔落地时多了一列本文没写的 `entities.type_source`(extracted / human / inferred):0009 让 `type_id IS NULL` 同时承载「还没判」和「人判了就是没有」,这一列把两者分开,也是类型消解取材的过滤条件(0001 P4a)。另有 `specific_type` 与 `proposed_type` 分列——前者是模型对这个实体的自由说法,专供类型消解。〕+配套:schema.org 在建库对话框里默认勾选,可反选。这在 45 秒的时候不成立,在 0.42 秒的时候成立(导入改批量插入之后的实测)。@@ -158,4 +162,4 @@ Postgres 里 **NULL 不等于 NULL**,所以未分类的同名实体不会被两个都没类型的同名实体,今天按 `Recall` 走画像相似度——够不够,没测过。- **`metric` / `dimension` 的去处**:语义层要用,而没有任何公开词表提供它们。是让用户自己建,还是我们出一个「Utopia 语义层」包?后者会把内置本体从代码搬到包里,- 性质完全不同——那是可选、带 IRI、可被替换的。+ 性质完全不同——那是可选、带 IRI、可被替换的。〔**仍未答,且有了可见代价**:映射探查按 `entity_types.key IN ('metric','dimension')` 找类型,找不到就 `continue`——不装包、也没人手建这两个类的库里,探查会**静默产出零条**。〕diff --git a/docs/decisions/0010-no-relation-is-no-relation.md b/docs/decisions/0010-no-relation-is-no-relation.mdindex 8a8bba3b..219981f1 100644--- a/docs/decisions/0010-no-relation-is-no-relation.md+++ b/docs/decisions/0010-no-relation-is-no-relation.md@@ -1,6 +1,6 @@# 「说不出是什么关系」不该是一个关系-**状态**:已实施 · `facts.predicate_id` 改为可空+**状态**:已实施 · `facts.predicate_id` 改为可空 · 文末两条待做已随 [0011](0011-a-mapping-is-not-a-fact.md)(#126)一并完成——`mapped_to` 不只撤出提示词,它整体退出了 `relation_types`,建库不再播种任何关系(2026-09-02 核)这是 [0009](0009-no-type-is-a-type.md) 在关系侧的孪生。那一篇讲的是`concept`——一个"还没判出来"被写成了一个类;这一篇讲 `related_to`——@@ -128,7 +128,7 @@0052 只删了 `relation_types` 里的**行**。种子关系是**代码**——`graph.rs` 的`DEFAULT_RELATION_TYPES` 里那一条还在,而 `ensure_default_ontology` 在建库、-看本体页、**每次抽取**时都会跑。账本上看得很清楚:+看本体页、**每次抽取**时都会跑。〔该函数连同种子表在 #128 整体退场,这类「长回来」从此不可能;`no_predicate_still_shows.rs` 里的对照组随之改写。〕账本上看得很清楚:0052 应用于 08-30 17:54 → 全库 related_to 归零bench demo-autoextend → 08-30 18:01 又长出一条 builtin=true@@ -159,10 +159,12 @@ SELECT count(*) FROM relation_types WHERE key = 'related_to' AND builtin另外两个连带修掉的:全库计数的断言会被并行测试污染(改成按 kb 查),以及断言 panic 会跳过 teardown(改成开跑前先扫地)。-## 待做+## 待做〔均已完成,见状态行〕- `mapped_to` 从抽取提示词里撤掉。它链接的是实体 → 数据源 schema(JSON 值),只有 `related_to` 被排除在提示词外,于是模型在实体↔实体上用了它 41 次。一行过滤的事。- 再进一步:`mapped_to` 根本不该在本体里,它是问数映射的内部机制,与这一篇讲的是同一类错误——把控制流写成词汇。++〔**顺带记两处死代码**(2026-09-02):`graph.rs` 的 `confirmed_mappings()` 全仓零调用(问数改走 `mappings::confirmed`);`confirm_fact` 里那段「同 (概念,源) 旧映射作废」的 `r.key = 'mapped_to'` 连接现在恒匹配零行。该清。〕diff --git a/docs/decisions/0011-a-mapping-is-not-a-fact.md b/docs/decisions/0011-a-mapping-is-not-a-fact.mdindex 765e7546..5a5b3b13 100644--- a/docs/decisions/0011-a-mapping-is-not-a-fact.md+++ b/docs/decisions/0011-a-mapping-is-not-a-fact.md@@ -1,6 +1,6 @@# 0011 · 「怎么算」不是「有什么」-- **状态**:规划中+- **状态**:已实施 · 建表与接线(#126,与本文同一提交)、独立的数据映射页(#140)、从 Review 队列里归位(#148);三样重做两样落地、证据链未做;两个开放问题一个已答(2026-09-02 核,修订见文末)- **成文**:2026-08-31(约定见 [README](README.md))- **相关**:[0009](0009-no-type-is-a-type.md) 删掉内置实体类、[0010](0010-no-relation-is-no-relation.md)删掉兜底关系、`#125` 删掉其余八条种子关系——本文是同一条线的最后一段:@@ -116,10 +116,22 @@ UPDATE facts SET confidence = 1.0 WHERE id = $1- **短期内多一段 UI**:Review 页要多一个分组。0002 R0 也需要它,两者合并做一次,别做两遍。+## 修订记录(2026-09-02):建成之后对照本文++**状态行写着「规划中」,而本文正是与它的实现同一个提交进来的**——这是本次复核里最大的一处偏差,记在这里作为教训:状态行该由实现它的 PR 负责更新。++**形状上的三处小差别**:唯一性 `(kb_id, concept_id, source)` 是 `UNIQUE` 约束不是主键(主键是 `id`),结论不变;表多一列 `derived`(派生指标,如「转化率 = 成交数 / 访问数」);+**没做数据迁移**——库里是 mock 数据,旧的 `mapped_to` 事实留在账本里没人读。++**三样重做**:Review 分组做了,然后又搬走了——#140 建了独立的「数据映射」页,#148 把 Review 左栏那一档挪到底部只留计数并跳转,理由是数据映射既不是队列也不是历史;审批端点仍留在 `review_routes`(`mapping.decided` 审计流水在那里)。+历史做了:`revise()` 落整版快照进 `concept_mapping_revisions`,页面有 History 抽屉。**证据链没做**:`concept_mappings` 上没有任何「LLM 读了哪张表的 schema」的记录列,探查提议不留证据。++**两条本文没写的**:`propose()` 用 `ON CONFLICT … DO UPDATE … WHERE status = 'proposed'`,重跑探查不会抹掉人的拒绝(顺带记下 Postgres 的实情:`DO UPDATE … WHERE` 不满足时 `RETURNING` 零行);可见性分级——列表 Viewer 可看、`revise` 要 Editor,「看得见答案却看不见口径,等于要人信一个不给看的算法」。+## 开放问题- **确认过的口径改了怎么办?** 双时态那套答得出「上季度的口径是什么」,- 换成 revisions 表之后要显式设计。问数回溯历史报表时会撞上它。+ 换成 revisions 表之后要显式设计。问数回溯历史报表时会撞上它。〔**已答**:`revise` + `concept_mapping_revisions` + History 抽屉。「上季度的口径」能从 revisions 里读出来,问数是否据此回溯仍未做。〕- **多源同概念**:`(kb_id, concept_id, source)` 允许同一个概念在不同源上有不同定义,这是有意的(0010 之前的注释就这么写)。但问数该用哪一条?- 今天靠 prompt 里全给、让模型挑。这条不因本篇改变,但搬表之后更容易加规则。+ 今天靠 prompt 里全给、让模型挑。这条不因本篇改变,但搬表之后更容易加规则。〔仍是全给(上限 30 条)由模型挑。〕diff --git a/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md b/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.mdindex c4092980..bc3624f5 100644--- a/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md+++ b/docs/decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md@@ -1,6 +1,6 @@# 本体是一份契约,不只是一份建议-**状态**:已实施 · 五轮对照实验 · 违反率 57% → 4%,反向 39 → 0+**状态**:已实施 · 五轮对照实验 · 违反率 57% → 4%,反向 39 → 0 · 文末三条待做全部仍未做;本文之后本体又能声明 `inverseOf` / `subPropertyOf`(#177 / #179)并被推理机消费,包清单扩到五个而实验只覆盖前两个(2026-09-02 核)[0008](0008-ontology-packs-as-cold-start.md) 建了预制本体包,但它要回答的那个问题——**大本体到底顶不顶用**——一次都没被问过:装了包的库全是 5 篇文档、26 条事实的@@ -167,8 +167,9 @@ distrust with Altman`(65 字符)是从句——字符数分不开,**谓语## 待做- **写入时的守卫挡不住写入之后的改动**:实体合并会把主语换成另一个类型的实体,- 于是事实「变成」违反。实测 6 条残留里 4 条如此。要治得把同样的检查放进合并路径。+ 于是事实「变成」违反。实测 6 条残留里 4 条如此。要治得把同样的检查放进合并路径。〔仍未做:`merge_entities` 只做互指事实作废、主宾改指、SPO 去重,全程没有 domain / range 复核。〕- 另外 2 条残留(`Stability AI Ltd`、`Colossus 2 data center`)没有合并也没有改类型,**原因未查明**。- 导入本体包时过滤掉需要中间节点才能用的关系(domain 全是 `Action`/`Offer`/- `LoanOrCredit` 这类具化壳的),它们铺给模型只会产出违反。+ `LoanOrCredit` 这类具化壳的),它们铺给模型只会产出违反。〔仍未做。〕+- **(2026-09-02 补)`bootstrap_ontology.rs` 开头的模块注释仍在说「新建的库只有 10 个默认关系……降级成 related_to」**,那是三次退场之前的世界。不属于本篇,但与本条线同源,该改。diff --git a/docs/decisions/0013-a-source-should-hand-over-its-history.md b/docs/decisions/0013-a-source-should-hand-over-its-history.mdindex b2801dba..3d6dc251 100644--- a/docs/decisions/0013-a-source-should-hand-over-its-history.md+++ b/docs/decisions/0013-a-source-should-hand-over-its-history.md@@ -1,6 +1,6 @@# 0013 · 一个来源该交出它的历史,不是它的现状-- **状态**:已实施两个(`github_issues` #134、`jira_issues` #135)· 文档协作类待做+- **状态**:已实施两个(`github_issues` #134、`jira_issues` #135)· 文档协作类(飞书 / Confluence / Notion)仍未开工,`instant` 精度未触发(2026-09-02 核,其余陈述逐条复核为真)- **成文**:2026-08-31(约定见 [README](README.md))- **相关**:[0001](0001-ontology-import-and-governance.md) 的双时态地基;语料侧的同一个判断见 `scripts/bench/fetch-wiki-history.mjs`(#122);@@ -152,6 +152,11 @@ day 精度,时刻在入库前就没了。两件都不是这篇的主题,但判据是同一条:**来历要看得见**。接新来源时值得一并想:这个来源带进来的东西,读者能不能一眼看出它是从哪来的。+## 相邻的一层:一个源能被谁挂载++本文谈「东西怎么进来」。写完之后加了一层本文没有的东西——**授权**(#142,`data_source_grants`):注册数据源是部署级动作,而它携带的连接串会到达每一个被授权的工作区,所以挂载只能在授权过的集合里挑,守卫在两侧都有(列表按工作区过滤 + 挂载端点复核)。+判据与本文一致:来历要看得见,去向也要管得住。+## 待做:飞书 / Confluence / Notion文档协作类是下一个该接的——它是 #122 那份维基历史快照语料的**企业版**:diff --git a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.mdindex edacd80f..5b89926b 100644--- a/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md+++ b/docs/decisions/0014-identity-from-the-person-scope-from-the-token.md@@ -1,6 +1,6 @@# 0014 · 身份跟着人,范围跟着令牌-- **状态**:规划中 · MCP 服务端的第一块地基,代码未动+- **状态**:已实施(#161 记录、#180 落地)· `personal_tokens` + Streamable HTTP 的 MCP 服务端已上线,暴露五个只读工具;**尚无前端界面**——令牌的发放 / 列表 / 撤销与 MCP 配置提示今天都只有 API(2026-09-02 核,修订见文末)- **成文**:2026-09-01(约定见 [README](README.md))- **相关**:迁移 `0014_data_source_grants` 刚给数据源补上授权层——本篇是同一个问题换到「机器来敲门」这一侧;[0004](0004-language-and-localization.md) 定下服务端只说英文,@@ -117,12 +117,23 @@ CREATE TABLE personal_tokens (MCP 的对应形态是:握手时校验一次,然后整条连接生命周期里都信任它。工具调用是一个个独立请求,`revoked_at` 在中途被写上时,正在跑的连接必须立刻失效。+## 修订记录(2026-09-02):落地之后对照本文++**形状**多一列 `token_prefix`(`utp_pat_…`,与 ingest 的 `utp_` 区分——日志与配置文件里一眼要认得出是哪一种),`token_hash` 加了 `UNIQUE`。哈希选 SHA-256 不选 argon2:高熵串不怕爆破,而每行盐不同就查不了唯一索引。++**「每个工具入口都校验 scope」那条纪律被满足了,但形态与预想不同**:做成完全无状态——每个 POST 重跑一次认证(撤销 / 过期在 SQL 的 `WHERE` 里判)+ `covers()` + `require_kb`,没有「连接」这个东西可以被信任。`scope` 在这一版没有分支:`can_write` 硬编码 `false`,就算令牌勾了 write 也不放开。每次工具调用写一条审计(`mcp.tool_called`,target 是令牌),归因是真的。++**前置条件本文没记**:#175 把七个工具的执行从 `chat.rs` 的 `match` 里抽成 `tools.rs`,对话与 MCP 共用同一份实现——否则「对话里的 `entity_facts` 和 MCP 里的不是同一个东西」。工具的 JSON schema 仍留在 `chat.rs`,MCP 复用它做转换,已知带一处瑕疵:`search_chunks` 的描述里还写着「可以引用成 [n]」,而 MCP 客户端拿不到引用编号。++**一处会误导人的陈述**:`crates/utopia-mcp` 曾是三行占位,宣称的三个工具名(`add_memory` / `search_memory` / `get_entity_timeline`)从未实现,MCP 服务端住在 `utopia-server/src/api/mcp.rs`。〔已删(2026-09-02,连同 `utopia-graph`、`utopia-connectors`),理由见 [0016](0016-close-the-open-seams-before-cutting-new-ones.md) A2。〕+## 未决- **`query_data` 与 `remember` 要不要进第一版。** 倾向不进——先发四个只读工具(`search_chunks` / `find_entities` / `entity_facts` / `changes`),把身份这条路走通再说。- 这两个各自还有没答的问题:外部 agent 写进来的事实挂什么证据?跑 SQL 的审计怎么记?+ 这两个各自还有没答的问题:外部 agent 写进来的事实挂什么证据?跑 SQL 的审计怎么记?〔**已答:不进**。实际发的是五个而非四个,多一个 `search_docs`。`remember` 的前提是 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 那道闸,而闸还没接上。〕- **传输层**:stdio(本地,配 Claude Desktop 最省事)还是 streamable HTTP(远程,- 和 Utopia 已经是个服务端相称)。这个选择不影响本篇的结论,两种都要认令牌。+ 和 Utopia 已经是个服务端相称)。这个选择不影响本篇的结论,两种都要认令牌。〔**已答:Streamable HTTP**,一条路由 `POST /api/v1/kbs/{kb_id}/mcp`,响应用 `application/json` 不用 SSE——工具一问一答,没有服务端主动推的东西。〕- **令牌能不能跨工作区。** 现在的 `kb_ids` 是库级白名单;如果将来要按工作区发,- 和数据源授权那张表会长得很像,届时看要不要合并概念。+ 和数据源授权那张表会长得很像,届时看要不要合并概念。〔仍未做。〕+- **(2026-09-02 补)没有界面。** 「UI 默认给 90 天」的 90 天在服务端,而前端根本没有令牌那一页。这是 MCP 今天对用户不可用的直接原因。diff --git a/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md b/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.mdindex cda3b952..80ddc2af 100644--- a/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md+++ b/docs/decisions/0015-recording-a-sentence-is-not-asserting-a-fact.md@@ -1,6 +1,6 @@# 0015 · 记下一句话,不等于断言一个事实-- **状态**:规划中 · schema 未动+- **状态**:进行中 · schema 已落(迁移 `0018_a_fact_awaiting_a_nod`,与本文同一 PR #180)· **抽取侧尚未接线,三条决定一条都没落地;`remember` 已被整体停用作为临时闸**(2026-09-02 核,修订见文末)- **成文**:2026-09-01(约定见 [README](README.md))- **相关**:[0010](0010-no-relation-is-no-relation.md) 删掉兜底关系(本篇那条空谓词正是它的正确行为)、[0011](0011-a-mapping-is-not-a-fact.md) 批过「拿浮点数编码二值状态」——@@ -122,6 +122,20 @@ object_value, valid_from, valid_to, ..., confidence, derived_by_rule, supersedes装上这道闸之后,**外部 agent 也只能提议,不能断言**。人先看见才生效,那条顾虑就不成立了。所以本篇不只是修一个 bug,它是 0014 里那个「未决」的答案。+## 修订记录(2026-09-02):只有 schema,没有运行时++`pending_facts` 与 `rejected_facts` 两张表在 #180 建好了,形状按「原句在上、三元组在下」设计:`chunk_id NOT NULL` 指回那句记忆、`proposed_predicate` 存模型原话、`predicate_id` **可空**——人要看见的正是这个空、`proposed_by` 补上「谁的话」。失败方向的论证被完整搬进了迁移注释。++**但全仓零读零写。** `memory::is_memory_document()` 为这道判据写好了,零调用;抽取管线没有任何 `pending_facts` 写入点;Review 的八档计数里没有 `pending` 这一档;`remember` 的回话仍是 `Recorded (effective …)`。++**临时闸是把工具整个关掉**:`chat.rs` 的 `REMEMBER_ENABLED = false`,注释写着「抽取侧接上那张表之后改回 true;在那之前宁可没有这个工具,也不要一个会悄悄改图的工具」。所以三条决定里只有隐含的第 0 条(不让说谎继续)实现了。++**于是下文「MCP 开写的障碍消掉了」在代码上还不成立**——闸没装上,MCP 依旧只读。++**一个数字的更正**:「27 处查询按 `invalidated_at IS NULL` 捞活事实,分布在 6 个文件」——今天是 56 处、7 个文件(多出 `ontology.rs`)。论证方向不变,数字若再被引用应重新数。++**同一类问题的另一面**(#173,迁移 `0015_what_it_did_not_just_what_it_said`):跨轮回放助手上一轮的工具调用与结果,模型才知道自己做过什么,不会把上一轮的检索重跑一遍落到另一批同名实体上。本文讲的是「助手说的」与「图里得到的」之间的落差,那一条讲的是「助手说的」与「助手做的」之间的落差。+## 未决- **闸只拦记忆,还是拦所有「单条、交互式」的写入?** 今天只有 `remember` 这一条路,@@ -130,4 +144,4 @@ object_value, valid_from, valid_to, ..., confidence, derived_by_rule, supersedesconfidence 表达人的态度,那大概是「不动它」——但要想清楚。- **拒绝之后那条记忆怎么办。** 文档还在(人确实说过那句话),只是没抽出可用的事实。下一轮重抽会不会又提议一遍?`concept_mappings` 那边靠 `status='rejected'` 挡住了- 重复提议,这里需要对应的东西。+ 重复提议,这里需要对应的东西。〔答了一半:`rejected_facts` 表与查重索引建好了,语义就是「这个三元组在这个库里被拒过」,但没有任何代码写它或查它。〕diff --git a/docs/decisions/0016-close-the-open-seams-before-cutting-new-ones.md b/docs/decisions/0016-close-the-open-seams-before-cutting-new-ones.mdnew file mode 100644index 00000000..5aa818e1--- /dev/null+++ b/docs/decisions/0016-close-the-open-seams-before-cutting-new-ones.md@@ -0,0 +1,118 @@+# 0016 · 先把开着的口子收上,再开新的++- **状态**:规划中 · v0.1.0 之后的第一份排期+- **成文**:2026-09-02(约定见 [README](README.md))+- **相关**:本文是对 [0001](0001-ontology-import-and-governance.md) 到 [0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 逐篇对照代码复核之后写的;每一条「待做」都能在那十五篇里找到出处。复核本身的产物是各篇里 2026-09-02 的修订记录,本文只排顺序、只讲为什么是这个顺序++> 这一篇没有实验数字。它是一次盘点:v0.1.0 发出去了,README 的能力表写了十二行,+> 十五篇决策记录里有三篇的状态行落后于同一个 PR 里的代码。**在开下一条大线之前,+> 先把「说的」和「做的」对齐一遍。**++## 现状,一段话++一个 Rust 二进制加一个 Postgres:摄入(十种格式、URL / RSS / GitHub / Jira 同步、按源令牌推送)→+混合检索 → 抽取(本体驱动、预算内全铺、超预算按块检索加祖先补齐、写入时按签名掰正方向)→+三段消解(等值召回、画像相似、包含关系)加攒批裁决 → 双时态账本(证据、supersedes、合并可回滚)→+本体从语料长出来(计数采纳、可撤销、默认开)→ 推理机 R0 全建、R1 带开关 → 语义层(概念映射另存、口径有历史)→+问数(Ontology2SQL,源授权到工作区)→ 对话是 agentic 的,七个工具,跨轮回放自己做过什么 → MCP 只读五工具、个人令牌。+告警五种,审计台账,每库角色矩阵。约 4.7 万行 Rust、2.2 万行前端、18 个连库测试、8 份可重跑语料。++**这些都是真的。** 下面这些也是真的:++| 半成品 | 出处 | 症状 |+|---|---|---|+| `pending_facts` 只有表没有运行时;`remember` 整个停用 | 0015 | README 里有 Chat 记忆,用户用不到 |+| MCP 只有 API,没有令牌界面 | 0014 | README 里有 MCP,用户配不了 |+| `utopia-mcp` / `utopia-connectors` / `utopia-graph` 三个 crate 是三行占位,其中一个宣称的工具名从未实现 | 0014 | 读源码的人被误导 |+| 证明树只展开一层;增量维护没做;派生 vs 断言矛盾不记信号 | 0002 | README 说 derivation path expands back to the sentence,只对了一层 |+| `disjointWith` 落库了,消解侧仍用硬编码 `CONFUSABLE_TYPE_KEYS` | 0009 / 0001 P5 | 本体声明了不相交,合并候选照样跨过去 |+| 合并路径没有签名复核 | 0012 待做 | 写入时掰正的方向,合并一次就能再反回去 |+| 类型消解只能手动跑 | 0001 P3a | 大本体下新实体的细化靠人记得点一下 |+| 中文库拿到纯英文本体;`zh.ts` 没追平所以界面默认英文 | 0008 / 0004 | 中文用户两头都是英文 |+| `merge_key` 不折 `_by`;叙述动词进本体 | 0007 | 同一关系两个方向并存 |+| 预算 24,000 与每块 40 / 30 / 30 标着「待测」;答案键仍是人填的;混装准确率没测 | 0006 / 0008 | 所有「更好」都说不清是改动还是方差 |+| 语义层映射不留证据;多源同概念全给模型挑 | 0011 | 口径是黑箱 |+| 映射探查硬依赖 `metric` / `dimension` 两个 key,空库静默零条 | 0009 未决 | 不装包就没有问数语义层 |+| 关掉自动扩本体后没有「新说法」提醒 | 0003 | 索引铺好了,提醒没做 |+| `document.no_text_layer` 未接,OCR 端点不存在 | 0005 | 扫描件全绿 |+| 死代码与陈旧注释:`graph.rs` 的 `confirmed_mappings()`、`confirm_fact` 里的 `mapped_to` 连接、`bootstrap_ontology.rs` 开头的注释、`reasoning.rs` 里写错的迁移号、测试抬头写错的迁移号 | 0010 / 0012 / 0002 / 0014 | 下一个读的人会信 |++## 判据++以后再排期,用这几条判,不重新辩论:++1. **说的和做的要一致。** README 的一行承诺、决策记录的一个状态行、代码里的一句注释——三者不一致时,先改到一致,再谈新功能。[0015](0015-recording-a-sentence-is-not-asserting-a-fact.md) 讲的是助手对用户,这条是我们对读者。+2. **写图的东西先于读图的东西。** 一个会悄悄改图的半成品比没有更坏;一个只读的半成品只是少一个功能。所以 `pending_facts` 排在证明树前面。+3. **能量的先做。** `scripts/bench/` 在,语料在,缺的是外部答案键。没有它,本体与抽取侧的任何调参都是把过拟合调得更紧([0006](0006-ontology-scale-and-the-prompt.md) 未决)。+4. **模拟与执行门等地基。** README 路线图的头两条——决策推演、执行校验——本质是「**不落账的提议叠加在账本之上**」。0015 的 `pending_facts` 就是这个形状的第一块砖:一条提议、原句在上三元组在下、人点头才进账。先把这块砖砌稳,模拟引擎才有可以叠的东西。++## 四条线,按这个顺序++### A · 收口——两到三周,不加新概念++**A1 · 把 0015 接上。** 抽取遇到记忆文档(`memory::is_memory_document`,已写好零调用)时写 `pending_facts` 而不是 `facts`;+Review 加 `pending` 一档,界面**原句在上、三元组在下**;确认 → `insert_fact`,**置信度不动**(0011 的教训:别拿浮点数表达人的态度,人的态度在审计台账里);+拒绝 → 写 `rejected_facts`,下一轮重抽先查它;`remember` 的回话改成「已记录,抽出 N 条待你确认」;然后把 `REMEMBER_ENABLED` 改回 true。+**验收**:那条实测(「Acme 把总部搬到深圳」)跑一遍,图上不出现空谓词活边,Review 里出现一条带原句的待确认项。+做完这一条,MCP 可以放 `remember`(scope = write,令牌以人的身份提议,人自己确认)——0014 未决的答案由此成立。++**A2 · 令牌有界面。** Account 页:列表(前缀、名字、scope、库、最后使用、过期)、发放(明文只显示一次)、撤销;旁边给一段可复制的 MCP 客户端配置(URL + Authorization 头)。+三个占位 crate **删掉**(已做,与 A3 同一刀):`utopia-mcp` 宣称的三个工具从未存在,服务端住在 `utopia-server/src/api/mcp.rs`;`utopia-graph` 没有对应物;`utopia-connectors` 的意图是对的,但两个连接器看不出边界该划在哪,[0013](0013-a-source-should-hand-over-its-history.md) 说等第三个来了再看抽象,crate 是同一个判断。占位是对读者的承诺,兑现不了就别留,需要时 `cargo new` 是几分钟的事。++**A3 · 清死代码与陈旧注释。** 上表最后一行那五处,加上 `resolution.rs` 里 `CONFUSABLE_TYPE_KEYS` 上方停留在旧世界的注释。一个 PR。++**A4 · README 与代码对表。** Reasoning 那一行的 "derivation path expands all the way back to the original sentence" 在 B1 做完之前改成只承诺一层;+Chat memory 与 MCP 两处在 A1 / A2 落地前标 in development。中英两份一起改。++### B · 推理机补完——A 之后,与 C 并行++**B1 · R2 证明树。** 递归展开到叶子 chunk 的 API + 实体面板里可展开的树。数据结构(`fact_derivations`)已够。+**B2 · 派生 vs 断言矛盾要有信号。** `axiom_violations` 加一种 kind(`derived_contradiction`),进 Review 同一档——0002 写了没做的那一行。+**B3 · `disjointWith` 进消解,合并路径复核签名。** `classify_type_drift` 改从 `entity_type_disjoint` 读(没声明就退回今天的行为,不硬编码);+`merge_entities` 搬事实前跑一遍与写入时相同的 domain / range 检查,违反的进 `axiom_violations` 而不是静默搬过去。这是 0009 与 0012 各自待做的同一件事。+**B4 · R3 增量维护——后置。** 只在测量台上全量重推超过一个明确阈值(建议:`ai-timeline-ends` 语料超过 10 秒)时才做。今天每次全量重推活得下去。++### C · 本体与抽取质量——先造尺子,再调参++**C1 · 外部答案键。** 0006 未决的那条:维基条目配 Wikidata `P31` 作类型答案,生成脚本入库。有了它,才能跑 0008 的混装对照(`run.mjs --packs` 已支持)与 0006 的预算曲线。+**C2 · 类型消解自动触发。** 抽取结束入队一次类型消解(与 `bootstrap_ontology` 并列),只自动落「在原类子树里」的那一档,跨轴仍进人工。**排在 C1 后面**:没有尺子,自动跑等于把噪声规模化(0001 P3 的原话)。+**C3 · 中文本体。** 三选一,倾向第一个:装包时若 `ontology_lang = zh`,由 LLM 批量生成中文 **description**(模型读的那一行,0004 说它该跟语料语言),存进库、原文 IRI 不动、`label` 不动(label 是 key 的展示,key 永不翻译);+另两个是「等社区出中文包」与「什么都不做只提示」。同时把 `zh.ts` 追平,把 `navigator.language` 加回 `detect()`。+**C4 · 0007 的两条尾巴。** `merge_key` 折 `_by` 并把整组标成需对调;叙述动词交给那次同义归并的 LLM 调用一并审(「这些里哪些是文章的口吻」),可撤销。+**C5 · 0003 的提醒。** 关掉开关后 Ontology 页显示「自上次以来有 N 个新说法」,数据从 `ontology_misses` 按 `dismissed_at IS NULL` 算,索引已在。++### D · 语义层与问数——C1 之后++**D1 · 映射留证据。** `concept_mappings` 加 `evidence`(探查时读了哪几张表的 schema 文档,chunk id 数组),数据映射页展示。+**D2 · `metric` / `dimension` 出包。** 0009 未决的答案:做一个「Utopia 语义层」包,带 IRI、可选、可替换,与其它包同一条装法;`mappings.rs` 改按 IRI 找类型,不按 key。+**D3 · 多源同概念的选法。** 先做最简单的规则:问数时若挂载的源只有一个,只给那个源的映射;多个源全给。规则写在 `mappings::confirmed` 一处。+**D4 · MySQL 线协议。** 白捡 TiDB / OceanBase / Doris / StarRocks,`sqlparser` 换方言。README 路线图里的那条。++### E · 企业交付——v0.2 的门槛,可穿插++- **凭据静态加密**(SECURITY.md 承诺「1.0 之前」;LLM key 与连接串同待遇)——小,可提前。+- **OIDC SSO**;**备份与恢复命令**;**十万文档基准**(先跑再说,数字比设计重要)。+- **`document.no_text_layer` + OCR**:告警那条接上要先有 OCR 端点(docling-serve sidecar),两件一起做,提示语才完整(0005 留到第二批的那条)。+- **`instant` 精度**:0013 说了触发条件(按当地营业日统计、或事件聚在午夜附近的源),没触发前不做。++### 后置:模拟引擎与执行门++README 路线图的头两条**不在这份排期里**,理由见判据 4。它们需要三样地基:`pending_facts` 的提议语义(A1)、派生的可解释性(B1)、派生与断言的矛盾信号(B2)。+A 与 B 做完之后单独写一篇决策记录,那时再排。++## 顺序与理由,一句话++**A → B ∥ C → D → E。** A 是对齐「说的和做的」,不做新东西;B 与 C 互不依赖,B 动写图的路径、C 动尺子;D 等 C1 的尺子;E 可穿插,加密先。++## 一条新约定++**状态行由实现它的 PR 负责更新。** 0011、0014、0015 三篇的状态行都落后于同一个 PR 里的代码——写决策记录的人和写代码的人是同一个人,在同一个提交里,仍然漏了。+所以不靠记性:PR 模板里加一行「这个改动实现或推翻了哪篇决策记录,状态行改了没有」。已写进 [README](README.md) 的约定。++## 开放问题++- **A1 的闸只拦记忆,还是拦所有单条交互式写入?** 0015 未决。今天只有 `remember` 一条路,先拦它;将来「在图上手工加一条边」的界面出现时,按同一张表走。+- **C3 生成的中文描述算不算「原文保真」的例外?** 它不是导入的原文,是我们生成的投影。倾向记成投影(可重跑、可丢弃),原文 IRI 与英文描述保留在包里。+- **B4 的阈值**:10 秒是拍的。+- **要不要把抽取层拆出 `utopia-server`。** 今天约 6,500 行领域代码(extraction、type_resolution、bootstrap_ontology、predicate_match、adjudication、owl_import、连接器)住在 HTTP crate 里,依赖方向仍是干净的一条线。讨论过(2026-09-02)决定**不拆**:唯一实在的收益是脱离 server 测纯函数,而它们的单测今天已经不起 server;搬动 1,500 行的 `extraction.rs` 会让紧接着的 A1 diff 和 blame 变难看。判据留下:**等它造成实际损失再拆,损失的定义是「有东西没法脱离 server 测试」**。连接器那一块的边界等第三个连接器(飞书)来了再定。+- **十万文档基准跑出来之后**,单进程 worker 与内嵌 Tantivy 的天花板在哪,决定了要不要在 v0.2 谈横向扩展。现在不谈。diff --git a/docs/decisions/README.md b/docs/decisions/README.mdindex 3b0da89a..ac215b94 100644--- a/docs/decisions/README.md+++ b/docs/decisions/README.md@@ -16,32 +16,37 @@**结论变得太多时**,另起一篇并在旧篇顶部标 `已被 NNNN 取代`,而不是把旧篇改成新的。+**状态行由实现它的 PR 负责更新。** 0011、0014、0015 三篇的状态行曾落后于同一个 PR 里的代码——写记录的人和写代码的人是同一个人、同一个提交,仍然漏了。所以 PR 描述里要答一句:这个改动实现或推翻了哪篇决策记录,状态行改了没有。(2026-09-02 加,出处见 [0016](0016-close-the-open-seams-before-cutting-new-ones.md)。)++**行号会漂,文件名会换。** 正文里的 `file.rs:123` 是成文时的坐标,不保证仍然准确;迁移在 #130 / #131 从 53 份折成 10 份、一个域一份,所以 2026-08-31 之前写的迁移文件名都要按域重找。引用时优先写函数名、表名、常量名。+**语言**:中文,与代码注释一致(UI 与 README 保持英文)。目前的读者是维护者,不是外部贡献者;将来需要时再译。## 索引| | 文档 | 状态 ||---|---|---|-| 0001 | [本体导入与治理路线](0001-ontology-import-and-governance.md) | 进行中 · P0–P2c 已建成;P3a 已建成(检索命中率见下)、P3b 部分;P4a 已建成,**P4b/P4c 待做**;P5 由 0002 取代 |-| 0002 | [推理机](0002-reasoning-engine.md) | 规划中 · 取代 0001 P5 的排期 |-| 0003 | [本体从语料里长出来,人站在哪一环](0003-ontology-growth-loop.md) | 已建成 · 含三次判断变化的留痕 |-| 0004 | [语言:哪些字跟着看的人走,哪些跟着语料走](0004-language-and-localization.md) | 已建成 · L0–L3 全部落地 |-| 0005 | [告警中心](0005-alert-center.md) | 第一刀已建成 · 三个决定推翻两个(就地留痕) |-| 0006 | [本体规模与抽取提示词](0006-ontology-scale-and-the-prompt.md) | 已建成 · 含可重跑的实测数字与一次撤回 |-| 0007 | [谁来决定一个说法值不值得成为关系](0007-who-decides-what-becomes-a-relation.md) | 已建成 · 采纳改由计数决定 · 含五条走过的死路 · **叙述动词待解** |-| 0008 | [预制本体包作为冷启动](0008-ontology-packs-as-cold-start.md) | 规划中 · 建库仍只发种子关系 |-| 0009 | [「还没判出来」不该是一个类](0009-no-type-is-a-type.md) | 已实施 · `entities.type_id` 改为可空 |-| 0010 | [「说不出是什么关系」不该是一个关系](0010-no-relation-is-no-relation.md) | 已实施 · `facts.predicate_id` 改为可空 · 0009 在关系侧的孪生 · **含一次七分钟后长回来的修订** |-| 0011 | [「怎么算」不是「有什么」](0011-a-mapping-is-not-a-fact.md) | 规划中 · 语义层映射搬出本体 · 0009/0010 那条线的最后一段 |-| 0012 | [本体是一份契约,不只是一份建议](0012-the-ontology-is-a-contract-not-a-suggestion.md) | 已实施 · 五轮对照实验 · 违反率 57%→4%、反向 39→0 · 首次拿真语料问 0008 那个问题 |-| 0013 | [一个来源该交出它的历史,不是它的现状](0013-a-source-should-hand-over-its-history.md) | 已实施两个(GitHub / Jira 工单)· **文档协作类待做** |-| 0014 | [身份跟着人,范围跟着令牌](0014-identity-from-the-person-scope-from-the-token.md) | 规划中 · MCP 服务端的第一块地基 · 含一条被否掉的岔路(KB 级机器令牌)|-| 0015 | [记下一句话,不等于断言一个事实](0015-recording-a-sentence-is-not-asserting-a-fact.md) | 规划中 · 起因是一次实测:助手说的与图里落的不是一回事 · **含一次就地推翻**(状态加在 facts 上 → 自己一张表)· 消掉 0014 里「不开写」的顾虑 |+| 0001 | [本体导入与治理路线](0001-ontology-import-and-governance.md) | 进行中 · P0–P2c 全建成;P3 按预算落地、P3a 只能手动跑;P3b 建成但形态不同;**P4b/P4c 待做**;P5 已由 0002 落地;判据 2 被 0012 推翻一半 |+| 0002 | [推理机](0002-reasoning-engine.md) | R0 建成(含本体自检八类)· R1 建成带开关默认关 · **R2 只一层、R3 未做** · 派生 vs 断言矛盾无信号 |+| 0003 | [本体从语料里长出来,人站在哪一环](0003-ontology-growth-loop.md) | 已建成且仍在跑 · 起点已被 0010 与种子退场改写 · 「拒绝有记忆」被 0007 推翻重做 · 新说法提醒待做 |+| 0004 | [语言:哪些字跟着看的人走,哪些跟着语料走](0004-language-and-localization.md) | 已建成 · L0–L3 全落地 · 界面刻意不猜浏览器语言 · 「中文内置本体」随播种退场作废 |+| 0005 | [告警中心](0005-alert-center.md) | 已建成 · 五种告警 · 三个决定推翻两个(就地留痕)· `no_text_layer` 待接 |+| 0006 | [本体规模与抽取提示词](0006-ontology-scale-and-the-prompt.md) | 已建成 · 「内置类恒在」换成祖先补齐 · 预算与候选数仍待测 · 外部答案键未做 |+| 0007 | [谁来决定一个说法值不值得成为关系](0007-who-decides-what-becomes-a-relation.md) | 已建成 · 六条缺陷全修 · 起点(种子、`related_to`)已不存在 · `_by` 折叠与叙述动词待解 |+| 0008 | [预制本体包作为冷启动](0008-ontology-packs-as-cold-start.md) | 已建成 · 五包内嵌、多选、对齐表 22 条 · 三个开放问题全开,中文标签变严重 |+| 0009 | [「还没判出来」不该是一个类](0009-no-type-is-a-type.md) | 已实施 · `disjointWith` 落库但消解侧未消费 · `metric`/`dimension` 去处未答且有可见代价 |+| 0010 | [「说不出是什么关系」不该是一个关系](0010-no-relation-is-no-relation.md) | 已实施 · 待做两条随 0011 完成 · 两处死代码待清 |+| 0011 | [「怎么算」不是「有什么」](0011-a-mapping-is-not-a-fact.md) | 已实施(#126 / #140 / #148)· 证据链未做 · 多源选法未做 |+| 0012 | [本体是一份契约,不只是一份建议](0012-the-ontology-is-a-contract-not-a-suggestion.md) | 已实施 · 违反率 57%→4%、反向 39→0 · 三条待做全未做 |+| 0013 | [一个来源该交出它的历史,不是它的现状](0013-a-source-should-hand-over-its-history.md) | 已实施两个(GitHub / Jira)· 文档协作类未开工 |+| 0014 | [身份跟着人,范围跟着令牌](0014-identity-from-the-person-scope-from-the-token.md) | 已实施(#180)· MCP 只读五工具 · **没有令牌界面** · 误导性的占位 crate 已删 |+| 0015 | [记下一句话,不等于断言一个事实](0015-recording-a-sentence-is-not-asserting-a-fact.md) | 进行中 · schema 已落、**运行时零接线** · `remember` 整体停用作临时闸 |+| 0016 | [先把开着的口子收上,再开新的](0016-close-the-open-seams-before-cutting-new-ones.md) | 规划中 · v0.1.0 之后的排期:A 收口 → B 推理机 ∥ C 尺子与本体 → D 语义层 → E 企业交付;模拟引擎后置 |## 不是决策记录的那些**[../pipeline.md](../pipeline.md) —— 一份文档如何变成图谱。** 决策记录讲「为什么这样-而不是那样」;那一篇讲「东西怎么流的、在哪一步会被丢掉」,带四张 mermaid 图。+而不是那样」;那一篇讲「东西怎么流的、在哪一步会被丢掉」,带五张 mermaid 图(2026-09-02 加了公理那一张)。新来的人先看它,再回来看这里的理由。这是本目录约定里说的「第二种性质不同的文档」。它没进子目录——放在 `docs/` 根上,diff --git a/docs/pipeline.md b/docs/pipeline.mdindex 6993b8cb..d9ba1c9d 100644--- a/docs/pipeline.md+++ b/docs/pipeline.md@@ -26,6 +26,11 @@ flowchart TBTR --> GGROW --> ONT[(本体)]ONT -.喂回.-> X+ G --> R0[一致性检查<br/>公理 vs 事实 · 不写库]+ ONT --> R0+ G --> R1[物化推导<br/>开关 · 派生另存]+ ONT --> R1+ R1 --> Gstyle RDY fill:#2d4a5a,color:#fffstyle G fill:#2d4a5a,color:#fff@@ -38,6 +43,12 @@ flowchart TB**本体那条回流虚线是这套东西的循环**:抽取用本体,抽取遇到本体没有的说法就把原词记下来,提案回流补进本体,下一批文档的抽取就用上了。见 [0003](decisions/0003-ontology-growth-loop.md)。+**本体从哪来**:建库时什么都不种。起点是可选的预制包(schema.org 默认勾选,另有 W3C Org、PROV-O、FOAF、IOF Core),+或者用户导入自己的 OWL,或者空着——空库照样能抽,实体没有类型就是没有类型。见 [0008](decisions/0008-ontology-packs-as-cold-start.md)、[0009](decisions/0009-no-type-is-a-type.md)。++**最下面那两个框是本体的公理在干活**:一致性检查不写 `facts`,只把矛盾摆出来(Review 的 violations / defects 两档);+物化推导默认关,打开后派生事实另存一张表、图上金色,永远不闭合任何断言事实。见第四节。+---## 一、抽取一个分块@@ -47,7 +58,7 @@ flowchart TBsubgraph 提示词B{本体装得下预算吗?}B -->|装得下| FULL[全量铺<br/>小本体的老路]- B -->|装不下| RET[按这一块的向量检索<br/>约 40 类 / 30 关系 / 30 属性<br/>+ 内置类恒在]+ B -->|装不下| RET[按这一块的向量检索<br/>约 40 类 / 30 关系 / 30 属性<br/>+ 命中类的祖先一起铺]endFULL --> LLM[LLM]RET --> LLM@@ -56,8 +67,12 @@ flowchart TBJ -->|entities| EN[实体<br/>type 从清单挑<br/>specific_type 自由文本]J -->|predicate 命中属性| AT[属性事实<br/>值按 datatype 归一]J -->|predicate 命中关系| RL[关系事实]+ RL --> DIR{主宾类型<br/>对得上签名?}+ DIR -->|对| OK[落库]+ DIR -->|主语违反且宾语符合| SWAP[按签名对调主宾<br/>留 direction_corrected]+ DIR -->|对调也不合法| NOP[谓词留空<br/>主宾时间证据都留]J -->|词表外 + 字面值| LIT[值落 object_value<br/>原词落 proposed_predicate]- J -->|词表外 + 实体宾语| FB[降级 related_to<br/>原词落 proposed_predicate]+ J -->|词表外 + 实体宾语| FB[谓词留空<br/>原词落 proposed_predicate]style LLM fill:#3a3a5a,color:#fff```@@ -68,25 +83,36 @@ flowchart TB因为清单里总有个"差不多"的,模型选了它,心里那个更准的说法就此丢失。**词表外的两条路都不丢东西**:带字面值的落 `object_value`(而不是凭空造一个叫「2015」的实体),-带实体宾语的降级成 `related_to`。两者的原词都进 `fact_evidence.proposed_predicate`,-那是这条事实身上唯一还留着原意的地方。+带实体宾语的**谓词留空**——不是降级成一个叫「有关联」的关系,那是断言不是含糊([0010](decisions/0010-no-relation-is-no-relation.md))。+两者的原词都进 `fact_evidence.proposed_predicate`,那是这条事实身上唯一还留着原意的地方,显示时由 `fact_surface_predicate()` 取回。++**命中的关系还要过一道签名**:本体声明了 `employee (organization → person)`,模型照样会写 `Musk employee Microsoft`——+提示词三轮都压不下去,英语的 "X is an employee of Y" 太强。所以写入时掰正:主语违反 domain 而宾语符合就对调,**绝不静默**,留一条 `direction_corrected`;+对调也不合法(`OpenAI affectedBy …`,schema.org 里那是医学检验用的)就丢掉谓词、留下主宾与证据。参数顺序是 key 的编码约定,不是关于世界的断言,所以这一处本体是执法的。+见 [0012](decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md)。### 这里会丢东西吗-会。七种,全部记进 `extraction_drops`,界面上可见:+会。十二种原因码,全部记进 `extraction_drops`,界面上可见(其中一种不是丢弃,是留痕):| 原因 | 什么时候 ||---|---|+| `truncated_reply` | 模型的输出被截断,这一块整块作废 |+| `malformed_item` | 一条事实格式不对——**只丢这一条**,不丢整块(#127) |+| `not_an_entity_name` | 「实体名」是一整句话(按词数 + 限定动词判,#143) || `low_confidence` | 模型自报置信度低于阈值 |-| `subject_not_declared` | 属性事实的主语没在 `entities` 里声明,类型不明、domain 无从校验 |-| `attr_domain_mismatch` | 属性挂到了 domain 之外的类上(沿父类上溯仍不匹配) |+| `subject_not_declared` | 主语没在 `entities` 里声明——关系与属性两条路径**都**记 |+| `attr_domain_mismatch` | 属性挂到了 domain 之外的类上(沿父类 DAG 上溯仍不匹配) || `attr_no_value` / `attr_datatype` | 属性事实没给值,或值换算不出声明的 datatype || `object_missing` | 关系事实没有宾语 |-| `fallback_relation_missing` | 本体里连兜底关系都被删了 |+| `direction_corrected` | **不是丢弃**:主宾按签名对调了,记下来是为了不静默 |+| `domain_mismatch` | 对调也不合法,谓词被丢掉(主宾与证据留下) |**`attr_domain_mismatch` 是最贵的一种**:它在落地当场丢弃,而事后改类救不回来——那条事实从没写入过,只能重抽。+从前还有一种 `fallback_relation_missing`(兜底关系被删了就整条消失)——随 `related_to` 一起没了。+---## 二、实体消解:这一条是谁@@ -203,16 +229,56 @@ flowchart TB### 这里会丢东西吗-不丢事实,但**改类不进时间轴**——它是 `entities` 上一次 UPDATE 加一行 `entity_retypes`,-而实体历史只读 `facts`。所以改错了不会自己显形。**可撤销不等于会被撤销**,+不丢事实,但**改类不进时间轴**——它是 `entities` 上一次 UPDATE 加一行 `entity_retypes`〔实体历史现在会显示 `retyped` / `retype_reverted` 两种事件,这一条已经补上〕。**可撤销不等于会被撤销**,这是先做 preview 再做 apply 的理由。+**类型消解今天只能手动跑**——本体页 preview → apply,没有任何自动触发。抽取结束只入队本体扩展与实体裁决。+所以大本体下新实体的细化依赖人记得去点一下,这是个真缺口(0001 P3a)。++**人拍过板的不再被引擎重判**:`entities.type_source` 是 `human` 的实体不进取材,包括「人判了,就是没有类型」(0001 P4a)。+**拒绝要给理由。** `left_alone` 曾经只是个数,而这一步的设计押在"选择都不是是个体面答案"上——最大的一档不透明。记上理由之后第一次跑就回答了此前答不出的问题:失败**全在检索一侧**(`administrative_area`、`periodical` 从没被端上来过),不在裁决。---+## 四、公理:检查与推导++```mermaid+flowchart TB+ ONT[(本体的公理<br/>functional · symmetric · asymmetric<br/>transitive · inverseOf · subPropertyOf · disjoint)] --> SELF[本体自检<br/>八类缺陷]+ SELF --> DEF[(ontology_defects)]+ ONT --> R0[事实层检查<br/>自环 · 反对称 · 传递环 · 基数]+ G[(图谱)] --> R0+ R0 --> VIO[(axiom_violations<br/>带完整路径)]+ VIO --> DEC{人裁}+ DEC -->|撤回事实| RET[事实作废]+ DEC -->|放宽公理| RLX[改本体]+ DEC -->|接受| ACC[两条都留]+ ONT --> R1{materialize_inferences<br/>开关,默认关}+ G --> R1+ R1 -->|开| DER[(derived_facts<br/>另一张表 · rule_id · 前提链)]+ DER --> GV[图上金色边<br/>实体面板「推出来的」]++ style DEC fill:#3a3a5a,color:#fff+```++**检查不写库,推导写另一张表。** 一致性检查(R0)只指出问题,风险面为零;物化推导(R1)会往图里加东西,所以它的每条约束都是必要的:+规则**只从本体公理编译**,没有用户 DSL;**断言硬性优先于派生**——已经断言过的三元组不再派生,「这条是谁说的」有唯一答案;+深度上限加环检测,每谓词封顶两万条且被截掉的**要说出来**;有效时间取前提的交集,空交集不推。+派生不进 `facts`:四十多处读 `facts` 的查询只有一处认得标记,分开之后忘了 UNION 的后果是**看不见**派生,而不是**混进去**。++**本体自检排在前面**:自相矛盾的本体(一个关系既 symmetric 又 asymmetric、子类成环、逆没指回来)会让事实层的结论全部可疑。++**没装本体包的库跑出来是零**,那是实情不是故障——没有公理就没有判据,不报矛盾比猜一个公理出来安全。++**什么时候跑**:导入本体后自动跑一次检查(公理刚变,最该重算的时刻);Review 页可手动跑;推导按 `inference_interval_minutes`(缺省 60)定时全量重推——增量维护还没做。++### 这里会丢东西吗++不丢,但**有两处沉默**:派生 vs 断言矛盾时派生不落地,今天**不记信号**;同一三元组有多条推导路径只留第一条证明。两者都是 [0002](decisions/0002-reasoning-engine.md) 里写了而没做的。+## 想自己跑一遍`scripts/bench/` 是可重跑的测量台,**每一组一个新库**——复用一个库省几分钟,@@ -238,3 +304,5 @@ node scripts/bench/run.mjs --corpus holmes --label holmes- [0001](decisions/0001-ontology-import-and-governance.md) 本体导入与治理,含 P3 的实测修订- [0003](decisions/0003-ontology-growth-loop.md) 本体从语料里长出来,人站在哪一环- [0006](decisions/0006-ontology-scale-and-the-prompt.md) 本体规模与抽取提示词,含曲线与一次撤回+- [0002](decisions/0002-reasoning-engine.md) 推理机的顺序与安全边界;[0012](decisions/0012-the-ontology-is-a-contract-not-a-suggestion.md) 写入时的方向掰正+- [0009](decisions/0009-no-type-is-a-type.md) / [0010](decisions/0010-no-relation-is-no-relation.md) 为什么「还没判出来」不是类、「说不出」不是关系