# 历史记录
> 回看历史版本、定位内容变化，并将选定版本恢复到当前共享文档。
- Human documentation: [https://docs.univer.ai/zh-CN/overview/features/shared/history](https://docs.univer.ai/zh-CN/overview/features/shared/history)
- Agent Markdown: [https://docs.univer.ai/zh-CN/overview/features/shared/history.md](https://docs.univer.ai/zh-CN/overview/features/shared/history.md)
- Requested language: `zh-CN`
- Content language: `zh-CN`
- Documentation version: `1.3.0`
- Source: [features/shared/history.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/history.zh-CN.mdx)
---
历史记录将已经协同确认的修改组织成可浏览的版本。开发者和用户可以沿时间线查看修改者、时间与操作，打开历史内容，检查变化，并在有权限时恢复版本。刷新页面后仍可追溯，不受当前编辑会话限制。
## 历史记录的原理
- **Mutation**：一条可重放的内容变更，例如修改单元格或插入段落。
- **Changeset**：按顺序封装一组 Mutation 的一次协同提交。
### 1. 记录变更
**编辑提交时发生。** 用户或 Agent 产生的内容变更，以 Mutation 的形式封装进 Changeset，提交给协同服务确认并保存。
```mermaid
flowchart LR
A["编辑内容"]
B["Mutation"]
C["Changeset"]
D["协同确认并保存
记录 revision"]
A --> B
B --> C
C --> D
```
**Revision（修订号）** 标识已确认提交在文档历史中的位置。History 基于已确认的 Changeset 建立索引，并按时间和操作分组，组织成版本时间线。
### 2. 重建历史内容
**选择历史版本时发生。** Snapshot（快照）是某个 revision 的完整内容状态。系统读取基准 Snapshot，以及此后直到目标 revision 的 Changeset，按顺序重放其中的 Mutation，生成只读历史视图。
```mermaid
flowchart LR
A["选择版本
revision N"]
B["读取 Snapshot
及后续 Changeset"]
C["顺序重放
Mutation"]
D["显示历史内容
只读视图"]
A --> B
B --> C
C --> D
```
例如：**revision 10 的 Snapshot + revision 11～15 的 Changeset = revision 15 的内容。**
### 3. 恢复为当前版本
**点击“恢复此版本”时发生。**
> 选定目标版本 → 提交恢复 Mutation → 协同确认 → 更新当前文档，产生新 revision
恢复操作本身也会形成新的历史记录，原有版本继续保留。
## 查看版本与变更
1. 从编辑器的**历史记录**入口打开时间线，选择要查看的版本。
2. 展开版本分组，查看其中更细的修改记录；选择记录后，在只读查看器中查看对应内容与差异。
3. 需要回退时，选择**恢复此版本**。恢复通过协同修改当前共享文档，其他参与者也会收到更新。
时间线可以将一段时间内的修改合并为一个版本分组，展开后再查看具体 revision。**历史条目不等于每次按键，也不等于每次生成 Snapshot。**
### 三种颜色如何阅读
| 标记 | 含义 | 示例 |
| --- | --- | --- |
| 🟦 **蓝色：修改** | 已有内容发生变化。 | 修改数值、段落格式或对象属性。 |
| 🟩 **绿色：新增** | 这一版本中加入的内容。 | 新增行、段落、记录或画布对象。 |
| 🟥 **红色：删除** | 这一版本中移除的内容。 | 删除的文字或对象在历史视图中保留标记，便于追溯。 |
颜色表示**变更类型**。文字替换可能同时展示新增与删除；具体高亮范围由各产品的历史查看器确定。
## 五个产品的历史视图
以下使用同一组 Northstar 英文项目示例，展开时间线，展示各产品中的内容与操作记录。
### 电子表格（Sheet）
在 Launch Budget 中回看预算与预测值的调整，以及行的新增和删除。结合工作表内容和右侧操作记录，可以定位一次调整影响的区域。
[接入 Sheets 历史记录](https://docs.univer.ai/zh-CN/guides/sheets/features/edit-history.md)
### 文档（Doc）
在 Product Launch Brief 中检查发布日期、段落格式与新增的客户准备事项。历史视图保留删除文字的红色删除线，方便把调整前后的表述放在上下文中阅读。
[接入 Docs 历史记录](https://docs.univer.ai/zh-CN/guides/docs/features/edit-history.md)
### 演示文稿（Slide）
在 Launch Review 中追溯目标数值和页面对象的变化。选中历史记录后，直接在幻灯片中查看更新、新增与移除的对象。
[接入 Slides 历史记录](https://docs.univer.ai/zh-CN/guides/slides/features/edit-history.md)
### 关系型表格（Relational Table）
在 Launch Tracker 中回看任务、负责人和状态的调整。记录与字段的变化结合表格视图呈现，适合检查业务数据何时、如何发生变化。
[接入 Relational Table 历史记录](https://docs.univer.ai/zh-CN/guides/bases/features/edit-history.md)
### 画布（Canvases）
在 Release Workspace 中回看规划卡片与对象属性的变化。新增、删除和修改的标记保留在画布上下文中，帮助理解一次规划调整。
[接入 Canvases 历史记录](https://docs.univer.ai/zh-CN/guides/boards/features/edit-history.md)
### PDF
**Coming soon**：PDF 历史记录尚未提供。
## 在应用中接入
历史记录由 Server SDK 的 History 扩展与 Web SDK 的产品历史插件共同提供：
- **服务端**：在核心协同之上接入 History Service、Endpoint 与持久化 Database Adapter。服务订阅 Unit 创建和 changeset 提交事件，建立历史索引，并提供版本列表与修改查询。
- **浏览器**：注册通用历史能力及对应产品的 History / History UI 插件，连接历史接口。查看器加载选定 revision 的内容并呈现差异；自定义内容需按产品接入相应查看器插件。
- **权限**：应用负责身份与授权，服务端检查历史读取与恢复权限。历史版本可能包含当前文档已经删除的数据。
从[协同扩展模块](https://docs.univer.ai/zh-CN/server/collaboration/extensions.md)了解模块关系，按 [History 示例](https://docs.univer.ai/zh-CN/server/collaboration/examples.md#history)组装服务，再使用上面的产品指南接入界面。
历史索引是可重建的派生数据，**已确认的 changeset 仍是内容的权威来源**。持久化与保留策略由应用配置；历史面板不能替代备份。
## 与撤销、比较和 Worktree 的关系
| 能力 | 解决什么问题 |
| --- | --- |
| 撤销 / 重做 | 在编辑过程中撤回或重做操作，不需要历史服务。 |
| 历史记录 | 跨会话追溯已确认的版本，查看变化并恢复共享内容。 |
| [内容比较](https://docs.univer.ai/zh-CN/overview/features/shared/compare.md) | 比较两份内容，得到可供界面或 Agent 使用的差异；只读比较本身不恢复内容。 |
| [Worktree](https://docs.univer.ai/zh-CN/overview/features/shared/worktree.md) | 隔离草稿修改，在审阅后决定是否合入共享内容。 |
Agent 通过 Facade API 产生的修改，在接入协同并获服务端确认后，也可进入同一条历史链路。应用可结合内容比较构建自动审阅与检查流程。
[返回功能总览](https://docs.univer.ai/zh-CN/overview/features.md)