Notarium文档
文档版本: latest

版本历史

每篇笔记都维护着自己的修订日志——记录它经历过的所有状态。这是应用层的版本化,而不是在文件夹之上套一层 git:日志存放在元数据库(metadata DB)里,累积那些流经 Notarium 或被文件同步捕捉到的状态。而 .md 文件本身始终是事实来源——日志是对它的补充,而非替代。

修订就是快照

每条修订都保存笔记在编辑那一刻的完整状态:标题、标签、slug 和规范化后的正文——而不是逐行 diff。用于比对版本的 diff 是即时算出来的,因为它们都能从快照中还原。

修订的正文按内容寻址(content-addressed,sha-256),因此相同的内容只存一份。还原某个版本、智能体反复编辑的循环、以及重复出现的状态都不会产生多余副本——去重依据的是内容本身。

日志以笔记的内部标识符(notarium-id)为键,而不是文件路径。所以历史能在文件夹之间移动和重命名后依然存续:它仍然是同一篇笔记,带着同一份历史。

溯源:谁改的,怎么改的

每条修订都带有签名——能看出改动从何而来。一条修订有其种类和一位创作主体:

修订种类含义
write通过 Notarium 保存(人类或智能体)
external文件同步直接在磁盘上捕捉到的状态
restore回滚到过往版本(保留指向来源的引用)
delete墓碑:已删除笔记的最后状态

作者会被记录为某个具体用户、智能体的个人令牌,或界面本身;外部编辑没有作者——没有谁可供签名。于是历史里就能清楚看出哪些是人类改的、哪些是 AI 智能体做的。关于区分人类与智能体编辑的更多内容,参见 人类与智能体

外部编辑的粒度

直接在文件里(绕过 Notarium)做的编辑,日志只能以一个同步周期的精度看到:两次轮询之间的多次改动会被折叠成单个被观测到的状态。而通过 Notarium 本身做的编辑则会被精确记录。

修订还携带新增和删除字符的计数——相对上一版本这次编辑的“代价”。

查看、比对与还原

笔记的历史可从阅读模式进入——侧边栏中的 History 标签页展示版本时间线:谁做了编辑、+N −M 计数以及日期。选中某条修订会将它替换当前正文显示,并可在 Changes(逐词 diff,高亮插入与删除)和 Content(内容本身)之间切换。

History 标签页:带作者与计数的修订;v3 由智能体写入

要回滚,使用 Restore this version 按钮。还原会从日志中取出正文,并通过乐观版本校验将其写为一次新的编辑:如果笔记在此期间被改动过,你会收到冲突(409),不会有任何内容被悄然覆盖。

存储与删除

默认情况下历史会完整保留——Notarium 不会自动精简修订。你可以手动彻底抹除一篇笔记的历史,将其从回收站中清除:删除笔记会创建一个带有最后状态的墓碑(仍可还原),而最终清除会连历史一并抹掉。

日志的边界

版本历史需要元数据库。没有元数据库,历史只在进程运行期间存在。不存在按计划自动精简旧修订的机制——我们完整保留历史。

相关主题:文件优先 —— 文件作为事实来源,回收站 —— 删除与还原,访问模型 —— 谁可以回滚版本。