Bilig WorkPaper

Bilig

Mantén el modelo de libro de trabajo. Ejecuta la regla en Node.

Bilig es un runtime de WorkPaper sin interfaz gráfica, nativo de TypeScript, para servicios Node.js, pruebas y agentes de IA. Establece entradas, recalcula fórmulas, lee salidas calculadas, persiste el JSON del WorkPaper, restáuralo y verifica el resultado—sin necesidad de usar Excel o una cuadrícula de navegador.

Documentación · Inicio rápido · API de TypeScript · MCP · Ejemplos · Discusiones

[!NOTA] Bilig es un runtime de libro de trabajo sin interfaz gráfica, no una aplicación de hoja de cálculo visual ni una afirmación de compatibilidad total con Excel. Si un archivo .xlsx es tu contrato, comienza con el informe de compatibilidad.

Inicio Rápido

Prueba el paquete publicado antes de instalarlo:

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

El evaluador edita Inputs!B2, recalcula Summary!B2, guarda el WorkPaper, lo restaura y compara el 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 la escritura, la lectura de la fórmula, la exportación JSON y la lectura restaurada pasaron todas. Es una evidencia más sólida que una llamada de escritura exitosa.

Úsalo desde 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 operaciones ordinarias, usa set(), setMany(), readMany(), display() y saveJson(). Usa editManyAndReadback() cuando múltiples entradas deban confirmarse y verificarse como una sola edición. La API pública completa está documentada en packages/workpaper/README.md.

El ciclo de vida es deliberadamente pequeño:

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

Por Qué Bilig

Usa Bilig para precios, aprobación de cotizaciones, pagos, pronósticos, reglas de validación, flujos de trabajo respaldados por fórmulas y pruebas donde un servicio o herramienta deba ser dueño del modelo. Elige una aplicación de hoja de cálculo o una API de hoja de cálculo alojada cuando necesites edición visual, colaboración, macros, tablas dinámicas o gráficos interactivos, o fidelidad de escritorio.

Agentes Y MCP

Los agentes deben primero preguntar qué sistema es dueño del estado, luego ejecutar la prueba más pequeña que coincida. Para un host de herramientas o 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

El evaluador MCP demuestra el descubrimiento de herramientas, la mutación, la lectura recalculada, la exportación JSON, la persistencia en disco, el reinicio del proceso y la lectura restaurada. Para un WorkPaper local y escribible:

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

Usa esa ruta stdio local para estado de proyecto privado o persistente. El endpoint alojado https://bilig.proompteng.ai/mcp es local a la solicitud y solo está destinado al descubrimiento de conectores sin estado y pruebas de humo; no envíes datos de libros de trabajo privados a él.

El servidor expone list_sheets, read_range, read_cell, set_cell_contents, set_cell_contents_and_readback, get_cell_display_value, export_workpaper_document y validate_formula. También publica recursos y avisos de MCP para que los hosts capaces puedan descubrir el flujo de trabajo antes de editar celdas.

Puntos de entrada legibles por máquina:

El paquete publicado también incluye AGENTS.md y SKILL.md, para que un agente pueda descubrir el mismo contrato de prueba desde node_modules. Instala o inspecciona la habilidad pública con cualquiera de las fuentes:

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

Recetas De Integración Después De La Prueba

Ejecuta un evaluador primero, luego usa la receta propiedad de tu host:

• OpenAI Agents SDK: herramientas directas, MCPServerStdio y MCPServerStreamableHttp.
• OpenAI Responses API: lectura de llamadas a funciones con evidencia explícita antes/después.
• Vercel AI SDK: bucles de herramientas generateText() y streamText().
• Open WebUI: descubrimiento MCP local o alojado.
• n8n: el nodo comunitario @bilig/n8n-nodes-workpaper.

Elige Una Ruta De Evaluación

Las puertas de evaluador workbook-compatibility y xlsx-cache usan libros de demostración incluidos para probar el paquete publicado; no inspeccionan tu archivo. No trates ningún evaluador como prueba de paridad con Excel de escritorio.

Ejemplos Y Guías Más Profundas

Comienza con un ejemplo mantenido, no con todo el monorepo:

• examples/headless-workpaper: precios, facturas, presupuestos, cumplimiento, suscripciones, persistencia y ejemplos de agentes.
• examples/serverless-workpaper-api: aprobación de cotizaciones a través de Hono, Next.js y adaptadores de persistencia.
• examples/xlsx-recalculation-node: importar, recalcular, exportar, reimportar y verificar un libro XLSX.
• examples/recalc-bridge-workflows: puentes enfocados para flujos de trabajo existentes de SheetJS, xlsx-populate y ExcelJS.

Guías de decisión útiles:

• Página de prueba de libros de fórmulas
• Matriz de evaluadores de agentes
• Servidor de hojas de cálculo MCP para agentes de codificación
• Lectura de fórmulas con Vercel AI SDK
• Llamadas a herramientas de OpenAI Responses
• Límite de resultados de fórmulas de ExcelJS
• Google Sheets QUERY y SORTN
• Límite de Excel de Microsoft Graph
• Respuestas de soporte de fórmulas XLSX
• Lista de verificación de adopción en producción

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"

Compatibilidad Con XLSX Y Excel

Bilig puede importar y exportar archivos de libro de trabajo, pero los valores de fórmula en caché dentro de un .xlsx son diagnósticos—no un oráculo de precisión. Inspecciona el archivo antes de confiar en él:

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

El primer comando es una prueba de humo del paquete sobre una demostración incluida. Los dos siguientes inspeccionan el archivo nombrado. El informe de compatibilidad identifica funciones no compatibles, enlaces externos, macros, tablas dinámicas, fórmulas volátiles y otros riesgos; no certifica la compatibilidad con Excel. Cuando la corrección importe, compara contra un libro recalculado recientemente por Excel. Consulta los límites de compatibilidad y el tutorial del oráculo de Excel.

Paquetes Y Mapa Del Repositorio

El paquete público requiere Node.js >=22. El desarrollo local del monorepo usa Node.js 24+, Bun y pnpm@10.32.1.

Las versiones publicadas incluyen firmas de registro npm y atestaciones de procedencia:

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

Desarrollo

Elige un servidor de desarrollo de larga duración:

pnpm dev:web
pnpm dev:web-local

Instala y valida el repositorio con:

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

La arquitectura vive en docs/architecture.md. Lee CONTRIBUTING.md antes de abrir una solicitud de extracción; los contribuyentes primerizos pueden comenzar con la guía para nuevos contribuyentes y los problemas iniciales. Toda participación sigue el CODE_OF_CONDUCT.md.

Soporte Y Seguridad

• Haz preguntas de adopción y diseño en Discusiones.
• Sigue los cambios versionados a través de GitHub Releases.
• Reporta errores reproducibles a través de Issues; los libros reducidos pueden usar la clínica de errores de fórmulas y el formulario de fixtures.
• Lee SUPPORT.md para la evidencia que hace accionable un informe.
• Sigue SECURITY.md para informes privados de vulnerabilidades. Nunca adjuntes datos de libros de trabajo privados, credenciales o tokens a un problema público.

Si Bilig encaja en uno de tus servicios o flujos de trabajo de agentes, marca el repositorio con una estrella para seguir las versiones y ayudar a otros desarrolladores de Node a encontrarlo. Cuéntanos qué prueba o fórmula aún falta.

Licencia

MIT