Bilig 是一个 TypeScript 原生的无头 WorkPaper 运行时（headless WorkPaper runtime），面向 Node.js 服务、测试和 AI 代理。它的核心思路是：保留工作簿模型，但在 Node 中运行规则，而不必驱动 Excel 或浏览器表格。
一、用途与定位 Bilig 用于让服务或工具拥有工作簿模型：设置输入、重新计算公式、读取计算输出、持久化 WorkPaper JSON、恢复该 JSON，并验证结果。它明确说明自己不是可视化电子表格应用，也不声称完全兼容 Excel。如果 .xlsx 文件是必须遵守的契约，应先从兼容性报告入手。
二、主要能力 根据资料，Bilig 的生命周期被定义为：输入 → 公式重新计算 → 有类型读回 → JSON 持久化 → 恢复验证。 公开的 TypeScript API 包括 set()、setMany()、readMany()、display() 和 saveJson()。当需要将多个输入作为一次编辑提交并验证时，使用 editManyAndReadback()。完整公开 API 记录在 packages/workpaper/README.md 中。 通过 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 资源和提示（prompts），让支持的主机在编辑单元格前发现工作流。 Bilig 可以导入和导出工作簿文件，但 .xlsx 中的公式缓存值只是诊断信息，不是准确性依据。兼容性报告可识别不支持的函数、外部链接、宏、数据透视表、易变公式等风险，但不认证 Excel 兼容性。
三、使用方式
- 在安装前验证已发布包：资料提到评估器会编辑 Inputs!B2、重新计算 Summary!B2、保存 WorkPaper、恢复它并比较恢复后的值。verified: true 表示写入、公式读回、JSON 导出和恢复读回全部通过。
- 从 TypeScript 使用：常规操作使用 set()、setMany()、readMany()、display()、saveJson()；多个输入需作为一次编辑提交并验证时使用 editManyAndReadback()。
- 通过 MCP 使用：对于本地可写的 WorkPaper，使用本地 stdio 路径；适用于私有或持久化的项目状态。托管端点 https://bilig.proompteng.ai/mcp 是请求局部的，仅用于无状态连接器发现和冒烟测试，不要向它发送私有工作簿数据。
- Agent 集成：仓库包含 AGENTS.md 和 SKILL.md，代理可从 node_modules 中发现相同的证明契约。还提供 CLAUDE.md、.claude/skills/bilig-workpaper/SKILL.md、.claude/commands/bilig-workpaper-proof.md、.cursor/rules/bilig-workpaper.mdc、.devin/rules/bilig-workpaper.md、.windsurf/rules/bilig-workpaper.md、.clinerules/bilig-workpaper.md、.continue/rules/bilig-workpaper.md、.zed/settings.json、opencode.jsonc、.opencode/agents/bilig-workpaper.md 等文件。可通过 agent rule chooser 或 host handoff prompt 使用。
- 集成配方：先运行评估器，然后使用对应主机的配方，包括 OpenAI Agents SDK（直接工具、MCPServerStdio、MCPServerStreamableHttp）、OpenAI Responses API（带显式前后证据的函数调用读回）、Vercel AI SDK（generateText() 和 streamText() 工具循环）、Open WebUI（本地或托管 MCP 发现）、n8n（@bilig/n8n-nodes-workpaper 社区节点）。
- 示例：examples/headless-workpaper（定价、发票、预算、履约、订阅、持久化和代理示例）、examples/serverless-workpaper-api（通过 Hono、Next.js 和持久化适配器进行报价审批）、examples/xlsx-recalculation-node（导入、重算、导出、重新导入并验证 XLSX 工作簿）、examples/recalc-bridge-workflows（面向现有 SheetJS、xlsx-populate 和 ExcelJS 工作流的桥接）。
- 运行环境：公开的 WorkPaper 包要求 Node.js >=24。本地 monorepo 开发使用 Node.js 24+、Bun 和 pnpm@10.32.1。已发布版本包含 npm registry 签名和来源证明。
四、适用场景 资料建议将 Bilig 用于定价、报价审批、支出、预测、校验规则、公式驱动的工作流，以及服务或工具应拥有模型的测试。当你需要可视化编辑、协作、宏、交互式数据透视表或图表，或桌面级保真度时，应选择电子表格应用或托管电子表格 API。
五、限制 Bilig 是无头工作簿运行时，不是可视化电子表格应用，也不宣称完全兼容 Excel。.xlsx 内的公式缓存值只是诊断信息，不是准确性依据。工作簿兼容性和 xlsx-cache 评估器使用打包的演示工作簿对已发布包进行冒烟测试，不会检查你的文件；不应将任何评估器视为桌面 Excel 一致性的证明。正确性重要时，应与由 Excel 重新计算的工作簿进行比较。
六、支持与安全 采用和设计问题可在 Discussions 提出；版本化变更见 GitHub Releases；可复现错误通过 Issues 报告，简化工作簿可使用 formula bug clinic 和 fixture form；报告可操作性证据见 SUPPORT.md；私有漏洞报告见 SECURITY.md。切勿在公开 issue 中附加私有工作簿数据、凭据或令牌。
（注：资料中多处提及“命令”与“评估器运行方式”，但未给出可直接照抄的完整安装命令或代码内容，故按原文保留相关描述，未编造具体命令。）
