OpenSheet

Una interfaz de base de datos sin la base de datos.

Tus tablas son archivos .jsonl simples en el disco. Edita una celda — git diff muestra una sola línea. Cierra OpenSheet, y jq, DuckDB, Excel, pandas y tus agentes de IA aún pueden leer todo.

中文文档

Qué es esto

Las herramientas de hoja de cálculo y base de datos tienen que poner tus filas en algún lugar. Las respuestas habituales son una base de datos que también tienes que ejecutar, un motor de almacenamiento que viene con la aplicación, o un único archivo binario en el formato propio de la aplicación. Las tres funcionan. Las tres significan que la herramienta se interpone entre tú y tus datos.

La fuente de verdad de OpenSheet es un archivo de texto que ya sabes leer. Una carpeta es una biblioteca, cada .jsonl dentro es una tabla, una línea es un registro. No hay base de datos, ni cuenta, ni servidor, ni sincronización. Borra OpenSheet y tus datos no se mueven ni un centímetro.

$ cat my-library/campaigns.jsonl
{"id":"KS-001","project":"Modular Mechanical Keyboard","raised_usd":412870,"rating":5}
{"id":"KS-002","project":"Solar Camp Lantern","raised_usd":88250,"rating":4}

$ jq -r 'select(.rating == 5) | .project' my-library/campaigns.jsonl
Modular Mechanical Keyboard

Ese es todo el formato de almacenamiento. La interfaz de hoja de cálculo es una vista sobre él, no un envoltorio.

Related MCP server: Universal JSON Agent MCP

Inicio rápido

Requiere Python 3.9+. Sin pip install, sin Docker, sin paso de compilación.

git clone https://github.com/newgepard/opensheet
cd opensheet
PYTHONPATH=src python3 -m opensheet ~/my-library/

Abre http://127.0.0.1:<puerto libre> en tu navegador. Apúntalo a una carpeta de archivos .jsonl, a un único archivo .jsonl, o a una carpeta vacía para empezar desde cero.

Aplicación de escritorio para macOS — un shell nativo de 860 KB (Swift + WKWebView, usa el WebKit del sistema):

bash shell/build.sh
open shell/build/OpenSheet.app

La promesa de fidelidad

Esto es sobre lo que se construye todo lo demás, y está probado en lugar de afirmado.

1. Las filas no tocadas se escriben de vuelta byte por byte. Edita una celda en una tabla de 10,000 filas y git diff muestra exactamente una línea cambiada. Las filas que no tocaste nunca se re-serializan — ni se reordenan, ni se reformatean, ni se re-escapan.

2. El texto no ASCII nunca se escapa. {"名前":"甲"} permanece exactamente así. Nunca se convierte en {"\u540d\u524d":"\u7532"}, que es lo que hace json.dumps por defecto y lo que hace que un archivo sea ilegible en cualquier herramienta que no sea un parser JSON.

3. Los archivos dispersos permanecen dispersos. Si una fila no tiene una clave, OpenSheet no la inventará. Añadir un campo a una tabla con 50,000 filas existentes reescribe cero de ellas.

Deshacer está construido como comandos inversos, no como restauración de instantáneas, específicamente para que la promesa 1 sobreviva: edita una celda, pulsa ⌘Z, guarda — git diff está vacío. Una implementación de restauración de instantáneas se vería correcta en pantalla mientras re-serializa silenciosamente cada fila que tocó.

Respaldando esto: una verificación de huella digital se niega a sobrescribir cambios hechos a espaldas de OpenSheet, las escrituras pasan por un archivo temporal más os.replace(), y cada guardado mantiene un .bak junto a una instantánea al abrir.

Características

• Tu dato es un archivo que posees — .jsonl simple, legible por jq, DuckDB, pandas, Excel y git

• Deshacer todo — ⌘Z / ⇧⌘Z; un borrado por lotes se colapsa en un solo paso de deshacer

• 13 tipos de campo — texto, número, selección, selección múltiple, fecha, casilla de verificación, URL, adjunto, fórmula, búsqueda entre tablas, hora de creación/actualización, auto-número. Los números se muestran como barras de progreso, moneda, calificaciones o porcentajes sin cambiar el valor almacenado

• 4 tipos de vista — cuadrícula, kanban, galería, más filtros por vista, ordenamientos, agrupación, estadísticas, altura de fila, columnas congeladas y orden de columnas

• 10,000 filas se mantienen fluidas — desplazamiento virtual; medido en 57 ms para cargar y 59 ms para guardar una tabla de 7.5 MB

• Importar y exportar — entrada desde CSV, XLSX, JSON, SQLite y .grist; salida a CSV, XLSX, JSON, JSONL, Markdown y Parquet

• Los adjuntos permanecen locales — los archivos van a <library>/assets/, la celda contiene una ruta relativa, nada se sube a ningún sitio

Hecho para agentes, no decorado con IA

Añadir un botón de IA a una hoja de cálculo es una característica. Elegir un formato de almacenamiento que un agente pueda leer y escribir sin un adaptador es una arquitectura. OpenSheet hizo lo segundo, y todo lo demás se deriva de ello: el archivo está orientado a líneas para que los añadidos sean >>, el formato es texto para que grep funcione, y el escritor es único para que la fidelidad de bytes sobreviva al acceso concurrente.

Un servidor MCP se ejecuta en el mismo proceso que el servidor HTTP, compartiendo una instancia de Store:

{
  "mcpServers": {
    "opensheet": {
      "command": "python3",
      "args": ["-m", "opensheet", "/path/to/libraries", "--mcp", "--mcp-root", "/path/to/libraries"],
      "env": { "PYTHONPATH": "/path/to/opensheet/src" }
    }
  }
}

Herramientas: list_libraries, list_tables, get_schema, query, upsert_rows. upsert_rows devuelve un recibo — contadores de inserted / updated / unchanged más las claves primarias para cada uno — y soporta dry_run. Las filas idénticas a lo que ya está en el disco cuentan como unchanged, y el archivo no se toca.

El mismo proceso no es un detalle de implementación. La fidelidad de bytes depende del estado en el proceso: en qué bytes llegó cada fila. Dos procesos que tengan cada uno su propia copia concluirían que las escrituras del otro son "cambios" y re-serializarían todo el archivo en el siguiente guardado. Un segundo proceso detecta el archivo de bloqueo y reenvía al primero, por lo que siempre hay exactamente un escritor.

Los agentes también pueden omitir OpenSheet y añadir al archivo directamente. Las reglas que mantienen la fidelidad intacta cuando lo hacen están documentadas en la guía de escritura directa.

Arquitectura

graph TD
    A["my-library/"] --> B["campaigns.jsonl<br/>source of truth"]
    A --> C["suppliers.jsonl"]
    A --> D[".opensheet/<br/>schema · views · links"]
    B --> E["store.py<br/>row passthrough · atomic write"]
    C --> E
    E --> F["single process"]
    F --> G["HTTP + browser UI"]
    F --> H["MCP over stdio"]
    G --> I["native macOS shell"]

.opensheet/ contiene tipos de campo, anchos de columna, definiciones de vista y enlaces entre tablas. Bórralo y pierdes formato, no datos — los tipos de campo caen en inferencia.

Por qué se mantiene pequeño

El backend es solo la biblioteca estándar de Python. El frontend es JavaScript puro — sin framework, sin paso de compilación. El shell de macOS es 184 KB de Swift sobre el WebKit del sistema, no un navegador empaquetado.

DuckDB es opcional y solo lectura, sirviendo el panel SQL y la exportación a Parquet. Nunca participa en filtrado, ordenamiento o agrupación, y nunca escribe. Cada escritura pasa por store.py.

Sin red, por construcción

Sin telemetría, sin comprobaciones de actualización, sin activos CDN, sin demo en línea. El navegador solo solicita rutas /api/* del mismo origen, el servidor se vincula solo al loopback IPv4, y el shell de escritorio no mantiene conexiones TCP propias. tests/test_offline.py hace cumplir todo esto.

Verificación

bash tests/opensheet-全量验收-20260815.sh

329 pruebas: 188 unitarias de JavaScript, 83 de Python, 42 de extremo a extremo en navegador (Playwright), 8 de ida y vuelta de fidelidad, 8 de ida y vuelta de biblioteca. Las pruebas de fidelidad comparan archivos byte por byte en lugar de campo por campo — una prueba que solo verificara valores pasaría mientras la promesa 1 se rompiera silenciosamente.

Las pruebas de navegador necesitan npm install dentro de web/ para el Chromium de Playwright.

Lo que OpenSheet no hará

Comentarios, permisos, colaboración en tiempo real, automatizaciones, una versión alojada, una demo en línea. Cada una de ellas necesita un sistema de cuentas o una dirección pública, lo que contradice la primera restricción de diseño: los datos nunca salen de tu máquina.

Este es un límite deliberado, no una brecha en la hoja de ruta.

Estado

Funciona y se usa a diario, con dos bordes ásperos que vale la pena conocer antes de probarlo:

• La interfaz actualmente es solo en chino. El código, los comentarios y las cadenas de interfaz están todos en chino. La localización al inglés aún no se ha hecho.

• Solo macOS para el shell de escritorio. La versión web funciona en cualquier lugar donde Python funcione.

Contribuir

Issues y PRs son bienvenidos. Dos cosas que saber antes de tocar la capa de almacenamiento:

1. La lógica de paso de filas en store.py es el producto. Cambiarla significa mantener las pruebas de fidelidad en verde, y esas comparan bytes, no campos.

2. Los comentarios de código están actualmente en chino. La ayuda con la traducción es muy bienvenida.

Licencia

MIT — ver LICENSE.