Bilig WorkPaper

Servidor MCP WorkPaper para editar pastas de trabalho de fórmulas, recalcular células e persistir o estado da pasta de trabalho com suporte a JSON.

GitHub

Experimente este MCPPatrocinado

Documentação

bilig

Execute regras de negócio em formato de pasta de trabalho dentro do Node.

O Bilig oferece a serviços, workers de fila, testes, servidores MCP e integrações de ferramentas um objeto WorkPaper tipado: escreva entradas, recalcule fórmulas, leia saídas, persista JSON, restaure e verifique. Ele se encaixa em modelos de precificação, aprovação de cotações, verificações de pagamento, validação de importação, previsões e etapas de fluxo de trabalho baseadas em fórmulas.

Execute a verificação de serviço sem projeto a partir de qualquer projeto Node:

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

Resultado esperado do serviço WorkPaper:

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

Para serviços TypeScript que devem possuir o modelo de pasta de trabalho:

npm create @bilig/workpaper@latest pricing-workpaper
cd pricing-workpaper
npm install
npm run smoke

Para clientes MCP ou outras integrações de ferramentas, execute o mesmo loop de prova através do avaliador MCP antes de adicionar configuração específica do host:

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

Exemplos de avaliadores estão em examples/bilig-evaluator-proof. Documentos de matriz de integração e arquivos de configuração específicos do host estão disponíveis quando uma equipe precisar deles, mas a prova pública começa com a leitura de retorno do serviço WorkPaper. Diagnósticos de compatibilidade de arquivos são um caminho separado para fronteiras de importação/exportação, não a história padrão de runtime.

Site do projeto: https://proompteng.github.io/bilig/

Comece Aqui

Escolha o caminho que corresponde ao trabalho:

Você tem...	Comece com	Você deve ver
Um serviço Node, rota, fila, teste ou ferramenta precisa de lógica de pasta de trabalho	Avaliador de WorkPaper para serviço Node	edição de entrada, saída recalculada, JSON serializado, verificação de restauração e `verified: true`.
Um cliente MCP ou integração de ferramenta precisa de comandos de pasta de trabalho	Avaliador de ferramenta MCP	descoberta de ferramentas, edição de célula, leitura de fórmula, exportação, verificação de reinício e `verified: true`.
Você quer um projeto inicial com o runtime instalado	Início rápido de 90 segundos para Node	um teste de fumaça de pacote local que edita uma entrada, recalcula, salva JSON e restaura o WorkPaper.
Um arquivo importado é a fronteira de integração	Relatório de Compatibilidade de Pasta de Trabalho	funções não suportadas, links externos, macros, tabelas dinâmicas, fórmulas voláteis e riscos de importação/exportação.

Se você não tem certeza de qual se encaixa, comece com a coisa que possui o estado. Use WorkPaper quando seu serviço ou ferramenta deve possuir o modelo de pasta de trabalho. Use diagnósticos de arquivo apenas quando a compatibilidade de importação/exportação for o contrato real.

Bons ajustes: precificação, aprovação de cotações, verificações de pagamento, validação de importação, previsões, fixtures de CI, etapas de fluxo de trabalho baseadas em fórmulas e integrações de ferramentas que precisam de endereços de célula exatos além de leitura de retorno. Ajustes ruins: edição manual de planilhas, macros do Office, automação de desktop do Excel ou aritmética pontual onde uma pasta de trabalho seria cerimônia.

Se Você Só Tentar Uma Coisa

Execute a prova do serviço WorkPaper no topo deste README primeiro. É a prova mais curta de que o Bilig dá ao código de backend um objeto de pasta de trabalho que ele pode alterar, recalcular, ler de volta, salvar e restaurar sem dirigir Excel, LibreOffice, Google Sheets ou uma grade de navegador.

Se um cliente MCP ou integração de ferramenta possui o fluxo de trabalho, execute a porta MCP:

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

Fronteiras de confiança:

Executa localmente em Node ou no seu runner do GitHub Actions; nenhum upload de pasta de trabalho hospedada é necessário.
Não afirma paridade com Excel. Comece com onde o Bilig ainda não é compatível com Excel antes de usá-lo para fluxos de trabalho irreversíveis.
Diagnósticos de importação/exportação de arquivos estão disponíveis quando um arquivo importado é o contrato, mas são um caminho separado do estado WorkPaper de propriedade do serviço.

Qual Caminho Devo Instalar?

Problema que você tem agora	Instale ou use	Primeira prova
O estado da pasta de trabalho de fórmulas pertence a um serviço Node, rota, fila, teste ou ferramenta	`npm install @bilig/workpaper`	Avaliador de WorkPaper para serviço Node
Um cliente MCP ou integração de ferramenta precisa de ferramentas de pasta de trabalho com leitura de retorno calculada	`npm install @bilig/workpaper`	Avaliador de ferramenta MCP
Compatibilidade de importação/exportação é a fronteira de integração	diagnósticos de compatibilidade	Relatório de Compatibilidade de Pasta de Trabalho

Adaptadores avançados ainda estão disponíveis quando a fronteira já é específica: SheetJS, ExcelJS, pastas de trabalho externas, integrações MCP/ferramentas, @bilig/workbook quando um runtime precisa de dados de plano neutros em transporte e recibos de comando, e proveniência de runtime.

Integrações MCP E De Ferramentas

Use o handoff de host WorkPaper quando um host de ferramenta precisa de leituras, gravações, recálculo, exportação JSON e prova de restauração de pasta de trabalho. A primeira verificação é sempre o avaliador MCP sem chave:

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

Esse avaliador inicia o servidor de ferramentas WorkPaper publicado, descobre ferramentas, edita uma entrada, lê a fórmula dependente, exporta JSON, reinicia, restaura e retorna verified: true. Use llms-install.md quando um host quiser um único arquivo de instalação, e use a matriz de avaliadores de host de ferramenta quando o host importar mais do que a fronteira do pacote.

O pacote publicado também carrega AGENTS.md e SKILL.md para que hosts que inspecionam node_modules/@bilig/workpaper possam encontrar a mesma prova localmente. Checkouts clonados mantêm configuração específica do host indexada no seletor de regras de agente: 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, e .opencode/agents/bilig-workpaper.md. O manifesto público é docs/.well-known/agent.json.

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. Depois use a receita que corresponde à fronteira da plataforma:

Open WebUI WorkPaper MCP: https://proompteng.github.io/bilig/open-webui-workpaper-mcp.html.
OpenAI Agents SDK com ferramentas diretas, stdio MCP ou MCPServerStreamableHttp: https://proompteng.github.io/bilig/openai-agents-sdk-workpaper-tool.html.
ChatGPT Apps WorkPaper MCP: https://proompteng.github.io/bilig/chatgpt-apps-workpaper-mcp.html.
Fluxos de trabalho auto-hospedados do n8n podem usar o pacote de nó comunitário de propriedade: @bilig/n8n-nodes-workpaper.

Escolha Um Caminho De Avaliação

Se você está avaliando...	Comece aqui	O que deve ser verdadeiro antes de adotar
Fórmulas de serviço Node	Avaliador de WorkPaper para serviço Node	Um starter escreve uma entrada, recalcula, persiste JSON, restaura e imprime `verified: true`.
Contrato de ferramenta MCP	Avaliador de workbook MCP	Descoberta de ferramenta MCP, edição de entrada, leitura de fórmula, persistência e prova de reinicialização passam.
Seletor de prova de integração	Matriz de avaliador de host de ferramenta, Servidor de ferramenta de planilha MCP e Leitura de fórmula do Vercel AI SDK	O caminho de integração começa com a menor prova verificada e evita alegações somente de escrita ou somente de UI.
Adaptadores de intenção de runtime	API de intenção de runtime de workbook	Um modelo prepara dados de plano neutros de transporte, prova de runtime estrita, recibos de comando e evidência de verificação.
Ajuste básico	Por que usar Bilig?	O problema é lógica de negócios em formato de workbook que precisa de leitura de API e persistência.
Pacote npm publicado	Início rápido de Node em 90 segundos	`@bilig/workpaper` edita uma entrada, recalcula, persiste JSON, restaura e imprime `verified: true`.
Formato de serviço backend	API de WorkPaper de aprovação de cotação	Um fluxo de trabalho realista no estilo de rota retorna leitura de fórmula e `restoredMatchesAfter: true`.
Clientes MCP e integrações de host	Manual do host de WorkPaper, Servidor de ferramenta de planilha MCP, Extensão CLI do Gemini e Pacote MCPB do Claude Desktop	O host instala um caminho de ferramenta, segue o guia de transferência e então prova escrita/leitura/persistência.
Revisão técnica de WorkPaper	Nota de prova do mantenedor de WorkPaper	Uma página compacta tem a verificação npm, ressalva de benchmark, limites conhecidos e perguntas em aberto.
Confiança e compatibilidade	Proveniência npm, Limites de compatibilidade e Relatório de Compatibilidade de Workbook	O npm mostra proveniência SLSA, e o comportamento do workbook é verificado por meio de avaliador determinístico e portões XLSX.
Arquivos importados	Relatório de Compatibilidade de Workbook, Recálculo de fórmula de arquivo e Recálculo de fórmula do ExcelJS	O limite do arquivo é inspecionado antes que um serviço, trabalho de CI ou fluxo de trabalho confie em fórmulas importadas.
Quase um ajuste	Discussão de lacuna de implementação	Nomeie a fórmula, importação/exportação, persistência, framework, MCP, pacote ou lacuna de benchmark.
Bug de fórmula ou importação	Clínica de bugs de fórmula e Envie um fixture de workbook	Compartilhe um caso público reduzido que possa se tornar um fixture.

Já tem um workbook reduzido em mãos? Se o bloqueio for uma lacuna de importação, fórmula ou persistência, gere o relatório de fixture:

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

Entregando uma tarefa de workbook a um cliente MCP ou integração de host? Comece com o guia de transferência de host antes de abrir Excel, LibreOffice, Google Sheets ou uma UI de captura de tela. Essa seção mantém o prompt de transferência de host para clientes que exigem instruções de copiar e colar. Para provar o loop MCP de propriedade do pacote sem clonar o repositório:

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

Hosts de ferramenta que suportam manifestos de habilidade podem começar por skill.md ou pelo índice conhecido em docs/.well-known/agent-skills/index.json. Usuários do Claude Desktop podem instalar o pacote MCPB lançado diretamente: https://github.com/proompteng/bilig/releases/latest/download/bilig-workpaper.mcpb. Para arquivos de projeto específicos do host, use o seletor de regras de agente.

Experimente em 90 Segundos

Isso usa o pacote npm publicado. Ele constrói um workbook, altera uma entrada, lê o valor calculado, salva JSON, restaura o workbook e imprime o mesmo valor novamente.

npm create @bilig/workpaper@latest pricing-workpaper
cd pricing-workpaper
npm install
npm run smoke

A saída esperada inclui estes campos:

{
  "before": {
    "summary": {
      "decision": "review"
    },
    "inputCells": {
      "units": "Inputs!B2",
      "listPrice": "Inputs!B3"
    }
  },
  "edit": {
    "before": {
      "decision": "review"
    },
    "after": {
      "decision": "approved"
    },
    "restored": {
      "decision": "approved"
    },
    "checks": {
      "decisionChanged": true,
      "formulasPersisted": true,
      "restoredMatchesAfter": true,
      "serializedBytes": 1242
    }
  },
  "verified": true
}

O starter gerado usa os mesmos campos de WorkPaper que o espelho público em https://proompteng.github.io/bilig/npm-eval.ts e examples/headless-workpaper/npm-eval.ts. A contagem exata de bytes pode mudar entre versões do pacote; verified: true, decisionChanged, formulasPersisted e restoredMatchesAfter são as verificações.

Para uma API de aprovação de cotação em formato de rota hoje, execute o exemplo mantido:

git clone --depth 1 https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke

Para um projeto gerado a partir de um diretório vazio, execute npm create @bilig/workpaper@latest pricing-workpaper por meio do pacote @bilig/create-workpaper. O código-fonte do pacote está em packages/create-workpaper, e o portão de publicação está documentado em criar um starter de Bilig WorkPaper. Para um projeto habilitado para MCP com arquivos de integração de host, configurações de cliente MCP e um script agent:verify, execute npm create @bilig/workpaper@latest pricing-agent -- --agent. Arquivos de host representativos incluem AGENTS.md, CLAUDE.md, GEMINI.md, .claude/skills/bilig-workpaper/SKILL.md, .cursor/rules/bilig-workpaper.mdc, .trae/mcp.json e .zed/settings.json. Para um repositório existente, execute npm create @bilig/workpaper@latest . -- --add-agent; ele adiciona Bilig MCP e instruções de host sem substituir seu modelo de aplicativo ou editar package.json. Se uma política de host já existir, ele escreve BILIG_WORKPAPER_INSTALL.md com os caminhos ignorados e um pequeno bloco de transferência.

Se essa prova quase corresponde a um serviço ou fluxo de trabalho de integração que você mantém, o próximo passo útil é um relatório de lacuna concreto em Discussões: cobertura de fórmula, persistência de serviço, configuração de MCP, writeback de agente, limite de importação/exportação ou cobertura de benchmark.

Formato da API TypeScript

A maioria das integrações é apenas isto: construir um workbook, escrever uma entrada, ler o valor calculado e salvar o estado do workbook. Quando um fluxo de trabalho escreve mais de uma entrada, use editManyAndReadback() para que as edições sejam aplicadas atomicamente e a prova compare valores de leitura tipados, saída de restauração persistida e diagnósticos de fórmula.

import { buildA1WorkPaper } from '@bilig/workpaper'

const book = buildA1WorkPaper({
  Inputs: [
    ['Metric', 'Value'],
    ['Customers', 20],
    ['Average revenue', 1200],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Revenue', '=Inputs!B2*Inputs!B3'],
  ],
})

const proof = book.editAndReadback('Inputs!B2', 32, {
  readbackRange: 'Summary!B2',
})

console.log({
  editedCell: proof.editedCell,
  revenue: proof.afterReadback.displayValues[0]?.[0],
  persistedDocumentBytes: proof.persistedDocumentBytes,
  verified: proof.verified,
})

book.dispose()

O runtime de nível inferior WorkPaper ainda é exportado para integrações de mecanismo, mas a fachada A1 é o caminho padrão de serviço e agente. Use book.set(), book.setMany(), book.readMany(), book.display() e book.saveJson() quando uma prova de leitura completa não for necessária. Use book.editManyAndReadback() quando várias entradas devem ser confirmadas e comprovadas como uma única edição atômica de workbook.

Quando Usar

Use @bilig/workpaper quando:

um serviço Node possui um cálculo em formato de workbook;
um agente precisa de ferramentas como readRange e setInputCell, com valores antes/depois calculados em vez de capturas de tela;
testes precisam de estado de planilha determinístico e leitura de fórmula;
um fluxo de trabalho precisa salvar o workbook editado como JSON e restaurá-lo depois.

Use outra coisa quando precisar de uma grade de planilha visual, macros do Office, automação de Excel para desktop ou um auxiliar de aritmética pontual. Não trate resultados de fórmula armazenados em XLSX incorporado como verdade; use o fluxo de trabalho do oráculo Excel quando a precisão for importante.

Limite do Pacote

Metadados npm atuais verificados para @bilig/workpaper@latest:

Pacote publicado: 57.7 kB descompactado, 49 entradas de pacote.
Limite: o pacote público possui starters de WorkPaper, avaliadores, wrappers de comando MCP, relatórios de clínica de fórmulas, persistência JSON e leitura restaurada.
Runtime: Node >=22.0.0; a compatibilidade com Node 22 é coberta pelo fluxo de trabalho do pacote de runtime.

Confiança no Pacote Publicado

@bilig/workpaper é publicado com assinaturas de registro npm e atestações de proveniência SLSA. Verifique a versão do pacote que você está prestes a adotar:

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

Após a instalação, o npm pode verificar a árvore de dependências atual:

npm audit signatures

O caminho de confiança do pacote atual está documentado em proveniência npm e confiança no pacote. A postura de segurança do repositório é rastreada pelo OpenSSF Scorecard e enviada para a varredura de código do GitHub em cada atualização de main.

Caminhos de Avaliação Mais Profundos

Após a primeira prova em Comece Aqui, use o guia mais profundo que corresponda ao próximo trabalho.

Execute a avaliação npm de 90 segundos em um projeto em branco.
Execute o exemplo principal da API WorkPaper serverless: npm run quote-approval-api.
Se o fluxo de trabalho começar com um arquivo de pasta de trabalho salvo, execute a recalculação de fórmulas XLSX em Node: npm start.
Se um host de ferramentas precisar de ferramentas de pasta de trabalho, comece pelo manual do host WorkPaper headless, e depois use o guia do servidor MCP quando o chamador for um cliente MCP.
Se uma pasta de trabalho real quase funcionar, comece pela clínica de bugs de fórmulas. Inclua a célula exata, o valor esperado, o valor real e a saída do comando. Se o fixture já estiver reduzido, envie o formulário de fixture estruturado para que o bloqueio possa se tornar um caso de teste, exemplo ou corpus em vez de feedback privado. https://github.com/proompteng/bilig/issues/new?template=workbook_fixture.yml. Se você ainda estiver reduzindo o caso, discuta a forma primeiro: https://github.com/proompteng/bilig/discussions/414.

O restante da documentação é um índice, não um pré-requisito.

Para detalhes de comparação e integração, use o guia de adequação em linguagem simples, limite de automação de captura de tela, limite da API do Google Sheets, Google Sheets QUERY/SORTN em Node, exemplos de automação de pasta de trabalho, a página de prova de pastas de trabalho de fórmulas, o guia do engine de fórmulas de planilha Node, automação de planilha no servidor, adaptadores de framework, clínica de bugs de fórmulas, envios de fixtures de pasta de trabalho, ferramentas do OpenAI Agents SDK, ferramenta de fórmulas do Browser Use, configuração MCP do OpenHands, configuração MCP do OpenCode, matriz de avaliador de host de ferramentas, servidor de fórmulas de planilha MCP para hosts de ferramentas, leitura de fórmulas do Vercel AI SDK, adaptador CrewAI, o manual do host WorkPaper, o guia do servidor MCP, comparação de servidores MCP de planilha, status do diretório MCP, configuração de cliente MCP, extensão Gemini CLI, pacote MCPB do Claude Desktop, proveniência npm e confiança de pacote, comparação de bibliotecas JavaScript, guia do engine de fórmulas de planilha Node, automação de planilha no servidor, recalculação de fórmulas de pasta de trabalho salva, respostas de suporte a fórmulas XLSX, limite SheetJS/ExcelJS, limite de resultado de fórmulas ExcelJS, limite Microsoft Graph Excel, e comparação de engines.

Exemplos mais aprofundados úteis: totais de fatura, alertas de variação orçamentária, plano de capacidade de atendimento, limite de aprovação de cotação, previsão de MRR de assinatura, adaptadores de framework de agente, formato de servidor de ferramentas MCP, recalculação de fórmulas XLSX em Node, e aprovação de cotação serverless. Execute npm run quote-approval-api, npm run agent:openai-agents-sdk, npm run agent:framework-adapters, npm run agent:mcp-tools, npm run agent:mcp-transcript, npm run agent:mcp-file-transcript, npm run agent:mcp-stdio, ou npm exec --package @bilig/workpaper -- bilig-workpaper-mcp quando esse for o caminho que você está avaliando.

Os diagnósticos de pasta de trabalho salva permanecem disponíveis quando um arquivo é o limite de integração:

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 --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc --demo --json
npm exec --package @bilig/sheetjs-formula-recalc@latest -- sheetjs-recalc --demo --json

O exemplo serverless também inclui npm run next-route-handler, npm run next-server-action, npm run next-server-action-formdata, npm run hono-route, npm run framework-adapters e npm run persistence-adapters para verificações de limite específicas de framework.

O servidor MCP também está listado no registro oficial: https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper. Clientes que suportam Streamable HTTP MCP também podem fazer um smoke-test do endpoint hospedado sem estado em https://bilig.proompteng.ai/mcp; use o servidor stdio local quando o agente precisar persistir um arquivo WorkPaper JSON do projeto.

Exemplos Que Você Pode Executar

Os exemplos executáveis são arquivos TypeScript. Alguns imports de código-fonte terminam em .js porque o Node ESM resolve a saída compilada do pacote dessa forma; os arquivos que você edita e executa ainda são .ts.

A partir de um checkout clonado:

pnpm --dir examples/headless-workpaper install --ignore-workspace
pnpm --dir examples/headless-workpaper run start
pnpm --dir examples/headless-workpaper run json-records
pnpm --dir examples/headless-workpaper run csv-shaped
pnpm --dir examples/headless-workpaper run invoice-totals
pnpm --dir examples/headless-workpaper run budget-variance
pnpm --dir examples/headless-workpaper run fulfillment-capacity
pnpm --dir examples/headless-workpaper run quote-approval
pnpm --dir examples/headless-workpaper run subscription-mrr
pnpm --dir examples/headless-workpaper run persistence

Os pontos de entrada mais úteis:

Para integrações de ferramentas:

pnpm --dir examples/headless-workpaper run agent:verify
pnpm --dir examples/headless-workpaper run agent:tool-call
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk-mcp
pnpm --dir examples/headless-workpaper run agent:openai-agents-sdk-hosted-mcp
pnpm --dir examples/headless-workpaper run agent:openai-responses
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:framework-adapters
pnpm --dir examples/serverless-workpaper-api run hono-route
pnpm --dir examples/headless-workpaper run agent:mcp-tools
pnpm --dir examples/headless-workpaper run agent:mcp-file-transcript
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
pnpm --dir examples/headless-workpaper run agent:mcp-stdio

O exemplo do AI SDK usa ai-sdk-generate-text-tool-smoke.ts. O guia do OpenAI Agents SDK é docs/openai-agents-sdk-workpaper-tool.md. Ele inclui encapsulamento direto de tool(), descoberta privada de MCPServerStdio e descoberta hospedada sem estado de MCPServerStreamableHttp por meio do loop de ferramentas MCP do WorkPaper. A configuração do ChatGPT Apps Developer Mode é docs/chatgpt-apps-workpaper-mcp.md. Ela mostra o endpoint público /mcp como um app MCP remoto somente de dados/ferramentas e mantém a UI de componentes do Apps SDK personalizada como escopo futuro. O guia do OpenAI Responses é docs/openai-responses-workpaper-tool-call.md. Os exemplos de framework de agente mantidos ficam em examples/headless-workpaper e são cobertos pelos seus scripts de smoke locais.

O pacote também inclui o binário MCP stdio:

npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells "Summary!B7,Inputs!B2"
npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx --workpaper ./.bilig/pricing.workpaper.json --writable
pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight
docker build --target bilig-workpaper-mcp -t bilig-workpaper-mcp:local .

bilig-agent-challenge imprime o mesmo objeto de prova de edição, leitura de fórmula, exportação de WorkPaper JSON, restauração e verified: true usado pela página de desafio de pasta de trabalho do agente.

bilig-mcp-challenge prova o caminho MCP com suporte a arquivo de ponta a ponta: inicializa JSON-RPC, lista ferramentas/recursos/prompts, edita Inputs!B3, lê Summary!B3 recalculado, exporta o WorkPaper JSON, reinicia a partir do disco e retorna verified: true.

bilig-formula-clinic importa um XLSX reduzido localmente, amostra fórmulas, lê células solicitadas por meio do WorkPaper e imprime um corpo de issue em Markdown. Ele não envia o conteúdo da pasta de trabalho.

Sem --workpaper, o binário inicia a pasta de trabalho de demonstração integrada. Com --workpaper, ele carrega seu WorkPaper JSON persistido e 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; --writable persiste edições de set_cell_contents ou set_cell_contents_and_readback de volta no mesmo arquivo. Se você já tiver um XLSX, --from-xlsx ./pricing.xlsx o importa para um servidor WorkPaper em memória para leitura, edições descartáveis e analyze_workbook_risk sem gravar um sidecar. Adicione --workpaper ... --writable somente quando o agente precisar de estado de arquivo persistido. Ele também expõe recursos e prompts MCP para bilig://workpaper/agent-handoff, bilig://workpaper/current-document, edit_and_verify_workpaper e debug_workpaper_formula, para que clientes capazes possam descobrir o fluxo de trabalho antes de chamar ferramentas. Para um transcript real-XLSX mantido, execute pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight. Ele chama analyze_workbook_risk, edita Inputs!B3, verifica alterações de Summary!B3 de 60000 para 96000, exporta WorkPaper JSON e mantém excelParity: "not_proven". O alvo Docker é para scanners de diretório MCP: ele semeia um WorkPaper JSON de demonstração dentro da imagem e inicia a superfície de ferramentas --writable com suporte a arquivo para que tools/list, resources/list e prompts/list retornem a superfície geral do agente WorkPaper sem clonar este monorepo. Para clientes MCP remotos, o runtime do app expõe https://bilig.proompteng.ai/mcp como um endpoint Streamable HTTP somente JSON sem estado para descoberta de ferramentas e smoke tests de escrita/leitura.

Ele está publicado no Registro MCP oficial como io.github.proompteng/bilig-workpaper: https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper. Ele também está ativo no Glama com Try in Browser, páginas de ferramentas com nota A e as ferramentas WorkPaper com suporte a arquivo: https://glama.ai/mcp/servers/proompteng/bilig.

Prova Que Você Pode Reproduzir

A verificação TypeScript de 90 segundos acima edita uma entrada, restaura o documento JSON salvo e verifica o resultado da fórmula dependente.
Para um caminho de avaliador de serviço, execute a prova da API WorkPaper de aprovação de cotação. Ela começa em um diretório Node vazio, baixa um smoke de rota TypeScript mantido, grava entradas de cotação, recalcula uma decisão de aprovação, persiste JSON e verifica a leitura restaurada.
Para uma página de avaliação mais curta, leia pastas de trabalho de fórmulas para serviços Node e integrações de ferramentas. Ela comprime o limite do WorkPaper, o modo MCP com suporte a arquivo, a ressalva de benchmark e a orientação de ferramentas alternativas em um único caminho de avaliação.
Para uma nota de revisão compacta, use a nota de prova do mantenedor do WorkPaper. Ela mantém juntos o comando de projeto npm vazio, a saída de verified: true, a ressalva de benchmark, os limites conhecidos e as perguntas em aberto.
Para integração de arquivo salvo, execute o exemplo de recalculação de fórmulas XLSX: examples/xlsx-recalculation-node. Ele importa uma pasta de trabalho de preços XLSX gerada, edita células de entrada, lê a decisão de aprovação recalculada, exporta XLSX, reimporta e verifica se as fórmulas sobreviveram à ida e volta. A página de decisão pública é Recalculação de fórmulas XLSX em Node.js.
Leia os limites de compatibilidade antes de importar pastas de trabalho Excel reais.
Use a lista de verificação de adoção em produção antes de promover um fluxo de trabalho com suporte do WorkPaper além da avaliação.
Para auditorias de precisão XLSX, use o harness de oráculo Excel. Ele separa sucesso de importação, timeouts, valores de pasta de trabalho em cache e resultados de recalculação do Microsoft Excel.
O servidor MCP do WorkPaper está listado no Registro MCP oficial e no Glama. A página de status do diretório mantém o comando npm, o endpoint remoto, o cartão estático do servidor MCP e as evidências do diretório em um só lugar.
Tópicos públicos de feedback: perguntas sobre fluxo de trabalho, exemplos de serviço, adaptadores de persistência, guia de biblioteca de planilhas JavaScript, chamadas de ferramentas do OpenAI Responses, e crítica de benchmark.

Se você estiver avaliando pacotes de runtime Bilig para produção e quiser notificações de lançamento, acompanhe os lançamentos: https://github.com/proompteng/bilig/subscription.

Política de Precisão XLSX

Valores de fórmula em cache incorporados em arquivos .xlsx são diagnósticos de cache, não um veredito de precisão. Um bug de correção do Bilig só deve ser relatado quando o valor esperado veio de um oráculo de recalculação Excel recente.

OUT=.cache/excel-oracle-evaluation
pnpm workpaper:xlsx-oracle -- prepare-oracle /path/to/xlsx-corpus "$OUT"
pnpm workpaper:xlsx-oracle -- evaluate-cache /path/to/xlsx-corpus "$OUT"
pnpm workpaper:xlsx-oracle -- evaluate-oracle /path/to/xlsx-corpus "$OUT/recalculated" "$OUT"
pnpm workpaper:xlsx-oracle -- summarize "$OUT"

evaluate-cache grava cache-diagnostic.json e permanece não autoritativo. evaluate-oracle grava excel-oracle-report.json e summarize grava summary.md. Se a automação do Excel não estiver disponível, as células são classificadas como missing_excel_oracle em vez de serem promovidas a bugs.

O Que Há Neste Repositório

packages/workpaper: pacote público do WorkPaper, starters, binários de avaliador e wrappers MCP.
packages/headless: runtime WorkPaper de nível mais baixo que dá suporte ao pacote público.
packages/excel-import: limite de importação/exportação de pasta de trabalho salva.
packages/formula: parser de fórmulas, binder, compilador e avaliador.
packages/core: engine de pasta de trabalho, snapshots, fluxo de mutação e agendador.
packages/grid e apps/web: shell de planilha para navegador.
apps/bilig: runtime monolítico fullstack, superfície de API e servidor de assets estáticos.
packages/renderer: renderizador de pasta de trabalho React.
packages/protocol, packages/binary-protocol, packages/agent-api e packages/worker-transport: limites de protocolo e integração.
packages/wasm-kernel: caminho rápido numérico AssemblyScript/WASM.
packages/benchmarks: harness de benchmark e contratos de desempenho.

Para importação/exportação XLSX a partir de TypeScript:

import { WorkPaper } from '@bilig/workpaper'
import { exportXlsx, importXlsx } from '@bilig/workpaper/xlsx'

Use WorkPaper.buildFromSnapshot(imported.snapshot) após a importação e workbook.exportSnapshot() antes de exportXlsx().

Desenvolvimento Local

Use Node 24+, Bun e pnpm@10.32.1.

pnpm install
pnpm dev:web
pnpm dev:web-local
pnpm dev:sync

Para uma verificação local completa:

pnpm lint
pnpm typecheck
pnpm test
pnpm test:browser
pnpm run ci

Fontes geradas e documentação pública determinística são verificadas:

pnpm protocol:check
pnpm formula-inventory:check
pnpm workspace-resolution:check
pnpm docs:discovery:check

Para Agentes de Codificação

Comece pelo limite do pacote público, a menos que a tarefa seja explicitamente trabalho de motor.

Leia packages/workpaper/README.md antes de tocar no comportamento público do WorkPaper.
Leia docs/AGENTS.md, docs/skill.md ou docs/llms-full.txt ao construir uma integração voltada para agentes de fora do repositório.
Use exportações públicas de @bilig/workpaper; não acesse src/ ou dist/ ao escrever exemplos para consumidores.
Mantenha os exemplos em TypeScript primeiro.
Não trate resultados de fórmulas armazenadas em XLSX embutido como uma fonte de precisão.
Adicione testes focados antes de alterar fórmulas, persistência, limites de intervalo, reconstruções de configuração, eventos, movimentos de linhas/colunas ou ciclo de vida de planilhas.
Execute primeiro os testes focados do pacote e depois amplie para pnpm run ci.

Contribuindo

Leia CONTRIBUTING.md antes de abrir um PR. Se este for o seu primeiro patch, comece pelo guia para novos contribuidores e depois reivindique uma issue inicial escopada.

Bons primeiros patches geralmente se encaixam em uma destas formas:

fixtures de fórmulas com comportamento esperado claro;
pequenos exemplos de WorkPaper que comprovam um serviço real ou fluxo de agente;
correções focadas de correção com testes de regressão;
melhorias de acessibilidade de grade e comportamento de teclado;
documentação que transforma uma nota de arquitetura existente em um comando executável.

O caminho público mais curto é a fila starter issues. Ela mantém seleções de código/testes, tarefas de exemplo, adaptadores e trabalho de documentação focada em uma lista atual, com pequenos comandos de aceitação para primeiros patches.

Se esta for a sua primeira contribuição para bilig, use o filtro first-timers-only.

Segurança e Suporte

Leia SECURITY.md antes de compartilhar detalhes de vulnerabilidades, dados privados de pastas de trabalho, tokens, credenciais ou reproduções de exploração. Relatórios de segurança devem usar o relatório privado de vulnerabilidades do GitHub quando disponível, ou security@proompteng.ai quando o fluxo privado não estiver visível.

Use SUPPORT.md para o caminho de suporte público mais rápido. Bons relatórios incluem a versão do pacote, versão do Node, SO, fórmula exata ou entrada de pasta de trabalho, valor esperado, valor real e o menor comando ou script que reproduz o problema.

CI

Forgejo Actions é a principal superfície de CI via .forgejo/workflows/forgejo-ci.yml. GitHub Actions espelha o contrato de verificação em .github/workflows/ci.yml.

O portão rigoroso inclui instalação com lockfile congelado, pnpm run ci completo, verificações de orçamento de artefatos, smoke de navegador e verificações de limpeza de arquivos rastreados.

Licença

MIT.