Bilig WorkPaper

io.github.proompteng由 GitHub 账号 proompteng 发布v1.1.0更新于 Oct 25, 2026

Formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence.

已验证Streamable HTTP可网页运行开发者工具数据与分析

概览

AI 生成的概览

一个无界面的 WorkPaper 运行时,让助手读取、编辑并重算基于公式的工作簿单元格,并把工作簿导出为 JSON。

可以做什么
列出工作表名称及已用区域,便于读取或编辑前了解结构。读取单个单元格或 A1 区域,返回计算值、显示文本、公式与诊断信息。向单元格写入原始内容并重算依赖项,可在同一次调用中回读依赖区域。获取用户实际看到的格式化显示值。在写入前校验公式语法。导出当前 WorkPaper JSON 文档,用于持久化或交接。
适用场景
适合由服务、测试或智能体自行持有定价、报价、付款或预测等基于公式的模型,而不必驱动 Excel 或浏览器表格。也适合需要带前后对比回读和 JSON 持久化的可验证编辑流程。
运行要求
可使用托管远程端点,或通过 stdio 运行 npm 包 @bilig/workpaper 的本地进程。本地方式需要 Node.js 24 或更高版本,并以 WorkPaper 文件路径启动;若编辑需持久化到 JSON,需启用可写模式。未声明认证、环境变量或请求头。
安装前请注意
托管端点仅按请求处理,只用于无状态连接器发现和冒烟测试,不要向其发送私有工作簿数据。私有或需持久化的状态应使用本地 stdio 方式。写入会重算依赖项,且仅在可写模式下持久化到 JSON。项目声明并非完全兼容 Excel,正确性重要时应与 Excel 重新计算的工作簿比对。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Bilig WorkPaper,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.proompteng%2Fbilig-workpaper/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "bilig-workpaper": {
      "type": "http",
      "url": "https://bilig.proompteng.ai/mcp"
    }
  }
}

README

Bilig

[CI] [npm] [Node.js] [OpenSSF Scorecard] [License: MIT]

Keep the workbook model. Run the rule in Node.

Bilig is a TypeScript-native, headless WorkPaper runtime for Node.js services, tests, and AI agents. Set inputs, recalculate formulas, read computed outputs, persist WorkPaper JSON, restore it, and verify the result—without driving Excel or a browser grid.

Docs · Quick start · TypeScript API · MCP · Examples · Discussions

[A WorkPaper input edit recalculating a formula, then surviving JSON restore]

[!NOTE] Bilig is a headless workbook runtime, not a visual spreadsheet app or a claim of full Excel compatibility. If an .xlsx file is your contract, start with the compatibility report.

Quick Start

Node runtime

Prove the published package before installing it:

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

The evaluator edits Inputs!B2, recalculates Summary!B2, saves the WorkPaper, restores it, and compares the restored value:

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

verified: true means the write, formula readback, JSON export, and restored readback all passed. It is stronger evidence than a successful write call.

Use It From TypeScript

sh
npm install @bilig/workpaper
ts
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]) // 38400console.log(proof.verified) // true
pricing.dispose()

For ordinary operations, use set(), setMany(), readMany(), display(), and saveJson(). Use editManyAndReadback() when multiple inputs must be committed and verified as one edit. The complete public API is documented in packages/workpaper/README.md.

The lifecycle is deliberately small:

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

Why Bilig

CapabilityWhat it gives you
Workbook-shaped modelsSheets, A1 addresses, formulas, ranges, and named expressions without a spreadsheet UI.
Verified mutationsBefore/after computed values plus persistence and restore checks.
Service-owned statePortable WorkPaper JSON for routes, queues, tests, tools, and audit trails.
Agent-safe toolsNarrow read/write tools with exact cells, computed readback, and writable-sheet boundaries.
Explicit file boundariesSeparate XLSX import, export, risk inspection, and Excel-oracle workflows.

Use Bilig for pricing, quote approval, payouts, forecasts, validation rules, formula-backed workflows, and tests where a service or tool should own the model. Choose a spreadsheet application or hosted spreadsheet API when you need visual editing, collaboration, macros, interactive pivots or charts, or desktop fidelity.

Agents And MCP

Agents should first ask which system owns state, then run the smallest matching proof. For a tool host or MCP client:

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

The MCP evaluator proves tool discovery, mutation, recalculated readback, JSON export, disk persistence, process restart, and restored readback. For a local, writable WorkPaper:

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

Use that local stdio path for private or persistent project state. The hosted https://bilig.proompteng.ai/mcp endpoint is request-local and only intended for stateless connector discovery and smoke tests; do not send private workbook data to it.

The server exposes list_sheets, read_range, read_cell, set_cell_contents, set_cell_contents_and_readback, get_cell_display_value, export_workpaper_document, and validate_formula. It also publishes MCP resources and prompts so capable hosts can discover the workflow before editing cells.

Machine-readable entry points:

NeedEntry point
A compact routing carddocs/agent-start.txt
A concise model indexdocs/llms.txt
Full agent documentationdocs/llms-full.txt
Installation contextdocs/llms-install.md
Structured capabilitiesdocs/agent.json
Reusable skillskills/bilig-workpaper/SKILL.md
Proof and host matrixdocs/agent-adoption-kit.md

The published package also carries AGENTS.md and SKILL.md, so an agent can discover the same proof contract from node_modules. Install or inspect the public skill with either source:

sh
npx --yes skills@latest add https://bilig.proompteng.ai --listnpx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list
Host-specific project files

Use the agent rule chooser or the host handoff prompt. The repository includes 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, and .opencode/agents/bilig-workpaper.md.

Integration Recipes After The Proof

Run an evaluator first, then use the recipe owned by your host:

  • OpenAI Agents SDK: direct tools, MCPServerStdio, and MCPServerStreamableHttp.
  • OpenAI Responses API: function-call readback with explicit before/after evidence.
  • Vercel AI SDK: generateText() and streamText() tool loops.
  • Open WebUI: local or hosted MCP discovery.
  • n8n: the @bilig/n8n-nodes-workpaper community node.

Choose An Evaluation Path

Your state ownerStart hereEvidence to require
TypeScript applicationnpm install @bilig/workpaperdirect A1 API and focused application tests
Node service, route, queue, or testbilig-evaluate --door workpaper-service --jsonedit, recalculation, JSON export, restore, verified: true
MCP client or tool hostbilig-evaluate --door agent-mcp --jsondiscovery, readback, disk persistence, restart
Imported .xlsx is the contractworkbook-compatibility-report workbook.xlsx --jsonunsupported formulas and workbook risk reasons for that file
Cached .xlsx values look stalexlsx-cache-doctor workbook.xlsx --jsonstale-cache diagnosis, recalculation, and readback for that file

The workbook-compatibility and xlsx-cache evaluator doors use bundled demo workbooks to smoke-test the published package; they do not inspect your file. Do not treat any evaluator as proof of desktop Excel parity.

Examples And Deeper Guides

Start with one maintained example, not the whole monorepo:

Useful decision guides:

Runnable integration and diagnostic commands
sh
pnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-textpnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-textpnpm --dir examples/headless-workpaper run agent:openai-responsespnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflightpnpm --dir examples/serverless-workpaper-api run hono-routepnpm --dir examples/serverless-workpaper-api run next-server-actionpnpm --dir examples/serverless-workpaper-api run next-server-action-formdata

The AI SDK generateText() smoke lives at ai-sdk-generate-text-tool-smoke.ts. The OpenAI example is documented in openai-responses-workpaper-tool-call.

For a reduced formula or import bug:

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

XLSX And Excel Compatibility

Bilig can import and export workbook files, but cached formula values inside an .xlsx are diagnostics—not an accuracy oracle. Inspect the file before trusting it:

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

The first command is a package smoke test over a bundled demo. The next two inspect the named file. The compatibility report identifies unsupported functions, external links, macros, pivots, volatile formulas, and other risks; it does not certify Excel compatibility. When correctness matters, compare against a workbook freshly recalculated by Excel. See the compatibility limits and Excel oracle walkthrough.

Packages And Repository Map

PathRole
packages/workpaperRecommended @bilig/workpaper API, evaluators, AI SDK adapter, MCP server, and XLSX boundary.
packages/xlsx-formula-recalcReal-file compatibility and stale-cache diagnostics.
packages/formulaFormula parser, binder, compiler, and evaluator.
packages/coreWorkbook state, mutations, snapshots, and scheduling.
apps/webBrowser spreadsheet shell.
apps/biligFull-stack runtime, APIs, and static site host.

The public WorkPaper package requires Node.js >=24. Local monorepo development uses Node.js 24+, Bun, and [email protected].

Published releases include npm registry signatures and provenance attestations:

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

Development

Choose one long-running development server:

sh
pnpm dev:webpnpm dev:web-local

Install and validate the repository with:

sh
pnpm installpnpm buildpnpm lintpnpm typecheckpnpm testpnpm run ci

Architecture lives in docs/architecture.md. Read CONTRIBUTING.md before opening a pull request; first-time contributors can start with the new contributor guide and starter issues. All participation follows the CODE_OF_CONDUCT.md.

Support And Security

If Bilig fits one of your services or agent workflows, star the repository to follow releases and help other Node developers find it. Tell us what proof or formula is still missing.

License

MIT

来源:README.md,提交 49db26b

工具

8

list_sheets

List WorkPaper Sheets

Discover sheet names and used dimensions before reading or editing a WorkPaper. Returns metadata only; use read_range or read_cell for values.

无需输入参数。

read_range

Read WorkPaper Range

Read calculated values plus serialized formulas/inputs for an A1 range. Use for audit readback after edits; use read_cell for one address.

输入参数range必填sheetName

read_cell

Read WorkPaper Cell

Read one cell with calculated value, display text, formula text, formula diagnostics, and serialized content. Use after set_cell_contents to verify readback.

输入参数address必填sheetName必填

set_cell_contents

Set WorkPaper Cell Contents

Write raw content to one cell and recalculate dependents in memory only. Start with --writable when the edit should persist to JSON.

输入参数value必填address必填sheetName必填

set_cell_contents_and_readback

Set WorkPaper Cell Contents And Read Back

Write raw content to one cell, recalculate dependents, read a dependent range in the same tool call, and return persistence proof. Use this for stateless MCP clients such as hosted Open WebUI integrations.

输入参数value必填address必填sheetName必填readbackRange必填readbackSheetName

get_cell_display_value

Get WorkPaper Cell Display Value

Return the formatted display string for one cell. Use when an agent needs what a user would see, not the raw numeric value.

输入参数address必填sheetName必填

export_workpaper_document

Export WorkPaper Document

Export the current WorkPaper JSON document for persistence, review, or handoff to another agent. Does not write files by itself.

输入参数includeConfig

validate_formula

Validate WorkPaper Formula

Validate formula syntax with the WorkPaper parser before writing it to a cell. This checks syntax only; use set_cell_contents plus readback to evaluate.

输入参数formula必填

版本历史

2
  1. v1.1.0最新Oct 4, 2026
  2. v0.164.11Sep 16, 2026

评分

已满足适用检查项的 100%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分