open-sheet

这是什么？适合谁？

OpenSheet（lianghsun/open-sheet）是一个为 AI Agent 而生的电子表格框架。它的核心洞察是：Agent 写分析很出色，写电子表格却很糟糕——原因是 =SUM(B2:B13) 这种 A1 单元格地址。地址是 Agent 唯一抓不住的东西：它数错表头行、忘记插入一行后公式该挪位、把一个引用写死成 B7 然后整张表的公式静默算错——不是崩溃，而是「错」，这比崩溃更糟。

OpenSheet 的解法是把地址拿走：你从不写一个单元格坐标，而是写语义引用 col('grossProfit', { formula: (r) => sub(r.cell('revenue'), r.cell('cogs')) })。框架在编译期拥有每一个坐标，加一行数据，所有引用自动重新解析。源文件里没有一个 A1 地址。

核心价值：把电子表格从「一个静态数字快照」变成「一个收件人可以改假设、看它重新计算的活模型」。一份被烤成静态数字的工作簿只是表格的照片；电子表格的价值在于公式是活的。

适合人群：

• 需要让 Agent 批量产出报表的团队（月度董事会材料、500 张发票、数据一到就重新生成的模型）
• 需要「代码评审」而不是「二进制 diff」来审阅表格变更的工程师
• 想让产出物带有活公式、能二次提问的分析师

不适合：只需要在已有 Excel 里帮人写公式的场景（那是 Claude for Excel 的活）；需要一个可以交互编辑的表格前端（这是编译器框架，不是编辑器）。

使用前提：Node.js（发布 CLI 需要 Node 18+）；pnpm 工具链；目标是「pipeline 的产出」而非「人打开的文档」。

准备工作

1. Node.js 18+：npx 脚手架和 CLI 都需要。
2. pnpm：monorepo 用 pnpm + Turbo 管理。
3. 成本：MIT 开源，完全免费；无 npm 依赖运行时、无远程渲染服务。
4. 时间预算：npx @open-sheet/cli init 到跑通 demo 约 10 分钟。
5. 心智准备：OpenSheet 是「编译期解析引用」的思路，不是传统表格工具，需要先理解「引用而非地址」的范式。

快速上手（3 步）

第一步：初始化工作区

npx @open-sheet/cli init my-sheets
cd my-sheets && npm install && npm run dev

脚手架会生成一个 .tsx 源文件作为工作区，开发服务器提供实时预览。

第二步：写第一个列

col('grossProfit', {
  header: 'Gross profit',
  formula: (r) => sub(r.cell('revenue'), r.cell('cogs')),
})

注意：没有 B2、没有 SUM 范围。你用 r.cell('revenue') 语义引用，框架负责把它解析成正确的坐标。

第三步：导出活 .xlsx

# 构建导出（.xlsx / .csv / .html / .pdf 四种格式）

成功判定：导出的 .xlsx 里净收入列是 =F6*(1-taxRate) 这种活公式而非烤死的数字；改一个假设单元格，整列跟着重算。OpenSheet 的 CI 甚至用 LibreOffice 重新计算导出的工作簿来做交叉引擎验证。

初级用法

引用而非地址

• r.cell('revenue') — 本行某列
• r.prev().cell('revenue') — 上一行
• ref('pl').column('revenue') — 引用另一张表某列
• ref('pl').total('revenue') — 另一张表某列合计
• ref('assumptions').get('growth') — 取标量假设（导出时还会成为 Excel 定义名称 growth）

自动布局

<Stack> 和 <Row> 把块打包到网格上而不碰撞。你描述顺序，框架决定坐标——这是 OpenSheet 对 open-doc flow() 的对应物。

双后端公式树

每个公式是一棵表达式 AST，有两个消费者：serialize() 写出 Excel 公式字符串进 .xlsx，evaluate() 计算预览显示的数值。两者在 CI 里用 LibreOffice 重算对账，证明「导出含活公式」且「求值器和真实表格引擎一致」。算不出来的公式显示 #NOT_EVALUATED，绝不编造数字。

高级玩法

Agent-native 工作流

脚手架自带四个 Skill：/create-sheet、/sheet-authoring、/current-sheet、/apply-comments。MCP 服务器（open-sheet dev --mcp）让任何 Agent 框架都能驱动它。Inspect 模式可以点一个单元格看它的源行、解析后的公式和计算值，或者给 Agent 留注释。

与 Claude for Excel 组合

两者顺序组合：OpenSheet 产出带活公式的文件，正因如此，收件人可以打开结果继续提问。OpenSheet 适合「表格是 pipeline 的产出」；Claude for Excel 适合「你已有一张表想让人帮忙」。

规模批处理

因为源文件是 .tsx 代码，改模型再重建 500 次只是循环，而不是 500 次人工会话。审阅一次变更是一次代码评审，不是二进制 diff。

小技巧

1. 标量假设用定义名称：ref('assumptions').get('growth') 会导出为 Excel 定义名称，让收件人看到 =B4*growth 而不是 =B4*Sheet2!$C$9。
2. 用 <Stack>/<Row> 描述顺序：别手排坐标，布局变化时你会感谢框架。
3. 信任 #NOT_EVALUATED：看到它意味着求值器没把握，这是设计行为，不是 bug。
4. Inspect 模式做交接：点单元格看源行，给下一个 Agent 留注释，团队协作更顺。
5. 四种导出都验证一遍：HTML/PDF 渲染器和 Excel writer 共享同一风格模型，打印版和工作簿应一致。

常见踩坑

踩坑 1：把 OpenSheet 当 Excel 编辑器用

• 现象：想打开已有 .xlsx 改几格，发现读不了。
• 原因：OpenSheet 只能读自己生成的 .tsx 源文件，无法读取未由它生成的既有工作簿。
• 解决：已有表格找人帮忙用 Claude for Excel；OpenSheet 用于「表格是产出」的 pipeline。

踩坑 2：期待它已有 500 个 Excel 函数

• 现象：某些函数找不到。
• 原因：当前约 100 余个函数，而 Excel 有 500 多个；Pivot 表也不支持。
• 解决：评估你的公式集是否在覆盖内；复杂分析型问题（方差归因）交给 Excel 引擎。

踩坑 3：误以为静态导出就够

• 现象：导出成纯数字快照，收件人无法改假设。
• 原因：没理解「活公式」才是价值所在。
• 解决：导出 .xlsx（含公式）而非 .csv 快照；用定义名称让公式可读。

踩坑 4：忽视早期开发状态

• 现象：以为 npm 上有稳定版。
• 原因：目前是 Early development，0.1.0 刚发布，里程碑仍在推进。
• 解决：关注仓库 milestones，生产使用前先跑通 demo 验证端到端。

踩坑 5：不装 LibreOffice 做交叉验证

• 现象：本地求值器结果和真实 Excel 打开结果不一致也没发现。
• 原因：求值器与真实引擎的对账依赖 CI 里的 LibreOffice 重算。
• 解决：CI 里保留 LibreOffice 重算步骤，别删掉这条对账测试。

常见问题 FAQ

Q1: OpenSheet 和 Claude for Excel 有什么区别？

A: 定位完全不同。Claude for Excel 让一个人更快地做表（输入已有工作簿，每次都在循环里）；OpenSheet 让表格不需要重做第二次（输入 .tsx 源文件，人在评审时出现一次）。前者在电子表格内部工作、仍写 =SUM(B2:B13) 手写地址；后者彻底不写地址，编译期解析引用。

Q2: 为什么 Agent 写 Excel 特别容易错？

A: 因为单元格地址是 Agent 抓不住的东西——它数错表头、忘记插入行后公式移位、写死一个引用然后整表静默算错。地址是 A1 表格语言唯一能表达的。OpenSheet 用语义引用在编译期解析，彻底绕开地址。

Q3: 支持哪些导出格式？

A: .xlsx（活公式，含数字格式/定义名称/冻结窗格/条件格式）、.csv、.html、.pdf。四种导出共享同一风格模型，打印版和工作簿一致。

Q4: 需要 GPU 或远程服务吗？

A: 不需要。零 npm 运行时依赖、无远程字体/资源、无网络访问。完全本地、MIT 开源。

Q5: 现在能用于生产吗？

A: 项目自述 Early development，0.1.0 已发布、144 个测试含两个驱动真实表格应用的测试。建议先在 demo 上跑通端到端，再决定是否上生产 pipeline。

进阶学习建议

掌握基础后，建议深入：

1. Agent 批量报表流水线：把「数据落地 → 重建表格 → 导出活 .xlsx」做成定时 pipeline，配合 /sheet-authoring Skill 让 Agent 自动生成源文件。
2. 定义名称驱动的可读模型：把关键假设全部走 ref('assumptions').get(...) 导出为 Excel 定义名称，让财务收件人能直接读公式、改假设。
3. LibreOffice 交叉验证闭环：复刻仓库 CI 里「导出后 LibreOffice 重算并 diff」的做法，把它作为你 pipeline 的必过门禁。

参考链接

• 官方仓库
• open-sheet.dev
• open-slide（同思路的幻灯片框架）
• open-doc（同思路的文档框架）

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成