Bilig WorkPaper

Bilig

Mantenha o modelo de workbook. Execute a regra no Node.

Bilig é um runtime de WorkPaper headless, nativo em TypeScript, para serviços Node.js, testes e agentes de IA. Defina entradas, recalcule fórmulas, leia saídas calculadas, persista o JSON do WorkPaper, restaure-o e verifique o resultado—sem acionar o Excel ou uma grade de navegador.

Docs · Início rápido · API TypeScript · MCP · Exemplos · Discussões

[!NOTE] Bilig é um runtime de workbook headless, não um aplicativo de planilha visual ou uma alegação de compatibilidade total com Excel. Se um arquivo .xlsx for seu contrato, comece com o relatório de compatibilidade.

Início Rápido

Prove o pacote publicado antes de instalá-lo:

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

O avaliador edita Inputs!B2, recalcula Summary!B2, salva o WorkPaper, restaura-o e compara o valor restaurado:

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

verified: true significa que a gravação, a leitura da fórmula, a exportação JSON e a leitura restaurada passaram. É uma evidência mais forte do que uma chamada de gravação bem-sucedida.

Use a Partir do 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();

Para operações comuns, use set(), setMany(), readMany(), display(), e saveJson(). Use editManyAndReadback() quando várias entradas precisarem ser confirmadas e verificadas como uma única edição. A API pública completa está documentada em packages/workpaper/README.md.

O ciclo de vida é deliberadamente pequeno:

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

Por que Bilig

Use Bilig para preços, aprovação de cotações, pagamentos, previsões, regras de validação, fluxos de trabalho baseados em fórmulas e testes em que um serviço ou ferramenta deve ser o dono do modelo. Escolha um aplicativo de planilha ou uma API de planilha hospedada quando precisar de edição visual, colaboração, macros, tabelas dinâmicas ou gráficos interativos, ou fidelidade de desktop.

Agentes e MCP

Os agentes devem primeiro perguntar qual sistema é o dono do estado e, em seguida, executar a menor prova correspondente. Para um host de ferramentas ou cliente 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

O avaliador MCP prova a descoberta de ferramentas, mutação, leitura recalculada, exportação JSON, persistência em disco, reinicialização do processo e leitura restaurada. Para um WorkPaper local e gravável:

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

Use esse caminho stdio local para estado de projeto privado ou persistente. O endpoint hospedado https://bilig.proompteng.ai/mcp é local à solicitação e destinado apenas à descoberta de conectores sem estado e testes de fumaça; não envie dados de workbook privados para ele.

O servidor expõe list_sheets, read_range, read_cell, set_cell_contents, set_cell_contents_and_readback, get_cell_display_value, export_workpaper_document e validate_formula. Ele também publica recursos e prompts MCP para que hosts capazes possam descobrir o fluxo de trabalho antes de editar células.

Pontos de entrada legíveis por máquina:

O pacote publicado também carrega AGENTS.md e SKILL.md, para que um agente possa descobrir o mesmo contrato de prova a partir de node_modules. Instale ou inspecione a habilidade pública com qualquer uma das fontes:

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

Receitas de Integração Após a Prova

Execute um avaliador primeiro e, em seguida, use a receita de propriedade do seu host:

• OpenAI Agents SDK: ferramentas diretas, MCPServerStdio e MCPServerStreamableHttp.
• OpenAI Responses API: leitura de chamada de função com evidência explícita de antes/depois.
• Vercel AI SDK: loops de ferramentas generateText() e streamText().
• Open WebUI: descoberta MCP local ou hospedada.
• n8n: o nó da comunidade @bilig/n8n-nodes-workpaper.

Escolha um Caminho de Avaliação

As portas de avaliador workbook-compatibility e xlsx-cache usam workbooks de demonstração agrupados para testar o pacote publicado; elas não inspecionam seu arquivo. Não trate nenhum avaliador como prova de paridade com o Excel de desktop.

Exemplos e Guias Mais Aprofundados

Comece com um exemplo mantido, não com o monorepo inteiro:

• examples/headless-workpaper: preços, fatura, orçamento, atendimento, assinatura, persistência e exemplos de agentes.
• examples/serverless-workpaper-api: aprovação de cotações por meio de Hono, Next.js e adaptadores de persistência.
• examples/xlsx-recalculation-node: importar, recalcular, exportar, reimportar e verificar um workbook XLSX.
• examples/recalc-bridge-workflows: pontes focadas para fluxos de trabalho existentes de SheetJS, xlsx-populate e ExcelJS.

Guias de decisão úteis:

• Página de prova de workbooks de fórmula
• Matriz de avaliadores de agentes
• Servidor de planilha MCP para agentes de codificação
• Leitura de fórmula do Vercel AI SDK
• Chamadas de ferramentas do OpenAI Responses
• Limite de resultado de fórmula do ExcelJS
• Google Sheets QUERY e SORTN
• Limite do Excel do Microsoft Graph
• Respostas de suporte a fórmulas XLSX
• Lista de verificação de adoção em produção

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"

Compatibilidade com XLSX e Excel

Bilig pode importar e exportar arquivos de workbook, mas os valores de fórmula em cache dentro de um .xlsx são diagnósticos—não um oráculo de precisão. Inspecione o arquivo antes de confiar nele:

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

O primeiro comando é um teste de fumaça do pacote sobre uma demonstração agrupada. Os próximos dois inspecionam o arquivo nomeado. O relatório de compatibilidade identifica funções não suportadas, links externos, macros, tabelas dinâmicas, fórmulas voláteis e outros riscos; ele não certifica compatibilidade com Excel. Quando a correção for importante, compare com um workbook recém-recalculado pelo Excel. Consulte os limites de compatibilidade e o passo a passo do oráculo Excel.

Pacotes e Mapa do Repositório

O pacote público requer Node.js >=22. O desenvolvimento local do monorepo usa Node.js 24+, Bun e pnpm@10.32.1.

As versões publicadas incluem assinaturas de registro npm e atestados de proveniência:

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

Desenvolvimento

Escolha um servidor de desenvolvimento de longa duração:

pnpm dev:web
pnpm dev:web-local

Instale e valide o repositório com:

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

A arquitetura está em docs/architecture.md. Leia CONTRIBUTING.md antes de abrir um pull request; contribuidores de primeira viagem podem começar com o guia para novos contribuidores e issues iniciais. Toda participação segue o CODE_OF_CONDUCT.md.

Suporte e Segurança

• Faça perguntas sobre adoção e design em Discussões.
• Acompanhe mudanças versionadas por meio de GitHub Releases.
• Relate bugs reproduzíveis por meio de Issues; workbooks reduzidos podem usar o clínica de bugs de fórmula e o formulário de fixture.
• Leia SUPPORT.md para a evidência que torna um relatório acionável.
• Siga SECURITY.md para relatórios privados de vulnerabilidade. Nunca anexe dados de workbook privados, credenciais ou tokens a um issue público.

Se Bilig se encaixar em um dos seus serviços ou fluxos de trabalho de agentes, marque o repositório com estrela para acompanhar as versões e ajudar outros desenvolvedores Node a encontrá-lo. Conte-nos qual prova ou fórmula ainda está faltando.

Licença

MIT