Skip to content

World's first open-source enterprise world 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.md
new file mode 100644
index 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.md
index 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 工单)· **文档协作类待做** |
## 不是决策记录的那些