
关于
使用公式驱动的 WorkPaper JSON 和 MCP 工具完成代理电子表格任务,无需操作 Excel 或浏览器 UI。
name: bilig-workpaper description: "使用基于公式的 WorkPaper JSON 和 MCP 工具完成代理电子表格任务,无需驱动 Excel 或浏览器 UI。" risk: unknown source: community date_added: "2026-05-21" tags:
- spreadsheets
- formulas
- mcp
- xlsx
- typescript
Bilig WorkPaper
概述
Bilig WorkPaper 为代理提供代码优先的工作簿运行时,用于电子表格风格的业务逻辑。当任务更容易建模为工作表和公式,但可靠的路径是通过 API 编辑单元格、重新计算、读回计算值并持久化 JSON 工作簿文档时使用它。
主要用例是用确定性的工具调用替代脆弱的电子表格 UI 自动化。适用于报价计算器、支付模型、预算检查、导入验证和减少 XLSX 公式错误报告。
何时使用此技能
当用户需要以下操作时使用此技能:
- 从 Node.js 服务、路由、测试或代理工具中使用电子表格公式;
- 写入工作簿输入并通过回读证明验证计算输出;
- 将公式工作簿持久化为可审查的 WorkPaper JSON;
- 通过 MCP 工具暴露基于文件的工作簿;
- 在不自动化 Excel、LibreOffice 或浏览器网格的情况下调查 XLSX 公式重新计算问题。
不要将其用于手动电子表格编辑、VBA/宏、数据透视表、图表、COM 自动化或精确的桌面 Excel 行为,除非用户明确要求与 Excel 作为参照进行比较。
更安全的命令模式
在 MCP/客户端配置中优先使用参数数组。不要对用户提供的路径、工作表名称、公式或单元格地址进行 shell 拼接。在命令中使用之前,拒绝包含换行符、反引号、$(、;、&、|、< 或 > 的路径或单元格输入。
快速 MCP 设置
首先证明包自带的挑战可以工作:
{
"command": "npm",
"args": ["exec", "--package", "@bilig/workpaper", "--", "bilig-mcp-challenge"]
}
然后运行可写的基于文件的 MCP 服务器:
{
"command": "npm",
"args": [
"exec",
"--package",
"@bilig/workpaper",
"--",
"bilig-workpaper-mcp",
"--workpaper",
"./pricing.workpaper.json",
"--init-demo-workpaper",
"--writable"
]
}
MCP 服务器暴露的有用工具:
list_sheetsread_rangeread_cellset_cell_contentsget_cell_display_valueexport_workpaper_documentvalidate_formula
每次写入后,读取依赖的输出单元格并导出 WorkPaper 文档。不要仅凭写入调用就声称成功。
直接 TypeScript 模式
当工作簿逻辑属于应用程序代码内部时,直接使用该包:
import {
WorkPaper,
exportWorkPaperDocument,
serializeWorkPaperDocument,
} from "@bilig/workpaper";
const workbook = WorkPaper.buildFromSheets({
Inputs: [
["Metric", "Value"],
["Customers", 20],
["Average revenue", 1200],
],
Summary: [
["Metric", "Value"],
["Revenue", "=Inputs!B2*Inputs!B3"],
],
});
const inputs = workbook.getSheetId("Inputs");
const summary = workbook.getSheetId("Summary");
if (inputs === undefined || summary === undefined) {
throw new Error("Workbook is missing required sheets");
}
workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32);
const revenue = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 });
const saved = serializeWorkPaperDocument(
exportWorkPaperDocument(workbook, { includeConfig: true }),
);
console.log({ revenue, savedBytes: saved.length });
必需的验证
一个好的代理响应应包括:
- 编辑的确切工作表名称和 A1 单元格;
- 重要输入和依赖输出的修改前值;
- 从重新计算的工作簿中读取的修改后值;
- 来自导出或序列化的 WorkPaper JSON 的持久化证据;
- 当文件边界重要时的恢复或重新导入证明;
- 不支持的公式或仅 Excel 行为的明确限制说明。
如果任何证明步骤失败,报告阻塞问题而不是说工作簿已更新。
限制
- WorkPaper 行为不能完全替代桌面 Excel、VBA、数据透视表、图表或 UI 自动化。
- 公式兼容性取决于 Bilig 运行时,当需要精确对等时应与 Excel 进行验证。
- MCP 写入应限定在受信任的工作簿路径范围内,并且必须在之后进行回读验证。
参考资料
- 仓库:https://github.com/proompteng/bilig
- 精简文档地图:https://proompteng.github.io/bilig/llms.txt
- 代理手册:https://proompteng.github.io/bilig/headless-workpaper-agent-handbook.html
- MCP 服务器指南:https://proompteng.github.io/bilig/mcp-workpaper-tool-server.html
- XLSX 公式诊所:https://proompteng.github.io/bilig/formula-bug-clinic.html
- 兼容性限制:https://proompteng.github.io/bilig/where-bilig-is-not-excel-compatible-yet.html
