Bilig WorkPaper

Visão Geral

O Bilig WorkPaper oferece aos agentes um ambiente de tempo de execução de "workbook" baseado em código para lógica de negócios no estilo de planilha. Use-o quando a tarefa for mais fácil de modelar como planilhas e fórmulas, mas o caminho confiável for editar células através de uma API, recalcular, ler valores computados de volta e persistir um documento de "workbook" em JSON.

O principal caso de uso é substituir a automação frágil de UI de planilha por chamadas de ferramenta determinísticas. É útil para calculadoras de cotação, modelos de pagamento, verificações de orçamento, validação de importação e redução de relatórios de bugs de fórmulas XLSX.

Quando Usar Esta Habilidade

Use esta habilidade quando o usuário precisar:

• trabalhar com fórmulas de planilha a partir de um serviço Node.js, rota, teste ou ferramenta de agente;
• escrever entradas de "workbook" e verificar saídas calculadas com prova de leitura;
• persistir um "workbook" de fórmulas como JSON de WorkPaper revisável;
• expor um "workbook" baseado em arquivo através de ferramentas MCP;
• investigar um problema de recálculo de fórmula XLSX sem automatizar Excel, LibreOffice ou uma grade de navegador.

Não o use para edição manual de planilha, VBA/macros, pivôs, gráficos, automação COM ou comportamento exato do Excel de desktop, a menos que o usuário peça explicitamente para comparar com o Excel como um oráculo.

Padrão de Comando Mais Seguro

Prefira arrays de argumentos na configuração do MCP/cliente. Não concatene shells com caminhos, nomes de planilhas, fórmulas ou endereços de células fornecidos pelo usuário. Rejeite a entrada de caminho ou célula contendo novas linhas, crases, $(, ;, &, |, < ou > antes de usá-la em um comando.

Os exemplos do MCP executam o pacote público @bilig/workpaper npm. Trate isso como execução de código de terceiros: fixe a versão do pacote que você revisou, execute-o apenas em um projeto confiável e obtenha aprovação explícita do usuário antes de iniciar um servidor MCP gravável.

Configuração Rápida do MCP

Primeiro, prove que o desafio de propriedade do pacote funciona:

{
  "command": "npm",
  "args": ["exec", "--package", "@bilig/workpaper@<reviewed-version>", "--", "bilig-mcp-challenge"]
}

Em seguida, execute um servidor MCP gravável baseado em arquivo:

{
  "command": "npm",
  "args": [
    "exec",
    "--package",
    "@bilig/workpaper@<reviewed-version>",
    "--",
    "bilig-workpaper-mcp",
    "--workpaper",
    "./pricing.workpaper.json",
    "--init-demo-workpaper",
    "--writable"
  ]
}

Ferramentas úteis expostas pelo servidor MCP:

• list_sheets
• read_range
• read_cell
• set_cell_contents
• get_cell_display_value
• export_workpaper_document
• validate_formula

Após cada gravação, leia a célula de saída dependente e exporte o documento WorkPaper. Não reivindique sucesso apenas pela chamada de gravação.

Padrão Direto de TypeScript

Use o pacote diretamente quando a lógica do "workbook" pertencer ao código da aplicação:

import {
  WorkPaper,
  exportWorkPaperDocument,
  serializeWorkPaperDocument,
} from "@bilig/workpaper";

const workbook = WorkPaper.buildFromSheets({
  Inputs: [
    ["Metric", "Value"],
    ["Customers", 20],
    ["Average revenue", 1200],
  ],
  Summary: [
    ["Metric", "Value"],
    ["Revenue", "=Inputs!B2*Inputs!B3"],
  ],
});

const inputs = workbook.getSheetId("Inputs");
const summary = workbook.getSheetId("Summary");
if (inputs === undefined || summary === undefined) {
  throw new Error("Workbook is missing required sheets");
}

workbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32);
const revenue = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 });
const saved = serializeWorkPaperDocument(
  exportWorkPaperDocument(workbook, { includeConfig: true }),
);

console.log({ revenue, savedBytes: saved.length });

Verificação Necessária

Uma boa resposta do agente deve incluir:

• nomes exatos das planilhas e células A1 editadas;
• valores anteriores para entradas importantes e saídas dependentes;
• valores posteriores lidos do "workbook" recalculado;
• evidência de persistência de JSON de WorkPaper exportado ou serializado;
• prova de restauração ou reimportação quando os limites de arquivo importam;
• limitações claras para fórmulas não suportadas ou comportamento exclusivo do Excel.

Se alguma etapa de prova falhar, relate o bloqueador em vez de dizer que o "workbook" foi atualizado.

Limitações

• O comportamento do WorkPaper não é um substituto completo para Excel de desktop, VBA, pivôs, gráficos ou automação de UI.
• A compatibilidade das fórmulas depende do tempo de execução do Bilig e deve ser verificada contra o Excel quando a paridade exata for importante.
• As gravações do MCP devem permanecer restritas a caminhos de "workbook" confiáveis e devem ser seguidas por validação de leitura.

Referências

• Repositório: https://github.com/proompteng/bilig

…