工作流模型

引擎留在代码里，工作流留在工作簿里。

开发者只需构建一次转换器。例行的业务规则、源表映射、版式和输出形态都留在工作簿模板中，便于团队归档和移交。

在 Excel 中定义契约

用 __config__、source_table 和 XTL 表达式描述原始工作簿如何转化为报表。

提供简单的上传流程

非开发人员只需选择原始 Excel 文件和已审核的模板，再运行转换器即可。

生成成品工作簿

输出保留工作表结构、数字格式、样式和合并单元格，同时以数据填充对应的值。

归档运营规则

模板成为移交产物：一份可携带的文件，完整记录这项例行 Excel 作业的运作方式。

__config__The template declares the source shape.

template.xlsxworkbook with transformation rules

B2fxB2 source_table = 1

	A	B	C
1	key	value	notes
2	source_sheet	Raw	worksheet to read
3	source_table	1	column names and data rows

__config__

source_table tells the engine where the raw table starts and which columns belong to it.

开发者为什么用它

把例行报表逻辑从一次性脚本中解放出来。

Python 脚本、VBA 宏和特定服务的工作流都能自动化 Excel，但业务规则往往散落在代码、账号和个人经验之中。

xl3 把可复用的引擎和工作簿专属的契约分离开来。开发者负责维护 TypeScript 集成，每项例行 Excel 作业则以模板工作簿的形式自由流转。

贴合运营

为移交而生，不只是自动化。

运行这套工作流的人不必读代码。他们需要的是一个稳定的转换器、一份已审核的模板，以及一份可预期的结果工作簿。

模板即移交

报表规则就在一份工作簿文件里——可审阅、可版本化、可归档，也可以直接交给下一位运营人员。

template.xlsx

业务人员友好的运行方式

运行时可以作为一个浏览器页面对外提供：上传原始数据、选择模板、下载工作簿。

raw.xlsx → result.xlsx

开发者掌控的引擎

部署、校验和集成都留在代码里，而模板专属的工作流规则则留在 Excel 中。

convert(template, raw)

XTL 0.1 已交付 70 ADRs、154 conformance fixtures，在 Stage 2 全部通过。TypeScript 参考实现已发布于 @jinyoung4478/xl3——移植者指南详细记录了契约，可供第二种语言的移植版本对齐。

横向对比

同一个问题，不同的解法。

方案	擅长场景	取舍
xl3	LLM 主笔的 Excel 流水线中的“执行”那一半。模型只需写一次模板，xl3 在每次运行时都以确定性方式渲染。	Alpha 阶段；仅有一位维护者；XTL 表面有意保持精简，在 1.0 之前仍在演进。
Direct LLM → xlsx (spreadsheet SDK function call)	快速的探索性起草、一次性图表。	每次渲染都是非确定性的；即使 temperature 设为 0，样式、数字格式和合计也会在多次运行之间漂移。
Spreadsheet SDKs (SheetJS, ExcelJS, openpyxl)	底层工作簿生成。	模型必须掌握整个 SDK 表面，并在每次渲染时重新生成代码；这里的“模板”是应用代码，而非可携带的文件。
Power Query / Office Scripts	Microsoft 365 工作流，在 Excel 生态内整形数据。	绑定到租户；工作流规则无法随工作簿一起携带。
Template engines (JXLS, xltpl, jsreport xlsx)	基于类电子表格模板的服务端报表生成。	诞生于 LLM 主笔模式之前；其模板 DSL 较为庞大，并非为模型输出而设计。
Doc-gen SaaS (Plumsail, Conga, Formstack)	托管式文档工作流、集成、审批与交付。	规则放在厂商服务里，而不是一份可以交给 LLM 去编辑的、可携带的工作簿。
Python / VBA scripts	贴近现有电子表格的快速一次性自动化。	规则藏在代码或某个维护者的记忆里；不是模型可以输出的产物。

开发者 API

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

当 Demo 流程要演进为内部门户、CLI 或服务端接口时，请使用这个包。业务人员可以继续以文件为中心，部署与校验则由你的应用来掌控。

terminal

$npm install @jinyoung4478/xl3

example.ts

import { convert } from '@jinyoung4478/xl3';

const outputs = await convert(templateBuffer, dataBuffer);
// OutputFile[] → formatted .xlsx workbook(s)

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