像Pull Request一样评审文档:Oxynote草稿分支与审批合并机制完全指南
像Pull Request一样评审文档:Oxynote草稿分支与审批合并机制完全指南
Oxynote 是一款开源自托管技术 Wiki,最大特色是让文档页面里的实时指标图表与日志、和文字说明一样走"草稿分支 → Diff 对比 → 审批 → 合并"的评审流程,像管理 Pull Request 一样管理文档。本文将带你完整走一遍 Oxynote 的草稿分支(draft)与审批合并机制:如何开启评审模式、如何在 draft 分支上编辑、如何用块级 Diff 审查变更、如何邀请评审人批准,以及最后一步"合并草稿到 main"。
为什么文档也需要"代码式"评审?
传统 Wiki(如 Notion)最大的问题是:文档和它所描述的系统逐渐脱节。图表加了新 label、接口改了参数、阈值调了数字,但文档还是老样子,而且没有任何人审查过这些改动。
Oxynote 的解法是直接把软件工程里最成熟的模式搬过来:
- 页面可以挂载 Live Metrics(Prometheus/SQL 查询)和 Live Logs(Loki 查询),说明文字就写在图表旁边;
- 一旦开启评审,main 分支锁定为只读,所有修改必须先进入 draft 草稿分支;
- 评审人在页面上直接看块级 Diff(文字、API 参数、图表阈值都能高亮对比);
- 批准(Approve)和合并(Merge)是两个独立步骤,批准后的草稿可以等到对应功能真正上线再合并。
项目 README 中对这个设计的描述很直白:
一个草稿会带着"图表块 + 文字"的同一份修改,走同一条评审流程(one draft carries a change to the block and its text through the same review)。
快速上手:五步走完 Oxynote 文档评审全流程
整个机制没有任何额外配置,全部在编辑器顶栏完成。下面按实际操作顺序拆解。
第一步:一键开启"可评审"模式
打开任意页面,点击右上角的文档选项菜单,选择 Make Reviewable。
这一步会在服务端完成一次"分支分叉"(fork):
- 自动创建
draft分支,并把当前内容完整复制进去; - 给
main分支打上保护标记(Protected),此后 main 拒绝一切直接编辑; - 编辑器顶栏出现分支切换器,显示
main/draft两个选项。
对应的服务端逻辑在 server/core/internal/document/document.go 的 Fork 函数中——新建分支继承源分支内容,但永远不会是保护分支或默认分支。
第二步:切换到 draft 分支编辑
在分支切换器中选择 draft,编辑器变为可写状态;切回 main 则整页只读(包括标题和正文),只读开关在 main 上会被禁用,悬浮提示会解释"该分支受保护"。
几个值得注意的细节(均由 e2e/tests/review.test.ts 端到端测试覆盖):
- 草稿改动不会污染 main:在 draft 上输入的文字,切回 main 时不可见,直到合并;
- 块级链接自带分支:在 draft 上复制某个块的链接,URL 会带上
?branch=<草稿ID>参数,对方点开直接进入草稿分支并滚动定位到该块; - 合并后自动回到 main:合并动作完成后,分支切换器自动切回 main 分支。
第三步:用"Show Changes"审查块级 Diff
这是 Oxynote 评审体验的核心。在 draft 分支上打开顶部的 Show Changes 开关,页面立即切换为合并式 Diff 视图:
- 新增文字标绿、删除文字标红,精确到单词级别;
- 不只纯文本:API 文档块的参数名、路径参数、JSON 响应字段、Live Metrics 块的阈值与单位变化,都会原地高亮;
- 标题(页面名)的修改同样纳入 Diff。
因为 diff 是基于**块(block)**而不是纯文本行,所以即使你把某个 API 参数改名、把某条告警阈值从 300ms 调到 250ms,评审人也能立刻在正确的位置看到"改了什么、为什么改"。这正是代码 Diff 给文档带来的能力。
第四步:邀请评审人与批准(Approve)
点击页面标题旁的 Reviewers 图标,弹出评审人面板,其中分三类人:
| 状态 | 含义 |
|---|---|
| Invited | 已发出评审请求,等待对方查看 |
| Approved by | 已批准当前草稿的人 |
| Maintainers | 页面维护者 |
操作流程:
- 点击 Invite to review,从工作区成员中选择评审人;
- 评审请求会推送到对方的 Inbox(收件箱),一键直达对应草稿块;
- 评审人在 draft 分支上点击 Approve Draft 完成批准,之后可随时 Unapprove 撤回;
- 批准状态通过 WebSocket 实时同步给页面所有者,无需刷新。
批准记录保存在数据库的 branch_reviewers 表中(字段 currently_approved / previously_approved),读写逻辑见 server/core/internal/db/document_reviewers.go。前端批准/撤回/合并三个动作的交互代码集中在 web/app/components/editor/NameEditor.vue。
第五步:合并草稿到 main(Merge Draft into Main)
批准并不等于生效。草稿区有一个 Merge Draft into Main 按钮,点击后才真正执行合并:
- 草稿内容整体写回 main 分支,
LastUpdatedBy记录为执行合并的人; - 草稿分支上的评审批准记录会晋升到 main(
previously_approved),作为"这份内容曾经被谁审过"的历史凭证; - 草稿分支随即被删除,页面自动切回 main。
服务端合并的核心是 server/core/internal/document/document.go 中的 MergeBranch 方法;而 main 分支的写保护由 server/core/internal/document/branch.go 的 ErrBranchProtected 错误强制兜底——受保护分支的任何直接变更都会返回 403。
💡 为什么批准和合并要拆开? 这是 Oxynote 面向运维场景的刻意设计:文档描述的往往是"即将上线"的变更。先批准(Approve)表示"方案没问题",等对应的代码变更真正上线后,再执行合并(Merge),让 Wiki 与生产环境严格同步。
分支模型在数据层是怎么实现的?
如果你好奇底层,Oxynote 的分支就是 document_branches 表中的一行记录,每个分支独立保存自己的标题、图标、Yjs 协同内容(content)与保护标记。关键设计:
- 保护(protected):合并或系统级操作(
System标记的更新)可以写入保护分支,普通编辑不行,见ApplyUpdate中的判断(document.go); - 默认分支(default):即 main,永不允许重命名、删除,也不能自合并;
- 搜索索引:每个分支的块都会被索引,所以草稿中的新内容同样可被
⌘K全文搜索到,只是带着分支标识。
相关实现可对照阅读:
- 分支 CRUD 与查询:server/core/internal/db/document_branchers.go
- 分支规则与错误定义:server/core/internal/document/branch.go
- 评审全流程端到端测试(锁分支、Diff、批准、合并、邀请、块链接):e2e/tests/review.test.ts
- 分支切换、Diff 开关、合并等操作助手:e2e/helpers/review.ts
关闭评审模式:回到单一可编辑分支
如果某页不再需要管控,可在文档选项中选 Make Non Reviewable。注意确认弹窗的提示:这会丢弃草稿分支及其全部改动,且不可撤销。执行后分支切换器消失,页面恢复为单分支、直接可编辑状态。
常见问题(FAQ)
Q:单人使用 Oxynote 也需要评审流程吗? 不强制。评审是"按页面"开启的,你可以只对 On-Call 手册、API 文档等关键页面开启 Make Reviewable,其余页面照常自由编辑。
Q:AI Agent 的修改也要走评审吗? 是的。通过 MCP 接入的 Agent(如 Claude Code)在可评审页面上的编辑同样进入 draft 分支,等待真人批准,机制与人类编辑完全一致。
Q:合并前草稿被继续修改了怎么办?
批准是针对"当前草稿版本"的。如果评审后有人继续改动草稿,建议让评审人重新确认并再次 Approve——数据层保留了 previously_approved 字段用于追溯历史批准。
总结
Oxynote 用一套极简的双分支模型(main + draft),把 Git 世界里验证了二十年的评审哲学带进了 Wiki:
| 概念 | 代码世界 | Oxynote 文档世界 |
|---|---|---|
| 保护分支 | main 禁止直推 |
main 锁定只读 |
| 特性分支 | feature/xxx |
draft 草稿分支 |
| Diff 审查 | 行级 Diff | 块级 Diff(文字/参数/图表阈值) |
| Code Review | Approve / Request Changes | Approve Draft + 收件箱评审请求 |
| Merge | 合并到 main | Merge Draft into Main(可延迟到上线后) |
对于需要维护架构图、API 参考、On-Call 手册的自托管团队来说,这套机制的价值在于:每一次文档变更都自带 Diff、自带审批人姓名,文档从此和你描述的线上系统一样"可信"。

