Bilig WorkPaper

Bilig

ワークブックモデルはそのままに、Node でルールを実行します。

Bilig は、Node.js サービス、テスト、AI エージェント向けの、TypeScript ネイティブなヘッドレス WorkPaper ランタイムです。入力を設定し、数式を再計算して計算結果を読み取り、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 をお選びください。

エージェントと MCP

エージェントはまず、どのシステムが状態を管理しているかを確認し、該当する最小限の検証を実行してください。ツールホストまたは 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 も含まれているため、エージェントは 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 との完全な互換性を証明するものとして扱わないでください。

例と詳細ガイド

モノレポ全体ではなく、メンテナンスされている例を 1 つ選んで始めてください。

• examples/headless-workpaper：価格設定、 請求書、予算、フルフィルメント、サブスクリプション、永続化、エージェントの例。
• examples/serverless-workpaper-api： Hono、Next.js、永続化アダプターを使った見積もり承認。
• examples/xlsx-recalculation-node：XLSX ワークブックのインポート、 再計算、エクスポート、再インポート、検証。
• examples/recalc-bridge-workflows：既存の SheetJS、xlsx-populate、ExcelJS のワークフロー向けの 目的を絞ったブリッジ。

参考になる選択ガイド：

• 数式ワークブックの証明ページ
• エージェント評価マトリクス
• コーディングエージェント向け 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

最初のコマンドは、同梱のデモを使ったパッケージのスモークテストです。次の 2 つのコマンドでは、 指定したファイルを調べます。互換性レポートでは、未対応の関数、外部リンク、 マクロ、ピボットテーブル、揮発性数式、その他のリスクを特定しますが、 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

開発

長時間実行する開発サーバーを 1 つ選択してください。

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で確認できます。
• 再現可能なバグは Issuesから報告してください。縮小したワークブックは、 数式バグ相談窓口や フィクスチャフォームをご利用いただけます。
• 報告を対応可能にするための証拠については SUPPORT.md をお読みください。
• 脆弱性を非公開で報告する場合は SECURITY.md に従ってください。公開 Issue に 非公開のワークブックデータ、認証情報、トークンを添付しないでください。

Bilig がサービスやエージェントのワークフローに適している場合は、 リポジトリにスターを付けて、リリースをチェックし、 ほかの Node 開発者にも見つけてもらえるようご協力ください。まだ不足している証拠や数式があれば、 ぜひお知らせください。

ライセンス

MIT