bilig：为AI Agent打造的无头电子表格引擎

bilig是一个专为Node服务和AI Agent设计的无头电子表格引擎，支持本地优先的工作簿自动化和公式驱动的工作流。它提供完整的公式解析、编译、计算能力，以及持久化、同步和性能优化等高级特性，是构建智能数据处理应用的理想基础设施。

电子表格是商业世界最普遍的数据处理工具，但传统实现要么绑定特定桌面软件，要么功能受限。bilig项目重新定义了电子表格引擎的概念——它是一个无头(Headless)运行时，专为现代服务架构和AI Agent设计，可以在Node.js环境中完整运行，无需浏览器界面。

bilig采用模块化架构，将电子表格的核心能力分解为多个独立的包：

@bilig/formula：完整的公式语言支持，包括A1地址解析、词法分析、语法解析、绑定、编译和JavaScript求值。公式引擎经过严格的等价性测试，确保与主流电子表格软件的行为一致。

@bilig/core：工作簿引擎的核心，处理工作簿状态变更、公式调度、快照管理、历史记录、选择区域和依赖关系检查。这是整个系统的计算中枢。

@bilig/headless：面向AI Agent和Node服务的无头运行时接口。Agent可以通过稳定的API直接操作工作簿状态，无需屏幕抓取或模拟用户交互。

@bilig/grid：可复用的React电子表格UI组件，为需要可视界面的应用提供支持。

WASM加速：通过AssemblyScript实现的WASM内核，为计算密集型公式族提供性能加速，同时保持与JavaScript实现的等价性。

bilig从设计之初就考虑了本地优先(Local-first)架构：

• 浏览器状态恢复：会话可以从本地状态恢复，保留副本快照
• 可重放变更：所有编辑操作都被记录为有序的变更批次，支持离线编辑和后续同步
• 二进制同步协议：高效的有线格式用于传输同步帧，减少网络开销
• 多人协作基础：架构支持最终一致的多人实时协作，尽管完整的后端同步仍在开发中

这种设计特别适合需要离线工作能力或数据主权敏感的应用场景。

这是bilig最具创新性的特性。传统上，AI Agent操作电子表格需要通过截图分析或模拟键盘鼠标输入，这种方式脆弱且效率低下。bilig提供了专门为Agent设计的API：

const workbook = WorkPaper.buildFromSheets({
  Revenue: [
    ['Region', 'Customers', 'ARPA', 'Revenue'],
    ['West', 20, 1200, '=B2*C2'],
    ['East', 30, 250, '=B3*C3'],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Total revenue', '=SUM(Revenue!D2:D3)'],
  ],
});

// Agent可以直接读写单元格
workbook.setCellContents({ sheet: revenue, row: 1, col: 1 }, 32);

// 持久化和恢复
const saved = serializeWorkPaperDocument(
  exportWorkPaperDocument(workbook, { includeConfig: true })
);
const restored = createWorkPaperFromDocument(parseWorkPaperDocument(saved));

Agent可以：

• 通过零基索引直接寻址单元格
• 批量设置单元格内容和公式
• 导出和导入完整的工作簿文档
• 验证公式在持久化后是否正确保留

bilig对性能和正确性有严格要求：

WorkPaper基准测试：项目建立了与HyperFormula等主流引擎的性能对比基准。当前数据显示，在46个可比工作负载上，bilig在均值性能上全部获胜。这些基准测试是持续集成的一部分，确保性能回归能被及时发现。

等价性测试：公式引擎通过大量固定测试用例(Fixtures)验证与参考实现的等价性。任何公式行为的变更都必须通过相应的测试。

CI门禁：完整的持续集成流程包括类型检查、单元测试、浏览器测试、基准测试冒烟验证和生成代码检查。

bilig特别适合以下场景：

服务端数据处理：在Node服务中处理上传的Excel文件，执行公式计算，生成报告。

自动化工作流：构建无人值守的数据处理管道，自动从多个源拉取数据，执行复杂的公式计算，输出结果。

AI Agent工具：为LLM Agent提供结构化的数据操作能力，让Agent能够理解和修改电子表格内容。

本地优先应用：构建支持离线编辑的协作电子表格应用，数据首先保存在本地，网络恢复后自动同步。

财务建模：支持复杂的财务模型计算，如收入预测、ARR/MRR分析等。

项目提供了完整的收入模型示例，展示如何构建公式驱动的财务工作簿：

const workbook = WorkPaper.buildFromSheets({
  Revenue: [
    ['Region', 'Customers', 'ARPA', 'Revenue'],
    ['West', 20, 1200, '=B2*C2'],
    ['East', 30, 250, '=B3*C3'],
    ['Central', 18, 300, '=B4*C4'],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Total revenue', '=SUM(Revenue!D2:D4)'],
    ['Total customers', '=SUM(Revenue!B2:B4)'],
    ['Gross MRR', '=SUM(Revenue!D2:D4)'],
  ],
});

修改输入数据后，所有依赖的公式会自动重新计算。这种声明式的数据建模方式大大降低了复杂财务逻辑的实现难度。