让 Agent 编辑表格,听上去像是一整套 AI 工程的标配动作:先接一个 AI SDK,再挂上大模型,写好工具编排,最后才轮到碰单元格。可 dream-num/univer 这套开源 Office SDK 给出的答案恰好反过来。仓库地址见 dream-num/univer,明文地址是 https://github.com/dream-num/univer 。它把工作簿、工作表与区间封成一套 Facade API,应用或 Agent 可以直接改单元格,公式自动重算,结果还能存成 JSON 快照,而整条链路不依赖 AI SDK。模型与工具编排由你自己的应用提供,SDK 只负责把 Office 能力摆进你的产品里。这是本篇想拆开讲清楚的反差:让 Agent 编辑表格这件事,难点从来不在 AI SDK,而在有没有一套足够稳的 Office 底座。
截至 2026 年 11 月 15 日,按 GitHub API 的累计总量读,这个仓库的 stargazers_count 是 25192,forks_count 是 2307,主语言是 TypeScript,默认分支是 dev,created_at 落在 2022-09-29,仓库状态是 public,license.spdx_id 是 Apache-2.0。这里有两处口径要特意点明。其一,星数是累计总量,按 stargazers_count 字段读,与单日变化无关。其二,GitHub API 里的 pushed_at 字段是 2026-11-15,那是核对这些字段时的抓取时点,并不是项目的发布日。上面每个数字都能在仓库页面与 API 上直接核到。本篇只核仓库 README、LICENSE 与 GitHub API 可核内容,不替官方补定价、不替官方补性能跑分,也不把别处的媒体转述当成一手事实。
先厘清它到底是什么。Univer 是一套给自己产品里嵌 Office 能力的 SDK,不是装给终端用户、点开就能写文档的办公软件。英文 README 的原话是,Univer is an Office SDK for building Office applications inside your own product,它把编辑、计算、协作与文件处理提供给 people and existing agents,用的还是你自己的数据与权限。仓库 description 说得更直白:Build your own AI office with Univer Office SDK,把编辑、计算、协作、文件处理带进你的产品,给人和 AI agents 用,底座是 an extensible open-source core。换句话说,你要建的是「你的 Office」,Univer 交到你手上的,是那套能嵌进去的零件。分清楚这一点,后面讨论 Agent 怎么改表才不会跑偏:调用方是你的应用,不是某个替你托管好的成品服务。
把底层能力封成对象的一层 Facade API
Facade API 是这套设计的入口。中文 README 的定义很干脆:Facade API 是面向应用的工作簿、工作表和范围接口;它把底层能力封装为 FWorkbook、FWorksheet 和 FRange 等面向应用的对象。英文版本写着 Facade APIs are the application-facing interface to workbooks, worksheets, and ranges。为什么非得多这一层?因为内容模型、编辑、渲染、公式计算这些地基能力本身并不适合直接摊给业务代码看,它们细碎、耦合、动一处牵一片。Facade API 把它们整理成应用一眼能懂的对象:一个 FWorkbook 对应一份工作簿,一个 FWorksheet 对应其中一张表,一个 FRange 对应一片区间,getRange 用来取到这片区间,setValues 把一组值写进去,createWorkbook 则从一份快照里造回整份工作簿。业务代码不必知道渲染怎么刷、公式引擎怎么调度,只要面对这几个对象就够了。
再往下看地基。英文 README 写 Web SDK is the foundation,它承载 content models、editing、rendering、formula calculation,以及 Facade APIs 这批 application-facing APIs;Presets compose plugins and register their Facade APIs,也就是由预设把插件组合起来、把对应的 Facade API 注册到位。这个细节解释了一件容易被忽略的事:Agent 走的不是一条外挂捷径,它和编辑器、和你的应用共用同一套 Facade API。章节名 Connect applications and agents through Facade APIs and events 说的正是这件事,应用与 Agent 借 Facade API 和事件,接到同一份工作簿上。也正因如此,编辑权限、数据归属、协作状态这些本来就归你的应用管的事,不会因为多了一个 Agent 调用方就换一套规则。
开源核心能做什么,README 的能力表逐条列得很细,这些是官方自述能力,不是第三方实测。Docs 一侧写的是 Rich-text editing、paragraph formatting、lists、hyperlinks、comments,以及 drawing integration;Sheets 一侧在 Editing and layout 条目下列出 Cell styles、merged cells、in-cell rich text、freeze panes、floating images 和 undo/redo。把这些摊开看,单元格样式、合并单元格、单元格内富文本、冻结窗格、浮动图片、撤销重做,都是冲着真实表格编辑场景去的,而不是一个只够跑演示的玩具内核。docs 首页那句 AI 与自动化 LLM 与 Agent 可直接调用 Facade API,实现文档的自动化读写与分析,正好点出这批能力对自动化的意义:能被人手点出来的编辑动作,同样能被程序稳定地复现。
Agent 编辑表格,却不依赖 AI SDK
标题里的反差到这里才真正落地:让 Agent 编辑表格,不需要额外买一套 AI SDK。README 给的示例极其克制,一行 getRange('A1:D4').setValues([...]) 就往一片区间里写值,另一行 sheet.getRange('B2').setValue(4) 把单个单元格改成 4,中间还配了一句注释 // An application control or agent can make the same edit. 应用控件也好,Agent 也好,做的是同一次编辑,没有两套接口,也没有一层专门的 AI 通道。把示例单独摆出来看会更清楚:
sheet.getRange('A1:D4').setValues([...])
// An application control or agent can make the same edit.
sheet.getRange('B2').setValue(4)官方接着把关键前提写在后面:The editor and your application operate on the same workbook; formula changes are recalculated automatically. 编辑器与你的应用操作的是同一份工作簿,公式改动会自动重算。这句话的分量不小:Agent 改完 B2,凡是依赖它的公式都不用你手动刷新,计算引擎自己会跟上,屏幕上的人、后台里的逻辑、跑着的 Agent 看到的是同一个结果。省掉的不只是一段同步代码,更是一整类改完值还得记着刷新的隐患。
那 Agent 的智能从哪来?README 把边界划得很清楚:Agents can use the same open-source APIs; your application supplies the model and tool orchestration. Agent 复用的是同一批开源 API,模型与工具编排由你的应用自己出。SDK 不内置大模型,也不自带 Agent 编排框架;它只保证无论调用方是人、是应用逻辑、还是 Agent,落到工作簿上的都是同一套 Facade API。紧接着那句结论把题眼说透:The quotation example demonstrates editing, calculation, and saving without an AI SDK dependency. 那份报价表示例把编辑、计算、保存都走通了,全程 without an AI SDK dependency,也就是不依赖 AI SDK。这正是 Univer 开源 Office SDK 让 Agent 编辑表格的特别之处,它把 AI 留在你的应用侧,把 Office 稳稳放在库里,两边各司其职,谁也不用替谁打包。
workbook.save() 存的是 JSON 快照,不是 XLSX
另一个高频误读落在保存上。workbook.save() 返回的不是 XLSX 文件,而是一份 JSON 快照。英文 README 写得很准:workbook.save() returns a JSON snapshot containing the workbook and its registered plugin data. Your application owns persistence; this example uses browser storage. 中文版本是 workbook.save() 返回包含工作簿及已注册插件数据的 JSON 快照,持久化由你的应用负责。也就是说,快照里装的是工作簿本身加上已注册插件的数据,而这份快照往哪存、怎么存、存多久,是你的应用说了算。示例里那句 localStorage.setItem('quotation', JSON.stringify(workbook.save())) 只是拿浏览器存储做个演示,不代表 localStorage 是官方钦定的持久化方案。恢复时反过来走:
localStorage.setItem('quotation', JSON.stringify(workbook.save()))
if (saved) { univerAPI.createWorkbook(JSON.parse(saved)) }用 createWorkbook 把 JSON 快照重新造回工作簿,一存一取,闭环就在你的应用手里,SDK 不替你决定存储后端。
务必把这条链路和 XLSX 导入导出分开。README 明写 This workflow uses only open-source packages. Snapshot persistence is separate from XLSX import and export, which uses the separately distributed file-conversion capabilities. 快照持久化走的是开源包,XLSX 的导入与导出则依赖单独分发的文件转换能力,两者不是一回事。把 workbook.save() 当成导出 Excel,或者以为这套开源核心自带完整的 XLSX 读写,都会把开源边界读歪。它给的是工作簿状态的一份 JSON 快照,加上把快照造回工作簿的 createWorkbook;至于文件格式的转换,留在另一条分发线里。分清这两件事,才不会在选型时误以为拿到开源核心就等于拿到全套文件兼容。
这套快照能力也不只跑在浏览器里。官方文档对 Node.js 的描述是 In Node.js, you can create or load workbooks, read and write cells and formatting, change rows and columns, calculate formulas, and save Univer snapshots. 创建或加载工作簿、读写单元格与格式、改行列、算公式、保存 Univer 快照,都能在服务端完成。对想在后台批处理表格、再由应用自己接模型与编排的场景来说,这条 Node.js 路径和前面的浏览器示例是同一套 Facade API 逻辑,只是运行位置不同。前端有界面也好,服务端无界面也好,getRange、setValues、workbook.save()、createWorkbook 这一组动作的含义保持一致:改的是同一份工作簿,存的是同一种 JSON 快照。
开源边界:Apache-2.0 只覆盖到这里
最该逐字读的是许可边界。英文 README 的原句是:This repository provides the Web SDK's core architecture and engine implementations under Apache-2.0:content models and snapshot formats、plugin and dependency management、the command system、formula and rendering engines、Facade APIs、UI foundation,以及 Sheets and Docs editing capabilities。中文版本对应:本仓库以 Apache-2.0 许可证提供 Web SDK 的核心架构和引擎实现,商业 Web SDK 插件、Server SDK 和商业 AI SDK 扩展单独分发和授权。注意这句话是带范围的,Apache-2.0 覆盖的是 Web SDK 的核心架构与引擎实现,从内容模型、快照格式,到插件与依赖管理、命令系统、公式与渲染引擎、Facade API、界面基础,再到 Sheets 与 Docs 的编辑能力,都在这份授权里;它不是一句仓库里所有东西随便拿的许诺。
紧接着那句把另一半说全:Commercial Web SDK plugins, Server SDK, and commercial AI SDK extensions are distributed and licensed separately. 商业 Web SDK 插件、Server SDK、商业 AI SDK 扩展,都是单独分发、单独授权。中文 README 许可节也写明 Copyright (c) 2021-present DreamNum Co., Ltd. 本仓库的开源包采用 Apache-2.0 许可证,商业 SDK 模块单独分发和授权,还提到 Freemium 评估包含水印和功能限制,把商业模块的评估方式一并交代了。于是贴近原文的理解是:Apache-2.0 授予的是 Web SDK 核心架构与引擎实现,商业 Web SDK 插件、Server SDK 与商业 AI SDK 扩展在授权清单之外,走另一条分发与授权线。把示例里的 localStorage 当成官方持久化方案、把 JSON 快照当成 XLSX、把商业插件算进 Apache-2.0,都是抹平这条边界之后才会冒出来的错读。
本篇只按 LICENSE 与 README 逐字呈现这条边界,不替官方补定价、性能或竞品对照,也不把 README 自述能力写成第三方实测。整套链路里,模型与工具编排始终待在应用侧,库本身不依赖 AI SDK;这一点和商业模块单独授权是两件事,别互相套用。开源的是核心,扩展的是商业线,应用自己管智能,几条线各归各,读清楚了才好用。
把边界读准之后,许多看似矛盾的说法就顺了。有人看到仓库挂着 Apache-2.0,便以为凡是 Univer 字样的能力都随手可用;也有人看到商业模块单独授权,便反过来把整座仓库都划到授权之外。两种读法都跳过了那句逐字限定的范围:开源的是 Web SDK 核心架构与引擎,商业线是另外分发的插件、Server SDK 与 AI SDK 扩展。应用侧要接模型、要写工具编排,那是你自己的工程,和库是否开源无关;库侧要不要 XLSX 转换,那是另一条分发线的事,也和 Agent 能不能改单元格无关。把这三层分开,开源核心能做什么、不能替你做什么,就都不必猜了。
把四层摞起来看,这套 Univer 开源 Office SDK 的定位就清楚了:25192 颗累计星背后,不是又一个聊天式办公玩具,而是一套把编辑、计算、协作、文件处理塞进你自己产品的零件;Facade API 把 FWorkbook、FWorksheet、FRange 摆到应用面前,getRange 与 setValues 让 Agent 编辑表格像改一个变量一样直接;workbook.save() 用 JSON 快照交接状态,createWorkbook 把它造回来;而 Apache-2.0 的边界停在 Web SDK 核心与引擎,商业 Web SDK 插件、Server SDK 与商业 AI SDK 扩展另算。本篇讲的是这个 SDK 项目本身,和站内那两篇讲用 AI 做表格操作流程的 ai-spreadsheet-sop、ai-agent-office-automation-sop 不是一个角度;agent-runtime-sdk-comparison-review 那篇是运行时横评,也不在本文射程里。
常见问题
Q1:让 Agent 编辑表格,必须先接一套 AI SDK 吗? A1:不需要。README 明写 Agents can use the same open-source APIs,Agent 复用应用与编辑器共用的那套 Facade API,getRange、setValues 直接就能改单元格;模型与工具编排由你的应用提供,报价表示例全程不依赖 AI SDK。
Q2:workbook.save() 导出的就是 XLSX 文件吗? A2:不是。workbook.save() 返回的是包含工作簿及已注册插件数据的 JSON 快照,持久化由你的应用负责,示例只是用 localStorage 演示。XLSX 导入导出依赖单独分发的文件转换能力,与快照持久化分离,createWorkbook 负责把快照造回工作簿。
Q3:仓库里所有功能都在 Apache-2.0 之下吗? A3:不是。Apache-2.0 覆盖 Web SDK 的核心架构与引擎实现;商业 Web SDK 插件、Server SDK 与商业 AI SDK 扩展单独分发、单独授权,中文许可节还提到 Freemium 评估含水印与功能限制。
Q4:Agent 改完单元格,公式会自己重算吗? A4:会。编辑器与你的应用操作同一份工作簿,formula changes are recalculated automatically,改完值不必手动刷新,计算引擎会跟进。
Q5:25192 是某一天涨出来的星吗? A5:不是。截至 2026 年 11 月 15 日,这是按 GitHub API 读到的累计总量 stargazers_count,不是单日增量;API 里的 pushed_at 是 2026-11-15,属于抓取字段的时点,不是项目发布日。
延伸阅读
- ai-spreadsheet-sop:用 AI 处理表格的操作流程。
- ai-agent-office-automation-sop:Agent 办公自动化的落地步骤。
- agent-runtime-sdk-comparison-review:运行时 SDK 的横向对照。
- invoice-ocr-to-excel-sop:发票识别到 Excel 的流程。
- officecli-resource:命令行侧 Office 工具资源。