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 分