工作原理

Excel 是模板，xl3 来执行它。

业务用户在 Excel 中编辑布局；应用提供数据与输入；xl3 确定性地执行工作簿。点击这三个阶段，跟随一份报表从原始数据走到成品输出。

data.xlsx从原始数据开始。

data.xlsx原始操作数据

	A	B	C	D
1	Account	Region	Renewal	Owner
2	Acme Logistics	Seoul	18400	Mina
3	Beta Works	Busan	7200	Joon
4
5
6
7
8

Sheet1

应用把一张数据表——一个 .xlsx 工作表或一个语言中立的 JSON 源——连同任意逐次输入一起交给 xl3。任何与布局相关的东西都不在代码里。

基于职责的自动化

把文档改动移出部署队列。

大多数 Excel 自动化工具让开发者更快。xl3 追求的是另一种结果：让操作者接手过去需要开发者才能完成的文档改动。当每个业务伙伴都需要自己的格式时，让一位工程师逐个实现、每次变更再重改一遍，就会成为瓶颈。

xl3 是在一项运行了数月的内部服务中打磨出来的。在那段时间里，非开发者直接在 Excel 中维护模板和转换规则，而开发者几乎只专注于运行时。真正的削减不只是代码量，而是必须由开发者来做的工作量本身。

开发者

拥有运行时：引擎行为、校验、集成、部署与可靠性。

runtime

操作者

拥有模板：布局、列、重复规则、输出格式以及文档专属逻辑——直接在 Excel 中编辑。

template.xlsx

业务方

直接使用完成的工作簿，无需等待每一次重复性文档改动都变成一次发布。

result.xlsx

xl3 并不打算取代开发者。开发者拥有运行时，操作者拥有模板；文档自动化不再是开发者专属的任务，而成为组织的一种能力。

为什么 Excel 就是模板

别再把报表布局写进一次性脚本里。

ExcelJS、SheetJS、openpyxl 和 Apache POI 是电子表格的 DOM API：强大但冗长。当报表的布局、样式、合并单元格和循环都写进代码后，每一次设计改动——新增一列、移动一处小计、重排表头——都会变成一次部署。

xl3 把这份反复出现的契约搬回 Excel。工作簿本身就是视图，XTL 让它变得可执行，而应用只需提供数据并运行引擎。模板就是一个普通的 .xlsx——没有宏，也没有厂商云——因此你可以对它做 diff、在 Pull Request 中审阅，并交给一个从没听说过 xl3 的人。

开放标准，而非一个库

一份规范、一套一致性套件，以及一个参考实现。

xl3 被定义为一个由三部分组成、与实现无关的开放标准。XTL 表面刻意保持精简，让模板既便于人阅读，也便于 AI 起草。

规范（xl3 + XTL）

规范性定义：xl3 工作簿格式，以及它小巧的内嵌表达式语言 XTL。只有当某个函数的值必须在工作簿写出之前确定时，它才存在于 XTL 中（ADR-0043）。

spec/

一致性套件

语言中立的一致性夹具，每个实现都要运行以证明自身合规。契约在于这套语料库，而非任何单一实现——移植必须与之匹配。

conformance/

参考实现

@xl3-lang/xl3（TypeScript）可在浏览器和 Node 中运行。它很有用，但并非规范——Rust/WASM 与 Python 移植正在进行中。

@xl3-lang/xl3

XTL 0.1 提供 79 ADRs 与 171 conformance fixtures，在 Stage 2 全部通过。TypeScript 参考实现发布于 @xl3-lang/xl3——移植指南记录了这份契约，使其他语言的移植也能与之对齐。

对比

同一个问题，不同的形态。

方案	擅长	取舍
xl3	声明式的 Excel 模板执行。工作簿已经存在，xl3 用数据来运行它。	发布候选版；单一维护者；1.0 契约将在 2026-11-28 前进行技术稳定性验证。
Workbook APIs (ExcelJS, SheetJS, openpyxl, POI)	从应用代码进行底层或全功能的工作簿生成。	布局、样式、合并、循环和业务规则都变成了代码。非开发者无法安全地编辑模板。
Python / VBA scripts	贴近现有电子表格的快速一次性自动化。	规则存在于代码或某位维护者的记忆中；布局变更仍需改代码。
Power Query / Office Scripts	Excel 生态内的 Microsoft 365 工作流与数据整形。	绑定租户；工作流规则不会随工作簿一起迁移。
Template engines (JXLS, xltpl, jsreport xlsx)	从类电子表格模板进行服务端报表生成。	有价值的先行经验，但通常绑定单一运行时，也没有定位为小巧、可移植的 Excel 规则格式。
Doc-gen SaaS (Plumsail, Conga, Formstack)	托管式文档工作流、集成、审批与分发。	规则存在于厂商服务中，而不是你可以自行审阅和运行的可移植工作簿模板。
Direct LLM → xlsx	快速的探索性起草、一次性图表。	并非面向重复运营的确定性转换契约；每次运行的样式与合计都会漂移。

开发者 API

把同一套工作流接入你的产品。

传入应用已经保存在内存中的数据，应用 Excel 模板，并取得生成好的 .xlsx。convertJson() 可直接接收 JavaScript 对象，因此不需要源数据文件或中间工作簿。

terminal

$npm install @xl3-lang/xl3

example.ts

import { convertJson } from '@xl3-lang/xl3';

const outputs = await convertJson(templateBuffer, {
  version: 'xl3-source-json/0.1',
  sources: { default: {
    headers: ['Customer', 'Amount'],
    rows: orders.map(o => [o.customer, o.amount]),
  } },
});
// OutputFile[].data → .xlsx Uint8Array

手册 01 — 5 分钟快速上手 · 阅读规范 · 移植指南

用模板生成 Excel 报表，
而不是写代码。

Excel 是模板，xl3 来执行它。

从原始数据开始

在工作簿中声明转换

每次都得到同一个工作簿