.univer 多 Unit 文件完整揭秘:dsh-univer-office 如何把表格、文档、幻灯片和画布装进一个文件
.univer 多 Unit 文件完整揭秘:dsh-univer-office 如何把表格、文档、幻灯片和画布装进一个文件
dsh-univer-office 是 DeepSeek Harness(DSH)的 Univer Office 插件,它的核心载体是一种叫 .univer 的多 Unit 文件——表格(Sheet)、文档(Doc)、幻灯片(Slide)、多维表(Base)和画布(Board)都能装进同一个文件,还能通过跨 Unit 公式互相引用数据。本文带你完整揭秘这个多 Unit 文件的内部结构:它基于 SQLite 存储,带版本管理、隔离草稿和自动升级机制,让你一次看懂 Agent 办公文件的"底座"。
为什么是"多 Unit"一个文件?
用 Agent 办公时最头疼的问题是成果散落:数据在 Excel、说明在 Word、汇报在 PPT、关系在白板,改一处要来回打开四个文件。
.univer 文件给出的解法是"一个文件 = 一座迷你办公套件"。一个 .univer 文件里可以同时存在五种 Unit(内容单元):
| Unit | 类型编码 | 定位 | 代表能力 | 导入/导出 |
|---|---|---|---|---|
| Sheet | 2 | 电子表格 | 公式、条件格式、图表、数据验证 | .xlsx .csv .tsv |
| Doc | 1 | 文字文档 | 富文本、任务、页眉页脚、分页 | .docx |
| Slide | 3 | 演示文稿 | 页面、形状、动画、布局检查 | .pptx |
| Base | 5 | 轻量数据库 | 表、字段、视图、分组过滤 | 导出 .xlsx 等 |
| Board | 6 | 无限画布 | 图形、连接线、原生图表 | 仅打印 PDF |
类型编码并非随意设定,五种 Unit 的适配逻辑集中定义在 unit-types.ts 中——它给每种 Unit 提供默认空快照,Agent 创建文件时先在这里"选类型、发空壳"。
.univer 文件的真相:一个 SQLite 数据库
打开 .univer 文件你不会看到 XML 或 JSON——它本质上是一个 SQLite 数据库文件。这是刻意为之:
- 事务安全:一次写入要么全部成功、要么全部回滚;
- 版本化修改:每次改动以"变更集(changeset)"逐条记录;
- 多分支协作:worktree 分支机制直接建在同一份数据库里,天然支持多 Agent 隔离编辑。
数据库里藏着哪些表
从 univerfile-v2.sql 这份冻结的旧版结构可以看清核心设计:
| 表族 | 代表表 | 职责 |
|---|---|---|
| Unit 注册表 | collaboration_units |
登记五种 Unit 的 ID、类型、名称、当前头版本 |
| 快照表 | collaboration_snapshots |
按 unit_id + revision 存储完整内容快照 |
| 变更集表 | collaboration_changesets |
记录每一次增量修改,配合快照重建任意历史版本 |
| worktree 表族 | collaboration_worktrees 等 |
管理草稿分支的状态与分支内的 Unit 副本 |
| 资产表 | collaboration_assets |
以 SHA-256 内容寻址去重存储图片等二进制资源(单资源上限 50MB) |
格式版本:v0 → v3 自动升级
.univer 格式经历了多次演进,当前版本是 v3(core v2 + worktree v3 + assets v1 + history v2)。好消息是:你不需要手动迁移——
- 打开旧文件时,插件会读取内部
collaboration_schema_versions表识别版本; - 在临时副本上执行迁移与校验;
- 校验通过才替换原文件,旁边保留备份;失败则原文件纹丝不动。
整个识别逻辑(包括逐张表、逐列的完整性校验)写在 detect.ts,升级流程的入口在 univerfile-sqlite/index.ts。
跨 Unit 公式:一个 .univer 文件的灵魂
多 Unit 文件真正的威力,是一个 Unit 的公式可以直接引用同一文件里另一个 Unit 的数据。支持两种消费方:
- Sheet 单元格——公式结果直接显示在格子里;
- 公式驱动 Shape——Sheet、Doc、Slide、Board 中任何由公式驱动的图形,文字随源数据自动更新。
参考写法很直观:
=SUM('[Orders]Sheet1'!B2:B10)
公式按 Unit 名称寻址,底层元数据则保留稳定 ID——改名、移动 Unit 后引用关系依然可靠;源数据一变,所有引用处自动重算。典型用法:销售数据放 Sheet,汇报放 Slide,Slide 上的图表直接读 Sheet 的区间。完整工作流(含引用构建、重算订阅、结果校验)见 SKILL.md。
worktree:草稿隔离机制让 Agent 改坏不了你的文件
Agent 每一次写入都先在隔离的草稿分支(worktree)中进行,不会碰你的正式版本:
- Agent 修改 → 生成 draft 草稿;
- 你在实时预览窗口(可拖动、缩放、折叠)中随时观察;
- 满意 → 合入当前版本;不满意 → 丢弃草稿,正式版本毫发无损。
而且合入与丢弃必须由用户明确要求,Agent 无法自作主张。
状态流转(draft → ready → merged / discarded)由数据库中的 worktree 表族管理,分支间的语义差异还能通过 Compare 模式与主线并排对比。
实战:3 个把"多 Unit"玩明白的姿势
- 报表一体:"创建销售数据 Sheet 和总结 Slide 放在同一个 .univer 文件里,Slide 图表直接读 Sheet 数据"——改数据,图表自动更新;
- 导入续编:把现成的
.xlsx、.docx、.pptx导入.univer继续编辑,完成后按需导出回对应格式(Base 支持导出.xlsx/.csv/.tsv); - 安全试验:任何大胆的重构都丢进 worktree,效果不好一键丢弃。
常见误区与注意事项
⚠️
.univer是二进制数据库——别用文本编辑器打开,也建议不要手动改库。⚠️ 跨 Unit 公式依赖 Unit 名称——重命名 Unit 后引用可能需要重建,建议通过插件工具操作而非手工改。
⚠️ Board 画布暂不支持文件导出——五种 Unit 中其余四种都能导出对应 Office 格式。
⚠️ 截图与 PDF 打印依赖本地浏览器——Chrome/Chromium、Edge 会被自动检测,也可用
browserExecutablePath显式指定。
小结
.univer 多 Unit 文件 = 一个带版本管理的单文件办公容器:
- 五种 Unit 共享一份 SQLite 底座,快照 + 变更集撑起版本历史;
- worktree 分支隔离草稿,审阅卡片里合入或丢弃,随时反悔;
- 跨 Unit 公式把分散的内容连成一个整体,一处改动处处更新。
理解了这个结构,你就能更好地指挥 Agent 管理你的办公资产——从"五个零散文件"进化到"一个会自我组织的 .univer"。
延伸资料
- 持久化实现:univerfile-sqlite/
- 版本自动升级:migration/
- 跨 Unit 公式工作流:SKILL.md
- 插件架构文档:architecture.md
- Unit 类型适配:unit-types.ts


