Bilig WorkPaper

Bilig

保留工作簿模型。在 Node 中运行规则。

Bilig 是一款原生 TypeScript、无头的 WorkPaper 运行时，适用于 Node.js 服务、测试和 AI Agent。设置输入、重新计算公式、读取计算结果、持久化 WorkPaper JSON、恢复并验证结果——无需操作 Excel 或浏览器网格。

文档 · 快速开始 · TypeScript API · MCP · 示例与深入指南 · 讨论

说明

Bilig 是无头工作簿运行时，不是可视化电子表格应用，也不声称完全兼容 Excel。如果 .xlsx 文件是你的契约，请从兼容性报告开始。

快速开始

Node 运行时

安装前先验证已发布的程序包：

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json

求值器会编辑 Inputs!B2，重新计算 Summary!B2，保存 WorkPaper，恢复它，并比较恢复后的值：

{
  "schemaVersion": "bilig-evaluator.v1",
  "door": "workpaper-service",
  "evidence": {
    "editedCell": "Inputs!B2",
    "dependentCell": "Summary!B2",
    "before": 24000,
    "after": 38400,
    "afterRestore": 38400
  },
  "verified": true
}

verified: true 表示写入、公式读回、JSON 导出和恢复后的读回全部通过。这比写入调用成功更有力。

在 TypeScript 中使用

npm install @bilig/workpaper

import { buildA1WorkPaper } from '@bilig/workpaper'

const pricing = buildA1WorkPaper({
  Inputs: [
    ['Metric', 'Value'],
    ['Units', 20],
    ['Price', 1200],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Revenue', '=Inputs!B2*Inputs!B3'],
  ],
})

const proof = pricing.editAndReadback('Inputs!B2', 32, {
  readbackRange: 'Summary!B2',
})

console.log(proof.afterReadback.displayValues[0]?.[0]) // 38400
console.log(proof.verified) // true

pricing.dispose()

对于常规操作，请使用 set()、setMany()、readMany()、display() 和 saveJson()。如果需要将多个输入作为一次编辑提交并验证，请使用 editManyAndReadback()。完整的公开 API 记录在 packages/workpaper/README.md 中。

生命周期刻意保持精简：

inputs → formula recalculation → typed readback → JSON persistence → restore verification

为什么选择 Bilig

在定价、报价审批、付款、预测、验证规则、公式驱动的工作流，以及服务或工具应拥有模型的测试中使用 Bilig。如果需要可视化编辑、协作、宏、交互式数据透视表或图表，或者桌面版效果，请选择电子表格应用或托管电子表格 API。

Agent 与 MCP

Agent 应先询问由哪个系统负责管理状态，然后运行最小匹配验证。对于工具宿主或 MCP 客户端：

npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

MCP 评估器会验证工具发现、修改、重新计算后的读回、JSON 导出、磁盘持久化、进程重启以及恢复后的读回。对于本地可写的 WorkPaper：

npm exec --yes --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable

对于私有或持久化的项目状态，请使用本地 stdio 路径。托管的 https://bilig.proompteng.ai/mcp 端点仅在单个请求期间有效，只适用于无状态的连接器发现和冒烟测试；请勿向其发送私有工作簿数据。

该服务提供 list_sheets、read_range、read_cell、set_cell_contents、set_cell_contents_and_readback、get_cell_display_value、export_workpaper_document 和 validate_formula。它还会发布 MCP 资源和提示词，让功能完善的宿主在编辑单元格前了解工作流。

机器可读入口：

发布的包还包含 AGENTS.md 和 SKILL.md，因此 Agent 可以从 node_modules 中发现相同的验证约定。可通过以下任一来源安装或查看公开技能：

npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list

验证后的集成方案

先运行评估器，然后使用适用于你的宿主的方案：

• OpenAI Agents SDK：直接使用工具、MCPServerStdio 和 MCPServerStreamableHttp。
• OpenAI Responses API：通过函数调用读回，并明确提供前后证据。
• Vercel AI SDK：generateText() 和 streamText() 工具循环。
• Open WebUI：本地或托管 MCP 发现。
• n8n：社区节点 @bilig/n8n-nodes-workpaper。

选择评估路径

workbook-compatibility 和 xlsx-cache 评估入口使用随附的演示工作簿对已发布的软件包进行冒烟测试；它们不会检查你的文件。 不要将任何评估器视为与桌面版 Excel 完全一致的证明。

示例和深入指南

从一个维护中的示例开始，而不是整个 monorepo：

• examples/headless-workpaper：定价、发票、预算、履约、订阅、持久化和 Agent 示例。
• examples/serverless-workpaper-api：通过 Hono、Next.js 和持久化适配器进行报价审批。
• examples/xlsx-recalculation-node：导入、重新计算、导出、重新导入并验证 XLSX 工作簿。
• examples/recalc-bridge-workflows：为现有 SheetJS、xlsx-populate 和 ExcelJS 工作流提供针对性桥接。

实用的决策指南：

• 公式工作簿证明页面
• Agent 评估矩阵
• 面向编码 Agent 的 MCP 电子表格服务
• Vercel AI SDK 公式回读
• OpenAI Responses 工具调用
• ExcelJS 公式结果边界
• Google Sheets QUERY 和 SORTN
• Microsoft Graph Excel 边界
• XLSX 公式支持答疑
• 生产环境采用检查清单

pnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-text
pnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-text
pnpm --dir examples/headless-workpaper run agent:openai-responses
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
pnpm --dir examples/serverless-workpaper-api run hono-route
pnpm --dir examples/serverless-workpaper-api run next-server-action
pnpm --dir examples/serverless-workpaper-api run next-server-action-formdata

npm exec --yes --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"

Bilig 可以导入和导出工作簿文件，但 .xlsx 中缓存的公式值只是诊断信息，不能作为准确性的最终依据。请先检查文件，再决定是否信任它：

npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json

第一条命令使用内置演示文件进行软件包冒烟测试。接下来的两条命令会检查指定文件。兼容性报告会指出不受支持的函数、外部链接、宏、数据透视表、易变公式和其他风险，但不会认证其与 Excel 兼容。需要确保正确性时，请与刚由 Excel 重新计算的工作簿进行比较。请参阅兼容性限制和Excel 基准验证演练。

软件包与仓库结构

公开的 WorkPaper 软件包要求 Node.js >=24。本地单体仓库开发使用 Node.js 24+、Bun 和 [email protected]。

已发布版本包含 npm 注册表签名和来源证明：

npm view @bilig/workpaper version dist.attestations dist.signatures --json
npm audit signatures

开发

选择一个长期运行的开发服务器：

pnpm dev:web
pnpm dev:web-local

使用以下命令安装并验证仓库：

pnpm install
pnpm build
pnpm lint
pnpm typecheck
pnpm test
pnpm run ci

架构文档位于 docs/architecture.md。提交拉取请求前，请阅读 CONTRIBUTING.md；首次贡献者可以从新贡献者指南 和入门问题开始。所有参与者都必须遵守 CODE_OF_CONDUCT.md。

支持与安全

• 在讨论区提出采用和设计相关问题。
• 通过 GitHub Releases关注版本更新。
• 通过问题跟踪报告可复现的错误；精简后的工作簿可以使用 公式问题诊所和 样例提交表单。
• 阅读 SUPPORT.md，了解哪些证据能让报告更具可操作性。
• 按照 SECURITY.md 的说明私下报告漏洞。切勿在公开问题中 附上私人工作簿数据、凭据或令牌。

如果 Bilig 适用于你的某项服务或 Agent 工作流， 为仓库点星，以关注版本更新， 并帮助其他 Node 开发者发现它。告诉我们还缺少哪些证明或公式。

许可证

MIT