World's first open-source enterprise world model.
Rust agent-memorybitemporalgraphragknowledge-baseknowledge-graphllmontologypgvectorpostgresqlragrustself-hostedsemantic-searchtemporal-knowledge-graphworld-model
A source should hand over its history, not its present (#137)
WaylandYang9a64366c97ca
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.mdnew file mode 100644index 00000000..46a25074--- /dev/null+++ b/docs/decisions/0013-a-source-should-hand-over-its-history.md@@ -0,0 +1,147 @@+# 0013 · 一个来源该交出它的历史,不是它的现状++- **状态**:已实施两个(`github_issues` #134、`jira_issues` #135)· 文档协作类待做+- **成文**:2026-08-31(约定见 [README](README.md))+- **相关**:[0001](0001-ontology-import-and-governance.md) 的双时态地基;+ 语料侧的同一个判断见 `scripts/bench/fetch-wiki-history.mjs`(#122);+ [0012](0012-the-ontology-is-a-contract-not-a-suggestion.md) 是同一件事的另一头——+ 这一篇管**东西怎么进来**,那一篇管**进来之后按什么规矩落**++## 判据:一个来源值不值得接++这产品是双时态账本,所以看四条,缺一条就退化成"又一个抓网页的":++1. **有没有真实时间戳** —— 认知时间那根轴靠它+2. **会不会自我推翻** —— `supersedes` 才有事可做+3. **有没有稳定身份** —— 同一份东西的新版能认出来(`external_key`)+4. **企业知识是不是真的住在那儿**++工单系统四条全中:每张工单的状态天生随时间变,而且信噪比远高于聊天记录。++## 核心判断:别取现在,取变化++**工单最有价值的部分不是"它现在是 closed"**,而是"8-18 开出、8-20 关掉、+中间被指派给谁、优先级怎么变的"。++只抓当前状态,这条时间线要靠一次次同步慢慢攒——第一次同步只能看见此刻,+之前发生的全丢了。而多数系统**已经把变更史准备好了**,只是要多问一句。++这与 #122 给维基百科语料做的是同一个判断。区别是维基要从修订列表里采样,+工单系统直接把变更事件给你。++落进正文的形状(两个来源一致,刻意的):++```+# KAFKA-9 Consumer logs ERROR during close++Type Bug.+Currently Closed.+Resolved on 2011-07-19.++## History+- 2011-08-05 — Alan Cabrera changed Workflow: jira → no-reopen-closed+- 2015-09-01 — Tony Stevenson changed Workflow: no-reopen-closed → Apache Kafka Workflow++## Comments+### Luke Chen on 2026-08-24+…+```++**抬头写成带日期的陈述句,不是键值对。** `Opened by X on 2026-08-18` 能抽出带+`valid_from` 的事实;`created_at: 2026-08-18` 则要模型自己猜这是什么意思。++## 两个供应商教的不同的事++| | GitHub | Jira |+|---|---|---|+| 取法 | 三次拉取 + **逐工单**取事件 | **一次调用**取全(`expand=changelog`)|+| 增量 | `since` 参数 | JQL `updated >= "…"` |+| 变更史 | 事件级("发生了 labeled")| **字段级**(`Workflow: A → B`)|+| 时间戳 | RFC3339 | `+0000` **无冒号**,不是 RFC3339 |++### GitHub:聪明的设计悄悄丢掉了全部价值++第一版想让三样都走仓库级端点、一次分页取全,避免 200 张工单 401 次请求。+**拿真实数据一跑就发现事件那一路是错的**:`issues/events` 不支持 `since`,+只能从最新往回翻,而 GitHub 的模型里 PR 也产生 issue 事件——实测本仓库的工单事件+埋在**第 5 页**,换一个 PR 活跃的仓库就会被推到翻页上限之外。++于是"状态变更史"悄悄变成空的,**而它正是这个来源存在的理由**。改成逐工单取,+N 只是本轮要写入的工单数。用一次准确换一次省事,这里该换。++### Jira:三个坑都藏在字段形状里++- **时间戳不是 RFC3339**(`2026-08-24T11:11:52.944+0000`,时区偏移没有冒号)。+ chrono 默认解不了,解不出来就是整页工单丢掉。+- **增量没有 `since` 参数**,只能靠 JQL,时间格式是 Jira 自己的且**要带引号**——+ 两点写错的症状都是 400,不是"查不到"。+- **`fields` 必须显式列**:不列 `comment` 就不返回评论;默认返回全部字段会把+ 一条响应撑到几百 KB。++## 拿真实响应钉住字段形状++手写的 JSON 只能证明"我以为的形状"解得出来。GitHub 一条 issue 有上百个字段,+我们只声明十个;哪个其实叫别的名、哪个在某些情况下是 null,只有真数据说得清。++两个连接器的夹具都取自**公开可匿名读的实例**(`deeplethe/utopia`、+`issues.apache.org`),字段裁到我们声明的那些——裁剪本身顺带证明了未声明的+字段不会让 serde 失败。++它当场抓到一个手写测试全绿而真实数据报错的 bug:**逐工单事件端点不返回 `issue`+字段**(上下文已经在 URL 里)。第一版按仓库级响应写成必填,换端点后整片解不出来。++**这条对后来者是硬要求**:接一个没有公开实例、拿不到真实响应的来源,+交付时必须说明"未经真实实例验证",别跟这两个混为一谈。++## 截断要说出来++Kafka 项目有 **14506** 张工单,一轮翻页上限取 500。不报的话界面上"同步完成"+是一句误导——所以取回数小于 `total` 时落一条 warn,说明本轮只覆盖了一段。++与 #108「部分抽取报告成完成」、#127「一条坏记录不该毁掉一整块」同一条原则:+**限了覆盖面就要说出来**。++## 为什么没有抽象成 `issues` + provider++接第二个供应商正是为了看清该不该抽象。答案是**暂时不该**:取法根本不同+(三次拉取 vs 一次调用、`since` vs JQL、事件 vs 字段变更)。共同的只有+"一张工单一篇文档、正文带变更史"这条判断——而它已经体现在两边一致的**文档形状**上,+不需要一个共同的 trait 来强制。++硬抽一个 provider 接口,会把这些真实差异挤进一堆 `match`。等第三个来了再看:+如果它的取法落在已有两种之一,那时抽象才有形状可依。++## 这条线后来延伸到了哪++「说清楚一样东西是哪来的」不止管来源。同一句话在本体侧也成立,+而且是这篇写完之后才补上的:++- **#141**:类的形状开始承载来历——**方 = 词表声明的(有 IRI),+ 圆 = 语料里长出来的**。从前所有自动建的类都写死 `circle`,+ 一张图上看不出哪些类是本体里定义过的、哪些是从文档里长出来的。+- **#145**:一个类被词汇表**认领**(`adopt_iri_onto_key`)之后形状要跟着改。+ 漏了这一处的症状很刺眼:类拿到了 IRI 却仍画成圆——**有 IRI 却是圆的,+ 画面就在说谎**。这个缝隙只有真导入一次才撞得到,实测撞上过。++两件都不是这篇的主题,但判据是同一条:**来历要看得见**。+接新来源时值得一并想:这个来源带进来的东西,读者能不能一眼看出它是从哪来的。++## 待做:飞书 / Confluence / Notion++文档协作类是下一个该接的——它是 #122 那份维基历史快照语料的**企业版**:+同一份文档在不同时刻的版本,天然带版本号,不用采样也不用跟埋在 PR 里的事件较劲。+四条判据全中。++**飞书优先**(`feishu_docs`):中文用户的实际落点,而且它的 API 直接给文档版本。++三个已知的未知,接的人要先答:++1. **拿不到公开实例。** 飞书/Confluence/Notion 都要租户与凭据,所以做不到+ GitHub/Jira 那样的真实端到端。要么用测试租户,要么明说未经真实验证。+2. **富文本不是字符串。** 飞书文档是块结构(`docx` 的 block 树),+ Notion 是 block、Confluence Cloud 是 ADF——都需要一个"块树 → 纯文本"的渲染器。+ Jira Cloud 的 v3 也是同一个问题,本轮绕开了(走 v2)。+3. **"变更史"在这里是什么。** 工单的变更史是事件流;文档的变更史是**版本序列**,+ 更接近 #122 那份语料的做法——可能要按"变了多少"采样,而不是每个版本都取。++已开 [issue #136](https://github.com/deeplethe/utopia/issues/136) 请人认领——那里写清了骨架、三条硬要求与验收标准。diff --git a/docs/decisions/README.md b/docs/decisions/README.mdindex 1fea19e9..7a0b4cbc 100644--- a/docs/decisions/README.md+++ b/docs/decisions/README.md@@ -34,6 +34,7 @@| 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 工单)· **文档协作类待做** |## 不是决策记录的那些