Univer 实测:不开浏览器也能算 Excel 公式,Agent 写表格前先弄清三处静默改数据

让模型处理表格,最容易出问题的地方不是它不会写代码,而是它交回来的东西「看起来对」。它给你一份 CSV,月份列写着 2026-07,你打开一看是 46204;它写了 =SUM(...) 却立刻读回来拿到 null 就报「任务完成」;它填第三千行时报错,因为它不知道默认的表只有 1000 行。这三件事我在同一个下午全踩了一遍,用的都是同一套工具:Univer 的开源 headless 模式。

Univer 是国内的 DreamNum 团队做的 Office SDK,昨天(11 月 16 日)刚发 v1.5.2,GitHub 上 27,797 star、Apache-2.0(star 数与发布时间都是我用 GitHub API 现查的)。11 月 17 日它在 GitHub 日榜前排,第三方日榜记录当日涨了 1,878 star。它的卖点不是「再做一个在线 Excel」,而是把表格的内容模型、命令系统、公式引擎拆成包,让你在 Node 里直接调用——没有浏览器,没有 Canvas,没有界面。

先说清楚哪些是开源的,哪些要钱

这件事决定你能拿它干什么,所以放在最前面:

  • Web SDK(Apache-2.0,开源):内容模型、单元格读写、公式计算、快照保存。可以嵌到自己的网页编辑器里,也可以像我这样在 Node 里跑无头任务。
  • Server SDK(商业授权):实时协作服务端、编辑历史、Office 文件导入导出。XLSX 的读和写在这一层,官方文档写得很明确:Office conversion requires Server SDK。
  • AI SDK(商业授权):把 Office 能力接进已有 Agent 的工具层。

所以「用 Univer 替代 openpyxl 读写 xlsx」这个想法,在开源版上是走不通的。开源版给你的是一个活在内存里的、会算公式的工作簿,出入都得你自己接(CSV、数据库、JSON 快照)。想清楚这一点,后面的判断才不会跑偏。

装起来:七个包,纯 Node,147 毫秒

我这次的实测环境:macOS 26.5.2 / Apple M4 / 16GB,Node v22.22.2,npm 10.9.7,@univerjs/* 全部 1.5.2。安装 64 个包用了 9 秒。

Bash
# 建个空项目,类型必须写 module(这些包是 ESM 优先)
mkdir univer-lab && cd univer-lab
npm init -y
node -e "const p=require('./package.json');p.type='module';require('fs').writeFileSync('package.json',JSON.stringify(p,null,2))"

npm install @univerjs/core@1.5.2 @univerjs/engine-render@1.5.2 \
  @univerjs/engine-formula@1.5.2 @univerjs/docs@1.5.2 \
  @univerjs/sheets@1.5.2 @univerjs/sheets-formula@1.5.2 \
  @univerjs/sheets-numfmt@1.5.2

然后是初始化。这段代码来自官方 Headless 指南,我照抄跑通。末尾那几个 xxx/facade 的 side-effect import 是 API 的挂载入口,照抄别删——我试过删掉 sheets-formula/facade,setFormula 和计算都还正常(说明 core facade 已经带了主路径),但官方把它列成必需项,其它组合我没有逐个试,没有必要省这几行:

Javascript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { FUniver } from '@univerjs/core/facade'
import { UniverDocsPlugin } from '@univerjs/docs'
import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
import { UniverSheetsPlugin } from '@univerjs/sheets'
import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
import SheetsEnUS from '@univerjs/sheets/locale/en-US'
import '@univerjs/engine-formula/facade'
import '@univerjs/sheets/facade'
import '@univerjs/sheets-formula/facade'
import '@univerjs/sheets-numfmt/facade'

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: { [LocaleType.EN_US]: mergeLocales(SheetsEnUS) },
})
univer.registerPlugin(UniverRenderEnginePlugin)
univer.registerPlugin(UniverFormulaEnginePlugin)
univer.registerPlugin(UniverDocsPlugin)
univer.registerPlugin(UniverSheetsPlugin)
univer.registerPlugin(UniverSheetsFormulaPlugin)
univer.registerPlugin(UniverSheetsNumfmtPlugin)

const univerAPI = FUniver.newAPI(univer)
univerAPI.createWorkbook({})
const sheet = univerAPI.getActiveWorkbook().getActiveSheet()

sheet.getRange('A1:B3').setValues([['apple', 3], ['banana', 5], ['cherry', 7]])
sheet.getRange('C1').setValue('=SUM(B1:B3)')
sheet.getRange('C2').setValue('=B1*2')

我原本以为 engine-render 在 Node 里会拉 DOM 或 canvas 依赖,实测纯 Node 直接跑通,不需要 jsdom 之类的补齐。冷启动也轻:@univerjs/core 首次 import 89ms,其余插件 58ms,合计 147ms——放进 serverless 也不会因为加载被打爆。

坑一:公式是异步算的,立刻读回来是 null

这是我第一个翻车点。写完公式马上读:

Javascript
sheet.getRange('A4').setValue('=SUM(A1:A3)')
console.log(sheet.getRange('A4').getValue())   // null ← 不是 0,不是旧值
await new Promise(r => setTimeout(r, 100))
console.log(sheet.getRange('A4').getValue())   // 6

拿到的是 null。它既不是 0,也不是报错,就是想让你以为这格是空的。原因是写操作走的是命令队列(mutation),公式计算在队尾,setValue 只是把命令排进去。任何「写完立刻读回来校验」的脚本都会在这里误判成失败,而这正是 Agent 生成代码最爱的写法——写完,读一下,打印「已验证」。

同一个坑还有第二种表现。我拿一个实例循环处理 200 轮报表,每轮清空、重写 100 行、加一条 =SUM,立刻读结果——200 轮全部 undefined,等到最后统一读,值是 4950,完全正确。也就是说:不会报错,不会警告,只有值是空的。

顺便说清 getValue 和 getRawValue 的区别,这个更要命:

Javascript
// A2 存 1234.5678,并设置了货币格式 ¥#,##0.00
sheet.getRange('A2').getValue()        // "¥1,234.57"  ← 字符串!
sheet.getRange('A2').getRawValue()     // 1234.5678
sheet.getRange('A2').getDisplayValue() // "¥1,234.57"

getValue() 返回的是按数字格式渲染后的结果,不是数值。1/3 通过 getValue 读是 0.333333333333(12 位),getRawValue 才是 0.3333333333333333(快照里存的也是全精度)。做数据校验、回写数据库、二次计算,一律用 getRawValue()。用 getValue 的下场是把 "¥1,234.57" 当数字塞进下游,然后在下游的 float() 里炸掉。

坑二:默认的表只有 1000 行、20 列

createWorkbook({}) 出来的工作簿,getMaxRows() 是 1000,getMaxColumns() 是 20。Excel 是 1,048,576 × 16,384。我往第 5000 行写数据,直接抛 Range is out of bounds. Max rows: 1000, Max columns: 20——好在这条会抛错,比静默好。

改起来不麻烦,但顺序不能错:先扩容,再写数据。

Javascript
sheet.setRowCount(20000)
sheet.setColumnCount(32)   // 1ms,纯改元数据
sheet.getRange(0, 0, 5000, 5).setValues(bigData)

值得记一笔的是这个默认值背后的设计取舍:Univer 是给「网页里嵌一个表格」设计的,默认小表更省内存和渲染开销。放到服务端跑批处理,这个默认值就是纯负担——你的第一批数据就可能超界。

坑三:日期样的字符串会被静默转成序列号(本节是重点)

这条我建议所有要做「AI 读表/写表」的人抄进笔记。Univer 的 setValues 会对字符串做类型推断,推断规则和 Excel 一致:像日期的就当日期,像数字的就当数字。

Javascript
sheet.getRange('A1').setValue('2026-07')       // raw = 46204, t = 2(数字), fmt = yyyy-mm
sheet.getRange('A2').setValue('2026-07-15')    // raw = 46218, fmt = yyyy-mm-dd
sheet.getRange('A3').setValue('07/15/2026')    // raw = 46218, fmt = mm/dd/yyyy(按美式解析)
sheet.getRange('A4').setValue('1-2')           // raw = 46024, fmt = m-d  ← 最阴的一条
sheet.getRange('A5').setValue('00123')         // raw = 123(前导零没了)

"1-2" 变成 46024,也就是 2026-01-02。一个产品型号、一个版本号、一个区间,只要长得像日期,就会变成某一天。更麻烦的是表面看不出来——数字格式被自动设成了 yyyy-mm,人在界面上看到还是「2026-07」,只有下游拿 raw 值时才炸。

我试了三种「应该管用」的写法,只有一种真的管用:

写法 结果 判断
先 setNumberFormat('@') 再 setValues 仍被转成 46204,只是格式挂上了 @ ✗ 无效
字符串加撇号 '2026-07(Excel 习惯) 存成字面量 "'2026-07",撇号也进了值 ✗ 更糟
setValueForCell({ v: '2026-07', t: 1 }) raw 返回 "2026-07",t=1(字符串) ✓ 唯一正解

注意第三种的代价:它是逐格 API,不能像 setValues 那样一次灌一片。数据量大的时候只能循环,我测的单格写入大约 1ms 级别,几千行还能接受,十万行就得重新想办法(比如把这类列单独走一遍逐格写)。

Agent 场景里这条几乎必然踩:模型拿到 CSV 或用户口述的表格,最自然的写法就是 setValues 一把灌进去,日期列全变数字,然后它读回来一看「2026-07 变成了 46204」,再自作聪明地 TEXT() 一下,改成字符串「46204」——错两次。

端到端跑一遍:CSV 进,汇总出

光看 API 没意思,我写了个真实的小报表:9 行销售明细(月份、产品、渠道、金额),进 Univer 算六个指标,导出 CSV,再用 Python 独立算一遍对答案。

Javascript
import fs from 'node:fs'
import { makeAPI, sleep } from './lib.mjs'   // lib.mjs 就是上面那段初始化

const rows = fs.readFileSync('data.csv', 'utf8').trim().split('\n').slice(1).map(l => l.split(','))
const { api } = await makeAPI()
const wb = api.getActiveWorkbook()
const s = wb.getActiveSheet()
s.setName('明细')
s.setRowCount(rows.length + 12)
s.setColumnCount(8)
s.getRange(1, 0, rows.length, 4).setValues(rows.map(r => [r[0], r[1], r[2], Number(r[3])]))

const r0 = 2, r1 = rows.length + 1          // A2:A10
const summary = [
  ['指标', '值'],
  ['总营收',   `=SUM(D${r0}:D${r1})`],
  ['订单数',   `=COUNTA(D${r0}:D${r1})`],
  ['客单价',   `=ROUND(SUM(D${r0}:D${r1})/COUNTA(D${r0}:D${r1}),2)`],
  ['直销占比', `=TEXT(SUMIF(C${r0}:C${r1},"直销",D${r0}:D${r1})/SUM(D${r0}:D${r1}),"0.0%")`],
  ['最大单笔', `=MAX(D${r0}:D${r1})`],
  ['9月营收',  `=SUMIF(A${r0}:A${r1},"2026-09",D${r0}:D${r1})`],
]
s.getRange(0, 5, summary.length, 2).setValues(summary)

await sleep(1200)                            // 坑一:等计算
const out = summary.map((_, i) => {
  const c = s.getRange(i, 6)
  return [summary[i][0], c.getRawValue()]    // 坑一:用 raw
})
console.log(out)

跑出来的结果和我用 Python 独立核算的完全一致:

指标 Univer 计算结果 Python 独立核算
总营收 682,200 682,200
订单数 9 9
客单价 75,800 75,800
直销占比 75.9% 75.9%
最大单笔 141,000 141,000
9 月营收 236,700 236,700

但导出的 CSV 又给我上了一课:月份列全是 46204 这样的数字。原因就是坑三,我在这个例子里故意没修,好让对比清楚——同样的代码,加上 setValueForCell({ v, t: 1 }) 逐格写月份列,导出的 CSV 才是 2026-07。

公式引擎到底能算到什么程度

我把 34 条常用公式一次性写进一张表,等 1.5 秒后逐条读 raw 值:32 条结果正确,两条有问题。

算对的部分挺全:SUM/AVERAGE/MAX/MEDIAN/STDEV、COUNTIF/SUMIF/SUMPRODUCT、VLOOKUP/INDEX/MATCH/XLOOKUP、IF/IFERROR/LET、TEXT/TEXTJOIN/CONCATENATE/TRIM/SUBSTITUTE/LEFT、DATE/YEAR/RANK。错误值是标准写法:=B1/0 给 #DIV/0!,=B1+ 给 #VALUE!。跨表也正常,=VLOOKUP("k3",Sheet1!A1:B3,2,FALSE) 和 =SUM(Sheet1!B1:B3)+SUM(B1:B2) 都对。

有问题的两类:

  • 动态数组不铺开,而且两次跑结果不一样:第一轮 UNIQUE 对 4 个不同值给 #SPILL!,SEQUENCE(3) 也是 #SPILL!;我单独复测时 UNIQUE 返回了第一个值 "x",SORT 返回排好序的第一格 "w"(内部算对了,只是不铺开),TRANSPOSE 稳定给 #SPILL!。也就是说靠溢出填充整片区域的写法在这里不成立,而且失败方式还不统一——这种不统一比单纯不支持更难排查。
  • 循环引用静默归零:A1==A2+1、A2==A1+1,两格都返回 0,没有 #REF!,getFormulaError() 也是空数组。Excel 会警告你循环引用,这里什么都不说。

对做「模型生成公式、我负责校验」的流程,这两条意味着校验不能只看「有没有报错」——没报错不等于算对了。

性能:够不够放进服务端

我在 M4 / 16GB 上量了几组数:

  • 写 25,000 个单元格(5000×5):50ms
  • 写 5,000 条公式:23ms;4 秒内全部算完,抽样值与手算一致
  • 快照 79 万字符(约 793KB JSON),压缩后还会更小
  • 同一进程连续建 50 个独立实例:657ms,RSS 稳定在 210MB
  • 复用单实例跑 200 轮「清空→写 100 行→加公式」:中位 1ms,P90 2ms

结论挺清楚:一个进程按请求建实例是可行的(50 个实例 657ms 就建完,内存没涨),也可以单实例复用(单轮 1ms 级)。协作、持久化这些它不管,你得自己接。

我的判断:什么情况下用它,什么情况下别用

值得用的场景:

  1. 要给 Agent 一个「算表格」的工具。模型不需要自己实现公式解析,用 Univer 当执行层,你只负责把单元格值喂进去、把 raw 值取回来。这条链路我上面验证过,数字对得上。
  2. 自己的产品里要嵌表格编辑器。这是它本来的用途,开源部分(模型+渲染+公式)够搭一个像样的编辑器内核。
  3. 服务端批量算表。比起用 openpyxl 算不了公式(它只读写,不算),Univer 是真的会算。

不适合的场景,也说清楚:

  • 要做 xlsx 保真往返。开源版不可以,Server SDK 是商业授权,这部分我没有可用授权,未实测。真需要,现成方案是 SheetJS 读写 + 自己维护公式,或者直接用 LibreOffice 无头转换。
  • 要跟 Excel 完全一致的计算结果。动态数组、循环引用检测、精度口径这三处已经能看出差异,财务级核对要慎用。
  • 要图表、要截图。文档明说图表数据能改但不渲染,截图需要渲染运行时。
  • 超大数据量。我只测到 25,000 格,更大的规模没有测,不要拿我的数字外推。

收尾:表格是 Agent 最容易「假装成功」的地方

把这次踩的坑排一下顺序,我觉得对做 AI 表格的人最有用的顺序是:类型推断(数据被改)> 异步计算(结果是空)> 默认尺寸(写不进去)。第一条最危险,因为它不报错、界面上还显示得挺对;第二条最容易被 Agent 误判为失败;第三条最好查,因为会直接抛异常。

Univer 这个项目本身是扎实的,公式引擎的水平不是玩具级,headless 模式也确实不需要浏览器。它的问题不在能力,在默认值:为网页编辑器设计的默认值(小表、自动类型推断、显示口径取值),放到「机器写表」的场景里全都是坑。这也算是给做 Agent 工具的人提个醒——给模型用的 API,默认值该按「机器」调,不该按「人」调。顺带一提,之前测 opencode 共享服务端时也是同一类问题:工具本身没毛病,默认假设和你的用法不匹配。

下一步我打算拿它接在 OCR 出来的长文档表格后面:先把扫描件的表抽成 CSV,再灌进 Univer 算汇总,让整条链路都不用开 Excel。服务端那层可以照 Flask 起个接口包起来;如果你已经在用 LoopForge 那类 SOP 编排,这段脚本正好放在 Script 节点里——确定性的活交给确定性代码,token 花在判断上。

推荐阅读

  • LoopForge 实测:腾讯开源的编码 Agent 交付引擎,我用免费模型跑通了一条完整 SOP 交付线

    腾讯开源的 LoopForge 把编码 Agent 的交付流程做成 SOP 引擎:角色分离、人工门禁、需求追踪。我在 M4 Mac 用 Local 版装进 Codex 和 opencode,免费模型一…

  • open-code-review 实测:阿里开源的 AI 代码审查 CLI,我种的 5 个 bug 它全抓到了

    阿里开源的 open-code-review 用确定性流水线锁死代码审查流程,Agent 只做动态决策。我在 M4 Mac 实测 v1.13.9:种 5 个缺陷的 diff 全部命中、0 误报、行号精…

  • agent-desktop 实测:Vercel 给 AI Agent 的电脑操控 CLI,我在 M4 Mac 上跑通了输入、保存、关窗全链路

    Vercel 开源的 agent-desktop 让 AI Agent 读无障碍树操控 macOS/Windows/Linux 桌面应用,不截图不像素匹配。我在 M4 Mac 实测 1.3.1:Fin…

  • modern-web-guidance 实测:Chrome/Edge/Firefox/MDN 联手给 AI 编码 Agent 塞了 208 条现代 Web 指南,我跑了一组 A/B 对照

    Chrome/Edge/Firefox/MDN 联合出品 modern-web-guidance,把 250 项现代 Web 特性喂给编码 Agent。我在 M4 Mac 实测 CLI 三板斧与 le…