---

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_sheets
• read_range
• read_cell
• set_cell_contents
• get_cell_display_value
• export_workpaper_document
• validate_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