改错也不怕:Poznote 修订历史(Revisions)详解,3 类快照与一键回滚技巧
改错也不怕:Poznote 修订历史(Revisions)详解,3 类快照与一键回滚技巧
Poznote 是一款自带修订历史(Revisions)机制的笔记应用:它会自动为每篇笔记保存快照(Snapshot),支持两版内容逐行对比、一键回滚到任意旧版本。本文用一篇讲透 Poznote 修订历史的 3 类快照类型、保留规则与一键回滚技巧,帮你彻底告别"改坏了找不回来"的焦虑。
1. 如何打开 Poznote 修订历史页面
Poznote 的修订功能是一个独立页面(revisions.php),而不是弹窗——官方解释是:对比一篇长笔记的两个版本需要整个窗口,而且页面可以被链接、刷新后用返回键离开。
两条最常用的入口:
- 笔记工具栏的"历史"图标:打开任意笔记,点击工具栏上的历史(History)图标,即可进入该笔记的修订页面(对应源码 revisions.php)。
- 快捷键 Ctrl + Alt + S(Mac 为 Cmd + Alt + S):在笔记打开时按下,直接为当前状态存一份手动修订,界面会弹出"Revision saved"提示。快捷键实现见 keyboard-shortcuts.js。
页面打开后,左侧是按天分组的修订列表,右侧是内容查看与操作区(前端逻辑在 revisions-page.js 与差异对比模块 revisions-diff.js)。
2. Poznote 的 3 类快照(Snapshot)是什么
后端把所有版本统一称为快照,存储与 API 都保留 snapshot 这个名字(见 SnapshotsController.php),但界面上呈现为 3 种带明确标签的修订:
| 类型 | 界面标签 | 触发时机 | 数量限制 |
|---|---|---|---|
| 自动修订 | Automatic | 笔记的内容、标题或标签发生变化时保存,保存的是"变化前"的状态;同一篇笔记最多每 10 分钟一份 | 最近 24 小时全保留,之后每天留最新一份,默认保留 30 天 |
| 手动修订 | Saved by hand | 点"Save a revision"或按 Ctrl + Alt + S | 不限量,永不精简,仅 30 天后过期 |
| 保护性修订 | Before AI edit / Before MCP edit | AI 助手或 MCP 服务器改写笔记内容之前自动保存 | 每篇笔记默认保留最近 20 份 |
💡 一个典型例子:你从 9:00 编辑到 9:35,历史里会出现约 9:00(动手前的原样)、9:10、9:20、9:30 四份修订。下午 14:00 你回来改了一个词,就会生成一份 14:00 的修订,正好保留你上午 9:35 离开时的完整状态。
几个容易误解的细节(来自 snapshots.php 与控制器源码):
- 打开或阅读笔记从不产生修订,只有"保存变化"这一动作才会在变化前存一份。
- 空笔记、或最新修订与当前内容完全相同时会跳过保存,历史里不会出现重复版本。
- 保护性修订虽与自动修订共享 30 天过期,但不受 10 分钟间隔限制——哪怕 10 分钟前刚存过自动修订,AI 改写前也会强制再存一份,保证"一次糟糕的重写"永远离撤销只差一个点击。
3. 一键回滚:4 步找回旧版本 + 一个必看的坑
回滚操作步骤:
- 进入笔记的修订页面,在左侧历史列表中选中目标修订;
- 点击右上角 Actions 菜单,选择 "Restore this revision";
- 确认对话框提示后点击 Restore,笔记即恢复为该修订的内容 + 标题 + 标签;
- 恢复完成后,笔记的
updated时间戳会更新,操作记入操作者账户。
⚠️ 回滚前务必先"Save a revision":被替换掉的当前状态不会自动保存。如果当前版本还有价值,先点 Actions 里的"Save a revision"(或 Ctrl + Alt + S)再回滚——这是官方文档明确强调的唯一坑点。
另外两个恢复规则:
- 标题冲突自动加后缀:恢复的标题若与同文件夹内其他笔记重名,会自动追加"(1)"之类的后缀,与重命名规则一致;
- 旧修订可能不含标签:在标签版本化之前保存的修订不带标签信息,恢复时不会改动笔记当前标签。
4. 用 Changes 对比视图精确定位改动
修订页面除"Content"标签外,还有 Changes 标签,提供逐行差异(diff)视图,改动词会高亮显示:
- 对比对象可选:与当前版本、上一份修订、或任意一份修订对比;
- 两种布局:Unified(合并)与 Side by side(并排),不变动的行默认折叠,点击可展开;
- 导航与统计:可点击上一处/下一处改动在差异间跳转,并统计新增与删除的行数;
- 对比维度:Markdown 笔记按源码对比;富文本笔记按文本对比,纯格式变化不会显示。diff 视图顶部还会显示标题变化(旧 → 新)与标签的增删。
列表中的 "Current" 徽章标记与当前笔记完全一致(内容+标题+标签)的修订,"No change" 徽章则标记与上一份修订相同的条目,帮助你快速判断哪些版本值得看。
5. 保留策略、附件保护与相关配置
保留规则一览(常量定义在 functions.php):
- 自动修订:最近 24 小时全部保留,之后每天仅留最新一份,默认保留 30 天(可在 设置 → Revisions 中调整为 1~30 天);
- 手动修订:不限量,仅受 30 天过期限制;
- 保护性修订:每篇笔记保留最近 20 份(可调整为 1~200,适合 AI/MCP 频繁改写的实例);
- 所有修订无论类型,30 天后自动过期删除,也可在修订页面手动删除任意一份。
附件与图片的处理机制很巧妙:修订只保存文本、标题和标签,从不复制文件。从笔记里删掉的附件只要还有修订引用它,就会继续留在磁盘上(对笔记隐藏)——恢复那份修订时,图片自动"回来";最后一份引用它的修订过期或被删除后,文件才真正清除。所以多保留修订永远不会产生文件重复,只是让被删除的文件多留存最多 30 天。
延伸阅读:
- REST API 与 MCP 工具沿用 snapshot 命名:
/api/v1/notes/{id}/snapshots、get_snapshot、restore_snapshot,完整接口见 API-REST.md; - 快照生命周期核心逻辑:src/lib/snapshots.php、SnapshotsController.php;
- 快照过期与孤立附件清理:cleanup-orphan-snapshots.php。
总结
Poznote 的修订历史机制可以概括为一句话:变化前自动存档、AI 改写前强制存档、手动随时存档、30 天自动过期、一键恢复内容+标题+标签。养成两个习惯即可高枕无忧——大改之前按一次 Ctrl + Alt + S,回滚之前先存一份手动修订。


